2 API introduction for CUPS.
4 Copyright 2007-2013 by Apple Inc.
5 Copyright 1997-2006 by Easy Software Products, all rights reserved.
7 These coded instructions, statements, and computer programs are the
8 property of Apple Inc. and are protected by Federal copyright
9 law. Distribution and use rights are outlined in the file "LICENSE.txt"
10 which should have been included with this file. If this file is
11 file is missing or damaged, see the license at "http://www.cups.org/".
14 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
16 <p>The CUPS API provides the convenience functions needed to support
17 applications, filters, printer drivers, and backends that need to interface
18 with the CUPS scheduler.</p>
20 <h3><a name='CLIENTS_AND_SERVERS'>Clients and Servers</a></h3>
22 <p>CUPS is based on the Internet Printing Protocol ("IPP"), which allows
23 clients (applications) to communicate with a server (the scheduler) to get a
24 list of printers, send print jobs, and so forth. You identify which server
25 you want to communicate with using a pointer to the opaque structure
26 <code>http_t</code>. All of the examples in this document use the
27 <code>CUPS_HTTP_DEFAULT</code> constant, referring to the default connection
28 to the scheduler. The <a href='api-httpipp.html' target='_top'>HTTP and IPP
29 APIs</a> document provides more information on server connections.</p>
31 <h3><a name='PRINTERS_AND_CLASSES'>Printers and Classes</a></h3>
33 <p>Printers and classes (collections of printers) are accessed through
34 the <a href="#cups_dest_t"><code>cups_dest_t</code></a> structure which
35 includes the name (<code>name</code>), instance (<code>instance</code> -
36 a way of selecting certain saved options/settings), and the options and
37 attributes associated with that destination (<code>num_options</code> and
38 <code>options</code>). Destinations are created using the
39 <a href="#cupsGetDests"><code>cupsGetDests</code></a> function and freed
40 using the <a href='#cupsFreeDests'><code>cupsFreeDests</code></a> function.
41 The <a href='#cupsGetDest'><code>cupsGetDest</code></a> function finds a
42 specific destination for printing:</p>
45 #include <cups/cups.h>
47 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
48 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
49 <a href='#cups_dest_t'>cups_dest_t</a> *dest = <a href='#cupsGetDest'>cupsGetDest</a>("name", NULL, num_dests, dests);
51 /* do something with dest */
53 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
56 <p>Passing <code>NULL</code> to
57 <a href='#cupsGetDest'><code>cupsGetDest</code></a> for the destination name
58 will return the default destination. Similarly, passing a <code>NULL</code>
59 instance will return the default instance for that destination.</p>
61 <div class='table'><table summary='Table 1: Printer Attributes' width='80%'>
62 <caption>Table 1: <a name='TABLE1'>Printer Attributes</a></caption>
65 <th>Attribute Name</th>
71 <td>"auth-info-required"</td>
72 <td>The type of authentication required for printing to this
73 destination: "none", "username,password", "domain,username,password",
74 or "negotiate" (Kerberos)</td>
77 <td>"printer-info"</td>
78 <td>The human-readable description of the destination such as "My
82 <td>"printer-is-accepting-jobs"</td>
83 <td>"true" if the destination is accepting new jobs, "false" if
87 <td>"printer-is-shared"</td>
88 <td>"true" if the destination is being shared with other computers,
92 <td>"printer-location"</td>
93 <td>The human-readable location of the destination such as "Lab 4".</td>
96 <td>"printer-make-and-model"</td>
97 <td>The human-readable make and model of the destination such as "HP
98 LaserJet 4000 Series".</td>
101 <td>"printer-state"</td>
102 <td>"3" if the destination is idle, "4" if the destination is printing
103 a job, and "5" if the destination is stopped.</td>
106 <td>"printer-state-change-time"</td>
107 <td>The UNIX time when the destination entered the current state.</td>
110 <td>"printer-state-reasons"</td>
111 <td>Additional comma-delimited state keywords for the destination
112 such as "media-tray-empty-error" and "toner-low-warning".</td>
115 <td>"printer-type"</td>
116 <td>The <a href='#cups_printer_t'><code>cups_printer_t</code></a>
117 value associated with the destination.</td>
122 <h3><a name='OPTIONS'>Options</a></h3>
124 <p>Options are stored in arrays of
125 <a href='#cups_option_t'><code>cups_option_t</code></a> structures. Each
126 option has a name (<code>name</code>) and value (<code>value</code>)
127 associated with it. The <a href='#cups_dest_t'><code>cups_dest_t</code></a>
128 <code>num_options</code> and <code>options</code> members contain the
129 default options for a particular destination, along with several informational
130 attributes about the destination as shown in <a href='#TABLE1'>Table 1</a>.
131 The <a href='#cupsGetOption'><code>cupsGetOption</code></a> function gets
132 the value for the named option. For example, the following code lists the
133 available destinations and their human-readable descriptions:</p>
135 <pre class='example'>
136 #include <cups/cups.h>
138 <a href='#cups_dest_t'>cups_dest_t</a> *dests;
139 int num_dests = <a href='#cupsGetDests'>cupsGetDests</a>(&dests);
140 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
144 for (i = num_dests, dest = dests; i > 0; i --, dest ++)
145 if (dest->instance == NULL)
147 value = <a href='#cupsGetOption'>cupsGetOption</a>("printer-info", dest->num_options, dest->options);
148 printf("%s (%s)\n", dest->name, value ? value : "no description");
151 <a href='#cupsFreeDests'>cupsFreeDests</a>(num_dests, dests);
154 <p>You can create your own option arrays using the
155 <a href='#cupsAddOption'><code>cupsAddOption</code></a> function, which
156 adds a single named option to an array:</p>
158 <pre class='example'>
159 #include <cups/cups.h>
162 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
164 /* The returned num_options value is updated as needed */
165 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "value", num_options, &options);
167 /* This adds a second option value */
168 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("second", "value", num_options, &options);
170 /* This replaces the first option we added */
171 num_options = <a href='#cupsAddOption'>cupsAddOption</a>("first", "new value", num_options, &options);
174 <p>Use a <code>for</code> loop to copy the options from a destination:</p>
176 <pre class='example'>
177 #include <cups/cups.h>
181 <a href='#cups_option_t'>cups_option_t</a> *options = NULL;
182 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
184 for (i = 0; i < dest->num_options; i ++)
185 num_options = <a href='#cupsAddOption'>cupsAddOption</a>(dest->options[i].name, dest->options[i].value,
186 num_options, &options);
189 <p>Use the <a href='#cupsFreeOptions'><code>cupsFreeOptions</code></a>
190 function to free the options array when you are done using it:</p>
192 <pre class='example'>
193 <a href='#cupsFreeOptions'>cupsFreeOptions</a>(num_options, options);
196 <h3><a name='PRINT_JOBS'>Print Jobs</a></h3>
198 <p>Print jobs are identified by a locally-unique job ID number from 1 to
199 2<sup>31</sup>-1 and have options and one or more files for printing to a
200 single destination. The <a href='#cupsPrintFile'><code>cupsPrintFile</code></a>
201 function creates a new job with one file. The following code prints the CUPS
204 <pre class='example'>
205 #include <cups/cups.h>
207 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
209 <a href='#cups_option_t'>cups_option_t</a> *options;
212 /* Print a single file */
213 job_id = <a href='#cupsPrintFile'>cupsPrintFile</a>(dest->name, "/usr/share/cups/data/testprint.ps",
214 "Test Print", num_options, options);
217 <p>The <a href='#cupsPrintFiles'><code>cupsPrintFiles</code></a> function
218 creates a job with multiple files. The files are provided in a
219 <code>char *</code> array:</p>
221 <pre class='example'>
222 #include <cups/cups.h>
224 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
226 <a href='#cups_option_t'>cups_option_t</a> *options;
228 char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
230 /* Print three files */
231 job_id = <a href='#cupsPrintFiles'>cupsPrintFiles</a>(dest->name, 3, files, "Test Print", num_options, options);
234 <p>Finally, the <a href='#cupsCreateJob'><code>cupsCreateJob</code></a>
235 function creates a new job with no files in it. Files are added using the
236 <a href='#cupsStartDocument'><code>cupsStartDocument</code></a>,
237 <a href='api-httpipp.html#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>,
238 and <a href='#cupsFinishDocument'><code>cupsFinishDocument</code></a> functions.
239 The following example creates a job with 10 text files for printing:</p>
241 <pre class='example'>
242 #include <cups/cups.h>
244 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
246 <a href='#cups_option_t'>cups_option_t</a> *options;
252 job_id = <a href='#cupsCreateJob'>cupsCreateJob</a>(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files",
253 num_options, options);
255 /* If the job is created, add 10 files */
258 for (i = 1; i <= 10; i ++)
260 snprintf(buffer, sizeof(buffer), "file%d.txt", i);
262 <a href='#cupsStartDocument'>cupsStartDocument</a>(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer,
263 CUPS_FORMAT_TEXT, i == 10);
265 snprintf(buffer, sizeof(buffer),
273 /* cupsWriteRequestData can be called as many times as needed */
274 <a href='#cupsWriteRequestData'>cupsWriteRequestData</a>(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
276 <a href='#cupsFinishDocument'>cupsFinishDocument</a>(CUPS_HTTP_DEFAULT, dest->name);
281 <p>Once you have created a job, you can monitor its status using the
282 <a href='#cupsGetJobs'><code>cupsGetJobs</code></a> function, which returns
283 an array of <a href='#cups_job_t'><code>cups_job_t</code></a> structures.
284 Each contains the job ID (<code>id</code>), destination name
285 (<code>dest</code>), title (<code>title</code>), and other information
286 associated with the job. The job array is freed using the
287 <a href='#cupsFreeJobs'><code>cupsFreeJobs</code></a> function. The following
288 example monitors a specific job ID, showing the current job state once every
289 5 seconds until the job is completed:</p>
291 <pre class='example'>
292 #include <cups/cups.h>
294 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
297 <a href='#cups_job_t'>cups_job_t</a> *jobs;
299 ipp_jstate_t job_state = IPP_JOB_PENDING;
301 while (job_state < IPP_JOB_STOPPED)
303 /* Get my jobs (1) with any state (-1) */
304 num_jobs = <a href='#cupsGetJobs'>cupsGetJobs</a>(&jobs, dest->name, 1, -1);
306 /* Loop to find my job */
307 job_state = IPP_JOB_COMPLETED;
309 for (i = 0; i < num_jobs; i ++)
310 if (jobs[i].id == job_id)
312 job_state = jobs[i].state;
316 /* Free the job array */
317 <a href='#cupsFreeJobs'>cupsFreeJobs</a>(num_jobs, jobs);
319 /* Show the current state */
322 case IPP_JOB_PENDING :
323 printf("Job %d is pending.\n", job_id);
326 printf("Job %d is held.\n", job_id);
328 case IPP_JOB_PROCESSING :
329 printf("Job %d is processing.\n", job_id);
331 case IPP_JOB_STOPPED :
332 printf("Job %d is stopped.\n", job_id);
334 case IPP_JOB_CANCELED :
335 printf("Job %d is canceled.\n", job_id);
337 case IPP_JOB_ABORTED :
338 printf("Job %d is aborted.\n", job_id);
340 case IPP_JOB_COMPLETED :
341 printf("Job %d is completed.\n", job_id);
345 /* Sleep if the job is not finished */
346 if (job_state < IPP_JOB_STOPPED)
351 <p>To cancel a job, use the
352 <a href='#cupsCancelJob'><code>cupsCancelJob</code></a> function with the
355 <pre class='example'>
356 #include <cups/cups.h>
358 <a href='#cups_dest_t'>cups_dest_t</a> *dest;
361 <a href='#cupsCancelJob'>cupsCancelJob</a>(dest->name, job_id);
364 <h3><a name='ERROR_HANDLING'>Error Handling</a></h3>
366 <p>If any of the CUPS API printing functions returns an error, the reason for
367 that error can be found by calling the
368 <a href='#cupsLastError'><code>cupsLastError</code></a> and
369 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> functions.
370 <a href='#cupsLastError'><code>cupsLastError</code></a> returns the last IPP
372 (<a href='api-httpipp.html#ipp_status_t'><code>ipp_status_t</code></a>)
373 that was encountered, while
374 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> returns
375 a (localized) human-readable string that can be shown to the user. For example,
376 if any of the job creation functions returns a job ID of 0, you can use
377 <a href='#cupsLastErrorString'><code>cupsLastErrorString</code></a> to show
378 the reason why the job could not be created:</p>
380 <pre class='example'>
381 #include <cups/cups.h>
386 puts(cupsLastErrorString());
389 <h3><a name='PASSWORDS_AND_AUTHENTICATION'>Passwords and Authentication</a></h3>
391 <p>CUPS supports authentication of any request, including submission of print
392 jobs. The default mechanism for getting the username and password is to use the
393 login user and a password from the console.</p>
395 <p>To support other types of applications, in particular Graphical User
396 Interfaces ("GUIs"), the CUPS API provides functions to set the default
397 username and to register a callback function that returns a password string.</p>
399 <p>The <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a>
400 function is used to set a password callback in your program. Only one
401 function can be used at any time.</p>
403 <p>The <a href="#cupsSetUser"><code>cupsSetUser</code></a> function sets the
404 current username for authentication. This function can be called by your
405 password callback function to change the current username as needed.</p>
407 <p>The following example shows a simple password callback that gets a
408 username and password from the user:</p>
410 <pre class='example'>
411 #include <cups/cups.h>
414 my_password_cb(const char *prompt)
421 /* Get a username from the user */
422 printf("Username: ");
423 if (fgets(user, sizeof(user), stdin) == NULL)
426 /* Strip the newline from the string and set the user */
427 user[strlen(user) - 1] = '\0';
429 <a href='#cupsSetUser'>cupsSetUser</a>(user);
431 /* Use getpass() to ask for the password... */
432 return (getpass("Password: "));
435 <a href='#cupsSetPasswordCB'>cupsSetPasswordCB</a>(my_password_cb);
438 <p>Similarly, a GUI could display the prompt string in a window with input
439 fields for the username and password. The username should default to the
440 string returned by the <a href="#cupsUser"><code>cupsUser</code></a>