Provided by: libglobus-ftp-control-doc_4.7-1_all bug

NAME

       globus_ftp_control.h -

SYNOPSIS

   Data Structures
       struct globus_ftp_control_dcau_subject_s
       struct globus_ftp_control_round_robin_s
       union globus_ftp_control_dcau_u
       union globus_ftp_control_layout_u
       union globus_ftp_control_parallelism_u
       struct globus_ftp_control_tcpbuffer_default_t
       struct globus_ftp_control_tcpbuffer_fixed_t
       struct globus_ftp_control_tcpbuffer_automatic_s
       union globus_ftp_control_tcpbuffer_t
       struct globus_ftp_control_auth_info_s

   Macros
       #define GLOBUS_FTP_CONTROL_MODULE   (&globus_i_ftp_control_module)

   Typedefs
       typedef enum
           globus_ftp_control_type_e globus_ftp_control_type_t"
       typedef enum
           globus_ftp_control_mode_e globus_ftp_control_mode_t"
       typedef enum
           globus_ftp_control_dcau_mode_e globus_ftp_control_dcau_mode_t"
       typedef struct
           globus_ftp_control_dcau_subject_s globus_ftp_control_dcau_subject_t"
       typedef enum
           globus_ftp_control_striping_mode_e globus_ftp_control_striping_mode_t"
       typedef struct
           globus_ftp_control_round_robin_s globus_ftp_control_round_robin_t"
       typedef union
           globus_ftp_control_dcau_u globus_ftp_control_dcau_t"
       typedef union
           globus_ftp_control_layout_u globus_ftp_control_layout_t"
       typedef enum
           globus_ftp_control_structure_e globus_ftp_control_structure_t"
       typedef enum
           globus_ftp_control_parallelism_mode_e globus_ftp_control_parallelism_mode_t"
       typedef union
           globus_ftp_control_parallelism_u globus_ftp_control_parallelism_t"
       typedef enum
           globus_ftp_control_tcpbuffer_mode_e globus_ftp_control_tcpbuffer_mode_t"
       typedef struct
           globus_ftp_control_tcpbuffer_automatic_s globus_ftp_control_tcpbuffer_automatic_t"
       typedef union
           globus_ftp_control_tcpbuffer_t globus_ftp_control_tcpbuffer_t"
       typedef struct
           globus_ftp_control_auth_info_s globus_ftp_control_auth_info_t"
       typedef void(* globus_ftp_control_response_callback_t )(void *callback_arg, struct
           globus_ftp_control_handle_s *handle, globus_object_t *error,
           globus_ftp_control_response_t *ftp_response)
       typedef void(* globus_ftp_control_callback_t )(void *callback_arg, struct
           globus_ftp_control_handle_s *handle, globus_object_t *error)
       typedef void(* globus_ftp_control_command_callback_t )(void *callback_arg, struct
           globus_ftp_control_handle_s *handle, globus_object_t *error, union
           globus_ftp_control_command_u *command)
       typedef void(* globus_ftp_control_auth_callback_t )(void *callback_arg, struct
           globus_ftp_control_handle_s *handle, globus_object_t *error,
           globus_ftp_control_auth_info_t *auth_result)
       typedef unsigned long globus_ftp_control_auth_requirements_t
       typedef void(* globus_ftp_control_data_callback_t )(void *callback_arg,
           globus_ftp_control_handle_t *handle, globus_object_t *error, globus_byte_t *buffer,
           globus_size_t length, globus_off_t offset, globus_bool_t eof)
       typedef void(* globus_ftp_control_server_callback_t )(void *callback_arg, struct
           globus_ftp_control_server_s *server_handle, globus_object_t *error)

   Enumerations
       enum globus_ftp_control_type_e
       enum globus_ftp_control_mode_e
       enum globus_ftp_control_dcau_mode_e
       enum globus_ftp_control_striping_mode_e
       enum globus_ftp_control_protection_t
       enum globus_ftp_control_delay_passive_t
       enum globus_ftp_control_structure_e
       enum globus_ftp_control_parallelism_mode_e
       enum globus_ftp_control_tcpbuffer_mode_e { GLOBUS_FTP_CONTROL_TCPBUFFER_DEFAULT,
           GLOBUS_FTP_CONTROL_TCPBUFFER_FIXED, GLOBUS_FTP_CONTROL_TCPBUFFER_AUTOMATIC }

   Functions
       globus_result_t globus_ftp_control_local_layout (globus_ftp_control_handle_t *handle,
           globus_ftp_control_layout_t *layout, globus_size_t data_size)
       globus_result_t globus_ftp_control_data_set_interface (globus_ftp_control_handle_t
           *handle, const char *interface_addr)
       globus_result_t globus_ftp_control_create_data_info (globus_ftp_control_handle_t *handle,
           globus_ftp_control_data_write_info_t *data_info, globus_byte_t *buffer, globus_size_t
           length, globus_off_t offset, globus_bool_t eof, globus_ftp_control_data_callback_t
           callback, void *callback_arg)
       globus_result_t globus_ftp_control_release_data_info (globus_ftp_control_handle_t *handle,
           globus_ftp_control_data_write_info_t *data_info)
       globus_result_t globus_ftp_control_data_write_stripe (globus_ftp_control_handle_t *handle,
           globus_byte_t *buffer, globus_size_t length, globus_off_t offset, globus_bool_t eof,
           int stripe_ndx, globus_ftp_control_data_callback_t callback, void *callback_arg)
       globus_result_t globus_X_ftp_control_data_write_stripe (globus_ftp_control_handle_t
           *handle, globus_byte_t *buffer, globus_size_t length, globus_off_t offset,
           globus_bool_t eof, int stripe_ndx, globus_ftp_control_data_write_info_t *data_info)

