GASS: Client Function Reference

Overview
GASS Client Activation and Deactivation
Functions

GASS Client Overview

The GASS client API is used to make get and put requests to ftp and x-gass servers. (http support will be added in a subsequent release.) Each of these operations can be performed to/from memory, to/from a file descriptor, or a combination of both.

In addition, a put operation can be performed to an x-gass server over a socket. This allows a file descriptor to be returned to a user which will automatically forward data to an x-gass server. This is used to implement GLOBUS_GASS_open(O_APPEND), to provide remote logging support to applications.

Note: All timestamps are as seconds since the epoch. (01 Jan 1970, 00:00 GMT)

GASS Client Activation and Deactivation

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

globus_module_activate(GLOBUS_GASS_CLIENT_MODULE);

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

To deactivate GASS client, the following function must be called:

globus_module_deactivate(GLOBUS_GASS_CLIENT_MODULE);

This function should be called once for each time the GASS client was activated.

GASS Client Functions

int
globus_gass_client_get_request(
char *url,
char *proxy_url,
globus_gass_client_get_request_t **request,
int *failure_code)

Initiate a data transfer from the remote file specified by the url. The **request argument is initialized for this request, and should be passed to one or more subsequent globus_gass_client_get_request_*() calls to retrieve the data, and to globus_gass_client_get_request_done() to cleanup after the request.

The url can be one of the following types: ftp, x-gass.

If proxy_url!=GLOBUS_GASS_NULL, then connect to the host and port specified in proxy_url. Otherwise, use the host and port from url.

This functions returns one of:

GLOBUS_GASS_REQUEST_PENDING
The request was successfully started. *request is initialized for this request. It should use globus_gass_client_get_request_fd() and/or globus_gass_client_get_request_memory() to receive the requested data, and globus_gass_client_get_request_done() must be called to cleanup the request.

GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died). *failure_code contains the reason for the failure.

GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure call by the GASS server. *failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client. *failure_code contains the reason for the failure, as supplied by the GASS client.

If this function returns GLOBUS_GASS_REQUEST_PENDING, the following fields can be accessed directly from the request structure until globus_gass_client_get_request_done() is called with the structure:

request->status (int)

GLOBUS_GASS_REQUEST_PENDING
The request is still in progress.

GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died).
The failure_code contains the reason for the failure.

GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure call by the GASS server. The failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client. The failure_code contains the reason for the failure, as supplied by the GASS client.

GLOBUS_GASS_REQUEST_DONE
The request has completed successfully.

request->failure_code (int)
Set to a failure code when request->status is

GLOBUS_GASS_REQUEST_*_FAILURE.

request->timestamp (unsigned long)

Timestamp of the file pointed to by the URL,or GLOBUS_GASS_TIMESTAMP_UNKNOWN if unknown.

request->total_length (unsigned long)

Total length of the requested data, or GLOBUS_GASS_LENGTH_UNKNOWN if unknown.

request->outstanding (int)

The number of globus_gass_client_get_request_fd() and
globus_gass_client_get_request_memory() calls that are currently
outstanding for this request.

request->subject (char *)

The subject (i.e. globus user name) of the server to which this request was made. It is NULL if the subject is not known.

request->user_pointer (void *)

A pointer that can be used by the user for any purpose.

int
globus_gass_client_get_request_fd(
    globus_gass_client_get_request_t *request,
    int fd,
    unsigned long block_size,
    unsigned long max_length,
    globus_gass_client_get_request_fd_done_t callback)

Receive data for the get request and write it to the file descriptor fd. If block_size!=0, then this specifies a preferred block size that GASS should use when writing to the file descriptor. If max_length==GLOBUS_GASS_LENGTH_UNKNOWN, then receive the remainder of the request's data. Otherwise, receive max_length bytes, unless fewer bytes remain in the request.

For a single request, calls to globus_gass_client_get_request_fd() and globus_gass_client_get_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_client_get_request(). If the return value is GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_client_get_request_fd_done_t)(
globus_gass_client_get_request_t *request,
int fd,
unsigned long receive_length)

This function is called as a result of completion of a globus_gass_client_get_request_fd() request.

receive_length is actual length of the portion of data received for this globus_gass_client_get_request_fd() call.

The request->status field is set to the current status of the request, as described in globus_gass_client_get_request(). A value of GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_client_get_request_fd() and/or globus_gass_client_get_request_memory() should be made to receive the remainder of the request's data.

