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 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
  31 maintenance commands to a printer in a device-independent way.
  32 The current specification supports basic maintenance functions
  33 such as head cleaning and self-test pages and query functions
  34 such as auto-configure, report supply levels, and report status.</p>
  35
  36 <p>Printer drivers advertise support for the CUPS command file
  37 format by providing a filter for the
  38 <var>application/vnd.cups-command</var> file type. Applications
  39 can determine if a printer supports printing of CUPS command
  40 files 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
  45 commands 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
  52 must support <a href='#AutoConfigure'><code>AutoConfigure</code></a>,
  53 <a href='#Clean'><code>Clean</code></a>,
  54 <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>,
  55 and <a href='#ReportLevels'><code>ReportLevels</code></a>. The scheduler also
  56 provides the <code>printer-commands</code> attribute containing the list of
  57 supported 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
  63 CUPS 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.
  70 Comments 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
  77 optionally followed by parameters separated by whitespace, e.g.:</p>
  78
  79 <pre class='command'>
  80 Clean all
  81 PrintSelfTestPage
  82 </pre>
  83
  84 <p>Command names are case-insensitive, so "PRINTSELFTESTPAGE",
  85 "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific
  86 commands should use a domain name prefix, e.g.:</p>
  87
  88 <pre class='command'>
  89 com.vendor.foo
  90 com.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
  97 required 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
 106 and driver state information to reflect the current configuration of the
 107 printer. There are no arguments for this command.</p>
 108
 109 <p>Example:</p>
 110
 111 <pre class='command'>
 112 #CUPS-COMMAND
 113 AutoConfigure
 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
 123 not support cleaning of individual colors or cartridges, then all colors are
 124 cleaned. Command filters MUST support the "all" colorname. Other standard color
 125 names 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
 132 Clean 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
 141 the printer. The "pass" parameter provides a pass number from 1 to N. The number
 142 of passes is device-dependent.</p>
 143
 144 <p>Example:</p>
 145
 146 <pre class='command'>
 147 #CUPS-COMMAND
 148 PrintAlignmentPage 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
 157 printer. Typically this page shows whether all jets on a print head are
 158 functioning and that the print feed mechanisms are working properly.</p>
 159
 160 <p>Example:</p>
 161
 162 <pre class='command'>
 163 #CUPS-COMMAND
 164 PrintSelfTestPage
 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
 173 and reports "marker-colors", "marker-levels", "marker-names", and
 174 "marker-types" attributes using "ATTR:" messages sent to the scheduler. This
 175 command should also report the current printer status using "STATE:" messages
 176 like the <a href='#ReportStatus'><code>ReportStatus</code></a> command.</p>
 177
 178 <p>Example:</p>
 179
 180 <pre class='command'>
 181 #CUPS-COMMAND
 182 ReportLevels
 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
 191 status and reports it using "STATE:" messages sent to the scheduler.</p>
 192
 193 <p>Example:</p>
 194
 195 <pre class='command'>
 196 #CUPS-COMMAND
 197 ReportLevels
 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
 207 device-dependent.</p>
 208
 209 <p>Example:</p>
 210
 211 <pre class='command'>
 212 #CUPS-COMMAND
 213 SetAlignment 1 14
 214 </pre>
 215
 216
 217 </body>
 218 </html>