.TH "globus_gram_client_callback" 3 "Version 14.6" "globus_gram_client" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_gram_client_callback \- Job state callbacks
.PP
 \- Job state callbacks\&.  

.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBglobus_gram_client_job_info_s\fP"
.br
.RI "Extensible job information structure\&. "
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef void(* \fBglobus_gram_client_callback_func_t\fP) (void *user_callback_arg, char *job_contact, int state, int errorcode)"
.br
.RI "Signature for GRAM state notification callback functions\&. "
.ti -1c
.RI "typedef struct \fBglobus_gram_client_job_info_s\fP \fBglobus_gram_client_job_info_t\fP"
.br
.RI "Extensible job information structure\&. "
.ti -1c
.RI "typedef void(* \fBglobus_gram_client_info_callback_func_t\fP) (void *user_callback_arg, const char *job_contact, \fBglobus_gram_client_job_info_t\fP *job_info)"
.br
.RI "Signature for GRAM state notification callback functions with extension support\&. "
.ti -1c
.RI "typedef void(* \fBglobus_gram_client_nonblocking_func_t\fP) (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)"
.br
.RI "Signature for callbacks signalling completion of non-blocking GRAM requests\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBglobus_gram_client_callback_allow\fP (\fBglobus_gram_client_callback_func_t\fP callback_func, void *user_callback_arg, char **callback_contact)"
.br
.RI "Begin listening for job state change callbacks\&. "
.ti -1c
.RI "int \fBglobus_gram_client_info_callback_allow\fP (\fBglobus_gram_client_info_callback_func_t\fP callback_func, void *user_callback_arg, char **callback_contact)"
.br
.RI "Begin listening for job state change callbacks\&. "
.ti -1c
.RI "int \fBglobus_gram_client_callback_disallow\fP (char *callback_contact)"
.br
.RI "Stop listening for job state change callbacks\&. "
.in -1c
.SH "Detailed Description"
.PP 
Job state callbacks\&. 


.SH "Typedef Documentation"
.PP 
.SS "typedef void(* globus_gram_client_callback_func_t) (void *user_callback_arg, char *job_contact, int state, int errorcode)"

