globus_gram_protocol_io(3)

📦
version 13.6 · 6 versions
, in fedora 43, fedora 44, ubuntu resolute, ubuntu stonking

💖 globus_gram_protocol_io(3) — NAME 💖

okay bestie, welcome to globus_gram_protocol_io, straight out of the Library Functions Manual, and it's literally all about Message I/O. That's the vibe. That's the name. Periodt. ✨

  • Message I/O.

✨ SYNOPSIS ✨

🎀 Typedefs 🎀

typedef unsigned long globus_gram_protocol_handle_t
    Unique GRAM protocol identifier.
typedef struct globus_gram_protocol_hash_entry_s
    globus_gram_protocol_extension_t
    GRAM protocol extension attribute-value pair.

🌸 Functions 🌸

int globus_gram_protocol_setup_attr (globus_io_attr_t *attr)
    Create default I/O attribute for GRAM.
globus_bool_t globus_gram_protocol_authorize_self (gss_ctx_id_t context)
    Determine if a GSSAPI context has the same source and target
    identities.
int globus_gram_protocol_allow_attach (char **url,
    globus_gram_protocol_callback_t callback, void *callback_arg)
    Create a GRAM protocol service listener.
int globus_gram_protocol_callback_disallow (char *url)
    Stop a GASS protocol listener from handling new requests.
int globus_gram_protocol_post (const char *url,
    globus_gram_protocol_handle_t *handle, globus_io_attr_t *attr,
    globus_byte_t *message, globus_size_t message_size,
    globus_gram_protocol_callback_t callback, void *callback_arg)
    Post a GRAM protocol request to a GRAM server.
int globus_gram_protocol_post_delegation (const char *url,
    globus_gram_protocol_handle_t *handle, globus_io_attr_t *attr,
    globus_byte_t *message, globus_size_t message_size, gss_cred_id_t
    cred_handle, gss_OID_set restriction_oids, gss_buffer_set_t
    restriction_buffers, OM_uint32 req_flags, OM_uint32 time_req,
    globus_gram_protocol_callback_t callback, void *callback_arg)
    Post a GRAM protocol delegation request to a GRAM server.
int globus_gram_protocol_reply (globus_gram_protocol_handle_t handle,
    int code, globus_byte_t *message, globus_size_t message_size)
    Reply to a GRAM protocol message.
int globus_gram_protocol_accept_delegation
    (globus_gram_protocol_handle_t handle, gss_OID_set restriction_oids,
    gss_buffer_set_t restriction_buffers, OM_uint32 req_flags, OM_uint32
    time_req, globus_gram_protocol_delegation_callback_t callback, void
    *arg)
    Perform the server-side of the GSSAPI delegation handshake to
    receive a new delegated credential.
int globus_gram_protocol_get_sec_context (globus_gram_protocol_handle_t
    handle, gss_ctx_id_t *context)
    Get a reference to the GSSAPI security context associated with a
    GRAM protocol handle.

🦋 Detailed Description 🦋

Message I/O.

The functions in this section are related to sending and receiving GRAM protocol messages. That's the whole assignment, bestie. Sending. Receiving. GRAM protocol messages. Iconic behavior fr fr. 💅

🌈 Typedef Documentation 🌈

🧚 typedef struct globus_gram_protocol_hash_entry_s globus_gram_protocol_extension_t

GRAM protocol extension attribute-value pair. The globus_gram_protocol_extension_t data type contains an attribute value pair that represents an extension to the GRAM2 protocol. It's giving "extra credit for the protocol" energy. 🎀

🧚 typedef unsigned long globus_gram_protocol_handle_t

Unique GRAM protocol identifier. The globus_gram_protocol_handle_t data type is used by functions in the GRAM protocol API as a unique discriminant between instances of a callback invocation.

There are no public functions that operate on these handles. They are used as identifiers for callback functions. So like, they're just little name tags for your callbacks. Cute. 🏷️

👑 Function Documentation 👑

