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