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