<li><a href="#EXITCODES">Exit Codes</a></li>
<li><a href="#ENVIRONMENT">Environment Variables</a></li>
<li><a href="#MESSAGES">Communicating with the Scheduler</a></li>
-<li><a href="#COMMUNICATING">Communicating with the Backend</a></li>
+<li><a href="#COMMUNICATING_BACKEND">Communicating with the Backend</a></li>
+<li><a href="#COMMUNICATING_FILTER">Communicating with Filters</a></li>
<li><a href="#SNMP">Doing SNMP Queries with Network Printers</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
<li><a href="#cupsBackendDeviceURI" title="Get the device URI for a backend.">cupsBackendDeviceURI</a></li>
<li><a href="#cupsSideChannelDoRequest" title="Send a side-channel command to a backend and wait for a response.">cupsSideChannelDoRequest</a></li>
<li><a href="#cupsSideChannelRead" title="Read a side-channel message.">cupsSideChannelRead</a></li>
+<li><a href="#cupsSideChannelSNMPGet" title="Query a SNMP OID's value.">cupsSideChannelSNMPGet</a></li>
+<li><a href="#cupsSideChannelSNMPWalk" title="Query multiple SNMP OID values.">cupsSideChannelSNMPWalk</a></li>
<li><a href="#cupsSideChannelWrite" title="Write a side-channel message.">cupsSideChannelWrite</a></li>
</ul>
<li><a href="#TYPES">Data Types</a><ul class="code">
<li><a href="#cups_sc_command_t" title="Request command codes">cups_sc_command_t</a></li>
<li><a href="#cups_sc_state_t" title="Printer state bits">cups_sc_state_t</a></li>
<li><a href="#cups_sc_status_t" title="Response status codes">cups_sc_status_t</a></li>
+ <li><a href="#cups_sc_walk_func_t" title="SNMP walk callback">cups_sc_walk_func_t</a></li>
</ul></li>
<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
<li><a href="#cups_backend_e" title="Backend exit codes">cups_backend_e</a></li>
</ul></li>
</ul>
<!--
- "$Id: api-filter.shtml 7288 2008-02-06 01:39:05Z mike $"
+ "$Id: api-filter.shtml 7502 2008-04-28 21:30:12Z mike $"
Filter and backend programming introduction for the Common UNIX Printing
System (CUPS).
#-copies to the job-media-sheets-completed attribute. The second
form sets the job-media-sheets-completed attribute to #-pages.</dd>
+ <dt>PPD: keyword=value [keyword=value ...]</dt>
+ <dd>Changes or adds keywords to the printer's PPD file. Typically
+ this is used to update installable options or default media settings
+ based on the printer configuration.</dd>
+
<dt>STATE: printer-state-reason [printer-state-reason ...]</dt>
<dt>STATE: + printer-state-reason [printer-state-reason ...]</dt>
<dt>STATE: - printer-state-reason [printer-state-reason ...]</dt>
<p>Messages without one of these prefixes are treated as if they began with
the "DEBUG:" prefix string.</p>
-<h3><a name="COMMUNICATING">Communicating with the Backend</a></h3>
+<h3><a name="COMMUNICATING_BACKEND">Communicating with the Backend</a></h3>
<p>Filters can communicate with the backend via the
<a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and
data[0] = '\0';
</pre>
+<h3><a name="COMMUNICATING_FILTER">Communicating with Filters</a></h3>
+
<p>Backends communicate with filters using the reciprocal functions
<a href="#cupsBackChannelWrite"><code>cupsBackChannelWrite</code></a>,
<a href="#cupsSideChannelRead"><code>cupsSideChannelRead</code></a>, and
indefinitely for commands using a <code>timeout</code> of -1.0 (probably in a
separate thread for that purpose), or use <code>select</code> or
<code>poll</code> on the <code>CUPS_SC_FD</code> file descriptor (4) to handle
-input and output on several file descriptors at the same time. Backends can pass
-<code>NULL</code> for the <code>data</code> and <code>datalen</code> parameters
-since none of the commands sent by upstream filters contain any data at this
-time.</p>
+input and output on several file descriptors at the same time.</p>
<p>Once a command is processed, the backend uses the
<a href="#cupsSideChannelWrite"><code>cupsSideChannelWrite</code></a> function
<a href="#cups_sc_command_t">cups_sc_command_t</a> command;
<a href="#cups_sc_status_t">cups_sc_status_t</a> status;
+char data[2048];
+int datalen = sizeof(data);
/* Poll for a command... */
-if (!<a href="#cupsSideChannelRead">cupsSideChannelRead</a>(&command, &status, NULL, NULL, 0.0))
+if (!<a href="#cupsSideChannelRead">cupsSideChannelRead</a>(&command, &status, data, &datalen, 0.0))
{
- char data[2048];
- int datalen;
-
switch (command)
{
- /* handle supported commands, file data/datalen/status with values as needed */
+ /* handle supported commands, fill data/datalen/status with values as needed */
default :
status = CUPS_SC_STATUS_NOT_IMPLEMENTED;
<h3><a name="SNMP">Doing SNMP Queries with Network Printers</a></h3>
-<p>Re-write for side-channel-based SNMP queries.</p>
-
-<!--
<p>The Simple Network Management Protocol (SNMP) allows you to get the current
status, page counter, and supply levels from most network printers. Every
piece of information is associated with an Object Identifier (OID), and
every printer has a <em>community</em> name associated with it. OIDs can be
queried directly or by "walking" over a range of OIDs with a common prefix.</p>
-<p>The CUPS SNMP functions provide a simple API for querying network printers.
-Queries are made using a datagram socket that is created using
-<a href="#cupsSNMPOpen"><code>cupsSNMPOpen</code></a> and destroyed using
-<a href="#cupsSNMPClose"><code>cupsSNMPClose</code></a>:</p>
-
-<pre class="example">
-#include <cups/snmp.h>
-
-int snmp = <a href="#cupsSNMPOpen">cupsSNMPOpen</a>(AF_INET);
-
-/* do some queries */
-
-<a href="#cupsSNMPClose">cupsSNMPClose</a>(snmp);
-</pre>
+<p>The two CUPS SNMP functions provide a simple API for querying network
+printers through the side-channel interface. Each accepts a string containing
+an OID like ".1.3.6.1.2.1.43.10.2.1.4.1.1" (the standard page counter OID)
+along with a timeout for the query.</p>
-<p>OIDs are simple C arrays of integers, terminated by a value of -1. For
-example, the page counter OID .1.3.6.1.2.1.43.10.2.1.4.1.1 would be:</p>
+<p>The <a href="#cupsSideChannelSNMPGet"><code>cupsSideChannelSNMPGet</code></a>
+function queries a single OID and returns the value as a string in a buffer
+you supply:</p>
<pre class="example">
-int page_counter_oid[] = { 1, 3, 6, 1, 2, 1, 43, 10, 2, 1, 4, 1, 1, -1 };
-</pre>
-
-<p>You send a query using
-<a href="#cupsSNMPWrite"><code>cupsSNMPWrite</code></a> and read the value back
-using <a href="#cupsSNMPRead"><code>cupsSNMPRead</code></a>. The value is read
-into a structure called <a href="#cups_snmp_t"><code>cups_snmp_t</code></a>:</p>
-
-<pre class="example">
-#include <cups/snmp.h>
+#include <cups/sidechannel.h>
-int page_counter_oid[] = { 1, 3, 6, 1, 2, 1, 43, 10, 2, 1, 4, 1, 1, -1 };
-http_addrlist_t *host = httpAddrGetList("myprinter", AF_UNSPEC, "161");
-int snmp = <a href="#cupsSNMPOpen">cupsSNMPOpen</a>(host->addr.addr.sa_family);
-<a href="#cups_snmp_t">cups_snmp_t</a> packet;
+char data[512];
+int datalen = sizeof(data);
-<a href="#cupsSNMPWrite">cupsSNMPWrite</a>(snmp, &(host->addr), CUPS_SNMP_VERSION_1,
- <a href="#cupsSNMPDefaultCommunity">cupsSNMPDefaultCommunity</a>(), CUPS_ASN1_GET_REQUEST, 1,
- page_counter_oid);
-if (<a href="#cupsSNMPRead">cupsSNMPRead</a>(snmp, &packet, 5000))
+if (<a href="#cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a>(".1.3.6.1.2.1.43.10.2.1.4.1.1", data, &datalen, 5.0)
+ == CUPS_SC_STATUS_OK)
{
/* Do something with the value */
- printf("Page counter is: %d\n", packet.object_value.integer);
+ printf("Page counter is: %s\n", data);
}
</pre>
-<p>The <a href="#cupsSNMPWalk"><code>cupsSNMPWalk</code></a> function allows you
-to query a whole group of OIDs, calling a function of your choice for each OID
-that is found:</p>
+<p>The
+<a href="#cupsSideChannelSNMPWalk"><code>cupsSideChannelSNMPWalk</code></a>
+function allows you to query a whole group of OIDs, calling a function of your
+choice for each OID that is found:</p>
<pre class="example">
-#include <cups/snmp.h>
+#include <cups/sidechannel.h>
void
-my_callback(<a href="#cups_snmp_t">cups_snmp_t</a> *packet, void *data)
+my_callback(const char *oid, const char *data, int datalen, void *context)
{
/* Do something with the value */
+ printf("%s=%s\n", oid, data);
}
-int printer_mib_oid[] = { 1, 3, 6, 1, 2, 1, 43, -1 };
-http_addrlist_t *host = httpAddrGetList("myprinter", AF_UNSPEC, "161");
-int snmp = <a href="#cupsSNMPOpen">cupsSNMPOpen</a>(host->addr.addr.sa_family);
+...
+
void *my_data;
-<a href="#cupsSNMPWalk">cupsSNMPWalk</a>(snmp, &(host->addr), CUPS_SNMP_VERSION_1,
- <a href="#cupsSNMPDefaultCommunity">cupsSNMPDefaultCommunity</a>(), printer_mib_oid, my_callback, my_data);
+<a href="#cupsSideChannelSNMPWalk">cupsSNMPSideChannelWalk</a>(".1.3.6.1.2.1.43", 5.0, my_callback, my_data);
</pre>
-
--><h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
+<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3>
<p class="description">Read data from the backchannel.</p>
<p class="code">
pointed to by the "data" parameter. cupsSideChannelDoRequest() will
update the value to contain the number of data bytes in the buffer.
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3>
+<p class="description">Query a SNMP OID's value.</p>
+<p class="code">
+<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br>
+ const char *oid,<br>
+ char *data,<br>
+ int *datalen,<br>
+ double timeout<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>oid</dt>
+<dd class="description">OID to query</dd>
+<dt>data</dt>
+<dd class="description">Buffer for OID value</dd>
+<dt>datalen</dt>
+<dd class="description">Size of OID buffer on entry, size of value on return</dd>
+<dt>timeout</dt>
+<dd class="description">Timeout in seconds</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Query status</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function asks the backend to do a SNMP OID query on behalf of the
+filter, port monitor, or backend using the default community name.<br>
+<br>
+"oid" contains a numeric OID consisting of integers separated by periods,
+for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not
+supported and must be converted to their numeric forms.<br>
+<br>
+On input, "data" and "datalen" provide the location and size of the
+buffer to hold the OID value as a string. HEX-String (binary) values are
+converted to hexadecimal strings representing the binary data, while
+NULL-Value and unknown OID types are returned as the empty string.
+The returned "datalen" does not include the trailing nul.
+
+<code>CUPS_SC_STATUS_NOT_IMPLEMENTED</code> is returned by backends that do not
+support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when
+the printer does not respond to the SNMP query.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3>
+<p class="description">Query multiple SNMP OID values.</p>
+<p class="code">
+<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br>
+ const char *oid,<br>
+ double timeout,<br>
+ <a href="#cups_sc_walk_func_t">cups_sc_walk_func_t</a> cb,<br>
+ void *context<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>oid</dt>
+<dd class="description">First numeric OID to query</dd>
+<dt>timeout</dt>
+<dd class="description">Timeout for each query in seconds</dd>
+<dt>cb</dt>
+<dd class="description">Function to call with each value</dd>
+<dt>context</dt>
+<dd class="description">Application-defined pointer to send to callback</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of first query of <code>CUPS_SC_STATUS_OK</code> on success</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function asks the backend to do multiple SNMP OID queries on behalf
+of the filter, port monitor, or backend using the default community name.
+All OIDs under the "parent" OID are queried and the results are sent to
+the callback function you provide.<br>
+<br>
+"oid" contains a numeric OID consisting of integers separated by periods,
+for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not
+supported and must be converted to their numeric forms.<br>
+<br>
+"timeout" specifies the timeout for each OID query. The total amount of
+time will depend on the number of OID values found and the time required
+for each query.<br>
+<br>
+"cb" provides a function to call for every value that is found. "context"
+is an application-defined pointer that is sent to the callback function
+along with the OID and current data. The data passed to the callback is the
+same as returned by <a href="#cupsSideChannelSNMPGet"><code>cupsSideChannelSNMPGet</code></a>.
+
+<code>CUPS_SC_STATUS_NOT_IMPLEMENTED</code> is returned by backends that do not
+support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when
+the printer does not respond to the first SNMP query.
+
</p>
<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3>
<p class="description">Write a side-channel message.</p>
<p class="code">
typedef enum <a href="#cups_sc_status_e">cups_sc_status_e</a> cups_sc_status_t;
</p>
+<h3 class="typedef"><a name="cups_sc_walk_func_t">cups_sc_walk_func_t</a></h3>
+<p class="description">SNMP walk callback</p>
+<p class="code">
+typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datalen, void *context);
+</p>
<h2 class="title"><a name="ENUMERATIONS">Constants</a></h2>
<h3 class="enumeration"><a name="cups_backend_e">cups_backend_e</a></h3>
<p class="description">Backend exit codes</p>
<dd class="description">Return the IEEE-1284 device ID</dd>
<dt>CUPS_SC_CMD_GET_STATE </dt>
<dd class="description">Return the device state</dd>
+<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4 </span></dt>
+<dd class="description">Query an SNMP OID </dd>
+<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4 </span></dt>
+<dd class="description">Query the next SNMP OID </dd>
<dt>CUPS_SC_CMD_SOFT_RESET </dt>
<dd class="description">Do a soft reset</dd>
</dl>
projects / thirdparty / cups.git / blobdiff