Notes:

receive_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_client_get_request_fd() is outstanding after the request completes or fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_client_get_request_memory(
    globus_gass_client_get_request_t *request,
    globus_gass_byte_t *buffer,
    unsigned long buffer_length,
    unsigned long wait_length,
    globus_gass_client_get_request_memory_done_t callback)

Receive data for the get request and save it into the memory buffer.

If buffer==NULL, then GASS will allocate a memory buffer with a maximum size of buffer_length, and a minimum size of wait_length. If buffer_length==GLOBUS_GASS_LENGTH_UNKNOWN, then gass will choose a buffer length of at least wait_length bytes. Buffers that are allocated by gass must be explicitly freed by calling globus_gass_client_get_request_memory_free().

If buffer!=NULL, then buffer_length is the maximum number of bytes that can be read into the buffer.

At least wait_length bytes will then be received into this buffer, unless fewer bytes remain in the request.

For a single request, calls to globus_gass_client_get_request_fd() and globus_gass_client_get_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_client_get_request(). If the return value is GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_client_get_request_memory_done_t)(
globus_gass_client_get_request_t *request,
globus_byte_t *buffer,
unsigned long buffer_length,
unsigned long receive_length)

This function is called as a result of completion of a globus_gass_client_get_request_memory() request.

receive_length is actual length of the portion of data received for this globus_gass_client_get_request_memory() call.

The request->status field is set to the current status of the request, as described in globus_gass_client_get_request(). A value of GLOBUS_GASS_REQUEST_PENDING, implies that subsequent calls to globus_gass_client_get_request_fd() and/or globus_gass_client_get_request_memory() should be made to receive the remainder of the request's data.

Notes:

receive_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_client_get_request_memory() is outstanding after the request completes or fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_client_get_request_memory_free(
globus_gass_client_get_request_t *request,
globus_byte_t *buffer)

Free a memory buffer that was allocated automatically by gass as a result of a call to globus_gass_client_get_request_memory(), and passed to a globus_gass_client_get_request_memory_done_t callback function.

int
globus_gass_client_get_request_fail(
    globus_gass_client_get_request_t *request,
    globus_gass_client_fail_t fail_callback
    int failure_code)

Abort the get request. Both the GASS client and server will be notified of the failure by setting their request->status to GLOBUS_GASS_REQUEST_CLIENT_FAILURE, and the request->failure_code to the value passed in the failure_code argument.

globus_gass_client_get_request_done() must still be called after globus_gass_client_get_request_fail() is called. All other outstanding callbacks for this request will be complete before the fail_callback is invoked.

typedef void
(*globus_gass_client_get_request_fail_t) (
globus_gass_client_get_request_t *);

int
globus_gass_client_get_request_done(
globus_gass_client_get_request_t *request)

Complete and cleanup the request that was started by a previous call to globus_gass_client_get_request().

It is an error to call globus_gass_client_get_request_done() before the final callback for a request has been invoked. It is not an error to call globus_gass_client_get_request_done() from the final callback, or after the final callback has completed. The last callback for a request will be

a globus_gass_client_fail_t callback, or if none is specified
a globus_gass_client_get_request_fd_done_t or globus_gass_client_get_request_memory_done_t callback with request->outstanding set to 0.

After globus_gass_client_get_request_done() has been called, it is an error to access *request.

void
globus_gass_client_get_fd(
    char *url,
    char *proxy_url,
    int fd,
    unsigned long block_size,
    unsigned long *timestamp,
    unsigned long *total_length,
    int *failure_code)

Transfer data from the remote file specified by the url. The file data is written to the passed file descriptor. If block_size!=0, then this specifies a preferred block size that GASS should use when writing to the file descriptor. This call blocks until the operation completes.

The url can be one of the following types: ftp, x-gass.

If proxy_url!=GLOBUS_GASS_NULL, then connect to the host and port specified in proxy_url. Otherwise, use the host and port from url.

Upon successful completion, GLOBUS_GASS_REQUEST_DONE is returned, *timestamp is filled in with the remote file's timestamp, and *total_length is set to the number of bytes written to the file descriptor.

Upon failure, one of the GLOBUS_GASS_REQUEST_*_FAILURE values is returned, as described in globus_gass_client_get_request(), *total_length is set to the number of bytes written to the file descriptor, and *failure_code is set appropriately.

