[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 CUPS.

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