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

NAME

6       papiPrintersList,  papiPrinterQuery, papiPrinterAdd, papiPrinterModify,
7       papiPrinterRemove, papiPrinterDisable, papiPrinterEnable,  papiPrinter‐
8       Pause,  papiPrinterResume,  papiPrinterPurgeJobs,  papiPrinterListJobs,
9       papiPrinterGetAttributeList,  papiPrinterFree,  papiPrinterListFree   -
10       print object manipulation
11

SYNOPSIS

13       cc [ flag... ] file... -lpapi [ library... ]
14       #include <papi.h>
15
16       papi_status_t papiPrintersList(papi_service_t handle,
17            char **requested_attrs, papi_filter_t *filter,
18            papi_printer_t **printers);
19
20
21       papi_status_t papiPrinterQuery(papi_service_t handle, char *name,
22            char **requested_attrs, papi_attribute_t **job_attributes,
23            papi_printer_t *printer);
24
25
26       papi_status_t papiPrinterAdd(papi_service_t handle, char *name,
27            papi_attribute_t **attributes, papi_printer_t *printer);
28
29
30       papi_status_t papiPrinterModify(papi_service_t handle, char *name,
31            papi_attribute_t **attributes, papi_printer_t *printer);
32
33
34       papi_status_t papiPrinterRemove(papi_service_t handle, char *name);
35
36
37       papi_status_t papiPrinterDisable(papi_service_t handle, char *name,
38            char *message);
39
40
41       papi_status_t papiPrinterEnable(papi_service_t handle, char *name);
42
43
44       papi_status_t papiPrinterPause(papi_service_t handle, char *name,
45            char *message);
46
47
48       papi_status_t papiPrinterResume(papi_service_t handle, char *name);
49
50
51       papi_status_t papiPrinterPurgeJobs(papi_service_t handle, char *name,
52            papi_job_t **jobs);
53
54
55       papi_status_t papiPrinterListJobs(papi_service_t handle, char *name,
56            char **requested_attrs, int type_mask, int max_num_jobs,
57            papi_job_t **jobs);
58
59
60       papi_attribute_t **papiPrinterGetAttributeList(papi_printer_t printer);
61
62
63       void papiPrinterFree(papi_printer_t printer);
64
65
66       void papiPrinterListFree(papi_printer_t *printers);
67
68

PARAMETERS

70       attributes         a  set  of  attributes  to  be  applied to a printer
71                          object
72
73
74       filter             a filter to be applied during printer enumeration
75
76
77       handle             a pointer to a handle to be used for all PAPI opera‐
78                          tions, created by calling papiServiceCreate()
79
80
81       job_attributes     unused
82
83
84       jobs               a  pointer to a list to return job objects (initial‐
85                          ized to NULL) enumerated by papiPrinterGetJobs()
86
87
88       max_num_jobs       the  maximum  number  of  jobs  to  return  from   a
89                          papiPrinterGetJobs() request
90
91
92       message            a message to be associated with a printer while dis‐
93                          abled or paused
94
95
96       name               the name of the printer object being operated on
97
98
99       printer            a pointer to a printer object (initialized to  NULL)
100                          to  be filled in by papiPrinterQuery(), papiPrinter‐
101                          Add(), and papiPrinterModify()
102
103
104       printers           a pointer to a list to return printer objects  (ini‐
105                          tialized to NULL) enumerated by papiPrintersList()
106
107
108       requested_attrs    a  null-terminated  array  of  pointers to attribute
109                          names   requested   during    printer    enumeration
110                          (papiPrintersList()),  printer  query  (papiPrinter‐
111                          Query()), or job enumeration (papiPrinterListJobs())
112
113
114       type_mask          a bit field indicating which type of jobs to  return
115                          PAPI_LIST_JOBS_OTHERS include jobs submitted by oth‐
116                          ers.  The default is to report only on your own jobs
117
118                          PAPI_LIST_JOBS_COMPLETED
119
120                              include completed jobs
121
122
123                          PAPI_LIST_JOBS_NOT_COMPLETED
124
125                              include jobs not complete
126
127
128                          PAPI_LIST_JOBS_ALL
129
130                              report on all jobs
131
132
133

DESCRIPTION

