1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
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.8">
9 <style type=
"text/css"><!--
11 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
14 H1, H2, H3, H4, H5, H6, P, TD, TH {
15 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
19 font-family: monaco, courier, monospace;
24 font-family: monaco, courier, monospace;
28 border: dotted thin #7f7f7f;
56 border: dotted thin #999999;
61 PRE.command EM, PRE.example EM {
62 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
66 font-family: monaco, courier, monospace;
77 border: solid thin #999999;
88 -moz-border-radius: 10px;
93 text-decoration: none;
96 A:link:hover, A:visited:hover, A:active {
97 text-decoration: underline;
104 TR.data, TD.data, TR.data TD {
107 border-bottom: solid 1pt #999999;
111 border-bottom: solid 1pt #999999;
118 border: solid thin #999999;
119 border-collapse: collapse;
135 border: solid thin #cccccc;
142 border-bottom: solid thin #999999;
151 caption-side: bottom;
175 border: thin solid black;
183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
192 border-bottom: solid 2pt #000000;
195 DIV.indent, TABLE.indent {
203 border-collapse: collapse;
206 TABLE.indent TD, TABLE.indent TH {
211 border-collapse: collapse;
219 border-bottom: solid thin #cccccc;
224 vertical-align: bottom;
233 border-bottom: solid thin #eeeeee;
238 TABLE.list TR:nth-child(even) {
242 TABLE.list TR:nth-child(odd) {
261 font-family: monaco, courier, monospace;
265 border: solid thin #999999;
266 border-collapse: collapse;
271 DIV.summary TABLE TD, DIV.summary TABLE TH {
272 border: solid thin #999999;
278 DIV.summary TABLE THEAD TH {
282 /* API documentation styles... */
289 div.body h3, div.body h4, div.body h5 {
290 margin-bottom: 0.5em;
293 .class, .enumeration, .function, .struct, .typedef, .union {
294 border-bottom: solid thin #999999;
301 code, p.code, pre, ul.code li {
302 font-family: monaco, courier, monospace;
305 ul.code, ul.contents, ul.subcontents {
306 list-style-type: none;
316 ul.contents li ul.code, ul.contents li ul.subcontents {
329 margin-bottom: 0.5em;
332 /* This is just for the HTML files generated with the framedhelp target */
335 border: solid thin black;
344 div.contents ul.contents {
347 div.contents ul.subcontents li {
356 Administrative API header for CUPS.
358 Copyright 2016 by Apple Inc.
360 These coded instructions, statements, and computer programs are the
361 property of Apple Inc. and are protected by Federal copyright
362 law. Distribution and use rights are outlined in the file "LICENSE.txt"
363 which should have been included with this file. If this file is
364 file is missing or damaged, see the license at "http://www.cups.org/".
367 <h1 class='title'
>Administrative APIs
</h1>
369 <div class='summary'
><table summary='General Information'
>
373 <th>cups/adminutil.h
</th>
383 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a><br>
384 Programming:
<a href='api-cups.html' target='_top'
>CUPS API
</a><br>
385 Programming:
<a href='api-httpipp.html' target='_top'
>HTTP and IPP APIs
</a></td>
389 <h2 class=
"title">Contents
</h2>
390 <ul class=
"contents">
391 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
392 <li><a href=
"#SETTINGS">Scheduler Settings
</a></li>
393 <li><a href=
"#DEVICES">Devices
</a></li>
395 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
396 <li><a href=
"#cupsAdminCreateWindowsPPD" title=
"Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD
</a></li>
397 <li><a href=
"#cupsAdminExportSamba" title=
"Export a printer to Samba.">cupsAdminExportSamba
</a></li>
398 <li><a href=
"#cupsAdminGetServerSettings" title=
"Get settings from the server.">cupsAdminGetServerSettings
</a></li>
399 <li><a href=
"#cupsAdminSetServerSettings" title=
"Set settings on the server.">cupsAdminSetServerSettings
</a></li>
400 <li><a href=
"#cupsGetDevices" title=
"Get available printer devices.">cupsGetDevices
</a></li>
402 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
403 <li><a href=
"#cups_device_cb_t" title=
"Device callback
404 ">cups_device_cb_t
</a></li>
408 Administrative API documentation for CUPS.
410 Copyright 2016 by Apple Inc.
412 These coded instructions, statements, and computer programs are the
413 property of Apple Inc. and are protected by Federal copyright
414 law. Distribution and use rights are outlined in the file "LICENSE.txt"
415 which should have been included with this file. If this file is
416 file is missing or damaged, see the license at "http://www.cups.org/".
419 <h2 class=
"title"><a name=
"OVERVIEW">Overview
</a></h2>
421 <p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.
</p>
423 <blockquote><b>Note:
<b>
424 <p>Administrative functions normally require administrative privileges to execute and must not be used in ordinary user applications!
</p>
427 <h3><a name=
"SETTINGS">Scheduler Settings
</a></h3>
429 <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>
432 <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>
433 <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>
434 <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>
435 <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>
436 <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>
439 <blockquote><b>Note:
</b>
440 <p>Changing settings will restart the CUPS scheduler.
</p>
441 <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>
444 <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>
446 <pre class=
"example">
447 #include
<cups/cups.h
>
448 #include
<cups/adminutil.h
>
451 enable_web_interface(void)
453 int num_settings =
0; /* Number of settings */
454 cups_option_t *settings = NULL; /* Settings */
457 if (!
<a href=
"#cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a>(CUPS_HTTP_DEFAULT,
&num_settings,
&settings))
459 fprintf(stderr,
"ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
463 num_settings =
<a href=
"api-cups.html#cupsAddOption">cupsAddOption
</a>(
"WebInterface",
"Yes", num_settings,
&settings);
465 if (!
<a href=
"#cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
467 fprintf(stderr,
"ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
470 <a href=
"api-cups.html#cupsFreeOptions">cupsFreeOptions
</a>(num_settings, settings);
474 <h3><a name=
"DEVICES">Devices
</a></h3>
476 <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>
478 <pre class=
"example">
479 #include
<cups/cups.h
>
480 #include
<cups/adminutil.h
>
485 const char *device_class, /* I - Class */
486 const char *device_id, /* I -
1284 device ID */
487 const char *device_info, /* I - Description */
488 const char *device_make_and_model, /* I - Make and model */
489 const char *device_uri, /* I - Device URI */
490 const char *device_location, /* I - Location */
491 void *user_data) /* I - User data */
500 <a href=
"#cupsGetDevices">cupsGetDevices
</a>(CUPS_HTTP_DEFAULT,
30, NULL, NULL, get_devices_cb, NULL);
503 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
504 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD
</a></h3>
505 <p class=
"description">Create the Windows PPD file for a printer.
</p>
507 char *cupsAdminCreateWindowsPPD (
<br>
508 http_t *http,
<br>
509 const char *dest,
<br>
510 char *buffer,
<br>
511 int bufsize
<br>
513 <h4 class=
"parameters">Parameters
</h4>
516 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
518 <dd class=
"description">Printer or class
</dd>
520 <dd class=
"description">Filename buffer
</dd>
522 <dd class=
"description">Size of filename buffer
</dd>
524 <h4 class=
"returnvalue">Return Value
</h4>
525 <p class=
"description">PPD file or NULL
</p>
526 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsAdminExportSamba">cupsAdminExportSamba
</a></h3>
527 <p class=
"description">Export a printer to Samba.
</p>
529 int cupsAdminExportSamba (
<br>
530 const char *dest,
<br>
531 const char *ppd,
<br>
532 const char *samba_server,
<br>
533 const char *samba_user,
<br>
534 const char *samba_password,
<br>
535 FILE *logfile
<br>
537 <h4 class=
"parameters">Parameters
</h4>
540 <dd class=
"description">Destination to export
</dd>
542 <dd class=
"description">PPD file
</dd>
543 <dt>samba_server
</dt>
544 <dd class=
"description">Samba server
</dd>
546 <dd class=
"description">Samba username
</dd>
547 <dt>samba_password
</dt>
548 <dd class=
"description">Samba password
</dd>
550 <dd class=
"description">Log file, if any
</dd>
552 <h4 class=
"returnvalue">Return Value
</h4>
553 <p class=
"description">1 on success,
0 on failure
</p>
554 <h3 class=
"function"><span class=
"info"> CUPS
1.3/OS X
10.5 </span><a name=
"cupsAdminGetServerSettings">cupsAdminGetServerSettings
</a></h3>
555 <p class=
"description">Get settings from the server.
</p>
557 int cupsAdminGetServerSettings (
<br>
558 http_t *http,
<br>
559 int *num_settings,
<br>
560 cups_option_t **settings
<br>
562 <h4 class=
"parameters">Parameters
</h4>
565 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
566 <dt>num_settings
</dt>
567 <dd class=
"description">Number of settings
</dd>
569 <dd class=
"description">Settings
</dd>
571 <h4 class=
"returnvalue">Return Value
</h4>
572 <p class=
"description">1 on success,
0 on failure
</p>
573 <h4 class=
"discussion">Discussion
</h4>
574 <p class=
"discussion">The returned settings should be freed with cupsFreeOptions() when
575 you are done with them.
578 <h3 class=
"function"><span class=
"info"> CUPS
1.3/OS X
10.5 </span><a name=
"cupsAdminSetServerSettings">cupsAdminSetServerSettings
</a></h3>
579 <p class=
"description">Set settings on the server.
</p>
581 int cupsAdminSetServerSettings (
<br>
582 http_t *http,
<br>
583 int num_settings,
<br>
584 cups_option_t *settings
<br>
586 <h4 class=
"parameters">Parameters
</h4>
589 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
590 <dt>num_settings
</dt>
591 <dd class=
"description">Number of settings
</dd>
593 <dd class=
"description">Settings
</dd>
595 <h4 class=
"returnvalue">Return Value
</h4>
596 <p class=
"description">1 on success,
0 on failure
</p>
597 <h3 class=
"function"><span class=
"info"> CUPS
1.4/OS X
10.6 </span><a name=
"cupsGetDevices">cupsGetDevices
</a></h3>
598 <p class=
"description">Get available printer devices.
</p>
600 ipp_status_t cupsGetDevices (
<br>
601 http_t *http,
<br>
602 int timeout,
<br>
603 const char *include_schemes,
<br>
604 const char *exclude_schemes,
<br>
605 <a href=
"#cups_device_cb_t">cups_device_cb_t
</a> callback,
<br>
606 void *user_data
<br>
608 <h4 class=
"parameters">Parameters
</h4>
611 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
613 <dd class=
"description">Timeout in seconds or
<code>CUPS_TIMEOUT_DEFAULT
</code></dd>
614 <dt>include_schemes
</dt>
615 <dd class=
"description">Comma-separated URI schemes to include or
<code>CUPS_INCLUDE_ALL
</code></dd>
616 <dt>exclude_schemes
</dt>
617 <dd class=
"description">Comma-separated URI schemes to exclude or
<code>CUPS_EXCLUDE_NONE
</code></dd>
619 <dd class=
"description">Callback function
</dd>
621 <dd class=
"description">User data pointer
</dd>
623 <h4 class=
"returnvalue">Return Value
</h4>
624 <p class=
"description">Request status -
<code>IPP_OK
</code> on success.
</p>
625 <h4 class=
"discussion">Discussion
</h4>
626 <p class=
"discussion">This function sends a CUPS-Get-Devices request and streams the discovered
627 devices to the specified callback function. The
"timeout
" parameter controls
628 how long the request lasts, while the
"include_schemes
" and
"exclude_schemes
"
629 parameters provide comma-delimited lists of backends to include or omit from
630 the request respectively.
633 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
634 <h3 class=
"typedef"><span class=
"info"> CUPS
1.4/OS X
10.6 </span><a name=
"cups_device_cb_t">cups_device_cb_t
</a></h3>
635 <p class=
"description">Device callback
638 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);