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