Subject: [IPP] Outline of IPP Resource Object for System Service Spec

From: Michael Sweet <[email-masked]>
Date: Wed, 24 Aug 2016 18:07:39 -0400

All,

The following outline summarizes how I see the IPP Resource object working in the System Service specification. Feedback welcome, and we can discuss this at the next regular IPP conference call (Sept 19).

TL;DR summary: Resource states are 'pending', 'pending-install', 'installed', 'aborted', and 'canceled'. No more "resource-category" attribute. State reasons and status codes for resource format and security errors.

........

IPP Resource Object

IPP Resource objects contain metadata and associated firmware, software, templates, and other static data files.  Resource objects have a simple life cycle: creation, installation, history, and deletion.  Resource objects can be listed (Get-Resources) or queried (Get-Resource-Attributes) until they are deleted by the System.

           Table N - IPP Resource Object Operations and Life Cycle

    Operation                resource-state         resource-state-reasons
    -----------------------  ---------------------  ----------------------
    Create-Resource          'pending' (3)          'resource-incomplete'

    Send-Resource-Data       'pending' (3)          'none'
                                   OR
                             'aborted' (8)          'resource-xxx-error'

    Install-Resource         'pending-install' (4)  'none'
                                   OR
                             'installed' (5)        'none'
                                   OR
                             'aborted' (8)          'resource-xxx-error'

    Cancel-Resource          'canceled' (7)         'none'
                                   OR
                             'installed' (5)        'none'

    Get-Resources            All States             All Reasons
    Get-Resource-Attributes  All States             All Reasons

Resource Creation Phase

Resources are created using the Create-Resource operation which creates the object and the Send-Resource-Data operation which provides the data for the resource. The state during creation is 'pending' (3). The state after creation is either 'pending' or 'aborted' (8) if the resource data contains errors or if the Send-Resource-Data operation is not done quickly enough.

Resource Installation Phase

Resources are installed using the Install-Resource operation. The state after installation is either 'pending-install' (4) if the Resource data must be installed after a reboot, 'installed' (5) if the Resource data can be installed immediately, or 'aborted' if the Resource data contains errors and cannot be installed.

Resource History Phase

Resources in the history phase of their life cycle are in the 'canceled' or 'aborted' states.

Resources are aborted by the System when it determines the Resource data contains errors, is missing, or has been replaced.

Resources are canceled using the Cancel-Resource operation. That state after cancellation is 'canceled' (7) unless the Resource cannot be canceled, such as running firmware that must be replaced before it can be canceled.

Systems delete Resource data when placing a Resource in the 'canceled' or 'aborted' state. Historical resources MUST be retained in these states for at least 300 seconds before deletion of the Resource object by the System service.

Resource Status Attributes

    date-time-at-creation (dateTime)
    date-time-at-history (dateTime)
    date-time-at-installed (dateTime)
    resource-data-uri (uri | no-value)
    resource-format (mimeMediaType)
    resource-id (integer(1:MAX))
    resource-job-id (integer(1:MAX))
    resource-k-octets (integer(0:MAX))
    resource-printer-id (integer(1:MAX))
    resource-state (type1 enum)
    resource-state-message (text(MAX))
    resource-state-reasons (1setOf type2 keyword)
    resource-string-version (text(MAX))
    resource-type (type2 keyword)
    resource-uuid (uri)
    time-at-creation (integer(MIN:MAX))
    time-at-history (integer(MIN:MAX))
    time-at-installed (integer(MIN:MAX))

Resource Description Attributes:

    resource-info (name(MAX))
    resource-name (name(MAX))
    resource-owner-col (collection)
      owner-uri (uri)
      owner-vcard (1setOf text(MAX))

"resource-state" values:

    - 3 ('pending'): state after creation but before installation
    - 4 ('pending-install'): state after install for resources that require a reboot
    - 5 ('installed'): state when a resource is installed
    - 7 ('canceled'): state when a resource has been canceled by Cancel-Resource operation
    - 8 ('aborted'): state when a resource has been canceled by System service (bad resource, etc.)

"resource-state-reasons" values:

    - 'none': No additional state.
    - 'resource-format-error': The Resource data contains format errors.
    - 'resource-incomplete': The Resource object has been created but no data has been sent.
    - 'resource-security-error': The Resource data's digital signature or other security features could not be verified.
    - 'resource-timeout': The Resource was not installed within the multiple-operation-time-out period.

"resource-type" values:

    - 'document': Template for creating Document object.
    - 'firmware': Executable firmware (reboot generally required).
    - 'font': Static font.
    - 'icc-profile': Static ICC profile.
    - 'image': Static image (icon, logo, etc.)
    - 'job': Template for creating Job object.
    - 'software': Executable software/application (reboot generally not required).
    - 'strings': Static message catalog (strings file).

