[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>The <var>&lt;cups/sidechannel.h&gt;</var> header file must be
included to use the <tt>CUPS_SC_</tt> constants and <tt>cupsSideChannel</tt> functions.</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>The <tt>cupsBackChannel</tt> functions require CUPS 1.2 or higher. The <tt>cupsSideChannel</tt> functions require CUPS 1.3 or higher.</p>


<h2 class='title'>Using the cupsBackChannel APIs</h2>

<p>The <tt>cupsBackChannel</tt> APIs allow your filters, drivers, and port monitors to read data back from a printer and your backends to send data from a printer to the filters, drivers, and port monitors associated with the current job. Back-channel data is normally sent by the printer in response to a command sent from your program to the printer via <tt>stdout</tt>.</p>

<p>The <tt>cupsBackChannelRead()</tt> function reads data from the printer via the backend. You provide a timeout in seconds along with a buffer pointer and the size of that buffer. It returns the number of bytes or -1 if there was an error. The following code example shows how to poll for back-channel data in your program:</p>

<pre class='command'>
#include &lt;cups/cups.h&gt;

char buffer[8192];
ssize_t bytes;

/* Use a timeout of 0.0 seconds to poll for back-channel data */
bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
</pre>

<p>If you are writing a backend, the <tt>cupsBackChannelWrite()</tt> function sends any back-channel data you have received from the printer to upstream filters in the print filter chain. We recommend using a timeout of 1.0 seconds:</p>

<pre class='command'>
#include &lt;cups/cups.h&gt;

char buffer[8192];
ssize_t bytes;

/* Use a timeout of 1.0 seconds to give filters a chance to read */
cupsBackChannelWrite(buffer, bytes, 1.0);
</pre>


<h2 class='title'>Using the cupsSideChannel APIs</h2>

<p>The <tt>cupsSideChannel</tt> APIs allow your filters, drivers, port monitors, and backend to send and receive the following out-of-band commands:</p>

<ul>

	<li><tt>CUPS_SC_CMD_SOFT_RESET</tt> -  Do a soft reset</li>
	<li><tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> -  Drain all pending output</li>
	<li><tt>CUPS_SC_CMD_GET_BIDI</tt> -  Return bidirectional capabilities</li>
	<li><tt>CUPS_SC_CMD_GET_DEVICE_ID</tt> -  Return the IEEE-1284 device ID</li>
	<li><tt>CUPS_SC_CMD_GET_STATE</tt> - Return the device state</li>

</ul>


<h3>Sending Commands from a Filter, Driver, or Port Monitor</h3>

<p>The <tt>cupsSideChannelDoRequest()</tt> function is used by filters, drivers, and port monitors to send a command to the backend and read back a response:</p>

<pre class='command'>
cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
                                          char *data, int *datalen,
                                          double timeout);
</pre>

<p>The <tt>CUPS_SC_CMD_SOFT_RESET</tt> and <tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> commands do not return any data values, while the others return one or more bytes. The <tt>timeout</tt> parameter allows your program to poll or wait for the command to complete - use a timeout of 30 seconds for <tt>CUPS_SC_CMD_SOFT_RESET</tt> and <tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> and a timeout of 1 second for all other commands.</p>

<p><tt>CUPS_SC_CMD_GET_BIDI</tt> returns a single <tt>char</tt> value that tells you whether the backend supports bidirectional communications:</p>

<pre class='command'>
#include &lt;cups/sidechannel.h&gt;

char data;
int datalen;
cups_sc_bidi_t bidi;
cups_sc_status_t status;

/* Tell cupsSideChannelDoRequest() how big our buffer is... */
datalen = 1;

/* Get the bidirectional capabilities, waiting for up to 1 second */
status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_BIDI, &amp;data, &amp;datalen, 1.0);

/* Use the returned value if OK was returned and the length is still 1 */
if (status == CUPS_SC_STATUS_OK && datalen == 1)
  bidi = (cups_sc_bidi_t)data;
else
  bidi = CUPS_SC_BIDI_NOT_SUPPORTED;
</pre>

