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;
59 text-decoration: none;
62 A:link:hover, A:visited:hover, A:active {
63 text-decoration: underline;
71 border: solid thin #999999;
72 border-collapse: collapse;
88 border: solid thin #cccccc;
95 border-bottom: solid thin #999999;
104 caption-side: bottom;
124 border: thin solid #000000;
132 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
138 border-bottom: solid 2pt #000000;
156 font-family: monaco, courier, monospace;
165 border: solid thin #999999;
166 border-collapse: collapse;
171 DIV.summary TABLE TD, DIV.summary TABLE TH {
172 border: solid thin #999999;
178 DIV.summary TABLE THEAD TH {
182 /* API documentation styles... */
189 div.body h3, div.body h4, div.body h5 {
190 margin-bottom: 0.5em;
193 .class, .enumeration, .function, .struct, .typedef, .union {
194 border-bottom: solid thin #999999;
201 code, p.code, pre, ul.code li {
202 font-family: monaco, courier, monospace;
205 ul.code, ul.contents, ul.subcontents {
206 list-style-type: none;
216 ul.contents li ul.code, ul.contents li ul.subcontents {
229 margin-bottom: 0.5em;
232 /* This is just for the HTML files generated with the framedhelp target */
235 border: solid thin black;
244 div.contents ul.contents {
247 div.contents ul.subcontents li {
256 "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
258 CUPS API header for the Common UNIX Printing System (CUPS).
260 Copyright 2008 by Apple Inc.
262 These coded instructions, statements, and computer programs are the
263 property of Apple Inc. and are protected by Federal copyright
264 law. Distribution and use rights are outlined in the file "LICENSE.txt"
265 which should have been included with this file. If this file is
266 file is missing or damaged, see the license at "http://www.cups.org/".
269 <h1 class=
"title">CUPS API
</h1>
271 <div class='summary'
><table summary='General Information'
>
285 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a><br>
286 Programming:
<a href='api-array.html' target='_top'
>Array API
</a><br>
287 Programming:
<a href='api-filedir.html' target='_top'
>File and Directory APIs
</a><br>
288 Programming:
<a href='api-filter.html' target='_top'
>Filter and Backend Programming
</a><br>
289 Programming:
<a href='api-httpipp.html' target='_top'
>HTTP and IPP APIs
</a><br>
290 Programming:
<a href='api-ppd.html' target='_top'
>PPD API
</a><br>
291 Programming:
<a href='api-raster.html' target='_top'
>Raster API
</a></td>
295 <h2 class=
"title">Contents
</h2>
296 <ul class=
"contents">
298 <li><a href=
"#OVERVIEW">Overview
</a><ul class=
"subcontents">
299 <li><a href=
"#CLIENTS_AND_SERVERS">Clients and Servers
</a></li>
300 <li><a href=
"#PRINTERS_AND_CLASSES">Printers and Classes
</a></li>
301 <li><a href=
"#OPTIONS">Options
</a></li>
302 <li><a href=
"#PRINT_JOBS">Print Jobs
</a></li>
303 <li><a href=
"#ERROR_HANDLING">Error Handling
</a></li>
304 <li><a href=
"#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication
</a></li>
306 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
307 <li><a href=
"#cupsAddDest" title=
"Add a destination to the list of destinations.">cupsAddDest
</a></li>
308 <li><a href=
"#cupsAddOption" title=
"Add an option to an option array.">cupsAddOption
</a></li>
309 <li><a href=
"#cupsCancelJob" title=
"Cancel a print job on the default server.">cupsCancelJob
</a></li>
310 <li><a href=
"#cupsCancelJob2" title=
"Cancel or purge a print job.">cupsCancelJob2
</a></li>
311 <li><a href=
"#cupsCreateJob" title=
"Create an empty job for streaming.">cupsCreateJob
</a></li>
312 <li><a href=
"#cupsEncryption" title=
"Get the default encryption settings.">cupsEncryption
</a></li>
313 <li><a href=
"#cupsFinishDocument" title=
"Finish sending a document.">cupsFinishDocument
</a></li>
314 <li><a href=
"#cupsFreeDests" title=
"Free the memory used by the list of destinations.">cupsFreeDests
</a></li>
315 <li><a href=
"#cupsFreeJobs" title=
"Free memory used by job data.">cupsFreeJobs
</a></li>
316 <li><a href=
"#cupsFreeOptions" title=
"Free all memory used by options.">cupsFreeOptions
</a></li>
317 <li><a href=
"#cupsGetClasses" title=
"Get a list of printer classes from the default server.">cupsGetClasses
</a></li>
318 <li><a href=
"#cupsGetDefault" title=
"Get the default printer or class for the default server.">cupsGetDefault
</a></li>
319 <li><a href=
"#cupsGetDefault2" title=
"Get the default printer or class for the specified server.">cupsGetDefault2
</a></li>
320 <li><a href=
"#cupsGetDest" title=
"Get the named destination from the list.">cupsGetDest
</a></li>
321 <li><a href=
"#cupsGetDests" title=
"Get the list of destinations from the default server.">cupsGetDests
</a></li>
322 <li><a href=
"#cupsGetDests2" title=
"Get the list of destinations from the specified server.">cupsGetDests2
</a></li>
323 <li><a href=
"#cupsGetJobs" title=
"Get the jobs from the default server.">cupsGetJobs
</a></li>
324 <li><a href=
"#cupsGetJobs2" title=
"Get the jobs from the specified server.">cupsGetJobs2
</a></li>
325 <li><a href=
"#cupsGetNamedDest" title=
"Get options for the named destination.">cupsGetNamedDest
</a></li>
326 <li><a href=
"#cupsGetOption" title=
"Get an option value.">cupsGetOption
</a></li>
327 <li><a href=
"#cupsGetPPD" title=
"Get the PPD file for a printer on the default server.">cupsGetPPD
</a></li>
328 <li><a href=
"#cupsGetPPD2" title=
"Get the PPD file for a printer from the specified server.">cupsGetPPD2
</a></li>
329 <li><a href=
"#cupsGetPPD3" title=
"Get the PPD file for a printer on the specified
330 server if it has changed.">cupsGetPPD3
</a></li>
331 <li><a href=
"#cupsGetPassword" title=
"Get a password from the user.">cupsGetPassword
</a></li>
332 <li><a href=
"#cupsGetPrinters" title=
"Get a list of printers from the default server.">cupsGetPrinters
</a></li>
333 <li><a href=
"#cupsGetServerPPD" title=
"Get an available PPD file from the server.">cupsGetServerPPD
</a></li>
334 <li><a href=
"#cupsLangDefault" title=
"Return the default language.">cupsLangDefault
</a></li>
335 <li><a href=
"#cupsLangEncoding" title=
"Return the character encoding (us-ascii, etc.)
336 for the given language.">cupsLangEncoding
</a></li>
337 <li><a href=
"#cupsLangFlush" title=
"Flush all language data out of the cache.">cupsLangFlush
</a></li>
338 <li><a href=
"#cupsLangFree" title=
"Free language data.">cupsLangFree
</a></li>
339 <li><a href=
"#cupsLangGet" title=
"Get a language.">cupsLangGet
</a></li>
340 <li><a href=
"#cupsLastError" title=
"Return the last IPP status code.">cupsLastError
</a></li>
341 <li><a href=
"#cupsLastErrorString" title=
"Return the last IPP status-message.">cupsLastErrorString
</a></li>
342 <li><a href=
"#cupsNotifySubject" title=
"Return the subject for the given notification message.">cupsNotifySubject
</a></li>
343 <li><a href=
"#cupsNotifyText" title=
"Return the text for the given notification message.">cupsNotifyText
</a></li>
344 <li><a href=
"#cupsParseOptions" title=
"Parse options from a command-line argument.">cupsParseOptions
</a></li>
345 <li><a href=
"#cupsPrintFile" title=
"Print a file to a printer or class on the default server.">cupsPrintFile
</a></li>
346 <li><a href=
"#cupsPrintFile2" title=
"Print a file to a printer or class on the specified
347 server.">cupsPrintFile2
</a></li>
348 <li><a href=
"#cupsPrintFiles" title=
"Print one or more files to a printer or class on the
349 default server.">cupsPrintFiles
</a></li>
350 <li><a href=
"#cupsPrintFiles2" title=
"Print one or more files to a printer or class on the
351 specified server.">cupsPrintFiles2
</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_device_cb_t" title=
"Device callback ">cups_device_cb_t
</a></li>
371 <li><a href=
"#cups_job_t" title=
"Job">cups_job_t
</a></li>
372 <li><a href=
"#cups_option_t" title=
"Printer Options">cups_option_t
</a></li>
373 <li><a href=
"#cups_password_cb_t" title=
"Password callback">cups_password_cb_t
</a></li>
374 <li><a href=
"#cups_ptype_t" title=
"Printer type/capability bits">cups_ptype_t
</a></li>
376 <li><a href=
"#STRUCTURES">Structures
</a><ul class=
"code">
377 <li><a href=
"#cups_dest_s" title=
"Destination">cups_dest_s
</a></li>
378 <li><a href=
"#cups_job_s" title=
"Job">cups_job_s
</a></li>
379 <li><a href=
"#cups_option_s" title=
"Printer Options">cups_option_s
</a></li>
381 <li><a href=
"#ENUMERATIONS">Constants
</a><ul class=
"code">
382 <li><a href=
"#cups_ptype_e" title=
"Printer type/capability bit constants">cups_ptype_e
</a></li>
386 "$Id: api-cups.shtml 7337 2008-02-22 04:44:04Z mike $"
388 CUPS API introduction for the Common UNIX Printing System (CUPS).
390 Copyright 2007-2008 by Apple Inc.
391 Copyright 1997-2006 by Easy Software Products, all rights reserved.
393 These coded instructions, statements, and computer programs are the
394 property of Apple Inc. and are protected by Federal copyright
395 law. Distribution and use rights are outlined in the file "LICENSE.txt"
396 which should have been included with this file. If this file is
397 file is missing or damaged, see the license at "http://www.cups.org/".
400 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
402 <p>The CUPS API provides the convenience functions needed to support
403 applications, filters, printer drivers, and backends that need to interface
404 with the CUPS scheduler.
</p>
406 <h3><a name='CLIENTS_AND_SERVERS'
>Clients and Servers
</a></h3>
408 <p>CUPS is based on the Internet Printing Protocol (
"IPP"), which allows
409 clients (applications) to communicate with a server (the scheduler) to get a
410 list of printers, send print jobs, and so forth. You identify which server
411 you want to communicate with using a pointer to the opaque structure
412 <code>http_t
</code>. All of the examples in this document use the
413 <code>CUPS_HTTP_DEFAULT
</code> constant, referring to the default connection
414 to the scheduler. The
<a href='api-httpipp.html' target='_top'
>HTTP and IPP
415 APIs
</a> document provides more information on server connections.
</p>
417 <h3><a name='PRINTERS_AND_CLASSES'
>Printers and Classes
</a></h3>
419 <p>Printers and classes (collections of printers) are accessed through
420 the
<a href=
"#cups_dest_t"><code>cups_dest_t
</code></a> structure which
421 includes the name (
<code>name
</code>), instance (
<code>instance
</code> -
422 a way of selecting certain saved options/settings), and the options and
423 attributes associated with that destination (
<code>num_options
</code> and
424 <code>options
</code>). Destinations are created using the
425 <a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> function and freed
426 using the
<a href='#cupsFreeDests'
><code>cupsFreeDests
</code></a> function.
427 The
<a href='#cupsGetDest'
><code>cupsGetDest
</code></a> function finds a
428 specific destination for printing:
</p>
430 <pre class='example'
>
431 #include
<cups/cups.h
>
433 <a href='#cups_dest_t'
>cups_dest_t
</a> *dests;
434 int num_dests =
<a href='#cupsGetDests'
>cupsGetDests
</a>(
&dests);
435 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest =
<a href='#cupsGetDest'
>cupsGetDest
</a>(
"name", NULL, num_dests, dests);
437 /* do something wiith dest */
439 <a href='#cupsFreeDests'
>cupsFreeDests
</a>(num_dests, dests);
442 <p>Passing
<code>NULL
</code> to
443 <a href='#cupsGetDest'
><code>cupsGetDest
</code></a> for the destination name
444 will return the default destination. Similarly, passing a
<code>NULL
</code>
445 instance will return the default instance for that destination.
</p>
447 <div class='table'
><table summary='Table
1: Printer Attributes' width='
80%'
>
448 <caption>Table
1:
<a name='TABLE1'
>Printer Attributes
</a></caption>
451 <th>Attribute Name
</th>
457 <td>"auth-info-required"</td>
458 <td>The type of authentication required for printing to this
459 destination:
"none",
"username,password",
"domain,username,password",
460 or
"negotiate" (Kerberos)
</td>
463 <td>"printer-info"</td>
464 <td>The human-readable description of the destination such as
"My
468 <td>"printer-is-accepting-jobs"</td>
469 <td>"1" if the destination is accepting new jobs,
"0" if not.
</td>
472 <td>"printer-is-shared"</td>
473 <td>"1" if the destination is being shared with other computers,
"0" if
477 <td>"printer-location"</td>
478 <td>The human-readable location of the destination such as
"Lab 4".
</td>
481 <td>"printer-make-and-model"</td>
482 <td>The human-readable make and model of the destination such as
"HP
483 LaserJet 4000 Series".
</td>
486 <td>"printer-state"</td>
487 <td>"3" if the destination is idle,
"4" if the destination is printing
488 a job, and
"5" if the destination is stopped.
</td>
491 <td>"printer-state-change-time"</td>
492 <td>The UNIX time when the destination entered the current state.
</td>
495 <td>"printer-state-reasons"</td>
496 <td>Additional comma-delimited state keywords for the destination
497 such as
"media-tray-empty-error" and
"toner-low-warning".
</td>
500 <td>"printer-type"</td>
501 <td>The
<a href='#cups_printer_t'
><code>cups_printer_t
</code></a>
502 value associated with the destination.
</td>
507 <h3><a name='OPTIONS'
>Options
</a></h3>
509 <p>Options are stored in arrays of
510 <a href='#cups_option_t'
><code>cups_option_t
</code></a> structures. Each
511 option has a name (
<code>name
</code>) and value (
<code>value
</code>)
512 associated with it. The
<a href='#cups_dest_t'
><code>cups_dest_t
</code></a>
513 <code>num_options
</code> and
<code>options
</code> members contain the
514 default options for a particular destination, along with several informational
515 attributes about the destination as shown in
<a href='#TABLE1'
>Table
1</a>.
516 The
<a href='#cupsGetOption'
><code>cupsGetOption
</code></a> function gets
517 the value for the named option. For example, the following code lists the
518 available destinations and their human-readable descriptions:
</p>
520 <pre class='example'
>
521 #include
<cups/cups.h
>
523 <a href='#cups_dest_t'
>cups_dest_t
</a> *dests;
524 int num_dests =
<a href='#cupsGetDests'
>cupsGetDests
</a>(
&dests);
525 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
529 for (i = num_dests, dest = dests; i
> 0; i --, dest ++)
530 if (dest-
>instance == NULL)
532 value =
<a href='#cupsGetOption'
>cupsGetOption
</a>(
"printer-info", dest-
>num_options, dest-
>options);
533 printf(
"%s (%s)\n", dest-
>name, value ? value :
"no description");
536 <a href='#cupsFreeDests'
>cupsFreeDests
</a>(num_dests, dests);
539 <p>You can create your own option arrays using the
540 <a href='#cupsAddOption'
><code>cupsAddOption
</code></a> function, which
541 adds a single named option to an array:
</p>
543 <pre class='example'
>
544 #include
<cups/cups.h
>
547 <a href='#cups_option_t'
>cups_option_t
</a> *options = NULL;
549 /* The returned num_options value is updated as needed */
550 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"first",
"value", num_options,
&options);
552 /* This adds a second option value */
553 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"second",
"value", num_options,
&options);
555 /* This replaces the first option we added */
556 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(
"first",
"new value", num_options,
&options);
559 <p>Use a
<code>for
</code> loop to copy the options from a destination:
</p>
561 <pre class='example'
>
562 #include
<cups/cups.h
>
566 <a href='#cups_option_t'
>cups_option_t
</a> *options = NULL;
567 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
569 for (i =
0; i < dest-
>num_options; i ++)
570 num_options =
<a href='#cupsAddOption'
>cupsAddOption
</a>(dest-
>options[i].name, dest-
>options[i].value,
571 num_options,
&options);
574 <p>Use the
<a href='#cupsFreeOptions'
><code>cupsFreeOptions
</code></a>
575 function to free the options array when you are done using it:
</p>
577 <pre class='example'
>
578 <a href='#cupsFreeOptions'
>cupsFreeOptions
</a>(num_options, options);
581 <h3><a name='PRINT_JOBS'
>Print Jobs
</a></h3>
583 <p>Print jobs are identified by a locally-unique job ID number from
1 to
584 2<sup>31</sup>-
1 and have options and one or more files for printing to a
585 single destination. The
<a href='#cupsPrintFile'
><code>cupsPrintFile
</code></a>
586 function creates a new job with one file. The following code prints the CUPS
589 <pre class='example'
>
590 #include
<cups/cups.h
>
592 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
594 <a href='#cups_option_t'
>cups_option_t
</a> *options;
597 /* Print a single file */
598 job_id =
<a href='#cupsPrintFile'
>cupsPrintFile
</a>(dest-
>name,
"/usr/share/cups/data/testprint.ps",
599 "Test Print", num_options, options);
602 <p>The
<a href='#cupsPrintFiles'
><code>cupsPrintFiles
</code></a> function
603 creates a job with multiple files. The files are provided in a
604 <code>char *
</code> array:
</p>
606 <pre class='example'
>
607 #include
<cups/cups.h
>
609 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
611 <a href='#cups_option_t'
>cups_option_t
</a> *options;
613 char *files[
3] = {
"file1.pdf",
"file2.pdf",
"file3.pdf" };
615 /* Print three files */
616 job_id =
<a href='#cupsPrintFiles'
>cupsPrintFiles
</a>(dest-
>name,
3, files,
"Test Print", num_options, options);
619 <p>Finally, the
<a href='#cupsCreateJob'
><code>cupsCreateJob
</code></a>
620 function creates a new job with no files in it. Files are added using the
621 <a href='#cupsStartDocument'
><code>cupsStartDocument
</code></a>,
622 <a href='api-httpipp.html#cupsWriteRequestData'
><code>cupsWriteRequestData
</code></a>,
623 and
<a href='#cupsFinishDocument'
><code>cupsFinishDocument
</code></a> functions.
624 The following example creates a job with
10 text files for printing:
</p>
626 <pre class='example'
>
627 #include
<cups/cups.h
>
629 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
631 <a href='#cups_option_t'
>cups_option_t
</a> *options;
637 job_id =
<a href='#cupsCreateJob'
>cupsCreateJob
</a>(CUPS_HTTP_DEFAULT, dest-
>name,
"10 Text Files",
638 num_options, options);
640 /* If the job is created, add
10 files */
643 for (i =
1; i
<=
10; i ++)
645 snprintf(buffer, sizeof(buffer),
"file%d.txt", i);
647 <a href='#cupsStartDocument'
>cupsStartDocument
</a>(CUPS_HTTP_DEFAULT, dest-
>name, job_id, buffer,
648 CUPS_FORMAT_TEXT, i ==
10);
650 snprintf(buffer, sizeof(buffer),
658 /* cupsWriteRequestData can be called as many times as needed */
659 <a href='#cupsWriteRequestData'
>cupsWriteRequestData
</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
661 <a href='#cupsFinishDocument'
>cupsFinishDocument
</a>(CUPS_HTTP_DEFAULT, dest-
>name);
666 <p>Once you have created a job, you can monitor its status using the
667 <a href='#cupsGetJobs'
><code>cupsGetJobs
</code></a> function, which returns
668 an array of
<a href='#cups_job_t'
><code>cups_job_t
</code></a> structures.
669 Each contains the job ID (
<code>id
</code>), destination name
670 (
<code>dest
</code>), title (
<code>title
</code>), and other information
671 associated with the job. The job array is freed using the
672 <a href='#cupsFreeJobs'
><code>cupsFreeJobs
</code></a> function. The following
673 example monitors a specific job ID, showing the current job state once every
674 5 seconds until the job is completed:
</p>
676 <pre class='example'
>
677 #include
<cups/cups.h
>
679 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
682 <a href='#cups_job_t'
>cups_job_t
</a> *jobs;
684 ipp_jstate_t job_state = IPP_JOB_PENDING;
686 while (job_state
< IPP_JOB_STOPPED)
688 /* Get my jobs (
1) with any state (-
1) */
689 num_jobs =
<a href='#cupsGetJobs'
>cupsGetJobs
</a>(
&jobs, dest-
>name,
1, -
1);
691 /* Loop to find my job */
692 job_state = IPP_JOB_COMPLETED;
694 for (i =
0; i
< num_jobs; i ++)
695 if (jobs[i].id == job_id)
697 job_state = jobs[i].state;
701 /* Free the job array */
702 <a href='#cupsFreeJobs'
>cupsFreeJobs
</a>(num_jobs, jobs);
704 /* Show the current state */
707 case IPP_JOB_PENDING :
708 printf(
"Job %d is pending.\n", job_id);
711 printf(
"Job %d is held.\n", job_id);
713 case IPP_JOB_PROCESSING :
714 printf(
"Job %d is processing.\n", job_id);
716 case IPP_JOB_STOPPED :
717 printf(
"Job %d is stopped.\n", job_id);
719 case IPP_JOB_CANCELED :
720 printf(
"Job %d is canceled.\n", job_id);
722 case IPP_JOB_ABORTED :
723 printf(
"Job %d is aborted.\n", job_id);
725 case IPP_JOB_COMPLETED :
726 printf(
"Job %d is completed.\n", job_id);
730 /* Sleep if the job is not finished */
731 if (job_state
< IPP_JOB_STOPPED)
736 <p>To cancel a job, use the
737 <a href='#cupsCancelJob'
><code>cupsCancelJob
</code></a> function with the
740 <pre class='example'
>
741 #include
<cups/cups.h
>
743 <a href='#cups_dest_t'
>cups_dest_t
</a> *dest;
746 <a href='#cupsCancelJob'
>cupsCancelJob
</a>(dest-
>name, job_id);
749 <h3><a name='ERROR_HANDLING'
>Error Handling
</a></h3>
751 <p>If any of the CUPS API printing functions returns an error, the reason for
752 that error can be found by calling the
753 <a href='#cupsLastError'
><code>cupsLastError
</code></a> and
754 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> functions.
755 <a href='#cupsLastError'
><code>cupsLastError
</code></a> returns the last IPP
757 (
<a href='api-httpipp.html#ipp_status_t'
><code>ipp_status_t
</code></a>)
758 that was encountered, while
759 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> returns
760 a (localized) human-readable string that can be shown to the user. For example,
761 if any of the job creation functions returns a job ID of
0, you can use
762 <a href='#cupsLastErrorString'
><code>cupsLastErrorString
</code></a> to show
763 the reason why the job could not be created:
</p>
765 <pre class='example'
>
766 #include
<cups/cups.h
>
771 puts(cupsLastErrorString());
774 <h3><a name='PASSWORDS_AND_AUTHENTICATION'
>Passwords and Authentication
</a></h3>
776 <p>CUPS supports authentication of any request, including submission of print
777 jobs. The default mechanism for getting the username and password is to use the
778 login user and a password from the console.
</p>
780 <p>To support other types of applications, in particular Graphical User
781 Interfaces (
"GUIs"), the CUPS API provides functions to set the default
782 username and to register a callback function that returns a password string.
</p>
784 <p>The
<a href=
"#cupsSetPasswordCB"><code>cupsSetPasswordCB
</code></a>
785 function is used to set a password callback in your program. Only one
786 function can be used at any time.
</p>
788 <p>The
<a href=
"#cupsSetUser"><code>cupsSetUser
</code></a> function sets the
789 current username for authentication. This function can be called by your
790 password callback function to change the current username as needed.
</p>
792 <p>The following example shows a simple password callback that gets a
793 username and password from the user:
</p>
795 <pre class='example'
>
796 #include
<cups/cups.h
>
799 my_password_cb(const char *prompt)
806 /* Get a username from the user */
807 printf(
"Username: ");
808 if (fgets(user, sizeof(user), stdin) == NULL)
811 /* Strip the newline from the string and set the user */
812 user[strlen(user) -
1] = '\
0';
814 <a href='#cupsSetUser'
>cupsSetUser
</a>(user);
816 /* Use getpass() to ask for the password... */
817 return (getpass(
"Password: "));
820 <a href='#cupsSetPasswordCB'
>cupsSetPasswordCB
</a>(my_password_cb);
823 <p>Similarly, a GUI could display the prompt string in a window with input
824 fields for the username and password. The username should default to the
825 string returned by the
<a href=
"#cupsUser"><code>cupsUser
</code></a>
827 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
828 <h3 class=
"function"><a name=
"cupsAddDest">cupsAddDest
</a></h3>
829 <p class=
"description">Add a destination to the list of destinations.
</p>
831 int cupsAddDest (
<br>
832 const char *name,
<br>
833 const char *instance,
<br>
834 int num_dests,
<br>
835 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
837 <h4 class=
"parameters">Parameters
</h4>
840 <dd class=
"description">Destination name
</dd>
842 <dd class=
"description">Instance name or
<code>NULL
</code> for none/primary
</dd>
844 <dd class=
"description">Number of destinations
</dd>
846 <dd class=
"description">Destinations
</dd>
848 <h4 class=
"returnvalue">Return Value
</h4>
849 <p class=
"description">New number of destinations
</p>
850 <h4 class=
"discussion">Discussion
</h4>
851 <p class=
"discussion">This function cannot be used to add a new class or printer queue,
852 it only adds a new container of saved options for the named
853 destination or instance.
<br>
855 If the named destination already exists, the destination list is
856 returned unchanged. Adding a new instance of a destination creates
857 a copy of that destination's options.
<br>
859 Use the
<a href=
"#cupsSaveDests"><code>cupsSaveDests
</code></a> function to save the updated list of
860 destinations to the user's lpoptions file.
</p>
861 <h3 class=
"function"><a name=
"cupsAddOption">cupsAddOption
</a></h3>
862 <p class=
"description">Add an option to an option array.
</p>
864 int cupsAddOption (
<br>
865 const char *name,
<br>
866 const char *value,
<br>
867 int num_options,
<br>
868 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
870 <h4 class=
"parameters">Parameters
</h4>
873 <dd class=
"description">Name of option
</dd>
875 <dd class=
"description">Value of option
</dd>
877 <dd class=
"description">Number of options
</dd>
879 <dd class=
"description">Pointer to options
</dd>
881 <h4 class=
"returnvalue">Return Value
</h4>
882 <p class=
"description">Number of options
</p>
883 <h4 class=
"discussion">Discussion
</h4>
884 <p class=
"discussion">New option arrays can be initialized simply by passing
0 for the
885 "num_options
" parameter.
</p>
886 <h3 class=
"function"><a name=
"cupsCancelJob">cupsCancelJob
</a></h3>
887 <p class=
"description">Cancel a print job on the default server.
</p>
889 int cupsCancelJob (
<br>
890 const char *name,
<br>
891 int job_id
<br>
893 <h4 class=
"parameters">Parameters
</h4>
896 <dd class=
"description">Name of printer or class
</dd>
898 <dd class=
"description">Job ID,
<code>CUPS_JOBID_CURRENT
</code> for the current job, or
<code>CUPS_JOBID_ALL
</code> for all jobs
</dd>
900 <h4 class=
"returnvalue">Return Value
</h4>
901 <p class=
"description">1 on success,
0 on failure
</p>
902 <h4 class=
"discussion">Discussion
</h4>
903 <p class=
"discussion">Pass
<code>CUPS_JOBID_ALL
</code> to cancel all jobs or
<code>CUPS_JOBID_CURRENT
</code>
904 to cancel the current job on the named destination.
<br>
906 Use the
<a href=
"#cupsLastError"><code>cupsLastError
</code></a> and
<a href=
"#cupsLastErrorString"><code>cupsLastErrorString
</code></a> functions to get
907 the cause of any failure.
</p>
908 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsCancelJob2">cupsCancelJob2
</a></h3>
909 <p class=
"description">Cancel or purge a print job.
</p>
911 ipp_status_t cupsCancelJob2 (
<br>
912 http_t *http,
<br>
913 const char *name,
<br>
914 int job_id,
<br>
915 int purge
<br>
917 <h4 class=
"parameters">Parameters
</h4>
920 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
922 <dd class=
"description">Name of printer or class
</dd>
924 <dd class=
"description">Job ID,
<code>CUPS_JOBID_CURRENT
</code> for the current job, or
<code>CUPS_JOBID_ALL
</code> for all jobs
</dd>
926 <dd class=
"description">1 to purge,
0 to cancel
</dd>
928 <h4 class=
"returnvalue">Return Value
</h4>
929 <p class=
"description">IPP status
</p>
930 <h4 class=
"discussion">Discussion
</h4>
931 <p class=
"discussion">Canceled jobs remain in the job history while purged jobs are removed
932 from the job history.
<br>
934 Pass
<code>CUPS_JOBID_ALL
</code> to cancel all jobs or
<code>CUPS_JOBID_CURRENT
</code>
935 to cancel the current job on the named destination.
<br>
937 Use the
<a href=
"#cupsLastError"><code>cupsLastError
</code></a> and
<a href=
"#cupsLastErrorString"><code>cupsLastErrorString
</code></a> functions to get
938 the cause of any failure.
941 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsCreateJob">cupsCreateJob
</a></h3>
942 <p class=
"description">Create an empty job for streaming.
</p>
944 int cupsCreateJob (
<br>
945 http_t *http,
<br>
946 const char *name,
<br>
947 const char *title,
<br>
948 int num_options,
<br>
949 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
951 <h4 class=
"parameters">Parameters
</h4>
954 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
956 <dd class=
"description">Destination name
</dd>
958 <dd class=
"description">Title of job
</dd>
960 <dd class=
"description">Number of options
</dd>
962 <dd class=
"description">Options
</dd>
964 <h4 class=
"returnvalue">Return Value
</h4>
965 <p class=
"description">Job ID or
0 on error
</p>
966 <h4 class=
"discussion">Discussion
</h4>
967 <p class=
"discussion">Use this function when you want to stream print data using the
968 <a href=
"#cupsStartDocument"><code>cupsStartDocument
</code></a>,
<a href=
"#cupsWriteRequestData"><code>cupsWriteRequestData
</code></a>, and
969 <a href=
"#cupsFinishDocument"><code>cupsFinishDocument
</code></a> functions. If you have one or more files to
970 print, use the
<a href=
"#cupsPrintFile2"><code>cupsPrintFile2
</code></a> or
<a href=
"#cupsPrintFiles2"><code>cupsPrintFiles2
</code></a> function
974 <h3 class=
"function"><a name=
"cupsEncryption">cupsEncryption
</a></h3>
975 <p class=
"description">Get the default encryption settings.
</p>
977 http_encryption_t cupsEncryption (void);
</p>
978 <h4 class=
"returnvalue">Return Value
</h4>
979 <p class=
"description">Encryption settings
</p>
980 <h4 class=
"discussion">Discussion
</h4>
981 <p class=
"discussion">The default encryption setting comes from the CUPS_ENCRYPTION
982 environment variable, then the ~/.cups/client.conf file, and finally the
983 /etc/cups/client.conf file. If not set, the default is
984 <code>HTTP_ENCRYPT_IF_REQUESTED
</code>.
</p>
985 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsFinishDocument">cupsFinishDocument
</a></h3>
986 <p class=
"description">Finish sending a document.
</p>
988 ipp_status_t cupsFinishDocument (
<br>
989 http_t *http,
<br>
990 const char *name
<br>
992 <h4 class=
"parameters">Parameters
</h4>
995 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
997 <dd class=
"description">Destination name
</dd>
999 <h4 class=
"returnvalue">Return Value
</h4>
1000 <p class=
"description">Status of document submission
</p>
1001 <h4 class=
"discussion">Discussion
</h4>
1002 <p class=
"discussion">The document must have been started using
<a href=
"#cupsStartDocument"><code>cupsStartDocument
</code></a>.
1005 <h3 class=
"function"><a name=
"cupsFreeDests">cupsFreeDests
</a></h3>
1006 <p class=
"description">Free the memory used by the list of destinations.
</p>
1008 void cupsFreeDests (
<br>
1009 int num_dests,
<br>
1010 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1012 <h4 class=
"parameters">Parameters
</h4>
1015 <dd class=
"description">Number of destinations
</dd>
1017 <dd class=
"description">Destinations
</dd>
1019 <h3 class=
"function"><a name=
"cupsFreeJobs">cupsFreeJobs
</a></h3>
1020 <p class=
"description">Free memory used by job data.
</p>
1022 void cupsFreeJobs (
<br>
1023 int num_jobs,
<br>
1024 <a href=
"#cups_job_t">cups_job_t
</a> *jobs
<br>
1026 <h4 class=
"parameters">Parameters
</h4>
1029 <dd class=
"description">Number of jobs
</dd>
1031 <dd class=
"description">Jobs
</dd>
1033 <h3 class=
"function"><a name=
"cupsFreeOptions">cupsFreeOptions
</a></h3>
1034 <p class=
"description">Free all memory used by options.
</p>
1036 void cupsFreeOptions (
<br>
1037 int num_options,
<br>
1038 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1040 <h4 class=
"parameters">Parameters
</h4>
1042 <dt>num_options
</dt>
1043 <dd class=
"description">Number of options
</dd>
1045 <dd class=
"description">Pointer to options
</dd>
1047 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsGetClasses">cupsGetClasses
</a></h3>
1048 <p class=
"description">Get a list of printer classes from the default server.
</p>
1050 int cupsGetClasses (
<br>
1051 char ***classes
<br>
1053 <h4 class=
"parameters">Parameters
</h4>
1056 <dd class=
"description">Classes
</dd>
1058 <h4 class=
"returnvalue">Return Value
</h4>
1059 <p class=
"description">Number of classes
</p>
1060 <h4 class=
"discussion">Discussion
</h4>
1061 <p class=
"discussion">This function is deprecated - use
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> instead.
1064 <h3 class=
"function"><a name=
"cupsGetDefault">cupsGetDefault
</a></h3>
1065 <p class=
"description">Get the default printer or class for the default server.
</p>
1067 const char *cupsGetDefault (void);
</p>
1068 <h4 class=
"returnvalue">Return Value
</h4>
1069 <p class=
"description">Default printer or
<code>NULL
</code></p>
1070 <h4 class=
"discussion">Discussion
</h4>
1071 <p class=
"discussion">This function returns the default printer or class as defined by
1072 the LPDEST or PRINTER environment variables. If these environment
1073 variables are not set, the server default destination is returned.
1074 Applications should use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a>
1075 functions to get the user-defined default printer, as this function does
1076 not support the lpoptions-defined default printer.
</p>
1077 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetDefault2">cupsGetDefault2
</a></h3>
1078 <p class=
"description">Get the default printer or class for the specified server.
</p>
1080 const char *cupsGetDefault2 (
<br>
1081 http_t *http
<br>
1083 <h4 class=
"parameters">Parameters
</h4>
1086 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1088 <h4 class=
"returnvalue">Return Value
</h4>
1089 <p class=
"description">Default printer or
<code>NULL
</code></p>
1090 <h4 class=
"discussion">Discussion
</h4>
1091 <p class=
"discussion">This function returns the default printer or class as defined by
1092 the LPDEST or PRINTER environment variables. If these environment
1093 variables are not set, the server default destination is returned.
1094 Applications should use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a>
1095 functions to get the user-defined default printer, as this function does
1096 not support the lpoptions-defined default printer.
1099 <h3 class=
"function"><a name=
"cupsGetDest">cupsGetDest
</a></h3>
1100 <p class=
"description">Get the named destination from the list.
</p>
1102 <a href=
"#cups_dest_t">cups_dest_t
</a> *cupsGetDest (
<br>
1103 const char *name,
<br>
1104 const char *instance,
<br>
1105 int num_dests,
<br>
1106 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1108 <h4 class=
"parameters">Parameters
</h4>
1111 <dd class=
"description">Destination name or
<code>NULL
</code> for the default destination
</dd>
1113 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1115 <dd class=
"description">Number of destinations
</dd>
1117 <dd class=
"description">Destinations
</dd>
1119 <h4 class=
"returnvalue">Return Value
</h4>
1120 <p class=
"description">Destination pointer or
<code>NULL
</code></p>
1121 <h4 class=
"discussion">Discussion
</h4>
1122 <p class=
"discussion">Use the
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> or
<a href=
"#cupsGetDests2"><code>cupsGetDests2
</code></a> functions to get a
1123 list of supported destinations for the current user.
</p>
1124 <h3 class=
"function"><a name=
"cupsGetDests">cupsGetDests
</a></h3>
1125 <p class=
"description">Get the list of destinations from the default server.
</p>
1127 int cupsGetDests (
<br>
1128 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1130 <h4 class=
"parameters">Parameters
</h4>
1133 <dd class=
"description">Destinations
</dd>
1135 <h4 class=
"returnvalue">Return Value
</h4>
1136 <p class=
"description">Number of destinations
</p>
1137 <h4 class=
"discussion">Discussion
</h4>
1138 <p class=
"discussion">Starting with CUPS
1.2, the returned list of destinations include the
1139 printer-info, printer-is-accepting-jobs, printer-is-shared,
1140 printer-make-and-model, printer-state, printer-state-change-time,
1141 printer-state-reasons, and printer-type attributes as options.
<br>
1143 Use the
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> function to free the destination list and
1144 the
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> function to find a particular destination.
</p>
1145 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetDests2">cupsGetDests2
</a></h3>
1146 <p class=
"description">Get the list of destinations from the specified server.
</p>
1148 int cupsGetDests2 (
<br>
1149 http_t *http,
<br>
1150 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1152 <h4 class=
"parameters">Parameters
</h4>
1155 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1157 <dd class=
"description">Destinations
</dd>
1159 <h4 class=
"returnvalue">Return Value
</h4>
1160 <p class=
"description">Number of destinations
</p>
1161 <h4 class=
"discussion">Discussion
</h4>
1162 <p class=
"discussion">Starting with CUPS
1.2, the returned list of destinations include the
1163 printer-info, printer-is-accepting-jobs, printer-is-shared,
1164 printer-make-and-model, printer-state, printer-state-change-time,
1165 printer-state-reasons, and printer-type attributes as options.
<br>
1167 Use the
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> function to free the destination list and
1168 the
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> function to find a particular destination.
1171 <h3 class=
"function"><a name=
"cupsGetJobs">cupsGetJobs
</a></h3>
1172 <p class=
"description">Get the jobs from the default server.
</p>
1174 int cupsGetJobs (
<br>
1175 <a href=
"#cups_job_t">cups_job_t
</a> **jobs,
<br>
1176 const char *name,
<br>
1177 int myjobs,
<br>
1178 int whichjobs
<br>
1180 <h4 class=
"parameters">Parameters
</h4>
1183 <dd class=
"description">Job data
</dd>
1185 <dd class=
"description"><code>NULL
</code> = all destinations, otherwise show jobs for named destination
</dd>
1187 <dd class=
"description">0 = all users,
1 = mine
</dd>
1189 <dd class=
"description"><code>CUPS_WHICHJOBS_ALL
</code>,
<code>CUPS_WHICHJOBS_ACTIVE
</code>, or
<code>CUPS_WHICHJOBS_COMPLETED
</code></dd>
1191 <h4 class=
"returnvalue">Return Value
</h4>
1192 <p class=
"description">Number of jobs
</p>
1193 <h4 class=
"discussion">Discussion
</h4>
1194 <p class=
"discussion">A
"whichjobs
" value of
<code>CUPS_WHICHJOBS_ALL
</code> returns all jobs regardless
1195 of state, while
<code>CUPS_WHICHJOBS_ACTIVE
</code> returns jobs that are
1196 pending, processing, or held and
<code>CUPS_WHICHJOBS_COMPLETED
</code> returns
1197 jobs that are stopped, canceled, aborted, or completed.
</p>
1198 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetJobs2">cupsGetJobs2
</a></h3>
1199 <p class=
"description">Get the jobs from the specified server.
</p>
1201 int cupsGetJobs2 (
<br>
1202 http_t *http,
<br>
1203 <a href=
"#cups_job_t">cups_job_t
</a> **jobs,
<br>
1204 const char *name,
<br>
1205 int myjobs,
<br>
1206 int whichjobs
<br>
1208 <h4 class=
"parameters">Parameters
</h4>
1211 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1213 <dd class=
"description">Job data
</dd>
1215 <dd class=
"description"><code>NULL
</code> = all destinations, otherwise show jobs for named destination
</dd>
1217 <dd class=
"description">0 = all users,
1 = mine
</dd>
1219 <dd class=
"description"><code>CUPS_WHICHJOBS_ALL
</code>,
<code>CUPS_WHICHJOBS_ACTIVE
</code>, or
<code>CUPS_WHICHJOBS_COMPLETED
</code></dd>
1221 <h4 class=
"returnvalue">Return Value
</h4>
1222 <p class=
"description">Number of jobs
</p>
1223 <h4 class=
"discussion">Discussion
</h4>
1224 <p class=
"discussion">A
"whichjobs
" value of
<code>CUPS_WHICHJOBS_ALL
</code> returns all jobs regardless
1225 of state, while
<code>CUPS_WHICHJOBS_ACTIVE
</code> returns jobs that are
1226 pending, processing, or held and
<code>CUPS_WHICHJOBS_COMPLETED
</code> returns
1227 jobs that are stopped, canceled, aborted, or completed.
1230 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsGetNamedDest">cupsGetNamedDest
</a></h3>
1231 <p class=
"description">Get options for the named destination.
</p>
1233 <a href=
"#cups_dest_t">cups_dest_t
</a> *cupsGetNamedDest (
<br>
1234 http_t *http,
<br>
1235 const char *name,
<br>
1236 const char *instance
<br>
1238 <h4 class=
"parameters">Parameters
</h4>
1241 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1243 <dd class=
"description">Destination name or
<code>NULL
</code> for the default destination
</dd>
1245 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1247 <h4 class=
"returnvalue">Return Value
</h4>
1248 <p class=
"description">Destination or
<code>NULL
</code></p>
1249 <h4 class=
"discussion">Discussion
</h4>
1250 <p class=
"discussion">This function is optimized for retrieving a single destination and should
1251 be used instead of
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> and
<a href=
"#cupsGetDest"><code>cupsGetDest
</code></a> when you either
1252 know the name of the destination or want to print to the default destination.
1253 If
<code>NULL
</code> is returned, the destination does not exist or there is no
1254 default destination.
<br>
1256 If
"http
" is
<code>CUPS_HTTP_DEFAULT
</code>, the connection to the default print
1257 server will be used.
<br>
1259 If
"name
" is
<code>NULL
</code>, the default printer for the current user will be
1262 The returned destination must be freed using
<a href=
"#cupsFreeDests"><code>cupsFreeDests
</code></a> with a
1263 "num_dests
" value of
1.
1266 <h3 class=
"function"><a name=
"cupsGetOption">cupsGetOption
</a></h3>
1267 <p class=
"description">Get an option value.
</p>
1269 const char *cupsGetOption (
<br>
1270 const char *name,
<br>
1271 int num_options,
<br>
1272 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1274 <h4 class=
"parameters">Parameters
</h4>
1277 <dd class=
"description">Name of option
</dd>
1278 <dt>num_options
</dt>
1279 <dd class=
"description">Number of options
</dd>
1281 <dd class=
"description">Options
</dd>
1283 <h4 class=
"returnvalue">Return Value
</h4>
1284 <p class=
"description">Option value or
<code>NULL
</code></p>
1285 <h3 class=
"function"><a name=
"cupsGetPPD">cupsGetPPD
</a></h3>
1286 <p class=
"description">Get the PPD file for a printer on the default server.
</p>
1288 const char *cupsGetPPD (
<br>
1289 const char *name
<br>
1291 <h4 class=
"parameters">Parameters
</h4>
1294 <dd class=
"description">Destination name
</dd>
1296 <h4 class=
"returnvalue">Return Value
</h4>
1297 <p class=
"description">Filename for PPD file
</p>
1298 <h4 class=
"discussion">Discussion
</h4>
1299 <p class=
"discussion">For classes,
<code>cupsGetPPD
</code> returns the PPD file for the first printer
1302 The returned filename is stored in a static buffer and is overwritten with
1303 each call to
<code>cupsGetPPD
</code> or
<a href=
"#cupsGetPPD2"><code>cupsGetPPD2
</code></a>.
</p>
1304 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsGetPPD2">cupsGetPPD2
</a></h3>
1305 <p class=
"description">Get the PPD file for a printer from the specified server.
</p>
1307 const char *cupsGetPPD2 (
<br>
1308 http_t *http,
<br>
1309 const char *name
<br>
1311 <h4 class=
"parameters">Parameters
</h4>
1314 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1316 <dd class=
"description">Destination name
</dd>
1318 <h4 class=
"returnvalue">Return Value
</h4>
1319 <p class=
"description">Filename for PPD file
</p>
1320 <h4 class=
"discussion">Discussion
</h4>
1321 <p class=
"discussion">For classes,
<code>cupsGetPPD2
</code> returns the PPD file for the first printer
1324 The returned filename is stored in a static buffer and is overwritten with
1325 each call to
<a href=
"#cupsGetPPD"><code>cupsGetPPD
</code></a> or
<code>cupsGetPPD2
</code>.
1328 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsGetPPD3">cupsGetPPD3
</a></h3>
1329 <p class=
"description">Get the PPD file for a printer on the specified
1330 server if it has changed.
</p>
1332 http_status_t cupsGetPPD3 (
<br>
1333 http_t *http,
<br>
1334 const char *name,
<br>
1335 time_t *modtime,
<br>
1336 char *buffer,
<br>
1337 size_t bufsize
<br>
1339 <h4 class=
"parameters">Parameters
</h4>
1342 <dd class=
"description">HTTP connection or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1344 <dd class=
"description">Destination name
</dd>
1346 <dd class=
"description">Modification time
</dd>
1348 <dd class=
"description">Filename buffer
</dd>
1350 <dd class=
"description">Size of filename buffer
</dd>
1352 <h4 class=
"returnvalue">Return Value
</h4>
1353 <p class=
"description">HTTP status
</p>
1354 <h4 class=
"discussion">Discussion
</h4>
1355 <p class=
"discussion">The
"modtime
" parameter contains the modification time of any
1356 locally-cached content and is updated with the time from the PPD file on
1359 The
"buffer
" parameter contains the local PPD filename. If it contains
1360 the empty string, a new temporary file is created, otherwise the existing
1361 file will be overwritten as needed.
<br>
1363 On success,
<code>HTTP_OK
</code> is returned for a new PPD file and
1364 <code>HTTP_NOT_MODIFIED
</code> if the existing PPD file is up-to-date. Any other
1365 status is an error.
<br>
1367 For classes,
<code>cupsGetPPD3
</code> returns the PPD file for the first printer
1371 <h3 class=
"function"><a name=
"cupsGetPassword">cupsGetPassword
</a></h3>
1372 <p class=
"description">Get a password from the user.
</p>
1374 const char *cupsGetPassword (
<br>
1375 const char *prompt
<br>
1377 <h4 class=
"parameters">Parameters
</h4>
1380 <dd class=
"description">Prompt string
</dd>
1382 <h4 class=
"returnvalue">Return Value
</h4>
1383 <p class=
"description">Password
</p>
1384 <h4 class=
"discussion">Discussion
</h4>
1385 <p class=
"discussion">Uses the current password callback function. Returns
<code>NULL
</code> if the
1386 user does not provide a password.
</p>
1387 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsGetPrinters">cupsGetPrinters
</a></h3>
1388 <p class=
"description">Get a list of printers from the default server.
</p>
1390 int cupsGetPrinters (
<br>
1391 char ***printers
<br>
1393 <h4 class=
"parameters">Parameters
</h4>
1396 <dd class=
"description">Printers
</dd>
1398 <h4 class=
"returnvalue">Return Value
</h4>
1399 <p class=
"description">Number of printers
</p>
1400 <h4 class=
"discussion">Discussion
</h4>
1401 <p class=
"discussion">This function is deprecated - use
<a href=
"#cupsGetDests"><code>cupsGetDests
</code></a> instead.
1404 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsGetServerPPD">cupsGetServerPPD
</a></h3>
1405 <p class=
"description">Get an available PPD file from the server.
</p>
1407 char *cupsGetServerPPD (
<br>
1408 http_t *http,
<br>
1409 const char *name
<br>
1411 <h4 class=
"parameters">Parameters
</h4>
1414 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1416 <dd class=
"description">Name of PPD file (
"ppd-name
")
</dd>
1418 <h4 class=
"returnvalue">Return Value
</h4>
1419 <p class=
"description">Name of PPD file or
<code>NULL
</code> on error
</p>
1420 <h4 class=
"discussion">Discussion
</h4>
1421 <p class=
"discussion">This function returns the named PPD file from the server. The
1422 list of available PPDs is provided by the IPP
<code>CUPS_GET_PPDS
</code>
1425 You must remove (unlink) the PPD file when you are finished with
1426 it. The PPD filename is stored in a static location that will be
1427 overwritten on the next call to
<a href=
"#cupsGetPPD"><code>cupsGetPPD
</code></a>,
<a href=
"#cupsGetPPD2"><code>cupsGetPPD2
</code></a>,
1428 or
<a href=
"#cupsGetServerPPD"><code>cupsGetServerPPD
</code></a>.
1431 <h3 class=
"function"><a name=
"cupsLangDefault">cupsLangDefault
</a></h3>
1432 <p class=
"description">Return the default language.
</p>
1434 cups_lang_t *cupsLangDefault (void);
</p>
1435 <h4 class=
"returnvalue">Return Value
</h4>
1436 <p class=
"description">Language data
</p>
1437 <h3 class=
"function"><a name=
"cupsLangEncoding">cupsLangEncoding
</a></h3>
1438 <p class=
"description">Return the character encoding (us-ascii, etc.)
1439 for the given language.
</p>
1441 const char *cupsLangEncoding (
<br>
1442 cups_lang_t *lang
<br>
1444 <h4 class=
"parameters">Parameters
</h4>
1447 <dd class=
"description">Language data
</dd>
1449 <h4 class=
"returnvalue">Return Value
</h4>
1450 <p class=
"description">Character encoding
</p>
1451 <h3 class=
"function"><a name=
"cupsLangFlush">cupsLangFlush
</a></h3>
1452 <p class=
"description">Flush all language data out of the cache.
</p>
1454 void cupsLangFlush (void);
</p>
1455 <h3 class=
"function"><a name=
"cupsLangFree">cupsLangFree
</a></h3>
1456 <p class=
"description">Free language data.
</p>
1458 void cupsLangFree (
<br>
1459 cups_lang_t *lang
<br>
1461 <h4 class=
"parameters">Parameters
</h4>
1464 <dd class=
"description">Language to free
</dd>
1466 <h4 class=
"discussion">Discussion
</h4>
1467 <p class=
"discussion">This does not actually free anything; use
<a href=
"#cupsLangFlush"><code>cupsLangFlush
</code></a> for that.
</p>
1468 <h3 class=
"function"><a name=
"cupsLangGet">cupsLangGet
</a></h3>
1469 <p class=
"description">Get a language.
</p>
1471 cups_lang_t *cupsLangGet (
<br>
1472 const char *language
<br>
1474 <h4 class=
"parameters">Parameters
</h4>
1477 <dd class=
"description">Language or locale
</dd>
1479 <h4 class=
"returnvalue">Return Value
</h4>
1480 <p class=
"description">Language data
</p>
1481 <h3 class=
"function"><a name=
"cupsLastError">cupsLastError
</a></h3>
1482 <p class=
"description">Return the last IPP status code.
</p>
1484 ipp_status_t cupsLastError (void);
</p>
1485 <h4 class=
"returnvalue">Return Value
</h4>
1486 <p class=
"description">IPP status code from last request
</p>
1487 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsLastErrorString">cupsLastErrorString
</a></h3>
1488 <p class=
"description">Return the last IPP status-message.
</p>
1490 const char *cupsLastErrorString (void);
</p>
1491 <h4 class=
"returnvalue">Return Value
</h4>
1492 <p class=
"description">status-message text from last request
</p>
1493 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsNotifySubject">cupsNotifySubject
</a></h3>
1494 <p class=
"description">Return the subject for the given notification message.
</p>
1496 char *cupsNotifySubject (
<br>
1497 cups_lang_t *lang,
<br>
1498 ipp_t *event
<br>
1500 <h4 class=
"parameters">Parameters
</h4>
1503 <dd class=
"description">Language data
</dd>
1505 <dd class=
"description">Event data
</dd>
1507 <h4 class=
"returnvalue">Return Value
</h4>
1508 <p class=
"description">Subject string or
<code>NULL
</code></p>
1509 <h4 class=
"discussion">Discussion
</h4>
1510 <p class=
"discussion">The returned string must be freed by the caller using
<code>free
</code>.
1513 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsNotifyText">cupsNotifyText
</a></h3>
1514 <p class=
"description">Return the text for the given notification message.
</p>
1516 char *cupsNotifyText (
<br>
1517 cups_lang_t *lang,
<br>
1518 ipp_t *event
<br>
1520 <h4 class=
"parameters">Parameters
</h4>
1523 <dd class=
"description">Language data
</dd>
1525 <dd class=
"description">Event data
</dd>
1527 <h4 class=
"returnvalue">Return Value
</h4>
1528 <p class=
"description">Message text or
<code>NULL
</code></p>
1529 <h4 class=
"discussion">Discussion
</h4>
1530 <p class=
"discussion">The returned string must be freed by the caller using
<code>free
</code>.
1533 <h3 class=
"function"><a name=
"cupsParseOptions">cupsParseOptions
</a></h3>
1534 <p class=
"description">Parse options from a command-line argument.
</p>
1536 int cupsParseOptions (
<br>
1537 const char *arg,
<br>
1538 int num_options,
<br>
1539 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
1541 <h4 class=
"parameters">Parameters
</h4>
1544 <dd class=
"description">Argument to parse
</dd>
1545 <dt>num_options
</dt>
1546 <dd class=
"description">Number of options
</dd>
1548 <dd class=
"description">Options found
</dd>
1550 <h4 class=
"returnvalue">Return Value
</h4>
1551 <p class=
"description">Number of options found
</p>
1552 <h4 class=
"discussion">Discussion
</h4>
1553 <p class=
"discussion">This function converts space-delimited name/value pairs according
1554 to the PAPI text option ABNF specification. Collection values
1555 (
"name={a=... b=... c=...}
") are stored with the curley brackets
1556 intact - use
<code>cupsParseOptions
</code> on the value to extract the
1557 collection attributes.
</p>
1558 <h3 class=
"function"><a name=
"cupsPrintFile">cupsPrintFile
</a></h3>
1559 <p class=
"description">Print a file to a printer or class on the default server.
</p>
1561 int cupsPrintFile (
<br>
1562 const char *name,
<br>
1563 const char *filename,
<br>
1564 const char *title,
<br>
1565 int num_options,
<br>
1566 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1568 <h4 class=
"parameters">Parameters
</h4>
1571 <dd class=
"description">Destination name
</dd>
1573 <dd class=
"description">File to print
</dd>
1575 <dd class=
"description">Title of job
</dd>
1576 <dt>num_options
</dt>
1577 <dd class=
"description">Number of options
</dd>
1579 <dd class=
"description">Options
</dd>
1581 <h4 class=
"returnvalue">Return Value
</h4>
1582 <p class=
"description">Job ID or
0 on error
</p>
1583 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsPrintFile2">cupsPrintFile2
</a></h3>
1584 <p class=
"description">Print a file to a printer or class on the specified
1587 int cupsPrintFile2 (
<br>
1588 http_t *http,
<br>
1589 const char *name,
<br>
1590 const char *filename,
<br>
1591 const char *title,
<br>
1592 int num_options,
<br>
1593 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1595 <h4 class=
"parameters">Parameters
</h4>
1598 <dd class=
"description">Connection to server
</dd>
1600 <dd class=
"description">Destination name
</dd>
1602 <dd class=
"description">File to print
</dd>
1604 <dd class=
"description">Title of job
</dd>
1605 <dt>num_options
</dt>
1606 <dd class=
"description">Number of options
</dd>
1608 <dd class=
"description">Options
</dd>
1610 <h4 class=
"returnvalue">Return Value
</h4>
1611 <p class=
"description">Job ID or
0 on error
</p>
1612 <h3 class=
"function"><a name=
"cupsPrintFiles">cupsPrintFiles
</a></h3>
1613 <p class=
"description">Print one or more files to a printer or class on the
1616 int cupsPrintFiles (
<br>
1617 const char *name,
<br>
1618 int num_files,
<br>
1619 const char **files,
<br>
1620 const char *title,
<br>
1621 int num_options,
<br>
1622 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1624 <h4 class=
"parameters">Parameters
</h4>
1627 <dd class=
"description">Destination name
</dd>
1629 <dd class=
"description">Number of files
</dd>
1631 <dd class=
"description">File(s) to print
</dd>
1633 <dd class=
"description">Title of job
</dd>
1634 <dt>num_options
</dt>
1635 <dd class=
"description">Number of options
</dd>
1637 <dd class=
"description">Options
</dd>
1639 <h4 class=
"returnvalue">Return Value
</h4>
1640 <p class=
"description">Job ID or
0 on error
</p>
1641 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsPrintFiles2">cupsPrintFiles2
</a></h3>
1642 <p class=
"description">Print one or more files to a printer or class on the
1643 specified server.
</p>
1645 int cupsPrintFiles2 (
<br>
1646 http_t *http,
<br>
1647 const char *name,
<br>
1648 int num_files,
<br>
1649 const char **files,
<br>
1650 const char *title,
<br>
1651 int num_options,
<br>
1652 <a href=
"#cups_option_t">cups_option_t
</a> *options
<br>
1654 <h4 class=
"parameters">Parameters
</h4>
1657 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1659 <dd class=
"description">Destination name
</dd>
1661 <dd class=
"description">Number of files
</dd>
1663 <dd class=
"description">File(s) to print
</dd>
1665 <dd class=
"description">Title of job
</dd>
1666 <dt>num_options
</dt>
1667 <dd class=
"description">Number of options
</dd>
1669 <dd class=
"description">Options
</dd>
1671 <h4 class=
"returnvalue">Return Value
</h4>
1672 <p class=
"description">Job ID or
0 on error
</p>
1673 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsRemoveDest">cupsRemoveDest
</a></h3>
1674 <p class=
"description">Remove a destination from the destination list.
</p>
1676 int cupsRemoveDest (
<br>
1677 const char *name,
<br>
1678 const char *instance,
<br>
1679 int num_dests,
<br>
1680 <a href=
"#cups_dest_t">cups_dest_t
</a> **dests
<br>
1682 <h4 class=
"parameters">Parameters
</h4>
1685 <dd class=
"description">Destination name
</dd>
1687 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1689 <dd class=
"description">Number of destinations
</dd>
1691 <dd class=
"description">Destinations
</dd>
1693 <h4 class=
"returnvalue">Return Value
</h4>
1694 <p class=
"description">New number of destinations
</p>
1695 <h4 class=
"discussion">Discussion
</h4>
1696 <p class=
"discussion">Removing a destination/instance does not delete the class or printer
1697 queue, merely the lpoptions for that destination/instance. Use the
1698 <a href=
"#cupsSetDests"><code>cupsSetDests
</code></a> or
<a href=
"#cupsSetDests2"><code>cupsSetDests2
</code></a> functions to save the new
1699 options for the user.
1702 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsRemoveOption">cupsRemoveOption
</a></h3>
1703 <p class=
"description">Remove an option from an option array.
</p>
1705 int cupsRemoveOption (
<br>
1706 const char *name,
<br>
1707 int num_options,
<br>
1708 <a href=
"#cups_option_t">cups_option_t
</a> **options
<br>
1710 <h4 class=
"parameters">Parameters
</h4>
1713 <dd class=
"description">Option name
</dd>
1714 <dt>num_options
</dt>
1715 <dd class=
"description">Current number of options
</dd>
1717 <dd class=
"description">Options
</dd>
1719 <h4 class=
"returnvalue">Return Value
</h4>
1720 <p class=
"description">New number of options
</p>
1721 <h3 class=
"function"><a name=
"cupsServer">cupsServer
</a></h3>
1722 <p class=
"description">Return the hostname/address of the default server.
</p>
1724 const char *cupsServer (void);
</p>
1725 <h4 class=
"returnvalue">Return Value
</h4>
1726 <p class=
"description">Server name
</p>
1727 <h4 class=
"discussion">Discussion
</h4>
1728 <p class=
"discussion">The returned value can be a fully-qualified hostname, a numeric
1729 IPv4 or IPv6 address, or a domain socket pathname.
</p>
1730 <h3 class=
"function"><span class=
"info"> CUPS
1.3 </span><a name=
"cupsSetDefaultDest">cupsSetDefaultDest
</a></h3>
1731 <p class=
"description">Set the default destination.
</p>
1733 void cupsSetDefaultDest (
<br>
1734 const char *name,
<br>
1735 const char *instance,
<br>
1736 int num_dests,
<br>
1737 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1739 <h4 class=
"parameters">Parameters
</h4>
1742 <dd class=
"description">Destination name
</dd>
1744 <dd class=
"description">Instance name or
<code>NULL
</code></dd>
1746 <dd class=
"description">Number of destinations
</dd>
1748 <dd class=
"description">Destinations
</dd>
1750 <h3 class=
"function"><a name=
"cupsSetDests">cupsSetDests
</a></h3>
1751 <p class=
"description">Save the list of destinations for the default server.
</p>
1753 void cupsSetDests (
<br>
1754 int num_dests,
<br>
1755 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1757 <h4 class=
"parameters">Parameters
</h4>
1760 <dd class=
"description">Number of destinations
</dd>
1762 <dd class=
"description">Destinations
</dd>
1764 <h4 class=
"discussion">Discussion
</h4>
1765 <p class=
"discussion">This function saves the destinations to /etc/cups/lpoptions when run
1766 as root and ~/.cups/lpoptions when run as a normal user.
</p>
1767 <h3 class=
"function"><span class=
"info"> CUPS
1.1.21 </span><a name=
"cupsSetDests2">cupsSetDests2
</a></h3>
1768 <p class=
"description">Save the list of destinations for the specified server.
</p>
1770 int cupsSetDests2 (
<br>
1771 http_t *http,
<br>
1772 int num_dests,
<br>
1773 <a href=
"#cups_dest_t">cups_dest_t
</a> *dests
<br>
1775 <h4 class=
"parameters">Parameters
</h4>
1778 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1780 <dd class=
"description">Number of destinations
</dd>
1782 <dd class=
"description">Destinations
</dd>
1784 <h4 class=
"returnvalue">Return Value
</h4>
1785 <p class=
"description">0 on success, -
1 on error
</p>
1786 <h4 class=
"discussion">Discussion
</h4>
1787 <p class=
"discussion">This function saves the destinations to /etc/cups/lpoptions when run
1788 as root and ~/.cups/lpoptions when run as a normal user.
1791 <h3 class=
"function"><a name=
"cupsSetEncryption">cupsSetEncryption
</a></h3>
1792 <p class=
"description">Set the encryption preference.
</p>
1794 void cupsSetEncryption (
<br>
1795 http_encryption_t e
<br>
1797 <h4 class=
"parameters">Parameters
</h4>
1800 <dd class=
"description">New encryption preference
</dd>
1802 <h3 class=
"function"><a name=
"cupsSetPasswordCB">cupsSetPasswordCB
</a></h3>
1803 <p class=
"description">Set the password callback for CUPS.
</p>
1805 void cupsSetPasswordCB (
<br>
1806 <a href=
"#cups_password_cb_t">cups_password_cb_t
</a> cb
<br>
1808 <h4 class=
"parameters">Parameters
</h4>
1811 <dd class=
"description">Callback function
</dd>
1813 <h4 class=
"discussion">Discussion
</h4>
1814 <p class=
"discussion">Pass
<code>NULL
</code> to restore the default (console) password callback.
</p>
1815 <h3 class=
"function"><a name=
"cupsSetServer">cupsSetServer
</a></h3>
1816 <p class=
"description">Set the default server name.
</p>
1818 void cupsSetServer (
<br>
1819 const char *server
<br>
1821 <h4 class=
"parameters">Parameters
</h4>
1824 <dd class=
"description">Server name
</dd>
1826 <h4 class=
"discussion">Discussion
</h4>
1827 <p class=
"discussion">The
"server
" string can be a fully-qualified hostname, a numeric
1828 IPv4 or IPv6 address, or a domain socket pathname. Pass
<code>NULL
</code> to
1829 restore the default server name.
</p>
1830 <h3 class=
"function"><a name=
"cupsSetUser">cupsSetUser
</a></h3>
1831 <p class=
"description">Set the default user name.
</p>
1833 void cupsSetUser (
<br>
1834 const char *user
<br>
1836 <h4 class=
"parameters">Parameters
</h4>
1839 <dd class=
"description">User name
</dd>
1841 <h4 class=
"discussion">Discussion
</h4>
1842 <p class=
"discussion">Pass
<code>NULL
</code> to restore the default user name.
</p>
1843 <h3 class=
"function"><span class=
"info"> CUPS
1.4 </span><a name=
"cupsStartDocument">cupsStartDocument
</a></h3>
1844 <p class=
"description">Add a document to a job created with cupsCreateJob().
</p>
1846 http_status_t cupsStartDocument (
<br>
1847 http_t *http,
<br>
1848 const char *name,
<br>
1849 int job_id,
<br>
1850 const char *docname,
<br>
1851 const char *format,
<br>
1852 int last_document
<br>
1854 <h4 class=
"parameters">Parameters
</h4>
1857 <dd class=
"description">Connection to server or
<code>CUPS_HTTP_DEFAULT
</code></dd>
1859 <dd class=
"description">Destination name
</dd>
1861 <dd class=
"description">Job ID from
<a href=
"#cupsCreateJob"><code>cupsCreateJob
</code></a></dd>
1863 <dd class=
"description">Name of document
</dd>
1865 <dd class=
"description">MIME type or
<code>CUPS_FORMAT_foo
</code></dd>
1866 <dt>last_document
</dt>
1867 <dd class=
"description">1 for last document in job,
0 otherwise
</dd>
1869 <h4 class=
"returnvalue">Return Value
</h4>
1870 <p class=
"description">HTTP status of request
</p>
1871 <h4 class=
"discussion">Discussion
</h4>
1872 <p class=
"discussion">Use
<a href=
"#cupsWriteRequestData"><code>cupsWriteRequestData
</code></a> to write data for the document and
1873 <a href=
"#cupsFinishDocument"><code>cupsFinishDocument
</code></a> to finish the document and get the submission status.
<br>
1875 The MIME type constants
<code>CUPS_FORMAT_AUTO
</code>,
<code>CUPS_FORMAT_PDF
</code>,
1876 <code>CUPS_FORMAT_POSTSCRIPT
</code>,
<code>CUPS_FORMAT_RAW
</code>, and
1877 <code>CUPS_FORMAT_TEXT
</code> are provided for the
"format
" argument, although
1878 any supported MIME type string can be supplied.
1881 <h3 class=
"function"><a name=
"cupsTempFd">cupsTempFd
</a></h3>
1882 <p class=
"description">Creates a temporary file.
</p>
1884 int cupsTempFd (
<br>
1885 char *filename,
<br>
1886 int len
<br>
1888 <h4 class=
"parameters">Parameters
</h4>
1891 <dd class=
"description">Pointer to buffer
</dd>
1893 <dd class=
"description">Size of buffer
</dd>
1895 <h4 class=
"returnvalue">Return Value
</h4>
1896 <p class=
"description">New file descriptor or -
1 on error
</p>
1897 <h4 class=
"discussion">Discussion
</h4>
1898 <p class=
"discussion">The temporary filename is returned in the filename buffer.
1899 The temporary file is opened for reading and writing.
</p>
1900 <h3 class=
"function"><span class=
"info"> DEPRECATED
</span><a name=
"cupsTempFile">cupsTempFile
</a></h3>
1901 <p class=
"description">Generates a temporary filename.
</p>
1903 char *cupsTempFile (
<br>
1904 char *filename,
<br>
1905 int len
<br>
1907 <h4 class=
"parameters">Parameters
</h4>
1910 <dd class=
"description">Pointer to buffer
</dd>
1912 <dd class=
"description">Size of buffer
</dd>
1914 <h4 class=
"returnvalue">Return Value
</h4>
1915 <p class=
"description">Filename or
<code>NULL
</code> on error
</p>
1916 <h4 class=
"discussion">Discussion
</h4>
1917 <p class=
"discussion">The temporary filename is returned in the filename buffer.
1918 This function is deprecated - use
<a href=
"#cupsTempFd"><code>cupsTempFd
</code></a> or
1919 <a href=
"#cupsTempFile2"><code>cupsTempFile2
</code></a> instead.
1922 <h3 class=
"function"><span class=
"info"> CUPS
1.2 </span><a name=
"cupsTempFile2">cupsTempFile2
</a></h3>
1923 <p class=
"description">Creates a temporary CUPS file.
</p>
1925 cups_file_t *cupsTempFile2 (
<br>
1926 char *filename,
<br>
1927 int len
<br>
1929 <h4 class=
"parameters">Parameters
</h4>
1932 <dd class=
"description">Pointer to buffer
</dd>
1934 <dd class=
"description">Size of buffer
</dd>
1936 <h4 class=
"returnvalue">Return Value
</h4>
1937 <p class=
"description">CUPS file or
<code>NULL
</code> on error
</p>
1938 <h4 class=
"discussion">Discussion
</h4>
1939 <p class=
"discussion">The temporary filename is returned in the filename buffer.
1940 The temporary file is opened for writing.
1943 <h3 class=
"function"><a name=
"cupsUser">cupsUser
</a></h3>
1944 <p class=
"description">Return the current user's name.
</p>
1946 const char *cupsUser (void);
</p>
1947 <h4 class=
"returnvalue">Return Value
</h4>
1948 <p class=
"description">User name
</p>
1949 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
1950 <h3 class=
"typedef"><a name=
"cups_dest_t">cups_dest_t
</a></h3>
1951 <p class=
"description">Destination
</p>
1953 typedef struct
<a href=
"#cups_dest_s">cups_dest_s
</a> cups_dest_t;
1955 <h3 class=
"typedef"><span class=
"info"> CUPS
1.4 </span><a name=
"cups_device_cb_t">cups_device_cb_t
</a></h3>
1956 <p class=
"description">Device callback
</p>
1958 typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, void *user_data);
1960 <h3 class=
"typedef"><a name=
"cups_job_t">cups_job_t
</a></h3>
1961 <p class=
"description">Job
</p>
1963 typedef struct
<a href=
"#cups_job_s">cups_job_s
</a> cups_job_t;
1965 <h3 class=
"typedef"><a name=
"cups_option_t">cups_option_t
</a></h3>
1966 <p class=
"description">Printer Options
</p>
1968 typedef struct
<a href=
"#cups_option_s">cups_option_s
</a> cups_option_t;
1970 <h3 class=
"typedef"><a name=
"cups_password_cb_t">cups_password_cb_t
</a></h3>
1971 <p class=
"description">Password callback
</p>
1973 typedef const char *(*cups_password_cb_t)(const char *prompt);
1975 <h3 class=
"typedef"><a name=
"cups_ptype_t">cups_ptype_t
</a></h3>
1976 <p class=
"description">Printer type/capability bits
</p>
1978 typedef unsigned cups_ptype_t;
1980 <h2 class=
"title"><a name=
"STRUCTURES">Structures
</a></h2>
1981 <h3 class=
"struct"><a name=
"cups_dest_s">cups_dest_s
</a></h3>
1982 <p class=
"description">Destination
</p>
1983 <p class=
"code">struct cups_dest_s {
<br>
1984 char *name, *instance;
<br>
1985 int is_default;
<br>
1986 int num_options;
<br>
1987 <a href=
"#cups_option_t">cups_option_t
</a> *options;
<br>
1989 <h4 class=
"members">Members
</h4>
1992 <dd class=
"description">Local instance name or NULL
</dd>
1993 <dt>is_default
</dt>
1994 <dd class=
"description">Is this printer the default?
</dd>
1995 <dt>num_options
</dt>
1996 <dd class=
"description">Number of options
</dd>
1998 <dd class=
"description">Options
</dd>
2000 <h3 class=
"struct"><a name=
"cups_job_s">cups_job_s
</a></h3>
2001 <p class=
"description">Job
</p>
2002 <p class=
"code">struct cups_job_s {
<br>
2003 time_t completed_time;
<br>
2004 time_t creation_time;
<br>
2005 char *dest;
<br>
2006 char *format;
<br>
2007 int id;
<br>
2008 int priority;
<br>
2009 time_t processing_time;
<br>
2010 int size;
<br>
2011 ipp_jstate_t state;
<br>
2012 char *title;
<br>
2013 char *user;
<br>
2015 <h4 class=
"members">Members
</h4>
2017 <dt>completed_time
</dt>
2018 <dd class=
"description">Time the job was completed
</dd>
2019 <dt>creation_time
</dt>
2020 <dd class=
"description">Time the job was created
</dd>
2022 <dd class=
"description">Printer or class name
</dd>
2024 <dd class=
"description">Document format
</dd>
2026 <dd class=
"description">The job ID
</dd>
2028 <dd class=
"description">Priority (
1-
100)
</dd>
2029 <dt>processing_time
</dt>
2030 <dd class=
"description">Time the job was processed
</dd>
2032 <dd class=
"description">Size in kilobytes
</dd>
2034 <dd class=
"description">Job state
</dd>
2036 <dd class=
"description">Title/job name
</dd>
2038 <dd class=
"description">User the submitted the job
</dd>
2040 <h3 class=
"struct"><a name=
"cups_option_s">cups_option_s
</a></h3>
2041 <p class=
"description">Printer Options
</p>
2042 <p class=
"code">struct cups_option_s {
<br>
2043 char *name;
<br>
2044 char *value;
<br>
2046 <h4 class=
"members">Members
</h4>
2049 <dd class=
"description">Name of option
</dd>
2051 <dd class=
"description">Value of option
</dd>
2053 <h2 class=
"title"><a name=
"ENUMERATIONS">Constants
</a></h2>
2054 <h3 class=
"enumeration"><a name=
"cups_ptype_e">cups_ptype_e
</a></h3>
2055 <p class=
"description">Printer type/capability bit constants
</p>
2056 <h4 class=
"constants">Constants
</h4>
2058 <dt>CUPS_PRINTER_AUTHENTICATED
<span class=
"info"> CUPS
1.2 </span></dt>
2059 <dd class=
"description">Printer requires authentication
</dd>
2060 <dt>CUPS_PRINTER_BIND
</dt>
2061 <dd class=
"description">Can bind output
</dd>
2062 <dt>CUPS_PRINTER_BW
</dt>
2063 <dd class=
"description">Can do B
&W printing
</dd>
2064 <dt>CUPS_PRINTER_CLASS
</dt>
2065 <dd class=
"description">Printer class
</dd>
2066 <dt>CUPS_PRINTER_COLLATE
</dt>
2067 <dd class=
"description">Can collage copies
</dd>
2068 <dt>CUPS_PRINTER_COLOR
</dt>
2069 <dd class=
"description">Can do color printing
</dd>
2070 <dt>CUPS_PRINTER_COMMANDS
<span class=
"info"> CUPS
1.2 </span></dt>
2071 <dd class=
"description">Printer supports maintenance commands
</dd>
2072 <dt>CUPS_PRINTER_COPIES
</dt>
2073 <dd class=
"description">Can do copies
</dd>
2074 <dt>CUPS_PRINTER_COVER
</dt>
2075 <dd class=
"description">Can cover output
</dd>
2076 <dt>CUPS_PRINTER_DEFAULT
</dt>
2077 <dd class=
"description">Default printer on network
</dd>
2078 <dt>CUPS_PRINTER_DELETE
<span class=
"info"> CUPS
1.2 </span></dt>
2079 <dd class=
"description">Delete printer
</dd>
2080 <dt>CUPS_PRINTER_DISCOVERED
<span class=
"info"> CUPS
1.3 </span></dt>
2081 <dd class=
"description">Printer was automatically discovered and added
</dd>
2082 <dt>CUPS_PRINTER_DUPLEX
</dt>
2083 <dd class=
"description">Can do duplexing
</dd>
2084 <dt>CUPS_PRINTER_FAX
</dt>
2085 <dd class=
"description">Fax queue
</dd>
2086 <dt>CUPS_PRINTER_IMPLICIT
</dt>
2087 <dd class=
"description">Implicit class
</dd>
2088 <dt>CUPS_PRINTER_LARGE
</dt>
2089 <dd class=
"description">Can do D/E/A1/A0
</dd>
2090 <dt>CUPS_PRINTER_LOCAL
</dt>
2091 <dd class=
"description">Local printer or class
</dd>
2092 <dt>CUPS_PRINTER_MEDIUM
</dt>
2093 <dd class=
"description">Can do Tabloid/B/C/A3/A2
</dd>
2094 <dt>CUPS_PRINTER_NOT_SHARED
<span class=
"info"> CUPS
1.2 </span></dt>
2095 <dd class=
"description">Printer is not shared
</dd>
2096 <dt>CUPS_PRINTER_PUNCH
</dt>
2097 <dd class=
"description">Can punch output
</dd>
2098 <dt>CUPS_PRINTER_REJECTING
</dt>
2099 <dd class=
"description">Printer is rejecting jobs
</dd>
2100 <dt>CUPS_PRINTER_REMOTE
</dt>
2101 <dd class=
"description">Remote printer or class
</dd>
2102 <dt>CUPS_PRINTER_SMALL
</dt>
2103 <dd class=
"description">Can do Letter/Legal/A4
</dd>
2104 <dt>CUPS_PRINTER_SORT
</dt>
2105 <dd class=
"description">Can sort output
</dd>
2106 <dt>CUPS_PRINTER_STAPLE
</dt>
2107 <dd class=
"description">Can staple output
</dd>
2108 <dt>CUPS_PRINTER_VARIABLE
</dt>
2109 <dd class=
"description">Can do variable sizes
</dd>