135       The papiPrintersList() function retrieves the requested attributes from
136       the  print  service(s) for all available printers.  Because the Solaris
137       implementation is name service-enabled,  applications  should  retrieve
138       only  the  printer-name and printer-uri-supported attributes using this
139       function, thereby  reducing  the  overhead  involved  in  generating  a
140       printer  list.   Further  integration of printer state and capabilities
141       can be performed with papiPrinterQuery().
142
143
144       The  papiPrinterAdd(),  papiPrinterModify(),  and   papiPrinterRemove()
145       functions  allow  for  creation,  modification,  and  removal  of print
146       queues.  Print queues are added or modified according to the  attribute
147       list  passed  into the call. A printer object is returned that reflects
148       the configuration of the printer after the addition or modification has
149       been  applied.   At  this time, they provide only minimal functionality
150       and only for the LP print service.
151
152
153       The papiPrinterDisable() and papiPrinterEnable() functions allow appli‐
154       cations  to  turn  off and on queueing (accepting print requests) for a
155       print queue. The papiPrinterEnable() and papiPrinterDisable() functions
156       allow  applications to turn on and off print job processing for a print
157       queue.
158
159
160       The papiPrinterPause() function stops queueing of  print  jobs  on  the
161       named print queue.
162
163
164       The  papiPrinterResume() function resumes queueing of print jobs on the
165       named print queue.
166
167
168       The papiPrinterPurgeJobs() function allows applications to  delete  all
169       print  jobs  that it has privilege to remove.  A list of cancelled jobs
170       is returned in the jobs argument.
171
172
173       The papiPrinterListJobs() function enumerates print jobs on a  particu‐
174       lar  queue.  papiPrinterGetAttributeList()  retrieves an attribute list
175       from a printer object.
176
177
178       The papiPrinterGetAttributeList() function retrieves an attribute  list
179       from  a  printer  object returned from papiPrinterQuery(), papiPrinter‐
180       sList(), papiPrinterModify(),  and  papiPrinterAdd().   This  attribute
181       list can be searched for various information about the printer object.
182
183
184       The  papiPrinterFree()  and  papiPrinterListFree() functions deallocate
185       memory allocated for the return of  printer  object(s)  from  functions
186       that return printer objects.
187

RETURN VALUES

189       Upon  successful  completion,  all functions that return a value return
190       PAPI_OK. Otherwise, they return an appropriate papi_status_t() indicat‐
191       ing the type of failure.
192
193
194       Upon  successful  completion,  papiPrinterGetAttributeList()  returns a
195       pointer to the requested data. Otherwise, it returns NULL.
196

EXAMPLES

