Internet Printing Protocol (IPP): Job and Printer Set Operations
updates
Extracted elements (32)
The 'admin-define' out-of-band value is intentionally restricted to 'xxx-supported' attributes defined to include the 'name' attribute syntax. It is not intended for attributes with other syntaxes (e.g., 'uri'), even if administrators define arbitrary values for them, to maintain a clear and limited scope.
The 'printer-xri-supported' collection attribute was created because 'printer-uri-supported', 'uri-authentication-supported', and 'uri-security-supported' are READ-ONLY in IPP/1.1 and cannot be set individually. The collection provides an atomic mechanism to update all three at once so they are never left in a partially inconsistent state.
The 'printer-xri-supported' (1setOf collection) attribute can be encoded as a single text string for use in directory schemas (e.g., SLPv2 or LDAPv3) that require single text string values, by using suitable delimiting characters to separate member attributes and collection values.
A client MUST NOT supply the 'not-settable' or 'admin-define' out-of-band values in any request. If a Printer receives either value in an operation request, it MUST either reject the entire request with 'client-error-bad-request' or ignore the attribute and return it with the 'unsupported' out-of-band value.
An IPP Printer MUST NOT provide any other way, using IPP, to set the three IPP/1.1 READ-ONLY Printer Description attributes 'printer-uri-supported', 'uri-authentication-supported', and 'uri-security-supported' other than through 'printer-xri-supported', since they MUST have consistent values at all times.
For Set-Printer-Attributes, an attribute validates only if: the Printer supports it, it is not READ-ONLY by definition, it is settable in the implementation, its values are supported per the corresponding 'xxx-supported' attribute rules, and its values do not conflict with other Printer attributes.
If Set-Printer-Attributes allows the administrator to define arbitrary 'name' values for an 'xxx-supported' attribute, Get-Printer-Supported-Values MUST return the 'admin-define' out-of-band value as one of the values of that attribute. If 'admin-define' is not present for an attribute, Set-Printer-Attributes MUST NOT accept values beyond those explicitly returned.
If the client supplies a job attribute with the 'delete-attribute' out-of-band value in Set-Job-Attributes, the Printer MUST remove the attribute and all its values from the Job object. Any subsequent Get-Job-Attributes or Get-Jobs MUST NOT return any attribute deleted this way.
If the Printer supports Set-Printer-Attributes AND any 'xxx-supported' attributes are settable, the Get-Printer-Supported-Values operation MUST also be supported. Get-Printer-Supported-Values requires administrator access rights.
Set-Printer-Attributes and Set-Job-Attributes MUST be atomic: if any supplied attribute fails validation, the Printer MUST reject the entire operation and MUST NOT partially set any of the supplied attributes.
Set-Printer-Attributes MUST NOT change the value of attributes not specified in the operation unless the attribute definition explicitly specifies such side-effects. If an 'xxx-default' attribute is changed, the new value MUST be in 'xxx-supported' or the request MUST include a new 'xxx-supported' value; otherwise the Printer MUST reject the operation.
The authenticated user performing Set-Printer-Attributes MUST be an operator or administrator of the Printer object. Most Printer attributes require administrator access rights (e.g., 'xxx-supported'), while some require only operator rights (e.g., 'media-ready', 'printer-message-from-operator').
The 'delete-attribute' out-of-band value MUST NOT be used in Set-Printer-Attributes, where the absence of an attribute indicates it is not supported. An IPP Printer MUST support 'delete-attribute' if it supports Set-Job-Attributes.
The Get-Printer-Supported-Values operation MUST return those, and only those, 'xxx-supported' Printer attributes that the Printer supports setting with Set-Printer-Attributes. It returns the values inherently supported by the implementation code, not the current configured values.
The 'printer-message-from-operator' operation attribute MUST NOT be supported as an operation attribute for the Set-Printer-Attributes operation; to set the Printer Description attribute of the same name via Set-Printer-Attributes, the client must supply it explicitly in Group 2.
The Printer MUST accept Set-Printer-Attributes when 'printer-state' is 'idle' or 'stopped', and SHOULD accept it when the value is 'processing'. The operation MUST be accepted regardless of 'printer-state-reasons' or 'printer-is-accepting-jobs' values unless explicitly stated otherwise.
The Set-Job-Attributes validation is performed as if the job were submitted originally with the new attribute values and 'ipp-attribute-fidelity' set to 'true'; if such a Job Creation would be accepted, the Set-Job-Attributes MUST be accepted, and if it would be rejected, the Set-Job-Attributes MUST be rejected and the Job MUST be unchanged.
New status code 'client-error-attributes-not-settable' (0x0413) is returned when Set-Printer-Attributes or Set-Job-Attributes fails because one or more attributes are READ-ONLY or not settable in the implementation. The Printer MUST return this code along with the 'not-settable' out-of-band value for each unsettable attribute in the Unsupported Attributes Group.
The 'document-format-varying-attributes' (1setOf type2 keyword) OPTIONAL READ-ONLY attribute lists attributes whose values vary by document format. If a listed attribute is changed in Set-Printer-Attributes with a 'document-format' operation attribute, the Printer MUST change the value only for that format; non-listed attributes are changed for all formats.
The 'job-message-from-operator' (text(127)) operation attribute is defined for use with Cancel-Job, Hold-Job, Release-Job, and Restart-Job. The Printer copies it to the Job's 'job-message-from-operator' Job Description attribute. Unlike the printer counterpart, there are no corresponding job-message-time or job-message-date-time attributes due to the limited lifetime of jobs.
The 'job-settable-attributes-supported' (1setOf type2 keyword) is a REQUIRED READ-ONLY Printer Description attribute listing Job attributes settable via Set-Job-Attributes. It MUST be supported if Set-Job-Attributes is supported.
The 'printer-message-from-operator' (text(127)) operation attribute is defined for use with Pause-Printer, Resume-Printer, and Purge-Jobs operations. When supplied, the Printer copies the value to the 'printer-message-from-operator' Printer Description attribute and also updates 'printer-message-time' and 'printer-message-date-time' as side effects.
The 'printer-settable-attributes-supported' (1setOf type2 keyword) is a REQUIRED READ-ONLY Printer Description attribute that lists which Printer attributes are settable in the implementation. It MUST be supported if Set-Printer-Attributes is supported, and the Printer MUST reject attempts to set attributes not listed here.
The 'printer-xri-supported' (1setOf collection) OPTIONAL Printer Description attribute provides a settable collection equivalent of the three READ-ONLY IPP/1.1 attributes 'printer-uri-supported', 'uri-authentication-supported', and 'uri-security-supported'. Setting it via Set-Printer-Attributes atomically updates all three READ-ONLY attributes as a defined side effect.
Three new OPTIONAL operations are defined: Set-Printer-Attributes (0x0013) sets attribute values of a target Printer object, Set-Job-Attributes (0x0014) sets attribute values of a target Job object, and Get-Printer-Supported-Values (0x0015) returns values valid for setting 'xxx-supported' Printer attributes.
New IPP out-of-band attribute values registered: 0x15 ('not-settable'), 0x16 ('delete-attribute'), 0x17 ('admin-define'). New status code registered: 'client-error-attributes-not-settable' (0x0413). Nine new Printer Description attributes and two new operation attributes registered.
Three new operations are registered in the IPP Operations registry: Set-Printer-Attributes (0x0013), Set-Job-Attributes (0x0014), and Get-Printer-Supported-Values (0x0015), along with corresponding enum values for 'operations-supported'.
The Set-Printer-Attributes and Set-Job-Attributes operations modify printer and job configuration and therefore require authenticated operator or administrator access rights. The security considerations are the same as those defined in IPP/1.1 [RFC2911], and all authentication and authorization mechanisms defined there apply equally to these new operations.
Set-Job-Attributes defines allowed job-state transitions: 'pending' may stay 'pending' or move to 'pending-held'; 'pending-held' may stay or move to 'pending'; 'processing' and 'processing-stopped' may stay in state or return 'client-error-not-possible' depending on implementation; 'completed', 'canceled', and 'aborted' always return 'client-error-not-possible'.
The 'admin-define' out-of-band attribute value is encoded as 0x17 (per RFC 2910). The value-length MUST be 0 and the value empty. It is returned by the Printer in Get-Printer-Supported-Values responses to indicate that arbitrary 'name' values may be defined for that 'xxx-supported' attribute.
The 'delete-attribute' out-of-band attribute value is encoded as 0x16 (per RFC 2910). The value-length MUST be 0 and the value empty. It is supplied by the client in Set-Job-Attributes requests to remove an attribute from the Job object.
The 'not-settable' out-of-band attribute value is encoded as 0x15 (per RFC 2910). The value-length MUST be 0 and the value empty. It is returned by the Printer in response to indicate an attribute is READ-ONLY or not settable in this implementation.