te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
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.
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.
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]
papiPrintersList, papiPrinterQuery, papiPrinterAdd, papiPrinterModify, papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinterPause, papiPrinterResume, papiPrinterPurgeJobs, papiPrinterListJobs, papiPrinterGetAttributeList, papiPrinterFree, papiPrinterListFree - print object manipulation

cc [ flag.\|.\|. ] file.\|.\|. -lpapi [ library.\|.\|. ] 
#include <papi.h>

papi_status_t papiPrintersList(papi_service_t handle,
 char **requested_attrs, papi_filter_t *filter,
 papi_printer_t **printers);

papi_status_t papiPrinterQuery(papi_service_t handle, char *name,
 char **requested_attrs, papi_attribute_t **job_attributes,
 papi_printer_t *printer);

papi_status_t papiPrinterAdd(papi_service_t handle, char *name,
 papi_attribute_t **attributes, papi_printer_t *printer);

papi_status_t papiPrinterModify(papi_service_t handle, char *name,
 papi_attribute_t **attributes, papi_printer_t *printer);

papi_status_t papiPrinterRemove(papi_service_t handle, char *name);

papi_status_t papiPrinterDisable(papi_service_t handle, char *name,
 char *message);

papi_status_t papiPrinterEnable(papi_service_t handle, char *name);

papi_status_t papiPrinterPause(papi_service_t handle, char *name,
 char *message);

papi_status_t papiPrinterResume(papi_service_t handle, char *name);

papi_status_t papiPrinterPurgeJobs(papi_service_t handle, char *name,
 papi_job_t **jobs);

papi_status_t papiPrinterListJobs(papi_service_t handle, char *name,
 char **requested_attrs, int type_mask, int max_num_jobs,
 papi_job_t **jobs);

papi_attribute_t **papiPrinterGetAttributeList(papi_printer_t printer);

void papiPrinterFree(papi_printer_t printer);

void papiPrinterListFree(papi_printer_t *printers);

attributes

filter

handle

job_attributes

jobs

max_num_jobs

message

name

printer

printers

requested_attrs

type_mask

The papiPrintersList() function retrieves the requested attributes from the print service(s) for all available printers. Because the Solaris implementation is name service-enabled, applications should retrieve only the printer-name and printer-uri-supported attributes using this function, thereby reducing the overhead involved in generating a printer list. Further integration of printer state and capabilities can be performed with papiPrinterQuery().

The papiPrinterAdd(), papiPrinterModify(), and papiPrinterRemove() functions allow for creation, modification, and removal of print queues. Print queues are added or modified according to the attribute list passed into the call. A printer object is returned that reflects the configuration of the printer after the addition or modification has been applied. At this time, they provide only minimal functionality and only for the LP print service.

The papiPrinterDisable() and papiPrinterEnable() functions allow applications to turn off and on queueing (accepting print requests) for a print queue. The papiPrinterEnable() and papiPrinterDisable() functions allow applications to turn on and off print job processing for a print queue.

The papiPrinterPause() function stops queueing of print jobs on the named print queue.

The papiPrinterResume() function resumes queueing of print jobs on the named print queue.

The papiPrinterPurgeJobs() function allows applications to delete all print jobs that it has privilege to remove. A list of cancelled jobs is returned in the jobs argument.

The papiPrinterListJobs() function enumerates print jobs on a particular queue. papiPrinterGetAttributeList() retrieves an attribute list from a printer object.

The papiPrinterGetAttributeList() function retrieves an attribute list from a printer object returned from papiPrinterQuery(), papiPrintersList(), papiPrinterModify(), and papiPrinterAdd(). This attribute list can be searched for various information about the printer object.

The papiPrinterFree() and papiPrinterListFree() functions deallocate memory allocated for the return of printer object(s) from functions that return printer objects.

Upon successful completion, all functions that return a value return PAPI_OK. Otherwise, they return an appropriate papi_status_t() indicating the type of failure.

Upon successful completion, papiPrinterGetAttributeList() returns a pointer to the requested data. Otherwise, it returns NULL.

Example 1 Enumerate all available printers.

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <libintl.h>
#include <pwd.h>
#include <papi.h>

