/* * 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. */ #if !defined(GLOBUS_GRAM_PROTOCOL_H) #define GLOBUS_GRAM_PROTOCOL_H /** * @file globus_gram_protocol.h * @brief GRAM Protocol API */ #ifndef GLOBUS_GLOBAL_DOCUMENT_SET /** * @mainpage Globus GRAM Protocol * @copydoc globus_gram_protocol */ #endif /** * @defgroup globus_gram_protocol GRAM Protocol * @brief GRAM Protocol * * @details * The Globus GRAM Protocol Library implements the GRAM protocol. It is used * by the GRAM Client and GRAM Job Manager. It provides the constants used * by in the sending and receiving of GRAM messages. It also provides * functions to encode GRAM requests and replies, and to send and receive * the GRAM queries. * * - @ref globus_gram_protocol_functions "GRAM Protocol Functions" * - @ref globus_gram_protocol_job_state_t "Job States" * - @ref globus_gram_protocol_job_signal_t "Signals" * - @ref globus_gram_protocol_error_t "GRAM Errors" * - @ref globus_gram_protocol "GRAM Protocol Message Format" */ #include "globus_io.h" #include "globus_gram_protocol_constants.h" #ifdef __cplusplus extern "C" { #endif enum { GLOBUS_GRAM_PROTOCOL_VERSION = 2 }; enum { GLOBUS_GRAM_PROTOCOL_MAX_MSG_SIZE = 64000 }; enum { GLOBUS_GRAM_PROTOCOL_PARAM_SIZE = 1024 }; /** * @typedef globus_gram_protocol_handle_t * @brief Unique GRAM protocol identifier * @ingroup globus_gram_protocol_io * * @details * The @a #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. */ typedef unsigned long globus_gram_protocol_handle_t; /** * @typedef globus_gram_protocol_extension_t * @brief GRAM protocol extension attribute-value pair * @ingroup globus_gram_protocol_io * * @details * The @a globus_gram_protocol_extension_t data type contains an attribute * value pair that represents an extension to the GRAM2 protocol. */ typedef struct globus_gram_protocol_hash_entry_s { /** Name of the extension attribute */ char * attribute; /** Value of the extension attribute */ char * value; } globus_gram_protocol_extension_t; typedef void (*globus_gram_protocol_callback_t)( void * arg, globus_gram_protocol_handle_t handle, globus_byte_t * message, globus_size_t msgsize, int errorcode, char * uri); typedef void (*globus_gram_protocol_delegation_callback_t)( void * arg, globus_gram_protocol_handle_t handle, gss_cred_id_t credential, int errorcode); #define GLOBUS_GRAM_PROTOCOL_MODULE (&globus_i_gram_protocol_module) extern globus_module_descriptor_t globus_i_gram_protocol_module; extern gss_cred_id_t globus_i_gram_protocol_credential; /* * creates a default set of TCP attributes (authentication with self, SSL * wrappers around messages) */ int globus_gram_protocol_setup_attr( globus_io_attr_t * attr); /* * authorizes the remote party if the remote party is the same as the * local party */ globus_bool_t globus_gram_protocol_authorize_self( gss_ctx_id_t context); /* * replaces all credentials used in this module with the given ones */ int globus_gram_protocol_set_credentials(gss_cred_id_t new_credentials); /* * sets up and registers a listener. returns port and host. user_ptr * must contain the read callback to be used. */ int globus_gram_protocol_allow_attach( char ** url, globus_gram_protocol_callback_t callback, void * callback_arg); /* * kills the listener at the specified URL. */ int globus_gram_protocol_callback_disallow( char * url); /* Frame and send a GRAM protocol message. */ 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); /* Frame and send a GRAM protocol message, following up an ok reply with * a GSSAPI delegation handshake. */ 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); /* Frame and send a 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); /* Frame and send a GRAM protocol reply indicating that we will * accept a delegated credential now. Call back when the delegation * is completed. * * After delegation is complete, the user must call * globus_gram_protocol_reply to indicate the status after the delegation. */ int globus_gram_protocol_accept_delegation( globus_gram_protocol_handle_t handle, gss_OID_set restriction_oids, gss_buffer_set_t restriction_bufers, OM_uint32 req_flags, OM_uint32 time_req, globus_gram_protocol_delegation_callback_t callback, void * arg); /* Frame a GRAM protocol message */ int globus_gram_protocol_frame_request( const char * url, const globus_byte_t * msg, globus_size_t msgsize, globus_byte_t ** framedmsg, globus_size_t * framedsize); /* Frame a GRAM protocol reply */ int globus_gram_protocol_frame_reply( int code, const globus_byte_t * msg, globus_size_t msgsize, globus_byte_t ** framedmsg, globus_size_t * framedsize); /************************ "HTTP" pack/unpack 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); int globus_gram_protocol_unpack_job_request( const globus_byte_t * query, globus_size_t querysize, int * job_state_mask, char ** callback_url, char ** description); int globus_gram_protocol_pack_job_request_reply( int status, const char * job_contact, /* may be null */ globus_byte_t ** reply, globus_size_t * replysize); int globus_gram_protocol_unpack_job_request_reply( const globus_byte_t * reply, globus_size_t replysize, int * status, char ** job_contact); int globus_gram_protocol_pack_job_request_reply_with_extensions( int status, const char * job_contact, /* may be null */ globus_hashtable_t * extensions, globus_byte_t ** reply, globus_size_t * replysize); int globus_gram_protocol_unpack_job_request_reply_with_extensions( const globus_byte_t * reply, globus_size_t replysize, int * status, char ** job_contact, globus_hashtable_t * extensions); int globus_gram_protocol_pack_status_request( const char * status_request, globus_byte_t ** query, globus_size_t * querysize); int globus_gram_protocol_unpack_status_request( const globus_byte_t * query, globus_size_t querysize, char ** status_requst); 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); 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); int globus_gram_protocol_unpack_status_reply( const globus_byte_t * reply, globus_size_t replysize, int * job_status, int * failure_code, int * job_failure_code); int globus_gram_protocol_unpack_status_reply_with_extensions( const globus_byte_t * reply, globus_size_t replysize, globus_hashtable_t * 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); int globus_gram_protocol_unpack_status_update_message( const globus_byte_t * reply, globus_size_t replysize, char ** job_contact, int * status, int * failure_code); 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); int globus_gram_protocol_unpack_status_update_message_with_extensions( const globus_byte_t * reply, globus_size_t replysize, globus_hashtable_t * message_hash); int globus_gram_protocol_unpack_message( const char * message, size_t message_length, globus_hashtable_t * message_attributes); int globus_gram_protocol_pack_version_request( char ** request, size_t * requestsize); void globus_gram_protocol_hash_destroy( globus_hashtable_t * message_hash); globus_gram_protocol_extension_t * globus_gram_protocol_create_extension( const char * attribute, const char * format, ...); int globus_gram_protocol_get_sec_context( globus_gram_protocol_handle_t handle, gss_ctx_id_t * context); const char * globus_gram_protocol_error_string(int error_code); /* To be used only by the GRAM client API */ void globus_gram_protocol_error_7_hack_replace_message(const char * message); void globus_gram_protocol_error_10_hack_replace_message(const char * message); /* * RSL Parameters */ #define GLOBUS_GRAM_PROTOCOL_EXECUTABLE_PARAM "executable" #define GLOBUS_GRAM_PROTOCOL_ARGUMENTS_PARAM "arguments" #define GLOBUS_GRAM_PROTOCOL_ENVIRONMENT_PARAM "environment" #define GLOBUS_GRAM_PROTOCOL_DIR_PARAM "directory" #define GLOBUS_GRAM_PROTOCOL_COUNT_PARAM "count" #define GLOBUS_GRAM_PROTOCOL_STDIN_PARAM "stdin" #define GLOBUS_GRAM_PROTOCOL_STDOUT_PARAM "stdout" #define GLOBUS_GRAM_PROTOCOL_STDERR_PARAM "stderr" #define GLOBUS_GRAM_PROTOCOL_MAX_WALL_TIME_PARAM "maxwalltime" #define GLOBUS_GRAM_PROTOCOL_MAX_CPU_TIME_PARAM "maxcputime" #define GLOBUS_GRAM_PROTOCOL_MAX_TIME_PARAM "maxtime" #define GLOBUS_GRAM_PROTOCOL_PARADYN_PARAM "paradyn" #define GLOBUS_GRAM_PROTOCOL_JOB_TYPE_PARAM "jobtype" #define GLOBUS_GRAM_PROTOCOL_MYJOB_PARAM "grammyjob" #define GLOBUS_GRAM_PROTOCOL_QUEUE_PARAM "queue" #define GLOBUS_GRAM_PROTOCOL_PROJECT_PARAM "project" #define GLOBUS_GRAM_PROTOCOL_HOST_COUNT_PARAM "hostcount" #define GLOBUS_GRAM_PROTOCOL_DRY_RUN_PARAM "dryrun" #define GLOBUS_GRAM_PROTOCOL_MIN_MEMORY_PARAM "minmemory" #define GLOBUS_GRAM_PROTOCOL_MAX_MEMORY_PARAM "maxmemory" #define GLOBUS_GRAM_PROTOCOL_START_TIME_PARAM "starttime" #define GLOBUS_GRAM_PROTOCOL_RESERVATION_HANDLE_PARAM "reservationhandle" #define GLOBUS_GRAM_PROTOCOL_STDOUT_POSITION_PARAM "stdoutposition" #define GLOBUS_GRAM_PROTOCOL_STDERR_POSITION_PARAM "stderrposition" #define GLOBUS_GRAM_PROTOCOL_SAVE_STATE_PARAM "savestate" #define GLOBUS_GRAM_PROTOCOL_RESTART_PARAM "restart" #define GLOBUS_GRAM_PROTOCOL_TWO_PHASE_COMMIT_PARAM "twophase" #define GLOBUS_GRAM_PROTOCOL_REMOTE_IO_URL_PARAM "remoteiourl" #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_IN_PARAM "filestagein" #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_IN_SHARED_PARAM "filestageinshared" #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_OUT_PARAM "filestageout" #define GLOBUS_GRAM_PROTOCOL_FILE_CLEANUP_PARAM "filecleanup" #define GLOBUS_GRAM_PROTOCOL_SCRATCHDIR_PARAM "scratchdir" #define GLOBUS_GRAM_PROTOCOL_GASS_CACHE_PARAM "gasscache" #define GLOBUS_GRAM_PROTOCOL_PROXY_TIMEOUT_PARAM "proxytimeout" #define GLOBUS_GRAM_PROTOCOL_USER_NAME "username" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDIN "/dev/null" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDOUT "/dev/null" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDERR "/dev/null" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_MYJOB "collective" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_JOBTYPE "multiple" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_DRYRUN "no" #define GLOBUS_GRAM_PROTOCOL_DEFAULT_START_TIME "none" #ifdef __cplusplus } #endif #endif