.TH "GLOBUS_XIO_API_ASSIST" 3 "Version 6.6" "globus_xio" \" -*- nroff -*-
.ad l
.nh
.SH NAME
GLOBUS_XIO_API_ASSIST \- XIO Examples
.PP
 \- XIO Examples\&.  

.SH SYNOPSIS
.br
.PP
.SH "Detailed Description"
.PP 
XIO Examples\&. 

Help understanding the globus_xio api\&.
.SH "Stack Construction"
.PP
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\&.
.PP
Stack setup example: 
.PP
.nf
// 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);

.fi
.PP
.SH "Servers"
.PP
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 \fBglobus_xio_server_create()\fP\&. Once a server is created many 'connections' can be accepted\&. Each connection will result in an initialized handle which can later be opened\&.
.PP
.PP
.nf
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);
.fi
.PP
.SH "Handle Construction"
.PP
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: \fBglobus_xio_handle_create()\fP is used to create such a handle and bind that handle to a protocol stack\&.
.PP
.PP
.nf
globus_xio_handle_create(&handle, stack);
.fi
.PP
.PP
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 \fBglobus_xio_server_accept()\fP or \fBglobus_xio_server_register_accept()\fP\&.
.PP
Mutable attrs can be altered via a call to \fBglobus_xio_handle_cntl()\fP described later\&.
.PP
.PP
.nf
globus_xio_server_accept(&xio_handle, server_handle);
.fi
.PP
.PP
once a handle is initialized the user can call \fBglobus_xio_open()\fP to begin the open process\&.
.SH "Timeouts"
.PP
A user can set a timeout value for any I/O operation\&. Each I/O operation (open close read write) can have its own timeout value\&. If no timeout is set the operation will be allowed to infinitely block\&.
.PP
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\&.
.PP
It is possible that part of an I/O operation will complete before the timeout expires\&. In this case the operation 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\&.
.PP
Timeouts are registered by using the following handle_cntl values:
.PP
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_ALL
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_OPEN
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_CLOSE
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_READ
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_WRITE
.IP "\(bu" 2
GLOBUS_XIO_ATTR_SET_TIMEOUT_ACCEPT
.PP
.PP
Each of these cntls expect three parameters:
.PP
.IP "\(bu" 2
globus_xio_timeout_callback_t callback_function
.IP "\(bu" 2
globus_reltime_t * delay_time
.IP "\(bu" 2
void * callback_arg
.PP
.SH "Data Descriptor"
.PP
The data descriptor ADT gives the user a means of attaching/extracting meta data to a read or write operation\&.
.br
 Things like offset, out of band message, and other driver specific meta data are contained in the data descriptor\&.
.br
 Data descriptors are passed to globus_xio in \fBglobus_xio_read()\fP and \fBglobus_xio_write()\fP\&. Within the globus_xio framework it is acceptable to pass NULL instead of a valid data_descriptor,
.PP
Example: 
.PP
.nf
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);

.fi
.PP
.SH "User Attributes"
.PP
Globus XIO uses a single attribute object for all of its functions\&. Attributes give the user an extensible mechanism to alter default values which control parameters in an operation\&.
.PP
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\&.
.PP
There are only three attribute functions\&. \fBglobus_xio_attr_init\fP \fBglobus_xio_attr_cntl\fP and \fBglobus_xio_attr_destroy\fP\&. The init and destroy functions are very simple and require little explanation\&. Before an attribute can be used it must be initialized, and to clean up all memory associated with it the user must call destroy on it\&.
.PP
The function \fBglobus_xio_attr_cntl\fP manipulates values in the attribute\&. For more info on it see \fBglobus_xio_attr_cntl\fP\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for globus_xio from the source code\&.