globus_gas...er_request(3)

📦
version 9.5 · 7 versions
, in epel 10, fedora 43, fedora 44, ubuntu resolute

💖 globus_gas...er_request — Library Functions Manual 💖

okay bestie, welcome to the Request Handles page of the GASS Transfer API. this is the <globus_gass_transfer_request.h> corner of the universe where file transfers get their little handle thingies. grab a boba, we're going in 🧋✨

🌸 NAME 🌸

globus_gass_transfer_request — Request Handles

like, literally just: Request Handles. that's the whole name section. iconic minimalism. 💅

✨ SYNOPSIS ✨

🎀 Data Structures

  • struct globus_gass_transfer_request_t — the Request handle itself. your main character. 👑

🦋 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

here's the whole squad, no cap:

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.

Request handles are the way the GASS Transfer API ties operations to one single file transfer request. like, one handle = one vibe = one transfer, fr fr. specifically? they're what you use to register multiple byte range buffers with a file transfer request, and to query the state of a transfer that's currently in-progress. 👀

If you're implementing a server 🖥️: the request handle gets populated for you by the protocol module implementation. then you, the server, get to use the functions in this section to figure out what the client is actually asking for.

If you're implementing a client 🫶: you should query the request handle in two moments —

  1. after the blocking call or the initial callback has been invoked, to find out whether the request has been authorized or referred, and
  2. after EOF, to find out whether the request has completed successfully.

and one more lil thing: a request handle contains a pointer, and the handler of the request can use that pointer to store a pointer to arbitrary application-specific data. very "store your own stuff in my pocket" energy. 🎒

🧚 Enumeration Type Documentation 🧚

⭐ enum globus_gass_transfer_request_status_t

Request Status

here's every status the girlies can be in:

  • GLOBUS_GASS_TRANSFER_REQUEST_INVALID — the handle is no longer valid. she's gone, bestie. 💀
  • GLOBUS_GASS_TRANSFER_REQUEST_STARTING — initial connection and authorization is not yet completed. still getting ready, still doing her hair. 💅
  • GLOBUS_GASS_TRANSFER_REQUEST_PENDING — request is authorized. ✅
  • GLOBUS_GASS_TRANSFER_REQUEST_FAILED — request failed due to protocol error, or because the client or server aborted the request. 😭
  • GLOBUS_GASS_TRANSFER_REQUEST_REFERRED — this server cannot process the request, so it's referred to another URL or URLs. not me, not here, go ask them. 👉
  • GLOBUS_GASS_TRANSFER_REQUEST_DENIED — the server denied this request. 🚫
  • GLOBUS_GASS_TRANSFER_REQUEST_DONE — all callbacks have completed. she ate and she's done. 👑

⭐ enum globus_gass_transfer_request_type_t

Type of operation associated with a request handle.

the four flavors of "what are we even doing here":

  • GLOBUS_GASS_TRANSFER_REQUEST_TYPE_INVALID — handle no longer valid. expired, babe. 💀
  • 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. 🧷

to be continued, bestie — this page is long and we are NOT done yet 💜

✨ Function Documentation ✨

Okay bestie, this is the part where we meet the actual functions. Buckle up, because there are a lot of them, and every single one is iconic in its own way. 💅

globus_gass_transfer_request_destroy

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. Like, not even a little. 🙈

Parameters

  • request — the request to destroy.

Return values

  • GLOBUS_SUCCESS — the request handle reference was successfully destroyed. Slay.
  • 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.

globus_gass_transfer_request_get_denial_message

char * globus_gass_transfer_request_get_denial_message (globus_gass_transfer_request_t request)

Get a 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. Don't forget, bestie, or it's a leak. 💀

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()

globus_gass_transfer_request_get_denial_reason

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. So if you're confused, that's a protocol vibe check, not a you problem. 🦋

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()

globus_gass_transfer_request_get_length

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. It's giving mystery length, and honestly? Same. 😭

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.

globus_gass_transfer_request_get_referral

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. Yes, that's a whole extra step, but we do it for the plot. 🎀

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;

globus_gass_transfer_request_get_status

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 proceed, or whether the file transfer was successfully processed. It's the vibe check for your transfer. ✨

Parameters

  • request — the request handle to query.

Returns

  • A globus_gass_transfer_request_status_t indicating the current status of the request.

globus_gass_transfer_request_get_subject

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. Do not free it, bestie, I'm serious. 🙅‍♀️

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.

globus_gass_transfer_request_get_type

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. Server besties, this one's for you. 👑

Parameters

  • request — the request to query.

Returns

  • The type of the request.

globus_gass_transfer_request_get_url

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. So if you're building a server, this is your moment. 🌈

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. So like, don't hold onto it after the request ghosts you. 💀

globus_gass_transfer_request_get_user_pointer

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. It's your little pocket for whatever data you want. 🍓

Parameters

  • request — the request to query.

Returns

  • The user pointer's value.

globus_gass_transfer_request_set_length

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. (The original says "it's" and "give length parameter", and we're keeping that energy exactly. 💅)

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. One shot, bestie. 🔥

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. (Yes, it says URL here even though we're setting length. The manpage said what it said. No cap. 😭)
  • GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE — the request handle was invalid, or the URL had already been set.

globus_gass_transfer_request_set_type

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. Protocol module besties only, everyone else back up. 🛑

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.

globus_gass_transfer_request_set_url

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. So allocate it right, bestie. 🧚

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.

globus_gass_transfer_request_set_user_pointer

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. Same pocket energy as before, but now you're putting something in. 💖

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. (Yes, GLOBUS_SUCCES with one S. That's the manpage's spelling, and we respect the typo. 👑)
  • GLOBUS_GASS_TRANSFER_ERROR_INVALID_USE — an invalid request handle was passed to this function

👑 Author 👑

Generated automatically by Doxygen for globus_gass_transfer from the source code.

And that's the whole function documentation, bestie. Every handle, every return value, every little GLOBUS_* constant — all accounted for. 💅✨

This page came from the globus_gass_transfer source, version 9.5, and the footer's date vibe is whatever the build machine stamped it with — but honestly, it's giving timeless. 🫶 Periodt. 🌈💖

📦 where this page comes from