🔥 int globus_gram_protocol_accept_delegation (globus_gram_protocol_handle_t handle, gss_OID_set restriction_oids, gss_buffer_set_t restriction_buffers, OM_uint32 req_flags, OM_uint32 time_req, globus_gram_protocol_delegation_callback_t callback, void * arg)

Perform the server-side of the GSSAPI delegation handshake to receive a new delegated credential. The globus_gram_protocol_accept_delegation() function performs the service side accepting of a GRAM protocol delegation exchange with a GRAM protocol client. This is performed after the delegation HTTP message has been unpacked by the application.

The globus_gram_protocol_accept_delegation() function returns after processing the GSSAPI handshake, passing the delegated credential or error information to the function pointed to by the callback parameter.

💖 Parameters 💖

  • handle — A GRAM protocol handle on which the server received a protocol refresh message.
  • restriction_oids — A set of OID values indicating the data in the restriction_buffers parameter. This parameter may have the value GSS_C_NO_OID_SET if there are no restriction buffers.
  • restriction_buffers — A set of binary data buffers which will be included in the delegated credential. The type of data in these buffers is determined by the OID values in restriction_oids. This parameter may have the value GSS_C_EMPTY_BUFFER_SET if there are no extra restrictions to be added to the credential.
  • req_flags — A bitwise-or of GSSAPI flag values to use when delegating the credential using gss_init_delegation().
  • time_req — An integer value indicating the length of time (in seconds) that the delegated credential should be valid for. This is an advisory parameter: no error will be returned if a credential with the requested lifetime can not be created.
  • callback — A pointer to a function to call when the delegation handshake has completed or failed. This function will be passed the value of arg as well as the handle and delegated credential or error that occurred processing the delegation messages.
  • arg — A pointer to application-specific data which will be passed to the function pointed to by callback as its first parameter. This may be NULL if the application has a NULL callback or does not require the pointer to establish its context in the callback.

🌟 Returns 🌟

Upon success, globus_gram_protocol_accept_delegation() returns GLOBUS_SUCCESS and registers the function pointed to by callback to be called after the delegation completes or fails. If an error occurs, globus_gram_protocol_accept_delegation() returns an integer error code and the callback function is not registered.

✨ Return values ✨

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED — Malloc failed
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

🔥 int globus_gram_protocol_allow_attach (char ** url, globus_gram_protocol_callback_t callback, void * callback_arg)

Create a GRAM protocol service listener. The globus_gram_protocol_allow_attach() function creates a GRAM protocol listener to which other processes can send GRAM protocol messages. The listener will automatically accept new connections on it's TCP/IP port and parse GRAM requests. The requests will be passed to the function pointed to by the callback parameter for the application to unpack, handle, and send a reply by calling globus_gram_protocol_reply().

💖 Parameters 💖

  • url — An output parameter that will be initialized to point to a string that will hold the URL of the new listener. This URL may be published or otherwise passed to applications which need to contact this GRAM protocol server. The URL will be of the form https://host:port/.
  • callback — A pointer to a function to be called when a new request has been received by this listener. This function will be passed the request, which may be unpacked using one of the functions described in the message packing section of the documentation.
  • callback_arg — A pointer to arbitrary user data which will be passed to the callback function as its first parameter.

🌟 Returns 🌟

Upon success, globus_gram_protocol_allow_attach() returns GLOBUS_SUCCESS and modifies the url parameter to point to a newly allocated string. The caller is then responsible for freeing this string. If an error occurs, an integer error code will be returned and the url parameter value will be uninitialized.

✨ Return values ✨

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

👀 See also 👀

globus_gram_protocol_callback_disallow()

🔥 globus_bool_t globus_gram_protocol_authorize_self (gss_ctx_id_t context)

Determine if a GSSAPI context has the same source and target identities. The globus_gram_protocol_authorize_self() function implements a predicate which returns true if the source and destination identities used to establish the GSSAPI security context are the same.

💖 Parameters 💖

  • context — A GSSAPI security context which has been previously established. The source and target names of this context will be inspected by this function.

🌟 Returns 🌟

If the source and target identities are the same, then globus_gram_protocol_authorize_self() returns GLOBUS_TRUE, otherwise, this function returns GLOBUS_FALSE.

