1papiJobSubmit(3PAPI)        PAPI Library Functions        papiJobSubmit(3PAPI)
2
3
4

NAME

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

SYNOPSIS

14       cc [ flag... ] file... -lpapi [ library... ]
15       #include <papi.h>
16
17       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
22
23       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
28
29       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
34
35       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
39
40       papi_status_t papiJobStreamWrite(papi_service_t handle,
41            papi_stream_t stream, void *buffer, size_t buflen);
42
43
44       papi_status_t papiJobStreamClose(papi_service_t handle,
45            papi_stream_t stream, papi_job_t *job);
46
47
48       papi_status_t papiJobQuery(papi_service_t handle,
49            char *printer, int32_t job_id, char **requested_attrs,
50            papi_job_t *job);
51
52
53       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
57
58       papi_status_t papiJobMove(papi_service_t handle,
59            char *printer, int32_t job_id, char *destination);
60
61
62       papi_status_t papiJobCancel(papi_service_t handle,
63            char *printer, int32_t job_id);
64
65
66       papi_status_t papiJobHold(papi_service_t handle,
67            char *printer, int32_t job_id);
68
69
70       papi_status_t papiJobRelease(papi_service_t handle,
71            char *printer, int32_t job_id);
72
73
74       papi_status_t papiJobRestart(papi_service_t handle,
75            char *printer, int32_t job_id);
76
77
78       papi_status_t papiJobPromote(papi_service_t handle,
79            char *printer, int32_t job_id);
80
81
82       papi_attribute_t **papiJobGetAttributeList(papi_job_t job);
83
84
85       char *papiJobGetPrinterName(papi_job_t job);
86
87
88       int32_t papiJobGetId(papi_job_t job);
89
90
91       papi_job_ticket_t *papiJobGetJobTicket(papi_job_t job);
92
93
94       void papiJobFree(papi_job_t job);
95
96
97       void papiJobListFree(papi_job_t *jobs);
98
99

PARAMETERS

101       attributes         a set of attributes  to  be  applied  to  a  printer
102                          object
103
104
105       buffer             a buffer of data to be written to the job stream
106
107
108       bufflen            the size of the supplied buffer
109
110
111       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
115
116       files              files to use during job submission
117
118
119       handle             a pointer to a handle to be used for all PAPI opera‐
120                          tions that is created by calling papiServiceCreate()
121
122
123       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
128
129       job_attributes     attributes to apply during job creation or modifica‐
130                          tion
131
132
133       job_id             ID number of the job reported on or manipulated
134
135
136       job_ticket         unused
137
138
139       jobs               a  list  of  job  objects  returned  by   papiPrint‐
140                          erListJobs() or papiPrinterPurgeJobs()
141
142
143       printer            name  of  the  printer  where  the  job is or should
144                          reside
145
146
147       requested_attrs    a null-terminated array  of  pointers  to  attribute
148                          names  requested  during job enumeration (papiPrint‐
149                          erListJobs()) or job query (papiJobQuery())
150
151
152       stream             a communication endpoint for sending print job data
153
154

DESCRIPTION

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
161
162       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
168
169       The   papiJobStreamOpen(),  papiJobStreamWrite(),  papiJobStreamClose()
170       functions create a print job  by  opening  a  stream,  writing  to  the
171       stream, and closing it.
172
173
174       The  papiJobValidate()  function validates that the supplied attributes
175       and files will result in a valid print job.
176
177
178       The papiJobQuery() function retrieves job information  from  the  print
179       service.
180
181
182       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
186
187       The  papiJobMove()  function  moves a job from its current queue to the
188       named destination within the same print service.
189
190
191       The papiJobCancel() function removes a job from the queue.
192
193
194       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
198
199       The papiJobRestart() function restarts processing of a currently queued
200       print job.
201
202
203       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
207
208       The  papiJobGetPrinterName()  function  returns  the  name of the queue
209       where the job is currently queued.
210
211
212       The papiJobGetId() function returns a job identifier  number  from  the
213       job object passed in.
214
215
216       The  papiJobPromote()  function  moves  a  job to the head of the print
217       queue.
218
219
220       The papiJobGetJobTicket() function retrieves a pointer to a job  ticket
221       associated with the job object.
222
223
224       The  papiJobFree()  and  papiJobListFree()  functions deallocate memory
225       allocated for the return  of  printer  object(s)  from  functions  that
226       return printer objects.
227

RETURN VALUES

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
233
234       Upon successful completion, papiJobGetAttributeList() returns a pointer
235       to the requested data. Otherwise, it returns NULL.
236

EXAMPLES

