Subject: [IPP] IPP JPS3 - "printer-supply[-description]" encodings

From: Ira McDonald <[email-masked]>
Date: Mon, 28 Mar 2011 22:55:24 -0400

Hi folks,                                         Monday (28 March 2011)

Below are proposed new JPS3 sections for the IPP attribute mapping of
prtMarkerSuppliesTable and prtMarkerColorantTable (flattened into one
table just like we did in the earlier DMTF CIM Print mapping).

Choices for IPP "printer-supply" element datatypes (String or Integer)
follow the same logic as we used in "printer-alert" in PWG 5100.9
(i.e., enumerations map to the equivalant *labels* from the textual
conventions, for human readability).

Comments?

Cheers,
- Ira

------------------------------------------------------------------------

5.5.21 printer-supply (1setOf octetString(MAX))

The RECOMMENDED "printer-supply" Printer attribute provides current
supply details mapped from the SNMP prtMarkerSuppliesTable and
prtMarkerColorantTable defined in IETF Printer MIB v2 [RFC3805].

5.5.21.1 Keywords for printer-supply

The table below defines the IPP datatypes and keywords for encoding
"printer-supply" from all of the machine-readable (non-localized)
columnar objects in prtMarkerSuppliesTable and prtMarkerColorantTable
[RFC3805].

Notes:

(1) prtMarkerSuppliesIndex is RECOMMENDED in "printer-supply"
in order to aid in correlation.

(2) prtMarkerSuppliesMarkerIndex is OPTIONAL in "printer-supply"
because most Printers don't have multiple markers.

(3) prtMarkerSuppliesColorantIndex is omitted in "printer-supply"
because it is redundant with prtMarkerColorantIndex for the rows that
include colorant information.

                Table 6 - Keywords for printer-supply

SNMP Supply Object      IPP Datatype    IPP Keyword         Conformance
------------------      ------------    -----------         -----------
prtMarkerSupplies...
Index (note 1)          Integer         index               RECOMMENDED
MarkerIndex (note 2)    Integer         markerindex         OPTIONAL
ColorantIndex (note 3)  Integer         ---                 ---
Class                   String          class               RECOMMENDED
Type                    String          type                REQUIRED
SupplyUnit              String          unit                RECOMMENDED
MaxCapacity             Integer         maxcapacity         RECOMMENDED
Level                   Integer         level               REQUIRED

prtMarkerColorant...
Index                   Integer         colorantindex       OPTIONAL
Role                    String          colorantrole        OPTIONAL
Value                   String          colorantname        OPTIONAL
Tonality                Integer         coloranttonality    OPTIONAL

5.5.21.2 Encoding of printer-supply

Values of "printer-supply" MUST be encoded using a visible subset of the
[US-ASCII] charset.  Control codes (0x00 to 0x1F and 0x7F) MUST NOT be
used.  The ABNF [RFC5234] below defines the standard encoding in
"printer-supply" for all the machine-readable (non-localized) columnar
objects in prtMarkerSuppliesTable and prtMarkerColorantTable [RFC3805].

printer-supply      = supply-type ";" supply-level *[";" supply-element]
    ; set of supply elements encoded into one value

supply-type         = "code" "=" 1*ALPHA
    ; enumerated value as an alpha string (e.g., 'toner') of
    ; prtMarkerSuppliesType in [RFC3805] mapped indirectly from
    ; the *label* in PrtMarkerSuppliesTypeTC in [IANAPRT]

supply-level        = "level" "=" 1*[DIGIT / "-"]
    ; integer value as a numeric string mapped directly from
    ; prtMarkerSuppliesLevel in [RFC3805]

supply-element      = supply-index /
                      marker-index /
                      supply-class /
                      supply-unit /
                      supply-max-capacity /
                      colorant-index /
                      colorant-role /
                      colorant-name /
                      colorant-tonality

supply-index        = "index" "=" 1*DIGIT
    ; integer value as a numeric string mapped directly from
    ; prtMarkerSuppliesIndex in [RFC3805]

marker-index        = "markerindex" "=" 1*DIGIT
    ; integer value as a numeric string mapped directly from
    ; prtMarkerSuppliesMarkerIndex in [RFC3805]

supply-class        = "class" "=" 1*ALPHA
    ; enumerated value as an alpha string (e.g., 'other') of
    ; prtMarkerSuppliesClass in [RFC3805] mapped indirectly from
    ; the *label* in PrtMarkerSuppliesClassTC in [RFC3805]