✨ Return values ✨

  • GLOBUS_TRUE — The source and target identities are the same.
  • GLOBUS_FALSE — The source and target identities are not the same or this function is unabled to inspect the security context.

🔥 int globus_gram_protocol_callback_disallow (char * url)

Stop a GASS protocol listener from handling new requests. The globus_gram_protocol_callback_disallow() function stops the listener named by the value of the url parameter from receiving any new requests. It also frees memory used internally by the GRAM protocol implementation to handle requests for this listener.

The globus_gram_protocol_callback_disallow() function will wait until all requests being processed by this listener have completed processing. Once globus_gram_protocol_callback_disallow() returns, no further request callbacks will occur for the listener.

💖 Parameters 💖

  • url — A pointer to the URL string which names the listener to disable.

🌟 Returns 🌟

Upon success, the globus_gram_protocol_callback_disallow() function returns GLOBUS_SUCCESS and frees internal state associated with the listener named by the url parameter. If an error occurs, its integer error code value will be returned and no listener will be affected.

✨ Return values ✨

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND — Callback not found

👀 See also 👀

globus_gram_protocol_allow_attach()

int globus_gram_protocol_get_sec_context (globus_gram_protocol_handle_t handle, gss_ctx_id_t * context)

okay so this one is literally about grabbing a reference to the GSSAPI security context that's tied to a GRAM protocol handle. The globus_gram_protocol_get_sec_context() function retrieves a reference to the GSSAPI security context associated with a particular GRAM protocol handle. You can peek at this context all you want, but bestie, you must not destroy it — that's not your job. And super important: you can only call globus_gram_protocol_get_sec_context() after the GRAM protocol library has already called the callback function that goes with a GRAM protocol message exchange. So like, wait for the callback, then do your thing. ✨

✨ Parameters ✨

  • handle — the GRAM protocol handle that's associated with a GRAM protocol message exchange. 🫶
  • context — the GSSAPI security context that's associated with the protocol handle. 👑

✨ Returns ✨

If everything's slay, globus_gram_protocol_get_sec_context() returns GLOBUS_SUCCESS and changes the context parameter to point to the security context tied to the handle parameter. But if something goes wrong, you get an integer error code back, and the value of the context parameter is just... undefined. 💀

✨ Return values ✨

  • GLOBUS_SUCCESS — Success 💖
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request 🙈

int globus_gram_protocol_post (const char * url, globus_gram_protocol_handle_t * handle, globus_io_attr_t * attr, globus_byte_t * message, globus_size_t message_size, globus_gram_protocol_callback_t callback, void * callback_arg)

So globus_gram_protocol_post() is how you slide into a GRAM server's DMs with a GRAM protocol request. It kicks off a GRAM protocol message exchange with a GRAM protocol listener. It comes back to you after it's framed the message and started the connection. When the whole message exchange is done, the function pointed to by callback gets called — either in another thread, or if you're running a non-threaded app, when you call globus_poll() or globus_cond_wait(). No cap. 🔥

✨ Parameters ✨

  • url — a pointer to a string with the URL of the server you're posting the request to. This URL has to be an HTTPS URL that names a GRAM service resource. Periodt. 🌐
  • handle — a pointer to a globus_gram_protocol_handle_t that will get initialized with a unique handle identifier. This identifier gets passed to the callback function so you can tell replies to multiple GRAM Protocol requests apart. This pointer can be NULL if you're not gonna have multiple simultaneous requests. 💅
  • attr — a pointer to a Globus I/O attribute set, which is used as parameters when connecting to the GRAM server. You can set attr to NULL, and then the default GRAM Protocol attributes get used (authentication to self, SSL-compatible transport, with message integrity). ✨
  • message — a pointer to a message string to send to the GRAM server. Normally you'd create this by calling one of the GRAM Protocol pack functions. This message doesn't need to be NULL terminated because the length is passed in message_size. 📦
  • message_size — the length of the message string. Usually you get this as one of the output parameters from one of the GRAM Protocol pack functions. 📏
  • callback — a pointer to a function to call when the response to this message is received or the message exchange fails. This can be NULL, in which case you get no callback and you won't be able to verify whether the message was successfully received. 😭
  • callback_arg — a pointer to application-specific data that gets passed to the function pointed to by callback as its first parameter. This can be NULL if you have a NULL callback or you don't need the pointer to establish context in the callback. 🫶

