globus_xio  5.8
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups 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 
173 /*************************************************************************
174  * define types
175  ************************************************************************/
176 
211 globus_result_t
213  globus_xio_attr_t * attr);
214 
241 globus_result_t
243  globus_xio_attr_t attr,
244  globus_xio_driver_t driver,
245  int cmd,
246  ...);
247 
253 globus_result_t
255  globus_xio_attr_t * dst,
256  globus_xio_attr_t src);
257 
267 globus_result_t
269  globus_xio_attr_t attr);
270 
271 /*************************************************************************
272  * Stack functions
273  * ---------------
274  ************************************************************************/
275 
280 globus_result_t
282  globus_xio_stack_t * stack,
283  globus_xio_attr_t stack_attr);
284 
293 globus_result_t
295  globus_xio_stack_t stack,
296  globus_xio_driver_t driver);
297 
302 globus_result_t
304  globus_xio_stack_t * dst,
305  globus_xio_stack_t src);
306 
311 globus_result_t
313  globus_xio_stack_t stack);
314 
315 /*-------------------------------------------------------------------------
316  * server
317  *-----------------------------------------------------------------------*/
340 typedef void
342  globus_xio_server_t server,
343  globus_xio_handle_t handle,
344  globus_result_t result,
345  void * user_arg);
346 
354 typedef void
356  globus_xio_server_t server,
357  void * user_arg);
358 
377 globus_result_t
379  globus_xio_server_t * server,
380  globus_xio_attr_t server_attr,
381  globus_xio_stack_t stack);
382 
397 globus_result_t
399  globus_xio_server_t server,
400  char ** contact_string);
401 
409 globus_result_t
411  globus_xio_server_t server,
413  void * user_arg);
414 
419 globus_result_t
421  globus_xio_server_t server);
422 
431 globus_result_t
433  globus_xio_server_t server,
434  globus_xio_driver_t driver,
435  int cmd,
436  ...);
437 
446 globus_result_t
448  globus_xio_handle_t * out_handle,
449  globus_xio_server_t server);
450 
458 globus_result_t
460  globus_xio_server_t server,
462  void * user_arg);
463 
472 globus_result_t
474  globus_xio_handle_t * handle,
475  globus_xio_stack_t stack);
476 
477 /******************************************************************
478  * handle construction
479  *****************************************************************/
480 
481 /******************************************************************
482  * setting timeout values
483  *****************************************************************/
484 
504 typedef globus_bool_t
506  globus_xio_handle_t handle,
508  void * user_arg);
509 
510 typedef globus_bool_t
511 (*globus_xio_timeout_server_callback_t)(
512  globus_xio_server_t server,
514 
515 
516 /******************************************************************
517  * data descriptor
518  *****************************************************************/
519 
532 globus_result_t
534  globus_xio_data_descriptor_t * data_desc,
535  globus_xio_handle_t handle);
536 
541 globus_result_t
543  globus_xio_data_descriptor_t data_desc);
544 
553 globus_result_t
555  globus_xio_data_descriptor_t data_desc,
556  globus_xio_driver_t driver,
557  int cmd,
558  ...);
559 
560 /*********************************************************************
561  * callbacks
562  ********************************************************************/
570 typedef void (*globus_xio_callback_t)(
571  globus_xio_handle_t handle,
572  globus_result_t result,
573  void * user_arg);
574 
585  globus_xio_handle_t handle,
586  globus_result_t result,
587  globus_byte_t * buffer,
588  globus_size_t len,
589  globus_size_t nbytes,
590  globus_xio_data_descriptor_t data_desc,
591  void * user_arg);
592 
603  globus_xio_handle_t handle,
604  globus_result_t result,
605  globus_xio_iovec_t * iovec,
606  int count,
607  globus_size_t nbytes,
608  globus_xio_data_descriptor_t data_desc,
609  void * user_arg);
610 
623 globus_result_t
625  globus_xio_handle_t handle,
626  globus_xio_driver_t driver,
627  int cmd,
628  ...);
629 
690 globus_result_t
692  globus_xio_handle_t handle,
693  const char * contact_string,
694  globus_xio_attr_t attr,
696  void * user_arg);
697 
702 globus_result_t
704  globus_xio_handle_t handle,
705  const char * contact_string,
706  globus_xio_attr_t attr);
707 
712 globus_result_t
714  globus_xio_handle_t handle,
715  globus_byte_t * buffer,
716  globus_size_t buffer_length,
717  globus_size_t waitforbytes,
718  globus_xio_data_descriptor_t data_desc,
720  void * user_arg);
721 
726 globus_result_t
728  globus_xio_handle_t handle,
729  globus_byte_t * buffer,
730  globus_size_t buffer_length,
731  globus_size_t waitforbytes,
732  globus_size_t * nbytes,
733  globus_xio_data_descriptor_t data_desc);
734 
739 globus_result_t
741  globus_xio_handle_t handle,
742  globus_xio_iovec_t * iovec,
743  int iovec_count,
744  globus_size_t waitforbytes,
745  globus_xio_data_descriptor_t data_desc,
747  void * user_arg);
748 
753 globus_result_t
755  globus_xio_handle_t handle,
756  globus_xio_iovec_t * iovec,
757  int iovec_count,
758  globus_size_t waitforbytes,
759  globus_size_t * nbytes,
760  globus_xio_data_descriptor_t data_desc);
761 
766 globus_result_t
768  globus_xio_handle_t handle,
769  globus_byte_t * buffer,
770  globus_size_t buffer_length,
771  globus_size_t waitforbytes,
772  globus_xio_data_descriptor_t data_desc,
774  void * user_arg);
775 
780 globus_result_t
782  globus_xio_handle_t handle,
783  globus_byte_t * buffer,
784  globus_size_t buffer_length,
785  globus_size_t waitforbytes,
786  globus_size_t * nbytes,
787  globus_xio_data_descriptor_t data_desc);
788 
793 globus_result_t
795  globus_xio_handle_t handle,
796  globus_xio_iovec_t * iovec,
797  int iovec_count,
798  globus_size_t waitforbytes,
799  globus_xio_data_descriptor_t data_desc,
801  void * user_arg);
802 
807 globus_result_t
809  globus_xio_handle_t handle,
810  globus_xio_iovec_t * iovec,
811  int iovec_count,
812  globus_size_t waitforbytes,
813  globus_size_t * nbytes,
814  globus_xio_data_descriptor_t data_desc);
815 
816 
820 globus_result_t
821 globus_xio_handle_cancel_operations(
822  globus_xio_handle_t handle,
823  int mask);
824 
825 globus_result_t
826 globus_xio_server_cancel_accept(
827  globus_xio_server_t server);
828 
849 globus_result_t
851  globus_xio_handle_t handle,
852  globus_xio_attr_t attr,
854  void * user_arg);
855 
860 globus_result_t
862  globus_xio_handle_t handle,
863  globus_xio_attr_t attr);
864 
865 /*
866  * signal stuff
867  * TODO:
868  * Signals are not implemented in the first release.
869  * =================================================
870  *
871  * Signals in Globus XIO give the user a means of requesting
872  * notification when given things in the system change.
873  *
874  * For example:
875  * It may be useful for the user of globus_xio to know when/if the
876  * optimal post buffer size changes. The optimal post buffer size is
877  * a value that tells the user the best possible length of a buffer to
878  * post for an I/O operation. This value is mutable and can be changed
879  * by events internal to globus_xio of which the user is unaware.
880  * The signal API allows the user to register for notification of when
881  * this value changes.
882  *
883  * Globus XIO enumerates the signal types for which the user can register.
884  * One of these types is GLOBUS_XIO_DRIVER_SPECIFIC. This type allows
885  * the user to catch driver specific signals. A driver specific signal
886  * example could be when the TCP window size changes. Only a TCP driver
887  * can be aware of this information so only it can send the signal.
888  * Further a user only knows to listen for that signal if it knows that
889  * tcp is in its driver stack.
890  *
891  * Once a signal is delivered to the globus_xio user the handle can be
892  * queried for specific information regarding that signal.
893  * Event Types.
894  * @ingroup GLOBUS_XIO_API
895  *
896  * An enumeration of the signal types of which globus_xio is aware.
897 enum globus_xio_signal_type_t
898 {
899  GLOBUS_XIO_SIGNAL_BUFFER_POST_SIZE,
900  GLOBUS_XIO_SIGNAL_OPTIMAL_BUFFER_SIZE,
901  GLOBUS_XIO_SIGNAL_DRIVER_SPECIFIC,
902 };
903  *
904  * Signal Callback
905  * @ingroup GLOBUS_XIO_API
906  *
907  * The callback signature for signal events.
908  *
909  * @param handle
910  * The handle associated with the event.
911  *
912  * @param signal_type
913  * The type of signal that occurred.
914  *
915  * @param driver
916  * The driver that caused this event. If it is not a driver
917  * specific signal than this will be NULL.
918 typedef void
919 (*globus_xio_signal_callback_t)(
920  globus_xio_handle_t handle,
921  globus_xio_signal_type_t signal_type,
922  globus_xio_driver_t driver);
923  *
924  * Register a signal listener.
925  * @ingroup GLOBUS_XIO_API
926  *
927  * Request notification when event change in the system relating
928  * to a given handle.
929  *
930  * @param handle
931  * The handle on which the user would like to receive
932  * notifications.
933  *
934  * @param signal_mask
935  * A mask of the signals to be observed.
936  *
937  * @param driver
938  * The driver to which the signal mask applies. If this is for a
939  * non driver specific event this will be null. This function
940  * must be called once for every driver of interest.
941  *
942  * @param callback
943  * The function to be called when the given events occur.
944  *
945  * @param user_arg
946  * A user pointed threaded through to the callback.
947 globus_result_t
948 globus_xio_handle_register_signal_handler(
949  globus_xio_handle_t handle,
950  int signal_mask,
951  globus_xio_driver_t driver,
952  globus_xio_signal_callback_t callback,
953  void * user_arg);
954 
955  * Register a signal listener.
956  * @ingroup GLOBUS_XIO_API
957  *
958  * Request notification when event change in the system relating
959  * to a given factory.
960  *
961  * @param factory
962  * The factory on which the user would like to receive
963  * notifications of events.
964  *
965  * @param signal_mask
966  * A mask of the signals to be observed.
967  *
968  * @param driver
969  * The driver to which the signal mask applies. If this is for a
970  * non driver specific event this will be null. This function
971  * must be called once for every driver of interest.
972  *
973  * @param callback
974  * The function to be called when the given events occur.
975  *
976  * @param user_arg
977  * A user pointed threaded through to the callback.
978 globus_result_t
979 globus_xio_server_register_signal_handler(
980  globus_xio_server_t factory,
981  int signal_mask,
982  globus_xio_driver_t driver,
983  globus_xio_callback_t callback,
984  void * user_arg);
985  */
986 
987 
988 globus_xio_driver_list_ent_t *
989 globus_xio_driver_list_find_driver(
990  globus_list_t * driver_list,
991  const char * driver_name);
992 
993 void
994 globus_xio_driver_list_destroy(
995  globus_list_t * driver_list,
996  globus_bool_t unload);
997 
998 globus_result_t
1000  globus_list_t * driver_list,
1001  globus_xio_stack_t stack,
1002  globus_xio_attr_t attr);
1003 
1004 globus_result_t
1005 globus_xio_driver_list_from_string(
1006  char * driver_string,
1007  globus_list_t ** driver_list,
1008  globus_hashtable_t * safe_table);
1009 
1010 globus_result_t
1011 globus_xio_driver_safe_table_from_string(
1012  char * driver_string,
1013  globus_hashtable_t * safe_table);
1014 
1015 globus_result_t
1016 globus_xio_driver_list_create_ent(
1017  const char * driver_desc,
1018  globus_xio_driver_t driver_in,
1019  globus_bool_t load,
1020  globus_xio_driver_list_ent_t ** ent_out);
1021 
1022 extern globus_module_descriptor_t globus_i_xio_module;
1023 #define GLOBUS_XIO_MODULE &globus_i_xio_module
1024 
1025 #define _XIOSL(s) globus_common_i18n_get_string( \
1026  GLOBUS_XIO_MODULE, \
1027  s)
1028 
1056 globus_result_t
1058  globus_xio_handle_t * out_h,
1059  const char * scheme,
1060  globus_xio_attr_t attr,
1061  char * param_string);
1062 
1063 #ifdef __cplusplus
1064 }
1065 #endif
1066 
1067 #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:1406
globus_result_t globus_xio_attr_copy(globus_xio_attr_t *dst, globus_xio_attr_t src)
Definition: globus_xio_attr.c:557
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:341
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:1005
globus_result_t globus_xio_stack_init(globus_xio_stack_t *stack, globus_xio_attr_t stack_attr)
Definition: globus_xio_attr.c:929
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:584
globus_result_t globus_xio_data_descriptor_destroy(globus_xio_data_descriptor_t data_desc)
Definition: globus_xio_attr.c:752
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:505
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:570
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:1063
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:1455
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:684
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:1135
globus_result_t globus_xio_driver_list_to_stack_attr(globus_list_t *driver_list, globus_xio_stack_t stack, globus_xio_attr_t attr)
Add a list of driver entries to a stack.
Definition: globus_xio_attr.c:181
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:1021
globus_result_t globus_xio_server_accept(globus_xio_handle_t *out_handle, globus_xio_server_t server)
Definition: globus_xio_server.c:1250
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:433
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:355
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:816
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:602
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:1078
globus_result_t globus_xio_attr_destroy(globus_xio_attr_t attr)
Definition: globus_xio_attr.c:478
globus_result_t globus_xio_stack_copy(globus_xio_stack_t *dst, globus_xio_stack_t src)
Definition: globus_xio_attr.c:955