198       Example 1 Enumerate all available printers.
199
200         #include <stdio.h>
201         #include <stdlib.h>
202         #include <unistd.h>
203         #include <libintl.h>
204         #include <pwd.h>
205         #include <papi.h>
206
207         static int
208         authCB(papi_service_t svc, void *app_data)
209         {
210             char prompt[BUFSIZ];
211             char *user, *svc_name, *passphrase;
212
213             /* get the name of the service we are contacting */
214             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
215                     return (-1);
216
217             /* find out who we are supposed to be */
218             if ((user = papiServiceGetUserName(svc)) == NULL) {
219                     struct passwd *pw;
220
221                     if ((pw = getpwuid(getuid())) != NULL)
222                             user = pw->pw_name;
223                     else
224                             user = "nobody";
225             }
226
227             /* build the prompt string */
228             snprintf(prompt, sizeof (prompt),
229                     gettext("passphrase for %s to access %s: "), user,
230                            svc_name);
231
232             /* ask for the passphrase */
233             if ((passphrase = getpassphrase(prompt)) != NULL)
234                     papiServiceSetPassword(svc, passphrase);
235
236             return (0);
237         }
238
239         /*ARGSUSED*/
240         int
241         main(int ac, char *av[])
242         {
243             papi_status_t status;
244             papi_service_t svc = NULL;
245             papi_printer_t *printers = NULL;
246             char *attrs[] = { "printer-name", "printer-uri-supported", NULL };
247             char *svc_name = NULL;
248             int c;
249
250             while ((c = getopt(ac, av, "s:")) != EOF)
251                 switch (c) {
252                 case 's':
253                     svc_name = optarg;
254                     break;
255                 }
256
257             status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
258                                     PAPI_ENCRYPT_NEVER, NULL);
259
260             if (status != PAPI_OK) {
261                 printf("papiServiceCreate(%s): %s\n", svc_name ? svc_name :
262                              "NULL", papiStatusString(status));
263                 papiServiceDestroy(svc);
264                 exit(1);
265             }
266
267             status = papiPrintersList(svc, attrs, NULL, &printers);
268             if (status != PAPI_OK) {
269                 printf("papiPrintersList(%s): %s\n", svc_name ? svc_name :
270                              "NULL", papiStatusString(status));
271                 papiServiceDestroy(svc);
272                 exit(1);
273             }
274
275             if (printers != NULL) {
276                 int i;
277
278                 for (i = 0; printers[i] != NULL; i++) {
279                     papi_attribute_t **list =
280                         papiPrinterGetAttributeList(printers[i]);
281
282                     if (list != NULL) {
283                         char *name = "unknown";
284                         char *uri = "unknown";
285
286                         (void) papiAttributeListGetString(list, NULL,
287                                             "printer-name", &name);
288
289                         (void) papiAttributeListGetString(list, NULL,
290                                             "printer-uri-supported", &uri);
291                         printf("%s is %s0, name, uri);
292                     }
293                 }
294                 papiPrinterListFree(printers);
295             }
296
297             papiServiceDestroy(svc);
298
299             exit(0);
300         }
301
302
303       Example 2 Dump all printer attributes.
304
305         /*
306          * program to query a printer for it's attributes via PAPI
307          */
308         #include <stdio.h>
309         #include <stdlib.h>
310         #include <unistd.h>
311         #include <libintl.h>
312         #include <pwd.h>
313         #include <papi.h>
314
315         static int
316         authCB(papi_service_t svc, void *app_data)
317         {
318             char prompt[BUFSIZ];
319             char *user, *svc_name, *passphrase;
320
321             /* get the name of the service we are contacting */
322             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
323                     return (-1);
324
325             /* find out who we are supposed to be */
326             if ((user = papiServiceGetUserName(svc)) == NULL) {
327                     struct passwd *pw;
328
329                     if ((pw = getpwuid(getuid())) != NULL)
330                             user = pw->pw_name;
331                     else
332                             user = "nobody";
333             }
334
335             /* build the prompt string */
336             snprintf(prompt, sizeof (prompt),
337                     gettext("passphrase for %s to access %s: "), user,
338                             svc_name);
339
340             /* ask for the passphrase */
341             if ((passphrase = getpassphrase(prompt)) != NULL)
342                     papiServiceSetPassword(svc, passphrase);
343
344             return (0);
345         }
346
347         /*ARGSUSED*/
348         int
349         main(int ac, char *av[])
350         {
351             papi_status_t status;
352             papi_service_t svc = NULL;
353             papi_printer_t printer = NULL;
354             char *svc_name = NULL;
355             char *pname = "unknown";
356             int c;
357
358             while ((c = getopt(ac, av, "s:p:")) != EOF)
359                 switch (c) {
360                 case 's':
361                     svc_name = optarg;
362                     break;
363                 case 'p':
364                     pname = optarg;
365                     break;
366                 }
367
368             status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
369                                     PAPI_ENCRYPT_NEVER, NULL);
370
371             if (status != PAPI_OK) {
372                 printf("papiServiceCreate(%s): %s\n", svc_name ? svc_name :
373                             "NULL", papiStatusString(status));
374                 papiServiceDestroy(svc);
375                 exit(1);
376             }
377
378             status = papiPrinterQuery(svc, pname, NULL, NULL, &printer);
379             if ((status == PAPI_OK) && (printer != NULL)) {
380                 papi_attribute_t **list = papiPrinterGetAttributeList(printer);
381                 char *buffer = NULL;
382                 size_t size = 0;
383
384                 while (papiAttributeListToString(list, "\n\t", buffer, size)
385                             != PAPI_OK)
386                     buffer = realloc(buffer, size += BUFSIZ);
387
388                 printf("%s:\n\t%s\n", pname, buffer);
389             } else
390                 printf("papiPrinterQuery(%s): %s\n", pname,
391                             papiStatusString(status));
392
393             papiPrinterFree(printer);
394             papiServiceDestroy(svc);
395
396             exit(0);
397         }
398
399

ATTRIBUTES

401       See attributes(5) for descriptions of the following attributes:
402
403
404
405
406       ┌─────────────────────────────┬─────────────────────────────┐
407       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
408       ├─────────────────────────────┼─────────────────────────────┤
409       │Interface Stability          │Volatile                     │
410       ├─────────────────────────────┼─────────────────────────────┤
411       │MT-Level                     │Safe                         │
412       └─────────────────────────────┴─────────────────────────────┘
413

SEE ALSO

415       libpapi(3LIB), attributes(5)
416
417
418
419SunOS 5.11                        17 Jan 2007          papiPrintersList(3PAPI)
Impressum