NAME

       Request Handles -

   Data Structures
       struct globus_gass_transfer_request_t

   Enumerations
       enum globus_gass_transfer_request_type_t { GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID,
           GLOBUS_GASS_TRANSFER_REQUEST_TYPE_GET, GLOBUS_GASS_TRANSFER_REQUEST_TYPE_PUT,
           GLOBUS_GASS_TRANSFER_REQUEST_TYPE_APPEND }
       enum globus_gass_transfer_request_status_t { GLOBUS_GASS_TRANSFER_REQUEST_INVALID,
           GLOBUS_GASS_TRANSFER_REQUEST_STARTING, GLOBUS_GASS_TRANSFER_REQUEST_PENDING,
           GLOBUS_GASS_TRANSFER_REQUEST_FAILED, GLOBUS_GASS_TRANSFER_REQUEST_REFERRED,
           GLOBUS_GASS_TRANSFER_REQUEST_DENIED, GLOBUS_GASS_TRANSFER_REQUEST_DONE }

   Functions
       globus_gass_transfer_request_type_t globus_gass_transfer_request_get_type
           (globus_gass_transfer_request_t request)
       void * globus_gass_transfer_request_get_user_pointer (globus_gass_transfer_request_t
           request)
       int globus_gass_transfer_request_set_user_pointer (globus_gass_transfer_request_t request,
           void *user_pointer)
       globus_gass_transfer_request_status_t globus_gass_transfer_request_get_status
           (globus_gass_transfer_request_t request)
       int globus_gass_transfer_request_get_referral (globus_gass_transfer_request_t request,
           globus_gass_transfer_referral_t *referral)
       char * globus_gass_transfer_request_get_url (globus_gass_transfer_request_t request)
       globus_size_t globus_gass_transfer_request_get_length (globus_gass_transfer_request_t
           request)
       int globus_gass_transfer_request_set_type (globus_gass_transfer_request_t request,
           globus_gass_transfer_request_type_t type)
       int globus_gass_transfer_request_set_url (globus_gass_transfer_request_t request, char
           *url)
       void globus_gass_transfer_request_set_length (globus_gass_transfer_request_t request,
           globus_size_t length)
       int globus_gass_transfer_request_get_denial_reason (globus_gass_transfer_request_t
           request)
       char * globus_gass_transfer_request_get_denial_message (globus_gass_transfer_request_t
           request)
       char * globus_gass_transfer_request_get_subject (globus_gass_transfer_request_t request)
       int globus_gass_transfer_request_destroy (globus_gass_transfer_request_t request)

Detailed Description

       Request handles are used by the GASS Transfer API to associate operations with a single
       file transfer request.

       Specifically, they are used to register multiple byte range buffers with a file transfer
       request, and to query the state of a transfer in-progress.

       To implement a server, the request handle is populated by the protocol module
       implementation. The server may use the functions in this section to determine information
       about what the client is requesting.

       To implement a client, the request handle should be queried after the blocking call or
       initial callback has been invoked to determine if the request has been authorized or
       referred, and after EOF, to determine whether the request has completed successfully.

       A request handle contains a pointer which may be used by the handler of the request to
       store a pointer to arbitrary application-specific data.

Enumeration Type Documentation

   enum globus_gass_transfer_request_type_t
       Type of operation associated with a request handle.

       Enumerator

       GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID
              Handle no longer valid.

       GLOBUS_GASS_TRANSFER_REQUEST_TYPE_GET
              A get request.

       GLOBUS_GASS_TRANSFER_REQUEST_TYPE_PUT
              A put request.

       GLOBUS_GASS_TRANSFER_REQUEST_TYPE_APPEND
              An append request.

   enum globus_gass_transfer_request_status_t
       Request Status.

       Enumerator

       GLOBUS_GASS_TRANSFER_REQUEST_INVALID
              Handle is no longer valid.

       GLOBUS_GASS_TRANSFER_REQUEST_STARTING
              Initial connection and authorization is not yet completed.

       GLOBUS_GASS_TRANSFER_REQUEST_PENDING
              Request is authorized.

       GLOBUS_GASS_TRANSFER_REQUEST_FAILED
              Request failed due to protocol error or client or server aborting the request.

       GLOBUS_GASS_TRANSFER_REQUEST_REFERRED
              Request can not be processed by this server, referred to another URL or URLs.

       GLOBUS_GASS_TRANSFER_REQUEST_DENIED
              The server denied this request.

       GLOBUS_GASS_TRANSFER_REQUEST_DONE
              All callbacks have completed.

