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