~ubuntu-branches/ubuntu/oneiric/globus-gram-client/oneiric

/*
 * Copyright 1999-2006 University of Chicago
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef GLOBUS_DONT_DOCUMENT_INTERNAL
/**
 * @file gram_client.h
 *
 * This header file contains the exported client interface of 
 * the Resource Allocation Management System.
 *
 * CVS Information:
 *  $Source: /home/globdev/CVS/globus-packages/gram/client/source/globus_gram_client.h,v $
 *  $Date: 2010/02/10 11:15:20 $
 *  $Revision: 1.59.2.2 $
 *  $Author: bester $
 */
#endif

#ifndef GLOBUS_I_GRAM_CLIENT_INCLUDE
#define GLOBUS_I_GRAM_CLIENT_INCLUDE

/* Include header files */
#include "globus_common.h"
#include "globus_io.h"
#include "globus_gram_protocol_constants.h"

#ifndef EXTERN_C_BEGIN
#ifdef __cplusplus
#define EXTERN_C_BEGIN extern "C" {
#define EXTERN_C_END }
#else
#define EXTERN_C_BEGIN
#define EXTERN_C_END
#endif
#endif
 
EXTERN_C_BEGIN


/** 
 * @mainpage Resource Management Client API
 * @anchor globus_gram_client_main
 *
 * The resource management API provides function for requesting
 * that a job be started or terminated, as well as for requesting
 * information about the status of a job.
 */

/******************************************************************************
                               Type definitions
******************************************************************************/


/**
 * @defgroup globus_gram_client_callback Job state callbacks
 */

/**
 * @brief Signature for GRAM state notification callback functions
 * @ingroup globus_gram_client_callback
 *
 * @details
 * The @a 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 @a globus_gram_client_callback_allow()
 * function to create a callback contact. The contact string can be passed to
 * @a globus_gram_client_job_request() or
 * @a globus_gram_client_job_callback_register() to let the job management
 * service know to where to send information on GRAM job state changes.
 *
 * @param user_callback_arg
 *     A pointer to application-specific data.
 * @param 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 @a job_contact from a call to @a globus_gram_client_job_request()
 *     or in the @a job_contact parameter to the
 *     @a globus_gram_client_nonblocking_func_t used with
 *     @a 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.
 * @param state
 *     The new state (one of the #globus_gram_protocol_job_state_t values)
 *     of the job.
 * @param errorcode
 *     The error code if the @a state parameter is equal to
 *     GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.
 */
typedef void (* globus_gram_client_callback_func_t)(
    void *                              user_callback_arg,
    char *                              job_contact,
    int                                 state,
    int                                 errorcode);

/**
 * @brief Extensible job information structure
 * @ingroup globus_gram_client_callback
 *
 * @details
 * The @a #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 @a #globus_gram_protocol_extension_t name-value pairs.
 */
typedef struct globus_gram_client_job_info_s
{
    /**
     * Table of extension values
     */
    globus_hashtable_t                  extensions;
    /**
     * GRAM Job Contact String
     */
    char *                              job_contact;
    /**
     * GRAM Job State
     */
    int                                 job_state;
    /**
     * GRAM Error Code
     */
    int                                 protocol_error_code;
}
globus_gram_client_job_info_t;

/**
 * @brief Signature for GRAM state notification callback functions with
 * extension support
 * @ingroup globus_gram_client_callback
 *
 * @details
 * The @a #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 @a globus_gram_client_info_callback_allow()
 * function to create a callback contact that can handle extensions. The
 * contact string can be passed to
 * @a globus_gram_client_job_request() or
 * @a globus_gram_client_job_callback_register() to let the job management
 * service know to where to send information on GRAM job state changes.
 *
 * @param  user_callback_arg
 *     Application-specific callback information.
 * @param job_contact
 *     Job this information is related to
 * @param job_info
 *     Job state and extensions
 *
 * @see globus_gram_client_info_callback_allow()
 */
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);

/**
 * @brief GRAM client operation attribute
 * @ingroup globus_gram_client_attr
 *
 * @details
 * The @a #globus_gram_client_attr_t type is an opaque type describing
 * GRAM attributes. It can be accessed or modified by functions in the 
 * @ref globus_gram_client_attr documentation.
 */
typedef void * globus_gram_client_attr_t;


/**
 * @brief Default GRAM client operation attribute
 * @ingroup globus_gram_client_attr
 * @hideinitializer
 * @details
 * The @a GLOBUS_GRAM_CLIENT_NO_ATTR macro defines a constant for use
 * when a user of the GRAM client API does not want to specify any
 * non-default GRAM attributes.
 */
#define GLOBUS_GRAM_CLIENT_NO_ATTR (globus_gram_client_attr_t) NULL

/**
 * @brief Signature for callbacks signalling completion of non-blocking GRAM requests
 * @ingroup globus_gram_client_callback
 *
 * @details
 * The @a #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:
 * - @a globus_gram_client_register_job_request()
 * - @a globus_gram_client_register_job_cancel()
 * - @a globus_gram_client_register_job_status()
 * - @a globus_gram_client_register_job_refresh_credentials()
 * - @a globus_gram_client_register_job_signal()
 * - @a globus_gram_client_register_job_callback_registration()
 * - @a globus_gram_client_register_job_callback_unregistration()
 * - @a globus_gram_client_register_ping()
 * 
 * @param user_callback_arg
 *     Application-specific callback information.
 * @param operation_failure_code
 *     The result of the nonblocking operation , indicating whether the
 *     operation was processed by the job manager successfully or not.
 * @param job_contact
 *     A string containing the job contact associated with this non-blocking
 *     operation.
 * @param job_state
 *     The state (one of the #globus_gram_protocol_job_state_t
 *     values) of the job related to this non-blocking operation.
 * @param 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.
 */
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);


