NAME

       User API Assistance. -

       Help understanding the globus_xio api.

       Stack Constuction.
           The driver stack that is used for a given xio handle is constructed using a
           globus_xio_stack_t. Each driver is loaded by name and pushed onto a stack.

       *  stack setup example:
       *
       *  // First load the drivers
       *  globus_xio_driver_load("tcp", &tcp_driver);
       *  globus_xio_driver_load("gsi", &gsi_driver);
       *
       *  //build the stack
       *  globus_xio_stack_init(&stack);
       *  globus_xio_stack_push_driver(stack, tcp_driver, NULL);
       *  globus_xio_stack_push_driver(stack, gsi_driver, NULL);
       *

       Servers
           A server data structure provides functionality for passive opens. A server is
           initialized and bound to a protocol stack and set of attributes with the function
           globus_xio_server_create(). Once a server is created many 'connections' can be
           accepted. Each connection will result in an intialized handle which can later be
           opened.

       *
       *  globus_xio_server_t             server;
       *  globus_xio_attr_t               attr;
       *
       *  globus_xio_attr_init(&attr);
       *  globus_xio_server_create(&server_handle, attr, stack);
       *  globus_xio_server_accept(&handle, server);
       *
       *

       Handle Construction
           There are two ways to create a handle. The first is for use as a client (one that is
           doing an active open). The function: globus_xio_handle_create() is used to create such
           a handle and bind that handle to a protocol stack.

       *  globus_xio_handle_create(&handle, stack);
       *

       The second means of creating a handle is for use as a server (one that is doing a passive
       open). This is created by accepting a connection on a server_handle with the function
       globus_xio_server_accept() or globus_xio_server_register_accept().

       Mutable attrs can be altered via a call to globus_xio_handle_cntl() described later.

       *  globus_xio_server_accept(&xio_handle, server_handle);
       *

       once a handle is intialized the user can call globus_xio_open() to begin the open process.

       Timeouts
           A user can set a timeout value for any io operation. Each IO operation (open close
           read write) can have its own timeout value. If no timeout is set the operation will be
           allowed to infinitly block.
            When time expires the outstanding operation is canceled. If the timeout callback for
           the given operation is not NULL it is called first to notify the user that the
           operation timed out and give the user a chance to ignore that timeout. If canceled,
           the user will get the callback they registered for the operation as well, but it will
           come with an error indicating that it has been canceled.
            It is possiblie that part of an io operation will complete before the timeout
           expires. In this case the opperation can still be canceled. The user will receive
           there IO callback with and error set and the length value appropriately set to
           indicate how much of the operation completed.

       Data Desciptor
           The data descriptor ADT gives the user a means of attaching/extracting meta data to a
           read or write operation.
            Things like offset, out of band message, and other driver specific meta data are
           contained in the data descriptor.
            Data descriptors are passed to globus_xio in globus_xio_read() and
           globus_xio_write(). Within the globus_xio framework it is acceptable to pass NULL
           instead of a valid data_descriptor,

       *  ex:
       *  globus_xio_data_descriptor_init(&desc);
       *  globus_xio_data_descriptor_cntl(desc,
       *      tcp_driver,
       *      GLOBUS_XIO_TCP_SET_SEND_FLAGS,
       *      GLOBUS_XIO_TCP_SEND_OOB);
       *

       User Attributes
           Globus XIO uses a single attribute object for all of its functions. Attributes give an
           the user an extenable mechanism to alter default values which control parameters in an
           operation.
            In most of the globus xio user api functions a user passes an attribute as a
           parameter. In many cases the user may ignore the attribute parameter and just pass in
           NULL. However at times the user will wish to tweak the operation. The attribute
           structure is used for this tweaking.
            There are only three attribute functions. globus_xio_attr_init globus_xio_attr_cntl
           and globus_xio_attr_destroy. The init and destroy functions are very simple and
           require little explaination. Before an attribute can be used it must be intialized,
           and to clean up all memory associated with it the user must call destroy on it.
            The function globus_xio_attr_cntl manipulates values in the attribute. For more info
           on it see globus_xio_attr_cntl.

Author

       Generated automatically by Doxygen for globus xio from the source code.