<html>
<!-- SECTION: Programming -->
<head>
-<title>CUPS API</title>
-<meta name="keywords" content="Programming">
-<meta name="creator" content="Mini-XML v2.6">
+ <title>CUPS API </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;
}
PRE.command {
+ border: dotted thin #7f7f7f;
margin-left: 36pt;
+ padding: 10px;
}
P.compact {
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
-<ul class="subcontents">
<li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
-<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
-<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
-<li><a href="#OPTIONS">Options</a></li>
-<li><a href="#PRINT_JOBS">Print Jobs</a></li>
-<li><a href="#ERROR_HANDLING">Error Handling</a></li>
-<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
+
<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li>
+
<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li>
+
<li><a href="#OPTIONS">Options</a></li>
+
<li><a href="#PRINT_JOBS">Print Jobs</a></li>
+
<li><a href="#ERROR_HANDLING">Error Handling</a></li>
+
<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
-<li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
-<li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
-<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="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li>
-<li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li>
-<li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li>
-<li><a href="#cupsEncryption" title="Get the default encryption settings.">cupsEncryption</a></li>
-<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
-<li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
-<li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
-<li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
-<li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
-<li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
-<li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
-<li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
-<li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
-<li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
-<li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li>
-<li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li>
-<li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li>
-<li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li>
-<li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li>
-<li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li>
-<li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified
+ <li><a href="#appleGetPaperSize" title="Get the default paper size.">appleGetPaperSize</a></li>
+ <li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li>
+ <li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li>
+ <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="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li>
+ <li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li>
+ <li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li>
+ <li><a href="#cupsEncryption" title="Get the current encryption settings.">cupsEncryption</a></li>
+ <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li>
+ <li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li>
+ <li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li>
+ <li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li>
+ <li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li>
+ <li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li>
+ <li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li>
+ <li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li>
+ <li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li>
+ <li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li>
+ <li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li>
+ <li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li>
+ <li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li>
+ <li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li>
+ <li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li>
+ <li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li>
+ <li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified
server if it has changed.">cupsGetPPD3</a></li>
-<li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li>
-<li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced
-callback.">cupsGetPassword2</a></li>
-<li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li>
-<li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li>
-<li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li>
-<li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.)
+
<li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li>
+
<li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced
+password callback.">cupsGetPassword2</a></li>
+
<li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li>
+
<li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li>
+
<li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li>
+
<li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.)
for the given language.">cupsLangEncoding</a></li>
-<li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li>
-<li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li>
-<li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li>
-<li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li>
-<li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li>
-<li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
-<li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
-<li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
-<li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
-<li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
+ <li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li>
+ <li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li>
+ <li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li>
+ <li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li>
+ <li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li>
+ <li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li>
+ <li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li>
+ <li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified
server.">cupsPrintFile2</a></li>
-<li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the
+
<li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the
default server.">cupsPrintFiles</a></li>
-<li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the
+
<li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the
specified server.">cupsPrintFiles2</a></li>
-<li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li>
-<li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li>
-<li><a href="#cupsServer" title="Return the hostname/address of the default server.">cupsServer</a></li>
-<li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
-<li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
-<li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
-<li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
-<li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
-<li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li>
-<li><a href="#cupsSetServer" title="Set the default server name.">cupsSetServer</a></li>
-<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
-<li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
-<li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
-<li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
-<li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
-<li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
+ <li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li>
+ <li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li>
+ <li><a href="#cupsServer" title="Return the hostname/address of the current server.">cupsServer</a></li>
+ <li><a href="#cupsSetClientCertCB" title="Set the client certificate callback.">cupsSetClientCertCB</a></li>
+ <li><a href="#cupsSetCredentials" title="Set the default credentials to be used for SSL/TLS
+connections.">cupsSetCredentials</a></li>
+ <li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li>
+ <li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li>
+ <li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li>
+ <li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li>
+ <li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li>
+ <li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li>
+ <li><a href="#cupsSetServer" title="Set the default server name and port.">cupsSetServer</a></li>
+ <li><a href="#cupsSetServerCertCB" title="Set the server certificate callback.">cupsSetServerCertCB</a></li>
+ <li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li>
+ <li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li>
+ <li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li>
+ <li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li>
+ <li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li>
+ <li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li>
</ul></li>
<li><a href="#TYPES">Data Types</a><ul class="code">
+ <li><a href="#cups_client_cert_cb_t" title="Client credentials callback ">cups_client_cert_cb_t</a></li>
<li><a href="#cups_dest_t" title="Destination">cups_dest_t</a></li>
<li><a href="#cups_device_cb_t" title="Device callback ">cups_device_cb_t</a></li>
<li><a href="#cups_job_t" title="Job">cups_job_t</a></li>
<li><a href="#cups_password_cb2_t" title="New password callback ">cups_password_cb2_t</a></li>
<li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li>
<li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li>
+ <li><a href="#cups_server_cert_cb_t" title="Server credentials callback ">cups_server_cert_cb_t</a></li>
</ul></li>
<li><a href="#STRUCTURES">Structures</a><ul class="code">
<li><a href="#cups_dest_s" title="Destination">cups_dest_s</a></li>
<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
<li><a href="#cups_ptype_e" title="Printer type/capability bit constants">cups_ptype_e</a></li>
</ul></li>
+</ul>
<!--
"$Id$"
CUPS API introduction for the Common UNIX Printing System (CUPS).
- Copyright 2007-2008 by Apple Inc.
+ Copyright 2007-2010 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
</tr>
<tr>
<td>"printer-is-accepting-jobs"</td>
- <td>"1" if the destination is accepting new jobs, "0" if not.</td>
+ <td>"true" if the destination is accepting new jobs, "false" if
+ not.</td>
</tr>
<tr>
<td>"printer-is-shared"</td>
- <td>"1" if the destination is being shared with other computers, "0" if
- not.</td>
+ <td>"true" if the destination is being shared with other computers,
+ "false" if not.</td>
</tr>
<tr>
<td>"printer-location"</td>
string returned by the <a href="#cupsUser"><code>cupsUser</code></a>
function.</p>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
+<h3 class="function"><a name="appleGetPaperSize">appleGetPaperSize</a></h3>
+<p class="description">Get the default paper size.</p>
+<p class="code">
+char *appleGetPaperSize (<br>
+ char *name,<br>
+ int namesize<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>name</dt>
+<dd class="description">Paper size name buffer</dd>
+<dt>namesize</dt>
+<dd class="description">Size of buffer</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Default paper size</p>
<h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3>
<p class="description">Add a destination to the list of destinations.</p>
<p class="code">
</p>
<h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3>
-<p class="description">Get the default encryption settings.</p>
+<p class="description">Get the current encryption settings.</p>
<p class="code">
http_encryption_t cupsEncryption (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
environment variable, then the ~/.cups/client.conf file, and finally the
/etc/cups/client.conf file. If not set, the default is
-<code>HTTP_ENCRYPT_IF_REQUESTED</code>.</p>
+<code>HTTP_ENCRYPT_IF_REQUESTED</code>.<br>
+<br>
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting via the
+<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same
+setting to be used.</p>
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3>
<p class="description">Finish sending a document.</p>
<p class="code">
in the class.<br>
<br>
The returned filename is stored in a static buffer and is overwritten with
-each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>.</p>
+each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.</p>
<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3>
<p class="description">Get the PPD file for a printer from the specified server.</p>
<p class="code">
in the class.<br>
<br>
The returned filename is stored in a static buffer and is overwritten with
-each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>.
+each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetPPD2</code>. The caller "owns" the
+file that is created and must <code>unlink</code> the returned filename.
</p>
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3>
<br>
The "buffer" parameter contains the local PPD filename. If it contains
the empty string, a new temporary file is created, otherwise the existing
-file will be overwritten as needed.<br>
+file will be overwritten as needed. The caller "owns" the file that is
+created and must <code>unlink</code> the returned filename.<br>
<br>
On success, <code>HTTP_OK</code> is returned for a new PPD file and
<code>HTTP_NOT_MODIFIED</code> if the existing PPD file is up-to-date. Any other
<p class="description">Password</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
-user does not provide a password.</p>
+user does not provide a password.<br>
+<br>
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
+do so in each thread for the same function to be used.</p>
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3>
<p class="description">Get a password from the user using the advanced
-callback.</p>
+password callback.</p>
<p class="code">
const char *cupsGetPassword2 (<br>
const char *prompt,<br>
<p class="description">Password</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
-user does not provide a password.
+user does not provide a password.<br>
+<br>
+Note: The current password callback function is tracked separately for each
+thread in a program. Multi-threaded programs that override the setting via
+the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to
+do so in each thread for the same function to be used.
</p>
<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetPrinters">cupsGetPrinters</a></h3>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Language data</p>
-<h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
-<p class="description">Return the last IPP status code.</p>
-<p class="code">
-ipp_status_t cupsLastError (void);</p>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">IPP status code from last request</p>
-<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
-<p class="description">Return the last IPP status-message.</p>
-<p class="code">
-const char *cupsLastErrorString (void);</p>
-<h4 class="returnvalue">Return Value</h4>
-<p class="description">status-message text from last request</p>
<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3>
<p class="description">Return the subject for the given notification message.</p>
<p class="code">
<h4 class="returnvalue">Return Value</h4>
<p class="description">New number of options</p>
<h3 class="function"><a name="cupsServer">cupsServer</a></h3>
-<p class="description">Return the hostname/address of the default server.</p>
+<p class="description">Return the hostname/address of the current server.</p>
<p class="code">
const char *cupsServer (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Server name</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The returned value can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname.</p>
+<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
+~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
+set, the default is the local system - either "localhost" or a domain socket
+path.<br>
+<br>
+The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
+address, or a domain socket pathname.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server via the
+<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
+server to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.5 </span><a name="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
+<p class="description">Set the client certificate callback.</p>
+<p class="code">
+void cupsSetClientCertCB (<br>
+ <a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data pointer</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
+<br>
+Note: The current certificate callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.5 </span><a name="cupsSetCredentials">cupsSetCredentials</a></h3>
+<p class="description">Set the default credentials to be used for SSL/TLS
+connections.</p>
+<p class="code">
+int cupsSetCredentials (<br>
+ cups_array_t *credentials<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>credentials</dt>
+<dd class="description">Array of credentials</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Status of call (0 = success)</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Note: The default credentials are tracked separately for each thread in a
+program. Multi-threaded programs that override the setting need to do so in
+each thread for the same setting to be used.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
<p class="description">Set the default destination.</p>
<p class="code">
<dt>e</dt>
<dd class="description">New encryption preference</dd>
</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
+environment variable, then the ~/.cups/client.conf file, and finally the
+/etc/cups/client.conf file. If not set, the default is
+<code>HTTP_ENCRYPT_IF_REQUESTED</code>.<br>
+<br>
+Note: The current encryption setting is tracked separately for each thread
+in a program. Multi-threaded programs that override the setting need to do
+so in each thread for the same setting to be used.</p>
<h3 class="function"><a name="cupsSetPasswordCB">cupsSetPasswordCB</a></h3>
<p class="description">Set the password callback for CUPS.</p>
<p class="code">
<dd class="description">Callback function</dd>
</dl>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.</p>
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.</p>
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
<p class="description">Set the advanced password callback for CUPS.</p>
<p class="code">
<dd class="description">User data pointer</dd>
</dl>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback.
+<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
+reads the password from the console. Programs should call either this
+function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
+by a program per thread.<br>
+<br>
+Note: The current password callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
</p>
<h3 class="function"><a name="cupsSetServer">cupsSetServer</a></h3>
-<p class="description">Set the default server name.</p>
+<p class="description">Set the default server name and port.</p>
<p class="code">
void cupsSetServer (<br>
const char *server<br>
</dl>
<h4 class="discussion">Discussion</h4>
<p class="discussion">The "server" string can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname. Pass <code>NULL</code> to
-restore the default server name.</p>
+IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
+addresses can be optionally followed by a colon and port number to override
+the default port 631, e.g. "hostname:8631". Pass <code>NULL</code> to restore the
+default server name and port.<br>
+<br>
+Note: The current server is tracked separately for each thread in a program.
+Multi-threaded programs that override the server need to do so in each
+thread for the same server to be used.</p>
+<h3 class="function"><span class="info"> CUPS 1.5 </span><a name="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
+<p class="description">Set the server certificate callback.</p>
+<p class="code">
+void cupsSetServerCertCB (<br>
+ <a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br>
+ void *user_data<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>cb</dt>
+<dd class="description">Callback function</dd>
+<dt>user_data</dt>
+<dd class="description">User data pointer</dd>
+</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
+<br>
+Note: The current credentials callback is tracked separately for each thread
+in a program. Multi-threaded programs that override the callback need to do
+so in each thread for the same callback to be used.
+
+</p>
<h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3>
<p class="description">Set the default user name.</p>
<p class="code">
<dd class="description">User name</dd>
</dl>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Pass <code>NULL</code> to restore the default user name.</p>
+<p class="discussion">Pass <code>NULL</code> to restore the default user name.<br>
+<br>
+Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name need to do so
+in each thread for the same user name to be used.</p>
<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3>
<p class="description">Add a document to a job created with cupsCreateJob().</p>
<p class="code">
const char *cupsUser (void);</p>
<h4 class="returnvalue">Return Value</h4>
<p class="description">User name</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">Note: The current user name is tracked separately for each thread in a
+program. Multi-threaded programs that override the user name with the
+<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
+name to be used.</p>
<h2 class="title"><a name="TYPES">Data Types</a></h2>
+<h3 class="typedef"><span class="info"> CUPS 1.5 </span><a name="cups_client_cert_cb_t">cups_client_cert_cb_t</a></h3>
+<p class="description">Client credentials callback </p>
+<p class="code">
+typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);
+</p>
<h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3>
<p class="description">Destination</p>
<p class="code">
<p class="code">
typedef unsigned cups_ptype_t;
</p>
+<h3 class="typedef"><span class="info"> CUPS 1.5 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3>
+<p class="description">Server credentials callback </p>
+<p class="code">
+typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);
+</p>
<h2 class="title"><a name="STRUCTURES">Structures</a></h2>
<h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3>
<p class="description">Destination</p>
projects / thirdparty / cups.git / blobdiff