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