238       Example 1 Enumerate all jobs in a queue
239
240         /*
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
250         static int
251         authCB(papi_service_t svc, void *app_data)
252         {
253             char prompt[BUFSIZ];
254             char *user, *svc_name, *passphrase;
255
256             /* get the name of the service we are contacting */
257             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
258                     return (-1);
259
260             /* find out who we are supposed to be */
261             if ((user = papiServiceGetUserName(svc)) == NULL) {
262                     struct passwd *pw;
263
264                     if ((pw = getpwuid(getuid())) != NULL)
265                             user = pw->pw_name;
266                     else
267                             user = "nobody";
268             }
269
270             /* build the prompt string */
271             snprintf(prompt, sizeof (prompt),
272                     gettext("passphrase for %s to access %s: "), user,
273                           svc_name);
274
275             /* ask for the passphrase */
276             if ((passphrase = getpassphrase(prompt)) != NULL)
277                     papiServiceSetPassword(svc, passphrase);
278
279             return (0);
280         }
281
282         /*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
293             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
303             status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
304                                     PAPI_ENCRYPT_NEVER, NULL);
305
306             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
313             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
321             if (jobs != NULL) {
322                 int i;
323
324                 for (i = 0; jobs[i] != NULL; i++) {
325                     papi_attribute_t **list = papiJobGetAttributeList(jobs[i]);
326
327                     if (list != NULL) {
328                         char *name = "unknown";
329                                     int32_t id = 0;
330                         char *buffer = NULL;
331                         size_t size = 0;
332
333                        (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
341                         printf("%s-%d:%s0, name, id, buffer);
342                         free(buffer);
343                     }
344                 }
345                 papiJobListFree(jobs);
346             }
347
348             papiServiceDestroy(svc);
349
350             exit(0);
351         }
352
353
354       Example 2 Dump all job attributes.
355
356         /*
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
366         static int
367         authCB(papi_service_t svc, void *app_data)
368         {
369             char prompt[BUFSIZ];
370             char *user, *svc_name, *passphrase;
371
372             /* get the name of the service we are contacting */
373             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
374                     return (-1);
375
376             /* find out who we are supposed to be */
377             if ((user = papiServiceGetUserName(svc)) == NULL) {
378                     struct passwd *pw;
379
380                     if ((pw = getpwuid(getuid())) != NULL)
381                             user = pw->pw_name;
382                     else
383                             user = "nobody";
384             }
385
386             /* build the prompt string */
387             snprintf(prompt, sizeof (prompt),
388                     gettext("passphrase for %s to access %s: "), user,
389                              svc_name);
390
391             /* ask for the passphrase */
392             if ((passphrase = getpassphrase(prompt)) != NULL)
393                     papiServiceSetPassword(svc, passphrase);
394
395             return (0);
396         }
397
398         /*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
410             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
423             status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
424                                     PAPI_ENCRYPT_NEVER, NULL);
425
426             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
433             status = papiJobQuery(svc, pname, id, NULL, &job);
434             if ((status == PAPI_OK) && (job != NULL)) {
435                 papi_attribute_t **list = papiJobGetAttributeList(job);
436
437                 if (list != NULL) {
438                     char *name = "unknown";
439                     int32_t id = 0;
440                     char *buffer = NULL;
441                     size_t size = 0;
442
443                     (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
451                     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
458             papiJobFree(job);
459             papiServiceDestroy(svc);
460
461             exit(0);
462         }
463
464
465       Example 3 Submit a job (stream).
466
467         /*
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
477         static int
478         authCB(papi_service_t svc, void *app_data)
479         {
480             char prompt[BUFSIZ];
481             char *user, *svc_name, *passphrase;
482
483             /* get the name of the service we are contacting */
484             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
485                     return (-1);
486
487             /* find out who we are supposed to be */
488             if ((user = papiServiceGetUserName(svc)) == NULL) {
489                     struct passwd *pw;
490
491                     if ((pw = getpwuid(getuid())) != NULL)
492                             user = pw->pw_name;
493                     else
494                             user = "nobody";
495             }
496
497             /* build the prompt string */
498             snprintf(prompt, sizeof (prompt),
499                     gettext("passphrase for %s to access %s: "), user,
500                             svc_name);
501
502             /* ask for the passphrase */
503             if ((passphrase = getpassphrase(prompt)) != NULL)
504                     papiServiceSetPassword(svc, passphrase);
505
506             return (0);
507         }
508
509         /*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
525             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
535             status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
536                                     PAPI_ENCRYPT_NEVER, NULL);
537
538             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
545             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
551             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
556             if (status == PAPI_OK)
557                     status = papiJobStreamClose(svc, stream, &job);
558
559
560             if ((status == PAPI_OK) && (job != NULL)) {
561                 papi_attribute_t **list = papiJobGetAttributeList(job);
562
563                 if (list != NULL) {
564                     char *name = "unknown";
565                     int32_t id = 0;
566                     char *buffer = NULL;
567                     size_t size = 0;
568
569                     (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
577                     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
584             papiJobFree(job);
585             papiServiceDestroy(svc);
586
587             exit(0);
588         }
589
590

ATTRIBUTES

592       See attributes(5) for descriptions of the following attributes:
593
594
595
596
597       ┌─────────────────────────────┬─────────────────────────────┐
598       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
599       ├─────────────────────────────┼─────────────────────────────┤
600       │Interface Stability          │Volatile                     │
601       ├─────────────────────────────┼─────────────────────────────┤
602       │MT-Level                     │Safe                         │
603       └─────────────────────────────┴─────────────────────────────┘
604

SEE ALSO

606       libpapi(3LIB), papiAttributeListAddValue(3PAPI), attributes(5)
607
608
609
610SunOS 5.11                        17 Jan 2007             papiJobSubmit(3PAPI)
Impressum