static int
authCB(papi_service_t svc, void *app_data)
{
 char prompt[BUFSIZ];
 char *user, *svc_name, *passphrase;

 /* get the name of the service we are contacting */
 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
 return (-1);

 /* find out who we are supposed to be */
 if ((user = papiServiceGetUserName(svc)) == NULL) {
 struct passwd *pw;

 if ((pw = getpwuid(getuid())) != NULL)
 user = pw->pw_name;
 else
 user = "nobody";
 }

 /* build the prompt string */
 snprintf(prompt, sizeof (prompt),
 gettext("passphrase for %s to access %s: "), user,
 svc_name);

 /* ask for the passphrase */
 if ((passphrase = getpassphrase(prompt)) != NULL)
 papiServiceSetPassword(svc, passphrase);

 return (0);
}

/*ARGSUSED*/
int
main(int ac, char *av[])
{
 papi_status_t status;
 papi_service_t svc = NULL;
 papi_printer_t *printers = NULL;
 char *attrs[] = { "printer-name", "printer-uri-supported", NULL };
 char *svc_name = NULL;
 int c;

 while ((c = getopt(ac, av, "s:")) != EOF)
 switch (c) {
 case 's':
 svc_name = optarg;
 break;
 }

 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
 PAPI_ENCRYPT_NEVER, NULL);

 if (status != PAPI_OK) {
 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name :
 "NULL", papiStatusString(status));
 papiServiceDestroy(svc);
 exit(1);
 }

 status = papiPrintersList(svc, attrs, NULL, &printers);
 if (status != PAPI_OK) {
 printf("papiPrintersList(%s): %s\en", svc_name ? svc_name :
 "NULL", papiStatusString(status));
 papiServiceDestroy(svc);
 exit(1);
 }

 if (printers != NULL) {
 int i;

 for (i = 0; printers[i] != NULL; i++) {
 papi_attribute_t **list = 
 papiPrinterGetAttributeList(printers[i]);

 if (list != NULL) {
 char *name = "unknown";
 char *uri = "unknown";

 (void) papiAttributeListGetString(list, NULL,
 "printer-name", &name);

 (void) papiAttributeListGetString(list, NULL,
 "printer-uri-supported", &uri);
 printf("%s is %s\n", name, uri);
 }
 }
 papiPrinterListFree(printers);
 }

 papiServiceDestroy(svc);

 exit(0);
}

Example 2 Dump all printer attributes.

/*
 * program to query a printer for it's attributes via PAPI
 */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <libintl.h>
#include <pwd.h>
#include <papi.h>

static int
authCB(papi_service_t svc, void *app_data)
{
 char prompt[BUFSIZ];
 char *user, *svc_name, *passphrase;

 /* get the name of the service we are contacting */
 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
 return (-1);

 /* find out who we are supposed to be */
 if ((user = papiServiceGetUserName(svc)) == NULL) {
 struct passwd *pw;

 if ((pw = getpwuid(getuid())) != NULL)
 user = pw->pw_name;
 else
 user = "nobody";
 }

 /* build the prompt string */
 snprintf(prompt, sizeof (prompt),
 gettext("passphrase for %s to access %s: "), user,
 svc_name);

 /* ask for the passphrase */
 if ((passphrase = getpassphrase(prompt)) != NULL)
 papiServiceSetPassword(svc, passphrase);

 return (0);
}

/*ARGSUSED*/
int
main(int ac, char *av[])
{
 papi_status_t status;
 papi_service_t svc = NULL;
 papi_printer_t printer = NULL;
 char *svc_name = NULL;
 char *pname = "unknown";
 int c;

 while ((c = getopt(ac, av, "s:p:")) != EOF)
 switch (c) {
 case 's':
 svc_name = optarg;
 break;
 case 'p':
 pname = optarg;
 break;
 }

 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
 PAPI_ENCRYPT_NEVER, NULL);

 if (status != PAPI_OK) {
 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name : 
 "NULL", papiStatusString(status));
 papiServiceDestroy(svc);
 exit(1);
 }

 status = papiPrinterQuery(svc, pname, NULL, NULL, &printer);
 if ((status == PAPI_OK) && (printer != NULL)) {
 papi_attribute_t **list = papiPrinterGetAttributeList(printer);
 char *buffer = NULL;
 size_t size = 0;

 while (papiAttributeListToString(list, "\en\et", buffer, size)
 != PAPI_OK)
 buffer = realloc(buffer, size += BUFSIZ);

 printf("%s:\en\et%s\en", pname, buffer);
 } else
 printf("papiPrinterQuery(%s): %s\en", pname,
 papiStatusString(status));

 papiPrinterFree(printer);
 papiServiceDestroy(svc);

 exit(0);
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Volatile
MT-Level	Safe

libpapi(3LIB), attributes(5)