1papiJobSubmit(3PAPI) PAPI Library Functions papiJobSubmit(3PAPI)
2
6 papiJobSubmit, papiJobSubmitByReference, papiJobValidate, papiJob‐
7 StreamOpen, papiJobStreamWrite, papiJobStreamClose, papiJobQuery, papi‐
8 JobModify, papiJobMove, papiJobCancel, papiJobHold, papiJobRelease,
9 papiJobRestart, papiJobPromote, papiJobGetAttributeList, papiJobGet‐
10 PrinterName, papiJobGetId, papiJobGetJobTicket, papiJobFree, papiJob‐
11 ListFree - job object manipulation
12
14 cc [ flag... ] file... -lpapi [ library... ]
15 #include <papi.h>
16 papi_status_t papiJobSubmit(papi_service_t handle,
18 char *printer, papi_attribute_t **job_attributes,
19 papi_job_ticket_t *job_ticket, char **files,
20 papi_job_t *job);
21 papi_status_t papiJobSubmitByReference(papi_service_t handle,
24 char *printer, papi_attribute_t **job_attributes,
25 papi_job_ticket_t *job_ticket, char **files,
26 papi_job_t *job);
27 papi_status_t papiJobValidate(papi_service_t handle,
30 char *printer, papi_attribute_t **job_attributes,
31 papi_job_ticket_t *job_ticket, char **files,
32 papi_job_t *job);
33 papi_status_t papiJobStreamOpen(papi_service_t handle,
36 char *printer, papi_attribute_t **job_attributes,
37 papi_job_ticket_t *job_ticket, papi_stream_t *stream);
38 papi_status_t papiJobStreamWrite(papi_service_t handle,
41 papi_stream_t stream, void *buffer, size_t buflen);
42 papi_status_t papiJobStreamClose(papi_service_t handle,
45 papi_stream_t stream, papi_job_t *job);
46 papi_status_t papiJobQuery(papi_service_t handle,
49 char *printer, int32_t job_id, char **requested_attrs,
50 papi_job_t *job);
51 papi_status_t papiJobModify(papi_service_t handle,
54 char *printer, int32_t job_id,
55 papi_attribute_t **attributes, papi_job_t *job);
56 papi_status_t papiJobMove(papi_service_t handle,
59 char *printer, int32_t job_id, char *destination);
60 papi_status_t papiJobCancel(papi_service_t handle,
63 char *printer, int32_t job_id);
64 papi_status_t papiJobHold(papi_service_t handle,
67 char *printer, int32_t job_id);
68 papi_status_t papiJobRelease(papi_service_t handle,
71 char *printer, int32_t job_id);
72 papi_status_t papiJobRestart(papi_service_t handle,
75 char *printer, int32_t job_id);
76 papi_status_t papiJobPromote(papi_service_t handle,
79 char *printer, int32_t job_id);
80 papi_attribute_t **papiJobGetAttributeList(papi_job_t job);
83 char *papiJobGetPrinterName(papi_job_t job);
86 int32_t papiJobGetId(papi_job_t job);
89 papi_job_ticket_t *papiJobGetJobTicket(papi_job_t job);
92 void papiJobFree(papi_job_t job);
95 void papiJobListFree(papi_job_t *jobs);
98
101 attributes a set of attributes to be applied to a printer
102 object
103 buffer a buffer of data to be written to the job stream
106 bufflen the size of the supplied buffer
109 destination the name of the printer where a print job should be
112 relocated, which must reside within the same print
113 services as the job is currently queued
114 files files to use during job submission
117 handle a pointer to a handle to be used for all PAPI opera‐
120 tions that is created by calling papiServiceCreate()
121 job a pointer to a printer object (initialized to NULL)
124 to be filled in by papiJobQuery(), papiJobSubmit(),
125 papiJobSubmitByReference(), papiJobValidate(), papi‐
126 JobStreamClose(), and papiJobModify()
127 job_attributes attributes to apply during job creation or modifica‐
130 tion
131 job_id ID number of the job reported on or manipulated
134 job_ticket unused
137 jobs a list of job objects returned by papiPrint‐
140 erListJobs() or papiPrinterPurgeJobs()
141 printer name of the printer where the job is or should
144 reside
145 requested_attrs a null-terminated array of pointers to attribute
148 names requested during job enumeration (papiPrint‐
149 erListJobs()) or job query (papiJobQuery())
150 stream a communication endpoint for sending print job data
153
156 The papiJobSubmit() function creates a print job containing the passed
157 in files with the supplied attributes. When the function returns, the
158 data in the passed files will have been copied by the print service. A
159 job object is returned that reflects the state of the job.
160 The papiJobSubmitByReference() function creates a print job containing
163 the passed in files with the supplied attributes. When the function
164 returns, the data in the passed files might have been copied by the
165 print service. A job object is returned that reflects the state of the
166 job.
167 The papiJobStreamOpen(), papiJobStreamWrite(), papiJobStreamClose()
170 functions create a print job by opening a stream, writing to the
171 stream, and closing it.
172 The papiJobValidate() function validates that the supplied attributes
175 and files will result in a valid print job.
176 The papiJobQuery() function retrieves job information from the print
179 service.
180 The papiJobModify() function modifies a queued job according to the
183 attribute list passed into the call. A job object is returned that
184 reflects the state of the job after the modification has been applied.
185 The papiJobMove() function moves a job from its current queue to the
188 named destination within the same print service.
189 The papiJobCancel() function removes a job from the queue.
192 The papiJobHold() and papiJobRelease() functions set the job state to
195 "held" or "idle" to indicate whether the job is eligible for process‐
196 ing.
197 The papiJobRestart() function restarts processing of a currently queued
200 print job.
201 The papiJobGetAttributeList() function returns a list of attributes
204 describing the job. This list can be searched and/or enumerated using
205 papiAttributeList*() calls. See papiAttributeListAddValue(3PAPI).
206 The papiJobGetPrinterName() function returns the name of the queue
209 where the job is currently queued.
210 The papiJobGetId() function returns a job identifier number from the
213 job object passed in.
214 The papiJobPromote() function moves a job to the head of the print
217 queue.
218 The papiJobGetJobTicket() function retrieves a pointer to a job ticket
221 associated with the job object.
222 The papiJobFree() and papiJobListFree() functions deallocate memory
225 allocated for the return of printer object(s) from functions that
226 return printer objects.
227
229 Upon successful completion, all papiJob*() functions that return a
230 value return PAPI_OK. Otherwise, they return an appropriate papi_sta‐
231 tus_t indicating the type of failure.
232 Upon successful completion, papiJobGetAttributeList() returns a pointer
235 to the requested data. Otherwise, it returns NULL.
236
238 Example 1 Enumerate all jobs in a queue
239 /*
241 * program to enumerate queued jobs using PAPI interfaces.
242 */
243 #include <stdio.h>
244 #include <stdlib.h>
245 #include <unistd.h>
246 #include <libintl.h>
247 #include <pwd.h>
248 #include <papi.h>
249 static int
251 authCB(papi_service_t svc, void *app_data)
252 {
253 char prompt[BUFSIZ];
254 char *user, *svc_name, *passphrase;
255 /* get the name of the service we are contacting */
257 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
258 return (-1);
259 /* find out who we are supposed to be */
261 if ((user = papiServiceGetUserName(svc)) == NULL) {
262 struct passwd *pw;
263 if ((pw = getpwuid(getuid())) != NULL)
265 user = pw->pw_name;
266 else
267 user = "nobody";
268 }
269 /* build the prompt string */
271 snprintf(prompt, sizeof (prompt),
272 gettext("passphrase for %s to access %s: "), user,
273 svc_name);
274 /* ask for the passphrase */
276 if ((passphrase = getpassphrase(prompt)) != NULL)
277 papiServiceSetPassword(svc, passphrase);
278 return (0);
280 }
281 /*ARGSUSED*/
283 int
284 main(int ac, char *av[])
285 {
286 papi_status_t status;
287 papi_service_t svc = NULL;
288 papi_job_t *jobs = NULL;
289 char *svc_name = NULL;
290 char *pname = "unknown";
291 int c;
292 while ((c = getopt(ac, av, "s:p:")) != EOF)
294 switch (c) {
295 case 's':
296 svc_name = optarg;
297 break;
298 case 'p':
299 pname = optarg;
300 break;
301 }
302 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
304 PAPI_ENCRYPT_NEVER, NULL);
305 if (status != PAPI_OK) {
307 printf("papiServiceCreate(%s): %s0, svc_name ? svc_name :
308 "NULL", papiStatusString(status));
309 papiServiceDestroy(svc);
310 exit(1);
311 }
312 status = papiPrinterListJobs(svc, pname, NULL, 0, 0, &jobs);
314 if (status != PAPI_OK) {
315 printf("papiPrinterListJobs(%s): %s0, pname,
316 papiStatusString(status));
317 papiServiceDestroy(svc);
318 exit(1);
319 }
320 if (jobs != NULL) {
322 int i;
323 for (i = 0; jobs[i] != NULL; i++) {
325 papi_attribute_t **list = papiJobGetAttributeList(jobs[i]);
326 if (list != NULL) {
328 char *name = "unknown";
329 int32_t id = 0;
330 char *buffer = NULL;
331 size_t size = 0;
332 (void) papiAttributeListGetString(list, NULL,
334 "printer-name", &name);
335 (void) papiAttributeListGetInteger(list, NULL,
336 "job-id", &id);
337 while (papiAttributeListToString(list, "", buffer,
338 size) != PAPI_OK)
339 buffer = realloc(buffer, size += BUFSIZ);
340 printf("%s-%d:%s0, name, id, buffer);
342 free(buffer);
343 }
344 }
345 papiJobListFree(jobs);
346 }
347 papiServiceDestroy(svc);
349 exit(0);
351 }
352 Example 2 Dump all job attributes.
355 /*
357 * program to dump a queued job's attributes using PAPI interfaces.
358 */
359 #include <stdio.h>
360 #include <stdlib.h>
361 #include <unistd.h>
362 #include <libintl.h>
363 #include <pwd.h>
364 #include <papi.h>
365 static int
367 authCB(papi_service_t svc, void *app_data)
368 {
369 char prompt[BUFSIZ];
370 char *user, *svc_name, *passphrase;
371 /* get the name of the service we are contacting */
373 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
374 return (-1);
375 /* find out who we are supposed to be */
377 if ((user = papiServiceGetUserName(svc)) == NULL) {
378 struct passwd *pw;
379 if ((pw = getpwuid(getuid())) != NULL)
381 user = pw->pw_name;
382 else
383 user = "nobody";
384 }
385 /* build the prompt string */
387 snprintf(prompt, sizeof (prompt),
388 gettext("passphrase for %s to access %s: "), user,
389 svc_name);
390 /* ask for the passphrase */
392 if ((passphrase = getpassphrase(prompt)) != NULL)
393 papiServiceSetPassword(svc, passphrase);
394 return (0);
396 }
397 /*ARGSUSED*/
399 int
400 main(int ac, char *av[])
401 {
402 papi_status_t status;
403 papi_service_t svc = NULL;
404 papi_job_t job = NULL;
405 char *svc_name = NULL;
406 char *pname = "unknown";
407 int id = 0;
408 int c;
409 while ((c = getopt(ac, av, "s:p:j:")) != EOF)
411 switch (c) {
412 case 's':
413 svc_name = optarg;
414 break;
415 case 'p':
416 pname = optarg;
417 break;
418 case 'j':
419 id = atoi(optarg);
420 break;
421 }
422 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
424 PAPI_ENCRYPT_NEVER, NULL);
425 if (status != PAPI_OK) {
427 printf("papiServiceCreate(%s): %s0, svc_name ? svc_name :
428 "NULL", papiStatusString(status));
429 papiServiceDestroy(svc);
430 exit(1);
431 }
432 status = papiJobQuery(svc, pname, id, NULL, &job);
434 if ((status == PAPI_OK) && (job != NULL)) {
435 papi_attribute_t **list = papiJobGetAttributeList(job);
436 if (list != NULL) {
438 char *name = "unknown";
439 int32_t id = 0;
440 char *buffer = NULL;
441 size_t size = 0;
442 (void) papiAttributeListGetString(list, NULL,
444 "printer-name", &name);
445 (void) papiAttributeListGetInteger(list, NULL,
446 "job-id", &id);
447 while (papiAttributeListToString(list, "", buffer, size)
448 != PAPI_OK)
449 buffer = realloc(buffer, size += BUFSIZ);
450 printf("%s-%d:%s0, name, id, buffer);
452 free(buffer);
453 }
454 } else
455 printf("papiJobQuery(%s-%d): %s0, pname, id,
456 papiStatusString(status));
457 papiJobFree(job);
459 papiServiceDestroy(svc);
460 exit(0);
462 }
463 Example 3 Submit a job (stream).
466 /*
468 * program to submit a job from standard input.
469 */
470 #include <stdio.h>
471 #include <stdlib.h>
472 #include <unistd.h>
473 #include <libintl.h>
474 #include <pwd.h>
475 #include <papi.h>
476 static int
478 authCB(papi_service_t svc, void *app_data)
479 {
480 char prompt[BUFSIZ];
481 char *user, *svc_name, *passphrase;
482 /* get the name of the service we are contacting */
484 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
485 return (-1);
486 /* find out who we are supposed to be */
488 if ((user = papiServiceGetUserName(svc)) == NULL) {
489 struct passwd *pw;
490 if ((pw = getpwuid(getuid())) != NULL)
492 user = pw->pw_name;
493 else
494 user = "nobody";
495 }
496 /* build the prompt string */
498 snprintf(prompt, sizeof (prompt),
499 gettext("passphrase for %s to access %s: "), user,
500 svc_name);
501 /* ask for the passphrase */
503 if ((passphrase = getpassphrase(prompt)) != NULL)
504 papiServiceSetPassword(svc, passphrase);
505 return (0);
507 }
508 /*ARGSUSED*/
510 int
511 main(int ac, char *av[])
512 {
513 papi_status_t status;
514 papi_service_t svc = NULL;
515 papi_stream_t stream = NULL;
516 papi_job_t job = NULL;
517 papi_attribute_t **attrs = NULL;
518 char *svc_name = NULL;
519 char *pname = "unknown";
520 int id = 0;
521 int c;
522 int rc;
523 char buf[BUFSIZ];
524 while ((c = getopt(ac, av, "s:p:")) != EOF)
526 switch (c) {
527 case 's':
528 svc_name = optarg;
529 break;
530 case 'p':
531 pname = optarg;
532 break;
533 }
534 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
536 PAPI_ENCRYPT_NEVER, NULL);
537 if (status != PAPI_OK) {
539 printf("papiServiceCreate(%s): %s0, svc_name ? svc_name :
540 "NULL", papiStatusString(status));
541 papiServiceDestroy(svc);
542 exit(1);
543 }
544 papiAttributeListAddInteger(&attrs, PAPI_ATTR_EXCL, "copies", 1);
546 papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL,
547 "document-format", "application/octet-stream");
548 papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL,
549 "job-title", "Standard Input");
550 status = papiJobStreamOpen(svc, pname, attrs, NULL, &stream);
552 while ((status == PAPI_OK) && ((rc = read(0, buf,
553 sizeof (buf))) > 0))
554 status = papiJobStreamWrite(svc, stream, buf, rc);
555 if (status == PAPI_OK)
557 status = papiJobStreamClose(svc, stream, &job);
558 if ((status == PAPI_OK) && (job != NULL)) {
561 papi_attribute_t **list = papiJobGetAttributeList(job);
562 if (list != NULL) {
564 char *name = "unknown";
565 int32_t id = 0;
566 char *buffer = NULL;
567 size_t size = 0;
568 (void) papiAttributeListGetString(list, NULL,
570 "printer-name", &name);
571 (void) papiAttributeListGetInteger(list, NULL,
572 "job-id", &id);
573 while (papiAttributeListToString(list, "", buffer, size)
574 != PAPI_OK)
575 buffer = realloc(buffer, size += BUFSIZ);
576 printf("%s-%d:%s0, name, id, buffer);
578 free(buffer);
579 }
580 } else
581 printf("papiJobStream*(%s-%d): %s0, pname, id,
582 papiStatusString(status));
583 papiJobFree(job);
585 papiServiceDestroy(svc);
586 exit(0);
588 }
589
592 See attributes(5) for descriptions of the following attributes:
593 ┌─────────────────────────────┬─────────────────────────────┐
598 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
599 ├─────────────────────────────┼─────────────────────────────┤
600 │Interface Stability │Volatile │
601 ├─────────────────────────────┼─────────────────────────────┤
602 │MT-Level │Safe │
603 └─────────────────────────────┴─────────────────────────────┘
604
606 libpapi(3LIB), papiAttributeListAddValue(3PAPI), attributes(5)
607SunOS 5.11 17 Jan 2007 papiJobSubmit(3PAPI)