]> git.ipfire.org Git - thirdparty/cups.git/blob - doc/help/api-admin.html
Update copyrights and license text on files that were missed.
[thirdparty/cups.git] / 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 BLOCKQUOTE {
31 border-left: solid 2px #777;
32 margin: 1em 0;
33 padding: 10px;
34 }
35
36 BLOCKQUOTE OL LI {
37 margin-left: -1em;
38 }
39
40 PRE.command, PRE.example {
41 background: #eee;
42 margin: 0 36pt;
43 padding: 10px;
44 }
45
46 P.compact {
47 margin: 0;
48 }
49
50 P.example {
51 font-style: italic;
52 margin-left: 36pt;
53 }
54
55 DL.man DD {
56 margin-left: 5em;
57 }
58
59 DL.man DT {
60 margin-left: 0;
61 }
62
63 PRE.man {
64 margin: 0;
65 }
66
67 PRE.command EM, PRE.example EM {
68 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
69 }
70
71 P.command {
72 font-family: monaco, courier, monospace;
73 margin-left: 36pt;
74 }
75
76 P.formula {
77 font-style: italic;
78 margin-left: 36pt;
79 }
80
81 A IMG {
82 border: none;
83 }
84
85 A:link:hover IMG {
86 background: #f0f0f0;
87 border-radius: 10px;
88 -moz-border-radius: 10px;
89 }
90
91 A:link, A:visited {
92 font-weight: inherit;
93 text-decoration: none;
94 }
95
96 A:link:hover, A:visited:hover, A:active {
97 text-decoration: underline;
98 }
99
100 SUB, SUP {
101 font-size: 50%;
102 }
103
104 TR.data, TD.data, TR.data TD {
105 margin-top: 10pt;
106 padding: 5pt;
107 border-bottom: solid 1pt #999999;
108 }
109
110 TR.data TH {
111 border-bottom: solid 1pt #999999;
112 padding-top: 10pt;
113 padding-left: 5pt;
114 text-align: left;
115 }
116
117 DIV.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
125 DIV.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
134 DIV.table TABLE TD {
135 border: solid thin #cccccc;
136 padding: 5pt 10pt 0;
137 }
138
139 DIV.table TABLE TH {
140 background: #cccccc;
141 border: none;
142 border-bottom: solid thin #999999;
143 }
144
145 DIV.figure TABLE {
146 margin-left: auto;
147 margin-right: auto;
148 }
149
150 DIV.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
159 TH.label {
160 text-align: right;
161 vertical-align: top;
162 }
163
164 TH.sublabel {
165 text-align: right;
166 font-weight: normal;
167 }
168
169 HR {
170 border: solid thin;
171 }
172
173 SPAN.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
183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
184 float: right;
185 font-size: 100%;
186 }
187
188 H1.title {
189 }
190
191 H2.title, H3.title {
192 border-bottom: solid 2pt #000000;
193 }
194
195 DIV.indent, TABLE.indent {
196 margin-top: 2em;
197 margin-left: auto;
198 margin-right: auto;
199 width: 90%;
200 }
201
202 TABLE.indent {
203 border-collapse: collapse;
204 }
205
206 TABLE.indent TD, TABLE.indent TH {
207 padding: 0;
208 }
209
210 TABLE.list {
211 border-collapse: collapse;
212 margin-left: auto;
213 margin-right: auto;
214 width: 90%;
215 }
216
217 TABLE.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
228 TABLE.list TH A {
229 color: #4444cc;
230 }
231
232 TABLE.list TD {
233 border-bottom: solid thin #eeeeee;
234 padding-top: 5pt;
235 padding-left: 5pt;
236 }
237
238 TABLE.list TR:nth-child(even) {
239 background: #f8f8f8;
240 }
241
242 TABLE.list TR:nth-child(odd) {
243 background: #f4f4f4;
244 }
245
246 DT {
247 margin-left: 36pt;
248 margin-top: 12pt;
249 }
250
251 DD {
252 margin-left: 54pt;
253 }
254
255 DL.category DT {
256 font-weight: bold;
257 }
258
259 P.summary {
260 margin-left: 36pt;
261 font-family: monaco, courier, monospace;
262 }
263
264 DIV.summary TABLE {
265 border: solid thin #999999;
266 border-collapse: collapse;
267 border-spacing: 0;
268 margin: 10px;
269 }
270
271 DIV.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
278 DIV.summary TABLE THEAD TH {
279 background: #eeeeee;
280 }
281
282 /* API documentation styles... */
283 div.body h1 {
284 font-size: 250%;
285 font-weight: bold;
286 margin: 0;
287 }
288 div.body h2 {
289 font-size: 250%;
290 margin-top: 1.5em;
291 }
292 div.body h3 {
293 font-size: 150%;
294 margin-bottom: 0.5em;
295 margin-top: 1.5em;
296 }
297 div.body h4 {
298 font-size: 110%;
299 margin-bottom: 0.5em;
300 margin-top: 1.5em;
301 }
302 div.body h5 {
303 font-size: 100%;
304 margin-bottom: 0.5em;
305 margin-top: 1.5em;
306 }
307 div.contents {
308 background: #e8e8e8;
309 border: solid thin black;
310 padding: 10px;
311 }
312 div.contents h1 {
313 font-size: 110%;
314 }
315 div.contents h2 {
316 font-size: 100%;
317 }
318 div.contents ul.contents {
319 font-size: 80%;
320 }
321 .class {
322 border-bottom: solid 2px gray;
323 }
324 .constants {
325 }
326 .description {
327 margin-top: 0.5em;
328 }
329 .discussion {
330 }
331 .enumeration {
332 border-bottom: solid 2px gray;
333 }
334 .function {
335 border-bottom: solid 2px gray;
336 margin-bottom: 0;
337 }
338 .members {
339 }
340 .method {
341 }
342 .parameters {
343 }
344 .returnvalue {
345 }
346 .struct {
347 border-bottom: solid 2px gray;
348 }
349 .typedef {
350 border-bottom: solid 2px gray;
351 }
352 .union {
353 border-bottom: solid 2px gray;
354 }
355 .variable {
356 }
357 h1, h2, h3, h4, h5, h6 {
358 page-break-inside: avoid;
359 }
360 blockquote {
361 border: solid thin gray;
362 box-shadow: 3px 3px 5px rgba(0,0,0,0.5);
363 padding: 0px 10px;
364 page-break-inside: avoid;
365 }
366 p code, li code, p.code, pre, ul.code li {
367 background: rgba(127,127,127,0.1);
368 border: thin dotted gray;
369 font-family: monospace;
370 font-size: 90%;
371 hyphens: manual;
372 -webkit-hyphens: manual;
373 page-break-inside: avoid;
374 }
375 p.code, pre, ul.code li {
376 padding: 10px;
377 }
378 p code, li code {
379 padding: 2px 5px;
380 }
381 a:link, a:visited {
382 text-decoration: none;
383 }
384 span.info {
385 background: black;
386 border: solid thin black;
387 color: white;
388 font-size: 80%;
389 font-style: italic;
390 font-weight: bold;
391 white-space: nowrap;
392 }
393 h3 span.info, h4 span.info {
394 border-top-left-radius: 10px;
395 border-top-right-radius: 10px;
396 float: right;
397 padding: 3px 6px;
398 }
399 ul.code, ul.contents, ul.subcontents {
400 list-style-type: none;
401 margin: 0;
402 padding-left: 0;
403 }
404 ul.code li {
405 margin: 0;
406 }
407 ul.contents > li {
408 margin-top: 1em;
409 }
410 ul.contents li ul.code, ul.contents li ul.subcontents {
411 padding-left: 2em;
412 }
413 table.list {
414 border-collapse: collapse;
415 width: 100%;
416 }
417 table.list tr:nth-child(even) {
418 background: rgba(127,127,127,0.1);]n}
419 table.list th {
420 border-right: 2px solid gray;
421 font-family: monospace;
422 padding: 5px 10px 5px 2px;
423 text-align: right;
424 vertical-align: top;
425 }
426 table.list td {
427 padding: 5px 2px 5px 10px;
428 text-align: left;
429 vertical-align: top;
430 }
431 h1.title {
432 }
433 h2.title {
434 border-bottom: solid 2px black;
435 }
436 h3.title {
437 border-bottom: solid 2px black;
438 }
439 --></style>
440 </head>
441 <body>
442 <!--
443 Administrative API header for CUPS.
444
445 Copyright © 2016 by Apple Inc.
446
447 Licensed under Apache License v2.0. See the file "LICENSE" for more
448 information.
449 -->
450
451 <h1 class='title'>Administrative APIs</h1>
452
453 <div class='summary'><table summary='General Information'>
454 <thead>
455 <tr>
456 <th>Header</th>
457 <th>cups/adminutil.h</th>
458 </tr>
459 </thead>
460 <tbody>
461 <tr>
462 <th>Library</th>
463 <td>-lcups</td>
464 </tr>
465 <tr>
466 <th>See Also</th>
467 <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
468 Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
469 Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a></td>
470 </tr>
471 </tbody>
472 </table></div>
473 <div class="contents">
474 <h2 class="title">Contents</h2>
475 <ul class="contents">
476 <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
477 <li><a href="#SETTINGS">Scheduler Settings</a></li>
478 <li><a href="#DEVICES">Devices</a></li>
479 </ul></li>
480 <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
481 <li><a href="#cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></li>
482 <li><a href="#cupsAdminExportSamba">cupsAdminExportSamba</a></li>
483 <li><a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></li>
484 <li><a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></li>
485 <li><a href="#cupsGetDevices">cupsGetDevices</a></li>
486 </ul></li>
487 <li><a href="#TYPES">Data Types</a><ul class="subcontents">
488 <li><a href="#cups_device_cb_t">cups_device_cb_t</a></li>
489 </ul></li>
490 </ul>
491 </div>
492 <div class="body">
493 <!--
494 Administrative API documentation for CUPS.
495
496 Copyright © 2016 by Apple Inc.
497
498 Licensed under Apache License v2.0. See the file "LICENSE" for more
499 information.
500 -->
501
502 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
503
504 <p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.</p>
505
506 <blockquote><b>Note:<b>
507 <p>Administrative functions normally require administrative privileges to execute and must not be used in ordinary user applications!</p>
508 </blockquote>
509
510 <h3><a name="SETTINGS">Scheduler Settings</a></h3>
511
512 <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>
513
514 <ul>
515 <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>
516 <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>
517 <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>
518 <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>
519 <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>
520 </ul>
521
522 <blockquote><b>Note:</b>
523 <p>Changing settings will restart the CUPS scheduler.</p>
524 <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>
525 </blockquote>
526
527 <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>
528
529 <pre class="example">
530 #include &lt;cups/cups.h&gt;
531 #include &lt;cups/adminutil.h&gt;
532
533 void
534 enable_web_interface(void)
535 {
536 int num_settings = 0; /* Number of settings */
537 cups_option_t *settings = NULL; /* Settings */
538
539
540 if (!<a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a>(CUPS_HTTP_DEFAULT, &amp;num_settings, &amp;settings))
541 {
542 fprintf(stderr, "ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
543 return;
544 }
545
546 num_settings = <a href="api-cups.html#cupsAddOption">cupsAddOption</a>("WebInterface", "Yes", num_settings, &amp;settings);
547
548 if (!<a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
549 {
550 fprintf(stderr, "ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
551 }
552
553 <a href="api-cups.html#cupsFreeOptions">cupsFreeOptions</a>(num_settings, settings);
554 }
555 </pre>
556
557 <h3><a name="DEVICES">Devices</a></h3>
558
559 <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>
560
561 <pre class="example">
562 #include &lt;cups/cups.h&gt;
563 #include &lt;cups/adminutil.h&gt;
564
565
566 void
567 get_devices_cb(
568 const char *device_class, /* I - Class */
569 const char *device_id, /* I - 1284 device ID */
570 const char *device_info, /* I - Description */
571 const char *device_make_and_model, /* I - Make and model */
572 const char *device_uri, /* I - Device URI */
573 const char *device_location, /* I - Location */
574 void *user_data) /* I - User data */
575 {
576 puts(device_uri);
577 }
578
579
580 void
581 show_devices(void)
582 {
583 <a href="#cupsGetDevices">cupsGetDevices</a>(CUPS_HTTP_DEFAULT, 30, NULL, NULL, get_devices_cb, NULL);
584 }
585 </pre>
586 <h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
587 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
588 <p class="description">Create the Windows PPD file for a printer.</p>
589 <p class="code">
590 char *cupsAdminCreateWindowsPPD(http_t *http, const char *dest, char *buffer, int bufsize);</p>
591 <h4 class="parameters">Parameters</h4>
592 <table class="list"><tbody>
593 <tr><th>http</th>
594 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
595 <tr><th>dest</th>
596 <td class="description">Printer or class</td></tr>
597 <tr><th>buffer</th>
598 <td class="description">Filename buffer</td></tr>
599 <tr><th>bufsize</th>
600 <td class="description">Size of filename buffer</td></tr>
601 </tbody></table>
602 <h4 class="returnvalue">Return Value</h4>
603 <p class="description">PPD file or NULL</p>
604 <h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
605 <p class="description">Export a printer to Samba.</p>
606 <p class="code">
607 int cupsAdminExportSamba(const char *dest, const char *ppd, const char *samba_server, const char *samba_user, const char *samba_password, FILE *logfile);</p>
608 <h4 class="parameters">Parameters</h4>
609 <table class="list"><tbody>
610 <tr><th>dest</th>
611 <td class="description">Destination to export</td></tr>
612 <tr><th>ppd</th>
613 <td class="description">PPD file</td></tr>
614 <tr><th>samba_server</th>
615 <td class="description">Samba server</td></tr>
616 <tr><th>samba_user</th>
617 <td class="description">Samba username</td></tr>
618 <tr><th>samba_password</th>
619 <td class="description">Samba password</td></tr>
620 <tr><th>logfile</th>
621 <td class="description">Log file, if any</td></tr>
622 </tbody></table>
623 <h4 class="returnvalue">Return Value</h4>
624 <p class="description">1 on success, 0 on failure</p>
625 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
626 <p class="description">Get settings from the server.</p>
627 <p class="code">
628 int cupsAdminGetServerSettings(http_t *http, int *num_settings, cups_option_t **settings);</p>
629 <h4 class="parameters">Parameters</h4>
630 <table class="list"><tbody>
631 <tr><th>http</th>
632 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
633 <tr><th>num_settings</th>
634 <td class="description">Number of settings</td></tr>
635 <tr><th>settings</th>
636 <td class="description">Settings</td></tr>
637 </tbody></table>
638 <h4 class="returnvalue">Return Value</h4>
639 <p class="description">1 on success, 0 on failure</p>
640 <h4 class="discussion">Discussion</h4>
641 <p class="discussion">The returned settings should be freed with cupsFreeOptions() when
642 you are done with them.
643
644 </p>
645 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
646 <p class="description">Set settings on the server.</p>
647 <p class="code">
648 int cupsAdminSetServerSettings(http_t *http, int num_settings, cups_option_t *settings);</p>
649 <h4 class="parameters">Parameters</h4>
650 <table class="list"><tbody>
651 <tr><th>http</th>
652 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
653 <tr><th>num_settings</th>
654 <td class="description">Number of settings</td></tr>
655 <tr><th>settings</th>
656 <td class="description">Settings</td></tr>
657 </tbody></table>
658 <h4 class="returnvalue">Return Value</h4>
659 <p class="description">1 on success, 0 on failure</p>
660 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetDevices">cupsGetDevices</a></h3>
661 <p class="description">Get available printer devices.</p>
662 <p class="code">
663 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>
664 <h4 class="parameters">Parameters</h4>
665 <table class="list"><tbody>
666 <tr><th>http</th>
667 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
668 <tr><th>timeout</th>
669 <td class="description">Timeout in seconds or <code>CUPS_TIMEOUT_DEFAULT</code></td></tr>
670 <tr><th>include_schemes</th>
671 <td class="description">Comma-separated URI schemes to include or <code>CUPS_INCLUDE_ALL</code></td></tr>
672 <tr><th>exclude_schemes</th>
673 <td class="description">Comma-separated URI schemes to exclude or <code>CUPS_EXCLUDE_NONE</code></td></tr>
674 <tr><th>callback</th>
675 <td class="description">Callback function</td></tr>
676 <tr><th>user_data</th>
677 <td class="description">User data pointer</td></tr>
678 </tbody></table>
679 <h4 class="returnvalue">Return Value</h4>
680 <p class="description">Request status - <code>IPP_OK</code> on success.</p>
681 <h4 class="discussion">Discussion</h4>
682 <p class="discussion">This function sends a CUPS-Get-Devices request and streams the discovered
683 devices to the specified callback function. The &quot;timeout&quot; parameter controls
684 how long the request lasts, while the &quot;include_schemes&quot; and &quot;exclude_schemes&quot;
685 parameters provide comma-delimited lists of backends to include or omit from
686 the request respectively.
687
688 </p>
689 <h2 class="title"><a id="TYPES">Data Types</a></h2>
690 <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>
691 <p class="description">Device callback
692 </p>
693 <p class="code">
694 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);
695 </p>
696 </div>
697 </body>
698 </html>