/**
 * @defgroup globus_gram_client_job_functions GRAM Job Functions
 */

/******************************************************************************
                              Function prototypes
******************************************************************************/
int 
globus_gram_client_callback_allow(
    globus_gram_client_callback_func_t  callback_func,
    void *                              user_callback_arg,
    char **                             callback_contact);


int
globus_gram_client_info_callback_allow(
    globus_gram_client_info_callback_func_t
                                        callback_func,
    void *                              user_callback_arg,
    char **                             callback_contact);

int
globus_gram_client_register_job_request(
    const char *                        resource_manager_contact,
    const char *                        description,
    int                                 job_state_mask,
    const char *                        callback_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int 
globus_gram_client_job_request(
    const char *                        resource_manager_contact,
    const char *                        description,
    int                                 job_state_mask,
    const char *                        callback_contact,
    char **                             job_contact);

int
globus_gram_client_register_job_request_with_info(
    const char *                        resource_manager_contact,
    const char *                        description,
    int                                 job_state_mask,
    const char *                        callback_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_info_callback_func_t
                                        callback,
    void *                              callback_arg);

int 
globus_gram_client_job_request_with_info(
    const char *                        resource_manager_contact,
    const char *                        description,
    int                                 job_state_mask,
    const char *                        callback_contact,
    char **                             job_contact,
    globus_gram_client_job_info_t *     info);

int
globus_gram_client_register_job_cancel(
    const char *                        job_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int 
globus_gram_client_job_cancel(
    const char *                        job_contact);

int
globus_gram_client_register_job_status(
    const char *                        job_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int
globus_gram_client_register_job_status_with_info(
    const char *                        job_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_info_callback_func_t
                                        info_callback,
    void *                              callback_arg);


int
globus_gram_client_job_refresh_credentials(
    char *                              job_contact,
    gss_cred_id_t                       creds);

int
globus_gram_client_register_job_refresh_credentials(
    char *                              job_contact,
    gss_cred_id_t                       creds,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int
globus_gram_client_job_status(
    const char *                        job_contact,
    int *                               job_status,
    int *                               failure_code);

int
globus_gram_client_job_status_with_info(
    const char *                        job_contact,
    globus_gram_client_job_info_t *     job_info);

int
globus_gram_client_register_job_signal(
    const char *                        job_contact,
    globus_gram_protocol_job_signal_t   signal,
    const char *                        signal_arg,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int
globus_gram_client_job_signal(
    const char *                        job_contact,
    globus_gram_protocol_job_signal_t   signal,
    const char *                        signal_arg,
    int *                               job_status,
    int *                               failure_code);


int
globus_gram_client_register_job_callback_registration(
    const char *                        job_contact,
    int                                 job_state_mask,
    const char *                        callback_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int
globus_gram_client_job_callback_register(
    const char *                        job_contact,
    int                                 job_state_mask,
    const char *                        callback_contact,
    int *                               job_status,
    int *                               failure_code);

int
globus_gram_client_register_job_callback_unregistration(
    const char *                        job_contact,
    const char *                        callback_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int
globus_gram_client_job_callback_unregister(
    const char *                        job_contact,
    const char *                        callback_contact,
    int *                               job_status,
    int *                               failure_code);

int 
globus_gram_client_callback_disallow(
    char *                              callback_contact);

int 
globus_gram_client_job_contact_free(
    char *                              job_contact);

/**
 * @defgroup globus_gram_client Other GRAM Client Functions
 */
const char *
globus_gram_client_error_string(
    int                                 error_code);

int
globus_gram_client_version(void);

int
globus_gram_client_set_credentials(gss_cred_id_t new_credentials);

int 
globus_gram_client_ping(
    const char *                        resource_manager_contact);

int 
globus_gram_client_register_ping(
    const char *                        resource_manager_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_nonblocking_func_t
                                        register_callback,
    void *                              register_callback_arg);

int 
globus_gram_client_get_jobmanager_version(
    const char *                        resource_manager_contact,
    globus_hashtable_t *                extensions);

int 
globus_gram_client_register_get_jobmanager_version(
    const char *                        resource_manager_contact,
    globus_gram_client_attr_t           attr,
    globus_gram_client_info_callback_func_t
                                        info_callback,
    void *                              callback_arg);

void
globus_gram_client_debug(void);

/**
 * @defgroup globus_gram_client_attr GRAM Client Attribute Functions
 */
int
globus_gram_client_attr_init(
    globus_gram_client_attr_t *         attr);
int
globus_gram_client_attr_destroy(
    globus_gram_client_attr_t *         attr);

int
globus_gram_client_attr_set_credential(
    globus_gram_client_attr_t           attr,
    gss_cred_id_t                       credential);

int
globus_gram_client_attr_get_credential(
    globus_gram_client_attr_t           attr,
    gss_cred_id_t *                     credential);

int
globus_gram_client_attr_set_delegation_mode(
    globus_gram_client_attr_t           attr,
    globus_io_secure_delegation_mode_t  mode);

int
globus_gram_client_attr_get_delegation_mode(
    globus_gram_client_attr_t           attr,
    globus_io_secure_delegation_mode_t *mode);

void
globus_gram_client_job_info_destroy(
    globus_gram_client_job_info_t *     info);

#define GLOBUS_GRAM_CLIENT_MODULE (&globus_gram_client_module)

extern globus_module_descriptor_t       globus_gram_client_module;

EXTERN_C_END
#endif /* GLOBUS_I_GRAM_CLIENT_INCLUDE */