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