<p><tt>CUPS_SC_CMD_GET_DEVICE_ID</tt> returns a string of characters containing the IEEE-1284 device ID for the connected printer:</p>

<pre class='command'>
#include &lt;cups/sidechannel.h&gt;

char data[2049];
int datalen;
cups_sc_status_t status;

/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
datalen = sizeof(data) - 1;

/* Get the IEEE-1284 device ID, waiting for up to 1 second */
status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &amp;datalen, 1.0);

/* Use the returned value if OK was returned and the length is non-zero */
if (status == CUPS_SC_STATUS_OK && datalen > 0)
  data[datalen] = '\0';
else
  data[0] = '\0';
</pre>

<p><tt>CUPS_SC_CMD_GET_STATE</tt> returns a single <tt>char</tt> value that tells you the current device state:</p>

<pre class='command'>
#include &lt;cups/sidechannel.h&gt;

char data;
int datalen;
cups_sc_state_t state;
cups_sc_status_t status;

/* Tell cupsSideChannelDoRequest() how big our buffer is... */
datalen = 1;

/* Get the bidirectional capabilities, waiting for up to 1 second */
status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_STATE, &amp;data, &amp;datalen, 1.0);

/* Use the returned value if OK was returned and the length is still 1 */
if (status == CUPS_SC_STATUS_OK && datalen == 1)
  state = (cups_sc_state_t)data;
else
  state = CUPS_SC_STATE_OFFLINE;
</pre>


<h3>Handling Commands in your Backend</h3>

<p>The <tt>cupsSideChannelRead()</tt> function is used by backends to read a command from a filter, driver, or port monitor:</p>

<pre class='command'>
int cupsSideChannelRead(cups_sc_command_t &amp;command,
                        cups_sc_status_t  &amp;status,
                        char *data, int *datalen, double timeout);
</pre>

<p>Backends can either poll for commands using a <tt>timeout</tt> of 0.0, wait indefinitely for commands using a <tt>timeout</tt> of -1.0 (probably in a separate thread for that purpose), or use <tt>select()</tt> or <tt>poll()</tt> on the <tt>CUPS_SC_FD</tt> file descriptor (4) to handle input and output on several file descriptors at the same time. Backends can pass <tt>NULL</tt> for the <tt>data</tt> and <tt>datalen</tt> parameters, since none of the commands sent by upstream filters contain any data at this time.</p>

<p>Once a command is processed, the backend uses the <tt>cupsSideChannelWrite()</tt> function to send its response:</p>

<pre class='command'>
#include &lt;cups/sidechannel.h&gt;

cups_sc_command_t command;
cups_sc_status_t status;

/* Poll for a command... */
if (!cupsSideChannelRead(&amp;command, &amp;status, NULL, NULL, 0.0))
{
  char data[2048];
  int datalen;

  switch (command)
  {
    ... handle supported commands, file data/datalen/status with values as needed ...

    default :
        status  = CUPS_SC_STATUS_NOT_IMPLEMENTED;
	datalen = 0;
	break;
  }

  /* Send a response... */
  cupsSideChannelWrite(command, status, data, datalen, 1.0);
}
</pre>
<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>
	<li><a href='#cupsSideChannelDoRequest'><tt>cupsSideChannelDoRequest()</tt></a> <span class='info'>&nbsp;CUPS 1.3&nbsp;</span></li>
	<li><a href='#cupsSideChannelRead'><tt>cupsSideChannelRead()</tt></a> <span class='info'>&nbsp;CUPS 1.3&nbsp;</span></li>
	<li><a href='#cupsSideChannelWrite'><tt>cupsSideChannelWrite()</tt></a> <span class='info'>&nbsp;CUPS 1.3&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>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'>&nbsp;CUPS 1.3&nbsp;</span><a name='cupsSideChannelDoRequest'>cupsSideChannelDoRequest()</a></h3>
<h4>Description</h4>
<p>Send a side-channel command to a backend and wait for a response.

