NAME

       globus_gram_client_callback - Job state callbacks

        - Job state callbacks.

SYNOPSIS

   Data Structures
       struct globus_gram_client_job_info_s
           Extensible job information structure.

   Typedefs
       typedef void(* globus_gram_client_callback_func_t) (void *user_callback_arg, char
           *job_contact, int state, int errorcode)
           Signature for GRAM state notification callback functions.
       typedef struct globus_gram_client_job_info_s globus_gram_client_job_info_t
           Extensible job information structure.
       typedef void(* globus_gram_client_info_callback_func_t) (void *user_callback_arg, const
           char *job_contact, globus_gram_client_job_info_t *job_info)
           Signature for GRAM state notification callback functions with extension support.
       typedef void(* globus_gram_client_nonblocking_func_t) (void *user_callback_arg,
           globus_gram_protocol_error_t operation_failure_code, const char *job_contact,
           globus_gram_protocol_job_state_t job_state, globus_gram_protocol_error_t
           job_failure_code)
           Signature for callbacks signalling completion of non-blocking GRAM requests.

   Functions
       int globus_gram_client_callback_allow (globus_gram_client_callback_func_t callback_func,
           void *user_callback_arg, char **callback_contact)
           Begin listening for job state change callbacks.
       int globus_gram_client_info_callback_allow (globus_gram_client_info_callback_func_t
           callback_func, void *user_callback_arg, char **callback_contact)
           Begin listening for job state change callbacks.
       int globus_gram_client_callback_disallow (char *callback_contact)
           Stop listening for job state change callbacks.

Detailed Description

       Job state callbacks.

