NAME

       Driver Programming -

   Typedefs
       typedef void(* globus_xio_driver_callback_t )(globus_xio_operation_t op, globus_result_t
           result, void *user_arg)
       typedef void(* globus_xio_driver_data_callback_t )(globus_xio_operation_t op,
           globus_result_t result, globus_size_t nbytes, void *user_arg)
       typedef globus_result_t(* globus_xio_driver_attr_init_t )(void **out_driver_attr)
       typedef globus_result_t(* globus_xio_driver_attr_copy_t )(void **dst, void *src)
       typedef globus_result_t(* globus_xio_driver_attr_destroy_t )(void *driver_attr)
       typedef globus_result_t(* globus_xio_driver_attr_cntl_t )(void *attr, int cmd, va_list ap)
       typedef globus_result_t(* globus_xio_driver_server_init_t )(void *driver_attr, const
           globus_xio_contact_t *contact_info, globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_server_destroy_t )(void *driver_server)
       typedef globus_result_t(* globus_xio_driver_server_accept_t )(void *driver_server,
           globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_server_cntl_t )(void *driver_server, int cmd,
           va_list ap)
       typedef globus_result_t(* globus_xio_driver_link_destroy_t )(void *driver_link)
       typedef globus_result_t(* globus_xio_driver_transform_open_t )(const globus_xio_contact_t
           *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_transport_open_t )(const globus_xio_contact_t
           *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_handle_cntl_t )(void *handle, int cmd, va_list
           ap)
       typedef globus_result_t(* globus_xio_driver_close_t )(void *driver_handle, void
           *driver_attr, globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_read_t )(void *driver_specific_handle, const
           globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)
       typedef globus_result_t(* globus_xio_driver_write_t )(void *driver_specific_handle, const
           globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)

   Functions
       globus_result_t globus_xio_driver_handle_cntl (globus_xio_driver_handle_t handle,
           globus_xio_driver_t driver, int cmd,...)
       void globus_xio_driver_finished_accept (globus_xio_operation_t op, void *driver_link,
           globus_result_t result)
       globus_result_t globus_xio_driver_pass_open (globus_xio_operation_t op, const
           globus_xio_contact_t *contact_info, globus_xio_driver_callback_t cb, void *user_arg)
       void globus_xio_driver_finished_open (void *driver_handle, globus_xio_operation_t op,
           globus_result_t result)
       globus_result_t globus_xio_driver_operation_create (globus_xio_operation_t *operation,
           globus_xio_driver_handle_t handle)
       globus_bool_t globus_xio_driver_operation_is_blocking (globus_xio_operation_t operation)
       globus_result_t globus_xio_driver_pass_close (globus_xio_operation_t op,
           globus_xio_driver_callback_t cb, void *user_arg)
       void globus_xio_driver_finished_close (globus_xio_operation_t op, globus_result_t result)
       globus_result_t globus_xio_driver_pass_read (globus_xio_operation_t op, globus_xio_iovec_t
           *iovec, int iovec_count, globus_size_t wait_for, globus_xio_driver_data_callback_t cb,
           void *user_arg)
       void globus_xio_driver_finished_read (globus_xio_operation_t op, globus_result_t result,
           globus_size_t nread)
       void globus_xio_driver_set_eof_received (globus_xio_operation_t op)
       globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)
       globus_result_t globus_xio_driver_pass_write (globus_xio_operation_t op,
           globus_xio_iovec_t *iovec, int iovec_count, globus_size_t wait_for,
           globus_xio_driver_data_callback_t cb, void *user_arg)
       void globus_xio_driver_finished_write (globus_xio_operation_t op, globus_result_t result,
           globus_size_t nwritten)
       globus_result_t globus_xio_driver_merge_operation (globus_xio_operation_t top_op,
           globus_xio_operation_t bottom_op)

Detailed Description

       The set of interface functions that the driver author must implement to create a driver
       and the functions to assist in the creation.

       Driver attribute functions

       If the driver wishes to provide driver specific attributes to the user it must implement
       the following functions:

       globus_xio_driver_attr_init_t globus_xio_driver_attr_copy_t globus_xio_driver_attr_cntl_t
       globus_xio_driver_attr_destroy_t

