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