Internet Printing Protocol (IPP): The 'ippget' Delivery Method for Event Notifications
updates
- rfc-2911 — Internet Printing Protocol/1.1: Model and Semantics
Extracted elements (28)
The Event Life minimum value of 15 seconds is designed to allow a client to create a Per-Job Subscription and then perform Get-Notifications within that window without missing events. 60 seconds is recommended to align with PWG Job Monitoring MIB persistence values.
The 'ippget' Delivery Method is described as having aspects of both a pull and push method: the Notification Recipient initiates the connection, but in Event Wait Mode the Printer proactively sends Event Notifications over that connection as they occur, without the Printer needing to initiate a new connection.
Proxy servers may delay Event Notifications or cause timeouts during Event Wait Mode; clients MUST be prepared to re-issue Get-Notifications when timeouts occur. If a Notification Recipient fails to receive a response, it can re-request the same Event Notifications (subject to Event Life expiry).
A Printer MUST support the Get-Notifications operation, MUST accept the request in any printer state, and MUST remain in the same state with the same 'printer-state-reasons' values after performing the operation.
Each Event Notification Attributes Group in the Get-Notifications response MUST contain all attributes specified in RFC 3995 section 9.1, including notify-subscription-id, notify-printer-uri, notify-subscribed-event, printer-up-time, notify-sequence-number, notify-charset, notify-natural-language, notify-user-data, and notify-text.
Event Notification groups in the Get-Notifications response MUST be ordered in ascending time stamp (and sequence number) order for each Subscription object, following the Event Notification Ordering requirements in RFC 3995 section 9.
If a Printer supports the 'ippget' Delivery Method, it MUST keep 'completed', 'canceled', or 'aborted' Job objects in Job Retention and/or Job History phases for at least as long as the value of 'ippget-event-life'.
If the Notification Recipient did not request Event Wait Mode, the Printer MUST immediately return all held Event Notifications and MUST return the 'notify-get-interval' operation attribute indicating when the client SHOULD repeat the Get-Notifications request.
IPP Clients MUST convert 'ipp' URLs for Get-Notifications operations to their corresponding 'http' URL forms for use in the HTTP layer, according to RFC 2910 section 5.
Printers MUST listen for IPP Get-Notifications operation requests on IANA-assigned well-known port 631 unless explicitly configured otherwise, and SHOULD NOT listen on any other port unless explicitly configured.
The authenticated user performing Get-Notifications MUST be (1) the owner of each identified Subscription Object, (2) an operator or administrator of the Printer, or (3) otherwise authorized by the Printer's security policy; otherwise the Printer MUST reject the operation with 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized'.
The 'ippget' Delivery Method is REQUIRED for all clients and Printers that support RFC 3995. If a Printer supports IPP Notifications, it MUST support the 'ippget' Delivery Method as one of its Delivery Methods.
When an Event occurs, the Printer MUST generate an Event Notification, MUST assign it the Event Life, and MUST hold the Event Notification for its assigned Event Life.
When the Printer terminates Event Wait Mode, it MUST return the 'notify-get-interval' operation attribute. The Notification Recipient MUST accept this response and MUST disconnect; if it does not disconnect, the Printer SHOULD do so.
The Get-Notifications request requires the 'notify-subscription-ids' (1setOf integer(1:MAX)) operation attribute identifying one or more Subscription objects. The client MUST supply this attribute with at least one value, and the Printer MUST support it with multiple values.
The 'ippget-event-life' (integer(15:MAX)) Printer Description attribute specifies the number of seconds after an Event occurs during which the Printer will return that Event in a Get-Notifications response. The value MUST be 15 or more; 60 seconds is RECOMMENDED.
The 'notify-get-interval' (integer(0:MAX)) response operation attribute specifies the number of seconds the Notification Recipient SHOULD wait before reissuing Get-Notifications. Its value MUST be at least as large as the Printer's 'ippget-event-life' attribute value.
The 'notify-sequence-numbers' (1setOf integer(1:MAX)) operation attribute specifies the lowest Event Notification sequence number values for each identified Subscription object. The Printer MUST NOT return Event Notifications with lower sequence numbers for the corresponding Subscription object.
The 'notify-wait' (boolean) operation attribute indicates whether the Notification Recipient requests Event Wait Mode. If 'true', the Printer keeps the connection open and sends Event Notifications as they occur; if 'false' or omitted, no Event Wait Mode is requested.
The 'printer-up-time' (integer(1:MAX)) attribute MUST be returned in every Get-Notifications response, reflecting the Printer's up-time at the moment the response is sent, allowing the Notification Recipient to determine when each Event Notification occurred relative to the response time.
The 'successful-ok-events-complete' status code (0x0007) indicates that the Get-Notifications response is the last response for a Subscription object. It is returned when the Subscription Object is canceled, deleted, lease expires, or the 'job-completed' event occurs for a Per-Job Subscription.
This document registers the following IANA IPP items: the 'ippget-event-life' Printer Description attribute (integer(15:MAX)); the 'ippget' keyword value for 'notify-pull-method' and 'notify-pull-method-supported'; operation-id 0x001C (Get-Notifications); and status code 'successful-ok-events-complete' (0x0007).
A client subscribing to a Per-Printer Subscription for job events may receive unwanted events if many jobs are started and canceled by others; clients should prefer Per-Job Subscriptions to limit event scope to their own jobs.
The 'ippget' Delivery Method leverages the same security mechanisms as IPP/1.1 (client authentication, server authentication, operation privacy via TLS) without adding new mechanisms. The access control model mirrors the Get-Job-Attributes operation.
Unlike Push Delivery Methods, the Pull Delivery Method eliminates the risk of spam notifications because the Notification Recipient initiates all Get-Notifications operations. Clients in Event Wait Mode can close the connection at any time to stop receiving notifications.
Event Wait Mode is entered when the client sends 'notify-wait' = true and the Printer honors it; the Printer remains in Event Wait Mode (returning events as they occur) until it sends 'notify-get-interval' (leaving mode) or closes the connection. The Notification Recipient terminates Event Wait Mode by closing the connection or sending a subsequent Get-Notifications with 'notify-wait' = false.
In a Get-Notifications response, each Event Notification Attributes Group MUST start with an 'event-notification-attributes-tag' (tag value 0x07) and end with an 'end-of-attributes-tag'. For Event Wait Mode, multipart/related MIME is used to separate multiple responses over time for a single request.
In Event Wait Mode, the Printer MUST return the response as an application/ipp part inside a multipart/related MIME media type; each subsequent Event Notification is returned as an additional application/ipp part under the same multipart/related type.