globus_xio  4.15
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Modules Pages
globus_xio.h
1 /*
2  * Copyright 1999-2006 University of Chicago
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #if !defined(GLOBUS_XIO_H)
18 #define GLOBUS_XIO_H
19 
20 #include "globus_common.h"
21 #include "globus_xio_types.h"
22 #include "globus_xio_util.h"
23 #include "globus_xio_load.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 #ifndef GLOBUS_GLOBAL_DOCUMENT_SET
30 
34 #endif
35 
174 /*************************************************************************
175  * define types
176  ************************************************************************/
177 
212 globus_result_t
214  globus_xio_attr_t * attr);
215 
242 globus_result_t
244  globus_xio_attr_t attr,
245  globus_xio_driver_t driver,
246  int cmd,
247  ...);
248 
254 globus_result_t
256  globus_xio_attr_t * dst,
257  globus_xio_attr_t src);
258 
268 globus_result_t
270  globus_xio_attr_t attr);
271 
272 /*************************************************************************
273  * Stack functions
274  * ---------------
275  ************************************************************************/
276 
281 globus_result_t
283  globus_xio_stack_t * stack,
284  globus_xio_attr_t stack_attr);
285 
294 globus_result_t
296  globus_xio_stack_t stack,
297  globus_xio_driver_t driver);
298 
303 globus_result_t
305  globus_xio_stack_t * dst,
306  globus_xio_stack_t src);
307 
312 globus_result_t
314  globus_xio_stack_t stack);
315 
316 /*-------------------------------------------------------------------------
317  * server
318  *-----------------------------------------------------------------------*/
341 typedef void
343  globus_xio_server_t server,
344  globus_xio_handle_t handle,
345  globus_result_t result,
346  void * user_arg);
347 
355 typedef void
357  globus_xio_server_t server,
358  void * user_arg);
359 
378 globus_result_t
380  globus_xio_server_t * server,
381  globus_xio_attr_t server_attr,
382  globus_xio_stack_t stack);
383 
398 globus_result_t
400  globus_xio_server_t server,
401  char ** contact_string);
402 
410 globus_result_t
412  globus_xio_server_t server,
414  void * user_arg);
415 
420 globus_result_t
422  globus_xio_server_t server);
423 
432 globus_result_t
434  globus_xio_server_t server,
435  globus_xio_driver_t driver,
436  int cmd,
437  ...);
438 
447 globus_result_t
449  globus_xio_handle_t * out_handle,
450  globus_xio_server_t server);
451 
459 globus_result_t
461  globus_xio_server_t server,
463  void * user_arg);
464 
473 globus_result_t
475  globus_xio_handle_t * handle,
476  globus_xio_stack_t stack);
477 
478 /******************************************************************
479  * handle construction
480  *****************************************************************/
481 
482 /******************************************************************
483  * setting timeout values
484  *****************************************************************/
485 
505 typedef globus_bool_t
507  globus_xio_handle_t handle,
509  void * user_arg);
510 
511 typedef globus_bool_t
512 (*globus_xio_timeout_server_callback_t)(
513  globus_xio_server_t server,
515 
516 
517 /******************************************************************
518  * data descriptor
519  *****************************************************************/
520 
533 globus_result_t
535  globus_xio_data_descriptor_t * data_desc,
536  globus_xio_handle_t handle);
537 
542 globus_result_t
544  globus_xio_data_descriptor_t data_desc);
545 
554 globus_result_t
556  globus_xio_data_descriptor_t data_desc,
557  globus_xio_driver_t driver,
558  int cmd,
559  ...);
560 
561 /*********************************************************************
562  * callbacks
563  ********************************************************************/
571 typedef void (*globus_xio_callback_t)(
572  globus_xio_handle_t handle,
573  globus_result_t result,
574  void * user_arg);
575 
586  globus_xio_handle_t handle,
587  globus_result_t result,
588  globus_byte_t * buffer,
589  globus_size_t len,
590  globus_size_t nbytes,
591  globus_xio_data_descriptor_t data_desc,
592  void * user_arg);
593 
604  globus_xio_handle_t handle,
605  globus_result_t result,
606  globus_xio_iovec_t * iovec,
607  int count,
608  globus_size_t nbytes,
609  globus_xio_data_descriptor_t data_desc,
610  void * user_arg);
611 
624 globus_result_t
626  globus_xio_handle_t handle,
627  globus_xio_driver_t driver,
628  int cmd,
629  ...);
630 
691 globus_result_t
693  globus_xio_handle_t handle,
694  const char * contact_string,
695  globus_xio_attr_t attr,
697  void * user_arg);
698 
703 globus_result_t
705  globus_xio_handle_t handle,
706  const char * contact_string,
707  globus_xio_attr_t attr);
708 
713 globus_result_t
715  globus_xio_handle_t handle,
716  globus_byte_t * buffer,
717  globus_size_t buffer_length,
718  globus_size_t waitforbytes,
719  globus_xio_data_descriptor_t data_desc,
721  void * user_arg);
722 
727 globus_result_t
729  globus_xio_handle_t handle,
730  globus_byte_t * buffer,
731  globus_size_t buffer_length,
732  globus_size_t waitforbytes,
733  globus_size_t * nbytes,
734  globus_xio_data_descriptor_t data_desc);
735 
740 globus_result_t
742  globus_xio_handle_t handle,
743  globus_xio_iovec_t * iovec,
744  int iovec_count,
745  globus_size_t waitforbytes,
746  globus_xio_data_descriptor_t data_desc,
748  void * user_arg);
749 
754 globus_result_t
756  globus_xio_handle_t handle,
757  globus_xio_iovec_t * iovec,
758  int iovec_count,
759  globus_size_t waitforbytes,
760  globus_size_t * nbytes,
761  globus_xio_data_descriptor_t data_desc);
762 
767 globus_result_t
769  globus_xio_handle_t handle,
770  globus_byte_t * buffer,
771  globus_size_t buffer_length,
772  globus_size_t waitforbytes,
773  globus_xio_data_descriptor_t data_desc,
775  void * user_arg);
776 
781 globus_result_t
783  globus_xio_handle_t handle,
784  globus_byte_t * buffer,
785  globus_size_t buffer_length,
786  globus_size_t waitforbytes,
787  globus_size_t * nbytes,
788  globus_xio_data_descriptor_t data_desc);
789 
794 globus_result_t
796  globus_xio_handle_t handle,
797  globus_xio_iovec_t * iovec,
798  int iovec_count,
799  globus_size_t waitforbytes,
800  globus_xio_data_descriptor_t data_desc,
802  void * user_arg);
803 
808 globus_result_t
810  globus_xio_handle_t handle,
811  globus_xio_iovec_t * iovec,
812  int iovec_count,
813  globus_size_t waitforbytes,
814  globus_size_t * nbytes,
815  globus_xio_data_descriptor_t data_desc);
816 
817 
821 globus_result_t
822 globus_xio_handle_cancel_operations(
823  globus_xio_handle_t handle,
824  int mask);
825 
826 globus_result_t
827 globus_xio_server_cancel_accept(
828  globus_xio_server_t server);
829 
850 globus_result_t
852  globus_xio_handle_t handle,
853  globus_xio_attr_t attr,
855  void * user_arg);
856 
861 globus_result_t
863  globus_xio_handle_t handle,
864  globus_xio_attr_t attr);
865 
866 /*
867  * signal stuff
868  * TODO:
869  * Signals are not implemented in the first release.
870  * =================================================
871  *
872  * Signals in Globus XIO give the user a means of requesting
873  * notification when given things in the system change.
874  *
875  * For example:
876  * It may be useful for the user of globus_xio to know when/if the
877  * optimal post buffer size changes. The optimal post buffer size is
878  * a value that tells the user the best possible length of a buffer to
879  * post for an I/O operation. This value is mutable and can be changed
880  * by events internal to globus_xio of which the user is unaware.
881  * The signal API allows the user to register for notification of when
882  * this value changes.
883  *
884  * Globus XIO enumerates the signal types for which the user can register.
885  * One of these types is GLOBUS_XIO_DRIVER_SPECIFIC. This type allows
886  * the user to catch driver specific signals. A driver specific signal
887  * example could be when the TCP window size changes. Only a TCP driver
888  * can be aware of this information so only it can send the signal.
889  * Further a user only knows to listen for that signal if it knows that
890  * tcp is in its driver stack.
891  *
892  * Once a signal is delivered to the globus_xio user the handle can be
893  * queried for specific information regarding that signal.
894  * Event Types.
895  * @ingroup GLOBUS_XIO_API
896  *
897  * An enumeration of the signal types of which globus_xio is aware.
898 enum globus_xio_signal_type_t
899 {
900  GLOBUS_XIO_SIGNAL_BUFFER_POST_SIZE,
901  GLOBUS_XIO_SIGNAL_OPTIMAL_BUFFER_SIZE,
902  GLOBUS_XIO_SIGNAL_DRIVER_SPECIFIC,
903 };
904  *
905  * Signal Callback
906  * @ingroup GLOBUS_XIO_API
907  *
908  * The callback signature for signal events.
909  *
910  * @param handle
911  * The handle associated with the event.
912  *
913  * @param signal_type
914  * The type of signal that occurred.
915  *
916  * @param driver
917  * The driver that caused this event. If it is not a driver
918  * specific signal than this will be NULL.
919 typedef void
920 (*globus_xio_signal_callback_t)(
921  globus_xio_handle_t handle,
922  globus_xio_signal_type_t signal_type,
923  globus_xio_driver_t driver);
924  *
925  * Register a signal listener.
926  * @ingroup GLOBUS_XIO_API
927  *
928  * Request notification when event change in the system relating
929  * to a given handle.
930  *
931  * @param handle
932  * The handle on which the user would like to receive
933  * notifications.
934  *
935  * @param signal_mask
936  * A mask of the signals to be observed.
937  *
938  * @param driver
939  * The driver to which the signal mask applies. If this is for a
940  * non driver specific event this will be null. This function
941  * must be called once for every driver of interest.
942  *
943  * @param callback
944  * The function to be called when the given events occur.
945  *
946  * @param user_arg
947  * A user pointed threaded through to the callback.
948 globus_result_t
949 globus_xio_handle_register_signal_handler(
950  globus_xio_handle_t handle,
951  int signal_mask,
952  globus_xio_driver_t driver,
953  globus_xio_signal_callback_t callback,
954  void * user_arg);
955 
956  * Register a signal listener.
957  * @ingroup GLOBUS_XIO_API
958  *
959  * Request notification when event change in the system relating
960  * to a given factory.
961  *
962  * @param factory
963  * The factory on which the user would like to receive
964  * notifications of events.
965  *
966  * @param signal_mask
967  * A mask of the signals to be observed.
968  *
969  * @param driver
970  * The driver to which the signal mask applies. If this is for a
971  * non driver specific event this will be null. This function
972  * must be called once for every driver of interest.
973  *
974  * @param callback
975  * The function to be called when the given events occur.
976  *
977  * @param user_arg
978  * A user pointed threaded through to the callback.
979 globus_result_t
980 globus_xio_server_register_signal_handler(
981  globus_xio_server_t factory,
982  int signal_mask,
983  globus_xio_driver_t driver,
984  globus_xio_callback_t callback,
985  void * user_arg);
986  */
987 
988 
989 globus_xio_driver_list_ent_t *
990 globus_xio_driver_list_find_driver(
991  globus_list_t * driver_list,
992  const char * driver_name);
993 
994 void
995 globus_xio_driver_list_destroy(
996  globus_list_t * driver_list,
997  globus_bool_t unload);
998 
999 globus_result_t
1000 globus_xio_driver_list_to_stack_attr(
1001  globus_list_t * driver_list,
1002  globus_xio_stack_t stack,
1003  globus_xio_attr_t attr);
1004 
1005 globus_result_t
1006 globus_xio_driver_list_from_string(
1007  char * driver_string,
1008  globus_list_t ** driver_list,
1009  globus_hashtable_t * safe_table);
1010 
1011 globus_result_t
1012 globus_xio_driver_safe_table_from_string(
1013  char * driver_string,
1014  globus_hashtable_t * safe_table);
1015 
1016 globus_result_t
1017 globus_xio_driver_list_create_ent(
1018  const char * driver_desc,
1019  globus_xio_driver_t driver_in,
1020  globus_bool_t load,
1021  globus_xio_driver_list_ent_t ** ent_out);
1022 
1023 extern globus_module_descriptor_t globus_i_xio_module;
1024 #define GLOBUS_XIO_MODULE &globus_i_xio_module
1025 
1026 #define _XIOSL(s) globus_common_i18n_get_string( \
1027  GLOBUS_XIO_MODULE, \
1028  s)
1029 
1057 globus_result_t
1059  globus_xio_handle_t * out_h,
1060  const char * scheme,
1061  globus_xio_attr_t attr,
1062  char * param_string);
1063 
1064 #ifdef __cplusplus
1065 }
1066 #endif
1067 
1068 #endif
globus_result_t globus_xio_writev(globus_xio_handle_t handle, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_handle.c:3454
globus_result_t globus_xio_server_register_close(globus_xio_server_t server, globus_xio_server_callback_t cb, void *user_arg)
Definition: globus_xio_server.c:1394
globus_result_t globus_xio_attr_copy(globus_xio_attr_t *dst, globus_xio_attr_t src)
Definition: globus_xio_attr.c:518
globus_result_t globus_xio_register_writev(globus_xio_handle_t handle, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_iovec_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2501
void(* globus_xio_accept_callback_t)(globus_xio_server_t server, globus_xio_handle_t handle, globus_result_t result, void *user_arg)
Definition: globus_xio.h:342
globus_result_t globus_xio_register_open(globus_xio_handle_t handle, const char *contact_string, globus_xio_attr_t attr, globus_xio_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2148
globus_result_t globus_xio_stack_push_driver(globus_xio_stack_t stack, globus_xio_driver_t driver)
Definition: globus_xio_attr.c:966
globus_result_t globus_xio_stack_init(globus_xio_stack_t *stack, globus_xio_attr_t stack_attr)
Definition: globus_xio_attr.c:890
void(* globus_xio_data_callback_t)(globus_xio_handle_t handle, globus_result_t result, globus_byte_t *buffer, globus_size_t len, globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void *user_arg)
Definition: globus_xio.h:585
globus_result_t globus_xio_data_descriptor_destroy(globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_attr.c:713
globus_bool_t(* globus_xio_timeout_callback_t)(globus_xio_handle_t handle, globus_xio_operation_type_t type, void *user_arg)
Definition: globus_xio.h:506
enum globus_i_xio_op_type_e globus_xio_operation_type_t
void(* globus_xio_callback_t)(globus_xio_handle_t handle, globus_result_t result, void *user_arg)
Definition: globus_xio.h:571
globus_result_t globus_xio_attr_init(globus_xio_attr_t *attr)
Definition: globus_xio_attr.c:38
globus_result_t globus_xio_register_close(globus_xio_handle_t handle, globus_xio_attr_t attr, globus_xio_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2583
globus_result_t globus_xio_server_cntl(globus_xio_server_t server, globus_xio_driver_t driver, int cmd,...)
Definition: globus_xio_server.c:1051
globus_result_t globus_xio_server_create(globus_xio_server_t *server, globus_xio_attr_t server_attr, globus_xio_stack_t stack)
Definition: globus_xio_server.c:869
globus_result_t globus_xio_server_close(globus_xio_server_t server)
Definition: globus_xio_server.c:1443
globus_result_t globus_xio_handle_create_from_url(globus_xio_handle_t *out_h, const char *scheme, globus_xio_attr_t attr, char *param_string)
Definition: globus_xio_handle.c:3742
globus_result_t globus_xio_read(globus_xio_handle_t handle, globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_handle.c:3073
globus_result_t globus_xio_data_descriptor_init(globus_xio_data_descriptor_t *data_desc, globus_xio_handle_t handle)
Definition: globus_xio_attr.c:645
globus_result_t globus_xio_server_register_accept(globus_xio_server_t server, globus_xio_accept_callback_t cb, void *user_arg)
Definition: globus_xio_server.c:1123
globus_result_t globus_xio_readv(globus_xio_handle_t handle, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_handle.c:3198
globus_result_t globus_xio_write(globus_xio_handle_t handle, globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_handle.c:3329
globus_result_t globus_xio_server_get_contact_string(globus_xio_server_t server, char **contact_string)
Definition: globus_xio_server.c:1009
globus_result_t globus_xio_server_accept(globus_xio_handle_t *out_handle, globus_xio_server_t server)
Definition: globus_xio_server.c:1238
globus_result_t globus_xio_open(globus_xio_handle_t handle, const char *contact_string, globus_xio_attr_t attr)
Definition: globus_xio_handle.c:2934
globus_result_t globus_xio_register_readv(globus_xio_handle_t handle, globus_xio_iovec_t *iovec, int iovec_count, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_iovec_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2341
globus_result_t globus_xio_attr_cntl(globus_xio_attr_t attr, globus_xio_driver_t driver, int cmd,...)
Definition: globus_xio_attr.c:394
globus_result_t globus_xio_register_read(globus_xio_handle_t handle, globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_data_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2264
void(* globus_xio_server_callback_t)(globus_xio_server_t server, void *user_arg)
Definition: globus_xio.h:356
globus_result_t globus_xio_close(globus_xio_handle_t handle, globus_xio_attr_t attr)
Definition: globus_xio_handle.c:3582
globus_result_t globus_xio_data_descriptor_cntl(globus_xio_data_descriptor_t data_desc, globus_xio_driver_t driver, int cmd,...)
Definition: globus_xio_attr.c:777
globus_result_t globus_xio_handle_cntl(globus_xio_handle_t handle, globus_xio_driver_t driver, int cmd,...)
Definition: globus_xio_handle.c:2694
void(* globus_xio_iovec_callback_t)(globus_xio_handle_t handle, globus_result_t result, globus_xio_iovec_t *iovec, int count, globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void *user_arg)
Definition: globus_xio.h:603
globus_result_t globus_xio_handle_create(globus_xio_handle_t *handle, globus_xio_stack_t stack)
Definition: globus_xio_handle.c:2058
globus_result_t globus_xio_register_write(globus_xio_handle_t handle, globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_data_callback_t cb, void *user_arg)
Definition: globus_xio_handle.c:2421
globus_result_t globus_xio_stack_destroy(globus_xio_stack_t stack)
Definition: globus_xio_attr.c:1039
globus_result_t globus_xio_attr_destroy(globus_xio_attr_t attr)
Definition: globus_xio_attr.c:439
globus_result_t globus_xio_stack_copy(globus_xio_stack_t *dst, globus_xio_stack_t src)
Definition: globus_xio_attr.c:916