✨ Returns ✨

On success, globus_gram_protocol_post() returns GLOBUS_SUCCESS, initiates the message exchange, registers the function pointed to by callback to be called when the exchange completes or fails, and modifies the handle parameter if it's non-NULL. If an error happens, its error code gets returned, the handle parameter will be uninitialized, and the function pointed to by callback will not be called. So yeah, no callback for you. 💀

✨ Return values ✨

  • GLOBUS_SUCCESS — Success 💖
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact 📞
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory 🧠
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request 🙈
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources 🚫

✨ Note ✨

There is literally no way to time out or cancel a service request that you start with globus_gram_protocol_post(). So be sure, bestie. ⏳

✨ See also ✨

globus_gram_protocol_reply()

int globus_gram_protocol_post_delegation (const char * url, globus_gram_protocol_handle_t * handle, globus_io_attr_t * attr, globus_byte_t * message, globus_size_t message_size, gss_cred_id_t cred_handle, gss_OID_set restriction_oids, gss_buffer_set_t restriction_buffers, OM_uint32 req_flags, OM_uint32 time_req, globus_gram_protocol_callback_t callback, void * callback_arg)

okay so globus_gram_protocol_post_delegation() is the delegation version of posting a GRAM protocol request. It initiates a GRAM protocol delegation exchange with a GRAM protocol listener. The delegation protocol is a custom mix of HTTP and SSL records. It's giving very specific vibes. 🌀

The function returns after framing the message and initiating the connection to be used for delegation. When the message exchange is complete, the function pointed to by callback gets invoked — either in another thread or when a non-threaded application calls globus_poll() or globus_cond_wait(). Same deal as before. ✨

✨ Parameters ✨

  • url — a pointer to a string with the URL of the server to post the request to. This URL must be an HTTPS URL naming a GRAM service resource. 🌐
  • handle — a pointer to a globus_gram_protocol_handle_t that will be initialized with a unique handle identifier. This identifier gets passed to the callback function so you can differentiate replies to multiple GRAM Protocol requests. This pointer may be NULL if you won't have multiple simultaneous requests. 💅
  • attr — a pointer to a Globus I/O attribute set, used as parameters when connecting to the GRAM server. The value of attr may be NULL, in which case the default GRAM Protocol attributes will be used (authentication to self, SSL-compatible transport, with message integrity). ✨
  • message — a pointer to a message string to send to the GRAM server. This is normally created by calling one of the GRAM Protocol pack functions. This message need not be NULL terminated as the length is passed in the message_size parameter. 📦
  • message_size — the length of the message string. Typically generated as one of the output parameters to one of the GRAM Protocol pack functions. 📏
  • cred_handle — handle to an existing GSSAPI security credential. If this parameter is set to GSS_C_NO_CREDENTIAL, then the current account's default credential will be used. A proxy credential sharing the identity of this credential will be delegated to the GRAM protocol server. 🔑
  • restriction_oids — a set of OID values indicating the data in the restriction_buffers parameter. This parameter may have the value GSS_C_NO_OID_SET if there are no restriction buffers. 🏷️
  • restriction_buffers — a set of binary data buffers which will be included in the delegated credential. The type of data in these buffers is determined by the OID values in restriction_oids. This parameter may have the value GSS_C_EMPTY_BUFFER_SET if there are no extra restrictions to be added to the credential. 📦
  • req_flags — a bitwise-or of GSSAPI flag values to use when delegating the credential using gss_init_delegation(). 🚩
  • time_req — an integer value indicating the length of time (in seconds) that the delegated credential should be valid for. This is an advisory parameter: no error will be returned if a credential with the requested lifetime can not be created. ⏱️
  • callback — a pointer to a function to call when the response to this message is received or the message exchange fails. This may be NULL, in which case no callback will be received, and the caller will be unable to verify whether the message was successfully received. 😭
  • callback_arg — a pointer to application-specific data which will be passed to the function pointed to by callback as its first parameter. This may be NULL if the application has a NULL callback or does not require the pointer to establish its context in the callback. 🫶

