Message I/O
[Functions]

Functions

• int globus_gram_protocol_allow_attach (char **url, globus_gram_protocol_callback_t callback, void *callback_arg)
• int globus_gram_protocol_callback_disallow (char *url)
• 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)
• int globus_gram_protocol_reply (globus_gram_protocol_handle_t handle, int code, globus_byte_t *message, globus_size_t message_size)
• int globus_gram_protocol_get_sec_context (globus_gram_protocol_handle_t handle, gss_ctx_id_t *context)

---

Detailed Description

The functions in this section

---

Function Documentation

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

Create a GRAM Protocol listener. Creates a GRAM Protocol listener. The listener will automatically accept new connections on it's TCP/IP port and parse GRAM requests. The requests will be passed to the specified callback function to the user can unpack the request, handle it, and send a reply by calling globus_gram_protocol_reply(). Parameters: url  A pointer to a character array which will be allocated to hold the URL of the listener. This URL may be published or otherwise passed to applications which need to contact this protocol server. The URL will be of the form https://<host>:<port>/. It is the user's responsibility to free this memory. callback  The callback 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 it's first parameter. Return values: GLOBUS_SUCCESS  The listener was created. The url parameter points to a string containing the contact URL for the listener. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST  The GRAM Protocol module was not properly activated. GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED  A memory allocation failed when trying to create the listener. GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES  Some I/O error occurred when trying to create the listener. See also: globus_gram_protocol_callback_disallow()

int globus_gram_protocol_callback_disallow (      char * url )

Disable a listener from handling any new requests. Disables a listener making it unable to receive any new requests, and freeing memory associated with the listener. Will block if a request is in progress, but once this function returns, no further request callbacks create by the listener will occur. Parameters: url  The URL of the listener to disable. Return values: GLOBUS_SUCCESS  The listener was closed. No further callbacks will be called on behalf of this listener. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT  The url string could not be parsed. GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND  The GRAM protocol library doesn't know of any listener associated with this URL. See also: globus_gram_protocol_allow_attach()

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)

Frame and send a GRAM protocol request. Connects to the GRAM Protocol server specified by the url parameter, frames the message with HTTP headers, and sends it. If callback is non-NULL, then the function pointed to by it will be called when a response is received from the server. Parameters: url  The URL of the server to send the message to. The url may be freed once this function returns. handle  A pointer to a globus_gram_protocol_handle_t which will be initialized with a unique handle identifier. This identifier will be passed to the callback function to allow the caller to differentiate replies to multiple GRAM Protocol servers. attr  A pointer to a Globus I/O attribute set, which will be used as parameters when connecting to the GRAM server. The attribute set may be GLOBUS_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 array to be sent to the GRAM server. This is normally created by calling one of the GRAM Protocol pack functions. This message need not be NULL terminated. The memory associated with message may be freed as soon as this function returns. message_size  The length of the message string. Typically generated as one of the output parameters to one of the GRAM Protocol pack functions. callback  A pointer to a callback function to call when the response to this message is received. This may be GLOBUS_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 arbitrary user data which will be passed to the callback function as it's first parameter. Return values: GLOBUS_SUCCESS  The message was successfully framed, and is in the process of being sent. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT  The url parameter could not be parsed. GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED  A memory allocation failed when trying to frame or send the message. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST  The GRAM Protocol module was not properly activated. GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES  Some I/O error occurred when trying to send the message. 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)

Frame and send a GRAM protocol reply. On an existing handle, frame and send the reply. The reply consists of a response code and a message. This function should only be called in response to a callback containing a GRAM Protocol request. It should not be called using the same handle as created by calling globus_gram_protocol_post(). Parameters: handle  The GRAM Protocol handle created when a connection arrives on a listener created by globus_gram_protocol_allow_attach(). The handle will be passed to the callback. The user must reply to all request callbacks which they receive. code  A response code. The code should be one from the standard HTTP response codes described in RFC XXX. message  A pointer to a message array to be sent to the GRAM client. This is normally created by calling one of the GRAM Protocol pack functions. This message need not be NULL terminated. The memory associated with message may be freed as soon as this function returns. message_size  The length of the message string. Typically generated as one of the output parameters to one of the GRAM Protocol pack functions. Return values: GLOBUS_SUCCESS  The reply was successfully framed and is being sent. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST  The GRAM Protocol module was not properly activated. GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES  Some I/O error occurred when trying to send the reply. See also: globus_gram_protocol_post()

int globus_gram_protocol_get_sec_context (      globus_gram_protocol_handle_t handle,      gss_ctx_id_t * context)

Extract the GSS Context from a GRAM Connection. Extract the GSS Context from a existing, connected handle This function should only be called after the GRAM protocol connection has been established. Parameters: handle  The GRAM Protocol handle created when a connection arrives on a listener created by globus_gram_protocol_allow_attach(). context  The GSS Context associated with the connection. Return values: GLOBUS_SUCCESS  The reply was successfully framed and is being sent. GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST  The GRAM Protocol module was not properly activated.

---

about globus | grid research | globus toolkit | software development

Comments? webmaster@globus.org

 

---

For questions or feedback about this website: webmaster@globus.org [privacy statements]
For technical support or questions about Globus software, visit our technical support page.

Globus, Globus Alliance, and Globus Toolkit are trademarks held by the University of Chicago.