doc/help/spec-command.html

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