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

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

  Copyright 2007-2009 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/".
-->

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