雲端裝置說明 (CDD) 是一般概念，大致涵蓋雲端裝置的屬性和功能。CDD 1.0 (GCP 2.0 支援的 CDD 版本) 將以下概念分為五種格式：
- CDD 說明裝置的功能。
- CJT (Cloud 工作票券) 說明瞭裝置支援的指令選項。
- CDS (Cloud Device State) 會描述裝置的完整語意狀態。
- CJS (Cloud 工作狀態) 描述了裝置上工作的語意狀態。
- 本機設定是指使用者可編輯的設定，不會隨著正常使用的裝置變更。
這些格式列於 Google 的 Protobuf 語言中，這些指令是從 Cloud proto 伺服器傳送並傳送，並透過 protobufs 序列化的 JSON 字串進行通訊，這就是本頁的範例。
注意：這些 protobuf 定義中應忽略 optional 關鍵字。上述說明中包含 (required) 的所有欄位均為必填，所有其他欄位則為選填 (或重複)。
雲端裝置說明 – 格式
CDD 格式是用於說明雲端連線裝置 (例如 Google 雲端列印的印表機) 的功能。例如色彩列印、雙重列印或支援多種紙張大小。
注意：Cloud Device 說明已淘汰，但已淘汰，但在 ChromeOS 的擴充功能中並無法與
chrome.printing API 搭配使用。
以下是頂層資料結構 CDD 的 protobuf 定義：
// Description of a cloud-enabled device's capabilities and properties. Also
// known as CDD.
message CloudDeviceDescription {
// Version of the CDD in the form "X.Y" where changes to Y are backwards
// compatible, and changes to X are not (required).
optional string version = 1;
// Section of the CDD that specifically describes printers.
optional PrinterDescriptionSection printer = 101;
// Section of the CDD that specifically describes scanners.
optional ScannerDescriptionSection scanner = 102;
}
XPS 和 PPD 等印表機功能語言是以一般語言指定功能，並使用關鍵字來指定特定功能的部分功能 (例如該功能代表文件的顏色，或應該列印的份數)。CDD 格式會採取不同方法，針對每部裝置功能定義一組自訂的自訂 protobufs。
GCP 提供的網站工具可將 XPS 和 PPD 檔案自動轉換為 CDD，並以視覺化的方式呈現使用者介面 (提供有效的 CDD)。
可以發現 CDD 的主要內容會細分為子區段。這些子區段原本就是印表機和掃描器，我們也許會感受到 CDD 可以代表印表機或掃描器，甚至是兩者的組合：印表機掃描器組合。
注意事項：CDD、CJT 和 CDS 的掃描工具區段 Protobuf 定義會在 GCP 正式發布雲端掃描 API 時公開。
印表機說明區段
本節的 CDD 說明印表機的功能和特色。以下是 protobuf 的定義：
// Section of a CDD that describes the capabilities and physical units of a
// cloud-connected printer.
message PrinterDescriptionSection {
// Content types (sometimes referred to as MIME types) that are supported by
// the printer.
//
// The order of these types determines which content type the document should
// be converted to. For example, if the types are ordered as:
//
// [
// {"content_type": "application/pdf"},
// {"content_type": "image/pwg-raster"}
// ]
//
// Then the document's content type will first be matched to any content type
// in the list. If there is a match, then the document will be sent to the
// printer as is. If there is no match, then the document will be converted to
// a content type which the server supports starting from the first option. In
// this example, if the document is sent as "text/html" and the printer
// supports "application/pdf" and "image/pwg-raster", then the document will
// be converted to "application/pdf" and not "image/pwg-raster", because
// "application/pdf" is declared earlier in this list.
repeated SupportedContentType supported_content_type = 1;
// Printing speeds that the printer can operate at.
optional PrintingSpeed printing_speed = 2;
// PWG raster configuration of the printer. Required if the printer supports
// image/pwg-raster content type, and it should be omitted otherwise.
// This allows a cloud service to understand how to rasterize a document in
// PWG-raster for the printer.
optional PwgRasterConfig pwg_raster_config = 3;
// Physical model of the printer's input trays.
repeated InputTrayUnit input_tray_unit = 4;
// Physical model of the printer's output bins.
repeated OutputBinUnit output_bin_unit = 5;
// Physical model of the printer's markers.
repeated Marker marker = 6;
// Physical model of the printer's covers.
repeated Cover cover = 7;
// Physical model of the printer's media paths.
repeated MediaPath media_path = 8;
// Vendor-provided printer capabilities.
repeated VendorCapability vendor_capability = 101;
// Color printing capabilities of the printer.
optional Color color = 102;
// Duplexing capabilities of the printer.
optional Duplex duplex = 103;
// Page/paper orientation capabilities of the printer.
optional PageOrientation page_orientation = 104;
// Multiple copy capability of the printer.
optional Copies copies = 105;
// Page margins capability of the printer.
optional Margins margins = 106;
// Printing quality or dots-per-inch (DPI) capabilities of the printer.
optional Dpi dpi = 107;
// Page fitting capabilities of the printer.
optional FitToPage fit_to_page = 108;
// Page range selection capability of the printer.
optional PageRange page_range = 109;
// Page or media size capabilities of the printer.
optional MediaSize media_size = 110;
// Paper collation capability of the printer.
optional Collate collate = 111;
// Reverse order printing capability of the printer.
optional ReverseOrder reverse_order = 112;
}
// Property that defines what content types the printer can print natively.
message SupportedContentType {
// Content type (e.g. "image/png" or "application/pdf"). Use */* if your
// printer supports all formats (required).
optional string content_type = 1;
// Minimum supported version of the content type if applicable (e.g. "1.5").
optional string min_version = 2;
// Maximum supported version of the content type if applicable (e.g. "1.5").
optional string max_version = 3;
}
// Property that defines what speeds (in pages per minute) the printer can
// operate at.
message PrintingSpeed {
// Available speed of the printer.
//
// Specify settings that are associated with the given speed. If a setting
// is left unset, then it will be assumed that the speed is independent of
// that setting. For example, the following Option
//
// {
// "speed_ppm": 5.5,
// "color_type": ["STANDARD_MONOCHROME"],
// "media_size_name": ["NA_LETTER", "ISO_A4"]
// }
//
// indicates that the printer prints at 5.5 pages per minute when printing in
// STANDARD_MONOCHROME in either NA_LETTER or ISO_A4 paper sizes.
message Option {
// Speed measured in pages per minute (required).
optional float speed_ppm = 1;
// Types of color settings that operate at this speed.
repeated Color.Type color_type = 2;
// Names of media sizes that operate at this speed.
repeated MediaSize.Name media_size_name = 3;
}
// Speeds that the printer can operate at.
repeated Option option = 1;
}
// Configuration of how printer should receive PWG raster images.
message PwgRasterConfig {
message Resolution {
optional int32 cross_feed_dir = 1; // Horizontal resolution in DPI.
optional int32 feed_dir = 2; // Vertical resolution in DPI.
}
// Resolutions (in DPI) of the pages that the printer supports in PWG-raster
// format. The resolution MUST be supported for every page media supported by
// the printer. (Same as PwgRasterDocumentResolutionSupported PWG-raster
// semantic model element.) This field is strongly recommended, as it helps
// GCP to decide which resolutions are supported by the printer for PWG-raster
// documents if it has to downscale the document to a lower resolution.
//
// This list can be a subset of the full set of resolutions supported by the
// printer (in formats different from PWG-raster, e.g. PDF), but it MUST
// include an NxN DPI resolution where N <= 360 and N evenly divides all
// resolutions supported by the printer. A resolution NxN where N >= 600
// (possibly 600 or 720) is also strongly recommended.
//
// GCP will generate PWG-raster pages not necessarily at the resolution
// reported in the ticket, but the actual DPIs of the page (horizontal and
// vertical) will always perfectly divide the corresponding values reported in
// the ticket.
repeated Resolution document_resolution_supported = 2;
// List of PWG-raster document types (in terms of color space and bits per
// color) supported by the printer. Color printers MUST support SRGB_8 and
// possibly SGRAY_8. Monochrome printers must support either SRGB_8 or
// SGRAY_8. However, any printer that doesn't support SGRAY_8 must be able
// to perform conversion from RGB to grayscale if it receives a PWG-raster
// document in SRGB and the print job ticket specifies monochrome printing.
//
// This field is strongly recommended, and we recommend to include all types
// supported by the printer, as GCP may start serving more document types in
// the future.
repeated PwgDocumentTypeSupported document_type_supported = 3;
// Describes which transformation needs to be applied to back pages in
// duplexing in order to have them printed properly.
// The value mainly depends on how duplexing works on the printer, and the
// actual effect depends on which duplexing is specified in the ticket.
enum DocumentSheetBack {
// No special treatment for back pages (same as front page).
NORMAL = 0;
// Back pages are rotated 180 degrees if the document is portrait
// (TwoSidedLongEdge duplexing).
ROTATED = 1;
// Back pages are rotated 180 degrees if the document is landscape
// (TwoSidedShortEdge duplexing, opposite of ROTATED).
MANUAL_TUMBLE = 2;
// Page is flipped upside-down if portrait (TwoSidedLongEdge duplexing),
// left-right if landscape (TwoSidedShortEdge duplexing).
FLIPPED = 3;
}
// Same as PwgRasterDocumentSheetBack PWG-raster semantic model element.
// Default value is ROTATED.
optional DocumentSheetBack document_sheet_back = 4 [default = ROTATED];
// Instructs GCP that the printer wants to print pages from the last to the
// first. In that case GCP will stream PWG-raster pages in that order.
optional bool reverse_order_streaming = 5;
// Instructs GCP that the printer prefers receiving pages rotated 180 degrees.
// This rotation is in addition to possible additional rotations of even pages
// based on document_sheet_back in case of duplexing.
optional bool rotate_all_pages = 6;
// PWG-raster document types (in terms of color space and bits per color).
// This list is based on the PWG-raster specs of March 14, 2012, and it
// will be extended without notice if new types are added to newer versions
// of the specs. If a new type is not accepted by GCP capability parser please
// inform the GCP team. (This doesn't mean that GCP will start sending
// documents of the new kind.)
//
// The string names are identical to the keyword attribute values in
// PWG-raster documentation, except they are uppercase, and dashes are
// replaced by underscores.
enum PwgDocumentTypeSupported {
BLACK_1 = 1;
SGRAY_1 = 2;
ADOBE_RGB_8 = 3;
BLACK_8 = 4;
CMYK_8 = 5;
DEVICE1_8 = 6;
DEVICE2_8 = 7;
DEVICE3_8 = 8;
DEVICE4_8 = 9;
DEVICE5_8 = 10;
DEVICE6_8 = 11;
DEVICE7_8 = 12;
DEVICE8_8 = 13;
DEVICE9_8 = 14;
DEVICE10_8 = 15;
DEVICE11_8 = 16;
DEVICE12_8 = 17;
DEVICE13_8 = 18;
DEVICE14_8 = 19;
DEVICE15_8 = 20;
RGB_8 = 21;
SGRAY_8 = 22;
SRGB_8 = 23;
ADOBE_RGB_16 = 24;
BLACK_16 = 25;
CMYK_16 = 26;
DEVICE1_16 = 27;
DEVICE2_16 = 28;
DEVICE3_16 = 29;
DEVICE4_16 = 30;
DEVICE5_16 = 31;
DEVICE6_16 = 32;
DEVICE7_16 = 33;
DEVICE8_16 = 34;
DEVICE9_16 = 35;
DEVICE10_16 = 36;
DEVICE11_16 = 37;
DEVICE12_16 = 38;
DEVICE13_16 = 39;
DEVICE14_16 = 40;
DEVICE15_16 = 41;
RGB_16 = 42;
SGRAY_16 = 43;
SRGB_16 = 44;
}
// [Deprecated: Please use the other fields of PwgRasterConfig.]
// Transformation to apply to pages during PWG rasterization.
message Transformation {
// Types of transformation operations to apply.
enum Operation {
// Rotate pages 180 degrees.
ROTATE_180 = 0;
// Flip pages along the long edge of the paper.
FLIP_ON_LONG_EDGE = 1;
// Flip pages along the short edge of the paper.
FLIP_ON_SHORT_EDGE = 2;
}
// Selectors of which pages to apply the transformation to.
enum Operand {
// Apply transformation to all pages.
ALL_PAGES = 0;
// Apply transformation to even pages only when duplexing (deprecated,
// instead use EVEN_PAGES and specify appropriate duplex types).
ONLY_DUPLEXED_EVEN_PAGES = 1;
// Apply transformation to odd pages only when duplexing (deprecated,
// instead use ODD_PAGES and specify appropriate duplex types).
ONLY_DUPLEXED_ODD_PAGES = 2;
// Apply transformation to even pages.
EVEN_PAGES = 3;
// Apply transformation to odd pages.
ODD_PAGES = 4;
}
// Required.
optional Operation operation = 1;
// Required.
optional Operand operand = 2;
// Duplex types that the transformation applies to. Leave empty if the
// transformation is applicable to all duplex types.
repeated Duplex.Type duplex_type = 3;
}
// [Deprecated and only partially supported. Please use the other fields of
// PwgRasterConfig.
// Out of all possible transformations GCP will only support rotating all
// pages, but for that we strongly recommend using the rotate_all_pages
// boolean field instead.]
// What transformations to apply to pages in the print job.
repeated Transformation transformation = 1;
}
// Physical model of a printer input tray.
message InputTrayUnit {
// Enumeration of input tray types.
enum Type {
CUSTOM = 0;
INPUT_TRAY = 1;
BYPASS_TRAY = 2;
MANUAL_FEED_TRAY = 3;
LCT = 4; // Large capacity tray.
ENVELOPE_TRAY = 5;
ROLL = 6;
}
// Vendor-provided ID of the input tray (required).
optional string vendor_id = 1;
// Type of input tray (required).
optional Type type = 2;
// Index of the input tray.
optional int64 index = 3;
// Non-localized custom display name of the input tray.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set if
// the tray's type is CUSTOM.
optional string custom_display_name = 4;
// Translations of custom display name of the input tray.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 5;
}
// Physical model of a printer output bin.
message OutputBinUnit {
// Enumeration of output bin types.
enum Type {
CUSTOM = 0;
OUTPUT_BIN = 1;
MAILBOX = 2;
STACKER = 3;
}
// Vendor-provided ID of the output bin (required).
optional string vendor_id = 1;
// Type of output bin (required).
optional Type type = 2;
// Index of the output bin.
optional int64 index = 3;
// Non-localized custom display name of the output bin.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set if
// the bin's type is CUSTOM.
optional string custom_display_name = 4;
// Translations of custom display name of the output bin.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 5;
}
// Physical model of a printer marker.
message Marker {
// Enumeration of types of printer markers.
enum Type {
CUSTOM = 0;
TONER = 1;
INK = 2;
STAPLES = 3;
}
// Message that describes the color of a marker.
message Color {
// Enumeration of color types of the printer marker.
enum Type {
CUSTOM = 0;
BLACK = 1;
COLOR = 2;
CYAN = 3;
MAGENTA = 4;
YELLOW = 5;
LIGHT_CYAN = 6;
LIGHT_MAGENTA = 7;
GRAY = 8;
LIGHT_GRAY = 9;
PIGMENT_BLACK = 10;
MATTE_BLACK = 11;
PHOTO_CYAN = 12;
PHOTO_MAGENTA = 13;
PHOTO_YELLOW = 14;
PHOTO_GRAY = 15;
RED = 16;
GREEN = 17;
BLUE = 18;
}
// Required.
optional Type type = 1;
// Non-localized custom display name of the color.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set
// if the color's type is CUSTOM.
optional string custom_display_name = 2;
// Translations of custom display name of the color.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 3;
}
// Vendor-provided ID of the marker (required).
optional string vendor_id = 1;
// Type of marker (required).
optional Type type = 2;
// Color of the marker. Only needed if marker type is INK or TONER.
optional Color color = 3;
// Non-localized custom display name of the marker.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set
// if the marker's type is CUSTOM.
optional string custom_display_name = 4;
// Translations of custom display name of the marker.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 5;
}
// Physical model of a printer cover.
message Cover {
// Enumeration of cover types.
enum Type {
CUSTOM = 0;
DOOR = 1;
COVER = 2;
}
// Vendor-provided ID of the cover (required).
optional string vendor_id = 1;
// Type of the cover (required).
optional Type type = 2;
// Index of the cover.
optional int64 index = 3;
// Non-localized custom display name of the cover.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set
// if the cover's type is CUSTOM.
optional string custom_display_name = 4;
// Translations of custom display name of the cover.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 5;
}
// Physical model of a media path of a printer. Media paths are the paths
// through which print media flows.
message MediaPath {
// Vendor-provided ID of a media path (required).
optional string vendor_id = 1;
}
注意：顯示印表機 CDD 內含的輸入匣、輸出容器、標記、封面和媒體路徑的模型。他們「不」代表使用者可設定的列印選項。
// Flexible capability that can represent range-based, selection-based, or
// typed-value-based capabilities.
message VendorCapability {
enum Type {
RANGE = 0;
SELECT = 1;
TYPED_VALUE = 2;
}
// ID of the capability. Used in CJT to associate a ticket item with this
// capability (required).
optional string id = 1;
// Non-localized user-friendly string to represent this capability.
// New CDDs should use display_name_localized instead. It is required that
// either display_name or display_name_localized is set.
optional string display_name = 2;
// Type of this capability (required).
optional Type type = 3;
// Range-based capability definition.
optional RangeCapability range_cap = 4;
// Selection-based capability definition.
optional SelectCapability select_cap = 5;
// Typed-value-based capability definition.
optional TypedValueCapability typed_value_cap = 6;
// Translations of display name of this capability.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString display_name_localized = 7;
}
// Message that stores capability information specific to range-based
// capabilities.
message RangeCapability {
enum ValueType {
FLOAT = 0;
INTEGER = 1;
}
// Data type of the value of the range capability (required).
optional ValueType value_type = 1;
optional string default = 2;
optional string min = 3;
optional string max = 4;
}
// Selection-based device capability. Allows the user to select one or many of
// a set of options.
message SelectCapability {
// A user-selectable option of the vendor capability.
message Option {
// A single string that represents the value of this option. This value
// will be used in the VendorTicketItem.value field (required).
optional string value = 1;
// Non-localized user-friendly string to represent this option.
// New CDDs should use display_name_localized instead. It is required that
// either display_name or display_name_localized is set.
optional string display_name = 2;
// Whether this option is the default option. Only one option should be
// marked as default.
optional bool is_default = 3 [default = false];
// Translations of display name of the option.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString display_name_localized = 4;
}
// List of options available for this capability.
repeated Option option = 1;
}
// Message that stores capability information specific to typed-value-based
// capabilities.
message TypedValueCapability {
enum ValueType {
BOOLEAN = 0;
FLOAT = 1;
INTEGER = 2;
STRING = 3;
}
// Type of data of the typed-value capability (required).
optional ValueType value_type = 1;
// Default value of the typed-value capability.
optional string default = 2;
}
// Capability that defines the color options available on a device.
message Color {
enum Type {
STANDARD_COLOR = 0;
STANDARD_MONOCHROME = 1;
CUSTOM_COLOR = 2;
CUSTOM_MONOCHROME = 3;
AUTO = 4;
}
message Option {
// ID to help vendor identify the color option (required for options of type
// CUSTOM_COLOR and CUSTOM_MONOCHROME).
optional string vendor_id = 1;
// Type of color option used in UIs to differentiate color and non-color
// options (required). Note that there can be any number of options of type
// CUSTOM_COLOR and CUSTOM_MONOCHROME, but there should be at most one
// option of each of the other types.
optional Type type = 2;
// Non-localized user-friendly string that represents this option.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set
// for options of type CUSTOM_COLOR and CUSTOM_MONOCHROME. Options of each
// of the other types will have their display name localized by the server.
optional string custom_display_name = 3;
// Whether this option should be selected by default. Only one option
// should be set as default.
optional bool is_default = 4 [default = false];
// Translations of custom display name of the option.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 5;
}
repeated Option option = 1;
// Whether the capability should always reset to the default option,
// regardless of the last user selected option. Only valid if a default
// option is configured.
optional reset_to_default = 2 [default = false];
}
// Capability that defines the duplexing options available on a device.
message Duplex {
enum Type {
NO_DUPLEX = 0;
LONG_EDGE = 1;
SHORT_EDGE = 2;
}
message Option {
optional Type type = 1 [default = NO_DUPLEX];
optional bool is_default = 2 [default = false];
}
repeated Option option = 1;
// Whether the capability should always reset to the default option,
// regardless of the last user selected option. Only valid if a default
// option is configured.
optional reset_to_default = 2 [default = false];
}
// Capability that defines the page orientation options available on a device.
message PageOrientation {
enum Type {
PORTRAIT = 0;
LANDSCAPE = 1;
AUTO = 2;
}
message Option {
// Type of page orientation (required).
optional Type type = 1;
optional bool is_default = 2 [default = false];
}
repeated Option option = 1;
}
// Capability that defines a default and maximum value for multiple copies on a
// device.
message Copies {
optional int32 default = 1;
optional int32 max = 2;
}
// Capability that defines the margins available on a device (including a custom
// one). Margins are measured in microns.
message Margins {
// Enumerates the set of predefined types of margins. Devices should use these
// types to semantically describe the margins option. This type will be used
// for UI purposes only.
enum Type {
BORDERLESS = 0;
STANDARD = 1;
CUSTOM = 2;
}
message Option {
// Type of margin option (required).
optional Type type = 1;
// Top margin of the page (required).
optional int32 top_microns = 2;
// Right margin of the page (required).
optional int32 right_microns = 3;
// Bottom margin of the page (required).
optional int32 bottom_microns = 4;
// Left margin of the page (required).
optional int32 left_microns = 5;
optional bool is_default = 6 [default = false];
}
repeated Option option = 1;
}
// Capability that defines the 2D image quality levels available on a device.
message Dpi {
message Option {
// Horizontal DPI (required).
optional int32 horizontal_dpi = 1;
// Vertical DPI (required).
optional int32 vertical_dpi = 2;
optional bool is_default = 3 [default = false];
// Non-localized custom display name to override the default display name
// which consists of "{$horizontal_dpi}x{$vertical_dpi} dpi".
// New CDDs should use custom_display_name_localized instead.
optional string custom_display_name = 4;
// Vendor-provided ID for the dpi option. Used to disambiguate dpi options
// that may have the same horizontal and vertical dpi but a different effect
// on the printer.
optional string vendor_id = 5;
// Translations of custom display name of the option, if empty,
// "{$horizontal_dpi}x{$vertical_dpi} dpi" will be used. If not empty, must
// contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 6;
}
repeated Option option = 1;
optional int32 min_horizontal_dpi = 2;
optional int32 max_horizontal_dpi = 3;
optional int32 min_vertical_dpi = 4;
optional int32 max_vertical_dpi = 5;
// Whether the capability should always reset to the default option,
// regardless of the last user selected option. Only valid if a default
// option is configured.
optional reset_to_default = 6 [default = false];
}
// Capability that defines the page fitting options available on a device.
message FitToPage {
// Enumeration of page fitting algorithms. The "page" is defined as the media
// size minus any given margins.
enum Type {
NO_FITTING = 0;
FIT_TO_PAGE = 1;
GROW_TO_PAGE = 2;
SHRINK_TO_PAGE = 3;
FILL_PAGE = 4;
}
message Option {
// Type of fitting algorithm (required).
optional Type type = 1;
optional bool is_default = 2 [default = false];
}
repeated Option option = 1;
}
// Capability that defines a default page-range selection on a device.
message PageRange {
// Interval of pages in the document to print.
message Interval {
// Beginning of the interval (inclusive) (required).
optional int32 start = 1;
// End of the interval (inclusive). If not set, then the interval will
// include all available pages after start.
optional int32 end = 2;
}
repeated Interval default = 1;
}
// Capability that defines the media sizes available on a device.
message MediaSize {
// Enumeration of media size names. This is used for UI purposes.
enum Name {
CUSTOM = 0;
// North American standard sheet media names.
NA_INDEX_3X5 = 100;
NA_PERSONAL = 101;
NA_MONARCH = 102;
NA_NUMBER_9 = 103;
NA_INDEX_4X6 = 104;
NA_NUMBER_10 = 105;
NA_A2 = 106;
NA_NUMBER_11 = 107;
NA_NUMBER_12 = 108;
NA_5X7 = 109;
NA_INDEX_5X8 = 110;
NA_NUMBER_14 = 111;
NA_INVOICE = 112;
NA_INDEX_4X6_EXT = 113;
NA_6X9 = 114;
NA_C5 = 115;
NA_7X9 = 116;
NA_EXECUTIVE = 117;
NA_GOVT_LETTER = 118;
NA_GOVT_LEGAL = 119;
NA_QUARTO = 120;
NA_LETTER = 121;
NA_FANFOLD_EUR = 122;
NA_LETTER_PLUS = 123;
NA_FOOLSCAP = 124;
NA_LEGAL = 125;
NA_SUPER_A = 126;
NA_9X11 = 127;
NA_ARCH_A = 128;
NA_LETTER_EXTRA = 129;
NA_LEGAL_EXTRA = 130;
NA_10X11 = 131;
NA_10X13 = 132;
NA_10X14 = 133;
NA_10X15 = 134;
NA_11X12 = 135;
NA_EDP = 136;
NA_FANFOLD_US = 137;
NA_11X15 = 138;
NA_LEDGER = 139;
NA_EUR_EDP = 140;
NA_ARCH_B = 141;
NA_12X19 = 142;
NA_B_PLUS = 143;
NA_SUPER_B = 144;
NA_C = 145;
NA_ARCH_C = 146;
NA_D = 147;
NA_ARCH_D = 148;
NA_ASME_F = 149;
NA_WIDE_FORMAT = 150;
NA_E = 151;
NA_ARCH_E = 152;
NA_F = 153;
// Chinese standard sheet media size names.
ROC_16K = 200;
ROC_8K = 201;
PRC_32K = 202;
PRC_1 = 203;
PRC_2 = 204;
PRC_4 = 205;
PRC_5 = 206;
PRC_8 = 207;
PRC_6 = 208;
PRC_3 = 209;
PRC_16K = 210;
PRC_7 = 211;
OM_JUURO_KU_KAI = 212;
OM_PA_KAI = 213;
OM_DAI_PA_KAI = 214;
PRC_10 = 215;
// ISO standard sheet media size names.
ISO_A10 = 301;
ISO_A9 = 302;
ISO_A8 = 303;
ISO_A7 = 304;
ISO_A6 = 305;
ISO_A5 = 306;
ISO_A5_EXTRA = 307;
ISO_A4 = 308;
ISO_A4_TAB = 309;
ISO_A4_EXTRA = 310;
ISO_A3 = 311;
ISO_A4X3 = 312;
ISO_A4X4 = 313;
ISO_A4X5 = 314;
ISO_A4X6 = 315;
ISO_A4X7 = 316;
ISO_A4X8 = 317;
ISO_A4X9 = 318;
ISO_A3_EXTRA = 319;
ISO_A2 = 320;
ISO_A3X3 = 321;
ISO_A3X4 = 322;
ISO_A3X5 = 323;
ISO_A3X6 = 324;
ISO_A3X7 = 325;
ISO_A1 = 326;
ISO_A2X3 = 327;
ISO_A2X4 = 328;
ISO_A2X5 = 329;
ISO_A0 = 330;
ISO_A1X3 = 331;
ISO_A1X4 = 332;
ISO_2A0 = 333;
ISO_A0X3 = 334;
ISO_B10 = 335;
ISO_B9 = 336;
ISO_B8 = 337;
ISO_B7 = 338;
ISO_B6 = 339;
ISO_B6C4 = 340;
ISO_B5 = 341;
ISO_B5_EXTRA = 342;
ISO_B4 = 343;
ISO_B3 = 344;
ISO_B2 = 345;
ISO_B1 = 346;
ISO_B0 = 347;
ISO_C10 = 348;
ISO_C9 = 349;
ISO_C8 = 350;
ISO_C7 = 351;
ISO_C7C6 = 352;
ISO_C6 = 353;
ISO_C6C5 = 354;
ISO_C5 = 355;
ISO_C4 = 356;
ISO_C3 = 357;
ISO_C2 = 358;
ISO_C1 = 359;
ISO_C0 = 360;
ISO_DL = 361;
ISO_RA2 = 362;
ISO_SRA2 = 363;
ISO_RA1 = 364;
ISO_SRA1 = 365;
ISO_RA0 = 366;
ISO_SRA0 = 367;
// Japanese standard sheet media size names.
JIS_B10 = 400;
JIS_B9 = 401;
JIS_B8 = 402;
JIS_B7 = 403;
JIS_B6 = 404;
JIS_B5 = 405;
JIS_B4 = 406;
JIS_B3 = 407;
JIS_B2 = 408;
JIS_B1 = 409;
JIS_B0 = 410;
JIS_EXEC = 411;
JPN_CHOU4 = 412;
JPN_HAGAKI = 413;
JPN_YOU4 = 414;
JPN_CHOU2 = 415;
JPN_CHOU3 = 416;
JPN_OUFUKU = 417;
JPN_KAHU = 418;
JPN_KAKU2 = 419;
// Other metric standard sheet media size names.
OM_SMALL_PHOTO = 500;
OM_ITALIAN = 501;
OM_POSTFIX = 502;
OM_LARGE_PHOTO = 503;
OM_FOLIO = 504;
OM_FOLIO_SP = 505;
OM_INVITE = 506;
}
message Option {
optional Name name = 1 [default = CUSTOM];
// Both of the fields ("width_microns" and "height_microns") are required
// if "is_continuous_feed" is set to false. If "is_continuous_feed" is set
// to true only one of these fields is required.
optional int32 width_microns = 2;
optional int32 height_microns = 3;
optional bool is_continuous_feed = 4 [default = false];
optional bool is_default = 5 [default = false];
// Non-localized user-friendly string that represents this option.
// New CDDs should use custom_display_name_localized instead. It is required
// that either custom_display_name or custom_display_name_localized is set
// for options whose "name" field is CUSTOM.
optional string custom_display_name = 6;
// Vendor-provided ID for the media size option. Used to disambiguate media
// sizes that may have the same width and height but a different effect on
// the printer.
optional string vendor_id = 7;
// Translations of custom display name of the option.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString custom_display_name_localized = 8;
// Specifies the bounding box of the imageable area. All 4 fields have to
// be set for the bounding box to be valid. The imageable area is only applicable when
// the feed is not continuous.
optional int32 imageable_area_top_microns = 9;
optional int32 imageable_area_right_microns = 10;
optional int32 imageable_area_bottom_microns = 11;
optional int32 imageable_area_left_microns = 12;
}
repeated Option option = 1;
optional int32 max_width_microns = 2;
optional int32 max_height_microns = 3;
optional int32 min_width_microns = 4;
optional int32 min_height_microns = 5;
// Whether the capability should always reset to the default option,
// regardless of the last user selected option. Only valid if a default
// option is configured.
optional reset_to_default = 6 [default = false];
}
// Capability that defines the default collation setting on a device.
message Collate {
optional bool default = 1 [default = true];
}
// Capability that defines the default reverse-printing-order setting on a
// device.
message ReverseOrder {
optional bool default = 1 [default = false];
}
// A localized human-readable string translated to a specific locale.
// It is recommended to include translations of custom strings only for locales
// for which significant use of the device can be expected. If the translation
// of a custom string for a user's language and country (e.g. ZH_TW) is not
// present, GCP will display the translation for the base language (e.g. ZH).
// If neither translation is present, the translation for EN (which is required
// in every list of localized strings) will be displayed.
message LocalizedString {
// Locale that the string is translated to (required).
optional Locale locale = 1;
// Translated content of the string (required).
optional string value = 2;
enum Locale {
AF = 0;
AM = 1;
AR = 2;
AR_XB = 3;
BG = 4;
BN = 5;
CA = 6;
CS = 7;
CY = 8;
DA = 9;
DE = 10;
DE_AT = 11;
DE_CH = 12;
EL = 13;
EN = 14;
EN_GB = 15;
EN_IE = 16;
EN_IN = 17;
EN_SG = 18;
EN_XA = 19;
EN_XC = 20;
EN_ZA = 21;
ES = 22;
ES_419 = 23;
ES_AR = 24;
ES_BO = 25;
ES_CL = 26;
ES_CO = 27;
ES_CR = 28;
ES_DO = 29;
ES_EC = 30;
ES_GT = 31;
ES_HN = 32;
ES_MX = 33;
ES_NI = 34;
ES_PA = 35;
ES_PE = 36;
ES_PR = 37;
ES_PY = 38;
ES_SV = 39;
ES_US = 40;
ES_UY = 41;
ES_VE = 42;
ET = 43;
EU = 44;
FA = 45;
FI = 46;
FR = 47;
FR_CA = 48;
FR_CH = 49;
GL = 50;
GU = 51;
HE = 52;
HI = 53;
HR = 54;
HU = 55;
HY = 56;
ID = 57;
IN = 58;
IT = 59;
JA = 60;
KA = 61;
KM = 62;
KN = 63;
KO = 64;
LN = 65;
LO = 66;
LT = 67;
LV = 68;
ML = 69;
MO = 70;
MR = 71;
MS = 72;
NB = 73;
NE = 74;
NL = 75;
NO = 76;
PL = 77;
PT = 78;
PT_BR = 79;
PT_PT = 80;
RM = 81;
RO = 82;
RU = 83;
SK = 84;
SL = 85;
SR = 86;
SR_LATN = 87;
SV = 88;
SW = 89;
TA = 90;
TE = 91;
TH = 92;
TL = 93;
TR = 94;
UK = 95;
UR = 96;
VI = 97;
ZH = 98;
ZH_CN = 99;
ZH_HK = 100;
ZH_TW = 101;
ZU = 102;
}
}
CDD 範例
以下範例為 CDD 的外觀，例如「支援」顏色及支援多頁顏色，以及支援原生列印 PDF、JPEG 和純文字且支援多種頁面大小的「一般」印表機印表機：
{
"version": "1.0",
"printer": {
"supported_content_type": [
{"content_type": "application/pdf", "min_version": "1.5"},
{"content_type": "image/jpeg"},
{"content_type": "text/plain"}
],
"input_tray_unit": [
{
"vendor_id": "tray",
"type": "INPUT_TRAY"
}
],
"marker": [
{
"vendor_id": "black",
"type": "INK",
"color": {"type": "BLACK"}
},
{
"vendor_id": "color",
"type": "INK",
"color": {"type": "COLOR"}
}
],
"cover": [
{
"vendor_id": "front",
"type": "CUSTOM",
"custom_display_name": "front cover"
}
],
"vendor_capability": [],
"color": {
"option": [
{"type": "STANDARD_MONOCHROME"},
{"type": "STANDARD_COLOR", "is_default": true},
{
"vendor_id": "ultra-color",
"type": "CUSTOM_COLOR",
"custom_display_name": "Best Color"
}
]
},
"copies": {
"default": 1,
"max": 100
},
"media_size": {
"option": [
{
"name": "ISO_A4",
"width_microns": 210000,
"height_microns": 297000,
"is_default": true
},
{
"name": "NA_LEGAL",
"width_microns": 215900,
"height_microns": 355600
},
{
"name": "NA_LETTER",
"width_microns": 215900,
"height_microns": 279400
}
]
}
}
}
Cloud 工作票券
使用者做出選擇並設定裝置功能來準備列印工作、雲端工作票券或簡稱「支援單」後，藉此引導印表機或其他裝置處理工作。此票券會透過列印用戶端 (例如手機應用程式) 傳送至雲端服務 (例如 GCP)，並與工作資料一起儲存。就像 CDD 一樣，CJT 會細分為裝置專用區段。例如，有關印表機和掃描器的票券項目分段各部。
注意：Cloud Job 票證由 Cloud 淘汰，但在 Chrome OS 的擴充功能中並不能與
chrome.printing API 搭配使用。
以下是 CJT 的 protobuf 定義：
// Description of how a cloud job (e.g. print job, scan job) should be handled
// by the cloud device. Also known as CJT.
message CloudJobTicket {
// Version of the CJT in the form "X.Y" where changes to Y are backwards
// compatible, and changes to X are not (required).
optional string version = 1;
// Section of CJT pertaining to cloud printer ticket items.
optional PrintTicketSection print = 101;
// Section of CJT pertaining to cloud scanner ticket items.
optional ScanTicketSection scan = 102;
}
列印票券部分
CJT 的列印票券部分說明瞭如何透過雲端連線印表機處理列印工作。以下是列印票券專區的 protobuf 定義：
// Section of a CJT which describes how a print job should be handled by a
// cloud-connected printer.
message PrintTicketSection {
repeated VendorTicketItem vendor_ticket_item = 1;
optional ColorTicketItem color = 2;
optional DuplexTicketItem duplex = 3;
optional PageOrientationTicketItem page_orientation = 4;
optional CopiesTicketItem copies = 5;
optional MarginsTicketItem margins = 6;
optional DpiTicketItem dpi = 7;
optional FitToPageTicketItem fit_to_page = 8;
optional PageRangeTicketItem page_range = 9;
optional MediaSizeTicketItem media_size = 10;
optional CollateTicketItem collate = 11;
optional ReverseOrderTicketItem reverse_order = 12;
}
// Ticket item indicating what value for a vendor-specific capability to use.
message VendorTicketItem {
// ID of vendor-specific capability that this ticket item refers to
// (required).
optional string id = 1;
// Value of ticket item (required).
optional string value = 2;
}
// Ticket item indicating which color option to use.
message ColorTicketItem {
// Vendor ID of the color (required if the type is CUSTOM_COLOR or
// CUSTOM_MONOCHROME).
optional string vendor_id = 1;
// Type of the color (required).
optional Color.Type type = 2;
}
// Ticket item indicating which duplexing option to use.
message DuplexTicketItem {
// Type of duplexing (required).
optional Duplex.Type type = 1;
}
// Ticket item indicating which page orientation option to use.
message PageOrientationTicketItem {
// Page orientation type (required).
optional PageOrientation.Type type = 1;
}
// Ticket item indicating how many copies to produce.
message CopiesTicketItem {
// Number of copies to print (required).
optional int32 copies = 1;
}
// Ticket item indicating what margins to use (in microns).
message MarginsTicketItem {
// Top margin of the page (required).
optional int32 top_microns = 1;
// Top margin of the page (required).
optional int32 right_microns = 2;
// Top margin of the page (required).
optional int32 bottom_microns = 3;
// Top margin of the page (required).
optional int32 left_microns = 4;
}
// Ticket item indicating what image resolution to use.
message DpiTicketItem {
// Horizontal DPI to print at (required).
optional int32 horizontal_dpi = 1;
// Vertical DPI to print at (required).
optional int32 vertical_dpi = 2;
// Vendor-provided ID of the Dpi option. Needed to disambiguate Dpi options
// that have the same DPI values, but may have a different effect for the
// printer.
optional string vendor_id = 3;
}
// Ticket item indicating what page-fitting algorithm to use.
message FitToPageTicketItem {
// Type of page fitting (required).
optional FitToPage.Type type = 1;
}
// Ticket item indicating what pages to use.
message PageRangeTicketItem {
repeated PageRange.Interval interval = 1;
}
// Ticket item indicating what media size to use.
message MediaSizeTicketItem {
// Width (in microns) of the media to print to.
optional int32 width_microns = 1;
// Height (in microns) of the media to print to.
optional int32 height_microns = 2;
// Whether the media size selection is continuously fed. If false, both width
// and height must be set. If true, only one need be set.
optional bool is_continuous_feed = 3 [default = false];
// Vendor-provided ID of the MediaSize option. Needed to disambiguate media
// sizes that may have the same width and height, but may have a different
// effect for the printer.
optional string vendor_id = 4;
}
// Ticket item indicating whether to collate pages.
message CollateTicketItem {
// Whether to print collated (required).
optional bool collate = 1;
}
// Ticket item indicating whether to print in reverse.
message ReverseOrderTicketItem {
// Whether to print in reverse (required).
optional bool reverse_order = 1;
}
CJT 範例
以下是針對上述「典型印表機」CDD 範例所產生的票券範例：
{
"version": "1.0",
"print": {
"vendor_ticket_item": [],
"color": {"type": "STANDARD_MONOCHROME"},
"copies": {"copies": 3}
}
}
我們很快就會新增網路工具，將列印為 CJT 格式的列印票券轉換為原生票證格式 (PPD 的 JSON 和 psf:PrintPass 文件 (XP 專屬)。
雲端裝置狀態
裝置的完整狀態會以 CloudDeviceState 訊息表示。本郵件中會介紹不同類型的裝置。多功能裝置可以使用一或多個定義區段。雲端列印功能會擴大支援的裝置類型，日後還會新增更多版面。
// Represents the entire cloud-connected device state.
message CloudDeviceState {
// Supported device states.
enum StateType {
// Device is ready to accept jobs. Self-testing, low power and all other
// states in which the device can start processing newly submitted jobs
// without user intervention should be mapped into this state.
IDLE = 0;
// Processing jobs (e.g. printing).
PROCESSING = 1;
// Device cannot process jobs. User should fix the problem to resume the
// processing (e.g. printer is out of paper).
STOPPED = 2;
}
// Device cloud connectivity state.
enum CloudConnectionStateType {
UNKNOWN = 0;
NOT_CONFIGURED = 1;
ONLINE = 2;
OFFLINE = 3;
}
// Version of the CDS in the form "X.Y" where changes to Y are backwards
// compatible, and changes to X are not (required).
optional string version = 1;
// Whether device is connected to the server. It is not intended to be
// reported by the device, it's set by the server.
optional CloudConnectionStateType cloud_connection_state = 2;
// Defined for devices with printing capabilities.
optional PrinterStateSection printer = 3;
// Defined for devices with scanning capabilities.
optional ScannerStateSection scanner = 4;
}
印表機狀態部分
如果裝置有列印功能，請使用這個部分說明列印單位的狀態。
// Represents the printer state.
message PrinterStateSection {
// Current printer state (required).
optional CloudDeviceState.StateType state = 1;
// State of the input trays.
optional InputTrayState input_tray_state = 2;
// State of the output bins.
optional OutputBinState output_bin_state = 3;
// State of the markers.
optional MarkerState marker_state = 4;
// State of the printer doors/covers/etc.
optional CoverState cover_state = 5;
// State of the printer media paths.
optional MediaPathState media_path_state = 6;
// Vendor-specific printer state.
optional VendorState vendor_state = 101;
}
// State of the device's input trays.
message InputTrayState {
message Item {
enum StateType {
// Tray is functional.
OK = 0;
// Tray is out of media. Treated as error.
EMPTY = 1;
// Tray is open. Treated as error.
OPEN = 2;
// Tray is installed, but turned off or disconnected. Treated as error.
OFF = 3;
// Tray is present, but not functioning properly. Treated as error.
FAILURE = 4;
}
// ID of the tray (refers to CDD model) (required).
optional string vendor_id = 1;
// Current tray state (required).
optional StateType state = 2;
// Loaded media level, percent. Ranges from 0 (empty) to 100 (fully loaded).
optional int32 level_percent = 3;
// Vendor-specific message, ignored when state == OK.
optional string vendor_message = 101;
}
repeated Item item = 1;
}
// State of the device's output bins.
message OutputBinState {
message Item {
enum StateType {
// Bin is functional.
OK = 0;
// Bin is full and cannot receive any more output. Treated as error.
FULL = 1;
// Bin is open. Treated as error.
OPEN = 2;
// Bin is installed, but turned off or disconnected. Treated as error.
OFF = 3;
// Bin is present, but not functioning properly. Treated as error.
FAILURE = 4;
}
// ID of the bin (refers to CDD model) (required).
optional string vendor_id = 1;
// Current bin state (required).
optional StateType state = 2;
// Used space, percent. Ranges from 0 (empty) to 100 (full).
optional int32 level_percent = 3;
// Vendor-specific message, ignored when state == OK.
optional string vendor_message = 101;
}
repeated Item item = 1;
}
// State of the device markers (toner/ink/staples/etc).
message MarkerState {
message Item {
enum StateType {
// Marker is functional.
OK = 0;
// Marker resource is exhausted. Treated as error.
EXHAUSTED = 1;
// Marker is removed. Treated as error.
REMOVED = 2;
// Marker is present, but not functioning properly. Treated as error.
FAILURE = 3;
}
// ID of the marker (refers to CDD model) (required).
optional string vendor_id = 1;
// Current marker state (required).
optional StateType state = 2;
// Marker supply amount, percent. Ranges from 0 to 100.
optional int32 level_percent = 3;
// Estimated number of pages for which the marker supply amount will last.
optional int32 level_pages = 4;
// Vendor-specific message, ignored when state == OK.
optional string vendor_message = 101;
}
repeated Item item = 1;
}
// State of the device covers (door/cover/etc).
message CoverState {
message Item {
enum StateType {
// Default cover state (closed, does not need any attention).
OK = 0;
// Cover is open. Treated as error.
OPEN = 1;
// Cover is not functioning properly. Treated as error.
FAILURE = 2;
}
// ID of the cover (refers to CDD model) (required).
optional string vendor_id = 1;
// Current cover state (required).
optional StateType state = 2;
// Vendor-specific message, ignored when state == OK.
optional string vendor_message = 101;
}
repeated Item item = 1;
}
// State of the device media paths.
message MediaPathState {
message Item {
enum StateType {
// Path is functioning.
OK = 0;
// Media is jammed. Treated as error.
MEDIA_JAM = 1;
// Path is present, but not functioning properly. Treated as error.
FAILURE = 2;
}
// ID of the media path (refers to CDD model) (required).
optional string vendor_id = 1;
// Current state (required).
optional StateType state = 2;
// Vendor-specific message, ignored when state == OK.
optional string vendor_message = 101;
}
repeated Item item = 1;
}
注意：如上方 protobuf 定義中的每個 vendor_id 欄位註解所示，CDS 訊息中實體單元的每個狀態項目的供應商 ID 必須與 CDD 中對應實體單元的供應商 ID 相符。
// Vendor-specific state.
message VendorState {
message Item {
enum StateType {
ERROR = 0;
WARNING = 1;
INFO = 2;
}
// Severity of the state (required).
optional StateType state = 1;
// Non-localized user-readable state description.
// New vendor state items should use description_localized instead. It is
// required that either description or description_localized is set.
optional string description = 2;
// Translations of state description.
// If not empty, must contain an entry with locale == EN.
repeated LocalizedString description_localized = 3;
}
repeated Item item = 1;
}
注意：建議您盡量從供應商訊息的結尾省略句號，以便與語意狀態資料產生的本地化訊息 (例如「黑色墨水空白」) 保持一致。
CDS 範例
以下範例針對 CDD 範例中「典型印表機」的 CDS 範例，其中的空白墨水匣相關說明。請注意：
- 工作尚待處理，因此「已停止」裝置狀態。
- 伺服器會假設在 DSDS 中未提及狀態的裝置 (這裡的輸入匣和前置封面) 處於「正常」狀態，且不會回報其他資訊 (例如「level_percent」)。
- 「cloud_connection_state」欄位已省略；由 /printer 和 /search 介面傳回的 CDS 設定伺服器 (如果「semanticState」是做為額外欄位要求)。
{
"version": "1.0",
"printer": {
"state": "STOPPED",
"marker_state": {
"item": [
{
"vendor_id": "black",
"state": "EXHAUSTED",
"level_percent": 0
},
{
"vendor_id": "color",
"state": "OK",
"level_percent": 88,
"level_pages": 100
}
]
}
}
}
CDS 差異分析
系統會按照上文所述，提供 /update 介面的 semantic_state_diff 參數做為一般 CloudDeviceState 訊息，但會被解讀為儲存在印表機上的 CDS，如下所示：「diff」。
- 原始 CDS 中的不變差異不會省略。
- 移除了 PrinterStateSection 和 ScannerStateSection 中空白值 (例如
"marker_state": {}) 的巢狀訊息欄位。 - 原始欄位或列舉類型欄位，以及提供的非空白值欄位會新增或變更。
- 使用「semantic_state_diff」參數時，系統一律會省略「version」欄位。 如果省略這種方式，但印表機先前並未設定 CDS，則 Cloud Print 伺服器會假設提供的差異比較是使用最新版本，並據此設定版本欄位。
雲端裝置 UI 狀態
CDS 格式不會立即向使用者提供有意義的裝置狀態，因此透過要求「uiState」做為額外欄位，傳回「UI 狀態」。格式的 protobuf 定義如下所示。
// Represents a cloud device's state in a form convenient for display in a UI.
message CloudDeviceUiState {
enum Summary {
IDLE = 0;
PROCESSING = 1;
STOPPED = 2;
OFFLINE = 3;
}
enum Severity {
NONE = 0;
LOW = 1;
MEDIUM = 2;
HIGH = 3;
}
// Device state summary (required).
optional Summary summary = 1 [default = IDLE];
// Overall severity (error level) of the device state (required).
// Must only be HIGH in the case that the device is STOPPED.
optional Severity severity = 2 [default = NONE];
// In the descriptions of the following three fields, "CDS is nontrivial"
// means that CDS is present and there is at least one state item in its
// PrinterStateSection or ScannerStateSection which is "interesting" enough
// to produce a UI state item for.
// Number of issues detected.
// Present if and only if CDS is nontrivial.
optional int32 num_issues = 3 [default = 0];
// Heuristically determined most relevant message from a state item.
// Present if and only if CDS is nontrivial, the device is not OFFLINE, and
// the maximum severity of a state item is at least MEDIUM if the device is
// IDLE or PROCESSING, or at least LOW if the device is STOPPED.
optional string caption = 4;
// State items specific to the printing capability of the device.
// Present if and only if CDS is nontrivial and this CloudDeviceUiState object
// is being returned in a single printer lookup or in a recent printer search.
optional PrinterUiStateSection printer = 5;
}
// Contains one UI state item for each CDS state item using the information
// obtained from cross-referencing the CDD.
message PrinterUiStateSection {
// A UI state item with a severity level and either:
// (1) a localized message and UI-displayable data from the properties and
// state of a particular unit of the device, or
// (2) a possibly non-localized vendor state message.
message Item {
// The severity of this individual state item (required).
optional CloudDeviceUiState.Severity severity = 1;
// A message produced from a state item, e.g. Black ink level is 60%. This
// message may not be localized if it is from a VendorState.Item (required).
optional string message = 2;
// A non-localized vendor-specific message that provides additional
// information about the state of the device unit described by this item.
optional string vendor_message = 3;
// The fullness level of an input tray, output bin or marker.
optional int32 level_percent = 4;
// The color of a marker.
optional cloudprint.capabilities.Marker.Color.Type color = 5;
}
repeated Item vendor_item = 1;
repeated Item input_tray_item = 2;
repeated Item output_bin_item = 3;
repeated Item marker_item = 4;
repeated Item cover_item = 5;
repeated Item media_path_item = 6;
}
CloudDeviceUiState 範例
以下是由上方 /search 介面 (適用於英文語言代碼) 範例 CDS 所產生的 CloudDeviceUiState 訊息。這是輕量版 CloudDeviceUiState。
{
"summary": "STOPPED",
"severity": "HIGH",
"num_issues": 1,
"caption": "Ink is empty"
}
以下的 CloudDeviceUiState 訊息是由 /printer 介面使用相同的 CDS 所產生 (適用於英文語言代碼)。這個 CloudDeviceUiState 完整表單會使用 CMP 描述的實體 ID 來交叉參照 CDS 中的狀態項目，並使用供應商 ID 進行說明。
{
"summary": "STOPPED",
"severity": "HIGH",
"num_issues": 1,
"caption": "Black ink is empty",
"printer": {
"marker_item": [
{
"severity": "MEDIUM",
"message": "Black ink is empty",
"color": "BLACK"
},
{
"severity": "NONE",
"message": "Color ink level is 88% – 100 pages remaining",
"level_percent": 88,
"color": "COLOR"
}
]
}
}
請按這裡，查看印表機自 2014 年 4 月 29 日起的呈現方式。
Cloud 工作狀態
雲端工作上工作狀態的裝置類型屬於部分工作。類型列舉定義了一般工作生命週期定義的基本狀態組合。這些狀態類型不適用於「印表機」工作，但可能適用於任何裝置類型的工作。
// Contains the device-agnostic state of a job on a cloud device.
message JobState {
// Supported job state types.
enum Type {
// Job is being created and is not ready for processing yet.
DRAFT = 0;
// Submitted and ready, but should not be processed yet.
HELD = 1;
// Ready for processing.
QUEUED = 2;
// Currently being processed.
IN_PROGRESS = 3;
// Was in progress, but stopped due to error or user intervention.
STOPPED = 4;
// Processed successfully.
DONE = 5;
// Aborted due to error or by user action (cancelled).
ABORTED = 6;
}
message UserActionCause {
// Next number = 2.
enum ActionCode {
// User has cancelled the job.
CANCELLED = 0;
// User has paused the job.
PAUSED = 1;
// User has performed some other action.
OTHER = 100;
}
// Code for the user action which caused the current job state (required).
optional ActionCode action_code = 1;
}
message DeviceStateCause {
// Next number = 5.
enum ErrorCode {
// Error due to input tray problem.
INPUT_TRAY = 0;
// Error due to marker problem.
MARKER = 1;
// Error due to a problem in the media path.
MEDIA_PATH = 2;
// Error due to media size problem.
MEDIA_SIZE = 3;
// Error due to media type problem.
MEDIA_TYPE = 4;
// Error due to some other device state.
OTHER = 100;
}
// Error code for the device state which caused the current job state
// (required).
optional ErrorCode error_code = 1;
}
message DeviceActionCause {
// Next number = 4.
enum ErrorCode {
// Error while downloading job.
DOWNLOAD_FAILURE = 0;
// Error due to invalid job ticket.
INVALID_TICKET = 1;
// A generic printing error occurred.
PRINT_FAILURE = 2;
// The document is too large for the printer.
DOCUMENT_TOO_LARGE = 3;
// Error due to some other device action.
OTHER = 100;
}
// Error code for the device action which caused the current job state
// (required).
optional ErrorCode error_code = 1;
}
message ServiceActionCause {
// Next number = 16.
enum ErrorCode {
COMMUNICATION_WITH_DEVICE_ERROR = 0;
CONVERSION_ERROR = 1;
CONVERSION_FILE_TOO_BIG = 2;
CONVERSION_UNSUPPORTED_CONTENT_TYPE = 3;
DELIVERY_FAILURE = 11;
EXPIRATION = 14;
FETCH_DOCUMENT_FORBIDDEN = 4;
FETCH_DOCUMENT_NOT_FOUND = 5;
GOOGLE_DRIVE_QUOTA = 15;
INCONSISTENT_JOB = 6;
INCONSISTENT_PRINTER = 13;
PRINTER_DELETED = 12;
REMOTE_JOB_NO_LONGER_EXISTS = 7;
REMOTE_JOB_ERROR = 8;
REMOTE_JOB_TIMEOUT = 9;
REMOTE_JOB_ABORTED = 10;
OTHER = 100;
}
// Error code for the service action which caused the current job state
// (required).
optional ErrorCode error_code = 1;
}
// Current job state type (required).
optional Type type = 1;
// Exactly one of the following four fields must be set if and only if the
// state type is ABORTED or STOPPED.
// For example:
// - {"type": "ABORTED", "user_action_cause": {"action_code": "CANCELLED"}}
// interpreted as the job was cancelled by the user.
// - {"type": "STOPPED", "device_state_cause": {"error_code": "MEDIA_PATH"}}
// interpreted as the job was stopped due to a temporary problem with the
// media path, such as paper jam (the specific cause will be discerned from
// the device state by the server).
// - {"type": "ABORTED",
// "device_action_cause": {"error_code": "DOWNLOAD_FAILURE"}}
// interpreted as the job was aborted due to a download failure.
// If present, job state was changed due to user action.
optional UserActionCause user_action_cause = 2;
// If present, job state was changed due to device state change.
optional DeviceStateCause device_state_cause = 3;
// If present, job state was changed due to device action.
optional DeviceActionCause device_action_cause = 4;
// If present, job state was changed due to service (Cloud Print) action.
// Should only be set by the Cloud Print server.
optional ServiceActionCause service_action_cause = 5;
}
「雲端列印」預期及支援的工作狀態類型轉換：
舊版工作狀態
上述定義的工作狀態類型會取代 /submit、/jobs 和 /control 介面中使用的舊版工作狀態列舉，但系統依然支援回溯相容性，可能的舊版工作狀態包括：- QUEUED：已新增工作但尚未下載
- IN_PROGRESS：已下載工作並新增至用戶端原生印表機佇列
- 完成：工作列印成功
- 錯誤：發生錯誤，因此無法列印工作
- SUBMITTED：工作已提交至第三方服務 (僅適用於 FedEx 印表機)
- HELD：工作已成功提交，但必須先經過某些使用者處理才能進行 QUEUED
您可以前往這裡查看轉換狀態在各種情況下的轉換條件。
頂層工作狀態
單一裝置可以具備多項功能 (例如列印和掃描)，但這類裝置上的工作僅由一個函式執行。因此，每個支援的裝置函式都有頂層工作狀態格式。
列印工作狀態
列印工作狀態 (PJS) 會儲存在伺服器上，凡是具有工作存取權的用戶端都能擷取。
// Represents the current state of a print job on a cloud device.
message PrintJobState {
// Version of the PJS in the form "X.Y" where changes to Y are backwards
// compatible, and changes to X are not (required).
optional string version = 1;
// Current state of the job (required).
optional JobState state = 2;
// Number of successfully printed pages. Printer should use this value to
// restart interrupted/suspended print jobs from the next page.
// Printer can only increase the number of pages printed.
optional int32 pages_printed = 3;
// Number of attempts to deliver the print job.
optional int32 delivery_attempts = 4;
}
列印工作狀態差異
只要是未傳送最終狀態 (DONE 或 ABORTED) 的工作，雲端裝置都可以傳送 PrintJobStateDiff 訊息，要求工作狀態變更。
// Diff that can be applied to a PrintJobState message. Any omitted field will
// not be changed.
message PrintJobStateDiff {
// New job state.
optional JobState state = 1;
// New number of pages printed.
optional int32 pages_printed = 2;
}
雲端列印支援更多裝置功能，因此會新增更多頂層工作狀態格式。
PrintJobStateDiff 範例
為最近輸入 IN_PROGRESS 狀態的工作傳送 PrintJobStateff 訊息：
{
"state": {"type": "IN_PROGRESS"}
}
輸出多頁文件後，顯示同一工作的 PrintJobStateDiff 訊息：
{
"pages_printed": 1
}
使用者列印第三次網頁時，取消的列印工作列印工作狀態訊息：
{
"state": {
"type": "ABORTED",
"user_action_cause": {"action_code": "CANCELLED"}
},
"pages_printed": 3
}
列印工作 UI 狀態
PrintJobState 格式不會立即向使用者顯示有意義的工作狀態，因此所有工作都會傳回「UI 狀態」格式。格式的 protobuf 定義如下所示。
// Represents a print job's state in a form convenient for display in a UI.
message PrintJobUiState {
enum Summary {
DRAFT = 0;
QUEUED = 1;
IN_PROGRESS = 2;
PAUSED = 3;
DONE = 4;
CANCELLED = 5;
ERROR = 6;
EXPIRED = 7;
}
// Job state summary (required).
optional Summary summary = 1;
// Localized string describing the progress of the job, e.g. the number of
// attempts to deliver it or the number of pages which have been printed.
optional string progress = 2;
// Localized string describing the cause of an abnormal state of the job.
optional string cause = 3;
}
PrintJobUiState 範例
以下是在列印 4 頁文件的第二頁時，顯示工作的 PrintJobUiState 訊息。
{
"summary": "IN_PROGRESS",
"progress": "Pages printed: 1 of 4"
}
下方有關相同工作的 PrintJobUiState 訊息，是在第三頁列印後、第 4 頁的列印工作取消之前，只要透過印表機的使用者介面取消工作。
{
"summary": "CANCELLED",
"progress": "Pages printed: 3 of 4",
"cause": "Cancelled by user"
}
地區設定
使用者可編輯的設定不會隨著裝置正常使用而變更，或使用下列印表機透過雲端列印伺服器傳送：
// Contains current and pending local settings.
message LocalSettings {
// Contains settings that do not change with normal use of the device.
message Settings {
// Whether Privet local discovery is enabled (required).
optional bool local_discovery = 1;
// Whether Privet access token API should be exposed on the local network.
optional bool access_token_enabled = 2;
// Whether Privet local printing API should be exposed on the local network.
optional bool printer/local_printing_enabled = 3;
// Whether Privet local printing may send jobs to the server for conversion.
optional bool printer/conversion_printing_enabled = 4;
// Number of seconds between XMPP channel pings.
optional int32 xmpp_timeout_value = 5;
}
// Current local settings.
// Required (for GCP 2.0) to be provided by the device via the /register
// interface. Should be provided or confirmed by the device via the /update
// interface as necessary. Prohibited to be provided by clients. Always
// present in the local_settings field returned by the /printer interface.
optional Settings current = 1;
// Pending local settings.
// Prohibited to be provided by the device. Provided by clients via the
// /update interface. Present in the local_settings field returned by the
// /printer interface if a client has provided pending local settings but the
// device has not yet confirmed them as current.
optional Settings pending = 2;
}
本機設定範例
裝置提供給 /register 或 /update 介面的 local_settings 參數值範例：
{
"current": {
"local_discovery": true,
"access_token_enabled": true,
"printer/local_printing_enabled": true,
"printer/conversion_printing_enabled": true,
"xmpp_timeout_value": 300
}
}
用戶端提供給 /update 介面的 local_settings 參數值範例：
{
"pending": {
"local_discovery": true,
"access_token_enabled": true,
"printer/local_printing_enabled": false,
"printer/conversion_printing_enabled": false,
"xmpp_timeout_value": 500
}
}
裝置在確認待處理的設定之前，由 /printer 介面傳回的 local_settings 欄位範例：
"local_settings": {
"current": {
"local_discovery": true,
"access_token_enabled": true,
"printer/local_printing_enabled": true,
"printer/conversion_printing_enabled": true,
"xmpp_timeout_value": 300
},
"pending": {
"local_discovery": true,
"access_token_enabled": true,
"printer/local_printing_enabled": false,
"printer/conversion_printing_enabled": false,
"xmpp_timeout_value": 500
}
}