EVOLUTION-MANAGER
Edit File: api-cups.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- SECTION: Programming --> <head> <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; } 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; } 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: normal; 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'> <!-- "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $" CUPS API header for CUPS. Copyright 2008-2011 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'>CUPS API</h1> <div class='summary'><table summary='General Information'> <thead> <tr> <th>Header</th> <th>cups/cups.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-array.html' target='_top'>Array API</a><br> Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br> Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br> Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br> Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br> Programming: <a href='api-raster.html' target='_top'>Raster API</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="#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="#cupsCancelDestJob" title="Include necessary headers...">cupsCancelDestJob</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="#cupsCheckDestSupported" title="Check that the option and value are supported by the destination.">cupsCheckDestSupported</a></li> <li><a href="#cupsCloseDestJob" title="Close a job and start printing.">cupsCloseDestJob</a></li> <li><a href="#cupsConnectDest" title="Connect to the server for a destination.">cupsConnectDest</a></li> <li><a href="#cupsConnectDestBlock" title="Connect to the server for a destination.">cupsConnectDestBlock</a></li> <li><a href="#cupsCopyDest" title="Callback block">cupsCopyDest</a></li> <li><a href="#cupsCopyDestConflicts" title="Get conflicts and resolutions for a new option/value pair.">cupsCopyDestConflicts</a></li> <li><a href="#cupsCopyDestInfo" title="Get the supported values/capabilities for the destination.">cupsCopyDestInfo</a></li> <li><a href="#cupsCreateDestJob" title="Create a job on a destination.">cupsCreateDestJob</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="#cupsEnumDests" title="Enumerate available destinations with a callback function.">cupsEnumDests</a></li> <li><a href="#cupsEnumDestsBlock" title="Enumerate available destinations with a block.">cupsEnumDestsBlock</a></li> <li><a href="#cupsFinishDestDocument" title="Finish the current document.">cupsFinishDestDocument</a></li> <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li> <li><a href="#cupsFreeDestInfo" title="Free destination information obtained using cupsCopyDestInfo.">cupsFreeDestInfo</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="#cupsGetDestMediaByName" title="Get media names, dimensions, and margins.">cupsGetDestMediaByName</a></li> <li><a href="#cupsGetDestMediaBySize" title="Get media names, dimensions, and margins.">cupsGetDestMediaBySize</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 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="#cupsLocalizeDestOption" title="Get the localized string for a destination option.">cupsLocalizeDestOption</a></li> <li><a href="#cupsLocalizeDestValue" title="Get the localized string for a destination option+value pair.">cupsLocalizeDestValue</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 default server.">cupsPrintFiles</a></li> <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 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="#cupsStartDestDocument" title="Start a new document.">cupsStartDestDocument</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_block_t" title="Destination enumeration block ">cups_dest_block_t</a></li> <li><a href="#cups_dest_cb_t" title="Destination enumeration callback ">cups_dest_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_dinfo_t" title="Destination capability and status information ">cups_dinfo_t</a></li> <li><a href="#cups_job_t" title="Job">cups_job_t</a></li> <li><a href="#cups_option_t" title="Printer Options">cups_option_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> <li><a href="#cups_size_t" title="Media Size ">cups_size_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="#cups_job_s" title="Job">cups_job_s</a></li> <li><a href="#cups_option_s" title="Printer Options">cups_option_s</a></li> <li><a href="#cups_size_s" title="Media Size ">cups_size_s</a></li> <li><a href="#pollfd" title="User data (unused)">pollfd</a></li> </ul></li> <li><a href="#VARIABLES">Variables</a><ul class="code"> <li><a href="#CF_RETURNS_RETAINED" title="Get the Apple language identifier associated with a locale ID.">CF_RETURNS_RETAINED</a></li> </ul></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: api-cups.shtml 7337 2008-02-22 04:44:04Z mike $" API introduction for CUPS. Copyright 2007-2013 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. 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 CUPS API provides the convenience functions needed to support applications, filters, printer drivers, and backends that need to interface with the CUPS scheduler.</p> <h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3> <p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler) to get a list of printers, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure <code>http_t</code>. All of the examples in this document use the <code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a> document provides more information on server connections.</p> <h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3> <p>Printers and classes (collections of printers) are accessed through the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which includes the name (<code>name</code>), instance (<code>instance</code> - a way of selecting certain saved options/settings), and the options and attributes associated with that destination (<code>num_options</code> and <code>options</code>). Destinations are created using the <a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function. The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a specific destination for printing:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dests; int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); <a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests); /* do something with dest */ <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); </pre> <p>Passing <code>NULL</code> to <a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name will return the default destination. Similarly, passing a <code>NULL</code> instance will return the default instance for that destination.</p> <div class='table'><table summary='Table 1: Printer Attributes' width='80%'> <caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption> <thead> <tr> <th>Attribute Name</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>"auth-info-required"</td> <td>The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos)</td> </tr> <tr> <td>"printer-info"</td> <td>The human-readable description of the destination such as "My Laser Printer".</td> </tr> <tr> <td>"printer-is-accepting-jobs"</td> <td>"true" if the destination is accepting new jobs, "false" if not.</td> </tr> <tr> <td>"printer-is-shared"</td> <td>"true" if the destination is being shared with other computers, "false" if not.</td> </tr> <tr> <td>"printer-location"</td> <td>The human-readable location of the destination such as "Lab 4".</td> </tr> <tr> <td>"printer-make-and-model"</td> <td>The human-readable make and model of the destination such as "HP LaserJet 4000 Series".</td> </tr> <tr> <td>"printer-state"</td> <td>"3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.</td> </tr> <tr> <td>"printer-state-change-time"</td> <td>The UNIX time when the destination entered the current state.</td> </tr> <tr> <td>"printer-state-reasons"</td> <td>Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".</td> </tr> <tr> <td>"printer-type"</td> <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a> value associated with the destination.</td> </tr> </tbody> </table></div> <h3><a name='OPTIONS'>Options</a></h3> <p>Options are stored in arrays of <a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each option has a name (<code>name</code>) and value (<code>value</code>) associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a> <code>num_options</code> and <code>options</code> members contain the default options for a particular destination, along with several informational attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>. The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets the value for the named option. For example, the following code lists the available destinations and their human-readable descriptions:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dests; int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests); <a href='#cups_dest_t'>cups_dest_t</a> *dest; int i; const char *value; for (i = num_dests, dest = dests; i > 0; i --, dest ++) if (dest->instance == NULL) { value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options); printf("%s (%s)\n", dest->name, value ? value : "no description"); } <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests); </pre> <p>You can create your own option arrays using the <a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which adds a single named option to an array:</p> <pre class='example'> #include <cups/cups.h> int num_options = 0; <a href='#cups_option_t'>cups_option_t</a> *options = NULL; /* The returned num_options value is updated as needed */ num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options); /* This adds a second option value */ num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options); /* This replaces the first option we added */ num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options); </pre> <p>Use a <code>for</code> loop to copy the options from a destination:</p> <pre class='example'> #include <cups/cups.h> int i; int num_options = 0; <a href='#cups_option_t'>cups_option_t</a> *options = NULL; <a href='#cups_dest_t'>cups_dest_t</a> *dest; for (i = 0; i < dest->num_options; i ++) num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value, num_options, &options); </pre> <p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a> function to free the options array when you are done using it:</p> <pre class='example'> <a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options); </pre> <h3><a name='PRINT_JOBS'>Print Jobs</a></h3> <p>Print jobs are identified by a locally-unique job ID number from 1 to 2<sup>31</sup>-1 and have options and one or more files for printing to a single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a> function creates a new job with one file. The following code prints the CUPS test page file:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dest; int num_options; <a href='#cups_option_t'>cups_option_t</a> *options; int job_id; /* Print a single file */ job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps", "Test Print", num_options, options); </pre> <p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function creates a job with multiple files. The files are provided in a <code>char *</code> array:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dest; int num_options; <a href='#cups_option_t'>cups_option_t</a> *options; int job_id; char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" }; /* Print three files */ job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options); </pre> <p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a> function creates a new job with no files in it. Files are added using the <a href='#cupsStartDocument'><code>cupsStartDocument</code></a>, <a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>, and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions. The following example creates a job with 10 text files for printing:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dest; int num_options; <a href='#cups_option_t'>cups_option_t</a> *options; int job_id; int i; char buffer[1024]; /* Create the job */ job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", num_options, options); /* If the job is created, add 10 files */ if (job_id > 0) { for (i = 1; i <= 10; i ++) { snprintf(buffer, sizeof(buffer), "file%d.txt", i); <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, CUPS_FORMAT_TEXT, i == 10); snprintf(buffer, sizeof(buffer), "File %d\n" "\n" "One fish,\n" "Two fish,\n "Red fish,\n "Blue fish\n", i); /* cupsWriteRequestData can be called as many times as needed */ <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer)); <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name); } } </pre> <p>Once you have created a job, you can monitor its status using the <a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures. Each contains the job ID (<code>id</code>), destination name (<code>dest</code>), title (<code>title</code>), and other information associated with the job. The job array is freed using the <a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following example monitors a specific job ID, showing the current job state once every 5 seconds until the job is completed:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dest; int job_id; int num_jobs; <a href='#cups_job_t'>cups_job_t</a> *jobs; int i; ipp_jstate_t job_state = IPP_JOB_PENDING; while (job_state < IPP_JOB_STOPPED) { /* Get my jobs (1) with any state (-1) */ num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1); /* Loop to find my job */ job_state = IPP_JOB_COMPLETED; for (i = 0; i < num_jobs; i ++) if (jobs[i].id == job_id) { job_state = jobs[i].state; break; } /* Free the job array */ <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs); /* Show the current state */ switch (job_state) { case IPP_JOB_PENDING : printf("Job %d is pending.\n", job_id); break; case IPP_JOB_HELD : printf("Job %d is held.\n", job_id); break; case IPP_JOB_PROCESSING : printf("Job %d is processing.\n", job_id); break; case IPP_JOB_STOPPED : printf("Job %d is stopped.\n", job_id); break; case IPP_JOB_CANCELED : printf("Job %d is canceled.\n", job_id); break; case IPP_JOB_ABORTED : printf("Job %d is aborted.\n", job_id); break; case IPP_JOB_COMPLETED : printf("Job %d is completed.\n", job_id); break; } /* Sleep if the job is not finished */ if (job_state < IPP_JOB_STOPPED) sleep(5); } </pre> <p>To cancel a job, use the <a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the job ID:</p> <pre class='example'> #include <cups/cups.h> <a href='#cups_dest_t'>cups_dest_t</a> *dest; int job_id; <a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id); </pre> <h3><a name='ERROR_HANDLING'>Error Handling</a></h3> <p>If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling the <a href='#cupsLastError'><code>cupsLastError</code></a> and <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions. <a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP error code (<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>) that was encountered, while <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns a (localized) human-readable string that can be shown to the user. For example, if any of the job creation functions returns a job ID of 0, you can use <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show the reason why the job could not be created:</p> <pre class='example'> #include <cups/cups.h> int job_id; if (job_id == 0) puts(cupsLastErrorString()); </pre> <h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3> <p>CUPS supports authentication of any request, including submission of print jobs. The default mechanism for getting the username and password is to use the login user and a password from the console.</p> <p>To support other types of applications, in particular Graphical User Interfaces ("GUIs"), the CUPS API provides functions to set the default username and to register a callback function that returns a password string.</p> <p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> function is used to set a password callback in your program. Only one function can be used at any time.</p> <p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the current username for authentication. This function can be called by your password callback function to change the current username as needed.</p> <p>The following example shows a simple password callback that gets a username and password from the user:</p> <pre class='example'> #include <cups/cups.h> const char * my_password_cb(const char *prompt) { char user[65]; puts(prompt); /* Get a username from the user */ printf("Username: "); if (fgets(user, sizeof(user), stdin) == NULL) return (NULL); /* Strip the newline from the string and set the user */ user[strlen(user) - 1] = '\0'; <a href='#cupsSetUser'>cupsSetUser</a>(user); /* Use getpass() to ask for the password... */ return (getpass("Password: ")); } <a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb); </pre> <p>Similarly, a GUI could display the prompt string in a window with input fields for the username and password. The username should default to the 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="cupsAddDest">cupsAddDest</a></h3> <p class="description">Add a destination to the list of destinations.</p> <p class="code"> int cupsAddDest (<br> const char *name,<br> const char *instance,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> **dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> <dt>instance</dt> <dd class="description">Instance name or <code>NULL</code> for none/primary</dd> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New number of destinations</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function cannot be used to add a new class or printer queue, it only adds a new container of saved options for the named destination or instance.<br> <br> If the named destination already exists, the destination list is returned unchanged. Adding a new instance of a destination creates a copy of that destination's options.<br> <br> Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of destinations to the user's lpoptions file.</p> <h3 class="function"><a name="cupsAddOption">cupsAddOption</a></h3> <p class="description">Add an option to an option array.</p> <p class="code"> int cupsAddOption (<br> const char *name,<br> const char *value,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> **options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Name of option</dd> <dt>value</dt> <dd class="description">Value of option</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Pointer to options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of options</p> <h4 class="discussion">Discussion</h4> <p class="discussion">New option arrays can be initialized simply by passing 0 for the "num_options" parameter.</p> <h3 class="function"><span class="info"> DEPRECATED </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> http_t *http,<br> const char *dest,<br> char *buffer,<br> 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"> DEPRECATED </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> <p class="description">Export a printer to Samba.</p> <p class="code"> int cupsAdminExportSamba (<br> const char *dest,<br> const char *ppd,<br> const char *samba_server,<br> const char *samba_user,<br> const char *samba_password,<br> 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"> CUPS 1.3/OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> <p class="description">Get settings from the server.</p> <p class="code"> int cupsAdminGetServerSettings (<br> http_t *http,<br> int *num_settings,<br> <a href="#cups_option_t">cups_option_t</a> **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"> CUPS 1.3/OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> <p class="description">Set settings on the server.</p> <p class="code"> int cupsAdminSetServerSettings (<br> http_t *http,<br> int num_settings,<br> <a href="#cups_option_t">cups_option_t</a> *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"><a name="cupsCancelDestJob">cupsCancelDestJob</a></h3> <p class="description">Include necessary headers...</p> <p class="code"> ipp_status_t cupsCancelDestJob (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> int job_id<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>job_id</dt> <dd class="description">Job ID</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Cancel a job on a destination.</p> <p class="discussion">The "job_id" is the number returned by cupsCreateDestJob.<br> <br> Returns IPP_OK on success and IPP_NOT_AUTHORIZED or IPP_FORBIDDEN on failure. </p> <h3 class="function"><a name="cupsCancelJob">cupsCancelJob</a></h3> <p class="description">Cancel a print job on the default server.</p> <p class="code"> int cupsCancelJob (<br> const char *name,<br> int job_id<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Name of printer or class</dd> <dt>job_id</dt> <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</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">Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> to cancel the current job on the named destination.<br> <br> Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get the cause of any failure.</p> <h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3> <p class="description">Cancel or purge a print job.</p> <p class="code"> ipp_status_t cupsCancelJob2 (<br> http_t *http,<br> const char *name,<br> int job_id,<br> int purge<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>name</dt> <dd class="description">Name of printer or class</dd> <dt>job_id</dt> <dd class="description">Job ID, <code>CUPS_JOBID_CURRENT</code> for the current job, or <code>CUPS_JOBID_ALL</code> for all jobs</dd> <dt>purge</dt> <dd class="description">1 to purge, 0 to cancel</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">IPP status</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Canceled jobs remain in the job history while purged jobs are removed from the job history.<br> <br> Pass <code>CUPS_JOBID_ALL</code> to cancel all jobs or <code>CUPS_JOBID_CURRENT</code> to cancel the current job on the named destination.<br> <br> Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get the cause of any failure. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCheckDestSupported">cupsCheckDestSupported</a></h3> <p class="description">Check that the option and value are supported by the destination.</p> <p class="code"> int cupsCheckDestSupported (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> const char *option,<br> const char *value<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>option</dt> <dd class="description">Option</dd> <dt>value</dt> <dd class="description">Value</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if supported, 0 otherwise</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Returns 1 if supported, 0 otherwise. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCloseDestJob">cupsCloseDestJob</a></h3> <p class="description">Close a job and start printing.</p> <p class="code"> ipp_status_t cupsCloseDestJob (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> int job_id<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>info</dt> <dd class="description">Destination information</dd> <dt>job_id</dt> <dd class="description">Job ID</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">IPP status code</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Use when the last call to cupsStartDocument passed 0 for "last_document". "job_id" is the job ID returned by cupsCreateDestJob. Returns <code>IPP_OK</code> on success. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDest">cupsConnectDest</a></h3> <p class="description">Connect to the server for a destination.</p> <p class="code"> http_t *cupsConnectDest (<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> unsigned flags,<br> int msec,<br> int *cancel,<br> char *resource,<br> size_t resourcesize,<br> <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> void *user_data<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>dest</dt> <dd class="description">Destination</dd> <dt>flags</dt> <dd class="description">Connection flags</dd> <dt>msec</dt> <dd class="description">Timeout in milliseconds</dd> <dt>cancel</dt> <dd class="description">Pointer to "cancel" variable</dd> <dt>resource</dt> <dd class="description">Resource buffer</dd> <dt>resourcesize</dt> <dd class="description">Size of resource buffer</dd> <dt>cb</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">Connection to server or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">Connect to the destination, returning a new http_t connection object and optionally the resource path to use for the destination. These calls will block until a connection is made, the timeout expires, the integer pointed to by "cancel" is non-zero, or the callback function (or block) returns 0, The caller is responsible for calling httpClose() on the returned object. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDestBlock">cupsConnectDestBlock</a></h3> <p class="description">Connect to the server for a destination.</p> <p class="code"> http_t *cupsConnectDestBlock (<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> unsigned flags,<br> int msec,<br> int *cancel,<br> char *resource,<br> size_t resourcesize,<br> <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>dest</dt> <dd class="description">Destination</dd> <dt>flags</dt> <dd class="description">Connection flags</dd> <dt>msec</dt> <dd class="description">Timeout in milliseconds</dd> <dt>cancel</dt> <dd class="description">Pointer to "cancel" variable</dd> <dt>resource</dt> <dd class="description">Resource buffer</dd> <dt>resourcesize</dt> <dd class="description">Size of resource buffer</dd> <dt>block</dt> <dd class="description">Callback block</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Connection to server or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">Connect to the destination, returning a new http_t connection object and optionally the resource path to use for the destination. These calls will block until a connection is made, the timeout expires, the integer pointed to by "cancel" is non-zero, or the callback function (or block) returns 0, The caller is responsible for calling httpClose() on the returned object. </p> <h3 class="function"><a name="cupsCopyDest">cupsCopyDest</a></h3> <p class="description">Callback block</p> <p class="code"> int cupsCopyDest (<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> **dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>dest</dt> <dt>num_dests</dt> <dt>dests</dt> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Copy a destination.</p> <p class="discussion">Make a copy of the destination to an array of destinations (or just a single copy) - for use with the cupsEnumDests* functions. The caller is responsible for calling cupsFreeDests() on the returned object(s). </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3> <p class="description">Get conflicts and resolutions for a new option/value pair.</p> <p class="code"> int cupsCopyDestConflicts (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options,<br> const char *new_option,<br> const char *new_value,<br> int *num_conflicts,<br> <a href="#cups_option_t">cups_option_t</a> **conflicts,<br> int *num_resolved,<br> <a href="#cups_option_t">cups_option_t</a> **resolved<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>num_options</dt> <dd class="description">Number of current options</dd> <dt>options</dt> <dd class="description">Current options</dd> <dt>new_option</dt> <dd class="description">New option</dd> <dt>new_value</dt> <dd class="description">New value</dd> <dt>num_conflicts</dt> <dd class="description">Number of conflicting options</dd> <dt>conflicts</dt> <dd class="description">Conflicting options</dd> <dt>num_resolved</dt> <dd class="description">Number of options to resolve</dd> <dt>resolved</dt> <dd class="description">Resolved options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if there is a conflict, 0 if none, -1 on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">"num_options" and "options" represent the currently selected options by the user. "new_option" and "new_value" are the setting the user has just changed.<br> <br> Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if there was an unrecoverable error such as a resolver loop.<br> <br> If "num_conflicts" and "conflicts" are not <code>NULL</code>, they are set to contain the list of conflicting option/value pairs. Similarly, if "num_resolved" and "resolved" are not <code>NULL</code> they will be set to the list of changes needed to resolve the conflict.<br> <br> If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCopyDestInfo">cupsCopyDestInfo</a></h3> <p class="description">Get the supported values/capabilities for the destination.</p> <p class="code"> <a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Destination information</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return value. <code>NULL</code> is returned on error. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsCreateDestJob">cupsCreateDestJob</a></h3> <p class="description">Create a job on a destination.</p> <p class="code"> ipp_status_t cupsCreateDestJob (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> int *job_id,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>info</dt> <dd class="description">Destination information</dd> <dt>job_id</dt> <dd class="description">Job ID or 0 on error</dd> <dt>title</dt> <dd class="description">Job name</dd> <dt>num_options</dt> <dd class="description">Number of job options</dd> <dt>options</dt> <dd class="description">Job options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">IPP status code</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Returns <code>IPP_OK</code> or <code>IPP_OK_SUBST</code> on success, saving the job ID in the variable pointed to by "job_id". </p> <h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3> <p class="description">Create an empty job for streaming.</p> <p class="code"> int cupsCreateJob (<br> http_t *http,<br> const char *name,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<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>name</dt> <dd class="description">Destination name</dd> <dt>title</dt> <dd class="description">Title of job</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Use this function when you want to stream print data using the <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> functions. If you have one or more files to print, use the <a href="#cupsPrintFile2"><code>cupsPrintFile2</code></a> or <a href="#cupsPrintFiles2"><code>cupsPrintFiles2</code></a> function instead. </p> <h3 class="function"><a name="cupsEncryption">cupsEncryption</a></h3> <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="description">Encryption settings</p> <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 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.6/OS X 10.8 </span><a name="cupsEnumDests">cupsEnumDests</a></h3> <p class="description">Enumerate available destinations with a callback function.</p> <p class="code"> int cupsEnumDests (<br> unsigned flags,<br> int msec,<br> int *cancel,<br> <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> void *user_data<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>flags</dt> <dd class="description">Enumeration flags</dd> <dt>msec</dt> <dd class="description">Timeout in milliseconds, -1 for indefinite</dd> <dt>cancel</dt> <dd class="description">Pointer to "cancel" variable</dd> <dt>type</dt> <dd class="description">Printer type bits</dd> <dt>mask</dt> <dd class="description">Mask for printer type bits</dd> <dt>cb</dt> <dd class="description">Callback function</dd> <dt>user_data</dt> <dd class="description">User data</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">Destinations are enumerated from one or more sources. The callback function receives the <code>user_data</code> pointer, destination name, instance, number of options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The function must return 1 to continue enumeration or 0 to stop.<br> <br> Enumeration happens on the current thread and does not return until all destinations have been enumerated or the callback function returns 0. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3> <p class="description">Enumerate available destinations with a block.</p> <p class="code"> int cupsEnumDestsBlock (<br> unsigned flags,<br> int timeout,<br> int *cancel,<br> <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>flags</dt> <dd class="description">Enumeration flags</dd> <dt>timeout</dt> <dd class="description">Timeout in milliseconds, 0 for indefinite</dd> <dt>cancel</dt> <dd class="description">Pointer to "cancel" variable</dd> <dt>type</dt> <dd class="description">Printer type bits</dd> <dt>mask</dt> <dd class="description">Mask for printer type bits</dd> <dt>block</dt> <dd class="description">Block</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">Destinations are enumerated from one or more sources. The block receives the destination name, instance, number of options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The block must return 1 to continue enumeration or 0 to stop.<br> <br> Enumeration happens on the current thread and does not return until all destinations have been enumerated or the block returns 0. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsFinishDestDocument">cupsFinishDestDocument</a></h3> <p class="description">Finish the current document.</p> <p class="code"> ipp_status_t cupsFinishDestDocument (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *info<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>info</dt> <dd class="description">Destination information</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status of document submission</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Returns <code>IPP_OK</code> or <code>IPP_OK_SUBST</code> on success. </p> <h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3> <p class="description">Finish sending a document.</p> <p class="code"> ipp_status_t cupsFinishDocument (<br> http_t *http,<br> const char *name<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>name</dt> <dd class="description">Destination name</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status of document submission</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The document must have been started using <a href="#cupsStartDocument"><code>cupsStartDocument</code></a>. </p> <h3 class="function"><a name="cupsFreeDestInfo">cupsFreeDestInfo</a></h3> <p class="description">Free destination information obtained using <a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p> <p class="code"> void cupsFreeDestInfo (<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>dinfo</dt> <dd class="description">Destination information</dd> </dl> <h3 class="function"><a name="cupsFreeDests">cupsFreeDests</a></h3> <p class="description">Free the memory used by the list of destinations.</p> <p class="code"> void cupsFreeDests (<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> *dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h3 class="function"><a name="cupsFreeJobs">cupsFreeJobs</a></h3> <p class="description">Free memory used by job data.</p> <p class="code"> void cupsFreeJobs (<br> int num_jobs,<br> <a href="#cups_job_t">cups_job_t</a> *jobs<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>num_jobs</dt> <dd class="description">Number of jobs</dd> <dt>jobs</dt> <dd class="description">Jobs</dd> </dl> <h3 class="function"><a name="cupsFreeOptions">cupsFreeOptions</a></h3> <p class="description">Free all memory used by options.</p> <p class="code"> void cupsFreeOptions (<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Pointer to options</dd> </dl> <h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsGetClasses">cupsGetClasses</a></h3> <p class="description">Get a list of printer classes from the default server.</p> <p class="code"> int cupsGetClasses (<br> char ***classes<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>classes</dt> <dd class="description">Classes</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of classes</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. </p> <h3 class="function"><a name="cupsGetDefault">cupsGetDefault</a></h3> <p class="description">Get the default printer or class for the default server.</p> <p class="code"> const char *cupsGetDefault (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">Default printer or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function returns the default printer or class as defined by the LPDEST or PRINTER environment variables. If these environment variables are not set, the server default destination is returned. Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer.</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3> <p class="description">Get the default printer or class for the specified server.</p> <p class="code"> const char *cupsGetDefault2 (<br> http_t *http<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Default printer or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function returns the default printer or class as defined by the LPDEST or PRINTER environment variables. If these environment variables are not set, the server default destination is returned. Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer. </p> <h3 class="function"><a name="cupsGetDest">cupsGetDest</a></h3> <p class="description">Get the named destination from the list.</p> <p class="code"> <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest (<br> const char *name,<br> const char *instance,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> *dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> <dt>instance</dt> <dd class="description">Instance name or <code>NULL</code></dd> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Destination pointer or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">Use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a list of supported destinations for the current user.</p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3> <p class="description">Get media names, dimensions, and margins.</p> <p class="code"> int cupsGetDestMediaByName (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> const char *media,<br> unsigned flags,<br> <a href="#cups_size_t">cups_size_t</a> *size<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>media</dt> <dd class="description">Media name</dd> <dt>flags</dt> <dd class="description">Media matching flags</dd> <dt>size</dt> <dd class="description">Media size information</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 on match, 0 on failure</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The "media" string is a PWG media name. "Flags" provides some matching guidance (multiple flags can be combined):<br> <br> CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer, CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size, CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing, CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the size amongst the "ready" media.<br> <br> The matching result (if any) is returned in the "cups_size_t" structure.<br> <br> Returns 1 when there is a match and 0 if there is not a match. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3> <p class="description">Get media names, dimensions, and margins.</p> <p class="code"> int cupsGetDestMediaBySize (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> int width,<br> int length,<br> unsigned flags,<br> <a href="#cups_size_t">cups_size_t</a> *size<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>width</dt> <dd class="description">Media width in hundredths of of millimeters</dd> <dt>length</dt> <dd class="description">Media length in hundredths of of millimeters</dd> <dt>flags</dt> <dd class="description">Media matching flags</dd> <dt>size</dt> <dd class="description">Media size information</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 on match, 0 on failure</p> <h4 class="discussion">Discussion</h4> <p class="discussion">"Width" and "length" are the dimensions in hundredths of millimeters. "Flags" provides some matching guidance (multiple flags can be combined):<br> <br> CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer, CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size, CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing, CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the size amongst the "ready" media.<br> <br> The matching result (if any) is returned in the "cups_size_t" structure.<br> <br> Returns 1 when there is a match and 0 if there is not a match. </p> <h3 class="function"><a name="cupsGetDests">cupsGetDests</a></h3> <p class="description">Get the list of destinations from the default server.</p> <p class="code"> int cupsGetDests (<br> <a href="#cups_dest_t">cups_dest_t</a> **dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of destinations</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, printer-state-reasons, and printer-type attributes as options. CUPS 1.4 adds the marker-change-time, marker-colors, marker-high-levels, marker-levels, marker-low-levels, marker-message, marker-names, marker-types, and printer-commands attributes as well.<br> <br> Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3> <p class="description">Get the list of destinations from the specified server.</p> <p class="code"> int cupsGetDests2 (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> **dests<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>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of destinations</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, printer-state-reasons, and printer-type attributes as options. CUPS 1.4 adds the marker-change-time, marker-colors, marker-high-levels, marker-levels, marker-low-levels, marker-message, marker-names, marker-types, and printer-commands attributes as well.<br> <br> Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination. </p> <h3 class="function"><a name="cupsGetJobs">cupsGetJobs</a></h3> <p class="description">Get the jobs from the default server.</p> <p class="code"> int cupsGetJobs (<br> <a href="#cups_job_t">cups_job_t</a> **jobs,<br> const char *name,<br> int myjobs,<br> int whichjobs<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>jobs</dt> <dd class="description">Job data</dd> <dt>name</dt> <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> <dt>myjobs</dt> <dd class="description">0 = all users, 1 = mine</dd> <dt>whichjobs</dt> <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of jobs</p> <h4 class="discussion">Discussion</h4> <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns jobs that are stopped, canceled, aborted, or completed.</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3> <p class="description">Get the jobs from the specified server.</p> <p class="code"> int cupsGetJobs2 (<br> http_t *http,<br> <a href="#cups_job_t">cups_job_t</a> **jobs,<br> const char *name,<br> int myjobs,<br> int whichjobs<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>jobs</dt> <dd class="description">Job data</dd> <dt>name</dt> <dd class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</dd> <dt>myjobs</dt> <dd class="description">0 = all users, 1 = mine</dd> <dt>whichjobs</dt> <dd class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of jobs</p> <h4 class="discussion">Discussion</h4> <p class="discussion">A "whichjobs" value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns jobs that are stopped, canceled, aborted, or completed. </p> <h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3> <p class="description">Get options for the named destination.</p> <p class="code"> <a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br> http_t *http,<br> const char *name,<br> const char *instance<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>name</dt> <dd class="description">Destination name or <code>NULL</code> for the default destination</dd> <dt>instance</dt> <dd class="description">Instance name or <code>NULL</code></dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Destination or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function is optimized for retrieving a single destination and should be used instead of <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you either know the name of the destination or want to print to the default destination. If <code>NULL</code> is returned, the destination does not exist or there is no default destination.<br> <br> If "http" is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print server will be used.<br> <br> If "name" is <code>NULL</code>, the default printer for the current user will be returned.<br> <br> The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a "num_dests" value of 1. </p> <h3 class="function"><a name="cupsGetOption">cupsGetOption</a></h3> <p class="description">Get an option value.</p> <p class="code"> const char *cupsGetOption (<br> const char *name,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Name of option</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Option value or <code>NULL</code></p> <h3 class="function"><a name="cupsGetPPD">cupsGetPPD</a></h3> <p class="description">Get the PPD file for a printer on the default server.</p> <p class="code"> const char *cupsGetPPD (<br> const char *name<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Filename for PPD file</p> <h4 class="discussion">Discussion</h4> <p class="discussion">For classes, <code>cupsGetPPD</code> returns the PPD file for the first printer 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>. 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/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"> const char *cupsGetPPD2 (<br> http_t *http,<br> const char *name<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>name</dt> <dd class="description">Destination name</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Filename for PPD file</p> <h4 class="discussion">Discussion</h4> <p class="discussion">For classes, <code>cupsGetPPD2</code> returns the PPD file for the first printer 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>. 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/OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3> <p class="description">Get the PPD file for a printer on the specified server if it has changed.</p> <p class="code"> http_status_t cupsGetPPD3 (<br> http_t *http,<br> const char *name,<br> time_t *modtime,<br> char *buffer,<br> size_t bufsize<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">HTTP connection or <code>CUPS_HTTP_DEFAULT</code></dd> <dt>name</dt> <dd class="description">Destination name</dd> <dt>modtime</dt> <dd class="description">Modification time</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">HTTP status</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The "modtime" parameter contains the modification time of any locally-cached content and is updated with the time from the PPD file on the server.<br> <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. 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 status is an error.<br> <br> For classes, <code>cupsGetPPD3</code> returns the PPD file for the first printer in the class. </p> <h3 class="function"><a name="cupsGetPassword">cupsGetPassword</a></h3> <p class="description">Get a password from the user.</p> <p class="code"> const char *cupsGetPassword (<br> const char *prompt<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>prompt</dt> <dd class="description">Prompt string</dd> </dl> <h4 class="returnvalue">Return Value</h4> <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.<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/OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3> <p class="description">Get a password from the user using the advanced password callback.</p> <p class="code"> const char *cupsGetPassword2 (<br> const char *prompt,<br> http_t *http,<br> const char *method,<br> const char *resource<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>prompt</dt> <dd class="description">Prompt string</dd> <dt>http</dt> <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd> <dt>method</dt> <dd class="description">Request method ("GET", "POST", "PUT")</dd> <dt>resource</dt> <dd class="description">Resource path</dd> </dl> <h4 class="returnvalue">Return Value</h4> <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.<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> <p class="description">Get a list of printers from the default server.</p> <p class="code"> int cupsGetPrinters (<br> char ***printers<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>printers</dt> <dd class="description">Printers</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of printers</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. </p> <h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3> <p class="description">Get an available PPD file from the server.</p> <p class="code"> char *cupsGetServerPPD (<br> http_t *http,<br> const char *name<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>name</dt> <dd class="description">Name of PPD file ("ppd-name")</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Name of PPD file or <code>NULL</code> on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function returns the named PPD file from the server. The list of available PPDs is provided by the IPP <code>CUPS_GET_PPDS</code> operation.<br> <br> You must remove (unlink) the PPD file when you are finished with it. The PPD filename is stored in a static location that will be overwritten on the next call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a>, <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>, or <a href="#cupsGetServerPPD"><code>cupsGetServerPPD</code></a>. </p> <h3 class="function"><a name="cupsLangDefault">cupsLangDefault</a></h3> <p class="description">Return the default language.</p> <p class="code"> cups_lang_t *cupsLangDefault (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">Language data</p> <h3 class="function"><a name="cupsLangEncoding">cupsLangEncoding</a></h3> <p class="description">Return the character encoding (us-ascii, etc.) for the given language.</p> <p class="code"> const char *cupsLangEncoding (<br> cups_lang_t *lang<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>lang</dt> <dd class="description">Language data</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Character encoding</p> <h3 class="function"><a name="cupsLangFlush">cupsLangFlush</a></h3> <p class="description">Flush all language data out of the cache.</p> <p class="code"> void cupsLangFlush (void);</p> <h3 class="function"><a name="cupsLangFree">cupsLangFree</a></h3> <p class="description">Free language data.</p> <p class="code"> void cupsLangFree (<br> cups_lang_t *lang<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>lang</dt> <dd class="description">Language to free</dd> </dl> <h4 class="discussion">Discussion</h4> <p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p> <h3 class="function"><a name="cupsLangGet">cupsLangGet</a></h3> <p class="description">Get a language.</p> <p class="code"> cups_lang_t *cupsLangGet (<br> const char *language<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>language</dt> <dd class="description">Language or locale</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Language data</p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3> <p class="description">Get the localized string for a destination option.</p> <p class="code"> const char *cupsLocalizeDestOption (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> const char *option<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>option</dt> <dd class="description">Option to localize</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Localized string</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The returned string is stored in the destination information and will become invalid if the destination information is deleted. </p> <h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3> <p class="description">Get the localized string for a destination option+value pair.</p> <p class="code"> const char *cupsLocalizeDestValue (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo,<br> const char *option,<br> const char *value<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>dinfo</dt> <dd class="description">Destination information</dd> <dt>option</dt> <dd class="description">Option to localize</dd> <dt>value</dt> <dd class="description">Value to localize</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Localized string</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The returned string is stored in the destination information and will become invalid if the destination information is deleted. </p> <h3 class="function"><span class="info"> CUPS 1.2/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"> char *cupsNotifySubject (<br> cups_lang_t *lang,<br> ipp_t *event<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>lang</dt> <dd class="description">Language data</dd> <dt>event</dt> <dd class="description">Event data</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Subject string or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">The returned string must be freed by the caller using <code>free</code>. </p> <h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3> <p class="description">Return the text for the given notification message.</p> <p class="code"> char *cupsNotifyText (<br> cups_lang_t *lang,<br> ipp_t *event<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>lang</dt> <dd class="description">Language data</dd> <dt>event</dt> <dd class="description">Event data</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Message text or <code>NULL</code></p> <h4 class="discussion">Discussion</h4> <p class="discussion">The returned string must be freed by the caller using <code>free</code>. </p> <h3 class="function"><a name="cupsParseOptions">cupsParseOptions</a></h3> <p class="description">Parse options from a command-line argument.</p> <p class="code"> int cupsParseOptions (<br> const char *arg,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> **options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>arg</dt> <dd class="description">Argument to parse</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options found</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of options found</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function converts space-delimited name/value pairs according to the PAPI text option ABNF specification. Collection values ("name={a=... b=... c=...}") are stored with the curley brackets intact - use <code>cupsParseOptions</code> on the value to extract the collection attributes.</p> <h3 class="function"><a name="cupsPrintFile">cupsPrintFile</a></h3> <p class="description">Print a file to a printer or class on the default server.</p> <p class="code"> int cupsPrintFile (<br> const char *name,<br> const char *filename,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> <dt>filename</dt> <dd class="description">File to print</dd> <dt>title</dt> <dd class="description">Title of job</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3> <p class="description">Print a file to a printer or class on the specified server.</p> <p class="code"> int cupsPrintFile2 (<br> http_t *http,<br> const char *name,<br> const char *filename,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to server</dd> <dt>name</dt> <dd class="description">Destination name</dd> <dt>filename</dt> <dd class="description">File to print</dd> <dt>title</dt> <dd class="description">Title of job</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> <h3 class="function"><a name="cupsPrintFiles">cupsPrintFiles</a></h3> <p class="description">Print one or more files to a printer or class on the default server.</p> <p class="code"> int cupsPrintFiles (<br> const char *name,<br> int num_files,<br> const char **files,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> <dt>num_files</dt> <dd class="description">Number of files</dd> <dt>files</dt> <dd class="description">File(s) to print</dd> <dt>title</dt> <dd class="description">Title of job</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3> <p class="description">Print one or more files to a printer or class on the specified server.</p> <p class="code"> int cupsPrintFiles2 (<br> http_t *http,<br> const char *name,<br> int num_files,<br> const char **files,<br> const char *title,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options<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>name</dt> <dd class="description">Destination name</dd> <dt>num_files</dt> <dd class="description">Number of files</dd> <dt>files</dt> <dd class="description">File(s) to print</dd> <dt>title</dt> <dd class="description">Title of job</dd> <dt>num_options</dt> <dd class="description">Number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> <h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3> <p class="description">Remove a destination from the destination list.</p> <p class="code"> int cupsRemoveDest (<br> const char *name,<br> const char *instance,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> **dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> <dt>instance</dt> <dd class="description">Instance name or <code>NULL</code></dd> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New number of destinations</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Removing a destination/instance does not delete the class or printer queue, merely the lpoptions for that destination/instance. Use the <a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new options for the user. </p> <h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3> <p class="description">Remove an option from an option array.</p> <p class="code"> int cupsRemoveOption (<br> const char *name,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> **options<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Option name</dd> <dt>num_options</dt> <dd class="description">Current number of options</dd> <dt>options</dt> <dd class="description">Options</dd> </dl> <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 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 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/OS X 10.7 </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/OS X 10.7 </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/OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> <p class="description">Set the default destination.</p> <p class="code"> void cupsSetDefaultDest (<br> const char *name,<br> const char *instance,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> *dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>name</dt> <dd class="description">Destination name</dd> <dt>instance</dt> <dd class="description">Instance name or <code>NULL</code></dd> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h3 class="function"><a name="cupsSetDests">cupsSetDests</a></h3> <p class="description">Save the list of destinations for the default server.</p> <p class="code"> void cupsSetDests (<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> *dests<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>num_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="discussion">Discussion</h4> <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.</p> <h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3> <p class="description">Save the list of destinations for the specified server.</p> <p class="code"> int cupsSetDests2 (<br> http_t *http,<br> int num_dests,<br> <a href="#cups_dest_t">cups_dest_t</a> *dests<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_dests</dt> <dd class="description">Number of destinations</dd> <dt>dests</dt> <dd class="description">Destinations</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user. </p> <h3 class="function"><a name="cupsSetEncryption">cupsSetEncryption</a></h3> <p class="description">Set the encryption preference.</p> <p class="code"> void cupsSetEncryption (<br> http_encryption_t e<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <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"> void cupsSetPasswordCB (<br> <a href="#cups_password_cb_t">cups_password_cb_t</a> cb<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>cb</dt> <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, 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/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"> void cupsSetPasswordCB2 (<br> <a href="#cups_password_cb2_t">cups_password_cb2_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 (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 and port.</p> <p class="code"> void cupsSetServer (<br> const char *server<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>server</dt> <dd class="description">Server name</dd> </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. 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/OS X 10.7 </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"> void cupsSetUser (<br> const char *user<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>user</dt> <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.<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.6/OS X 10.8 </span><a name="cupsStartDestDocument">cupsStartDestDocument</a></h3> <p class="description">Start a new document.</p> <p class="code"> http_status_t cupsStartDestDocument (<br> http_t *http,<br> <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> <a href="#cups_dinfo_t">cups_dinfo_t</a> *info,<br> int job_id,<br> const char *docname,<br> const char *format,<br> int num_options,<br> <a href="#cups_option_t">cups_option_t</a> *options,<br> int last_document<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>http</dt> <dd class="description">Connection to destination</dd> <dt>dest</dt> <dd class="description">Destination</dd> <dt>info</dt> <dd class="description">Destination information</dd> <dt>job_id</dt> <dd class="description">Job ID</dd> <dt>docname</dt> <dd class="description">Document name</dd> <dt>format</dt> <dd class="description">Document format</dd> <dt>num_options</dt> <dd class="description">Number of document options</dd> <dt>options</dt> <dd class="description">Document options</dd> <dt>last_document</dt> <dd class="description">1 if this is the last document</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status of document creation</p> <h4 class="discussion">Discussion</h4> <p class="discussion">"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name of the document/file being printed, "format" is the MIME media type for the document (see CUPS_FORMAT_xxx constants), and "num_options" and "options" are the options do be applied to the document. "last_document" should be 1 if this is the last document to be submitted in the job. Returns <code>HTTP_CONTINUE</code> on success. </p> <h3 class="function"><span class="info"> CUPS 1.4/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"> http_status_t cupsStartDocument (<br> http_t *http,<br> const char *name,<br> int job_id,<br> const char *docname,<br> const char *format,<br> int last_document<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>name</dt> <dd class="description">Destination name</dd> <dt>job_id</dt> <dd class="description">Job ID from <a href="#cupsCreateJob"><code>cupsCreateJob</code></a></dd> <dt>docname</dt> <dd class="description">Name of document</dd> <dt>format</dt> <dd class="description">MIME type or <code>CUPS_FORMAT_foo</code></dd> <dt>last_document</dt> <dd class="description">1 for last document in job, 0 otherwise</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">HTTP status of request</p> <h4 class="discussion">Discussion</h4> <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write data for the document and <a href="#cupsFinishDocument"><code>cupsFinishDocument</code></a> to finish the document and get the submission status.<br> <br> The MIME type constants <code>CUPS_FORMAT_AUTO</code>, <code>CUPS_FORMAT_PDF</code>, <code>CUPS_FORMAT_POSTSCRIPT</code>, <code>CUPS_FORMAT_RAW</code>, and <code>CUPS_FORMAT_TEXT</code> are provided for the "format" argument, although any supported MIME type string can be supplied. </p> <h3 class="function"><a name="cupsTempFd">cupsTempFd</a></h3> <p class="description">Creates a temporary file.</p> <p class="code"> int cupsTempFd (<br> char *filename,<br> int len<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>filename</dt> <dd class="description">Pointer to buffer</dd> <dt>len</dt> <dd class="description">Size of buffer</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New file descriptor or -1 on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The temporary filename is returned in the filename buffer. The temporary file is opened for reading and writing.</p> <h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsTempFile">cupsTempFile</a></h3> <p class="description">Generates a temporary filename.</p> <p class="code"> char *cupsTempFile (<br> char *filename,<br> int len<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>filename</dt> <dd class="description">Pointer to buffer</dd> <dt>len</dt> <dd class="description">Size of buffer</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Filename or <code>NULL</code> on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The temporary filename is returned in the filename buffer. This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code></a> or <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead. </p> <h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3> <p class="description">Creates a temporary CUPS file.</p> <p class="code"> cups_file_t *cupsTempFile2 (<br> char *filename,<br> int len<br> );</p> <h4 class="parameters">Parameters</h4> <dl> <dt>filename</dt> <dd class="description">Pointer to buffer</dd> <dt>len</dt> <dd class="description">Size of buffer</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">CUPS file or <code>NULL</code> on error</p> <h4 class="discussion">Discussion</h4> <p class="discussion">The temporary filename is returned in the filename buffer. The temporary file is opened for writing. </p> <h3 class="function"><a name="cupsUser">cupsUser</a></h3> <p class="description">Return the current user's name.</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/OS X 10.7 </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"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_block_t">cups_dest_block_t</a></h3> <p class="description">Destination enumeration block </p> <p class="code"> typedef int (*cups_dest_block_t(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); </p> <h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_cb_t">cups_dest_cb_t</a></h3> <p class="description">Destination enumeration callback </p> <p class="code"> typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); </p> <h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3> <p class="description">Destination</p> <p class="code"> typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t; </p> <h3 class="typedef"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3> <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> <h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dinfo_t">cups_dinfo_t</a></h3> <p class="description">Destination capability and status information </p> <p class="code"> typedef struct _cups_dinfo_s cups_dinfo_t; </p> <h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3> <p class="description">Job</p> <p class="code"> typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t; </p> <h3 class="typedef"><a name="cups_option_t">cups_option_t</a></h3> <p class="description">Printer Options</p> <p class="code"> typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t; </p> <h3 class="typedef"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3> <p class="description">New password callback </p> <p class="code"> typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data); </p> <h3 class="typedef"><a name="cups_password_cb_t">cups_password_cb_t</a></h3> <p class="description">Password callback</p> <p class="code"> typedef const char *(*cups_password_cb_t)(const char *prompt); </p> <h3 class="typedef"><a name="cups_ptype_t">cups_ptype_t</a></h3> <p class="description">Printer type/capability bits</p> <p class="code"> typedef unsigned cups_ptype_t; </p> <h3 class="typedef"><span class="info"> CUPS 1.5/OS X 10.7 </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> <h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_t">cups_size_t</a></h3> <p class="description">Media Size </p> <p class="code"> typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t; </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> <p class="code">struct cups_dest_s {<br> char *name, *instance;<br> int is_default;<br> int num_options;<br> <a href="#cups_option_t">cups_option_t</a> *options;<br> };</p> <h4 class="members">Members</h4> <dl> <dt>instance </dt> <dd class="description">Local instance name or NULL</dd> <dt>is_default </dt> <dd class="description">Is this printer the default?</dd> <dt>num_options </dt> <dd class="description">Number of options</dd> <dt>options </dt> <dd class="description">Options</dd> </dl> <h3 class="struct"><a name="cups_job_s">cups_job_s</a></h3> <p class="description">Job</p> <p class="code">struct cups_job_s {<br> time_t completed_time;<br> time_t creation_time;<br> char *dest;<br> char *format;<br> int id;<br> int priority;<br> time_t processing_time;<br> int size;<br> ipp_jstate_t state;<br> char *title;<br> char *user;<br> };</p> <h4 class="members">Members</h4> <dl> <dt>completed_time </dt> <dd class="description">Time the job was completed</dd> <dt>creation_time </dt> <dd class="description">Time the job was created</dd> <dt>dest </dt> <dd class="description">Printer or class name</dd> <dt>format </dt> <dd class="description">Document format</dd> <dt>id </dt> <dd class="description">The job ID</dd> <dt>priority </dt> <dd class="description">Priority (1-100)</dd> <dt>processing_time </dt> <dd class="description">Time the job was processed</dd> <dt>size </dt> <dd class="description">Size in kilobytes</dd> <dt>state </dt> <dd class="description">Job state</dd> <dt>title </dt> <dd class="description">Title/job name</dd> <dt>user </dt> <dd class="description">User the submitted the job</dd> </dl> <h3 class="struct"><a name="cups_option_s">cups_option_s</a></h3> <p class="description">Printer Options</p> <p class="code">struct cups_option_s {<br> char *name;<br> char *value;<br> };</p> <h4 class="members">Members</h4> <dl> <dt>name </dt> <dd class="description">Name of option</dd> <dt>value </dt> <dd class="description">Value of option</dd> </dl> <h3 class="struct"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_s">cups_size_s</a></h3> <p class="description">Media Size </p> <p class="code">struct cups_size_s {<br> char media[128];<br> int width, length, bottom, left, right, top;<br> };</p> <h4 class="members">Members</h4> <dl> <dt>media[128] </dt> <dd class="description">Media name to use</dd> <dt>top </dt> <dd class="description">Top margin in hundredths of millimeters</dd> </dl> <h3 class="struct"><a name="pollfd">pollfd</a></h3> <p class="description">User data (unused)</p> <p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br> _cups_dnssd_data_t *data;<br> else if(val 0) data - got_data;<br> void) timeout;<br> int val;<br> };</p> <h4 class="members">Members</h4> <dl> <dt>data </dt> <dd class="description">Enumeration data</dd> <dt>got_data </dt> <dt>timeout </dt> <dt>val </dt> <dd class="description">Return value</dd> </dl> <h2 class="title"><a name="VARIABLES">Variables</a></h2> <h3 class="variable"><a name="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3> <p class="description">Get the Apple language identifier associated with a locale ID.</p> <p class="code">const char *locale) CF_RETURNS_RETAINED;</p> <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> <h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3> <p class="description">Printer type/capability bit constants</p> <h4 class="constants">Constants</h4> <dl> <dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Printer requires authentication </dd> <dt>CUPS_PRINTER_BIND </dt> <dd class="description">Can bind output</dd> <dt>CUPS_PRINTER_BW </dt> <dd class="description">Can do B&W printing</dd> <dt>CUPS_PRINTER_CLASS </dt> <dd class="description">Printer class</dd> <dt>CUPS_PRINTER_COLLATE </dt> <dd class="description">Can collage copies</dd> <dt>CUPS_PRINTER_COLOR </dt> <dd class="description">Can do color printing</dd> <dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Printer supports maintenance commands </dd> <dt>CUPS_PRINTER_COPIES </dt> <dd class="description">Can do copies</dd> <dt>CUPS_PRINTER_COVER </dt> <dd class="description">Can cover output</dd> <dt>CUPS_PRINTER_DEFAULT </dt> <dd class="description">Default printer on network</dd> <dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Delete printer </dd> <dt>CUPS_PRINTER_DUPLEX </dt> <dd class="description">Can do duplexing</dd> <dt>CUPS_PRINTER_FAX </dt> <dd class="description">Fax queue</dd> <dt>CUPS_PRINTER_LARGE </dt> <dd class="description">Can do D/E/A1/A0</dd> <dt>CUPS_PRINTER_LOCAL </dt> <dd class="description">Local printer or class</dd> <dt>CUPS_PRINTER_MEDIUM </dt> <dd class="description">Can do Tabloid/B/C/A3/A2</dd> <dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> <dd class="description">Printer with scanning capabilities </dd> <dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Printer is not shared </dd> <dt>CUPS_PRINTER_PUNCH </dt> <dd class="description">Can punch output</dd> <dt>CUPS_PRINTER_REJECTING </dt> <dd class="description">Printer is rejecting jobs</dd> <dt>CUPS_PRINTER_REMOTE </dt> <dd class="description">Remote printer or class</dd> <dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> <dd class="description">Scanner-only device </dd> <dt>CUPS_PRINTER_SMALL </dt> <dd class="description">Can do Letter/Legal/A4</dd> <dt>CUPS_PRINTER_SORT </dt> <dd class="description">Can sort output</dd> <dt>CUPS_PRINTER_STAPLE </dt> <dd class="description">Can staple output</dd> <dt>CUPS_PRINTER_VARIABLE </dt> <dd class="description">Can do variable sizes</dd> </dl> </div> </body> </html>