]> git.ipfire.org Git - thirdparty/cups.git/blob - doc/help/api-overview.html
90726bf6454e81477a22b7fbe98d7cbfa6660f50
[thirdparty/cups.git] / doc / help / api-overview.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- SECTION: Programming -->
4 <head>
5 <title>Introduction to CUPS Programming </title>
6 <meta name="keywords" content="Programming">
7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
8 <meta name="creator" content="Mini-XML v2.7">
9 <style type="text/css"><!--
10 BODY {
11 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
12 }
13
14 H1, H2, H3, H4, H5, H6, P, TD, TH {
15 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
16 }
17
18 KBD {
19 font-family: monaco, courier, monospace;
20 font-weight: bold;
21 }
22
23 PRE {
24 font-family: monaco, courier, monospace;
25 }
26
27 PRE.command {
28 border: dotted thin #7f7f7f;
29 margin-left: 36pt;
30 padding: 10px;
31 }
32
33 P.compact {
34 margin: 0;
35 }
36
37 P.example {
38 font-style: italic;
39 margin-left: 36pt;
40 }
41
42 PRE.example {
43 background: #eeeeee;
44 border: dotted thin #999999;
45 margin-left: 36pt;
46 padding: 10pt;
47 }
48
49 PRE.command EM, PRE.example EM {
50 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
51 }
52
53 P.command {
54 font-family: monaco, courier, monospace;
55 margin-left: 36pt;
56 }
57
58 P.formula {
59 font-style: italic;
60 margin-left: 36pt;
61 }
62
63 BLOCKQUOTE {
64 background: #eeeeee;
65 border: solid thin #999999;
66 padding: 10pt;
67 }
68
69 A IMG {
70 border: none;
71 }
72
73 A:link:hover IMG {
74 background: #f0f0f0;
75 border-radius: 10px;
76 -moz-border-radius: 10px;
77 }
78
79 A:link, A:visited {
80 font-weight: normal;
81 text-decoration: none;
82 }
83
84 A:link:hover, A:visited:hover, A:active {
85 text-decoration: underline;
86 }
87
88 SUB, SUP {
89 font-size: 50%;
90 }
91
92 TR.data, TD.data, TR.data TD {
93 margin-top: 10pt;
94 padding: 5pt;
95 border-bottom: solid 1pt #999999;
96 }
97
98 TR.data TH {
99 border-bottom: solid 1pt #999999;
100 padding-top: 10pt;
101 padding-left: 5pt;
102 text-align: left;
103 }
104
105 DIV.table TABLE {
106 border: solid thin #999999;
107 border-collapse: collapse;
108 border-spacing: 0;
109 margin-left: auto;
110 margin-right: auto;
111 }
112
113 DIV.table CAPTION {
114 caption-side: top;
115 font-size: 120%;
116 font-style: italic;
117 font-weight: bold;
118 margin-left: auto;
119 margin-right: auto;
120 }
121
122 DIV.table TABLE TD {
123 border: solid thin #cccccc;
124 padding-top: 5pt;
125 }
126
127 DIV.table TABLE TH {
128 background: #cccccc;
129 border: none;
130 border-bottom: solid thin #999999;
131 }
132
133 DIV.figure TABLE {
134 margin-left: auto;
135 margin-right: auto;
136 }
137
138 DIV.figure CAPTION {
139 caption-side: bottom;
140 font-size: 120%;
141 font-style: italic;
142 font-weight: bold;
143 margin-left: auto;
144 margin-right: auto;
145 }
146
147 TH.label {
148 text-align: right;
149 vertical-align: top;
150 }
151
152 TH.sublabel {
153 text-align: right;
154 font-weight: normal;
155 }
156
157 HR {
158 border: solid thin;
159 }
160
161 SPAN.info {
162 background: black;
163 border: thin solid black;
164 color: white;
165 font-size: 80%;
166 font-style: italic;
167 font-weight: bold;
168 white-space: nowrap;
169 }
170
171 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
172 float: right;
173 font-size: 100%;
174 }
175
176 H1.title {
177 }
178
179 H2.title, H3.title {
180 border-bottom: solid 2pt #000000;
181 }
182
183 DIV.indent, TABLE.indent {
184 margin-top: 2em;
185 margin-left: auto;
186 margin-right: auto;
187 width: 90%;
188 }
189
190 TABLE.indent {
191 border-collapse: collapse;
192 }
193
194 TABLE.indent TD, TABLE.indent TH {
195 padding: 0;
196 }
197
198 TABLE.list {
199 border-collapse: collapse;
200 margin-left: auto;
201 margin-right: auto;
202 width: 90%;
203 }
204
205 TABLE.list TH {
206 background: white;
207 border-bottom: solid thin #cccccc;
208 color: #444444;
209 padding-top: 10pt;
210 padding-left: 5pt;
211 text-align: left;
212 vertical-align: bottom;
213 white-space: nowrap;
214 }
215
216 TABLE.list TH A {
217 color: #4444cc;
218 }
219
220 TABLE.list TD {
221 border-bottom: solid thin #eeeeee;
222 padding-top: 5pt;
223 padding-left: 5pt;
224 }
225
226 TABLE.list TR:nth-child(even) {
227 background: #f8f8f8;
228 }
229
230 TABLE.list TR:nth-child(odd) {
231 background: #f4f4f4;
232 }
233
234 DT {
235 margin-left: 36pt;
236 margin-top: 12pt;
237 }
238
239 DD {
240 margin-left: 54pt;
241 }
242
243 DL.category DT {
244 font-weight: bold;
245 }
246
247 P.summary {
248 margin-left: 36pt;
249 font-family: monaco, courier, monospace;
250 }
251
252 DIV.summary TABLE {
253 border: solid thin #999999;
254 border-collapse: collapse;
255 border-spacing: 0;
256 margin: 10px;
257 }
258
259 DIV.summary TABLE TD, DIV.summary TABLE TH {
260 border: solid thin #999999;
261 padding: 5px;
262 text-align: left;
263 vertical-align: top;
264 }
265
266 DIV.summary TABLE THEAD TH {
267 background: #eeeeee;
268 }
269
270 /* API documentation styles... */
271 div.body h1 {
272 margin: 0;
273 }
274 div.body h2 {
275 margin-top: 1.5em;
276 }
277 div.body h3, div.body h4, div.body h5 {
278 margin-bottom: 0.5em;
279 margin-top: 1.5em;
280 }
281 .class, .enumeration, .function, .struct, .typedef, .union {
282 border-bottom: solid thin #999999;
283 margin-bottom: 0;
284 margin-top: 2em;
285 }
286 .description {
287 margin-top: 0.5em;
288 }
289 code, p.code, pre, ul.code li {
290 font-family: monaco, courier, monospace;
291 font-size: 90%;
292 }
293 ul.code, ul.contents, ul.subcontents {
294 list-style-type: none;
295 margin: 0;
296 padding-left: 0;
297 }
298 ul.code li {
299 margin: 0;
300 }
301 ul.contents > li {
302 margin-top: 1em;
303 }
304 ul.contents li ul.code, ul.contents li ul.subcontents {
305 padding-left: 2em;
306 }
307 div.body dl {
308 margin-left: 0;
309 margin-top: 0;
310 }
311 div.body dt {
312 font-style: italic;
313 margin-left: 0;
314 margin-top: 0;
315 }
316 div.body dd {
317 margin-bottom: 0.5em;
318 }
319
320 /* This is just for the HTML files generated with the framedhelp target */
321 div.contents {
322 background: #e8e8e8;
323 border: solid thin black;
324 padding: 10px;
325 }
326 div.contents h1 {
327 font-size: 110%;
328 }
329 div.contents h2 {
330 font-size: 100%;
331 }
332 div.contents ul.contents {
333 font-size: 80%;
334 }
335 div.contents ul.subcontents li {
336 margin-left: 1em;
337 text-indent: -1em;
338 }
339 --></style>
340 </head>
341 <body>
342 <div class='body'>
343 <!--
344 "$Id$"
345
346 Introduction to CUPS programming header for the Common UNIX Printing System
347 (CUPS).
348
349 Copyright 2008-2009 by Apple Inc.
350
351 These coded instructions, statements, and computer programs are the
352 property of Apple Inc. and are protected by Federal copyright
353 law. Distribution and use rights are outlined in the file "LICENSE.txt"
354 which should have been included with this file. If this file is
355 file is missing or damaged, see the license at "http://www.cups.org/".
356 -->
357
358 <h1 class='title'>Introduction to CUPS Programming</h1>
359
360 <div class='summary'><table summary='General Information'>
361 <thead>
362 <tr>
363 <th>Headers</th>
364 <th>cups/cups.h<br>
365 cups/array.h<br>
366 cups/backend.h<br>
367 cups/dir.h<br>
368 cups/file.h<br>
369 cups/ppd.h<br>
370 cups/raster.h<br>
371 cups/sidechannel.h</th>
372 </tr>
373 </thead>
374 <tbody>
375 <tr>
376 <th>Libraries</th>
377 <td>-lcups<br>
378 -lcupsimage</td>
379 </tr>
380 <tr>
381 <th>See Also</th>
382 <td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
383 Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
384 Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
385 Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
386 Programming: <a href='api-array.html' target='_top'>Array API</a><br>
387 Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
388 Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
389 Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
390 Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
391 Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
392 References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
393 Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
394 </tr>
395 </tbody>
396 </table></div>
397 <h2 class="title">Contents</h2>
398 <ul class="contents">
399 <li><a href="#OVERVIEW">Overview</a></li>
400 <li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
401 <li><a href="#XCODE">Compiling with Xcode</a></li>
402 <li><a href="#COMMANDLINE">Compiling with GCC</a></li>
403 </ul></li>
404 <li><a href="#WHERETOGO">Where to Go Next</a></li>
405 </ul>
406 <!--
407 "$Id$"
408
409 Introduction to CUPS programming content for CUPS.
410
411 Copyright 2008-2011 by Apple Inc.
412
413 These coded instructions, statements, and computer programs are the
414 property of Apple Inc. and are protected by Federal copyright
415 law. Distribution and use rights are outlined in the file "LICENSE.txt"
416 which should have been included with this file. If this file is
417 file is missing or damaged, see the license at "http://www.cups.org/".
418 -->
419
420 <h2 class="title"><a name="OVERVIEW">Overview</a></h2>
421
422 <p>CUPS provides two libraries that interface with the different parts of the
423 printing system. The "cups" library provides all of the common application and
424 filter functions while the "cupsimage" library provides all of the imaging
425 functions used in raster printer drivers. The "cups" library functions are
426 accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
427 "cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
428 header.</p>
429
430 <h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
431
432 <p>The CUPS libraries can be used from any C, C++, or Objective C program.
433 The method of compiling against the libraries varies depending on the
434 operating system and installation of CUPS. The following sections show how
435 to compile a simple program (shown below) in two common environments.</p>
436
437 <p>The following simple program lists the available printers on the system:</p>
438
439 <pre class="example">
440 #include &lt;stdio.h&gt;
441 #include &lt;cups/cups.h&gt;
442
443 int main(void)
444 {
445 int i;
446 cups_dest_t *dests, *dest;
447 int num_dests = cupsGetDests(&amp;dests);
448
449 for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
450 {
451 if (dest->instance)
452 printf("%s/%s\n", dest->name, dest->instance);
453 else
454 puts(dest->name);
455 }
456
457 return (0);
458 }
459 </pre>
460
461 <h3><a name="XCODE">Compiling with Xcode</a></h3>
462
463 <p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
464 then select the <var>Standard Tool</var> project type under <var>Command Line
465 Utility</var>. Click <var>Next</var> and choose a project directory. Click
466 <var>Next</var> to create the project.</p>
467
468 <p>In the project window, double-click on the <var>Targets</var> group and
469 control-click on the simple target to show the context menu. Choose
470 <var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
471 chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
472 down the file list and select the <var>libcups.dylib</var> file. Click the
473 <var>Add</var> button in the file chooser and attributes sheets.</p>
474
475 <p>In the project window, double-click on the <var>main.c</var> source file.
476 Replace the template source code with the listing above and save it. Click the
477 <var>Build and Go</var> button to build the sample program and run it.</p>
478
479 <h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
480
481 <p>From the command-line, create a file called <var>sample.c</var> using your
482 favorite editor and then run the following command to compile it with GCC and
483 run it:</p>
484
485 <pre class="command">
486 gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
487 ./simple
488 </pre>
489
490 <p>The <code>cups-config</code> command provides the compiler flags
491 ("cups-config --cflags") and libraries ("cups-config --libs") needed for the
492 local system.</p>
493
494 <h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
495
496 <p>If you are developing a print filter, driver, or backend, see the
497 <a href="api-filter.html" target="_top">Filter and Backend Programming</a>
498 guide. Raster printer driver developers should also read the
499 <a href="api-raster.html" target="_top">Raster API</a> reference.</p>
500 </div>
501 </body>
502 </html>