NAME

       globus_gass_copy - GASS Copy

       Protocol-Independent File Transfer.

   Data Structures
       struct globus_gass_copy_attr_s
           Attributes.
       struct globus_gass_copy_handleattr_s
           Handle Attributes.
       struct globus_gass_copy_glob_stat_t
           Glob expanded entry information.

   Macros
       #define GLOBUS_GASS_COPY_MODULE   (&globus_i_gass_copy_module)
           Module Descriptor.

   Typedefs
       typedef void(* globus_gass_copy_performance_cb_t) (void *user_arg,
           globus_gass_copy_handle_t *handle, globus_off_t total_bytes, float
           instantaneous_throughput, float avg_throughput)
           Performance Callback.
       typedef void(* globus_gass_copy_callback_t) (void *callback_arg, globus_gass_copy_handle_t
           *handle, globus_object_t *error)
           Copy Callback.
       typedef struct globus_gass_copy_attr_s globus_gass_copy_attr_t
           Attributes.
       typedef struct globus_gass_copy_handleattr_s globus_gass_copy_handleattr_t
           Handle Attributes.
       typedef void(* globus_gass_copy_glob_entry_cb_t) (const char *url, const
           globus_gass_copy_glob_stat_t *info_stat, void *user_arg)
           Gass copy glob entry callback.

   Enumerations
   Functions
       globus_result_t globus_gass_copy_handle_init (globus_gass_copy_handle_t *handle,
           globus_gass_copy_handleattr_t *attr)
           Initialize a GASS Copy handle.
       globus_result_t globus_gass_copy_handle_destroy (globus_gass_copy_handle_t *handle)
           Destroy a GASS Copy handle.
       globus_result_t globus_gass_copy_set_buffer_length (globus_gass_copy_handle_t *handle, int
           length)
           Set the size of the buffer to be used for doing transfers.
       globus_result_t globus_gass_copy_get_buffer_length (globus_gass_copy_handle_t *handle, int
           *length)
           Get the size of the transfer buffer.
       globus_result_t globus_gass_copy_set_no_third_party_transfers (globus_gass_copy_handle_t
           *handle, globus_bool_t no_third_party_transfers)
           Enable/Disable third-party transfers.
       globus_result_t globus_gass_copy_get_no_third_party_transfers (globus_gass_copy_handle_t
           *handle, globus_bool_t *no_third_party_transfers)
           Query third-party transfer status.
       globus_result_t globus_gass_copy_set_allocate (globus_gass_copy_handle_t *handle,
           globus_bool_t send_allo)
           Set allo on or off.
       globus_result_t globus_gass_copy_set_stat_on_expand (globus_gass_copy_handle_t *handle,
           globus_bool_t always_stat)
           Make globus_gass_copy_expand_url() always send stat info.
       globus_result_t globus_gass_copy_set_partial_offsets (globus_gass_copy_handle_t *handle,
           globus_off_t offset, globus_off_t end_offset)
           Set partial file offsets.
       globus_result_t globus_gass_copy_get_partial_offsets (globus_gass_copy_handle_t *handle,
           globus_off_t *offset, globus_off_t *end_offset)
           Get partial transfer offsets.
       globus_result_t globus_gass_copy_attr_init (globus_gass_copy_attr_t *attr)
           Initialize an attribute structure.
       globus_result_t globus_gass_copy_attr_set_ftp (globus_gass_copy_attr_t *attr,
           globus_ftp_client_operationattr_t *ftp_attr)
           Set the attributes for ftp/gsiftp transfers.
       globus_result_t globus_gass_copy_attr_set_io (globus_gass_copy_attr_t *attr,
           globus_io_attr_t *io_attr)
           Set file transfers attributes.
       globus_result_t globus_gass_copy_attr_set_gass (globus_gass_copy_attr_t *attr,
           globus_gass_transfer_requestattr_t *gass_attr)
           Set the http/https attributes.
       globus_result_t globus_gass_copy_get_url_mode (char *url, globus_gass_copy_url_mode_t
           *mode)
           Get URL scheme.
       globus_result_t globus_gass_copy_register_performance_cb (globus_gass_copy_handle_t
           *handle, globus_gass_copy_performance_cb_t callback, void *user_arg)
           Register a performance information callback.
       globus_result_t globus_gass_copy_get_status (globus_gass_copy_handle_t *handle,
           globus_gass_copy_status_t *status)
           Get the status code of a transfer.
       const char * globus_gass_copy_get_status_string (globus_gass_copy_handle_t *handle)
           Get the status string of a transfer.
       globus_result_t globus_gass_copy_glob_expand_url (globus_gass_copy_handle_t *handle, const
           char *url, globus_gass_copy_attr_t *attr, globus_gass_copy_glob_entry_cb_t entry_cb,
           void *user_arg)
           Expand globbed url.
       globus_result_t globus_gass_copy_mkdir (globus_gass_copy_handle_t *handle, char *url,
           globus_gass_copy_attr_t *attr)
           Make directory.

