[thirdparty/cups.git] / doc / help / spec-command.html

<!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.css'>
</head>
<body>
<!--
  "$Id$"

  CUPS command file format specification for the Common UNIX Printing
  System (CUPS).

  Copyright 2007-2008 by Apple Inc.
  Copyright 1997-2006 by Easy Software Products.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

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