PWG DRAFT ipp-ops-set1-981023.txt R. Bergman Dataproducts Corp. T. Hastings Xerox Corporation R. Herriot Sun Microsystems P. Moore Microsoft October 23, 1998 Internet Printing Protocol/1.0: Additional Optional Operations - Set 1 Status of this Memo This document is a Printer Working Group (PWG) DRAFT. The previous version (980920) was posted to the IPP mailing list for comment on 9/20/98 and reviewed at the September 30, 1998 PWG meeting in Savannah. This version contains the changes agreed to at that meeting and need to be reviewed by the participants on the mailing list using the Last Call PWG procedures. Abstract This document specifies six OPTIONAL operations for use with the Internet Printing Protocol/1.0 (IPP) [ipp-mod, ipp-pro]. The defined Set 1 operations are 3 Job object operations that end-users may perform on their jobs and operators/administrators may perform on any job: Hold-Job Release-Job Restart-Job and 3 Printer object operations that operators/administrators may perform on a Printer object: Pause-Printer Resume-Printer Purge-Jobs PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 Table of Contents 1 Summary of Set 1 and Operation-Id Assignments...........3 2 Job Operations.............................................3 2.1Hold-Job..................................................3 2.1.1"job-hold-until" (type3 keyword | name(MAX)) operation attribute..................................................3 2.2Release-Job...............................................5 2.3Restart-Job...............................................6 3 Additional "job-state-reasons" and the Job History concept 7 3.1The "job history" concept 7 3.2Add a new 'job-restartable' value to the "job-state-reasons" attribute 8 4 Printer operations.........................................9 4.1Pause-Printer............................................10 4.1.1Add a new 'moving-to-paused' value to the "printer-state- reasons" attribute........................................12 4.2Resume-Printer...........................................12 4.3Purge-Jobs...............................................12 5 Security Considerations...................................13 6 References................................................13 Bergman, Hastings, Herriot, Moore 2 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 1 Summary of Set 1 and Operation-Id Assignments The Set 1 operations are summarized in the following table: Operation Operati Brief description Name on-Id Hold-Job 0x000C Holds a pending job so that it cannot be scheduled for processing Release-Job 0x000D Allows a previously held job to be scheduled for processing Restart-Job 0x000E Restarts a job as the same job on the same Printer object 0x000F Reserved for the future. Pause- 0x0010 Stops the device(s) as soon as possible Printer from processing jobs Resume- 0x0011 Resumes the device(s) processing jobs Printer Purge-Jobs 0x0012 Removes all jobs from the Printer regardless of job state All of the operations in Set 1 are OPTIONAL for an IPP object to support. Unless the specification of an OPTIONAL operation requires support of another OPTIONAL operation, conforming implementations may support any combination of these operations. 2 Job Operations The job operations in Set 1 are for use by end users on their jobs and by operators and administrators on any jobs. The operation attributes in requests and responses for the job operations are the same as the standard Cancel-Job operation (see [model] 3.3.3). Additional operation attributes are specified that the client MAY supply in a request. 2.1 Hold-Job This operation allows a client to hold a pending job in the queue so that it is not eligible for scheduling. If the Hold-Job operation is supported, then the Release-Job operation MUST be supported, and vice- versa. 2.1.1"job-hold-until" (type3 keyword | name(MAX)) operation attribute The client OPTIONALLY supplies this attribute. The IPP object MUST support this operation attribute in a Hold-Job request, if it supports the "job-hold-until" Job template attribute in create operations. See [ipp-mod] section 4.2.2. Otherwise, the IPP object NEED NOT support the "job-hold-until" operation attribute in a Hold-Job request. If supplied and supported as specified in the Printer's "job-hold-until-supported" attribute, the IPP object copies the attribute to the Job object, replacing the job's previous "job-hold-until" attribute, if present, and Bergman, Hastings, Herriot, Moore 3 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 makes the job a candidate for scheduling during the supplied named time period. As with all operations, if the client supplies the "job-hold-until" (or any OPTIONAL) Operation attribute that is unknown or unsupported or the value is unsupported, the IPP object MUST accept and perform the operation, ignoring the unknown or unsupported operation attribute and returning the ignored or unsupported attributes and/or values in Group 2 Unsupported Attributes (see [ipp-mod] sections 3.3.3.2 and 16.3.6). If the client (1) supplies a value that specifies a time period that has already started or the 'no-hold' value [ipp-mod 4.2.2] (meaning don't hold the job) and (2) the IPP object supports the "job-hold-until" operation attribute and there are no other reasons to hold the job, the IPP object MUST accept the operation and make the job be a candidate for processing immediately (see [ipp-mod] Section 4.2.2). The following new keyword value is defined for use with the "job-hold- until" Job Template attribute in job create operations and the "job- hold-until" operation attribute in Hold-Job and Restart-Job operations: 'indefinite': - the job is held indefinitely, until a client performs a Release-Job or Restart-Job operation If the client does not supply a "job-hold-until" operation attribute in the request, the IPP object MUST populate the job object with a "job- hold-until" attribute with the 'indefinite' value (if IPP object supports the "job-hold-until" attribute) and hold the job indefinitely, until a client performs a Release-Job or Restart-Job operation. The IPP object SHOULD support the "job-hold-until" Job Template attribute for use in job create operations with at least the 'indefinite' value, if it supports the Hold-Job operation. Otherwise, a client cannot create a job and hold it immediately (without picking some supported time period in the future). The IPP object MUST accept or reject the request based on the job's current state, transition the job to the indicated new state as follows: Current "job- New "job- IPP object's response status state" state" code and action: 'pending' 'pending- 'successful-ok' See Note 1 held' 'pending' 'pending' 'successful-ok' See Note 2 'pending- 'pending- 'successful-ok' See Note 1 held' held' 'pending- 'pending' 'successful-ok' See Note 2 held' 'processing' 'processing' 'client-error-not-possible' 'processing- 'processing- 'client-error-not-possible' stopped' stopped' 'completed' 'completed' 'client-error-not-possible' Bergman, Hastings, Herriot, Moore 4 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 'canceled' 'canceled' 'client-error-not-possible' 'aborted' 'aborted' 'client-error-not-possible' Note 1: If the OPTIONAL "job-state-reasons" attribute is supported and if the implementation supports multiple reasons for a job to be in the 'pending-held' state, the IPP object MUST add the 'job-hold-until- specified' value to the job's "job-state-reasons" attribute. Note 2: If the IPP object supports the "job-hold-until" operation attribute, but the specified time period has already started (or is the 'no-hold' value) and there are no other reasons to hold the job, the IPP object MUST make the job be a candidate for processing immediately (see [ipp-mod] Section 4.2.2) by putting the job in the 'pending' state. Note: In order to keep the Hold-Job operation simple, such a request is rejected when the job is in the 'processing' or 'processing-stopped' states. If an operation is needed to hold jobs while in these states, it will be added as an additional operation, rather than overloading the Hold-Job operation. Then it is clear to clients by querying the Printer object's "operations-supported" [ipp-mod 4.4.13] and the Job object's "job-state" [ipp-mod 4.3.7] attributes which operations are possible. Access Rights: The requesting user must either be the submitter of the job or an operator or administrator of the Printer object (see [ipp-mod] Section 1). Otherwise, the IPP object MUST reject the operation and return: 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' as appropriate. 2.2 Release-Job This operation allows a client to release a previously held job so that it is again eligible for scheduling. This operation removes the "job- hold-until" job attribute, if present, from the job object that had been supplied in the create or most recent Hold-Job or Restart-Job operation and remove its effect on the job. If the Hold-Job operation is supported, then the Release-Job operation MUST be supported, and vice-versa. If the OPTIONAL "job-state-reasons" attribute is supported, the IPP object MUST remove the 'job-hold-until-specified' value from the job's "job-state-reasons" attribute, if present. The IPP object MUST accept or reject the request based on the job's current state, transition the job to the indicated new state as follows: Current "job- New "job- IPP object's response status state" state" code and action: 'pending' 'pending' 'successful-ok' No effect on the job. 'pending- 'pending- 'successful-ok' See Note 1 held' held' 'pending- 'pending' 'successful-ok' held' Bergman, Hastings, Herriot, Moore 5 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 'processing' 'processing' 'successful-ok' No effect on the job. 'processing- 'processing- 'successful-ok' No effect on stopped' stopped' the job. 'completed' 'completed' 'client-error-not-possible' 'canceled' 'canceled' 'client-error-not-possible' 'aborted' 'aborted' 'client-error-not-possible' Note 1: If there are other reasons to keep the job in the 'pending- held' state, such as 'resources-are-not-ready', the job remains in the 'pending-held' state. Thus the 'pending-held' state is not just for jobs that have the 'job-hold-until' applied to them, but are for any reason to keep the job from being a candidate for scheduling and processing, such as 'resources-are-not-ready'. See the "job-hold-until" attribute ([ipp-mod] Section 4.2.2). Access Rights: The requesting user must either be the submitter of the job or an operator or administrator of the Printer object. Otherwise, the IPP object MUST reject the operation and return: 'client-error- forbidden', 'client-error-not-authenticated', or 'client-error-not- authorized' as appropriate. 2.3 Restart-Job This operation allows a client to restart a job that is retained in the queue after processing has completed. As an implementation option, a job in the 'processing' and/or 'processing-stopped' states MAY be restarted. The job is moved to the 'pending' job state and restarts at the beginning on the same IPP Printer object with the same attribute values. The Job Description attributes that accumulate job progress, such as "job-impressions-completed", "job-media-sheets-completed", and "job-k- octets-processed", MUST be reset to 0 so that they give an accurate record of the job from its restart point. The job object MUST continue to use the same "job-uri" and "job-id" attribute values. 2.3.1"job-hold-until" (type3 keyword | name(MAX)) operation attribute The client OPTIONALLY supplies this attribute. The IPP object MUST support this operation attribute in a Restart-Job request, if it supports the "job-hold-until" Job template attribute in create operations. See [ipp-mod] section 4.2.2. Otherwise, the IPP object NEED NOT support the "job-hold-until" operation attribute in a Restart- Job request. If supplied and supported, the IPP object copies the attribute to the Job object, replacing the job's previous "job-hold- until" attribute, if present, and makes the job a candidate for scheduling during the supplied named time period. See Section 2.1.1 for the common semantics of the "job-hold-until" operation attribute for the Hold-Job operation and Restart-Job operation. Bergman, Hastings, Herriot, Moore 6 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 Note: In the future an OPTIONAL Modify-Job operation may be specified that allows the client to modify other attributes before releasing the restarted job. The IPP object MUST accept or reject the request based on the job's current state, transition the job (or new job, depending on implementation) to the indicated new state as follows: Current "job- New "job- IPP object's response status state" state" code and action: 'pending' 'pending' 'client-error-not-possible'. 'pending- 'pending- 'client-error-not-possible'. held' held' 'processing' 'pending' OPTION 1: 'successful-ok' - job is started over. See Note 1. 'processing' 'processing' OPTION 2: 'client-error-not- possible'. 'processing- 'pending' OPTION 1: 'successful-ok' - job stopped' is started over. See Note 1 'processing- 'processing- OPTION 2: 'client-error-not- stopped' stopped' possible'. 'completed' 'pending' 'successful-ok' - job is started over. 'canceled' 'pending' 'successful-ok' - job is started over. 'aborted' 'pending' 'successful-ok' - job is started over. Note 1: For OPTION 1, the IPP object SHOULD indicate to clients that a Restart-Job operation is possible while the job is in the 'processing' and/or 'processing-stopped' states, by populating the job's "job-state- reasons" attribute with the 'job-restartable' value. Access Rights: The requesting user must either be the submitter of the job or an operator or administrator of the Printer object. 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 The Job History concept and additional "job-state-reasons" This section explains the so-called Printer object's "job-history" that contains the recently completed, canceled, and aborted jobs. This section also specifies the 'job-restartable' value of the "job-state- reasons" Job Description attribute for use with the Restart-Job operations. 3.1 The "job history" concept When a job is completed, canceled, or aborted, the IPP Printer object MAY retain the job with its document data in a restartable condition using the Restart-Job operation for an implementation-defined time Bergman, Hastings, Herriot, Moore 7 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 period which may be zero seconds. If the IPP object supports the "job- state-reasons" attribute and the Restart-Job operation, then it SHOULD indicate that such jobs are restartable by adding the 'job-restartable' value to the job's "job-state-reasons" attribute (see Section 3.2) during that implementation-defined time period. After the implementation-defined restartable time period expires, the Printer object deletes the document data for the job and the job becomes part of the "job history". The Print object MAY also delete any number of the job attributes. Since the job is no longer restartable, the Printer object MUST remove the 'job-restartable' value from the job's "job-state-reasons" attribute, if supported. Clients are able to query jobs in the Printer object's "job history" using Get-Job-Attributes and Get-Jobs operations. Subsequently, the IPP Printer removes jobs from its "job history" in an implementation-defined manner, such as after a fixed time period (which MAY be zero seconds) or when the number of jobs exceeds a fixed number. Thereupon, the job can no longer be queried using the Get-Job-Attributes and Get-Jobs operations and the IPP object returns the 'client-error- not-found' or 'client-error-gone' as appropriate. 3.2 Add a new 'job-restartable' value to the "job-state-reasons" attribute The following new keyword value is specified for use with the "job- state-reasons" Job Description attribute and the Restart-Job operation (see Section 2.3): 'job-restartable' - This job is currently able to be restarted using the Restart-Job operation. With which job states this values is used depends on implementation, i.e., OPTION 1 vs. OPTION 2 in the job state transition table in Section 2.3. Whenever the IPP object will reject a Restart-Job operation for the job with the 'client- error-not-possible' error status code because the job is not restartable, the IPP object MUST remove this value from the job's "job-state-reasons" attribute. For example, after a job is completed (job state is 'completed', 'aborted', or 'canceled), the implementation MAY retain the job in a restartable condition for an implementation-defined time period. When that time elapses, an implementation MAY delete the document data, but MAY retain some or all of the job attributes as a "job history" for an additional implementation-defined time period. During this second time period, the implementation removes the 'job-restartable' value from the job's "job-state-reasons" attribute, since the job can no longer be restarted. Bergman, Hastings, Herriot, Moore 8 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 4 Printer operations The printer operations in Set 1 are for use by operators and administrators of each Printer object. The following figure is copied from [ipp-mod] with the addition of the following arrow: any****> indicating an additional source of job submission using IPP or any other job submission protocol that passes to the device but does NOT pass through the IPP Printer object in question. Legend: ##### indicates a Printer object which is either embedded in an output device or is hosted in a server. The Printer object might or might not be capable of queuing/spooling. any indicates any network protocol or direct connect, including IPP embedded printer: output device any****>+---------------+ O +--------+ | ########### | /|\ | client |------------IPP------------># Printer # | / \ +--------+ | # Object # | | ########### | +---------------+ hosted printer: any****>+---------------+ O +--------+ ########### | | /|\ | client |--IPP--># Printer #-any->| output device | / \ +--------+ # Object # | | ########### +---------------+ any****>+---------------+ fan out: | | +-->| output device | any/ | | O +--------+ ########### / +---------------+ /|\ | client |-IPP-># Printer #--* / \ +--------+ # Object # \ +---------------+ ########### any\ | | +-->| output device | | | +---------------+ Bergman, Hastings, Herriot, Moore 9 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 The operation attributes for the Printer operation requests are as follows:- 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 of [ipp-mod]. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5 of [ipp-mod]. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3 of [ipp-mod]. The operation attributes for the Printer operation responses are as follows: 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) operation attribute as described in section 3.1.6 of [ipp-mod]. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2 of [ipp-mod]. Group 2: Unsupported Attributes This is a set of Operation attributes supplied by the client (in the request) that are not supported by the Printer object or that conflict with one another (see sections 3.2.1.2 and 16). 4.1 Pause-Printer This 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 supports the "printer- Bergman, Hastings, Herriot, Moore 10 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 state-reasons" attribute and the devices will take appreciable time to stop, the IPP Printer adds the 'moving-to-paused' value to the Printer object's "printer-state-reasons" attribute. 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, if the "job-state-reasons" attribute is supported, adds the 'printer-stopped' value to the job's "job-state-reasons" attribute. Note: 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 job's "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 (see the any***> arrow in the figure above) 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, 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' 'processin 'processin 'moving- OPTION 1: 'successful-ok'; g' g' 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 'processin 'stopped' 'paused' OPTION 2: 'successful-ok'; g' all output stopped immediately 'stopped' 'stopped' 'paused' 'successful-ok' Access Rights: The requesting user must be an operator or administrator of the Printer object. Otherwise, the IPP Printer MUST reject the operation and return: 'client-error-forbidden', 'client-error-not- authenticated', or 'client-error-not-authorized' as appropriate. Bergman, Hastings, Herriot, Moore 11 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 4.1.1Add a new 'moving-to-paused' value to the "printer-state-reasons" attribute The following new keyword value is specified for use with the "printer- state-reasons" Printer Description attribute: 'moving-to-paused': The Printer object's operator or administrator has paused the Printer object using the Pause-Printer operation or other means, but it has not yet stopped producing output. When all the devices stop producing output, the Printer object MUST replace this value with the 'paused' value. 4.2 Resume-Printer This operation allows a client to resume the Printer object scheduling jobs on all its devices. If the Printer object supports the "printer- state-reasons" attribute, it 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 transitions 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 "printer- state" and 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 requesting user must be an operator or administrator of the Printer object. Otherwise, the IPP Printer MUST reject the operation and return: 'client-error-forbidden', 'client-error-not- authenticated', or 'client-error-not-authorized' as appropriate. 4.3 Purge-Jobs This operation allows a client to remove all jobs from an IPP Printer object, regardless of their job states, including jobs in the Printer Bergman, Hastings, Herriot, Moore 12 PWG-DRAFT IPP Set 1 Additional Optional OperationsSeptember 20, 1998 object's "job-history" (see Section 3.1). 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 (see the any***> arrow in the figure in Section 4) 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-Job operation. The Printer object MUST accept this operation in any state and transition the Printer object to the 'idle' state. Access Rights: The requesting user must be an operator or administrator of the Printer object. Otherwise, the IPP object MUST reject the operation and return: client-error-forbidden, client-error-not- authenticated, and client-error-not-authorized as appropriate. 5 Security Considerations For the job operations in Set 1 (Section 2), the requesting user must either be the submitter of the job or an operator or administrator of the Printer object (see [ipp-mod] Section 1). Otherwise, the IPP object MUST reject the operation and return: 'client-error-forbidden', 'client- error-not-authenticated', or 'client-error-not-authorized' as appropriate. See [ipp-mod] Section 8.3 on the two ways that the client MUST specify the user who is performing each IPP operation. For the printer operations in Set 1 (Section 4), the requesting user must by an operator or administrator of the Printer object (see [ipp- mod] Section 1). The means for authorizing an operator or administrator of the Printer object are not specified in either [ipp-mod] or this document. 6 References [ipp-mod] Isaacson, S., deBry, R., Hastings, T., Herriot, R., Powell, P., .Internet Printing Protocol/1.0: Model and Semantics. draft-ietf- ipp-mod-10.txt, June, 1998. [ipp-pro] Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing Protocol/1.0: Encoding and Transport", draft-ietf-ipp-pro-06.txt, June, 1998. Bergman, Hastings, Herriot, Moore 13