[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: 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'>
<!--
  "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"

  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>
<!--
  "$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"

  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	}
ca6b43fc	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 {
ca6b43fc	80	font-weight: inherit;
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	<!--
9c0e8e5d	344	"$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
5a738aea	345
321d8d57	346	Introduction to CUPS programming header for CUPS.
5a738aea	347
321d8d57	348	Copyright 2008-2011 by Apple Inc.
5a738aea MS	349
	350	These coded instructions, statements, and computer programs are the
	351	property of Apple Inc. and are protected by Federal copyright
	352	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	353	which should have been included with this file. If this file is
	354	file is missing or damaged, see the license at "http://www.cups.org/".
	355	-->
	356
178cb736 MS	357	<h1 class='title'>Introduction to CUPS Programming</h1>
178cb736 MS	358
5a738aea MS	359	<div class='summary'><table summary='General Information'>
	360	<thead>
	361	<tr>
	362	<th>Headers</th>
	363	<th>cups/cups.h<br>
	364	cups/array.h<br>
	365	cups/backend.h<br>
	366	cups/dir.h<br>
	367	cups/file.h<br>
	368	cups/ppd.h<br>
	369	cups/raster.h<br>
	370	cups/sidechannel.h</th>
	371	</tr>
	372	</thead>
	373	<tbody>
	374	<tr>
	375	<th>Libraries</th>
	376	<td>-lcups<br>
	377	-lcupsimage</td>
	378	</tr>
	379	<tr>
	380	<th>See Also</th>
e4572d57 MS	381	<td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
	382	Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
	383	Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
	384	Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
5a738aea	385	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
e4572d57	386	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
5a738aea	387	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
5a738aea MS	388	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
5a738aea MS	389	Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
e4572d57 MS	390	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	391	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	392	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
5a738aea MS	393	</tr>
	394	</tbody>
	395	</table></div>
	396	<h2 class="title">Contents</h2>
	397	<ul class="contents">
5a738aea MS	398	<li><a href="#OVERVIEW">Overview</a></li>
5a738aea MS	399	<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
0268488e MS	400	<li><a href="#XCODE">Compiling with Xcode</a></li>
0268488e MS	401	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
8b450588	402	</ul></li>
5a738aea	403	<li><a href="#WHERETOGO">Where to Go Next</a></li>
0268488e	404	</ul>
5a738aea	405	<!--
9c0e8e5d	406	"$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
5a738aea	407
eac3a0a0	408	Introduction to CUPS programming content for CUPS.
5a738aea	409
eac3a0a0	410	Copyright 2008-2011 by Apple Inc.
5a738aea MS	411
	412	These coded instructions, statements, and computer programs are the
	413	property of Apple Inc. and are protected by Federal copyright
	414	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	415	which should have been included with this file. If this file is
	416	file is missing or damaged, see the license at "http://www.cups.org/".
	417	-->
	418
	419	<h2 class="title"><a name="OVERVIEW">Overview</a></h2>
	420
	421	<p>CUPS provides two libraries that interface with the different parts of the
	422	printing system. The "cups" library provides all of the common application and
	423	filter functions while the "cupsimage" library provides all of the imaging
	424	functions used in raster printer drivers. The "cups" library functions are
	425	accessed by including the <var><cups/cups.h></var> header, while
	426	"cupsimage" functions are found in the <var><cups/raster.h></var>
	427	header.</p>
	428
	429	<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
	430
	431	<p>The CUPS libraries can be used from any C, C++, or Objective C program.
	432	The method of compiling against the libraries varies depending on the
	433	operating system and installation of CUPS. The following sections show how
	434	to compile a simple program (shown below) in two common environments.</p>
	435
	436	<p>The following simple program lists the available printers on the system:</p>
	437
	438	<pre class="example">
	439	#include <stdio.h>
	440	#include <cups/cups.h>
	441
	442	int main(void)
	443	{
	444	int i;
	445	cups_dest_t dests, dest;
	446	int num_dests = cupsGetDests(&dests);
	447
	448	for (i = num_dests, dest = dests; i > 0; i --, dest ++)
	449	{
	450	if (dest->instance)
	451	printf("%s/%s\n", dest->name, dest->instance);
	452	else
	453	puts(dest->name);
	454	}
	455
	456	return (0);
	457	}
	458	</pre>
	459
	460	<h3><a name="XCODE">Compiling with Xcode</a></h3>
	461
	462	<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
	463	then select the <var>Standard Tool</var> project type under <var>Command Line
	464	Utility</var>. Click <var>Next</var> and choose a project directory. Click
	465	<var>Next</var> to create the project.</p>
	466
	467	<p>In the project window, double-click on the <var>Targets</var> group and
	468	control-click on the simple target to show the context menu. Choose
	469	<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
	470	chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
	471	down the file list and select the <var>libcups.dylib</var> file. Click the
	472	<var>Add</var> button in the file chooser and attributes sheets.</p>
	473
	474	<p>In the project window, double-click on the <var>main.c</var> source file.
475	Replace the template source code with the listing above and save it. Click the
476	<var>Build and Go</var> button to build the sample program and run it.</p>
477
478	<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
479
480	<p>From the command-line, create a file called <var>sample.c</var> using your
481	favorite editor and then run the following command to compile it with GCC and
482	run it:</p>
483
484	<pre class="command">
485	gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
486	./simple
487	</pre>
488
489	<p>The <code>cups-config</code> command provides the compiler flags
490	("cups-config --cflags") and libraries ("cups-config --libs") needed for the
491	local system.</p>
492
493	<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
494
495	<p>If you are developing a print filter, driver, or backend, see the
496	<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
497	guide. Raster printer driver developers should also read the
498	<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
499	</div>
500	</body>
501	</html>