Detailed Description

       Protocol-Independent File Transfer.

       The Globus GASS Copy library is motivated by the desire to provide a uniform interface to
       transfer files specified by different protocols.

       The goals in doing this are to:

       • Provide a robust way to describe and apply file transfer properties for a variety of
         protocols. These include the standard HTTP, FTP and GSIFTP options. Some of the new file
         transfer capabilities in GSIFTP are parallel, striping, authentication and TCP buffer
         sizing.

       • Provide a service to support nonblocking file transfer and handle asynchronous file and
         network events.

       • Provide a simple and portable way to implement file transfers.

       Any program that uses Globus GASS Copy functions must include 'globus_gass_copy.h'.

       Globus GASS Copy uses standard Globus module activation and deactivation. Before any
       Globus GASS Copy functions are called, the following function must be called:

       globus_module_activate(GLOBUS_GASS_COPY_MODULE)

       This function returns GLOBUS_SUCCESS if Globus GASS Copy was successfully initialized, and
       you are therefore allowed to subsequently call Globus GASS Copy functions. Otherwise, an
       error code is returned, and Globus GASS Copy functions should not be subsequently called.
       This function may be called multiple times.

       To deactivate Globus GASS Copy, the following function must be called:

       globus_module_deactivate(GLOBUS_GASS_COPY_MODULE)

       This function should be called once for each time Globus GASS Copy was activated.

Typedef Documentation

   typedef struct globus_gass_copy_attr_s  globus_gass_copy_attr_t
       Attributes. Contains any/all attributes that are required to perform the supported
       transfer methods (ftp, gass, io).

   typedef void(* globus_gass_copy_callback_t) (void *callback_arg, globus_gass_copy_handle_t
       *handle, globus_object_t *error)
       Copy Callback. Signature of a callback from globus_gass_copy_register_*() functions.
       (nonblocking transfer functions)

   typedef void(* globus_gass_copy_glob_entry_cb_t) (const char *url, const
       globus_gass_copy_glob_stat_t *info_stat, void *user_arg)
       Gass copy glob entry callback. This callback is passed as a parameter to
       globus_gass_copy_glob_expand_url(). It is called once for each entry that the original
       expands to.

       Parameters:
           url The full url to the expanded entry. A directory entry will end in a forward slash
           '/'.
           stat A pointer to a globus_gass_copy_glob_stat_t containing information about the
           entry.
           user_arg The user_arg passed to globus_gass_copy_glob_expand()

       See also:
           globus_gass_copy_glob_stat_t, globus_gass_copy_glob_expand_url

   typedef struct globus_gass_copy_handleattr_s  globus_gass_copy_handleattr_t
       Handle Attributes. Contains any/all attributes that are required to create lower-level
       handles (ftp, gass, io).

   typedef void(* globus_gass_copy_performance_cb_t) (void *user_arg, globus_gass_copy_handle_t
       *handle, globus_off_t total_bytes, float instantaneous_throughput, float avg_throughput)
       Performance Callback. This callback is registered with
       'globus_gass_copy_register_performance_cb' It will be called during a transfer to supply
       performance information on current transfer. Its frequency will be at most one per second,
       but it is possible to receive no callbacks. This is possible in very short transfers and
       in ftp transfers in which the server does not provide performance information.

       Parameters:
           handle the gass copy handle this transfer is occurring on
           user_arg a user pointer registered with 'globus_gass_copy_register_performance_cb'
           total_bytes the total number of bytes transfer so far
           instantaneous_throughput instantaneous rate of transfer (since last callback or start)
           (bytes / sec)
           avg_throughput the avg thoughput calculated since the start of the transfer (bytes /
           sec)

       Returns:

           • n/a

Enumeration Type Documentation

   enum globus_gass_copy_glob_entry_t
       globbed entry types

