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