NAME
Request Handles -
Request handles are used by the GASS Transfer API to associate
operations with a single file transfer request.
Data Structures
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 }
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_t request)
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.
void* globus_gass_transfer_request_get_user_pointer
(globus_gass_transfer_request_t request)
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.
int globus_gass_transfer_request_set_user_pointer
(globus_gass_transfer_request_t request, 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_t
request)
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.
int globus_gass_transfer_request_get_referral
(globus_gass_transfer_request_t request,
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_t
request)
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_t request)
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_t
request, globus_gass_transfer_request_type_t type)
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.
int globus_gass_transfer_request_set_url (globus_gass_transfer_request_t
request, 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_t request, globus_size_t length)
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_t request)
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_t request)
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_t request)
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_t
request)
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.
Author
Generated automatically by Doxygen for globus gass transfer from the
source code.