[thirdparty/cups.git] / doc / help / api-filter.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
	<title>Filter and Backend APIs</title>
	<meta name='keywords' content='Programming'>
	<meta name='creator' content='Mini-XML v2.3'>
	<style type='text/css'><!--
	h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
	tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
	pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
	span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
	h3 span.info { float: right; font-size: 100%; }
	h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
	--></style>
</head>
<body>
<!--
  "$Id: api-filter.shtml 5138 2006-02-21 10:49:06Z mike $"

  Filter and backend API introduction for the Common UNIX Printing System (CUPS).

  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'>Introduction</h2>

<p>The CUPS filter and backend APIs define standard exit codes
and provide access to the backchannel data stream. They are only
used when writing backends, filters, and port monitors.</p>

<h2 class='title'>General Usage</h2>

<p>The <var>&lt;cups/backend.h&gt;</var> and
<var>&lt;cups/cups.h&gt;</var> header files must be included to
use the <tt>CUPS_BACKEND_</tt> constants and
<tt>cupsBackChannel</tt> functions, respectively.</p>

<p>Programs using these functions must be linked to the CUPS
library: <var>libcups.a</var>, <var>libcups.so.2</var>,
<var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
<var>libcups2.lib</var> depending on the platform. The following
command compiles <var>myprogram.c</var> using GCC and the CUPS
library:</p>

<pre class='command'>
<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
</pre>

<h2 class='title'>Compatibility</h2>

<p>All of these functions require CUPS 1.2 or higher.</p>
<h2 class='title'>Contents</h2>
<ul>
	<li><a href='#FUNCTIONS'>Functions</a></li>
</ul>
<!-- NEW PAGE -->
<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
<ul>
	<li><a href='#cupsBackChannelRead'><tt>cupsBackChannelRead()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
	<li><a href='#cupsBackChannelWrite'><tt>cupsBackChannelWrite()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
</ul>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsBackChannelRead'>cupsBackChannelRead()</a></h3>
<h4>Description</h4>
<p>Read data from the backchannel.

Reads up to &quot;bytes&quot; bytes from the backchannel. The &quot;timeout&quot;
parameter controls how many seconds to wait for the data - use
0.0 to return immediately if there is no data, -1.0 to wait
for data indefinitely.

</p>
<h4>Syntax</h4>
<pre>
ssize_t
cupsBackChannelRead(
    char * buffer,
    size_t bytes,
    double timeout);
</pre>
<h4>Arguments</h4>
<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>buffer</tt></td><td>Buffer to read</td></tr>
<tr><td><tt>bytes</tt></td><td>Bytes to read</td></tr>
<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
</tbody></table></div>
<h4>Returns</h4>
<p>Bytes read or -1 on error</p>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsBackChannelWrite'>cupsBackChannelWrite()</a></h3>
<h4>Description</h4>
<p>Write data to the backchannel.

Writes &quot;bytes&quot; bytes to the backchannel. The &quot;timeout&quot; parameter
controls how many seconds to wait for the data to be written - use
0.0 to return immediately if the data cannot be written, -1.0 to wait
indefinitely.

</p>
<h4>Syntax</h4>
<pre>
ssize_t
cupsBackChannelWrite(
    const char * buffer,
    size_t bytes,
    double timeout);
</pre>
<h4>Arguments</h4>
<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
<thead><tr><th>Name</th><th>Description</th></tr></thead>
<tbody>
<tr><td><tt>buffer</tt></td><td>Buffer to write</td></tr>
<tr><td><tt>bytes</tt></td><td>Bytes to write</td></tr>
<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
</tbody></table></div>
<h4>Returns</h4>
<p>Bytes written or -1 on error</p>
</body>
</html>
Commit	Line	Data
ef416fc2	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
	2	<html>
	3	<!-- SECTION: Programming -->
	4	<head>
	5	<title>Filter and Backend APIs</title>
	6	<meta name='keywords' content='Programming'>
	7	<meta name='creator' content='Mini-XML v2.3'>
	8	<style type='text/css'><!--
	9	h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
	10	tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
	11	pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
	12	span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
	13	h3 span.info { float: right; font-size: 100%; }
	14	h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
	15	--></style>
	16	</head>
	17	<body>
	18	<!--
b423cd4c	19	"$Id: api-filter.shtml 5138 2006-02-21 10:49:06Z mike $"
ef416fc2	20
	21	Filter and backend API introduction for the Common UNIX Printing System (CUPS).
	22
