reject the operation and return: the ’client-error-forbidden’,
’client-error-not-authenticated’, or ’client-error-not-authorized’
status code as appropriate.
11.1.1.1. Create-Job-Subscriptions Request
The following groups of attributes are part of the Create-Job-
Subscriptions Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
11.1.1.1.1. notify-job-id (integer(1:MAX))
The client MUST supply this attribute and it MUST specify the Job
object to associate the Per-Job Subscription with. The value of
"notify-job-id" MUST be the value of the "job-id" of the associated
Job object. If the client does not supply this attribute, the
Printer MUST reject this request with a ’client-error-bad-request’
status code.
Group 2-N: Subscription Template Attributes
For each occurrence of this group:
The client MUST supply one or more Subscription Template
Attributes in any order. See section 5.3 for a description of
each such attribute. See section 5.2 for details on processing
these attributes.
11.1.1.2. Create-Job-Subscriptions Response
The Printer MUST return to the client the following sets of
attributes as part of a Create-Job-Subscriptions 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 [RFC2911] sections 13 and
3.1.6.
In this group, the Printer can return any status codes defined in
[RFC2911] and section 12. The following is a description of the
important status codes:
successful-ok: the Printer created all Subscription Objects
requested (see [RFC2911]).
successful-ok-ignored-subscriptions: the Printer created some
Subscription Objects requested but some failed. The
Subscription Attributes Groups with a "notify-status-code"
attribute are the ones that failed (see section 12.1).
client-error-ignored-all-subscriptions: the Printer created no
Subscription Objects requested and all failed. The
Subscription Attributes Groups with a "notify-status-code"
attribute are the ones that failed (see section 12.2).
client-error-not-possible: For this operation and other Per-Job
Subscription operations, this error can occur because the
specified Job has already completed (see [RFC2911], whether or
not the Job is retained in the Job Retention and/or Job History
phases (see [RFC2911] section 4.3.7.1).
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning Unsupported
Attributes. This group does not contain any unsupported
Subscription Template Attributes; they are returned in the
Subscription Attributes Group (see below).
Group 3-N: Subscription Attributes
These groups MUST be returned unless the Printer is unable to
interpret the entire request, e.g., the "status-code" parameter
returned in Group 1 has the value: ’client-error-bad-request’.
"notify-status-code" (type2 enum):
Indicates the status of this subscription (see section 13 for
the status code definitions). Section 5.2 defines when this
attribute MUST be present in this group.
See section 5.2 for details on the contents of each occurrence of
this group.
11.1.2. Create-Printer-Subscriptions operation
The operation is identical to Create-Job-Subscriptions with
exceptions noted in this section.
The operation creates Per-Printer Subscription Objects instead of
Per-Job Subscription Objects, and associates each newly created Per-
Printer Subscription Object with the Printer specified by the
operation target rather than with a specific Job.
The Printer MUST accept the request in any of its states, i.e.,
’idle’, ’processing’, or ’stopped’. The Printer MUST NOT change its
"printer-state" attribute because of this operation.
Access Rights: To create Per-Printer Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST have (1) Operator or Administrator access rights for
this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise
authorized by the Printer’s administrator-configured security policy
to create Per-Printer Subscription Objects for this Printer.
Otherwise, the Printer MUST reject the operation and return: the
’client-error-forbidden’, ’client-error-not-authenticated’, or
’client-error-not-authorized’ status code as appropriate.
11.1.2.1. Create-Printer-Subscriptions Request
The groups are identical to the Create-Job-Subscriptions (see section
11.1.1.1) except that the Operation Attributes group MUST NOT contain
the "notify-job-id" attribute. If the client does supply the
"notify-job-id" attribute, then the Printer MUST treat it as any
other unsupported Operation attribute and MUST return it in the
Unsupported Attributes group.
11.1.2.2. Create-Printer-Subscriptions Response
The groups are identical to the Create-Job-Subscriptions (see section
11.1.1.2).
11.1.3. Job Creation Operations - Extensions for Notification
This document extends the Job Creation operations (see section 3.2)
to create Subscription Objects as a part of the operation.
The Job Creation operations are identical to Create-Job-Subscriptions
operation with exceptions noted in this section.
Unlike the Create-Job-Subscriptions operation, a Job Creation
operation associates the newly created Subscription Objects with the
Job object created by this operation. The operation succeeds if and
only if the Job creation succeeds. If the Printer does not create
some or all of the requested Subscription Objects, the Printer MUST
return a ’successful-ok-ignored-subscriptions’ status-code instead
of a ’successful-ok’ status-code, but the Printer MUST NOT reject the
operation because of a failure to create Subscription Objects.
If the Job Creation operation includes a Job Template group, the
client MUST supply it after the Operation Attributes group and before
the first Subscription Template Attributes Group.
If a Printer does not support this Notification specification, then
it MUST treat the Subscription Attributes Group like an unknown group
and ignore it (see [RFC2911] section 5.2.2). Because the Printer
ignores the Subscription Attributes Group, it doesn’t return them in
the response either, thus indicating to the client that the Printer
doesn’t support Notification.
After completion of a successful Job Creation operation, the Printer
generates a ’job-created’ event (see section 5.3.3.4.3).
Access Rights: To create Per-Job Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST either have permission to create Jobs on the Printer
or have Operator or Administrator access rights for this Printer (see
[RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the
operation and return: the ’client-error-forbidden’, ’client-error-
not-authenticated’, or ’client-error-not-authorized’ status code as
appropriate.
11.1.3.1. Job Creation Request
The groups for this operation are sufficiently different from the
Create-Job-Subscriptions operation that they are all presented here.
The following groups of attributes are supplied as part of a Job
Creation Request:
Group 1: Operation Attributes
Same as defined in [RFC2911] for Print-Job, Print-URI, and
Create-Job requests.
Group 2: Job Template Attributes
The client OPTIONALLY supplies a set of Job Template attributes as
defined in [RFC2911] section 4.2.
Group 3 to N: Subscription Template Attributes
The same as Group 2-N in Create-Job-Subscriptions. See section
11.1.1.1.
Group N+1: Document Content (Print-Job only)
The client MUST supply the document data to be processed.
11.1.3.2. Job Creation Response
The Printer MUST return to the client the following sets of
attributes as part of a Print-Job, Print-URI, and Create-Job
Response:
Group 1: Operation Attributes
Status Message:
As defined in [RFC2911] for Print-Job, Print-URI, and Create-
Job requests.
In this group, the Printer can return any status codes defined
in [RFC2911] and section 12. The following is a description of
the important status codes:
successful-ok: the Printer created the Job and all
Subscription Objects requested (see [RFC2911].
successful-ok-ignored-subscriptions: the Printer created
the Job and not all of the Subscription Objects requested
(see section 12.1). This status-code hides ’successful-ok-
xxx’ status-codes that could reveal problems in Job
creation. The Printer MUST NOT return the ’client-error-
ignored-all-subscriptions’ status code for Job Creation
operations because the Printer returns an error status-code
only when it fails to create a Job.
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning Unsupported
Attributes. This group does not contain any unsupported
Subscription Template Attributes; they are returned in the
Subscription Attributes Group (see below).
Group 3: Job Object Attributes
The "job-id" of the Job Object just created, etc., as defined in
[RFC2911] for Print-Job, Print-URI, and Create-Job requests.
Group 4 to N: Subscription Attributes
These groups MUST be returned if and only if the client supplied
Subscription Template Attributes and the operation was accepted.
See section 5.2 for details on the contents of each occurrence of
this group.
11.2. Other Operations
This section defines other operations on Subscription objects.
11.2.1. Restart-Job Operation - Extensions for Notification
The Restart-Job operation [RFC2911] is neither a Job Creation
operation nor a Subscription Creation operation (see section 3.2).
For the Restart-Job operation, the client MUST NOT supply any Job
Subscription Attributes Groups. The Printer MUST treat any supplied
Job Subscription Attributes as unsupported attributes.
For this operation, the Printer does not return a job-id or any
Subscription Attributes groups because the Printer reuses the
existing Job object with the same job-id and the existing Per-Job
Subscription Objects with the same subscription-ids. However, after
successful completion of this operation, the Printer generates a
’job-created’ event (see section 5.3.3.4.3).
11.2.2. Validate-Job Operation - Extensions for Notification
A client can test whether one or more Subscription Objects could be
created using the Validate-Job operation. The client supplies one or
more Subscription Template Attributes Groups (defined in section
5.3), just as in a Job Creation request.
A Printer MUST support this extension to this operation.
The Printer MUST accept requests that are identical to the Job
Creation request defined in section 11.1.3.1, except that the request
MUST NOT contain document data.
The Printer MUST return the same groups and attributes as the Print-
Job operation (section 11.1.3.1) with the following exceptions. The
Printer MUST NOT return a Job Object Attributes Group because no Job
is created. The Printer MUST NOT return the "notify-subscription-id"
attribute in any Subscription Attribute Group because no Subscription
Object is created.
If the Printer would succeed in creating a Subscription Object, the
corresponding Subscription Attributes Group either has no ’status-
code’ attribute or a ’status-code’ attribute with a value of
’successful-ok-too-many-events’ or ’successful-ok-ignored-or-
substituted-attributes’ (see sections 5.2 and 13). The status-codes
have the same meaning as in Job Creation except the results state
what "would happen".
The Printer MUST validate Subscription Template Attributes Groups in
the same manner as the Job Creation operations.
11.2.3. Get-Printer-Attributes - Extensions for Notification
This operation is extended so that it returns Printer attributes
defined in this document.
A Printer MUST support this extension to this operation.
In addition to the requirements of [RFC2911] section 3.2.5, a Printer
MUST support the following additional values for the "requested-
attributes" Operation attribute in this operation and return such
attributes in the Printer Object Attributes group of its response.
1. Subscription Template Attributes: Each supported attribute in
column 2 of Table 1.
2. New Printer Description Attributes: Each supported attribute in
section 6.
3. New Group Name: The ’subscription-template’ group name, which
names all supported Subscription Template Attribute in column 2 of
Table 1. This group name is also used in the Get-Subscription-
Attributes and Get-Subscriptions operation with an analogous
meaning.
4. Extended Group Name: The ’all’ group name, which names all Printer
attributes according to [RFC2911] section 3.2.5. In this
extension ’all’ names all attributes specified in [RFC2911] plus
those named in items 1 and 2 of this list.
11.2.4. Get-Subscription-Attributes operation
This operation allows a client to request the values of the
attributes of a Subscription Object.
A Printer MUST support this operation.
This operation is almost identical to the Get-Job-Attributes
operation (see [RFC2911] section 3.3.4). The only differences are
that the operation is directed at a Subscription Object rather than a
Job object, and the returned attribute group contains Subscription
Object attributes rather than Job object attributes.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST (1) be the Subscription Object owner,
(2) have Operator or Administrator access rights for this Printer
(see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by
the Printer’s administrator-configured security policy to query the
Subscription Object for the target job. Otherwise the Printer MUST
reject the operation and return: the ’client-error-forbidden’,
’client-error-not-authenticated’, or ’client-error-not-authorized’
status code as appropriate. Furthermore, the Printer’s security
policy MAY limit which attributes are returned, in a manner similar
to the Get-Job-Attributes operation (see [RFC2911] end of section
3.3.4.2).
11.2.4.1. Get-Subscription-Attributes Request
The following groups of attributes are part of the Get-Subscription-
Attributes request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in section [RFC2911] 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
11.2.4.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this
attribute. This attribute specifies the Subscription Object from
which the client is requesting attributes. If the client omits this
attribute, the Printer MUST reject this request with the ’client-
error-bad-request’ status code.
11.2.4.1.2. "requested-attributes" (1setOf keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. This attribute specifies the attributes of
the specified Subscription Object that the Printer MUST return in the
response. Each value of this attribute is either an attribute name
(defined in sections 5.3 and 5.4) or an attribute group name. The
attribute group names are:
- ’subscription-template’: all attributes that are both defined in
section 5.3 and present on the specified Subscription Object
(column 1 of Table 1).
- ’subscription-description’: all attributes that are both defined
in section 5.4 and present on the specified Subscription Object
(Table 2).
- ’all’: all attributes that are present on the specified
Subscription Object.
A Printer MUST support all these group names.
If the client omits this attribute, the Printer MUST respond as if
this attribute had been supplied with a value of ’all’.
11.2.4.2. Get-Subscription-Attributes Response
The Printer returns the following sets of attributes as part of the
Get-Subscription-Attributes Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2. The
"attributes-natural-language" MAY be the natural language of the
Subscription Object, rather than the one requested.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on
returning Unsupported Attributes.
The response NEED NOT contain the "requested-attributes" operation
attribute with any supplied keyword values 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, the values of the
"requested-attributes" attribute returned MUST include only the
unsupported keywords that were requested by the client. If the
client had requested a group name, such as ’all’, the resulting
unsupported attributes returned MUST NOT include attribute keyword
names described in the standard but not supported by the
implementation.
Group 3: Subscription Attributes
This group contains a set of attributes with their current values.
Each attribute returned in this group:
a) MUST be specified by the "requested-attributes" attribute in the
request, AND
b) MUST be present on the specified Subscription Object AND
c) MUST NOT be restricted by the security policy in force. For
example, a Printer MAY prohibit a client who is not the creator of
a Subscription Object from seeing some or all of its attributes.
See [RFC2911] end of section 3.3.4.2 and section 8.
The Printer can return the attributes of the Subscription Object
in any order. The client MUST accept the attributes in any order.
11.2.5. Get-Subscriptions operation
This operation allows a client to retrieve the values of attributes
of all Subscription Objects belonging to a Job or Printer.
A Printer MUST supported this operation.
This operation is similar to the Get-Subscription-Attributes
operation, except that this Get-Subscriptions operation returns
attributes from possibly more than one object.
This operation is similar to the Get-Jobs operation (see [RFC2911]
section 3.2.6), except that the operation returns Subscription
Objects rather than Job objects.
Access Rights: To query Per-Job Subscription Objects of the
specified job (client supplied the "notify-job-id" operation
attribute - see section 11.2.5.1.1), the authenticated user (see
[RFC2911] section 8.3) performing this operation MUST (1) be the
Subscription Object owner, (2) have Operator or Administrator access
rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be
otherwise authorized by the Printer’s administrator-configured
security policy to query the Subscription Object for the target job.
To query Per-Printer Subscription Objects of the Printer (client
omits the "notify-job-id" operation attribute - see section
11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3)
performing this operation MUST (1) have Operator or Administrator
access rights for this Printer (see [RFC2911] sections 1 and 8.5), or
(2) be otherwise authorized by the Printer’s administrator-configured
security policy to query Per-Printer Subscription Objects for the
target Printer. Otherwise the Printer MUST reject the operation and
return: the ’client-error-forbidden’, ’client-error-not-
authenticated’, or ’client-error-not-authorized’ status code as
appropriate. Furthermore, the Printer’s security policy MAY limit
which attributes are returned, in a manner similar to the Get-Jobs
and Get-Printer-Attributes operations (see [RFC2911] end of sections
3.2.6.2 and 3.2.5.2).
11.2.5.1. Get-Subscriptions Request
The following groups of attributes are part of the Get-Subscriptions
request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
11.2.5.1.1. "notify-job-id" (integer(1:MAX))
If the client specifies this attribute, the Printer returns the
specified attributes of all Per-Job Subscription Objects associated
with the Job whose "job-id" attribute value equals the value of this
attribute. If the client does not specify this attribute, the
Printer returns the specified attributes of all Per-Printer
Subscription Objects. Note: there is no way to get all Per-Job
Subscriptions known to the Printer in a single operation. A Get-Jobs
operation followed by a Get-Subscriptions operation for each Job will
return all Per-Job Subscriptions.
11.2.5.1.2. "limit" (integer(1:MAX))
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. It is an integer value that determines the
maximum number of Subscription Objects that a client will receive
from the Printer even if the "my-subscriptions" attribute constrains
which Subscription Objects are returned. The limit is a "stateless
limit" in that if the value supplied by the client is ’N’, then only
the first ’N’ Subscription Objects are returned in the Get-
Subscriptions Response. There is no mechanism to allow for the next
’M’ Subscription Objects after the first ’N’ Subscription Objects.
If the client does not supply this attribute, the Printer responds
with all applicable Subscription Objects.
11.2.5.1.3. "requested-attributes" (1setOf type2 keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. This attribute specifies the attributes of
the specified Subscription Objects that the Printer MUST return in
the response. Each value of this attribute is either an attribute
name (defined in sections 5.3 and 5.4) or an attribute group name
(defined in section 11.2.4.1). If the client omits this attribute,
the Printer MUST respond as if the client had supplied this attribute
with the one value: ’notify-subscription-id’.
11.2.5.1.4. "my-subscriptions" (boolean)
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. If the value is ’false’, the Printer MUST
consider the Subscription Objects from all users as candidates. If
the value is ’true’, the Printer MUST return the Subscription Objects
created by the requesting user of this request. If the client does
not supply this attribute, the Printer MUST respond as if the client
had supplied the attribute with a value of ’false’. The means for
authenticating the requesting user and matching the Subscription
Objects is similar to that for Jobs which is described in [RFC2911]
section 8.