Grid Community Toolkit  6.2.1705709074 (tag: v6.2.20240202)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros 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 
190 /*************************************************************************
191  * define types
192  ************************************************************************/
193 
230  globus_xio_attr_t * attr);
231 
260  globus_xio_attr_t attr,
261  globus_xio_driver_t driver,
262  int cmd,
263  ...);
264 
272  globus_xio_attr_t * dst,
273  globus_xio_attr_t src);
274 
286  globus_xio_attr_t attr);
287 
288 /*************************************************************************
289  * Stack functions
290  * ---------------
291  ************************************************************************/
292 
299  globus_xio_stack_t * stack,
300  globus_xio_attr_t stack_attr);
301 
312  globus_xio_stack_t stack,
313  globus_xio_driver_t driver);
314 
321  globus_xio_stack_t * dst,
322  globus_xio_stack_t src);
323 
330  globus_xio_stack_t stack);
331 
332 /*-------------------------------------------------------------------------
333  * server
334  *-----------------------------------------------------------------------*/
357 typedef void
359  globus_xio_server_t server,
360  globus_xio_handle_t handle,
361  globus_result_t result,
362  void * user_arg);
363 
371 typedef void
373  globus_xio_server_t server,
374  void * user_arg);
375 
396  globus_xio_server_t * server,
397  globus_xio_attr_t server_attr,
398  globus_xio_stack_t stack);
399 
416  globus_xio_server_t server,
417  char ** contact_string);
418 
428  globus_xio_server_t server,
430  void * user_arg);
431 
438  globus_xio_server_t server);
439 
450  globus_xio_server_t server,
451  globus_xio_driver_t driver,
452  int cmd,
453  ...);
454 
465  globus_xio_handle_t * out_handle,
466  globus_xio_server_t server);
467 
477  globus_xio_server_t server,
479  void * user_arg);
480 
491  globus_xio_handle_t * handle,
492  globus_xio_stack_t stack);
493 
494 /******************************************************************
495  * handle construction
496  *****************************************************************/
497 
498 /******************************************************************
499  * setting timeout values
500  *****************************************************************/
501 
521 typedef globus_bool_t
523  globus_xio_handle_t handle,
525  void * user_arg);
526 
527 typedef globus_bool_t
528 (*globus_xio_timeout_server_callback_t)(
529  globus_xio_server_t server,
531 
532 
533 /******************************************************************
534  * data descriptor
535  *****************************************************************/
536 
551  globus_xio_data_descriptor_t * data_desc,
552  globus_xio_handle_t handle);
553 
560  globus_xio_data_descriptor_t data_desc);
561 
572  globus_xio_data_descriptor_t data_desc,
573  globus_xio_driver_t driver,
574  int cmd,
575  ...);
576 
577 /*********************************************************************
578  * callbacks
579  ********************************************************************/
587 typedef void (*globus_xio_callback_t)(
588  globus_xio_handle_t handle,
589  globus_result_t result,
590  void * user_arg);
591 
602  globus_xio_handle_t handle,
603  globus_result_t result,
604  globus_byte_t * buffer,
605  globus_size_t len,
606  globus_size_t nbytes,
607  globus_xio_data_descriptor_t data_desc,
608  void * user_arg);
609 
620  globus_xio_handle_t handle,
621  globus_result_t result,
622  globus_xio_iovec_t * iovec,
623  int count,
624  globus_size_t nbytes,
625  globus_xio_data_descriptor_t data_desc,
626  void * user_arg);
627 
642  globus_xio_handle_t handle,
643  globus_xio_driver_t driver,
644  int cmd,
645  ...);
646 
709  globus_xio_handle_t handle,
710  const char * contact_string,
711  globus_xio_attr_t attr,
713  void * user_arg);
714 
721  globus_xio_handle_t handle,
722  const char * contact_string,
723  globus_xio_attr_t attr);
724 
731  globus_xio_handle_t handle,
732  globus_byte_t * buffer,
733  globus_size_t buffer_length,
734  globus_size_t waitforbytes,
735  globus_xio_data_descriptor_t data_desc,
737  void * user_arg);
738 
745  globus_xio_handle_t handle,
746  globus_byte_t * buffer,
747  globus_size_t buffer_length,
748  globus_size_t waitforbytes,
749  globus_size_t * nbytes,
750  globus_xio_data_descriptor_t data_desc);
751 
758  globus_xio_handle_t handle,
759  globus_xio_iovec_t * iovec,
760  int iovec_count,
761  globus_size_t waitforbytes,
762  globus_xio_data_descriptor_t data_desc,
764  void * user_arg);
765 
772  globus_xio_handle_t handle,
773  globus_xio_iovec_t * iovec,
774  int iovec_count,
775  globus_size_t waitforbytes,
776  globus_size_t * nbytes,
777  globus_xio_data_descriptor_t data_desc);
778 
785  globus_xio_handle_t handle,
786  globus_byte_t * buffer,
787  globus_size_t buffer_length,
788  globus_size_t waitforbytes,
789  globus_xio_data_descriptor_t data_desc,
791  void * user_arg);
792 
799  globus_xio_handle_t handle,
800  globus_byte_t * buffer,
801  globus_size_t buffer_length,
802  globus_size_t waitforbytes,
803  globus_size_t * nbytes,
804  globus_xio_data_descriptor_t data_desc);
805 
812  globus_xio_handle_t handle,
813  globus_xio_iovec_t * iovec,
814  int iovec_count,
815  globus_size_t waitforbytes,
816  globus_xio_data_descriptor_t data_desc,
818  void * user_arg);
819 
826  globus_xio_handle_t handle,
827  globus_xio_iovec_t * iovec,
828  int iovec_count,
829  globus_size_t waitforbytes,
830  globus_size_t * nbytes,
831  globus_xio_data_descriptor_t data_desc);
832 
833 
838 globus_xio_handle_cancel_operations(
839  globus_xio_handle_t handle,
840  int mask);
841 
843 globus_xio_server_cancel_accept(
844  globus_xio_server_t server);
845 
868  globus_xio_handle_t handle,
869  globus_xio_attr_t attr,
871  void * user_arg);
872 
879  globus_xio_handle_t handle,
880  globus_xio_attr_t attr);
881 
882 /*
883  * signal stuff
884  * TODO:
885  * Signals are not implemented in the first release.
886  * =================================================
887  *
888  * Signals in Globus XIO give the user a means of requesting
889  * notification when given things in the system change.
890  *
891  * For example:
892  * It may be useful for the user of globus_xio to know when/if the
893  * optimal post buffer size changes. The optimal post buffer size is
894  * a value that tells the user the best possible length of a buffer to
895  * post for an I/O operation. This value is mutable and can be changed
896  * by events internal to globus_xio of which the user is unaware.
897  * The signal API allows the user to register for notification of when
898  * this value changes.
899  *
900  * Globus XIO enumerates the signal types for which the user can register.
901  * One of these types is GLOBUS_XIO_DRIVER_SPECIFIC. This type allows
902  * the user to catch driver specific signals. A driver specific signal
903  * example could be when the TCP window size changes. Only a TCP driver
904  * can be aware of this information so only it can send the signal.
905  * Further a user only knows to listen for that signal if it knows that
906  * tcp is in its driver stack.
907  *
908  * Once a signal is delivered to the globus_xio user the handle can be
909  * queried for specific information regarding that signal.
910  * Event Types.
911  * @ingroup GLOBUS_XIO_API
912  *
913  * An enumeration of the signal types of which globus_xio is aware.
914 enum globus_xio_signal_type_t
915 {
916  GLOBUS_XIO_SIGNAL_BUFFER_POST_SIZE,
917  GLOBUS_XIO_SIGNAL_OPTIMAL_BUFFER_SIZE,
918  GLOBUS_XIO_SIGNAL_DRIVER_SPECIFIC,
919 };
920  *
921  * Signal Callback
922  * @ingroup GLOBUS_XIO_API
923  *
924  * The callback signature for signal events.
925  *
926  * @param handle
927  * The handle associated with the event.
928  *
929  * @param signal_type
930  * The type of signal that occurred.
931  *
932  * @param driver
933  * The driver that caused this event. If it is not a driver
934  * specific signal than this will be NULL.
935 typedef void
936 (*globus_xio_signal_callback_t)(
937  globus_xio_handle_t handle,
938  globus_xio_signal_type_t signal_type,
939  globus_xio_driver_t driver);
940  *
941  * Register a signal listener.
942  * @ingroup GLOBUS_XIO_API
943  *
944  * Request notification when event change in the system relating
945  * to a given handle.
946  *
947  * @param handle
948  * The handle on which the user would like to receive
949  * notifications.
950  *
951  * @param signal_mask
952  * A mask of the signals to be observed.
953  *
954  * @param driver
955  * The driver to which the signal mask applies. If this is for a
956  * non driver specific event this will be null. This function
957  * must be called once for every driver of interest.
958  *
959  * @param callback
960  * The function to be called when the given events occur.
961  *
962  * @param user_arg
963  * A user pointed threaded through to the callback.
964 globus_result_t
965 globus_xio_handle_register_signal_handler(
966  globus_xio_handle_t handle,
967  int signal_mask,
968  globus_xio_driver_t driver,
969  globus_xio_signal_callback_t callback,
970  void * user_arg);
971 
972  * Register a signal listener.
973  * @ingroup GLOBUS_XIO_API
974  *
975  * Request notification when event change in the system relating
976  * to a given factory.
977  *
978  * @param factory
979  * The factory on which the user would like to receive
980  * notifications of events.
981  *
982  * @param signal_mask
983  * A mask of the signals to be observed.
984  *
985  * @param driver
986  * The driver to which the signal mask applies. If this is for a
987  * non driver specific event this will be null. This function
988  * must be called once for every driver of interest.
989  *
990  * @param callback
991  * The function to be called when the given events occur.
992  *
993  * @param user_arg
994  * A user pointed threaded through to the callback.
995 globus_result_t
996 globus_xio_server_register_signal_handler(
997  globus_xio_server_t factory,
998  int signal_mask,
999  globus_xio_driver_t driver,
1000  globus_xio_callback_t callback,
1001  void * user_arg);
1002  */
1003 
1004 
1005 globus_xio_driver_list_ent_t *
1006 globus_xio_driver_list_find_driver(
1007  globus_list_t * driver_list,
1008  const char * driver_name);
1009 
1010 void
1011 globus_xio_driver_list_destroy(
1012  globus_list_t * driver_list,
1013  globus_bool_t unload);
1014 
1017  globus_list_t * driver_list,
1018  globus_xio_stack_t stack,
1019  globus_xio_attr_t attr);
1020 
1022 globus_xio_driver_list_from_string(
1023  char * driver_string,
1024  globus_list_t ** driver_list,
1025  globus_hashtable_t * safe_table);
1026 
1028 globus_xio_driver_safe_table_from_string(
1029  char * driver_string,
1030  globus_hashtable_t * safe_table);
1031 
1033 globus_xio_driver_list_create_ent(
1034  const char * driver_desc,
1035  globus_xio_driver_t driver_in,
1036  globus_bool_t load,
1037  globus_xio_driver_list_ent_t ** ent_out);
1038 
1039 extern globus_module_descriptor_t globus_i_xio_module;
1040 #define GLOBUS_XIO_MODULE &globus_i_xio_module
1041 
1042 #define _XIOSL(s) globus_common_i18n_get_string( \
1043  GLOBUS_XIO_MODULE, \
1044  s)
1045 
1075  globus_xio_handle_t * out_h,
1076  const char * scheme,
1077  globus_xio_attr_t attr,
1078  char * param_string);
1079 
1080 #ifdef __cplusplus
1081 }
1082 #endif
1083 
1084 #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:358
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:601
int globus_bool_t
Boolean type.
Definition: globus_types.h:93
globus_result_t globus_xio_attr_cntl(attr, driver, GLOBUS_XIO_FILE_SET_MODE, int mode)
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:522
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:587
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_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_server_cntl(server, driver, GLOBUS_XIO_TCP_GET_HANDLE, globus_xio_system_socket_t *handle_out)
List data type.
Definition: globus_list.h:44
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
size_t globus_size_t
Standard size of memory objectThe globus_size_t is the size of a memory object. It is identical to si...
Definition: globus_types.h:48
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
unsigned char globus_byte_t
Unsigned byte datatypeThis is used for byte-addressable arrays of arbitrary data which is not subject...
Definition: globus_types.h:85
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_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
Headers common to all of Globus.
uint32_t globus_result_t
Definition: globus_types.h:99
void(* globus_xio_server_callback_t)(globus_xio_server_t server, void *user_arg)
Definition: globus_xio.h:372
globus_result_t globus_xio_data_descriptor_cntl(dd, driver, GLOBUS_XIO_HTTP_GET_REQUEST, char **method, char **uri, globus_xio_http_version_t *http_version, globus_hashtable_t *headers)
globus_result_t globus_xio_handle_cntl(handle, driver, GLOBUS_XIO_FILE_GET_HANDLE, globus_xio_system_file_t *handle_out)
globus_result_t globus_xio_close(globus_xio_handle_t handle, globus_xio_attr_t attr)
Definition: globus_xio_handle.c:3582
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:619
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
Module Descriptor.
Definition: globus_module.h:71