globus_ftp_control.h - GridFTP Control Connection API.

Author

       Generated automatically by Doxygen for globus_ftp_control from the source code.

globus_ftp_control                                Version 9.10                           globus_ftp_control.h(3)

Detailed Description

       GridFTP Control Connection API.

Enumeration Type Documentation

enumglobus_ftp_control_delay_passive_t
       delayed passive flags

   enumglobus_ftp_control_parallelism_mode_e
       control parallelism Types

   enumglobus_ftp_control_structure_e
       control structure structure

   enumglobus_ftp_control_tcpbuffer_mode_e
       TCP Buffer Setting Modes

       EnumeratorGLOBUS_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

Name

       globus_ftp_control.h - GridFTP Control Connection API.

Synopsis

       #include 'globus_common.h'
       #include 'globus_error_string.h'
       #include 'globus_io.h'
       #include 'globus_gss_assist.h'
       #include 'globus_handle_table.h'

   DataStructures
       struct globus_ftp_control_dcau_subject_s
           Control DCAU subject authentication type.
       struct globus_ftp_control_round_robin_s
           Control striping round robin attribute structure.
       union globus_ftp_control_dcau_u
           Control DCAU union.
       union globus_ftp_control_layout_u
           Control striping attribute union.
       union globus_ftp_control_parallelism_u
           Control parallelism attribute structure
            "
       struct globus_ftp_control_tcpbuffer_default_t
           Don't change the TCP buffer/window size from the system default.
       struct globus_ftp_control_tcpbuffer_fixed_t
           Set the TCP buffer/window size to a fixed value.
       struct globus_ftp_control_tcpbuffer_automatic_s
           Automatically set the TCP buffer/window size.
       union globus_ftp_control_tcpbuffer_t
           Control tcpbuffer attribute structure.
       struct globus_ftp_control_auth_info_s
           Authentication Values.

   Macros
       #define GLOBUS_FTP_CONTROL_MODULE   (&globus_i_ftp_control_module)
           Module descriptor.

   Typedefs
       typedef enum globus_ftp_control_type_eglobus_ftp_control_type_t
           GridFTP TYPE values.
       typedef enum globus_ftp_control_mode_eglobus_ftp_control_mode_t
           GridFTP MODE values.
       typedef enum globus_ftp_control_dcau_mode_eglobus_ftp_control_dcau_mode_t
           GridFTP DCAU values.
       typedef struct globus_ftp_control_dcau_subject_sglobus_ftp_control_dcau_subject_t
           Control DCAU subject authentication type.
       typedef enum globus_ftp_control_striping_mode_eglobus_ftp_control_striping_mode_t
           GridFTP Striping Types.
       typedef struct globus_ftp_control_round_robin_sglobus_ftp_control_round_robin_t
           Control striping round robin attribute structure.
       typedef union globus_ftp_control_dcau_uglobus_ftp_control_dcau_t
           Control DCAU union.
       typedef union globus_ftp_control_layout_uglobus_ftp_control_layout_t
           Control striping attribute union.
       typedef enum globus_ftp_control_structure_eglobus_ftp_control_structure_t
       typedef enum globus_ftp_control_parallelism_mode_eglobus_ftp_control_parallelism_mode_t
       typedef union globus_ftp_control_parallelism_uglobus_ftp_control_parallelism_t
           Control parallelism attribute structure
            "
       typedef enum globus_ftp_control_tcpbuffer_mode_eglobus_ftp_control_tcpbuffer_mode_t
       typedef struct globus_ftp_control_tcpbuffer_automatic_sglobus_ftp_control_tcpbuffer_automatic_t
           Automatically set the TCP buffer/window size.
       typedef union globus_ftp_control_tcpbuffer_tglobus_ftp_control_tcpbuffer_t
           Control tcpbuffer attribute structure.
       typedef struct globus_ftp_control_auth_info_sglobus_ftp_control_auth_info_t
           Authentication Values.
       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)
           Server callback.

   Enumerations
       enum globus_ftp_control_type_e { GLOBUS_FTP_CONTROL_TYPE_NONE, GLOBUS_FTP_CONTROL_TYPE_ASCII = 'A',
           GLOBUS_FTP_CONTROL_TYPE_EBCDIC = 'E', GLOBUS_FTP_CONTROL_TYPE_IMAGE = 'I',
           GLOBUS_FTP_CONTROL_TYPE_LOCAL = 'L' }
           GridFTP TYPE values.
       enum globus_ftp_control_mode_e { GLOBUS_FTP_CONTROL_MODE_NONE, GLOBUS_FTP_CONTROL_MODE_STREAM = 'S',
           GLOBUS_FTP_CONTROL_MODE_BLOCK = 'B', GLOBUS_FTP_CONTROL_MODE_EXTENDED_BLOCK = 'E',
           GLOBUS_FTP_CONTROL_MODE_COMPRESSED = 'C' }
           GridFTP MODE values.
       enum globus_ftp_control_dcau_mode_e { GLOBUS_FTP_CONTROL_DCAU_NONE = 'N', GLOBUS_FTP_CONTROL_DCAU_SELF =
           'A', GLOBUS_FTP_CONTROL_DCAU_SUBJECT = 'S', GLOBUS_FTP_CONTROL_DCAU_DEFAULT }
           GridFTP DCAU values.
       enum globus_ftp_control_striping_mode_e
           GridFTP Striping Types.
       enum globus_ftp_control_protection_t { GLOBUS_FTP_CONTROL_PROTECTION_CLEAR = 'C',
           GLOBUS_FTP_CONTROL_PROTECTION_SAFE = 'S', GLOBUS_FTP_CONTROL_PROTECTION_CONFIDENTIAL = 'E',
           GLOBUS_FTP_CONTROL_PROTECTION_PRIVATE = 'P' }
           GridFTP Protection Types.
       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)
           Set data layout.
       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.
       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)
           Create a globus_ftp_control_data_write_info_t structure.
       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.
       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)
           Write FTP data to a stripe.
       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)
           Write data to a stripe from an enqueue callback.
       globus_result_t globus_ftp_control_auth_info_init (globus_ftp_control_auth_info_t *auth_info,
           gss_cred_id_t credential_handle, globus_bool_t encrypt, char *user, char *password, char *account,
           char *subject)
           Initialize authentication information.
       int globus_ftp_control_auth_info_compare (globus_ftp_control_auth_info_t *auth_info_1,
           globus_ftp_control_auth_info_t *auth_info_2)
           Compare authentication information.
       globus_result_t globus_ftp_control_handle_init (globus_ftp_control_handle_t *handle)
           Initialize a globus ftp handle.
       globus_result_t globus_ftp_control_handle_destroy (globus_ftp_control_handle_t *handle)
           Destroy a globus ftp handle.
       globus_result_t globus_ftp_control_server_handle_init (globus_ftp_control_server_t *handle)
           Initialize a GridFTP server handle.
       globus_result_t globus_ftp_control_server_handle_destroy (globus_ftp_control_server_t *handle)
           Destroy a GridFTP server handle.
       globus_result_t globus_ftp_control_response_destroy (globus_ftp_control_response_t *response)
           Free the memory associated with a response.
       globus_result_t globus_ftp_control_response_copy (globus_ftp_control_response_t *src,
           globus_ftp_control_response_t *dest)
           Copy a response structure.
       globus_result_t globus_ftp_control_connect (globus_ftp_control_handle_t *handle, char *host, unsigned
           short port, globus_ftp_control_response_callback_t callback, void *callback_arg)
           Create a new control connection to an FTP server.
       globus_result_t globus_ftp_control_authenticate (globus_ftp_control_handle_t *handle,
           globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth,
           globus_ftp_control_response_callback_t callback, void *callback_arg)
           Authenticate the user to the FTP server.
       globus_result_t globus_ftp_control_authenticate_ex (globus_ftp_control_handle_t *handle,
           globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth,
           globus_ftp_control_response_callback_t callback, void *callback_arg)
           Authenticate the user to the FTP server.
       globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t *handle,
           globus_ftp_control_response_callback_t callback, void *callback_arg)
           Send a GridFTP ABORT.
       globus_result_t globus_ftp_control_quit (globus_ftp_control_handle_t *handle,
           globus_ftp_control_response_callback_t callback, void *callback_arg)
           Send a GridFTP QUIT.
       globus_result_t globus_ftp_control_force_close (globus_ftp_control_handle_t *handle,
           globus_ftp_control_response_callback_t callback, void *callback_arg)
           Force a control connection to close.
       globus_result_t globus_ftp_control_send_command (globus_ftp_control_handle_t *handle, const char
           *cmdspec, globus_ftp_control_response_callback_t callback, void *callback_arg,...)
           Send an FTP protocol command.
       globus_result_t globus_ftp_control_local_pbsz (globus_ftp_control_handle_t *handle, unsigned long
           bufsize)
           Set data channel protection buffer size.
       globus_result_t globus_ftp_control_get_pbsz (globus_ftp_control_handle_t *handle, unsigned long *bufsize)
           Get data channel protection buffer size.
       globus_result_t globus_ftp_control_server_listen (globus_ftp_control_server_t *handle, unsigned short
           *port, globus_ftp_control_server_callback_t callback, void *callback_arg)
           Listen on for FTP Client Connections.
       globus_result_t globus_ftp_control_server_listen_ex (globus_ftp_control_server_t *handle,
           globus_io_attr_t *attr, unsigned short *port, globus_ftp_control_server_callback_t callback, void
           *callback_arg)
           Listen on for FTP Client Connections.
       globus_result_t globus_ftp_control_server_stop (globus_ftp_control_server_t *listener,
           globus_ftp_control_server_callback_t callback, void *callback_arg)
           Stop listening for GridFTP client connections.
       globus_result_t globus_ftp_control_server_accept (globus_ftp_control_server_t *listener,
           globus_ftp_control_handle_t *handle, globus_ftp_control_callback_t callback, void *callback_arg)
           Accept a Client Connection.
       globus_result_t globus_ftp_control_server_authenticate (globus_ftp_control_handle_t *handle,
           globus_ftp_control_auth_requirements_t auth_requirements, globus_ftp_control_auth_callback_t
           callback, void *callback_arg)
           Authenticate a GridFTP Client Connection.
       globus_result_t globus_ftp_control_read_commands (globus_ftp_control_handle_t *handle,
           globus_ftp_control_command_callback_t callback, void *callback_arg)
           Read GridFTP commands.
       globus_result_t globus_ftp_control_send_response (globus_ftp_control_handle_t *handle, const char
           *respspec, globus_ftp_control_callback_t callback, void *callback_arg,...)
           Send a GridFTP response.
       globus_result_t globus_ftp_control_command_copy (globus_ftp_control_command_t *dest,
           globus_ftp_control_command_t *src)
           Copy of GridFTP command.
       globus_result_t globus_ftp_control_command_init (globus_ftp_control_command_t *command, char
           *raw_command, globus_ftp_control_auth_info_t *auth_info)
           Initialize a GridFTP command.
       globus_result_t globus_ftp_control_command_destroy (globus_ftp_control_command_t *command)
           Destroy a GridFTP command.
       globus_result_t globus_ftp_control_data_force_close (globus_ftp_control_handle_t *control_handle,
           globus_ftp_control_callback_t destroy_callback, void *destroy_callback_arg)
           Close data connections.
       globus_result_t globus_ftp_control_local_send_eof (globus_ftp_control_handle_t *handle, globus_bool_t
           send_eof)
           Enable or disable automatic EOF handling.
       globus_result_t globus_ftp_control_data_send_eof (globus_ftp_control_handle_t *handle, int count[], int
           array_size, globus_bool_t eof_message, globus_ftp_control_callback_t cb, void *user_arg)
           Send EOF.
       globus_result_t globus_ftp_control_data_connect_read (globus_ftp_control_handle_t *handle,
           globus_ftp_control_data_connect_callback_t callback, void *user_arg)
           Create an incoming FTP data connection.
       globus_result_t globus_ftp_control_data_connect_write (globus_ftp_control_handle_t *handle,
           globus_ftp_control_data_connect_callback_t callback, void *user_arg)
           Create an outgoing FTP data connection.
       globus_result_t globus_ftp_control_data_add_channels (globus_ftp_control_handle_t *handle, unsigned int
           num_channels, unsigned int stripe)
           Add data channels.
       globus_result_t globus_ftp_control_data_remove_channels (globus_ftp_control_handle_t *handle, unsigned
           int num_channels, unsigned int stripe)
           Remove Data Channels.
       globus_result_t globus_ftp_control_data_query_channels (globus_ftp_control_handle_t *handle, unsigned int
           *num_channels, unsigned int stripe)
           Number of data channels.
       globus_result_t globus_ftp_control_data_get_total_data_channels (globus_ftp_control_handle_t *handle,
           unsigned int *num_channels, unsigned int stripe_ndx)
           Get Total Data Channels For a Stripe.
       globus_result_t globus_ftp_control_local_parallelism (globus_ftp_control_handle_t *handle,
           globus_ftp_control_parallelism_t *parallelism)
           Set control handle parallelism.
       globus_result_t globus_ftp_control_local_pasv (globus_ftp_control_handle_t *handle,
           globus_ftp_control_host_port_t *address)
           Create a passive socket.
       globus_result_t globus_ftp_control_local_spas (globus_ftp_control_handle_t *handle,
           globus_ftp_control_host_port_t addresses[], unsigned int num_addresses)
           Create multiple passive sockets.
       globus_result_t globus_ftp_control_local_port (globus_ftp_control_handle_t *handle,
           globus_ftp_control_host_port_t *address)
           Set remote data address.
       globus_result_t globus_ftp_control_local_spor (globus_ftp_control_handle_t *handle,
           globus_ftp_control_host_port_t addresses[], unsigned int num_addresses)
           Set remote data addresses.
       globus_result_t globus_ftp_control_local_type (globus_ftp_control_handle_t *handle,
           globus_ftp_control_type_t type, int form_code)
           Set control handle TYPE value.
       globus_result_t globus_ftp_control_local_tcp_buffer (globus_ftp_control_handle_t *handle,
           globus_ftp_control_tcpbuffer_t *tcp_buffer)
           Set data handle TCP buffer size.
       globus_result_t globus_ftp_control_local_mode (globus_ftp_control_handle_t *handle,
           globus_ftp_control_mode_t mode)
           Set data handle mode.
       globus_result_t globus_ftp_control_local_dcau (globus_ftp_control_handle_t *handle, const
           globus_ftp_control_dcau_t *dcau, gss_cred_id_t delegated_credential_handle)
           Set data channel DCAU.
       globus_result_t globus_ftp_control_local_stru (globus_ftp_control_handle_t *handle,
           globus_ftp_control_structure_t structure)
           Set data channel structure.
       globus_result_t globus_ftp_control_data_write (globus_ftp_control_handle_t *handle, 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)
           Write data to data connections.
       globus_result_t globus_ftp_control_data_read (globus_ftp_control_handle_t *handle, globus_byte_t *buffer,
           globus_size_t max_length, globus_ftp_control_data_callback_t callback, void *callback_arg)
           Read data from data connections.
       globus_result_t globus_ftp_control_set_force_order (globus_ftp_control_handle_t *handle, globus_bool_t
           order_data, globus_off_t starting_offset)
           Set data handle to return read mode E data in order.
       globus_result_t globus_ftp_control_ipv6_allow (globus_ftp_control_handle_t *handle, globus_bool_t allow)
           Not documented yet.
       globus_result_t globus_ftp_control_client_get_connection_info_ex (globus_ftp_control_handle_t *handle,
           globus_ftp_control_host_port_t *local_info, globus_ftp_control_host_port_t *remote_info)
           Not documented yet.

