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