1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PAPIPRINTERSLIST 3PAPI "Jan 17, 2007"
7 .SH NAME
8 papiPrintersList, papiPrinterQuery, papiPrinterAdd, papiPrinterModify,
9 papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinterPause,
10 papiPrinterResume, papiPrinterPurgeJobs, papiPrinterListJobs,
11 papiPrinterGetAttributeList, papiPrinterFree, papiPrinterListFree \- print
12 object manipulation
13 .SH SYNOPSIS
14 .LP
15 .nf
16 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ]
17 #include <papi.h>
18
19 \fBpapi_status_t\fR \fBpapiPrintersList\fR(\fBpapi_service_t\fR \fIhandle\fR,
20 \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_filter_t *\fR\fIfilter\fR,
21 \fBpapi_printer_t **\fR\fIprinters\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBpapi_status_t\fR \fBpapiPrinterQuery\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
27 \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR,
28 \fBpapi_printer_t *\fR\fIprinter\fR);
29 .fi
30
31 .LP
32 .nf
33 \fBpapi_status_t\fR \fBpapiPrinterAdd\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
34 \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR);
35 .fi
36
37 .LP
38 .nf
39 \fBpapi_status_t\fR \fBpapiPrinterModify\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
40 \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR);
41 .fi
42
43 .LP
44 .nf
45 \fBpapi_status_t\fR \fBpapiPrinterRemove\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
46 .fi
47
48 .LP
49 .nf
50 \fBpapi_status_t\fR \fBpapiPrinterDisable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
51 \fBchar *\fR\fImessage\fR);
52 .fi
53
54 .LP
55 .nf
56 \fBpapi_status_t\fR \fBpapiPrinterEnable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
57 .fi
58
59 .LP
60 .nf
61 \fBpapi_status_t\fR \fBpapiPrinterPause\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
62 \fBchar *\fR\fImessage\fR);
63 .fi
64
65 .LP
66 .nf
67 \fBpapi_status_t\fR \fBpapiPrinterResume\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
68 .fi
69
70 .LP
71 .nf
72 \fBpapi_status_t\fR \fBpapiPrinterPurgeJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
73 \fBpapi_job_t **\fR\fIjobs\fR);
74 .fi
75
76 .LP
77 .nf
78 \fBpapi_status_t\fR \fBpapiPrinterListJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
79 \fBchar **\fR\fIrequested_attrs\fR, \fBint\fR \fItype_mask\fR, \fBint\fR \fImax_num_jobs\fR,
80 \fBpapi_job_t **\fR\fIjobs\fR);
81 .fi
82
83 .LP
84 .nf
85 \fBpapi_attribute_t **\fR\fBpapiPrinterGetAttributeList\fR(\fBpapi_printer_t\fR \fIprinter\fR);
86 .fi
87
88 .LP
89 .nf
90 \fBvoid\fR \fBpapiPrinterFree\fR(\fBpapi_printer_t\fR \fIprinter\fR);
91 .fi
92
93 .LP
94 .nf
95 \fBvoid\fR \fBpapiPrinterListFree\fR(\fBpapi_printer_t *\fR\fIprinters\fR);
96 .fi
97
98 .SH PARAMETERS
99 .sp
100 .ne 2
101 .na
102 \fB\fIattributes\fR\fR
103 .ad
104 .RS 19n
105 a set of attributes to be applied to a printer object
106 .RE
107
108 .sp
109 .ne 2
110 .na
111 \fB\fIfilter\fR\fR
112 .ad
113 .RS 19n
114 a filter to be applied during printer enumeration
115 .RE
116
117 .sp
118 .ne 2
119 .na
120 \fB\fIhandle\fR\fR
121 .ad
122 .RS 19n
123 a pointer to a handle to be used for all PAPI operations, created by calling
124 \fBpapiServiceCreate()\fR
125 .RE
126
127 .sp
128 .ne 2
129 .na
130 \fB\fIjob_attributes\fR\fR
131 .ad
132 .RS 19n
133 unused
134 .RE
135
136 .sp
137 .ne 2
138 .na
139 \fB\fIjobs\fR\fR
140 .ad
141 .RS 19n
142 a pointer to a list to return job objects (initialized to \fINULL\fR)
143 enumerated by \fBpapiPrinterGetJobs()\fR
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fImax_num_jobs\fR\fR
150 .ad
151 .RS 19n
152 the maximum number of jobs to return from a \fBpapiPrinterGetJobs()\fR request
153 .RE
154
155 .sp
156 .ne 2
157 .na
158 \fB\fImessage\fR\fR
159 .ad
160 .RS 19n
161 a message to be associated with a printer while disabled or paused
162 .RE
163
164 .sp
165 .ne 2
166 .na
167 \fB\fIname\fR\fR
168 .ad
169 .RS 19n
170 the name of the printer object being operated on
171 .RE
172
173 .sp
174 .ne 2
175 .na
176 \fB\fIprinter\fR\fR
177 .ad
178 .RS 19n
179 a pointer to a printer object (initialized to \fINULL\fR) to be filled in by
180 \fBpapiPrinterQuery()\fR, \fBpapiPrinterAdd()\fR, and \fBpapiPrinterModify()\fR
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fB\fIprinters\fR\fR
187 .ad
188 .RS 19n
189 a pointer to a list to return printer objects (initialized to \fINULL\fR)
190 enumerated by \fBpapiPrintersList()\fR
191 .RE
192
193 .sp
194 .ne 2
195 .na
196 \fB\fIrequested_attrs\fR\fR
197 .ad
198 .RS 19n
199 a null-terminated array of pointers to attribute names requested during printer
200 enumeration (\fBpapiPrintersList()\fR), printer query
201 (\fBpapiPrinterQuery()\fR), or job enumeration (\fBpapiPrinterListJobs()\fR)
202 .RE
203
204 .sp
205 .ne 2
206 .na
207 \fB\fItype_mask\fR\fR
208 .ad
209 .RS 19n
210 a bit field indicating which type of jobs to return \fBPAPI_LIST_JOBS_OTHERS\fR
211 include jobs submitted by others. The default is to report only on your own
212 jobs
213 .sp
214 .ne 2
215 .na
216 \fB\fBPAPI_LIST_JOBS_COMPLETED\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 include completed jobs
221 .RE
222
223 .sp
224 .ne 2
225 .na
226 \fB\fBPAPI_LIST_JOBS_NOT_COMPLETED\fR\fR
227 .ad
228 .sp .6
229 .RS 4n
230 include jobs not complete
231 .RE
232
233 .sp
234 .ne 2
235 .na
236 \fB\fBPAPI_LIST_JOBS_ALL\fR\fR
237 .ad
238 .sp .6
239 .RS 4n
240 report on all jobs
241 .RE
242
243 .RE
244
245 .SH DESCRIPTION
246 .sp
247 .LP
248 The \fBpapiPrintersList()\fR function retrieves the requested attributes from
249 the print service(s) for all available printers. Because the Solaris
250 implementation is name service-enabled, applications should retrieve only the
251 \fBprinter-name\fR and \fBprinter-uri-supported\fR attributes using this
252 function, thereby reducing the overhead involved in generating a printer list.
253 Further integration of printer state and capabilities can be performed with
254 \fBpapiPrinterQuery()\fR.
255 .sp
256 .LP
257 The \fBpapiPrinterAdd()\fR, \fBpapiPrinterModify()\fR, and
258 \fBpapiPrinterRemove()\fR functions allow for creation, modification, and
259 removal of print queues. Print queues are added or modified according to the
260 attribute list passed into the call. A printer object is returned that reflects
261 the configuration of the printer after the addition or modification has been
262 applied. At this time, they provide only minimal functionality and only for
263 the LP print service.
264 .sp
265 .LP
266 The \fBpapiPrinterDisable()\fR and \fBpapiPrinterEnable()\fR functions allow
267 applications to turn off and on queueing (accepting print requests) for a print
268 queue. The \fBpapiPrinterEnable()\fR and \fBpapiPrinterDisable()\fR functions
269 allow applications to turn on and off print job processing for a print queue.
270 .sp
271 .LP
272 The \fBpapiPrinterPause()\fR function stops queueing of print jobs on the named
273 print queue.
274 .sp
275 .LP
276 The \fBpapiPrinterResume()\fR function resumes queueing of print jobs on the
277 named print queue.
278 .sp
279 .LP
280 The \fBpapiPrinterPurgeJobs()\fR function allows applications to delete all
281 print jobs that it has privilege to remove. A list of cancelled jobs is
282 returned in the jobs argument.
283 .sp
284 .LP
285 The \fBpapiPrinterListJobs()\fR function enumerates print jobs on a particular
286 queue. \fBpapiPrinterGetAttributeList()\fR retrieves an attribute list from a
287 printer object.
288 .sp
289 .LP
290 The \fBpapiPrinterGetAttributeList()\fR function retrieves an attribute list
291 from a printer object returned from \fBpapiPrinterQuery()\fR,
292 \fBpapiPrintersList()\fR, \fBpapiPrinterModify()\fR, and
293 \fBpapiPrinterAdd()\fR. This attribute list can be searched for various
294 information about the printer object.
295 .sp
296 .LP
297 The \fBpapiPrinterFree()\fR and \fBpapiPrinterListFree()\fR functions
298 deallocate memory allocated for the return of printer object(s) from functions
299 that return printer objects.
300 .SH RETURN VALUES
301 .sp
302 .LP
303 Upon successful completion, all functions that return a value return
304 \fBPAPI_OK\fR. Otherwise, they return an appropriate \fBpapi_status_t()\fR
305 indicating the type of failure.
306 .sp
307 .LP
308 Upon successful completion, \fBpapiPrinterGetAttributeList()\fR returns a
309 pointer to the requested data. Otherwise, it returns \fINULL\fR.
310 .SH EXAMPLES
311 .LP
312 \fBExample 1 \fREnumerate all available printers.
313 .sp
314 .in +2
315 .nf
316 #include <stdio.h>
317 #include <stdlib.h>
318 #include <unistd.h>
319 #include <libintl.h>
320 #include <pwd.h>
321 #include <papi.h>
322
323 static int
324 authCB(papi_service_t svc, void *app_data)
325 {
326 char prompt[BUFSIZ];
327 char *user, *svc_name, *passphrase;
328
329 /* get the name of the service we are contacting */
330 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
331 return (-1);
332
333 /* find out who we are supposed to be */
334 if ((user = papiServiceGetUserName(svc)) == NULL) {
335 struct passwd *pw;
336
337 if ((pw = getpwuid(getuid())) != NULL)
338 user = pw->pw_name;
339 else
340 user = "nobody";
341 }
342
343 /* build the prompt string */
344 snprintf(prompt, sizeof (prompt),
345 gettext("passphrase for %s to access %s: "), user,
346 svc_name);
347
348 /* ask for the passphrase */
349 if ((passphrase = getpassphrase(prompt)) != NULL)
350 papiServiceSetPassword(svc, passphrase);
351
352 return (0);
353 }
354
355 /*ARGSUSED*/
356 int
357 main(int ac, char *av[])
358 {
359 papi_status_t status;
360 papi_service_t svc = NULL;
361 papi_printer_t *printers = NULL;
362 char *attrs[] = { "printer-name", "printer-uri-supported", NULL };
363 char *svc_name = NULL;
364 int c;
365
366 while ((c = getopt(ac, av, "s:")) != EOF)
367 switch (c) {
368 case 's':
369 svc_name = optarg;
370 break;
371 }
372
373 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
374 PAPI_ENCRYPT_NEVER, NULL);
375
376 if (status != PAPI_OK) {
377 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name :
378 "NULL", papiStatusString(status));
379 papiServiceDestroy(svc);
380 exit(1);
381 }
382
383 status = papiPrintersList(svc, attrs, NULL, &printers);
384 if (status != PAPI_OK) {
385 printf("papiPrintersList(%s): %s\en", svc_name ? svc_name :
386 "NULL", papiStatusString(status));
387 papiServiceDestroy(svc);
388 exit(1);
389 }
390
391 if (printers != NULL) {
392 int i;
393
394 for (i = 0; printers[i] != NULL; i++) {
395 papi_attribute_t **list =
396 papiPrinterGetAttributeList(printers[i]);
397
398 if (list != NULL) {
399 char *name = "unknown";
400 char *uri = "unknown";
401
402 (void) papiAttributeListGetString(list, NULL,
403 "printer-name", &name);
404
405 (void) papiAttributeListGetString(list, NULL,
406 "printer-uri-supported", &uri);
407 printf("%s is %s\n", name, uri);
408 }
409 }
410 papiPrinterListFree(printers);
411 }
412
413 papiServiceDestroy(svc);
414
415 exit(0);
416 }
417 .fi
418 .in -2
419
420 .LP
421 \fBExample 2 \fRDump all printer attributes.
422 .sp
423 .in +2
424 .nf
425 /*
426 * program to query a printer for it's attributes via PAPI
427 */
428 #include <stdio.h>
429 #include <stdlib.h>
430 #include <unistd.h>
431 #include <libintl.h>
432 #include <pwd.h>
433 #include <papi.h>
434
435 static int
436 authCB(papi_service_t svc, void *app_data)
437 {
438 char prompt[BUFSIZ];
439 char *user, *svc_name, *passphrase;
440
441 /* get the name of the service we are contacting */
442 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
443 return (-1);
444
445 /* find out who we are supposed to be */
446 if ((user = papiServiceGetUserName(svc)) == NULL) {
447 struct passwd *pw;
448
449 if ((pw = getpwuid(getuid())) != NULL)
450 user = pw->pw_name;
451 else
452 user = "nobody";
453 }
454
455 /* build the prompt string */
456 snprintf(prompt, sizeof (prompt),
457 gettext("passphrase for %s to access %s: "), user,
458 svc_name);
459
460 /* ask for the passphrase */
461 if ((passphrase = getpassphrase(prompt)) != NULL)
462 papiServiceSetPassword(svc, passphrase);
463
464 return (0);
465 }
466
467 /*ARGSUSED*/
468 int
469 main(int ac, char *av[])
470 {
471 papi_status_t status;
472 papi_service_t svc = NULL;
473 papi_printer_t printer = NULL;
474 char *svc_name = NULL;
475 char *pname = "unknown";
476 int c;
477
478 while ((c = getopt(ac, av, "s:p:")) != EOF)
479 switch (c) {
480 case 's':
481 svc_name = optarg;
482 break;
483 case 'p':
484 pname = optarg;
485 break;
486 }
487
488 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
489 PAPI_ENCRYPT_NEVER, NULL);
490
491 if (status != PAPI_OK) {
492 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name :
493 "NULL", papiStatusString(status));
494 papiServiceDestroy(svc);
495 exit(1);
496 }
497
498 status = papiPrinterQuery(svc, pname, NULL, NULL, &printer);
499 if ((status == PAPI_OK) && (printer != NULL)) {
500 papi_attribute_t **list = papiPrinterGetAttributeList(printer);
501 char *buffer = NULL;
502 size_t size = 0;
503
504 while (papiAttributeListToString(list, "\en\et", buffer, size)
505 != PAPI_OK)
506 buffer = realloc(buffer, size += BUFSIZ);
507
508 printf("%s:\en\et%s\en", pname, buffer);
509 } else
510 printf("papiPrinterQuery(%s): %s\en", pname,
511 papiStatusString(status));
512
513 papiPrinterFree(printer);
514 papiServiceDestroy(svc);
515
516 exit(0);
517 }
518 .fi
519 .in -2
520
521 .SH ATTRIBUTES
522 .sp
523 .LP
524 See \fBattributes\fR(5) for descriptions of the following attributes:
525 .sp
526
527 .sp
528 .TS
529 box;
530 c | c
531 l | l .
532 ATTRIBUTE TYPE ATTRIBUTE VALUE
533 _
534 Interface Stability Volatile
535 _
536 MT-Level Safe
537 .TE
538
539 .SH SEE ALSO
540 .sp
541 .LP
542 \fBlibpapi\fR(3LIB), \fBattributes\fR(5)