usr/src/man/man3papi/papiPrintersList.3papi

   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 "Sep 10, 2013"
   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\en", 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)