PAPI Library Functions papiPrintersList(3PAPI)
NAME
papiPrintersList, papiPrinterQuery, papiPrinterAdd,
papiPrinterModify, papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinterPause, papiPrinterResume,papiPrinterPurgeJobs, papiPrinterListJobs, papiPrinterGetAt-
tributeList, papiPrinterFree, papiPrinterListFree - print
object manipulationSYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
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);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiPrintersList(3PAPI)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);
PARAMETERS
attributes a set of attributes to be applied to a printer object filter a filter to be applied during printer enumeration handle a pointer to a handle to be used for allPAPI operations, created by calling pap-
iServiceCreate()job_attributes unused
jobs a pointer to a list to return job objects (initialized to NULL) enumerated by papiPrinterGetJobs()max_num_jobs the maximum number of jobs to return from
a papiPrinterGetJobs() request message a message to be associated with a printer while disabled or paused name the name of the printer object being operated onprinter a pointer to a printer object (initial-
ized to NULL) to be filled in bypapiPrinterQuery(), papiPrinterAdd(), and
papiPrinterModify()SunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiPrintersList(3PAPI) printers a pointer to a list to return printer objects (initialized to NULL) enumerated by papiPrintersList()requested_attrs a null-terminated array of pointers to
attribute names requested during printer enumeration (papiPrintersList()), printer query (papiPrinterQuery()), or job enumeration (papiPrinterListJobs())type_mask a bit field indicating which type of jobs
to return PAPI_LIST_JOBS_OTHERS include
jobs submitted by others. The default is to report only on your own jobsPAPI_LIST_JOBS_COMPLETED
include completed jobsPAPI_LIST_JOBS_NOT_COMPLETED
include jobs not completePAPI_LIST_JOBS_ALL
report on all jobsDESCRIPTION
The papiPrintersList() function retrieves the requested attributes from the print service(s) for all available printers. Because the Solaris implementation is nameservice-enabled, applications should retrieve only the
printer-name and printer-uri-supported attributes using this
function, thereby reducing the overhead involved in generat-
ing a printer list. Further integration of printer state and capabilities can be performed with papiPrinterQuery().The papiPrinterAdd(), papiPrinterModify(), and papiPrinter-
Remove() 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 beenapplied. At this time, they provide only minimal func-
tionality and only for the LP print service.SunOS 5.11 Last change: 17 Jan 2007 3
PAPI Library Functions papiPrintersList(3PAPI) 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 anattribute list from a printer object returned from papiPrin-
terQuery(), papiPrintersList(), papiPrinterModify(), andpapiPrinterAdd(). 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.RETURN VALUES
Upon successful completion, all functions that return avalue 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.EXAMPLES
Example 1 Enumerate all available printers.#include
#include
#include
SunOS 5.11 Last change: 17 Jan 2007 4
PAPI Library Functions papiPrintersList(3PAPI)#include
#include
#include
static intauthCB(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;SunOS 5.11 Last change: 17 Jan 2007 5
PAPI Library Functions papiPrintersList(3PAPI) }status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
PAPI_ENCRYPT_NEVER, NULL);
if (status != PAPI_OK) {
printf("papiServiceCreate(%s): %s\n", 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\n", 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 %s0, name, uri);
} } papiPrinterListFree(printers); } papiServiceDestroy(svc); exit(0); } Example 2 Dump all printer attributes. /* * program to query a printer for it's attributes via PAPISunOS 5.11 Last change: 17 Jan 2007 6
PAPI Library Functions papiPrintersList(3PAPI) */#include
#include
#include
#include
#include
#include
static intauthCB(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)SunOS 5.11 Last change: 17 Jan 2007 7
PAPI Library Functions papiPrintersList(3PAPI) 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\n", 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, "\n\t", buffer, size)!= PAPI_OK)
buffer = realloc(buffer, size += BUFSIZ);printf("%s:\n\t%s\n", pname, buffer);
} elseprintf("papiPrinterQuery(%s): %s\n", pname,
papiStatusString(status)); papiPrinterFree(printer); papiServiceDestroy(svc); exit(0); }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 17 Jan 2007 8
PAPI Library Functions papiPrintersList(3PAPI)____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Volatile ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libpapi(3LIB), attributes(5)SunOS 5.11 Last change: 17 Jan 2007 9