supply-unit         = "unit" "=" 1*ALPHA
    ; enumerated value as an alpha string (e.g., 'other') of
    ; prtMarkerSuppliesSupplUnit in [RFC3805] mapped indirectly from
    ; the *label* in PrtMarkerSuppliesSupplyUnitTC in [RFC3805]

supply-max-capacity = "maxcapacity" "=" 1*[DIGIT / "-"]
    ; integer value as a numeric string mapped directly from
    ; prtMarkerSuppliesMaxCapacity in [RFC3805]

colorant-index      = "colorantindex" "=" 1*DIGIT
    ; integer value as a numeric string mapped directly from
    ; prtMarkerColorantIndex in [RFC3805]

colorant-role       = "colorantrole" "=" 1*ALPHA
    ; enumerated value as an alpha string (e.g., 'other') of
    ; prtMarkerColorantRole in [RFC3805] mapped indirectly from
    ; the *label* in PrtMarkerColorantRoleTC in [RFC3805]

colorant-name       = "colorantname" "=" 1*ALPHA
    ; string value as an alpha string mapped directly from
    ; prtMarkerColorantValue in [RFC3805]

colorant-tonality   = "coloranttonality" "=" 1*DIGIT
    ; integer value as a numeric string mapped directly from
    ; prtMarkerColorantTonality in [RFC3805]

5.5.21.3 Example of printer-supply

The following example shows two rows of the machine-readable
(non-localized) columnar objects from prtMarkerSuppliesTable and
prtMarkerColorantTable encoded into corresponding values of
"printer-supply".

Note:  Line breaks are shown below for readability of this example.
Line breaks MUST NOT be encoded into actual values of "printer-supply".

printer-supply[1] =
    type=toner;level=75;index=1;markerindex=1;
    class=supplyThatIsConsumed;unit=percent;maxcapacity=100;
    colorantindex=4;colorantrole=process;colorantname=cyan;
    coloranttonality=128

printer-supply[2] =
    type=toner;level=72;index=2;markerindex=1;
    class=supplyThatIsConsumed;unit=percent;maxcapacity=100;
    colorantindex=4;colorantrole=process;colorantname=magenta;
    coloranttonality=128

5.5.22 printer-supply-description (1setOf text(MAX))

The RECOMMENDED "printer-supply-description" Printer attribute provides
current supply descriptions mapped from the SNMP
prtMarkerSuppliesDescription object in the prtMarkerSuppliesTable
defined in IETF Printer MIB v2 [RFC3805].

5.5.22.1 Encoding of printer-supply-description

Values of the "printer-supply-description" attribute MUST be mapped from
the corresponding human-readable (localized) values of
prtMarkerSuppliesDescription, exactly as follows:

(a) Each value of prtMarkerSuppliesDescription MUST be converted
from the charset [RFC3808] specified by prtGeneralCurrentLocalization
and prtLocalizationCharacterSet into the charset specified by
"charset-configured" and then copied into a text value of
"printer-supply-description";

(b) Each value of "printer-supply-description" MUST be tagged with the
natural language [RFC5646] specified by prtGeneralCurrentLocalization,
prtLocalizationLanguage, and prtLocalizationCountry;

(c) Each value of "printer-supply-description" MUST be in the same order
as the corresponding value of "printer-supply" (i.e., strictly ascending
order according to prtMarkerSuppliesIndex).

5.5.22.2 Example of printer-supply-description

The following example shows two instances of the human-readable
(localized) columnar object prtMarkerSuppliesDescription in the
prtMarkerSuppliesTable encoded into corresponding values of
"printer-supply-description".

printer-supply-description[1] =
    Cyan Toner Cartridge S/N:CRUM-09111141087

printer-supply-description[2] =
    Magenta Toner Cartridge S/N:CRUM-08561031091

------------------------------------------------------------------------

-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.

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

---

From: Michael Sweet <[email-masked]>
Date: Tue, 29 Mar 2011 14:19:22 -0700

Ira,

I'm working on getting this text into a new rev of the JPS3 specification. Some comments below...

On Mar 28, 2011, at 7:55 PM, Ira McDonald wrote:
> ...

Do we even need the colorantIndex from the prtMarkerColorant table? Seems like unnecessary information that will never get used in this composite view of the two tables...

