[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;
}

DL.man DD {
  margin-left: 5em;
}

DL.man DT {
  margin-left: 0;
}

PRE.man {
  margin: 0;
}

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: inherit;
  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'>
<!--
  Introduction to CUPS programming header 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/".
-->

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