This function is normally only called by filters, drivers, or port
monitors in order to communicate with the backend used by the current
printer.  Programs must be prepared to handle timeout or &quot;not
implemented&quot; status codes, which indicate that the backend or device
do not support the specified side-channel command.

The &quot;datalen&quot; parameter must be initialized to the size of the buffer
pointed to by the &quot;data&quot; parameter.  cupsSideChannelDoRequest() will
update the value to contain the number of data bytes in the buffer.

</p>
<h4>Syntax</h4>
<pre>
<a href='#cups_sc_status_t'>cups_sc_status_t</a>
cupsSideChannelDoRequest(
    cups_sc_command_t command,
    char * data,
    int * datalen,
    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>command</tt></td><td>Command to send</td></tr>
<tr><td><tt>data</tt></td><td>Response data buffer pointer</td></tr>
<tr><td><tt>datalen</tt></td><td>Size of data buffer on entry, number of bytes in buffer on return</td></tr>
<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
</tbody></table></div>
<h4>Returns</h4>
<p>Status of command</p>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'>&nbsp;CUPS 1.3&nbsp;</span><a name='cupsSideChannelRead'>cupsSideChannelRead()</a></h3>
<h4>Description</h4>
<p>Read a side-channel message.

This function is normally only called by backend programs to read
commands from a filter, driver, or port monitor program.  The
caller must be prepared to handle incomplete or invalid messages
and return the corresponding status codes.

The &quot;datalen&quot; parameter must be initialized to the size of the buffer
pointed to by the &quot;data&quot; parameter.  cupsSideChannelDoRequest() will
update the value to contain the number of data bytes in the buffer.

</p>
<h4>Syntax</h4>
<pre>
int
cupsSideChannelRead(
    cups_sc_command_t * command,
    <a href='#cups_sc_status_t'>cups_sc_status_t</a> * status,
    char * data,
    int * datalen,
    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>command</tt></td><td>Command code</td></tr>
<tr><td><tt>status</tt></td><td>Status code</td></tr>
<tr><td><tt>data</tt></td><td>Data buffer pointer</td></tr>
<tr><td><tt>datalen</tt></td><td>Size of data buffer on entry, number of bytes in buffer on return</td></tr>
<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
</tbody></table></div>
<h4>Returns</h4>
<p>0 on success, -1 on error</p>
<!-- NEW PAGE -->
<h3 class='title'><span class='info'>&nbsp;CUPS 1.3&nbsp;</span><a name='cupsSideChannelWrite'>cupsSideChannelWrite()</a></h3>
<h4>Description</h4>
<p>Write a side-channel message.

This function is normally only called by backend programs to send
responses to a filter, driver, or port monitor program.

</p>
<h4>Syntax</h4>
<pre>
int
cupsSideChannelWrite(
    cups_sc_command_t command,
    <a href='#cups_sc_status_t'>cups_sc_status_t</a> status,
    const char * data,
    int datalen,
    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>command</tt></td><td>Command code</td></tr>
<tr><td><tt>status</tt></td><td>Status code</td></tr>
<tr><td><tt>data</tt></td><td>Data buffer pointer</td></tr>
<tr><td><tt>datalen</tt></td><td>Number of bytes of data</td></tr>
<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
</tbody></table></div>
<h4>Returns</h4>
<p>0 on success, -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	<!--
f7faf1f5	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
f7deaa1a	55	<p>The <var><cups/sidechannel.h></var> header file must be
	56	included to use the <tt>CUPS_SC_</tt> constants and <tt>cupsSideChannel</tt> functions.</p>
	57
ef416fc2	58	<p>Programs using these functions must be linked to the CUPS
	59	library: <var>libcups.a</var>, <var>libcups.so.2</var>,
	60	<var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
	61	<var>libcups2.lib</var> depending on the platform. The following
	62	command compiles <var>myprogram.c</var> using GCC and the CUPS
	63	library:</p>
	64
	65	<pre class='command'>
	66	<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
	67	</pre>
	68
f7deaa1a	69
ef416fc2	70	<h2 class='title'>Compatibility</h2>
ef416fc2	71
f7deaa1a	72	<p>The <tt>cupsBackChannel</tt> functions require CUPS 1.2 or higher. The <tt>cupsSideChannel</tt> functions require CUPS 1.3 or higher.</p>
	73
	74
	75	<h2 class='title'>Using the cupsBackChannel APIs</h2>
	76
	77	<p>The <tt>cupsBackChannel</tt> APIs allow your filters, drivers, and port monitors to read data back from a printer and your backends to send data from a printer to the filters, drivers, and port monitors associated with the current job. Back-channel data is normally sent by the printer in response to a command sent from your program to the printer via <tt>stdout</tt>.</p>
	78
	79	<p>The <tt>cupsBackChannelRead()</tt> function reads data from the printer via the backend. You provide a timeout in seconds along with a buffer pointer and the size of that buffer. It returns the number of bytes or -1 if there was an error. The following code example shows how to poll for back-channel data in your program:</p>
	80
	81	<pre class='command'>
	82	#include <cups/cups.h>
	83
	84	char buffer[8192];
	85	ssize_t bytes;
	86
	87	/* Use a timeout of 0.0 seconds to poll for back-channel data */
	88	bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
	89	</pre>
	90
	91	<p>If you are writing a backend, the <tt>cupsBackChannelWrite()</tt> function sends any back-channel data you have received from the printer to upstream filters in the print filter chain. We recommend using a timeout of 1.0 seconds:</p>
	92
	93	<pre class='command'>
	94	#include <cups/cups.h>
	95
	96	char buffer[8192];
	97	ssize_t bytes;
	98
	99	/* Use a timeout of 1.0 seconds to give filters a chance to read */
	100	cupsBackChannelWrite(buffer, bytes, 1.0);
	101	</pre>
	102
	103
	104	<h2 class='title'>Using the cupsSideChannel APIs</h2>
	105
	106	<p>The <tt>cupsSideChannel</tt> APIs allow your filters, drivers, port monitors, and backend to send and receive the following out-of-band commands:</p>
	107
	108	<ul>
	109
	110	<li><tt>CUPS_SC_CMD_SOFT_RESET</tt> - Do a soft reset</li>
	111	<li><tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> - Drain all pending output</li>
	112	<li><tt>CUPS_SC_CMD_GET_BIDI</tt> - Return bidirectional capabilities</li>
	113	<li><tt>CUPS_SC_CMD_GET_DEVICE_ID</tt> - Return the IEEE-1284 device ID</li>
	114	<li><tt>CUPS_SC_CMD_GET_STATE</tt> - Return the device state</li>
	115
	116	</ul>
	117
	118
	119	<h3>Sending Commands from a Filter, Driver, or Port Monitor</h3>
	120
	121	<p>The <tt>cupsSideChannelDoRequest()</tt> function is used by filters, drivers, and port monitors to send a command to the backend and read back a response:</p>
	122
	123	<pre class='command'>
	124	cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
	125	char data, int datalen,
	126	double timeout);
	127	</pre>
	128
	129	<p>The <tt>CUPS_SC_CMD_SOFT_RESET</tt> and <tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> commands do not return any data values, while the others return one or more bytes. The <tt>timeout</tt> parameter allows your program to poll or wait for the command to complete - use a timeout of 30 seconds for <tt>CUPS_SC_CMD_SOFT_RESET</tt> and <tt>CUPS_SC_CMD_DRAIN_OUTPUT</tt> and a timeout of 1 second for all other commands.</p>
	130
	131	<p><tt>CUPS_SC_CMD_GET_BIDI</tt> returns a single <tt>char</tt> value that tells you whether the backend supports bidirectional communications:</p>
	132
	133	<pre class='command'>
	134	#include <cups/sidechannel.h>
	135
136	char data;
137	int datalen;
138	cups_sc_bidi_t bidi;
139	cups_sc_status_t status;
140
141	/* Tell cupsSideChannelDoRequest() how big our buffer is... */
142	datalen = 1;
143
144	/* Get the bidirectional capabilities, waiting for up to 1 second */
145	status = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_BIDI, &data, &datalen, 1.0);
146
147	/* Use the returned value if OK was returned and the length is still 1 */
148	if (status == CUPS_SC_STATUS_OK && datalen == 1)
149	bidi = (cups_sc_bidi_t)data;
150	else
151	bidi = CUPS_SC_BIDI_NOT_SUPPORTED;
152	</pre>
153
154	<p><tt>CUPS_SC_CMD_GET_DEVICE_ID</tt> returns a string of characters containing the IEEE-1284 device ID for the connected printer:</p>
155
156	<pre class='command'>
157	#include <cups/sidechannel.h>
158
159	char data[2049];
160	int datalen;
161	cups_sc_status_t status;
162
163	/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
164	datalen = sizeof(data) - 1;
165
166	/* Get the IEEE-1284 device ID, waiting for up to 1 second */
167	status = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0);
168
169	/* Use the returned value if OK was returned and the length is non-zero */
170	if (status == CUPS_SC_STATUS_OK && datalen > 0)
171	data[datalen] = '\0';
172	else
173	data[0] = '\0';
174	</pre>
175
176	<p><tt>CUPS_SC_CMD_GET_STATE</tt> returns a single <tt>char</tt> value that tells you the current device state:</p>
177
178	<pre class='command'>
179	#include <cups/sidechannel.h>
180
181	char data;
182	int datalen;
183	cups_sc_state_t state;
184	cups_sc_status_t status;
185
186	/* Tell cupsSideChannelDoRequest() how big our buffer is... */
187	datalen = 1;
188
189	/* Get the bidirectional capabilities, waiting for up to 1 second */
190	status = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_STATE, &data, &datalen, 1.0);
191
192	/* Use the returned value if OK was returned and the length is still 1 */
193	if (status == CUPS_SC_STATUS_OK && datalen == 1)
194	state = (cups_sc_state_t)data;
195	else
196	state = CUPS_SC_STATE_OFFLINE;
197	</pre>
198
199
200	<h3>Handling Commands in your Backend</h3>
201
202	<p>The <tt>cupsSideChannelRead()</tt> function is used by backends to read a command from a filter, driver, or port monitor:</p>
203
204	<pre class='command'>
205	int cupsSideChannelRead(cups_sc_command_t &command,
206	cups_sc_status_t &status,
207	char data, int datalen, double timeout);
208	</pre>
209
210	<p>Backends can either poll for commands using a <tt>timeout</tt> of 0.0, wait indefinitely for commands using a <tt>timeout</tt> of -1.0 (probably in a separate thread for that purpose), or use <tt>select()</tt> or <tt>poll()</tt> on the <tt>CUPS_SC_FD</tt> file descriptor (4) to handle input and output on several file descriptors at the same time. Backends can pass <tt>NULL</tt> for the <tt>data</tt> and <tt>datalen</tt> parameters, since none of the commands sent by upstream filters contain any data at this time.</p>
211
212	<p>Once a command is processed, the backend uses the <tt>cupsSideChannelWrite()</tt> function to send its response:</p>
213
214	<pre class='command'>
215	#include <cups/sidechannel.h>
216
217	cups_sc_command_t command;
218	cups_sc_status_t status;
219
220	/* Poll for a command... */
221	if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
222	{
223	char data[2048];
224	int datalen;
225
226	switch (command)
227	{
228	... handle supported commands, file data/datalen/status with values as needed ...
229
230	default :
231	status = CUPS_SC_STATUS_NOT_IMPLEMENTED;
232	datalen = 0;
233	break;
234	}
235
236	/* Send a response... */
237	cupsSideChannelWrite(command, status, data, datalen, 1.0);
238	}
239	</pre>
ef416fc2	240	<h2 class='title'>Contents</h2>
	241	<ul>
	242	<li><a href='#FUNCTIONS'>Functions</a></li>
	243	</ul>
	244	<!-- NEW PAGE -->
	245	<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
	246	<ul>
