Merge changes from CUPS 1.4svn-r7874.
[thirdparty/cups.git] / doc / help / spec-command.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2 <html>
3 <!-- SECTION: Specifications -->
4 <head>
5         <title>CUPS Command File Format</title>
6         <meta name='keywords' content='Programming, CUPS Command File Format'>
7         <link rel='stylesheet' type='text/css' href='../cups.css'>
8 </head>
9 <body>
10 <!--
11   "$Id$"
12
13   CUPS command file format specification for the Common UNIX Printing
14   System (CUPS).
15
16   Copyright 2007-2008 by Apple Inc.
17   Copyright 1997-2006 by Easy Software Products.
18
19   These coded instructions, statements, and computer programs are the
20   property of Apple Inc. and are protected by Federal copyright
21   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
22   which should have been included with this file.  If this file is
23   file is missing or damaged, see the license at "http://www.cups.org/".
24 -->
25
26 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
27
28 <p>This specification describes the CUPS command file format
29 (application/vnd.cups-command) which is used to send printer
30 maintenance commands to a printer in a device-independent way.
31 The current specification supports basic maintenance functions
32 such as head cleaning and self-test pages.</p>
33
34 <p>Printer drivers advertise support for the CUPS command file
35 format by providing a filter for the
36 <var>application/vnd.cups-command</var> file type. Applications
37 can determine if a printer supports printing of CUPS command
38 files by checking the <code>printer-type</code> attribute for the
39 <code>CUPS_PRINTER_COMMANDS</code> capability bit.</p>
40
41 <p>In addition, the PPD file for a printer can contain a
42 <code>cupsCommands</code> keyword that provides a list of supported
43 commands separated by spaces, for example:</p>
44
45 <pre class='command'>
46 *cupsCommand: "AutoConfigure Clean PrintSelfTestPage ReportLevels"
47 </pre>
48
49 <p>If no <code>cupsCommands</code> keyword is provided, the command filter
50 must support <a href='#AutoConfigure'><code>AutoConfigure</code></a>,
51 <a href='#Clean'><code>Clean</code></a>,
52 <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>,
53 and <a href='#ReportLevels'><code>ReportLevels</code></a>. The scheduler also
54 provides the <code>printer-commands</code> attribute containing the list of
55 supported commands.</p>
56
57
58 <h2 class='title'><a name='SYNTAX'>File Syntax</a></h2>
59
60 <p>CUPS command files are ASCII text files.  The first line of a
61 CUPS command file MUST contain:</p>
62
63 <pre class='command'>
64 #CUPS-COMMAND
65 </pre>
66
67 <p>After that, each line is either a command or a comment.
68 Comments begin with the # character, e.g.:</p>
69
70 <pre class='command'>
71 # This is a comment
72 </pre>
73
74 <p>Commands are any sequence of letters, numbers, and punctuation characters
75 optionally followed by parameters separated by whitespace, e.g.:</p>
76
77 <pre class='command'>
78 Clean all
79 PrintSelfTestPage
80 </pre>
81
82 <p>Command names are case-insensitive, so "PRINTSELFTESTPAGE",
83 "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific
84 commands should use a domain name prefix, e.g.:</p>
85
86 <pre class='command'>
87 com.vendor.foo
88 com.vendor.bar param param2 ... paramN
89 </pre>
90
91
92 <h2 class='title'><a name='COMMANDS'>Standard Commands</a></h2>
93
94 <p>The following are the standard commands supported by the format. The only
95 required command is
96 <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>.</p>
97
98
99 <h3><a name='AutoConfigure'>AutoConfigure</a></h3>
100
101 <p class='summary'>AutoConfigure</p>
102
103 <p>The <code>AutoConfigure</code> command updates the printer's PPD file
104 and driver state information to reflect the current configuration of the
105 printer. There are no arguments for this command.</p>
106
107 <p>Example:</p>
108
109 <pre class='command'>
110 #CUPS-COMMAND
111 AutoConfigure
112 </pre>
113
114
115 <h3><a name='Clean'>Clean</a></h3>
116
117 <p class='summary'>Clean <i>colorname</i></p>
118
119 <p>The <code>Clean</code> command performs a standard print head cleaning. The
120 "colorname" parameter specifies which color or head to clean. If a printer does
121 not support cleaning of individual colors or cartridges, then all colors are
122 cleaned. Command filters MUST support the "all" colorname. Other standard color
123 names include "black", "color", "photo", "cyan", "magenta", "yellow",
124 "light-cyan", "light-magenta", "light-black", "light-gray", and "dark-gray".</p>
125
126 <p>Example:</p>
127
128 <pre class='command'>
129 #CUPS-COMMAND
130 Clean all
131 </pre>
132
133
134 <h3><a name='PrintAlignmentPage'>PrintAlignmentPage</a></h3>
135
136 <p class='summary'>PrintAlignmentPage pass</p>
137
138 <p>The <code>PrintAlignmentPage</code> command prints a head alignment page on
139 the printer. The "pass" parameter provides a pass number from 1 to N. The number
140 of passes is device-dependent.</p>
141
142 <p>Example:</p>
143
144 <pre class='command'>
145 #CUPS-COMMAND
146 PrintAlignmentPage 1
147 </pre>
148
149
150 <h3><a name='PrintSelfTestPage'>PrintSelfTestPage</a></h3>
151
152 <p class='summary'>PrintSelfTestPage</p>
153
154 <p>The <code>PrintSelfTestPage</code> command prints a self-test page on the
155 printer. Typically this page shows whether all jets on a print head are
156 functioning and that the print feed mechanisms are working properly.</p>
157
158 <p>Example:</p>
159
160 <pre class='command'>
161 #CUPS-COMMAND
162 PrintSelfTestPage
163 </pre>
164
165
166 <h3><a name='ReportLevels'>ReportLevels</a></h3>
167
168 <p class='summary'>ReportLevels</p>
169
170 <p>The <code>ReportLevels</code> command queries the supply levels on a printer
171 and reports "marker-colors", "marker-levels", "marker-names", and
172 "marker-types" attributes using "ATTR:" messages sent to the scheduler.</p>
173
174 <p>Example:</p>
175
176 <pre class='command'>
177 #CUPS-COMMAND
178 ReportLevels
179 </pre>
180
181
182 <h3><a name='SetAlignment'>SetAlignment</a></h3>
183
184 <p class='summary'>SetAlignment pass value ... valueN</p>
185
186 <p>The <code>SetAlignment</code> command sets print head alignment values. The
187 "pass" parameter is a number from 1 to N. All parameters are
188 device-dependent.</p>
189
190 <p>Example:</p>
191
192 <pre class='command'>
193 #CUPS-COMMAND
194 SetAlignment 1 14
195 </pre>
196
197
198 </body>
199 </html>