.PP
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 \fBglobus_gram_client_callback_allow()\fP function to create a callback contact\&. The contact string can be passed to \fBglobus_gram_client_job_request()\fP or \fBglobus_gram_client_job_callback_register()\fP to let the job management service know to where to send information on GRAM job state changes\&.
.PP
\fBParameters\fP
.RS 4
\fIuser_callback_arg\fP A pointer to application-specific data\&. 
.br
\fIjob_contact\fP 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 \fIjob_contact\fP from a call to \fBglobus_gram_client_job_request()\fP or in the \fIjob_contact\fP parameter to the globus_gram_client_nonblocking_func_t used with \fBglobus_gram_client_register_job_request()\fP\&. However, in some cases, the port number in the job contact URL may change if the job manager is restarted\&. 
.br
\fIstate\fP The new state (one of the #globus_gram_protocol_job_state_t values) of the job\&. 
.br
\fIerrorcode\fP The error code if the \fIstate\fP parameter is equal to GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED\&. 
.RE
.PP

.SS "typedef void(* globus_gram_client_info_callback_func_t) (void *user_callback_arg, const char *job_contact, \fBglobus_gram_client_job_info_t\fP *job_info)"

.PP
Signature for GRAM state notification callback functions with extension support\&. The \fBglobus_gram_client_info_callback_func_t\fP 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 \fBglobus_gram_client_info_callback_allow()\fP function to create a callback contact that can handle extensions\&. The contact string can be passed to \fBglobus_gram_client_job_request()\fP or \fBglobus_gram_client_job_callback_register()\fP to let the job management service know to where to send information on GRAM job state changes\&.
.PP
\fBParameters\fP
.RS 4
\fIuser_callback_arg\fP Application-specific callback information\&. 
.br
\fIjob_contact\fP Job this information is related to 
.br
\fIjob_info\fP Job state and extensions
.RE
.PP
\fBSee also\fP
.RS 4
\fBglobus_gram_client_info_callback_allow()\fP 
.RE
.PP

.SS "typedef struct \fBglobus_gram_client_job_info_s\fP \fBglobus_gram_client_job_info_t\fP"

.PP
Extensible job information structure\&. The \fBglobus_gram_client_job_info_t\fP 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\&. 
.SS "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)"

.PP
Signature for callbacks signalling completion of non-blocking GRAM requests\&. The \fBglobus_gram_client_info_callback_func_t\fP 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:
.IP "\(bu" 2
\fBglobus_gram_client_register_job_request()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_cancel()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_status()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_refresh_credentials()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_signal()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_callback_registration()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_job_callback_unregistration()\fP
.IP "\(bu" 2
\fBglobus_gram_client_register_ping()\fP
.PP
.PP
\fBParameters\fP
.RS 4
\fIuser_callback_arg\fP Application-specific callback information\&. 
.br
\fIoperation_failure_code\fP The result of the nonblocking operation , indicating whether the operation was processed by the job manager successfully or not\&. 
.br
\fIjob_contact\fP A string containing the job contact associated with this non-blocking operation\&. 
.br
\fIjob_state\fP The state (one of the #globus_gram_protocol_job_state_t values) of the job related to this non-blocking operation\&. 
.br
\fIjob_failure_code\fP The error code of the job request if the job_state parameter is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED\&. Otherwise, its value is undefined\&. 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "int globus_gram_client_callback_allow (\fBglobus_gram_client_callback_func_t\fP callback_func, void * user_callback_arg, char ** callback_contact)"

.PP
Begin listening for job state change callbacks\&. The \fBglobus_gram_client_callback_allow()\fP 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 \fBglobus_gram_client_job_request()\fP or globus_gram_client_callback_register() family of functions\&.
.PP
\fBParameters\fP
.RS 4
\fIcallback_func\fP A pointer to a function to call when a new job state update is received\&. 
.br
\fIuser_callback_arg\fP A pointer to application-specific data which is passed to the function pointed to by \fIcallback_func\fP as its \fIuser_callback_arg\fP parameter\&. 
.br
\fIcallback_contact\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
Upon success, \fBglobus_gram_client_callback_allow()\fP returns \fIGLOBUS_SUCCESS\fP opens a TCP port to accept job state updates and modifies the value pointed to by the \fIcallback_contact\fP parameter as described above\&. If an error occurs, \fBglobus_gram_client_callback_allow()\fP returns an integer error code\&.
.RE
.PP
\fBReturn values\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER\fP Null parameter 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST\fP Invalid request 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED\fP Out of memory 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES\fP No resources 
.RE
.PP

.SS "int globus_gram_client_callback_disallow (char * callback_contact)"

.PP
Stop listening for job state change callbacks\&. The \fBglobus_gram_client_callback_disallow()\fP 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\&.
.PP
This function can only be used to disable a callback contact created in the current process\&.
.PP
\fBParameters\fP
.RS 4
\fIcallback_contact\fP A callback contact string that refers to a protocol handler in the current process\&.
.RE
.PP
\fBReturns\fP
.RS 4
Upon success, \fBglobus_gram_client_callback_disallow()\fP returns \fIGLOBUS_SUCCESS\fP, closes the network port associated with the \fIcallback_contact\fP parameter and stops further callbacks from occurring\&. If an error occurs, \fBglobus_gram_client_callback_disallow()\fP returns an integer error code\&.
.RE
.PP
\fBReturn values\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND\fP Callback not found 
.RE
.PP

.SS "int globus_gram_client_info_callback_allow (\fBglobus_gram_client_info_callback_func_t\fP callback_func, void * user_callback_arg, char ** callback_contact)"

.PP
Begin listening for job state change callbacks\&. The \fBglobus_gram_client_info_callback_allow()\fP 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 \fBglobus_gram_client_job_request_with_info()\fP or \fBglobus_gram_client_register_job_status_with_info()\fP family of functions\&.
.PP
\fBParameters\fP
.RS 4
\fIcallback_func\fP 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\&. 
.br
\fIuser_callback_arg\fP A pointer to application-specific data which is passed to the function pointed to by \fIcallback_func\fP as its \fIuser_callback_arg\fP parameter\&. 
.br
\fIcallback_contact\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
Upon success, \fBglobus_gram_client_callback_allow()\fP returns \fIGLOBUS_SUCCESS\fP opens a TCP port to accept job state updates and modifies the value pointed to by the \fIcallback_contact\fP parameter as described above\&. If an error occurs, \fBglobus_gram_client_callback_allow()\fP returns an integer error code\&.
.RE
.PP
\fBReturn values\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER\fP Null parameter 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST\fP Invalid request 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED\fP Out of memory 
.br
\fIGLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES\fP No resources 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_gram_client from the source code\&.