NAME

       globus_gram_protocol_io - Message I/O

        - 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.

Typedef Documentation

   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.

   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.

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 identiies 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)
       Get a reference to the GSSAPI security context associated with 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. This context may be
       inspected by the caller but must not be destroyed by the caller. The
       globus_gram_protocol_get_sec_context() function must only be called after the GRAM
       protocol library has called the callback function associated with a GRAM protocol message
       exchange.

       Parameters
           handle The GRAM protocol handle associated with a GRAM protocol message exchange.
           context The GSSAPI security context associated with the protocol handle.

       Returns
           Upon success, globus_gram_protocol_get_sec_context() returns GLOBUS_SUCCESS and
           modifies the context parameter to point to the security context associated with the
           handle parameter. If an error occurs, an integer error code is returned and the value
           of the context parameter is 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)
       Post a GRAM protocol request to a GRAM server. The globus_gram_protocol_post() function
       initiates a GRAM protocol message exchange with a GRAM protocol listener. It returns after
       framing the message and initiating the connection. When the message exchange is complete,
       the function pointed to by callback is invoked either in another thread or when a non-
       threaded application calls the globus_poll() or globus_cond_wait() functions.

       Parameters
           url A pointer to a string containing 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 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 requests. This
           pointer may be NULL if the caller will not have multiple simultaneous requests.
           attr A pointer to a Globus I/O attribute set, which will be 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 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 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.
           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() 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 be callback will not be called.

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

       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)
       Post a GRAM protocol delegation request to a GRAM server. The
       globus_gram_protocol_post_delegation() function initiates a GRAM protocol delegation
       exchange with a GRAM protocol listener. The delegation protocol is a custom mix of HTTP
       and SSL records.

       The globus_gram_protocol_post_delegation() 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 is invoked either in another thread or when
       a non-threaded application calls the globus_poll() or globus_cond_wait() functions.

       Parameters
           url A pointer to a string containing 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 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 requests. This
           pointer may be NULL if the caller will not have multiple simultaneous requests.
           attr A pointer to a Globus I/O attribute set, which will be 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 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 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 be 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().

       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)
       Reply to a GRAM protocol message. The globus_gram_protocol_reply() function 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.

       Parameters
           handle A GRAM protocol handle which is used by this function to determine the network
           connection to use for this reply. This must be the same value as was passed as a
           parameter to the callback function registered with the
           globus_gram_protocol_allow_attach() function.
           code The HTTP response code. The code should be one from the set described in RFC
           2616.
           message A pointer to a message string 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 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.

       Returns
           Upon success, globus_gram_protocol_reply() returns GLOBUS_SUCCESS, frames the message
           with an HTTP header and initiates sending the message to the client. The caller must
           not try to use the value of the handle parameter after this function returns. If an
           error occurs, its integer error code will be returned.

       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)
       Create default I/O attribute for GRAM. The globus_gram_protocol_setup_attr() function
       creates a new globus_io attribute containing the default set of values needed for
       communication between a GRAM client and a job manager. These attributes include:

       • SO_KEEPALIVE

       • GSSAPI Mutual Authentication

       • GSSAPI Self Authorization

       • SSL-compatible message wrapping

       Parameters
           attr A pointer to a globus_io_attr_t structure which will be initialized by this
           function.

       Returns
           Upon success, globus_gram_protocol_setup_attr() modifies the attr parameter to point
           to a new attribute and returns the value GLOBUS_SUCCESS. When this occurs, the caller
           must destroy the attribute when no longer needed by calling
           globus_io_tcpattr_destroy(). If an error occurs, its value will be returned and the
           attribute pointed to by the attr parameter will be set to an uninitialized state.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_CONNECTION_FAILED Error initializing attribute

Author

       Generated automatically by Doxygen for globus_gram_protocol from the source code.