ecdc0628	23	Copyright 1997-2006 by Easy Software Products.
ef416fc2	24
	25	These coded instructions, statements, and computer programs are the
	26	property of Easy Software Products and are protected by Federal
	27	copyright law. Distribution and use rights are outlined in the file
	28	"LICENSE.txt" which should have been included with this file. If this
	29	file is missing or damaged please contact Easy Software Products
	30	at:
	31
	32	Attn: CUPS Licensing Information
	33	Easy Software Products
	34	44141 Airport View Drive, Suite 204
	35	Hollywood, Maryland 20636 USA
	36
	37	Voice: (301) 373-9600
	38	EMail: cups-info@cups.org
	39	WWW: http://www.cups.org
	40	-->
	41
	42	<h2 class='title'>Introduction</h2>
	43
ecdc0628	44	<p>The CUPS filter and backend APIs define standard exit codes
	45	and provide access to the backchannel data stream. They are only
	46	used when writing backends, filters, and port monitors.</p>
ef416fc2	47
	48	<h2 class='title'>General Usage</h2>
	49
	50	<p>The <var><cups/backend.h></var> and
	51	<var><cups/cups.h></var> header files must be included to
	52	use the <tt>CUPS_BACKEND_</tt> constants and
ecdc0628	53	<tt>cupsBackChannel</tt> functions, respectively.</p>
ef416fc2	54
	55	<p>Programs using these functions must be linked to the CUPS
	56	library: <var>libcups.a</var>, <var>libcups.so.2</var>,
	57	<var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
	58	<var>libcups2.lib</var> depending on the platform. The following
	59	command compiles <var>myprogram.c</var> using GCC and the CUPS
	60	library:</p>
	61
	62	<pre class='command'>
	63	<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
	64	</pre>
	65
	66	<h2 class='title'>Compatibility</h2>
	67
	68	<p>All of these functions require CUPS 1.2 or higher.</p>
	69	<h2 class='title'>Contents</h2>
	70	<ul>
	71	<li><a href='#FUNCTIONS'>Functions</a></li>
	72	</ul>
	73	<!-- NEW PAGE -->
	74	<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
	75	<ul>
ecdc0628	76	<li><a href='#cupsBackChannelRead'><tt>cupsBackChannelRead()</tt></a> <span class='info'> CUPS 1.2 </span></li>
ecdc0628	77	<li><a href='#cupsBackChannelWrite'><tt>cupsBackChannelWrite()</tt></a> <span class='info'> CUPS 1.2 </span></li>
ef416fc2	78	</ul>
ef416fc2	79	<!-- NEW PAGE -->
ecdc0628	80	<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsBackChannelRead'>cupsBackChannelRead()</a></h3>
ef416fc2	81	<h4>Description</h4>
	82	<p>Read data from the backchannel.
	83
	84	Reads up to "bytes" bytes from the backchannel. The "timeout"
	85	parameter controls how many seconds to wait for the data - use
	86	0.0 to return immediately if there is no data, -1.0 to wait
	87	for data indefinitely.
	88
	89	</p>
	90	<h4>Syntax</h4>
	91	<pre>
ecdc0628	92	ssize_t
ecdc0628	93	cupsBackChannelRead(
ef416fc2	94	char * buffer,
ecdc0628	95	size_t bytes,
ef416fc2	96	double timeout);
	97	</pre>
	98	<h4>Arguments</h4>
	99	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	100	<thead><tr><th>Name</th><th>Description</th></tr></thead>
	101	<tbody>
	102	<tr><td><tt>buffer</tt></td><td>Buffer to read</td></tr>
	103	<tr><td><tt>bytes</tt></td><td>Bytes to read</td></tr>
	104	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
	105	</tbody></table></div>
	106	<h4>Returns</h4>
	107	<p>Bytes read or -1 on error</p>
	108	<!-- NEW PAGE -->
ecdc0628	109	<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsBackChannelWrite'>cupsBackChannelWrite()</a></h3>
ef416fc2	110	<h4>Description</h4>
	111	<p>Write data to the backchannel.
	112
	113	Writes "bytes" bytes to the backchannel. The "timeout" parameter
	114	controls how many seconds to wait for the data to be written - use
	115	0.0 to return immediately if the data cannot be written, -1.0 to wait
	116	indefinitely.
	117
	118	</p>
	119	<h4>Syntax</h4>
	120	<pre>
ecdc0628	121	ssize_t
ecdc0628	122	cupsBackChannelWrite(
ef416fc2	123	const char * buffer,
ecdc0628	124	size_t bytes,
ef416fc2	125	double timeout);
	126	</pre>
	127	<h4>Arguments</h4>
	128	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	129	<thead><tr><th>Name</th><th>Description</th></tr></thead>
	130	<tbody>
	131	<tr><td><tt>buffer</tt></td><td>Buffer to write</td></tr>
	132	<tr><td><tt>bytes</tt></td><td>Bytes to write</td></tr>
	133	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
	134	</tbody></table></div>
	135	<h4>Returns</h4>
	136	<p>Bytes written or -1 on error</p>
	137	</body>
	138	</html>