Tizen 2.1 basesubmit/tizen_2.1/20130424.225344submit/tizen/20130517.051336accepted/tizen_2.1/20130425.033012accepted/tizen/20130520.1018052.1b_releasetizen_2.1

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 &mdash; 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
+&ldquo;commands&rdquo;, 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 &ldquo;speaks&rdquo; 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 &ldquo;network order&rdquo;) 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 &ldquo;real&rdquo; 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
+&ldquo;dumb&rdquo; 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
+&ldquo;extension&rdquo; 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 &lt;ackno&gt; 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>