[thirdparty/cups.git] / doc / help / api-overview.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
	<title>Introduction to CUPS Programming	</title>
	<meta name="keywords" content="Programming">
	<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
	<meta name="creator" content="Mini-XML v2.7">
<style type="text/css"><!--
BODY {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

H1, H2, H3, H4, H5, H6, P, TD, TH {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

KBD {
  font-family: monaco, courier, monospace;
  font-weight: bold;
}

PRE {
  font-family: monaco, courier, monospace;
}

PRE.command {
  border: dotted thin #7f7f7f;
  margin-left: 36pt;
  padding: 10px;
}

P.compact {
  margin: 0;
}

P.example {
  font-style: italic;
  margin-left: 36pt;
}
  
PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 10pt;
}

PRE.command EM, PRE.example EM {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

P.command {
  font-family: monaco, courier, monospace;
  margin-left: 36pt;
}

P.formula {
  font-style: italic;
  margin-left: 36pt;
}

BLOCKQUOTE {
  background: #eeeeee;
  border: solid thin #999999;
  padding: 10pt;
}

A IMG {
  border: none;
}

A:link:hover IMG {
  background: #f0f0f0;
  border-radius: 10px;
  -moz-border-radius: 10px;
}

A:link, A:visited {
  font-weight: normal;
  text-decoration: none;
}

A:link:hover, A:visited:hover, A:active {
  text-decoration: underline;
}

SUB, SUP {
  font-size: 50%;
}

TR.data, TD.data, TR.data TD {
  margin-top: 10pt;
  padding: 5pt;
  border-bottom: solid 1pt #999999;
}

TR.data TH {
  border-bottom: solid 1pt #999999;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
}

DIV.table TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin-left: auto;
  margin-right: auto;
}

DIV.table CAPTION {
  caption-side: top;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

DIV.table TABLE TD {
  border: solid thin #cccccc;
  padding-top: 5pt;
}

DIV.table TABLE TH {
  background: #cccccc;
  border: none;
  border-bottom: solid thin #999999;
}

DIV.figure TABLE {
  margin-left: auto;
  margin-right: auto;
}

DIV.figure CAPTION {
  caption-side: bottom;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

TH.label {
  text-align: right;
  vertical-align: top;
}

TH.sublabel {
  text-align: right;
  font-weight: normal;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: black;
  border: thin solid black;
  color: white;
  font-size: 80%;
  font-style: italic;
  font-weight: bold;
  white-space: nowrap;
}

H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
  float: right;
  font-size: 100%;
}

H1.title {
}

H2.title, H3.title {
  border-bottom: solid 2pt #000000;
}

DIV.indent, TABLE.indent {
  margin-top: 2em;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.indent {
  border-collapse: collapse;
}

TABLE.indent TD, TABLE.indent TH {
  padding: 0;
}

TABLE.list {
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.list TH {
  background: white;
  border-bottom: solid thin #cccccc;
  color: #444444;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
  vertical-align: bottom;
  white-space: nowrap;
}

TABLE.list TH A {
  color: #4444cc;
}

TABLE.list TD {
  border-bottom: solid thin #eeeeee;
  padding-top: 5pt;
  padding-left: 5pt;
}

TABLE.list TR:nth-child(even) {
  background: #f8f8f8;
}

TABLE.list TR:nth-child(odd) {
  background: #f4f4f4;
}

DT {
  margin-left: 36pt;
  margin-top: 12pt;
}

DD {
  margin-left: 54pt;
}

DL.category DT {
  font-weight: bold;
}

P.summary {
  margin-left: 36pt;
  font-family: monaco, courier, monospace;
}

DIV.summary TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin: 10px;
}

DIV.summary TABLE TD, DIV.summary TABLE TH {
  border: solid thin #999999;
  padding: 5px;
  text-align: left;
  vertical-align: top;
}

DIV.summary TABLE THEAD TH {
  background: #eeeeee;
}

/* API documentation styles... */
div.body h1 {
  margin: 0;
}
div.body h2 {
  margin-top: 1.5em;
}
div.body h3, div.body h4, div.body h5 {
  margin-bottom: 0.5em;
  margin-top: 1.5em;
}
.class, .enumeration, .function, .struct, .typedef, .union {
  border-bottom: solid thin #999999;
  margin-bottom: 0;
  margin-top: 2em;
}
.description {
  margin-top: 0.5em;
}
code, p.code, pre, ul.code li {
  font-family: monaco, courier, monospace;
  font-size: 90%;
}
ul.code, ul.contents, ul.subcontents {
  list-style-type: none;
  margin: 0;
  padding-left: 0;
}
ul.code li {
  margin: 0;
}
ul.contents > li {
  margin-top: 1em;
}
ul.contents li ul.code, ul.contents li ul.subcontents {
  padding-left: 2em;
}
div.body dl {
  margin-left: 0;
  margin-top: 0;
}
div.body dt {
  font-style: italic;
  margin-left: 0;
  margin-top: 0;
}
div.body dd {
  margin-bottom: 0.5em;
}

/* This is just for the HTML files generated with the framedhelp target */
div.contents {
  background: #e8e8e8;
  border: solid thin black;
  padding: 10px;
}
div.contents h1 {
  font-size: 110%;
}
div.contents h2 {
  font-size: 100%;
}
div.contents ul.contents {
  font-size: 80%;
}
div.contents ul.subcontents li {
  margin-left: 1em;
  text-indent: -1em;
}
--></style>
</head>
<body>
<div class='body'>
<!--
  "$Id$"

  Introduction to CUPS programming header for the Common UNIX Printing System
  (CUPS).

  Copyright 2008-2009 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h1 class='title'>Introduction to CUPS Programming</h1>

<div class='summary'><table summary='General Information'>
<thead>
<tr>
	<th>Headers</th>
	<th>cups/cups.h<br>
	cups/array.h<br>
	cups/backend.h<br>
	cups/dir.h<br>
	cups/file.h<br>
	cups/ppd.h<br>
	cups/raster.h<br>
	cups/sidechannel.h</th>
</tr>
</thead>
<tbody>
<tr>
	<th>Libraries</th>
	<td>-lcups<br>
	-lcupsimage</td>
</tr>
<tr>
	<th>See Also</th>
	<td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
	Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
	Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
	Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
	Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
</tr>
</tbody>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
<li><a href="#OVERVIEW">Overview</a></li>
<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
	<li><a href="#XCODE">Compiling with Xcode</a></li>
	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
</ul></li>
<li><a href="#WHERETOGO">Where to Go Next</a></li>
</ul>
<!--
  "$Id$"

  Introduction to CUPS programming content for CUPS.

  Copyright 2008-2011 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h2 class="title"><a name="OVERVIEW">Overview</a></h2>

<p>CUPS provides two libraries that interface with the different parts of the
printing system. The "cups" library provides all of the common application and
filter functions while the "cupsimage" library provides all of the imaging
functions used in raster printer drivers. The "cups" library functions are
accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
"cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
header.</p>

<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>

<p>The CUPS libraries can be used from any C, C++, or Objective C program.
The method of compiling against the libraries varies depending on the
operating system and installation of CUPS. The following sections show how
to compile a simple program (shown below) in two common environments.</p>

<p>The following simple program lists the available printers on the system:</p>

<pre class="example">
#include &lt;stdio.h&gt;
#include &lt;cups/cups.h&gt;

int main(void)
{
  int i;
  cups_dest_t *dests, *dest;
  int num_dests = cupsGetDests(&amp;dests);

  for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
  {
    if (dest->instance)
      printf("%s/%s\n", dest->name, dest->instance);
    else
      puts(dest->name);
  }

  return (0);
}
</pre>

<h3><a name="XCODE">Compiling with Xcode</a></h3>

<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
then select the <var>Standard Tool</var> project type under <var>Command Line
Utility</var>. Click <var>Next</var> and choose a project directory. Click
<var>Next</var> to create the project.</p>

<p>In the project window, double-click on the <var>Targets</var> group and
control-click on the simple target to show the context menu. Choose
<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
down the file list and select the <var>libcups.dylib</var> file. Click the
<var>Add</var> button in the file chooser and attributes sheets.</p>

<p>In the project window, double-click on the <var>main.c</var> source file.
Replace the template source code with the listing above and save it. Click the
<var>Build and Go</var> button to build the sample program and run it.</p>

<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>

<p>From the command-line, create a file called <var>sample.c</var> using your
favorite editor and then run the following command to compile it with GCC and
run it:</p>

<pre class="command">
gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
./simple
</pre>

<p>The <code>cups-config</code> command provides the compiler flags
("cups-config --cflags") and libraries ("cups-config --libs") needed for the
local system.</p>

<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>

<p>If you are developing a print filter, driver, or backend, see the
<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
guide. Raster printer driver developers should also read the
<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
</div>
</body>
</html>
Commit	Line	Data
745129be	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5a738aea MS	2	<html>
	3	<!-- SECTION: Programming -->
	4	<head>
0268488e MS	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">
5a738aea MS	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 {
10d09e33	28	border: dotted thin #7f7f7f;
5a738aea	29	margin-left: 36pt;
10d09e33	30	padding: 10px;
5a738aea MS	31	}
5a738aea MS	32
f11a948a MS	33	P.compact {
	34	margin: 0;
	35	}
	36
e4572d57 MS	37	P.example {
	38	font-style: italic;
	39	margin-left: 36pt;
	40	}
	41
5a738aea MS	42	PRE.example {
	43	background: #eeeeee;
	44	border: dotted thin #999999;
	45	margin-left: 36pt;
178cb736	46	padding: 10pt;
5a738aea MS	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 {
178cb736	64	background: #eeeeee;
5a738aea MS	65	border: solid thin #999999;
	66	padding: 10pt;
	67	}
	68
e4572d57 MS	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
5a738aea	79	A:link, A:visited {
568fa3fa	80	font-weight: normal;
5a738aea	81	text-decoration: none;
5a738aea MS	82	}
	83
	84	A:link:hover, A:visited:hover, A:active {
	85	text-decoration: underline;
5a738aea MS	86	}
	87
	88	SUB, SUP {
	89	font-size: 50%;
	90	}
	91
e4572d57 MS	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
5a738aea MS	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 {
5a738aea MS	148	text-align: right;
	149	vertical-align: top;
	150	}
	151
e4572d57 MS	152	TH.sublabel {
	153	text-align: right;
	154	font-weight: normal;
	155	}
	156
5a738aea MS	157	HR {
	158	border: solid thin;
	159	}
	160
	161	SPAN.info {
e4572d57 MS	162	background: black;
	163	border: thin solid black;
	164	color: white;
5a738aea MS	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
178cb736 MS	176	H1.title {
	177	}
	178
5a738aea MS	179	H2.title, H3.title {
	180	border-bottom: solid 2pt #000000;
	181	}
	182
e4572d57 MS	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
5a738aea MS	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
5a738aea MS	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	}
ac884b6a MS	335	div.contents ul.subcontents li {
	336	margin-left: 1em;
	337	text-indent: -1em;
	338	}
5a738aea MS	339	--></style>
	340	</head>
	341	<body>
	342	<div class='body'>
	343	<!--
68b10830	344	"$Id$"
5a738aea MS	345
	346	Introduction to CUPS programming header for the Common UNIX Printing System
	347	(CUPS).
	348
178cb736	349	Copyright 2008-2009 by Apple Inc.
5a738aea MS	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
178cb736 MS	358	<h1 class='title'>Introduction to CUPS Programming</h1>
178cb736 MS	359
5a738aea MS	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>
e4572d57 MS	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>
5a738aea	386	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
e4572d57	387	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
5a738aea	388	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
5a738aea MS	389	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
5a738aea MS	390	Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
e4572d57 MS	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>
5a738aea MS	394	</tr>
	395	</tbody>
	396	</table></div>
	397	<h2 class="title">Contents</h2>
	398	<ul class="contents">
5a738aea MS	399	<li><a href="#OVERVIEW">Overview</a></li>
5a738aea MS	400	<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
0268488e MS	401	<li><a href="#XCODE">Compiling with Xcode</a></li>
0268488e MS	402	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
8b450588	403	</ul></li>
5a738aea	404	<li><a href="#WHERETOGO">Where to Go Next</a></li>
0268488e	405	</ul>
5a738aea	406	<!--
68b10830	407	"$Id$"
5a738aea	408
eac3a0a0	409	Introduction to CUPS programming content for CUPS.
5a738aea	410
eac3a0a0	411	Copyright 2008-2011 by Apple Inc.
5a738aea MS	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><cups/cups.h></var> header, while
	427	"cupsimage" functions are found in the <var><cups/raster.h></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 <stdio.h>
	441	#include <cups/cups.h>
	442
	443	int main(void)
	444	{
	445	int i;
	446	cups_dest_t dests, dest;
	447	int num_dests = cupsGetDests(&dests);
	448
	449	for (i = num_dests, dest = dests; i > 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>