PAPI Library Functions papiPrintersList(3PAPI)
NAME
papiPrintersList, papiPrinterQuery, papiPrinterAdd,
papiPrinterModify, papiPrinterRemove, papiPrinterDisable,
papiPrinterEnable, papiPrinterPause, papiPrinterResume,
papiPrinterPurgeJobs, papiPrinterListJobs, papiPrinterGetAt-
tributeList, papiPrinterFree, papiPrinterListFree - print
object manipulation
SYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papistatust papiPrintersList(papiservicet handle,
char **requestedattrs, papifiltert *filter,
papiprintert **printers);
papistatust papiPrinterQuery(papiservicet handle, char *name,
char **requestedattrs, papiattributet **jobattributes,
papiprintert *printer);
papistatust papiPrinterAdd(papiservicet handle, char *name,
papiattributet **attributes, papiprintert *printer);
papistatust papiPrinterModify(papiservicet handle, char *name,
papiattributet **attributes, papiprintert *printer);
papistatust papiPrinterRemove(papiservicet handle, char *name);
papistatust papiPrinterDisable(papiservicet handle, char *name,
char *message);
papistatust papiPrinterEnable(papiservicet handle, char *name);
papistatust papiPrinterPause(papiservicet handle, char *name,
char *message);
papistatust papiPrinterResume(papiservicet handle, char *name);
papistatust papiPrinterPurgeJobs(papiservicet handle, char *name,
papijobt **jobs);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiPrintersList(3PAPI)
papistatust papiPrinterListJobs(papiservicet handle, char *name,
char **requestedattrs, int typemask, int maxnumjobs,
papijobt **jobs);
papiattributet **papiPrinterGetAttributeList(papiprintert printer);
void papiPrinterFree(papiprintert printer);
void papiPrinterListFree(papiprintert *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 all
PAPI operations, created by calling pap-
iServiceCreate()
jobattributes unused
jobs a pointer to a list to return job objects
(initialized to NUL) enumerated by
papiPrinterGetJobs()
maxnumjobs 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 on
printer a pointer to a printer object (initial-
ized to NUL) to be filled in by
papiPrinterQuery(), 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 NUL) enumerated
by papiPrintersList()
requestedattrs a null-terminated array of pointers to
attribute names requested during printer
enumeration (papiPrintersList()), printer
query (papiPrinterQuery()), or job
enumeration (papiPrinterListJobs())
typemask a bit field indicating which type of jobs
to return PAPILISTJOBSOTHERS include
jobs submitted by others. The default is
to report only on your own jobs
PAPILISTJOBSCOMPLETED
include completed jobs
PAPILISTJOBSNOTCOMPLETED
include jobs not complete
PAPILISTJOBSAL
report on all jobs
DESCRIPTION
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 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 been
applied. 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 an
attribute list from a printer object returned from papiPrin-
terQuery(), 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.
RETURN VALUES
Upon successful completion, all functions that return a
value return PAPIOK. Otherwise, they return an appropriate
papistatust() indicating the type of failure.
Upon successful completion, papiPrinterGetAttributeList()
returns a pointer to the requested data. Otherwise, it
returns NUL.
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 int
authCB(papiservicet svc, void *appdata)
{
char prompt[BUFSIZ];
char *user, *svcname, *passphrase;
/* get the name of the service we are contacting */
if ((svcname = papiServiceGetServiceName(svc)) == NUL)
return (-1);
/* find out who we are supposed to be */
if ((user = papiServiceGetUserName(svc)) == NUL) {
struct passwd *pw;
if ((pw = getpwuid(getuid())) != NUL)
user = pw->pwname;
else
user = "nobody";
}
/* build the prompt string */
snprintf(prompt, sizeof (prompt),
gettext("passphrase for %s to access %s: "), user,
svcname);
/* ask for the passphrase */
if ((passphrase = getpassphrase(prompt)) != NUL)
papiServiceSetPassword(svc, passphrase);
return (0);
}
/*ARGSUSED*/
int
main(int ac, char *av[])
{
papistatust status;
papiservicet svc = NUL;
papiprintert *printers = NUL;
char *attrs[] = { "printer-name", "printer-uri-supported", NUL };
char *svcname = NUL;
int c;
while ((c = getopt(ac, av, "s:")) != EOF)
switch (c) {
case 's':
svcname = optarg;
break;
SunOS 5.11 Last change: 17 Jan 2007 5
PAPI Library Functions papiPrintersList(3PAPI)
}
status = papiServiceCreate(&svc, svcname, NUL, NUL, authCB,
PAPIENCRYPTNEVER, NUL);
if (status != PAPIOK) {
printf("papiServiceCreate(%s): %s\n", svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
status = papiPrintersList(svc, attrs, NUL, &printers);
if (status != PAPIOK) {
printf("papiPrintersList(%s): %s\n", svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
if (printers != NUL) {
int i;
for (i = 0; printers[i] != NUL; i]) {
papiattributet **list =
papiPrinterGetAttributeList(printers[i]);
if (list != NUL) {
char *name = "unknown";
char *uri = "unknown";
(void) papiAttributeListGetString(list, NUL,
"printer-name", &name);
(void) papiAttributeListGetString(list, NUL,
"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 PAPI
SunOS 5.11 Last change: 17 Jan 2007 6
PAPI Library Functions papiPrintersList(3PAPI)
*/
#include
#include
#include
#include
#include
#include
static int
authCB(papiservicet svc, void *appdata)
{
char prompt[BUFSIZ];
char *user, *svcname, *passphrase;
/* get the name of the service we are contacting */
if ((svcname = papiServiceGetServiceName(svc)) == NUL)
return (-1);
/* find out who we are supposed to be */
if ((user = papiServiceGetUserName(svc)) == NUL) {
struct passwd *pw;
if ((pw = getpwuid(getuid())) != NUL)
user = pw->pwname;
else
user = "nobody";
}
/* build the prompt string */
snprintf(prompt, sizeof (prompt),
gettext("passphrase for %s to access %s: "), user,
svcname);
/* ask for the passphrase */
if ((passphrase = getpassphrase(prompt)) != NUL)
papiServiceSetPassword(svc, passphrase);
return (0);
}
/*ARGSUSED*/
int
main(int ac, char *av[])
{
papistatust status;
papiservicet svc = NUL;
papiprintert printer = NUL;
char *svcname = NUL;
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':
svcname = optarg;
break;
case 'p':
pname = optarg;
break;
}
status = papiServiceCreate(&svc, svcname, NUL, NUL, authCB,
PAPIENCRYPTNEVER, NUL);
if (status != PAPIOK) {
printf("papiServiceCreate(%s): %s\n", svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
status = papiPrinterQuery(svc, pname, NUL, NUL, &printer);
if ((status == PAPIOK) && (printer != NUL)) {
papiattributet **list = papiPrinterGetAttributeList(printer);
char *buffer = NUL;
sizet size = 0;
while (papiAttributeListToString(list, "\n\t", buffer, size)
!= PAPIOK)
buffer = realloc(buffer, size ]= BUFSIZ);
printf("%s:\n\t%s\n", pname, buffer);
} else
printf("papiPrinterQuery(%s): %s\n", pname,
papiStatusString(status));
papiPrinterFree(printer);
papiServiceDestroy(svc);
exit(0);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 17 Jan 2007 8
PAPI Library Functions papiPrintersList(3PAPI)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Volatile
MT-Level Safe
SEE ALSO
libpapi(3LIB), attributes(5)
SunOS 5.11 Last change: 17 Jan 2007 9
|
