globus_gass_transfer_request - Request Handles

       Generated automatically by Doxygen for globus_gass_transfer from the source code.

globus_gass_transfer                               Version 9.4                   globus_gass_transfer_request(3)

       Request Handles.

       Request Handles

       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.

enumglobus_gass_transfer_request_status_t
       Request Status

       EnumeratorGLOBUS_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

   enumglobus_gass_transfer_request_type_t
       Type of operation associated with a request handle.

       EnumeratorGLOBUS_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

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

       Parametersrequest The request to destroy.

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

   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.

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

       Seealsoglobus_gass_transfer_request_get_denial_reason()intglobus_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.

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

       Seealsoglobus_gass_transfer_request_get_denial_message()globus_size_tglobus_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.

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

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

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

       ReturnvaluesGLOBUS_SUCCESS The referral was successfully extracted from the request handle.
           GLOBUS_GASS_TRANSFER_ERROR_NULL_POINTER The referral pointer was GLOBUS_NULL;

   globus_gass_transfer_request_status_tglobus_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 proceed, or whether the file transfer was successfully
       processed.

       Parametersrequest The request handle to query.

       Returns
           A globus_gass_transfer_request_status_t indicating the current status of the request.

   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.

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

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

       Parametersrequest The request to query.

       Returns
           The type of the request.

   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.

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

   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.

       Parametersrequest The request to query.

       Returns
           The user pointer's value.

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

       Parametersrequest A handle to the request to modify.
           length The length of the file request.

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

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

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

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

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

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

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

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

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

       ReturnvaluesGLOBUS_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 - Request Handles

        - Request Handles.

DataStructures
       struct globus_gass_transfer_request_t
           Request handle.

   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 }

   Functionsglobus_gass_transfer_request_type_tglobus_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_tglobus_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)