ecdc0628	247	<li><a href='#cupsBackChannelRead'><tt>cupsBackChannelRead()</tt></a> <span class='info'> CUPS 1.2 </span></li>
ecdc0628	248	<li><a href='#cupsBackChannelWrite'><tt>cupsBackChannelWrite()</tt></a> <span class='info'> CUPS 1.2 </span></li>
f7deaa1a	249	<li><a href='#cupsSideChannelDoRequest'><tt>cupsSideChannelDoRequest()</tt></a> <span class='info'> CUPS 1.3 </span></li>
	250	<li><a href='#cupsSideChannelRead'><tt>cupsSideChannelRead()</tt></a> <span class='info'> CUPS 1.3 </span></li>
	251	<li><a href='#cupsSideChannelWrite'><tt>cupsSideChannelWrite()</tt></a> <span class='info'> CUPS 1.3 </span></li>
ef416fc2	252	</ul>
ef416fc2	253	<!-- NEW PAGE -->
ecdc0628	254	<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsBackChannelRead'>cupsBackChannelRead()</a></h3>
ef416fc2	255	<h4>Description</h4>
	256	<p>Read data from the backchannel.
	257
	258	Reads up to "bytes" bytes from the backchannel. The "timeout"
	259	parameter controls how many seconds to wait for the data - use
	260	0.0 to return immediately if there is no data, -1.0 to wait
	261	for data indefinitely.
	262
	263	</p>
	264	<h4>Syntax</h4>
	265	<pre>
