Open Standard Print API (PAPI)

Version 0.92

Alan Hlava
IBM Printing Systems Division
Norm Jacobs
Sun Microsystems, Inc.
Michael R. Sweet
Easy Software Products

Open Standard Print API (PAPI): Version 0.92

by Alan Hlava, Norm Jacobs, and Michael R. Sweet

Version 0.92 Edition

Copyright © 2002-2005 Free Standards Group

Permission to use, copy, modify and distribute this document for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies.

Table of Contents

Chapter 1: Introduction	6

Chapter 2: Print System Model	7

2.1 Introduction	7

2.2 Model	7

2.3 Security	8

2.4 Globalization	9

Chapter 3: Common Structures	10

3.1 Conventions	10

3.2 Service Object (papi_service_t)	10

3.3 Attributes and Values (papi_attribute_t)	10

3.4 Job Object (papi_job_t)	12

3.5 Stream Object (papi_stream_t)	12

3.6 Printer Object (papi_printer_t)	12

3.7 Job Ticket (papi_job_ticket_t)	12

3.8 Status (papi_status_t)	13

3.9 List Filter (papi_filter_t)	14

3.10 Encryption (papi_encrypt_t)	16

Chapter 4: Attributes API	17

4.1 papiAttributeListAdd	18

4.2 papiAttributeListAddString	19

4.3 papiAttributeListAddInteger	20

4.4 papiAttributeListAddBoolean	22

4.5 papiAttributeListAddRange	23

4.6 papiAttributeListAddResolution	24

4.7 papiAttributeListAddDatetime	26

4.8 papiAttributeListAddCollection	27

4.9 papiAttributeListAddMetadata	28

4.10 papiAttributeListDelete	30

4.11 papiAttributeListGetValue	31

4.12 papiAttributeListGetString	32

4.13 papiAttributeListGetInteger	34

4.14 papiAttributeListGetBoolean	35

4.15 papiAttributeListGetRange	36

4.16 papiAttributeListGetResolution	38

4.17 papiAttributeListGetDatetime	39

4.18 papiAttributeListGetCollection	41

4.19 papiAttributeListGetMetadata	42

4.20 papiAttributeListFree	43

4.21 papiAttributeListFind	44

4.22 papiAttributeListGetNext	45

4.23 papiAttributeListFromString	46

4.24 papiAttributeListToString	47

Chapter 5: Service API	50

5.1 papiServiceCreate	50

5.2 papiServiceDestroy	52

5.3 papiServiceSetUserName	52

5.4 papiServiceSetPassword	54

5.5 papiServiceSetEncryption	55

5.6 papiServiceSetAuthCB	56

5.7 papiServiceSetAppData	57

5.8 papiServiceGetServiceName	58

5.9 papiServiceGetUserName	59

5.10 papiServiceGetPassword	59

5.11 papiServiceGetEncryption	60

5.12 papiServiceGetAppData	61

5.13 papiServiceGetAttributeList	62

5.14 papiServiceGetStatusMessage	63

Chapter 6: Printer API	65

6.1 papiPrintersList	65

6.2 papiPrinterQuery	67

6.3 papiPrinterModify	69

6.4 papiPrinterAdd	70

6.5 papiPrinterRemove	72

6.6 papiPrinterPause	73

6.7 papiPrinterResume	74

6.8 papiPrinterEnable	75

6.9 papiPrinterDisable	76

6.10 papiPrinterPurgeJobs	77

6.11 papiPrinterListJobs	79

6.12 papiPrinterGetAttributeList	81

6.13 papiPrinterFree	82

6.14 papiPrinterListFree	82

Chapter 7: Job API	84

7.1 papiJobSubmit	84

7.2 papiJobSubmitByReference	86

7.3 papiJobValidate	88

7.4 papiJobStreamOpen	90

7.5 papiJobStreamWrite	92

7.6 papiJobStreamClose	93

7.7 papiJobQuery	94

7.8 papiJobModify	96

7.9 papiJobCancel	97

7.10 papiJobHold	98

7.11 papiJobRelease	99

7.12 papiJobRestart	100

7.13 papiJobPromote	101

7.14 papiJobGetAttributeList	103

7.15 papiJobGetPrinterName	104

7.16 papiJobGetId	104

7.17 papiJobGetJobTicket	105

7.18 papiJobFree	106

7.19 papiJobListFree	107

Chapter 8: Miscellaneous API	108

8.1 papiStatusString	108

8.2 papiLibrarySupportedCalls	108

8.3 papiLibrarySupportedCall	109

Chapter 9: Capabilities	111

9.1 Introduction	111

9.2 Objectives	112

9.3 Interfaces	113

Chapter 10: Attributes	117

10.1 Extension Attributes	117

10.2 Required Job Attributes	117

10.3 Required Printer Attributes	118

10.4 IPP Attribute Type Mapping	118

Chapter 11: Attribute List Text Representation	120

11.1 ABNF Definition	120

11.2 Examples	121

Chapter 12: Conformance	123

12.1 Query Profile	123

12.2 Job Submission Profile	123

12.3 Conformance Table	123

Chapter 13: Sample Code	127

Chapter 14: References	128

14.1 Internet Printing Protocol (IPP)	128

14.2 Job Ticket	128

14.3 Printer Working Group (PWG)	128

14.4 Other	128

Chapter 15: Change History	129

15.1 Version 0.91 (January 28, 2004).	129

15.2 Version 0.9 (November 18, 2002).	129

15.3 Version 0.8 (November 15, 2002).	129

15.4 Version 0.7 (October 18, 2002).	129

15.5 Version 0.6 (September 20, 2002)	130

15.6 Version 0.5 (August 30, 2002).	131

15.7 Version 0.4 (July 19, 2002).	131

15.8 Version 0.3 (June 24, 2002).	131

15.9 Version 0.2 (April 17, 2002).	132

15.10 Version 0.1 (April 3, 2002).	132

Introduction

This document describes the Open Standard Print Application Programming Interface (API), also known as the "PAPI" (Print API). This is a set of open standard C functions that can be called by application programs to use the print spooling facilities available in Linux (NOTE: this interface is being proposed as a print standard for Linux, but there is really nothing Linux-specific about it and it can be adopted on other platforms). Typically, the "application" is a GUI program attempting to perform a request by the user to print something.

This version of the document describes stage 1 and stage 2 of the Open Standard Print API:

Simple interfaces for job submission and querying printer capabilities

Addition of interfaces to use Job Tickets, addition of operator interfaces

Addition of administrative interfaces (create/delete objects, enable/disable objects, etc.)

Subsequent versions of this document will incorporate the additional functions described in the later stages.

Print System Model

Introduction

Any printing system API must be based on some "model". A printing system model defines the objects on which the API functions operate (e.g. a "printer"), and how those objects are interrelated (e.g. submitting a file to a "printer" results in a "job" being created).

The print system model must answer the following questions in order to be used to define a set of print system APIs:

Object Definition: What objects are part of the model?

Object Naming: How is each object identified/named?

Object Relationships: What are the associations and relationships between the objects?

Some possible objects a printing system model might include are:

Printer	Queue	Print Resources (font, etc.)
Document	Filter/Transform	Job Ticket
Medium/Form	Job	Auxiliary Sheet
Server	Class/Pool	

Model

The model on which the Open Standard Print API is derived from reflect the semantics defined by the Internet Printing Protocol (IPP) standard. This is a fairly simple model in terms of the number of object types. It is defined very clearly and in detail in the IPP [RFC2911], Chapter 2. Additional IPP-related documents can be found in the References appendix

Consult the above document for a thorough understanding of the IPP print model. A brief summary of the model is provided here.

Print Service

Note that an implementation of the PAPI interface may use protocols other than IPP for communicating with a print service. The only requirement is that the implementation accept and return the data structures as defined in this document.

Printer

