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