ecdc0628	266	ssize_t
ecdc0628	267	cupsBackChannelRead(
ef416fc2	268	char * buffer,
ecdc0628	269	size_t bytes,
ef416fc2	270	double timeout);
	271	</pre>
	272	<h4>Arguments</h4>
	273	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	274	<thead><tr><th>Name</th><th>Description</th></tr></thead>
	275	<tbody>
	276	<tr><td><tt>buffer</tt></td><td>Buffer to read</td></tr>
	277	<tr><td><tt>bytes</tt></td><td>Bytes to read</td></tr>
	278	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
	279	</tbody></table></div>
	280	<h4>Returns</h4>
	281	<p>Bytes read or -1 on error</p>
	282	<!-- NEW PAGE -->
ecdc0628	283	<h3 class='title'><span class='info'> CUPS 1.2 </span><a name='cupsBackChannelWrite'>cupsBackChannelWrite()</a></h3>
ef416fc2	284	<h4>Description</h4>
	285	<p>Write data to the backchannel.
	286
	287	Writes "bytes" bytes to the backchannel. The "timeout" parameter
	288	controls how many seconds to wait for the data to be written - use
	289	0.0 to return immediately if the data cannot be written, -1.0 to wait
	290	indefinitely.
	291
	292	</p>
	293	<h4>Syntax</h4>
	294	<pre>
