Man Linux: Main Page and Category List

NAME

       Message I/O -

       The functions in this section are related to sending and receiving GRAM
       protocol messages.

   Typedefs
       typedef unsigned long globus_gram_protocol_handle_t
       typedef struct globus_gram_protocol_hash_entry_s
           globus_gram_protocol_extension_t

   Functions
       int globus_gram_protocol_setup_attr (globus_io_attr_t *attr)
       globus_bool_t globus_gram_protocol_authorize_self (gss_ctx_id_t
           context)
       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_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)
       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_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)
       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 are related to sending and receiving GRAM
       protocol messages.

Typedef Documentation

   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.

   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.

Function Documentation

   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

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

   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_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_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
           erorr 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_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 interger 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

Author

       Generated automatically by Doxygen for globus gram protocol from the
       source code.