NAME
globus_ftp_control_client.c -
Client-side FTP Control API.
SYNOPSIS
Functions
globus_result_t globus_ftp_control_handle_init
(globus_ftp_control_handle_t *handle)
globus_result_t globus_ftp_control_handle_destroy
(globus_ftp_control_handle_t *handle)
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)
globus_result_t globus_ftp_control_response_destroy
(globus_ftp_control_response_t *response)
globus_result_t globus_ftp_control_response_copy
(globus_ftp_control_response_t *src, globus_ftp_control_response_t
*dest)
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)
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,...)
globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t
*handle, globus_ftp_control_response_callback_t callback, void
*callback_arg)
globus_result_t globus_ftp_control_quit (globus_ftp_control_handle_t
*handle, globus_ftp_control_response_callback_t callback, void
*callback_arg)
globus_result_t globus_ftp_control_force_close
(globus_ftp_control_handle_t *handle,
globus_ftp_control_response_callback_t callback, void
*callback_arg)
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)
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)
Detailed Description
Client-side FTP Control API.
Function Documentation
globus_result_t globus_ftp_control_handle_init (globus_ftp_control_handle_t
* handle)
Initialize a globus ftp handle. This function will set up (i.e.
intialize all mutexes and variables) a globus ftp handle. It will also
enter the handle in a list used by the module activation/deactivation
functions.
Parameters:
handle The handle to initialize.
Returns:
· GLOBUS_SUCCESS
· error object
References globus_ftp_control_auth_info_init(), and
GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_handle_destroy
(globus_ftp_control_handle_t * handle)
Destroy a globus ftp handle. This function will free up all dynamicly
allocated memory associated with a given globus ftp handle. It will
also remove the handle from a list used by the module
activation/deactivation functions. This function should only be called
after a call to either globus_ftp_control_force_close or
globus_ftp_control_quit.
Parameters:
handle The handle to destory.
Returns:
· success
· invalid handle
· handle is still in connected state
References GLOBUS_FTP_CONTROL_MODULE, and
globus_ftp_control_response_destroy().
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. This function is used
to initiate an FTP control connection. It creates the socket to the FTP
server. When the connection is made to the server, and the server’s
identification string is received, the callback function will be
invoked.
Parameters:
handle A pointer to a initialized FTP control handle. This handle
will be used for all subsequent FTP control operations.
host The hostname of the FTP server.
port The TCP port number of the FTP server.
callback A function to be called once the connection to the server
is established, and a response has been read.
callback_arg Parameter to the callback function.
Returns:
· success
· Null handle
· Null host
· Illegal port number
· Null callback
· Cannot resolve hostname
· Cannot create socket
Callback errors:
· success
· connection refused
· protocol error
· eof
Expected callback response values:
· 120 Service ready in nnn minutes.
· 220 Service ready for new user.
· 421 Service not available, closing control connection.
· 500 Syntax error, command unrecognized.
Note:
The server may send other responses.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_response_destroy
(globus_ftp_control_response_t * response)
Helper function which frees the memory associated with a response
structure. This is a helper function which frees the memory associated
with a response structure.
Parameters:
response This parameter indicates the response structure to destroy
Returns:
· Error object
· GLOBUS_SUCCESS
globus_result_t globus_ftp_control_response_copy
(globus_ftp_control_response_t * src, globus_ftp_control_response_t *
dest)
Helper function which copies one response structure to another. This is
a helper function which copies one response structure to another.
Parameters:
src This parameter indicates the response structure to copy
dest This parameter specifies the target response structure
Returns:
· Error object
· GLOBUS_SUCCESS
References GLOBUS_FTP_CONTROL_MODULE.
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. This will perform the
authentication handshake with the FTP server. depending on which
parameters are non-NULL, the authentication may involve GSSAPI
credentials, a username, a password, and an account name.
Note:
Do we want to add attribute arguments for:
· specifying type of delegation
· gsswrap control messages for integrity or confidentiality
Parameters:
handle A pointer to a unauthenticated GSIFTP control handle. In the
case of GSS authentication the GSS security context is stored in
this structure.
auth_info This structure is used to pass the following information:
· user The user’s name for login purposes. If this string is
’anonymous’, ’ftp’, GLOBUS_NULL or ’:globus-mapping:’ then the
password argument is optional. If this string is GLOBUS_NULL or
’:globus-mapping:’ and gss_auth is true then the users login is
looked by the FTP server host.
· password The password for the above user argument. If the user
argument is ’anonymous’ or ’ftp’ or if gss_auth is true this
string may be GLOBUS_NULL.
· account This parameter is optional. If not used it should be set
to GLOBUS_NULL. It might be needed by firewalls.
· auth_gssapi_subject The GSSAPI subject name of the server you are
connecting to. If this is GLOBUS_NULL, and the gss_auth parameter
is set to GLOBUS_TRUE, then the name will default to the host
name.
use_auth If set to GLOBUS_TRUE the above argument indicates that
GSS authentication should be used, otherwise cleartext
user/password authentication is used.
callback The function to be called once the authentication process
is complete or when an error occurs.
callback_arg User supplied argument to the callback function
Returns:
· success
· Null handle
· Invalid handle
· Handle already authenticated
Callback errors:
· success
· authentication failed
· protocol error
· eof
Expected callback response values:
· 230 User logged in, proceed.
· 232 User logged in, authorized by security data exchange.
· 234 Security data exchange complete.
· 331 User name okay, need password.
· 332 Need account for login.
· 336 Username okay, need password. Challenge is ’....’
· 431 Need some unavailable resource to process security.
· 500 Syntax error, command unrecognized.
· 530 Not logged in.
Note:
The server may send other responses.
References GLOBUS_FTP_CONTROL_MODULE, and
globus_ftp_control_send_command().
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 to the FTP server and register a response
handler. This function is used to send an FTP command, and register a
handler to receive the FTP reply (or replies, if an intermediate one is
sent). When the control channel is gss authenticated, the message and
the reply will be automatically gss wrapped/unwrapped.
Parameters:
handle A pointer to a GSIFTP control handle. The command described
by the cmdspec is issued to the server over the control channel
associated with this handle.
cmdspec A printf-style format string containing the text of the
command to send to the server. The optional parameters to the
format string are passed after the callback_arg in the function
invocation.
callback The function to be called once the authentication process
is complete or when an error occurs.
callback_arg User supplied argument to the callback function
Returns:
· Success
· Null handle
· Command already in progress
Callback errors:
· success
· protocol error
· eof
Expected callback response values:
Any defined in RFC 959, 2228, 2389, draft-ietf-ftpext-mlst-10, or
the protocol extensions document.
References GLOBUS_FTP_CONTROL_MODULE.
globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t *
handle, globus_ftp_control_response_callback_t callback, void *
callback_arg)
Send an ABORT to the FTP server and register a response handler. This
function is used to send the ABORT message to the FTP server. The ABORT
message is sent out-of-band, and terminates any current data transfer
in progress.
As a result of the ABORT, the data channels used by this control
channel will be closed. The data command callback will be issued with
either a completion reply, or a transfer aborted reply. The ABORT
callback will also be invoked, with the server’s response to the abort
command.
Any attempts to register buffers for read or write after an ABORT has
been sent will fail with a ’no transfer in progress’ error.
Parameters:
handle A pointer to a GSIFTP control handle. The ABORT command is
issued to the server over the control channel associated with this
handle.
callback The function to be called once the authentication process
is complete or when an error occurs.
callback_arg User supplied argument to the callback function
Returns:
· Success
· Null handle
· No transfer in progress
Callback errors:
· success
· protocol error
· eof
Expected callback response values:
· 226 Abort successful.
· 500 Syntax error, command unrecognized.
Note:
The server may send other responses.
References GLOBUS_FTP_CONTROL_MODULE.
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 QUIT message to the FTP server and register a response handler.
This function is used to close the control channel to the FTP server.
There should be no transfer commands in progress when this is called.
Once the final response callback passed to this function is invoked,
the control handle can no longer be used for any gsiftp control
operations.
Note:
Need to further define behavior for when a QUIT happens during a
transfer or command is in progress.
Since this function waits until all other callbacks are completed
before calling it’s own callback it may not be called in a blocking
fashion from another callback.
Parameters:
handle A pointer to a GSIFTP control handle. The quit message is
issued to the server over the control channel associated with this
handle.
callback The function to be called once the authentication process
is complete or when an error occurs.
callback_arg User supplied argument to the callback function
Returns:
· Success
· Null handle
· Command in progress
Callback errors:
· success
· protocol error
· eof
Expected callback response values:
· 221 Service closing control connection.
· 500 Syntax error, command unrecognized.
Note:
The server may send other responses.
References GLOBUS_FTP_CONTROL_MODULE, and
globus_ftp_control_send_command().
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 close of the control connection without waiting for outstanding
commands to complete and without sending QUIT. This function is used to
close the control channel to the FTP server. Once the final response
callback passed to this function is invoked, the control handle can no
longer be used for any gsiftp control operations.
Note:
Since this function waits until all other callbacks are completed
before calling it’s own callback it may not be called in a blocking
fashion from another callback.
Parameters:
handle A pointer to a GSIFTP control handle. The quit message is
issued to the server over the control channel associated with this
handle.
callback The function to be called once the authentication process
is complete or when an error occurs.
callback_arg User supplied argument to the callback function
Returns:
· Success
· Null handle
Callback errors:
· success
· failure
Expected callback response values:
· GLOBUS_NULL
References globus_ftp_control_data_force_close(), and
GLOBUS_FTP_CONTROL_MODULE.
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)
Helper function which initializes a authentication information
structure. This is helper function initializes a authentication
information structure with the values contained in the second to fifth
arguments, which may be GLOBUS_NULL. No memory is allocated in this
function.
Parameters:
auth_info The authentication structure to initialize.
credential_handle The credential to use for authentication. This
may be GSS_C_NO_CREDENTIAL to use the user’s default credential.
encrypt Boolean whether or not to encrypt the control channel for
this handle.
user The user name
password The password for the user name
account The account for the user name/password
subject The gss api subject name
Returns:
· Error object
· GLOBUS_SUCCESS
References GLOBUS_FTP_CONTROL_MODULE.
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)
Helper function which compares two authentication information
structures. This is helper function compares two authentication
information structures and return zero if the two structures are deemed
equal and a non-zero value otherwise.
Parameters:
auth_info_1 The first authentication structure
auth_info_2 The second authentication structure
Returns:
· 0 if the structures are equal
· !0 if the structures differ or an error occured
Author
Generated automatically by Doxygen for globus ftp control from the
source code.