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