Grid Community Toolkit  6.2.1629922860 (tag: v6.2.20210826)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
globus_gram_protocol.h
Go to the documentation of this file.
1 /*
2  * Copyright 1999-2006 University of Chicago
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #if !defined(GLOBUS_GRAM_PROTOCOL_H)
18 #define GLOBUS_GRAM_PROTOCOL_H
19 
25 #ifndef GLOBUS_GLOBAL_DOCUMENT_SET
26 
30 #endif
31 
50 #include "globus_io.h"
52 
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56 
57 enum { GLOBUS_GRAM_PROTOCOL_VERSION = 2 };
58 enum { GLOBUS_GRAM_PROTOCOL_MAX_MSG_SIZE = 64000 };
59 enum { GLOBUS_GRAM_PROTOCOL_PARAM_SIZE = 1024 };
73 typedef unsigned long globus_gram_protocol_handle_t;
74 
84 typedef struct globus_gram_protocol_hash_entry_s
85 {
87  char * attribute;
89  char * value;
90 }
92 
93 typedef void (*globus_gram_protocol_callback_t)(
94  void * arg,
95  globus_gram_protocol_handle_t handle,
96  globus_byte_t * message,
97  globus_size_t msgsize,
98  int errorcode,
99  char * uri);
100 
101 typedef void (*globus_gram_protocol_delegation_callback_t)(
102  void * arg,
103  globus_gram_protocol_handle_t handle,
104  gss_cred_id_t credential,
105  int errorcode);
106 #define GLOBUS_GRAM_PROTOCOL_MODULE (&globus_i_gram_protocol_module)
107 
108 extern globus_module_descriptor_t globus_i_gram_protocol_module;
109 
110 extern gss_cred_id_t globus_i_gram_protocol_credential;
111 
112 /*
113  * creates a default set of TCP attributes (authentication with self, SSL
114  * wrappers around messages)
115  */
116 int
118  globus_io_attr_t * attr);
119 
120 
121 /*
122  * authorizes the remote party if the remote party is the same as the
123  * local party
124  */
125 
128  gss_ctx_id_t context);
129 
130 
131 /*
132  * replaces all credentials used in this module with the given ones
133  */
134 int
135 globus_gram_protocol_set_credentials(gss_cred_id_t new_credentials);
136 
137 
138 /*
139  * sets up and registers a listener. returns port and host. user_ptr
140  * must contain the read callback to be used.
141  */
142 int
144  char ** url,
145  globus_gram_protocol_callback_t callback,
146  void * callback_arg);
147 
148 /*
149  * kills the listener at the specified URL.
150  */
151 int
153  char * url);
154 
155 
156 /* Frame and send a GRAM protocol message. */
157 int
159  const char * url,
160  globus_gram_protocol_handle_t * handle,
161  globus_io_attr_t * attr,
162  globus_byte_t * message,
163  globus_size_t message_size,
164  globus_gram_protocol_callback_t callback,
165  void * callback_arg);
166 
167 /* Frame and send a GRAM protocol message, following up an ok reply with
168  * a GSSAPI delegation handshake.
169  */
170 int
172  const char * url,
173  globus_gram_protocol_handle_t * handle,
174  globus_io_attr_t * attr,
175  globus_byte_t * message,
176  globus_size_t message_size,
177  gss_cred_id_t cred_handle,
178  gss_OID_set restriction_oids,
179  gss_buffer_set_t restriction_buffers,
180  OM_uint32 req_flags,
181  OM_uint32 time_req,
182  globus_gram_protocol_callback_t callback,
183  void * callback_arg);
184 
185 /* Frame and send a GRAM protocol reply. */
186 int
188  globus_gram_protocol_handle_t handle,
189  int code,
190  globus_byte_t * message,
191  globus_size_t message_size);
192 
193 /* Frame and send a GRAM protocol reply indicating that we will
194  * accept a delegated credential now. Call back when the delegation
195  * is completed.
196  *
197  * After delegation is complete, the user must call
198  * globus_gram_protocol_reply to indicate the status after the delegation.
199  */
200 int
202  globus_gram_protocol_handle_t handle,
203  gss_OID_set restriction_oids,
204  gss_buffer_set_t restriction_bufers,
205  OM_uint32 req_flags,
206  OM_uint32 time_req,
207  globus_gram_protocol_delegation_callback_t
208  callback,
209  void * arg);
210 /* Frame a GRAM protocol message */
211 int
213  const char * url,
214  const globus_byte_t * msg,
215  globus_size_t msgsize,
216  globus_byte_t ** framedmsg,
217  globus_size_t * framedsize);
218 
219 /* Frame a GRAM protocol reply */
220 int
222  int code,
223  const globus_byte_t * msg,
224  globus_size_t msgsize,
225  globus_byte_t ** framedmsg,
226  globus_size_t * framedsize);
227 
228 /************************ "HTTP" pack/unpack functions *********************/
229 
230 int
232  int job_state_mask,
233  const char * callback_url,
234  const char * rsl,
235  globus_byte_t ** query,
236  globus_size_t * querysize);
237 
238 
239 int
241  const globus_byte_t * query,
242  globus_size_t querysize,
243  int * job_state_mask,
244  char ** callback_url,
245  char ** description);
246 
247 
248 int
250  int status,
251  const char * job_contact, /* may be null */
252  globus_byte_t ** reply,
253  globus_size_t * replysize);
254 
255 
256 int
258  const globus_byte_t * reply,
259  globus_size_t replysize,
260  int * status,
261  char ** job_contact);
262 
263 int
265  int status,
266  const char * job_contact, /* may be null */
267  globus_hashtable_t * extensions,
268  globus_byte_t ** reply,
269  globus_size_t * replysize);
270 
271 
272 int
274  const globus_byte_t * reply,
275  globus_size_t replysize,
276  int * status,
277  char ** job_contact,
278  globus_hashtable_t * extensions);
279 
280 int
282  const char * status_request,
283  globus_byte_t ** query,
284  globus_size_t * querysize);
285 
286 
287 int
289  const globus_byte_t * query,
290  globus_size_t querysize,
291  char ** status_requst);
292 
293 
294 int
296  int job_status,
297  int failure_code,
298  int job_failure_code,
299  globus_byte_t ** reply,
300  globus_size_t * replysize);
301 
302 int
304  int job_status,
305  int failure_code,
306  int job_failure_code,
307  globus_hashtable_t * extensions,
308  globus_byte_t ** reply,
309  globus_size_t * replysize);
310 
311 int
313  const globus_byte_t * reply,
314  globus_size_t replysize,
315  int * job_status,
316  int * failure_code,
317  int * job_failure_code);
318 
319 int
321  const globus_byte_t * reply,
322  globus_size_t replysize,
323  globus_hashtable_t * extensions);
324 
325 int
327  char * job_contact,
328  int status,
329  int failure_code,
330  globus_byte_t ** reply,
331  globus_size_t * replysize);
332 
333 
334 int
336  const globus_byte_t * reply,
337  globus_size_t replysize,
338  char ** job_contact,
339  int * status,
340  int * failure_code);
341 
342 int
344  char * job_contact,
345  int status,
346  int failure_code,
347  globus_hashtable_t * extensions,
348  globus_byte_t ** reply,
349  globus_size_t * replysize);
350 
351 int
353  const globus_byte_t * reply,
354  globus_size_t replysize,
355  globus_hashtable_t * message_hash);
356 
357 int
358 globus_gram_protocol_unpack_message(
359  const char * message,
360  size_t message_length,
361  globus_hashtable_t * message_attributes);
362 
363 int
365  char ** request,
366  size_t * requestsize);
367 
368 void
370  globus_hashtable_t * message_hash);
371 
374  const char * attribute,
375  const char * format,
376  ...);
377 
378 int
380  globus_gram_protocol_handle_t handle,
381  gss_ctx_id_t * context);
382 
383 const char *
384 globus_gram_protocol_error_string(int error_code);
385 
386 /* To be used only by the GRAM client API */
387 void
389 void
391 
392 /*
393  * RSL Parameters
394  */
395 #define GLOBUS_GRAM_PROTOCOL_EXECUTABLE_PARAM "executable"
396 #define GLOBUS_GRAM_PROTOCOL_ARGUMENTS_PARAM "arguments"
397 #define GLOBUS_GRAM_PROTOCOL_ENVIRONMENT_PARAM "environment"
398 #define GLOBUS_GRAM_PROTOCOL_DIR_PARAM "directory"
399 #define GLOBUS_GRAM_PROTOCOL_COUNT_PARAM "count"
400 #define GLOBUS_GRAM_PROTOCOL_STDIN_PARAM "stdin"
401 #define GLOBUS_GRAM_PROTOCOL_STDOUT_PARAM "stdout"
402 #define GLOBUS_GRAM_PROTOCOL_STDERR_PARAM "stderr"
403 #define GLOBUS_GRAM_PROTOCOL_MAX_WALL_TIME_PARAM "maxwalltime"
404 #define GLOBUS_GRAM_PROTOCOL_MAX_CPU_TIME_PARAM "maxcputime"
405 #define GLOBUS_GRAM_PROTOCOL_MAX_TIME_PARAM "maxtime"
406 #define GLOBUS_GRAM_PROTOCOL_PARADYN_PARAM "paradyn"
407 #define GLOBUS_GRAM_PROTOCOL_JOB_TYPE_PARAM "jobtype"
408 #define GLOBUS_GRAM_PROTOCOL_MYJOB_PARAM "grammyjob"
409 #define GLOBUS_GRAM_PROTOCOL_QUEUE_PARAM "queue"
410 #define GLOBUS_GRAM_PROTOCOL_PROJECT_PARAM "project"
411 #define GLOBUS_GRAM_PROTOCOL_HOST_COUNT_PARAM "hostcount"
412 #define GLOBUS_GRAM_PROTOCOL_DRY_RUN_PARAM "dryrun"
413 #define GLOBUS_GRAM_PROTOCOL_MIN_MEMORY_PARAM "minmemory"
414 #define GLOBUS_GRAM_PROTOCOL_MAX_MEMORY_PARAM "maxmemory"
415 #define GLOBUS_GRAM_PROTOCOL_START_TIME_PARAM "starttime"
416 #define GLOBUS_GRAM_PROTOCOL_RESERVATION_HANDLE_PARAM "reservationhandle"
417 #define GLOBUS_GRAM_PROTOCOL_STDOUT_POSITION_PARAM "stdoutposition"
418 #define GLOBUS_GRAM_PROTOCOL_STDERR_POSITION_PARAM "stderrposition"
419 #define GLOBUS_GRAM_PROTOCOL_SAVE_STATE_PARAM "savestate"
420 #define GLOBUS_GRAM_PROTOCOL_RESTART_PARAM "restart"
421 #define GLOBUS_GRAM_PROTOCOL_TWO_PHASE_COMMIT_PARAM "twophase"
422 #define GLOBUS_GRAM_PROTOCOL_REMOTE_IO_URL_PARAM "remoteiourl"
423 #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_IN_PARAM "filestagein"
424 #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_IN_SHARED_PARAM "filestageinshared"
425 #define GLOBUS_GRAM_PROTOCOL_FILE_STAGE_OUT_PARAM "filestageout"
426 #define GLOBUS_GRAM_PROTOCOL_FILE_CLEANUP_PARAM "filecleanup"
427 #define GLOBUS_GRAM_PROTOCOL_SCRATCHDIR_PARAM "scratchdir"
428 #define GLOBUS_GRAM_PROTOCOL_GASS_CACHE_PARAM "gasscache"
429 #define GLOBUS_GRAM_PROTOCOL_PROXY_TIMEOUT_PARAM "proxytimeout"
430 #define GLOBUS_GRAM_PROTOCOL_USER_NAME "username"
431 
432 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDIN "/dev/null"
433 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDOUT "/dev/null"
434 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_STDERR "/dev/null"
435 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_MYJOB "collective"
436 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_JOBTYPE "multiple"
437 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_DRYRUN "no"
438 #define GLOBUS_GRAM_PROTOCOL_DEFAULT_START_TIME "none"
439 
440 #ifdef __cplusplus
441 }
442 #endif
443 
444 #endif
445 
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)
Create a HTTP-framed copy of a GRAM request.
Definition: globus_gram_protocol_frame.c:93
struct globus_gram_protocol_hash_entry_s globus_gram_protocol_extension_t
GRAM protocol extension attribute-value pair.
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)
Unpack a GRAM Job Request.
Definition: globus_gram_protocol_pack.c:202
int globus_gram_protocol_unpack_job_request_reply(const globus_byte_t *reply, globus_size_t replysize, int *status, char **job_contact)
Unpack a GRAM reply message.
Definition: globus_gram_protocol_pack.c:418
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)
Create a HTTP-framed copy of a GRAM reply.
Definition: globus_gram_protocol_frame.c:223
void globus_gram_protocol_hash_destroy(globus_hashtable_t *message_hash)
Definition: globus_gram_protocol_pack.c:1989
int globus_gram_protocol_pack_status_request(const char *status_request, globus_byte_t **query, globus_size_t *querysize)
Pack a GRAM query message.
Definition: globus_gram_protocol_pack.c:825
int globus_bool_t
Boolean type.
Definition: globus_types.h:93
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.
Definition: globus_gram_protocol_pack.c:536
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.
Definition: globus_gram_protocol_pack.c:1517
int globus_gram_protocol_get_sec_context(globus_gram_protocol_handle_t handle, gss_ctx_id_t *context)
Get a reference to the GSSAPI security context associated with a GRAM protocol handle.
Definition: globus_gram_protocol_io.c:895
unsigned long globus_gram_protocol_handle_t
Unique GRAM protocol identifier.
Definition: globus_gram_protocol.h:73
int globus_gram_protocol_setup_attr(globus_io_attr_t *attr)
Create default I/O attribute for GRAM.
Definition: globus_gram_protocol.c:223
globus_bool_t globus_gram_protocol_authorize_self(gss_ctx_id_t context)
Determine if a GSSAPI context has the same source and target identities.
Definition: globus_gram_protocol.c:308
int globus_gram_protocol_reply(globus_gram_protocol_handle_t handle, int code, globus_byte_t *message, globus_size_t message_size)
Reply to a GRAM protocol message.
Definition: globus_gram_protocol_io.c:746
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)
Unpack a GRAM query reply.
Definition: globus_gram_protocol_pack.c:1082
int globus_gram_protocol_pack_version_request(char **request, size_t *requestsize)
Pack a GRAM version request message.
Definition: globus_gram_protocol_pack.c:2265
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)
Unpack a GRAM status update message.
Definition: globus_gram_protocol_pack.c:1654
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.
Definition: globus_gram_protocol_pack.c:1005
int globus_gram_protocol_unpack_status_request(const globus_byte_t *query, globus_size_t querysize, char **status_requst)
Unpack a GRAM query message.
Definition: globus_gram_protocol_pack.c:893
int globus_gram_protocol_unpack_status_reply_with_extensions(const globus_byte_t *reply, globus_size_t replysize, globus_hashtable_t *extensions)
Unpack a GRAM query reply with extensions.
Definition: globus_gram_protocol_pack.c:1305
size_t globus_size_t
Standard size of memory objectThe globus_size_t is the size of a memory object. It is identical to si...
Definition: globus_types.h:48
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.
Definition: globus_gram_protocol_pack.c:1177
unsigned char globus_byte_t
Unsigned byte datatypeThis is used for byte-addressable arrays of arbitrary data which is not subject...
Definition: globus_types.h:85
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)
Post a GRAM protocol request to a GRAM server.
Definition: globus_gram_protocol_io.c:536
const char * globus_gram_protocol_error_string(int error_code)
Get a description of a a GRAM error code.
Definition: globus_gram_protocol_error.c:239
int globus_gram_protocol_unpack_status_update_message_with_extensions(const globus_byte_t *reply, globus_size_t replysize, globus_hashtable_t *message_hash)
Unpack a GRAM status update message with extensions.
Definition: globus_gram_protocol_pack.c:1759
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)
Perform the server-side of the GSSAPI delegation handshake to receive a new delegated credential...
Definition: globus_gram_protocol_io.c:828
int globus_gram_protocol_callback_disallow(char *url)
Stop a GASS protocol listener from handling new requests.
Definition: globus_gram_protocol_io.c:401
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.
Definition: globus_gram_protocol_pack.c:339
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)
Unpack a GRAM reply message, parsing all extensions.
Definition: globus_gram_protocol_pack.c:690
void globus_gram_protocol_error_7_hack_replace_message(const char *message)
Replace the error message associated with error 7 with a custom message.
Definition: globus_gram_protocol_error.c:298
globus_gram_protocol_extension_t * globus_gram_protocol_create_extension(const char *attribute, const char *format,...)
Definition: globus_gram_protocol_pack.c:2026
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.
Definition: globus_gram_protocol_pack.c:1436
void globus_gram_protocol_error_10_hack_replace_message(const char *message)
Replace the error message associated with error 10 with a custom message.
Definition: globus_gram_protocol_error.c:336
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)
Post a GRAM protocol delegation request to a GRAM server.
Definition: globus_gram_protocol_io.c:668
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.
Definition: globus_gram_protocol_pack.c:117
int globus_gram_protocol_allow_attach(char **url, globus_gram_protocol_callback_t callback, void *callback_arg)
Create a GRAM protocol service listener.
Definition: globus_gram_protocol_io.c:259
Module Descriptor.
Definition: globus_module.h:71