3 <!-- SECTION: Programming -->
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=
"codedoc v3.1">
9 <meta name=
"author" content=
"Unknown">
10 <meta name=
"copyright" content=
"Unknown">
11 <meta name=
"version" content=
"0.0">
12 <style type=
"text/css"><!--
14 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
17 H1, H2, H3, H4, H5, H6, P, TD, TH {
18 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
21 H1 { font-size: 2em; }
22 H2 { font-size: 1.75em; }
23 H3 { font-size: 1.5em; }
24 H4 { font-size: 1.25em; }
27 font-family: monaco, courier, monospace;
32 font-family: monaco, courier, monospace;
36 border-left: solid 2px #777;
45 PRE.command, PRE.example {
72 PRE.command EM, PRE.example EM {
73 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
77 font-family: monaco, courier, monospace;
93 -moz-border-radius: 10px;
98 text-decoration: none;
101 A:link:hover, A:visited:hover, A:active {
102 text-decoration: underline;
109 TR.data, TD.data, TR.data TD {
112 border-bottom: solid 1pt #999999;
116 border-bottom: solid 1pt #999999;
123 border: solid thin #999999;
124 border-collapse: collapse;
140 border: solid thin #cccccc;
147 border-bottom: solid thin #999999;
156 caption-side: bottom;
180 border: thin solid black;
188 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
197 border-bottom: solid 2pt #000000;
200 DIV.indent, TABLE.indent {
208 border-collapse: collapse;
211 TABLE.indent TD, TABLE.indent TH {
216 border-collapse: collapse;
224 border-bottom: solid thin #cccccc;
229 vertical-align: bottom;
238 border-bottom: solid thin #eeeeee;
243 TABLE.list TR:nth-child(even) {
247 TABLE.list TR:nth-child(odd) {
266 font-family: monaco, courier, monospace;
270 border: solid thin #999999;
271 border-collapse: collapse;
276 DIV.summary TABLE TD, DIV.summary TABLE TH {
277 border: solid thin #999999;
283 DIV.summary TABLE THEAD TH {
287 /* API documentation styles... */
299 margin-bottom: 0.5em;
304 margin-bottom: 0.5em;
309 margin-bottom: 0.5em;
314 border: solid thin black;
323 div.contents ul.contents {
327 border-bottom: solid 2px gray;
337 border-bottom: solid 2px gray;
340 border-bottom: solid 2px gray;
352 border-bottom: solid 2px gray;
355 border-bottom: solid 2px gray;
358 border-bottom: solid 2px gray;
362 h1, h2, h3, h4, h5, h6 {
363 page-break-inside: avoid;
366 border: solid thin gray;
367 box-shadow: 3px 3px 5px rgba(0,0,0,0.5);
368 padding: 10px 10px 0px;
369 page-break-inside: avoid;
371 p code, li code, p.code, pre, ul.code li {
372 background: rgba(127,127,127,0.1);
373 border: thin dotted gray;
374 font-family: monospace;
376 -webkit-hyphens: manual;
377 page-break-inside: avoid;
379 p.code, pre, ul.code li {
386 text-decoration: none;
390 border: solid thin black;
397 h2 span.info, h3 span.info, h4 span.info {
403 h2.title span.info, h3.title span.info, h4.title span.info {
404 border-bottom-left-radius: 0px;
405 border-bottom-right-radius: 0px;
410 ul.code, ul.contents, ul.subcontents {
411 list-style-type: none;
421 ul.contents li ul.code, ul.contents li ul.subcontents {
425 border-collapse: collapse;
428 table.list tr:nth-child(even) {
429 background: rgba(127,127,127,0.1);]n}
431 border-right: 2px solid gray;
432 font-family: monospace;
433 padding: 5px 10px 5px 2px;
438 padding: 5px 2px 5px 10px;
445 border-bottom: solid 2px black;
448 border-bottom: solid 2px black;
454 Administrative API header for CUPS.
456 Copyright © 2016 by Apple Inc.
458 Licensed under Apache License v2.0. See the file "LICENSE" for more
462 <h1 class='title'
>Administrative APIs
</h1>
464 <div class='summary'
><table summary='General Information'
>
468 <th>cups/adminutil.h
</th>
478 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a><br>
479 Programming:
<a href='api-cups.html' target='_top'
>CUPS API
</a><br>
480 Programming:
<a href='api-httpipp.html' target='_top'
>HTTP and IPP APIs
</a></td>
484 <div class=
"contents">
485 <h2 class=
"title">Contents
</h2>
486 <ul class=
"contents">
487 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
488 <li><a href=
"#SETTINGS">Scheduler Settings
</a></li>
489 <li><a href=
"#DEVICES">Devices
</a></li>
491 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"subcontents">
492 <li><a href=
"#cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD
</a></li>
493 <li><a href=
"#cupsAdminExportSamba">cupsAdminExportSamba
</a></li>
494 <li><a href=
"#cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a></li>
495 <li><a href=
"#cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a></li>
496 <li><a href=
"#cupsGetDevices">cupsGetDevices
</a></li>
498 <li><a href=
"#TYPES">Data Types
</a><ul class=
"subcontents">
499 <li><a href=
"#cups_device_cb_t">cups_device_cb_t
</a></li>
505 Administrative API documentation for CUPS.
507 Copyright © 2016 by Apple Inc.
509 Licensed under Apache License v2.0. See the file "LICENSE" for more
513 <h2 class=
"title"><a name=
"OVERVIEW">Overview
</a></h2>
515 <p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.
</p>
517 <blockquote><b>Note:
</b>
518 <p>Administrative functions normally require administrative privileges to execute and must not be used in ordinary user applications!
</p>
521 <h3><a name=
"SETTINGS">Scheduler Settings
</a></h3>
523 <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>
526 <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>
527 <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>
528 <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>
529 <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>
530 <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>
533 <blockquote><b>Note:
</b>
534 <p>Changing settings will restart the CUPS scheduler.
</p>
535 <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>
538 <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>
540 <pre class=
"example">
541 #include
<cups/cups.h
>
542 #include
<cups/adminutil.h
>
545 enable_web_interface(void)
547 int num_settings =
0; /* Number of settings */
548 cups_option_t *settings = NULL; /* Settings */
551 if (!
<a href=
"#cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a>(CUPS_HTTP_DEFAULT,
&num_settings,
&settings))
553 fprintf(stderr,
"ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
557 num_settings =
<a href=
"api-cups.html#cupsAddOption">cupsAddOption
</a>(
"WebInterface",
"Yes", num_settings,
&settings);
559 if (!
<a href=
"#cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
561 fprintf(stderr,
"ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
564 <a href=
"api-cups.html#cupsFreeOptions">cupsFreeOptions
</a>(num_settings, settings);
568 <h3><a name=
"DEVICES">Devices
</a></h3>
570 <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>
572 <pre class=
"example">
573 #include
<cups/cups.h
>
574 #include
<cups/adminutil.h
>
579 const char *device_class, /* I - Class */
580 const char *device_id, /* I -
1284 device ID */
581 const char *device_info, /* I - Description */
582 const char *device_make_and_model, /* I - Make and model */
583 const char *device_uri, /* I - Device URI */
584 const char *device_location, /* I - Location */
585 void *user_data) /* I - User data */
594 <a href=
"#cupsGetDevices">cupsGetDevices
</a>(CUPS_HTTP_DEFAULT,
30, NULL, NULL, get_devices_cb, NULL);
597 <h2 class=
"title"><a id=
"FUNCTIONS">Functions
</a></h2>
598 <h3 class=
"function"><span class=
"info"> DEPRECATED
 </span><a id=
"cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD
</a></h3>
599 <p class=
"description">Create the Windows PPD file for a printer.
</p>
601 char *cupsAdminCreateWindowsPPD(http_t *http, const char *dest, char *buffer, int bufsize);
</p>
602 <h4 class=
"parameters">Parameters
</h4>
603 <table class=
"list"><tbody>
605 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
607 <td class=
"description">Printer or class
</td></tr>
609 <td class=
"description">Filename buffer
</td></tr>
611 <td class=
"description">Size of filename buffer
</td></tr>
613 <h4 class=
"returnvalue">Return Value
</h4>
614 <p class=
"description">PPD file or NULL
</p>
615 <h3 class=
"function"><span class=
"info"> DEPRECATED
 </span><a id=
"cupsAdminExportSamba">cupsAdminExportSamba
</a></h3>
616 <p class=
"description">Export a printer to Samba.
</p>
618 int cupsAdminExportSamba(const char *dest, const char *ppd, const char *samba_server, const char *samba_user, const char *samba_password, FILE *logfile);
</p>
619 <h4 class=
"parameters">Parameters
</h4>
620 <table class=
"list"><tbody>
622 <td class=
"description">Destination to export
</td></tr>
624 <td class=
"description">PPD file
</td></tr>
625 <tr><th>samba_server
</th>
626 <td class=
"description">Samba server
</td></tr>
627 <tr><th>samba_user
</th>
628 <td class=
"description">Samba username
</td></tr>
629 <tr><th>samba_password
</th>
630 <td class=
"description">Samba password
</td></tr>
632 <td class=
"description">Log file, if any
</td></tr>
634 <h4 class=
"returnvalue">Return Value
</h4>
635 <p class=
"description">1 on success,
0 on failure
</p>
636 <h3 class=
"function"><span class=
"info"> CUPS
1.3/macOS
10.5 </span><a id=
"cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a></h3>
637 <p class=
"description">Get settings from the server.
</p>
639 int cupsAdminGetServerSettings(http_t *http, int *num_settings, cups_option_t **settings);
</p>
640 <h4 class=
"parameters">Parameters
</h4>
641 <table class=
"list"><tbody>
643 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
644 <tr><th>num_settings
</th>
645 <td class=
"description">Number of settings
</td></tr>
646 <tr><th>settings
</th>
647 <td class=
"description">Settings
</td></tr>
649 <h4 class=
"returnvalue">Return Value
</h4>
650 <p class=
"description">1 on success,
0 on failure
</p>
651 <h4 class=
"discussion">Discussion
</h4>
652 <p class=
"discussion">The returned settings should be freed with cupsFreeOptions() when
653 you are done with them.
656 <h3 class=
"function"><span class=
"info"> CUPS
1.3/macOS
10.5 </span><a id=
"cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a></h3>
657 <p class=
"description">Set settings on the server.
</p>
659 int cupsAdminSetServerSettings(http_t *http, int num_settings, cups_option_t *settings);
</p>
660 <h4 class=
"parameters">Parameters
</h4>
661 <table class=
"list"><tbody>
663 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
664 <tr><th>num_settings
</th>
665 <td class=
"description">Number of settings
</td></tr>
666 <tr><th>settings
</th>
667 <td class=
"description">Settings
</td></tr>
669 <h4 class=
"returnvalue">Return Value
</h4>
670 <p class=
"description">1 on success,
0 on failure
</p>
671 <h3 class=
"function"><span class=
"info"> DEPRECATED
 </span><a id=
"cupsGetDevices">cupsGetDevices
</a></h3>
672 <p class=
"description">Get available printer devices.
</p>
674 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>
675 <h4 class=
"parameters">Parameters
</h4>
676 <table class=
"list"><tbody>
678 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
680 <td class=
"description">Timeout in seconds or
<code>CUPS_TIMEOUT_DEFAULT
</code></td></tr>
681 <tr><th>include_schemes
</th>
682 <td class=
"description">Comma-separated URI schemes to include or
<code>CUPS_INCLUDE_ALL
</code></td></tr>
683 <tr><th>exclude_schemes
</th>
684 <td class=
"description">Comma-separated URI schemes to exclude or
<code>CUPS_EXCLUDE_NONE
</code></td></tr>
685 <tr><th>callback
</th>
686 <td class=
"description">Callback function
</td></tr>
687 <tr><th>user_data
</th>
688 <td class=
"description">User data pointer
</td></tr>
690 <h4 class=
"returnvalue">Return Value
</h4>
691 <p class=
"description">Request status -
<code>IPP_OK
</code> on success.
</p>
692 <h4 class=
"discussion">Discussion
</h4>
693 <p class=
"discussion">This function sends a CUPS-Get-Devices request and streams the discovered
694 devices to the specified callback function. The
"timeout
" parameter controls
695 how long the request lasts, while the
"include_schemes
" and
"exclude_schemes
"
696 parameters provide comma-delimited lists of backends to include or omit from
697 the request respectively.
<br>
699 This function is deprecated with the IPP printer discovery functionality
700 being provided by the
<a href=
"#cupsEnumDests"><code>cupsEnumDests
</code></a> and @cupsGetDests@ functions.
703 <h2 class=
"title"><a id=
"TYPES">Data Types
</a></h2>
704 <h3 class=
"typedef"><a id=
"cups_device_cb_t"><span class=
"info"> CUPS
1.4/macOS
10.6 </span>cups_device_cb_t
</a></h3>
705 <p class=
"description">Device callback
708 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);