PWG DRAFT to become an INTERNET-DRAFT draft-pwg-ipp-ops-set1-00.txt R. Bergman Data Products T. Hastings Xerox Corporation R. Herriot Sun Microsystems P. Moore Microsoft July 27, 1998 Internet Printing Protocol/1.0: Additional Optional Operations - Set 1 Copyright (C) The Internet Society (date). All Rights Reserved. Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract This document specifies seven OPTIONAL operations for use with the Internet Printing Protocol/1.0 (IPP) [ipp-mod, ipp-pro]. The defined Set 1 operations are: Hold-Job Release-Job Restart-Job Reprocess-Job Pause-Printer Resume-Printer Purge-Jobs Bergman, Hastings, Herriot, Moore Expires January, 27, 1999 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 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..................................................4 2.2Release-Job...............................................5 2.3Restart-Job...............................................6 2.4Reprocess-Job.............................................7 3 Printer operations.........................................8 3.1Pause-Printer.............................................9 3.1.1Add a new 'moving-to-paused' value to the "printer-state- reasons" attribute........................................10 3.2Resume-Printer...........................................10 3.3Purge-Jobs...............................................11 4 References................................................12 Bergman, Hastings, Herriot, Moore 2 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 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 completed job as the same job on the same Printer object Reprocess- 0x000F Reprocesses a completed job as a new Job copy of the job on the same Printer object 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 attributes 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 operation attributes 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. In addition, the IPP object MUST return the "job-state" [ipp-mod 4.3.7] attribute and, if supported, the "job-state-reasons" [ipp-mod 4.3.8] attribute in the response in order to indicate the effect of the operation on the job object. Note: In order to keep the operations in Operation Set 1 simple, they are rejected when the job is in the 'processing' or 'processing-stopped' states. If operations are needed to affect jobs while in these states, they will be added as additional operations, rather than overloading these operations. Then it is clear to clients by querying the Printer object's "operations-supported" [ipp-mod 4.4.13] what the behavior is. 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 Bergman, Hastings, Herriot, Moore 3 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 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, if it supports the "job-hold-until" Job template attribute. See [ipp-mod] section 4.2.2. If supplied and supported, the IPP object copies the attribute to the Job object, replacing the previous attribute, if present, and 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 operation attribute and returning the ignored or unsupported attributes and/or values (see [ipp-mod] sections 3.3.3.2 and 16.3.6). If the client supplies the 'no-hold' value [ipp-mod 4.2.2] (meaning don't hold the job) and the IPP object supports the "job-hold-until" operation attribute, the IPP object MUST reject the operation and return the 'client-error-bad-syntax' error status code. 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 operations: 'indefinite': - the job is held indefinitely, until a client performs a Release-Job operation If the client does not supply a "job-hold-until" operation attribute in the Hold-Job operation, 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 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, and return the indicated new "job-state" attribute and status code as follows: Current "job- New "job- IPP object's response status state" state" code and action: 'pending' 'pending- 'successful-ok' See Note 1 held' Bergman, Hastings, Herriot, Moore 4 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 'pending- 'pending- 'successful-ok' See Note 1 held' held' 'processing' 'processing' 'client-error-not-possible' 'processing- 'processing- 'client-error-not-possible' stopped' stopped' 'completed' 'completed' 'client-error-not-possible' '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. Access Rights: The requesting user must either be the submitter of the job or an administrator of the printer. 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 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, and return the indicated new "job-state" attribute and status code 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' 'processing' 'processing' 'successful-ok' No effect on the job. 'processing- 'processing- 'successful-ok' No effect on stopped' stopped' job. Bergman, Hastings, Herriot, Moore 5 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 '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'. Access Rights: The requesting user must either be the submitter of the job or an administrator of the printer. 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. The job 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. The IPP object MUST accept or reject the request based on the job's current state, transition the job to the indicated new state, and return the indicated new "job-state" attribute and status code 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' 'processing' 'client-error-not-possible'. 'processing- 'processing' 'client-error-not-possible'. stopped' '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: Resetting the job progress attributes, allows job monitoring applications to function unchanged for a job that has been restarted. Bergman, Hastings, Herriot, Moore 6 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 However, there is a problem for accounting applications that "pull" the job accounting data from the IPP object after the job completes using the Get-Job-Attributes or Get-Jobs operations (or SNMP MIBs). Since the "job-id" and "job-uri" for the restarted job are the same as the original job and the accounting attributes are reset, the accounting program may not be able to detect that the job was restarted and is using additional resources. It is recommended that the Reprocess-Job operation (see section 2.4) be used when accurate accounting data is desired to be made available to accounting programs that pull the data from the IPP Printer after the job completes, since a new job with a new "job-id" and "job-uri" is created while the old job remains for the accounting program to query accounting attributes. On the other hand, if an IPP object "pushes" the accounting data to the accounting application when the job completes, say, using event notification [ipp- not], then support of the Restart-Job operation is not in conflict with such "pull" accounting. Access Rights: The requesting user must either be the submitter of the job or an administrator of the printer. 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.4 Reprocess-Job This operation allows a client to reprocess a copy of the job that is retained in the queue after processing is completed. A copy of the job restarts at the beginning on the same IPP Printer object with possibly different Job Template attributes supplied by the client in the request. Thus the Reprocess-Job operation is another create job operation and all of the semantics that [ipp-mod] specifies for "create job operations" also apply to the Reprocess-Job operation. The client MAY supply any Job Template attributes as in a create job operation whether they were originally supplied in the job create operation or not. The Printer object performs a validation as in a create operation of the job that would be made up of any supplied attributes replacing the corresponding job's attributes in combination with any of the job's remaining Job Template attributes. If the Printer object supports the new combination of Job Template attributes, the Printer object accepts the Reprocess-Job operation, creates a new job, assigns new "job-id" and "job-uri" values, and makes a copy of the job attributes with their new values. The IPP object initializes the Job Description attributes of the new job as in a create job operation, so that attributes such as "media-sheets- completed", and "job-k-octets-processed" start at 0 and the new job enters the 'pending' or 'pending-held' state, as after a job create operation. The returned groups are the same as for the Print-Job operation including the "job-id" and "job-uri" attributes with the new values assigned by the Printer object, whether the job has one or multiple documents. Bergman, Hastings, Herriot, Moore 7 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 The Printer object leaves the old 'completed', 'canceled', or 'aborted' job as is and does not change any of its attributes. Therefore, the Job Description attributes are preserved for job monitoring and accounting purposes for the specified (old) job. Whether the document data is copied or shared between the old and the new job, depends on implementation, and cannot be detected by the client. Either the old job or the new job may be the target of subsequent Reprocess-Job operations. The IPP object MUST accept or reject the request based on the job's current state, transition the job to the indicated new state, and return the indicated new job's new "job-state" attribute and status code as follows: Old job's New job's new IPP object's response current "job-state" status code and action: "job-state" 'pending' n/a 'client-error-not- possible'. 'pending- n/a 'client-error-not- held' possible'. 'processing' n/a 'client-error-not- possible'. 'processing- n/a 'client-error-not- stopped' possible'. 'completed' 'pending' or 'successful-ok' 'pending-held' 'canceled' 'pending' or 'successful-ok' 'pending-held' 'aborted' 'pending' or 'successful-ok' 'pending-held' Access Rights: The requesting user must either be the submitter of the job or an administrator of the printer. 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 Printer operations 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]. Bergman, Hastings, Herriot, Moore 8 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 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]. "printer-state" and "printer-state-reasons: The Printer object MUST return the "printer-state" [ipp-mod 4.4.10] and, if supported, the "printer-state-reasons" [ipp-mod 4.4.11] attributes in order to indicate the effect of the operation on the Printer object. 3.1 Pause-Printer This operation allows a client to stop the Printer object from scheduling jobs on all its devices and to stop the Printer from processing the current job or jobs, if supported. 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- 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' Bergman, Hastings, Herriot, Moore 9 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 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"). The IPP Printer MUST accept the request in any state, transition the Printer to the indicated new "printer-state" before returning, and return the indicated "printer-state", "printer-state-reasons", and status code as follows: Current New "printer IPP Printer's response status "printer- "printer- -state- code and action: state" state" reasons" returned '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 administrator of the printer. 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.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': Someone has paused the Printer object, 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. 3.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- Bergman, Hastings, Herriot, Moore 10 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 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, and return the indicated "printer-state" and status code as follows: Current New IPP Printer's response status code "printer- "printer- and action: state" state" returned 'idle' 'idle' 'successful-ok' 'processing' 'processin 'successful-ok' g' 'stopped' 'processin 'successful-ok'; g' 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 administrator of the printer. 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.3 Purge-Jobs This operation allows a client to remove all jobs from an IPP Printer object, regardless of their job states. 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 administrator of the printer. Otherwise, the IPP object MUST reject the operation and return: client-error-forbidden, client-error-not-authenticated, and client-error-not-authorized as appropriate. Bergman, Hastings, Herriot, Moore 11 PWG-DRAFT IPP Set 1 Additional Optional Operations July 27, 1998 4 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-not] Isaacson, S., Martin, J., deBry, R., Hastings, T., .IPP Event Notifications (Very Short). , work in progress, July 1, 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. [ISO-10175] ISO/IEC 10175 Document Printing Application (DPA), June 1996. Bergman, Hastings, Herriot, Moore 12