Home | History | Annotate | Download | only in cups
      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>
    316