1papiPrintersList(3PAPI) PAPI Library Functions papiPrintersList(3PAPI)
2
6 papiPrintersList, papiPrinterQuery, papiPrinterAdd, papiPrinterModify,
7 papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinter‐
8 Pause, papiPrinterResume, papiPrinterPurgeJobs, papiPrinterListJobs,
9 papiPrinterGetAttributeList, papiPrinterFree, papiPrinterListFree -
10 print object manipulation
11
13 cc [ flag... ] file... -lpapi [ library... ]
14 #include <papi.h>
15 papi_status_t papiPrintersList(papi_service_t handle,
17 char **requested_attrs, papi_filter_t *filter,
18 papi_printer_t **printers);
19 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 papi_status_t papiPrinterAdd(papi_service_t handle, char *name,
27 papi_attribute_t **attributes, papi_printer_t *printer);
28 papi_status_t papiPrinterModify(papi_service_t handle, char *name,
31 papi_attribute_t **attributes, papi_printer_t *printer);
32 papi_status_t papiPrinterRemove(papi_service_t handle, char *name);
35 papi_status_t papiPrinterDisable(papi_service_t handle, char *name,
38 char *message);
39 papi_status_t papiPrinterEnable(papi_service_t handle, char *name);
42 papi_status_t papiPrinterPause(papi_service_t handle, char *name,
45 char *message);
46 papi_status_t papiPrinterResume(papi_service_t handle, char *name);
49 papi_status_t papiPrinterPurgeJobs(papi_service_t handle, char *name,
52 papi_job_t **jobs);
53 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 papi_attribute_t **papiPrinterGetAttributeList(papi_printer_t printer);
61 void papiPrinterFree(papi_printer_t printer);
64 void papiPrinterListFree(papi_printer_t *printers);
67
70 attributes a set of attributes to be applied to a printer
71 object
72 filter a filter to be applied during printer enumeration
75 handle a pointer to a handle to be used for all PAPI opera‐
78 tions, created by calling papiServiceCreate()
79 job_attributes unused
82 jobs a pointer to a list to return job objects (initial‐
85 ized to NULL) enumerated by papiPrinterGetJobs()
86 max_num_jobs the maximum number of jobs to return from a
89 papiPrinterGetJobs() request
90 message a message to be associated with a printer while dis‐
93 abled or paused
94 name the name of the printer object being operated on
97 printer a pointer to a printer object (initialized to NULL)
100 to be filled in by papiPrinterQuery(), papiPrinter‐
101 Add(), and papiPrinterModify()
102 printers a pointer to a list to return printer objects (ini‐
105 tialized to NULL) enumerated by papiPrintersList()
106 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 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 PAPI_LIST_JOBS_COMPLETED
119 include completed jobs
121 PAPI_LIST_JOBS_NOT_COMPLETED
124 include jobs not complete
126 PAPI_LIST_JOBS_ALL
129 report on all jobs
131
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 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 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 The papiPrinterPause() function stops queueing of print jobs on the
161 named print queue.
162 The papiPrinterResume() function resumes queueing of print jobs on the
165 named print queue.
166 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 The papiPrinterListJobs() function enumerates print jobs on a particu‐
174 lar queue. papiPrinterGetAttributeList() retrieves an attribute list
175 from a printer object.
176 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 The papiPrinterFree() and papiPrinterListFree() functions deallocate
185 memory allocated for the return of printer object(s) from functions
186 that return printer objects.
187
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 Upon successful completion, papiPrinterGetAttributeList() returns a
195 pointer to the requested data. Otherwise, it returns NULL.
196
198 Example 1 Enumerate all available printers.
199 #include <stdio.h>
201 #include <stdlib.h>
202 #include <unistd.h>
203 #include <libintl.h>
204 #include <pwd.h>
205 #include <papi.h>
206 static int
208 authCB(papi_service_t svc, void *app_data)
209 {
210 char prompt[BUFSIZ];
211 char *user, *svc_name, *passphrase;
212 /* get the name of the service we are contacting */
214 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
215 return (-1);
216 /* find out who we are supposed to be */
218 if ((user = papiServiceGetUserName(svc)) == NULL) {
219 struct passwd *pw;
220 if ((pw = getpwuid(getuid())) != NULL)
222 user = pw->pw_name;
223 else
224 user = "nobody";
225 }
226 /* build the prompt string */
228 snprintf(prompt, sizeof (prompt),
229 gettext("passphrase for %s to access %s: "), user,
230 svc_name);
231 /* ask for the passphrase */
233 if ((passphrase = getpassphrase(prompt)) != NULL)
234 papiServiceSetPassword(svc, passphrase);
235 return (0);
237 }
238 /*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 while ((c = getopt(ac, av, "s:")) != EOF)
251 switch (c) {
252 case 's':
253 svc_name = optarg;
254 break;
255 }
256 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
258 PAPI_ENCRYPT_NEVER, NULL);
259 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 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 if (printers != NULL) {
276 int i;
277 for (i = 0; printers[i] != NULL; i++) {
279 papi_attribute_t **list =
280 papiPrinterGetAttributeList(printers[i]);
281 if (list != NULL) {
283 char *name = "unknown";
284 char *uri = "unknown";
285 (void) papiAttributeListGetString(list, NULL,
287 "printer-name", &name);
288 (void) papiAttributeListGetString(list, NULL,
290 "printer-uri-supported", &uri);
291 printf("%s is %s0, name, uri);
292 }
293 }
294 papiPrinterListFree(printers);
295 }
296 papiServiceDestroy(svc);
298 exit(0);
300 }
301 Example 2 Dump all printer attributes.
304 /*
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 static int
316 authCB(papi_service_t svc, void *app_data)
317 {
318 char prompt[BUFSIZ];
319 char *user, *svc_name, *passphrase;
320 /* get the name of the service we are contacting */
322 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
323 return (-1);
324 /* find out who we are supposed to be */
326 if ((user = papiServiceGetUserName(svc)) == NULL) {
327 struct passwd *pw;
328 if ((pw = getpwuid(getuid())) != NULL)
330 user = pw->pw_name;
331 else
332 user = "nobody";
333 }
334 /* build the prompt string */
336 snprintf(prompt, sizeof (prompt),
337 gettext("passphrase for %s to access %s: "), user,
338 svc_name);
339 /* ask for the passphrase */
341 if ((passphrase = getpassphrase(prompt)) != NULL)
342 papiServiceSetPassword(svc, passphrase);
343 return (0);
345 }
346 /*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 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 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
369 PAPI_ENCRYPT_NEVER, NULL);
370 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 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 while (papiAttributeListToString(list, "\n\t", buffer, size)
385 != PAPI_OK)
386 buffer = realloc(buffer, size += BUFSIZ);
387 printf("%s:\n\t%s\n", pname, buffer);
389 } else
390 printf("papiPrinterQuery(%s): %s\n", pname,
391 papiStatusString(status));
392 papiPrinterFree(printer);
394 papiServiceDestroy(svc);
395 exit(0);
397 }
398
401 See attributes(5) for descriptions of the following attributes:
402 ┌─────────────────────────────┬─────────────────────────────┐
407 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
408 ├─────────────────────────────┼─────────────────────────────┤
409 │Interface Stability │Volatile │
410 ├─────────────────────────────┼─────────────────────────────┤
411 │MT-Level │Safe │
412 └─────────────────────────────┴─────────────────────────────┘
413
415 libpapi(3LIB), attributes(5)
416SunOS 5.11 17 Jan 2007 papiPrintersList(3PAPI)