cups/api-httpipp.shtml

   1 <!--
   2   "$Id: api-httpipp.shtml 7684 2008-06-23 16:47:38Z mike $"
   3
   4   HTTP and IPP API introduction for the Common UNIX Printing System (CUPS).
   5
   6   Copyright 2007-2008 by Apple Inc.
   7   Copyright 1997-2006 by Easy Software Products, all rights reserved.
   8
   9   These coded instructions, statements, and computer programs are the
  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/".
  14 -->
  15
  16 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
  17
  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>
  22
  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>
  31
  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>
  39
  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>
  49
  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 &lt;cups/cups.h&gt;
  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);
 104 </pre>
 105
 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 &amp;&amp; job_name != NULL &amp;&amp; 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") &amp;&amp; attr->value_tag == IPP_TAG_INTEGER)
 139       job_id = attr->values[0].integer;
 140     else if (!strcmp(attr->name, "job-name") &amp;&amp; attr->value_tag == IPP_TAG_NAME)
 141       job_name = attr->values[0].string.text;
 142     else if (!strcmp(attr->name, "job-originating-user-name") &amp;&amp;
 143              attr->value_tag == IPP_TAG_NAME)
 144       job_originating_user_name = attr->values[0].string.text;
 145   }
 146
 147   if (job_id > 0 &amp;&amp; job_name != NULL &amp;&amp; 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");
 193
 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 &amp;&amp; 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>