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