[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 {
  text-decoration: none;
  font-weight: bold;
}

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

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