]>
Commit | Line | Data |
---|---|---|
745129be | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
b423cd4c | 2 | <html> |
4744bd90 | 3 | <!-- SECTION: Specifications --> |
b423cd4c | 4 | <head> |
5 | <title>CUPS Command File Format</title> | |
6 | <meta name='keywords' content='Programming, CUPS Command File Format'> | |
178cb736 | 7 | <link rel='stylesheet' type='text/css' href='../cups-printable.css'> |
b423cd4c | 8 | </head> |
9 | <body> | |
10 | <!-- | |
eac3a0a0 | 11 | CUPS command file format specification for CUPS. |
b423cd4c | 12 | |
dfe5f3b9 | 13 | Copyright © 2007-2018 by Apple Inc. |
53f8d64f | 14 | Copyright © 1997-2006 by Easy Software Products. |
b423cd4c | 15 | |
53f8d64f MS |
16 | Licensed under Apache License v2.0. See the file "LICENSE" for more |
17 | information. | |
b423cd4c | 18 | --> |
19 | ||
178cb736 MS |
20 | <H1 CLASS="title">CUPS Command File Format</H1> |
21 | ||
b423cd4c | 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 | |
26 | maintenance commands to a printer in a device-independent way. | |
27 | The current specification supports basic maintenance functions | |
8b116e60 MS |
28 | such as head cleaning and self-test pages and query functions |
29 | such as auto-configure, report supply levels, and report status.</p> | |
b423cd4c | 30 | |
31 | <p>Printer drivers advertise support for the CUPS command file | |
32 | format by providing a filter for the | |
33 | <var>application/vnd.cups-command</var> file type. Applications | |
34 | can determine if a printer supports printing of CUPS command | |
35 | files by checking the <code>printer-type</code> attribute for the | |
36 | <code>CUPS_PRINTER_COMMANDS</code> capability bit.</p> | |
37 | ||
01ce6322 MS |
38 | <p>In addition, the PPD file for a printer can contain a |
39 | <code>cupsCommands</code> keyword that provides a list of supported | |
40 | commands separated by spaces, for example:</p> | |
41 | ||
42 | <pre class='command'> | |
f594a3db | 43 | *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels ReportStatus" |
01ce6322 MS |
44 | </pre> |
45 | ||
46 | <p>If no <code>cupsCommands</code> keyword is provided, the command filter | |
47 | must support <a href='#AutoConfigure'><code>AutoConfigure</code></a>, | |
48 | <a href='#Clean'><code>Clean</code></a>, | |
49 | <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>, | |
50 | and <a href='#ReportLevels'><code>ReportLevels</code></a>. The scheduler also | |
51 | provides the <code>printer-commands</code> attribute containing the list of | |
52 | supported commands.</p> | |
53 | ||
54 | ||
b423cd4c | 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 | |
58 | CUPS 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. | |
65 | Comments begin with the # character, e.g.:</p> | |
66 | ||
67 | <pre class='command'> | |
68 | # This is a comment | |
69 | </pre> | |
70 | ||
01ce6322 MS |
71 | <p>Commands are any sequence of letters, numbers, and punctuation characters |
72 | optionally followed by parameters separated by whitespace, e.g.:</p> | |
73 | ||
74 | <pre class='command'> | |
75 | Clean all | |
76 | PrintSelfTestPage | |
77 | </pre> | |
78 | ||
79 | <p>Command names are case-insensitive, so "PRINTSELFTESTPAGE", | |
80 | "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific | |
81 | commands should use a domain name prefix, e.g.:</p> | |
82 | ||
83 | <pre class='command'> | |
84 | com.vendor.foo | |
85 | com.vendor.bar param param2 ... paramN | |
86 | </pre> | |
87 | ||
88 | ||
89 | <h2 class='title'><a name='COMMANDS'>Standard Commands</a></h2> | |
b423cd4c | 90 | |
01ce6322 MS |
91 | <p>The following are the standard commands supported by the format. The only |
92 | required command is | |
93 | <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>.</p> | |
b423cd4c | 94 | |
b423cd4c | 95 | |
01ce6322 | 96 | <h3><a name='AutoConfigure'>AutoConfigure</a></h3> |
b423cd4c | 97 | |
01ce6322 MS |
98 | <p class='summary'>AutoConfigure</p> |
99 | ||
100 | <p>The <code>AutoConfigure</code> command updates the printer's PPD file | |
101 | and driver state information to reflect the current configuration of the | |
102 | printer. There are no arguments for this command.</p> | |
103 | ||
104 | <p>Example:</p> | |
105 | ||
106 | <pre class='command'> | |
107 | #CUPS-COMMAND | |
108 | AutoConfigure | |
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 | |
118 | not support cleaning of individual colors or cartridges, then all colors are | |
119 | cleaned. Command filters MUST support the "all" colorname. Other standard color | |
120 | names include "black", "color", "photo", "cyan", "magenta", "yellow", | |
121 | "light-cyan", "light-magenta", "light-black", "light-gray", and "dark-gray".</p> | |
b423cd4c | 122 | |
123 | <p>Example:</p> | |
124 | ||
125 | <pre class='command'> | |
126 | #CUPS-COMMAND | |
127 | Clean all | |
128 | </pre> | |
129 | ||
01ce6322 MS |
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 | |
136 | the printer. The "pass" parameter provides a pass number from 1 to N. The number | |
137 | of passes is device-dependent.</p> | |
138 | ||
139 | <p>Example:</p> | |
140 | ||
141 | <pre class='command'> | |
142 | #CUPS-COMMAND | |
143 | PrintAlignmentPage 1 | |
144 | </pre> | |
145 | ||
146 | ||
147 | <h3><a name='PrintSelfTestPage'>PrintSelfTestPage</a></h3> | |
b423cd4c | 148 | |
149 | <p class='summary'>PrintSelfTestPage</p> | |
150 | ||
01ce6322 MS |
151 | <p>The <code>PrintSelfTestPage</code> command prints a self-test page on the |
152 | printer. Typically this page shows whether all jets on a print head are | |
153 | functioning and that the print feed mechanisms are working properly.</p> | |
b423cd4c | 154 | |
155 | <p>Example:</p> | |
156 | ||
157 | <pre class='command'> | |
158 | #CUPS-COMMAND | |
159 | PrintSelfTestPage | |
160 | </pre> | |
161 | ||
01ce6322 MS |
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 | |
168 | and reports "marker-colors", "marker-levels", "marker-names", and | |
8b116e60 MS |
169 | "marker-types" attributes using "ATTR:" messages sent to the scheduler. This |
170 | command should also report the current printer status using "STATE:" messages | |
171 | like the <a href='#ReportStatus'><code>ReportStatus</code></a> command.</p> | |
172 | ||
173 | <p>Example:</p> | |
174 | ||
175 | <pre class='command'> | |
176 | #CUPS-COMMAND | |
177 | ReportLevels | |
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 | |
186 | status and reports it using "STATE:" messages sent to the scheduler.</p> | |
01ce6322 MS |
187 | |
188 | <p>Example:</p> | |
189 | ||
190 | <pre class='command'> | |
191 | #CUPS-COMMAND | |
192 | ReportLevels | |
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 | |
202 | device-dependent.</p> | |
203 | ||
204 | <p>Example:</p> | |
205 | ||
206 | <pre class='command'> | |
207 | #CUPS-COMMAND | |
208 | SetAlignment 1 14 | |
209 | </pre> | |
210 | ||
211 | ||
b423cd4c | 212 | </body> |
213 | </html> |