Printer objects are the target of print job requests. A printer object may represent an actual printer (if the printer itself supports PAPI), an object in a server representing an actual printer, or an abstract object in a server (perhaps representing a pool or class of printers). Printer objects are identified by one or more names which may be short, local names (such as "prtr1") or longer global names (such as a URI like "http://printserv.mycompany.com:631/printers/prtr1", “ipp://printserv/printers/prt1”, “lpd://server/queue”, etc.). The PAPI implementation may detect and map short names to long global names in an implementation-specific manner.

Job

Job objects are created after a successful print submission. They contain a set of attributes describing the job and specifying how it will be printed. They also contain (logically) the print data itself in the form of one or more "documents".

Job objects are identified by an integer "job ID" that is assumed to be unique within the scope of the printer object to which the job was submitted. Thus, the combination of printer name or URI and the integer job ID globally identify a job.

Document

Document objects are sub-units of a job object. Conceptually, they may each contain a separate set of attributes describing the document and specifying how it will be printed. They also contain (logically) the print data itself.

This version of PAPI does NOT support separate document objects, but they will be added in a future version. It is likely that this will be done by adding new "Open job", "Add document", and "Close job" functions to allow submitting a multiple document job and specifying separate attributes for each document.

Security

The security model of this API is based on the IPP security model, which uses HTTP security mechanisms as well as implementation-defined security policies.

Authentication

Authentication will be done by using methods appropriate to the underlying server/printer being used. For example, if the underlying printer/server is using IPP protocol then either HTTP Basic or HTTP Digest authentication might be used.

Authentication is supported by supplying a user name and password. If the user name and password are not passed on the API call, the call may fail with an error code indicating an authentication problem.

Authorization

Authorization is the security checking that follows authentication. It verifies that the identified user is authorized to perform the requested operation on the specified object.

Since authorization is an entirely server-side (or printer-side) function, how it works is not specified by this API. In other words, the server (or printer) may or may not do authorization checking according to its capability and current configuration. If authorization checking is performed, any call may fail with an error code indicating the failure (PAPI_NOT_AUTHORIZED).

Encryption

Encrypting certain data sent to and from the print service may be desirable in some environments. See the "encryption" field in the service object for information on how to request encryption on a print operation. Note that some print services may not support encryption. To comply with this standard, only the PAPI_ENCRYPT_NEVER value must be supported.

Globalization

The PAPI interface follows the conventions for globalization and translation of human-readable strings that are outlined in the IPP standards. A quick summary:

Attribute names are never translated.

Most text values are not translated.

Supporting translation by PAPI implementation is optional.

If translation is supported, only the values of the following attributes are translated: job-state-message, document-state-message, and printer-state-message.

The above is just a summary. For details, see [RFC2911] section 3.1.4 and [PWGSemMod] section 6.

Common Structures

Conventions

All "char *" variables and fields are pointers to standard C/C++ NULL-terminated strings. It is assumed that these strings are all UTF-8 encoded characters strings.

All pointer arrays (e.g. "char **") are assumed to be terminated by NULL pointers. That is, the valid elements of the array are followed by an element containing a NULL pointer that marks the end of the list.

Service Object (papi_service_t)

This opaque structure is used as a "handle" to maintain information about the print service being used to handle the PAPI requests. It is typically created once, used on one or more subsequent PAPI calls, and then destroyed.

typedef void *papi_service_t;

Included in the information associated with a papi_service_t is a definition about how requests will be encrypted during communication with the print service.

typedef enum {
PAPI_ENCRYPT_IF_REQUESTED,/* Encrypt if requested (TLS upgrade) */
PAPI_ENCRYPT_NEVER	/* Never encrypt */
PAPI_ENCRYPT_REQUIRED,	/* Encryption is required (TLS upgrade) */
PAPI_ENCRYPT_ALWAYS	/* Always encrypt (SSL) */
} papi_encryption_t;

Note that to comply with this standard, only the PAPI_ENCRYPT_NEVER value must be supported.

Attributes and Values (papi_attribute_t)

These are the structures defining how attributes and values are passed to and from PAPI.

/* Attribute Type */
typedef enum {
PAPI_STRING,
PAPI_INTEGER,
PAPI_BOOLEAN,
PAPI_RANGE,
PAPI_RESOLUTION,
PAPI_DATETIME,
PAPI_COLLECTION
PAPI_METADATA
} papi_attribute_value_type_t;
/* Resolution units */
typedef enum {
PAPI_RES_PER_INCH = 3,
PAPI_RES_PER_CM
} papi_res_t; /* Boolean values */
enum {
PAPI_FALSE = 0,
PAPI_TRUE = 1
};
typedef enum {
PAPI_UNSUPPORTED = 0x10,
PAPI_DEFAULT = 0x11,
PAPI_UNKNOWN,
PAPI_NO_VALUE,
PAPI_NOT_SETTABLE = 0x15,
PAPI_DELETE = 0x16
} papi_metadata_t;
struct papi_attribute_str;
/* Attribute Value */
typedef union {
char *string;	/* PAPI_STRING value */
int integer;	/* PAPI_INTEGER value */
char boolean;	/* PAPI_BOOLEAN value */
struct {	/* PAPI_RANGE value */
int lower;
int upper;
} range;
struct {	/* PAPI_RESOLUTION value */
int xres;
int yres;
papi_res_t units;
} resolution
time_t datetime;	/* PAPI_DATETIME value */
struct papi_attribute_str **
collection;	/* PAPI_COLLECTION value */
papi_metadata_t metadata;
} papi_attribute_value_t;
/* Attribute and Values */
typedef struct papi_attribute_str {
char *name;	/* attribute name */
papi_attribute_value_type_t type;	/* type of values */
papi_attribute_value_t **values;	/* list of values */
} papi_attribute_t;

The following constants are used by the papiAttributeListAdd* functions to control how values are added to the list.

/* Attribute add flags (add_flags) */
#define PAPI_ATTR_APPEND	0x0001	/* Add values to attribute*/
#define PAPI_ATTR_REPLACE	0x0002	/* Delete existing values, then add */
#define PAPI_ATTR_EXCL	0x0004	/* Fail if attribute exists */

For the valid attribute names which may be supported, see The Attributes appendix.

Job Object (papi_job_t)

This opaque structure is used as a "handle" to information associated with a job object. This handle is returned in response to successful job creation, modification, query, or list operations. See the "papiJobGet*" functions to see what information can be retrieved from the job object using the handle.

Stream Object (papi_stream_t)

This opaque structure is used as a "handle" to a stream of data. See the "papiJobStream*" functions for further details on how it is used.

Printer Object (papi_printer_t)

This opaque structure is used as a "handle" to information associated with a printer object. This handle is returned in response to successful printer modification, query, or list operations. See the "papiPrinterGet*" functions to see what information can be retrieved from the printer object using the handle.

Job Ticket (papi_job_ticket_t)

This structure is used to pass a job ticket when submitting a print job. Currently, Job Definition Format (JDF) is the only supported job ticket format. JDF is an XML- based job ticket syntax. The JDF specification can be found at http://www.cip4.org/.

/* Job Ticket Format */
typedef enum {
PAPI_JT_FORMAT_JDF = 0,	/* Job Definition Format */
PAPI_JT_FORMAT_PWG = 1	/* PWG Job Ticket Format */
} papi_jt_format_t;
/* Job Ticket */
typedef struct papi_job_ticket_s {
papi_jt_format_t format;	/* Format of job ticket */
char *ticket_data;	/* Buffer containing the job ticket data. If NULL,
file_name must be specified */
char *file_name;	/* Name of the file containing the job ticket data.
If ticket_data is specified, then file_name
is ignored. */
} papi_job_ticket_t;

The file_name field may contain absolute path names, relative path names or URIs ([RFC1738], [RFC2396]). In the event that the name contains an absolute or relative path name (relative to the current directory), the implementation MUST copy the file contents before returning. If the name contains a URI, the implementation SHOULD NOT copy the referenced data unless (or until) it is no longer feasible to maintain the reference. Feasibility limitations may arise out of security issues, name space issues, and/or protocol or printer limitations.

Status (papi_status_t)

typedef enum {
PAPI_OK = 0x0000,
PAPI_OK_SUBST,
PAPI_OK_CONFLICT,
PAPI_OK_IGNORED_SUBSCRIPTIONS,
PAPI_OK_IGNORED_NOTIFICATIONS,
PAPI_OK_TOO_MANY_EVENTS,
PAPI_OK_BUT_CANCEL_SUBSCRIPTION,
PAPI_REDIRECTION_OTHER_SITE = 0x300,
PAPI_BAD_REQUEST = 0x0400,
PAPI_FORBIDDEN,
PAPI_NOT_AUTHENTICATED,
PAPI_NOT_AUTHORIZED,
PAPI_NOT_POSSIBLE,
PAPI_TIMEOUT,
PAPI_NOT_FOUND,
PAPI_GONE,
PAPI_REQUEST_ENTITY,
PAPI_REQUEST_VALUE,
PAPI_DOCUMENT_FORMAT,
PAPI_ATTRIBUTES,
PAPI_URI_SCHEME,
PAPI_CHARSET,
PAPI_CONFLICT,
PAPI_COMPRESSION_NOT_SUPPORTED,
PAPI_COMPRESSION_ERROR,
PAPI_DOCUMENT_FORMAT_ERROR,
PAPI_DOCUMENT_ACCESS_ERROR,
PAPI_ATTRIBUTES_NOT_SETTABLE,
PAPI_IGNORED_ALL_SUBSCRIPTIONS,
PAPI_TOO_MANY_SUBSCRIPTIONS,
PAPI_IGNORED_ALL_NOTIFICATIONS,
PAPI_PRINT_SUPPORT_FILE_NOT_FOUND,
PAPI_INTERNAL_ERROR = 0x0500,
PAPI_OPERATION_NOT_SUPPORTED,
PAPI_SERVICE_UNAVAILABLE,
PAPI_VERSION_NOT_SUPPORTED,
PAPI_DEVICE_ERROR,
PAPI_TEMPORARY_ERROR,
PAPI_NOT_ACCEPTING,
PAPI_PRINTER_BUSY,
PAPI_ERROR_JOB_CANCELLED,
PAPI_MULTIPLE_JOBS_NOT_SUPPORTED,
PAPI_PRINTER_IS_DEACTIVATED,
PAPI_BAD_ARGUMENT,
PAPI_JOB_TICKET_NOT_SUPPORTED
} papi_status_t;

NOTE: If a Particular implementation of PAPI does not support a requested function, PAPI_OPERATION_NOT_SUPPORTED must be returned from that function.

See [RFC2911], section 13.1 for further explanations of the meanings of these status values.

List Filter (papi_filter_t)

This structure is used to filter the objects that get returned on a list request. When many objects could be returned from the request, reducing the list using a filter may have significant performance and network traffic benefits.

typedef enum {
PAPI_FILTER_BITMASK = 0
/* future filter types may be added here */
} papi_filter_type_t;
typedef struct {
papi_filter_type_t type; /* Type of filter specified */
union {
/* Bitmask filter */
struct {
unsigned int mask; /* bit mask */
unsigned int value; /* bit value */
} bitmask;
/* future filter types may be added here */
} filter;
} papi_filter_t;

For papiPrintersList requests, the following values may be OR-ed together and used in the papi_filter_t mask and value fields to limit the printers returned. The logic used is to select printers which satisfy: "(printer-type & mask) == (value & mask)". This allows for simple "positive logic" (checking for the presence of characteristics) when mask and value are identical, and it also allows for "negative logic" (checking for the absence of characteristics) when they are different. For example, to select local (i.e. NOT remote) printers that support color:

papi_filter_t filter; filter.type = PAPI_FILTER_BITMASK;
filter.filter.bitmask.mask = PAPI_PRINTER_REMOTE | PAPI_PRINTER_COLOR;
filter.filter.bitmask.value = PAPI_PRINTER_COLOR;

The filter bitmask values are:

enum {
PAPI_PRINTER_LOCAL = 0x0000,	/* Local printer or class */
PAPI_PRINTER_CLASS = 0x0001,	/* Printer class */
PAPI_PRINTER_REMOTE = 0x0002,	/* Remote printer or class */
PAPI_PRINTER_BW = 0x0004,	/* Can do B&W printing */
PAPI_PRINTER_COLOR = 0x0008,	/* Can do color printing */
PAPI_PRINTER_DUPLEX = 0x0010,	/* Can do duplexing */
PAPI_PRINTER_STAPLE = 0x0020,	/* Can staple output */
PAPI_PRINTER_COPIES = 0x0040,	/* Can do copies */
PAPI_PRINTER_COLLATE = 0x0080,	/* Can collage copies */
PAPI_PRINTER_PUNCH = 0x0100,	/* Can punch output */
PAPI_PRINTER_COVER = 0x0200,	/* Can cover output */
PAPI_PRINTER_BIND = 0x0400,	/* Can bind output */
PAPI_PRINTER_SORT = 0x0800,	/* Can sort output */
PAPI_PRINTER_SMALL = 0x1000,	/* Can do Letter/Legal/A4 */
PAPI_PRINTER_MEDIUM = 0x2000,	/* Can do Tabloid/B/C/A3/A2 */
PAPI_PRINTER_LARGE = 0x4000,	/* Can do D/E/A1/A0 */
PAPI_PRINTER_VARIABLE = 0x8000,	/* Can do variable sizes */
PAPI_PRINTER_IMPLICIT = 0x10000,	/* Implicit class */
PAPI_PRINTER_DEFAULT = 0x20000,	/* Default printer on network */
PAPI_PRINTER_OPTIONS = 0xfffc /* ~(CLASS | REMOTE | IMPLICIT) */
};

Encryption (papi_encrypt_t)

This enumeration is used to get/set the encryption type to be used during communication with the print service.

typedef enum {
PAPI_ENCRYPT_IF_REQUESTED,
PAPI_ENCRYPT_NEVER,
PAPI_ENCRYPT_REQUIRED,
PAPI_ENCRYPT_ALWAYS
} papi_encryption_t;

Attributes API

The interface described in this section is central to the PAPI printing model. Virtually all of the operations that can be performed against the print service objects (via function calls) make use of attributes. Object creation or modification operations tend to take in attribute list dewscribing the object or the requested modifications. Object creation, modification, queyr and list operations tent to return updated lists of print service objects containing attribute lists to more completely describe the objects.

In the case of a printer object, it's associated attribute list can be retreived using papiPrinterGetAttributeList. Job object attribute lists can be retreived using papiJobGetAttributeList. Once retreived, these attribute lists can be searched (or enumerated) to gather further information about the associated object. When creating or modifying print service objects, attribute lists can be built and passed into the create/modify operation. As a general rule of thumb, application developers should not modify or destroy attribute lists that they did not create. Modification or descruction of attribute lists retreived from print service objects should be handled by the PAPI implementation upon object destruction (free).

Because the attribute interface has specific functions to easy the use of various types of data that can be contained in an attribute list, there are a few things that are common to all of the papiAttributeAdd* fuctions and some common to all of the papiAttribute ListGet* functions.

All of the papiAttributeListAdd* functions take in a pointer to an attribute list, a set of flags, an attribute name, and call/type specific values. For all of the papiAttributeListAdd* functions, the attribute list pointer (papi_attribute_t ***attrs) may not contain a NULL value. If a NULL value is passed to any of these functions, the function must return PAPI_BAD_ARGUMENT. The flags passed into each of the papiAttributeListAdd* calls describe how the attribute/values are to be added to the attribute list. Currently, there are three flags that can be passed: PAPI_ATTR_EXCL, PAPI_ATTR_REPLACE, and PAPI_ATTR_APPEND. If PAPI_ATTR_EXCL is passed, it indicates that this call should only succeed if the named attribute does not already exist in the attribute list. PAPI_ATTR_REPLACE indicates that prior to addition to the attribute list, this call should truncate any existing attribute values for the named attribute if is already contained in the list. PAPI_ATTR_APPEND indicates that any attribute values contained in this call should be appended to the named attribute's value list if the named attribute was already contained in the attribute list.

All of the papiAttributeListGet* functions take in an attribute list, iterator, name, and pointer(s) for type specific results. If the named attribute is found in the attirbute list, but it's type does not match the type supplied in papiAttributeListGet or the type implied by the various type specific calls, a value of PAPI_NOT_POSSIBLE must be returned from the call. Any papiAttributeListGet* failure must not modify the information in the provided results arguments.

papiAttributeListAdd

Description

Add an attribute/value to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

This function is equivalent to the papiAttributeListAddString, papiAttributeListAddInteger, papiAttributeListAddBoolean, papiAttributeListAddRange, papiAttributeListAddResolution, papiAttributeListAddDatetime, papiAttributeListAddCollection, and papiAttributeListAddMetadata functions defined later in this chapter.

Syntax

papi_status_t papiAttributeListAdd(papi_attribute_t ***attrs, int add_flags,
char *name, papi_attribute_value_type_t type,
papi_attribute_value_t *value );

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

type

The type of values for this attribute.

value

Points to the attribute value to be added.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
papi_attribute_value_t value;
...
value.string = “My Job”;
status = papiAttributeListAdd(&attrs, PAPI_ATTR_EXCL, "job-name",
PAPI_STRING, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAddString, papiAttributeListAddInteger, papiAttributeListAddBoolean, papiAttributeListAddRange, papiAttributeListAddResolution, papiAttributeListAddDatetime, papiAttributeListAddCollection, papiAttributeListFromString, papiAttributeListFree

papiAttributeListAddString

Description

Add a string-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddString(papi_attribute_t ***attrs, int add_flags,
char *name, char *value);

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

value

The string value to be added to the attribute.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL,
"job-name", "My job" );
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddInteger

Description

Add an integer-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddInteger(papi_attribute_t ***attrs, int add_flags,
char *name,int value );

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

value

The integer value to be added to the attribute.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddInteger(&attrs, PAPI_ATTR_EXCL,
"copies", 3);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddBoolean

Description

Add a boolean-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddBoolean(papi_attribute_t ***attrs, int add_flags,
char *name, char value );

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

value

The boolean value (PAPI_FALSE or PAPI_TRUE) to be added to the attribute.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddBoolean(&attrs, PAPI_ATTR_EXCL,
”color-supported”, PAPI_TRUE);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddRange

Description

Add a range-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddRange(papi_attribute_t ***attrs, int add_flags,
char *name, int lower, int upper);

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

lower

An integer value representing the lower boundary of a range value. This value must be less than or equal to the upper range value.

upper

An integer value representing the upper boundary of the range value. This value must be greater than or equal to the lower range value

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddRange(&attrs, PAPI_ATTR_EXCL,
"job-k-octets-supported",1, 100000);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddResolution

Description

Add a resolution-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddResolution(papi_attribute_t ***attrs,
int add_flags, char *name,
int xres, int yres, papi_res_t units);

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

xres

The integer X-axis resolution value.

yres

The integer Y-axis resolution value.

Units

The units of the X-axis and y-axis resolution values provided.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddResolution(&attrs, PAPI_ATTR_EXCL,
“printer-resolution”, 300, 300,
PAPI_RES_PER_INCH);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddDatetime

Description

Add a date/time-valued attribute to an attribute list. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddDatetime(papi_attribute_t ***attrs, int add_flags,
char *name, time_t value );

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

value

The time_t representation of the date/time value to be added to the attribute.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;

time_t date_time;
...
time(&date_time);
status = papiAttributeListAdd(&attrs, PAPI_EXCL,
"date-time-at-creation", date_time);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddCollection

Description

Add a collection-valued attribute to an attribute list. A collection-valued attribute is a container for list of attributes. Depending on the add_flags, this may also be used to add values to an existing multi-valued attribute. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddCollection(papi_attribute_t ***attrs,
int add_flags, char *name,
papi_attribute_t **collection);

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

collection

Points to the attribute list to be added as a collection.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
papi_attribute_t **collection = NULL;
...
/* create the collection /
status = papiAttributeListAddString(&collection, PAPI_EXCL,
"media-key", “iso-a4-white”);
status = papiAttributeListAddString(&collection, PAPI_EXCL,
"media-type", “stationery”);
...
/ add the collection to the attribute list */
status = papiAttributeListAddCollection(&attrs, PAPI_EXCL,
"media-col", collection);
...
papiAttributeListFree(collection);
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListAddMetadata

Description

Add a meta-valued attribute to an attribute list. A meta-valued attribute is a container for attribute information not normally represented in an attribute value. Memory is allocated and copies of the input arguments are created. It is the caller's responsibility to call papiAttributeListFree when done with the attribute list.

Syntax

papi_status_t papiAttributeListAddMetadata(papi_attribute_t ***attrs,
int add_flags, char *name,
papi_metadata_t value);

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

name

Points to the name of the attribute to add.

value

The type of metadata to be added to the attribute. PAPI_DELETE can be used to indicate that an attribute should be removed from a print service object when calling one of the papi*Modify functions. PAPI_DEFAULT can be used to indicate that the print service should set (or reset) the named attribute value to a “default” value during a create or modify operation of a print service object.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
/ add the collection to the attribute list */
status = papiAttributeListAddMetadata(&attrs, PAPI_EXCL,
"media", PAPI_DELETE);
...
papiAttributeListFree(collection);
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListFree

papiAttributeListDelete

Description

Delete an attribute from an attribute list. All memory associated with the deleted attribute is deallocated.

Syntax

papi_status_t papiAttributeListDelete(papi_attribute_t ***attrs, char *name);

Inputs

attrs

Points to an attribute list.

name

Points to the name of the attribute to remove.

Outputs

attrs

The attribute list is updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
...
status = papiAttributeListAddDelete(&attrs, “copies”);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListFree

papiAttributeListGetValue

Description

Get an attribute's value from an attribute list.

This function is equivalent to the papiAttributeListGetString, papiAttributeListGetInteger, papiAttributeListGetBoolean, papiAttributeListGetRange, papiAttributeListGetResolution, papiAttributeListGetDatetime, and papiAttributeListGetCollection functions defined later in this chapter.

Syntax

papi_status_t papiAttributeListGetValue(papi_attribute_t **attrs, void **iterator,
char *name, papi_attribute_value_type_t type,
papi_attribute_t **value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be located in the attribute list supplied, PAPI_NOT_FOUND is returned.

type

The type of values for this attribute. If the type supplied does not match the type of the named attribute in the attribute list, PAPI_NOT_POSSIBLE is returned.

Outputs

Iterator

See iterator in the Inputs section above

value

Points to the variable where a pointer to the attribute value is to be returned. Note that the returned pointer points to the attribute's value in the list (no copy of the value is made) so that the caller does not need to do any special cleanup of the returned value's memory (it is cleaned up when the containing attribute list is deallocated).

If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
papi_attribute_value_t *job_name_value;
...
status = papiAttributeListGetValue(attrs, NULL, “job-name”,
PAPI_STRING, &job_name_value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetString, papiAttributeListGetInteger, papiAttributeListGetBoolean, papiAttributeListGetRange, papiAttributeListGetResolution, papiAttributeListGetDatetime, papiAttributeListGetCollection, papiAttributeListFree

papiAttributeListGetString

Description

Get a string-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetString(papi_attribute_t **attrs, void **iterator,
char *name, char **value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_STRING, PAPI_NOT_POSSIBLE will be returned.

Outputs

Iterator

See iterator in the Inputs section above

value

Pointer to the string (char *) where a pointer to the value is returned. If this call returns an error, the output value is not changed. Note that the returned pointer points to the attribute's value in the list (no copy of the value is made) so that the caller does not need to perform any special cleanup of the returned value's memory (it is cleaned up when the containing attribute list is deallocated).

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
char *value = NULL;
...
status = papiAttributeListGetString(attrs, NULL, “job-name”,
PAPI_STRING, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetInteger

Description

Get an integer-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetInteger(papi_attribute_t **attrs, void **iterator,
char *name, int *value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_INTEGER, PAPI_NOT_POSSIBLE will be returned.

Outputs

Iterator

See iterator in the Inputs section above

value

Pointer to the int where the value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
int value = 0;
...
status = papiAttributeListGetInteger(attrs, NULL, “copies”, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetBoolean

Description

Get a boolean-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetBoolean(papi_attribute_t **attrs, void **iterator,
char *name, char *value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_BOOLEAN, PAPI_NOT_POSSIBLE will be returned.

Outputs

Iterator

See iterator in the Inputs section above.

value

Pointer to the char where the value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
char value = PAPI_FALSE;
...
status = papiAttributeListGetBoolean(attrs, NULL,
“color-supported”, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetRange

Description

Get a range-valued attribute's values from an attribute list.

Syntax

papi_status_t papiAttributeListGetRange(papi_attribute_t **attrs, void **iterator,
char *name, int *lower, int *upper);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_RANGE, PAPI_NOT_POSSIBLE will be returned.

Outputs

Iterator

See iterator in the inputs section above.

lower

Pointer to the integer where the values are returned. The value from the attribute list is copied to this location. If this call returns an error, the output values are not changed.

upper

Pointer to the integer where the values are returned. The value from the attribute list is copied to this location. If this call returns an error, the output values are not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
int lower = 0;
int upper = 0;
...
status = papiAttributeListGetRange(attrs, NULL,
“job-k-octets-supported”, &lower, &upper);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetResolution

Description

Get a resolution-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetResolution(papi_attribute_t **attrs, void **iterator,
char *name, int *xres, int *yres, papi_res_t *units);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_RESOLUTION, PAPI_NOT_POSSIBLE will be returned.

Outputs

iterator

See iterator in the Inputs section above.

xres

Pointer to the int where the X-resolution value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

yres

Pointer to the int where the Y-resolution value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

units

Pointer to the variable where the resolution-units value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
int xres, yres;
papi_res_t units;
...
status = papiAttributeListGetResolution(attrs, NULL,
“printer-resolution”, &xres, &yres, &units);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetDatetime

Description

Get a datetime-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetDatetime(papi_attribute_t **attrs, void **iterator,
char *name, time_t *value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_DATETIME, PAPI_NOT_POSSIBLE will be returned.

Outputs

iterator

See iterator in the Inputs section above

value

Pointer to the time_t where the value is returned. The value from the attribute list is copied to this location. If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
time_t value = 0;
...
status = papiAttributeListGetDatetime(attrs, NULL,
“date-time-at-creation”, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetCollection

Description

Get a collection-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetCollection(papi_attribute_t **attrs, void **iterator,
char *name, papi_attribute_t ***value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_COLLECTION, PAPI_NOT_POSSIBLE will be returned.

type

The type of values for this attribute.

Outputs

Iterator

See iterator in the Inputs section above.

value

Points to the variable where a pointer to the attribute value is to be returned. Note that the returned pointer points to the attribute's value in the list (no copy of the value is made) so that the caller does not need to do any special cleanup of the returned value's memory (it is cleaned up when the containing attribute list is deallocated).

If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
papi_attribute_t **value = NULL;
...
status = papiAttributeListGetCollection(attrs, NULL,
“media-col”, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListGetMetadata

Description

Get a meta-valued attribute's value from an attribute list.

Syntax

papi_status_t papiAttributeListGetMetadata(papi_attribute_t **attrs, void **iterator,
char *name, papi_metadata_t *value);

Inputs

attrs

Points to an attribute list.

iterator

(optional) Pointer to an opaque (void*) value iterator. If the argument is NULL then only the first value is returned, even if the attribute is multi-valued. If the argument points to a void* that is set to NULL, then the first attribute value is returned and the iterator can then be passed in unchanged on subsequent calls to this function to get the remaining values.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned. If the named attribute is found in the attribute list, but is not a PAPI_STRING, PAPI_NOT_POSSIBLE will be returned.

type

The type of values for this attribute.

Outputs

Iterator

See iterator in the Inputs section above.

value

Points to the variable where the attribute value is to be returned. If this call returns an error, the output value is not changed.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
papi_metadata_t value = PAPI_NO_VALUE;
...
status = papiAttributeListGetMetadata(attrs, NULL,
“media”, &value);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue, papiAttributeListFree

papiAttributeListFree

Description

Frees an attribute list

Syntax

void papiAttributeListFree(papi_attribute_t **attrs);

Inputs

attrs

Attribute list to be deallocated.

Outputs

none

Returns

none

Example

papi_attribute_t **attrs = NULL;
...
papiAttributeListFree(attrs);

See Also

papiAttributeListAdd, papiAttributeListAddString, papiAttributeListAddInteger, papiAttributeListAddBoolean, papiAttributeListAddRange, papiAttributeListAddResolution, papiAttributeListAddDatetime, papiAttributeListAddCollection, papiAttributeListFromString, papiAttributeListFree

papiAttributeListFind

Description

Find an attribute in an attribute list.

Syntax

papi_attribute_t *papiAttributeListFind(papi_attribute_t **attrs, char *name);

Inputs

attrs

Points to an attribute list.

name

Points to the name of the attribute to retrieve. If the named attribute can not be found in the supplied attribute list, PAPI_NOT_FOUND will be returned.

Outputs

none

Returns

Pointer to the named attribute found in the attribute list. The result will be deallocated when the containing attribute list is destroyed. NULL indicates that the specified attribute was not found

Example

papi_attribute_t **attrs = NULL;
papi_attribute_t *value;
...
value = papiAttributeListFind(attrs, “job-name”);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListGetValue

papiAttributeListGetNext

Description

Get the next attribute in an attribute list.

Syntax

papi_attribute_t **papiAttributeListGetNext(papi_attribute_t **attrs, void **iterator);

Inputs

attrs

Points to an attribute list.

iterator

Pointer to an opaque (void*) iterator. This should be NULL to find the first attribute and then passed in unchanged on subsequent calls to this function.

Outputs

Iterator

See iterator in the Inputs section above.

Returns

Pointer to the next attribute in the attribute list. The result will be deallocated when the containing attribute list is destroyed. NULL indicates that the end of the attribute list was reached

Example

papi_attribute_t **attrs = NULL;
papi_attribute_t *value;

void *iterator = NULL;
...
while ((value = papiAttributeGetNext(attrs, &iterator)) != NULL) {
...
}
...
papiAttributeListFree(attrs);

See Also

papiAttributeListFind

papiAttributeListFromString

Description

Convert a string of text options to an attribute list. PAPI provides two functions which map job attributes to and from text options that are typically provided on the command-line by the user. This text encoding is also backwards-compatible with existing printing systems and is relatively simple to parse and generate. See Attribute List Text Representation for a definition of the string syntax.

Syntax

papi_status_t papiAttributeListFromString(papi_attribute_t*** attrs,
int add_flags, char* buffer );

Inputs

attrs

Points to an attribute list. If *attrs is NULL then this function will allocate the attribute list.

add_flags

A mask field consisting of one or more PAPI_ATTR_* values OR-ed together that indicates how to handle the request.

buffer

Points to text options.

Outputs

attrs

The attribute list is updated.

Returns

If the text string is successfully converted to an attribute list, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_attribute_t **attrs = NULL;
char *string = "copies=1 job-name=John\'s\ Really\040Nice\ Job";
...
status = papiAttributeListFromString(attrs, PAPI_ATTR_EXCL, string);
...
papiAttributeListFree(attrs);

See Also

papiAttributeListFind

papiAttributeListToString

Description

Convert an attribute list to its text representation. The destination string is limited to at most (buflen - 1) bytes plus the trailing null byte.

PAPI provides two functions which map job attributes to and from text options that are typically provided on the command-line by the user. This text encoding is also backwards-compatible with existing printing systems and is relatively simple to parse and generate. See Attribute List Text Representation for a definition of the string syntax.

Syntax

papi_status_t papiAttributeListToString(papi_attribute_t** attrs,
char* attr_delim, char* buffer,
size_t buflen );

Inputs

attr

Points to an attribute list.

attr_delim

(optional) If not NULL, points to a string to be placed between attributes in the output buffer. If NULL, a space is used as the attribute delimiter.

buffer

Points to a string buffer to receive the to receive the text representation of the attribute list.

buflen

Specifies the length of the string buffer in bytes.

Outputs

buffer

The buffer is filled with the text representation of the attribute list. The buffer will always be set to something by this function (buffer[0] = NULL in cases of an error).

Returns

If the attribute list is successfully converted to a text string, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_attribute_t **attrs = NULL;
char buffer[8192];
...
papiAttributeListToString(attrs, NULL, buffer, sizeof (buffer));
...
papiAttributeListFree(attrs);

See Also

PapiAttributeListFromString

Service API

The service segment of the PAPI provides a means of creating, modifying, or destroying a context (or object) used to interact with a print service. This context is opaque to applications using it and may be used by implementations to store internal data such as file or socket descriptors, operation results, credentials, etc.

papiServiceCreate

Description

Create a print service handle to be used in subsequent calls. Memory is allocated and copies of the input arguments are created so that the handle can be used outside the scope of the input variables.

The caller must call papiServiceDestroy when done in order to free the resources associated with the print service handle. This must be done even if the papiServiceCreate call failed, because a service creation failure may have resulted in a partial service context with additional error information.

Syntax

papi_status_t papiServiceCreate( papi_service_t *handle, char *service_name,
char *user_name, char *password,
int (*authCB)(papi_service_t svc),
papi_encryption_t encryption, void *app_data );

Inputs

service_name

(optional) Points to the name or URI of the service to use. A NULL value indicates that a “default service” should be used (the configuration of a default service is implementation-specific and may consist of environment variables, config files, etc. Default service selection is not addressed by this standard).

user_name

(optional) Points to the name of the user who is making the requests. A NULL value indicates that the user name associated with the process in which the API call is made should be used.

Password

(optional) Points to the password to be used to authenticate the user to the print service.

AuthCB

(optional) Points to a callback function to be used in authenticating the user to the print service if no password was supplied (or user input is required). A NULL value indicates that no callback should be made. The callback function should return 0 if the request is to be canceled and non-zero if new authentication information has been set.

Encryption

Specifies the encryption type to be used by the PAPI functions.

app_data

(optional) Points to application-specific data for use by the callback. The caller is responsible for allocating and freeing memory associated with this data.

Outputs

handle

A print service handle to be used on subsequent API calls. The handle will always be set to something even if the function fails. In the event that the function fails, the handle may be set to NULL or it may be set to a valid handle that contains error information.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
papiServiceDestroy(handle);

See Also

papiServiceDestroy, papiServiceGetStatusMessage, papiServiceSetUserName, papiServiceSetPassword, papiServiceSetEncryption, papiServiceSetAuthCB, papiServiceSetAppData,.papiServiceGetStatusMessage

papiServiceDestroy

Description

Destroy a print service handle and free the resources associated with it. This must be called even if the papiServiceCreate call failed, because there may be error information associated with the returned handle. If there is application data associated with the service handle, it is the caller’s responsibility to free this memory.

Syntax

void papiServiceDestroy(papi_service_t handle );

Inputs

handle

The print service handle to be destroyed.

Outputs

None

Returns

None

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate

papiServiceSetUserName

Description

Set the user name in the print service handle to be used in subsequent calls. Memory is allocated and a copy of the input argument is created so that the handle can be used outside the scope of the input variable.

Syntax

papi_status_t papiServiceSetUserName( papi_service_t handle,
char* user_name );

Inputs

handle

Handle to the print service to update.

user_name

Points to the name of the user who is making the requests. A NULL value indicates that the user name associated with the process in which the API call is made should be used.

Outputs

handle

Handle remains unchanged, but it’s contents may be updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
status = papiServiceSetUserName(handle, “root”);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceGetUserName, papiServiceGetStatusMessage

papiServiceSetPassword

Description

Set the password in the print service handle to be used in subsequent calls. Memory is allocated and a copy of the input argument is created so that the handle can be used outside the scope of the input variable.

Syntax

papi_status_t papiServiceSetPassword( papi_service_t handle, char* password);

Inputs

handle

Handle to the print service to update.

password

Points to the password to be used to authenticate the user to the print service.

Outputs

handle

Handle remains unchanged, but it’s contents may be updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
status = papiServiceSetPassword(handle, “passsword”);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceGetPassword, papiServiceGetStatusMessage

papiServiceSetEncryption

Description

Set the encryption in the print service handle to be used in subsequent calls.

Syntax

papi_status_t papiServiceSetEncryption( papi_service_t handle,
papi_encryption_t encryption);

Inputs

handle

Handle to the print service to update.

encryption

Specifies the encryption type to be used by the PAPI functions.

Outputs

handle

Handle remains unchanged, but it’s contents may be updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
status = papiServiceSetEncryption(handle, PAPI_ENCRYPT_NEVER);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceGetEncryption, papiServiceGetStatusMessage

papiServiceSetAuthCB

Description

Set the authorization callback function in the print service handle to be used in subsequent calls.

Syntax

papi_status_t papiServiceSetAuthCB( papi_service_t handle,
int (*authCB)(papi_service_t svc));

Inputs

handle

Handle to the print service to update.

authCB

Points to a callback function to be used in authenticating the user to the print service if no password was supplied (or user input is required). A NULL value indicates that no callback should be made. The callback function should return 0 if the request is to be canceled and non-zero if new authentication information has been set.

Outputs

handle

Handle remains unchanged, but it’s contents may be updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
status = papiServiceSetAuthCB(handle, get_password_callback);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceGetStatusMessage

papiServiceSetAppData

Description

Set a pointer to some application-specific data in the print service. This data may be used by the authentication callback function. The caller is responsible for allocating and freeing memory associated with this data.

Syntax

papi_status_t papiServiceSetAppData( papi_service_t handle, void *app_data);

Inputs

handle

Handle to the print service to update.

app_data

Points to application-specific data for use by the callback. The caller is responsible for allocating and freeing memory associated with this data.

Outputs

handle

Handle remains unchanged, but it’s contents may be updated.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiServiceCreate(&handle, “ipp://printserver:631”,
“user”, “password”, NULL,
PAPI_ENCRYPT_IF_REQUESTED, NULL);
...
status = papiServiceSetAppData(handle, app_data);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceGetAppData, papiServiceGetStatusMessage

papiServiceGetServiceName

Description

Get the service name associated with the print service handle.

Syntax

char *papiServiceGetServiceName(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

A pointer to the service name associated with the print service handle. The value returned will be deallocated upon destruction of the service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *service_name = NULL;
...
service_name = papiServiceGetServiceName(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate

papiServiceGetUserName

Description

Get the user name associated with the print service handle.

Syntax

char *papiServiceGetUserName(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

A pointer to the user name associated with the print service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *service_name = NULL;
...
user_name = papiServiceGetUserName(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceSetUserName

papiServiceGetPassword

Description

Get the password associated with the print service handle.

Syntax

char *papiServiceGetPassword(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

A pointer to the password associated with the print service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *password = NULL;
...
password = papiServiceGetPassword(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceSetPassword

papiServiceGetEncryption

Description

Get the encryption associated with the print service handle.

Syntax

papi_encryption_t papiServiceGetEncryption(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

The type of encryption associated with the print service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_encryption_t encryption;
...
encryption = papiServiceGetEncryption(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceSetEncryption

papiServiceGetAppData

Description

Get a pointer to the application-specific data associated with the print service handle.

Syntax

void *papiServiceGetAppData(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

A pointer to the application-specific data associated with the print service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
void app_data = NULL;
...
app_data = papiServiceGetAppData(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceSetAppData

papiServiceGetAttributeList

Description

Retrieve an attribute list from the print service. This attribute list contains service specific attributes describing service and implementation specific features.

Syntax

papi_attribute_t **papiServiceGetAttributeList(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

An attribute list associated with the print service handle. The attribute list is destroyed when the service handle is destroyed.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_attribute_t **attributes = NULL;
...
attributes = papiServiceGetAttributeList(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceDestroy

papiServiceGetStatusMessage

Description

Get the message associated with the status of the last operation performed. The status message returned from this function may be more detailed than the status message returned from papiStatusString (if the print service supports returning more detailed error messages).

The returned message will be localized in the language of the submitter of the original operation.

Syntax

Char *papiServiceGetStatusMessage(papi_service_t handle);

Inputs

handle

Handle to the print service.

Outputs

None

Returns

Pointer to the message associated with the print service handle.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *message = NULL;
...
message = papiServiceGetStatusMessage(handle);
...
papiServiceDestroy(handle);

See Also

papiServiceCreate, papiServiceSetUserName, papiServiceSetPassword, papiServiceSetEncryption, papiServiceSetAuthCB, papiServiceSetAppData, Printer API, Attributes API, Job API

Printer API

The printer segment of the PAPI provides a means of interacting with printer objects contained in a print service. This interaction can include listing, querying, modifying, pausing, and releasing the printer objects themselves. It can also include clearing all jobs from a printer object or enumerating all jobs associated with a printer object.

The papiPrinterQuery function queries all/some of the attributes of a printer object. It returns a list of printer attributes. A successful call to papiPrinterQuery is typically followed by code which examines and processes the returned attributes. When the calling program is finished with the printer object and it's attributes, it should then call papiPrinterFree to delete the returned results.

Printers can be found via calls to papiPrintersList. A successful call to papiPrintersList is typically followed by code to iterate through the list of returned printers, possibly querying each (papiPrinterQuery) for further information (e.g. to restrict what printers get displayed for a particular user/request). When the calling program is finished with the list of printer objects, it should then call papiPrinterListFree to free the returned results.

papiPrintersList

Description

List all printers known by the print service which match the specified filter.

Depending on the functionality of the target service's "printer directory", the returned list may be limited to only printers managed by a particular server or it may include printers managed by other servers.

Syntax

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

Inputs

handle

Handle to the print service.

requested_attrs

(optional) NULL terminated array of attributes to be queried. If NULL is passed then all attributes are queried. (NOTE: The printer may return more attributes than you requested. This is merely an advisory request that may reduce the amount of data returned if the printer/server supports it.)

filter

(optional) Pointer to a filter to limit the number if printers returned on the list request. See for details. If NULL is passed then all known printers are listed.

Outputs

printers

List of printer objects that matched the filter criteria. The resulting list of printer objects must be deallocated by the caller using papiPrinterListFree().

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *req_attrs[] = { "printer-name", "printer-uri", NULL };
papi_filter_t filter;
papi_printer_t *printers = NULL;
...
/* Select local printers (non-remote) that support color */
filter.type = PAPI_FILTER_BITMASK;
filter.filter.bitmask.mask = PAPI_PRINTER_REMOTE |
PAPI_PRINTER_COLOR;
filter.filter.bitmask.value = PAPI_PRINTER_COLOR;
...
status = papiPrinterList(handle, req_attrs, filter, &printers);
...
if (printers != NULL) {
int i;
for (i = 0; printers[i] != NULL; i++) {
...
}
papiPrinterListFree(printers);
}
...
papiServiceDestroy(handle);

See Also

papiPrinterListFree, papiPrinterQuery

papiPrinterQuery

Description

Queries some or all the attributes of the specified printer object. This includes attributes representing information and capabilities of the printer. The caller may use this information to determine which print options to present to the user. How the attributes are obtained (e.g. from a static database, from a dialog with the hardware, from a dialog with a driver, etc.) is implementation specific and is beyond the scope of this standard. The call optionally includes "context" information which specifies job attributes that provide a context that can be used by the print service to construct capabilities information.

Semantics Reference

Get-Printer-Attributes in [RFC2911], section 3.2.5

Syntax

papi_status_t papiPrinterQuery(papi_service_t handle, char *name,
char *requested_attrs[], papi_attribute_t **job_attrs,
papi_printer_t *printer );

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to query.

requested_attrs

(optional) NULL terminated array of attributes to be queried. If NULL is passed then all attributes are queried. (NOTE: The printer may return more attributes than you requested. This is merely an advisory request that may reduce the amount of data returned if the printer/server supports it.)

job_attrs

(optional) NULL terminated array of job attributes in the context of which the capabilities information is to be constructed. In other words, the returned printer attributes represent the capabilities of the printer given that these specified job attributes are requested. This allows for more accurate information to be retrieved by the caller for a specific job (e.g. "if the job is printed on A4 size media then duplex output is not available"). If NULL is passed then the full capabilities of the printer are queried.

Support for this argument is optional. If the underlying print system does not have access to capabilities information bound by job context, then this argument may be ignored. But if the calling application will be using the returned information to build print job data, then it is always advisable to specify the job context attributes. The more context information provided, the more accurate capabilities information is likely to be returned from the print system.

Outputs

printer

Pointer to a printer object containing the requested attributes.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
char *req_attrs[] = { "printer-name", "printer-uri",
“printer-state”, “printer-state-reasons”, NULL };
papi_attribute_t **job_attrs = NULL;
papi_printer_t printer = NULL;
...
papiAttributeListAddString(&job_attrs, PAPI_EXCL,
"media", "legal");
...
status = papiPrinterQuery(handle, “ipp://server/printers/queue”,

req_attrs, job_attrs, &printer);
papiAttributeListFree(job_attrs);
...
if (printer != NULL) {
/* process the printer object */
...
papiPrinterFree(printer);
}
...
papiServiceDestroy(handle);

See Also

papiPrintersList, papiPrinterFree

papiPrinterModify

Description

Modifies some or all the attributes of the specified printer object. Upon successful completion, the function will return a handle to an object representing the updated printer.

Semantics Reference

Set-Job-Attributes in [RFC3380], section 4.2

Syntax

papi_status_t papiPrinterModify(papi_service_t handle, char *printer_name,
papi_attribute_t **attrs, papi_printer_t *printer );

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to be modified.

attrs

Attributes to be modified. Any attributes not specified are left unchanged. Attributes can be deleted from the print service's printer object through the use of the PAPI_DELETE attribute metadata type.

Outputs

printer

The modified printer object.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_printer_t printer = NULL;
papi_attribute_t **attrs = NULL;
...
papiAttributeListAddString(&attrs, PAPI_EXCL,
"printer-location", "Bldg 17/Room 234");
papiAttributeListAddMetadata(&attrs, PAPI_EXCL,
“sample-data”, PAPI_DELETE);
...
status = papiPrinterModify(handle, “printer”, attrs, &printer);
...
if (printer != NULL) {
/* process the printer */
...
papiPrinterFree(printer);
}
...
papiServiceDestroy(handle);

See Also

PapiPrinterQuery, papiPrinterAdd, papiPrinterRemove, papiPrinterFree

papiPrinterAdd

Description

Creates a printer object with some or all the attributes specified. Upon successful completion, the function will return a handle to an object representing the created printer.

Semantics Reference

Set-Job-Attributes in [RFC3380], section 4.2

Syntax

papi_status_t papiPrinterAdd(papi_service_t handle, char *printer_name,
papi_attribute_t **attrs, papi_printer_t *printer );

Inputs

handle

Handle to the print service on which to create the printer object.

name

The name or URI of the printer to be created

attrs

Attributes to associate with the printer object being created. The print service may not honor all requested attributes and it may also add attributes of it's own during printer creation.

Outputs

printer

The created printer object.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_printer_t printer = NULL;
papi_attribute_t **attrs = NULL;
...
papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL,
"printer-location", "Bldg 17/Room 234");
papiAttributeListAddString(&attrs, PAPI_ATTR_APPEND,
“document-format-supported”, “application/ps”);

papiAttributeListAddString(&attrs, PAPI_ATTR_APPEND,
“document-format-supported”, “text/plain”);

papiAttributeListAddInteger(&attrs, PAPI_ATTR_APPEND,
“copies-default”, 3);
...
status = papiPrinterModify(handle, “ipp://server/printers/triplicate”,

attrs, &printer);

papiAttributeListFree(attrs);
...

if (status != PAPI_OK) {

/* report a failure */

}

if (printer != NULL) {
/* process the printer */
...
papiPrinterFree(printer);
}
...
papiServiceDestroy(handle);

See Also

papiPrinterQuery, papiPrinterModify, papiPrinterRemove, papiPrinterFree

papiPrinterRemove

Description

Removes a printer object from a print service.

Semantics Reference

Set-Job-Attributes in [RFC3380], section 4.2

Syntax

papi_status_t papiPrinterRemove(papi_service_t handle, char *printer_name);

Inputs

handle

Handle to the print service from which to remove the printer object.

name

The name or URI of the printer to be removed

Outputs

None

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiPrinterRemove(handle, “ipp://server/printers/goodbye”);

if (status != PAPI_OK) {

/* report a failure */

}
...
papiServiceDestroy(handle);

See Also

papiPrinterQuery, papiPrinterModify, papiPrinterAdd, papiPrinterFree

papiPrinterPause

Description

Stops the printer object from scheduling jobs to be printed. Depending on the implementation, this operation may also stop the printer from processing the current job(s). This operation is optional and may not be supported by all printers/servers. Use papiPrinterResume to undo the effects of this operation.

Semantics Reference

Pause-Printer in [RFC2911], section 3.2.7

Syntax

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

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to operate on.

message

(optional) An explanatory message to be associated with the paused printer. This message may be ignored if the underlying print system does not support associating a message with a paused printer.

Outputs

None

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiPrinterPause(handle, “printer”, “because I can”);
...
papiServiceDestroy(handle);

See Also

papiPrinterResume

papiPrinterResume

Description

Requests that the printer resume scheduling jobs to be printed (i.e. it undoes the effects of papiPrinterPause). This operation is optional and may not be supported by all printers/servers, but it must be supported if papiPrinterPause is supported.

Semantics Reference

Resume-Printer in [RFC2911], section 3.2.8

Syntax

papi_status_t papiPrinterResume(papi_service_t handle, char *name);

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to operate on.

Outputs

None

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiPrinterResume(handle, “printer”);
...
papiServiceDestroy(handle);

See Also

papiPrinterPause

papiPrinterEnable

Description

Requests that the printer enable job creation (queueing) (i.e. it undoes the effects of papiPrinterDisable). This operation is optional and may not be supported by all printers/servers, but it must be supported if papiPrinterDisable is supported.

Semantics Reference

Resume-Printer in [RFC2911], section 3.2.8

Syntax

papi_status_t papiPrinterEnable(papi_service_t handle, char *name);

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to operate on.

Outputs

None

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiPrinterEnable(handle, “printer”);
...
papiServiceDestroy(handle);

See Also

papiPrinterDisable

papiPrinterDisable

Description

Requests that the printer disable job creation (queueing) (i.e. it undoes the effects of papiPrinterEnable). This operation is optional and may not be supported by all printers/servers, but it must be supported if papiPrinterEnable is supported.

Semantics Reference

Resume-Printer in [RFC2911], section 3.2.8

Syntax

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

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to operate on.

Message

An optional reason for disabling the print queue.

Outputs

None

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiPrinterEnable(handle, “printer”, “because it's tuesday”);
...
papiServiceDestroy(handle);

See Also

papiPrinterDisable

papiPrinterPurgeJobs

Description

Remove all jobs from the specified printer object regardless of their states. This includes removing jobs that have completed and are being retained(if any). This operation is optional and may not be supported by all printers/servers.

Semantics Reference

Purge-Jobs in [RFC2911], section 3.2.9

Syntax

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

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to operate on.

Outputs

jobs

(optional) Pointer to a list of purged jobs with the identifying information (job-id/job-uri), success/fail, and possibly a detailed message. If NULL is passed then no job list is returned. Support for the returned job list is optional and may not be supported by all implementations (if not supported, the function completes with PAPI_OK_SUBST but no list is returned).

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

#include "papi.h"
papi_status_t status;
papi_service_t handle = NULL;
char *service_name = "ipp://printserv:631";
char *user_name = "pappy";
char *password = "goober";
char *printer_name = "my-printer";
papi_job_t *jobs = NULL;
status = papiServiceCreate(handle, service_name, user_name,
password, NULL, PAPI_ENCRYPT_IF_REQUESTED,
NULL);
if (status != PAPI_OK) {
/* handle the error */
...
}
status = papiPrinterPurgeJobs(handle, printer_name, &jobs);
if (status != PAPI_OK) {
/* handle the error */
fprintf(stderr, "papiPrinterPurgeJobs failed: %s\n",
papiServiceGetStatusMessage(handle));
...
}
if (jobs != NULL) {

int i;
for(i=0; jobs[i] != NULL; i++) {
/* process the job */
...
}
papiJobListFree(jobs);
}
...
papiServiceDestroy(handle);

See Also

papiJobCancel, papiJobListFree

papiPrinterListJobs

Description

List print job(s) associated with the specified printer.

Semantics Reference

Get-Jobs in [RFC2911], section 3.2.6

Syntax

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

Inputs

handle

Handle to the print service to use.

name

The name or URI of the printer to query.

requested_attrs

(optional) NULL terminated array of attributes to be queried. If NULL is passed then all available attributes are queried. (NOTE: The printer may return more attributes than you requested. This is merely an advisory request that may reduce the amount of data returned if the printer/server supports it.)

type_mask

A bit mask which determines what jobs will get returned. The following constants can be bitwise-OR-ed together to select which types of jobs to list:

#define PAPI_LIST_JOBS_OTHERS 0x0001 /* return jobs other than
those submitted by the
user name associated with
the handle */
#define PAPI_LIST_JOBS_COMPLETED 0x0002 /* return completed jobs */
#define PAPI_LIST_JOBS_NOT_COMPLETED 0x0004 /* return not-completed
jobs */
#define PAPI_LIST_JOBS_ALL 0xFFFF /* return all jobs */

max_num_jobs

Limit to the number of jobs returned. If 0 is passed, then there is no limit to the number of jobs which may be returned.

Outputs

jobs

List of job objects returned.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_job_t *jobs = NULL;
char *job_attrs[] = {
“job-id”, “job-name”, “job-originating-user-name”,
“job-state”, “job-state-reasons”, “job-state-message” };
...
status = papiPrinterListJobs(handle, printer_name, job_attrs,
PAPI_LIST_JOBS_ALL, 0, &jobs);
...
if (jobs != NULL) {

int i;
for(i = 0; jobs[i] != NULL; i++) {
/* process the job */
...
}
papiJobListFree(jobs);
}
...
papiServiceDestroy(handle);

See Also

papiJobQuery, papiJobListFree

papiPrinterGetAttributeList

Description

Get the attribute list associated with a printer object.

This function retrieves an attribute list from a printer object returned in a previous call. Printer objects are returned as the result of operations performed by papiPrintersList, papiPrinterQuery, and papiPrinterModify.

Syntax

papi_attribute_t **papiPrinterGetAttributeList(papi_printer_t printer );

Inputs

printer

Handle of the printer object.

Outputs

none

Returns

Pointer to the attribute list associated with the printer object. This attribute list is deallocated when the printer object it was retrieved from is deallocated using papiPrinterFree(printer).

Example

papi_attribute_t **attrs = NULL;
papi_printer_t printer = NULL;
...
attrs = papiPrinterGetAttributeList(printer);
...
papiPrinterFree(printer);

See Also

papiPrintersList, papiPrinterQuery, papiPrinterModify

papiPrinterFree

Description

Free a printer object.

Syntax

void papiPrinterFree(papi_printer_t printer);

Inputs

printer

Handle of the printer object to free.

Outputs

none

Returns

none

Example

papi_printer_t printer = NULL;
...
papiPrinterFree(printer);

See Also

papiPrinterQuery, papiPrinterModify

papiPrinterListFree

Description

Free a list of printer objects.

Syntax

void papiPrinterListFree(papi_printer_t *printers);

Inputs

printers

Pointer to the printer object list to free.

Outputs

none

Returns

none

Example

papi_printer_t* printers = NULL;
...
papiPrinterListFree(printers);

See Also

papiPrintersList

Job API

The job segment of the PAPI provides a means of interacting with job objects contained in a print service. This interaction can include listing, querying, creating, modifying, canceling, holding, releasing, and restarting the job objects themselves.

The papiJobSubmit, papiJobSubmitByReference, papiJobStreamOpen, and papiJobStreamClose functions provide a means of creating job objects under a print service. The papiJobValidate function can be used to determine if a job submission will be successful. Each of these functions results in a job object with an attribute list that can be queried to determine what the resulting job looks like.

The papiJobQuery function queries all/some of the attributes of a job. A successful call to papiJobQuery is typically followed by code which examines and processes the returned attributes. When the calling program is finished with the job object and it's attributes, it should then call papiJobFree to delete the returned results.

Jobs and job state can be modified through the use of papiJobModify, papiJobHold, papiJobRelease, and papiJobRestart. The papiJobModify call returns a job object that contains a representation of the modified job. The job object's attribute list can be queried to determin what the resulting job looks like. When the calling program is finished with the job object and it's attributes, it should then call papiJobFree to delete the returned results.

papiJobSubmit

Description

Submits a print job having the specified attributes to the specified printer. This interface copies the specified print files before returning to the caller (contrast to papiJobSubmitByReference). The caller must call papiJobFree when done in order to free the resources associated with the returned job object. Attributes of the print job may be passed in the job_attributes argument and/or in a job ticket (using the job_ticket argument). If both are specified, the attributes in the job_attributes list will be applied to the job_ticket attributes and the resulting attribute set will be used.

Semantics Reference

Print-Job in [RFC2911], section 3.2.1

Syntax

papi_status_t papiJobSubmit(papi_service_t handle, char *printer_name,
papi_attribute_t **job_attributes,
papi_job_ticket_t *job_ticket,
char **file_names, papi_job_t *job );

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name of the printer to which the job is to be submitted.

job_attributes

(optional) The list of attributes describing the job and how it is to be printed. If options are specified here and also in the job ticket data, the value specified here takes precedence. If this is NULL then only default attributes and (optionally) a job ticket is submitted with the job.

job_ticket

(optional) Pointer to structure specifying the job ticket. If this argument is NULL, then no job ticket is used with the job. Whether the implementation passes both the attributes and the job ticket to the server/printer, or merges them to some print protocol or internal representation depends on the implementation.

file_names

NULL terminated list of pointers to names of files to print. If more than one file is specified, the files will be treated by the print system as separate "documents" for things like page breaks and separator sheets, but they will be scheduled and printed together as one job and the specified attributes will apply to all the files.

These file names may contain absolute path names or relative path names (relative to the current path). The implementation MUST copy the file contents before returning.

Outputs

job

The resulting job object representing the submitted job. The caller must deallocate this object using papiJobFree() when finished using it.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_attribute_t **attrs = NULL;
papi_job_ticket_t *ticket = NULL;
char *files[] = { "/etc/motd", NULL };
papi_job_t job = NULL;
...
papiAttributeListAddString(attrs, "job-name", PAPI_ATTR_EXCL,
PAPI_STRING, 1, "test job");
papiAttributeListAddInteger(attrs, "copies", PAPI_ATTR_EXCL,
PAPI_INTEGER, 4);
...
status = papiJobSubmit(handle, “printer”, attrs, ticket, files, &job);
papiAttributeListFree(attrs);
...
if (job != NULL) {
/* look at the job object (maybe get the id) */
papiJobFree(job);
}
...

See Also

papiJobSubmitByReference, papiJobValidate, papiJobStreamOpen, papiJobStreamWrite, papiJobStreamClose, papiJobFree

papiJobSubmitByReference

Description

Submits a print job having the specified attributes to the specified printer. This interface delays copying the specified print files as long as possible, ideally only "pulling" the files when the printer is actually printing the job (contrast to papiJobSubmit).

Attributes of the print job may be passed in the job_attributes argument and/or in a job ticket (using the job_ticket argument). If both are specified, the attributes in the job_attributes list will be applied to the job_ticket attributes and the resulting attribute set will be used.

Semantics Reference

Print-URI in [RFC2911], section 3.2.2

Syntax

papi_status_t papiJobSubmitByReference(papi_service_t handle,
char *printer_name,
papi_attribute_t **job_attributes,
papi_job_ticket_t *job_ticket,
char **file_names, papi_job_t *job );

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name of the printer to which the job is to be submitted.

job_attributes

(optional) The list of attributes describing the job and how it is to be printed. If options are specified here and also in the job ticket data, the value specified here takes precedence. If this is NULL then only default attributes and (optionally) a job ticket is submitted with the job.

job_ticket

(optional) Pointer to structure specifying the job ticket. If this argument is NULL, then no job ticket is used with the job. Whether the implementation passes both the attributes and the job ticket to the server/printer, or merges them to some print protocol or internal representation depends on the implementation.

file_names

NULL terminated list of pointers to names of files to print. If more than one file is specified, the files will be treated by the print system as separate "documents" for things like page breaks and separator sheets, but they will be scheduled and printed together as one job and the specified attributes will apply to all the files.

These file names may contain absolute path names, relative path names or URIs ([RFC1738], [RFC2396]). The implementation SHOULD NOT copy the referenced data unless (or until) it is no longer feasible to maintain the reference. Feasibility limitations may arise out of security issues, name space issues, and/or protocol or printer limitations.

Implementations MUST support the absolute path, relative path, and "file:" URI scheme. Use of other URI schemes could result in a PAPI_URI_SCHEME error, depending on the implementation.

The semantics explained in the preceding paragraphs allows for flexibility in the PAPI implementation. For example: (1) PAPI on top of a local service to maintain the reference for the life of the job, if the local service supports it. (2) PAPI on top of IPP to send a reference when the server can access the referenced data and copy it when it is not accessible to the server. (3) PAPI on top of network printing protocols that don't support references to copy the data on the way out to the remote server.

Outputs

job

The resulting job object representing the submitted job. The caller must deallocate this object using papiJobFree() when finished using it.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_attribute_t **attrs = NULL;
papi_job_ticket_t *ticket = NULL;
char *files[] = { "/etc/motd", NULL };
papi_job_t job = NULL;
...
papiAttributeListAddString(attrs, "job-name", PAPI_ATTR_EXCL,
PAPI_STRING, 1, "test job");
papiAttributeListAddInteger(attrs, "copies", PAPI_ATTR_EXCL,
PAPI_INTEGER, 4);
status = papiJobSubmitByReference(handle, “printer”, attrs, ticket,
files, &job);
papiAttributeListFree(attrs)
...
if (job != NULL) {
/* look at the job object (maybe get the id) */
papiJobFree(job);
}
...

See Also

papiJobSubmit, papiJobValidate, papiJobStreamOpen, papiJobStreamWrite, papiJobStreamClose, papiJobFree

papiJobValidate

Description

Validates the specified job attributes against the specified printer. This function can be used to validate the capability of a print object to accept a specific combination of attributes.

Attributes of the print job may be passed in the job_attributes argument and/or in a job ticket (using the job_ticket argument). If both are specified, the attributes in the job_attributes list will be applied to the job_ticket attributes and the resulting attribute set will be used.

Semantics Reference

Validate-Job in [RFC2911], section 3.2.3

Syntax

papi_status_t papiJobValidate(papi_service_t handle, char *printer_name,
papi_attribute_t **job_attributes,
papi_job_ticket_t *job_ticket,
char **file_names, papi_job_t *job );

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name of the printer to which the job is to be validated.

job_attributes

(optional) The list of attributes describing the job and how it is to be printed. If options are specified here and also in the job ticket data, the value specified here takes precedence. If this is NULL then only default attributes and (optionally) a job ticket is submitted with the job.

job_ticket

(optional) Pointer to structure specifying the job ticket. If this argument is NULL, then no job ticket is used with the job. Whether the implementation passes both the attributes and the job ticket to the server/printer, or merges them to some print protocol or internal representation depends on the implementation.

file_names

NULL terminated list of pointers to names of files to validate.

Outputs

job

The resulting job object representing the validated job. The caller must deallocate this object using papiJobFree() when finished using it.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_attribute_t **attrs = NULL;
papi_job_ticket_t *ticket = NULL;
char *files[] = { "/etc/motd", NULL };
papi_job_t job = NULL;
...
papiAttributeListAddString(attrs, "job-name", PAPI_ATTR_EXCL,
PAPI_STRING, 1, "test job");
papiAttributeListAddInteger(attrs, "copies", PAPI_ATTR_EXCL,
PAPI_INTEGER, 4);
...
status = papiJobValidate(handle, printer, attrs, ticket, files, &job);
papiAttributeListFree(attrs);
...
if (job != NULL) {
papiJobFree(job);
}
...

See Also

papiJobSubmit, papiJobSubmitByReference, papiJobStreamOpen, papiJobStreamWrite, papiJobStreamClose, papiJobFree

papiJobStreamOpen

Description

Opens a print job and an associated stream of print data to be sent to the specified printer. After calling this function papiJobStreamWrite can be called (repeatedly) to write the print data to the stream, and then papiJobStreamClose is called to complete the submission of the print job.

After this function is called successfully, papiJobStreamClose must eventually be called to close the stream (this includes all error paths).

Attributes of the print job may be passed in the job_attributes argument and/or in a job ticket (using the job_ticket argument). If both are specified, the attributes in the job_attributes list will be applied to the job_ticket attributes and the resulting attribute set will be used.

Syntax

papi_status_t papiJobStreamOpen(papi_service_t handle, char *printer_name,
papi_attribute_t **job_attributes,
papi_job_ticket_t *job_ticket,
papi_stream_t *stream);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name of the printer to which the job is to be validated.

job_attributes

(optional) The list of attributes describing the job and how it is to be printed. If options are specified here and also in the job ticket data, the value specified here takes precedence. If this is NULL then only default attributes and (optionally) a job ticket is submitted with the job.

job_ticket

(optional) Pointer to structure specifying the job ticket. If this argument is NULL, then no job ticket is used with the job. Whether the implementation passes both the attributes and the job ticket to the server/printer, or merges them to some print protocol or internal representation depends on the implementation.

Outputs

stream

The resulting stream object to which print data can be written. The stream object will be deallocated when closed using papiJobStreamClose().

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_attribute_t **attrs = NULL;
papi_job_ticket_t *ticket = NULL;
papi_job_t job = NULL;
char buffer[4096];
size_t buflen = 0;
...
papiAttributeListAddString(attrs, "job-name", PAPI_ATTR_EXCL,
PAPI_STRING, 1, "test job");
papiAttributeListAddInteger(attrs, "copies", PAPI_ATTR_EXCL,
PAPI_INTEGER, 4);
...
status = papiJobStreamOpen(handle, “printer”, attrs, ticket, &stream);
papiAttributeListFree(attrs);
...
while (print_data_remaining) {
status = papiJobStreamWrite(handle, stream, buffer, buflen);
}
...
status = papiJobStreamClose(handle, stream, &job);
...
if (job != NULL) {
...
papiJobFree(job);
}
...

See Also

papiJobStreamWrite, papiJobStreamClose

papiJobStreamWrite

Description

Writes print data to the specified open job stream. The open job stream must have been obtained by a successful call to papiJobStreamOpen

Syntax

papi_status_t papiJobStreamWrite(papi_service_t handle, papi_stream_t stream,
void *buffer, size_t buflen);

Inputs

handle

Handle to the print service to use.

stream

The open stream object to which print data is written.

buffer

Pointer to the buffer of print data to write.

buflen

The number of bytes to write.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

See papiJobStreamOpen

See Also

papiJobStreamOpen, papiJobStreamClose

papiJobStreamClose

Description

Closes the specified open job stream and completes submission of the job (if there were no previous errors returned from papiJobSubmitWrite). The open job stream must have been obtained by a successful call to papiJobStreamOpen.

Syntax

papi_status_t papiJobStreamClose(papi_service_t handle, papi_stream_t stream,
papi_job_t *job);

Inputs

handle

Handle to the print service to use.

stream

The open stream object to close.

Outputs

Job

The resulting job object representing the submitted job. The caller must deallocate this object using papiJobFree() when finished using it.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

See papiJobStreamOpen

See Also

papiJobStreamOpen, papiJobStreamWrite

papiJobQuery

Description

Queries some or all the attributes of the specified job object.

Semantics Reference

Get-Job-Attributes in [RFC2911], section 3.3.4

Syntax

papi_status_t papiJobQuery(papi_service_t handle,char* printer_name,
int32_t job_id, char *requested_attrs[],
papi_job_t *job);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be queried.

requested_attrs

NULL terminated array of attributes to be queried. If NULL is passed then all available attributes are queried. (NOTE: The job may return more attributes than you requested. This is merely an advisory request that may reduce the amount of data returned if the printer/server supports it.)

Outputs

job

The returned job object containing the requested attributes.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_job_t job = NULL;
char *job_attrs[] = {
"job-id", "job-name", "job-originating-user-name",
"job-state", "job-state-reasons", NULL };
...
status = papiJobQuery(handle, “printer”, job_id, job_attrs, &job);
...
if (job != NULL) {
/* process the job */
...
papiJobFree(job);
}
...

See Also

papiPrinterListJobs, papiJobFree

papiJobModify

Description

Modifies some or all the attributes of the specified job object. Upon successful completion, the function will return a handle to an object representing the updated job.

Semantics Reference

Set-Job-Attributes in [RFC3380], section 4.2

Syntax

papi_status_t papiJobModify(papi_service_t handle,char* printer_name,
int32_t job_id, papi_attribute_t **attrs,
papi_job_t *job);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be queried.

attrs

Attributes to be modified. Any attributes not specified are left unchanged.

Outputs

job

The modified job object.

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
papi_job_t job = NULL;
papi_attribute_t **attrs = NULL;
...
papiAttributeListAddString(&attrs, PAPI_EXCL,
"job-name", "sample job");
papiAttributeListAddMetadata(&attrs, PAPI_EXCL,
“media”, PAPI_DELETE);
...
status = papiJobModify(handle, “printer”, 12, attrs, &job);
...
if (job != NULL) {
/* process the job */
...
papiJobFree(job);
}
...

See Also

papiJobFree

papiJobCancel

Description

Cancel the specified print job

Semantics Reference

Cancel Job in [RFC2911], section 3.3.3

Syntax

papi_status_t papiJobCancel(papi_service_t handle, char* printer_name,
int32_t job_id);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be canceled.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiJobCancel(handle, “printer”, 12);
...

See Also

papiPrinterPurgeJobs

papiJobHold

Description

Hold the specified print job

Semantics Reference

Hold Job in [RFC2911], section 3.3.5

Syntax

papi_status_t papiJobHold(papi_service_t handle, char* printer_name,
int32_t job_id);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be held.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiJobHold(handle, “printer”, 12);
...

See Also

papiJobRelease

papiJobRelease

Description

Release the specified print job

Semantics Reference

Release Job in [RFC2911], section 3.3.6

Syntax

papi_status_t papiJobRelease(papi_service_t handle,char* printer_name,
int32_t job_id);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be released.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiJobRelease(handle, “printer”, 12);
...

See Also

papiJobHold

papiJobRestart

Description

Restarts a job that was retained after processing. If and how a job is retained after processing is implementation-specific and is not covered by this API. This operation is optional and may not be supported by all printers/servers.

Semantics Reference

Restart Job in [RFC2911], section 3.3.7

Syntax

papi_status_t papiJobRestart(papi_service_t handle,char* printer_name,
int32_t job_id);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be restart.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiJobRestart(handle, “printer”, 12);
...

See Also

papiJobHold, papiJobRelease

papiJobPromote

Description

Promotes a job to the front of the queue so that it may be printed after any currently printing job completes. This operation is optional and may not be supported by all printers/servers.

Semantics Reference

Restart Job in [RFC2911], section 3.3.7

Syntax

papi_status_t papiJobPromote(papi_service_t handle,char* printer_name,
int32_t job_id);

Inputs

handle

Handle to the print service to use.

printer_name

Pointer to the name or URI of the printer to which the job was submitted.

job_id

The ID number of the job to be promoted.

Outputs

none

Returns

If successful, a value of PAPI_OK is returned. Otherwise an appropriate failure value is returned.

Example

papi_status_t status;
papi_service_t handle = NULL;
...
status = papiJobPromote(handle, “printer”, 12);
...

See Also

papiJobHold, papiJobRelease

papiJobGetAttributeList

Description

Get the attribute list associated with a job object.

This function retrieves an attribute list from a job object returned in a previous call. Job objects are returned as a result of the operations performed by papiPrinterListJobs, papiJobQuery, papiJobModify, papiJobSubmit, papiJobSubmitByReference, papiJobValidate, and papiJobStreamClose.

Syntax.

papi_attribute_t **papiJobGetAttributeList(papi_job_t job);

Inputs

job

Handle of the job object.

Outputs

none

Returns

The attribute list associated with the job object. The attribute list is deallocated when the containing job object is destroyed using papiJobFree().

Example

papi_job_t job = NULL;
papi_attribute_list **attrs = NULL;
...
attrs = papiJobGetAttributeList(job);
...
papiJobFree(job);

See Also

papiPrinterListJobs, papiJobQuery, papiJobModify, papiJobSubmit, papiJobSubmitByReference, papiJobValidate, papiJobStreamClose

papiJobGetPrinterName

Description

Get the printer name associated with a job object.

Syntax.

char *papiJobGetPrinterName(papi_job_t job);

Inputs

job

Handle of the job object.

Outputs

none

Returns

Pointer to the printer name associated with the job object. The resulting string is deallocated when the containing job object is destroyed using papiJobFree().

Example

char *printer = NULL;
papi_job_t job = NULL;
...
printer = papiJobGetPrinterName(job);
...
papiJobFree(job);

See Also

papiJobGetAttributeList

papiJobGetId

Description

Get the job ID associated with a job object.

Syntax.

int32_t papiJobGetId(papi_job_t job);

Inputs

job

Handle of the job object.

Outputs

none

Returns

The job id associated with the job object.

Example

papi_job_t job = NULL;
int32_t id;
...
id = papiJobGetId(job);
...
papiJobFree(job);

See Also

papiJobGetAttributeList

papiJobGetJobTicket

Description

Get the job ticket associated with a job object. The job ticket is deallocated when the containing job object is destroyed using papiJobFree().

Syntax

papi_job_ticket_t *papiJobGetJobTicket(papi_job_t job);

Inputs

job

Handle of the job object.

Outputs

none

Returns

Pointer to the job ticket associated with the job object.

Example

papi_job_t job = NULL;
papi_job_ticket_t *ticket;
...
ticket = papiJobGetJobTicket(job);
...
papiJobFree(job);

See Also

papiJobSubmit, papiJobSubmitByReference, papiJobValidate, papiJobStreamOpen

papiJobFree

Description

Free a job object.

Syntax

void papiJobFree(papi_job_t job );

Inputs

Job

Handle of the job object to free.

Outputs

none

Returns

none

Example

papi_job_t job = NULL;
...
papiJobFree(job);

See Also

papiJobSubmit, papiJobSubmitByReference, papiJobValidate, papiJobStreamClose, papiJobQuery, papiJobModify

papiJobListFree

Description

Free a job list.

Syntax

void papiJobListFree(papi_job_t *job );

Inputs

Job

Handle of the job list to free.

Outputs

none

Returns

none

Example

papi_job_t *jobs = NULL;
...
papiJobListFree(jobs);

See Also

papiPrinterListJobs

Miscellaneous API

papiStatusString

Description

Get a status string for the specified papi_status_t. The status message returned from this function may be less detailed than the status message returned from papiServiceGetStatusMessage (if the print service supports returning more detailed error messages)

Syntax

char *papiStatusString(papi_status_t status);

Inputs

status

The status value to convert to a status string

Outputs

none

Returns

The returned string provides a (potentially localized) human readable message representing the status provided. The return value should not be deallocated by the caller.

Example

papi_status_t status;
char *message;
...
message = papiServiceGetStatusMessage(handle);
...

See Also

PapiServiceGetStatusMessage

papiLibrarySupportedCalls

Description

The papiLibrarySupportedCalls() function can be called to request a list of API functions that are supported in the implementation. Support for a function means that the implementation of that function is not a stub that simply returns PAPI_OPERATION_NOT_SUPPORTED

Syntax

char **papiLibrarySupportedCalls();

Inputs

none

Outputs

none

Returns

A NULL terminated list of supported function names. This list should not be deallocated by the caller.

Example

papi_service_t handle = NULL;
char **calls;
...
calls = papiLibrarySupportedCalls(handle);
...

See Also

Conformance Table

papiLibrarySupportedCall

Description

The papiLibrarySupportedCalls() function can be called to request a list of API functions that are supported in the implementation. Support for a function means that the implementation of that function is not a stub that simply returns PAPI_OPERATION_NOT_SUPPORTED

Syntax

char papiLibrarySupportedCall(char *name);

Inputs

name

The name of the function that is being asked about

Outputs

none

Returns

A return of PAPI_TRUE indicates that the named function is supported by the API implementation. A return of PAPI_FALSE indicates that the the named function is not supported by the API implementation.

Example

papi_service_t handle = NULL;
char supported;
...
supported = papiLibrarySupportedCall(handle, “papiJobQuery”);
...

See Also

ConformanceProfiles

Capabilities

Introduction

In the context of this document, printer capabilities refers to information about the features, options, limitation, etc. of a print device (either an actual device or an abstract device which may represent a group or pool of actual devices). This includes such information as:

Does the printer support color printing?

At what resolution(s) can the printer print?

What input trays are present?

What size media is loaded in each tray?

Which trays are manual-feed and which are auto-feed?

Can the printer print duplex output?

What is the printable area on each of the loaded media?

What output bins are present?

What finishing (staple, punch, etc.) does the printer support?

What combinations of features are not allowed together?

What features should be presented on the print user interface?

... and many others...

The uses of printer capabilities by applications include:

To control how to display print options in a print UI dialog. Examples:

What values to put in the bin selection pull-down lists

Whether or not to gray-out the duplex option when a particular output bin has been selected.

Whether or not to display a color vs. black and white selection

To Control how the print data stream is generated. Examples:

How large an image to draw to fill the printable area.

How much to shift the image if “3-hole punch” finishing has been selected.

How to request that the printer print on paper from the manual envelope feeder

To do job validation and printer selection. Examples:

Can I print this job with these options on this printer?

Find a printer which can print this job with these options.

Objectives

This section attempts to describe the objectives of the PAPI printer capabilities support. It is important to understand these objectives in order to understand why the support is structured the way that it is.

Standard printer capabilities API

There is no standard API which a Linux application can use to retrieve printer capabilities regardless of the device, driver, and print server being used. This makes it very difficult for application writers to support generating print data without writing multiple versions of the print logic or without tying the application to very specific print system environments. This specification provides the standard API, making applications which use it independent of the underlying print system.

Independent of underlying source of capabilities

The capabilities information returned to the application may come from one of a variety of sources or combination of sources. The data retrieved from these sources may be represented in a variety of formats, including:

PPD files

UPDF database

SNMP queries

Device drivers

The API defined here hides these differences so that the application is independent of data source and format used.

Support returning information in context

The API supports a means for requesting capabilities information in the context of a particular set of job options. For example, set of printer capabilities can be queried given that medium and color/black-and-white selections have already been made.

Support returning constraints

The API must support a means for returning constraints on printer capabilities. This allows applications to not submit job with disallowed combinations of options, and to display better print job dialogs (gray-out potentially conflicting options, highlight conflicting options that have been selected, display an error message when invalid comb9inatoins are submitted, etc.).

The constraints returned should should allow some level of “boolean logic”, including negation, to simplify the information returned. For example, to not allow doing finishing when transparencies are selected as the medium, it would be preferable if the constraints could express “(type – transparency) AND (finishing NOT = none)” instead of having to list a combination of “(type = transparency)” with every possible finishing value other than “none”.

Support returning display hints

The API should support a means of returning “display hints”. This is information that the application can use to display print options in a print dialog that is easy to use. For example, returning information about which options should be displayed on the “main window”, which should be displayed in an “advanced” dialog, and which should not be displayed at all.

Support logically grouping features

The API should support a means of returning logical groupings of printer features. This is information about combinations of lower-level features that can be displayed and selected as a group to make the user interface easier to use. For example, a group of features called “black-and-white-draft” could include a logical setting of the color, resolution, and print density options.

The feature group support should be an open, extendible way for printer vendors and print administrators to express logical and commonly used groupings of print options that make it easier for end-users to take advantage of lower-level printer features. They should not be used to blindly list all possible combinations of a set of options, whether or not all the combinations make sense.

Interfaces

Query Functionality

The API used by the application to retrieve printer capabilities is the papiPrinterQuery function. See the description of that function for further details.

Capability Attributes

In addition to the xxx-supported attributes defined by the IPP standard [RFC2911], this section defines new attributes needed to satisfy the objectives described above.

Job-constraints-col (1 setOf collection)

Constraints are expressed in the printer object's job-constraints-col attribute. This attribute is multi-valued with each value having collection syntax. Each value is, in fact, an attribute list that represents one combination of job attributes/values which are not allowed for that printer. If an attribute in the collection does not have a value, then all values of that attribute are disallowed in this combination.

The set of values associated with job-constraints-col represents the complete set of job attribute constraints associated wit the containing printer object.

The attribute values in job-constraints-col may also be in range syntax, if the corresponding job attribute has integer syntax. This represents the included (or excluded, if the attribute is named in job-constraints-inverted) range of values of that attribute within that constraint.

Job-constraints-inverted (1setOf type2 keyword)

The job-constraints-inverted attribute lists the names of other attributes in the current job-constraints-col value whose comparison logic must be inverted. That is, the values of named attributes are to be excluded (“not equal to” values) from the constraint. If an attribute name is not included in the job-constraints-inverted attribute, then that attribute's values are to be included (“equal to” values) in the constraint.

You can think of the each att5ribute in a job-constraints-cols value as AND-ed together to express a disallowed combination of options: “(attr1 == values) AND (attr2 == values) AND ...”. The job constraints-inverted attribute lists those attribute/value comparisons which are to be “!=” instead of “==”.

Example

Here is an example of how the job-constraints-col attribute can be used to express various printer constraints. The example is expressed in pseudo-code with curly brackets enclosing each collection value and attributes within each collection are shown on separate lines with commas separating the values (this is the PAPI text encoding format documented in Chapter11: Attribute List Text Representation, with the addition of not-legal-syntax comments in “/* ... */” to help describe the examples):

job-constraints-col = {
/*
* Constraint: no high print quality with 240 dpi resolution
* (print-quality == high) AND (printer-resolution == 240dpi)
/
{
print-quality = high
printer -resolution = 240dpi
},
/*
* Constraint: no transparency with duplex
* (sides != one-sided) AND (media – transparency)
/
{
job-constraints-inverted = sides
sides = one-sided
media = transparency
},
/*
* Constraint: no finishing with heavy-stock media
* (finishings != none) AND (media == heavy-stock)
/
{
job-constraints-inverted = finishing
finishings = none
media = heavy-stock
},
/*
* Constraint: no duplex printing of A4 paper in landscape
* (sides != one-sided) AND (media == A4) AND
* (orientation-requested == landscape)
/
{
job-constraints-inverted = sides
sides = one-sided
media = A4
orientation-requested = landscape
},
/*
* Constraint: no duplex printing of COM-10 envelopes
* (sides != one-sided) AND (media == envelope) AND
* (media-size == com10)
/
{
job-constraints-inverted = sides
sides = one-sided
media = envelope
media-size = com10
},
/*
* Constraint: no stapling of greater than 50 sheets
* (finishings == staple) AND (job-media-sheets > 50)
*/
{
job-constraints-inverted = job-media-sheets
finishings = staple
job-media-sheets = 1-50
}
};

Validation Function

The API used by the application to validate print job attributes against printer capabilities is the papiJobValidate function. See the description of that function for further details.

Attributes

For a summary of the IPP attributes which can be used with the PAPI interface, see: ftp://ftp.pwg.org/pub/pwg/fsg/spool/IPP-Object-Attributes.pdf

Extension Attributes

The following attributes are not currently defined by IPP, but may be used with this API.

Job-ticket-formats-supported

(1setOf type2 keyword) This optional printer attribute lists the job ticket formats that are supported by the printer. If this attribute is not present, it is assumed that the printer does not support any job ticket formats

media-margins

(1setOf integer) The media-margins attribute defines the printable margins for the current printer object and consists of exactly 4 or 8 ordered integers. Each group of 4 integers represent the minimum distance from the top, right, bottom, and left edges of the media in 100ths of millimeters.

If 4 integers are provided, the margins are the same for the front and back sides of the media when producing duplexed output. If 8 integers are provided, the first 4 integers represent the margins for the front side and the last 4 integers represent the margins for the back side of the media.

Currently the margin values only represent the minimum margins that can be used with all sizes and types of media. Future versions of the PAPI specification may define an interface for getting the margin values for specific combinations of job template attributes.

Required Job Attributes

The following job attributes must be supported to comply with this API standard. These attributes may be supported by the underlying print server directly, or they may be mapped by the PAPI library.

job-id

job-name

job-originating-user-name

job-printer-uri

job-state

job-state-reasons

job-uri

time-at-creation

time-at-processing

time-at-completed

Required Printer Attributes

The following printer attributes must be supported to comply with this API standard. These attributes may be supported by the underlying print server directly, or they may be mapped by the PAPI library.

charset-configured

charset-supported

compression-supported

document-format-default

document-format-supported

generated-natural-language-supported

natural-language-configured

operations-supported

pdl-override-supported

printer-is-accepting-jobs

printer-name

printer-state

printer-state-reasons

printer-up-time

printer-uri-supported

queued-job-count

uri-authentication-supported

uri-security-supported

IPP Attribute Type Mapping

The following table maps IPP to PAPI attribute value types:

IPP Type	PAPI Type
boolean	PAPI_BOOLEAN
charset	PAPI_STRING
collection	PAPI_COLLECTION
dateTime	PAPI_DATETIME
enum	PAPI_INTEGER (with C enum values)
integer	PAPI_INTEGER
keyword	PAPI_STRING
mimeMediaType	PAPI_STRING
name	PAPI_STRING
naturalLanguage	PAPI_STRING
octetString	not yet supported
rangeOfInteger	PAPI_RANGE
resolution	PAPI_RESOLUTION
text	PAPI_STRING
uri	PAPI_STRING
uriScheme	PAPI_STRING
1setOf X	C array
OOB (unused, delete, unsupported, etc.)	PAPI_METADATA (with enum value)

Attribute List Text Representation

ABNF Definition

The following ABNF definition [RFC2234] describes the syntax of PAPI attributes encoded as text options:

OPTION-STRING = [OPTION] *(1*WC OPTION) *WC
OPTION = TRUEOPTION / FALSEOPTION / VALUEOPTION
TRUEOPTION = NAME
FALSEOPTION = "no" NAME
VALUEOPTION = NAME "=" VALUE *( "," VALUE )
NAME = 1*NAMECHAR
NAMECHAR = DIGIT / ALPHA / "-" / "_" / "."
VALUE = BOOLVALUE / COLVALUE / DATEVALUE / NUMBERVALUE / QUOTEDVALUE /
RANGEVALUE / RESVALUE / STRINGVALUE
BOOLVALUE = "yes" / "no" / "true" / "false"
COLVALUE = "{" OPTION-STRING "}"
DATEVALUE = HOUR MINUTE [ SECOND ] / YEAR MONTH DAY /
YEAR MONTH DAY HOUR MINUTE [ SECOND ]
YEAR = 4DIGIT
MONTH = "0" %x31-39 / "10" / "11" / "12"
DAY = %x30-32 DIGIT / "1" DIGIT / "2" DIGIT / "30" / "31"
HOUR = %x30-31 DIGIT / "1" DIGIT / "20" / "21" / "22" / "23"
MINUTE = %x30-35 DIGIT
SECOND = %x30-35 DIGIT
NUMBERVALUE = 1*DIGIT / "-" 1*DIGIT / "+" 1*DIGIT
QUOTEDVALUE = DQUOTE *QUOTEDCHAR DQUOTE / SQUOTE *QUOTEDCHAR SQUOTE
QUOTEDCHAR = %x5C %x5C / %x5C DQUOTE / %x5C SQUOTE /
%x5C 3OCTALDIGIT / %x21 / %x23-26 / %x28-5B /
%x5D-7E / %xA0-FF
OCTALDIGIT = %x30-37
RANGEVALUE = 1*DIGIT "-" 1*DIGIT
RESVALUE = 1*DIGIT [ "x" 1*DIGIT ] ("dpi" / "dpc")
STRINGVALUE = 1*STRINGCHAR
STRINGCHAR = %x5C %x20 / %x5C %x5C / %x5C DQUOTE / %x5C SQUOTE /
%x5C 3OCTALDIGIT / %x21 / %x23-26 / %x28-5B /
%x5D-7E / %xA0-FF
SQUOTE = %x27
WC = %x09 / %x0A / %x20

Examples

The following example strings illustrate the format of text options:

Boolean Attributes

foo
nofoo
foo=false
foo=true
foo=no
foo=yes

Collection Attributes

media-col={media-size={x-dimension=123 y-dimension=456}}

Integer Attributes

copies=123
hue=-123

String Attributes

job-sheets=standard
job-sheets=standard,standard
media=na-custom-foo.8000-10000
job-name=John\'s\ Really\040Nice\ Document

String Attributes (quoted)

job-name="John\'s Really Nice Document"
document-name='Another \"Word\042 document.doc'

Range Attributes

page-ranges=1-5
page-ranges=1-2,5-6,101-120

Date Attributes

job-hold-until-datetime=1234
job-hold-until-datetime=123456
job-hold-until-datetime=20020904
job-hold-until-datetime=200209041234
job-hold-until-datetime=20020904123456

Resolution Attributes

resolution=360dpi
resolution=720x360dpi
resolution=1000dpc

Multiple Attributes

job-sheets=standard page-ranges=1-2,5-6,101-120 resolution=360dpi

Conformance

There are some cases where it may not be necessary or even desirable to implement the interfaces defined in this specification in their entirety. This section describes which elements of the interfaces must be implemented and defines sets of interfaces that may be implemented. The sets of interfaces that may be implemented define various levels of conformance. Conformance to a particular level may only be claimed by an implementation if and only if all of the interfaces defined in that level are implemented as described in their associated section of this document. These implementations may only return PAPI_OPERATION_NOT_SUPPORTED if and only if the underlying support has been administratively disabled. Regardless of conformance level claimed by an implementation, the header file for every implementation must be complete. That is to say that it must include a complete set of type definitions, enumeration and function prototypes.

Query Profile

The Query Profile is defined to provide querying functionality. A PAPI implementation conforming to the Query Profile must provide code for all functions defined in the PAPI and must support all of the definitions in the “papi.h” C header file. For each function defined in the PAPI specification, a conforming implementation must either perform the requested function or return the PAPI_OPERATION_NOT_SUPPORTED status code (see section 3.8). The PAPI_OPERATION_NOT_SUPPORTED status code indicates either (1) that the PAPI implementation doesn’t provide any support for the function, i.e., the function is stubbed out, or (2), the PAPI implementation does provide code support for the function, but the Printer or Print system selected by the application does not support the corresponding function.

lists the functions and attributes that a PAPI implementation is REQUIRED to provide code support in order to claim conformance to the Query Profile. The blank entries are OPTIONAL for a PAPI implementation to support.

Job Submission Profile

The Job Submission Profile is defined to provide the job submission functionality and is a superset of the Querying Profile. lists the functions and attributes that a PAPI implementation is REQUIRED to provide code support in order to claim conformance to the Job Submission Profile. The blank entries are OPTIONAL for a PAPI implementation to support.

Conformance Table

PAPI Functions & Attributes	Query Profile	Job Submission Profile
Chapter3: Common Structures	All Structures	All Structures
Chapter4: Attributes API		
4.1 papiAttributeListAdd	REQUIRED	REQUIRED
4.2 papiAttributeListAddString	REQUIRED	REQUIRED
4.3 papiAttributeListAddInteger	REQUIRED	REQUIRED
4.4 papiAttributeListAddBoolean	REQUIRED	REQUIRED
4.5 papiAttributeListAddRange	REQUIRED	REQUIRED
4.6 papiAttributeListAddResolution	REQUIRED	REQUIRED
4.7 papiAttributeListAddDatetime	REQUIRED	REQUIRED
4.8 papiAttributeListAddCollection	REQUIRED	REQUIRED
4.9 papiAttributeListDelete	REQUIRED	REQUIRED
4.10 papiAttributeListGetValue	REQUIRED	REQUIRED
4.11 papiAttributeListGetString	REQUIRED	REQUIRED
4.12 papiAttributeListGetInteger	REQUIRED	REQUIRED
4.13 papiAttributeListGetBoolean	REQUIRED	REQUIRED
4.14 papiAttributeListGetRange	REQUIRED	REQUIRED
4.15 papiAttributeListGetResolution	REQUIRED	REQUIRED
4.16 papiAttributeListGetDatetime	REQUIRED	REQUIRED
4.17 papiAttributeListGetCollection	REQUIRED	REQUIRED
4.18 papiAttributeListFree	REQUIRED	REQUIRED
4.19 papiAttributeListFind	REQUIRED	REQUIRED
4.20 papiAttributeListGetNext	REQUIRED	REQUIRED
4.21 papiAttributeListFromString		
4.22 papiAttributeListToString		
Chapter5: Service API	All Functions	All Functions
Chapter6: Printer API		
6.2 papiPrintersList	REQUIRED	REQUIRED
6.3 papiPrinterQuery	REQUIRED	REQUIRED
6.4 papiPrinterModify		
6.5 papiPrinterPause		
6.6 papiPrinterResume		
6.7 papiPrinterPurgeJobs		
6.8 papiPrinterListJobs	REQUIRED	REQUIRED
6.9 papiPrinterGetAttributeList	REQUIRED	REQUIRED
6.10 papiPrinterFree	REQUIRED	REQUIRED
6.11 papiPrinterListFree	REQUIRED	REQUIRED
Chapter7: Job API		
7.1 papiJobSubmit		REQUIRED
7.2 papiJobSubmitByReference		REQUIRED
7.3 papiJobValidate		
7.4 papiJobStreamOpen		REQUIRED
7.5 papiJobStreamWrite		REQUIRED
7.6 papiJobStreamClose		REQUIRED
7.7 papiJobQuery	REQUIRED	REQUIRED
7.8 papiJobModify		REQUIRED
7.9 papiJobCancel		REQUIRED
7.10 papiJobHold		REQUIRED
7.11 papiJobRelease		REQUIRED
7.12 papiJobRestart		REQUIRED
7.13 papiJobGetAttributeList		REQUIRED
7.14 papiJobGetPrinterName		REQUIRED
7.15 papiJobGetId		REQUIRED
7.16 papiJobGetJobTicket		
7.17 papiJobFree		REQUIRED
7.18 papiJobListFree		REQUIRED
Chapter8: Miscellaneous API		
8.1 papiStatusString		REQUIRED
8.2 papiLibrarySupportedCalls		REQUIRED
8.3 papiLibrarySupportedCall		REQUIRED
Chapter9: Attributes		
9.1.1 Job-ticket-formats-supported	REQUIRED	REQUIRED
9.1.2 media-margins	REQUIRED	REQUIRED
9.2 Required Job Attributes	REQUIRED	REQUIRED
9.3 Required Printer Attributes	REQUIRED	REQUIRED
9.4 IPP Attribute Type Mapping	REQUIRED	REQUIRED

Sample Code

Sample implementations of this specification and client applications built upon it can be found at http://www.openprinting.org/PAPI/source/... While the implemenations and clients applications found there are intended to be true to the spec, they are not authoritative. This document is the athoritavie definition of the Free Standard Group Open Standard Print API (PAPI).

References

Internet Printing Protocol (IPP)

IETF RFCs can be obtained from "http://www.rfc-editor.org/rfcsearch.html". Other IPP documents can be obtained from "http://www.pwg.org/ipp/index.html" and "ftp://ftp.pwg.org/pub/pwg/ipp/new_XXX/".

[RFC2911] T. Hastings R. Herriot R. deBry S. Isaacson and P. Powell August 1998 Internet Printing Protocol/1.1: Model and Semantics (Obsoletes 2566)

[RFC3196] T. Hastings H. Holst C. Kugler C. Manros and P. Zehler November 2001 Internet Printing Protocol/1.1: Implementor's Guide

[RFC3380] T. Hastings R. Herriot C. Kugler and H. Lewis September 2002 Internet Printing Protocol (IPP): Job and Printer Set Operations

[RFC3381] T. Hastings H. Lewis and R. Bergman September 2002 Internet Printing Protocol (IPP): Job Progress Attributes

[RFC3382] R. deBry T. Hastings R. Herriot K. Ocke and P. Zehler September 2002 Internet Printing Protocol (IPP): The 'collection' attribute syntax

[5100.2] T. Hastings and R. Bergman IEEE-ISTO 5100.2 February 2001 Internet Printing Protocol (IPP): output-bin attribute extension

[5100.3] T. Hastings and K. Ocke IEEE-ISTO 5100.3 February 2001 Internet Printing Protocol (IPP): Production Printing Attributes

[5100.4] R. Herriot and K. Ocke IEEE-ISTO 5100.4 February 2001 Internet Printing Protocol (IPP): Override Attributes for Documents and Pages

[5101.1] T. Hastings and D. Fullman IEEE-ISTO 5101.1 February 2001 Internet Printing Protocol (IPP): finishings attribute values extension

[ops-set2] C. Kugler T. Hastings and H. Lewis July 2001 Internet Printing Protocol (IPP): Job and Printer Administrative Operations

Job Ticket

[jdf] CIP4 Organization April 2002 Job Definition Format (JDF) Specification Version 1.1

Printer Working Group (PWG)

[PWGSemMod] P. Zehler and Albright September 2002 Printer Working Group (PWG): Semantic Model

Other

[RFC1738] T. Berners-Lee L. Masinter and M. McCahill December 1994 Uniform Resource Locators (URL) (Updated by RFC1808, RFC2368, RFC2396)

[RFC2234] D. Crocker and P. Overell November 1997 Augmented BNF for Syntax Specifications: ABNF

[RFC2396] T. Berners-Lee R. Fielding and L. Masinter August 1998 Uniform Resource Locators (URL): Generic Syntax (Updates RFC1808, RFC1738)

Change History

Version 0.92 (January 12, 2005).

Added administrative operations: papiPrinterAdd, papiPrinterRemove, papiPrinter Enable, papaPrinterDisable, papiJobPromote.

Version 0.91 (January 28, 2004).

Pruned several example code excerpts to the essential information required to get a better understanding of the various calls.

Added/modified introductory text for Attribute, Service, Printer, and Job API chapters.

Added papi_metadata_t type/support for various OOB IPP types that we need to support.

Converted from SGML to OpenOffice to be able to use versioning, change bars, line number, ... (will begin using versioning and change bars after this release)

Added numerous cross references.

Added papiLibrarySupportedCall() and papiLibrarySupportedCalls(). To enumerate/verify actual support for a function in the library

Added papiServiceGetAttributeList() call to retrieve print service and implementation specific information from a service handle.

Added a “Conformance” section to the document. A draft introduction and conformance table are included, but the actual conformance levels need work. The bulk of this was included from Ira's and Tom’s draft.

Moved Attribute section in front of the Service, Printer, and Job sections interfaces to improve flow of document.

Added papi_encryption_t to common structures

Added constraints chapter. The bulk of this chapter was copied directly from v0.3 of the papi capabilities document.

Version 0.9 (November 18, 2002).

Changed media-margins order to "top, right, bottom, left" to match other standards.

Changed media-margins units to "100ths of millimeters" to match other standards. Also, reworded last paragraph of description of this attribute.

Version 0.8 (November 15, 2002).

Added value field, explanation, and corrected example for papi_filter_t.

Added media-margins attribute to "Extension Attributes" section.

Renamed function names with "Username" to "UserName", and renamed function names with "Servicename" to "ServiceName", and Miscellaneous wording and typo corrections.

Version 0.7 (October 18, 2002).

Added attr_delim argument to papiAttributeListToString and made new-line ("\n") an allowed attribute delimiter on input to papiAttributeListFromString.

Added "Semantics Reference" subsections to functions.

Added to References: [5101.1], [RFC3196], and URIs for obtaining IPP documents.

Added PAPI_JOB_TICKET_NOT_SUPPORTED status code.

Added "Globalization" section in the "Print System Model" chapter.

Changed definition and usage of returned value from papiAttributeListGetValue. Also clarified what happens to output values when a papiAttributeListGet* call has an error.

Clarified descriptions of papiPrinterGetAttributeList and papiJobGetAttributeList.

Changed buffer length arguments from int to size_t.

Clarified that papiServiceDestroy must always be called after a call to papiServiceCreate.

Removed attributes-charset, attributes-natural-language, and job-printer-up-time from the "Required Job Attributes" (they may be hidden inside the PAPI implementation).

Clarified result of passing both attributes and a job ticket on all the job submission functions.

Miscellaneous wording and typo corrections.

Version 0.6 (September 20, 2002)

Made explanation of requested_attrs in papiPrintersList the same as it is for papiPrinterQuery.

Moved units argument on papiAttributeListAddResolution to the end of the argument list to match the corresponding get function.

Added papiAttributeListAddCollection and papiAttributeListGetCollection.

Removed unneeded extra level of indirection from attrs argument to papiAttributeListGet* functions. Also made the attrs argument const.

Added note to "Conventions" section that strings are assumed to be UTF-8 encoded.

Added papiAttributeListFromString and papiAttributeListToString functions, along with a new appendix defining the string format syntax.

Added papiJobSubmitByReference, papiJobStreamOpen, papiJobStreamWrite, and papiJobStreamClose functions.

Added short "Document" section in the "Print System Model" chapter.

Added explanation of how multiple files specified in the papiJobSubmit file_names argument are handled by the print system.

Changed papi_job_ticket_t "uri" field to "file_name" and added explanation text.

Added explanation of implementation option for merging papiJobSubmit attributes with job_ticket argument.

Added "References" appendix.

Added "IPP Attribute Type Mapping" appendix.

Added "PWG" job ticket format to papi_jt_format_t.

Miscellaneous wording and typo corrections.

Version 0.5 (August 30, 2002).

Added job_attrs argument to papiPrinterQuery to support more accurate query of printer capabilities.

Added management functions papiAttributeDelete, papiJobModify, and papiPrinterModify.

Added functions papiAttributeListGetValue, papiAttributeListGetString, papiAttributeListGetInteger, etc.

Renamed papiAttributeAdd* functions to papiAttributeListAdd* to be consistent with the naming convention (first word after "papi" is the object being operated upon).

Changed last argument of papiAttributeListAdd to papi_attribute_value_t*.

Made description of authentication more implementation-independent.

Added reference to IPP attributes summary document.

Added result argument to papiPrinterPurgeJobs.

Added "collection attribute" support (PAPI_COLLECTION type).

Changed boolean values to consistently use char. Added PAPI_FALSE and PAPI_TRUE enum values.

Version 0.4 (July 19, 2002).

Made papi_job_t and papi_printer_t opaque handles and added "get" functions to access the associated information (papiPrinterGetAttributeList, papiJobGetAttributeList, papiJobGetId, papiJobGetPrinterName, papiJobGetJobTicket).

Removed variable length argument lists from attribute add functions.

Changed order and name of flag value passed to attribute add functions.

Eliminated indirection in date/time value passed to papiAttributeAddDatetime.

Added message argument to papiPrinterPause.

Version 0.3 (June 24, 2002).

Converted to DocBook format from Microsoft Word

Major rewrite, including:

Changed how printer names are described in "Model/Printer"

Changed fixed length strings to pointers in numerous structures/sections

Redefined attribute/value structures and associated API descriptions

Changed list/query functions to return "objects"

Rewrote "Attributes API" chapter

Changed many function definitions to pass NULL-terminated arrays of pointers instead of a separate count argument

Changed papiJobSubmit to take an attribute list structure as input instead of a formatted string

Version 0.2 (April 17, 2002).

Updated references to IPP RFC from 2566 (IPP 1.0) to 2911 (IPP 1.1)

Filled in "Encryption" section and added information about encryption in "Object Identification" section

Added "short_name" field in "Object Identification" section

Added "Job Ticket (papi_job_ticket_t)" section

Added papiPrinterPause

Added papiPrinterResume

Added papiPurgeJobs

Added optional job_ticket argument to papiJobSubmit

Added optional passing of filenames by URI to papiJobSubmit

Added papiHoldJob

Added papiReleaseJob

Added papiRestartJob

Version 0.1 (April 3, 2002).

Original draft version

Chapter 15: Change History

132

Open Standard Print API (PAPI)

Norm Jacobs

2004-01-14T13:13:18

Norm Jacobs