ecdc0628	295	ssize_t
ecdc0628	296	cupsBackChannelWrite(
ef416fc2	297	const char * buffer,
ecdc0628	298	size_t bytes,
ef416fc2	299	double timeout);
	300	</pre>
	301	<h4>Arguments</h4>
	302	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	303	<thead><tr><th>Name</th><th>Description</th></tr></thead>
	304	<tbody>
	305	<tr><td><tt>buffer</tt></td><td>Buffer to write</td></tr>
	306	<tr><td><tt>bytes</tt></td><td>Bytes to write</td></tr>
	307	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
	308	</tbody></table></div>
	309	<h4>Returns</h4>
	310	<p>Bytes written or -1 on error</p>
f7deaa1a	311	<!-- NEW PAGE -->
	312	<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsSideChannelDoRequest'>cupsSideChannelDoRequest()</a></h3>
	313	<h4>Description</h4>
	314	<p>Send a side-channel command to a backend and wait for a response.
	315
	316	This function is normally only called by filters, drivers, or port
	317	monitors in order to communicate with the backend used by the current
	318	printer. Programs must be prepared to handle timeout or "not
	319	implemented" status codes, which indicate that the backend or device
	320	do not support the specified side-channel command.
	321
	322	The "datalen" parameter must be initialized to the size of the buffer
	323	pointed to by the "data" parameter. cupsSideChannelDoRequest() will
	324	update the value to contain the number of data bytes in the buffer.
	325
	326	</p>
	327	<h4>Syntax</h4>
	328	<pre>
	329	<a href='#cups_sc_status_t'>cups_sc_status_t</a>
	330	cupsSideChannelDoRequest(
	331	cups_sc_command_t command,
	332	char * data,
	333	int * datalen,
	334	double timeout);
	335	</pre>
	336	<h4>Arguments</h4>
	337	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	338	<thead><tr><th>Name</th><th>Description</th></tr></thead>
	339	<tbody>
	340	<tr><td><tt>command</tt></td><td>Command to send</td></tr>
	341	<tr><td><tt>data</tt></td><td>Response data buffer pointer</td></tr>
	342	<tr><td><tt>datalen</tt></td><td>Size of data buffer on entry, number of bytes in buffer on return</td></tr>
	343	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
	344	</tbody></table></div>
	345	<h4>Returns</h4>
	346	<p>Status of command</p>
	347	<!-- NEW PAGE -->
	348	<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsSideChannelRead'>cupsSideChannelRead()</a></h3>
	349	<h4>Description</h4>
	350	<p>Read a side-channel message.
	351
	352	This function is normally only called by backend programs to read
	353	commands from a filter, driver, or port monitor program. The
	354	caller must be prepared to handle incomplete or invalid messages
	355	and return the corresponding status codes.
	356
	357	The "datalen" parameter must be initialized to the size of the buffer
	358	pointed to by the "data" parameter. cupsSideChannelDoRequest() will
	359	update the value to contain the number of data bytes in the buffer.
	360
	361	</p>
	362	<h4>Syntax</h4>
	363	<pre>
	364	int
	365	cupsSideChannelRead(
	366	cups_sc_command_t * command,
	367	<a href='#cups_sc_status_t'>cups_sc_status_t</a> * status,
	368	char * data,
	369	int * datalen,
	370	double timeout);
	371	</pre>
	372	<h4>Arguments</h4>
	373	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
	374	<thead><tr><th>Name</th><th>Description</th></tr></thead>
