[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: 10px;
}

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: #cccccc;
  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%;
}

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 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/".
-->

<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;
	43	padding: 10px;
	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 {
	61	background: #cccccc;
	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
	173	H2.title, H3.title {
	174	border-bottom: solid 2pt #000000;
	175	}
	176
e4572d57 MS	177	DIV.indent, TABLE.indent {
	178	margin-top: 2em;
	179	margin-left: auto;
	180	margin-right: auto;
	181	width: 90%;
	182	}
	183
	184	TABLE.indent {
	185	border-collapse: collapse;
	186	}
	187
	188	TABLE.indent TD, TABLE.indent TH {
	189	padding: 0;
	190	}
	191
	192	TABLE.list {
	193	border-collapse: collapse;
	194	margin-left: auto;
	195	margin-right: auto;
	196	width: 90%;
	197	}
	198
	199	TABLE.list TH {
	200	background: white;
	201	border-bottom: solid thin #cccccc;
	202	color: #444444;
	203	padding-top: 10pt;
	204	padding-left: 5pt;
	205	text-align: left;
	206	vertical-align: bottom;
	207	white-space: nowrap;
	208	}
	209
	210	TABLE.list TH A {
	211	color: #4444cc;
	212	}
	213
	214	TABLE.list TD {
	215	border-bottom: solid thin #eeeeee;
	216	padding-top: 5pt;
	217	padding-left: 5pt;
	218	}
	219
	220	TABLE.list TR:nth-child(even) {
	221	background: #f8f8f8;
	222	}
	223
	224	TABLE.list TR:nth-child(odd) {
	225	background: #f4f4f4;
	226	}
	227
5a738aea MS	228	DT {
	229	margin-left: 36pt;
	230	margin-top: 12pt;
	231	}
	232
	233	DD {
	234	margin-left: 54pt;
	235	}
	236
	237	DL.category DT {
	238	font-weight: bold;
	239	}
	240
	241	P.summary {
	242	margin-left: 36pt;
	243	font-family: monaco, courier, monospace;
	244	}
	245
5a738aea MS	246	DIV.summary TABLE {
	247	border: solid thin #999999;
	248	border-collapse: collapse;
	249	border-spacing: 0;
	250	margin: 10px;
	251	}
	252
	253	DIV.summary TABLE TD, DIV.summary TABLE TH {
	254	border: solid thin #999999;
	255	padding: 5px;
	256	text-align: left;
	257	vertical-align: top;
	258	}
	259
	260	DIV.summary TABLE THEAD TH {
	261	background: #eeeeee;
	262	}
	263
	264	/* API documentation styles... */
	265	div.body h1 {
	266	margin: 0;
	267	}
	268	div.body h2 {
	269	margin-top: 1.5em;
	270	}
	271	div.body h3, div.body h4, div.body h5 {
	272	margin-bottom: 0.5em;
	273	margin-top: 1.5em;
	274	}
	275	.class, .enumeration, .function, .struct, .typedef, .union {
	276	border-bottom: solid thin #999999;
	277	margin-bottom: 0;
	278	margin-top: 2em;
	279	}
	280	.description {
	281	margin-top: 0.5em;
	282	}
	283	code, p.code, pre, ul.code li {
	284	font-family: monaco, courier, monospace;
	285	font-size: 90%;
	286	}
	287	ul.code, ul.contents, ul.subcontents {
	288	list-style-type: none;
	289	margin: 0;
	290	padding-left: 0;
	291	}
	292	ul.code li {
	293	margin: 0;
	294	}
	295	ul.contents > li {
	296	margin-top: 1em;
	297	}
	298	ul.contents li ul.code, ul.contents li ul.subcontents {
	299	padding-left: 2em;
	300	}
	301	div.body dl {
	302	margin-left: 0;
	303	margin-top: 0;
	304	}
	305	div.body dt {
	306	font-style: italic;
	307	margin-left: 0;
	308	margin-top: 0;
	309	}
310	div.body dd {
311	margin-bottom: 0.5em;
312	}
313
314	/* This is just for the HTML files generated with the framedhelp target */
315	div.contents {
316	background: #e8e8e8;
317	border: solid thin black;
318	padding: 10px;
319	}
320	div.contents h1 {
321	font-size: 110%;
322	}
323	div.contents h2 {
324	font-size: 100%;
325	}
326	div.contents ul.contents {
327	font-size: 80%;
328	}
ac884b6a MS	329	div.contents ul.subcontents li {
	330	margin-left: 1em;
	331	text-indent: -1em;
	332	}
5a738aea MS	333	--></style>
	334	</head>
	335	<body>
	336	<div class='body'>
	337	<!--
	338	"$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
	339
	340	Introduction to CUPS programming header for the Common UNIX Printing System
	341	(CUPS).
	342
	343	Copyright 2008 by Apple Inc.
	344
	345	These coded instructions, statements, and computer programs are the
	346	property of Apple Inc. and are protected by Federal copyright
	347	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	348	which should have been included with this file. If this file is
	349	file is missing or damaged, see the license at "http://www.cups.org/".
	350	-->
	351
5a738aea MS	352	<div class='summary'><table summary='General Information'>
	353	<thead>
	354	<tr>
	355	<th>Headers</th>
	356	<th>cups/cups.h<br>
	357	cups/array.h<br>
	358	cups/backend.h<br>
	359	cups/dir.h<br>
	360	cups/file.h<br>
	361	cups/ppd.h<br>
	362	cups/raster.h<br>
	363	cups/sidechannel.h</th>
	364	</tr>
	365	</thead>
	366	<tbody>
	367	<tr>
	368	<th>Libraries</th>
	369	<td>-lcups<br>
	370	-lcupsimage</td>
	371	</tr>
	372	<tr>
	373	<th>See Also</th>
e4572d57 MS	374	<td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
	375	Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
	376	Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
	377	Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
5a738aea	378	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
e4572d57	379	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
5a738aea	380	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
5a738aea MS	381	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
5a738aea MS	382	Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
e4572d57 MS	383	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	384	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	385	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
5a738aea MS	386	</tr>
	387	</tbody>
	388	</table></div>
	389	<h2 class="title">Contents</h2>
	390	<ul class="contents">
426c6a59	391	<ul class="subcontents">
5a738aea MS	392	<li><a href="#OVERVIEW">Overview</a></li>
	393	<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
	394	<li><a href="#XCODE">Compiling with Xcode</a></li>
	395	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
8b450588	396	</ul></li>
5a738aea	397	<li><a href="#WHERETOGO">Where to Go Next</a></li>
5a738aea MS	398	<!--
	399	"$Id: api-cups.header 7279 2008-01-31 01:50:44Z mike $"
	400
	401	Introduction to CUPS programming content for the Common UNIX Printing System
	402	(CUPS).
	403
	404	Copyright 2008 by Apple Inc.
	405
	406	These coded instructions, statements, and computer programs are the
	407	property of Apple Inc. and are protected by Federal copyright
	408	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	409	which should have been included with this file. If this file is
	410	file is missing or damaged, see the license at "http://www.cups.org/".
	411	-->
	412
	413	<h2 class="title"><a name="OVERVIEW">Overview</a></h2>
	414
	415	<p>CUPS provides two libraries that interface with the different parts of the
	416	printing system. The "cups" library provides all of the common application and
	417	filter functions while the "cupsimage" library provides all of the imaging
	418	functions used in raster printer drivers. The "cups" library functions are
	419	accessed by including the <var><cups/cups.h></var> header, while
	420	"cupsimage" functions are found in the <var><cups/raster.h></var>
	421	header.</p>
	422
	423	<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
	424
	425	<p>The CUPS libraries can be used from any C, C++, or Objective C program.
	426	The method of compiling against the libraries varies depending on the
	427	operating system and installation of CUPS. The following sections show how
	428	to compile a simple program (shown below) in two common environments.</p>
	429
	430	<p>The following simple program lists the available printers on the system:</p>
	431
	432	<pre class="example">
	433	#include <stdio.h>
	434	#include <cups/cups.h>
	435
	436	int main(void)
	437	{
	438	int i;
	439	cups_dest_t dests, dest;
	440	int num_dests = cupsGetDests(&dests);
	441
	442	for (i = num_dests, dest = dests; i > 0; i --, dest ++)
	443	{
	444	if (dest->instance)
	445	printf("%s/%s\n", dest->name, dest->instance);
	446	else
	447	puts(dest->name);
	448	}
	449
	450	return (0);
	451	}
	452	</pre>
	453
	454	<h3><a name="XCODE">Compiling with Xcode</a></h3>
	455
	456	<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
	457	then select the <var>Standard Tool</var> project type under <var>Command Line
	458	Utility</var>. Click <var>Next</var> and choose a project directory. Click
	459	<var>Next</var> to create the project.</p>
	460
	461	<p>In the project window, double-click on the <var>Targets</var> group and
462	control-click on the simple target to show the context menu. Choose
463	<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
464	chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
465	down the file list and select the <var>libcups.dylib</var> file. Click the
466	<var>Add</var> button in the file chooser and attributes sheets.</p>
467
468	<p>In the project window, double-click on the <var>main.c</var> source file.
469	Replace the template source code with the listing above and save it. Click the
470	<var>Build and Go</var> button to build the sample program and run it.</p>
471
472	<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
473
474	<p>From the command-line, create a file called <var>sample.c</var> using your
475	favorite editor and then run the following command to compile it with GCC and
476	run it:</p>
477
478	<pre class="command">
479	gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
480	./simple
481	</pre>
482
483	<p>The <code>cups-config</code> command provides the compiler flags
484	("cups-config --cflags") and libraries ("cups-config --libs") needed for the
485	local system.</p>
486
487	<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
488
489	<p>If you are developing a print filter, driver, or backend, see the
490	<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
491	guide. Raster printer driver developers should also read the
492	<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
493	</div>
494	</body>
495	</html>