int
globus_gass_client_put_request(
    char *url,
    char *proxy_url,
    unsigned long total_length,
    globus_bool_t append,
    int ack_type,
    globus_gass_client_put_request_ack_t ack_callback,
    globus_gass_client_put_request_t **request)

Initiate a data transfer to the remote file specified by the url. The **request argument is initialized for this request, and should be passed to one or more subsequent globus_gass_client_put_request_*() calls to supply the data, and to globus_gass_client_put_request_done() to cleanup after the request.

The url can be one of the following types: ftp, x-gass.

If proxy_url!=GLOBUS_GASS_NULL, then connect to the host and port specified in proxy_url. Otherwise, use the host and port from url.

total_length is the length of the data, or globus_GLOBUS_GASS_LENGTH_UNKNOWN if it is not know and the start of the request.

If append==GLOBUS_TRUE, the data will be appended to the end of the specified url. Otherwise, the contents pointed to by the url will be replaced.

This functions returns one of:

GLOBUS_GASS_REQUEST_PENDING
The request was successfully started. *request is initialized for this request. It should use globus_gass_client_put_request_fd() and/or globus_gass_client_put_request_memory() to send the requested data, and globus_gass_client_put_request_done() must be called to cleanup the request.

GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died).
*failure_code contains the reason for the failure.

GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure callby the GASS server.
*failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client.
*failure_code contains the reason for the failure, as supplied by the GASS client.

If this function returns GLOBUS_GASS_REQUEST_PENDING, the ack_type argument determines when the put request is considered to be done. The options are:

GLOBUS_GASS_ACK_NONE
The request is done when all data has been sent by the client, but not necessarily received or handled by the server.

GLOBUS_GASS_ACK_COMPLETE
The request is done when all data has been received and handled by the server.

GLOBUS_GASS_ACK_TIMESTAMP
The request is done when all data has been received and handled by the server. In addition, this requests the server to return a timestamp for the file after the all data has been handled.

If this function returns GLOBUS_GASS_REQUEST_PENDING, ack_callback should be a function pointer which, if not NULL, will be called when the request is done, regardless of the ack_type. However, it is only called if the request succeeds (i.e. request->status is GLOBUS_GASS_REQUEST_DONE), but not if the request fails (i.e. request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If this function returns GLOBUS_GASS_REQUEST_PENDING, the following fields can be accessed directly from the request structure until globus_gass_client_get_request_done() is called with the structure:

request->status (int)

GLOBUS_GASS_REQUEST_PENDING
The request is still in progress.

GLOBUS_GASS_REQUEST_SYSTEM_FAILURE
The request failed due to a system failure (e.g. the server died).
*The failure_code contains the reason for the failure.

GLOBUS_GASS_REQUEST_SERVER_FAILURE
The request failed due to an explicit failure call by the GASS server.
*The failure_code contains the reason for the failure, as supplied by the GASS server.

GLOBUS_GASS_REQUEST_CLIENT_FAILURE
The request failed due to an explicit failure call by the GASS client.
*The failure_code contains the reason for the failure, as supplied by the GASS client.

GLOBUS_GASS_REQUEST_DONE
The request has completed successfully.

request->failure_code (int)

Set to a failure code when request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

request->timestamp (unsigned long)

Once the request is done (request->status is GLOBUS_GASS_REQUEST_DONE), if ack_type is GLOBUS_GASS_ACK_TIMESTAMP,
then this will contain the timestamp returned by the server, or GLOBUS_GASS_TIMESTAMP_UNKNOWN if it is not known.

request->total_length (unsigned long)

Total length of the data sent.

request->outstanding (int)

The number of globus_gass_client_put_request_fd() and globus_gass_client_put_request_memory() calls that are currently
outstanding for this request.

request->subject (char *)

The subject (i.e. globus user name) of the server to which this request was made. It is NULL if the subject is not known.

request->user_pointer (void *)

A pointer that can be used by the user for any purpose.

typedef void
(*globus_gass_client_put_request_ack_t)
(globus_gass_client_put_request_t *request)

This function is called when a put request from globus_gass_client_put_request() is considered done.

int
globus_gass_client_put_request_fd(
    globus_gass_client_put_request_t *request,
    int fd,
    unsigned long block_size,
    unsigned long max_length,
    globus_bool_t last_data,
    globus_gass_client_put_request_fd_done_t callback)

Read data from the file descriptor fd and send it for the put request. If block_size!=0, then this specifies a preferred block size that GASS should use when reading from the file descriptor. If max_length==GLOBUS_GASS_LENGTH_UNKNOWN, then read and send until end-of-file is reached on the file descriptor. Otherwise, read and send send max_length bytes or until end-of-file, whichever comes first.

If last_data==GLOBUS_TRUE, then this is the last globus_gass_client_put_request_*() function that will be called for this request.

For a single request, calls to globus_gass_client_put_request_fd() and globus_gass_client_put_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_client_put_request(). If the return value is GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_client_put_request_fd_done_t)(
    globus_gass_client_put_request_t *request,
    int fd,
    unsigned long send_length)