375	<tbody>
376	<tr><td><tt>command</tt></td><td>Command code</td></tr>
377	<tr><td><tt>status</tt></td><td>Status code</td></tr>
378	<tr><td><tt>data</tt></td><td>Data buffer pointer</td></tr>
379	<tr><td><tt>datalen</tt></td><td>Size of data buffer on entry, number of bytes in buffer on return</td></tr>
380	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
381	</tbody></table></div>
382	<h4>Returns</h4>
383	<p>0 on success, -1 on error</p>
384	<!-- NEW PAGE -->
385	<h3 class='title'><span class='info'> CUPS 1.3 </span><a name='cupsSideChannelWrite'>cupsSideChannelWrite()</a></h3>
386	<h4>Description</h4>
387	<p>Write a side-channel message.
388
389	This function is normally only called by backend programs to send
390	responses to a filter, driver, or port monitor program.
391
392	</p>
393	<h4>Syntax</h4>
394	<pre>
395	int
396	cupsSideChannelWrite(
397	cups_sc_command_t command,
398	<a href='#cups_sc_status_t'>cups_sc_status_t</a> status,
399	const char * data,
400	int datalen,
401	double timeout);
402	</pre>
403	<h4>Arguments</h4>
404	<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
405	<thead><tr><th>Name</th><th>Description</th></tr></thead>
406	<tbody>
407	<tr><td><tt>command</tt></td><td>Command code</td></tr>
408	<tr><td><tt>status</tt></td><td>Status code</td></tr>
409	<tr><td><tt>data</tt></td><td>Data buffer pointer</td></tr>
410	<tr><td><tt>datalen</tt></td><td>Number of bytes of data</td></tr>
411	<tr><td><tt>timeout</tt></td><td>Timeout in seconds</td></tr>
412	</tbody></table></div>
413	<h4>Returns</h4>
414	<p>0 on success, -1 on error</p>
ef416fc2	415	</body>
ef416fc2	416	</html>