[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-2016 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/adminutil.h<br>
	cups/array.h<br>
	cups/dir.h<br>
	cups/file.h<br>
	cups/http.h<br>
	cups/ipp.h<br>
	cups/language.h<br>
	cups/ppd.h<br>
	cups/pwg.h<br>
	cups/raster.h</th>
</tr>
</thead>
<tbody>
<tr>
	<th>Libraries</th>
	<td>-lcups</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-admin.html' target='_top'>Administrative APIs</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 (DEPRECATED)</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
	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	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
	54	PRE.example {
	55	background: #eeeeee;
	56	border: dotted thin #999999;
	57	margin-left: 36pt;
	58	padding: 10pt;
	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 {
	76	background: #eeeeee;
	77	border: solid thin #999999;
	78	padding: 10pt;
	79	}
	80
	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
	91	A:link, A:visited {
	92	font-weight: inherit;
	93	text-decoration: none;
	94	}
	95
	96	A:link:hover, A:visited:hover, A:active {
	97	text-decoration: underline;
	98	}
	99
	100	SUB, SUP {
	101	font-size: 50%;
	102	}
	103
	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
	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 {
	160	text-align: right;
	161	vertical-align: top;
	162	}
	163
	164	TH.sublabel {
	165	text-align: right;
	166	font-weight: normal;
	167	}
	168
	169	HR {
	170	border: solid thin;
	171	}
	172
	173	SPAN.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
	183	H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
	184	float: right;
	185	font-size: 100%;
	186	}
	187
	188	H1.title {
	189	}
	190
	191	H2.title, H3.title {
	192	border-bottom: solid 2pt #000000;
	193	}
	194
	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
	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
	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	}
	347	div.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	Introduction to CUPS programming header for CUPS.
	357
	358	Copyright 2008-2016 by Apple Inc.
	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
	367	<h1 class='title'>Introduction to CUPS Programming</h1>
	368
	369	<div class='summary'><table summary='General Information'>
	370	<thead>
	371	<tr>
	372	<th>Headers</th>
	373	<th>cups/cups.h<br>
	374	cups/adminutil.h<br>
	375	cups/array.h<br>
	376	cups/dir.h<br>
	377	cups/file.h<br>
	378	cups/http.h<br>
	379	cups/ipp.h<br>
	380	cups/language.h<br>
	381	cups/ppd.h<br>
	382	cups/pwg.h<br>
	383	cups/raster.h</th>
	384	</tr>
	385	</thead>
	386	<tbody>
	387	<tr>
	388	<th>Libraries</th>
	389	<td>-lcups</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-admin.html' target='_top'>Administrative APIs</a><br>
	398	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
	399	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
	400	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
	401	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
	402	Programming: <a href='api-ppd.html' target='_top'>PPD API (DEPRECATED)</a><br>
	403	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	404	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	405	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
	406	</tr>
	407	</tbody>
	408	</table></div>
	409	<h2 class="title">Contents</h2>
	410	<ul class="contents">
	411	<li><a href="#OVERVIEW">Overview</a></li>
	412	<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
	413	<li><a href="#XCODE">Compiling with Xcode</a></li>
	414	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
	415	</ul></li>
	416	<li><a href="#WHERETOGO">Where to Go Next</a></li>
	417	</ul>
	418	<!--
	419	Introduction to CUPS programming content for CUPS.
	420
	421	Copyright 2008-2011 by Apple Inc.
	422
	423	These coded instructions, statements, and computer programs are the
	424	property of Apple Inc. and are protected by Federal copyright
	425	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	426	which should have been included with this file. If this file is
	427	file is missing or damaged, see the license at "http://www.cups.org/".
	428	-->
	429
	430	<h2 class="title"><a name="OVERVIEW">Overview</a></h2>
	431
	432	<p>CUPS provides two libraries that interface with the different parts of the
	433	printing system. The "cups" library provides all of the common application and
	434	filter functions while the "cupsimage" library provides all of the imaging
	435	functions used in raster printer drivers. The "cups" library functions are
	436	accessed by including the <var><cups/cups.h></var> header, while
	437	"cupsimage" functions are found in the <var><cups/raster.h></var>
	438	header.</p>
	439
	440	<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
	441
	442	<p>The CUPS libraries can be used from any C, C++, or Objective C program.
	443	The method of compiling against the libraries varies depending on the
	444	operating system and installation of CUPS. The following sections show how
	445	to compile a simple program (shown below) in two common environments.</p>
	446
	447	<p>The following simple program lists the available printers on the system:</p>
	448
	449	<pre class="example">
	450	#include <stdio.h>
	451	#include <cups/cups.h>
	452
	453	int main(void)
	454	{
	455	int i;
	456	cups_dest_t dests, dest;
	457	int num_dests = cupsGetDests(&dests);
	458
	459	for (i = num_dests, dest = dests; i > 0; i --, dest ++)
	460	{
	461	if (dest->instance)
	462	printf("%s/%s\n", dest->name, dest->instance);
	463	else
	464	puts(dest->name);
	465	}
	466
	467	return (0);
	468	}
	469	</pre>
	470
	471	<h3><a name="XCODE">Compiling with Xcode</a></h3>
	472
	473	<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
	474	then select the <var>Standard Tool</var> project type under <var>Command Line
	475	Utility</var>. Click <var>Next</var> and choose a project directory. Click
	476	<var>Next</var> to create the project.</p>
	477
	478	<p>In the project window, double-click on the <var>Targets</var> group and
	479	control-click on the simple target to show the context menu. Choose
	480	<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
	481	chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
	482	down the file list and select the <var>libcups.dylib</var> file. Click the
	483	<var>Add</var> button in the file chooser and attributes sheets.</p>
	484
	485	<p>In the project window, double-click on the <var>main.c</var> source file.
	486	Replace the template source code with the listing above and save it. Click the
	487	<var>Build and Go</var> button to build the sample program and run it.</p>
	488
	489	<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
	490
	491	<p>From the command-line, create a file called <var>sample.c</var> using your
	492	favorite editor and then run the following command to compile it with GCC and
	493	run it:</p>
	494
	495	<pre class="command">
	496	gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
	497	./simple
	498	</pre>
	499
	500	<p>The <code>cups-config</code> command provides the compiler flags
	501	("cups-config --cflags") and libraries ("cups-config --libs") needed for the
	502	local system.</p>
	503
	504	<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
	505
	506	<p>If you are developing a print filter, driver, or backend, see the
	507	<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
	508	guide. Raster printer driver developers should also read the
	509	<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
	510	</div>
	511	</body>
	512	</html>