Detailed Description

       GSIFTP Control Connection API (Data structures and types)

Macro Definition Documentation

   #define GLOBUS_FTP_CONTROL_MODULE   (&globus_i_ftp_control_module)
       Module descriptor. The Globus FTP Control library uses the standard module activation and
       deactivation API to initialize it's state. Before any GSIFTP functions are called, the
       module must be activated

       *    globus_module_activate(GLOBUS_GSIFTP_CONTROL_MODULE);
       *

       This function returns GLOBUS_SUCCESS if the GSIFTP library was successfully initialized.
       This may be called multiple times.

       To deactivate the GSIFTP library, the following must be called

       *    globus_module_deactivate(GLOBUS_GSIFTP_CONTROL_MODULE);
       *

Typedef Documentation

   typedef enum globus_ftp_control_type_e  globus_ftp_control_type_t
       control structure types. The enumeration values match the character value of the argument
       to TYPE.

   typedef enum globus_ftp_control_mode_e  globus_ftp_control_mode_t
       control structure mode

   typedef enum globus_ftp_control_dcau_mode_e  globus_ftp_control_dcau_mode_t
       control dcau types

   typedef struct globus_ftp_control_dcau_subject_s  globus_ftp_control_dcau_subject_t
       control dcau subject authentication type

   typedef enum globus_ftp_control_striping_mode_e  globus_ftp_control_striping_mode_t
       control striping Types

   typedef struct globus_ftp_control_round_robin_s  globus_ftp_control_round_robin_t
       control striping round robin attribute structure

   typedef union globus_ftp_control_dcau_u  globus_ftp_control_dcau_t
       control dcau union

   typedef union globus_ftp_control_layout_u  globus_ftp_control_layout_t
       control striping attribute union

   typedef enum globus_ftp_control_structure_e  globus_ftp_control_structure_t
       control structure structure

   typedef enum globus_ftp_control_parallelism_mode_e  globus_ftp_control_parallelism_mode_t
       control parallelism Types

   typedef union globus_ftp_control_parallelism_u  globus_ftp_control_parallelism_t
       control parallelism attribute structure

   typedef enum globus_ftp_control_tcpbuffer_mode_e  globus_ftp_control_tcpbuffer_mode_t
       TCP Buffer Setting Modes.

   typedef struct globus_ftp_control_tcpbuffer_automatic_s
       globus_ftp_control_tcpbuffer_automatic_t
       Automatically set the TCP buffer/window size.

   typedef union globus_ftp_control_tcpbuffer_t  globus_ftp_control_tcpbuffer_t
       control tcpbuffer attribute structure

   typedef struct globus_ftp_control_auth_info_s
        globus_ftp_control_auth_info_t"

       Authentication Values. This structure is populated and passed back to the user via the
       globus_ftp_control_auth_callback_t(). It contains the information needed to decide if a
       client may use the server.

   typedef void(* globus_ftp_control_response_callback_t)(void *callback_arg, struct
       globus_ftp_control_handle_s *handle, globus_object_t *error, globus_ftp_control_response_t
       *ftp_response)
       Asynchronous operation completion callback. This callback is called whenever a reply to
       command is received on the FTP control channel. It allows the user to handle the received
       reply or alternatively handle any errors that occurred during the interaction with the FTP
       server. This function will be called multiple times in the case when intermediate
       responses (1yz) are received.

       Parameters:
           callback_arg User supplied argument to the callback function
           handle A pointer to the GSIFTP control handle. Used to identify which control
           connection the operation was applied to.
           error Pointer to a globus error object containing information about any errors that
           occurred processing the operation
           ftp_response Pointer to a response structure containing the FTP response to the
           command.

   typedef void(* globus_ftp_control_callback_t)(void *callback_arg, struct
       globus_ftp_control_handle_s *handle, globus_object_t *error)
       Asynchronous control callback. This callback is used as a generic control operation
       callback.

       Parameters:
           callback_arg User supplied argument to the callback function
           handle A pointer to the GSIFTP control handle. Used to identify which control
           connection the operation was applied to.
           error Pointer to a globus error object containing information about any errors that
           occurred processing the operation

   typedef void(* globus_ftp_control_command_callback_t)(void *callback_arg, struct
       globus_ftp_control_handle_s *handle, globus_object_t *error, union
       globus_ftp_control_command_u *command)
       Server command callback. When a command from a client is received on the control channel a
       user callback with this signature is called.

       Parameters:
           callback_arg The user argument passed to the callback function.
           handle The control handle that the command was issued on.
           error Indicates if a command was successful read or or if a failure occurred. This
           object will be freed once this callback returns. If the user wishes to have a copy of
           the error that persists past the life of this callback, they must make a copy using
           globus_object_copy(), and free it with globus_object_free().
           command The command structure indicates what type of command the client issued. Based
           on the 'type' further information can be extracted. This command structure will be
           freed once this callback returns. If the user wishes to have a copy of the error that
           persists past the life of this callback, they must make a copy using
           globus_ftp_control_command_copy(), and free it with globus_ftp_control_command_free().

   typedef void(* globus_ftp_control_auth_callback_t)(void *callback_arg, struct
       globus_ftp_control_handle_s *handle, globus_object_t *error,
       globus_ftp_control_auth_info_t *auth_result)
       Server authentication complete callback. A function with this signature is registered by
       calling globus_ftp_control_accept(). It is called when the authentication protocal has
       completed. Based on the auth_result, the server implementor should determine authorization
       and then send the appropriate response using globus_ftp_control_send_response(),
       indicating to the client whether authorization was successful or not.

       Parameters:
           handle This structure is populated when the callback is called and represents a
           control connection to the client.
           auth_result A globus_ftp_control_auth_result_t containing the values the client sent
           for gss authentication, user name, password and account. If any of the values were not
           sent by the client they will be NULL. Based on that information the user can decide if
           the client will be authorized for use of the server.
           callback_arg The user argument passed to the callback.

   typedef unsigned long globus_ftp_control_auth_requirements_t
       Authentication requirements. The value of this should be a bitwise or of

       • GLOBUS_FTP_CONTROL_AUTH_NONE

       • GLOBUS_FTP_CONTROL_AUTH_GSSAPI

       • GLOBUS_FTP_CONTROL_AUTH_USER

       • GLOBUS_FTP_CONTROL_AUTH_PASS

       • GLOBUS_FTP_CONTROL_AUTH_ACCT

   typedef void(* globus_ftp_control_data_callback_t)(void *callback_arg,
       globus_ftp_control_handle_t *handle, globus_object_t *error, globus_byte_t *buffer,
       globus_size_t length, globus_off_t offset, globus_bool_t eof)
       Asynchronous data transmission operation callback. This callback is called in functions
       that send or receive data on the data channel(s).

       In the case of a write, this function is invoked when the entire data buffer is sent.
       Depending on the data transfer properties set by the globus_ftp_control_local_*()
       functions, the data may actually be split into multiple buffers and sent to multiple data
       nodes.

       In the case of a read, this function will return a single extent of the data. The order of
       the data returned is not defined in an extended block mode data transfer. It is up to the
       user of the API to re-construct the file order.

       Parameters:
           callback_arg User supplied argument to the callback function
           handle A pointer to the GSIFTP control handle. Used to identify which control
           connection the operation was applied to.
           error Pointer to a globus error object containing information about any errors that
           occurred processing the operation
           buffer The user buffer passed as a parameter to globus_ftp_control_data_read() or
           globus_ftp_control_data_write().
           length The amount of data in the buffer. In the case of an incoming data channel, this
           may be less than the buffer size.
           offset The file offset of the data which is contained in the buffer.
           eof This is set to GLOBUS_TRUE then all of the data associated with the transfer has
           arrived on the data connections associated with this handle. If multiple data
           callbacks are registered with this handle, there is no guaranteed order of the EOF
           callback with respect to other data callbacks. If multiple callbacks are registered
           when EOF is reached on the data connections, at least one callback function will be
           called with eof set to GLOBUS_TRUE.

   typedef void(* globus_ftp_control_server_callback_t)(void *callback_arg, struct
       globus_ftp_control_server_s *server_handle, globus_object_t *error)
       Server callback. A functions with this signature can be used as general callbacks for the
       GSIFTP server API.

       Parameters:
           server_handle The server handle associated with callback.
           result Indicates if the operation completed successfully or if a failure occurred.
           callback_arg The user argument passed to the callback function.

