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