This function is called as a result of completion of a globus_gass_client_put_request_fd() request.

send_length is actual length of the portion of data sent for this globus_gass_client_put_request_fd() call.

The request->status field is set to the current status of the request, as described in globus_gass_client_put_request(). A value of GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_client_put_request_fd() and/or globus_gass_client_put_request_memory() should be made to receive the remainder of the request's data.

Notes:

send_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_client_put_request_fd() is outstanding after the request fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_client_put_request_memory(
    globus_gass_client_put_request_t *request,
    globus_byte_t *buffer,
    unsigned long buffer_length,
    globus_bool_t last_data,
    globus_gass_client_put_request_memory_done_t callback)

Send buffer_length bytes of data from the memory buffer for the put request.

If last_data==GLOBUS_TRUE, then this is the last globus_gass_client_put_request_*() function that will be called for this request.

For a single request, calls to globus_gass_client_put_request_fd() and globus_gass_client_put_request_memory() can be intermixed. Further, multiple calls to these function can be outstanding, and their order will be preserved.

This function returns the current status of the request, as described in globus_gass_client_put_request(). If the return value is GLOBUS_GASS_REQUEST_PENDING, then once the requested operation completes the callback function is called.

typedef void
(*globus_gass_client_put_request_memory_done_t)(
    globus_gass_client_put_request_t *request,
    globus_byte_t *buffer,
    unsigned long send_length)

This function is called as a result of completion of a globus_gass_client_put_request_memory() request.

send_length is actual length of the portion of data sent for this globus_gass_client_put_request_memory() call.

The request->status field is set to the current status of the request, as described in globus_gass_client_put_request(). A value of GLOBUS_GASS_REQUEST_PENDING implies that subsequent calls to globus_gass_client_put_request_fd() and/or globus_gass_client_put_request_memory() should be made to receive the remainder of the request's data.

Notes:

send_length may be greater than 0 even if request->status is GLOBUS_GASS_REQUEST_*_FAILURE.

If a call to globus_gass_client_put_request_fd() is outstanding after the request fails, this callback will be called with receive_length set to 0.

The request->outstanding field can be used to determine the number of currently outstanding requests.

int
globus_gass_client_put_request_fail(
    globus_gass_client_put_request_t *request,
    globus_gass_client_fail_t *fail_callback
     int failure_code)

Abort the put request. Both the GASS client and server will be notified of the failure by setting their request->status to GLOBUS_GASS_REQUEST_CLIENT_FAILURE, and the request->failure_code to the value passed in the failure_code argument.

globus_gass_client_put_request_done() must still be called after globus_gass_client_put_request_fail() is called. globus_gass_client_put_request_fail() returns immediately. The fail_callback will be called after all other outstanding callbacks for this request have been called.

typedef void
(*globus_gass_client_put_request_fail_t) (
globus_gass_client_put_request_t *);

int
globus_gass_client_put_request_done(
globus_gass_client_put_request_t *request)

Cleanup the request that was started by a previous call to globus_gass_client_put_request().

It is an error to call globus_gass_client_put_request_done() before the final callback for a request has been invoked. It is not an error to call globus_gass_client_put_request_done() from the final callback, or after the last callback has returned. The last callback for a request will be

a globus_gass_client_put_request_fail_t callback, or if none is specified
a globus_gass_client_ack_t callback, or if none is specified
a globus_gass_client_put_request_fd_done_t or globus_gass_client_put_request_memory_done_t callback with request->outstanding set to 0.

After globus_gass_client_put_request_done() has been called, it is an error to access *request.

