| <!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$" |
| |
| 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="#appleGetPaperSize" title="Get the default paper size.">appleGetPaperSize</a></li> |
| <li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li> |
| <li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li> |
| <li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li> |
| <li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li> |
| <li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li> |
| <li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li> |
| <li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li> |
| <li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li> |
| <li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li> |
| <li><a href="#cupsEncryption" title="Get the current encryption settings.">cupsEncryption</a></li> |
| <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li> |
| <li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li> |
| <li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li> |
| <li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li> |
| <li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li> |
| <li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li> |
| <li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li> |
| <li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li> |
| <li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li> |
| <li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li> |
| <li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li> |
| <li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li> |
| <li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li> |
| <li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li> |
| <li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li> |
| <li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li> |
| <li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified |
| server if it has changed.">cupsGetPPD3</a></li> |
| <li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li> |
| <li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced |
| 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="#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="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li> |
| <li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li> |
| <li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li> |
| <li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li> |
| <li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li> |
| </ul></li> |
| <li><a href="#TYPES">Data Types</a><ul class="code"> |
| <li><a href="#cups_client_cert_cb_t" title="Client credentials callback ">cups_client_cert_cb_t</a></li> |
| <li><a href="#cups_dest_t" title="Destination">cups_dest_t</a></li> |
| <li><a href="#cups_device_cb_t" title="Device callback ">cups_device_cb_t</a></li> |
| <li><a href="#cups_job_t" title="Job">cups_job_t</a></li> |
| <li><a href="#cups_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> |
| </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> |
| </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 introduction for CUPS. |
| |
| Copyright 2007-2011 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="appleGetPaperSize">appleGetPaperSize</a></h3> |
| <p class="description">Get the default paper size.</p> |
| <p class="code"> |
| char *appleGetPaperSize (<br> |
| char *name,<br> |
| int namesize<br> |
| );</p> |
| <h4 class="parameters">Parameters</h4> |
| <dl> |
| <dt>name</dt> |
| <dd class="description">Paper size name buffer</dd> |
| <dt>namesize</dt> |
| <dd class="description">Size of buffer</dd> |
| </dl> |
| <h4 class="returnvalue">Return Value</h4> |
| <p class="description">Default paper size</p> |
| <h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3> |
| <p class="description">Add a destination to the list of destinations.</p> |
| <p class="code"> |
| 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"> CUPS 1.2/Mac OS X 10.5 </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"> CUPS 1.2/Mac OS X 10.5 </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/Mac 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/Mac 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="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/Mac 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.4/Mac 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.4/Mac 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="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/Mac 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"><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/Mac 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/Mac 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/Mac 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/Mac OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3> |
| <p class="description">Get the PPD file for a printer from the specified server.</p> |
| <p class="code"> |
| 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/Mac 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/Mac 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/Mac 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.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3> |
| <p class="description">Return the subject for the given notification message.</p> |
| <p class="code"> |
| 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac 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/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> |
| <p class="description">Set the advanced password callback for CUPS.</p> |
| <p class="code"> |
| 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/Mac 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.4/Mac OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3> |
| <p class="description">Add a document to a job created with cupsCreateJob().</p> |
| <p class="code"> |
| 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/Mac 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/Mac 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"><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/Mac 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"><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/Mac 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/Mac 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> |
| <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> |
| <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/Mac 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/Mac 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/Mac OS X 10.5 </span></dt> |
| <dd class="description">Delete printer </dd> |
| <dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> |
| <dd class="description">Printer was automatically discovered and added </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_IMPLICIT </dt> |
| <dd class="description">Implicit class</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/Mac 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/Mac 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/Mac 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> |