globus_xio.h

00001 /*
00002  * Copyright 1999-2006 University of Chicago
00003  * 
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  * 
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #if !defined(GLOBUS_XIO_H)
00018 #define GLOBUS_XIO_H
00019 
00020 #include "globus_common.h"
00021 #include "globus_xio_types.h"
00022 #include "globus_xio_util.h"
00023 #include "globus_xio_load.h"
00024 
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 #ifndef GLOBUS_GLOBAL_DOCUMENT_SET
00030 
00034 #endif
00035 
00189 /*************************************************************************
00190  *    define types
00191  ************************************************************************/
00192 
00227 globus_result_t
00228 globus_xio_attr_init(
00229     globus_xio_attr_t *                 attr);
00230 
00257 globus_result_t
00258 globus_xio_attr_cntl(
00259     globus_xio_attr_t                   attr,
00260     globus_xio_driver_t                 driver,
00261     int                                 cmd,
00262     ...);
00263 
00269 globus_result_t
00270 globus_xio_attr_copy(
00271     globus_xio_attr_t *                 dst,
00272     globus_xio_attr_t                   src);
00273 
00283 globus_result_t
00284 globus_xio_attr_destroy(
00285     globus_xio_attr_t                   attr);
00286 
00287 /*************************************************************************
00288  *                      Stack functions
00289  *                      ---------------
00290  ************************************************************************/
00291 
00296 globus_result_t
00297 globus_xio_stack_init(
00298     globus_xio_stack_t *                stack,
00299     globus_xio_attr_t                  stack_attr);
00300 
00309 globus_result_t
00310 globus_xio_stack_push_driver(
00311     globus_xio_stack_t                  stack,
00312     globus_xio_driver_t                 driver);
00313 
00318 globus_result_t
00319 globus_xio_stack_copy(
00320     globus_xio_stack_t *                dst,
00321     globus_xio_stack_t                  src);
00322 
00327 globus_result_t
00328 globus_xio_stack_destroy(
00329     globus_xio_stack_t                  stack);
00330 
00331 /*-------------------------------------------------------------------------
00332  *  server 
00333  *-----------------------------------------------------------------------*/
00356 typedef void
00357 (*globus_xio_accept_callback_t)(
00358     globus_xio_server_t                 server,
00359     globus_xio_handle_t                 handle,
00360     globus_result_t                     result,
00361     void *                              user_arg);
00362 
00370 typedef void
00371 (*globus_xio_server_callback_t)(
00372     globus_xio_server_t                 server,
00373     void *                              user_arg);
00374 
00393 globus_result_t
00394 globus_xio_server_create(
00395     globus_xio_server_t *               server,
00396     globus_xio_attr_t                   server_attr,
00397     globus_xio_stack_t                  stack);
00398 
00413 globus_result_t
00414 globus_xio_server_get_contact_string(
00415     globus_xio_server_t                 server,
00416     char **                             contact_string);
00417 
00425 globus_result_t
00426 globus_xio_server_register_close(
00427     globus_xio_server_t                 server,
00428     globus_xio_server_callback_t        cb,
00429     void *                              user_arg);
00430 
00435 globus_result_t
00436 globus_xio_server_close(
00437     globus_xio_server_t                 server);
00438 
00447 globus_result_t
00448 globus_xio_server_cntl(
00449     globus_xio_server_t                 server,
00450     globus_xio_driver_t                 driver,
00451     int                                 cmd,
00452     ...);
00453 
00462 globus_result_t
00463 globus_xio_server_accept(
00464     globus_xio_handle_t *               out_handle,
00465     globus_xio_server_t                 server);
00466 
00474 globus_result_t
00475 globus_xio_server_register_accept(
00476     globus_xio_server_t                 server,
00477     globus_xio_accept_callback_t        cb,
00478     void *                              user_arg);
00479 
00488 globus_result_t
00489 globus_xio_handle_create(
00490     globus_xio_handle_t *               handle,
00491     globus_xio_stack_t                  stack);
00492 
00493 /******************************************************************
00494  *                      handle construction
00495  *****************************************************************/
00496 
00497 /******************************************************************
00498  *                      setting timeout values
00499  *****************************************************************/
00500 
00520 typedef globus_bool_t
00521 (*globus_xio_timeout_callback_t)(
00522     globus_xio_handle_t                 handle,
00523     globus_xio_operation_type_t         type,
00524     void *                              user_arg);
00525 
00526 typedef globus_bool_t
00527 (*globus_xio_timeout_server_callback_t)(
00528     globus_xio_server_t                 server,
00529     globus_xio_operation_type_t         type);
00530 
00531 
00532 /******************************************************************
00533  *                      data descriptor
00534  *****************************************************************/
00535 
00548 globus_result_t
00549 globus_xio_data_descriptor_init(
00550     globus_xio_data_descriptor_t *      data_desc,
00551     globus_xio_handle_t                 handle);
00552 
00557 globus_result_t
00558 globus_xio_data_descriptor_destroy(
00559     globus_xio_data_descriptor_t        data_desc);
00560 
00569 globus_result_t
00570 globus_xio_data_descriptor_cntl(
00571     globus_xio_data_descriptor_t        data_desc,
00572     globus_xio_driver_t                 driver,
00573     int                                 cmd,
00574     ...);
00575 
00576 /*********************************************************************
00577  *                         callbacks
00578  ********************************************************************/
00586 typedef void (*globus_xio_callback_t)(
00587     globus_xio_handle_t                 handle,
00588     globus_result_t                     result,
00589     void *                              user_arg);
00590 
00600 typedef void (*globus_xio_data_callback_t)(
00601     globus_xio_handle_t                 handle, 
00602     globus_result_t                     result,
00603     globus_byte_t *                     buffer,
00604     globus_size_t                       len,
00605     globus_size_t                       nbytes, 
00606     globus_xio_data_descriptor_t        data_desc,
00607     void *                              user_arg);
00608 
00618 typedef void (*globus_xio_iovec_callback_t)(
00619     globus_xio_handle_t                 handle,
00620     globus_result_t                     result,
00621     globus_xio_iovec_t *                iovec,
00622     int                                 count,
00623     globus_size_t                       nbytes,
00624     globus_xio_data_descriptor_t        data_desc,
00625     void *                              user_arg);
00626 
00639 globus_result_t
00640 globus_xio_handle_cntl(
00641     globus_xio_handle_t                 handle,
00642     globus_xio_driver_t                 driver,
00643     int                                 cmd,
00644     ...);
00645 
00706 globus_result_t
00707 globus_xio_register_open(
00708     globus_xio_handle_t                 handle,
00709     const char *                        contact_string,
00710     globus_xio_attr_t                   attr,
00711     globus_xio_callback_t               cb,
00712     void *                              user_arg);
00713 
00718 globus_result_t
00719 globus_xio_open(
00720     globus_xio_handle_t                 handle,
00721     const char *                        contact_string,
00722     globus_xio_attr_t                   attr);
00723 
00728 globus_result_t
00729 globus_xio_register_read(
00730     globus_xio_handle_t                 handle,
00731     globus_byte_t *                     buffer,
00732     globus_size_t                       buffer_length,
00733     globus_size_t                       waitforbytes,
00734     globus_xio_data_descriptor_t        data_desc,
00735     globus_xio_data_callback_t          cb,
00736     void *                              user_arg);
00737 
00742 globus_result_t
00743 globus_xio_read(
00744     globus_xio_handle_t                 handle,
00745     globus_byte_t *                     buffer,
00746     globus_size_t                       buffer_length,
00747     globus_size_t                       waitforbytes,
00748     globus_size_t *                     nbytes,
00749     globus_xio_data_descriptor_t        data_desc);
00750 
00755 globus_result_t
00756 globus_xio_register_readv(
00757     globus_xio_handle_t                 handle,
00758     globus_xio_iovec_t *                iovec,
00759     int                                 iovec_count,
00760     globus_size_t                       waitforbytes,
00761     globus_xio_data_descriptor_t        data_desc,
00762     globus_xio_iovec_callback_t         cb,
00763     void *                              user_arg);
00764 
00769 globus_result_t
00770 globus_xio_readv( 
00771     globus_xio_handle_t                 handle,
00772     globus_xio_iovec_t *                iovec,
00773     int                                 iovec_count,
00774     globus_size_t                       waitforbytes,
00775     globus_size_t *                     nbytes,
00776     globus_xio_data_descriptor_t        data_desc);
00777 
00782 globus_result_t
00783 globus_xio_register_write(
00784     globus_xio_handle_t                 handle,
00785     globus_byte_t *                     buffer,
00786     globus_size_t                       buffer_length,
00787     globus_size_t                       waitforbytes,
00788     globus_xio_data_descriptor_t        data_desc,
00789     globus_xio_data_callback_t          cb,
00790     void *                              user_arg);
00791 
00796 globus_result_t
00797 globus_xio_write(
00798     globus_xio_handle_t                 handle,
00799     globus_byte_t *                     buffer,
00800     globus_size_t                       buffer_length,
00801     globus_size_t                       waitforbytes,
00802     globus_size_t *                     nbytes,
00803     globus_xio_data_descriptor_t        data_desc);
00804 
00809 globus_result_t
00810 globus_xio_register_writev(
00811     globus_xio_handle_t                 handle,
00812     globus_xio_iovec_t *                iovec,
00813     int                                 iovec_count,
00814     globus_size_t                       waitforbytes,
00815     globus_xio_data_descriptor_t        data_desc,
00816     globus_xio_iovec_callback_t         cb,
00817     void *                              user_arg);
00818 
00823 globus_result_t
00824 globus_xio_writev(
00825     globus_xio_handle_t                 handle,
00826     globus_xio_iovec_t *                iovec,
00827     int                                 iovec_count,
00828     globus_size_t                       waitforbytes,
00829     globus_size_t *                     nbytes,
00830     globus_xio_data_descriptor_t        data_desc);
00831 
00832 
00836 globus_result_t
00837 globus_xio_handle_cancel_operations(
00838     globus_xio_handle_t                 handle,
00839     int                                 mask);
00840 
00841 globus_result_t
00842 globus_xio_server_cancel_accept(
00843     globus_xio_server_t                 server);
00844 
00865 globus_result_t
00866 globus_xio_register_close(
00867     globus_xio_handle_t                 handle,
00868     globus_xio_attr_t                   attr,
00869     globus_xio_callback_t               cb,
00870     void *                              user_arg);
00871 
00876 globus_result_t
00877 globus_xio_close(
00878     globus_xio_handle_t                 handle,
00879     globus_xio_attr_t                   attr);
00880 
00881 /*
00882  *                         signal stuff
00883  *  TODO:
00884  *  Signals are not implemented in the first release.
00885  *  =================================================
00886  *
00887  *  Signals in Globus XIO give the user a means of requesting 
00888  *  notification when given things in the system change.  
00889  *
00890  *  For example:
00891  *  It may be useful for the user of globus_xio to know when/if the 
00892  *  optimal post buffer size changes.  The optimal post buffer size is
00893  *  a value that tells the user the best possible length of a buffer to 
00894  *  post for an I/O operation.  This value is mutable and can be changed
00895  *  by events internal to globus_xio of which the user is unaware.
00896  *  The signal API allows the user to register for notification of when
00897  *  this value changes.
00898  *
00899  *  Globus XIO enumerates the signal types for which the user can register.  
00900  *  One of these types is GLOBUS_XIO_DRIVER_SPECIFIC.  This type allows
00901  *  the user to catch driver specific signals.  A driver specific signal
00902  *  example could be when the TCP window size changes.  Only a TCP driver
00903  *  can be aware of this information so only it can send the signal.  
00904  *  Further a user only knows to listen for that signal if it knows that
00905  *  tcp is in its driver stack.
00906  *
00907  *  Once a signal is delivered to the globus_xio user the handle can be 
00908  *  queried for specific information regarding that signal.
00909  *  Event Types.
00910  *  @ingroup GLOBUS_XIO_API
00911  *  
00912  *  An enumeration of the signal types of which globus_xio is aware.  
00913 enum globus_xio_signal_type_t
00914 {
00915     GLOBUS_XIO_SIGNAL_BUFFER_POST_SIZE,
00916     GLOBUS_XIO_SIGNAL_OPTIMAL_BUFFER_SIZE,
00917     GLOBUS_XIO_SIGNAL_DRIVER_SPECIFIC,
00918 };
00919  *
00920  *  Signal Callback
00921  *  @ingroup GLOBUS_XIO_API
00922  *
00923  *  The callback signature for signal events.
00924  *
00925  *  @param handle
00926  *         The handle associated with the event.
00927  * 
00928  *  @param signal_type
00929  *         The type of signal that occurred.
00930  *
00931  *  @param driver
00932  *         The driver that caused this event.  If it is not a driver
00933  *         specific signal than this will be NULL.
00934 typedef void
00935 (*globus_xio_signal_callback_t)(
00936     globus_xio_handle_t                     handle,
00937     globus_xio_signal_type_t                signal_type,
00938     globus_xio_driver_t                     driver);
00939  *
00940  *  Register a signal listener.
00941  *  @ingroup GLOBUS_XIO_API
00942  *
00943  *  Request notification when event change in the system relating
00944  *  to a given handle.
00945  *
00946  *  @param handle
00947  *         The handle on which the user would like to receive 
00948  *         notifications.
00949  *
00950  *  @param signal_mask
00951  *         A mask of the signals to be observed.
00952  *
00953  *  @param driver
00954  *         The driver to which the signal mask applies.  If this is for a
00955  *         non driver specific event this will be null.  This function
00956  *         must be called once for every driver of interest.
00957  *
00958  *  @param callback
00959  *         The function to be called when the given events occur.
00960  *
00961  *  @param user_arg
00962  *         A user pointed threaded through to the callback.
00963 globus_result_t
00964 globus_xio_handle_register_signal_handler(
00965     globus_xio_handle_t                     handle,
00966     int                                     signal_mask,
00967     globus_xio_driver_t                     driver,
00968     globus_xio_signal_callback_t            callback,
00969     void *                                  user_arg);
00970 
00971  *  Register a signal listener.
00972  *  @ingroup GLOBUS_XIO_API
00973  *
00974  *  Request notification when event change in the system relating
00975  *  to a given factory.
00976  *
00977  *  @param factory
00978  *         The factory on which the user would like to receive 
00979  *         notifications of events.
00980  *
00981  *  @param signal_mask
00982  *         A mask of the signals to be observed.
00983  *
00984  *  @param driver
00985  *         The driver to which the signal mask applies.  If this is for a
00986  *         non driver specific event this will be null.  This function
00987  *         must be called once for every driver of interest.
00988  *
00989  *  @param callback
00990  *         The function to be called when the given events occur.
00991  *
00992  *  @param user_arg
00993  *         A user pointed threaded through to the callback.
00994 globus_result_t
00995 globus_xio_server_register_signal_handler(
00996     globus_xio_server_t                     factory,
00997     int                                     signal_mask,
00998     globus_xio_driver_t                     driver,
00999     globus_xio_callback_t                   callback,
01000     void *                                  user_arg);
01001  */
01002 
01003 
01004 globus_xio_driver_list_ent_t *
01005 globus_xio_driver_list_find_driver(
01006     globus_list_t *                     driver_list,
01007     const char *                        driver_name);
01008 
01009 void
01010 globus_xio_driver_list_destroy(
01011     globus_list_t *                     driver_list,
01012     globus_bool_t                       unload);
01013 
01014 globus_result_t
01015 globus_xio_driver_list_to_stack_attr(
01016     globus_list_t *                     driver_list,
01017     globus_xio_stack_t                  stack,
01018     globus_xio_attr_t                   attr);
01019 
01020 globus_result_t
01021 globus_xio_driver_list_from_string(
01022     char *                              driver_string,
01023     globus_list_t **                    driver_list,
01024     globus_hashtable_t *                safe_table);
01025 
01026 globus_result_t
01027 globus_xio_driver_safe_table_from_string(
01028     char *                              driver_string,
01029     globus_hashtable_t *                safe_table);
01030 
01031 globus_result_t
01032 globus_xio_driver_list_create_ent(
01033     const char *                        driver_desc,
01034     globus_xio_driver_t                 driver_in,
01035     globus_bool_t                       load,
01036     globus_xio_driver_list_ent_t **     ent_out);
01037 
01038 extern globus_module_descriptor_t       globus_i_xio_module;
01039 #define GLOBUS_XIO_MODULE &globus_i_xio_module
01040 
01041 #define _XIOSL(s) globus_common_i18n_get_string( \
01042                      GLOBUS_XIO_MODULE, \
01043                      s)
01044 
01072 globus_result_t
01073 globus_xio_handle_create_from_url(
01074     globus_xio_handle_t *           out_h,
01075     const char *                    scheme,
01076     globus_xio_attr_t               attr,
01077     char *                          param_string);
01078 
01079 #ifdef __cplusplus
01080 }
01081 #endif
01082 
01083 #endif

Generated on 25 Nov 2015 for globus_xio by  doxygen 1.4.7