]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/api-cups.html
Load cups into easysw/current.
[thirdparty/cups.git] / doc / help / api-cups.html
CommitLineData
ef416fc2 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2<html>
3<!-- SECTION: Programming -->
4<head>
5 <title>CUPS API</title>
6 <meta name='keywords' content='Programming'>
7 <meta name='creator' content='Mini-XML v2.3'>
8 <style type='text/css'><!--
9 h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
10 tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
11 pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
12 span.info { background: #000000; border: solid thin #000000; color: #ffffff; font-size: 80%; font-style: italic; font-weight: bold; white-space: nowrap; }
13 h3 span.info { float: right; font-size: 100%; }
14 h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
15 --></style>
16</head>
17<body>
18<!--
19 "$Id$"
20
21 CUPS API introduction for the Common UNIX Printing System (CUPS).
22
23 Copyright 1997-2006 by Easy Software Products.
24
25 These coded instructions, statements, and computer programs are the
26 property of Easy Software Products and are protected by Federal
27 copyright law. Distribution and use rights are outlined in the file
28 "LICENSE.txt" which should have been included with this file. If this
29 file is missing or damaged please contact Easy Software Products
30 at:
31
32 Attn: CUPS Licensing Information
33 Easy Software Products
34 44141 Airport View Drive, Suite 204
35 Hollywood, Maryland 20636 USA
36
37 Voice: (301) 373-9600
38 EMail: cups-info@cups.org
39 WWW: http://www.cups.org
40-->
41
42<h2 class='title'>Introduction</h2>
43
44<p>The CUPS APIs provide...</p>
45
46<h2 class='title'>General Usage</h2>
47
48<p>The <var>&lt;cups/cups.h&gt;</var> header file must be included to
49use the CUPS functions.</p>
50
51<p>Programs using these functions must be linked to the CUPS
52library: <var>libcups.a</var>, <var>libcups.so.2</var>,
53<var>libcups.2.dylib</var>, <var>libcups_s.a</var>, or
54<var>libcups2.lib</var> depending on the platform. The following
55command compiles <var>myprogram.c</var> using GCC and the CUPS
56library:</p>
57
58<pre class='command'>
59<kbd>gcc -o myprogram myprogram.c -lcups</kbd>
60</pre>
61
62<h2 class='title'>Compatibility</h2>
63
64<p>Unless otherwise specified, the CUPS API functions require
65CUPS 1.1 or higher.</p>
66<h2 class='title'>Contents</h2>
67<ul>
68 <li><a href='#ENUMERATIONS'>Enumerations</a></li>
69 <li><a href='#FUNCTIONS'>Functions</a></li>
70 <li><a href='#STRUCTURES'>Structures</a></li>
71 <li><a href='#TYPES'>Types</a></li>
72</ul>
73<!-- NEW PAGE -->
74<h2 class='title'><a name='ENUMERATIONS'>Enumerations</a></h2>
75<ul>
76 <li><a href='#cups_ptype_e'><tt>cups_ptype_e</tt></a> </li>
77</ul>
78<!-- NEW PAGE -->
79<h3 class='title'><a name='cups_ptype_e'>cups_ptype_e</a></h3>
80<h4>Description</h4>
81<p>Not a typedef'd enum so we can OR</p>
82<h4>Values</h4>
83<div class='table'><table align='center' border='1' width='80%'>
84<thead><tr><th>Name</th><th>Description</th></tr></thead>
85<tbody>
86<tr><td><tt>CUPS_PRINTER_AUTHENTICATED</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Printer requires authentication </td></tr>
87<tr><td><tt>CUPS_PRINTER_BIND</tt> </td><td>Can bind output</td></tr>
88<tr><td><tt>CUPS_PRINTER_BW</tt> </td><td>Can do B&amp;W printing</td></tr>
89<tr><td><tt>CUPS_PRINTER_CLASS</tt> </td><td>Printer class</td></tr>
90<tr><td><tt>CUPS_PRINTER_COLLATE</tt> </td><td>Can collage copies</td></tr>
91<tr><td><tt>CUPS_PRINTER_COLOR</tt> </td><td>Can do color printing</td></tr>
92<tr><td><tt>CUPS_PRINTER_COPIES</tt> </td><td>Can do copies</td></tr>
93<tr><td><tt>CUPS_PRINTER_COVER</tt> </td><td>Can cover output</td></tr>
94<tr><td><tt>CUPS_PRINTER_DEFAULT</tt> </td><td>Default printer on network</td></tr>
95<tr><td><tt>CUPS_PRINTER_DELETE</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Delete printer </td></tr>
96<tr><td><tt>CUPS_PRINTER_DUPLEX</tt> </td><td>Can do duplexing</td></tr>
97<tr><td><tt>CUPS_PRINTER_FAX</tt> </td><td>Fax queue</td></tr>
98<tr><td><tt>CUPS_PRINTER_IMPLICIT</tt> </td><td>Implicit class</td></tr>
99<tr><td><tt>CUPS_PRINTER_LARGE</tt> </td><td>Can do D/E/A1/A0</td></tr>
100<tr><td><tt>CUPS_PRINTER_LOCAL</tt> </td><td>Local printer or class</td></tr>
101<tr><td><tt>CUPS_PRINTER_MEDIUM</tt> </td><td>Can do Tabloid/B/C/A3/A2</td></tr>
102<tr><td><tt>CUPS_PRINTER_NOT_SHARED</tt> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></td><td>Printer is not shared </td></tr>
103<tr><td><tt>CUPS_PRINTER_OPTIONS</tt> </td><td>~(CLASS | REMOTE | IMPLICIT)</td></tr>
104<tr><td><tt>CUPS_PRINTER_PUNCH</tt> </td><td>Can punch output</td></tr>
105<tr><td><tt>CUPS_PRINTER_REJECTING</tt> </td><td>Printer is rejecting jobs</td></tr>
106<tr><td><tt>CUPS_PRINTER_REMOTE</tt> </td><td>Remote printer or class</td></tr>
107<tr><td><tt>CUPS_PRINTER_SMALL</tt> </td><td>Can do Letter/Legal/A4</td></tr>
108<tr><td><tt>CUPS_PRINTER_SORT</tt> </td><td>Can sort output</td></tr>
109<tr><td><tt>CUPS_PRINTER_STAPLE</tt> </td><td>Can staple output</td></tr>
110<tr><td><tt>CUPS_PRINTER_VARIABLE</tt> </td><td>Can do variable sizes</td></tr>
111</tbody></table></div>
112<!-- NEW PAGE -->
113<h2 class='title'><a name='FUNCTIONS'>Functions</a></h2>
114<ul>
115 <li><a href='#cupsAddDest'><tt>cupsAddDest()</tt></a> </li>
116 <li><a href='#cupsAddOption'><tt>cupsAddOption()</tt></a> </li>
117 <li><a href='#cupsCancelJob'><tt>cupsCancelJob()</tt></a> </li>
118 <li><a href='#cupsDoAuthentication'><tt>cupsDoAuthentication()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
119 <li><a href='#cupsDoFileRequest'><tt>cupsDoFileRequest()</tt></a> </li>
120 <li><a href='#cupsEncodeOptions'><tt>cupsEncodeOptions()</tt></a> </li>
121 <li><a href='#cupsEncodeOptions2'><tt>cupsEncodeOptions2()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
122 <li><a href='#cupsEncryption'><tt>cupsEncryption()</tt></a> </li>
123 <li><a href='#cupsFreeDests'><tt>cupsFreeDests()</tt></a> </li>
124 <li><a href='#cupsFreeJobs'><tt>cupsFreeJobs()</tt></a> </li>
125 <li><a href='#cupsFreeOptions'><tt>cupsFreeOptions()</tt></a> </li>
126 <li><a href='#cupsGetClasses'><tt>cupsGetClasses()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
127 <li><a href='#cupsGetDefault'><tt>cupsGetDefault()</tt></a> </li>
128 <li><a href='#cupsGetDefault2'><tt>cupsGetDefault2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
129 <li><a href='#cupsGetDest'><tt>cupsGetDest()</tt></a> </li>
130 <li><a href='#cupsGetDests'><tt>cupsGetDests()</tt></a> </li>
131 <li><a href='#cupsGetDests2'><tt>cupsGetDests2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
132 <li><a href='#cupsGetFd'><tt>cupsGetFd()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
133 <li><a href='#cupsGetFile'><tt>cupsGetFile()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
134 <li><a href='#cupsGetJobs'><tt>cupsGetJobs()</tt></a> </li>
135 <li><a href='#cupsGetJobs2'><tt>cupsGetJobs2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
136 <li><a href='#cupsGetOption'><tt>cupsGetOption()</tt></a> </li>
137 <li><a href='#cupsGetPPD'><tt>cupsGetPPD()</tt></a> </li>
138 <li><a href='#cupsGetPPD2'><tt>cupsGetPPD2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
139 <li><a href='#cupsGetPassword'><tt>cupsGetPassword()</tt></a> </li>
140 <li><a href='#cupsGetPrinters'><tt>cupsGetPrinters()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
141 <li><a href='#cupsLangDefault'><tt>cupsLangDefault()</tt></a> </li>
142 <li><a href='#cupsLangEncoding'><tt>cupsLangEncoding()</tt></a> </li>
143 <li><a href='#cupsLangFlush'><tt>cupsLangFlush()</tt></a> </li>
144 <li><a href='#cupsLangFree'><tt>cupsLangFree()</tt></a> </li>
145 <li><a href='#cupsLangGet'><tt>cupsLangGet()</tt></a> </li>
146 <li><a href='#cupsLastError'><tt>cupsLastError()</tt></a> </li>
147 <li><a href='#cupsLastErrorString'><tt>cupsLastErrorString()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
148 <li><a href='#cupsMarkOptions'><tt>cupsMarkOptions()</tt></a> </li>
149 <li><a href='#cupsParseOptions'><tt>cupsParseOptions()</tt></a> </li>
150 <li><a href='#cupsPrintFile'><tt>cupsPrintFile()</tt></a> </li>
151 <li><a href='#cupsPrintFile2'><tt>cupsPrintFile2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
152 <li><a href='#cupsPrintFiles'><tt>cupsPrintFiles()</tt></a> </li>
153 <li><a href='#cupsPrintFiles2'><tt>cupsPrintFiles2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
154 <li><a href='#cupsPutFd'><tt>cupsPutFd()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
155 <li><a href='#cupsPutFile'><tt>cupsPutFile()</tt></a> <span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span></li>
156 <li><a href='#cupsServer'><tt>cupsServer()</tt></a> </li>
157 <li><a href='#cupsSetDests'><tt>cupsSetDests()</tt></a> </li>
158 <li><a href='#cupsSetDests2'><tt>cupsSetDests2()</tt></a> <span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span></li>
159 <li><a href='#cupsSetEncryption'><tt>cupsSetEncryption()</tt></a> </li>
160 <li><a href='#cupsSetPasswordCB'><tt>cupsSetPasswordCB()</tt></a> </li>
161 <li><a href='#cupsSetServer'><tt>cupsSetServer()</tt></a> </li>
162 <li><a href='#cupsSetUser'><tt>cupsSetUser()</tt></a> </li>
163 <li><a href='#cupsTempFd'><tt>cupsTempFd()</tt></a> </li>
164 <li><a href='#cupsTempFile'><tt>cupsTempFile()</tt></a> <span class='info'>&nbsp;DEPRECATED&nbsp;</span></li>
165 <li><a href='#cupsTempFile2'><tt>cupsTempFile2()</tt></a> <span class='info'>&nbsp;CUPS 1.2&nbsp;</span></li>
166 <li><a href='#cupsUser'><tt>cupsUser()</tt></a> </li>
167</ul>
168<!-- NEW PAGE -->
169<h3 class='title'><a name='cupsAddDest'>cupsAddDest()</a></h3>
170<h4>Description</h4>
171<p>Add a destination to the list of destinations.
172
173Use the cupsSaveDests() function to save the updated list of destinations
174to the user's lpoptions file.</p>
175<h4>Syntax</h4>
176<pre>
177int
178cupsAddDest(
179 const <a href='#char'>char</a> * name,
180 const <a href='#char'>char</a> * instance,
181 int num_dests,
182 <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
183</pre>
184<h4>Arguments</h4>
185<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
186<thead><tr><th>Name</th><th>Description</th></tr></thead>
187<tbody>
188<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
189<tr><td><tt>instance</tt></td><td>Instance of destination or NULL for none/primary</td></tr>
190<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
191<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
192</tbody></table></div>
193<h4>Returns</h4>
194<p>New number of destinations</p>
195<!-- NEW PAGE -->
196<h3 class='title'><a name='cupsAddOption'>cupsAddOption()</a></h3>
197<h4>Description</h4>
198<p>Add an option to an option array.</p>
199<h4>Syntax</h4>
200<pre>
201int
202cupsAddOption(
203 const <a href='#char'>char</a> * name,
204 const <a href='#char'>char</a> * value,
205 int num_options,
206 <a href='#cups_option_t'>cups_option_t</a> ** options);
207</pre>
208<h4>Arguments</h4>
209<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
210<thead><tr><th>Name</th><th>Description</th></tr></thead>
211<tbody>
212<tr><td><tt>name</tt></td><td>Name of option</td></tr>
213<tr><td><tt>value</tt></td><td>Value of option</td></tr>
214<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
215<tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
216</tbody></table></div>
217<h4>Returns</h4>
218<p>Number of options</p>
219<!-- NEW PAGE -->
220<h3 class='title'><a name='cupsCancelJob'>cupsCancelJob()</a></h3>
221<h4>Description</h4>
222<p>Cancel a print job on the default server.
223
224Use the cupsLastError() and cupsLastErrorString() functions to get
225the cause of any failure.</p>
226<h4>Syntax</h4>
227<pre>
228int
229cupsCancelJob(
230 const <a href='#char'>char</a> * name,
231 int job);
232</pre>
233<h4>Arguments</h4>
234<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
235<thead><tr><th>Name</th><th>Description</th></tr></thead>
236<tbody>
237<tr><td><tt>name</tt></td><td>Name of printer or class</td></tr>
238<tr><td><tt>job</tt></td><td>Job ID</td></tr>
239</tbody></table></div>
240<h4>Returns</h4>
241<p>1 on success, 0 on failure</p>
242<!-- NEW PAGE -->
243<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsDoAuthentication'>cupsDoAuthentication()</a></h3>
244<h4>Description</h4>
245<p>Authenticate a request.
246
247This function should be called in response to a HTTP_UNAUTHORIZED
248status, prior to resubmitting your request.
249
250</p>
251<h4>Syntax</h4>
252<pre>
253int
254cupsDoAuthentication(
255 http_t * http,
256 const <a href='#char'>char</a> * method,
257 const <a href='#char'>char</a> * resource);
258</pre>
259<h4>Arguments</h4>
260<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
261<thead><tr><th>Name</th><th>Description</th></tr></thead>
262<tbody>
263<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
264<tr><td><tt>method</tt></td><td>Request method (GET, POST, PUT)</td></tr>
265<tr><td><tt>resource</tt></td><td>Resource path</td></tr>
266</tbody></table></div>
267<h4>Returns</h4>
268<p>0 on success, -1 on error</p>
269<!-- NEW PAGE -->
270<h3 class='title'><a name='cupsDoFileRequest'>cupsDoFileRequest()</a></h3>
271<h4>Description</h4>
272<p>Do an IPP request.
273
274This function sends any IPP request to the specified server, retrying
275and authenticating as necessary.</p>
276<h4>Syntax</h4>
277<pre>
278ipp_t *
279cupsDoFileRequest(
280 http_t * http,
281 ipp_t * request,
282 const <a href='#char'>char</a> * resource,
283 const <a href='#char'>char</a> * filename);
284</pre>
285<h4>Arguments</h4>
286<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
287<thead><tr><th>Name</th><th>Description</th></tr></thead>
288<tbody>
289<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
290<tr><td><tt>request</tt></td><td>IPP request</td></tr>
291<tr><td><tt>resource</tt></td><td>HTTP resource for POST</td></tr>
292<tr><td><tt>filename</tt></td><td>File to send or NULL for none</td></tr>
293</tbody></table></div>
294<h4>Returns</h4>
295<p>Response data</p>
296<!-- NEW PAGE -->
297<h3 class='title'><a name='cupsEncodeOptions'>cupsEncodeOptions()</a></h3>
298<h4>Description</h4>
299<p>Encode printer options into IPP attributes.
300
301This function adds operation, job, and then subscription attributes,
302in that order. Use the cupsEncodeOptions2() function to add attributes
303for a single group.</p>
304<h4>Syntax</h4>
305<pre>
306void
307cupsEncodeOptions(
308 ipp_t * ipp,
309 int num_options,
310 <a href='#cups_option_t'>cups_option_t</a> * options);
311</pre>
312<h4>Arguments</h4>
313<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
314<thead><tr><th>Name</th><th>Description</th></tr></thead>
315<tbody>
316<tr><td><tt>ipp</tt></td><td>Request to add to</td></tr>
317<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
318<tr><td><tt>options</tt></td><td>Options</td></tr>
319</tbody></table></div>
320<h4>Returns</h4>
321<p>Nothing.</p>
322<!-- NEW PAGE -->
323<h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsEncodeOptions2'>cupsEncodeOptions2()</a></h3>
324<h4>Description</h4>
325<p>Encode printer options into IPP attributes for a group.
326
327This function only adds attributes for a single group. Call this
328function multiple times for each group, or use cupsEncodeOptions()
329to add the standard groups.
330
331</p>
332<h4>Syntax</h4>
333<pre>
334void
335cupsEncodeOptions2(
336 ipp_t * ipp,
337 int num_options,
338 <a href='#cups_option_t'>cups_option_t</a> * options,
339 ipp_tag_t group_tag);
340</pre>
341<h4>Arguments</h4>
342<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
343<thead><tr><th>Name</th><th>Description</th></tr></thead>
344<tbody>
345<tr><td><tt>ipp</tt></td><td>Request to add to</td></tr>
346<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
347<tr><td><tt>options</tt></td><td>Options</td></tr>
348<tr><td><tt>group_tag</tt></td><td>Group to encode</td></tr>
349</tbody></table></div>
350<h4>Returns</h4>
351<p>Nothing.</p>
352<!-- NEW PAGE -->
353<h3 class='title'><a name='cupsEncryption'>cupsEncryption()</a></h3>
354<h4>Description</h4>
355<p>Get the default encryption settings.
356
357The default encryption setting comes from the CUPS_ENCRYPTION
358environment variable, then the ~/.cupsrc file, and finally the
359/etc/cups/client.conf file. If not set, the default is
360HTTP_ENCRYPT_IF_REQUESTED.</p>
361<h4>Syntax</h4>
362<pre>
363http_encryption_t
364cupsEncryption(void);
365</pre>
366<h4>Arguments</h4>
367<p>None.</p>
368<h4>Returns</h4>
369<p>Encryption settings</p>
370<!-- NEW PAGE -->
371<h3 class='title'><a name='cupsFreeDests'>cupsFreeDests()</a></h3>
372<h4>Description</h4>
373<p>Free the memory used by the list of destinations.</p>
374<h4>Syntax</h4>
375<pre>
376void
377cupsFreeDests(
378 int num_dests,
379 <a href='#cups_dest_t'>cups_dest_t</a> * dests);
380</pre>
381<h4>Arguments</h4>
382<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
383<thead><tr><th>Name</th><th>Description</th></tr></thead>
384<tbody>
385<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
386<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
387</tbody></table></div>
388<h4>Returns</h4>
389<p>Nothing.</p>
390<!-- NEW PAGE -->
391<h3 class='title'><a name='cupsFreeJobs'>cupsFreeJobs()</a></h3>
392<h4>Description</h4>
393<p>Free memory used by job data.</p>
394<h4>Syntax</h4>
395<pre>
396void
397cupsFreeJobs(
398 int num_jobs,
399 <a href='#cups_job_t'>cups_job_t</a> * jobs);
400</pre>
401<h4>Arguments</h4>
402<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
403<thead><tr><th>Name</th><th>Description</th></tr></thead>
404<tbody>
405<tr><td><tt>num_jobs</tt></td><td>Number of jobs</td></tr>
406<tr><td><tt>jobs</tt></td><td>Jobs</td></tr>
407</tbody></table></div>
408<h4>Returns</h4>
409<p>Nothing.</p>
410<!-- NEW PAGE -->
411<h3 class='title'><a name='cupsFreeOptions'>cupsFreeOptions()</a></h3>
412<h4>Description</h4>
413<p>Free all memory used by options.</p>
414<h4>Syntax</h4>
415<pre>
416void
417cupsFreeOptions(
418 int num_options,
419 <a href='#cups_option_t'>cups_option_t</a> * options);
420</pre>
421<h4>Arguments</h4>
422<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
423<thead><tr><th>Name</th><th>Description</th></tr></thead>
424<tbody>
425<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
426<tr><td><tt>options</tt></td><td>Pointer to options</td></tr>
427</tbody></table></div>
428<h4>Returns</h4>
429<p>Nothing.</p>
430<!-- NEW PAGE -->
431<h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsGetClasses'>cupsGetClasses()</a></h3>
432<h4>Description</h4>
433<p>Get a list of printer classes from the default server.
434
435This function is deprecated - use cupsGetDests() instead.
436
437</p>
438<h4>Syntax</h4>
439<pre>
440int
441cupsGetClasses(
442 <a href='#char'>char</a> *** classes);
443</pre>
444<h4>Arguments</h4>
445<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
446<thead><tr><th>Name</th><th>Description</th></tr></thead>
447<tbody>
448<tr><td><tt>classes</tt></td><td>Classes</td></tr>
449</tbody></table></div>
450<h4>Returns</h4>
451<p>Number of classes</p>
452<!-- NEW PAGE -->
453<h3 class='title'><a name='cupsGetDefault'>cupsGetDefault()</a></h3>
454<h4>Description</h4>
455<p>Get the default printer or class for the default server.
456
457This function returns the default printer or class as defined by
458the LPDEST or PRINTER environment variables. If these environment
459variables are not set, the server default destination is returned.
460Applications should use the cupsGetDests() and cupsGetDest() functions
461to get the user-defined default printer, as this function does not
462support the lpoptions-defined default printer.</p>
463<h4>Syntax</h4>
464<pre>
465const <a href='#char'>char</a> *
466cupsGetDefault(void);
467</pre>
468<h4>Arguments</h4>
469<p>None.</p>
470<h4>Returns</h4>
471<p>Default printer or NULL</p>
472<!-- NEW PAGE -->
473<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetDefault2'>cupsGetDefault2()</a></h3>
474<h4>Description</h4>
475<p>Get the default printer or class for the specified server.
476
477This function returns the default printer or class as defined by
478the LPDEST or PRINTER environment variables. If these environment
479variables are not set, the server default destination is returned.
480Applications should use the cupsGetDests() and cupsGetDest() functions
481to get the user-defined default printer, as this function does not
482support the lpoptions-defined default printer.
483
484</p>
485<h4>Syntax</h4>
486<pre>
487const <a href='#char'>char</a> *
488cupsGetDefault2(
489 http_t * http);
490</pre>
491<h4>Arguments</h4>
492<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
493<thead><tr><th>Name</th><th>Description</th></tr></thead>
494<tbody>
495<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
496</tbody></table></div>
497<h4>Returns</h4>
498<p>Default printer or NULL</p>
499<!-- NEW PAGE -->
500<h3 class='title'><a name='cupsGetDest'>cupsGetDest()</a></h3>
501<h4>Description</h4>
502<p>Get the named destination from the list.
503
504Use the cupsGetDests() or cupsGetDests2() functions to get a
505list of supported destinations for the current user.</p>
506<h4>Syntax</h4>
507<pre>
508<a href='#cups_dest_t'>cups_dest_t</a> *
509cupsGetDest(
510 const <a href='#char'>char</a> * name,
511 const <a href='#char'>char</a> * instance,
512 int num_dests,
513 <a href='#cups_dest_t'>cups_dest_t</a> * dests);
514</pre>
515<h4>Arguments</h4>
516<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
517<thead><tr><th>Name</th><th>Description</th></tr></thead>
518<tbody>
519<tr><td><tt>name</tt></td><td>Name of destination</td></tr>
520<tr><td><tt>instance</tt></td><td>Instance of destination</td></tr>
521<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
522<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
523</tbody></table></div>
524<h4>Returns</h4>
525<p>Destination pointer or NULL</p>
526<!-- NEW PAGE -->
527<h3 class='title'><a name='cupsGetDests'>cupsGetDests()</a></h3>
528<h4>Description</h4>
529<p>Get the list of destinations from the default server.</p>
530<h4>Syntax</h4>
531<pre>
532int
533cupsGetDests(
534 <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
535</pre>
536<h4>Arguments</h4>
537<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
538<thead><tr><th>Name</th><th>Description</th></tr></thead>
539<tbody>
540<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
541</tbody></table></div>
542<h4>Returns</h4>
543<p>Number of destinations</p>
544<!-- NEW PAGE -->
545<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetDests2'>cupsGetDests2()</a></h3>
546<h4>Description</h4>
547<p>Get the list of destinations from the specified server.
548
549</p>
550<h4>Syntax</h4>
551<pre>
552int
553cupsGetDests2(
554 http_t * http,
555 <a href='#cups_dest_t'>cups_dest_t</a> ** dests);
556</pre>
557<h4>Arguments</h4>
558<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
559<thead><tr><th>Name</th><th>Description</th></tr></thead>
560<tbody>
561<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
562<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
563</tbody></table></div>
564<h4>Returns</h4>
565<p>Number of destinations</p>
566<!-- NEW PAGE -->
567<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsGetFd'>cupsGetFd()</a></h3>
568<h4>Description</h4>
569<p>Get a file from the server.
570
571This function returns HTTP_OK when the file is successfully retrieved.
572
573</p>
574<h4>Syntax</h4>
575<pre>
576http_status_t
577cupsGetFd(
578 http_t * http,
579 const <a href='#char'>char</a> * resource,
580 int fd);
581</pre>
582<h4>Arguments</h4>
583<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
584<thead><tr><th>Name</th><th>Description</th></tr></thead>
585<tbody>
586<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
587<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
588<tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
589</tbody></table></div>
590<h4>Returns</h4>
591<p>Status</p>
592<!-- NEW PAGE -->
593<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsGetFile'>cupsGetFile()</a></h3>
594<h4>Description</h4>
595<p>Get a file from the server.
596
597This function returns HTTP_OK when the file is successfully retrieved.
598
599</p>
600<h4>Syntax</h4>
601<pre>
602http_status_t
603cupsGetFile(
604 http_t * http,
605 const <a href='#char'>char</a> * resource,
606 const <a href='#char'>char</a> * filename);
607</pre>
608<h4>Arguments</h4>
609<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
610<thead><tr><th>Name</th><th>Description</th></tr></thead>
611<tbody>
612<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
613<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
614<tr><td><tt>filename</tt></td><td>Filename</td></tr>
615</tbody></table></div>
616<h4>Returns</h4>
617<p>Status</p>
618<!-- NEW PAGE -->
619<h3 class='title'><a name='cupsGetJobs'>cupsGetJobs()</a></h3>
620<h4>Description</h4>
621<p>Get the jobs from the default server.</p>
622<h4>Syntax</h4>
623<pre>
624int
625cupsGetJobs(
626 <a href='#cups_job_t'>cups_job_t</a> ** jobs,
627 const <a href='#char'>char</a> * mydest,
628 int myjobs,
629 int completed);
630</pre>
631<h4>Arguments</h4>
632<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
633<thead><tr><th>Name</th><th>Description</th></tr></thead>
634<tbody>
635<tr><td><tt>jobs</tt></td><td>Job data</td></tr>
636<tr><td><tt>mydest</tt></td><td>Only show jobs for dest?</td></tr>
637<tr><td><tt>myjobs</tt></td><td>Only show my jobs?</td></tr>
638<tr><td><tt>completed</tt></td><td>Only show completed jobs?</td></tr>
639</tbody></table></div>
640<h4>Returns</h4>
641<p>Number of jobs</p>
642<!-- NEW PAGE -->
643<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetJobs2'>cupsGetJobs2()</a></h3>
644<h4>Description</h4>
645<p>Get the jobs from the specified server.
646
647</p>
648<h4>Syntax</h4>
649<pre>
650int
651cupsGetJobs2(
652 http_t * http,
653 <a href='#cups_job_t'>cups_job_t</a> ** jobs,
654 const <a href='#char'>char</a> * mydest,
655 int myjobs,
656 int completed);
657</pre>
658<h4>Arguments</h4>
659<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
660<thead><tr><th>Name</th><th>Description</th></tr></thead>
661<tbody>
662<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
663<tr><td><tt>jobs</tt></td><td>Job data</td></tr>
664<tr><td><tt>mydest</tt></td><td>Only show jobs for dest?</td></tr>
665<tr><td><tt>myjobs</tt></td><td>Only show my jobs?</td></tr>
666<tr><td><tt>completed</tt></td><td>Only show completed jobs?</td></tr>
667</tbody></table></div>
668<h4>Returns</h4>
669<p>Number of jobs</p>
670<!-- NEW PAGE -->
671<h3 class='title'><a name='cupsGetOption'>cupsGetOption()</a></h3>
672<h4>Description</h4>
673<p>Get an option value.</p>
674<h4>Syntax</h4>
675<pre>
676const <a href='#char'>char</a> *
677cupsGetOption(
678 const <a href='#char'>char</a> * name,
679 int num_options,
680 <a href='#cups_option_t'>cups_option_t</a> * options);
681</pre>
682<h4>Arguments</h4>
683<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
684<thead><tr><th>Name</th><th>Description</th></tr></thead>
685<tbody>
686<tr><td><tt>name</tt></td><td>Name of option</td></tr>
687<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
688<tr><td><tt>options</tt></td><td>Options</td></tr>
689</tbody></table></div>
690<h4>Returns</h4>
691<p>Option value or NULL</p>
692<!-- NEW PAGE -->
693<h3 class='title'><a name='cupsGetPPD'>cupsGetPPD()</a></h3>
694<h4>Description</h4>
695<p>Get the PPD file for a printer on the default server.
696
697For classes, cupsGetPPD() returns the PPD file for the first printer
698in the class.</p>
699<h4>Syntax</h4>
700<pre>
701const <a href='#char'>char</a> *
702cupsGetPPD(
703 const <a href='#char'>char</a> * name);
704</pre>
705<h4>Arguments</h4>
706<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
707<thead><tr><th>Name</th><th>Description</th></tr></thead>
708<tbody>
709<tr><td><tt>name</tt></td><td>Printer name</td></tr>
710</tbody></table></div>
711<h4>Returns</h4>
712<p>Filename for PPD file</p>
713<!-- NEW PAGE -->
714<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsGetPPD2'>cupsGetPPD2()</a></h3>
715<h4>Description</h4>
716<p>Get the PPD file for a printer from the specified server.
717
718For classes, cupsGetPPD2() returns the PPD file for the first printer
719in the class.
720
721</p>
722<h4>Syntax</h4>
723<pre>
724const <a href='#char'>char</a> *
725cupsGetPPD2(
726 http_t * http,
727 const <a href='#char'>char</a> * name);
728</pre>
729<h4>Arguments</h4>
730<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
731<thead><tr><th>Name</th><th>Description</th></tr></thead>
732<tbody>
733<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
734<tr><td><tt>name</tt></td><td>Printer name</td></tr>
735</tbody></table></div>
736<h4>Returns</h4>
737<p>Filename for PPD file</p>
738<!-- NEW PAGE -->
739<h3 class='title'><a name='cupsGetPassword'>cupsGetPassword()</a></h3>
740<h4>Description</h4>
741<p>Get a password from the user.
742
743Returns NULL if the user does not provide a password.</p>
744<h4>Syntax</h4>
745<pre>
746const <a href='#char'>char</a> *
747cupsGetPassword(
748 const <a href='#char'>char</a> * prompt);
749</pre>
750<h4>Arguments</h4>
751<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
752<thead><tr><th>Name</th><th>Description</th></tr></thead>
753<tbody>
754<tr><td><tt>prompt</tt></td><td>Prompt string</td></tr>
755</tbody></table></div>
756<h4>Returns</h4>
757<p>Password</p>
758<!-- NEW PAGE -->
759<h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsGetPrinters'>cupsGetPrinters()</a></h3>
760<h4>Description</h4>
761<p>Get a list of printers from the default server.
762
763This function is deprecated - use cupsGetDests() instead.
764
765</p>
766<h4>Syntax</h4>
767<pre>
768int
769cupsGetPrinters(
770 <a href='#char'>char</a> *** printers);
771</pre>
772<h4>Arguments</h4>
773<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
774<thead><tr><th>Name</th><th>Description</th></tr></thead>
775<tbody>
776<tr><td><tt>printers</tt></td><td>Printers</td></tr>
777</tbody></table></div>
778<h4>Returns</h4>
779<p>Number of printers</p>
780<!-- NEW PAGE -->
781<h3 class='title'><a name='cupsLangDefault'>cupsLangDefault()</a></h3>
782<h4>Description</h4>
783<p>Return the default language.</p>
784<h4>Syntax</h4>
785<pre>
786cups_lang_t *
787cupsLangDefault(void);
788</pre>
789<h4>Arguments</h4>
790<p>None.</p>
791<h4>Returns</h4>
792<p>Language data</p>
793<!-- NEW PAGE -->
794<h3 class='title'><a name='cupsLangEncoding'>cupsLangEncoding()</a></h3>
795<h4>Description</h4>
796<p>Return the character encoding (us-ascii, etc.)
797for the given language.</p>
798<h4>Syntax</h4>
799<pre>
800const <a href='#char'>char</a> *
801cupsLangEncoding(
802 cups_lang_t * lang);
803</pre>
804<h4>Arguments</h4>
805<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
806<thead><tr><th>Name</th><th>Description</th></tr></thead>
807<tbody>
808<tr><td><tt>lang</tt></td><td>Language data</td></tr>
809</tbody></table></div>
810<h4>Returns</h4>
811<p>Character encoding</p>
812<!-- NEW PAGE -->
813<h3 class='title'><a name='cupsLangFlush'>cupsLangFlush()</a></h3>
814<h4>Description</h4>
815<p>Flush all language data out of the cache.</p>
816<h4>Syntax</h4>
817<pre>
818void
819cupsLangFlush(void);
820</pre>
821<h4>Arguments</h4>
822<p>None.</p>
823<h4>Returns</h4>
824<p>Nothing.</p>
825<!-- NEW PAGE -->
826<h3 class='title'><a name='cupsLangFree'>cupsLangFree()</a></h3>
827<h4>Description</h4>
828<p>Free language data.
829
830This does not actually free anything; use cupsLangFlush() for that.</p>
831<h4>Syntax</h4>
832<pre>
833void
834cupsLangFree(
835 cups_lang_t * lang);
836</pre>
837<h4>Arguments</h4>
838<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
839<thead><tr><th>Name</th><th>Description</th></tr></thead>
840<tbody>
841<tr><td><tt>lang</tt></td><td>Language to free</td></tr>
842</tbody></table></div>
843<h4>Returns</h4>
844<p>Nothing.</p>
845<!-- NEW PAGE -->
846<h3 class='title'><a name='cupsLangGet'>cupsLangGet()</a></h3>
847<h4>Description</h4>
848<p>Get a language.</p>
849<h4>Syntax</h4>
850<pre>
851cups_lang_t *
852cupsLangGet(
853 const <a href='#char'>char</a> * language);
854</pre>
855<h4>Arguments</h4>
856<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
857<thead><tr><th>Name</th><th>Description</th></tr></thead>
858<tbody>
859<tr><td><tt>language</tt></td><td>Language or locale</td></tr>
860</tbody></table></div>
861<h4>Returns</h4>
862<p>Language data</p>
863<!-- NEW PAGE -->
864<h3 class='title'><a name='cupsLastError'>cupsLastError()</a></h3>
865<h4>Description</h4>
866<p>Return the last IPP status code.</p>
867<h4>Syntax</h4>
868<pre>
869ipp_status_t
870cupsLastError(void);
871</pre>
872<h4>Arguments</h4>
873<p>None.</p>
874<h4>Returns</h4>
875<p>IPP status code from last request</p>
876<!-- NEW PAGE -->
877<h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsLastErrorString'>cupsLastErrorString()</a></h3>
878<h4>Description</h4>
879<p>Return the last IPP status-message.
880
881</p>
882<h4>Syntax</h4>
883<pre>
884const <a href='#char'>char</a> *
885cupsLastErrorString(void);
886</pre>
887<h4>Arguments</h4>
888<p>None.</p>
889<h4>Returns</h4>
890<p>status-message text from last request</p>
891<!-- NEW PAGE -->
892<h3 class='title'><a name='cupsMarkOptions'>cupsMarkOptions()</a></h3>
893<h4>Description</h4>
894<p>Mark command-line options in a PPD file.</p>
895<h4>Syntax</h4>
896<pre>
897int
898cupsMarkOptions(
899 ppd_file_t * ppd,
900 int num_options,
901 <a href='#cups_option_t'>cups_option_t</a> * options);
902</pre>
903<h4>Arguments</h4>
904<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
905<thead><tr><th>Name</th><th>Description</th></tr></thead>
906<tbody>
907<tr><td><tt>ppd</tt></td><td>PPD file</td></tr>
908<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
909<tr><td><tt>options</tt></td><td>Options</td></tr>
910</tbody></table></div>
911<h4>Returns</h4>
912<p>1 if conflicting</p>
913<!-- NEW PAGE -->
914<h3 class='title'><a name='cupsParseOptions'>cupsParseOptions()</a></h3>
915<h4>Description</h4>
916<p>Parse options from a command-line argument.
917
918This function converts space-delimited name/value pairs according
919to the PAPI text option ABNF specification. Collection values
920(&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
921intact - use cupsParseOptions() on the value to extract the collection
922attributes.</p>
923<h4>Syntax</h4>
924<pre>
925int
926cupsParseOptions(
927 const <a href='#char'>char</a> * arg,
928 int num_options,
929 <a href='#cups_option_t'>cups_option_t</a> ** options);
930</pre>
931<h4>Arguments</h4>
932<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
933<thead><tr><th>Name</th><th>Description</th></tr></thead>
934<tbody>
935<tr><td><tt>arg</tt></td><td>Argument to parse</td></tr>
936<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
937<tr><td><tt>options</tt></td><td>Options found</td></tr>
938</tbody></table></div>
939<h4>Returns</h4>
940<p>Number of options found</p>
941<!-- NEW PAGE -->
942<h3 class='title'><a name='cupsPrintFile'>cupsPrintFile()</a></h3>
943<h4>Description</h4>
944<p>Print a file to a printer or class on the default server.</p>
945<h4>Syntax</h4>
946<pre>
947int
948cupsPrintFile(
949 const <a href='#char'>char</a> * name,
950 const <a href='#char'>char</a> * filename,
951 const <a href='#char'>char</a> * title,
952 int num_options,
953 <a href='#cups_option_t'>cups_option_t</a> * options);
954</pre>
955<h4>Arguments</h4>
956<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
957<thead><tr><th>Name</th><th>Description</th></tr></thead>
958<tbody>
959<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
960<tr><td><tt>filename</tt></td><td>File to print</td></tr>
961<tr><td><tt>title</tt></td><td>Title of job</td></tr>
962<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
963<tr><td><tt>options</tt></td><td>Options</td></tr>
964</tbody></table></div>
965<h4>Returns</h4>
966<p>Job ID</p>
967<!-- NEW PAGE -->
968<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsPrintFile2'>cupsPrintFile2()</a></h3>
969<h4>Description</h4>
970<p>Print a file to a printer or class on the specified server.
971
972</p>
973<h4>Syntax</h4>
974<pre>
975int
976cupsPrintFile2(
977 http_t * http,
978 const <a href='#char'>char</a> * name,
979 const <a href='#char'>char</a> * filename,
980 const <a href='#char'>char</a> * title,
981 int num_options,
982 <a href='#cups_option_t'>cups_option_t</a> * options);
983</pre>
984<h4>Arguments</h4>
985<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
986<thead><tr><th>Name</th><th>Description</th></tr></thead>
987<tbody>
988<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
989<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
990<tr><td><tt>filename</tt></td><td>File to print</td></tr>
991<tr><td><tt>title</tt></td><td>Title of job</td></tr>
992<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
993<tr><td><tt>options</tt></td><td>Options</td></tr>
994</tbody></table></div>
995<h4>Returns</h4>
996<p>Job ID</p>
997<!-- NEW PAGE -->
998<h3 class='title'><a name='cupsPrintFiles'>cupsPrintFiles()</a></h3>
999<h4>Description</h4>
1000<p>Print one or more files to a printer or class on the default server.</p>
1001<h4>Syntax</h4>
1002<pre>
1003int
1004cupsPrintFiles(
1005 const <a href='#char'>char</a> * name,
1006 int num_files,
1007 const <a href='#char'>char</a> ** files,
1008 const <a href='#char'>char</a> * title,
1009 int num_options,
1010 <a href='#cups_option_t'>cups_option_t</a> * options);
1011</pre>
1012<h4>Arguments</h4>
1013<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1014<thead><tr><th>Name</th><th>Description</th></tr></thead>
1015<tbody>
1016<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
1017<tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
1018<tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
1019<tr><td><tt>title</tt></td><td>Title of job</td></tr>
1020<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
1021<tr><td><tt>options</tt></td><td>Options</td></tr>
1022</tbody></table></div>
1023<h4>Returns</h4>
1024<p>Job ID</p>
1025<!-- NEW PAGE -->
1026<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsPrintFiles2'>cupsPrintFiles2()</a></h3>
1027<h4>Description</h4>
1028<p>Print one or more files to a printer or class on the specified server.
1029
1030</p>
1031<h4>Syntax</h4>
1032<pre>
1033int
1034cupsPrintFiles2(
1035 http_t * http,
1036 const <a href='#char'>char</a> * name,
1037 int num_files,
1038 const <a href='#char'>char</a> ** files,
1039 const <a href='#char'>char</a> * title,
1040 int num_options,
1041 <a href='#cups_option_t'>cups_option_t</a> * options);
1042</pre>
1043<h4>Arguments</h4>
1044<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1045<thead><tr><th>Name</th><th>Description</th></tr></thead>
1046<tbody>
1047<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
1048<tr><td><tt>name</tt></td><td>Printer or class name</td></tr>
1049<tr><td><tt>num_files</tt></td><td>Number of files</td></tr>
1050<tr><td><tt>files</tt></td><td>File(s) to print</td></tr>
1051<tr><td><tt>title</tt></td><td>Title of job</td></tr>
1052<tr><td><tt>num_options</tt></td><td>Number of options</td></tr>
1053<tr><td><tt>options</tt></td><td>Options</td></tr>
1054</tbody></table></div>
1055<h4>Returns</h4>
1056<p>Job ID</p>
1057<!-- NEW PAGE -->
1058<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsPutFd'>cupsPutFd()</a></h3>
1059<h4>Description</h4>
1060<p>Put a file on the server.
1061
1062This function returns HTTP_CREATED when the file is stored successfully.
1063
1064</p>
1065<h4>Syntax</h4>
1066<pre>
1067http_status_t
1068cupsPutFd(
1069 http_t * http,
1070 const <a href='#char'>char</a> * resource,
1071 int fd);
1072</pre>
1073<h4>Arguments</h4>
1074<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1075<thead><tr><th>Name</th><th>Description</th></tr></thead>
1076<tbody>
1077<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
1078<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
1079<tr><td><tt>fd</tt></td><td>File descriptor</td></tr>
1080</tbody></table></div>
1081<h4>Returns</h4>
1082<p>Status</p>
1083<!-- NEW PAGE -->
1084<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.20&nbsp;</span><a name='cupsPutFile'>cupsPutFile()</a></h3>
1085<h4>Description</h4>
1086<p>Put a file on the server.
1087
1088This function returns HTTP_CREATED when the file is stored successfully.
1089
1090</p>
1091<h4>Syntax</h4>
1092<pre>
1093http_status_t
1094cupsPutFile(
1095 http_t * http,
1096 const <a href='#char'>char</a> * resource,
1097 const <a href='#char'>char</a> * filename);
1098</pre>
1099<h4>Arguments</h4>
1100<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1101<thead><tr><th>Name</th><th>Description</th></tr></thead>
1102<tbody>
1103<tr><td><tt>http</tt></td><td>HTTP connection to server</td></tr>
1104<tr><td><tt>resource</tt></td><td>Resource name</td></tr>
1105<tr><td><tt>filename</tt></td><td>Filename</td></tr>
1106</tbody></table></div>
1107<h4>Returns</h4>
1108<p>Status</p>
1109<!-- NEW PAGE -->
1110<h3 class='title'><a name='cupsServer'>cupsServer()</a></h3>
1111<h4>Description</h4>
1112<p>Return the hostname/address of the default server.
1113
1114The returned value can be a fully-qualified hostname, a numeric
1115IPv4 or IPv6 address, or a domain socket pathname.</p>
1116<h4>Syntax</h4>
1117<pre>
1118const <a href='#char'>char</a> *
1119cupsServer(void);
1120</pre>
1121<h4>Arguments</h4>
1122<p>None.</p>
1123<h4>Returns</h4>
1124<p>Server name</p>
1125<!-- NEW PAGE -->
1126<h3 class='title'><a name='cupsSetDests'>cupsSetDests()</a></h3>
1127<h4>Description</h4>
1128<p>Save the list of destinations for the default server.
1129
1130This function saves the destinations to /etc/cups/lpoptions when run
1131as root and ~/.lpoptions when run as a normal user.</p>
1132<h4>Syntax</h4>
1133<pre>
1134void
1135cupsSetDests(
1136 int num_dests,
1137 <a href='#cups_dest_t'>cups_dest_t</a> * dests);
1138</pre>
1139<h4>Arguments</h4>
1140<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1141<thead><tr><th>Name</th><th>Description</th></tr></thead>
1142<tbody>
1143<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
1144<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
1145</tbody></table></div>
1146<h4>Returns</h4>
1147<p>Nothing.</p>
1148<!-- NEW PAGE -->
1149<h3 class='title'><span class='info'>&nbsp;CUPS 1.1.21&nbsp;</span><a name='cupsSetDests2'>cupsSetDests2()</a></h3>
1150<h4>Description</h4>
1151<p>Save the list of destinations for the specified server.
1152
1153This function saves the destinations to /etc/cups/lpoptions when run
1154as root and ~/.lpoptions when run as a normal user.
1155
1156</p>
1157<h4>Syntax</h4>
1158<pre>
1159int
1160cupsSetDests2(
1161 http_t * http,
1162 int num_dests,
1163 <a href='#cups_dest_t'>cups_dest_t</a> * dests);
1164</pre>
1165<h4>Arguments</h4>
1166<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1167<thead><tr><th>Name</th><th>Description</th></tr></thead>
1168<tbody>
1169<tr><td><tt>http</tt></td><td>HTTP connection</td></tr>
1170<tr><td><tt>num_dests</tt></td><td>Number of destinations</td></tr>
1171<tr><td><tt>dests</tt></td><td>Destinations</td></tr>
1172</tbody></table></div>
1173<h4>Returns</h4>
1174<p>0 on success, -1 on error</p>
1175<!-- NEW PAGE -->
1176<h3 class='title'><a name='cupsSetEncryption'>cupsSetEncryption()</a></h3>
1177<h4>Description</h4>
1178<p>Set the encryption preference.</p>
1179<h4>Syntax</h4>
1180<pre>
1181void
1182cupsSetEncryption(
1183 http_encryption_t e);
1184</pre>
1185<h4>Arguments</h4>
1186<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1187<thead><tr><th>Name</th><th>Description</th></tr></thead>
1188<tbody>
1189<tr><td><tt>e</tt></td><td>New encryption preference</td></tr>
1190</tbody></table></div>
1191<h4>Returns</h4>
1192<p>Nothing.</p>
1193<!-- NEW PAGE -->
1194<h3 class='title'><a name='cupsSetPasswordCB'>cupsSetPasswordCB()</a></h3>
1195<h4>Description</h4>
1196<p>Set the password callback for CUPS.
1197
1198Pass NULL to restore the default (console) password callback.</p>
1199<h4>Syntax</h4>
1200<pre>
1201void
1202cupsSetPasswordCB(
1203 cups_password_cb_t cb);
1204</pre>
1205<h4>Arguments</h4>
1206<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1207<thead><tr><th>Name</th><th>Description</th></tr></thead>
1208<tbody>
1209<tr><td><tt>cb</tt></td><td>Callback function</td></tr>
1210</tbody></table></div>
1211<h4>Returns</h4>
1212<p>Nothing.</p>
1213<!-- NEW PAGE -->
1214<h3 class='title'><a name='cupsSetServer'>cupsSetServer()</a></h3>
1215<h4>Description</h4>
1216<p>Set the default server name.
1217
1218The &quot;server&quot; string can be a fully-qualified hostname, a numeric
1219IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
1220restore the default server name.</p>
1221<h4>Syntax</h4>
1222<pre>
1223void
1224cupsSetServer(
1225 const <a href='#char'>char</a> * server);
1226</pre>
1227<h4>Arguments</h4>
1228<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1229<thead><tr><th>Name</th><th>Description</th></tr></thead>
1230<tbody>
1231<tr><td><tt>server</tt></td><td>Server name</td></tr>
1232</tbody></table></div>
1233<h4>Returns</h4>
1234<p>Nothing.</p>
1235<!-- NEW PAGE -->
1236<h3 class='title'><a name='cupsSetUser'>cupsSetUser()</a></h3>
1237<h4>Description</h4>
1238<p>Set the default user name.
1239
1240Pass NULL to restore the default user name.</p>
1241<h4>Syntax</h4>
1242<pre>
1243void
1244cupsSetUser(
1245 const <a href='#char'>char</a> * user);
1246</pre>
1247<h4>Arguments</h4>
1248<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1249<thead><tr><th>Name</th><th>Description</th></tr></thead>
1250<tbody>
1251<tr><td><tt>user</tt></td><td>User name</td></tr>
1252</tbody></table></div>
1253<h4>Returns</h4>
1254<p>Nothing.</p>
1255<!-- NEW PAGE -->
1256<h3 class='title'><a name='cupsTempFd'>cupsTempFd()</a></h3>
1257<h4>Description</h4>
1258<p>Create a temporary file.
1259
1260The temporary filename is stored in the filename buffer.</p>
1261<h4>Syntax</h4>
1262<pre>
1263int
1264cupsTempFd(
1265 <a href='#char'>char</a> * filename,
1266 int len);
1267</pre>
1268<h4>Arguments</h4>
1269<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1270<thead><tr><th>Name</th><th>Description</th></tr></thead>
1271<tbody>
1272<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1273<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1274</tbody></table></div>
1275<h4>Returns</h4>
1276<p>New file descriptor</p>
1277<!-- NEW PAGE -->
1278<h3 class='title'><span class='info'>&nbsp;DEPRECATED&nbsp;</span><a name='cupsTempFile'>cupsTempFile()</a></h3>
1279<h4>Description</h4>
1280<p>Generate a temporary filename.
1281
1282The temporary filename is stored in the filename buffer.
1283This function is deprecated - use cupsTempFd() or cupsTempFile2()
1284instead.
1285
1286</p>
1287<h4>Syntax</h4>
1288<pre>
1289<a href='#char'>char</a> *
1290cupsTempFile(
1291 <a href='#char'>char</a> * filename,
1292 int len);
1293</pre>
1294<h4>Arguments</h4>
1295<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1296<thead><tr><th>Name</th><th>Description</th></tr></thead>
1297<tbody>
1298<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1299<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1300</tbody></table></div>
1301<h4>Returns</h4>
1302<p>Filename</p>
1303<!-- NEW PAGE -->
1304<h3 class='title'><span class='info'>&nbsp;CUPS 1.2&nbsp;</span><a name='cupsTempFile2'>cupsTempFile2()</a></h3>
1305<h4>Description</h4>
1306<p>Create a temporary CUPS file.
1307
1308The temporary filename is stored in the filename buffer.
1309
1310</p>
1311<h4>Syntax</h4>
1312<pre>
1313cups_file_t *
1314cupsTempFile2(
1315 <a href='#char'>char</a> * filename,
1316 int len);
1317</pre>
1318<h4>Arguments</h4>
1319<div class='table'><table align='center' border='1' width='80%' cellpadding='5' cellspacing='0'>
1320<thead><tr><th>Name</th><th>Description</th></tr></thead>
1321<tbody>
1322<tr><td><tt>filename</tt></td><td>Pointer to buffer</td></tr>
1323<tr><td><tt>len</tt></td><td>Size of buffer</td></tr>
1324</tbody></table></div>
1325<h4>Returns</h4>
1326<p>CUPS file or NULL on error</p>
1327<!-- NEW PAGE -->
1328<h3 class='title'><a name='cupsUser'>cupsUser()</a></h3>
1329<h4>Description</h4>
1330<p>Return the current user's name.</p>
1331<h4>Syntax</h4>
1332<pre>
1333const <a href='#char'>char</a> *
1334cupsUser(void);
1335</pre>
1336<h4>Arguments</h4>
1337<p>None.</p>
1338<h4>Returns</h4>
1339<p>User name</p>
1340<!-- NEW PAGE -->
1341<h2 class='title'><a name='STRUCTURES'>Structures</a></h2>
1342<ul>
1343 <li><a href='#cups_dest_s'><tt>cups_dest_s</tt></a> </li>
1344 <li><a href='#cups_job_s'><tt>cups_job_s</tt></a> </li>
1345 <li><a href='#cups_option_s'><tt>cups_option_s</tt></a> </li>
1346</ul>
1347<!-- NEW PAGE -->
1348<h3 class='title'><a name='cups_dest_s'>cups_dest_s</a></h3>
1349<h4>Description</h4>
1350<p>Destination</p>
1351<h4>Definition</h4>
1352<pre>
1353struct cups_dest_s
1354{
1355 <a href='#char'>char</a> *name, * instance;
1356 int is_default;
1357 int num_options;
1358 <a href='#cups_option_t'>cups_option_t</a> * options;
1359};
1360</pre>
1361<h4>Members</h4>
1362<div class='table'><table align='center' border='1' width='80%'>
1363<thead><tr><th>Name</th><th>Description</th></tr></thead>
1364<tbody>
1365<tr><td><tt>instance</tt> </td><td>Local instance name or NULL</td></tr>
1366<tr><td><tt>is_default</tt> </td><td>Is this printer the default?</td></tr>
1367<tr><td><tt>num_options</tt> </td><td>Number of options</td></tr>
1368<tr><td><tt>options</tt> </td><td>Options</td></tr>
1369</tbody></table></div>
1370<!-- NEW PAGE -->
1371<h3 class='title'><a name='cups_job_s'>cups_job_s</a></h3>
1372<h4>Description</h4>
1373<p>Job</p>
1374<h4>Definition</h4>
1375<pre>
1376struct cups_job_s
1377{
1378 <a href='#char'>char</a> *dest, *title, *user, * format;
1379 int id;
1380 int size, priority;
1381 time_t completed_time, creation_time, processing_time;
1382 ipp_jstate_t state;
1383};
1384</pre>
1385<h4>Members</h4>
1386<div class='table'><table align='center' border='1' width='80%'>
1387<thead><tr><th>Name</th><th>Description</th></tr></thead>
1388<tbody>
1389<tr><td><tt>format</tt> </td><td>Document format</td></tr>
1390<tr><td><tt>id</tt> </td><td>The job ID</td></tr>
1391<tr><td><tt>priority</tt> </td><td>Priority (1-100)</td></tr>
1392<tr><td><tt>processing_time</tt> </td><td>Time the job was processed</td></tr>
1393<tr><td><tt>state</tt> </td><td>Job state</td></tr>
1394</tbody></table></div>
1395<!-- NEW PAGE -->
1396<h3 class='title'><a name='cups_option_s'>cups_option_s</a></h3>
1397<h4>Description</h4>
1398<p>Types and structures...</p>
1399<h4>Definition</h4>
1400<pre>
1401struct cups_option_s
1402{
1403 <a href='#char'>char</a> * name;
1404 <a href='#char'>char</a> * value;
1405};
1406</pre>
1407<h4>Members</h4>
1408<div class='table'><table align='center' border='1' width='80%'>
1409<thead><tr><th>Name</th><th>Description</th></tr></thead>
1410<tbody>
1411<tr><td><tt>name</tt> </td><td>Name of option</td></tr>
1412<tr><td><tt>value</tt> </td><td>Value of option</td></tr>
1413</tbody></table></div>
1414<!-- NEW PAGE -->
1415<h2 class='title'><a name='TYPES'>Types</a></h2>
1416<ul>
1417 <li><a href='#char'><tt>char</tt></a> </li>
1418 <li><a href='#cups_dest_t'><tt>cups_dest_t</tt></a> </li>
1419 <li><a href='#cups_job_t'><tt>cups_job_t</tt></a> </li>
1420 <li><a href='#cups_option_t'><tt>cups_option_t</tt></a> </li>
1421 <li><a href='#cups_ptype_t'><tt>cups_ptype_t</tt></a> </li>
1422</ul>
1423<!-- NEW PAGE -->
1424<h3 class='title'><a name='char'>char</a></h3>
1425<h4>Description</h4>
1426<p>Printer Options</p>
1427<h4>Definition</h4>
1428<pre>
1429typedef const * (*charcups_password_cb_t)(const <a href='#char'>char</a> *);
1430</pre>
1431<!-- NEW PAGE -->
1432<h3 class='title'><a name='cups_dest_t'>cups_dest_t</a></h3>
1433<h4>Description</h4>
1434<p>Destination</p>
1435<h4>Definition</h4>
1436<pre>
1437typedef struct <a href='#cups_dest_s'>cups_dest_s</a> cups_dest_t;
1438</pre>
1439<!-- NEW PAGE -->
1440<h3 class='title'><a name='cups_job_t'>cups_job_t</a></h3>
1441<h4>Description</h4>
1442<p>Job</p>
1443<h4>Definition</h4>
1444<pre>
1445typedef struct <a href='#cups_job_s'>cups_job_s</a> cups_job_t;
1446</pre>
1447<!-- NEW PAGE -->
1448<h3 class='title'><a name='cups_option_t'>cups_option_t</a></h3>
1449<h4>Description</h4>
1450<p>Types and structures...</p>
1451<h4>Definition</h4>
1452<pre>
1453typedef struct <a href='#cups_option_s'>cups_option_s</a> cups_option_t;
1454</pre>
1455<!-- NEW PAGE -->
1456<h3 class='title'><a name='cups_ptype_t'>cups_ptype_t</a></h3>
1457<h4>Description</h4>
1458<p>Printer Type/Capability Bits</p>
1459<h4>Definition</h4>
1460<pre>
1461typedef unsigned cups_ptype_t;
1462</pre>
1463</body>
1464</html>