doc/help/api-admin.html

   1 <!doctype html>
   2 <html>
   3 <!-- SECTION: Programming -->
   4   <head>
   5     <title>Administration APIs</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.11">
   9     <meta name="author" content="Unknown">
  10     <meta name="copyright" content="Unknown">
  11     <meta name="version" content="0.0">
  12     <style type="text/css"><!--
  13 BODY {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 H1, H2, H3, H4, H5, H6, P, TD, TH {
  18   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  19 }
  20
  21 KBD {
  22   font-family: monaco, courier, monospace;
  23   font-weight: bold;
  24 }
  25
  26 PRE {
  27   font-family: monaco, courier, monospace;
  28 }
  29
  30 PRE.command {
  31   border: dotted thin #7f7f7f;
  32   margin-left: 36pt;
  33   padding: 10px;
  34 }
  35
  36 P.compact {
  37   margin: 0;
  38 }
  39
  40 P.example {
  41   font-style: italic;
  42   margin-left: 36pt;
  43 }
  44
  45 DL.man DD {
  46   margin-left: 5em;
  47 }
  48
  49 DL.man DT {
  50   margin-left: 0;
  51 }
  52
  53 PRE.man {
  54   margin: 0;
  55 }
  56
  57 PRE.example {
  58   background: #eeeeee;
  59   border: dotted thin #999999;
  60   margin-left: 36pt;
  61   padding: 10pt;
  62 }
  63
  64 PRE.command EM, PRE.example EM {
  65   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  66 }
  67
  68 P.command {
  69   font-family: monaco, courier, monospace;
  70   margin-left: 36pt;
  71 }
  72
  73 P.formula {
  74   font-style: italic;
  75   margin-left: 36pt;
  76 }
  77
  78 BLOCKQUOTE {
  79   background: #eeeeee;
  80   border: solid thin #999999;
  81   padding: 10pt;
  82 }
  83
  84 A IMG {
  85   border: none;
  86 }
  87
  88 A:link:hover IMG {
  89   background: #f0f0f0;
  90   border-radius: 10px;
  91   -moz-border-radius: 10px;
  92 }
  93
  94 A:link, A:visited {
  95   font-weight: inherit;
  96   text-decoration: none;
  97 }
  98
  99 A:link:hover, A:visited:hover, A:active {
 100   text-decoration: underline;
 101 }
 102
 103 SUB, SUP {
 104   font-size: 50%;
 105 }
 106
 107 TR.data, TD.data, TR.data TD {
 108   margin-top: 10pt;
 109   padding: 5pt;
 110   border-bottom: solid 1pt #999999;
 111 }
 112
 113 TR.data TH {
 114   border-bottom: solid 1pt #999999;
 115   padding-top: 10pt;
 116   padding-left: 5pt;
 117   text-align: left;
 118 }
 119
 120 DIV.table TABLE {
 121   border: solid thin #999999;
 122   border-collapse: collapse;
 123   border-spacing: 0;
 124   margin-left: auto;
 125   margin-right: auto;
 126 }
 127
 128 DIV.table CAPTION {
 129   caption-side: top;
 130   font-size: 120%;
 131   font-style: italic;
 132   font-weight: bold;
 133   margin-left: auto;
 134   margin-right: auto;
 135 }
 136
 137 DIV.table TABLE TD {
 138   border: solid thin #cccccc;
 139   padding-top: 5pt;
 140 }
 141
 142 DIV.table TABLE TH {
 143   background: #cccccc;
 144   border: none;
 145   border-bottom: solid thin #999999;
 146 }
 147
 148 DIV.figure TABLE {
 149   margin-left: auto;
 150   margin-right: auto;
 151 }
 152
 153 DIV.figure CAPTION {
 154   caption-side: bottom;
 155   font-size: 120%;
 156   font-style: italic;
 157   font-weight: bold;
 158   margin-left: auto;
 159   margin-right: auto;
 160 }
 161
 162 TH.label {
 163   text-align: right;
 164   vertical-align: top;
 165 }
 166
 167 TH.sublabel {
 168   text-align: right;
 169   font-weight: normal;
 170 }
 171
 172 HR {
 173   border: solid thin;
 174 }
 175
 176 SPAN.info {
 177   background: black;
 178   border: thin solid black;
 179   color: white;
 180   font-size: 80%;
 181   font-style: italic;
 182   font-weight: bold;
 183   white-space: nowrap;
 184 }
 185
 186 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 187   float: right;
 188   font-size: 100%;
 189 }
 190
 191 H1.title {
 192 }
 193
 194 H2.title, H3.title {
 195   border-bottom: solid 2pt #000000;
 196 }
 197
 198 DIV.indent, TABLE.indent {
 199   margin-top: 2em;
 200   margin-left: auto;
 201   margin-right: auto;
 202   width: 90%;
 203 }
 204
 205 TABLE.indent {
 206   border-collapse: collapse;
 207 }
 208
 209 TABLE.indent TD, TABLE.indent TH {
 210   padding: 0;
 211 }
 212
 213 TABLE.list {
 214   border-collapse: collapse;
 215   margin-left: auto;
 216   margin-right: auto;
 217   width: 90%;
 218 }
 219
 220 TABLE.list TH {
 221   background: white;
 222   border-bottom: solid thin #cccccc;
 223   color: #444444;
 224   padding-top: 10pt;
 225   padding-left: 5pt;
 226   text-align: left;
 227   vertical-align: bottom;
 228   white-space: nowrap;
 229 }
 230
 231 TABLE.list TH A {
 232   color: #4444cc;
 233 }
 234
 235 TABLE.list TD {
 236   border-bottom: solid thin #eeeeee;
 237   padding-top: 5pt;
 238   padding-left: 5pt;
 239 }
 240
 241 TABLE.list TR:nth-child(even) {
 242   background: #f8f8f8;
 243 }
 244
 245 TABLE.list TR:nth-child(odd) {
 246   background: #f4f4f4;
 247 }
 248
 249 DT {
 250   margin-left: 36pt;
 251   margin-top: 12pt;
 252 }
 253
 254 DD {
 255   margin-left: 54pt;
 256 }
 257
 258 DL.category DT {
 259   font-weight: bold;
 260 }
 261
 262 P.summary {
 263   margin-left: 36pt;
 264   font-family: monaco, courier, monospace;
 265 }
 266
 267 DIV.summary TABLE {
 268   border: solid thin #999999;
 269   border-collapse: collapse;
 270   border-spacing: 0;
 271   margin: 10px;
 272 }
 273
 274 DIV.summary TABLE TD, DIV.summary TABLE TH {
 275   border: solid thin #999999;
 276   padding: 5px;
 277   text-align: left;
 278   vertical-align: top;
 279 }
 280
 281 DIV.summary TABLE THEAD TH {
 282   background: #eeeeee;
 283 }
 284
 285 /* API documentation styles... */
 286 div.body h1 {
 287   margin: 0;
 288 }
 289 div.body h2 {
 290   margin-top: 1.5em;
 291 }
 292 div.body h3, div.body h4, div.body h5 {
 293   margin-bottom: 0.5em;
 294   margin-top: 1.5em;
 295 }
 296 .class, .enumeration, .function, .struct, .typedef, .union {
 297   border-bottom: solid thin #999999;
 298   margin-bottom: 0;
 299   margin-top: 2em;
 300 }
 301 .description {
 302   margin-top: 0.5em;
 303 }
 304 code, p.code, pre, ul.code li {
 305   font-family: monaco, courier, monospace;
 306   font-size: 90%;
 307 }
 308 ul.code, ul.contents, ul.subcontents {
 309   list-style-type: none;
 310   margin: 0;
 311   padding-left: 0;
 312 }
 313 ul.code li {
 314   margin: 0;
 315 }
 316 ul.contents > li {
 317   margin-top: 1em;
 318 }
 319 ul.contents li ul.code, ul.contents li ul.subcontents {
 320   padding-left: 2em;
 321 }
 322 div.body dl {
 323   margin-left: 0;
 324   margin-top: 0;
 325 }
 326 div.body dt {
 327   font-style: italic;
 328   margin-left: 0;
 329   margin-top: 0;
 330 }
 331 div.body dd {
 332   margin-bottom: 0.5em;
 333 }
 334
 335 /* This is just for the HTML files generated with the framedhelp target */
 336 div.contents {
 337   background: #e8e8e8;
 338   border: solid thin black;
 339   padding: 10px;
 340 }
 341 div.contents h1 {
 342   font-size: 110%;
 343 }
 344 div.contents h2 {
 345   font-size: 100%;
 346 }
 347 div.contents ul.contents {
 348   font-size: 80%;
 349 }
 350 div.contents ul.subcontents li {
 351   margin-left: 1em;
 352   text-indent: -1em;
 353 }
 354 --></style>
 355   </head>
 356   <body>
 357 <!--
 358   Administrative API header for CUPS.
 359
 360   Copyright 2016 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'>Administrative APIs</h1>
 370
 371 <div class='summary'><table summary='General Information'>
 372 <thead>
 373 <tr>
 374         <th>Header</th>
 375         <th>cups/adminutil.h</th>
 376 </tr>
 377 </thead>
 378 <tbody>
 379 <tr>
 380         <th>Library</th>
 381         <td>-lcups</td>
 382 </tr>
 383 <tr>
 384         <th>See Also</th>
 385         <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
 386         Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
 387         Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a></td>
 388 </tr>
 389 </tbody>
 390 </table></div>
 391     <div class="contents">
 392       <h2 class="title">Contents</h2>
 393       <ul class="contents">
 394         <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 395           <li><a href="#SETTINGS">Scheduler Settings</a></li>
 396           <li><a href="#DEVICES">Devices</a></li>
 397         </ul></li>
 398         <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
 399           <li><a href="#cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></li>
 400           <li><a href="#cupsAdminExportSamba">cupsAdminExportSamba</a></li>
 401           <li><a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></li>
 402           <li><a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></li>
 403           <li><a href="#cupsGetDevices">cupsGetDevices</a></li>
 404         </ul></li>
 405         <li><a href="#TYPES">Data Types</a><ul class="subcontents">
 406           <li><a href="#cups_device_cb_t">cups_device_cb_t</a></li>
 407         </ul></li>
 408       </ul>
 409     </div>
 410     <div class="body">
 411 <!--
 412   Administrative API documentation for CUPS.
 413
 414   Copyright 2016 by Apple Inc.
 415
 416   These coded instructions, statements, and computer programs are the
 417   property of Apple Inc. and are protected by Federal copyright
 418   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 419   which should have been included with this file.  If this file is
 420   file is missing or damaged, see the license at "http://www.cups.org/".
 421 -->
 422
 423 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
 424
 425 <p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.</p>
 426
 427 <blockquote><b>Note:<b>
 428   <p>Administrative functions normally require administrative privileges to execute and must not be used in ordinary user applications!</p>
 429 </blockquote>
 430
 431 <h3><a name="SETTINGS">Scheduler Settings</a></h3>
 432
 433 <p>The <a href="#cupsAdminGetServerSettings"><code>cupsAdminGetServerSettings</code></a> and <a href="#cupsAdminSetServerSettings"><code>cupsAdminSetServerSettings</code></a> functions allow you to get and set simple directives and their values, respectively, in the <var>cupsd.conf</var> file for the CUPS scheduler. Settings are stored in CUPS option arrays which provide a simple list of string name/value pairs. While any simple <var>cupsd.conf</var> directive name can be specified, the following convenience names are also defined to control common complex directives:</p>
 434
 435 <ul>
 436   <li><code>CUPS_SERVER_DEBUG_LOGGING</code></li>: For <code>cupsAdminGetServerSettings</code>, a value of "1" means that the <code>LogLevel</code> directive is set to <code>debug</code> or <code>debug2</code> while a value of "0" means it is set to any other value. For <code>cupsAdminSetServerSettings</code> a value of "1" sets the <code>LogLeveL</code> to <code>debug</code> while a value of "0" sets it to <code>warn</code>.</li>
 437   <li><code>CUPS_SERVER_REMOTE_ADMIN</code></li>: A value of "1" specifies that administrative requests are accepted from remote addresses while "0" specifies that requests are only accepted from local addresses (loopback interface and domain sockets).</li>
 438   <li><code>CUPS_SERVER_REMOTE_ANY</code></li>: A value of "1" specifies that requests are accepts from any address while "0" specifies that requests are only accepted from the local subnet (when sharing is enabled) or local addresses (loopback interface and domain sockets).</li>
 439   <li><code>CUPS_SERVER_SHARE_PRINTERS</code></li>: A value of "1" specifies that printer sharing is enabled for selected printers and remote requests are accepted while a value of "0" specifies that printer sharing is disables and remote requests are not accepted.</li>
 440   <li><code>CUPS_SERVER_USER_CANCEL_ANY</code></li>: A value of "1" specifies that the default security policy allows any user to cancel any print job, regardless of the owner. A value of "0" specifies that only administrative users can cancel other user's jobs.</li>
 441 </ul>
 442
 443 <blockquote><b>Note:</b>
 444   <p>Changing settings will restart the CUPS scheduler.</p>
 445   <p>When printer sharing or the web interface are enabled, the scheduler's launch-on-demand functionality is effectively disabled. This can affect power usage, system performance, and the security profile of a system.</p>
 446 </blockquote>
 447
 448 <p>The recommended way to make changes to the <var>cupsd.conf</var> is to first call <a href="#cupsAdminGetServerSettings"><code>cupsAdminGetServerSettings</code></a>, make any changes to the returned option array, and then call <a href="#cupsAdminSetServerSettings"><code>cupsAdminSetServerSettings</code></a> to save those settings. For example, to enable the web interface:</p>
 449
 450 <pre class="example">
 451 #include &lt;cups/cups.h&gt;
 452 #include &lt;cups/adminutil.h&gt;
 453
 454 void
 455 enable_web_interface(void)
 456 {
 457   int num_settings = 0;           /* Number of settings */
 458   cups_option_t *settings = NULL; /* Settings */
 459
 460
 461   if (!<a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a>(CUPS_HTTP_DEFAULT, &amp;num_settings, &amp;settings))
 462   {
 463     fprintf(stderr, "ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
 464     return;
 465   }
 466
 467   num_settings = <a href="api-cups.html#cupsAddOption">cupsAddOption</a>("WebInterface", "Yes", num_settings, &amp;settings);
 468
 469   if (!<a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
 470   {
 471     fprintf(stderr, "ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
 472   }
 473
 474   <a href="api-cups.html#cupsFreeOptions">cupsFreeOptions</a>(num_settings, settings);
 475 }
 476 </pre>
 477
 478 <h3><a name="DEVICES">Devices</a></h3>
 479
 480 <p>Printers can be discovered through the CUPS scheduler using the <a href="#cupsGetDevices"><code>cupsGetDevices</code></a> API. Typically this API is used to locate printers to add the the system. Each device that is found will cause a supplied callback function to be executed. For example, to list the available printer devices that can be found within 30 seconds:</p>
 481
 482 <pre class="example">
 483 #include &lt;cups/cups.h&gt;
 484 #include &lt;cups/adminutil.h&gt;
 485
 486
 487 void
 488 get_devices_cb(
 489     const char *device_class,           /* I - Class */
 490     const char *device_id,              /* I - 1284 device ID */
 491     const char *device_info,            /* I - Description */
 492     const char *device_make_and_model,  /* I - Make and model */
 493     const char *device_uri,             /* I - Device URI */
 494     const char *device_location,        /* I - Location */
 495     void       *user_data)              /* I - User data */
 496 {
 497   puts(device_uri);
 498 }
 499
 500
 501 void
 502 show_devices(void)
 503 {
 504   <a href="#cupsGetDevices">cupsGetDevices</a>(CUPS_HTTP_DEFAULT, 30, NULL, NULL, get_devices_cb, NULL);
 505 }
 506 </pre>
 507       <h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
 508 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
 509         <p class="description">Create the Windows PPD file for a printer.</p>
 510 <p class="code">
 511 char *cupsAdminCreateWindowsPPD(http_t *http, const char *dest, char *buffer, int bufsize);</p>
 512 <h4 class="parameters">Parameters</h4>
 513 <table class="list"><tbody>
 514 <tr><th>http</th>
 515         <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
 516 <tr><th>dest</th>
 517         <td class="description">Printer or class</td></tr>
 518 <tr><th>buffer</th>
 519         <td class="description">Filename buffer</td></tr>
 520 <tr><th>bufsize</th>
 521         <td class="description">Size of filename buffer</td></tr>
 522 </tbody></table>
 523 <h4 class="returnvalue">Return Value</h4>
 524         <p class="description">PPD file or NULL</p>
 525 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
 526         <p class="description">Export a printer to Samba.</p>
 527 <p class="code">
 528 int cupsAdminExportSamba(const char *dest, const char *ppd, const char *samba_server, const char *samba_user, const char *samba_password, FILE *logfile);</p>
 529 <h4 class="parameters">Parameters</h4>
 530 <table class="list"><tbody>
 531 <tr><th>dest</th>
 532         <td class="description">Destination to export</td></tr>
 533 <tr><th>ppd</th>
 534         <td class="description">PPD file</td></tr>
 535 <tr><th>samba_server</th>
 536         <td class="description">Samba server</td></tr>
 537 <tr><th>samba_user</th>
 538         <td class="description">Samba username</td></tr>
 539 <tr><th>samba_password</th>
 540         <td class="description">Samba password</td></tr>
 541 <tr><th>logfile</th>
 542         <td class="description">Log file, if any</td></tr>
 543 </tbody></table>
 544 <h4 class="returnvalue">Return Value</h4>
 545         <p class="description">1 on success, 0 on failure</p>
 546 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
 547         <p class="description">Get settings from the server.</p>
 548 <p class="code">
 549 int cupsAdminGetServerSettings(http_t *http, int *num_settings, cups_option_t **settings);</p>
 550 <h4 class="parameters">Parameters</h4>
 551 <table class="list"><tbody>
 552 <tr><th>http</th>
 553         <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
 554 <tr><th>num_settings</th>
 555         <td class="description">Number of settings</td></tr>
 556 <tr><th>settings</th>
 557         <td class="description">Settings</td></tr>
 558 </tbody></table>
 559 <h4 class="returnvalue">Return Value</h4>
 560         <p class="description">1 on success, 0 on failure</p>
 561 <h4 class="discussion">Discussion</h4>
 562         <p class="discussion">The returned settings should be freed with cupsFreeOptions() when
 563 you are done with them.
 564
 565 </p>
 566 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
 567         <p class="description">Set settings on the server.</p>
 568 <p class="code">
 569 int cupsAdminSetServerSettings(http_t *http, int num_settings, cups_option_t *settings);</p>
 570 <h4 class="parameters">Parameters</h4>
 571 <table class="list"><tbody>
 572 <tr><th>http</th>
 573         <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
 574 <tr><th>num_settings</th>
 575         <td class="description">Number of settings</td></tr>
 576 <tr><th>settings</th>
 577         <td class="description">Settings</td></tr>
 578 </tbody></table>
 579 <h4 class="returnvalue">Return Value</h4>
 580         <p class="description">1 on success, 0 on failure</p>
 581 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetDevices">cupsGetDevices</a></h3>
 582         <p class="description">Get available printer devices.</p>
 583 <p class="code">
 584 ipp_status_t cupsGetDevices(http_t *http, int timeout, const char *include_schemes, const char *exclude_schemes, <a href="#cups_device_cb_t">cups_device_cb_t</a> callback, void *user_data);</p>
 585 <h4 class="parameters">Parameters</h4>
 586 <table class="list"><tbody>
 587 <tr><th>http</th>
 588         <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
 589 <tr><th>timeout</th>
 590         <td class="description">Timeout in seconds or <code>CUPS_TIMEOUT_DEFAULT</code></td></tr>
 591 <tr><th>include_schemes</th>
 592         <td class="description">Comma-separated URI schemes to include or <code>CUPS_INCLUDE_ALL</code></td></tr>
 593 <tr><th>exclude_schemes</th>
 594         <td class="description">Comma-separated URI schemes to exclude or <code>CUPS_EXCLUDE_NONE</code></td></tr>
 595 <tr><th>callback</th>
 596         <td class="description">Callback function</td></tr>
 597 <tr><th>user_data</th>
 598         <td class="description">User data pointer</td></tr>
 599 </tbody></table>
 600 <h4 class="returnvalue">Return Value</h4>
 601         <p class="description">Request status - <code>IPP_OK</code> on success.</p>
 602 <h4 class="discussion">Discussion</h4>
 603         <p class="discussion">This function sends a CUPS-Get-Devices request and streams the discovered
 604 devices to the specified callback function. The &quot;timeout&quot; parameter controls
 605 how long the request lasts, while the &quot;include_schemes&quot; and &quot;exclude_schemes&quot;
 606 parameters provide comma-delimited lists of backends to include or omit from
 607 the request respectively.
 608
 609 </p>
 610       <h2 class="title"><a id="TYPES">Data Types</a></h2>
 611       <h3 class="typedef"><a id="cups_device_cb_t"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span>cups_device_cb_t</a></h3>
 612         <p class="description">Device callback
 613 </p>
 614       <p class="code">
 615 typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);
 616 </p>
 617     </div>
 618   </body>
 619 </html>