PAPI Library Functions papiJobSubmit(3PAPI)
NAME
papiJobSubmit, papiJobSubmitByReference, papiJobValidate,
papiJobStreamOpen, papiJobStreamWrite, papiJobStreamClose,
papiJobQuery, papiJobModify, papiJobMove, papiJobCancel,
papiJobHold, papiJobRelease, papiJobRestart, papiJobPromote,
papiJobGetAttributeList, papiJobGetPrinterName, papi-
JobGetId, papiJobGetJobTicket, papiJobFree, papiJobListFree
- job object manipulation
SYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papistatust papiJobSubmit(papiservicet handle,
char *printer, papiattributet **jobattributes,
papijobtickett *jobticket, char **files,
papijobt *job);
papistatust papiJobSubmitByReference(papiservicet handle,
char *printer, papiattributet **jobattributes,
papijobtickett *jobticket, char **files,
papijobt *job);
papistatust papiJobValidate(papiservicet handle,
char *printer, papiattributet **jobattributes,
papijobtickett *jobticket, char **files,
papijobt *job);
papistatust papiJobStreamOpen(papiservicet handle,
char *printer, papiattributet **jobattributes,
papijobtickett *jobticket, papistreamt *stream);
papistatust papiJobStreamWrite(papiservicet handle,
papistreamt stream, void *buffer, sizet buflen);
papistatust papiJobStreamClose(papiservicet handle,
papistreamt stream, papijobt *job);
papistatust papiJobQuery(papiservicet handle,
char *printer, int32t jobid, char **requestedattrs,
papijobt *job);
papistatust papiJobModify(papiservicet handle,
char *printer, int32t jobid,
papiattributet **attributes, papijobt *job);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiJobSubmit(3PAPI)
papistatust papiJobMove(papiservicet handle,
char *printer, int32t jobid, char *destination);
papistatust papiJobCancel(papiservicet handle,
char *printer, int32t jobid);
papistatust papiJobHold(papiservicet handle,
char *printer, int32t jobid);
papistatust papiJobRelease(papiservicet handle,
char *printer, int32t jobid);
papistatust papiJobRestart(papiservicet handle,
char *printer, int32t jobid);
papistatust papiJobPromote(papiservicet handle,
char *printer, int32t jobid);
papiattributet **papiJobGetAttributeList(papijobt job);
char *papiJobGetPrinterName(papijobt job);
int32t papiJobGetId(papijobt job);
papijobtickett *papiJobGetJobTicket(papijobt job);
void papiJobFree(papijobt job);
void papiJobListFree(papijobt *jobs);
PARAMETERS
attributes a set of attributes to be applied to a
printer object
buffer a buffer of data to be written to the job
stream
SunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiJobSubmit(3PAPI)
bufflen the size of the supplied buffer
destination the name of the printer where a print job
should be relocated, which must reside
within the same print services as the job
is currently queued
files files to use during job submission
handle a pointer to a handle to be used for all
PAPI operations that is created by cal-
ling papiServiceCreate()
job a pointer to a printer object (initial-
ized to NUL) to be filled in by papi-
JobQuery(), papiJobSubmit(), papiJobSub-
mitByReference(), papiJobValidate(),
papiJobStreamClose(), and papiJobModify()
jobattributes attributes to apply during job creation
or modification
jobid ID number of the job reported on or mani-
pulated
jobticket unused
jobs a list of job objects returned by
papiPrinterListJobs() or papiPrinterPur-
geJobs()
printer name of the printer where the job is or
should reside
requestedattrs a null-terminated array of pointers to
attribute names requested during job
enumeration (papiPrinterListJobs()) or
job query (papiJobQuery())
stream a communication endpoint for sending
print job data
SunOS 5.11 Last change: 17 Jan 2007 3
PAPI Library Functions papiJobSubmit(3PAPI)
DESCRIPTION
The papiJobSubmit() function creates a print job containing
the passed in files with the supplied attributes. When the
function returns, the data in the passed files will have
been copied by the print service. A job object is returned
that reflects the state of the job.
The papiJobSubmitByReference() function creates a print job
containing the passed in files with the supplied attributes.
When the function returns, the data in the passed files
might have been copied by the print service. A job object is
returned that reflects the state of the job.
The papiJobStreamOpen(), papiJobStreamWrite(), papiJob-
StreamClose() functions create a print job by opening a
stream, writing to the stream, and closing it.
The papiJobValidate() function validates that the supplied
attributes and files will result in a valid print job.
The papiJobQuery() function retrieves job information from
the print service.
The papiJobModify() function modifies a queued job according
to the attribute list passed into the call. A job object is
returned that reflects the state of the job after the modif-
ication has been applied.
The papiJobMove() function moves a job from its current
queue to the named destination within the same print ser-
vice.
The papiJobCancel() function removes a job from the queue.
The papiJobHold() and papiJobRelease() functions set the job
state to "held" or "idle" to indicate whether the job is
eligible for processing.
The papiJobRestart() function restarts processing of a
currently queued print job.
SunOS 5.11 Last change: 17 Jan 2007 4
PAPI Library Functions papiJobSubmit(3PAPI)
The papiJobGetAttributeList() function returns a list of
attributes describing the job. This list can be searched
and/or enumerated using papiAttributeList*() calls. See
papiAttributeListAddValue(3PAPI).
The papiJobGetPrinterName() function returns the name of the
queue where the job is currently queued.
The papiJobGetId() function returns a job identifier number
from the job object passed in.
The papiJobPromote() function moves a job to the head of the
print queue.
The papiJobGetJobTicket() function retrieves a pointer to a
job ticket associated with the job object.
The papiJobFree() and papiJobListFree() functions deallocate
memory allocated for the return of printer object(s) from
functions that return printer objects.
RETURN VALUES
Upon successful completion, all papiJob*() functions that
return a value return PAPIOK. Otherwise, they return an
appropriate papistatust indicating the type of failure.
Upon successful completion, papiJobGetAttributeList()
returns a pointer to the requested data. Otherwise, it
returns NUL.
EXAMPLES
Example 1 Enumerate all jobs in a queue
/*
* program to enumerate queued jobs using PAPI interfaces.
*/
#include
#include
#include
#include
#include
#include
static int
authCB(papiservicet svc, void *appdata)
{
SunOS 5.11 Last change: 17 Jan 2007 5
PAPI Library Functions papiJobSubmit(3PAPI)
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;
papijobt *jobs = NUL;
char *svcname = NUL;
char *pname = "unknown";
int c;
while ((c = getopt(ac, av, "s:p:")) != EOF)
switch (c) {
case 's':
svcname = optarg;
break;
case 'p':
pname = optarg;
break;
}
status = papiServiceCreate(&svc, svcname, NUL, NUL, authCB,
PAPIENCRYPTNEVER, NUL);
SunOS 5.11 Last change: 17 Jan 2007 6
PAPI Library Functions papiJobSubmit(3PAPI)
if (status != PAPIOK) {
printf("papiServiceCreate(%s): %s0, svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
status = papiPrinterListJobs(svc, pname, NUL, 0, 0, &jobs);
if (status != PAPIOK) {
printf("papiPrinterListJobs(%s): %s0, pname,
papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
if (jobs != NUL) {
int i;
for (i = 0; jobs[i] != NUL; i]) {
papiattributet **list = papiJobGetAttributeList(jobs[i]);
if (list != NUL) {
char *name = "unknown";
int32t id = 0;
char *buffer = NUL;
sizet size = 0;
(void) papiAttributeListGetString(list, NUL,
"printer-name", &name);
(void) papiAttributeListGetInteger(list, NUL,
"job-id", &id);
while (papiAttributeListToString(list, "0", buffer,
size) != PAPIOK)
buffer = realloc(buffer, size ]= BUFSIZ);
printf("%s-%d:0%s0, name, id, buffer);
free(buffer);
}
}
papiJobListFree(jobs);
}
papiServiceDestroy(svc);
exit(0);
}
Example 2 Dump all job attributes.
/*
* program to dump a queued job's attributes using PAPI interfaces.
SunOS 5.11 Last change: 17 Jan 2007 7
PAPI Library Functions papiJobSubmit(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;
papijobt job = NUL;
char *svcname = NUL;
char *pname = "unknown";
int id = 0;
int c;
SunOS 5.11 Last change: 17 Jan 2007 8
PAPI Library Functions papiJobSubmit(3PAPI)
while ((c = getopt(ac, av, "s:p:j:")) != EOF)
switch (c) {
case 's':
svcname = optarg;
break;
case 'p':
pname = optarg;
break;
case 'j':
id = atoi(optarg);
break;
}
status = papiServiceCreate(&svc, svcname, NUL, NUL, authCB,
PAPIENCRYPTNEVER, NUL);
if (status != PAPIOK) {
printf("papiServiceCreate(%s): %s0, svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
status = papiJobQuery(svc, pname, id, NUL, &job);
if ((status == PAPIOK) && (job != NUL)) {
papiattributet **list = papiJobGetAttributeList(job);
if (list != NUL) {
char *name = "unknown";
int32t id = 0;
char *buffer = NUL;
sizet size = 0;
(void) papiAttributeListGetString(list, NUL,
"printer-name", &name);
(void) papiAttributeListGetInteger(list, NUL,
"job-id", &id);
while (papiAttributeListToString(list, "0", buffer, size)
!= PAPIOK)
buffer = realloc(buffer, size ]= BUFSIZ);
printf("%s-%d:0%s0, name, id, buffer);
free(buffer);
}
} else
printf("papiJobQuery(%s-%d): %s0, pname, id,
papiStatusString(status));
papiJobFree(job);
papiServiceDestroy(svc);
exit(0);
SunOS 5.11 Last change: 17 Jan 2007 9
PAPI Library Functions papiJobSubmit(3PAPI)
}
Example 3 Submit a job (stream).
/*
* program to submit a job from standard input.
*/
#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;
SunOS 5.11 Last change: 17 Jan 2007 10
PAPI Library Functions papiJobSubmit(3PAPI)
papiservicet svc = NUL;
papistreamt stream = NUL;
papijobt job = NUL;
papiattributet **attrs = NUL;
char *svcname = NUL;
char *pname = "unknown";
int id = 0;
int c;
int rc;
char buf[BUFSIZ];
while ((c = getopt(ac, av, "s:p:")) != EOF)
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): %s0, svcname ? svcname :
"NUL", papiStatusString(status));
papiServiceDestroy(svc);
exit(1);
}
papiAttributeListAddInteger(&attrs, PAPIATREXCL, "copies", 1);
papiAttributeListAddString(&attrs, PAPIATREXCL,
"document-format", "application/octet-stream");
papiAttributeListAddString(&attrs, PAPIATREXCL,
"job-title", "Standard Input");
status = papiJobStreamOpen(svc, pname, attrs, NUL, &stream);
while ((status == PAPIOK) && ((rc = read(0, buf,
sizeof (buf))) > 0))
status = papiJobStreamWrite(svc, stream, buf, rc);
if (status == PAPIOK)
status = papiJobStreamClose(svc, stream, &job);
if ((status == PAPIOK) && (job != NUL)) {
papiattributet **list = papiJobGetAttributeList(job);
if (list != NUL) {
char *name = "unknown";
int32t id = 0;
SunOS 5.11 Last change: 17 Jan 2007 11
PAPI Library Functions papiJobSubmit(3PAPI)
char *buffer = NUL;
sizet size = 0;
(void) papiAttributeListGetString(list, NUL,
"printer-name", &name);
(void) papiAttributeListGetInteger(list, NUL,
"job-id", &id);
while (papiAttributeListToString(list, "0", buffer, size)
!= PAPIOK)
buffer = realloc(buffer, size ]= BUFSIZ);
printf("%s-%d:0%s0, name, id, buffer);
free(buffer);
}
} else
printf("papiJobStream*(%s-%d): %s0, pname, id,
papiStatusString(status));
papiJobFree(job);
papiServiceDestroy(svc);
exit(0);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Volatile
MT-Level Safe
SEE ALSO
libpapi(3LIB), papiAttributeListAddValue(3PAPI), attri-
butes(5)
SunOS 5.11 Last change: 17 Jan 2007 12
|
