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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
<title>Introduction to CUPS Programming</title>
<meta name="keywords" content="Programming">
<meta name="creator" content="Mini-XML v2.5">
<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;
}

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

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 {
  padding-top: 5pt;
  text-align: right;
  vertical-align: top;
}

HR {
  border: solid thin;
}

SPAN.info {
  background: #000000;
  border: thin solid #000000;
  color: #ffffff;
  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;
}

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;
}

SPAN.message {
  font-style: italic;
  font-size: smaller;
}

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

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