| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- SECTION: Specifications --> |
| <head> |
| <title>CUPS Command File Format</title> |
| <meta name='keywords' content='Programming, CUPS Command File Format'> |
| <link rel='stylesheet' type='text/css' href='../cups-printable.css'> |
| </head> |
| <body> |
| <!-- |
| CUPS command file format specification for CUPS. |
| |
| Copyright © 2007-2018 by Apple Inc. |
| Copyright © 1997-2006 by Easy Software Products. |
| |
| Licensed under Apache License v2.0. See the file "LICENSE" for more |
| information. |
| --> |
| |
| <H1 CLASS="title">CUPS Command File Format</H1> |
| |
| <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2> |
| |
| <p>This specification describes the CUPS command file format |
| (application/vnd.cups-command) which is used to send printer |
| maintenance commands to a printer in a device-independent way. |
| The current specification supports basic maintenance functions |
| such as head cleaning and self-test pages and query functions |
| such as auto-configure, report supply levels, and report status.</p> |
| |
| <p>Printer drivers advertise support for the CUPS command file |
| format by providing a filter for the |
| <var>application/vnd.cups-command</var> file type. Applications |
| can determine if a printer supports printing of CUPS command |
| files by checking the <code>printer-type</code> attribute for the |
| <code>CUPS_PRINTER_COMMANDS</code> capability bit.</p> |
| |
| <p>In addition, the PPD file for a printer can contain a |
| <code>cupsCommands</code> keyword that provides a list of supported |
| commands separated by spaces, for example:</p> |
| |
| <pre class='command'> |
| *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels ReportStatus" |
| </pre> |
| |
| <p>If no <code>cupsCommands</code> keyword is provided, the command filter |
| must support <a href='#AutoConfigure'><code>AutoConfigure</code></a>, |
| <a href='#Clean'><code>Clean</code></a>, |
| <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>, |
| and <a href='#ReportLevels'><code>ReportLevels</code></a>. The scheduler also |
| provides the <code>printer-commands</code> attribute containing the list of |
| supported commands.</p> |
| |
| |
| <h2 class='title'><a name='SYNTAX'>File Syntax</a></h2> |
| |
| <p>CUPS command files are ASCII text files. The first line of a |
| CUPS command file MUST contain:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| </pre> |
| |
| <p>After that, each line is either a command or a comment. |
| Comments begin with the # character, e.g.:</p> |
| |
| <pre class='command'> |
| # This is a comment |
| </pre> |
| |
| <p>Commands are any sequence of letters, numbers, and punctuation characters |
| optionally followed by parameters separated by whitespace, e.g.:</p> |
| |
| <pre class='command'> |
| Clean all |
| PrintSelfTestPage |
| </pre> |
| |
| <p>Command names are case-insensitive, so "PRINTSELFTESTPAGE", |
| "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific |
| commands should use a domain name prefix, e.g.:</p> |
| |
| <pre class='command'> |
| com.vendor.foo |
| com.vendor.bar param param2 ... paramN |
| </pre> |
| |
| |
| <h2 class='title'><a name='COMMANDS'>Standard Commands</a></h2> |
| |
| <p>The following are the standard commands supported by the format. The only |
| required command is |
| <a href='#PrintSelfTestPage'><code>PrintSelfTestPage</code></a>.</p> |
| |
| |
| <h3><a name='AutoConfigure'>AutoConfigure</a></h3> |
| |
| <p class='summary'>AutoConfigure</p> |
| |
| <p>The <code>AutoConfigure</code> command updates the printer's PPD file |
| and driver state information to reflect the current configuration of the |
| printer. There are no arguments for this command.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| AutoConfigure |
| </pre> |
| |
| |
| <h3><a name='Clean'>Clean</a></h3> |
| |
| <p class='summary'>Clean <i>colorname</i></p> |
| |
| <p>The <code>Clean</code> command performs a standard print head cleaning. The |
| "colorname" parameter specifies which color or head to clean. If a printer does |
| not support cleaning of individual colors or cartridges, then all colors are |
| cleaned. Command filters MUST support the "all" colorname. Other standard color |
| names include "black", "color", "photo", "cyan", "magenta", "yellow", |
| "light-cyan", "light-magenta", "light-black", "light-gray", and "dark-gray".</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| Clean all |
| </pre> |
| |
| |
| <h3><a name='PrintAlignmentPage'>PrintAlignmentPage</a></h3> |
| |
| <p class='summary'>PrintAlignmentPage pass</p> |
| |
| <p>The <code>PrintAlignmentPage</code> command prints a head alignment page on |
| the printer. The "pass" parameter provides a pass number from 1 to N. The number |
| of passes is device-dependent.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| PrintAlignmentPage 1 |
| </pre> |
| |
| |
| <h3><a name='PrintSelfTestPage'>PrintSelfTestPage</a></h3> |
| |
| <p class='summary'>PrintSelfTestPage</p> |
| |
| <p>The <code>PrintSelfTestPage</code> command prints a self-test page on the |
| printer. Typically this page shows whether all jets on a print head are |
| functioning and that the print feed mechanisms are working properly.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| PrintSelfTestPage |
| </pre> |
| |
| |
| <h3><a name='ReportLevels'>ReportLevels</a></h3> |
| |
| <p class='summary'>ReportLevels</p> |
| |
| <p>The <code>ReportLevels</code> command queries the supply levels on a printer |
| and reports "marker-colors", "marker-levels", "marker-names", and |
| "marker-types" attributes using "ATTR:" messages sent to the scheduler. This |
| command should also report the current printer status using "STATE:" messages |
| like the <a href='#ReportStatus'><code>ReportStatus</code></a> command.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| ReportLevels |
| </pre> |
| |
| |
| <h3><a name='ReportStatus'>ReportStatus</a></h3> |
| |
| <p class='summary'>ReportStatus</p> |
| |
| <p>The <code>ReportStatus</code> command queries the printer for its current |
| status and reports it using "STATE:" messages sent to the scheduler.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| ReportLevels |
| </pre> |
| |
| |
| <h3><a name='SetAlignment'>SetAlignment</a></h3> |
| |
| <p class='summary'>SetAlignment pass value ... valueN</p> |
| |
| <p>The <code>SetAlignment</code> command sets print head alignment values. The |
| "pass" parameter is a number from 1 to N. All parameters are |
| device-dependent.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| #CUPS-COMMAND |
| SetAlignment 1 14 |
| </pre> |
| |
| |
| </body> |
| </html> |