Enumeration Type Documentation

   enum globus_ftp_control_type_e
       control structure types. The enumeration values match the character value of the argument
       to TYPE.

   enum globus_ftp_control_mode_e
       control structure mode

   enum globus_ftp_control_dcau_mode_e
       control dcau types

   enum globus_ftp_control_striping_mode_e
       control striping Types

   enum globus_ftp_control_protection_t
       control protection levels

   enum globus_ftp_control_delay_passive_t
       delayed passive flags

   enum globus_ftp_control_structure_e
       control structure structure

   enum globus_ftp_control_parallelism_mode_e
       control parallelism Types

   enum globus_ftp_control_tcpbuffer_mode_e
       TCP Buffer Setting Modes.

       Enumerator

       GLOBUS_FTP_CONTROL_TCPBUFFER_DEFAULT
              Don't change the TCP buffer/window size from the system default.

       GLOBUS_FTP_CONTROL_TCPBUFFER_FIXED
              Set the TCP buffer/window size to a fixed value.

       GLOBUS_FTP_CONTROL_TCPBUFFER_AUTOMATIC
              Automatically set the TCP buffer/window size.

Function Documentation

   globus_result_t globus_ftp_control_local_layout (globus_ftp_control_handle_t *handle,
       globus_ftp_control_layout_t *layout, globus_size_tdata_size)
       Update the handle with the layout and the size of the data sent over the data channel.
       This function is deprecated. The interface will be the changed to that of
       globus_X_ftp_control_local_layout()

       Parameters:
           handle A pointer to the FTP control handle into which to insert the layout
           information.
           layout A variable containing the layout information
           data_size The size of the data that is going to be sent. This may be needed to
           interpret the layout information.

       References GLOBUS_FTP_CONTROL_MODULE.

   globus_result_t globus_ftp_control_data_set_interface (globus_ftp_control_handle_t *handle,
       const char *interface_addr)
       Create an outgoing FTP data connection. This function sets the interface that will be used
       to send and receive information along the data channel.

       Parameters:
           handle A pointer to a FTP control handle which is configured to create an outgoing
           data connection.
           interface_addr

       References GLOBUS_FTP_CONTROL_MODULE.

   globus_result_t globus_ftp_control_create_data_info (globus_ftp_control_handle_t *handle,
       globus_ftp_control_data_write_info_t *data_info, globus_byte_t *buffer,
       globus_size_tlength, globus_off_toffset, globus_bool_teof,
       globus_ftp_control_data_callback_tcallback, void *callback_arg)
       Create a globus_ftp_control_data_write_info_t structure. This funciton populates a
       globus_ftp_control_data_callback_t structure with valid information. This structure
       provides the user a way to register several data writes with a single callback. This is
       quite useful to the writter of enqueue functions. It allows a single call to
       globus_ftp_control_data_write() to be broken up into many writes, potentially on different
       stripes, and for a single callback to be called when all are finished.

       Parameters:
           handle A pointer to a FTP control handle. The handle contains information about the
           current state of the control and data connections.
           data_info The globus_ftp_control_data_write_info_t structure to be released.
           buffer The pointer to the user buffer that will be passed to the callback argument
           when there are zero references to data_info. This is intended to be the start of all
           the data the user intends to write using globus_ftp_control_data_write_stripe(), but
           it does not have to be.
           length The length of the memory segment pointed to by the argument buffer.
           offset The file offset of the data segment specified.
           eof This should be set to true if the user plans on registering eof on the data_info
           structure.
           callback The user function to be called when all references to data_info are released.
           This occurs after all data registered for write from
           globus_ftp_control_data_write_stripe have occured and the user calls
           globus_ftp_control_release_data_info(). The callback is passed all of the arguments
           passed to this function with the exception of data_info.
           callback_arg User supplied argument to the callback function

       References GLOBUS_FTP_CONTROL_MODULE.

   globus_result_t globus_ftp_control_release_data_info (globus_ftp_control_handle_t *handle,
       globus_ftp_control_data_write_info_t *data_info)
       Release a data_info structure. This function releases all memory and references created
       when a call to globus_ftp_control_create_data_info() was made. For every call to
       globus_ftp_control_create_data_info() a call to this function must be made.

       Parameters:
           handle A pointer to a FTP control handle. The handle contains information about the
           current state of the control and data connections.
           data_info The globus_ftp_control_data_write_info_t structure to be released.

       References GLOBUS_FTP_CONTROL_MODULE.

   globus_result_t globus_ftp_control_data_write_stripe (globus_ftp_control_handle_t *handle,
       globus_byte_t *buffer, globus_size_tlength, globus_off_toffset, globus_bool_teof,
       intstripe_ndx, globus_ftp_control_data_callback_tcallback, void *callback_arg)
       Write FTP data to a particular stripe. This function allows the user to write to a
       specified stripe. The stripe index relates to the order passsed into local_spor(). This
       function differs from globus_ftp_control_data_write() in that no enqueue function is
       needed since the user specifies the stripe on which data is written. In order to use this
       function the user must have a valid pointer to a globus_ftp_control_data_write_info_t
       structure. The data_info structure can be obtained by a call to
       globus_ftp_control_create_data_info(). Many calls to this function can be made, but only a
       single user callback occurs per creation of a globus_ftp_control_data_write_info_t
       structure.

       Parameters:
           handle A pointer to a FTP control handle. The handle contains information about the
           current state of the control and data connections.
           buffer a pointer to the data the user wishes to send along the FTP data channels.
           length the length of the data pointer to by the parameter buffer.
           offset the offset into the file of the data.
           eof A boolean stating that this will be the last chuck of data registered on the given
           stripe. In order to properly send an eof message the user must register an eof on
           every stripe.
           stripe_ndx The index of the stripe on which the data will be sent. The index of each
           stripe is determined by the call to local_spas or local_spor.
           callback The function to be called once the data has been sent
           callback_arg User supplied argument to the callback function

       References GLOBUS_FTP_CONTROL_MODULE.

   globus_result_t globus_X_ftp_control_data_write_stripe (globus_ftp_control_handle_t *handle,
       globus_byte_t *buffer, globus_size_tlength, globus_off_toffset, globus_bool_teof,
       intstripe_ndx, globus_ftp_control_data_write_info_t *data_info)
       Write data on a specific stripe from an enqueue callback function only. This function
       allows the user to register the write of ftp data on a specfic stripe. This function can
       only be called fromed an enqueue function callback. This function should be used only by
       the implementor of an enqueue funciton. It should be viewed as unstable and used used only
       by advanced users. This is the only function in the library that the enqueue function
       implemtor is allowed from the enqueue callback.

       Parameters:
           handle A pointer to a FTP control handle. The handle contains information about the
           current state of the control and data connections.
           buffer a pointer to the data the user wishes to send along the FTP data channels.
           length the length of the data pointer to by the parameter buffer.
           offset the offset into the file of the data.
           eof a boolean stating that this is the last buffer to be registered. When using the X
           version of this function the user does not need to register an eof on each stripe, the
           control library will take care of that internally.
           stripe_ndx The index of the stripe on which the data will be sent. The index of each
           stripe is determined by the call to local_spas or local_spor.
           data_info An opaque structure that is passed into the enqueue function and contains
           reference count and state information. The same data_info pointer that is passed into
           the enqueue function must be used for this parameter.

       References GLOBUS_FTP_CONTROL_MODULE.

Author

       Generated automatically by Doxygen for globus ftp control from the source code.