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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/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 Easy Software Products 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 missing or damaged please contact Easy Software Products
  at:

      Attn: CUPS Licensing Information
      Easy Software Products
      44141 Airport View Drive, Suite 204
      Hollywood, Maryland 20636 USA

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