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