diff options
Diffstat (limited to 'ijs_spec.sgml')
| -rw-r--r-- | ijs_spec.sgml | 1099 |
1 files changed, 1099 insertions, 0 deletions
diff --git a/ijs_spec.sgml b/ijs_spec.sgml new file mode 100644 index 0000000..f85cf76 --- /dev/null +++ b/ijs_spec.sgml @@ -0,0 +1,1099 @@ +<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> +<article> +<artheader> + <title>IJS Protocol Specification</title> + <subtitle>Version 0.34 — 22 Feb 2002</subtitle> + <!-- the date should be a <date> element, but I can't for the + life of me figure out how to coax db2ps into actually + rendering it --> + <author><firstname>Raph</> <surname>Levien</></author> + +</artheader> + +<abstract> +<para> +This document contains a specification for the IJS protocol, which is +intended to make it easier to deploy raster-based printer drivers in +a wide variety of environments, including Unix desktops. +</para> +</abstract> + +<sect1><title>Introduction</title> + +<para> +IJS is, first and foremost, a protocol for transmission of raster page +images. The protocol is a fairly traditional client-server design. In +general, the client sends one or more page images to the server, along +with various metadata. Communication is through simple +“commands”, which are essentially size-prefixed +packets. The client sends a command to the server, then waits for a +response command, either ACK or NAK. +</para> + +<para> +Since, in the typical IJS scenario, there is only one client for +any given server, it may be helpful to denote the client role as +"master" and the server role as "slave". However, this document +uses the terms "client" and "server". +</para> + +<para> +On Unix systems, the server “speaks” IJS through stdin and stdout. One +consequence of this design decision is that the server can be invoked +remotely, for example through <command>ssh</command>. +<comment>It's not clear yet how +useful this will be, but at least people can experiment with +it.</comment> +</para> + +<para> +Other forms of communication (such as domain sockets) may be useful, +as well, but are not specified in this version. +</para> + +<para> +There are also a large number of things that the IJS specification +does <emphasis>not</emphasis> address. It does not provide strings for +a UI (although the parameter names and values may be used as a +fallback when higher-level mechanisms designed to provide these +fail). It does not address the task of discovering printers or +drivers. It is not designed to dispatch jobs to multiple printers. It +does not provide queue management features. It does not address higher +level imaging models, or fonts. These are important components of a +printing system, and should be addressed by other modules and +interfaces. +</para> + +</sect1> + +<sect1><title>Wire protocol</title> + +<para> +After a brief initialization handshake, all IJS communication occurs +through <emphasis>commands</emphasis>. Most of these are sent from the +client to the server, but three (IJS_CMD_PONG, IJS_CMD_ACK, and +IJS_CMD_NAK) are sent from the server to the client. +</para> + +<para>With the exception of IJS_CMD_PING, the appropriate response to +a command sent from the server is either IJS_CMD_ACK or IJS_CMD_NAK. +</para> + +<para> +The initialization handshake is as follows. First, the client sends +the string "IJS\n\252v1\n" (with C backslash escaping). Upon receipt +of this string, the server sends the string "IJS\n\253v1\n". At this +point, the client may send IJS commands to the server. +</para> + +<para> +IJS is designed to have a simple wire encoding. Integers are encoded +as 32-bit big-endian (ie “network order”) values. The +encoding for a command is as follows: +</para> + +<table><title>Wire Encoding of IJS Commands</title> +<tgroup cols=2> +<colspec colname=c1 colwidth=1in> +<colspec colname=c2 colwidth=1in> +<spanspec spanname=hspan namest=c1 nameend=c2 align=center> +<tbody> +<row><entry>Command</entry><entry>4-byte integer</entry></row> +<row><entry>Size in bytes</entry><entry>4-byte integer</entry></row> +<row rowsep=0><entry spanname=hspan>Arguments</entry></row> +<row><entry spanname=hspan>...</entry></row> +</tbody> +</tgroup> +</table> + +<para> +The arguments are simply concatenated. For variable size arguments, +the size is either explicitly given as another argument, or, in the +case of the last argument, is inferred from the size of the command. +</para> + +<para> +A wire encoding for a typical command is given below. This command +sets the Dpi parameter to 600. +</para> + +<table><title>Example Wire Encoding</title> +<tgroup cols=3> +<colspec colname=c1 colwidth=1.5in> +<colspec colname=c2> +<colspec colname=c3 colwidth=3in> + +<thead> +<row> + <entry>Encoded bytes</entry> + <entry>Field</entry> + <entry>Value</entry> +</row> +</thead> + +<tbody> + +<row><entry>00 00 00 0c</entry> <entry>Command</entry> +<entry>IJS_COMMAND_SET_PARAM</entry></row> + +<row><entry>00 00 00 16</entry> <entry>Size in bytes</entry> +<entry>22</entry></row> + +<row><entry>00 00 00 00</entry> <entry>Job id</entry> +<entry>0</entry></row> + +<row><entry>00 00 00 03</entry> <entry>Size of parameter name</entry> +<entry>3</entry> + +<row><entry>44 70 69 </entry> <entry>Parameter name</entry> +<entry>Dpi</entry></row> + +<row><entry>36 30 30 </entry> <entry>Value</entry> <entry>600</entry></row> + +</tbody> +</tgroup> +</table> + +<para>The numerical values of the commands are:</para> + +<table><title>Numerical Values of IJS Commands</title> + +<tgroup cols=2> +<colspec colwidth=3in> +<colspec colwidth=1in> +<thead> +<row> + <entry>Command</entry> + <entry>Value</entry> +</row> +</thead> + +<tbody> +<row><entry>IJS_CMD_ACK</entry> <entry>0</entry></row> +<row><entry>IJS_CMD_NAK</entry> <entry>1</entry></row> +<row><entry>IJS_CMD_PING</entry> <entry>2</entry></row> +<row><entry>IJS_CMD_PONG</entry> <entry>3</entry></row> +<row><entry>IJS_CMD_OPEN</entry> <entry>4</entry></row> +<row><entry>IJS_CMD_CLOSE</entry> <entry>5</entry></row> +<row><entry>IJS_CMD_BEGIN_JOB</entry> <entry>6</entry></row> +<row><entry>IJS_CMD_END_JOB</entry> <entry>7</entry></row> +<row><entry>IJS_CMD_CANCEL_JOB</entry> <entry>8</entry></row> +<row><entry>IJS_CMD_QUERY_STATUS</entry> <entry>9</entry></row> +<row><entry>IJS_CMD_LIST_PARAMS</entry> <entry>10</entry></row> +<row><entry>IJS_CMD_ENUM_PARAM</entry> <entry>11</entry></row> +<row><entry>IJS_CMD_SET_PARAM</entry> <entry>12</entry></row> +<row><entry>IJS_CMD_GET_PARAM</entry> <entry>13</entry></row> +<row><entry>IJS_CMD_BEGIN_PAGE</entry> <entry>14</entry></row> +<row><entry>IJS_CMD_SEND_DATA_BLOCK</entry> <entry>15</entry></row> +<row><entry>IJS_CMD_END_PAGE</entry> <entry>16</entry></row> +<row><entry>IJS_CMD_EXIT</entry> <entry>17</entry></row> +</tbody> +</tgroup> +</table> + +<para> +A state transition diagram for servers supporting a maximum of one +active job at a time is given below: +</para> + +<graphic fileref="state.eps" format="eps" scale=50> +</graphic> + +<sect2><title>IJS_CMD_ACK</title> + +<para>This command is sent from server to the client in response to a +command from the client, to indicate successful completion. There are +no arguments specific to this command. However, for commands (such as +IJS_CMD_GET_PARAM) which request a value, this value is returned as +the argument in an ACK command. +</para> +</sect2> + +<sect2><title>IJS_CMD_NAK</title> + +<para>This command is sent from server to the client in response to a +command from the client, to indicate an error. There is one integer +argument, which is the error code. A list of error codes is given +in <xref linkend="sect-errorcodes">. + +<sect2><title>IJS_CMD_PING</title> + +<para>The PING command is sent from the client to the server as part +of the connection setup. It contains one integer argument, which is +the 100 times the real-valued version number of the largest IJS +protocol understood by the client. Thus, for the version of the +protocol described in this document, the argument is 30. The +appropriate response to a PING is a PONG. +</para> +</sect2> + +<sect2><title>IJS_CMD_PONG</title> + +<para>The PONG command is sent from the server to the client in +response to the PING command. It contains one integer argument, which +is 100 times the largest IJS version number understood by the +server. After a PING/PONG handshake, both client and server should use +the minimum of the two version numbers. This negotiation mechanism +preserves the ability to make deep changes in future version of the +protocol, while preserving backwards compatibility for both clients +and servers. +</para> +</sect2> + +<sect2><title>IJS_CMD_OPEN</title> + +<para> +The client should send an OPEN command to the server to indicate +that printing is imminent. The server can allocate resources, such +as tables, at this time. +</para> +</sect2> + +<sect2><title>IJS_CMD_CLOSE</title> + +<para> +The client should send a CLOSE command to the server to indicate +that printing is complete for now. The server can free any allocated +resources at this time. +</para> + +<para> +There should not be any jobs open at the time of the CLOSE command. +Handling of any such jobs is undefined. +</sect2> + +<sect2><title>IJS_CMD_BEGIN_JOB</title> + +<para> +The client should send a BEGIN_JOB to the server to begin a job. +There is one integer argument, a job id. This id is allocated by +the client, and jobs are uniquely identified by the (client, job +id) tuple. This job id is present as an argument for all the +commands which operate within the context of a job. This job +id is valid until the corresponding END_JOB command is invoked, +at which point it can be reused if desired. + +<para> +The connection must be in an open state to begin a job, ie an +OPEN command must have been sent, without a corresponding CLOSE. +</para> + +<para> +Servers can choose whether or not to implement multiple jobs, +depending on their sophistication. When the number of jobs supported +is exceeded, the server should return an IJS_ETOOMANYJOBS error code. +</para> +</sect2> + +<sect2><title>IJS_CMD_END_JOB</title> + +<para> +The client should send an END_JOB command to the server on the +completion of a job. The one argument is the job id. This command +cannot be used in the middle of a page, i.e. when a BEGIN_PAGE command +has been issued without its corresponding END_PAGE. +</para> +</sect2> + +<sect2><title>IJS_CMD_CANCEL_JOB</title> + +<para> +This command cancels a job. The one argument is the job id. This +command can be used whether or not a page is open. +</para> +</sect2> + +<sect2><title>IJS_CMD_QUERY_STATUS</title> + +<para> +This command queries the status of a job, or general printer status +within a job context. The one argument is the job id. The return +data is the printer status. +</para> + +<para> +The format of the printer status is yet to be determined. Glen Petrie +has made a proposal on the inkjet-list mailing list. Michael Sweet has +suggested adopting the IPP status codes. That standard is fairly rich +in status queries. There appear to be at least four queries related to +this IJS command: printer-state (enum), printer-state-reasons +(keyword), printer-state-message (text), printer-is-accepting-jobs +(boolean). +</para> +</sect2> + +<sect2><title>IJS_CMD_LIST_PARAMS</title> + +<para> +This command queries the server for a complete list of parameters. +Note that this list may change dynamically, in response to setting +various parameters, or external events. The argument is the job id. +The return value is a comma-separated list of parameters. +</para> +</sect2> + +<sect2><title>IJS_CMD_ENUM_PARAM</title> + +<para> +This command queries the possible values for a given parameter. +The arguments are the job id and the name of the parameter. The +return value is a comma-separated list of values, with the default +given first. +</para> + +<para> +Some parameters may not have a small finite enumeration. In these +cases, the server should report IJS_ERANGE. +</para> + +<para> +Note also that the comma-separated encoding does not provide a way +to report values containing commas. Thus, these should be avoided. +</sect2> + +<sect2><title>IJS_CMD_SET_PARAM</title> + +<para> +This command sets a parameter. There are four arguments: the job id, +the size of the parameter name (in bytes), the parameter name, and the +value. The size of the value is inferred from the size of the command. +</para> + +<para>If the parameter is unknown, the server returns an IJS_EUNKPARAM +error. If the parameter is known but the value is not appropriate, the +server returns an IJS_ERANGE error. +</para> +</sect2> + +<sect2><title>IJS_CMD_GET_PARAM</title> + +<para> +This command retrieves the current value of a parameter. There are two +arguments: the job id and the parameter name. The value of the parameter +is returned. +</para> + +<para> +If the parameter is unknown, the server returns an IJS_EUNKPARAM error. +</para> +</sect2> + +<sect2><title>IJS_CMD_BEGIN_PAGE</title> + +<para> +This command begins a new page. All of the parameters affecting the +data format of the page should have already been set by this time. +</para> +</sect2> + +<sect2><title>IJS_CMD_SEND_DATA_BLOCK</title> + +<para> +This command sends a block of data, in the format defined by +PageImageLanguage and its subsidiary parameters. There are no +alignment restrictions. There are two arguments: the job id, +and the size of the data block in bytes. The data block follows +the command, in the same stream. +</para> + +<para> +Note that shared-memory transport of bulk data is anticipated in +a future version of this standard. Pipe transport will still be +used as a fallback in case shared-memory transport is unavailable. +</para> + +<para> +The server must be in the middle of a page (ie BEGIN_PAGE without +the corresponding END_PAGE) when this command is issued. +</para> +</sect2> + +<sect2><title>IJS_CMD_END_PAGE</title> + +<para> +This command ends a page. The server must be in the middle of a +page when this command is issued. The argument is the job id. +</para> +</sect2> + +<sect2><title>IJS_CMD_EXIT</title> + +<para> +This command signals the end of the IJS connection. In the typical +case of a server with a single client, the server process terminates +upon receipt of this command. +</para> + +<para> +The connection must be in a closed state at the time of this command. +</para> + +<comment>Need to look into race condition.</comment> +</sect2> + +</sect1> + +<sect1><title>Parameters</title> + +<para> +IJS defines a small set of standard parameters, which all clients and +servers are expected to understand. Individual implementations may +extend this standard set with additional parameters specific to the +device or driver. Clients should, in general, provide some mechanism +for setting (and possibly querying) arbitrary additional +parameters. In particular, command line clients should accept command +line options to set additional parameters. Interactive clients should +ideally query the server for a list of these parameters to display in +the interface, then query each parameter for the list of possible +values, presented as menu choices. +</para> + +<para> +In addition, in many scenarios, the client may have additional +information specific to the device, obtained through other means, for +example a PPD (or PPD-like) file specified by the user. Such file +formats are well beyond the scope of this specification. However, many +users may find the simple parameter mechanism of IJS to be sufficient +for their needs. A particular strength of the IJS parameter mechanism +is that no additional effort is required to handle dynamic capability +information, for example the presence of a hot-pluggable duplexer. +</para> + +<para> +Often, one parameter will be subsidiary to another. In this case, +the subsidiary parameter should be set, gotten, or enumerated after +the other parameter is set. +</para> + +</sect1> + +<sect1><title>Standard parameters</title> + +<para> +This section describes the standard parameters specified by IJS. +</para> + +<sect2><title>OutputFile</title> + +<para> +This parameter is the filename intended for IJS output. It will +often refer to a device, but can also be a regular file. +</para> + +<para> +Note that this parameter should be considered security-sensitive. +Clients should take care to ensure that it is set only to legitimate +values. +</para> + +</sect2> + +<sect2><title>OutputFD</title> + +<para> +This is an alternative to OutputFile, and is intended to support +-sOutputFile=- and -sOutputFile="|cmd" configurations of Ghostscript. +The parameter is a numeric file descriptor. +</para> + +</sect2> + +<sect2><title>DeviceManufacturer</title> + +<para> +This parameter is the manufacturer of the printer. In general, it +should match the "MANUFACTURER" (or "MFR") field of the IEEE 1284 +Device ID string exactly<citation>IEEE1284</citation>. +</para> + +<para> +There are many different scenarios for setting and querying this +parameter, depending on what information is known about the device. +</para> + +<para> +In the case where the server is able to identify the device, for +example by retrieving the IEEE 1284 Device ID string, or through the +GET_DEVICE_ID request of the USB Printer +Class<citation>USBPrint</citation>, getting the value of the parameter +will retrieve this identification string. In general, the server should +perform the device ID query at the time of the GET_PARAM command. +</para> + +<para> +In the case where the device identification is configured by the +client, the client may set this parameter, then set the DeviceModel +parameter. +</para> + +<para> +Finally, enumerating this parameter returns a list of manufacturers +known by the server. This may be helpful for installing a new +printer in cases where automatic device identification is not +available. +</para> + +<para> +There may be cases where the server is able to automatically identify +the device, and the client attempts to override this identification. +The server should allow this override to occur, particularly when +the device ID is not one known to the server. However, the server +can reject such attempts by returning an IJS_ERANGE error. +</para> +</sect2> + +<sect2><title>DeviceModel</title> + +<para> +This parameter is the model name of the printer, and together with +DeviceManufacturer, identifies the device. In general it should match +the "MODEL" (or "MDL") field of the IEEE 1284 Device ID string. +</para> + +<para> +Usage scenarios are similar to DeviceManufacturer. This parameter is +subsidiary to DeviceManufacturer. +</para> + +<para> +Setting the device manufacturer and model may have profound effects on +the list of other parameters available. For example, the server may in +fact be a wrapper that invokes the “real” server once +the device id is known, and then proxies all IJS commands +subsequently. Thus, all other parameters other than OutputFD, +OutputFile, and DeviceManufacturer, should be considered subsidiary to +this one. +</para> +</sect2> + +<sect2><title>PageImageFormat</title> + +<para> +This parameter specifies the format of the page image data to be sent +to the printer. This standard only defines one standard value: +"Raster". Other values, including compressed raster formats, as well +as possibly higher level page description languages such as PostScript +and PDF, are envisioned as possible future extensions. + +<para> +When it makes sense, names consistent with the "COMMAND SET" (or +"CMD") field of the IEEE 1284 Device ID string are recommended. +However, this namespace has many shortcomings for use with IJS. +In particular, it tends to identify the command set too vaguely. +For example, many Epson printers report merely "ESCPL2", which is +not nearly precise enough to usefully drive the printer. +</para> + +<para> +When the value is "Raster", the following parameters are required, and +are subsidiary to this one: Dpi, Width, Height, BitsPerSample, +ColorSpace, and NumChan. +</para> +</sect2> + +<sect2><title>Dpi</title> + +<para> +This parameter is the resolution for transfer of raster data. It is +specified as a horizontal resolution, in floating decimal dpi units, +an "x", and a vertical resolution, in floating decimal dpi units. +Thus, a typical value is "1440x720". +</para> + +<para> +Note that the server may perform scaling of the raster data as part of +its processing, before sending it to the device. In these cases, the +Dpi parameter specifies the resolution prior to scaling. For example, +a driver might accept 720 dpi raster data, then perform 2:1 horizontal +pixel replication to drive the actual device at 1440x720 dpi. In this +example, the value of the Dpi parameter is "720x720". +</para> +</sect2> + +<sect2><title>Width</title> +<para> +This parameter is the decimal encoded width of the raster image, +in pixels. It MUST be set when PageImageFormat is Raster. +</para> +</sect2> + +<sect2><title>Height</title> +<para> +This parameter is the decimal encoded height of the raster image, +in pixels. It MUST be set for raster images. +</para> +</sect2> + +<sect2><title>BitsPerSample</title> +<para> +This parameter is the decimal encoded bit depth of samples for pixel +values. It MUST be set for raster images. Valid values include 1-7 +(implying client-side dithering of image pixels), 8, and 16 (both +implying server-side dithering if needed by the device). In general, +the total number of bits per pixel is equal to BitsPerSample times +NumChan. +</para> + +<para> +In many cases, querying this parameter will be useful. A +“dumb” server may choose not to implement color +transform and dithering, leaving these to the client. In this case, +the result of the query operation will be a list of bit depths +actually supported by the device. Simple devices may report "1", while +devices capable of both bilevel and 4-level variable dots may report +"1,2". +</para> + +<para> +Note that not all combinations of BitsPerSample and ColorSpace are +valid. In particular, BitsPerSample less than 8 in combination with a +ColorSpace of sRGB or any other colorimetric color space are not +valid. Also for scRGB (also known as sRGB64), 16 is the only valid +value. +</para> + +<para> +When the value is 16, the ByteSex parameter is required, and is +subsidiary to this one. +</para> +</sect2> + +<sect2><title>ByteSex</title> + +<para> +When BitsPerSample is equal to 16, this parameter specifies the byte +sex of the raster data. Possible values are "big-endian" and +"little-endian". +</para> + +<para> +Enumerating this parameter should list the preferred byte sex as the +default (ie first in the comma-separated list). In most cases, this +will be the byte sex of the server's host architecture. +</para> + +<para> +Servers limited to 8 bits of depth need not implement this parameter +at all. +</para> +</sect2> + +<sect2><title>ColorSpace</title> + +<para> +This parameter is a string identifying the color space of the raster +image data. It MUST be set for raster images. Standard values +include "DeviceGray", "DeviceRGB", "DeviceCMYK", and "sRGB". Servers +should support at least one of these color spaces. Clients should be +able to produce raster output if at least one of these color spaces is +supported by the server. +</para> + +<comment> I think we should have a wide-gamut colorimetric color space +in the standard list as well. I like La*b* with a recommended bit +depth of 16. Any objections? +</comment> + +<para> +A device may choose to provide more color spaces. For example, 6 color +inkjets may provide a "DeviceCcMmYK" space. In general, for a client +to use any of these nonstandard spaces requires detailed knowledge of +the color rendering characteristics of the device. +</para> + +<para> +Servers should not provide additional color spaces which are merely +transforms of the standard color spaces. Examples of such discouraged +color spaces are HSV, XYZ, Luv, Yuv, YCC, and colorimetric RGB spaces +other than sRGB (TODO: unless we decide to accept scRGB/sRGB64). +</para> +</sect2> + +<sect2><title>NumChan</title> + +<para> +This parameter is the number of channels in the chosen color space. +In general, it can be determined from the ColorSpace. In particular, +DeviceGray implies 1, DeviceRGB and sRGB imply 3, and DeviceCMYK +implies 4. Attempting to set a NumChan inconsistent with ColorSpace +should result in an error. +</para> + +<sect2><title>PaperSize</title> + +<para>This parameter is in W.WWxH.HH format, in inches, i.e. a string +that may be produced by sprintf (str, "%fx%f", width, height). If the +server knows the paper size (which is unlikely for inkjets), then +getting the parameter will give a good value. In the more common case, +get simply returns an error code (todo: probably need to allocate a +new one for this). Enumerating this parameter may give a list of paper +sizes known by the driver that are plausible for the device. +</para> + +<para> +The result of getting or enumerating PaperSize may change dynamically +depending on the DeviceModel, Duplex, and possibly +“extension” parameters such as those for selecting +trays. +</para> + +<para> +Note that this parameter is essentially the same as the PageSize +page device parameter. The main difference is units (PostScript uses +1/72" inch units), and the minor syntax nit of PostScript array +encoding. +</para> +</sect2> + +<sect2><title>PrintableArea</title> + +<para> +This parameter is in W.WWxH.HH format, and describes the printable +area of the page. It is expected that the client will usually get it +from the server. Any attempt to set it is allowed to fail with an +error, even if it's the same value as the get. The value may change +dynamically depending on PaperSize and other parameters. +</para> + +</sect2> + +<sect2><title>PrintableTopLeft</title> + +<para> +This parameter is in W.WWxH.HH format, and contains the left and top +margins of the printable area with respect to the media. It is the +companion to PrintableArea (I'm considering having a single parameter +that ASCII encodes the four floats). +</para> +</sect2> + +<sect2><title>TopLeft</title> + +<para> +This parameter, in W.WWxH.HH is intended to be set, and controls the +placement of the raster image on the page. The corresponding size of +the raster image area can be inferred from the Width, Height, and Dpi +parameters. +</para> +</sect2> + +<sect2><title>PostScript Page Device Parameters</title> + +<para> +PostScript defines a number of page device parameters, many of which +are relevant to IJS, whether using PostScript or not. Further, many +proposals for characterizing device capabilities are based on PPD +files, which use a consistent namespace and semantics to page device +parameters. +</para> + +<para> +IJS imports the namespace of PostScript page device parameters, +prefixing it with the string "PS:". The client can assume that any +parameters returned by a LIST_PARAMS command matching this prefix are +in fact PostScript page device parameters. Values are straightforward +ASCII encodings. For example, arrays are encoded as space-separated +values, enclosed in square brackets. The set of valid page device +parameters is defined in the PostScript Language Reference +Manual<citation>PLRM</citation>, particularly Chapter 6. +</para> + +<para> +Some page device parameters are subsumed by native IJS parameters, and +should not be used. These include PageSize (subsumed by PaperSize), +ProcessColorModel (subsumed by ColorSpace), Margins and PageOffset +(subsumed by TopLeft), and HWResolution (subsumed by Dpi). +</para> + +<para> +Devices supporting duplexing should implement PS:Duplex and PS:Tumble, +both booleans. A value of true for PS:Duplex requests printing on both +sides of the page. When PS:Duplex is true, PS:Tumble specifies the +relative orientation of the pages. When PS:Tumble is false, the pages +are oriented suitably at the left or right. When PS:Tumble is true, +the pages are oriented suitably for binding at the top or +bottom. Enumerating the PS:Duplex parameter should return a single +"false" value when the server knows that the device is not capable of +duplexing, and either "false,true" or "true,false" if it may be. +</para> + +<comment> +Note that the HPIJS 1.0 implementation of IJS, identifying itself as +IJS version 0.29, specifies an integer-valued Duplex parameter, with +values of 0 (PS:Duplex = false, PS:Tumble don't care), 1 (PS:Duplex = +true, PS:Tumble = false), and 2 (PS:Duplex = true, PS:Tumble = true). +An integer valued Duplex parameter is inconsistent with the PostScript +specification. However, clients desiring compatibility should set +the integer-valued Duplex parameter rather than the PS: parameters +when the server reports a version of 0.29. +</comment> + +<para> +Devices supporting roll-fed media should implement PS:RollFedMedia, +PS:Orientation, PS:AdvanceMedia, PS:AdvanceDistance (note that units +are integer 1/72"), and PS:CutMedia. +</para> + +<para> +Other parameters that may be useful for some devices include +PS:MediaColor, PS:MediaWeight, PS:MediaType, PS:MediaClass, +PS:InsertSheet, PS:LeadingEdge, PS:ManualFeed, PS:TraySwitch, +PS:MediaPosition, PS:ImageShift, PS:MirrorPrint, PS:NegativePrint, +PS:NumCopies, PS:Collate, PS:Jog, PS:OutputFaceUp, PS:Separations, and +PS:SeparationColorNames. Other parameters are allowed, but are +unlikely to be useful in an IJS context. +</para> +</sect2> + +</sect1> + +<sect1><title>Parameter Namespace Extension</title> + +<para> +While this document specifies enough parameters to be able to print +usefully, there is a huge diversity of devices and applications, often +indicating additional parameters not specified. IJS is designed to +accomodate these additional parameters as extensions. It is expected +that the namespace of these extensions will be managed informally. +Note that collisions in this namespace are not necessarily fatal, as +many will be device or manufacturer specific, so that the device id +may be used to disentangle them. Even so, it is clearly a good idea +to manage this namespace well. This section recommends some practices +towards this goal. +</para> + +<para> +When possible, extension parameters should be prefixed, with a colon +separating the prefix from the base parameter name. Well known +prefixes give clients useful information about parameters, even when +the client lacks information about the specific parameter. An unknown +prefix at least allows the client to identify the parameter as a +nonstandard extension. +</para> + +<para> +This document specifies a number of standard prefixes. We also reserve +the following prefixes for possible use in future revisions of this +protocol: IPP, UPDF. Further, the Omni: prefix is reserved for the Omni +group at IBM, and CUPS: is reserved for the CUPS project. +</para> + +<comment> +Robert, do you want STP:? Anyone else? +</comment> + +<sect2><title>Quality:</title> + +<para> +Inkjet printers often provide a rich set of options for tuning output +quality, or selecting a point along a speed/quality tradeoff. The +details of these options vary widely from device to device. When made +available through IJS, they should be grouped under the Quality: +prefix. +</para> + +<para> +Parameters in the Quality: namespace are to be interpreted in the +context of the device id (as defined by the DeviceManufacturer and +DeviceModel parameters). In the context of different device id's, +Quality: parameters with the same name may have entirely different +meaning. This recommendation reflects the diversity of quality +parameters and settings in devices and drivers. +</para> + +<para> +For example, HPIJS 1.0 has the following parameters, for HP inkjet +printers: Quality, MediaType, ColorMode, and PenSet. To be compliant +with versions 0.30 and later of IJS, they should be named +Quality:Quality, Quality:MediaType, Quality:ColorMode, and +Quality:PenSet. +</para> + +<para> +Note that Quality:MediaType overlaps somewhat with PS:MediaType. In +general, the former specifies a color profile or printing mode (for +example, to optimize printing on transparencies). The latter is often +used for selecting a paper source, for example letterhead or +envelopes. The former is more likely to be useful in inkjet +applications. +</para> + +<para> +The Dpi and ColorSpace parameters are subsidiary to any Quality: +parameters provided. +</para> + +</sect2> + +<sect2><title>Finishing:</title> + +<para> +Finishing options, such as stapling and collating, should be +grouped under the Finishing prefix. +</para> + +<para> +The PS page device parameter namespace includes some finishing +options, including Duplex, Tumble, Collate, Jog, and the roll-fed +parameters: RollFedMedia, Orientation, AdvanceMedia, AdvanceDistance, +and CutMedia. For these parameters, the PS: prefix is preferred. +</para> + +<para> +The PPD specification describes a number of additional finishing +parameters (section 5.18 of <citation>PPD</citation>). Where possible, +Finishing: parameters should be consistent with the PPD specification. +</para> + +</sect2> + +<sect2><title>PPD:</title> + +<para> +The PPD specification<citation>PPD</citation> contains a large +number of options and parameters that may be provided by printers. +The PPD: prefix is reserved for PPD parameters that are made +available through the IJS protocol. +</para> + +<para> +In cases where both a page device parameter and a PPD parameter +specify the same setting, the PS: page device parameter takes +priority. In many cases, page device parameters are advantageous +because they are designed for both getting and setting, while PPD +itself is a static file format. In addition, finishing parameters +should be under the Finishing: namespace. +</para> + +<para> +In general, use of the PPD: extension is not recommended, as the +PPD file format tends to be specific to PostScript printers. +</para> + +<comment> +We could use more specific advice on when to use PPD: parameters, and +when not to. Anyone with more PPD knowledge willing to help with this? +</comment> + +</sect2> + +</sect1> + +<sect1 id="sect-errorcodes"><title>Error codes</title> + +<para> +Any IJS command may either succeed or fail. Success is indicated +by an IJS_ACK response. Failure is indicated by an IJS_NAK response, +which includes an integer error code. +</para> + +<para> +The current draft contains the following error codes: + +</para> + +<table><title>Draft IJS Error Codes</title> +<tgroup cols=3> +<colspec colname=def> +<colspec colname=val> +<colspec colname=exp> +<thead> +<row> + <entry>Symbolic definition</entry> + <entry>Numeric value</entry> + <entry>Meaning</entry> +</row> +</thead> + +<tbody> +<row><entry>IJS_EIO</entry> <entry>-2</entry> <entry>I/O error</entry></row> +<row><entry>IJS_EPROTO</entry> <entry>-3</entry> <entry>protocol error</entry></row> +<row><entry>IJS_ERANGE</entry> <entry>-4</entry> <entry>out of range</entry></row> +<row><entry>IJS_EINTERNAL</entry> <entry>-5</entry> <entry>internal error</entry></row> +<row><entry>IJS_ENYI</entry> <entry>-6</entry> <entry>not yet implemented</entry></row> +<row><entry>IJS_ESYNTAX</entry> <entry>-7</entry> <entry>syntax error</entry></row> +<row><entry>IJS_ECOLORSPACE</entry> <entry>-8</entry> <entry>unknown color space</entry></row> +<row><entry>IJS_EUNKPARAM</entry> <entry>-9</entry> <entry>unknown parameter</entry></row> +<row><entry>IJS_EJOBID</entry> <entry>-10</entry> <entry>job id doesn't match</entry></row> +<row><entry>IJS_ETOOMANYJOBS</entry> <entry>-11</entry> <entry>reached limit of server's #jobs</entry></row> +<row><entry>IJS_EBUF</entry> <entry>-12</entry> <entry>buffer isn't big enough</entry></row> +</tbody> +</tgroup> +</table> + +<para> +However, I see that this list overlaps the status codes for IPP +operations (section 13.2 of <citation>RFC 2911</citation>) to a large extent. I am strongly +considering unifying these. +</para> + +</sect1> + +<sect1><title>Acknowledgements</title> + +<para> +IJS is directly inspired by the HPIJS work done by the HP Vancouver +team, particularly David Suffield. This spec also benefited from +comments and suggestions from Robert Krawitz, Grant Taylor, Glen +Petrie, Russell Lang, Michael Sweet, and the Omni team at IBM: Mark +VanderWiele, Mark Hamzy, and Pete Zannucci. +</para> + +<comment>Please add your name here. Incidentally, the <ackno> tag +of DocBook seems more reasonable than a section, but I can't get it +to format with a nice title. +</comment> +</sect1> + +<bibliography><title>References</title> +<biblioentry> + <abbrev>RFC 2911</abbrev> + <authorgroup> + <author><firstname>T.</firstname> <surname>Hastings</surname></author> + <author><firstname>R.</firstname> <surname>Herriot</surname></author> + <author><firstname>R.</firstname> <surname>deBry</surname></author> + <author><firstname>S.</firstname> <surname>Isaacson</surname></author> + <author><firstname>P.</firstname> <surname>Powell</surname></author> + </authorgroup> + + <title>Internet Printing Protocol/1.1: Model and Semantics</title> + <date>September 2000</date> +</biblioentry> + +<biblioentry> + <abbrev>IEEE1284</abbrev> + <title>IEEE Std.1284-1994 Standard Signaling Method for a + Bi-directional Parallel Peripheral Interface for Personal + Computers</title> + <date>1994</date> +</biblioentry> + +<biblioentry> + <abbrev>USBPrint</abbrev> + <title>Universal Serial Bus Device Class Definition for Printing Devices</title> + <edition>1.1</edition> + <date>January 2000</date> +</biblioentry> + +<biblioentry> + <abbrev>PLRM</abbrev> + <title>PostScript Language Reference</title> + <edition>third edition</edition> + <corpname>Adobe Systems Incorporated</corpname> + <publisher><publishername>Addison-Wesley</publishername></publisher> + <date>1999</date> +</biblioentry> + +<biblioentry> + <abbrev>PPD</abbrev> + <title>PostScript Printer Description File Format</title> + <edition>version 4.3</edition> + <corpname>Adobe Systems Incorporated</corpname> + <pubsnumber>Technical Note 5003</pubsnumber> + <date>9 February 1996</date> +</biblioentry> + +</bibliography> + + +</article> |