Provided by: libglobus-ftp-control-doc_9.10-3build1_all bug

NAME

       globus_ftp_control_client - GridFTP Control Client

        - Control Client.

SYNOPSIS

   Functions
       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_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_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_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_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_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_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_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.
       globus_result_t globus_ftp_control_ipv6_allow (globus_ftp_control_handle_t *handle,
           globus_bool_t allow)
           Not documented yet.

Detailed Description

       Control Client.

Function Documentation

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

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

   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. 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 GSSAPI subject name

       Returns

           • Error object

           • GLOBUS_SUCCESS

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

           The function globus_ftp_control_authenticate_ex() is identical except that the
           auth_info->req_flags is used. If delegation flags or any flags other than
           GSS_C_MUTUAL_FLAG and GSS_C_CONF_FLAG are desired, they must be set explicitly. It is
           the caller's responsibility to ensure that req_flags only contains valid flags.

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

           The function globus_ftp_control_authenticate_ex() is identical except that the
           auth_info->req_flags is used. If delegation flags or any flags other than
           GSS_C_MUTUAL_FLAG and GSS_C_CONF_FLAG are desired, they must be set explicitly. It is
           the caller's responsibility to ensure that req_flags only contains valid flags.

   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.

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

   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 dynamically 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 destroy.

       Returns

           • success

           • invalid handle

           • handle is still in connected state

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

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

   globus_result_t globus_ftp_control_response_copy (globus_ftp_control_response_t * src,
       globus_ftp_control_response_t * dest)
       Copy a response structure. 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

   globus_result_t globus_ftp_control_response_destroy (globus_ftp_control_response_t * response)
       Free the memory associated with a response. 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_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. 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 GridFTP 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
           ... Parameters which will be substituted into the % escapes in the cmdspec string.

       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.

Author

       Generated automatically by Doxygen for globus_ftp_control from the source code.