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