]>
Commit | Line | Data |
---|---|---|
ef416fc2 | 1 | <!-- |
bc44d920 | 2 | "$Id: api-httpipp.shtml 6649 2007-07-11 21:46:42Z mike $" |
ef416fc2 | 3 | |
4 | HTTP and IPP API introduction for the Common UNIX Printing System (CUPS). | |
5 | ||
5a738aea | 6 | Copyright 2007-2008 by Apple Inc. |
bc44d920 | 7 | Copyright 1997-2006 by Easy Software Products, all rights reserved. |
ef416fc2 | 8 | |
9 | These coded instructions, statements, and computer programs are the | |
bc44d920 | 10 | property of Apple Inc. and are protected by Federal copyright |
11 | law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
12 | which should have been included with this file. If this file is | |
13 | file is missing or damaged, see the license at "http://www.cups.org/". | |
ef416fc2 | 14 | --> |
15 | ||
5a738aea | 16 | <h2 class='title'><a name='OVERVIEW'>Overview</a></h2> |
ef416fc2 | 17 | |
5a738aea MS |
18 | <p>The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP |
19 | protocols and CUPS scheduler. They are typically used by monitoring and | |
20 | administration programs to perform specific functions not supported by the | |
21 | high-level CUPS API functions.</p> | |
ef416fc2 | 22 | |
5a738aea MS |
23 | <p>The HTTP APIs use an opaque structure called |
24 | <a href='#http_t'><code>http_t</code></a> to manage connections to | |
25 | a particular HTTP or IPP server. The | |
26 | <a href='#httpConnectEncrypt'><code>httpConnectEncrypt</code></a> function is | |
27 | used to create an instance of this structure for a particular server. | |
28 | The constant <code>CUPS_HTTP_DEFAULT</code> can be used with all of the | |
29 | <code>cups</code> functions to refer to the default CUPS server - the functions | |
30 | create a per-thread <a href='#http_t'><code>http_t</code></a> as needed.</p> | |
ef416fc2 | 31 | |
5a738aea MS |
32 | <p>The IPP APIs use two structures for requests (messages sent to the CUPS |
33 | scheduler) and responses (messages sent back to your application from the | |
34 | scheduler). The <a href='#ipp_t'><code>ipp_t</code></a> structure holds a | |
35 | complete request or response and is allocated using the | |
36 | <a href='#ippNew'><code>ippNew</code></a> or | |
37 | <a href='#ippNewRequest'><code>ippNewRequest</code></a> functions and | |
38 | freed using the <a href='#ippDelete'><code>ippDelete</code></a> function.</p> | |
ef416fc2 | 39 | |
5a738aea MS |
40 | <p>The second structure is called |
41 | <a href='#ipp_attribute_t'><code>ipp_attribute_t</code></a> and holds a | |
42 | single IPP attribute which consists of a group tag (<code>group_tag</code>), a | |
43 | value type tag (<code>value_tag</code>), the attribute name (<code>name</code>), | |
44 | and 1 or more values (<code>values[]</code>). Attributes are added to an | |
45 | <a href='#ipp_t'><code>ipp_t</code></a> structure using one of the | |
46 | <code>ippAdd</code> functions. For example, use | |
47 | <a href='#ippAddString'><code>ippAddString</code></a> to add a | |
48 | "requesting-user-name" string attribute to a request:</p> | |
ef416fc2 | 49 | |
5a738aea MS |
50 | <pre class='example'> |
51 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); | |
52 | ||
53 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", | |
54 | NULL, cupsUser()); | |
55 | </pre> | |
56 | ||
57 | <p>Once you have created an IPP request, use the <code>cups</code> | |
58 | functions to send the request to and read the response from the server. | |
59 | For example, the <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> | |
60 | function can be used for simple query operations that do not involve files:</p> | |
61 | ||
62 | <pre class='example'> | |
63 | #include <cups/cups.h> | |
64 | ||
65 | ||
66 | <a href='#ipp_t'>ipp_t</a> *<a name='get_jobs'>get_jobs</a>(void) | |
67 | { | |
68 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); | |
69 | ||
70 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", | |
71 | NULL, cupsUser()); | |
72 | ||
73 | return (<a href='#cupsDoRequest'>cupsDoRequest</a>(CUPS_HTTP_DEFAULT, request, "/")); | |
74 | } | |
75 | </pre> | |
76 | ||
77 | <p>The <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function frees | |
78 | the request structure and returns an IPP response structure or NULL pointer if | |
79 | the request could not be sent to the server. Once you have a response from | |
80 | the server, you can either use the | |
81 | <a href='#ippFindAttribute'><code>ippFindAttribute</code></a> and | |
82 | <a href='#ippFindNextAttribute'><code>ippFindNextAttribute</code></a> functions | |
83 | to find specific attributes, for example:</p> | |
84 | ||
85 | <pre class='example'> | |
86 | <a href='#ipp_t'>ipp_t</a> *response; | |
87 | <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; | |
88 | ||
89 | attr = <a href='#ippFindAttribute'>ippFindAttribute</a>(response, "printer-state", IPP_TAG_ENUM); | |
90 | </pre> | |
91 | ||
92 | <p>You can also walk the list of attributes with a simple <code>for</code> loop | |
93 | like this:</p> | |
94 | ||
95 | <pre class='example'> | |
96 | <a href='#ipp_t'>ipp_t</a> *response; | |
97 | <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; | |
98 | ||
99 | for (attr = response->attrs; attr != NULL; attr = attr->next) | |
100 | if (attr->name == NULL) | |
101 | puts("--SEPARATOR--"); | |
102 | else | |
103 | puts(attr->name); | |
ef416fc2 | 104 | </pre> |
105 | ||
5a738aea MS |
106 | <p>The <code>for</code> loop approach is normally used when collecting |
107 | attributes for multiple objects (jobs, printers, etc.) in a response. Attributes | |
108 | with <code>NULL</code> names indicate a separator between the attributes of | |
109 | each object. For example, the following code will list the jobs returned from | |
110 | our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> | |
111 | ||
112 | <pre class='example'> | |
113 | <a href='#ipp_t'>ipp_t</a> *response = <a href='#get_jobs'>get_jobs</a>(); | |
114 | ||
115 | if (response != NULL) | |
116 | { | |
117 | <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; | |
118 | int job_id = 0; | |
119 | char *job_name = NULL; | |
120 | char *job_originating_user_name = NULL; | |
121 | ||
122 | puts("Job ID Owner Title"); | |
123 | puts("------ ---------------- ---------------------------------"); | |
124 | ||
125 | for (attr = response->attrs; attr != NULL; attr = attr->next) | |
126 | { | |
127 | /* Attributes without names are separators between jobs */ | |
128 | if (attr->name == NULL) | |
129 | { | |
130 | if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) | |
131 | printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); | |
132 | ||
133 | job_id = 0; | |
134 | job_name = NULL; | |
135 | job_originating_user_name = NULL; | |
136 | continue; | |
137 | } | |
138 | else if (!strcmp(attr->name, "job-id") && attr->value_tag == IPP_TAG_INTEGER) | |
139 | job_id = attr->values[0].integer; | |
140 | else if (!strcmp(attr->name, "job-name") && attr->value_tag == IPP_TAG_NAME) | |
141 | job_name = attr->values[0].string.text; | |
142 | else if (!strcmp(attr->name, "job-originating-user-name") && | |
143 | attr->value_tag == IPP_TAG_NAME) | |
144 | job_originating_user_name = attr->values[0].string.text; | |
145 | } | |
146 | ||
147 | if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) | |
148 | printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); | |
149 | } | |
150 | </pre> | |
151 | ||
152 | <h3><a name='CREATING_URI_STRINGS'>Creating URI Strings</a></h3> | |
153 | ||
154 | <p>To ensure proper encoding, the | |
155 | <a href='#httpAssembleURIf'><code>httpAssembleURIf</code></a> function must be | |
156 | used to format a "printer-uri" string for all printer-based requests:</p> | |
157 | ||
158 | <pre class='example'> | |
159 | const char *name = "Foo"; | |
160 | char uri[1024]; | |
161 | <a href='#ipp_t'>ipp_t</a> *request; | |
162 | ||
163 | <a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), | |
164 | ippPort(), "/printers/%s", name); | |
165 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); | |
166 | </pre> | |
167 | ||
168 | <h3><a name='SENDING_REQUESTS_WITH_FILES'>Sending Requests with Files</a></h3> | |
169 | ||
170 | <p>The <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> and | |
171 | <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> functions are | |
172 | used for requests involving files. The | |
173 | <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> function | |
174 | attaches the named file to a request and is typically used when sending a print | |
175 | file or changing a printer's PPD file:</p> | |
176 | ||
177 | <pre class='example'> | |
178 | const char *filename = "/usr/share/cups/data/testprint.ps"; | |
179 | const char *name = "Foo"; | |
180 | char uri[1024]; | |
181 | char resource[1024]; | |
182 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_PRINT_JOB); | |
183 | <a href='#ipp_t'>ipp_t</a> *response; | |
184 | ||
185 | /* Use httpAssembleURIf for the printer-uri string */ | |
186 | <a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), | |
187 | ippPort(), "/printers/%s", name); | |
188 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); | |
189 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", | |
190 | NULL, cupsUser()); | |
191 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", | |
192 | NULL, "testprint.ps"); | |
ef416fc2 | 193 | |
5a738aea MS |
194 | /* Use snprintf for the resource path */ |
195 | snprintf(resource, sizeof(resource), "/printers/%s", name); | |
196 | ||
197 | response = <a href='#cupsDoFileRequest'>cupsDoFileRequest</a>(CUPS_HTTP_DEFAULT, request, resource, filename); | |
198 | </pre> | |
199 | ||
200 | <p>The <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> function | |
201 | optionally attaches a file to the request and optionally saves a file in the | |
202 | response from the server. It is used when using a pipe for the request | |
203 | attachment or when using a request that returns a file, currently only | |
204 | <code>CUPS_GET_DOCUMENT</code> and <code>CUPS_GET_PPD</code>. For example, | |
205 | the following code will download the PPD file for the sample HP LaserJet | |
206 | printer driver:</p> | |
207 | ||
208 | <pre class='example'> | |
209 | char tempfile[1024]; | |
210 | int tempfd; | |
211 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); | |
212 | <a href='#ipp_t'>ipp_t</a> *response; | |
213 | ||
214 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", | |
215 | NULL, "laserjet.ppd"); | |
216 | ||
217 | tempfd = cupsTempFd(tempfile, sizeof(tempfile)); | |
218 | ||
219 | response = <a href='#cupsDoIORequest'>cupsDoIORequest</a>(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd); | |
220 | </pre> | |
221 | ||
222 | <p>The example passes <code>-1</code> for the input file descriptor to specify | |
223 | that no file is to be attached to the request. The PPD file attached to the | |
224 | response is written to the temporary file descriptor we created using the | |
225 | <code>cupsTempFd</code> function.</p> | |
226 | ||
227 | <h3><a name='ASYNCHRONOUS_REQUEST_PROCESSING'>Asynchronous Request Processing</a></h3> | |
228 | ||
229 | <p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> and | |
230 | <a href='#cupsGetResponse'><code>cupsGetResponse</code></a> support | |
231 | asynchronous communications with the server. Unlike the other request | |
232 | functions, the IPP request is not automatically freed, so remember to | |
233 | free your request with the <a href='#ippDelete'><code>ippDelete</code></a> | |
234 | function.</p> | |
235 | ||
236 | <p>File data is attached to the request using the | |
237 | <a href='#cupsWriteRequestData'><code>cupsWriteRequestData</code></a> | |
238 | function, while file data returned from the server is read using the | |
239 | <a href='#cupsReadResponseData'><code>cupsReadResponseData</code></a> | |
240 | function. We can rewrite the previous <code>CUPS_GET_PPD</code> example | |
241 | to use the asynchronous functions quite easily:</p> | |
242 | ||
243 | <pre class='example'> | |
244 | char tempfile[1024]; | |
245 | int tempfd; | |
246 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); | |
247 | <a href='#ipp_t'>ipp_t</a> *response; | |
248 | ||
249 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", | |
250 | NULL, "laserjet.ppd"); | |
251 | ||
252 | tempfd = cupsTempFd(tempfile, sizeof(tempfile)); | |
253 | ||
254 | if (<a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE) | |
255 | { | |
256 | response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); | |
257 | ||
258 | if (response != NULL) | |
259 | { | |
260 | ssize_t bytes; | |
261 | char buffer[8192]; | |
262 | ||
263 | while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) | |
264 | write(tempfd, buffer, bytes); | |
265 | } | |
266 | } | |
267 | ||
268 | /* Free the request! */ | |
269 | <a href='#ippDelete'>ippDelete</a>(request); | |
270 | </pre> | |
271 | ||
272 | <p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> function | |
273 | returns the initial HTTP request status, typically either | |
274 | <code>HTTP_CONTINUE</code> or <code>HTTP_UNAUTHORIZED</code>. The latter status | |
275 | is returned when the request requires authentication of some sort. The | |
276 | <a href='#cupsDoAuthentication'><code>cupsDoAuthentication</code></a> function | |
277 | must be called when your see <code>HTTP_UNAUTHORIZED</code> and the request | |
278 | re-sent. We can add authentication support to our example code by using a | |
279 | <code>do ... while</code> loop:</p> | |
280 | ||
281 | <pre class='example'> | |
282 | char tempfile[1024]; | |
283 | int tempfd; | |
284 | <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD); | |
285 | <a href='#ipp_t'>ipp_t</a> *response; | |
286 | http_status_t status; | |
287 | ||
288 | <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", | |
289 | NULL, "laserjet.ppd"); | |
290 | ||
291 | tempfd = cupsTempFd(tempfile, sizeof(tempfile)); | |
292 | ||
293 | /* Loop for authentication */ | |
294 | do | |
295 | { | |
296 | status = a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/"); | |
297 | ||
298 | if (status == HTTP_UNAUTHORIZED) | |
299 | { | |
300 | /* Try to authenticate, break out of the loop if that fails */ | |
301 | if (<a href='#cupsDoAuthentication'>cupsDoAuthentication</a>(CUPS_HTTP_DEFAULT, "POST", "/")) | |
302 | break; | |
303 | } | |
304 | } | |
305 | while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED); | |
306 | ||
307 | if (status == HTTP_CONTINUE) | |
308 | { | |
309 | response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/"); | |
310 | ||
311 | if (response != NULL) | |
312 | { | |
313 | ssize_t bytes; | |
314 | char buffer[8192]; | |
315 | ||
316 | while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) | |
317 | write(tempfd, buffer, bytes); | |
318 | } | |
319 | } | |
320 | ||
321 | /* Free the request! */ | |
322 | <a href='#ippDelete'>ippDelete</a>(request); | |
323 | </pre> |