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