1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
3 <!-- SECTION: Programming -->
5 <title>CUPS API
</title>
6 <meta name=
"keywords" content=
"Programming">
7 <meta name=
"creator" content=
"Mini-XML v2.5">
8 <style type=
"text/css"><!--
10 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
13 H1, H2, H3, H4, H5, H6, P, TD, TH {
14 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
18 font-family: monaco, courier, monospace;
23 font-family: monaco, courier, monospace;
32 border: dotted thin #999999;
37 PRE.command EM, PRE.example EM {
38 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
42 font-family: monaco, courier, monospace;
53 border: solid thin #999999;
58 text-decoration: none;
62 A:link:hover, A:visited:hover, A:active {
63 text-decoration: underline;
72 border: solid thin #999999;
73 border-collapse: collapse;
89 border: solid thin #cccccc;
96 border-bottom: solid thin #999999;
105 caption-side: bottom;
125 border: thin solid #000000;
133 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
139 border-bottom: solid 2pt #000000;
157 font-family: monaco, courier, monospace;
166 border: solid thin #999999;
167 border-collapse: collapse;
172 DIV.summary TABLE TD, DIV.summary TABLE TH {
173 border: solid thin #999999;
179 DIV.summary TABLE THEAD TH {
183 /* API documentation styles... */
190 div.body h3, div.body h4, div.body h5 {
191 margin-bottom: 0.5em;
194 .class, .enumeration, .function, .struct, .typedef, .union {
195 border-bottom: solid thin #999999;
202 code, p.code, pre, ul.code li {
203 font-family: monaco, courier, monospace;
206 ul.code, ul.contents, ul.subcontents {
207 list-style-type: none;
217 ul.contents li ul.code, ul.contents li ul.subcontents {
230 margin-bottom: 0.5em;
233 /* This is just for the HTML files generated with the framedhelp target */
236 border: solid thin black;
245 div.contents ul.contents {
253 "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
255 CUPS API header for the Common UNIX Printing System (CUPS).
257 Copyright 2008 by Apple Inc.
259 These coded instructions, statements, and computer programs are the
260 property of Apple Inc. and are protected by Federal copyright
261 law. Distribution and use rights are outlined in the file "LICENSE.txt"
262 which should have been included with this file. If this file is
263 file is missing or damaged, see the license at "http://www.cups.org/".
266 <h1 class=
"title">CUPS API
</h1>
268 <div class='summary'
><table summary='General Information'
>
282 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a><br>
283 Programming:
<a href='api-array.html' target='_top'
>Array API
</a><br>
284 Programming:
<a href='api-filedir.html' target='_top'
>File and Directory APIs
</a><br>
285 Programming:
<a href='api-filter.html' target='_top'
>Filter and Backend Programming
</a><br>
286 Programming:
<a href='api-httpipp.html' target='_top'
>HTTP and IPP APIs
</a><br>
287 Programming:
<a href='api-ppd.html' target='_top'
>PPD API
</a><br>
288 Programming:
<a href='api-raster.html' target='_top'
>Raster API
</a></td>
292 <h2 class=
"title">Contents
</h2>
293 <ul class=
"contents">
295 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
296 <li><a href=
"#PRINTERS_AND_CLASSES">Printers and Classes
</a></li>
297 <li><a href=
"#OPTIONS">Options
</a></li>
298 <li><a href=
"#PRINT_JOBS">Print Jobs
</a></li>
299 <li><a href=
"#ERROR_HANDLING">Error Handling
</a></li>
300 <li><a href=
"#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication
</a></li>
302 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
303 <li><a href=
"#cupsAddDest" title=
"Add a destination to the list of destinations.">cupsAddDest
</a></li>
304 <li><a href=
"#cupsAddOption" title=
"Add an option to an option array.">cupsAddOption
</a></li>
305 <li><a href=
"#cupsCancelJob" title=
"Cancel a print job on the default server.">cupsCancelJob
</a></li>
306 <li><a href=
"#cupsCancelJob2" title=
"Cancel or purge a print job.">cupsCancelJob2
</a></li>
307 <li><a href=
"#cupsCreateJob" title=
"Create an empty job.">cupsCreateJob
</a></li>
308 <li><a href=
"#cupsEncryption" title=
"Get the default encryption settings.">cupsEncryption
</a></li>
309 <li><a href=
"#cupsFinishDocument" title=
"Finish sending a document.">cupsFinishDocument
</a></li>
310 <li><a href=
"#cupsFreeDests" title=
"Free the memory used by the list of destinations.">cupsFreeDests
</a></li>
311 <li><a href=
"#cupsFreeJobs" title=
"Free memory used by job data.">cupsFreeJobs
</a></li>
312 <li><a href=
"#cupsFreeOptions" title=
"Free all memory used by options.">cupsFreeOptions
</a></li>
313 <li><a href=
"#cupsGetClasses" title=
"Get a list of printer classes from the default server.">cupsGetClasses
</a></li>
314 <li><a href=
"#cupsGetDefault" title=
"Get the default printer or class for the default server.">cupsGetDefault
</a></li>
315 <li><a href=
"#cupsGetDefault2" title=
"Get the default printer or class for the specified server.">cupsGetDefault2
</a></li>
316 <li><a href=
"#cupsGetDest" title=
"Get the named destination from the list.">cupsGetDest
</a></li>
317 <li><a href=
"#cupsGetDests" title=
"Get the list of destinations from the default server.">cupsGetDests
</a></li>
318 <li><a href=
"#cupsGetDests2" title=
"Get the list of destinations from the specified server.">cupsGetDests2
</a></li>
319 <li><a href=
"#cupsGetFd" title=
"Get a file from the server.">cupsGetFd
</a></li>
320 <li><a href=
"#cupsGetFile" title=
"Get a file from the server.">cupsGetFile
</a></li>
321 <li><a href=
"#cupsGetJobs" title=
"Get the jobs from the default server.">cupsGetJobs
</a></li>
322 <li><a href=
"#cupsGetJobs2" title=
"Get the jobs from the specified server.">cupsGetJobs2
</a></li>
323 <li><a href=
"#cupsGetNamedDest" title=
"Get options for the named destination.">cupsGetNamedDest
</a></li>
324 <li><a href=
"#cupsGetOption" title=
"Get an option value.">cupsGetOption
</a></li>
325 <li><a href=
"#cupsGetPPD" title=
"Get the PPD file for a printer on the default server.">cupsGetPPD
</a></li>
326 <li><a href=
"#cupsGetPPD2" title=
"Get the PPD file for a printer from the specified server.">cupsGetPPD2
</a></li>
327 <li><a href=
"#cupsGetPPD3" title=
"Get the PPD file for a printer on the specified
328 server if it has changed.">cupsGetPPD3
</a></li>
329 <li><a href=
"#cupsGetPassword" title=
"Get a password from the user.">cupsGetPassword
</a></li>
330 <li><a href=
"#cupsGetPrinters" title=
"Get a list of printers from the default server.">cupsGetPrinters
</a></li>
331 <li><a href=
"#cupsGetServerPPD" title=
"Get an available PPD file from the server.">cupsGetServerPPD
</a></li>
332 <li><a href=
"#cupsLangDefault" title=
"Return the default language.">cupsLangDefault
</a></li>
333 <li><a href=
"#cupsLangEncoding" title=
"Return the character encoding (us-ascii, etc.)
334 for the given language.">cupsLangEncoding
</a></li>
335 <li><a href=
"#cupsLangFlush" title=
"Flush all language data out of the cache.">cupsLangFlush
</a></li>
336 <li><a href=
"#cupsLangFree" title=
"Free language data.">cupsLangFree
</a></li>
337 <li><a href=
"#cupsLangGet" title=
"Get a language.">cupsLangGet
</a></li>
338 <li><a href=
"#cupsLastError" title=
"Return the last IPP status code.">cupsLastError
</a></li>
339 <li><a href=
"#cupsLastErrorString" title=
"Return the last IPP status-message.">cupsLastErrorString
</a></li>
340 <li><a href=
"#cupsNotifySubject" title=
"Return the subject for the given notification message.">cupsNotifySubject
</a></li>
341 <li><a href=
"#cupsNotifyText" title=
"Return the text for the given notification message.">cupsNotifyText
</a></li>
342 <li><a href=
"#cupsParseOptions" title=
"Parse options from a command-line argument.">cupsParseOptions
</a></li>
343 <li><a href=
"#cupsPrintFile" title=
"Print a file to a printer or class on the default server.">cupsPrintFile
</a></li>
344 <li><a href=
"#cupsPrintFile2" title=
"Print a file to a printer or class on the specified
345 server.">cupsPrintFile2
</a></li>
346 <li><a href=
"#cupsPrintFiles" title=
"Print one or more files to a printer or class on the
347 default server.">cupsPrintFiles
</a></li>
348 <li><a href=
"#cupsPrintFiles2" title=
"Print one or more files to a printer or class on the
349 specified server.">cupsPrintFiles2
</a></li>
350 <li><a href=
"#cupsPutFd" title=
"Put a file on the server.">cupsPutFd
</a></li>
351 <li><a href=
"#cupsPutFile" title=
"Put a file on the server.">cupsPutFile
</a></li>
352 <li><a href=
"#cupsRemoveDest" title=
"Remove a destination from the destination list.">cupsRemoveDest
</a></li>
353 <li><a href=
"#cupsRemoveOption" title=
"Remove an option from an option array.">cupsRemoveOption
</a></li>
354 <li><a href=
"#cupsServer" title=
"Return the hostname/address of the default server.">cupsServer
</a></li>
355 <li><a href=
"#cupsSetDefaultDest" title=
"Set the default destination.">cupsSetDefaultDest
</a></li>
356 <li><a href=
"#cupsSetDests" title=
"Save the list of destinations for the default server.">cupsSetDests
</a></li>
357 <li><a href=
"#cupsSetDests2" title=
"Save the list of destinations for the specified server.">cupsSetDests2
</a></li>
358 <li><a href=
"#cupsSetEncryption" title=
"Set the encryption preference.">cupsSetEncryption
</a></li>
359 <li><a href=
"#cupsSetPasswordCB" title=
"Set the password callback for CUPS.">cupsSetPasswordCB
</a></li>
360 <li><a href=
"#cupsSetServer" title=
"Set the default server name.">cupsSetServer
</a></li>
361 <li><a href=
"#cupsSetUser" title=
"Set the default user name.">cupsSetUser
</a></li>
362 <li><a href=
"#cupsStartDocument" title=
"Add a document to a job created with cupsCreateJob().">cupsStartDocument
</a></li>
363 <li><a href=
"#cupsTempFd" title=
"Creates a temporary file.">cupsTempFd
</a></li>
364 <li><a href=
"#cupsTempFile" title=
"Generates a temporary filename.">cupsTempFile
</a></li>
365 <li><a href=
"#cupsTempFile2" title=
"Creates a temporary CUPS file.">cupsTempFile2
</a></li>
366 <li><a href=
"#cupsUser" title=
"Return the current user's name.">cupsUser
</a></li>
368 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
369 <li><a href=
"#cups_dest_t" title=
"Destination">cups_dest_t
</a></li>
370 <li><a href=
"#cups_job_t" title=
"Job">cups_job_t
</a></li>
371 <li><a href=
"#cups_option_t" title=
"Printer Options">cups_option_t
</a></li>
372 <li><a href=
"#cups_password_cb_t" title=
"Password callback">cups_password_cb_t
</a></li>
373 <li><a href=
"#cups_ptype_t" title=
"Printer type/capability bits">cups_ptype_t
</a></li>
375 <li><a href=
"#STRUCTURES">Structures
</a><ul class=
"code">
376 <li><a href=
"#cups_dest_s" title=
"Destination">cups_dest_s
</a></li>
377 <li><a href=
"#cups_job_s" title=
"Job">cups_job_s
</a></li>
378 <li><a href=
"#cups_option_s" title=
"Printer Options">cups_option_s
</a></li>
380 <li><a href=
"#ENUMERATIONS">Constants
</a><ul class=
"code">
381 <li><a href=
"#cups_ptype_e" title=
"Printer type/capability bit constants">cups_ptype_e
</a></li>
385 "$Id: api-cups.shtml 7258 2008-01-28 00:15:05Z mike $"
387 CUPS API introduction for the Common UNIX Printing System (CUPS).
389 Copyright 2007-2008 by Apple Inc.
390 Copyright 1997-2006 by Easy Software Products, all rights reserved.
392 These coded instructions, statements, and computer programs are the
393 property of Apple Inc. and are protected by Federal copyright
394 law. Distribution and use rights are outlined in the file "LICENSE.txt"
395 which should have been included with this file. If this file is
396 file is missing or damaged, see the license at "http://www.cups.org/".
399 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
401 <p>The CUPS API provides the convenience functions needed to support
402 applications, filters, printer drivers, and backends that need to interface
403 with the CUPS scheduler.
</p>
405 <h3><a name='PRINTERS_AND_CLASSES'
>Printers and Classes
</a></h3>
407 <p>Printers and classes (collections of printers) are accessed through
408 the
<a href=
"#cups_dest_t"><code>cups_dest_t
</code></a> structure which
409 includes the name (
<code>name
</code>), instance (
<code>instance
</code> -
410 a way of selected certain saved options), and the options and attributes
411 associated with that destination (
<code>num_options
</code> and
412 <code>options
</code>). Destinations are created using the
413 <a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> function and freed
414 using the
<a href='#cupsFreeDests'
><code>cupsFreeDests
</code></a> function.
415 The
<a href='#cupsGetDest'
><code>cupsGetDest
</code></a> function finds a
416 specific destination for printing:
</p>
418 <pre class='example'
>
419 #include
<cups/cups.h
>
421 <a href='#cups_dest_t'
>cups_dest_t
</a> *dests;
422 int num_dests =
<a href='#cupsGetDests'
>cupsGetDests
</a>(
&dests);
423 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest =
<a href='#cupsGetDest'
>cupsGetDest
</a>(
"name", NULL, num_dests, dests);
425 /* do something wiith dest */
427 <a href='#cupsFreeDests'
>cupsFreeDests
</a>(num_dests, dests);
430 <p>Passing
<code>NULL
</code> to
431 <a href='#cupsGetDest'
><code>cupsGetDest
</code></a> for the destination name
432 will return the default destination. Similarly, passing a
<code>NULL
</code>
433 instance will return the default instance for that destination.
</p>
435 <div class='table'
><table summary='Table
1: Printer Attributes' width='
80%'
>
436 <caption>Table
1:
<a name='TABLE1'
>Printer Attributes
</a></caption>
439 <th>Attribute Name
</th>
445 <td>"auth-info-required"</td>
446 <td>The type of authentication required for printing to this
447 destination:
"none",
"username,password",
"domain,username,password",
448 or
"negotiate" (Kerberos)
</td>
451 <td>"printer-info"</td>
452 <td>The human-readable description of the destination such as
"My
456 <td>"printer-is-accepting-jobs"</td>
457 <td>"1" if the destination is accepting new jobs,
"0" if not.
</td>
460 <td>"printer-is-shared"</td>
461 <td>"1" if the destination is being shared with other computers,
"0" if
465 <td>"printer-location"</td>
466 <td>The human-readable location of the destination such as
"Lab 4".
</td>
469 <td>"printer-make-and-model"</td>
470 <td>The human-readable make and model of the destination such as
"HP
471 LaserJet 4000 Series".
</td>
474 <td>"printer-state"</td>
475 <td>"3" if the destination is idle,
"4" if the destination is printing
476 a job, and
"5" if the destination is stopped.
</td>
479 <td>"printer-state-change-time"</td>
480 <td>The UNIX time when the destination entered the current state.
</td>
483 <td>"printer-state-reasons"</td>
484 <td>Additional comma-delimited state keywords for the destination
485 such as
"media-tray-empty-error" and
"toner-low-warning".
</td>
488 <td>"printer-type"</td>
489 <td>The
<a href='#cups_printer_t'
><code>cups_printer_t
</code></a>
490 value associated with the destination.
</td>
495 <h3><a name='OPTIONS'
>Options
</a></h3>
497 <p>Options are stored in arrays of
498 <a href='#cups_option_t'
><code>cups_option_t
</code></a> structures. Each
499 option has a name (
<code>name
</code>) and value (
<code>value
</code>)
500 associated with it. The
<a href='#cups_dest_t'
><code>cups_dest_t
</code></a>
501 <code>num_options
</code> and
<code>options
</code> members contain the
502 default options for a particular destination, along with several informational
503 attributes about the destination as shown in
<a href='#TABLE1'
>Table
1</a>.
504 The
<a href='#cupsGetOption'
><code>cupsGetOption
</code></a> function gets
505 the value for the named option. For example, the following code lists the
506 available destinations and their human-readable descriptions:
</p>
508 <pre class='example'
>
509 #include
<cups/cups.h
>
511 <a href='#cups_dest_t'
>cups_dest_t
</a> *dests;
512 int num_dests =
<a href='#cupsGetDests'
>cupsGetDests
</a>(
&dests);
513 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
517 for (i = num_dests, dest = dests; i
> 0; i --, dest ++)
518 if (dest-
>instance == NULL)
520 value =
<a href='#cupsGetOption'
>cupsGetOption
</a>(
"printer-info", dest-
>num_options, dest-
>options);
521 printf(
"%s (%s)\n", dest-
>name, value ? value :
"no description");
524 <a href='#cupsFreeDests'
>cupsFreeDests
</a>(num_dests, dests);
527 <p>You can create your own option arrays using the
528 <a href='#cupsAddOption'
><code>cupsAddOption
</code></a> function, which
529 adds a single named option to an array:
</p>
531 <pre class='example'
>
532 #include
<cups/cups.h
>
535 <a href='#cups_option_t'
>cups_option_t
</a> *options = NULL;
537 /* The returned num_options value is updated as needed */
538 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"first",
"value", num_options,
&options);
540 /* This adds a second option value */
541 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"second",
"value", num_options,
&options);
543 /* This replaces the first option we added */
544 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"first",
"new value", num_options,
&options);
547 <p>Use a
<code>for
</code> loop to copy the options from a destination:
</p>
549 <pre class='example'
>
550 #include
<cups/cups.h
>
554 <a href='#cups_option_t'
>cups_option_t
</a> *options = NULL;
555 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
557 for (i =
0; i < dest-
>num_options; i ++)
558 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(dest-
>options[i].name, dest-
>options[i].value, num_options,
&options);
561 <p>Use the
<a href='#cupsFreeOptions'
><code>cupsFreeOptions
</code></a>
562 function to free the options array when you are done using it:
</p>
564 <pre class='example'
>
565 <a href='#cupsFreeOptions'
>cupsFreeOptions
</a>(num_options, options);
568 <h3><a name='PRINT_JOBS'
>Print Jobs
</a></h3>
570 <p>Print jobs are identified by a locally-unique job ID number from
1 to
571 2<sup>31</sup>-
1 and have options and one or more files for printing to a
572 single destination. The
<a href='#cupsPrintFile'
><code>cupsPrintFile
</code></a>
573 function creates a new job with one file. The following code prints the CUPS
576 <pre class='example'
>
577 #include
<cups/cups.h
>
579 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
581 <a href='#cups_option_t'
>cups_option_t
</a> *options;
584 /* Print a single file */
585 job_id =
<a href='#cupsPrintFile'
>cupsPrintFile
</a>(dest-
>name,
"/usr/share/cups/data/testprint.ps",
"Test Print", num_options, options);
588 <p>The
<a href='#cupsPrintFiles'
><code>cupsPrintFiles
</code></a> function
589 creates a job with multiple files. The files are provided in a
590 <code>char *
</code> array:
</p>
592 <pre class='example'
>
593 #include
<cups/cups.h
>
595 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
597 <a href='#cups_option_t'
>cups_option_t
</a> *options;
599 char *files[
3] = {
"file1.pdf",
"file2.pdf",
"file3.pdf" };
601 /* Print three files */
602 job_id =
<a href='#cupsPrintFiles'
>cupsPrintFiles
</a>(dest-
>name,
3, files,
"Test Print", num_options, options);
605 <p>Finally, the
<a href='#cupsCreateJob'
><code>cupsCreateJob
</code></a>
606 function creates a new job with no files in it. Files are added using the
607 <a href='#cupsStartDocument'
><code>cupsStartDocument
</code></a>,
608 <a href='api-httpipp.html#cupsWriteRequestData'
><code>cupsWriteRequestData
</code></a>,
609 and
<a href='#cupsFinishDocument'
><code>cupsFinishDocument
</code></a> functions.
610 The following example creates a job with
10 text files for printing:
</p>
612 <pre class='example'
>
613 #include
<cups/cups.h
>
615 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
617 <a href='#cups_option_t'
>cups_option_t
</a> *options;
623 job_id =
<a href='#cupsCreateJob'
>cupsCreateJob
</a>(CUPS_HTTP_DEFAULT, dest-
>name,
"10 Text Files", num_options, options);
625 /* If the job is created, add
10 files */
628 for (i =
1; i
<=
10; i ++)
630 snprintf(buffer, sizeof(buffer),
"file%d.txt", i);
632 <a href='#cupsStartDocument'
>cupsStartDocument
</a>(CUPS_HTTP_DEFAULT, dest-
>name, job_id, buffer, CUPS_FORMAT_TEXT, i ==
10);
634 snprintf(buffer, sizeof(buffer),
642 /* cupsWriteRequestData can be called as many times as needed */
643 <a href='#cupsWriteRequestData'
>cupsWriteRequestData
</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
645 <a href='#cupsFinishDocument'
>cupsFinishDocument
</a>(CUPS_HTTP_DEFAULT, dest-
>name);
650 <p>Once you have created a job, you can monitor its status using the
651 <a href='#cupsGetJobs'
><code>cupsGetJobs
</code></a> function, which returns
652 an array of
<a href='#cups_job_t'
><code>cups_job_t
</code></a> structures.
653 Each contains the job ID (
<code>id
</code>), destination name
654 (
<code>dest
</code>), title (
<code>title
</code>), and other information
655 associated with the job. The job array is freed using the
656 <a href='#cupsFreeJobs'
><code>cupsFreeJobs
</code></a> function. The following
657 example monitors a specific job ID, showing the current job state once every
658 5 seconds until the job is completed:
</p>
660 <pre class='example'
>
661 #include
<cups/cups.h
>
663 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
666 <a href='#cups_job_t'
>cups_job_t
</a> *jobs;
668 ipp_jstate_t job_state = IPP_JOB_PENDING;
670 while (job_state
< IPP_JOB_STOPPED)
672 /* Get my jobs (
1) with any state (-
1) */
673 num_jobs =
<a href='#cupsGetJobs'
>cupsGetJobs
</a>(
&jobs, dest-
>name,
1, -
1);
675 /* Loop to find my job */
676 job_state = IPP_JOB_COMPLETED;
678 for (i =
0; i
< num_jobs; i ++)
679 if (jobs[i].id == job_id)
681 job_state = jobs[i].state;
685 /* Free the job array */
686 <a href='#cupsFreeJobs'
>cupsFreeJobs
</a>(num_jobs, jobs);
688 /* Show the current state */
691 case IPP_JOB_PENDING :
692 printf(
"Job %d is pending.\n", job_id);
695 printf(
"Job %d is held.\n", job_id);
697 case IPP_JOB_PROCESSING :
698 printf(
"Job %d is processing.\n", job_id);
700 case IPP_JOB_STOPPED :
701 printf(
"Job %d is stopped.\n", job_id);
703 case IPP_JOB_CANCELED :
704 printf(
"Job %d is canceled.\n", job_id);
706 case IPP_JOB_ABORTED :
707 printf(
"Job %d is aborted.\n", job_id);
709 case IPP_JOB_COMPLETED :
710 printf(
"Job %d is completed.\n", job_id);
714 /* Sleep if the job is not finished */
715 if (job_state
< IPP_JOB_STOPPED)
720 <p>To cancel a job, use the
721 <a href='#cupsCancelJob'
><code>cupsCancelJob
</code></a> function with the
724 <pre class='exmaple'
>
725 #include
<cups/cups.h
>
727 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
730 <a href='#cupsCancelJob'
>cupsCancelJob
</a>(dest-
>name, job_id);
733 <h3><a name='ERROR_HANDLING'
>Error Handling
</a></h3>
735 <p>If any of the CUPS API printing functions returns an error, the reason for
736 that error can be found by calling the
737 <a href='#cupsLastError'
><code>cupsLastError
</code></a> and
738 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> functions.
739 <a href='#cupsLastError'
><code>cupsLastError
</code></a> returns the last IPP
741 (
<a href='api-httpipp.html#ipp_status_t'
><code>ipp_status_t
</code></a>)
742 that was encountered, while
743 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> returns
744 a (localized) human-readable string that can be shown to the user. For example,
745 if any of the job creation functions returns a job ID of
0, you can use
746 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> to show
747 the reason why the job could not be created:
</p>
749 <pre class='example'
>
750 #include
<cups/cups.h
>
755 puts(cupsLastErrorString());
758 <h3><a name='PASSWORDS_AND_AUTHENTICATION'
>Passwords and Authentication
</a></h3>
760 <p>CUPS supports authentication of any request, including submission of print
761 jobs. The default mechanism for getting the username and password is to use the
762 login user and a password from the console.
</p>
764 <p>To support other types of applications, in particular Graphical User
765 Interfaces (
"GUIs"), the CUPS API provides functions to set the default
766 username and to register a callback function that returns a password string.
</p>
768 <p>The
<a href=
"#cupsSetPasswordCB"><code>cupsSetPasswordCB
</code></a>
769 function is used to set a password callback in your program. Only one
770 function can be used at any time.
</p>
772 <p>The
<a href=
"#cupsSetUser"><code>cupsSetUser
</code></a> function sets the
773 current username for authentication. This function can be called by your
774 password callback function to change the current username as needed.
</p>
776 <p>The following example shows a simple password callback that gets a
777 username and password from the user:
</p>
779 <pre class='example'
>
780 #include
<cups/cups.h
>
783 my_password_cb(const char *prompt)
790 /* Get a username from the user */
791 printf(
"Username: ");
792 if (fgets(user, sizeof(user), stdin) == NULL)
795 /* Strip the newline from the string and set the user */
796 user[strlen(user) -
1] = '\
0';
798 <a href='#cupsSetUser'
>cupsSetUser
</a>(user);
800 /* Use getpass() to ask for the password... */
801 return (getpass(
"Password: "));
804 <a href='#cupsSetPasswordCB'
>cupsSetPasswordCB
</a>(my_password_cb);
807 <p>Similarly, a GUI could display the prompt string in a window with input
808 fields for the username and password. The username should default to the
809 string returned by the
<a href=
"#cupsUser"><code>cupsUser
</code></a>
811 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
812 <h3 class=
"function"><a name=
"cupsAddDest">cupsAddDest
</a></h3>
813 <p class=
"description">Add a destination to the list of destinations.
</p>
815 int cupsAddDest (
<br>
816 const char *name,
<br>
817 const char *instance,
<br>
818 int num_dests,
<br>
819 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
821 <h4 class=
"parameters">Parameters
</h4>
824 <dd class=
"description">Destination name
</dd>
826 <dd class=
"description">Instance name or
<code>NULL
</code> for none/primary
</dd>
828 <dd class=
"description">Number of destinations
</dd>
830 <dd class=
"description">Destinations
</dd>
832 <h4 class=
"returnvalue">Return Value
</h4>
833 <p class=
"description">New number of destinations
</p>
834 <h4 class=
"discussion">Discussion
</h4>
835 <p class=
"discussion">This function cannot be used to add a new class or printer queue,
836 it only adds a new container of saved options for the named
837 destination or instance.
<br>
839 If the named destination already exists, the destination list is
840 returned unchanged. Adding a new instance of a destination creates
841 a copy of that destination's options.
<br>
843 Use the
<a href=
"#cupsSaveDests"><code>cupsSaveDests
</code></a> function to save the updated list of
844 destinations to the user's lpoptions file.
</p>
845 <h3 class=
"function"><a name=
"cupsAddOption">cupsAddOption
</a></h3>
846 <p class=
"description">Add an option to an option array.
</p>
848 int cupsAddOption (
<br>
849 const char *name,
<br>
850 const char *value,
<br>
851 int num_options,
<br>
852 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
854 <h4 class=
"parameters">Parameters
</h4>
857 <dd class=
"description">Name of option
</dd>
859 <dd class=
"description">Value of option
</dd>
861 <dd class=
"description">Number of options
</dd>
863 <dd class=
"description">Pointer to options
</dd>
865 <h4 class=
"returnvalue">Return Value
</h4>
866 <p class=
"description">Number of options
</p>
867 <h4 class=
"discussion">Discussion
</h4>
868 <p class=
"discussion">New option arrays can be initialized simply by passing
0 for the
869 "num_options
" parameter.
</p>
870 <h3 class=
"function"><a name=
"cupsCancelJob">cupsCancelJob
</a></h3>
871 <p class=
"description">Cancel a print job on the default server.
</p>
873 int cupsCancelJob (
<br>
874 const char *name,
<br>
875 int job_id
<br>
877 <h4 class=
"parameters">Parameters
</h4>
880 <dd class=
"description">Name of printer or class
</dd>
882 <dd class=
"description">Job ID
</dd>
884 <h4 class=
"returnvalue">Return Value
</h4>
885 <p class=
"description">1 on success,
0 on failure
</p>
886 <h4 class=
"discussion">Discussion
</h4>
887 <p class=
"discussion">Pass
<code>CUPS_JOBID_ALL
</code> to cancel all jobs or
<code>CUPS_JOBID_CURRENT
</code>
888 to cancel the current job on the named destination.
<br>
890 Use the
<a href=
"#cupsLastError"><code>cupsLastError
</code></a> and
<a href=
"#cupsLastErrorString"><code>cupsLastErrorString
</code></a> functions to get
891 the cause of any failure.
</p>
892 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsCancelJob2">cupsCancelJob2
</a></h3>
893 <p class=
"description">Cancel or purge a print job.
</p>
895 ipp_status_t cupsCancelJob2 (
<br>
896 http_t *http,
<br>
897 const char *name,
<br>
898 int job_id,
<br>
899 int purge
<br>
901 <h4 class=
"parameters">Parameters
</h4>
904 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
906 <dd class=
"description">Name of printer or class
</dd>
908 <dd class=
"description">Job ID or
0 for the current job, -
1 for all jobs
</dd>
910 <dd class=
"description">1 to purge,
0 to cancel
</dd>
912 <h4 class=
"returnvalue">Return Value
</h4>
913 <p class=
"description">IPP status
</p>
914 <h4 class=
"discussion">Discussion
</h4>
915 <p class=
"discussion">Canceled jobs remain in the job history while purged jobs are removed
916 from the job history.
<br>
918 Pass
<code>CUPS_JOBID_ALL
</code> to cancel all jobs or
<code>CUPS_JOBID_CURRENT
</code>
919 to cancel the current job on the named destination.
<br>
921 Use the
<a href=
"#cupsLastError"><code>cupsLastError
</code></a> and
<a href=
"#cupsLastErrorString"><code>cupsLastErrorString
</code></a> functions to get
922 the cause of any failure.
925 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsCreateJob">cupsCreateJob
</a></h3>
926 <p class=
"description">Create an empty job.
</p>
928 int cupsCreateJob (
<br>
929 http_t *http,
<br>
930 const char *name,
<br>
931 const char *title,
<br>
932 int num_options,
<br>
933 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
935 <h4 class=
"parameters">Parameters
</h4>
938 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
940 <dd class=
"description">Printer or class name
</dd>
942 <dd class=
"description">Title of job
</dd>
944 <dd class=
"description">Number of options
</dd>
946 <dd class=
"description">Options
</dd>
948 <h4 class=
"returnvalue">Return Value
</h4>
949 <p class=
"description">Job ID or
0 on error
</p>
950 <h4 class=
"discussion">Discussion
</h4>
951 <p class=
"discussion">Submit files for printing to the job using the
<a href=
"#cupsStartDocument"><code>cupsStartDocument
</code></a>,
952 <a href=
"#cupsWriteRequestData"><code>cupsWriteRequestData
</code></a>, and
<a href=
"#cupsFinishDocument"><code>cupsFinishDocument
</code></a> functions.
955 <h3 class=
"function"><a name=
"cupsEncryption">cupsEncryption
</a></h3>
956 <p class=
"description">Get the default encryption settings.
</p>
958 http_encryption_t cupsEncryption (void);
</p>
959 <h4 class=
"returnvalue">Return Value
</h4>
960 <p class=
"description">Encryption settings
</p>
961 <h4 class=
"discussion">Discussion
</h4>
962 <p class=
"discussion">The default encryption setting comes from the CUPS_ENCRYPTION
963 environment variable, then the ~/.cupsrc file, and finally the
964 /etc/cups/client.conf file. If not set, the default is
965 <code>HTTP_ENCRYPT_IF_REQUESTED
</code>.
</p>
966 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsFinishDocument">cupsFinishDocument
</a></h3>
967 <p class=
"description">Finish sending a document.
</p>
969 ipp_status_t cupsFinishDocument (
<br>
970 http_t *http,
<br>
971 const char *name
<br>
973 <h4 class=
"parameters">Parameters
</h4>
976 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
978 <dd class=
"description">Printer or class name
</dd>
980 <h4 class=
"returnvalue">Return Value
</h4>
981 <p class=
"description">Status of document submission
</p>
982 <h4 class=
"discussion">Discussion
</h4>
983 <p class=
"discussion">The document must have been started using
<a href=
"#cupsStartDocument"><code>cupsStartDocument
</code></a>.
986 <h3 class=
"function"><a name=
"cupsFreeDests">cupsFreeDests
</a></h3>
987 <p class=
"description">Free the memory used by the list of destinations.
</p>
989 void cupsFreeDests (
<br>
990 int num_dests,
<br>
991 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
993 <h4 class=
"parameters">Parameters
</h4>
996 <dd class=
"description">Number of destinations
</dd>
998 <dd class=
"description">Destinations
</dd>
1000 <h3 class=
"function"><a name=
"cupsFreeJobs">cupsFreeJobs
</a></h3>
1001 <p class=
"description">Free memory used by job data.
</p>
1003 void cupsFreeJobs (
<br>
1004 int num_jobs,
<br>
1005 <a href=
"#cups_job_t">cups_job_t
</a> *jobs
<br>
1007 <h4 class=
"parameters">Parameters
</h4>
1010 <dd class=
"description">Number of jobs
</dd>
1012 <dd class=
"description">Jobs
</dd>
1014 <h3 class=
"function"><a name=
"cupsFreeOptions">cupsFreeOptions
</a></h3>
1015 <p class=
"description">Free all memory used by options.
</p>
1017 void cupsFreeOptions (
<br>
1018 int num_options,
<br>
1019 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1021 <h4 class=
"parameters">Parameters
</h4>
1023 <dt>num_options
</dt>
1024 <dd class=
"description">Number of options
</dd>
1026 <dd class=
"description">Pointer to options
</dd>
1028 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsGetClasses">cupsGetClasses
</a></h3>
1029 <p class=
"description">Get a list of printer classes from the default server.
</p>
1031 int cupsGetClasses (
<br>
1032 char ***classes
<br>
1034 <h4 class=
"parameters">Parameters
</h4>
1037 <dd class=
"description">Classes
</dd>
1039 <h4 class=
"returnvalue">Return Value
</h4>
1040 <p class=
"description">Number of classes
</p>
1041 <h4 class=
"discussion">Discussion
</h4>
1042 <p class=
"discussion">This function is deprecated - use
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> instead.
1045 <h3 class=
"function"><a name=
"cupsGetDefault">cupsGetDefault
</a></h3>
1046 <p class=
"description">Get the default printer or class for the default server.
</p>
1048 const char *cupsGetDefault (void);
</p>
1049 <h4 class=
"returnvalue">Return Value
</h4>
1050 <p class=
"description">Default printer or
<code>NULL
</code></p>
1051 <h4 class=
"discussion">Discussion
</h4>
1052 <p class=
"discussion">This function returns the default printer or class as defined by
1053 the LPDEST or PRINTER environment variables. If these environment
1054 variables are not set, the server default destination is returned.
1055 Applications should use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a>
1056 functions to get the user-defined default printer, as this function does
1057 not support the lpoptions-defined default printer.
</p>
1058 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetDefault2">cupsGetDefault2
</a></h3>
1059 <p class=
"description">Get the default printer or class for the specified server.
</p>
1061 const char *cupsGetDefault2 (
<br>
1062 http_t *http
<br>
1064 <h4 class=
"parameters">Parameters
</h4>
1067 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1069 <h4 class=
"returnvalue">Return Value
</h4>
1070 <p class=
"description">Default printer or
<code>NULL
</code></p>
1071 <h4 class=
"discussion">Discussion
</h4>
1072 <p class=
"discussion">This function returns the default printer or class as defined by
1073 the LPDEST or PRINTER environment variables. If these environment
1074 variables are not set, the server default destination is returned.
1075 Applications should use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a>
1076 functions to get the user-defined default printer, as this function does
1077 not support the lpoptions-defined default printer.
1080 <h3 class=
"function"><a name=
"cupsGetDest">cupsGetDest
</a></h3>
1081 <p class=
"description">Get the named destination from the list.
</p>
1083 <a href=
"#cups_dest_t">cups_dest_t
</a> *cupsGetDest (
<br>
1084 const char *name,
<br>
1085 const char *instance,
<br>
1086 int num_dests,
<br>
1087 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1089 <h4 class=
"parameters">Parameters
</h4>
1092 <dd class=
"description">Destination name or
<code>NULL
</code> for the default destination
</dd>
1094 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1096 <dd class=
"description">Number of destinations
</dd>
1098 <dd class=
"description">Destinations
</dd>
1100 <h4 class=
"returnvalue">Return Value
</h4>
1101 <p class=
"description">Destination pointer or
<code>NULL
</code></p>
1102 <h4 class=
"discussion">Discussion
</h4>
1103 <p class=
"discussion">Use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> or
<a href=
"#cupsGetDests2"><code>cupsGetDests2
</code></a> functions to get a
1104 list of supported destinations for the current user.
</p>
1105 <h3 class=
"function"><a name=
"cupsGetDests">cupsGetDests
</a></h3>
1106 <p class=
"description">Get the list of destinations from the default server.
</p>
1108 int cupsGetDests (
<br>
1109 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1111 <h4 class=
"parameters">Parameters
</h4>
1114 <dd class=
"description">Destinations
</dd>
1116 <h4 class=
"returnvalue">Return Value
</h4>
1117 <p class=
"description">Number of destinations
</p>
1118 <h4 class=
"discussion">Discussion
</h4>
1119 <p class=
"discussion">Starting with CUPS
1.2, the returned list of destinations include the
1120 printer-info, printer-is-accepting-jobs, printer-is-shared,
1121 printer-make-and-model, printer-state, printer-state-change-time,
1122 printer-state-reasons, and printer-type attributes as options.
<br>
1124 Use the
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> function to free the destination list and
1125 the
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> function to find a particular destination.
</p>
1126 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetDests2">cupsGetDests2
</a></h3>
1127 <p class=
"description">Get the list of destinations from the specified server.
</p>
1129 int cupsGetDests2 (
<br>
1130 http_t *http,
<br>
1131 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1133 <h4 class=
"parameters">Parameters
</h4>
1136 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1138 <dd class=
"description">Destinations
</dd>
1140 <h4 class=
"returnvalue">Return Value
</h4>
1141 <p class=
"description">Number of destinations
</p>
1142 <h4 class=
"discussion">Discussion
</h4>
1143 <p class=
"discussion">Starting with CUPS
1.2, the returned list of destinations include the
1144 printer-info, printer-is-accepting-jobs, printer-is-shared,
1145 printer-make-and-model, printer-state, printer-state-change-time,
1146 printer-state-reasons, and printer-type attributes as options.
<br>
1148 Use the
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> function to free the destination list and
1149 the
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> function to find a particular destination.
1152 <h3 class=
"function"><span class=
"info"> CUPS
1.1.20 </span><a name=
"cupsGetFd">cupsGetFd
</a></h3>
1153 <p class=
"description">Get a file from the server.
</p>
1155 http_status_t cupsGetFd (
<br>
1156 http_t *http,
<br>
1157 const char *resource,
<br>
1158 int fd
<br>
1160 <h4 class=
"parameters">Parameters
</h4>
1163 <dd class=
"description">HTTP connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1165 <dd class=
"description">Resource name
</dd>
1167 <dd class=
"description">File descriptor
</dd>
1169 <h4 class=
"returnvalue">Return Value
</h4>
1170 <p class=
"description">HTTP status
</p>
1171 <h4 class=
"discussion">Discussion
</h4>
1172 <p class=
"discussion">This function returns
<code>HTTP_OK
</code> when the file is successfully retrieved.
1175 <h3 class=
"function"><span class=
"info"> CUPS
1.1.20 </span><a name=
"cupsGetFile">cupsGetFile
</a></h3>
1176 <p class=
"description">Get a file from the server.
</p>
1178 http_status_t cupsGetFile (
<br>
1179 http_t *http,
<br>
1180 const char *resource,
<br>
1181 const char *filename
<br>
1183 <h4 class=
"parameters">Parameters
</h4>
1186 <dd class=
"description">HTTP connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1188 <dd class=
"description">Resource name
</dd>
1190 <dd class=
"description">Filename
</dd>
1192 <h4 class=
"returnvalue">Return Value
</h4>
1193 <p class=
"description">HTTP status
</p>
1194 <h4 class=
"discussion">Discussion
</h4>
1195 <p class=
"discussion">This function returns
<code>HTTP_OK
</code> when the file is successfully retrieved.
1198 <h3 class=
"function"><a name=
"cupsGetJobs">cupsGetJobs
</a></h3>
1199 <p class=
"description">Get the jobs from the default server.
</p>
1201 int cupsGetJobs (
<br>
1202 <a href=
"#cups_job_t">cups_job_t
</a> **jobs,
<br>
1203 const char *name,
<br>
1204 int myjobs,
<br>
1205 int whichjobs
<br>
1207 <h4 class=
"parameters">Parameters
</h4>
1210 <dd class=
"description">Job data
</dd>
1212 <dd class=
"description"><code>NULL
</code> = all destinations, otherwise show jobs for mydest
</dd>
1214 <dd class=
"description">0 = all users,
1 = mine
</dd>
1216 <dd class=
"description"><code>CUPS_WHICHJOBS_ALL
</code>,
<code>CUPS_WHICHJOBS_ACTIVE
</code>, or
<code>CUPS_WHICHJOBS_COMPLETED
</code></dd>
1218 <h4 class=
"returnvalue">Return Value
</h4>
1219 <p class=
"description">Number of jobs
</p>
1220 <h4 class=
"discussion">Discussion
</h4>
1221 <p class=
"discussion">A
"whichjobs
" value of
<code>CUPS_WHICHJOBS_ALL
</code> returns all jobs regardless
1222 of state, while
<code>CUPS_WHICHJOBS_ACTIVE
</code> returns jobs that are
1223 pending, processing, or held and
<code>CUPS_WHICHJOBS_COMPLETED
</code> returns
1224 jobs that are stopped, canceled, aborted, or completed.
</p>
1225 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetJobs2">cupsGetJobs2
</a></h3>
1226 <p class=
"description">Get the jobs from the specified server.
</p>
1228 int cupsGetJobs2 (
<br>
1229 http_t *http,
<br>
1230 <a href=
"#cups_job_t">cups_job_t
</a> **jobs,
<br>
1231 const char *name,
<br>
1232 int myjobs,
<br>
1233 int whichjobs
<br>
1235 <h4 class=
"parameters">Parameters
</h4>
1238 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1240 <dd class=
"description">Job data
</dd>
1242 <dd class=
"description"><code>NULL
</code> = all destinations, otherwise show jobs for mydest
</dd>
1244 <dd class=
"description">0 = all users,
1 = mine
</dd>
1246 <dd class=
"description"><code>CUPS_WHICHJOBS_ALL
</code>,
<code>CUPS_WHICHJOBS_ACTIVE
</code>, or
<code>CUPS_WHICHJOBS_COMPLETED
</code></dd>
1248 <h4 class=
"returnvalue">Return Value
</h4>
1249 <p class=
"description">Number of jobs
</p>
1250 <h4 class=
"discussion">Discussion
</h4>
1251 <p class=
"discussion">A
"whichjobs
" value of
<code>CUPS_WHICHJOBS_ALL
</code> returns all jobs regardless
1252 of state, while
<code>CUPS_WHICHJOBS_ACTIVE
</code> returns jobs that are
1253 pending, processing, or held and
<code>CUPS_WHICHJOBS_COMPLETED
</code> returns
1254 jobs that are stopped, canceled, aborted, or completed.
1257 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsGetNamedDest">cupsGetNamedDest
</a></h3>
1258 <p class=
"description">Get options for the named destination.
</p>
1260 <a href=
"#cups_dest_t">cups_dest_t
</a> *cupsGetNamedDest (
<br>
1261 http_t *http,
<br>
1262 const char *name,
<br>
1263 const char *instance
<br>
1265 <h4 class=
"parameters">Parameters
</h4>
1268 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1270 <dd class=
"description">Destination name or
<code>NULL
</code></dd>
1272 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1274 <h4 class=
"returnvalue">Return Value
</h4>
1275 <p class=
"description">Destination or
<code>NULL
</code></p>
1276 <h4 class=
"discussion">Discussion
</h4>
1277 <p class=
"discussion">This function is optimized for retrieving a single destination and should
1278 be used instead of
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> when you either
1279 know the name of the destination or want to print to the default destination.
1280 If
<code>NULL
</code> is returned, the destination does not exist or there is no
1281 default destination.
<br>
1283 If
"http
" is
<code>CUPS_HTTP_DEFAULT
</code>, the connection to the default print
1284 server will be used.
<br>
1286 If
"name
" is
<code>NULL
</code>, the default printer for the current user will be
1289 The returned destination must be freed using
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> with a
1290 "num_dests
" value of
1.
1293 <h3 class=
"function"><a name=
"cupsGetOption">cupsGetOption
</a></h3>
1294 <p class=
"description">Get an option value.
</p>
1296 const char *cupsGetOption (
<br>
1297 const char *name,
<br>
1298 int num_options,
<br>
1299 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1301 <h4 class=
"parameters">Parameters
</h4>
1304 <dd class=
"description">Name of option
</dd>
1305 <dt>num_options
</dt>
1306 <dd class=
"description">Number of options
</dd>
1308 <dd class=
"description">Options
</dd>
1310 <h4 class=
"returnvalue">Return Value
</h4>
1311 <p class=
"description">Option value or
<code>NULL
</code></p>
1312 <h3 class=
"function"><a name=
"cupsGetPPD">cupsGetPPD
</a></h3>
1313 <p class=
"description">Get the PPD file for a printer on the default server.
</p>
1315 const char *cupsGetPPD (
<br>
1316 const char *name
<br>
1318 <h4 class=
"parameters">Parameters
</h4>
1321 <dd class=
"description">Printer name
</dd>
1323 <h4 class=
"returnvalue">Return Value
</h4>
1324 <p class=
"description">Filename for PPD file
</p>
1325 <h4 class=
"discussion">Discussion
</h4>
1326 <p class=
"discussion">For classes,
<code>cupsGetPPD
</code> returns the PPD file for the first printer
1328 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetPPD2">cupsGetPPD2
</a></h3>
1329 <p class=
"description">Get the PPD file for a printer from the specified server.
</p>
1331 const char *cupsGetPPD2 (
<br>
1332 http_t *http,
<br>
1333 const char *name
<br>
1335 <h4 class=
"parameters">Parameters
</h4>
1338 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1340 <dd class=
"description">Printer name
</dd>
1342 <h4 class=
"returnvalue">Return Value
</h4>
1343 <p class=
"description">Filename for PPD file
</p>
1344 <h4 class=
"discussion">Discussion
</h4>
1345 <p class=
"discussion">For classes,
<code>cupsGetPPD2
</code> returns the PPD file for the first printer
1349 <h3 class=
"function"><a name=
"cupsGetPPD3">cupsGetPPD3
</a></h3>
1350 <p class=
"description">Get the PPD file for a printer on the specified
1351 server if it has changed.
</p>
1353 http_status_t cupsGetPPD3 (
<br>
1354 http_t *http,
<br>
1355 const char *name,
<br>
1356 time_t *modtime,
<br>
1357 char *buffer,
<br>
1358 size_t bufsize
<br>
1360 <h4 class=
"parameters">Parameters
</h4>
1363 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1365 <dd class=
"description">Printer name
</dd>
1367 <dd class=
"description">Modification time
</dd>
1369 <dd class=
"description">Filename buffer
</dd>
1371 <dd class=
"description">Size of filename buffer
</dd>
1373 <h4 class=
"returnvalue">Return Value
</h4>
1374 <p class=
"description">HTTP status
</p>
1375 <h4 class=
"discussion">Discussion
</h4>
1376 <p class=
"discussion">The
"modtime
" parameter contains the modification time of any
1377 locally-cached content and is updated with the time from the PPD file on
1380 The
"buffer
" parameter contains the local PPD filename. If it contains
1381 the empty string, a new temporary file is created, otherwise the existing
1382 file will be overwritten as needed.
<br>
1384 On success,
<code>HTTP_OK
</code> is returned for a new PPD file and
1385 <code>HTTP_NOT_MODIFIED
</code> if the existing PPD file is up-to-date. Any other
1386 status is an error.
<br>
1388 For classes,
<code>cupsGetPPD3
</code> returns the PPD file for the first printer
1390 <h3 class=
"function"><a name=
"cupsGetPassword">cupsGetPassword
</a></h3>
1391 <p class=
"description">Get a password from the user.
</p>
1393 const char *cupsGetPassword (
<br>
1394 const char *prompt
<br>
1396 <h4 class=
"parameters">Parameters
</h4>
1399 <dd class=
"description">Prompt string
</dd>
1401 <h4 class=
"returnvalue">Return Value
</h4>
1402 <p class=
"description">Password
</p>
1403 <h4 class=
"discussion">Discussion
</h4>
1404 <p class=
"discussion">Uses the current password callback function. Returns
<code>NULL
</code> if the
1405 user does not provide a password.
</p>
1406 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsGetPrinters">cupsGetPrinters
</a></h3>
1407 <p class=
"description">Get a list of printers from the default server.
</p>
1409 int cupsGetPrinters (
<br>
1410 char ***printers
<br>
1412 <h4 class=
"parameters">Parameters
</h4>
1415 <dd class=
"description">Printers
</dd>
1417 <h4 class=
"returnvalue">Return Value
</h4>
1418 <p class=
"description">Number of printers
</p>
1419 <h4 class=
"discussion">Discussion
</h4>
1420 <p class=
"discussion">This function is deprecated - use
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> instead.
1423 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsGetServerPPD">cupsGetServerPPD
</a></h3>
1424 <p class=
"description">Get an available PPD file from the server.
</p>
1426 char *cupsGetServerPPD (
<br>
1427 http_t *http,
<br>
1428 const char *name
<br>
1430 <h4 class=
"parameters">Parameters
</h4>
1433 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1435 <dd class=
"description">Name of PPD file (
"ppd-name
")
</dd>
1437 <h4 class=
"returnvalue">Return Value
</h4>
1438 <p class=
"description">Name of PPD file or
<code>NULL
</code> on error
</p>
1439 <h4 class=
"discussion">Discussion
</h4>
1440 <p class=
"discussion">This function returns the named PPD file from the server. The
1441 list of available PPDs is provided by the IPP
<code>CUPS_GET_PPDS
</code>
1444 You must remove (unlink) the PPD file when you are finished with
1445 it. The PPD filename is stored in a static location that will be
1446 overwritten on the next call to
<a href=
"#cupsGetPPD"><code>cupsGetPPD
</code></a>,
<a href=
"#cupsGetPPD2"><code>cupsGetPPD2
</code></a>,
1447 or
<a href=
"#cupsGetServerPPD"><code>cupsGetServerPPD
</code></a>.
1450 <h3 class=
"function"><a name=
"cupsLangDefault">cupsLangDefault
</a></h3>
1451 <p class=
"description">Return the default language.
</p>
1453 cups_lang_t *cupsLangDefault (void);
</p>
1454 <h4 class=
"returnvalue">Return Value
</h4>
1455 <p class=
"description">Language data
</p>
1456 <h3 class=
"function"><a name=
"cupsLangEncoding">cupsLangEncoding
</a></h3>
1457 <p class=
"description">Return the character encoding (us-ascii, etc.)
1458 for the given language.
</p>
1460 const char *cupsLangEncoding (
<br>
1461 cups_lang_t *lang
<br>
1463 <h4 class=
"parameters">Parameters
</h4>
1466 <dd class=
"description">Language data
</dd>
1468 <h4 class=
"returnvalue">Return Value
</h4>
1469 <p class=
"description">Character encoding
</p>
1470 <h3 class=
"function"><a name=
"cupsLangFlush">cupsLangFlush
</a></h3>
1471 <p class=
"description">Flush all language data out of the cache.
</p>
1473 void cupsLangFlush (void);
</p>
1474 <h3 class=
"function"><a name=
"cupsLangFree">cupsLangFree
</a></h3>
1475 <p class=
"description">Free language data.
</p>
1477 void cupsLangFree (
<br>
1478 cups_lang_t *lang
<br>
1480 <h4 class=
"parameters">Parameters
</h4>
1483 <dd class=
"description">Language to free
</dd>
1485 <h4 class=
"discussion">Discussion
</h4>
1486 <p class=
"discussion">This does not actually free anything; use
<a href=
"#cupsLangFlush"><code>cupsLangFlush
</code></a> for that.
</p>
1487 <h3 class=
"function"><a name=
"cupsLangGet">cupsLangGet
</a></h3>
1488 <p class=
"description">Get a language.
</p>
1490 cups_lang_t *cupsLangGet (
<br>
1491 const char *language
<br>
1493 <h4 class=
"parameters">Parameters
</h4>
1496 <dd class=
"description">Language or locale
</dd>
1498 <h4 class=
"returnvalue">Return Value
</h4>
1499 <p class=
"description">Language data
</p>
1500 <h3 class=
"function"><a name=
"cupsLastError">cupsLastError
</a></h3>
1501 <p class=
"description">Return the last IPP status code.
</p>
1503 ipp_status_t cupsLastError (void);
</p>
1504 <h4 class=
"returnvalue">Return Value
</h4>
1505 <p class=
"description">IPP status code from last request
</p>
1506 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsLastErrorString">cupsLastErrorString
</a></h3>
1507 <p class=
"description">Return the last IPP status-message.
</p>
1509 const char *cupsLastErrorString (void);
</p>
1510 <h4 class=
"returnvalue">Return Value
</h4>
1511 <p class=
"description">status-message text from last request
</p>
1512 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsNotifySubject">cupsNotifySubject
</a></h3>
1513 <p class=
"description">Return the subject for the given notification message.
</p>
1515 char *cupsNotifySubject (
<br>
1516 cups_lang_t *lang,
<br>
1517 ipp_t *event
<br>
1519 <h4 class=
"parameters">Parameters
</h4>
1522 <dd class=
"description">Language data
</dd>
1524 <dd class=
"description">Event data
</dd>
1526 <h4 class=
"returnvalue">Return Value
</h4>
1527 <p class=
"description">Subject string or
<code>NULL
</code></p>
1528 <h4 class=
"discussion">Discussion
</h4>
1529 <p class=
"discussion">The returned string must be freed by the caller using free().
1532 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsNotifyText">cupsNotifyText
</a></h3>
1533 <p class=
"description">Return the text for the given notification message.
</p>
1535 char *cupsNotifyText (
<br>
1536 cups_lang_t *lang,
<br>
1537 ipp_t *event
<br>
1539 <h4 class=
"parameters">Parameters
</h4>
1542 <dd class=
"description">Language data
</dd>
1544 <dd class=
"description">Event data
</dd>
1546 <h4 class=
"returnvalue">Return Value
</h4>
1547 <p class=
"description">Message text or
<code>NULL
</code></p>
1548 <h4 class=
"discussion">Discussion
</h4>
1549 <p class=
"discussion">The returned string must be freed by the caller using
<code>free
</code>.
1552 <h3 class=
"function"><a name=
"cupsParseOptions">cupsParseOptions
</a></h3>
1553 <p class=
"description">Parse options from a command-line argument.
</p>
1555 int cupsParseOptions (
<br>
1556 const char *arg,
<br>
1557 int num_options,
<br>
1558 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
1560 <h4 class=
"parameters">Parameters
</h4>
1563 <dd class=
"description">Argument to parse
</dd>
1564 <dt>num_options
</dt>
1565 <dd class=
"description">Number of options
</dd>
1567 <dd class=
"description">Options found
</dd>
1569 <h4 class=
"returnvalue">Return Value
</h4>
1570 <p class=
"description">Number of options found
</p>
1571 <h4 class=
"discussion">Discussion
</h4>
1572 <p class=
"discussion">This function converts space-delimited name/value pairs according
1573 to the PAPI text option ABNF specification. Collection values
1574 (
"name={a=... b=... c=...}
") are stored with the curley brackets
1575 intact - use
<code>cupsParseOptions
</code> on the value to extract the
1576 collection attributes.
</p>
1577 <h3 class=
"function"><a name=
"cupsPrintFile">cupsPrintFile
</a></h3>
1578 <p class=
"description">Print a file to a printer or class on the default server.
</p>
1580 int cupsPrintFile (
<br>
1581 const char *name,
<br>
1582 const char *filename,
<br>
1583 const char *title,
<br>
1584 int num_options,
<br>
1585 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1587 <h4 class=
"parameters">Parameters
</h4>
1590 <dd class=
"description">Printer or class name
</dd>
1592 <dd class=
"description">File to print
</dd>
1594 <dd class=
"description">Title of job
</dd>
1595 <dt>num_options
</dt>
1596 <dd class=
"description">Number of options
</dd>
1598 <dd class=
"description">Options
</dd>
1600 <h4 class=
"returnvalue">Return Value
</h4>
1601 <p class=
"description">Job ID or
0 on error
</p>
1602 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsPrintFile2">cupsPrintFile2
</a></h3>
1603 <p class=
"description">Print a file to a printer or class on the specified
1606 int cupsPrintFile2 (
<br>
1607 http_t *http,
<br>
1608 const char *name,
<br>
1609 const char *filename,
<br>
1610 const char *title,
<br>
1611 int num_options,
<br>
1612 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1614 <h4 class=
"parameters">Parameters
</h4>
1617 <dd class=
"description">HTTP connection
</dd>
1619 <dd class=
"description">Printer or class name
</dd>
1621 <dd class=
"description">File to print
</dd>
1623 <dd class=
"description">Title of job
</dd>
1624 <dt>num_options
</dt>
1625 <dd class=
"description">Number of options
</dd>
1627 <dd class=
"description">Options
</dd>
1629 <h4 class=
"returnvalue">Return Value
</h4>
1630 <p class=
"description">Job ID or
0 on error
</p>
1631 <h3 class=
"function"><a name=
"cupsPrintFiles">cupsPrintFiles
</a></h3>
1632 <p class=
"description">Print one or more files to a printer or class on the
1635 int cupsPrintFiles (
<br>
1636 const char *name,
<br>
1637 int num_files,
<br>
1638 const char **files,
<br>
1639 const char *title,
<br>
1640 int num_options,
<br>
1641 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1643 <h4 class=
"parameters">Parameters
</h4>
1646 <dd class=
"description">Printer or class name
</dd>
1648 <dd class=
"description">Number of files
</dd>
1650 <dd class=
"description">File(s) to print
</dd>
1652 <dd class=
"description">Title of job
</dd>
1653 <dt>num_options
</dt>
1654 <dd class=
"description">Number of options
</dd>
1656 <dd class=
"description">Options
</dd>
1658 <h4 class=
"returnvalue">Return Value
</h4>
1659 <p class=
"description">Job ID or
0 on error
</p>
1660 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsPrintFiles2">cupsPrintFiles2
</a></h3>
1661 <p class=
"description">Print one or more files to a printer or class on the
1662 specified server.
</p>
1664 int cupsPrintFiles2 (
<br>
1665 http_t *http,
<br>
1666 const char *name,
<br>
1667 int num_files,
<br>
1668 const char **files,
<br>
1669 const char *title,
<br>
1670 int num_options,
<br>
1671 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1673 <h4 class=
"parameters">Parameters
</h4>
1676 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1678 <dd class=
"description">Printer or class name
</dd>
1680 <dd class=
"description">Number of files
</dd>
1682 <dd class=
"description">File(s) to print
</dd>
1684 <dd class=
"description">Title of job
</dd>
1685 <dt>num_options
</dt>
1686 <dd class=
"description">Number of options
</dd>
1688 <dd class=
"description">Options
</dd>
1690 <h4 class=
"returnvalue">Return Value
</h4>
1691 <p class=
"description">Job ID or
0 on error
</p>
1692 <h3 class=
"function"><span class=
"info"> CUPS
1.1.20 </span><a name=
"cupsPutFd">cupsPutFd
</a></h3>
1693 <p class=
"description">Put a file on the server.
</p>
1695 http_status_t cupsPutFd (
<br>
1696 http_t *http,
<br>
1697 const char *resource,
<br>
1698 int fd
<br>
1700 <h4 class=
"parameters">Parameters
</h4>
1703 <dd class=
"description">HTTP connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1705 <dd class=
"description">Resource name
</dd>
1707 <dd class=
"description">File descriptor
</dd>
1709 <h4 class=
"returnvalue">Return Value
</h4>
1710 <p class=
"description">HTTP status
</p>
1711 <h4 class=
"discussion">Discussion
</h4>
1712 <p class=
"discussion">This function returns
<code>HTTP_CREATED
</code> when the file is stored
1716 <h3 class=
"function"><span class=
"info"> CUPS
1.1.20 </span><a name=
"cupsPutFile">cupsPutFile
</a></h3>
1717 <p class=
"description">Put a file on the server.
</p>
1719 http_status_t cupsPutFile (
<br>
1720 http_t *http,
<br>
1721 const char *resource,
<br>
1722 const char *filename
<br>
1724 <h4 class=
"parameters">Parameters
</h4>
1727 <dd class=
"description">HTTP connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1729 <dd class=
"description">Resource name
</dd>
1731 <dd class=
"description">Filename
</dd>
1733 <h4 class=
"returnvalue">Return Value
</h4>
1734 <p class=
"description">HTTP status
</p>
1735 <h4 class=
"discussion">Discussion
</h4>
1736 <p class=
"discussion">This function returns
<code>HTTP_CREATED
</code> when the file is stored
1740 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsRemoveDest">cupsRemoveDest
</a></h3>
1741 <p class=
"description">Remove a destination from the destination list.
</p>
1743 int cupsRemoveDest (
<br>
1744 const char *name,
<br>
1745 const char *instance,
<br>
1746 int num_dests,
<br>
1747 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1749 <h4 class=
"parameters">Parameters
</h4>
1752 <dd class=
"description">Destination name
</dd>
1754 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1756 <dd class=
"description">Number of destinations
</dd>
1758 <dd class=
"description">Destinations
</dd>
1760 <h4 class=
"returnvalue">Return Value
</h4>
1761 <p class=
"description">New number of destinations
</p>
1762 <h4 class=
"discussion">Discussion
</h4>
1763 <p class=
"discussion">Removing a destination/instance does not delete the class or printer
1764 queue, merely the lpoptions for that destination/instance. Use the
1765 <a href=
"#cupsSetDests"><code>cupsSetDests
</code></a> or
<a href=
"#cupsSetDests2"><code>cupsSetDests2
</code></a> functions to save the new
1766 options for the user.
1769 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsRemoveOption">cupsRemoveOption
</a></h3>
1770 <p class=
"description">Remove an option from an option array.
</p>
1772 int cupsRemoveOption (
<br>
1773 const char *name,
<br>
1774 int num_options,
<br>
1775 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
1777 <h4 class=
"parameters">Parameters
</h4>
1780 <dd class=
"description">Option name
</dd>
1781 <dt>num_options
</dt>
1782 <dd class=
"description">Current number of options
</dd>
1784 <dd class=
"description">Options
</dd>
1786 <h4 class=
"returnvalue">Return Value
</h4>
1787 <p class=
"description">New number of options
</p>
1788 <h3 class=
"function"><a name=
"cupsServer">cupsServer
</a></h3>
1789 <p class=
"description">Return the hostname/address of the default server.
</p>
1791 const char *cupsServer (void);
</p>
1792 <h4 class=
"returnvalue">Return Value
</h4>
1793 <p class=
"description">Server name
</p>
1794 <h4 class=
"discussion">Discussion
</h4>
1795 <p class=
"discussion">The returned value can be a fully-qualified hostname, a numeric
1796 IPv4 or IPv6 address, or a domain socket pathname.
</p>
1797 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsSetDefaultDest">cupsSetDefaultDest
</a></h3>
1798 <p class=
"description">Set the default destination.
</p>
1800 void cupsSetDefaultDest (
<br>
1801 const char *name,
<br>
1802 const char *instance,
<br>
1803 int num_dests,
<br>
1804 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1806 <h4 class=
"parameters">Parameters
</h4>
1809 <dd class=
"description">Destination name
</dd>
1811 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1813 <dd class=
"description">Number of destinations
</dd>
1815 <dd class=
"description">Destinations
</dd>
1817 <h3 class=
"function"><a name=
"cupsSetDests">cupsSetDests
</a></h3>
1818 <p class=
"description">Save the list of destinations for the default server.
</p>
1820 void cupsSetDests (
<br>
1821 int num_dests,
<br>
1822 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1824 <h4 class=
"parameters">Parameters
</h4>
1827 <dd class=
"description">Number of destinations
</dd>
1829 <dd class=
"description">Destinations
</dd>
1831 <h4 class=
"discussion">Discussion
</h4>
1832 <p class=
"discussion">This function saves the destinations to /etc/cups/lpoptions when run
1833 as root and ~/.cups/lpoptions when run as a normal user.
</p>
1834 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsSetDests2">cupsSetDests2
</a></h3>
1835 <p class=
"description">Save the list of destinations for the specified server.
</p>
1837 int cupsSetDests2 (
<br>
1838 http_t *http,
<br>
1839 int num_dests,
<br>
1840 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1842 <h4 class=
"parameters">Parameters
</h4>
1845 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1847 <dd class=
"description">Number of destinations
</dd>
1849 <dd class=
"description">Destinations
</dd>
1851 <h4 class=
"returnvalue">Return Value
</h4>
1852 <p class=
"description">0 on success, -
1 on error
</p>
1853 <h4 class=
"discussion">Discussion
</h4>
1854 <p class=
"discussion">This function saves the destinations to /etc/cups/lpoptions when run
1855 as root and ~/.cups/lpoptions when run as a normal user.
1858 <h3 class=
"function"><a name=
"cupsSetEncryption">cupsSetEncryption
</a></h3>
1859 <p class=
"description">Set the encryption preference.
</p>
1861 void cupsSetEncryption (
<br>
1862 http_encryption_t e
<br>
1864 <h4 class=
"parameters">Parameters
</h4>
1867 <dd class=
"description">New encryption preference
</dd>
1869 <h3 class=
"function"><a name=
"cupsSetPasswordCB">cupsSetPasswordCB
</a></h3>
1870 <p class=
"description">Set the password callback for CUPS.
</p>
1872 void cupsSetPasswordCB (
<br>
1873 <a href=
"#cups_password_cb_t">cups_password_cb_t
</a> cb
<br>
1875 <h4 class=
"parameters">Parameters
</h4>
1878 <dd class=
"description">Callback function
</dd>
1880 <h4 class=
"discussion">Discussion
</h4>
1881 <p class=
"discussion">Pass
<code>NULL
</code> to restore the default (console) password callback.
</p>
1882 <h3 class=
"function"><a name=
"cupsSetServer">cupsSetServer
</a></h3>
1883 <p class=
"description">Set the default server name.
</p>
1885 void cupsSetServer (
<br>
1886 const char *server
<br>
1888 <h4 class=
"parameters">Parameters
</h4>
1891 <dd class=
"description">Server name
</dd>
1893 <h4 class=
"discussion">Discussion
</h4>
1894 <p class=
"discussion">The
"server
" string can be a fully-qualified hostname, a numeric
1895 IPv4 or IPv6 address, or a domain socket pathname. Pass
<code>NULL
</code> to
1896 restore the default server name.
</p>
1897 <h3 class=
"function"><a name=
"cupsSetUser">cupsSetUser
</a></h3>
1898 <p class=
"description">Set the default user name.
</p>
1900 void cupsSetUser (
<br>
1901 const char *user
<br>
1903 <h4 class=
"parameters">Parameters
</h4>
1906 <dd class=
"description">User name
</dd>
1908 <h4 class=
"discussion">Discussion
</h4>
1909 <p class=
"discussion">Pass
<code>NULL
</code> to restore the default user name.
</p>
1910 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsStartDocument">cupsStartDocument
</a></h3>
1911 <p class=
"description">Add a document to a job created with cupsCreateJob().
</p>
1913 http_status_t cupsStartDocument (
<br>
1914 http_t *http,
<br>
1915 const char *name,
<br>
1916 int job_id,
<br>
1917 const char *docname,
<br>
1918 const char *format,
<br>
1919 int last_document
<br>
1921 <h4 class=
"parameters">Parameters
</h4>
1924 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1926 <dd class=
"description">Printer or class name
</dd>
1928 <dd class=
"description">Job ID from
<a href=
"#cupsCreateJob"><code>cupsCreateJob
</code></a></dd>
1930 <dd class=
"description">Name of document
</dd>
1932 <dd class=
"description">MIME type or
<code>CUPS_FORMAT_foo
</code></dd>
1933 <dt>last_document
</dt>
1934 <dd class=
"description">1 for last document in job,
0 otherwise
</dd>
1936 <h4 class=
"returnvalue">Return Value
</h4>
1937 <p class=
"description">HTTP status of request
</p>
1938 <h4 class=
"discussion">Discussion
</h4>
1939 <p class=
"discussion">Use
<a href=
"#cupsWriteRequestData"><code>cupsWriteRequestData
</code></a> to write data for the document and
1940 <a href=
"#cupsFinishDocument"><code>cupsFinishDocument
</code></a> to finish the document and get the submission status.
<br>
1942 The MIME type constants
<code>CUPS_FORMAT_AUTO
</code>,
<code>CUPS_FORMAT_PDF
</code>,
1943 <code>CUPS_FORMAT_POSTSCRIPT
</code>,
<code>CUPS_FORMAT_RAW
</code>, and
1944 <code>CUPS_FORMAT_TEXT
</code> are provided for the
"format
" argument, although
1945 any supported MIME type string can be supplied.
1948 <h3 class=
"function"><a name=
"cupsTempFd">cupsTempFd
</a></h3>
1949 <p class=
"description">Creates a temporary file.
</p>
1951 int cupsTempFd (
<br>
1952 char *filename,
<br>
1953 int len
<br>
1955 <h4 class=
"parameters">Parameters
</h4>
1958 <dd class=
"description">Pointer to buffer
</dd>
1960 <dd class=
"description">Size of buffer
</dd>
1962 <h4 class=
"returnvalue">Return Value
</h4>
1963 <p class=
"description">New file descriptor or -
1 on error
</p>
1964 <h4 class=
"discussion">Discussion
</h4>
1965 <p class=
"discussion">The temporary filename is returned in the filename buffer.
1966 The temporary file is opened for reading and writing.
</p>
1967 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsTempFile">cupsTempFile
</a></h3>
1968 <p class=
"description">Generates a temporary filename.
</p>
1970 char *cupsTempFile (
<br>
1971 char *filename,
<br>
1972 int len
<br>
1974 <h4 class=
"parameters">Parameters
</h4>
1977 <dd class=
"description">Pointer to buffer
</dd>
1979 <dd class=
"description">Size of buffer
</dd>
1981 <h4 class=
"returnvalue">Return Value
</h4>
1982 <p class=
"description">Filename or NULL on error
</p>
1983 <h4 class=
"discussion">Discussion
</h4>
1984 <p class=
"discussion">The temporary filename is returned in the filename buffer.
1985 This function is deprecated - use
<a href=
"#cupsTempFd"><code>cupsTempFd
</code></a> or
1986 <a href=
"#cupsTempFile2"><code>cupsTempFile2
</code></a> instead.
1989 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsTempFile2">cupsTempFile2
</a></h3>
1990 <p class=
"description">Creates a temporary CUPS file.
</p>
1992 cups_file_t *cupsTempFile2 (
<br>
1993 char *filename,
<br>
1994 int len
<br>
1996 <h4 class=
"parameters">Parameters
</h4>
1999 <dd class=
"description">Pointer to buffer
</dd>
2001 <dd class=
"description">Size of buffer
</dd>
2003 <h4 class=
"returnvalue">Return Value
</h4>
2004 <p class=
"description">CUPS file or NULL on error
</p>
2005 <h4 class=
"discussion">Discussion
</h4>
2006 <p class=
"discussion">The temporary filename is returned in the filename buffer.
2007 The temporary file is opened for writing.
2010 <h3 class=
"function"><a name=
"cupsUser">cupsUser
</a></h3>
2011 <p class=
"description">Return the current user's name.
</p>
2013 const char *cupsUser (void);
</p>
2014 <h4 class=
"returnvalue">Return Value
</h4>
2015 <p class=
"description">User name
</p>
2016 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
2017 <h3 class=
"typedef"><a name=
"cups_dest_t">cups_dest_t
</a></h3>
2018 <p class=
"description">Destination
</p>
2020 typedef struct
<a href=
"#cups_dest_s">cups_dest_s
</a> cups_dest_t;
2022 <h3 class=
"typedef"><a name=
"cups_job_t">cups_job_t
</a></h3>
2023 <p class=
"description">Job
</p>
2025 typedef struct
<a href=
"#cups_job_s">cups_job_s
</a> cups_job_t;
2027 <h3 class=
"typedef"><a name=
"cups_option_t">cups_option_t
</a></h3>
2028 <p class=
"description">Printer Options
</p>
2030 typedef struct
<a href=
"#cups_option_s">cups_option_s
</a> cups_option_t;
2032 <h3 class=
"typedef"><a name=
"cups_password_cb_t">cups_password_cb_t
</a></h3>
2033 <p class=
"description">Password callback
</p>
2035 typedef const char *(*cups_password_cb_t)(const char *);
2037 <h3 class=
"typedef"><a name=
"cups_ptype_t">cups_ptype_t
</a></h3>
2038 <p class=
"description">Printer type/capability bits
</p>
2040 typedef unsigned cups_ptype_t;
2042 <h2 class=
"title"><a name=
"STRUCTURES">Structures
</a></h2>
2043 <h3 class=
"struct"><a name=
"cups_dest_s">cups_dest_s
</a></h3>
2044 <p class=
"description">Destination
</p>
2045 <p class=
"code">struct cups_dest_s {
<br>
2046 char *name, *instance;
<br>
2047 int is_default;
<br>
2048 int num_options;
<br>
2049 <a href=
"#cups_option_t">cups_option_t
</a> *options;
<br>
2051 <h4 class=
"members">Members
</h4>
2054 <dd class=
"description">Local instance name or NULL
</dd>
2055 <dt>is_default
</dt>
2056 <dd class=
"description">Is this printer the default?
</dd>
2057 <dt>num_options
</dt>
2058 <dd class=
"description">Number of options
</dd>
2060 <dd class=
"description">Options
</dd>
2062 <h3 class=
"struct"><a name=
"cups_job_s">cups_job_s
</a></h3>
2063 <p class=
"description">Job
</p>
2064 <p class=
"code">struct cups_job_s {
<br>
2065 time_t completed_time;
<br>
2066 time_t creation_time;
<br>
2067 char *dest;
<br>
2068 char *format;
<br>
2069 int id;
<br>
2070 int priority;
<br>
2071 time_t processing_time;
<br>
2072 int size;
<br>
2073 ipp_jstate_t state;
<br>
2074 char *title;
<br>
2075 char *user;
<br>
2077 <h4 class=
"members">Members
</h4>
2079 <dt>completed_time
</dt>
2080 <dd class=
"description">Time the job was completed
</dd>
2081 <dt>creation_time
</dt>
2082 <dd class=
"description">Time the job was created
</dd>
2084 <dd class=
"description">Printer or class name
</dd>
2086 <dd class=
"description">Document format
</dd>
2088 <dd class=
"description">The job ID
</dd>
2090 <dd class=
"description">Priority (
1-
100)
</dd>
2091 <dt>processing_time
</dt>
2092 <dd class=
"description">Time the job was processed
</dd>
2094 <dd class=
"description">Size in kilobytes
</dd>
2096 <dd class=
"description">Job state
</dd>
2098 <dd class=
"description">Title/job name
</dd>
2100 <dd class=
"description">User the submitted the job
</dd>
2102 <h3 class=
"struct"><a name=
"cups_option_s">cups_option_s
</a></h3>
2103 <p class=
"description">Printer Options
</p>
2104 <p class=
"code">struct cups_option_s {
<br>
2105 char *name;
<br>
2106 char *value;
<br>
2108 <h4 class=
"members">Members
</h4>
2111 <dd class=
"description">Name of option
</dd>
2113 <dd class=
"description">Value of option
</dd>
2115 <h2 class=
"title"><a name=
"ENUMERATIONS">Constants
</a></h2>
2116 <h3 class=
"enumeration"><a name=
"cups_ptype_e">cups_ptype_e
</a></h3>
2117 <p class=
"description">Printer type/capability bit constants
</p>
2118 <h4 class=
"constants">Constants
</h4>
2120 <dt>CUPS_PRINTER_AUTHENTICATED
<span class=
"info"> CUPS
1.2 </span></dt>
2121 <dd class=
"description">Printer requires authentication
</dd>
2122 <dt>CUPS_PRINTER_BIND
</dt>
2123 <dd class=
"description">Can bind output
</dd>
2124 <dt>CUPS_PRINTER_BW
</dt>
2125 <dd class=
"description">Can do B
&W printing
</dd>
2126 <dt>CUPS_PRINTER_CLASS
</dt>
2127 <dd class=
"description">Printer class
</dd>
2128 <dt>CUPS_PRINTER_COLLATE
</dt>
2129 <dd class=
"description">Can collage copies
</dd>
2130 <dt>CUPS_PRINTER_COLOR
</dt>
2131 <dd class=
"description">Can do color printing
</dd>
2132 <dt>CUPS_PRINTER_COMMANDS
<span class=
"info"> CUPS
1.2 </span></dt>
2133 <dd class=
"description">Printer supports maintenance commands
</dd>
2134 <dt>CUPS_PRINTER_COPIES
</dt>
2135 <dd class=
"description">Can do copies
</dd>
2136 <dt>CUPS_PRINTER_COVER
</dt>
2137 <dd class=
"description">Can cover output
</dd>
2138 <dt>CUPS_PRINTER_DEFAULT
</dt>
2139 <dd class=
"description">Default printer on network
</dd>
2140 <dt>CUPS_PRINTER_DELETE
<span class=
"info"> CUPS
1.2 </span></dt>
2141 <dd class=
"description">Delete printer
</dd>
2142 <dt>CUPS_PRINTER_DISCOVERED
<span class=
"info"> CUPS
1.3 </span></dt>
2143 <dd class=
"description">Printer was automatically discovered and added
</dd>
2144 <dt>CUPS_PRINTER_DUPLEX
</dt>
2145 <dd class=
"description">Can do duplexing
</dd>
2146 <dt>CUPS_PRINTER_FAX
</dt>
2147 <dd class=
"description">Fax queue
</dd>
2148 <dt>CUPS_PRINTER_IMPLICIT
</dt>
2149 <dd class=
"description">Implicit class
</dd>
2150 <dt>CUPS_PRINTER_LARGE
</dt>
2151 <dd class=
"description">Can do D/E/A1/A0
</dd>
2152 <dt>CUPS_PRINTER_LOCAL
</dt>
2153 <dd class=
"description">Local printer or class
</dd>
2154 <dt>CUPS_PRINTER_MEDIUM
</dt>
2155 <dd class=
"description">Can do Tabloid/B/C/A3/A2
</dd>
2156 <dt>CUPS_PRINTER_NOT_SHARED
<span class=
"info"> CUPS
1.2 </span></dt>
2157 <dd class=
"description">Printer is not shared
</dd>
2158 <dt>CUPS_PRINTER_PUNCH
</dt>
2159 <dd class=
"description">Can punch output
</dd>
2160 <dt>CUPS_PRINTER_REJECTING
</dt>
2161 <dd class=
"description">Printer is rejecting jobs
</dd>
2162 <dt>CUPS_PRINTER_REMOTE
</dt>
2163 <dd class=
"description">Remote printer or class
</dd>
2164 <dt>CUPS_PRINTER_SMALL
</dt>
2165 <dd class=
"description">Can do Letter/Legal/A4
</dd>
2166 <dt>CUPS_PRINTER_SORT
</dt>
2167 <dd class=
"description">Can sort output
</dd>
2168 <dt>CUPS_PRINTER_STAPLE
</dt>
2169 <dd class=
"description">Can staple output
</dd>
2170 <dt>CUPS_PRINTER_VARIABLE
</dt>
2171 <dd class=
"description">Can do variable sizes
</dd>