3.2 Printer Operations
All Printer operations are directed at Printer objects. A client MUST always supply the "printer-uri" operation attribute in order to identify the correct target of the operation.3.2.1 Print-Job Operation
This REQUIRED operation allows a client to submit a print job with only one document and supply the document data (rather than just a reference to the data). See Section 15 for the suggested steps for processing create operations and their Operation and Job Template attributes.3.2.1.1 Print-Job Request
The following groups of attributes are supplied as part of the Print-Job Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. The Printer object MUST copy these values to the corresponding Job Description attributes described in sections 4.3.19 and 4.3.20. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "job-name" (name(MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It contains the client supplied Job name. If this attribute is supplied by the client, its value is used for the "job-name" attribute of the newly created Job object. The client MAY automatically include any information that will help the end-user distinguish amongst his/her jobs, such as the name of the application program along with information from the document, such as the document name, document subject, or source file name. If this attribute is not supplied by the client, the Printer generates a name to use in the "job-name" attribute of the newly created Job object (see Section 4.3.5).
"ipp-attribute-fidelity" (boolean): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. The value 'true' indicates that total fidelity to client supplied Job Template attributes and values is required, else the Printer object MUST reject the Print-Job request. The value 'false' indicates that a reasonable attempt to print the Job object is acceptable and the Printer object MUST accept the Print-Job request. If not supplied, the Printer object assumes the value is 'false'. All Printer objects MUST support both types of job processing. See section 15 for a full description of "ipp-attribute-fidelity" and its relationship to other attributes, especially the Printer object's "pdl-override-supported" attribute. "document-name" (name(MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It contains the client supplied document name. The document name MAY be different than the Job name. Typically, the client software automatically supplies the document name on behalf of the end user by using a file name or an application generated name. If this attribute is supplied, its value can be used in a manner defined by each implementation. Examples include: printed along with the Job (job start sheet, page adornments, etc.), used by accounting or resource tracking management tools, or even stored along with the document as a document level attribute. IPP/1.1 does not support the concept of document level attributes. "compression" (type3 keyword): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute and the "compression- supported" attribute (see section 4.4.32). The client supplied "compression" operation attribute identifies the compression algorithm used on the document data. The following cases exist: a) If the client omits this attribute, the Printer object MUST assume that the data is not compressed (i.e. the Printer follows the rules below as if the client supplied the "compression" attribute with a value of 'none'). b) If the client supplies this attribute, but the value is not supported by the Printer object, i.e., the value is not one of the values of the Printer object's "compression- supported" attribute, the Printer object MUST reject the request, and return the 'client-error-compression-not- supported' status code. See section 3.1.7 for returning unsupported attributes and values.
c) If the client supplies the attribute and the Printer object supports the attribute value, the Printer object uses the corresponding decompression algorithm on the document data. d) If the decompression algorithm fails before the Printer returns an operation response, the Printer object MUST reject the request and return the 'client-error- compression-error' status code. e) If the decompression algorithm fails after the Printer returns an operation response, the Printer object MUST abort the job and add the 'compression-error' value to the job's "job-state-reasons" attribute. f) If the decompression algorithm succeeds, the document data MUST then have the format specified by the job's "document- format" attribute, if supplied (see "document-format" operation attribute definition below). "document-format" (mimeMediaType): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. The value of this attribute identifies the format of the supplied document data. The following cases exist: a) If the client does not supply this attribute, the Printer object assumes that the document data is in the format defined by the Printer object's "document-format-default" attribute. (i.e. the Printer follows the rules below as if the client supplied the "document-format" attribute with a value equal to the printer's default value). b) If the client supplies this attribute, but the value is not supported by the Printer object, i.e., the value is not one of the values of the Printer object's "document-format- supported" attribute, the Printer object MUST reject the request and return the 'client-error-document-format-not- supported' status code. c) If the client supplies this attribute and its value is 'application/octet-stream' (i.e. to be auto-sensed, see Section 4.1.9.1), and the format is not one of the document-formats that the Printer can auto-sense, and this check occurs before the Printer returns an operation response, then the Printer MUST reject the request and return the 'client-error-document-format-not-supported' status code. d) If the client supplies this attribute, and the value is supported by the Printer object, the Printer is capable of interpreting the document data.
e) If interpreting of the document data fails before the Printer returns an operation response, the Printer object MUST reject the request and return the 'client-error- document-format-error' status code. f) If interpreting of the document data fails after the Printer returns an operation response, the Printer object MUST abort the job and add the 'document-format-error' value to the job's "job-state-reasons" attribute. "document-natural-language" (naturalLanguage): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute. This attribute specifies the natural language of the document for those document-formats that require a specification of the natural language in order to image the document unambiguously. There are no particular values required for the Printer object to support. "job-k-octets" (integer(0:MAX)): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute and the "job-k- octets-supported" attribute (see section 4.4.33). The client supplied "job-k-octets" operation attribute identifies the total size of the document(s) in K octets being submitted (see section 4.3.17.1 for the complete semantics). If the client supplies the attribute and the Printer object supports the attribute, the value of the attribute is used to populate the Job object's "job-k-octets" Job Description attribute. For this attribute and the following two attributes ("job- impressions", and "job-media-sheets"), if the client supplies the attribute, but the Printer object does not support the attribute, the Printer object ignores the client-supplied value. If the client supplies the attribute and the Printer supports the attribute, and the value is within the range of the corresponding Printer object's "xxx-supported" attribute, the Printer object MUST use the value to populate the Job object's "xxx" attribute. If the client supplies the attribute and the Printer supports the attribute, but the value is outside the range of the corresponding Printer object's "xxx- supported" attribute, the Printer object MUST copy the attribute and its value to the Unsupported Attributes response group, reject the request, and return the 'client-error- attributes-or-values-not-supported' status code. If the client does not supply the attribute, the Printer object MAY choose to populate the corresponding Job object attribute depending on whether the Printer object supports the attribute and is able to calculate or discern the correct value.
"job-impressions" (integer(0:MAX)): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute and the "job- impressions-supported" attribute (see section 4.4.34). The client supplied "job-impressions" operation attribute identifies the total size in number of impressions of the document(s) being submitted (see section 4.3.17.2 for the complete semantics). See last paragraph under "job-k-octets". "job-media-sheets" (integer(0:MAX)): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute and the "job-media- sheets-supported" attribute (see section 4.4.35). The client supplied "job-media-sheets" operation attribute identifies the total number of media sheets to be produced for this job (see section 4.3.17.3 for the complete semantics). See last paragraph under "job-k-octets". Group 2: Job Template Attributes The client OPTIONALLY supplies a set of Job Template attributes as defined in section 4.2. If the client is not supplying any Job Template attributes in the request, the client SHOULD omit Group 2 rather than sending an empty group. However, a Printer object MUST be able to accept an empty group. Group 3: Document Content The client MUST supply the document data to be processed. In addition to the MANDATORY parameters required for every operation request, the simplest Print-Job Request consists of just the "attributes-charset" and "attributes-natural-language" operation attributes; the "printer-uri" target operation attribute; the Document Content and nothing else. In this simple case, the Printer object: - creates a new Job object (the Job object contains a single document), - stores a generated Job name in the "job-name" attribute in the natural language and charset requested (see Section 3.1.4.1) (if those are supported, otherwise using the Printer object's default natural language and charset), and
- at job processing time, uses its corresponding default value attributes for the supported Job Template attributes that were not supplied by the client as IPP attribute or embedded instructions in the document data.3.2.1.2 Print-Job Response
The Printer object MUST return to the client the following sets of attributes as part of the Print-Job Response: Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in sections 13 and 3.1.6. If the client supplies unsupported or conflicting Job Template attributes or values, the Printer object MUST reject or accept the Print-Job request depending on the whether the client supplied a 'true' or 'false' value for the "ipp-attribute- fidelity" operation attribute. See the Implementer's Guide [IPP-IIG] for a complete description of the suggested steps for processing a create request. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. The value of the "ipp-attribute-fidelity" supplied by the client does not affect what attributes the Printer object returns in this group. The value of "ipp-attribute-fidelity" only affects whether the Print-Job operation is accepted or rejected. If the job is accepted, the client may query the job using the Get-Job- Attributes operation requesting the unsupported attributes that were returned in the create response to see which attributes were ignored (not stored on the Job object) and which attributes were stored with other (substituted) values.
Group 3: Job Object Attributes "job-uri" (uri): The Printer object MUST return the Job object's URI by returning the contents of the REQUIRED "job-uri" Job object attribute. The client uses the Job object's URI when directing operations at the Job object. The Printer object always uses its configured security policy when creating the new URI. However, if the Printer object supports more than one URI, the Printer object also uses information about which URI was used in the Print-Job Request to generated the new URI so that the new URI references the correct access channel. In other words, if the Print-Job Request comes in over a secure channel, the Printer object MUST generate a Job URI that uses the secure channel as well. "job-id" (integer(1:MAX)): The Printer object MUST return the Job object's Job ID by returning the REQUIRED "job-id" Job object attribute. The client uses this "job-id" attribute in conjunction with the "printer-uri" attribute used in the Print-Job Request when directing Job operations at the Printer object. "job-state" (type1 enum): The Printer object MUST return the Job object's REQUIRED "job- state" attribute. The value of this attribute (along with the value of the next attribute: "job-state-reasons") is taken from a "snapshot" of the new Job object at some meaningful point in time (implementation defined) between when the Printer object receives the Print-Job Request and when the Printer object returns the response. "job-state-reasons" (1setOf type2 keyword): The Printer object MUST return the Job object's REQUIRED "job- state-reasons" attribute. "job-state-message" (text(MAX)): The Printer object OPTIONALLY returns the Job object's OPTIONAL "job-state-message" attribute. If the Printer object supports this attribute then it MUST be returned in the response. If this attribute is not returned in the response, the client can assume that the "job-state-message" attribute is not supported and will not be returned in a subsequent Job object query. "number-of-intervening-jobs" (integer(0:MAX)): The Printer object OPTIONALLY returns the Job object's OPTIONAL "number-of-intervening-jobs" attribute. If the Printer object supports this attribute then it MUST be returned in the
response. If this attribute is not returned in the response, the client can assume that the "number-of-intervening-jobs" attribute is not supported and will not be returned in a subsequent Job object query. Note: Since any printer state information which affects a job's state is reflected in the "job-state" and "job-state-reasons" attributes, it is sufficient to return only these attributes and no specific printer status attributes. Note: In addition to the MANDATORY parameters required for every operation response, the simplest response consists of the just the "attributes-charset" and "attributes-natural-language" operation attributes and the "job-uri", "job-id", and "job-state" Job Object Attributes. In this simplest case, the status code is 'successful- ok' and there is no "status-message" or "detailed-status-message" operation attribute.3.2.2 Print-URI Operation
This OPTIONAL operation is identical to the Print-Job operation (section 3.2.1) except that a client supplies a URI reference to the document data using the "document-uri" (uri) operation attribute (in Group 1) rather than including the document data itself. Before returning the response, the Printer MUST validate that the Printer supports the retrieval method (e.g., http, ftp, etc.) implied by the URI, and MUST check for valid URI syntax. If the client-supplied URI scheme is not supported, i.e. the value is not in the Printer object's "referenced-uri-scheme-supported" attribute, the Printer object MUST reject the request and return the 'client-error-uri- scheme-not-supported' status code. The IPP Printer MAY validate the accessibility of the document as part of the operation or subsequently. If the Printer determines an accessibility problem before returning an operation response, it rejects the request and returns the 'client-error-document-access- error' status code. The Printer MAY also return a specific document access error code using the "document-access-error" operation attribute (see section 3.1.6.4). If the Printer determines this document accessibility problem after accepting the request and returning an operation response with one of the successful status codes, the Printer adds the 'document-access- error' value to the job's "job-state-reasons" attribute and MAY populate the job's "job-document-access-errors" Job Description attribute (see section 4.3.11). See The Implementer's Guide [IPP- IIG] for suggested additional checks.
If the Printer object supports this operation, it MUST support the "reference-uri-schemes-supported" Printer attribute (see section 4.4.27). It is up to the IPP object to interpret the URI and subsequently "pull" the document from the source referenced by the URI string.3.2.3 Validate-Job Operation
This REQUIRED operation is similar to the Print-Job operation (section 3.2.1) except that a client supplies no document data and the Printer allocates no resources (i.e., it does not create a new Job object). This operation is used only to verify capabilities of a printer object against whatever attributes are supplied by the client in the Validate-Job request. By using the Validate-Job operation a client can validate that an identical Print-Job operation (with the document data) would be accepted. The Validate-Job operation also performs the same security negotiation as the Print-Job operation (see section 8), so that a client can check that the client and Printer object security requirements can be met before performing a Print-Job operation. The Validate-Job operation does not accept a "document-uri" attribute in order to allow a client to check that the same Print-URI operation will be accepted, since the client doesn't send the data with the Print-URI operation. The client SHOULD just issue the Print-URI request. The Printer object returns the same status codes, Operation Attributes (Group 1) and Unsupported Attributes (Group 2) as the Print-Job operation. However, no Job Object Attributes (Group 3) are returned, since no Job object is created.3.2.4 Create-Job Operation
This OPTIONAL operation is similar to the Print-Job operation (section 3.2.1) except that in the Create-Job request, a client does not supply document data or any reference to document data. Also, the client does not supply any of the "document-name", "document- format", "compression", or "document-natural-language" operation attributes. This operation is followed by one or more Send-Document or Send-URI operations. In each of those operation requests, the client OPTIONALLY supplies the "document-name", "document-format", and "document-natural-language" attributes for each document in the multi-document Job object.
If a Printer object supports the Create-Job operation, it MUST also support the Send-Document operation and also MAY support the Send-URI operation. If the Printer object supports this operation, it MUST support the "multiple-operation-time-out" Printer attribute (see section 4.4.31). If the Printer object supports this operation, then it MUST support the "multiple-document-jobs-supported" Printer Description attribute (see section 4.4.16) and indicate whether or not it supports multiple-document jobs. If the Printer object supports this operation and supports multiple documents in a job, then it MUST support the "multiple-document- handling" Job Template job attribute with at least one value (see section 4.2.4) and the associated "multiple-document-handling- default" and "multiple-document-handling-supported" Job Template Printer attributes (see section 4.2). After the Create-Job operation has completed, the value of the "job- state" attribute is similar to the "job-state" after a Print-Job, even though no document-data has arrived. A Printer MAY set the 'job-data-insufficient' value of the job's "job-state-reason" attribute to indicate that processing cannot begin until sufficient data has arrived and set the "job-state" to either 'pending' or 'pending-held'. A non-spooling printer that doesn't implement the 'pending' job state may even set the "job-state" to 'processing', even though there is not yet any data to process. See sections 4.3.7 and 4.3.8.3.2.5 Get-Printer-Attributes Operation
This REQUIRED operation allows a client to request the values of the attributes of a Printer object. In the request, the client supplies the set of Printer attribute names and/or attribute group names in which the requester is interested. In the response, the Printer object returns a corresponding attribute set with the appropriate attribute values filled in. For Printer objects, the possible names of attribute groups are: - 'job-template': the subset of the Job Template attributes that apply to a Printer object (the last two columns of the table in Section 4.2) that the implementation supports for Printer objects. - 'printer-description': the subset of the attributes specified in Section 4.4 that the implementation supports for Printer objects.
- 'all': the special group 'all' that includes all attributes that the implementation supports for Printer objects. Since a client MAY request specific attributes or named groups, there is a potential that there is some overlap. For example, if a client requests, 'printer-name' and 'all', the client is actually requesting the "printer-name" attribute twice: once by naming it explicitly, and once by inclusion in the 'all' group. In such cases, the Printer object NEED NOT return each attribute only once in the response even if it is requested multiple times. The client SHOULD NOT request the same attribute in multiple ways. It is NOT REQUIRED that a Printer object support all attributes belonging to a group (since some attributes are OPTIONAL). However, it is REQUIRED that each Printer object support all group names.3.2.5.1 Get-Printer-Attributes Request
The following sets of attributes are part of the Get-Printer- Attributes Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "requested-attributes" (1setOf keyword): The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. The Printer object MUST support this attribute. If the client omits this attribute, the Printer MUST respond as if this attribute had been supplied with a value of 'all'. "document-format" (mimeMediaType): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. This attribute is useful for a Printer object to determine the set of supported attribute values that relate to the requested document format. The Printer object MUST return the attributes and values that
it uses to validate a job on a create or Validate-Job operation in which this document format is supplied. The Printer object SHOULD return only (1) those attributes that are supported for the specified format and (2) the attribute values that are supported for the specified document format. By specifying the document format, the client can get the Printer object to eliminate the attributes and values that are not supported for a specific document format. For example, a Printer object might have multiple interpreters to support both 'application/postscript' (for PostScript) and 'text/plain' (for text) documents. However, for only one of those interpreters might the Printer object be able to support "number-up" with values of '1', '2', and '4'. For the other interpreter it might be able to only support "number-up" with a value of '1'. Thus a client can use the Get-Printer-Attributes operation to obtain the attributes and values that will be used to accept/reject a create job operation. If the Printer object does not distinguish between different sets of supported values for each different document format when validating jobs in the create and Validate-Job operations, it MUST NOT distinguish between different document formats in the Get-Printer-Attributes operation. If the Printer object does distinguish between different sets of supported values for each different document format specified by the client, this specialization applies only to the following Printer object attributes: - Printer attributes that are Job Template attributes ("xxx- default" "xxx-supported", and "xxx-ready" in the Table in Section 4.2), - "pdl-override-supported", - "compression-supported", - "job-k-octets-supported", - "job-impressions-supported", - "job-media-sheets-supported", - "printer-driver-installer", - "color-supported", and - "reference-uri-schemes-supported" The values of all other Printer object attributes (including "document-format-supported") remain invariant with respect to the client supplied document format (except for new Printer description attribute as registered according to section 6.2). If the client omits this "document-format" operation attribute, the Printer object MUST respond as if the attribute had been supplied with the value of the Printer object's "document-format-
default" attribute. It is RECOMMENDED that the client always supply a value for "document-format", since the Printer object's "document-format-default" may be 'application/octet-stream', in which case the returned attributes and values are for the union of the document formats that the Printer can automatically sense. For more details, see the description of the 'mimeMediaType' attribute syntax in section 4.1.9. If the client supplies a value for the "document-format" Operation attribute that is not supported by the Printer, i.e., is not among the values of the Printer object's "document-format-supported" attribute, the Printer object MUST reject the operation and return the 'client-error-document-format-not-supported' status code.3.2.5.2 Get-Printer-Attributes Response
The Printer object returns the following sets of attributes as part of the Get-Printer-Attributes Response: Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. The response NEED NOT contain the "requested-attributes" operation attribute with any supplied values (attribute keywords) that were requested by the client but are not supported by the IPP object. If the Printer object does return unsupported attributes referenced in the "requested-attributes" operation attribute and that attribute included group names, such as 'all', the unsupported attributes MUST NOT include attributes described in the standard but not supported by the implementation.
Group 3: Printer Object Attributes This is the set of requested attributes and their current values. The Printer object ignores (does not respond with) any requested attribute which is not supported. The Printer object MAY respond with a subset of the supported attributes and values, depending on the security policy in force. However, the Printer object MUST respond with the 'unknown' value for any supported attribute (including all REQUIRED attributes) for which the Printer object does not know the value. Also the Printer object MUST respond with the 'no-value' for any supported attribute (including all REQUIRED attributes) for which the system administrator has not configured a value. See the description of the "out-of-band" values in the beginning of Section 4.1.3.2.6 Get-Jobs Operation
This REQUIRED operation allows a client to retrieve the list of Job objects belonging to the target Printer object. The client may also supply a list of Job attribute names and/or attribute group names. A group of Job object attributes will be returned for each Job object that is returned. This operation is similar to the Get-Job-Attributes operation, except that this Get-Jobs operation returns attributes from possibly more than one object.3.2.6.1 Get-Jobs Request
The client submits the Get-Jobs request to a Printer object. The following groups of attributes are part of the Get-Jobs Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3.
"limit" (integer(1:MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It is an integer value that determines the maximum number of jobs that a client will receive from the Printer even if "which-jobs" or "my-jobs" constrain which jobs are returned. The limit is a "stateless limit" in that if the value supplied by the client is 'N', then only the first 'N' jobs are returned in the Get-Jobs Response. There is no mechanism to allow for the next 'M' jobs after the first 'N' jobs. If the client does not supply this attribute, the Printer object responds with all applicable jobs. "requested-attributes" (1setOf type2 keyword): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It is a set of Job attribute names and/or attribute groups names in whose values the requester is interested. This set of attributes is returned for each Job object that is returned. The allowed attribute group names are the same as those defined in the Get-Job-Attributes operation in section 3.3.4. If the client does not supply this attribute, the Printer MUST respond as if the client had supplied this attribute with two values: 'job- uri' and 'job-id'. "which-jobs" (type2 keyword): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It indicates which Job objects MUST be returned by the Printer object. The values for this attribute are: 'completed': This includes any Job object whose state is 'completed', 'canceled', or 'aborted'. 'not-completed': This includes any Job object whose state is 'pending', 'processing', 'processing-stopped', or 'pending- held'. A Printer object MUST support both values. However, if the implementation does not keep jobs in the 'completed', 'canceled', and 'aborted' states, then it returns no jobs when the 'completed' value is supplied. If a client supplies some other value, the Printer object MUST copy the attribute and the unsupported value to the Unsupported Attributes response group, reject the request, and return the 'client-error-attributes-or-values-not-supported' status code.
If the client does not supply this attribute, the Printer object MUST respond as if the client had supplied the attribute with a value of 'not-completed'. "my-jobs" (boolean): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It indicates whether jobs from all users or just the jobs submitted by the requesting user of this request MUST be considered as candidate jobs to be returned by the Printer object. If the client does not supply this attribute, the Printer object MUST respond as if the client had supplied the attribute with a value of 'false', i.e., jobs from all users. The means for authenticating the requesting user and matching the jobs is described in section 8.3.2.6.2 Get-Jobs Response
The Printer object returns all of the Job objects up to the number specified by the "limit" attribute that match the criteria as defined by the attribute values supplied by the client in the request. It is possible that no Job objects are returned since there may literally be no Job objects at the Printer, or there may be no Job objects that match the criteria supplied by the client. If the client requests any Job attributes at all, there is a set of Job Object Attributes returned for each Job object. It is not an error for the Printer to return 0 jobs. If the response returns 0 jobs because there are no jobs matching the criteria, and the request would have returned 1 or more jobs with a status code of 'successful-ok' if there had been jobs matching the criteria, then the status code for 0 jobs MUST be 'successful-ok'. Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2.
Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. The response NEED NOT contain the "requested-attributes" operation attribute with any supplied values (attribute keywords) that were requested by the client but are not supported by the IPP object. If the Printer object does return unsupported attributes referenced in the "requested-attributes" operation attribute and that attribute included group names, such as 'all', the unsupported attributes MUST NOT include attributes described in the standard but not supported by the implementation. Groups 3 to N: Job Object Attributes The Printer object responds with one set of Job Object Attributes for each returned Job object. The Printer object ignores (does not respond with) any requested attribute or value which is not supported or which is restricted by the security policy in force, including whether the requesting user is the user that submitted the job (job originating user) or not (see section 8). However, the Printer object MUST respond with the 'unknown' value for any supported attribute (including all REQUIRED attributes) for which the Printer object does not know the value, unless it would violate the security policy. See the description of the "out-of- band" values in the beginning of Section 4.1. Jobs are returned in the following order: - If the client requests all 'completed' Jobs (Jobs in the 'completed', 'aborted', or 'canceled' states), then the Jobs are returned newest to oldest (with respect to actual completion time) - If the client requests all 'not-completed' Jobs (Jobs in the 'pending', 'processing', 'pending-held', and 'processing- stopped' states), then Jobs are returned in relative chronological order of expected time to complete (based on whatever scheduling algorithm is configured for the Printer object).3.2.7 Pause-Printer Operation
This OPTIONAL operation allows a client to stop the Printer object from scheduling jobs on all its devices. Depending on implementation, the Pause-Printer operation MAY also stop the Printer from processing the current job or jobs. Any job that is currently being printed is either stopped as soon as the implementation permits
or is completed, depending on implementation. The Printer object MUST still accept create operations to create new jobs, but MUST prevent any jobs from entering the 'processing' state. If the Pause-Printer operation is supported, then the Resume-Printer operation MUST be supported, and vice-versa. The IPP Printer stops the current job(s) on its device(s) that were in the 'processing' or 'processing-stopped' states as soon as the implementation permits. If the implementation will take appreciable time to stop, the IPP Printer adds the 'moving-to-paused' value to the Printer object's "printer-state-reasons" attribute (see section 4.4.12). When the device(s) have all stopped, the IPP Printer transitions the Printer object to the 'stopped' state, removes the 'moving-to-paused' value, if present, and adds the 'paused' value to the Printer object's "printer-state-reasons" attribute. When the current job(s) complete that were in the 'processing' state, the IPP Printer transitions them to the 'completed' state. When the current job(s) stop in mid processing that were in the 'processing' state, the IPP Printer transitions them to the 'processing-stopped' state and adds the 'printer-stopped' value to the job's "job-state- reasons" attribute. For any jobs that are 'pending' or 'pending-held', the 'printer- stopped' value of the jobs' "job-state-reasons" attribute also applies. However, the IPP Printer NEED NOT update those jobs' "job- state-reasons" attributes and only need return the 'printer-stopped' value when those jobs are queried (so-called "lazy evaluation"). Whether the Pause-Printer operation affects jobs that were submitted to the device from other sources than the IPP Printer object in the same way that the Pause-Printer operation affects jobs that were submitted to the IPP Printer object using IPP, depends on implementation, i.e., on whether the IPP protocol is being used as a universal management protocol or just to manage IPP jobs, respectively. The IPP Printer MUST accept the request in any state and transition the Printer to the indicated new "printer-state" before returning as follows:
Current New "printer IPP Printer's response status "printer- "printer- -state- code and action: state" state" reasons" 'idle' 'stopped' 'paused' 'successful-ok' 'processing' 'processing' 'moving- OPTION 1: 'successful-ok'; to- Later, when all output has paused' stopped, the "printer-state" becomes 'stopped', and the 'paused' value replaces the 'moving-to-paused' value in the "printer-state-reasons" attribute 'processing' 'stopped' 'paused' OPTION 2: 'successful-ok'; all device output stopped immediately 'stopped' 'stopped' 'paused' 'successful-ok' Access Rights: The authenticated user (see section 8.3) performing this operation must be an operator or administrator of the Printer object (see Sections 1 and 8.5). Otherwise, the IPP Printer MUST reject the operation and return: 'client-error-forbidden', 'client- error-not-authenticated', or 'client-error-not-authorized' as appropriate.3.2.7.1 Pause-Printer Request
The following groups of attributes are part of the Pause-Printer Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3.
3.2.7.2 Pause-Printer Response
The following groups of attributes are part of the Pause-Printer Response: Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes.3.2.8 Resume-Printer Operation
This operation allows a client to resume the Printer object scheduling jobs on all its devices. The Printer object MUST remove the 'paused' and 'moving-to-paused' values from the Printer object's "printer-state-reasons" attribute, if present. If there are no other reasons to keep a device paused (such as media-jam), the IPP Printer is free to transition itself to the 'processing' or 'idle' states, depending on whether there are jobs to be processed or not, respectively, and the device(s) resume processing jobs. If the Pause-Printer operation is supported, then the Resume-Printer operation MUST be supported, and vice-versa. The IPP Printer removes the 'printer-stopped' value from any job's "job-state-reasons" attributes contained in that Printer. The IPP Printer MUST accept the request in any state, transition the Printer object to the indicated new state as follows:
Current New "printer- IPP Printer's response status code and "printer- state" action: state" 'idle' 'idle' 'successful-ok' 'processing' 'processing' 'successful-ok' 'stopped' 'processing' 'successful-ok'; when there are jobs to be processed 'stopped' 'idle' 'successful-ok'; when there are no jobs to be processed. Access Rights: The authenticated user (see section 8.3) performing this operation must be an operator or administrator of the Printer object (see Sections 1 and 8.5). Otherwise, the IPP Printer MUST reject the operation and return: 'client-error-forbidden', 'client- error-not-authenticated', or 'client-error-not-authorized' as appropriate. The Resume-Printer Request and Resume-Printer Response have the same attribute groups and attributes as the Pause-Printer operation (see sections 3.2.7.1 and 3.2.7.2).3.2.9 Purge-Jobs Operation
This OPTIONAL operation allows a client to remove all jobs from an IPP Printer object, regardless of their job states, including jobs in the Printer object's Job History (see Section 4.3.7.2). After a Purge-Jobs operation has been performed, a Printer object MUST return no jobs in subsequent Get-Job-Attributes and Get-Jobs responses (until new jobs are submitted). Whether the Purge-Jobs (and Get-Jobs) operation affects jobs that were submitted to the device from other sources than the IPP Printer object in the same way that the Purge-Jobs operation affects jobs that were submitted to the IPP Printer object using IPP, depends on implementation, i.e., on whether the IPP protocol is being used as a universal management protocol or just to manage IPP jobs, respectively. Note: if an operator wants to cancel all jobs without clearing out the Job History, the operator uses the Cancel-Job operation on each job instead of using the Purge-Jobs operation. The Printer object MUST accept this operation in any state and transition the Printer object to the 'idle' state.
Access Rights: The authenticated user (see section 8.3) performing this operation must be an operator or administrator of the Printer object (see Sections 1 and 8.5). Otherwise, the IPP object MUST reject the operation and return: client-error-forbidden, client- error-not-authenticated, and client-error-not-authorized as appropriate. The Purge-Jobs Request and Purge-Jobs Response have the same attribute groups and attributes as the Pause-Printer operation (see sections 3.2.7.1 and 3.2.7.2).3.3 Job Operations
All Job operations are directed at Job objects. A client MUST always supply some means of identifying the Job object in order to identify the correct target of the operation. That job identification MAY either be a single Job URI or a combination of a Printer URI with a Job ID. The IPP object implementation MUST support both forms of identification for every job.3.3.1 Send-Document Operation
This OPTIONAL operation allows a client to create a multi-document Job object that is initially "empty" (contains no documents). In the Create-Job response, the Printer object returns the Job object's URI (the "job-uri" attribute) and the Job object's 32-bit identifier (the "job-id" attribute). For each new document that the client desires to add, the client uses a Send-Document operation. Each Send- Document Request contains the entire stream of document data for one document. If the Printer supports this operation but does not support multiple documents per job, the Printer MUST reject subsequent Send-Document operations supplied with data and return the 'server-error-multiple- document-jobs-not-supported'. However, the Printer MUST accept the first document with a 'true' or 'false' value for the "last-document" operation attribute (see below), so that clients MAY always submit one document jobs with a 'false' value for "last-document" in the first Send-Document and a 'true' for "last-document" in the second Send-Document (with no data). Since the Create-Job and the send operations (Send-Document or Send- URI operations) that follow could occur over an arbitrarily long period of time for a particular job, a client MUST send another send operation within an IPP Printer defined minimum time interval after the receipt of the previous request for the job. If a Printer object supports the Create-Job and Send-Document operations, the Printer object MUST support the "multiple-operation-time-out" attribute (see
section 4.4.31). This attribute indicates the minimum number of seconds the Printer object will wait for the next send operation before taking some recovery action. An IPP object MUST recover from an errant client that does not supply a send operation, sometime after the minimum time interval specified by the Printer object's "multiple-operation-time-out" attribute. Such recovery MAY include any of the following or other recovery actions: 1. Assume that the Job is an invalid job, start the process of changing the job state to 'aborted', add the 'aborted-by- system' value to the job's "job-state-reasons" attribute (see section 4.3.8), and clean up all resources associated with the Job. In this case, if another send operation is finally received, the Printer responds with an "client-error-not- possible" or "client-error-not-found" depending on whether or not the Job object is still around when the send operation finally arrives. 2. Assume that the last send operation received was in fact the last document (as if the "last-document" flag had been set to 'true'), close the Job object, and proceed to process it (i.e., move the Job's state to 'pending'). 3. Assume that the last send operation received was in fact the last document, close the Job, but move it to the 'pending-held' and add the 'submission-interrupted' value to the job's "job- state-reasons" attribute (see section 4.3.8). This action allows the user or an operator to determine whether to continue processing the Job by moving it back to the 'pending' state using the Release-Job operation (see section 3.3.6) or to cancel the job using the Cancel-Job operation (see section 3.3.3). Each implementation is free to decide the "best" action to take depending on local policy, whether any documents have been added, whether the implementation spools jobs or not, and/or any other piece of information available to it. If the choice is to abort the Job object, it is possible that the Job object may already have been processed to the point that some media sheet pages have been printed. Access Rights: The authenticated user (see section 8.3) performing this operation must either be the job owner (as determined in the Create-Job operation) or an operator or administrator of the Printer object (see Sections 1 and 8.5). Otherwise, the IPP object MUST reject the operation and return: 'client-error-forbidden', 'client- error-not-authenticated', or 'client-error-not-authorized' as appropriate.
3.3.1.1 Send-Document Request
The following attribute sets are part of the Send-Document Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: Either (1) the "printer-uri" (uri) plus "job-id" (integer(1:MAX))or (2) the "job-uri" (uri) operation attribute(s) which define the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "document-name" (name(MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It contains the client supplied document name. The document name MAY be different than the Job name. It might be helpful, but NEED NOT be unique across multiple documents in the same Job. Typically, the client software automatically supplies the document name on behalf of the end user by using a file name or an application generated name. See the description of the "document-name" operation attribute in the Print-Job Request (section 3.2.1.1) for more information about this attribute. "compression" (type3 keyword): See the description of "compression" for the Print-Job operation in Section 3.2.1.1. "document-format" (mimeMediaType): See the description of "document-format" for the Print-Job operation in Section 3.2.1.1. "document-natural-language" (naturalLanguage): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute. This attribute specifies the natural language of the document for those document-formats that require a specification of the natural language in order to image the document unambiguously. There are no particular values required for the Printer object to support.
"last-document" (boolean): The client MUST supply this attribute. The Printer object MUST support this attribute. It is a boolean flag that is set to 'true' if this is the last document for the Job, 'false' otherwise. Group 2: Document Content The client MUST supply the document data if the "last-document" flag is set to 'false'. However, since a client might not know that the previous document sent with a Send-Document (or Send-URI) operation was the last document (i.e., the "last-document" attribute was set to 'false'), it is legal to send a Send-Document request with no document data where the "last-document" flag is set to 'true'. Such a request MUST NOT increment the value of the Job object's "number-of-documents" attribute, since no real document was added to the job. It is not an error for a client to submit a job with no actual document data, i.e., only a single Create-Job and Send-Document request with a "last-document" operation attribute set to 'true' with no document data.3.3.1.2 Send-Document Response
The following sets of attributes are part of the Send-Document Response: Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. Group 3: Job Object Attributes This is the same set of attributes as described in the Print-Job response (see section 3.2.1.2).