Typedef Documentation

typedefvoid(*globus_ftp_control_auth_callback_t)(void*callback_arg,structglobus_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 protocol 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.

Parametershandle This structure is populated when the callback is called and represents a control connection to
the client.
error Indicates if a command was successfully 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().
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.

typedefstructglobus_ftp_control_auth_info_sglobus_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.

typedefunsignedlongglobus_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

typedefvoid(*globus_ftp_control_callback_t)(void*callback_arg,structglobus_ftp_control_handle_s*handle,globus_object_t*error)
Asynchronous control callback.

This callback is used as a generic control operation callback.

typedefvoid(*globus_ftp_control_command_callback_t)(void*callback_arg,structglobus_ftp_control_handle_s*handle,globus_object_t*error,unionglobus_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.

Parameterscallback_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 successfully 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().

typedefvoid(*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_tlength,globus_off_toffset,globus_bool_teof)
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, unless the ordered_data flag is set. It
is up to the user of the API to re-construct the file order.

Parameterscallback_arg User supplied argument to the callback function
handle A pointer to the GridFTP 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.

typedefenumglobus_ftp_control_parallelism_mode_eglobus_ftp_control_parallelism_mode_t
control parallelism Types

typedefvoid(*globus_ftp_control_response_callback_t)(void*callback_arg,structglobus_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.

typedefenumglobus_ftp_control_structure_eglobus_ftp_control_structure_t
control structure structure

typedefenumglobus_ftp_control_tcpbuffer_mode_eglobus_ftp_control_tcpbuffer_mode_t
TCP Buffer Setting Modes