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