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