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 27maintenance commands to a printer in a device-independent way. 28The current specification supports basic maintenance functions 29such as head cleaning and self-test pages and query functions 30such as auto-configure, report supply levels, and report status.</p> 31 32<p>Printer drivers advertise support for the CUPS command file 33format by providing a filter for the 34<var>application/vnd.cups-command</var> file type. Applications 35can determine if a printer supports printing of CUPS command 36files 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 41commands 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 48must support <a href='#AutoConfigure'><code>AutoConfigure</code></a>, 49<a href='#Clean'><code>Clean</code></a>, 50<a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>, 51and <a href='#ReportLevels'><code>ReportLevels</code></a>. The scheduler also 52provides the <code>printer-commands</code> attribute containing the list of 53supported 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 59CUPS 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. 66Comments 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 73optionally followed by parameters separated by whitespace, e.g.:</p> 74 75<pre class='command'> 76Clean all 77PrintSelfTestPage 78</pre> 79 80<p>Command names are case-insensitive, so "PRINTSELFTESTPAGE", 81"printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific 82commands should use a domain name prefix, e.g.:</p> 83 84<pre class='command'> 85com.vendor.foo 86com.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 93required 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 102and driver state information to reflect the current configuration of the 103printer. There are no arguments for this command.</p> 104 105<p>Example:</p> 106 107<pre class='command'> 108#CUPS-COMMAND 109AutoConfigure 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 119not support cleaning of individual colors or cartridges, then all colors are 120cleaned. Command filters MUST support the "all" colorname. Other standard color 121names 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 128Clean 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 137the printer. The "pass" parameter provides a pass number from 1 to N. The number 138of passes is device-dependent.</p> 139 140<p>Example:</p> 141 142<pre class='command'> 143#CUPS-COMMAND 144PrintAlignmentPage 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 153printer. Typically this page shows whether all jets on a print head are 154functioning and that the print feed mechanisms are working properly.</p> 155 156<p>Example:</p> 157 158<pre class='command'> 159#CUPS-COMMAND 160PrintSelfTestPage 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 169and reports "marker-colors", "marker-levels", "marker-names", and 170"marker-types" attributes using "ATTR:" messages sent to the scheduler. This 171command should also report the current printer status using "STATE:" messages 172like the <a href='#ReportStatus'><code>ReportStatus</code></a> command.</p> 173 174<p>Example:</p> 175 176<pre class='command'> 177#CUPS-COMMAND 178ReportLevels 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 187status and reports it using "STATE:" messages sent to the scheduler.</p> 188 189<p>Example:</p> 190 191<pre class='command'> 192#CUPS-COMMAND 193ReportLevels 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 203device-dependent.</p> 204 205<p>Example:</p> 206 207<pre class='command'> 208#CUPS-COMMAND 209SetAlignment 1 14 210</pre> 211 212 213</body> 214</html> 215