doc/help/api-filter.html

   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 <!--
  19   "$Id$"
  20
  21   Filter and backend API introduction for the Common UNIX Printing System (CUPS).
  22
  23   Copyright 1997-2006 by Easy Software Products.
  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
  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>
  47
  48 <h2 class='title'>General Usage</h2>
  49
  50 <p>The <var>&lt;cups/backend.h&gt;</var> and
  51 <var>&lt;cups/cups.h&gt;</var> header files must be included to
  52 use the <tt>CUPS_BACKEND_</tt> constants and
  53 <tt>cupsBackChannel</tt> functions, respectively.</p>
  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>
  76         <li><a href='#cupsBackChannelRead'><tt>cupsBackChannelRead()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
  77         <li><a href='#cupsBackChannelWrite'><tt>cupsBackChannelWrite()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
  78 </ul>
  79 <!-- NEW PAGE -->
  80 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsBackChannelRead'>cupsBackChannelRead()</a></h3>
  81 <h4>Description</h4>
  82 <p>Read data from the backchannel.
  83
  84 Reads up to &quot;bytes&quot; bytes from the backchannel. The &quot;timeout&quot;
  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>
  92 ssize_t
  93 cupsBackChannelRead(
  94     char * buffer,
  95     size_t bytes,
  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 -->
 109 <h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsBackChannelWrite'>cupsBackChannelWrite()</a></h3>
 110 <h4>Description</h4>
 111 <p>Write data to the backchannel.
 112
 113 Writes &quot;bytes&quot; bytes to the backchannel. The &quot;timeout&quot; 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>
 121 ssize_t
 122 cupsBackChannelWrite(
 123     const char * buffer,
 124     size_t bytes,
 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>