Function Documentation

   globus_result_t globus_gass_copy_attr_init (globus_gass_copy_attr_t * attr)
       Initialize an attribute structure. The globus_gass_copy_attr_t can be used to pass the
       globus_gass_copy library information about how a transfer should be performed. It must
       first be initialized by calling this function. Then any or all of the following functions
       may be called to set attributes associated with a particular protocol:
       globus_gass_copy_attr_set_ftp(), globus_gass_copy_attr_set_gass(),
       globus_gass_copy_attr_set_io(). Any function which takes a globus_gass_copy_attr_t as an
       argument will also accept GLOBUS_NULL, in which case the appropriate set of default
       attributes will be used.

       Parameters:
           attr The attribute structure to be initialized

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_attr_set_ftp(), globus_gass_copy_attr_set_gass(),
           globus_gass_copy_attr_set_io(), globus_gass_copy_get_url_mode().

   globus_result_t globus_gass_copy_attr_set_ftp (globus_gass_copy_attr_t * attr,
       globus_ftp_client_operationattr_t * ftp_attr)
       Set the attributes for ftp/gsiftp transfers. In order to specify attributes for ftp/gsiftp
       transfers, a globus_ftp_client_operationattr_t should be initialized and its values set
       using the appropriate globus_ftp_client_operationattr_* functions. The
       globus_ftp_client_operationattr_t * can then be passed to the globus_gass_copy_attr_t via
       this function.

       Parameters:
           attr A globus_gass_copy attribute structure
           ftp_attr The ftp/gsiftp attributes to be used

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_attr_init(), globus_gass_copy_attr_set_gass(),
           globus_gass_copy_attr_set_io(), globus_gass_copy_get_url_mode(),
           globus_ftp_client_operationattr_*

   globus_result_t globus_gass_copy_attr_set_gass (globus_gass_copy_attr_t * attr,
       globus_gass_transfer_requestattr_t * gass_attr)
       Set the http/https attributes. In order to specify attributes for http/https transfers, a
       globus_gass_transfer_requestattr_t should be initialized and its values set using the
       appropriate globus_gass_transfer_requestattr_* functions. The
       globus_gass_transfer_requestattr_t can then be passed to the globus_gass_copy_attr_t via
       this function.

       Parameters:
           attr A globus_gass_copy attribute structure
           gass_attr The http/https attributes to be used

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_attr_init(), globus_gass_copy_attr_set_io(),
           globus_gass_copy_attr_set_ftp(), globus_gass_copy_get_url_mode(),
           globus_gass_transfer_requestattr_*

   globus_result_t globus_gass_copy_attr_set_io (globus_gass_copy_attr_t * attr, globus_io_attr_t
       * io_attr)
       Set file transfers attributes. In order to specify attributes for file transfers, a
       globus_io_attr_t should be initialized and its values set using the appropriate
       globus_io_attr_* functions. The globus_io_attr_t can then be passed to the
       globus_gass_copy_attr_t via this function.

       Parameters:
           attr A globus_gass_copy attribute structure
           io_attr The file attributes to be used

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_attr_init(), globus_gass_copy_attr_set_gass(),
           globus_gass_copy_attr_set_ftp(), globus_gass_copy_get_url_mode(), globus_io_attr_*

   globus_result_t globus_gass_copy_get_buffer_length (globus_gass_copy_handle_t * handle, int *
       length)
       Get the size of the transfer buffer. This function allows the user to get the size of the
       buffer that is being used for doing transfers.

       Parameters:
           handle Get the buffer length for transfers associated with this handle.
           length The length, in bytes, of the buffer.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   globus_result_t globus_gass_copy_get_no_third_party_transfers (globus_gass_copy_handle_t *
       handle, globus_bool_t * no_third_party_transfers)
       Query third-party transfer status. This function allows the user to see if third-party
       transfers are turned on or off for ftp to ftp transfers associated with a particular
       handle. This is often desired if one of the servers involved in the transfer does not
       allow third-party transfers.

       Parameters:
           handle See if third-party transfers are turned on or off for transfers associated with
           this handle. They are on by default.
           no_third_party_transfers GLOBUS_FALSE if third-party transfers should be used.
           GLOBUS_TRUE if third-party transfers should not be used.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   globus_result_t globus_gass_copy_get_partial_offsets (globus_gass_copy_handle_t * handle,
       globus_off_t * offset, globus_off_t * end_offset)
       Get partial transfer offsets. This function allows the user to get the offsets that are
       being used for doing partial transfers. An offset of -1 means partial transfers are
       disabled.

       Parameters:
           handle Get the offsets for partial transfers associated with this handle.
           offset The starting offset for the partial transfer.
           end_offset The ending offset for the partial transfer.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   globus_result_t globus_gass_copy_get_status (globus_gass_copy_handle_t * handle,
       globus_gass_copy_status_t * status)
       Get the status code of a transfer. Get the status of the last transfer to be initiated
       using the given handle. Only one transfer can be active on a handle at a given time,
       therefore new transfers may only be initiated when the current status is one of the
       following: GLOBUS_GASS_COPY_STATUS_NONE, GLOBUS_GASS_COPY_STATUS_DONE_SUCCESS,
       GLOBUS_GASS_COPY_STATUS_DONE_FAILURE, GLOBUS_GASS_COPY_STATUS_DONE_CANCELLED

       Parameters:
           handle A globus_gass_copy_handle
           status Will be one of the following: GLOBUS_GASS_COPY_STATUS_NONE (No transfers have
           been initiated using this handle.) GLOBUS_GASS_COPY_STATUS_PENDING (A transfer is
           currently being set up.) GLOBUS_GASS_COPY_STATUS_TRANSFER_IN_PROGRESS (There is
           currently a transfer in progress.) GLOBUS_GASS_COPY_STATUS_CANCEL (The last transfer
           initiated using this handle has been cancelled by the user before completing, and is
           in the process of being cleaned up.) GLOBUS_GASS_COPY_STATUS_FAILURE (The last
           transfer initiated using this handle failed, and is in the process of being cleaned
           up.) GLOBUS_GASS_COPY_STATUS_DONE_SUCCESS (The last transfer initiated using this
           handle has completed successfully.) GLOBUS_GASS_COPY_STATUS_DONE_FAILURE (The last
           transfer initiated using this handle failed and has finished cleaning up.)
           GLOBUS_GASS_COPY_STATUS_DONE_CANCELLED (The last transfer initiated using this handle
           was cancelled and has finished cleaning up.)

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   const char* globus_gass_copy_get_status_string (globus_gass_copy_handle_t * handle)
       Get the status string of a transfer. Get the status of the last transfer to be initiated
       using the given handle. Only one transfer can be active on a handle at a given time,
       therefore new transfers may only be initiated when the current status is one of the
       following: GLOBUS_GASS_COPY_STATUS_NONE, GLOBUS_GASS_COPY_STATUS_DONE_SUCCESS,
       GLOBUS_GASS_COPY_STATUS_DONE_FAILURE, GLOBUS_GASS_COPY_STATUS_DONE_CANCELLED

       Parameters:
           handle A globus_gass_copy_handle

       Returns:
           Returns a pointer to a character string describing the current status

   globus_result_t globus_gass_copy_get_url_mode (char * url, globus_gass_copy_url_mode_t * mode)
       Get URL scheme. This function enables the user to determine what protocol will be used to
       transfer data to/from a particular url. This information can then be used to specify the
       appropriate attributes when initiating a transfer.

       Parameters:
           url The URL for schema checking
           mode the filled in schema type of the URL param

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_attr_init(), globus_gass_copy_attr_set_io(),
           globus_gass_copy_attr_set_ftp(), globus_gass_copy_set_gass()

   globus_result_t globus_gass_copy_glob_expand_url (globus_gass_copy_handle_t * handle, const
       char * url, globus_gass_copy_attr_t * attr, globus_gass_copy_glob_entry_cb_t entry_cb,
       void * user_arg)
       Expand globbed url. This function expands wildcards in a globbed url, and calls entry_cb()
       on each one.

       Parameters:
           handle A gass copy handle to use for the operation.
           url The URL to expand. The URL may be an ftp, gsiftp or file URL. Wildcard characters
           supported are '?' '*' '[ ]' in the filename portion of the url.
           attr Gass copy attributes for this operation.
           entry_cb Function to call with information about each entry
           user_arg An argument to pass to entry_cb()

       Returns:
           This function returns an error when any of these conditions are true:

           • handle is GLOBUS_NULL

           • url is GLOBUS_NULL

           • url cannot be parsed

           • url is not a ftp, gsiftp or file url

   globus_result_t globus_gass_copy_handle_destroy (globus_gass_copy_handle_t * handle)
       Destroy a GASS Copy handle. Destroy a gass_copy_handle, which was initialized using
       globus_gass_copy_handle_init(), that will no longer be used for doing transfers. Once the
       handle is detroyed, no further transfers should be associated with it.

       Parameters:
           handle The handle to be destroyed

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_handle_init(), globus_ftp_client_handle_destroy()

   globus_result_t globus_gass_copy_handle_init (globus_gass_copy_handle_t * handle,
       globus_gass_copy_handleattr_t * attr)
       Initialize a GASS Copy handle. A globus_gass_copy_handle must be initialized before any
       transfers may be associated with it. This function initializes a globus_gass_copy_handle
       to be used for doing transfers, this includes initializing a globus_ftp_client_handle
       which will be used for doing any ftp/gsiftp transfers. The same handle may be used to
       perform multiple, consecutive transfers. However, there can only be one transfer
       associated with a particular handle at any given time. After all transfers to be
       associated with this handle have completed, the handle should be destroyed by calling
       globus_gass_copy_handle_destroy().

       Parameters:
           handle The handle to be initialized
           attr The handle attributes used to use with this handle

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

       See also:
           globus_gass_copy_handle_destroy() , globus_gass_copy_handleattr_init(),
           globus_ftp_client_hande_init()

   globus_result_t globus_gass_copy_mkdir (globus_gass_copy_handle_t * handle, char * url,
       globus_gass_copy_attr_t * attr)
       Make directory. This function creates a directory given a ftp or file url.

       Parameters:
           handle A gass copy handle to use for the mkdir operation.
           url The URL for the directory to create. The URL may be an ftp, gsiftp or file URL.
           attr Gass copy attributes for this operation.

       Returns:
           This function returns an error when any of these conditions are true:

           • handle is GLOBUS_NULL

           • url is GLOBUS_NULL

           • url cannot be parsed

           • url is not a ftp, gsiftp or file url

           • the directory could not be created

   globus_result_t globus_gass_copy_register_performance_cb (globus_gass_copy_handle_t * handle,
       globus_gass_copy_performance_cb_t callback, void * user_arg)
       Register a performance information callback. Use this to register a performance
       information callback. You change or set to GLOBUS_NULL the callback any time a transfer is
       not occurring.

       Parameters:
           handle an initialized gass copy handle for which you would like to see performance
           info
           callback the performance callback
           user_arg a user pointer that will be passed to all callbacks for a given handle

       Returns:

           • GLOBUS_SUCCESS

           • error on a NULL or busy handle

       See also:
           globus_gass_copy_performance_cb_t

   globus_result_t globus_gass_copy_set_buffer_length (globus_gass_copy_handle_t * handle, int
       length)
       Set the size of the buffer to be used for doing transfers. This function allows the user
       to set the size of the buffer that will be used for doing transfers, if this function is
       not called the buffer size will default to 1M.

       Parameters:
           handle Set the buffer length for transfers associated with this handle.
           length The length, in bytes, to make the buffer.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   globus_result_t globus_gass_copy_set_no_third_party_transfers (globus_gass_copy_handle_t *
       handle, globus_bool_t no_third_party_transfers)
       Enable/Disable third-party transfers. This function allows the user to turn third-party
       transfers on or off for ftp to ftp transfers associated with a particular handle. This is
       often desired if one of the servers involved in the transfer does not allow third-party
       transfers.

       Parameters:
           handle Turn third-party transfers on or off for transfers associated with this handle.
           They are on by default.
           no_third_party_transfers GLOBUS_FALSE if third-party transfers should be used.
           GLOBUS_TRUE if third-party transfers should not be used.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

   globus_result_t globus_gass_copy_set_partial_offsets (globus_gass_copy_handle_t * handle,
       globus_off_t offset, globus_off_t end_offset)
       Set partial file offsets. This function allows the user to set the offsets that will be
       used for doing partial transfers. An offset of -1 will disable partial transfers. An
       end_offset of -1 means EOF.

       Parameters:
           handle Set the offsets for partial transfers associated with this handle.
           offset The starting offset for the partial transfer.
           end_offset The ending offset for the partial transfer.

       Returns:
           This function returns GLOBUS_SUCCESS if successful, or a globus_result_t indicating
           the error that occurred.

Author

       Generated automatically by Doxygen for globus_gass_copy from the source code.