File: ijs_spec.sgml

package info (click to toggle)
ghostscript 8.71~dfsg2-9+squeeze1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 79,896 kB
  • ctags: 80,654
  • sloc: ansic: 501,432; sh: 25,689; python: 4,853; cpp: 3,633; perl: 3,597; tcl: 1,480; makefile: 1,187; lisp: 407; asm: 284; xml: 263; awk: 66; csh: 17; yacc: 15
file content (1099 lines) | stat: -rw-r--r-- 37,026 bytes parent folder | download | duplicates (18)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
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>