NAME
globus_ftp_control.h -
GSIFTP Control Connection API (Data structures and types).
SYNOPSIS
Data Structures
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
Dont 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.
Defines
#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).
Define 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_t data_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_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. 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_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 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_t length, globus_off_t offset, globus_bool_t eof, int
stripe_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.