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

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