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