Provided by: libglobus-gram-protocol-doc_13.6-3build1_all bug

NAME

       globus_gram_protocol_pack - Message Packing

        - Message Packing.

SYNOPSIS

   Functions
       int globus_gram_protocol_pack_job_request (int job_state_mask, const char *callback_url,
           const char *rsl, globus_byte_t **query, globus_size_t *querysize)
           Pack a GRAM Job Request.
       int globus_gram_protocol_pack_job_request_reply (int status, const char *job_contact,
           globus_byte_t **reply, globus_size_t *replysize)
           Pack a GRAM reply message.
       int globus_gram_protocol_pack_job_request_reply_with_extensions (int status, const char
           *job_contact, globus_hashtable_t *extensions, globus_byte_t **reply, globus_size_t
           *replysize)
           Pack a GRAM reply message with extension attributes.
       int globus_gram_protocol_pack_status_request (const char *status_request, globus_byte_t
           **query, globus_size_t *querysize)
           Pack a GRAM query message.
       int globus_gram_protocol_pack_status_reply (int job_status, int failure_code, int
           job_failure_code, globus_byte_t **reply, globus_size_t *replysize)
           Pack a GRAM query reply message.
       int globus_gram_protocol_pack_status_reply_with_extensions (int job_status, int
           failure_code, int job_failure_code, globus_hashtable_t *extensions, globus_byte_t
           **reply, globus_size_t *replysize)
           Pack a GRAM query reply message with extensions.
       int globus_gram_protocol_pack_status_update_message (char *job_contact, int status, int
           failure_code, globus_byte_t **reply, globus_size_t *replysize)
           Pack a GRAM status update message.
       int globus_gram_protocol_pack_status_update_message_with_extensions (char *job_contact,
           int status, int failure_code, globus_hashtable_t *extensions, globus_byte_t **reply,
           globus_size_t *replysize)
           Pack a GRAM status update message with extensions.
       int globus_gram_protocol_pack_version_request (char **request, size_t *requestsize)
           Pack a GRAM version request message.

Detailed Description

       Message Packing.