int
globus_gass_client_put_fd(
    char *url,
    char *proxy_url,
    int fd,
    unsigned long block_size,
    unsigned long max_length,
    globus_bool_t append,
    int ack_type,
    unsigned long *timestamp,
    unsigned long *total_length,
    int *failure_code)

Transfer data to the remote file specified by the url. If max_length==GLOBUS_GASS_LENGTH_UNKNOWN, then read and send until end-of-file is reached on the file descriptor. Otherwise, read and send send max_length bytes or until end-of-file, whichever comes first. If block_size!=0, then this specifies a preferred block size that GASS should use when reading from the file descriptor.

The url can be one of the following types: ftp, x-gass.

If proxy_url!=GLOBUS_GASS_NULL, then connect to the host and port specified in proxy_url. Otherwise, use the host and port from url.

If append==GLOBUS_TRUE, the data will be appended to the end of the specified url. Otherwise, the contents pointed to by the url will be replaced.

Upon successful completion, GLOBUS_GASS_REQUEST_DONE is returned, *timestamp is filled in with the remote file's timestamp or GLOBUS_GASS_TIMESTAMP_UNKNOWN (depending on ack_type), and *total_length is set to the number of bytes read and sent.

The ack_type argument determines when this put request returns:

GLOBUS_GASS_ACK_NONE
The request returns when all data has been sent by the client, but not necessarily received or handled by the server.
*timestamp is set to GLOBUS_GASS_TIMESTAMP_UNKNOWN.

GLOBUS_GASS_ACK_COMPLETE
The request returns when all data has been received and handled by the server.
*timestamp is set to GLOBUS_GASS_TIMESTAMP_UNKNOWN.

GLOBUS_GASS_ACK_TIMESTAMP
The request returns when all data has been received and handled by the server. In addition, this requests the server to return a timestamp for the file after the all data has been handled, which is returned in *timestamp.

Upon failure, one of the GLOBUS_GASS_REQUEST_*_FAILURE values is returned, as described in globus_gass_client_put_request(), *total_length is set to the number of bytes read from the file descriptor and sent, and *failure_code is set appropriately.

int
globus_gass_client_put_socket(
    char *url,
    char *proxy_url,
    globus_bool_t append,
    int ack_type,
    int *return_fd)

Return a TCP socket in *return_fd, such that data that is subsequently written to this fd will be immediately sent
to the file specified by the url.

The url must be of the x-gass type.

If proxy_url!=GLOBUS_GASS_NULL, then connect to the host and port specified in proxy_url. Otherwise, use the host and port from url.

If append==GLOBUS_TRUE, the data will be appended to the end of the specified url. Otherwise, the contents pointed to by the url will be replaced.

The ack_type argument affects the behavior of globus_gass_client_put_socket_close(), as describe below with that function.

This function returns GLOBUS_GASS_SUCCESS if the socket is successfully setup, otherwise it returns a non-zero system failure code.

int
globus_gass_client_put_socket_close(
    int fd,
    unsigned long *timestamp,
    unsigned long *total_Length,
    int *failure_code)

Close the socket previously returned by globus_gass_client_put_socket().

Upon successful completion, GLOBUS_GASS_REQUEST_DONE is returned. The ack_type that was passed to globus_gass_client_put_socket() when creating this socket affects this function's return as follows:

GLOBUS_GASS_ACK_NONE
This function returns when the socket has been closed, but the data has not necessarily received or handled by the server.
*timestamp is set to GLOBUS_GASS_TIMESTAMP_UNKNOWN.
*total_length is set to GLOBUS_GASS_LENGTH_UNKNOWN.

GLOBUS_GASS_ACK_COMPLETE
This function returns when all data has been received and handled by the server.
*timestamp is set to GLOBUS_GASS_TIMESTAMP_UNKNOWN.
*total_length is set to the total number of bytes sent on this socket.

GLOBUS_GASS_ACK_TIMESTAMP
This function returns when all data has been received and handled by the server. In addition, this requests
the server to return a timestamp for the file after the all data has been handled, which is returned in *timestamp.
*total_length is set to the total number of bytes sent on this socket.

Upon failure, one of the GLOBUS_GASS_REQUEST_*_FAILURE values is returned, as described in globus_gass_client_put_request(), *total_length is set to the number of bytes sent on this socket, and *failure_code is set appropriately.