Typedef Documentation

   typedef void(* globus_gram_client_callback_func_t) (void *user_callback_arg, char
       *job_contact, int state, int errorcode)
       Signature for GRAM state notification callback functions. The
       globus_gram_client_callback_func_t type describes the function signature for job state
       callbacks. A pointer to a function of this type is passed to the
       globus_gram_client_callback_allow() function to create a callback contact. The contact
       string can be passed to globus_gram_client_job_request() or
       globus_gram_client_job_callback_register() to let the job management service know to where
       to send information on GRAM job state changes.

       Parameters
           user_callback_arg A pointer to application-specific data.
           job_contact A string containing the job contact. This string indicates which job this
           callback is referring to. It should in most cases match the return value job_contact
           from a call to globus_gram_client_job_request() or in the job_contact parameter to the
           globus_gram_client_nonblocking_func_t used with
           globus_gram_client_register_job_request(). However, in some cases, the port number in
           the job contact URL may change if the job manager is restarted.
           state The new state (one of the #globus_gram_protocol_job_state_t values) of the job.
           errorcode The error code if the state parameter is equal to
           GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.

   typedef void(* globus_gram_client_info_callback_func_t) (void *user_callback_arg, const char
       *job_contact, globus_gram_client_job_info_t *job_info)
       Signature for GRAM state notification callback functions with extension support. The
       globus_gram_client_info_callback_func_t type describes the function signature for job
       state callbacks that carry any GRAM protocol extensions beyond the set used in GRAM2. A
       pointer to a function of this type is passed to the
       globus_gram_client_info_callback_allow() function to create a callback contact that can
       handle extensions. The contact string can be passed to globus_gram_client_job_request() or
       globus_gram_client_job_callback_register() to let the job management service know to where
       to send information on GRAM job state changes.

       Parameters
           user_callback_arg Application-specific callback information.
           job_contact Job this information is related to
           job_info Job state and extensions

       See also
           globus_gram_client_info_callback_allow()

   typedef struct globus_gram_client_job_info_s globus_gram_client_job_info_t
       Extensible job information structure. The globus_gram_client_job_info_t data type is used
       to pass protocol extensions along with the standard job status information included in the
       GRAM2 protocol. This structure contains the information returned in job state callbacks
       plus a hash table of extension entries that contain #globus_gram_protocol_extension_t
       name-value pairs.

   typedef void(* globus_gram_client_nonblocking_func_t) (void *user_callback_arg,
       globus_gram_protocol_error_t operation_failure_code, const char *job_contact,
       globus_gram_protocol_job_state_t job_state, globus_gram_protocol_error_t job_failure_code)
       Signature for callbacks signalling completion of non-blocking GRAM requests. The
       globus_gram_client_info_callback_func_t type describes the function signature for
       callbacks which indicate that a GRAM operation has completed. A pointer to a function of
       this type is passed to the following functions:

       • globus_gram_client_register_job_request()

       • globus_gram_client_register_job_cancel()

       • globus_gram_client_register_job_status()

       • globus_gram_client_register_job_refresh_credentials()

       • globus_gram_client_register_job_signal()

       • globus_gram_client_register_job_callback_registration()

       • globus_gram_client_register_job_callback_unregistration()

       • globus_gram_client_register_ping()

       Parameters
           user_callback_arg Application-specific callback information.
           operation_failure_code The result of the nonblocking operation , indicating whether
           the operation was processed by the job manager successfully or not.
           job_contact A string containing the job contact associated with this non-blocking
           operation.
           job_state The state (one of the #globus_gram_protocol_job_state_t values) of the job
           related to this non-blocking operation.
           job_failure_code The error code of the job request if the job_state parameter is
           GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. Otherwise, its value is undefined.

Function Documentation

   int globus_gram_client_callback_allow (globus_gram_client_callback_func_t callback_func, void
       * user_callback_arg, char ** callback_contact)
       Begin listening for job state change callbacks. The globus_gram_client_callback_allow()
       function initializes a GRAM protocol service in the current process which will process job
       state updates from GRAM Job Managers. The URL to contact this service is returned and may
       be used with the globus_gram_client_job_request() or
       globus_gram_client_callback_register() family of functions.

       Parameters
           callback_func A pointer to a function to call when a new job state update is received.
           user_callback_arg A pointer to application-specific data which is passed to the
           function pointed to by callback_func as its user_callback_arg parameter.
           callback_contact An output parameter that points to a string that will be allocated
           and set to the URL that the GRAM callback listener is waiting on.

       Returns
           Upon success, globus_gram_client_callback_allow() returns GLOBUS_SUCCESS opens a TCP
           port to accept job state updates and modifies the value pointed to by the
           callback_contact parameter as described above. If an error occurs,
           globus_gram_client_callback_allow() returns an integer error code.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter
           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

   int globus_gram_client_callback_disallow (char * callback_contact)
       Stop listening for job state change callbacks. The globus_gram_client_callback_disallow()
       function stops the GRAM protocol handler associated with a callback contact from receiving
       further messages. After this function returns, no further callbacks for this contact will
       be called. Furthermore, the network port associated with the protocol handler will be
       released.

       This function can only be used to disable a callback contact created in the current
       process.

       Parameters
           callback_contact A callback contact string that refers to a protocol handler in the
           current process.

       Returns
           Upon success, globus_gram_client_callback_disallow() returns GLOBUS_SUCCESS, closes
           the network port associated with the callback_contact parameter and stops further
           callbacks from occurring. If an error occurs, globus_gram_client_callback_disallow()
           returns an integer error code.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND Callback not found

   int globus_gram_client_info_callback_allow (globus_gram_client_info_callback_func_t
       callback_func, void * user_callback_arg, char ** callback_contact)
       Begin listening for job state change callbacks. The
       globus_gram_client_info_callback_allow() function initializes a GRAM protocol service in
       the current process which will process job state updates from GRAM Job Managers. The URL
       to contact this service is returned and may be used with the
       globus_gram_client_job_request_with_info() or
       globus_gram_client_register_job_status_with_info() family of functions.

       Parameters
           callback_func A pointer to a function to call when a new job state update is received.
           The function signature of this parameter supports GRAM protocol extensions.
           user_callback_arg A pointer to application-specific data which is passed to the
           function pointed to by callback_func as its user_callback_arg parameter.
           callback_contact An output parameter that points to a string that will be allocated
           and set to the URL that the GRAM callback listener is waiting on.

       Returns
           Upon success, globus_gram_client_callback_allow() returns GLOBUS_SUCCESS opens a TCP
           port to accept job state updates and modifies the value pointed to by the
           callback_contact parameter as described above. If an error occurs,
           globus_gram_client_callback_allow() returns an integer error code.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter
           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

Author

       Generated automatically by Doxygen for globus_gram_client from the source code.