Function Documentation

   int globus_gram_protocol_pack_job_request (int job_state_mask, const char * callback_url,
       const char * rsl, globus_byte_t ** query, globus_size_t * querysize)
       Pack a GRAM Job Request. The globus_gram_protocol_pack_job_request() function combines its
       parameters into a GRAM job request message body. The caller may frame and send the
       resulting message by calling globus_gram_protocol_post() or just frame it by calling
       globus_gram_protocol_frame_request() and send it by some other mechanism. The
       globus_gram_protocol_pack_job_request() function returns the packed message by modifying
       the query parameter to point to a new string containing the message. The caller is
       responsible for freeing that string.

       Parameters
           job_state_mask The bitwise-or of the GRAM job states which the client would like to
           register for job state change callbacks.
           callback_url A callback contact string which will be contacted when a job state change
           which matches the job_state_mask occurs. This may be NULL, if the client does not wish
           to register a callback contact with this job request. Typically, this value is
           returned in the url parameter to globus_gram_protocol_allow_attach().
           rsl An RSL string which contains the job request. This will be processed on the server
           side.
           query An output parameter which will be set to a new string containing the packed job
           request message. The caller must free this memory by calling free()
           querysize An output parameter which will be populated with the length of the job
           request message returned in query.

       Returns
           Upon success, globus_gram_protocol_pack_job_request() returns GLOBUS_SUCCESS and
           modifies the query and querysize parameters to point to the values described above.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter

   int globus_gram_protocol_pack_job_request_reply (int status, const char * job_contact,
       globus_byte_t ** reply, globus_size_t * replysize)
       Pack a GRAM reply message. The globus_gram_protocol_pack_job_request_reply() function
       combines its parameters into a GRAM reply message body. The caller may frame and send the
       resulting message by calling globus_gram_protocol_reply() or just frame it by calling
       globus_gram_protocol_frame_reply() and send it by some other mechanism. The
       globus_gram_protocol_pack_job_request_reply() function returns the packed message by
       modifying the reply parameter to point to a new string containing the message. The caller
       is responsible for freeing that string.

       Parameters
           status The job's failure code if the job failed, or 0, if the job request was
           processed successfully.
           job_contact A string containing the job contact string. This may be NULL, if the job
           request was not successful.
           reply A pointer which will be set to the packed reply string The caller must free this
           string by calling free().
           replysize A pointer which will be set to the length of the reply string.

       Returns
           Upon success, globus_gram_protocol_pack_job_request_reply() returns GLOBUS_SUCCESS and
           modifies the reply and replysize parameters to point to the values described above. If
           an error occurs, an integer error code is returned and the values pointed to by reply
           and replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_job_request_reply_with_extensions (int status, const char *
       job_contact, globus_hashtable_t * extensions, globus_byte_t ** reply, globus_size_t *
       replysize)
       Pack a GRAM reply message with extension attributes. The
       globus_gram_protocol_pack_job_request_reply_with_extensions() function combines its
       parameters into a GRAM reply message body. The caller may frame and send the resulting
       message by calling globus_gram_protocol_reply() or just frame it by calling
       globus_gram_protocol_frame_reply() and send it by some other mechanism. The
       globus_gram_protocol_pack_job_request_reply_with_extensions() function returns the packed
       message by modifying the reply parameter to point to a new string containing the message.
       The caller is responsible for freeing that string.

       Parameters
           status The job's failure code if the job failed, or 0, if the job request was
           processed successfully.
           job_contact A string containing the job contact string. This may be NULL, if the job
           request was not successful.
           extensions A pointer to a hash table keyed on a string attribute name with the hash
           values being pointers to globus_gram_protocol_extension_t structures. These will be
           encoded in the reply message after the standard attributes.
           reply A pointer which will be set to the packed reply string The caller must free this
           string by calling free().
           replysize A pointer which will be set to the length of the reply string.

       Returns
           Upon success, globus_gram_protocol_pack_job_request_reply_with_extensions() returns
           GLOBUS_SUCCESS and modifies the reply and replysize parameters to point to the values
           described above. If an error occurs, an integer error code is returned and the values
           pointed to by reply and replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_status_reply (int job_status, int failure_code, int
       job_failure_code, globus_byte_t ** reply, globus_size_t * replysize)
       Pack a GRAM query reply message. The globus_gram_protocol_pack_status_reply() function
       combines its parameters into a GRAM status reply message body. The caller may frame and
       send the resulting message by calling globus_gram_protocol_reply() or just frame it by
       calling globus_gram_protocol_frame_reply() and send it by some other mechanism. The
       globus_gram_protocol_pack_status_reply() function returns the packed message by modifying
       the reply parameter to point to a new string containing the message. The caller is
       responsible for freeing that string.

       Parameters
           job_status The job's current job state.
           failure_code The error code generated by the query. This may be GLOBUS_SUCCESS if the
           query succeeded.
           job_failure_code The error code associated with the job if it has failed. This may be
           GLOBUS_SUCCESS if the job has not failed.
           reply An output parameter which will be set to a new string containing the packed
           reply message.
           replysize An output parameter which will be set to the length of the reply message
           returned in reply.

       Returns
           Upon success, globus_gram_protocol_pack_status_reply() returns GLOBUS_SUCCESS and
           modifies the reply and replysize parameters to point to the values described above. If
           an error occurs, an integer error code is returned and the values pointed to by reply
           and replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_status_reply_with_extensions (int job_status, int failure_code,
       int job_failure_code, globus_hashtable_t * extensions, globus_byte_t ** reply,
       globus_size_t * replysize)
       Pack a GRAM query reply message with extensions. The
       globus_gram_protocol_pack_status_reply_with_extensions() function combines its parameters
       into a GRAM status reply message body. The caller may frame and send the resulting message
       by calling globus_gram_protocol_reply() or just frame it by calling
       globus_gram_protocol_frame_reply() and send it by some other mechanism. The
       globus_gram_protocol_pack_status_reply_with_extensions() function returns the packed
       message by modifying the reply parameter to point to a new string containing the message.
       The caller is responsible for freeing that string.

       Parameters
           job_status The job's current job state.
           failure_code The error code generated by the query. This may be GLOBUS_SUCCESS if the
           query succeeded.
           job_failure_code The error code associated with the job if it has failed. This may be
           GLOBUS_SUCCESS if the job has not failed.
           extensions A pointer to a hash table containing the names and values of the protocol
           extensions to add to this message.
           reply An output parameter which will be set to a new string containing the packed
           reply message.
           replysize An output parameter which will be set to the length of the reply message
           returned in reply.

       Returns
           Upon success, globus_gram_protocol_pack_status_reply_with_extensions() returns
           GLOBUS_SUCCESS and modifies the reply and replysize parameters to point to the values
           described above. If an error occurs, an integer error code is returned and the values
           pointed to by reply and replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_status_request (const char * status_request, globus_byte_t **
       query, globus_size_t * querysize)
       Pack a GRAM query message. The globus_gram_protocol_pack_status_request() function
       combines its parameters into a GRAM status query message body. The caller may frame and
       send the resulting message by calling globus_gram_protocol_post() or just frame it by
       calling globus_gram_protocol_frame_request() and send it by some other mechanism. The
       globus_gram_protocol_pack_status_request() function returns the packed message by
       modifying the query parameter to point to a new string containing the message. The caller
       is responsible for freeing that string.

       Parameters
           status_request A string containing the type of query message to send, including any
           query parameters. The valid strings supported by GRAM in GT5 are:

           • status

           • register

           • unregister

           • signal

           • renew

           • cancel

           query An output parameter which will be set to a new string containing the packed job
           query message.
           querysize An output parameter which will be set to the length of the job query message
           returned in query.

       Returns
           Upon success, globus_gram_protocol_pack_status_request() returns GLOBUS_SUCCESS and
           modifies the query and querysize parameters to point to the values described above. If
           an error occurs, an integer error code is returned and the values pointed to by query
           and querysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_status_update_message (char * job_contact, int status, int
       failure_code, globus_byte_t ** reply, globus_size_t * replysize)
       Pack a GRAM status update message. The globus_gram_protocol_pack_status_update_message()
       function combines its parameters into a GRAM status update message body. The caller may
       frame and send the resulting message by calling globus_gram_protocol_post() or just frame
       it by calling globus_gram_protocol_frame_request() and send it by some other mechanism.
       The globus_gram_protocol_pack_status_update_message() function returns the packed message
       by modifying the reply parameter to point to a new string containing the message. The
       caller is responsible for freeing that string.

       Parameters
           job_contact The job contact string associated with the job.
           status The job's current job state.
           failure_code The error associated with this job request if the status value is
           GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.
           reply An output parameter which will be set to a new string containing the packed
           status message. The caller must free this memory by calling free()
           replysize An output parameter which will be set to the length of the status message
           returned in reply.

       Returns
           Upon success, globus_gram_protocol_pack_status_update_message() returns GLOBUS_SUCCESS
           and modifies the reply and replysize parameters as described above. If an error
           occurs, an integer error code is returned and the values pointed to by reply and
           replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_status_update_message_with_extensions (char * job_contact, int
       status, int failure_code, globus_hashtable_t * extensions, globus_byte_t ** reply,
       globus_size_t * replysize)
       Pack a GRAM status update message with extensions. The
       globus_gram_protocol_pack_status_update_message_with_extensions() function combines its
       parameters into a GRAM status update message body. The caller may frame and send the
       resulting message by calling globus_gram_protocol_post() or just frame it by calling
       globus_gram_protocol_frame_request() and send it by some other mechanism. The
       globus_gram_protocol_pack_status_update_message_with_extensions() function returns the
       packed message by modifying the reply parameter to point to a new string containing the
       message. The caller is responsible for freeing that string.

       Parameters
           job_contact The job contact string associated with the job.
           status The job's current job state.
           failure_code The error associated with this job request if the status value is
           GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.
           extensions A pointer to a hash table keyed by extension attribute names with the
           values being pointers to globus_gram_protocol_extension_t structures.
           reply An output parameter which will be set to a new string containing the packed
           status message. The caller must free this memory by calling free()
           replysize An output parameter which will be set to the length of the status message
           returned in reply.

       Returns
           Upon success, globus_gram_protocol_pack_status_update_message_with_extensions()
           returns GLOBUS_SUCCESS and modifies the reply and replysize parameters as described
           above. If an error occurs, an integer error code is returned and the values pointed to
           by reply and replysize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory

   int globus_gram_protocol_pack_version_request (char ** request, size_t * requestsize)
       Pack a GRAM version request message. The globus_gram_protocol_pack_job_request() function
       creates a copy of the GRAM version request. The caller may frame and send the resulting
       message by calling globus_gram_protocol_post() or just frame it by calling
       globus_gram_protocol_frame_request() and send it by some other mechanism. The
       globus_gram_protocol_pack_version_request() function returns the packed message by
       modifying the request parameter to point to a new string containing the message. The
       caller is responsible for freeing that string.

       Parameters
           request An output parameter which will be set to a new string containing the packed
           version request message. The caller must free this memory by calling free().
           requestsize An output parameter which will be populated with the length of the version
           request message returned in query.

       Returns
           Upon success, globus_gram_protocol_pack_job_request() returns GLOBUS_SUCCESS and
           modifies the request and requestsize parameters to point to the values described
           above. If an error occurs, globus_gram_protocol_pack_version_request() returns an
           integer error code and the values pointed to by request and requestsize are undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory

Author

       Generated automatically by Doxygen for globus_gram_protocol from the source code.