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