1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- SECTION: Programming --> 4<head> 5 <title>Filter and Backend Programming </title> 6 <meta name="keywords" content="Programming"> 7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 8 <meta name="creator" content="Mini-XML v2.7"> 9<style type="text/css"><!-- 10BODY { 11 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 12} 13 14H1, H2, H3, H4, H5, H6, P, TD, TH { 15 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 16} 17 18KBD { 19 font-family: monaco, courier, monospace; 20 font-weight: bold; 21} 22 23PRE { 24 font-family: monaco, courier, monospace; 25} 26 27PRE.command { 28 border: dotted thin #7f7f7f; 29 margin-left: 36pt; 30 padding: 10px; 31} 32 33P.compact { 34 margin: 0; 35} 36 37P.example { 38 font-style: italic; 39 margin-left: 36pt; 40} 41 42DL.man DD { 43 margin-left: 5em; 44} 45 46DL.man DT { 47 margin-left: 0; 48} 49 50PRE.man { 51 margin: 0; 52} 53 54PRE.example { 55 background: #eeeeee; 56 border: dotted thin #999999; 57 margin-left: 36pt; 58 padding: 10pt; 59} 60 61PRE.command EM, PRE.example EM { 62 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 63} 64 65P.command { 66 font-family: monaco, courier, monospace; 67 margin-left: 36pt; 68} 69 70P.formula { 71 font-style: italic; 72 margin-left: 36pt; 73} 74 75BLOCKQUOTE { 76 background: #eeeeee; 77 border: solid thin #999999; 78 padding: 10pt; 79} 80 81A IMG { 82 border: none; 83} 84 85A:link:hover IMG { 86 background: #f0f0f0; 87 border-radius: 10px; 88 -moz-border-radius: 10px; 89} 90 91A:link, A:visited { 92 font-weight: inherit; 93 text-decoration: none; 94} 95 96A:link:hover, A:visited:hover, A:active { 97 text-decoration: underline; 98} 99 100SUB, SUP { 101 font-size: 50%; 102} 103 104TR.data, TD.data, TR.data TD { 105 margin-top: 10pt; 106 padding: 5pt; 107 border-bottom: solid 1pt #999999; 108} 109 110TR.data TH { 111 border-bottom: solid 1pt #999999; 112 padding-top: 10pt; 113 padding-left: 5pt; 114 text-align: left; 115} 116 117DIV.table TABLE { 118 border: solid thin #999999; 119 border-collapse: collapse; 120 border-spacing: 0; 121 margin-left: auto; 122 margin-right: auto; 123} 124 125DIV.table CAPTION { 126 caption-side: top; 127 font-size: 120%; 128 font-style: italic; 129 font-weight: bold; 130 margin-left: auto; 131 margin-right: auto; 132} 133 134DIV.table TABLE TD { 135 border: solid thin #cccccc; 136 padding-top: 5pt; 137} 138 139DIV.table TABLE TH { 140 background: #cccccc; 141 border: none; 142 border-bottom: solid thin #999999; 143} 144 145DIV.figure TABLE { 146 margin-left: auto; 147 margin-right: auto; 148} 149 150DIV.figure CAPTION { 151 caption-side: bottom; 152 font-size: 120%; 153 font-style: italic; 154 font-weight: bold; 155 margin-left: auto; 156 margin-right: auto; 157} 158 159TH.label { 160 text-align: right; 161 vertical-align: top; 162} 163 164TH.sublabel { 165 text-align: right; 166 font-weight: normal; 167} 168 169HR { 170 border: solid thin; 171} 172 173SPAN.info { 174 background: black; 175 border: thin solid black; 176 color: white; 177 font-size: 80%; 178 font-style: italic; 179 font-weight: bold; 180 white-space: nowrap; 181} 182 183H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { 184 float: right; 185 font-size: 100%; 186} 187 188H1.title { 189} 190 191H2.title, H3.title { 192 border-bottom: solid 2pt #000000; 193} 194 195DIV.indent, TABLE.indent { 196 margin-top: 2em; 197 margin-left: auto; 198 margin-right: auto; 199 width: 90%; 200} 201 202TABLE.indent { 203 border-collapse: collapse; 204} 205 206TABLE.indent TD, TABLE.indent TH { 207 padding: 0; 208} 209 210TABLE.list { 211 border-collapse: collapse; 212 margin-left: auto; 213 margin-right: auto; 214 width: 90%; 215} 216 217TABLE.list TH { 218 background: white; 219 border-bottom: solid thin #cccccc; 220 color: #444444; 221 padding-top: 10pt; 222 padding-left: 5pt; 223 text-align: left; 224 vertical-align: bottom; 225 white-space: nowrap; 226} 227 228TABLE.list TH A { 229 color: #4444cc; 230} 231 232TABLE.list TD { 233 border-bottom: solid thin #eeeeee; 234 padding-top: 5pt; 235 padding-left: 5pt; 236} 237 238TABLE.list TR:nth-child(even) { 239 background: #f8f8f8; 240} 241 242TABLE.list TR:nth-child(odd) { 243 background: #f4f4f4; 244} 245 246DT { 247 margin-left: 36pt; 248 margin-top: 12pt; 249} 250 251DD { 252 margin-left: 54pt; 253} 254 255DL.category DT { 256 font-weight: bold; 257} 258 259P.summary { 260 margin-left: 36pt; 261 font-family: monaco, courier, monospace; 262} 263 264DIV.summary TABLE { 265 border: solid thin #999999; 266 border-collapse: collapse; 267 border-spacing: 0; 268 margin: 10px; 269} 270 271DIV.summary TABLE TD, DIV.summary TABLE TH { 272 border: solid thin #999999; 273 padding: 5px; 274 text-align: left; 275 vertical-align: top; 276} 277 278DIV.summary TABLE THEAD TH { 279 background: #eeeeee; 280} 281 282/* API documentation styles... */ 283div.body h1 { 284 margin: 0; 285} 286div.body h2 { 287 margin-top: 1.5em; 288} 289div.body h3, div.body h4, div.body h5 { 290 margin-bottom: 0.5em; 291 margin-top: 1.5em; 292} 293.class, .enumeration, .function, .struct, .typedef, .union { 294 border-bottom: solid thin #999999; 295 margin-bottom: 0; 296 margin-top: 2em; 297} 298.description { 299 margin-top: 0.5em; 300} 301code, p.code, pre, ul.code li { 302 font-family: monaco, courier, monospace; 303 font-size: 90%; 304} 305ul.code, ul.contents, ul.subcontents { 306 list-style-type: none; 307 margin: 0; 308 padding-left: 0; 309} 310ul.code li { 311 margin: 0; 312} 313ul.contents > li { 314 margin-top: 1em; 315} 316ul.contents li ul.code, ul.contents li ul.subcontents { 317 padding-left: 2em; 318} 319div.body dl { 320 margin-left: 0; 321 margin-top: 0; 322} 323div.body dt { 324 font-style: italic; 325 margin-left: 0; 326 margin-top: 0; 327} 328div.body dd { 329 margin-bottom: 0.5em; 330} 331 332/* This is just for the HTML files generated with the framedhelp target */ 333div.contents { 334 background: #e8e8e8; 335 border: solid thin black; 336 padding: 10px; 337} 338div.contents h1 { 339 font-size: 110%; 340} 341div.contents h2 { 342 font-size: 100%; 343} 344div.contents ul.contents { 345 font-size: 80%; 346} 347div.contents ul.subcontents li { 348 margin-left: 1em; 349 text-indent: -1em; 350} 351--></style> 352</head> 353<body> 354<div class='body'> 355<!-- 356 "$Id: api-filter.header 7616 2008-05-28 00:34:13Z mike $" 357 358 Filter and backend programming header for CUPS. 359 360 Copyright 2008-2014 by Apple Inc. 361 362 These coded instructions, statements, and computer programs are the 363 property of Apple Inc. and are protected by Federal copyright 364 law. Distribution and use rights are outlined in the file "LICENSE.txt" 365 which should have been included with this file. If this file is 366 file is missing or damaged, see the license at "http://www.cups.org/". 367--> 368 369<h1 class='title'>Filter and Backend Programming</h1> 370 371<div class='summary'><table summary='General Information'> 372<thead> 373<tr> 374 <th>Headers</th> 375 <th>cups/backend.h<br> 376 cups/sidechannel.h</th> 377</tr> 378</thead> 379<tbody> 380<tr> 381 <th>Library</th> 382 <td>-lcups</td> 383</tr> 384<tr> 385 <th>See Also</th> 386 <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br> 387 Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br> 388 Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br> 389 Programming: <a href='api-raster.html' target='_top'>Raster API</a><br> 390 Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br> 391 Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br> 392 Specifications: <a href='spec-design.html' target='_top'>CUPS Design Description</a></td> 393</tr> 394</tbody> 395</table></div> 396<h2 class="title">Contents</h2> 397<ul class="contents"> 398<li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> 399 <li><a href="#SECURITY">Security Considerations</a></li> 400 <li><a href="#SIGNALS">Canceled Jobs and Signal Handling</a></li> 401 <li><a href="#PERMISSIONS">File Permissions</a></li> 402 <li><a href="#TEMPFILES">Temporary Files</a></li> 403 <li><a href="#COPIES">Copy Generation</a></li> 404 <li><a href="#EXITCODES">Exit Codes</a></li> 405 <li><a href="#ENVIRONMENT">Environment Variables</a></li> 406 <li><a href="#MESSAGES">Communicating with the Scheduler</a></li> 407 <li><a href="#COMMUNICATING_BACKEND">Communicating with the Backend</a></li> 408 <li><a href="#COMMUNICATING_FILTER">Communicating with Filters</a></li> 409 <li><a href="#SNMP">Doing SNMP Queries with Network Printers</a></li> 410</ul></li> 411<li><a href="#SANDBOXING">Sandboxing on OS X</a></li> 412<li><a href="#FUNCTIONS">Functions</a><ul class="code"> 413 <li><a href="#cupsBackChannelRead" title="Read data from the backchannel.">cupsBackChannelRead</a></li> 414 <li><a href="#cupsBackChannelWrite" title="Write data to the backchannel.">cupsBackChannelWrite</a></li> 415 <li><a href="#cupsBackendDeviceURI" title="Get the device URI for a backend.">cupsBackendDeviceURI</a></li> 416 <li><a href="#cupsBackendReport" title="Write a device line from a backend.">cupsBackendReport</a></li> 417 <li><a href="#cupsSideChannelDoRequest" title="Send a side-channel command to a backend and wait for a response.">cupsSideChannelDoRequest</a></li> 418 <li><a href="#cupsSideChannelRead" title="Read a side-channel message.">cupsSideChannelRead</a></li> 419 <li><a href="#cupsSideChannelSNMPGet" title="Query a SNMP OID's value.">cupsSideChannelSNMPGet</a></li> 420 <li><a href="#cupsSideChannelSNMPWalk" title="Query multiple SNMP OID values.">cupsSideChannelSNMPWalk</a></li> 421 <li><a href="#cupsSideChannelWrite" title="Write a side-channel message.">cupsSideChannelWrite</a></li> 422</ul></li> 423<li><a href="#TYPES">Data Types</a><ul class="code"> 424 <li><a href="#cups_backend_t" title="Backend exit codes">cups_backend_t</a></li> 425 <li><a href="#cups_sc_bidi_t" title="Bidirectional capabilities">cups_sc_bidi_t</a></li> 426 <li><a href="#cups_sc_command_t" title="Request command codes">cups_sc_command_t</a></li> 427 <li><a href="#cups_sc_connected_t" title="Connectivity values">cups_sc_connected_t</a></li> 428 <li><a href="#cups_sc_state_t" title="Printer state bits">cups_sc_state_t</a></li> 429 <li><a href="#cups_sc_status_t" title="Response status codes">cups_sc_status_t</a></li> 430 <li><a href="#cups_sc_walk_func_t" title="SNMP walk callback">cups_sc_walk_func_t</a></li> 431</ul></li> 432<li><a href="#ENUMERATIONS">Constants</a><ul class="code"> 433 <li><a href="#cups_backend_e" title="Backend exit codes">cups_backend_e</a></li> 434 <li><a href="#cups_sc_bidi_e" title="Bidirectional capability values">cups_sc_bidi_e</a></li> 435 <li><a href="#cups_sc_command_e" title="Request command codes">cups_sc_command_e</a></li> 436 <li><a href="#cups_sc_connected_e" title="Connectivity values">cups_sc_connected_e</a></li> 437 <li><a href="#cups_sc_state_e" title="Printer state bits">cups_sc_state_e</a></li> 438 <li><a href="#cups_sc_status_e" title="Response status codes">cups_sc_status_e</a></li> 439</ul></li> 440</ul> 441<!-- 442 "$Id: api-filter.shtml 7677 2008-06-19 23:22:19Z mike $" 443 444 Filter and backend programming introduction for CUPS. 445 446 Copyright 2007-2014 by Apple Inc. 447 Copyright 1997-2006 by Easy Software Products, all rights reserved. 448 449 These coded instructions, statements, and computer programs are the 450 property of Apple Inc. and are protected by Federal copyright 451 law. Distribution and use rights are outlined in the file "LICENSE.txt" 452 which should have been included with this file. If this file is 453 file is missing or damaged, see the license at "http://www.cups.org/". 454--> 455 456<h2 class='title'><a name="OVERVIEW">Overview</a></h2> 457 458<p>Filters (which include printer drivers and port monitors) and backends 459are used to convert job files to a printable format and send that data to the 460printer itself. All of these programs use a common interface for processing 461print jobs and communicating status information to the scheduler. Each is run 462with a standard set of command-line arguments:<p> 463 464<dl class="code"> 465 466 <dt>argv[1]</dt> 467 <dd>The job ID</dd> 468 469 <dt>argv[2]</dt> 470 <dd>The user printing the job</dd> 471 472 <dt>argv[3]</dt> 473 <dd>The job name/title</dd> 474 475 <dt>argv[4]</dt> 476 <dd>The number of copies to print</dd> 477 478 <dt>argv[5]</dt> 479 <dd>The options that were provided when the job was submitted</dd> 480 481 <dt>argv[6]</dt> 482 <dd>The file to print (first program only)</dd> 483</dl> 484 485<p>The scheduler runs one or more of these programs to print any given job. The 486first filter reads from the print file and writes to the standard output, while 487the remaining filters read from the standard input and write to the standard 488output. The backend is the last filter in the chain and writes to the 489device.</p> 490 491<p>Filters are always run as a non-privileged user, typically "lp", with no 492connection to the user's desktop. Backends are run either as a non-privileged 493user or as root if the file permissions do not allow user or group execution. 494The <a href="#PERMISSIONS">file permissions</a> section talks about this in 495more detail.</p> 496 497<h3><a name="SECURITY">Security Considerations</a></h3> 498 499<p>It is always important to use security programming practices. Filters and 500most backends are run as a non-privileged user, so the major security 501consideration is resource utilization - filters should not depend on unlimited 502amounts of CPU, memory, or disk space, and should protect against conditions 503that could lead to excess usage of any resource like infinite loops and 504unbounded recursion. In addition, filters must <em>never</em> allow the user to 505specify an arbitrary file path to a separator page, template, or other file 506used by the filter since that can lead to an unauthorized disclosure of 507information. <em>Always</em> treat input as suspect and validate it!</p> 508 509<p>If you are developing a backend that runs as root, make sure to check for 510potential buffer overflows, integer under/overflow conditions, and file 511accesses since these can lead to privilege escalations. When writing files, 512always validate the file path and <em>never</em> allow a user to determine 513where to store a file.</p> 514 515<blockquote><b>Note:</b> 516 517<p><em>Never</em> write files to a user's home directory. Aside from the 518security implications, CUPS is a network print service and as such the network 519user may not be the same as the local user and/or there may not be a local home 520directory to write to.</p> 521 522<p>In addition, some operating systems provide additional security mechanisms 523that further limit file system access, even for backends running as root. On 524OS X, for example, no backend may write to a user's home directory. See the <a href="#SANDBOXING">Sandboxing on OS X</a> section for more information.</p> 525</blockquote> 526 527<h3><a name="SIGNALS">Canceled Jobs and Signal Handling</a></h3> 528 529<p>The scheduler sends <code>SIGTERM</code> when a printing job is canceled or 530held. Filters, backends, and port monitors <em>must</em> catch 531<code>SIGTERM</code> and perform any cleanup necessary to produce a valid output 532file or return the printer to a known good state. The recommended behavior is to 533end the output on the current page, preferably on the current line or object 534being printed.</p> 535 536<p>Filters and backends may also receive <code>SIGPIPE</code> when an upstream or downstream filter/backend exits with a non-zero status. Developers should generally ignore <code>SIGPIPE</code> at the beginning of <code>main()</code> with the following function call:</p> 537 538<pre class="example"> 539#include <signal.h>> 540 541... 542 543int 544main(int argc, char *argv[]) 545{ 546 signal(SIGPIPE, SIG_IGN); 547 548 ... 549} 550</pre> 551 552<h3><a name="PERMISSIONS">File Permissions</a></h3> 553 554<p>For security reasons, CUPS will only run filters and backends that are owned 555by root and do not have world or group write permissions. The recommended 556permissions for filters and backends are 0555 - read and execute but no write. 557Backends that must run as root should use permissions of 0500 - read and execute 558by root, no access for other users. Write permissions can be enabled for the 559root user only.</p> 560 561<p>To avoid a warning message, the directory containing your filter(s) must also 562be owned by root and have world and group write disabled - permissions of 0755 563or 0555 are strongly encouraged.</p> 564 565<h3><a name="TEMPFILES">Temporary Files</a></h3> 566 567<p>Temporary files should be created in the directory specified by the 568"TMPDIR" environment variable. The 569<a href="#cupsTempFile2"><code>cupsTempFile2</code></a> function can be 570used to safely create temporary files in this directory.</p> 571 572<h3><a name="COPIES">Copy Generation</a></h3> 573 574<p>The <code>argv[4]</code> argument specifies the number of copies to produce 575of the input file. In general, you should only generate copies if the 576<em>filename</em> argument is supplied. The only exception to this are 577filters that produce device-independent PostScript output, since the PostScript 578filter <var>pstops</var> is responsible for generating copies of PostScript 579files.</p> 580 581<h3><a name="EXITCODES">Exit Codes</a></h3> 582 583<p>Filters must exit with status 0 when they successfully generate print data 584or 1 when they encounter an error. Backends can return any of the 585<a href="#cups_backend_t"><code>cups_backend_t</code></a> constants.</p> 586 587<h3><a name="ENVIRONMENT">Environment Variables</a></h3> 588 589<p>The following environment variables are defined by the printing system 590when running print filters and backends:</p> 591 592<dl class="code"> 593 594 <dt>APPLE_LANGUAGE</dt> 595 <dd>The Apple language identifier associated with the job 596 (OS X only).</dd> 597 598 <dt>CHARSET</dt> 599 <dd>The job character set, typically "utf-8".</dd> 600 601 <dt>CLASS</dt> 602 <dd>When a job is submitted to a printer class, contains the name of 603 the destination printer class. Otherwise this environment 604 variable will not be set.</dd> 605 606 <dt>CONTENT_TYPE</dt> 607 <dd>The MIME type associated with the file (e.g. 608 application/postscript).</dd> 609 610 <dt>CUPS_CACHEDIR</dt> 611 <dd>The directory where cache files can be stored. Cache files can be 612 used to retain information between jobs or files in a job.</dd> 613 614 <dt>CUPS_DATADIR</dt> 615 <dd>The directory where (read-only) CUPS data files can be found.</dd> 616 617 <dt>CUPS_FILETYPE</dt> 618 <dd>The type of file being printed: "job-sheet" for a banner page and 619 "document" for a regular print file.</dd> 620 621 <dt>CUPS_SERVERROOT</dt> 622 <dd>The root directory of the server.</dd> 623 624 <dt>DEVICE_URI</dt> 625 <dd>The device-uri associated with the printer.</dd> 626 627 <dt>FINAL_CONTENT_TYPE</dt> 628 <dd>The MIME type associated with the printer (e.g. 629 application/vnd.cups-postscript).</dd> 630 631 <dt>LANG</dt> 632 <dd>The language locale associated with the job.</dd> 633 634 <dt>PPD</dt> 635 <dd>The full pathname of the PostScript Printer Description (PPD) 636 file for this printer.</dd> 637 638 <dt>PRINTER</dt> 639 <dd>The queue name of the class or printer.</dd> 640 641 <dt>RIP_CACHE</dt> 642 <dd>The recommended amount of memory to use for Raster Image 643 Processors (RIPs).</dd> 644 645 <dt>TMPDIR</dt> 646 <dd>The directory where temporary files should be created.</dd> 647 648</dl> 649 650<h3><a name="MESSAGES">Communicating with the Scheduler</a></h3> 651 652<p>Filters and backends communicate with the scheduler by writing messages 653to the standard error file. The scheduler reads messages from all filters in 654a job and processes the message based on its prefix. For example, the following 655code sets the current printer state message to "Printing page 5":</p> 656 657<pre class="example"> 658int page = 5; 659 660fprintf(stderr, "INFO: Printing page %d\n", page); 661</pre> 662 663<p>Each message is a single line of text starting with one of the following 664prefix strings:</p> 665 666<dl class="code"> 667 668 <dt>ALERT: message</dt> 669 <dd>Sets the printer-state-message attribute and adds the specified 670 message to the current error log file using the "alert" log level.</dd> 671 672 <dt>ATTR: attribute=value [attribute=value]</dt> 673 <dd>Sets the named printer or job attribute(s). Typically this is used 674 to set the <code>marker-colors</code>, <code>marker-high-levels</code>, 675 <code>marker-levels</code>, <code>marker-low-levels</code>, 676 <code>marker-message</code>, <code>marker-names</code>, 677 <code>marker-types</code>, <code>printer-alert</code>, and 678 <code>printer-alert-description</code> printer attributes. Standard 679 <code>marker-types</code> values are listed in <a href='#TABLE1'>Table 680 1</a>. String values need special handling - see <a href="#ATTR_STRINGS">Reporting Attribute String Values</a> below.</dd> 681 682 <dt>CRIT: message</dt> 683 <dd>Sets the printer-state-message attribute and adds the specified 684 message to the current error log file using the "critical" log 685 level.</dd> 686 687 <dt>DEBUG: message</dt> 688 <dd>Sets the printer-state-message attribute and adds the specified 689 message to the current error log file using the "debug" log level.</dd> 690 691 <dt>DEBUG2: message</dt> 692 <dd>Sets the printer-state-message attribute and adds the specified 693 message to the current error log file using the "debug2" log level.</dd> 694 695 <dt>EMERG: message</dt> 696 <dd>Sets the printer-state-message attribute and adds the specified 697 message to the current error log file using the "emergency" log 698 level.</dd> 699 700 <dt>ERROR: message</dt> 701 <dd>Sets the printer-state-message attribute and adds the specified 702 message to the current error log file using the "error" log level. 703 Use "ERROR:" messages for non-persistent processing errors.</dd> 704 705 <dt>INFO: message</dt> 706 <dd>Sets the printer-state-message attribute. If the current log level 707 is set to "debug2", also adds the specified message to the current error 708 log file using the "info" log level.</dd> 709 710 <dt>NOTICE: message</dt> 711 <dd>Sets the printer-state-message attribute and adds the specified 712 message to the current error log file using the "notice" log level.</dd> 713 714 <dt>PAGE: page-number #-copies</dt> 715 <dt>PAGE: total #-pages</dt> 716 <dd>Adds an entry to the current page log file. The first form adds 717 #-copies to the job-media-sheets-completed attribute. The second 718 form sets the job-media-sheets-completed attribute to #-pages.</dd> 719 720 <dt>PPD: keyword=value [keyword=value ...]</dt> 721 <dd>Changes or adds keywords to the printer's PPD file. Typically 722 this is used to update installable options or default media settings 723 based on the printer configuration.</dd> 724 725 <dt>STATE: + printer-state-reason [printer-state-reason ...]</dt> 726 <dt>STATE: - printer-state-reason [printer-state-reason ...]</dt> 727 <dd>Sets or clears printer-state-reason keywords for the current queue. 728 Typically this is used to indicate persistent media, ink, toner, and 729 configuration conditions or errors on a printer. 730 <a href='#TABLE2'>Table 2</a> lists the standard state keywords - 731 use vendor-prefixed ("com.example.foo") keywords for custom states. See 732 <a href="#MANAGING_STATE">Managing Printer State in a Filter</a> for more 733 information. 734 735 <dt>WARNING: message</dt> 736 <dd>Sets the printer-state-message attribute and adds the specified 737 message to the current error log file using the "warning" log 738 level.</dd> 739 740</dl> 741 742<p>Messages without one of these prefixes are treated as if they began with 743the "DEBUG:" prefix string.</p> 744 745<div class='table'><table width='80%' summary='Table 1: Standard marker-types Values'> 746<caption>Table 1: <a name='TABLE1'>Standard marker-types Values</a></caption> 747<thead> 748<tr> 749 <th>marker-type</th> 750 <th>Description</th> 751</tr> 752</thead> 753<tbody> 754<tr> 755 <td>developer</td> 756 <td>Developer unit</td> 757</tr> 758<tr> 759 <td>fuser</td> 760 <td>Fuser unit</td> 761</tr> 762<tr> 763 <td>fuser-cleaning-pad</td> 764 <td>Fuser cleaning pad</td> 765</tr> 766<tr> 767 <td>fuser-oil</td> 768 <td>Fuser oil</td> 769</tr> 770<tr> 771 <td>ink</td> 772 <td>Ink supply</td> 773</tr> 774<tr> 775 <td>opc</td> 776 <td>Photo conductor</td> 777</tr> 778<tr> 779 <td>solid-wax</td> 780 <td>Wax supply</td> 781</tr> 782<tr> 783 <td>staples</td> 784 <td>Staple supply</td> 785</tr> 786<tr> 787 <td>toner</td> 788 <td>Toner supply</td> 789</tr> 790<tr> 791 <td>transfer-unit</td> 792 <td>Transfer unit</td> 793</tr> 794<tr> 795 <td>waste-ink</td> 796 <td>Waste ink tank</td> 797</tr> 798<tr> 799 <td>waste-toner</td> 800 <td>Waste toner tank</td> 801</tr> 802<tr> 803 <td>waste-wax</td> 804 <td>Waste wax tank</td> 805</tr> 806</tbody> 807</table></div> 808 809<br> 810 811<div class='table'><table width='80%' summary='Table 2: Standard State Keywords'> 812<caption>Table 2: <a name='TABLE2'>Standard State Keywords</a></caption> 813<thead> 814<tr> 815 <th>Keyword</th> 816 <th>Description</th> 817</tr> 818</thead> 819<tbody> 820<tr> 821 <td>connecting-to-device</td> 822 <td>Connecting to printer but not printing yet.</td> 823</tr> 824<tr> 825 <td>cover-open</td> 826 <td>The printer's cover is open.</td> 827</tr> 828<tr> 829 <td>input-tray-missing</td> 830 <td>The paper tray is missing.</td> 831</tr> 832<tr> 833 <td>marker-supply-empty</td> 834 <td>The printer is out of ink.</td> 835</tr> 836<tr> 837 <td>marker-supply-low</td> 838 <td>The printer is almost out of ink.</td> 839</tr> 840<tr> 841 <td>marker-waste-almost-full</td> 842 <td>The printer's waste bin is almost full.</td> 843</tr> 844<tr> 845 <td>marker-waste-full</td> 846 <td>The printer's waste bin is full.</td> 847</tr> 848<tr> 849 <td>media-empty</td> 850 <td>The paper tray (any paper tray) is empty.</td> 851</tr> 852<tr> 853 <td>media-jam</td> 854 <td>There is a paper jam.</td> 855</tr> 856<tr> 857 <td>media-low</td> 858 <td>The paper tray (any paper tray) is almost empty.</td> 859</tr> 860<tr> 861 <td>media-needed</td> 862 <td>The paper tray needs to be filled (for a job that is printing).</td> 863</tr> 864<tr> 865 <td>paused</td> 866 <td>Stop the printer.</td> 867</tr> 868<tr> 869 <td>timed-out</td> 870 <td>Unable to connect to printer.</td> 871</tr> 872<tr> 873 <td>toner-empty</td> 874 <td>The printer is out of toner.</td> 875</tr> 876<tr> 877 <td>toner-low</td> 878 <td>The printer is low on toner.</td> 879</tr> 880</tbody> 881</table></div> 882 883 884<h4><a name="ATTR_STRINGS">Reporting Attribute String Values</a></h4> 885 886<p>When reporting string values using "ATTR:" messages, a filter or backend must take special care to appropriately quote those values. The scheduler uses the CUPS option parsing code for attributes, so the general syntax is:</p> 887 888<pre class="example"> 889name=simple 890name=simple,simple,... 891name='complex value' 892name="complex value" 893name='"complex value"','"complex value"',... 894</pre> 895 896<p>Simple values are strings that do not contain spaces, quotes, backslashes, or the comma and can be placed verbatim in the "ATTR:" message, for example:</p> 897 898<pre class="example"> 899int levels[4] = { 40, 50, 60, 70 }; /* CMYK */ 900 901fputs("ATTR: marker-colors=#00FFFF,#FF00FF,#FFFF00,#000000\n", stderr); 902fputs("ATTR: marker-high-levels=100,100,100,100\n", stderr); 903fprintf(stderr, "ATTR: marker-levels=%d,%d,%d,%d\n", levels[0], levels[1], 904 levels[2], levels[3], levels[4]); 905fputs("ATTR: marker-low-levels=5,5,5,5\n", stderr); 906fputs("ATTR: marker-types=toner,toner,toner,toner\n", stderr); 907</pre> 908 909<p>Complex values that contains spaces, quotes, backslashes, or the comma must be quoted. For a single value a single set of quotes is sufficient:</p> 910 911<pre class="example"> 912fputs("ATTR: marker-message='Levels shown are approximate.'\n", stderr); 913</pre> 914 915<p>When multiple values are reported, each value must be enclosed by a set of single and double quotes:</p> 916 917<pre class="example"> 918fputs("ATTR: marker-names='\"Cyan Toner\"','\"Magenta Toner\"'," 919 "'\"Yellow Toner\"','\"Black Toner\"'\n", stderr); 920</pre> 921 922<p>The IPP backend includes a <var>quote_string</var> function that may be used to properly quote a complex value in an "ATTR:" message:</p> 923 924<pre class="example"> 925static const char * /* O - Quoted string */ 926quote_string(const char *s, /* I - String */ 927 char *q, /* I - Quoted string buffer */ 928 size_t qsize) /* I - Size of quoted string buffer */ 929{ 930 char *qptr, /* Pointer into string buffer */ 931 *qend; /* End of string buffer */ 932 933 934 qptr = q; 935 qend = q + qsize - 5; 936 937 if (qend < q) 938 { 939 *q = '\0'; 940 return (q); 941 } 942 943 *qptr++ = '\''; 944 *qptr++ = '\"'; 945 946 while (*s && qptr < qend) 947 { 948 if (*s == '\\' || *s == '\"' || *s == '\'') 949 { 950 if (qptr < (qend - 4)) 951 { 952 *qptr++ = '\\'; 953 *qptr++ = '\\'; 954 *qptr++ = '\\'; 955 } 956 else 957 break; 958 } 959 960 *qptr++ = *s++; 961 } 962 963 *qptr++ = '\"'; 964 *qptr++ = '\''; 965 *qptr = '\0'; 966 967 return (q); 968} 969</pre> 970 971 972<h4><a name="MANAGING_STATE">Managing Printer State in a Filter</a></h4> 973 974<p>Filters are responsible for managing the state keywords they set using 975"STATE:" messages. Typically you will update <em>all</em> of the keywords that 976are used by the filter at startup, for example:</p> 977 978<pre class="example"> 979if (foo_condition != 0) 980 fputs("STATE: +com.example.foo\n", stderr); 981else 982 fputs("STATE: -com.example.foo\n", stderr); 983 984if (bar_condition != 0) 985 fputs("STATE: +com.example.bar\n", stderr); 986else 987 fputs("STATE: -com.example.bar\n", stderr); 988</pre> 989 990<p>Then as conditions change, your filter sends "STATE: +keyword" or "STATE: 991-keyword" messages as necessary to set or clear the corresponding keyword, 992respectively.</p> 993 994<p>State keywords are often used to notify the user of issues that span across 995jobs, for example "media-empty-warning" that indicates one or more paper trays 996are empty. These keywords should not be cleared unless the corresponding issue 997no longer exists.</p> 998 999<p>Filters should clear job-related keywords on startup and exit so that they 1000do not remain set between jobs. For example, "connecting-to-device" is a job 1001sub-state and not an issue that applies when a job is not printing.</p> 1002 1003<blockquote><b>Note:</b> 1004 1005<p>"STATE:" messages often provide visible alerts to the user. For example, 1006on OS X setting a printer-state-reason value with an "-error" or 1007"-warning" suffix will cause the printer's dock item to bounce if the 1008corresponding reason is localized with a cupsIPPReason keyword in the 1009printer's PPD file.</p> 1010 1011<p>When providing a vendor-prefixed keyword, <em>always</em> provide the 1012corresponding standard keyword (if any) to allow clients to respond to the 1013condition correctly. For example, if you provide a vendor-prefixed keyword 1014for a low cyan ink condition ("com.example.cyan-ink-low") you must also set the 1015"marker-supply-low-warning" keyword. In such cases you should also refrain 1016from localizing the vendor-prefixed keyword in the PPD file - otherwise both 1017the generic and vendor-specific keyword will be shown in the user 1018interface.</p> 1019 1020</blockquote> 1021 1022<h4><a name="REPORTING_SUPPLIES">Reporting Supply Levels</a></h4> 1023 1024<p>CUPS tracks several "marker-*" attributes for ink/toner supply level 1025reporting. These attributes allow applications to display the current supply 1026levels for a printer without printer-specific software. <a href="#TABLE3">Table 3</a> lists the marker attributes and what they represent.</p> 1027 1028<p>Filters set marker attributes by sending "ATTR:" messages to stderr. For 1029example, a filter supporting an inkjet printer with black and tri-color ink 1030cartridges would use the following to initialize the supply attributes:</p> 1031 1032<pre class="example"> 1033fputs("ATTR: marker-colors=#000000,#00FFFF#FF00FF#FFFF00\n", stderr); 1034fputs("ATTR: marker-low-levels=5,10\n", stderr); 1035fputs("ATTR: marker-names=Black,Tri-Color\n", stderr); 1036fputs("ATTR: marker-types=ink,ink\n", stderr); 1037</pre> 1038 1039<p>Then periodically the filter queries the printer for its current supply 1040levels and updates them with a separate "ATTR:" message:</p> 1041 1042<pre class="example"> 1043int black_level, tri_level; 1044... 1045fprintf(stderr, "ATTR: marker-levels=%d,%d\n", black_level, tri_level); 1046</pre> 1047 1048<div class='table'><table width='80%' summary='Table 3: Supply Level Attributes'> 1049<caption>Table 3: <a name='TABLE3'>Supply Level Attributes</a></caption> 1050<thead> 1051<tr> 1052 <th>Attribute</th> 1053 <th>Description</th> 1054</tr> 1055</thead> 1056<tbody> 1057<tr> 1058 <td>marker-colors</td> 1059 <td>A list of comma-separated colors; each color is either "none" or one or 1060 more hex-encoded sRGB colors of the form "#RRGGBB".</td> 1061</tr> 1062<tr> 1063 <td>marker-high-levels</td> 1064 <td>A list of comma-separated "almost full" level values from 0 to 100; a 1065 value of 100 should be used for supplies that are consumed/emptied like ink 1066 cartridges.</td> 1067</tr> 1068<tr> 1069 <td>marker-levels</td> 1070 <td>A list of comma-separated level values for each supply. A value of -1 1071 indicates the level is unavailable, -2 indicates unknown, and -3 indicates 1072 the level is unknown but has not yet reached capacity. Values from 0 to 100 1073 indicate the corresponding percentage.</td> 1074</tr> 1075<tr> 1076 <td>marker-low-levels</td> 1077 <td>A list of comma-separated "almost empty" level values from 0 to 100; a 1078 value of 0 should be used for supplies that are filled like waste ink 1079 tanks.</td> 1080</tr> 1081<tr> 1082 <td>marker-message</td> 1083 <td>A human-readable supply status message for the user like "12 pages of 1084 ink remaining."</td> 1085</tr> 1086<tr> 1087 <td>marker-names</td> 1088 <td>A list of comma-separated supply names like "Cyan Ink", "Fuser", 1089 etc.</td> 1090</tr> 1091<tr> 1092 <td>marker-types</td> 1093 <td>A list of comma-separated supply types; the types are listed in 1094 <a href="#TABLE1">Table 1</a>.</td> 1095</tr> 1096</tbody> 1097</table></div> 1098 1099<h3><a name="COMMUNICATING_BACKEND">Communicating with the Backend</a></h3> 1100 1101<p>Filters can communicate with the backend via the 1102<a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and 1103<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 1104functions. The 1105<a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> function 1106reads data that has been sent back from the device and is typically used to 1107obtain status and configuration information. For example, the following code 1108polls the backend for back-channel data:</p> 1109 1110<pre class="example"> 1111#include <cups/cups.h> 1112 1113char buffer[8192]; 1114ssize_t bytes; 1115 1116/* Use a timeout of 0.0 seconds to poll for back-channel data */ 1117bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0); 1118</pre> 1119 1120<p>Filters can also use <code>select()</code> or <code>poll()</code> on the 1121back-channel file descriptor (3 or <code>CUPS_BC_FD</code>) to read data only 1122when it is available.</p> 1123 1124<p>The 1125<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 1126function allows you to get out-of-band status information and do synchronization 1127with the device. For example, the following code gets the current IEEE-1284 1128device ID string from the backend:</p> 1129 1130<pre class="example"> 1131#include <cups/sidechannel.h> 1132 1133char data[2049]; 1134int datalen; 1135<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 1136 1137/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for 1138 nul-termination... */ 1139datalen = sizeof(data) - 1; 1140 1141/* Get the IEEE-1284 device ID, waiting for up to 1 second */ 1142status = <a href="#cupsSideChannelDoRequest">cupsSideChannelDoRequest</a>(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0); 1143 1144/* Use the returned value if OK was returned and the length is non-zero */ 1145if (status == CUPS_SC_STATUS_OK && datalen > 0) 1146 data[datalen] = '\0'; 1147else 1148 data[0] = '\0'; 1149</pre> 1150 1151<h4><a name="DRAIN_OUTPUT">Forcing All Output to a Printer</a></h4> 1152 1153<p>The 1154<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> 1155function allows you to tell the backend to send all pending data to the printer. 1156This is most often needed when sending query commands to the printer. For example:</p> 1157 1158<pre class="example"> 1159#include <cups/cups.h> 1160#include <cups/sidechannel.h> 1161 1162char data[1024]; 1163int datalen = sizeof(data); 1164<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 1165 1166/* Flush pending output to stdout */ 1167fflush(stdout); 1168 1169/* Drain output to backend, waiting for up to 30 seconds */ 1170status = <a href="#cupsSideChannelDoRequest">cupsSideChannelDoRequest</a>(CUPS_SC_CMD_DRAIN_OUTPUT, data, &datalen, 30.0); 1171 1172/* Read the response if the output was sent */ 1173if (status == CUPS_SC_STATUS_OK) 1174{ 1175 ssize_t bytes; 1176 1177 /* Wait up to 10.0 seconds for back-channel data */ 1178 bytes = cupsBackChannelRead(data, sizeof(data), 10.0); 1179 /* do something with the data from the printer */ 1180} 1181</pre> 1182 1183<h3><a name="COMMUNICATING_FILTER">Communicating with Filters</a></h3> 1184 1185<p>Backends communicate with filters using the reciprocal functions 1186<a href="#cupsBackChannelWrite"><code>cupsBackChannelWrite</code></a>, 1187<a href="#cupsSideChannelRead"><code>cupsSideChannelRead</code></a>, and 1188<a href="#cupsSideChannelWrite"><code>cupsSideChannelWrite</code></a>. We 1189recommend writing back-channel data using a timeout of 1.0 seconds:</p> 1190 1191<pre class="example"> 1192#include <cups/cups.h> 1193 1194char buffer[8192]; 1195ssize_t bytes; 1196 1197/* Obtain data from printer/device */ 1198... 1199 1200/* Use a timeout of 1.0 seconds to give filters a chance to read */ 1201cupsBackChannelWrite(buffer, bytes, 1.0); 1202</pre> 1203 1204<p>The <a href="#cupsSideChannelRead"><code>cupsSideChannelRead</code></a> 1205function reads a side-channel command from a filter, driver, or port monitor. 1206Backends can either poll for commands using a <code>timeout</code> of 0.0, wait 1207indefinitely for commands using a <code>timeout</code> of -1.0 (probably in a 1208separate thread for that purpose), or use <code>select</code> or 1209<code>poll</code> on the <code>CUPS_SC_FD</code> file descriptor (4) to handle 1210input and output on several file descriptors at the same time.</p> 1211 1212<p>Once a command is processed, the backend uses the 1213<a href="#cupsSideChannelWrite"><code>cupsSideChannelWrite</code></a> function 1214to send its response. For example, the following code shows how to poll for a 1215side-channel command and respond to it:</p> 1216 1217<pre class="example"> 1218#include <cups/sidechannel.h> 1219 1220<a href="#cups_sc_command_t">cups_sc_command_t</a> command; 1221<a href="#cups_sc_status_t">cups_sc_status_t</a> status; 1222char data[2048]; 1223int datalen = sizeof(data); 1224 1225/* Poll for a command... */ 1226if (!<a href="#cupsSideChannelRead">cupsSideChannelRead</a>(&command, &status, data, &datalen, 0.0)) 1227{ 1228 switch (command) 1229 { 1230 /* handle supported commands, fill data/datalen/status with values as needed */ 1231 1232 default : 1233 status = CUPS_SC_STATUS_NOT_IMPLEMENTED; 1234 datalen = 0; 1235 break; 1236 } 1237 1238 /* Send a response... */ 1239 <a href="#cupsSideChannelWrite">cupsSideChannelWrite</a>(command, status, data, datalen, 1.0); 1240} 1241</pre> 1242 1243<h3><a name="SNMP">Doing SNMP Queries with Network Printers</a></h3> 1244 1245<p>The Simple Network Management Protocol (SNMP) allows you to get the current 1246status, page counter, and supply levels from most network printers. Every 1247piece of information is associated with an Object Identifier (OID), and 1248every printer has a <em>community</em> name associated with it. OIDs can be 1249queried directly or by "walking" over a range of OIDs with a common prefix.</p> 1250 1251<p>The two CUPS SNMP functions provide a simple API for querying network 1252printers through the side-channel interface. Each accepts a string containing 1253an OID like ".1.3.6.1.2.1.43.10.2.1.4.1.1" (the standard page counter OID) 1254along with a timeout for the query.</p> 1255 1256<p>The <a href="#cupsSideChannelSNMPGet"><code>cupsSideChannelSNMPGet</code></a> 1257function queries a single OID and returns the value as a string in a buffer 1258you supply:</p> 1259 1260<pre class="example"> 1261#include <cups/sidechannel.h> 1262 1263char data[512]; 1264int datalen = sizeof(data); 1265 1266if (<a href="#cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a>(".1.3.6.1.2.1.43.10.2.1.4.1.1", data, &datalen, 5.0) 1267 == CUPS_SC_STATUS_OK) 1268{ 1269 /* Do something with the value */ 1270 printf("Page counter is: %s\n", data); 1271} 1272</pre> 1273 1274<p>The 1275<a href="#cupsSideChannelSNMPWalk"><code>cupsSideChannelSNMPWalk</code></a> 1276function allows you to query a whole group of OIDs, calling a function of your 1277choice for each OID that is found:</p> 1278 1279<pre class="example"> 1280#include <cups/sidechannel.h> 1281 1282void 1283my_callback(const char *oid, const char *data, int datalen, void *context) 1284{ 1285 /* Do something with the value */ 1286 printf("%s=%s\n", oid, data); 1287} 1288 1289... 1290 1291void *my_data; 1292 1293<a href="#cupsSideChannelSNMPWalk">cupsSNMPSideChannelWalk</a>(".1.3.6.1.2.1.43", 5.0, my_callback, my_data); 1294</pre> 1295 1296<h2><a name="SANDBOXING">Sandboxing on OS X</a></h2> 1297 1298<p>Starting with OS X 10.6, filters and backends are run inside a security "sandbox" which further limits (beyond the normal UNIX user/group permissions) what a filter or backend can do. This helps to both secure the printing system from malicious software and enforce the functional separation of components in the CUPS filter chain. What follows is a list of actions that are explicitly allowed for all filters and backends:</p> 1299 1300<ol> 1301 1302 <li>Reading of files: pursuant to normal UNIX file permissions, filters and backends can read files for the current job from the <var>/private/var/spool/cups</var> directory and other files on mounted filesystems <em>except</em> for user home directories under <var>/Users</var>.</li> 1303 1304 <li>Writing of files: pursuant to normal UNIX file permissions, filters and backends can read/write files to the cache directory specified by the <code>CUPS_CACHEDIR</code> environment variable, to the state directory specified by the <code>CUPS_STATEDIR</code> environment variable, to the temporary directory specified by the <code>TMPDIR</code> environment variable, and under the <var>/private/var/db</var>, <var>/private/var/folders</var>, <var>/private/var/lib</var>, <var>/private/var/mysql</var>, <var>/private/var/run</var>, <var>/private/var/spool</var> (except <var>/private/var/spool/cups</var>), <var>/Library/Application Support</var>, <var>/Library/Caches</var>, <var>/Library/Logs</var>, <var>/Library/Preferences</var>, <var>/Library/WebServer</var>, and <var>/Users/Shared</var> directories.</li> 1305 1306 <li>Execution of programs: pursuant to normal UNIX file permissions, filters and backends can execute any program not located under the <var>/Users</var> directory. Child processes inherit the sandbox and are subject to the same restrictions as the parent.</li> 1307 1308 <li>Bluetooth and USB: backends can access Bluetooth and USB printers through IOKit. <em>Filters cannot access Bluetooth and USB printers directly.</em></li> 1309 1310 <li>Network: filters and backends can access UNIX domain sockets under the <var>/private/tmp</var>, <var>/private/var/run</var>, and <var>/private/var/tmp</var> directories. Backends can also create IPv4 and IPv6 TCP (outgoing) and UDP (incoming and outgoing) socket, and bind to local source ports. <em>Filters cannot directly create IPv4 and IPv6 TCP or UDP sockets.</em></li> 1311 1312 <li>Notifications: filters and backends can send notifications via the Darwin <code>notify_post()</code> API.</li> 1313 1314</ol> 1315 1316<blockquote><b>Note:</b> The sandbox profile used in CUPS 2.0 still allows some actions that are not listed above - these privileges will be removed over time until the profile matches the list above.</blockquote> 1317<h2 class="title"><a name="FUNCTIONS">Functions</a></h2> 1318<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3> 1319<p class="description">Read data from the backchannel.</p> 1320<p class="code"> 1321ssize_t cupsBackChannelRead (<br> 1322 char *buffer,<br> 1323 size_t bytes,<br> 1324 double timeout<br> 1325);</p> 1326<h4 class="parameters">Parameters</h4> 1327<dl> 1328<dt>buffer</dt> 1329<dd class="description">Buffer to read into</dd> 1330<dt>bytes</dt> 1331<dd class="description">Bytes to read</dd> 1332<dt>timeout</dt> 1333<dd class="description">Timeout in seconds, typically 0.0 to poll</dd> 1334</dl> 1335<h4 class="returnvalue">Return Value</h4> 1336<p class="description">Bytes read or -1 on error</p> 1337<h4 class="discussion">Discussion</h4> 1338<p class="discussion">Reads up to "bytes" bytes from the backchannel/backend. The "timeout" 1339parameter controls how many seconds to wait for the data - use 0.0 to 1340return immediately if there is no data, -1.0 to wait for data indefinitely. 1341 1342</p> 1343<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3> 1344<p class="description">Write data to the backchannel.</p> 1345<p class="code"> 1346ssize_t cupsBackChannelWrite (<br> 1347 const char *buffer,<br> 1348 size_t bytes,<br> 1349 double timeout<br> 1350);</p> 1351<h4 class="parameters">Parameters</h4> 1352<dl> 1353<dt>buffer</dt> 1354<dd class="description">Buffer to write</dd> 1355<dt>bytes</dt> 1356<dd class="description">Bytes to write</dd> 1357<dt>timeout</dt> 1358<dd class="description">Timeout in seconds, typically 1.0</dd> 1359</dl> 1360<h4 class="returnvalue">Return Value</h4> 1361<p class="description">Bytes written or -1 on error</p> 1362<h4 class="discussion">Discussion</h4> 1363<p class="discussion">Writes "bytes" bytes to the backchannel/filter. The "timeout" parameter 1364controls how many seconds to wait for the data to be written - use 13650.0 to return immediately if the data cannot be written, -1.0 to wait 1366indefinitely. 1367 1368</p> 1369<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3> 1370<p class="description">Get the device URI for a backend.</p> 1371<p class="code"> 1372const char *cupsBackendDeviceURI (<br> 1373 char **argv<br> 1374);</p> 1375<h4 class="parameters">Parameters</h4> 1376<dl> 1377<dt>argv</dt> 1378<dd class="description">Command-line arguments</dd> 1379</dl> 1380<h4 class="returnvalue">Return Value</h4> 1381<p class="description">Device URI or <code>NULL</code></p> 1382<h4 class="discussion">Discussion</h4> 1383<p class="discussion">The "argv" argument is the argv argument passed to main(). This 1384function returns the device URI passed in the DEVICE_URI environment 1385variable or the device URI passed in argv[0], whichever is found 1386first. 1387 1388</p> 1389<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsBackendReport">cupsBackendReport</a></h3> 1390<p class="description">Write a device line from a backend.</p> 1391<p class="code"> 1392void cupsBackendReport (<br> 1393 const char *device_scheme,<br> 1394 const char *device_uri,<br> 1395 const char *device_make_and_model,<br> 1396 const char *device_info,<br> 1397 const char *device_id,<br> 1398 const char *device_location<br> 1399);</p> 1400<h4 class="parameters">Parameters</h4> 1401<dl> 1402<dt>device_scheme</dt> 1403<dd class="description">device-scheme string</dd> 1404<dt>device_uri</dt> 1405<dd class="description">device-uri string</dd> 1406<dt>device_make_and_model</dt> 1407<dd class="description">device-make-and-model string or <code>NULL</code></dd> 1408<dt>device_info</dt> 1409<dd class="description">device-info string or <code>NULL</code></dd> 1410<dt>device_id</dt> 1411<dd class="description">device-id string or <code>NULL</code></dd> 1412<dt>device_location</dt> 1413<dd class="description">device-location string or <code>NULL</code></dd> 1414</dl> 1415<h4 class="discussion">Discussion</h4> 1416<p class="discussion">This function writes a single device line to stdout for a backend. 1417It handles quoting of special characters in the device-make-and-model, 1418device-info, device-id, and device-location strings. 1419 1420</p> 1421<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3> 1422<p class="description">Send a side-channel command to a backend and wait for a response.</p> 1423<p class="code"> 1424<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelDoRequest (<br> 1425 <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br> 1426 char *data,<br> 1427 int *datalen,<br> 1428 double timeout<br> 1429);</p> 1430<h4 class="parameters">Parameters</h4> 1431<dl> 1432<dt>command</dt> 1433<dd class="description">Command to send</dd> 1434<dt>data</dt> 1435<dd class="description">Response data buffer pointer</dd> 1436<dt>datalen</dt> 1437<dd class="description">Size of data buffer on entry, number of bytes in buffer on return</dd> 1438<dt>timeout</dt> 1439<dd class="description">Timeout in seconds</dd> 1440</dl> 1441<h4 class="returnvalue">Return Value</h4> 1442<p class="description">Status of command</p> 1443<h4 class="discussion">Discussion</h4> 1444<p class="discussion">This function is normally only called by filters, drivers, or port 1445monitors in order to communicate with the backend used by the current 1446printer. Programs must be prepared to handle timeout or "not 1447implemented" status codes, which indicate that the backend or device 1448do not support the specified side-channel command.<br> 1449<br> 1450The "datalen" parameter must be initialized to the size of the buffer 1451pointed to by the "data" parameter. cupsSideChannelDoRequest() will 1452update the value to contain the number of data bytes in the buffer. 1453 1454</p> 1455<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelRead">cupsSideChannelRead</a></h3> 1456<p class="description">Read a side-channel message.</p> 1457<p class="code"> 1458int cupsSideChannelRead (<br> 1459 <a href="#cups_sc_command_t">cups_sc_command_t</a> *command,<br> 1460 <a href="#cups_sc_status_t">cups_sc_status_t</a> *status,<br> 1461 char *data,<br> 1462 int *datalen,<br> 1463 double timeout<br> 1464);</p> 1465<h4 class="parameters">Parameters</h4> 1466<dl> 1467<dt>command</dt> 1468<dd class="description">Command code</dd> 1469<dt>status</dt> 1470<dd class="description">Status code</dd> 1471<dt>data</dt> 1472<dd class="description">Data buffer pointer</dd> 1473<dt>datalen</dt> 1474<dd class="description">Size of data buffer on entry, number of bytes in buffer on return</dd> 1475<dt>timeout</dt> 1476<dd class="description">Timeout in seconds</dd> 1477</dl> 1478<h4 class="returnvalue">Return Value</h4> 1479<p class="description">0 on success, -1 on error</p> 1480<h4 class="discussion">Discussion</h4> 1481<p class="discussion">This function is normally only called by backend programs to read 1482commands from a filter, driver, or port monitor program. The 1483caller must be prepared to handle incomplete or invalid messages 1484and return the corresponding status codes.<br> 1485<br> 1486The "datalen" parameter must be initialized to the size of the buffer 1487pointed to by the "data" parameter. cupsSideChannelDoRequest() will 1488update the value to contain the number of data bytes in the buffer. 1489 1490</p> 1491<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3> 1492<p class="description">Query a SNMP OID's value.</p> 1493<p class="code"> 1494<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br> 1495 const char *oid,<br> 1496 char *data,<br> 1497 int *datalen,<br> 1498 double timeout<br> 1499);</p> 1500<h4 class="parameters">Parameters</h4> 1501<dl> 1502<dt>oid</dt> 1503<dd class="description">OID to query</dd> 1504<dt>data</dt> 1505<dd class="description">Buffer for OID value</dd> 1506<dt>datalen</dt> 1507<dd class="description">Size of OID buffer on entry, size of value on return</dd> 1508<dt>timeout</dt> 1509<dd class="description">Timeout in seconds</dd> 1510</dl> 1511<h4 class="returnvalue">Return Value</h4> 1512<p class="description">Query status</p> 1513<h4 class="discussion">Discussion</h4> 1514<p class="discussion">This function asks the backend to do a SNMP OID query on behalf of the 1515filter, port monitor, or backend using the default community name.<br> 1516<br> 1517"oid" contains a numeric OID consisting of integers separated by periods, 1518for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not 1519supported and must be converted to their numeric forms.<br> 1520<br> 1521On input, "data" and "datalen" provide the location and size of the 1522buffer to hold the OID value as a string. HEX-String (binary) values are 1523converted to hexadecimal strings representing the binary data, while 1524NULL-Value and unknown OID types are returned as the empty string. 1525The returned "datalen" does not include the trailing nul. 1526 1527<code>CUPS_SC_STATUS_NOT_IMPLEMENTED</code> is returned by backends that do not 1528support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when 1529the printer does not respond to the SNMP query. 1530 1531</p> 1532<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3> 1533<p class="description">Query multiple SNMP OID values.</p> 1534<p class="code"> 1535<a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br> 1536 const char *oid,<br> 1537 double timeout,<br> 1538 <a href="#cups_sc_walk_func_t">cups_sc_walk_func_t</a> cb,<br> 1539 void *context<br> 1540);</p> 1541<h4 class="parameters">Parameters</h4> 1542<dl> 1543<dt>oid</dt> 1544<dd class="description">First numeric OID to query</dd> 1545<dt>timeout</dt> 1546<dd class="description">Timeout for each query in seconds</dd> 1547<dt>cb</dt> 1548<dd class="description">Function to call with each value</dd> 1549<dt>context</dt> 1550<dd class="description">Application-defined pointer to send to callback</dd> 1551</dl> 1552<h4 class="returnvalue">Return Value</h4> 1553<p class="description">Status of first query of <code>CUPS_SC_STATUS_OK</code> on success</p> 1554<h4 class="discussion">Discussion</h4> 1555<p class="discussion">This function asks the backend to do multiple SNMP OID queries on behalf 1556of the filter, port monitor, or backend using the default community name. 1557All OIDs under the "parent" OID are queried and the results are sent to 1558the callback function you provide.<br> 1559<br> 1560"oid" contains a numeric OID consisting of integers separated by periods, 1561for example ".1.3.6.1.2.1.43". Symbolic names from SNMP MIBs are not 1562supported and must be converted to their numeric forms.<br> 1563<br> 1564"timeout" specifies the timeout for each OID query. The total amount of 1565time will depend on the number of OID values found and the time required 1566for each query.<br> 1567<br> 1568"cb" provides a function to call for every value that is found. "context" 1569is an application-defined pointer that is sent to the callback function 1570along with the OID and current data. The data passed to the callback is the 1571same as returned by <a href="#cupsSideChannelSNMPGet"><code>cupsSideChannelSNMPGet</code></a>. 1572 1573<code>CUPS_SC_STATUS_NOT_IMPLEMENTED</code> is returned by backends that do not 1574support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when 1575the printer does not respond to the first SNMP query. 1576 1577</p> 1578<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3> 1579<p class="description">Write a side-channel message.</p> 1580<p class="code"> 1581int cupsSideChannelWrite (<br> 1582 <a href="#cups_sc_command_t">cups_sc_command_t</a> command,<br> 1583 <a href="#cups_sc_status_t">cups_sc_status_t</a> status,<br> 1584 const char *data,<br> 1585 int datalen,<br> 1586 double timeout<br> 1587);</p> 1588<h4 class="parameters">Parameters</h4> 1589<dl> 1590<dt>command</dt> 1591<dd class="description">Command code</dd> 1592<dt>status</dt> 1593<dd class="description">Status code</dd> 1594<dt>data</dt> 1595<dd class="description">Data buffer pointer</dd> 1596<dt>datalen</dt> 1597<dd class="description">Number of bytes of data</dd> 1598<dt>timeout</dt> 1599<dd class="description">Timeout in seconds</dd> 1600</dl> 1601<h4 class="returnvalue">Return Value</h4> 1602<p class="description">0 on success, -1 on error</p> 1603<h4 class="discussion">Discussion</h4> 1604<p class="discussion">This function is normally only called by backend programs to send 1605responses to a filter, driver, or port monitor program. 1606 1607</p> 1608<h2 class="title"><a name="TYPES">Data Types</a></h2> 1609<h3 class="typedef"><a name="cups_backend_t">cups_backend_t</a></h3> 1610<p class="description">Backend exit codes</p> 1611<p class="code"> 1612typedef enum <a href="#cups_backend_e">cups_backend_e</a> cups_backend_t; 1613</p> 1614<h3 class="typedef"><a name="cups_sc_bidi_t">cups_sc_bidi_t</a></h3> 1615<p class="description">Bidirectional capabilities</p> 1616<p class="code"> 1617typedef enum <a href="#cups_sc_bidi_e">cups_sc_bidi_e</a> cups_sc_bidi_t; 1618</p> 1619<h3 class="typedef"><a name="cups_sc_command_t">cups_sc_command_t</a></h3> 1620<p class="description">Request command codes</p> 1621<p class="code"> 1622typedef enum <a href="#cups_sc_command_e">cups_sc_command_e</a> cups_sc_command_t; 1623</p> 1624<h3 class="typedef"><a name="cups_sc_connected_t">cups_sc_connected_t</a></h3> 1625<p class="description">Connectivity values</p> 1626<p class="code"> 1627typedef enum <a href="#cups_sc_connected_e">cups_sc_connected_e</a> cups_sc_connected_t; 1628</p> 1629<h3 class="typedef"><a name="cups_sc_state_t">cups_sc_state_t</a></h3> 1630<p class="description">Printer state bits</p> 1631<p class="code"> 1632typedef enum <a href="#cups_sc_state_e">cups_sc_state_e</a> cups_sc_state_t; 1633</p> 1634<h3 class="typedef"><a name="cups_sc_status_t">cups_sc_status_t</a></h3> 1635<p class="description">Response status codes</p> 1636<p class="code"> 1637typedef enum <a href="#cups_sc_status_e">cups_sc_status_e</a> cups_sc_status_t; 1638</p> 1639<h3 class="typedef"><a name="cups_sc_walk_func_t">cups_sc_walk_func_t</a></h3> 1640<p class="description">SNMP walk callback</p> 1641<p class="code"> 1642typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datalen, void *context); 1643</p> 1644<h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> 1645<h3 class="enumeration"><a name="cups_backend_e">cups_backend_e</a></h3> 1646<p class="description">Backend exit codes</p> 1647<h4 class="constants">Constants</h4> 1648<dl> 1649<dt>CUPS_BACKEND_AUTH_REQUIRED </dt> 1650<dd class="description">Job failed, authentication required</dd> 1651<dt>CUPS_BACKEND_CANCEL </dt> 1652<dd class="description">Job failed, cancel job</dd> 1653<dt>CUPS_BACKEND_FAILED </dt> 1654<dd class="description">Job failed, use error-policy</dd> 1655<dt>CUPS_BACKEND_HOLD </dt> 1656<dd class="description">Job failed, hold job</dd> 1657<dt>CUPS_BACKEND_OK </dt> 1658<dd class="description">Job completed successfully</dd> 1659<dt>CUPS_BACKEND_RETRY </dt> 1660<dd class="description">Job failed, retry this job later</dd> 1661<dt>CUPS_BACKEND_RETRY_CURRENT </dt> 1662<dd class="description">Job failed, retry this job immediately</dd> 1663<dt>CUPS_BACKEND_STOP </dt> 1664<dd class="description">Job failed, stop queue</dd> 1665</dl> 1666<h3 class="enumeration"><a name="cups_sc_bidi_e">cups_sc_bidi_e</a></h3> 1667<p class="description">Bidirectional capability values</p> 1668<h4 class="constants">Constants</h4> 1669<dl> 1670<dt>CUPS_SC_BIDI_NOT_SUPPORTED </dt> 1671<dd class="description">Bidirectional I/O is not supported</dd> 1672<dt>CUPS_SC_BIDI_SUPPORTED </dt> 1673<dd class="description">Bidirectional I/O is supported</dd> 1674</dl> 1675<h3 class="enumeration"><a name="cups_sc_command_e">cups_sc_command_e</a></h3> 1676<p class="description">Request command codes</p> 1677<h4 class="constants">Constants</h4> 1678<dl> 1679<dt>CUPS_SC_CMD_DRAIN_OUTPUT </dt> 1680<dd class="description">Drain all pending output</dd> 1681<dt>CUPS_SC_CMD_GET_BIDI </dt> 1682<dd class="description">Return bidirectional capabilities</dd> 1683<dt>CUPS_SC_CMD_GET_CONNECTED <span class="info"> CUPS 1.5/OS X 10.7 </span></dt> 1684<dd class="description">Return whether the backend is "connected" to the printer </dd> 1685<dt>CUPS_SC_CMD_GET_DEVICE_ID </dt> 1686<dd class="description">Return the IEEE-1284 device ID</dd> 1687<dt>CUPS_SC_CMD_GET_STATE </dt> 1688<dd class="description">Return the device state</dd> 1689<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> 1690<dd class="description">Query an SNMP OID </dd> 1691<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> 1692<dd class="description">Query the next SNMP OID </dd> 1693<dt>CUPS_SC_CMD_SOFT_RESET </dt> 1694<dd class="description">Do a soft reset</dd> 1695</dl> 1696<h3 class="enumeration"><a name="cups_sc_connected_e">cups_sc_connected_e</a></h3> 1697<p class="description">Connectivity values</p> 1698<h4 class="constants">Constants</h4> 1699<dl> 1700<dt>CUPS_SC_CONNECTED </dt> 1701<dd class="description">Backend is "connected" to printer</dd> 1702<dt>CUPS_SC_NOT_CONNECTED </dt> 1703<dd class="description">Backend is not "connected" to printer</dd> 1704</dl> 1705<h3 class="enumeration"><a name="cups_sc_state_e">cups_sc_state_e</a></h3> 1706<p class="description">Printer state bits</p> 1707<h4 class="constants">Constants</h4> 1708<dl> 1709<dt>CUPS_SC_STATE_BUSY </dt> 1710<dd class="description">Device is busy</dd> 1711<dt>CUPS_SC_STATE_ERROR </dt> 1712<dd class="description">Other error condition</dd> 1713<dt>CUPS_SC_STATE_MARKER_EMPTY </dt> 1714<dd class="description">Toner/ink out condition</dd> 1715<dt>CUPS_SC_STATE_MARKER_LOW </dt> 1716<dd class="description">Toner/ink low condition</dd> 1717<dt>CUPS_SC_STATE_MEDIA_EMPTY </dt> 1718<dd class="description">Paper out condition</dd> 1719<dt>CUPS_SC_STATE_MEDIA_LOW </dt> 1720<dd class="description">Paper low condition</dd> 1721<dt>CUPS_SC_STATE_OFFLINE </dt> 1722<dd class="description">Device is offline</dd> 1723<dt>CUPS_SC_STATE_ONLINE </dt> 1724<dd class="description">Device is online</dd> 1725</dl> 1726<h3 class="enumeration"><a name="cups_sc_status_e">cups_sc_status_e</a></h3> 1727<p class="description">Response status codes</p> 1728<h4 class="constants">Constants</h4> 1729<dl> 1730<dt>CUPS_SC_STATUS_BAD_MESSAGE </dt> 1731<dd class="description">The command/response message was invalid</dd> 1732<dt>CUPS_SC_STATUS_IO_ERROR </dt> 1733<dd class="description">An I/O error occurred</dd> 1734<dt>CUPS_SC_STATUS_NONE </dt> 1735<dd class="description">No status</dd> 1736<dt>CUPS_SC_STATUS_NOT_IMPLEMENTED </dt> 1737<dd class="description">Command not implemented</dd> 1738<dt>CUPS_SC_STATUS_NO_RESPONSE </dt> 1739<dd class="description">The device did not respond</dd> 1740<dt>CUPS_SC_STATUS_OK </dt> 1741<dd class="description">Operation succeeded</dd> 1742<dt>CUPS_SC_STATUS_TIMEOUT </dt> 1743<dd class="description">The backend did not respond</dd> 1744<dt>CUPS_SC_STATUS_TOO_BIG </dt> 1745<dd class="description">Response too big</dd> 1746</dl> 1747</div> 1748</body> 1749</html> 1750