NAME
globus_ftp_control_data.c -
FTP Data Connection Configuration and Management.
SYNOPSIS
Functions
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)
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_data_connect_write
(globus_ftp_control_handle_t *handle,
globus_ftp_control_data_connect_callback_t callback, void
*user_arg)
globus_result_t globus_ftp_control_data_add_channels
(globus_ftp_control_handle_t *handle, unsigned int num_channels,
unsigned int stripe_ndx)
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)
globus_result_t globus_ftp_control_data_remove_channels
(globus_ftp_control_handle_t *handle, unsigned int num_channels,
unsigned int stripe_ndx)
globus_result_t globus_ftp_control_data_query_channels
(globus_ftp_control_handle_t *handle, unsigned int *num_channels,
unsigned int stripe_ndx)
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)
globus_result_t globus_ftp_control_local_send_eof
(globus_ftp_control_handle_t *handle, globus_bool_t send_eof)
globus_result_t globus_ftp_control_local_parallelism
(globus_ftp_control_handle_t *handle,
globus_ftp_control_parallelism_t *parallelism)
globus_result_t globus_ftp_control_local_pasv
(globus_ftp_control_handle_t *handle,
globus_ftp_control_host_port_t *address)
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)
globus_result_t globus_ftp_control_local_port
(globus_ftp_control_handle_t *handle,
globus_ftp_control_host_port_t *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)
globus_result_t globus_ftp_control_local_type
(globus_ftp_control_handle_t *handle, globus_ftp_control_type_t
type, int form_code)
globus_result_t globus_ftp_control_local_mode
(globus_ftp_control_handle_t *handle, globus_ftp_control_mode_t
mode)
globus_result_t globus_ftp_control_local_tcp_buffer
(globus_ftp_control_handle_t *handle,
globus_ftp_control_tcpbuffer_t *tcp_buffer)
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)
globus_result_t globus_ftp_control_local_pbsz
(globus_ftp_control_handle_t *handle, unsigned long bufsize)
globus_result_t globus_ftp_control_get_pbsz
(globus_ftp_control_handle_t *handle, unsigned long *bufsize)
globus_result_t globus_ftp_control_local_stru
(globus_ftp_control_handle_t *handle,
globus_ftp_control_structure_t 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)
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)
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_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)
globus_result_t globus_ftp_control_data_force_close
(globus_ftp_control_handle_t *control_handle,
globus_ftp_control_callback_t close_callback_func, void *close_arg)
Detailed Description
FTP Data Connection Configuration and Management.
Function Documentation
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. This function will register a
globus_io_{accept, connect}. Further accepts/connects are done by
registering a new accept/connect in the current accept/connect
callback. A call to either globus_ftp_control_local_pasv() or
globus_ftp_control_local_port() needs to precede this calling this
function. This function may be followed by a globus_ftp_data_read.
Parameters:
handle A pointer to a FTP control handle which is configured to
create an incoming data connection.
callback This callback is called when the connection occurs. This
parameter may be NULL.
user_arg The user argument passed to the connect callback.
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_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. This function will register a
globus_io_{accept, connect}. Further accepts/connects are done by
registering a new accept/connect in the current accept/connect
callback. A call to either globus_ftp_control_local_pasv() or
globus_ftp_control_local_port() needs to precede this calling this
function. This function may be followed by a globus_ftp_data_write.
Parameters:
handle A pointer to a FTP control handle which is configured to
create an outgoing data connection.
callback This callback is called when the connection occurs. This
parameter may be NULL.
user_arg The user argument passed to the connect callback.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_data_add_channels
(globus_ftp_control_handle_t * handle, unsigned int num_channels,
unsigned int stripe_ndx)
Opens additional data channels (connections) to the host identified by
the stripe parameter. Parameters:
handle A pointer to a FTP control handle. This handle is used to
determine the host corresponding to the stripe number and to store
information about any channels added by this function.
num_channels The number of additional channels to add.
stripe_ndx A integer identifying the stripe to add channels too. In
the case of non-striped transfer this parameter will be ignored.
References GLOBUS_FTP_CONTROL_MODULE.
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)
Sends an eof message to each stripe along an open data connection.
Parameters:
handle A pointer to a FTP control handle. This handle contains the
the state for a conneciton.
count[] This array of integers should contain an integer that will
be added to the current parallel data connection count on each
stripe. The order of the integers corresponds to each stripe in the
same order as what was returned from local_port().
An eof message must be sent to all receiving hosts in a transfer. The
message contains the total number of data connections used by each
stripe. Many stripes may be sending to a single receiver but only one
eof message may be sent. The count parameter allows the user to pass in
the total number of data connections used by all other hosts. The local
values are added to the passed in values and then sent to the receiver.
Parameters:
array_size The number of elements in count[].
eof_message
cb The function to be called when the eof message has been called.
user_arg A user pointer that is threaded through to the user
callback.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_data_remove_channels
(globus_ftp_control_handle_t * handle, unsigned int num_channels,
unsigned int stripe_ndx)
Removes data channels (connections) to the host identified by the
stripe parameter. Parameters:
handle A pointer to a FTP control handle. This handle is used to
determine the host corresponding to the stripe number and to update
information about any channels removed by this function.
num_channels The number of channels to remove.
stripe_ndx A integer identifying the stripe to remove channels
from. In the case of non-striped transfer this parameter will be
ignored.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_data_query_channels
(globus_ftp_control_handle_t * handle, unsigned int * num_channels,
unsigned int stripe_ndx)
Returns the number of currently open channels for the host identified
by the stripe parameter. This number may be less then the level of
parallelism specified in local_parallelism, due to the possibility that
some channels have not yet connected.
Parameters:
handle A pointer to a FTP control handle. This handle is used to
determine the host corresponding to ’stripe’ and number of channels
corresponding to that host.
num_channels
stripe_ndx A integer identifying the stripe for which to return the
number of channels. In the case of non-striped transfer this
parameter should be zero.
References GLOBUS_FTP_CONTROL_MODULE.
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)
Returns the total number of data channels used so far in the current
transfer on the given stripe. Parameters:
handle A pointer to a FTP control handle. This handle is used to
determine the host corresponding to ’stripe’ and number of channels
corresponding to that host.
num_channels
stripe_ndx A integer identifying the stripe for which to return the
number of channels. In the case of non-striped transfer this
parameter should be zero.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_send_eof
(globus_ftp_control_handle_t * handle, globus_bool_t send_eof)
Determines if the library will automatically send an EOF message in
extended block mode, or if the user will have to explicitly do it by
calling globus_ftp_control_data_send_eof(). Parameters:
handle The ftp handle you wish to sent the send_eof attribute on.
send_eof A boolean representing whether or not to automatically
send an EOF message.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_parallelism
(globus_ftp_control_handle_t * handle, globus_ftp_control_parallelism_t
* parallelism)
Set the parallelism information in a FTP control handle. Parameters:
handle A pointer to the FTP control handle for which the
parallelism information is to be updated
parallelism A structure containing parallelism information
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_pasv (globus_ftp_control_handle_t
* handle, globus_ftp_control_host_port_t * address)
Create a local listening socket, bind it and return the address the
socket is listening to. If there is a existing data connection it is
closed.
Parameters:
handle A pointer to a FTP control handle. Information about the
listening socket is stored in the handle.
address The host IP address and port is returned through this
parameter.
References GLOBUS_FTP_CONTROL_MODULE.
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 num_addresses local listening sockets, bind them and return the
addresses the sockets are listening to. If there is a existing data
connection it is closed.
Parameters:
handle A pointer to a FTP control handle. Information about the
listening sockets is stored in the handle.
addresses The host IP addresses and ports are returned through this
parameter.
num_addresses The number of listening sockets to create
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_port (globus_ftp_control_handle_t
* handle, globus_ftp_control_host_port_t * address)
Insert the host/port information returned by a PASV on the remote host
into the local FTP control handle. (close any outstanding data con)
Parameters:
handle A pointer to the FTP control handle into which to insert the
host/port information
address The host IP address and port
References GLOBUS_FTP_CONTROL_MODULE.
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)
Insert the host/port addresses returned by a SPAS on the remote host
into the local FTP control handle. If there are any outstanding data
connections at this point, they are closed.
Parameters:
handle A pointer to the FTP control handle into which to insert the
host/port addresses
addresses The host IP addresses and port numbers
num_addresses The number of addresses
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_type (globus_ftp_control_handle_t
* handle, globus_ftp_control_type_t type, int form_code)
Update the FTP control handle with the given type information.
Parameters:
handle A pointer to the FTP control handle to be updated
type The type of the data connection. Possible values are: ASCII,
EBCDIC, IMAGE and LOCAL. Currently only ASCII and IMAGE types are
supported.
form_code The logical byte size parameter for the LOCAL type.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_mode (globus_ftp_control_handle_t
* handle, globus_ftp_control_mode_t mode)
Update the FTP control handle with the given mode information.
Parameters:
handle A pointer to the FTP control handle to be updated
mode Specifies the mode of the data connection. Possible modes are
STREAM, BLOCK, EXTENDED BLOCK and COMPRESSED. Out of these only
STREAM and EXTENDED BLOCK are supported in this implementation.
Also, EXTENDED BLOCK is only supported in combination with the
IMAGE type.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_tcp_buffer
(globus_ftp_control_handle_t * handle, globus_ftp_control_tcpbuffer_t *
tcp_buffer)
Update the FTP control handle with the given socket buffer information.
Parameters:
handle A pointer to the FTP control handle to be updated
tcp_buffer A pointer to the socket buffer.
References GLOBUS_FTP_CONTROL_MODULE, and
GLOBUS_FTP_CONTROL_TCPBUFFER_FIXED.
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)
Update the FTP control handle with the given data channel
authentication information. If authentication is set to
GLOBUS_FTP_CONTROL_DCAU_NONE, then protection will also be disabled for
this control handle.
Parameters:
handle A pointer to the FTP control handle to be updated
dcau A parameter specifying the data channel authentication mode.
Possible values are No Authentication, Self Authentication and
Subject-name authentication.
delegated_credential_handle
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_pbsz (globus_ftp_control_handle_t
* handle, unsigned long bufsize)
Update the FTP control handle with the given protection buffer size
information. This function sets protection buffer size to be used by
this handle. This value is used to determine how much data will be sent
in each packet during a protected data transfer.
Parameters:
handle A pointer to the FTP control handle to be updated
bufsize A parameter specifying the protection buffer size value.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_get_pbsz (globus_ftp_control_handle_t *
handle, unsigned long * bufsize)
Query the FTP control handle for the protection buffer size
information. This function queries the handle to determine the
protection buffer size which is used by this handle. This value is used
to determine how much data will be sent in each packet during a
protected data transfer.
Parameters:
handle A pointer to the FTP control handle to be updated
bufsize A pointer to a parameter to store the value of the
protection buffer size.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_local_stru (globus_ftp_control_handle_t
* handle, globus_ftp_control_structure_t structure)
Updates the handle with information on the structure of the data being
sent on the data channel. This function updates the handle with the
provided structure information. At this point the only structure type
that is supported is the file type.
Parameters:
handle A pointer to a FTP control handle. The handle contains
information about the current state of the control and data
connections.
structure This parameter is used to pass the structure information.
Possible values are file, record and page. Only the file type is
supported
References GLOBUS_FTP_CONTROL_MODULE.
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)
Writes data from the supplied buffer to data connection(s). This
function writes contained in the buffer to the data channel(s).
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 user supplied buffer from which data will written to the
data connection(s)
length The length of the data contained in the buffer.
offset The offset in the file at which the data in the buffer
starts
eof Indicates that the buffer is that last part of a file. In the
striped case this will cause a EOF block to be send to every data
node involved in the transfer.
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_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)
Reads data from data connection(s) and put them in the supplied buffer.
This function takes the given buffer and will try to read data from the
data connection(s).
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 user supplied buffer into which data from the data
connection(s) will be written
max_length The maximum length of the data that can be written to
the buffer
callback The function to be called once the data has been read
callback_arg User supplied argument to the callback function
References GLOBUS_FTP_CONTROL_MODULE.
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_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.
globus_result_t globus_ftp_control_data_force_close
(globus_ftp_control_handle_t * control_handle,
globus_ftp_control_callback_t close_callback_func, void * close_arg)
Forces an imediate close of all data connections. Parameters:
control_handle The globus_ftp_control_handle that is have its data
connections closed.
close_callback_func A user function that will be called when the
data connections are closed.
close_arg The user argument that will be threaded through to
close_callback_func.
References GLOBUS_FTP_CONTROL_MODULE.
Author
Generated automatically by Doxygen for globus ftp control from the
source code.