[thirdparty/cups.git] / doc / help / api-admin.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
	<title>Administration APIs	</title>
	<meta name="keywords" content="Programming">
	<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
	<meta name="creator" content="Mini-XML v2.7">
<style type="text/css"><!--
BODY {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

H1, H2, H3, H4, H5, H6, P, TD, TH {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

KBD {
  font-family: monaco, courier, monospace;
  font-weight: bold;
}

PRE {
  font-family: monaco, courier, monospace;
}

PRE.command {
  border: dotted thin #7f7f7f;
  margin-left: 36pt;
  padding: 10px;
}

P.compact {
  margin: 0;
}

P.example {
  font-style: italic;
  margin-left: 36pt;
}

DL.man DD {
  margin-left: 5em;
}

DL.man DT {
  margin-left: 0;
}

PRE.man {
  margin: 0;
}

PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 10pt;
}

PRE.command EM, PRE.example EM {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

P.command {
  font-family: monaco, courier, monospace;
  margin-left: 36pt;
}

P.formula {
  font-style: italic;
  margin-left: 36pt;
}

BLOCKQUOTE {
  background: #eeeeee;
  border: solid thin #999999;
  padding: 10pt;
}

A IMG {
  border: none;
}

A:link:hover IMG {
  background: #f0f0f0;
  border-radius: 10px;
  -moz-border-radius: 10px;
}

A:link, A:visited {
  font-weight: inherit;
  text-decoration: none;
}

A:link:hover, A:visited:hover, A:active {
  text-decoration: underline;
}

SUB, SUP {
  font-size: 50%;
}

TR.data, TD.data, TR.data TD {
  margin-top: 10pt;
  padding: 5pt;
  border-bottom: solid 1pt #999999;
}

TR.data TH {
  border-bottom: solid 1pt #999999;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
}

DIV.table TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin-left: auto;
  margin-right: auto;
}

DIV.table CAPTION {
  caption-side: top;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

DIV.table TABLE TD {
  border: solid thin #cccccc;
  padding-top: 5pt;
}

DIV.table TABLE TH {
  background: #cccccc;
  border: none;
  border-bottom: solid thin #999999;
}

DIV.figure TABLE {
  margin-left: auto;
  margin-right: auto;
}

DIV.figure CAPTION {
  caption-side: bottom;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

TH.label {
  text-align: right;
  vertical-align: top;
}

TH.sublabel {
  text-align: right;
  font-weight: normal;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: black;
  border: thin solid black;
  color: white;
  font-size: 80%;
  font-style: italic;
  font-weight: bold;
  white-space: nowrap;
}

H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
  float: right;
  font-size: 100%;
}

H1.title {
}

H2.title, H3.title {
  border-bottom: solid 2pt #000000;
}

DIV.indent, TABLE.indent {
  margin-top: 2em;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.indent {
  border-collapse: collapse;
}

TABLE.indent TD, TABLE.indent TH {
  padding: 0;
}

TABLE.list {
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.list TH {
  background: white;
  border-bottom: solid thin #cccccc;
  color: #444444;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
  vertical-align: bottom;
  white-space: nowrap;
}

TABLE.list TH A {
  color: #4444cc;
}

TABLE.list TD {
  border-bottom: solid thin #eeeeee;
  padding-top: 5pt;
  padding-left: 5pt;
}

TABLE.list TR:nth-child(even) {
  background: #f8f8f8;
}

TABLE.list TR:nth-child(odd) {
  background: #f4f4f4;
}

DT {
  margin-left: 36pt;
  margin-top: 12pt;
}

DD {
  margin-left: 54pt;
}

DL.category DT {
  font-weight: bold;
}

P.summary {
  margin-left: 36pt;
  font-family: monaco, courier, monospace;
}

DIV.summary TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin: 10px;
}

DIV.summary TABLE TD, DIV.summary TABLE TH {
  border: solid thin #999999;
  padding: 5px;
  text-align: left;
  vertical-align: top;
}

DIV.summary TABLE THEAD TH {
  background: #eeeeee;
}

/* API documentation styles... */
div.body h1 {
  margin: 0;
}
div.body h2 {
  margin-top: 1.5em;
}
div.body h3, div.body h4, div.body h5 {
  margin-bottom: 0.5em;
  margin-top: 1.5em;
}
.class, .enumeration, .function, .struct, .typedef, .union {
  border-bottom: solid thin #999999;
  margin-bottom: 0;
  margin-top: 2em;
}
.description {
  margin-top: 0.5em;
}
code, p.code, pre, ul.code li {
  font-family: monaco, courier, monospace;
  font-size: 90%;
}
ul.code, ul.contents, ul.subcontents {
  list-style-type: none;
  margin: 0;
  padding-left: 0;
}
ul.code li {
  margin: 0;
}
ul.contents > li {
  margin-top: 1em;
}
ul.contents li ul.code, ul.contents li ul.subcontents {
  padding-left: 2em;
}
div.body dl {
  margin-left: 0;
  margin-top: 0;
}
div.body dt {
  font-style: italic;
  margin-left: 0;
  margin-top: 0;
}
div.body dd {
  margin-bottom: 0.5em;
}

/* This is just for the HTML files generated with the framedhelp target */
div.contents {
  background: #e8e8e8;
  border: solid thin black;
  padding: 10px;
}
div.contents h1 {
  font-size: 110%;
}
div.contents h2 {
  font-size: 100%;
}
div.contents ul.contents {
  font-size: 80%;
}
div.contents ul.subcontents li {
  margin-left: 1em;
  text-indent: -1em;
}
--></style>
</head>
<body>
<div class='body'>
<!--
  Administrative API header for CUPS.

  Copyright 2016 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h1 class='title'>Administrative APIs</h1>

<div class='summary'><table summary='General Information'>
<thead>
<tr>
	<th>Header</th>
	<th>cups/adminutil.h</th>
</tr>
</thead>
<tbody>
<tr>
	<th>Library</th>
	<td>-lcups</td>
</tr>
<tr>
	<th>See Also</th>
	<td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a></td>
</tr>
</tbody>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
<li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
	<li><a href="#SETTINGS">Scheduler Settings</a></li>
	<li><a href="#DEVICES">Devices</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
	<li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li>
	<li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li>
	<li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li>
	<li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li>
	<li><a href="#cupsGetDevices" title="Get available printer devices.">cupsGetDevices</a></li>
</ul></li>
<li><a href="#TYPES">Data Types</a><ul class="code">
	<li><a href="#cups_device_cb_t" title="Device callback
">cups_device_cb_t</a></li>
</ul></li>
</ul>
<!--
  Administrative API documentation for CUPS.

  Copyright 2016 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h2 class="title"><a name="OVERVIEW">Overview</a></h2>

<p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.</p>

<blockquote><b>Note:<b>
  <p>Administrative functions normally require administrative privileges to execute and must not be used in ordinary user applications!</p>
</blockquote>

<h3><a name="SETTINGS">Scheduler Settings</a></h3>

<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>

<ul>
  <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>
  <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>
  <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>
  <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>
  <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>
</ul>

<blockquote><b>Note:</b>
  <p>Changing settings will restart the CUPS scheduler.</p>
  <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>
</blockquote>

<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>

<pre class="example">
#include &lt;cups/cups.h&gt;
#include &lt;cups/adminutil.h&gt;

void
enable_web_interface(void)
{
  int num_settings = 0;           /* Number of settings */
  cups_option_t *settings = NULL; /* Settings */


  if (!<a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a>(CUPS_HTTP_DEFAULT, &amp;num_settings, &amp;settings))
  {
    fprintf(stderr, "ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
    return;
  }

  num_settings = <a href="api-cups.html#cupsAddOption">cupsAddOption</a>("WebInterface", "Yes", num_settings, &amp;settings);

  if (!<a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
  {
    fprintf(stderr, "ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
  }

  <a href="api-cups.html#cupsFreeOptions">cupsFreeOptions</a>(num_settings, settings);
}
</pre>

<h3><a name="DEVICES">Devices</a></h3>

<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>

<pre class="example">
#include &lt;cups/cups.h&gt;
#include &lt;cups/adminutil.h&gt;


void
get_devices_cb(
    const char *device_class,           /* I - Class */
    const char *device_id,              /* I - 1284 device ID */
    const char *device_info,            /* I - Description */
    const char *device_make_and_model,  /* I - Make and model */
    const char *device_uri,             /* I - Device URI */
    const char *device_location,        /* I - Location */
    void       *user_data)              /* I - User data */
{
  puts(device_uri);
}


void
show_devices(void)
{
  <a href="#cupsGetDevices">cupsGetDevices</a>(CUPS_HTTP_DEFAULT, 30, NULL, NULL, get_devices_cb, NULL);
}
</pre>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
<h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3>
<p class="description">Create the Windows PPD file for a printer.</p>
<p class="code">
char *cupsAdminCreateWindowsPPD (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *dest,<br>
&nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int bufsize<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>http</dt>
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
<dt>dest</dt>
<dd class="description">Printer or class</dd>
<dt>buffer</dt>
<dd class="description">Filename buffer</dd>
<dt>bufsize</dt>
<dd class="description">Size of filename buffer</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">PPD file or NULL</p>
<h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3>
<p class="description">Export a printer to Samba.</p>
<p class="code">
int cupsAdminExportSamba (<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *dest,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *ppd,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_server,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_user,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *samba_password,<br>
&nbsp;&nbsp;&nbsp;&nbsp;FILE *logfile<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>dest</dt>
<dd class="description">Destination to export</dd>
<dt>ppd</dt>
<dd class="description">PPD file</dd>
<dt>samba_server</dt>
<dd class="description">Samba server</dd>
<dt>samba_user</dt>
<dd class="description">Samba username</dd>
<dt>samba_password</dt>
<dd class="description">Samba password</dd>
<dt>logfile</dt>
<dd class="description">Log file, if any</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.3/macOS 10.5&nbsp;</span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
<p class="description">Get settings from the server.</p>
<p class="code">
int cupsAdminGetServerSettings (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int *num_settings,<br>
&nbsp;&nbsp;&nbsp;&nbsp;cups_option_t **settings<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>http</dt>
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
<dt>num_settings</dt>
<dd class="description">Number of settings</dd>
<dt>settings</dt>
<dd class="description">Settings</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The returned settings should be freed with cupsFreeOptions() when
you are done with them.

</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.3/macOS 10.5&nbsp;</span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
<p class="description">Set settings on the server.</p>
<p class="code">
int cupsAdminSetServerSettings (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int num_settings,<br>
&nbsp;&nbsp;&nbsp;&nbsp;cups_option_t *settings<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>http</dt>
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
<dt>num_settings</dt>
<dd class="description">Number of settings</dd>
<dt>settings</dt>
<dd class="description">Settings</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
<h3 class="function"><span class="info">&nbsp;CUPS 1.4/macOS 10.6&nbsp;</span><a name="cupsGetDevices">cupsGetDevices</a></h3>
<p class="description">Get available printer devices.</p>
<p class="code">
ipp_status_t cupsGetDevices (<br>
&nbsp;&nbsp;&nbsp;&nbsp;http_t *http,<br>
&nbsp;&nbsp;&nbsp;&nbsp;int timeout,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *include_schemes,<br>
&nbsp;&nbsp;&nbsp;&nbsp;const char *exclude_schemes,<br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#cups_device_cb_t">cups_device_cb_t</a> callback,<br>
&nbsp;&nbsp;&nbsp;&nbsp;void *user_data<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>http</dt>
<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
<dt>timeout</dt>
<dd class="description">Timeout in seconds or <code>CUPS_TIMEOUT_DEFAULT</code></dd>
<dt>include_schemes</dt>
<dd class="description">Comma-separated URI schemes to include or <code>CUPS_INCLUDE_ALL</code></dd>
<dt>exclude_schemes</dt>
<dd class="description">Comma-separated URI schemes to exclude or <code>CUPS_EXCLUDE_NONE</code></dd>
<dt>callback</dt>
<dd class="description">Callback function</dd>
<dt>user_data</dt>
<dd class="description">User data pointer</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Request status - <code>IPP_OK</code> on success.</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function sends a CUPS-Get-Devices request and streams the discovered
devices to the specified callback function. The &quot;timeout&quot; parameter controls
how long the request lasts, while the &quot;include_schemes&quot; and &quot;exclude_schemes&quot;
parameters provide comma-delimited lists of backends to include or omit from
the request respectively.

</p>
<h2 class="title"><a name="TYPES">Data Types</a></h2>
<h3 class="typedef"><span class="info">&nbsp;CUPS 1.4/macOS 10.6&nbsp;</span><a name="cups_device_cb_t">cups_device_cb_t</a></h3>
<p class="description">Device callback
</p>
<p class="code">
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);
</p>
</div>
</body>
</html>
Commit	Line	Data
dffa3c74 MS	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	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">
8072030b	8	<meta name="creator" content="Mini-XML v2.7">
dffa3c74 MS	9	<style type="text/css"><!--
	10	BODY {
	11	font-family: lucida grande, geneva, helvetica, arial, sans-serif;
	12	}
	13
	14	H1, H2, H3, H4, H5, H6, P, TD, TH {
	15	font-family: lucida grande, geneva, helvetica, arial, sans-serif;
	16	}
	17
	18	KBD {
	19	font-family: monaco, courier, monospace;
	20	font-weight: bold;
	21	}
	22
	23	PRE {
	24	font-family: monaco, courier, monospace;
	25	}
	26
	27	PRE.command {
	28	border: dotted thin #7f7f7f;
	29	margin-left: 36pt;
	30	padding: 10px;
	31	}
	32
	33	P.compact {
	34	margin: 0;
	35	}
	36
	37	P.example {
	38	font-style: italic;
	39	margin-left: 36pt;
	40	}
	41
	42	DL.man DD {
	43	margin-left: 5em;
	44	}
	45
	46	DL.man DT {
	47	margin-left: 0;
	48	}
	49
	50	PRE.man {
	51	margin: 0;
	52	}
	53
	54	PRE.example {
	55	background: #eeeeee;
	56	border: dotted thin #999999;
	57	margin-left: 36pt;
	58	padding: 10pt;
	59	}
	60
	61	PRE.command EM, PRE.example EM {
	62	font-family: lucida grande, geneva, helvetica, arial, sans-serif;
	63	}
	64
	65	P.command {
	66	font-family: monaco, courier, monospace;
	67	margin-left: 36pt;
	68	}
	69
	70	P.formula {
	71	font-style: italic;
	72	margin-left: 36pt;
73	}
74
75	BLOCKQUOTE {
76	background: #eeeeee;
77	border: solid thin #999999;
78	padding: 10pt;
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-top: 5pt;
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	margin: 0;
285	}
286	div.body h2 {
287	margin-top: 1.5em;
288	}
289	div.body h3, div.body h4, div.body h5 {
290	margin-bottom: 0.5em;
291	margin-top: 1.5em;
292	}
293	.class, .enumeration, .function, .struct, .typedef, .union {
294	border-bottom: solid thin #999999;
295	margin-bottom: 0;
296	margin-top: 2em;
297	}
298	.description {
299	margin-top: 0.5em;
300	}
301	code, p.code, pre, ul.code li {
302	font-family: monaco, courier, monospace;
303	font-size: 90%;
304	}
305	ul.code, ul.contents, ul.subcontents {
306	list-style-type: none;
307	margin: 0;
308	padding-left: 0;
309	}
310	ul.code li {
311	margin: 0;
312	}
313	ul.contents > li {
314	margin-top: 1em;
315	}
316	ul.contents li ul.code, ul.contents li ul.subcontents {
317	padding-left: 2em;
318	}
319	div.body dl {
320	margin-left: 0;
321	margin-top: 0;
322	}
323	div.body dt {
324	font-style: italic;
325	margin-left: 0;
326	margin-top: 0;
327	}
328	div.body dd {
329	margin-bottom: 0.5em;
330	}
331
332	/* This is just for the HTML files generated with the framedhelp target */
333	div.contents {
334	background: #e8e8e8;
335	border: solid thin black;
336	padding: 10px;
337	}
338	div.contents h1 {
339	font-size: 110%;
340	}
341	div.contents h2 {
342	font-size: 100%;
343	}
344	div.contents ul.contents {
345	font-size: 80%;
346	}
347	div.contents ul.subcontents li {
348	margin-left: 1em;
349	text-indent: -1em;
350	}
351	--></style>
352	</head>
353	<body>
354	<div class='body'>
355	<!--
356	Administrative API header for CUPS.
357
358	Copyright 2016 by Apple Inc.
359
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/".
365	-->
366
367	<h1 class='title'>Administrative APIs</h1>
368
369	<div class='summary'><table summary='General Information'>
370	<thead>
371	<tr>
372	<th>Header</th>
373	<th>cups/adminutil.h</th>
374	</tr>
375	</thead>
376	<tbody>
377	<tr>
378	<th>Library</th>
379	<td>-lcups</td>
380	</tr>
381	<tr>
382	<th>See Also</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>
386	</tr>
387	</tbody>
388	</table></div>
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>
394	</ul></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>
401	</ul></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>
405	</ul></li>
406	</ul>
407	<!--
408	Administrative API documentation for CUPS.
409
410	Copyright 2016 by Apple Inc.
411
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/".
417	-->
418
419	<h2 class="title"><a name="OVERVIEW">Overview</a></h2>
420
421	<p>The administrative APIs provide convenience functions to perform certain administrative functions with the CUPS scheduler.</p>
422
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>
425	</blockquote>
426
427	<h3><a name="SETTINGS">Scheduler Settings</a></h3>
428
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>
430
431	<ul>
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>
437	</ul>
438
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>
442	</blockquote>
443
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>
445
446	<pre class="example">
447	#include <cups/cups.h>
448	#include <cups/adminutil.h>
449
450	void
451	enable_web_interface(void)
452	{
453	int num_settings = 0; /* Number of settings */
454	cups_option_t settings = NULL; / Settings */
455
456
457	if (!<a href="#cupsAdminGetServerSettings">cupsAdminGetServerSettings</a>(CUPS_HTTP_DEFAULT, &num_settings, &settings))
458	{
459	fprintf(stderr, "ERROR: Unable to get server settings: %s\n", cupsLastErrorString());
460	return;
461	}
462
463	num_settings = <a href="api-cups.html#cupsAddOption">cupsAddOption</a>("WebInterface", "Yes", num_settings, &settings);
464
465	if (!<a href="#cupsAdminSetServerSettings">cupsAdminSetServerSettings</a>(CUPS_HTTP_DEFAULT, num_settings, settings))
466	{
467	fprintf(stderr, "ERROR: Unable to set server settings: %s\n", cupsLastErrorString());
468	}
469
470	<a href="api-cups.html#cupsFreeOptions">cupsFreeOptions</a>(num_settings, settings);
471	}
472	</pre>
473
474	<h3><a name="DEVICES">Devices</a></h3>
475
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>
477
478	<pre class="example">
479	#include <cups/cups.h>
480	#include <cups/adminutil.h>
481
482
483	void
484	get_devices_cb(
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 */
492	{
493	puts(device_uri);
494	}
495
496
497	void
498	show_devices(void)
499	{
500	<a href="#cupsGetDevices">cupsGetDevices</a>(CUPS_HTTP_DEFAULT, 30, NULL, NULL, get_devices_cb, NULL);
501	}
502	</pre>
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>
506	<p class="code">
507	char *cupsAdminCreateWindowsPPD (<br>
508	http_t *http,<br>
509	const char *dest,<br>
510	char *buffer,<br>
511	int bufsize<br>
512	);</p>
513	<h4 class="parameters">Parameters</h4>
514	<dl>
515	<dt>http</dt>
516	<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
517	<dt>dest</dt>
518	<dd class="description">Printer or class</dd>
519	<dt>buffer</dt>
520	<dd class="description">Filename buffer</dd>
521	<dt>bufsize</dt>
522	<dd class="description">Size of filename buffer</dd>
523	</dl>
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>
528	<p class="code">
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>
536	);</p>
537	<h4 class="parameters">Parameters</h4>
538	<dl>
539	<dt>dest</dt>
540	<dd class="description">Destination to export</dd>
541	<dt>ppd</dt>
542	<dd class="description">PPD file</dd>
543	<dt>samba_server</dt>
544	<dd class="description">Samba server</dd>
545	<dt>samba_user</dt>
546	<dd class="description">Samba username</dd>
547	<dt>samba_password</dt>
548	<dd class="description">Samba password</dd>
549	<dt>logfile</dt>
550	<dd class="description">Log file, if any</dd>
551	</dl>
552	<h4 class="returnvalue">Return Value</h4>
553	<p class="description">1 on success, 0 on failure</p>
8072030b	554	<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3>
dffa3c74 MS	555	<p class="description">Get settings from the server.</p>
	556	<p class="code">
	557	int cupsAdminGetServerSettings (<br>
	558	http_t *http,<br>
	559	int *num_settings,<br>
	560	cups_option_t **settings<br>
	561	);</p>
	562	<h4 class="parameters">Parameters</h4>
	563	<dl>
	564	<dt>http</dt>
	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>
	568	<dt>settings</dt>
	569	<dd class="description">Settings</dd>
	570	</dl>
	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.
	576
	577	</p>
8072030b	578	<h3 class="function"><span class="info"> CUPS 1.3/macOS 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3>
dffa3c74 MS	579	<p class="description">Set settings on the server.</p>
	580	<p class="code">
	581	int cupsAdminSetServerSettings (<br>
	582	http_t *http,<br>
	583	int num_settings,<br>
	584	cups_option_t *settings<br>
	585	);</p>
	586	<h4 class="parameters">Parameters</h4>
	587	<dl>
	588	<dt>http</dt>
	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>
	592	<dt>settings</dt>
	593	<dd class="description">Settings</dd>
	594	</dl>
	595	<h4 class="returnvalue">Return Value</h4>
	596	<p class="description">1 on success, 0 on failure</p>
8072030b	597	<h3 class="function"><span class="info"> CUPS 1.4/macOS 10.6 </span><a name="cupsGetDevices">cupsGetDevices</a></h3>
dffa3c74 MS	598	<p class="description">Get available printer devices.</p>
	599	<p class="code">
	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>
	607	);</p>
	608	<h4 class="parameters">Parameters</h4>
	609	<dl>
	610	<dt>http</dt>
	611	<dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
	612	<dt>timeout</dt>
	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>
	618	<dt>callback</dt>
	619	<dd class="description">Callback function</dd>
	620	<dt>user_data</dt>
	621	<dd class="description">User data pointer</dd>
	622	</dl>
	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.
	631
	632	</p>
	633	<h2 class="title"><a name="TYPES">Data Types</a></h2>
8072030b	634	<h3 class="typedef"><span class="info"> CUPS 1.4/macOS 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3>
dffa3c74 MS	635	<p class="description">Device callback
	636	</p>
	637	<p class="code">
	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);
	639	</p>
	640	</div>
	641	</body>
	642	</html>