Typedef Documentation

   typedef void(* globus_xio_driver_callback_t)(globus_xio_operation_t op, globus_result_t
       result, void *user_arg)
       callback interface

       This is the function signature of callbacks for the globus_xio_driver_open/close().

       Parameters:
           op The operation structure associated with the open or the close requested operation.
           The driver should call the appropriate finished operation to clean up this structure.
           result The result of the requested data operation
           user_arg The user pointer that is threaded through to the callback.

   typedef void(* globus_xio_driver_data_callback_t)(globus_xio_operation_t op, globus_result_t
       result, globus_size_t nbytes, void *user_arg)
       Data Callback interface

       This is the function signature of read and write operation callbacks.

       Parameters:
           op The operation structure associated with the read or write operation request. The
           driver should call the approriate finished operation when it receives this operation.
           result The result of the requested data operation
           nbytes the number of bytes read or written
           user_arg The user pointer that is threaded through to the callback.

   typedef globus_result_t(* globus_xio_driver_attr_init_t)(void **out_driver_attr)
       Create a driver specific attribute. The driver should implement this function to create a
       driver specific attribute and return it via the out_attr parameter.

   typedef globus_result_t(* globus_xio_driver_attr_copy_t)(void **dst, void *src)
       Copy a driver attr. When this function is called the driver will create a copy of the attr
       in parameter src and place it in the parameter dst.

   typedef globus_result_t(* globus_xio_driver_attr_destroy_t)(void *driver_attr)
       Destroy the driver attr. Clean up all resources associate with the attr.

   typedef globus_result_t(* globus_xio_driver_attr_cntl_t)(void *attr, int cmd, va_list ap)
       get or set information in an attr. The cmd parameter determines what functionality the
       user is requesting. The driver is resonsible for providing documentation to the user on
       all the possible values that cmd can be.

       Parameters:
           driver_attr The driver specific attr, created by globus_xio_driver_attr_init_t.
           cmd An integer representing what functionality the user is requesting.
           ap variable arguments. These are determined by the driver and the value of cmd.

   typedef globus_result_t(* globus_xio_driver_server_init_t)(void *driver_attr, const
       globus_xio_contact_t *contact_info, globus_xio_operation_t op)
       Initialize a server object. The driver developer should implement this function if their
       driver handles server operations (pasive opens). In the tcp driver this function should
       create a listener.

       Parameters:
           op An op which should be passed to globus_xio_driver_server_created. Note, that unlike
           most operations, the server is created from the bottom of the stack to the top.
           contact_info This the contact info for the stack below this driver. (entries will
           always be NULL for the transport driver)
           driver_attr A server attr if the user specified any driver specific attributes. This
           may be NULL.

       Returns:
           Returning GLOBUS_SUCCESS for this means that ` globus_xio_driver_pass_server_init
           returned success and the driver's server was successfully initialized.

   typedef globus_result_t(* globus_xio_driver_server_destroy_t)(void *driver_server)
       destroy a server. When this function is called the driver should free up all resources
       associated with a server.

       Parameters:
           server The server that the driver should clean up.
           driver_server The reference to the iunternal server that is being declaired invaild
           with this function call.

   typedef globus_result_t(* globus_xio_driver_server_accept_t)(void *driver_server,
       globus_xio_operation_t op)
       Accept a server connection. The driver developer should implement this function if their
       driver handles server operations. Once the accept operation completes, the connection is
       established. The user still has an opertunity to open the link or destroy it. They can
       query the link for additional information on which to base the decision to open.

       Parameters:
           driver_server The server object from which the link connection will be accepted.
           op The requested operation. When the driver is finished acepting the server connection
           it uses this structure to signal globus_xio that it has completed the operation.

   typedef globus_result_t(* globus_xio_driver_server_cntl_t)(void *driver_server, int cmd,
       va_list ap)
       Query a server for information. This function allows a user to request information from a
       driver specific server handle.

       Parameters:
           driver_server the server handle.
           cmd An integer telling the driver what operation to preform on this server handle.
           ap variable args.

   typedef globus_result_t(* globus_xio_driver_link_destroy_t)(void *driver_link)
       destroy a link The driver should clean up all resources associated with the link when this
       function is called.

       Parameters:
           driver_link The link to be destroyed.

   typedef globus_result_t(* globus_xio_driver_transform_open_t)(const globus_xio_contact_t
       *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
       Open a handle

       This is called when a user requests to open a handle.

       Parameters:
           driver_link Comes from server accept. Used to link an accepted connection to an xio
           handle. xio will destroy this object upon the return of this interface call.
           driver_attr A attribute describing how to open. This points to a piece of memory
           created by the globus_xio_driver_driver_attr_init_t interface funstion.
           contact_info Contains information about the requested resource. Its members may all be
           null (especially when link is not null). XIO will destroy this contact info upon
           return from the interface function
           op The requested operation. When the driver is finished opening the handle it uses
           this structure to signal globus_xio that it has completed the operation requested. It
           does this by calling globus_xio_driver_finished_open()

   typedef globus_result_t(* globus_xio_driver_transport_open_t)(const globus_xio_contact_t
       *contact_info, void *driver_link, void *driver_attr, globus_xio_operation_t op)
       transport open

   typedef globus_result_t(* globus_xio_driver_handle_cntl_t)(void *handle, int cmd, va_list ap)
       this call must return an GLOBUS_XIO_ERROR_COMMAND error for unsupported command numbers.
       (use GlobusXIOErrorInvalidCommand(cmd))

       Drivers that have reason to support the commands listed at globus_xio_handle_cmd_t should
       accept the xio generic cmd numbers and their driver specific command number. Do NOT
       implement those handle cntls unless you really are the definitive source.

   typedef globus_result_t(* globus_xio_driver_close_t)(void *driver_handle, void *driver_attr,
       globus_xio_operation_t op)
       Close an open handle

       This is called when a user requests to close a handle. The driver implemntor should clean
       up all resources connected to there driver handle when this function is called.

       Parameters:
           driver_specific_handle The driver handle to be closed.
           driver_attr A driver specific attr which may be used to alter how a close is performed
           (e,g, caching drivers)
           op The requested operation. When the driver is finished closing the handle it uses
           this structure to signal globus_xio that it has completed the operation requested. It
           does this by calling globus_xio_driver_finished_close()

   typedef globus_result_t(* globus_xio_driver_read_t)(void *driver_specific_handle, const
       globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)
       Read data from an open handle. This function is called when the user requests to read data
       from a handle. The driver author shall implement all code needed to for there driver to
       complete a read operations.

       Parameters:
           driver_handle The driver handle from which data should be read.
           iovec An io vector pointing to the buffers to be read into.
           iovec_count The number if entries in the io vector.
           op The requested operation. When the driver is finished fullfilling the requested read
           operation it must use this structure to signal globus_xio that the operation is
           completed. This is done by calling globus_xio_driver_finished_operation()..

   typedef globus_result_t(* globus_xio_driver_write_t)(void *driver_specific_handle, const
       globus_xio_iovec_t *iovec, int iovec_count, globus_xio_operation_t op)
       Write data from an open handle. This function is called when the user requests to write
       data to a handle. The driver author shall implement all code needed to for there driver to
       complete write operations.

       Parameters:
           driver_handle The driver handle to which data should be writen.
           iovec An io vector pointing to the buffers to be written.
           iovec_count The number if entries in the io vector.
           op The requested operation. When the driver is finished fullfilling the requested read
           operation it must use this structure to signal globus_xio that the operation is
           completed. This is done by calling globus_xio_driver_finished_operation()..

Function Documentation

   globus_result_t globus_xio_driver_handle_cntl (globus_xio_driver_handle_thandle,
       globus_xio_driver_tdriver, intcmd, ...)
       Touch driver specific information in a handle object. pass the driver to control a
       specific driver pass NULL for driver for XIO specific cntls pass GLOBUS_XIO_QUERY for
       driver to try each driver (below current) in order

       References globus_xio_driver_handle_cntl().

   void globus_xio_driver_finished_accept (globus_xio_operation_top, void *driver_link,
       globus_result_tresult)
       Driver API finished accept. This function should be called to signal globus_xio that it
       has completed the accept operation requested of it. It will free up resources associated
       with the accept_op and potientially cause xio to pop the signal up the driver stack.

       Parameters:
           op The requested accept operation that has completed.
           driver_link This is the initialized driver link that is that will be passed to the
           open interface when this handle is opened.
           result Return status of the completed operation

       References globus_xio_driver_finished_accept().

   globus_result_t globus_xio_driver_pass_open (globus_xio_operation_top, const
       globus_xio_contact_t *contact_info, globus_xio_driver_callback_tcb, void *user_arg)
       Driver API Open

       This function will pass an open request down the driver stack. Upon completion of the open
       operation globus_xio will call the cb function, at which point the handle structure will
       be intialized and available for use.

       As soon as the function returns the handle is valid for creating other operations.

       Parameters:
           op The operation from which the handle will be established. This parameter is used to
           determine what drivers are in the stack and other such information.
           contact_info The contact info describing the resource the driver below should open.
           This will normally be the same contact info that was passed in on the open interface.
           cb The function to be called wehn the open operation is complete.
           user_arg a user pointer that will be threaded through to the callback.

       References globus_xio_driver_pass_open().

   void globus_xio_driver_finished_open (void *driver_handle, globus_xio_operation_top,
       globus_result_tresult)
       Driver API finished open

       This function should be called to signal globus_xio that it has completed the open
       operation requested of it. It will free up resources associated with the op and
       potientially cause xio to pop the signal up the driver stack.

       Parameters:
           driver_handle The driver specific handle pointer that will be passed to future
           interface funstion calls.
           op The requested open operation that has completed.
           result Return status of the completed operation

       References globus_xio_driver_finished_open().

   globus_result_t globus_xio_driver_operation_create (globus_xio_operation_t *operation,
       globus_xio_driver_handle_thandle)
       Driver API Create Operation

       This function will create an operation from an initialized handle This operation can then
       be used for io operations related to the handle that created them.

       Parameters:
           operation The operation to be created. When this function returns this structure will
           be populated and available for use for the driver.
           handle The initialized handle representing the user handle from which the operation
           will be created.

       References globus_xio_driver_operation_create().

   globus_bool_t globus_xio_driver_operation_is_blocking (globus_xio_operation_toperation)
       Is Operation blocking. If the operation is blocking the driver developer may be able to
       make certian optimizations. The function returns true if the given operation was created
       via a user call to a blocking funciton.

   globus_result_t globus_xio_driver_pass_close (globus_xio_operation_top,
       globus_xio_driver_callback_tcb, void *user_arg)
       Driver API Close

       This function will pass a close request down the driver stack. Upon completion of the
       close operation globus_xio will call the funciton pointed to by the cb argument.

       Parameters:
           op The operation to pass along the driver stack for closing.
           cb A pointer to the function to be called once all drivers lower in the stack have
           closed.
           user_arg A user pointer that will be threaded through to the callback.

       References globus_xio_driver_pass_close().

   void globus_xio_driver_finished_close (globus_xio_operation_top, globus_result_tresult)
       Driver API finished_close

       The driver calls this function after completing a close operation on a driver_handle. Once
       this function returns the driver_handle is no longer valid.

       Parameters:
           op The close operation that has completed.
           result Return status of the completed operation

       References globus_xio_driver_finished_close().

   globus_result_t globus_xio_driver_pass_read (globus_xio_operation_top, globus_xio_iovec_t
       *iovec, intiovec_count, globus_size_twait_for, globus_xio_driver_data_callback_tcb, void
       *user_arg)
       Driver read

       This function passes a read operation down the driver stack. After this function is called
       the op structure is no longer valid. However when the driver stack finishes servicing the
       read request it will pass a new operation structure in the funciton pointed to by cb.
       Finishe read can be called on the new operation received.

       Parameters:
           op The operation structure representing this requested io operation.
           iovec A pointer to the array of iovecs.
           iovec_count The number of iovecs in the array.
           wait_for The minimum number of bytes to read before returning... if a driver has no
           specifc requirement, he should use the user's request... available via
           GlobusXIOOperationMinimumRead(op)
           cb The function to be called when the operation request is completed.
           user_arg A user pointer that will be threaded through to the callback.

       References globus_xio_driver_pass_read().

   void globus_xio_driver_finished_read (globus_xio_operation_top, globus_result_tresult,
       globus_size_tnread)
       Finished Read

       This function is called to signal globus_xio that the requested read operation has been
       completed.

       Parameters:
           op The operation structure representing the requested read operation.
           result Return status of the completed operation
           nread The number of bytes read

       References globus_xio_driver_finished_read().

   void globus_xio_driver_set_eof_received (globus_xio_operation_top)
       EOF state manipulation

       This function is used by drivers that allow multiple outstanding reads at a time. It can
       only be called on behalf of a read operation (while in the read interface call or the
       pass_read callback).

       Typical use for this would be to hold a driver specific lock and call this when an
       internal eof has been received. The read operation this is called on behalf of must be
       finished with an eof error or the results are undefined.

       In general, you should not have an eof flag in your driver. Use this call and
       globus_xio_driver_eof_received() instead. This is necessary to support xio's automatic eof
       resetting. If your driver absolutely can not be read after an eof has been set, then you
       will need your own eof flag.

       This call will typically only be used just before a finished_read() call.

       Parameters:
           op The operation structure representing the requested read operation.

       References globus_xio_driver_set_eof_received().

   globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_top)
       EOF state checking

       This function is used by drivers that allow multiple outstanding reads at a time. It can
       only be called on behalf of a read operation (while in the read interface call or the
       pass_read callback).

       Typical use for this would be to hold a driver specific lock (the same one used when
       calling globus_xio_driver_set_eof_received()) and call this to see if an eof has been
       received. If so, the operation should immediately be finished with an eof error (do not
       return an eof error).

       This call will typically only be used in the read interface call.

       Parameters:
           op The operation structure representing the requested read operation.

       Returns:
           GLOBUS_TRUE if eof received, GLOBUS_FALSE otherwise.

       References globus_xio_driver_eof_received().

   globus_result_t globus_xio_driver_pass_write (globus_xio_operation_top, globus_xio_iovec_t
       *iovec, intiovec_count, globus_size_twait_for, globus_xio_driver_data_callback_tcb, void
       *user_arg)
       Driver write

       This function passes a write operation down the driver stack. After this function is
       called the op structure is no longer valid. However when the driver stack finishes
       servicing the write request it will pass a new operation structure in the funciton pointed
       to by cb. Finished write can be called on the new operation received.

       Parameters:
           op The operation structure representing this requested io operation.
           iovec A pointer to the array of iovecs.
           iovec_count The number of iovecs in the array.
           wait_for The minimum number of bytes to write before returning... if a driver has no
           specifc requirement, he should use the user's request... available via
           GlobusXIOOperationMinimumWrite(op)
           cb The function to be called when the operation request is completed.
           user_arg A user pointer that will be threaded through to the callback.

       References globus_xio_driver_pass_write().

   void globus_xio_driver_finished_write (globus_xio_operation_top, globus_result_tresult,
       globus_size_tnwritten)
       Finished Write

       This function is called to signal globus_xio that the requested write operation has been
       completed.

       Parameters:
           op The operation structure representing the requested write operation.
           result Return status of the completed operation
           nwritten The number of bytes written

       References globus_xio_driver_finished_write().

   globus_result_t globus_xio_driver_merge_operation (globus_xio_operation_ttop_op,
       globus_xio_operation_tbottom_op)
       Finishes an operation and merge two op structures. (XXX not implemented yet)

       This function will join to operations together and signal globus_xio that it has
       completed. This is an advanced function. Most drivers will not require its use. This
       function takes an operation that was created by this driver and passed on to drivers lower
       on the stack and an operation that came in on the interface function (that has seen the
       top half of the stack) and joins them together. The purpose of this function is to join
       data descriptors that were prestaged and cached with those that have later come in at the
       users request. See the read ahead doc for more information.

       Parameters:
           top_op The operation that has seen the top part of the driver stack.
           bottom_op The operation that has seen the bottom part of the driver stack.

       (result is always success in this case.. if there is an error, use the other finish()
       call)

Author

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