[thirdparty/cups.git] / doc / help / api-overview.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
	<title>Introduction to CUPS Programming	</title>
	<meta name="keywords" content="Programming">
	<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
	<meta name="creator" content="Mini-XML v2.7">
<style type="text/css"><!--
BODY {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

H1, H2, H3, H4, H5, H6, P, TD, TH {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

KBD {
  font-family: monaco, courier, monospace;
  font-weight: bold;
}

PRE {
  font-family: monaco, courier, monospace;
}

PRE.command {
  border: dotted thin #7f7f7f;
  margin-left: 36pt;
  padding: 10px;
}

P.compact {
  margin: 0;
}

P.example {
  font-style: italic;
  margin-left: 36pt;
}

DL.man DD {
  margin-left: 5em;
}

DL.man DT {
  margin-left: 0;
}

PRE.man {
  margin: 0;
}

PRE.example {
  background: #eeeeee;
  border: dotted thin #999999;
  margin-left: 36pt;
  padding: 10pt;
}

PRE.command EM, PRE.example EM {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
}

P.command {
  font-family: monaco, courier, monospace;
  margin-left: 36pt;
}

P.formula {
  font-style: italic;
  margin-left: 36pt;
}

BLOCKQUOTE {
  background: #eeeeee;
  border: solid thin #999999;
  padding: 10pt;
}

A IMG {
  border: none;
}

A:link:hover IMG {
  background: #f0f0f0;
  border-radius: 10px;
  -moz-border-radius: 10px;
}

A:link, A:visited {
  font-weight: inherit;
  text-decoration: none;
}

A:link:hover, A:visited:hover, A:active {
  text-decoration: underline;
}

SUB, SUP {
  font-size: 50%;
}

TR.data, TD.data, TR.data TD {
  margin-top: 10pt;
  padding: 5pt;
  border-bottom: solid 1pt #999999;
}

TR.data TH {
  border-bottom: solid 1pt #999999;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
}

DIV.table TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin-left: auto;
  margin-right: auto;
}

DIV.table CAPTION {
  caption-side: top;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

DIV.table TABLE TD {
  border: solid thin #cccccc;
  padding-top: 5pt;
}

DIV.table TABLE TH {
  background: #cccccc;
  border: none;
  border-bottom: solid thin #999999;
}

DIV.figure TABLE {
  margin-left: auto;
  margin-right: auto;
}

DIV.figure CAPTION {
  caption-side: bottom;
  font-size: 120%;
  font-style: italic;
  font-weight: bold;
  margin-left: auto;
  margin-right: auto;
}

TH.label {
  text-align: right;
  vertical-align: top;
}

TH.sublabel {
  text-align: right;
  font-weight: normal;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: black;
  border: thin solid black;
  color: white;
  font-size: 80%;
  font-style: italic;
  font-weight: bold;
  white-space: nowrap;
}

H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
  float: right;
  font-size: 100%;
}

H1.title {
}

H2.title, H3.title {
  border-bottom: solid 2pt #000000;
}

DIV.indent, TABLE.indent {
  margin-top: 2em;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.indent {
  border-collapse: collapse;
}

TABLE.indent TD, TABLE.indent TH {
  padding: 0;
}

TABLE.list {
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
  width: 90%;
}

TABLE.list TH {
  background: white;
  border-bottom: solid thin #cccccc;
  color: #444444;
  padding-top: 10pt;
  padding-left: 5pt;
  text-align: left;
  vertical-align: bottom;
  white-space: nowrap;
}

TABLE.list TH A {
  color: #4444cc;
}

TABLE.list TD {
  border-bottom: solid thin #eeeeee;
  padding-top: 5pt;
  padding-left: 5pt;
}

TABLE.list TR:nth-child(even) {
  background: #f8f8f8;
}

TABLE.list TR:nth-child(odd) {
  background: #f4f4f4;
}

DT {
  margin-left: 36pt;
  margin-top: 12pt;
}

DD {
  margin-left: 54pt;
}

DL.category DT {
  font-weight: bold;
}

P.summary {
  margin-left: 36pt;
  font-family: monaco, courier, monospace;
}

DIV.summary TABLE {
  border: solid thin #999999;
  border-collapse: collapse;
  border-spacing: 0;
  margin: 10px;
}

DIV.summary TABLE TD, DIV.summary TABLE TH {
  border: solid thin #999999;
  padding: 5px;
  text-align: left;
  vertical-align: top;
}

DIV.summary TABLE THEAD TH {
  background: #eeeeee;
}

/* API documentation styles... */
div.body h1 {
  margin: 0;
}
div.body h2 {
  margin-top: 1.5em;
}
div.body h3, div.body h4, div.body h5 {
  margin-bottom: 0.5em;
  margin-top: 1.5em;
}
.class, .enumeration, .function, .struct, .typedef, .union {
  border-bottom: solid thin #999999;
  margin-bottom: 0;
  margin-top: 2em;
}
.description {
  margin-top: 0.5em;
}
code, p.code, pre, ul.code li {
  font-family: monaco, courier, monospace;
  font-size: 90%;
}
ul.code, ul.contents, ul.subcontents {
  list-style-type: none;
  margin: 0;
  padding-left: 0;
}
ul.code li {
  margin: 0;
}
ul.contents > li {
  margin-top: 1em;
}
ul.contents li ul.code, ul.contents li ul.subcontents {
  padding-left: 2em;
}
div.body dl {
  margin-left: 0;
  margin-top: 0;
}
div.body dt {
  font-style: italic;
  margin-left: 0;
  margin-top: 0;
}
div.body dd {
  margin-bottom: 0.5em;
}

/* This is just for the HTML files generated with the framedhelp target */
div.contents {
  background: #e8e8e8;
  border: solid thin black;
  padding: 10px;
}
div.contents h1 {
  font-size: 110%;
}
div.contents h2 {
  font-size: 100%;
}
div.contents ul.contents {
  font-size: 80%;
}
div.contents ul.subcontents li {
  margin-left: 1em;
  text-indent: -1em;
}
--></style>
</head>
<body>
<div class='body'>
<!--
  Introduction to CUPS programming header for CUPS.

  Copyright 2008-2016 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h1 class='title'>Introduction to CUPS Programming</h1>

<div class='summary'><table summary='General Information'>
<thead>
<tr>
	<th>Headers</th>
	<th>cups/cups.h<br>
	cups/adminutil.h<br>
	cups/array.h<br>
	cups/dir.h<br>
	cups/file.h<br>
	cups/http.h<br>
	cups/ipp.h<br>
	cups/language.h<br>
	cups/ppd.h<br>
	cups/pwg.h<br>
	cups/raster.h</th>
</tr>
</thead>
<tbody>
<tr>
	<th>Libraries</th>
	<td>-lcups</td>
</tr>
<tr>
	<th>See Also</th>
	<td>Programming: <a href='raster-driver.html' target='_top'>Developing Raster Printer Drivers</a><br>
	Programming: <a href='postscript-driver.html' target='_top'>Developing PostScript Printer Drivers</a><br>
	Programming: <a href='api-filter.html' target='_top'>Filter and Backend Programming</a><br>
	Programming: <a href='ppd-compiler.html' target='_top'>Introduction to the PPD Compiler</a><br>
	Programming: <a href='api-admin.html' target='_top'>Administrative APIs</a><br>
	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
	Programming: <a href='api-ppd.html' target='_top'>PPD API (DEPRECATED)</a><br>
	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
</tr>
</tbody>
</table></div>
<h2 class="title">Contents</h2>
<ul class="contents">
<li><a href="#OVERVIEW">Overview</a></li>
<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
	<li><a href="#XCODE">Compiling with Xcode</a></li>
	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
</ul></li>
<li><a href="#WHERETOGO">Where to Go Next</a></li>
</ul>
<!--
  Introduction to CUPS programming content for CUPS.

  Copyright 2008-2011 by Apple Inc.

  These coded instructions, statements, and computer programs are the
  property of Apple Inc. and are protected by Federal copyright
  law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  which should have been included with this file.  If this file is
  file is missing or damaged, see the license at "http://www.cups.org/".
-->

<h2 class="title"><a name="OVERVIEW">Overview</a></h2>

<p>CUPS provides two libraries that interface with the different parts of the
printing system. The "cups" library provides all of the common application and
filter functions while the "cupsimage" library provides all of the imaging
functions used in raster printer drivers. The "cups" library functions are
accessed by including the <var>&lt;cups/cups.h&gt;</var> header, while
"cupsimage" functions are found in the <var>&lt;cups/raster.h&gt;</var>
header.</p>

<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>

<p>The CUPS libraries can be used from any C, C++, or Objective C program.
The method of compiling against the libraries varies depending on the
operating system and installation of CUPS. The following sections show how
to compile a simple program (shown below) in two common environments.</p>

<p>The following simple program lists the available printers on the system:</p>

<pre class="example">
#include &lt;stdio.h&gt;
#include &lt;cups/cups.h&gt;

int main(void)
{
  int i;
  cups_dest_t *dests, *dest;
  int num_dests = cupsGetDests(&amp;dests);

  for (i = num_dests, dest = dests; i &gt; 0; i --, dest ++)
  {
    if (dest->instance)
      printf("%s/%s\n", dest->name, dest->instance);
    else
      puts(dest->name);
  }

  return (0);
}
</pre>

<h3><a name="XCODE">Compiling with Xcode</a></h3>

<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
then select the <var>Standard Tool</var> project type under <var>Command Line
Utility</var>. Click <var>Next</var> and choose a project directory. Click
<var>Next</var> to create the project.</p>

<p>In the project window, double-click on the <var>Targets</var> group and
control-click on the simple target to show the context menu. Choose
<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
down the file list and select the <var>libcups.dylib</var> file. Click the
<var>Add</var> button in the file chooser and attributes sheets.</p>

<p>In the project window, double-click on the <var>main.c</var> source file.
Replace the template source code with the listing above and save it. Click the
<var>Build and Go</var> button to build the sample program and run it.</p>

<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>

<p>From the command-line, create a file called <var>sample.c</var> using your
favorite editor and then run the following command to compile it with GCC and
run it:</p>

<pre class="command">
gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
./simple
</pre>

<p>The <code>cups-config</code> command provides the compiler flags
("cups-config --cflags") and libraries ("cups-config --libs") needed for the
local system.</p>

<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>

<p>If you are developing a print filter, driver, or backend, see the
<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
guide. Raster printer driver developers should also read the
<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
</div>
</body>
</html>
Commit	Line	Data
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">
8072030b	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	}
ca6b43fc	41
240214ef MS	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 {
ca6b43fc	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	<!--
321d8d57	356	Introduction to CUPS programming header for CUPS.
5a738aea	357
dffa3c74	358	Copyright 2008-2016 by Apple Inc.
5a738aea MS	359
	360	These coded instructions, statements, and computer programs are the
	361	property of Apple Inc. and are protected by Federal copyright
	362	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	363	which should have been included with this file. If this file is
	364	file is missing or damaged, see the license at "http://www.cups.org/".
	365	-->
	366
178cb736 MS	367	<h1 class='title'>Introduction to CUPS Programming</h1>
178cb736 MS	368
5a738aea MS	369	<div class='summary'><table summary='General Information'>
	370	<thead>
	371	<tr>
	372	<th>Headers</th>
	373	<th>cups/cups.h<br>
dffa3c74	374	cups/adminutil.h<br>
5a738aea	375	cups/array.h<br>
5a738aea MS	376	cups/dir.h<br>
5a738aea MS	377	cups/file.h<br>
dffa3c74 MS	378	cups/http.h<br>
	379	cups/ipp.h<br>
	380	cups/language.h<br>
5a738aea	381	cups/ppd.h<br>
dffa3c74 MS	382	cups/pwg.h<br>
dffa3c74 MS	383	cups/raster.h</th>
5a738aea MS	384	</tr>
	385	</thead>
	386	<tbody>
	387	<tr>
	388	<th>Libraries</th>
dffa3c74	389	<td>-lcups</td>
5a738aea MS	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>
dffa3c74	397	Programming: <a href='api-admin.html' target='_top'>Administrative APIs</a><br>
5a738aea	398	Programming: <a href='api-array.html' target='_top'>Array API</a><br>
e4572d57	399	Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
5a738aea	400	Programming: <a href='api-filedir.html' target='_top'>File and Directory APIs</a><br>
5a738aea	401	Programming: <a href='api-httpipp.html' target='_top'>HTTP and IPP APIs</a><br>
dffa3c74	402	Programming: <a href='api-ppd.html' target='_top'>PPD API (DEPRECATED)</a><br>
e4572d57 MS	403	Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
	404	References: <a href='ref-ppdcfile.html' target='_top'>PPD Compiler Driver Information File Reference</a><br>
	405	Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
5a738aea MS	406	</tr>
	407	</tbody>
	408	</table></div>
	409	<h2 class="title">Contents</h2>
	410	<ul class="contents">
5a738aea MS	411	<li><a href="#OVERVIEW">Overview</a></li>
5a738aea MS	412	<li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents">
0268488e MS	413	<li><a href="#XCODE">Compiling with Xcode</a></li>
0268488e MS	414	<li><a href="#COMMANDLINE">Compiling with GCC</a></li>
8b450588	415	</ul></li>
5a738aea	416	<li><a href="#WHERETOGO">Where to Go Next</a></li>
0268488e	417	</ul>
5a738aea	418	<!--
eac3a0a0	419	Introduction to CUPS programming content for CUPS.
5a738aea	420
eac3a0a0	421	Copyright 2008-2011 by Apple Inc.
5a738aea MS	422
	423	These coded instructions, statements, and computer programs are the
	424	property of Apple Inc. and are protected by Federal copyright
	425	law. Distribution and use rights are outlined in the file "LICENSE.txt"
	426	which should have been included with this file. If this file is
	427	file is missing or damaged, see the license at "http://www.cups.org/".
	428	-->
	429
	430	<h2 class="title"><a name="OVERVIEW">Overview</a></h2>
	431
	432	<p>CUPS provides two libraries that interface with the different parts of the
	433	printing system. The "cups" library provides all of the common application and
	434	filter functions while the "cupsimage" library provides all of the imaging
	435	functions used in raster printer drivers. The "cups" library functions are
	436	accessed by including the <var><cups/cups.h></var> header, while
	437	"cupsimage" functions are found in the <var><cups/raster.h></var>
	438	header.</p>
	439
	440	<h2 class="title"><a name="COMPILING">Compiling Programs</a></h2>
	441
	442	<p>The CUPS libraries can be used from any C, C++, or Objective C program.
	443	The method of compiling against the libraries varies depending on the
	444	operating system and installation of CUPS. The following sections show how
	445	to compile a simple program (shown below) in two common environments.</p>
	446
	447	<p>The following simple program lists the available printers on the system:</p>
	448
	449	<pre class="example">
	450	#include <stdio.h>
	451	#include <cups/cups.h>
	452
	453	int main(void)
	454	{
	455	int i;
	456	cups_dest_t dests, dest;
	457	int num_dests = cupsGetDests(&dests);
	458
	459	for (i = num_dests, dest = dests; i > 0; i --, dest ++)
	460	{
	461	if (dest->instance)
	462	printf("%s/%s\n", dest->name, dest->instance);
	463	else
	464	puts(dest->name);
	465	}
	466
	467	return (0);
	468	}
	469	</pre>
	470
	471	<h3><a name="XCODE">Compiling with Xcode</a></h3>
	472
	473	<p>In Xcode, choose <var>New Project...</var> from the <var>File</var> menu,
	474	then select the <var>Standard Tool</var> project type under <var>Command Line
	475	Utility</var>. Click <var>Next</var> and choose a project directory. Click
	476	<var>Next</var> to create the project.</p>
	477
	478	<p>In the project window, double-click on the <var>Targets</var> group and
	479	control-click on the simple target to show the context menu. Choose
	480	<var>Existing Framework...</var> from the <var>Add</var> submenu. When the file
	481	chooser sheet appears, press the <kbd>/</kbd> key and enter "/usr/lib". Scroll
	482	down the file list and select the <var>libcups.dylib</var> file. Click the
	483	<var>Add</var> button in the file chooser and attributes sheets.</p>
	484
	485	<p>In the project window, double-click on the <var>main.c</var> source file.
486	Replace the template source code with the listing above and save it. Click the
487	<var>Build and Go</var> button to build the sample program and run it.</p>
488
489	<h3><a name="COMMANDLINE">Compiling with GCC</a></h3>
490
491	<p>From the command-line, create a file called <var>sample.c</var> using your
492	favorite editor and then run the following command to compile it with GCC and
493	run it:</p>
494
495	<pre class="command">
496	gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
497	./simple
498	</pre>
499
500	<p>The <code>cups-config</code> command provides the compiler flags
501	("cups-config --cflags") and libraries ("cups-config --libs") needed for the
502	local system.</p>
503
504	<h2 class="title"><a name="WHERETOGO">Where to Go Next</a></h2>
505
506	<p>If you are developing a print filter, driver, or backend, see the
507	<a href="api-filter.html" target="_top">Filter and Backend Programming</a>
508	guide. Raster printer driver developers should also read the
509	<a href="api-raster.html" target="_top">Raster API</a> reference.</p>
510	</div>
511	</body>
512	</html>