✨ Returns ✨

Upon success, globus_gram_protocol_post_delegation() returns GLOBUS_SUCCESS, initiates the message exchange, registers the function pointed to by callback to be called when the exchange completes or fails, and modifies the handle parameter if it is non-NULL. If an error occurs, its error code will be returned, the handle parameter will be uninitialized, and the function pointed to by callback will not be called. In the case of a protocol or delegation failure, the callback function will be called with the errorcode parameter set to the error. 💀

✨ Return values ✨

  • GLOBUS_SUCCESS — Success 💖
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact 📞
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory 🧠
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request 🙈
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources 🚫

✨ Note ✨

There is no way to time out or cancel a service request that is begun with globus_gram_protocol_post_delegation(). So once you post, you're in it. ⏳

✨ See also ✨

globus_gram_protocol_reply()

int globus_gram_protocol_reply (globus_gram_protocol_handle_t handle, int code, globus_byte_t * message, globus_size_t message_size)

So globus_gram_protocol_reply() is all about replying to a GRAM protocol message. It sends a response message to a client which initiated a GRAM message exchange. The globus_gram_protocol_reply() function composes the message with an HTTP message frame and then sends it to the client which initiated the exchange. That's it — the original text cuts off here, so we're done for this part! 💅

Parameters 💅

okay so for globus_gram_protocol_reply(), here's the tea on the arguments:

  • handle — a GRAM protocol handle that this function uses to figure out which network connection to send this reply on. it HAS to be the exact same value you passed as a parameter to the callback function you registered with globus_gram_protocol_allow_attach(). no substitutions, bestie. 🙅‍♀️
  • code — the HTTP response code. should be one from the set described in RFC 2616.
  • message — a pointer to a message string to send to the GRAM client. normally you get this by calling one of the GRAM Protocol pack functions. it does NOT need to be NULL terminated because the length is passed separately in message_size. 💖
  • message_size — the length of that message string. typically it's one of the output parameters from one of the GRAM Protocol pack functions.

Returns ✨

when it works, globus_gram_protocol_reply() returns GLOBUS_SUCCESS, wraps the message in an HTTP header, and starts sending it to the client.

major warning: the caller must NOT try to use the value of the handle parameter after this function returns. like, it's done. let it go. 😭

if something goes wrong, you get its integer error code back instead.

Return values 🫶

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No Resources

See also 👀

  • globus_gram_protocol_allow_attach()

✨ int globus_gram_protocol_setup_attr (globus_io_attr_t * attr) ✨

okay so this one? it's giving "create default I/O attribute for GRAM." basically globus_gram_protocol_setup_attr() makes a brand new globus_io attribute with all the default values you need for a GRAM client and a job manager to talk to each other. and those defaults include:

  • SO_KEEPALIVE
  • GSSAPI Mutual Authentication
  • GSSAPI Self Authorization
  • SSL-compatible message wrapping

Parameters

  • attr — a pointer to a globus_io_attr_t structure that this function will initialize. 💅

Returns

when it works, globus_gram_protocol_setup_attr() changes the attr parameter to point at a new attribute and returns GLOBUS_SUCCESS. when that happens, you must destroy the attribute when you're done with it by calling globus_io_tcpattr_destroy(). if an error happens, its value gets returned and the attribute that attr points to gets set to an uninitialized state. 😭

Return values

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_CONNECTION_FAILED — Error initializing attribute

✨ Author ✨

ngl this whole page was generated automatically by Doxygen for globus_gram_protocol from the source code. so no human author credit, just robot magic. 🤖💖

and that's a wrap on globus_gram_protocol_io(3) from globus_gram_protocol, Version 13.6. periodt. 💅✨🦋

📦 where this page comes from