Function Documentation

   globus_gass_transfer_request_type_t globus_gass_transfer_request_get_type
       (globus_gass_transfer_request_trequest)
       Determine the type of a request. This function is used by GASS server implementations to
       discover what type of operation the client is requesting for an URL.

       Parameters:
           request The request to query.

       Returns:
           The type of the request.

       References GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID.

   void* globus_gass_transfer_request_get_user_pointer (globus_gass_transfer_request_trequest)
       Get the user pointer associated with a request

       This function extracts the user pointer from a request handle. The user-pointer may be
       used by the application which is generating or servicing the request to store a pointer to
       any application-specific piece of data.

       Parameters:
           request The request to query.

       Returns:
           The user pointer's value.

       References GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID.

   int globus_gass_transfer_request_set_user_pointer (globus_gass_transfer_request_trequest, void
       *user_pointer)
       Set the user pointer associated with a request handle. This function sets the user pointer
       from a request handle. The user-pointer may be used by the application which is generating
       or servicing the request to store a pointer to any application-specific piece of data.

       Parameters:
           request The request to modify.
           user_pointer The new value of the user pointer for the request.

       Return values:
           GLOBUS_SUCCES The user pointer's value was set.
           GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE An invalid request handle was passed to this
           function

   globus_gass_transfer_request_status_t globus_gass_transfer_request_get_status
       (globus_gass_transfer_request_trequest)
       Check the status of a request. This function queries a request to determine the status of
       the request. This function should be called after EOF has been reached, or after the
       initial get, put, or append has returned or had it's callback function called to determine
       if it is possible to procede, or whether the file transfer was successfully processed.

       Parameters:
           request The request handle to query.

       Returns:
           A globus_gass_transfer_request_status_t indicating the current status of the request.

       References GLOBUS_GASS_TRANSFER_REQUEST_DENIED, GLOBUS_GASS_TRANSFER_REQUEST_DONE,
       GLOBUS_GASS_TRANSFER_REQUEST_FAILED, GLOBUS_GASS_TRANSFER_REQUEST_INVALID,
       GLOBUS_GASS_TRANSFER_REQUEST_PENDING, GLOBUS_GASS_TRANSFER_REQUEST_REFERRED, and
       GLOBUS_GASS_TRANSFER_REQUEST_STARTING.

   int globus_gass_transfer_request_get_referral (globus_gass_transfer_request_trequest,
       globus_gass_transfer_referral_t *referral)
       Extract referral information from a request handle. This function queries the request
       handle to determine any referral information that it contains. This function should only
       be called on request handles in the GLOBUS_GASS_TRANSFER_REQUEST_REFERRED state. If no
       referral information is stored in the request handle, then the referral will be
       initialized to an empty referral. The referral must be destroyed by calling
       globus_gass_transfer_referral_destroy() by the caller.

       Parameters:
           request The request handle to query.
           referral A pointer to an uninitialized referral structure. It will be populated by
           calling this function.

       Return values:
           GLOBUS_SUCCESS The referral was successfully extracted from the request handle.
           GLOBUS_GASS_TRANSFER_ERROR_NULL_POINTER The referral pointer was GLOBUS_NULL;

   char* globus_gass_transfer_request_get_url (globus_gass_transfer_request_trequest)
       Get the URL from a request handle. This function queries the request handle to determine
       the URL associated with the request. This function is intended to be useful to GASS server
       implementors.

       Parameters:
           request The request handle to query.

       Returns:
           A pointer to the URL, or GLOBUS_NULL if the request handle is invalid. The string
           which is returned must not be freed by the caller. It may not be accessed after the
           request has been destroyed.

   globus_size_t globus_gass_transfer_request_get_length (globus_gass_transfer_request_trequest)
       Get the length of a file to be transferred using GASS. This function queries the request
       handle to determine the amount of data that will be transferred to copy the URL. The
       length may be GLOBUS_GASS_TRANSFER_LENGTH_UNKNOWN if the sender can not determine the
       length before making or authorizing the request.

       Parameters:
           request The request to query.

       Returns:
           The length of the file located at the request's URL, or
           GLOBUS_GASS_TRANSFER_LENGTH_UNKNOWN if that cannot be determined.

   int globus_gass_transfer_request_set_type (globus_gass_transfer_request_trequest,
       globus_gass_transfer_request_type_ttype)
       Set the type of a request. This function modifies a request handle by setting the type of
       operation that it is being used for. This function may only be called once per handle, and
       only from a GASS protocol module implementation.

       Parameters:
           request The request handle to modify.
           type The type of operation that this request handle will be used for.

       Return values:
           GLOBUS_SUCCESS The request handle's type has been set.
           GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE The request handle was invalid or it's type was
           already set. The request handle was not modified.

       Note:
           Only GASS Protocol modules may call this function.

       References GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID.

   int globus_gass_transfer_request_set_url (globus_gass_transfer_request_trequest, char *url)
       Set the URL to which a request handle refers. This function modifies the given request
       handle so that it's URL field is set to string pointed to by url.

       No copy is made of the string, so the caller must not free it. It must be allocated by
       calling one of the memory allocators in globus_libc, as it will be freed when the request
       handle is destroyed.

       This function must only be called by protocol modules when constructing a request handle
       when accepting a new request. This function can only be called once per request handle.

       Parameters:
           request A handle to the request to modify.
           url A string containing the URL that this request will be associated with.

       Return values:
           GLOBUS_SUCCESS The URL was set for the request handle.
           GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE The request handle was invalid, or the URL had
           already been set.

   void globus_gass_transfer_request_set_length (globus_gass_transfer_request_trequest,
       globus_size_tlength)
       Set the length of a transfer associated request handle. This function modifies the given
       request handle so that it's length field is set to give length parameter.

       This function must only be called by protocol modules when constructing a request handle
       when receiving the response to a get request. This function can only be called once per
       request handle.

       Parameters:
           request A handle to the request to modify.
           length The length of the file request.

       Return values:
           GLOBUS_SUCCESS The URL was set for the request handle.
           GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE The request handle was invalid, or the URL had
           already been set.

   int globus_gass_transfer_request_get_denial_reason (globus_gass_transfer_request_trequest)
       Get an integer code describing why the request was denied. This function queries a request
       which was denied by a server to determine why it was denied. The denial reason will be
       expressed in a protocol-specific response code. Knowledge of the protocol is needed to
       understand this response.

       Parameters:
           request A handle to the request to query.

       Returns:
           A protocol-specific integer indicating why the request was denied. If the request
           handle is invalid or the request was not denied, then this function returns 0.

       See Also:
           globus_gass_transfer_request_get_denial_message()

   char* globus_gass_transfer_request_get_denial_message (globus_gass_transfer_request_trequest)
       Get an string describing why a request was denied. This function queries a request which
       was denied by a server to determine why it was denied. The denial reason will be expressed
       as a response string. The string must be freed by the caller.

       Parameters:
           request A handle to the request to query.

       Returns:
           A string indicating why the request was denied. If the request handle is invalid or
           the request was not denied, then this function returns GLOBUS_NULL.

       See Also:
           globus_gass_transfer_request_get_denial_reason()

   char* globus_gass_transfer_request_get_subject (globus_gass_transfer_request_trequest)
       Get the subject string associated with a request. This function queries a request handle
       to determine the subject identity of the client who initiated the request. The string must
       not be freed by the caller.

       Parameters:
           request A handle to the request to query.

       Returns:
           A string containing the request initiator's subject identity. If the request handle is
           invalid or a credential was not used to initiate the request, this value will be
           GLOBUS_NULL.

   int globus_gass_transfer_request_destroy (globus_gass_transfer_request_trequest)
       Destroy a request handle. This function destroys the caller's reference to a request
       handle. It must be called for all request handles which are created by calling functions
       in the '@ref globus_gass_transfer_client' or '@ref globus_gass_transfer_server' sections
       of this manual. After calling the function, the caller must not attempt to use the request
       handle for any purpose.

       Parameters:
           request The request to destroy.

       Return values:
           GLOBUS_SUCCESS The request handle reference was successfully destroyed.
           GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE Either an invalid request handle or one which
           is actively being used was passed to this function as the request parameter.

       References GLOBUS_GASS_TRANSFER_REQUEST_DENIED, GLOBUS_GASS_TRANSFER_REQUEST_DONE,
       GLOBUS_GASS_TRANSFER_REQUEST_FAILED, and GLOBUS_GASS_TRANSFER_REQUEST_REFERRED.

Author

       Generated automatically by Doxygen for globus gass transfer from the source code.