cups/api-httpipp.shtml

   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 &lt;cups/cups.h&gt;
  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") &amp;&amp; ippGetValueTag(attr) == IPP_TAG_INTEGER)
 123       job_id = ippGetInteger(attr, 0);
 124     else if (!strcmp(attrname, "job-name") &amp;&amp; ippGetValueTag(attr) == IPP_TAG_NAME)
 125       job_name = ippGetString(attr, 0, NULL);
 126     else if (!strcmp(attrname, "job-originating-user-name") &amp;&amp;
 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 &amp;&amp; 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>