Same for Index - we implicitly already have it (1setOf is ordered) so why include it?

MaxCapacity should be REQUIRED since otherwise how do you interpret Level?

Finally, I would make at least the colorant Value conditionally required, otherwise the data can't be represented properly in UI.

> SNMP Supply Object      IPP Datatype    IPP Keyword         Conformance

__________________________________________________
Michael Sweet, Senior Printing System Engineer, PWG Chair

---

From: "Zehler, Peter" <[email-masked]>
Date: Wed, 30 Mar 2011 04:49:46 -0700

It is my understanding that 1SetOf is unordered.  But rfc2911 states
"Sets are normally unordered.  However each attribute description of
this type may specify that the values MUST be in a certain order for
that attribute."  I assume that the description will detail the ordering
including the mapping to the Printer MIB and any ordering relationship
between attributes.

Peter Zehler

Xerox Research Center Webster
Email: [email-masked]
Voice: (585) 265-8755
FAX: (585) 265-7441
US Mail: Peter Zehler
Xerox Corp.
800 Phillips Rd.
M/S 128-25E
Webster NY, 14580-9701 

From: [email-masked] [mailto:[email-masked]] On Behalf Of
Michael Sweet
Sent: Tuesday, March 29, 2011 5:19 PM
To: Ira McDonald
Cc: [email-masked]
Subject: [IPP] Re: IPP JPS3 - "printer-supply[-description]" encodings

Ira,

I'm working on getting this text into a new rev of the JPS3
specification. Some comments below...

	...

	(3) prtMarkerSuppliesColorantIndex is omitted in
"printer-supply"
	because it is redundant with prtMarkerColorantIndex for the rows
that
	include colorant information.

Do we even need the colorantIndex from the prtMarkerColorant table?
Seems like unnecessary information that will never get used in this
composite view of the two tables...

Same for Index - we implicitly already have it (1setOf is ordered) so
why include it?

MaxCapacity should be REQUIRED since otherwise how do you interpret
Level?

Finally, I would make at least the colorant Value conditionally
required, otherwise the data can't be represented properly in UI.

	
	SNMP Supply Object      IPP Datatype    IPP Keyword
Conformance
	------------------      ------------    -----------
-----------
	prtMarkerSupplies...
	Index (note 1)          Integer         index
RECOMMENDED
	MarkerIndex (note 2)    Integer         markerindex
OPTIONAL
	ColorantIndex (note 3)  Integer         ---                 ---
	Class                   String          class
RECOMMENDED
	Type                    String          type
REQUIRED
	SupplyUnit              String          unit
RECOMMENDED
	MaxCapacity             Integer         maxcapacity
RECOMMENDED
	Level                   Integer         level
REQUIRED
	
	prtMarkerColorant...
	Index                   Integer         colorantindex
OPTIONAL
	Role                    String          colorantrole
OPTIONAL
	Value                   String          colorantname
OPTIONAL
	Tonality                Integer         coloranttonality
OPTIONAL

-- 
This message has been scanned for viruses and 
dangerous content by MailScanner <http://www.mailscanner.info/> , and is

believed to be clean.

---

From: Michael Sweet <[email-masked]>
Date: Wed, 30 Mar 2011 07:41:11 -0700

Pete,

You are correct, and I *think* we have this wording in the current PSX (will check - if not that is an important oversight!). Will make sure that I include the appropriate verbiage in the JPS3 spec...

Thanks!

On Mar 30, 2011, at 4:49 AM, Zehler, Peter wrote:

> It is my understanding that 1SetOf is unordered.  But rfc2911 states “Sets are normally unordered.  However each attribute description of this type may specify that the values MUST be in a certain order for that attribute.”  I assume that the description will detail the ordering including the mapping to the Printer MIB and any ordering relationship between attributes.
>  
>  
> Peter Zehler
> 
> From: [email-masked] [mailto:[email-masked]] On Behalf Of Michael Sweet

________________________________________________________________________
Michael Sweet, Senior Printing System Engineer, PWG Chair

---

From: Michael Sweet <[email-masked]>
Date: Wed, 30 Mar 2011 08:17:17 -0700

Pete,

I checked 5100.9 and we aren't saying anything about the ordering of printer-alert and printer-alert-description. Seems like we'll need to do an errata for that at some point.

Ira, I'll add the necessary verbiage to the text you supplied and post it in the version of JPS3 for the F2F...