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