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=
"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"><!--
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;
22 font-family: monaco, courier, monospace;
27 font-family: monaco, courier, monospace;
31 border: dotted thin #7f7f7f;
59 border: dotted thin #999999;
64 PRE.command EM, PRE.example EM {
65 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
69 font-family: monaco, courier, monospace;
80 border: solid thin #999999;
91 -moz-border-radius: 10px;
96 text-decoration: none;
99 A:link:hover, A:visited:hover, A:active {
100 text-decoration: underline;
107 TR.data, TD.data, TR.data TD {
110 border-bottom: solid 1pt #999999;
114 border-bottom: solid 1pt #999999;
121 border: solid thin #999999;
122 border-collapse: collapse;
138 border: solid thin #cccccc;
145 border-bottom: solid thin #999999;
154 caption-side: bottom;
178 border: thin solid black;
186 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
195 border-bottom: solid 2pt #000000;
198 DIV.indent, TABLE.indent {
206 border-collapse: collapse;
209 TABLE.indent TD, TABLE.indent TH {
214 border-collapse: collapse;
222 border-bottom: solid thin #cccccc;
227 vertical-align: bottom;
236 border-bottom: solid thin #eeeeee;
241 TABLE.list TR:nth-child(even) {
245 TABLE.list TR:nth-child(odd) {
264 font-family: monaco, courier, monospace;
268 border: solid thin #999999;
269 border-collapse: collapse;
274 DIV.summary TABLE TD, DIV.summary TABLE TH {
275 border: solid thin #999999;
281 DIV.summary TABLE THEAD TH {
285 /* API documentation styles... */
292 div.body h3, div.body h4, div.body h5 {
293 margin-bottom: 0.5em;
296 .class, .enumeration, .function, .struct, .typedef, .union {
297 border-bottom: solid thin #999999;
304 code, p.code, pre, ul.code li {
305 font-family: monaco, courier, monospace;
308 ul.code, ul.contents, ul.subcontents {
309 list-style-type: none;
319 ul.contents li ul.code, ul.contents li ul.subcontents {
332 margin-bottom: 0.5em;
335 /* This is just for the HTML files generated with the framedhelp target */
338 border: solid thin black;
347 div.contents ul.contents {
350 div.contents ul.subcontents li {
358 Administrative API header for CUPS.
360 Copyright 2016 by Apple Inc.
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/".
369 <h1 class='title'
>Administrative APIs
</h1>
371 <div class='summary'
><table summary='General Information'
>
375 <th>cups/adminutil.h
</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>
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>
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>
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>
412 Administrative API documentation for CUPS.
414 Copyright 2016 by Apple Inc.
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/".
423 <h2 class=
"title"><a name=
"OVERVIEW">Overview
</a></h2>
425 <p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.
</p>
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>
431 <h3><a name=
"SETTINGS">Scheduler Settings
</a></h3>
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>
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>
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>
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>
450 <pre class=
"example">
451 #include
<cups/cups.h
>
452 #include
<cups/adminutil.h
>
455 enable_web_interface(void)
457 int num_settings =
0; /* Number of settings */
458 cups_option_t *settings = NULL; /* Settings */
461 if (!
<a href=
"#cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a>(CUPS_HTTP_DEFAULT,
&num_settings,
&settings))
463 fprintf(stderr,
"ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
467 num_settings =
<a href=
"api-cups.html#cupsAddOption">cupsAddOption
</a>(
"WebInterface",
"Yes", num_settings,
&settings);
469 if (!
<a href=
"#cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
471 fprintf(stderr,
"ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
474 <a href=
"api-cups.html#cupsFreeOptions">cupsFreeOptions
</a>(num_settings, settings);
478 <h3><a name=
"DEVICES">Devices
</a></h3>
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>
482 <pre class=
"example">
483 #include
<cups/cups.h
>
484 #include
<cups/adminutil.h
>
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 */
504 <a href=
"#cupsGetDevices">cupsGetDevices
</a>(CUPS_HTTP_DEFAULT,
30, NULL, NULL, get_devices_cb, NULL);
507 <h2 class=
"title"><a id=
"FUNCTIONS">Functions
</a></h2>
508 <h3 class=
"function"><span class=
"info"> DEPRECATED
 </span><a id=
"cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD
</a></h3>
509 <p class=
"description">Create the Windows PPD file for a printer.
</p>
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>
515 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
517 <td class=
"description">Printer or class
</td></tr>
519 <td class=
"description">Filename buffer
</td></tr>
521 <td class=
"description">Size of filename buffer
</td></tr>
523 <h4 class=
"returnvalue">Return Value
</h4>
524 <p class=
"description">PPD file or NULL
</p>
525 <h3 class=
"function"><span class=
"info"> DEPRECATED
 </span><a id=
"cupsAdminExportSamba">cupsAdminExportSamba
</a></h3>
526 <p class=
"description">Export a printer to Samba.
</p>
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>
532 <td class=
"description">Destination to export
</td></tr>
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>
542 <td class=
"description">Log file, if any
</td></tr>
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"> CUPS
1.3/macOS
10.5 </span><a id=
"cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a></h3>
547 <p class=
"description">Get settings from the server.
</p>
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>
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>
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.
566 <h3 class=
"function"><span class=
"info"> CUPS
1.3/macOS
10.5 </span><a id=
"cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a></h3>
567 <p class=
"description">Set settings on the server.
</p>
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>
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>
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"> CUPS
1.4/macOS
10.6 </span><a id=
"cupsGetDevices">cupsGetDevices
</a></h3>
582 <p class=
"description">Get available printer devices.
</p>
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>
588 <td class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></td></tr>
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>
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
"timeout
" parameter controls
605 how long the request lasts, while the
"include_schemes
" and
"exclude_schemes
"
606 parameters provide comma-delimited lists of backends to include or omit from
607 the request respectively.
610 <h2 class=
"title"><a id=
"TYPES">Data Types
</a></h2>
611 <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>
612 <p class=
"description">Device callback
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);