[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 name="creator" content="Mini-XML v2.6">
<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 {
  margin-left: 36pt;
}

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

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

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

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