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