"status-code" values (and operations that can return them):

    - 'successful-ok': All
    - 'client-error-bad-request': All
    - 'client-error-forbidden': All
    - 'client-error-not-authenticated': All
    - 'client-error-not-authorized': All
    - 'client-error-not-found': Cancel-Resource
    - 'client-error-request-entity-too-large': Send-Resource-Data
    - 'client-error-document-format-not-supported': Send-Resource-Data
    - 'client-error-attributes-or-values-not-supported': Create-Resource
    - 'client-error-charset-not-supported': All
    - 'client-error-conflicting-attributes': Create-Resource
    - 'client-error-document-security-error': Send-Resource-Data, Install-Resource
    - 'server-error-internal-error': All
    - 'server-error-busy': Cancel-Resource, Create-Resource, Send-Resource-Data
    - (NEW) 'server-error-too-many-resources': Create-Resource

_________________________________________________________
Michael Sweet, Senior Printing System Engineer

_______________________________________________
ipp mailing list
[email-masked]
https://www.pwg.org/mailman/listinfo/ipp

---

From: Ira McDonald <[email-masked]>
Date: Wed, 31 Aug 2016 17:50:31 -0400

Hi Mike,

Apologies for late response.  Been a busy week.

I like most all of this except for two state names, because they're
obscure.  The Job state 'pending' has fuzzy applicability here.

I suggest states/state reasons:

'created' - result of Create-Resource

'uploaded' - result of Send-Resource-Data, except when Resource
stays 'created' w/ state reason 'resource-incoming' (like job-incoming
in RFC 2911)

'installed' - result of Install-Resource, except when Resource
stays 'uploaded' w/ state reason 'resource-installed'

'canceled' - result of Cancel-Resource, except when Resource
stays 'created/loaded/installed' w/ state reason 'resource-canceled'

'pending-install' meaning "pending but NOT installed" is not symmetric
with 'pending-held' meaning "pending AND held"

Comments?

Cheers,
- Ira

PS - Reasoning behind the 'uploaded' state name is potential
first class Admin operation Send-Resource-URI (for local domain
authenticated Resource upload by reference rather than value).

Ira McDonald (Musician / Software Architect)
Co-Chair - TCG Trusted Mobility Solutions WG
Chair - Linux Foundation Open Printing WG
Secretary - IEEE-ISTO Printer Working Group
Co-Chair - IEEE-ISTO PWG Internet Printing Protocol WG
IETF Designated Expert - IPP & Printer MIB
Blue Roof Music / High North Inc
http://sites.google.com/site/blueroofmusic
http://sites.google.com/site/highnorthinc
mailto: [email-masked]
Jan-April: 579 Park Place  Saline, MI  48176  734-944-0094
May-Dec: PO Box 221  Grand Marais, MI 49839  906-494-2434

On Wed, Aug 24, 2016 at 6:07 PM, Michael Sweet <[email-masked]> wrote:

> All,
>
> The following outline summarizes how I see the IPP Resource object working
> in the System Service specification. Feedback welcome, and we can discuss
> this at the next regular IPP conference call (Sept 19).
>
> TL;DR summary: Resource states are 'pending', 'pending-install',
> 'installed', 'aborted', and 'canceled'. No more "resource-category"
> attribute. State reasons and status codes for resource format and security
> errors.
>
> ........
>
> IPP Resource Object
>
> IPP Resource objects contain metadata and associated firmware, software,
> templates, and other static data files.  Resource objects have a simple
> life cycle: creation, installation, history, and deletion.  Resource
> objects can be listed (Get-Resources) or queried (Get-Resource-Attributes)
> until they are deleted by the System.
>
>
> Resources are created using the Create-Resource operation which creates
> the object and the Send-Resource-Data operation which provides the data for
> the resource. The state during creation is 'pending' (3). The state after
> creation is either 'pending' or 'aborted' (8) if the resource data contains
> errors or if the Send-Resource-Data operation is not done quickly enough.
>
>
> Resources are installed using the Install-Resource operation. The state
> after installation is either 'pending-install' (4) if the Resource data
> must be installed after a reboot, 'installed' (5) if the Resource data can
> be installed immediately, or 'aborted' if the Resource data contains errors
> and cannot be installed.
>
>
> Resource History Phase
>
> Resources are aborted by the System when it determines the Resource data
> contains errors, is missing, or has been replaced.
>
> Resources are canceled using the Cancel-Resource operation. That state
> after cancellation is 'canceled' (7) unless the Resource cannot be
> canceled, such as running firmware that must be replaced before it can be
> canceled.
>
> Systems delete Resource data when placing a Resource in the 'canceled' or
> 'aborted' state. Historical resources MUST be retained in these states for
> at least 300 seconds before deletion of the Resource object by the System
> service.
>
>
>     - 'resource-security-error': The Resource data's digital signature or
> other security features could not be verified.