doc/help/api-httpipp.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5         <title>HTTP and IPP APIs        </title>
   6         <meta name="keywords" content="Programming">
   7         <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
   8         <meta name="creator" content="Mini-XML v2.7">
   9 <style type="text/css"><!--
  10 BODY {
  11   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  12 }
  13
  14 H1, H2, H3, H4, H5, H6, P, TD, TH {
  15   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  16 }
  17
  18 KBD {
  19   font-family: monaco, courier, monospace;
  20   font-weight: bold;
  21 }
  22
  23 PRE {
  24   font-family: monaco, courier, monospace;
  25 }
  26
  27 PRE.command {
  28   border: dotted thin #7f7f7f;
  29   margin-left: 36pt;
  30   padding: 10px;
  31 }
  32
  33 P.compact {
  34   margin: 0;
  35 }
  36
  37 P.example {
  38   font-style: italic;
  39   margin-left: 36pt;
  40 }
  41
  42 PRE.example {
  43   background: #eeeeee;
  44   border: dotted thin #999999;
  45   margin-left: 36pt;
  46   padding: 10pt;
  47 }
  48
  49 PRE.command EM, PRE.example EM {
  50   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  51 }
  52
  53 P.command {
  54   font-family: monaco, courier, monospace;
  55   margin-left: 36pt;
  56 }
  57
  58 P.formula {
  59   font-style: italic;
  60   margin-left: 36pt;
  61 }
  62
  63 BLOCKQUOTE {
  64   background: #eeeeee;
  65   border: solid thin #999999;
  66   padding: 10pt;
  67 }
  68
  69 A IMG {
  70   border: none;
  71 }
  72
  73 A:link:hover IMG {
  74   background: #f0f0f0;
  75   border-radius: 10px;
  76   -moz-border-radius: 10px;
  77 }
  78
  79 A:link, A:visited {
  80   font-weight: normal;
  81   text-decoration: none;
  82 }
  83
  84 A:link:hover, A:visited:hover, A:active {
  85   text-decoration: underline;
  86 }
  87
  88 SUB, SUP {
  89   font-size: 50%;
  90 }
  91
  92 TR.data, TD.data, TR.data TD {
  93   margin-top: 10pt;
  94   padding: 5pt;
  95   border-bottom: solid 1pt #999999;
  96 }
  97
  98 TR.data TH {
  99   border-bottom: solid 1pt #999999;
 100   padding-top: 10pt;
 101   padding-left: 5pt;
 102   text-align: left;
 103 }
 104
 105 DIV.table TABLE {
 106   border: solid thin #999999;
 107   border-collapse: collapse;
 108   border-spacing: 0;
 109   margin-left: auto;
 110   margin-right: auto;
 111 }
 112
 113 DIV.table CAPTION {
 114   caption-side: top;
 115   font-size: 120%;
 116   font-style: italic;
 117   font-weight: bold;
 118   margin-left: auto;
 119   margin-right: auto;
 120 }
 121
 122 DIV.table TABLE TD {
 123   border: solid thin #cccccc;
 124   padding-top: 5pt;
 125 }
 126
 127 DIV.table TABLE TH {
 128   background: #cccccc;
 129   border: none;
 130   border-bottom: solid thin #999999;
 131 }
 132
 133 DIV.figure TABLE {
 134   margin-left: auto;
 135   margin-right: auto;
 136 }
 137
 138 DIV.figure CAPTION {
 139   caption-side: bottom;
 140   font-size: 120%;
 141   font-style: italic;
 142   font-weight: bold;
 143   margin-left: auto;
 144   margin-right: auto;
 145 }
 146
 147 TH.label {
 148   text-align: right;
 149   vertical-align: top;
 150 }
 151
 152 TH.sublabel {
 153   text-align: right;
 154   font-weight: normal;
 155 }
 156
 157 HR {
 158   border: solid thin;
 159 }
 160
 161 SPAN.info {
 162   background: black;
 163   border: thin solid black;
 164   color: white;
 165   font-size: 80%;
 166   font-style: italic;
 167   font-weight: bold;
 168   white-space: nowrap;
 169 }
 170
 171 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 172   float: right;
 173   font-size: 100%;
 174 }
 175
 176 H1.title {
 177 }
 178
 179 H2.title, H3.title {
 180   border-bottom: solid 2pt #000000;
 181 }
 182
 183 DIV.indent, TABLE.indent {
 184   margin-top: 2em;
 185   margin-left: auto;
 186   margin-right: auto;
 187   width: 90%;
 188 }
 189
 190 TABLE.indent {
 191   border-collapse: collapse;
 192 }
 193
 194 TABLE.indent TD, TABLE.indent TH {
 195   padding: 0;
 196 }
 197
 198 TABLE.list {
 199   border-collapse: collapse;
 200   margin-left: auto;
 201   margin-right: auto;
 202   width: 90%;
 203 }
 204
 205 TABLE.list TH {
 206   background: white;
 207   border-bottom: solid thin #cccccc;
 208   color: #444444;
 209   padding-top: 10pt;
 210   padding-left: 5pt;
 211   text-align: left;
 212   vertical-align: bottom;
 213   white-space: nowrap;
 214 }
 215
 216 TABLE.list TH A {
 217   color: #4444cc;
 218 }
 219
 220 TABLE.list TD {
 221   border-bottom: solid thin #eeeeee;
 222   padding-top: 5pt;
 223   padding-left: 5pt;
 224 }
 225
 226 TABLE.list TR:nth-child(even) {
 227   background: #f8f8f8;
 228 }
 229
 230 TABLE.list TR:nth-child(odd) {
 231   background: #f4f4f4;
 232 }
 233
 234 DT {
 235   margin-left: 36pt;
 236   margin-top: 12pt;
 237 }
 238
 239 DD {
 240   margin-left: 54pt;
 241 }
 242
 243 DL.category DT {
 244   font-weight: bold;
 245 }
 246
 247 P.summary {
 248   margin-left: 36pt;
 249   font-family: monaco, courier, monospace;
 250 }
 251
 252 DIV.summary TABLE {
 253   border: solid thin #999999;
 254   border-collapse: collapse;
 255   border-spacing: 0;
 256   margin: 10px;
 257 }
 258
 259 DIV.summary TABLE TD, DIV.summary TABLE TH {
 260   border: solid thin #999999;
 261   padding: 5px;
 262   text-align: left;
 263   vertical-align: top;
 264 }
 265
 266 DIV.summary TABLE THEAD TH {
 267   background: #eeeeee;
 268 }
 269
 270 /* API documentation styles... */
 271 div.body h1 {
 272   margin: 0;
 273 }
 274 div.body h2 {
 275   margin-top: 1.5em;
 276 }
 277 div.body h3, div.body h4, div.body h5 {
 278   margin-bottom: 0.5em;
 279   margin-top: 1.5em;
 280 }
 281 .class, .enumeration, .function, .struct, .typedef, .union {
 282   border-bottom: solid thin #999999;
 283   margin-bottom: 0;
 284   margin-top: 2em;
 285 }
 286 .description {
 287   margin-top: 0.5em;
 288 }
 289 code, p.code, pre, ul.code li {
 290   font-family: monaco, courier, monospace;
 291   font-size: 90%;
 292 }
 293 ul.code, ul.contents, ul.subcontents {
 294   list-style-type: none;
 295   margin: 0;
 296   padding-left: 0;
 297 }
 298 ul.code li {
 299   margin: 0;
 300 }
 301 ul.contents > li {
 302   margin-top: 1em;
 303 }
 304 ul.contents li ul.code, ul.contents li ul.subcontents {
 305   padding-left: 2em;
 306 }
 307 div.body dl {
 308   margin-left: 0;
 309   margin-top: 0;
 310 }
 311 div.body dt {
 312   font-style: italic;
 313   margin-left: 0;
 314   margin-top: 0;
 315 }
 316 div.body dd {
 317   margin-bottom: 0.5em;
 318 }
 319
 320 /* This is just for the HTML files generated with the framedhelp target */
 321 div.contents {
 322   background: #e8e8e8;
 323   border: solid thin black;
 324   padding: 10px;
 325 }
 326 div.contents h1 {
 327   font-size: 110%;
 328 }
 329 div.contents h2 {
 330   font-size: 100%;
 331 }
 332 div.contents ul.contents {
 333   font-size: 80%;
 334 }
 335 div.contents ul.subcontents li {
 336   margin-left: 1em;
 337   text-indent: -1em;
 338 }
 339 --></style>
 340 </head>
 341 <body>
 342 <div class='body'>
 343 <!--
 344   "$Id$"
 345
 346   HTTP and IPP API header for CUPS.
 347
 348   Copyright 2007-2011 by Apple Inc.
 349   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 350
 351   These coded instructions, statements, and computer programs are the
 352   property of Apple Inc. and are protected by Federal copyright
 353   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 354   which should have been included with this file.  If this file is
 355   file is missing or damaged, see the license at "http://www.cups.org/".
 356 -->
 357
 358 <h1 class='title'>HTTP and IPP APIs</h1>
 359
 360 <div class='summary'><table summary='General Information'>
 361 <thead>
 362 <tr>
 363         <th>Header</th>
 364         <th>cups/cups.h</th>
 365 </tr>
 366 </thead>
 367 <tbody>
 368 <tr>
 369         <th>Library</th>
 370         <td>-lcups</td>
 371 </tr>
 372 <tr>
 373         <th>See Also</th>
 374         <td>Programming: <a href='api-overview.html'>Introduction to CUPS Programming</a><br>
 375         Programming: <a href='api-cups.html'>CUPS API</a><br>
 376         References: <a href='spec-ipp.html'>CUPS Implementation of IPP</a></td>
 377 </tr>
 378 </tbody>
 379 </table></div>
 380 <h2 class="title">Contents</h2>
 381 <ul class="contents">
 382 <li><a href="#OVERVIEW">Overview</a><ul class="subcontents">
 383         <li><a href="#CREATING_URI_STRINGS">Creating URI Strings</a></li>
 384         <li><a href="#SENDING_REQUESTS_WITH_FILES">Sending Requests with Files</a></li>
 385         <li><a href="#ASYNCHRONOUS_REQUEST_PROCESSING">Asynchronous Request Processing</a></li>
 386 </ul></li>
 387 <li><a href="#FUNCTIONS">Functions</a><ul class="code">
 388         <li><a href="#cupsDoAuthentication" title="Authenticate a request.">cupsDoAuthentication</a></li>
 389         <li><a href="#cupsDoFileRequest" title="Do an IPP request with a file.">cupsDoFileRequest</a></li>
 390         <li><a href="#cupsDoIORequest" title="Do an IPP request with file descriptors.">cupsDoIORequest</a></li>
 391         <li><a href="#cupsDoRequest" title="Do an IPP request.">cupsDoRequest</a></li>
 392         <li><a href="#cupsEncodeOptions" title="Encode printer options into IPP attributes.">cupsEncodeOptions</a></li>
 393         <li><a href="#cupsEncodeOptions2" title="Encode printer options into IPP attributes for a group.">cupsEncodeOptions2</a></li>
 394         <li><a href="#cupsGetDevices" title="Get available printer devices.">cupsGetDevices</a></li>
 395         <li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li>
 396         <li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li>
 397         <li><a href="#cupsGetResponse" title="Get a response to an IPP request.">cupsGetResponse</a></li>
 398         <li><a href="#cupsLastError" title="Return the last IPP status code received on the current
 399 thread.">cupsLastError</a></li>
 400         <li><a href="#cupsLastErrorString" title="Return the last IPP status-message received on the
 401 current thread.">cupsLastErrorString</a></li>
 402         <li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li>
 403         <li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li>
 404         <li><a href="#cupsReadResponseData" title="Read additional data after the IPP response.">cupsReadResponseData</a></li>
 405         <li><a href="#cupsSendRequest" title="Send an IPP request.">cupsSendRequest</a></li>
 406         <li><a href="#cupsWriteRequestData" title="Write additional data after an IPP request.">cupsWriteRequestData</a></li>
 407         <li><a href="#httpAcceptConnection" title="Accept a new HTTP client connection from the
 408 specified listening socket.">httpAcceptConnection</a></li>
 409         <li><a href="#httpAddCredential" title="Allocates and adds a single credential to an array.">httpAddCredential</a></li>
 410         <li><a href="#httpAddrAny" title="Check for the &quot;any&quot; address.">httpAddrAny</a></li>
 411         <li><a href="#httpAddrEqual" title="Compare two addresses.">httpAddrEqual</a></li>
 412         <li><a href="#httpAddrLength" title="Return the length of the address in bytes.">httpAddrLength</a></li>
 413         <li><a href="#httpAddrListen" title="Create a listening socket bound to the specified
 414 address and port.">httpAddrListen</a></li>
 415         <li><a href="#httpAddrLocalhost" title="Check for the local loopback address.">httpAddrLocalhost</a></li>
 416         <li><a href="#httpAddrLookup" title="Lookup the hostname associated with the address.">httpAddrLookup</a></li>
 417         <li><a href="#httpAddrPort" title="Get the port number associated with an address.">httpAddrPort</a></li>
 418         <li><a href="#httpAddrString" title="Convert an address to a numeric string.">httpAddrString</a></li>
 419         <li><a href="#httpAssembleURI" title="Assemble a uniform resource identifier from its
 420 components.">httpAssembleURI</a></li>
 421         <li><a href="#httpAssembleURIf" title="Assemble a uniform resource identifier from its
 422 components with a formatted resource.">httpAssembleURIf</a></li>
 423         <li><a href="#httpAssembleUUID" title="Assemble a name-based UUID URN conforming to RFC 4122.">httpAssembleUUID</a></li>
 424         <li><a href="#httpBlocking" title="Set blocking/non-blocking behavior on a connection.">httpBlocking</a></li>
 425         <li><a href="#httpCheck" title="Check to see if there is a pending response from the server.">httpCheck</a></li>
 426         <li><a href="#httpClearCookie" title="Clear the cookie value(s).">httpClearCookie</a></li>
 427         <li><a href="#httpClearFields" title="Clear HTTP request fields.">httpClearFields</a></li>
 428         <li><a href="#httpClose" title="Close an HTTP connection.">httpClose</a></li>
 429         <li><a href="#httpConnect" title="Connect to a HTTP server.">httpConnect</a></li>
 430         <li><a href="#httpConnect2" title="Connect to a HTTP server.">httpConnect2</a></li>
 431         <li><a href="#httpConnectEncrypt" title="Connect to a HTTP server using encryption.">httpConnectEncrypt</a></li>
 432         <li><a href="#httpCopyCredentials" title="Copy the credentials associated with an encrypted
 433 connection.">httpCopyCredentials</a></li>
 434         <li><a href="#httpDecode64" title="Base64-decode a string.">httpDecode64</a></li>
 435         <li><a href="#httpDecode64_2" title="Base64-decode a string.">httpDecode64_2</a></li>
 436         <li><a href="#httpDelete" title="Send a DELETE request to the server.">httpDelete</a></li>
 437         <li><a href="#httpEncode64" title="Base64-encode a string.">httpEncode64</a></li>
 438         <li><a href="#httpEncode64_2" title="Base64-encode a string.">httpEncode64_2</a></li>
 439         <li><a href="#httpEncryption" title="Set the required encryption on the link.">httpEncryption</a></li>
 440         <li><a href="#httpError" title="Get the last error on a connection.">httpError</a></li>
 441         <li><a href="#httpFlush" title="Flush data from a HTTP connection.">httpFlush</a></li>
 442         <li><a href="#httpFlushWrite" title="Flush data in write buffer.">httpFlushWrite</a></li>
 443         <li><a href="#httpFreeCredentials" title="Free an array of credentials.">httpFreeCredentials</a></li>
 444         <li><a href="#httpGet" title="Send a GET request to the server.">httpGet</a></li>
 445         <li><a href="#httpGetAuthString" title="Get the current authorization string.">httpGetAuthString</a></li>
 446         <li><a href="#httpGetBlocking" title="Get the blocking/non-block state of a connection.">httpGetBlocking</a></li>
 447         <li><a href="#httpGetContentEncoding" title="Get a common content encoding, if any, between
 448 the client and server.">httpGetContentEncoding</a></li>
 449         <li><a href="#httpGetCookie" title="Get any cookie data from the response.">httpGetCookie</a></li>
 450         <li><a href="#httpGetDateString" title="Get a formatted date/time string from a time value.">httpGetDateString</a></li>
 451         <li><a href="#httpGetDateString2" title="Get a formatted date/time string from a time value.">httpGetDateString2</a></li>
 452         <li><a href="#httpGetDateTime" title="Get a time value from a formatted date/time string.">httpGetDateTime</a></li>
 453         <li><a href="#httpGetExpect" title="Get the value of the Expect header, if any.">httpGetExpect</a></li>
 454         <li><a href="#httpGetFd" title="Get the file descriptor associated with a connection.">httpGetFd</a></li>
 455         <li><a href="#httpGetField" title="Get a field value from a request/response.">httpGetField</a></li>
 456         <li><a href="#httpGetHostByName" title="Lookup a hostname or IPv4 address, and return
 457 address records for the specified name.">httpGetHostByName</a></li>
 458         <li><a href="#httpGetHostname" title="Get the FQDN for the connection or local system.">httpGetHostname</a></li>
 459         <li><a href="#httpGetLength" title="Get the amount of data remaining from the
 460 content-length or transfer-encoding fields.">httpGetLength</a></li>
 461         <li><a href="#httpGetLength2" title="Get the amount of data remaining from the
 462 content-length or transfer-encoding fields.">httpGetLength2</a></li>
 463         <li><a href="#httpGetState" title="Get the current state of the HTTP request.">httpGetState</a></li>
 464         <li><a href="#httpGetStatus" title="Get the status of the last HTTP request.">httpGetStatus</a></li>
 465         <li><a href="#httpGetSubField" title="Get a sub-field value.">httpGetSubField</a></li>
 466         <li><a href="#httpGetSubField2" title="Get a sub-field value.">httpGetSubField2</a></li>
 467         <li><a href="#httpGetVersion" title="Get the HTTP version at the other end.">httpGetVersion</a></li>
 468         <li><a href="#httpGets" title="Get a line of text from a HTTP connection.">httpGets</a></li>
 469         <li><a href="#httpHead" title="Send a HEAD request to the server.">httpHead</a></li>
 470         <li><a href="#httpInitialize" title="Initialize the HTTP interface library and set the
 471 default HTTP proxy (if any).">httpInitialize</a></li>
 472         <li><a href="#httpMD5" title="Compute the MD5 sum of the username:group:password.">httpMD5</a></li>
 473         <li><a href="#httpMD5Final" title="Combine the MD5 sum of the username, group, and password
 474 with the server-supplied nonce value, method, and
 475 request-uri.">httpMD5Final</a></li>
 476         <li><a href="#httpMD5String" title="Convert an MD5 sum to a character string.">httpMD5String</a></li>
 477         <li><a href="#httpOptions" title="Send an OPTIONS request to the server.">httpOptions</a></li>
 478         <li><a href="#httpPeek" title="Peek at data from a HTTP connection.">httpPeek</a></li>
 479         <li><a href="#httpPost" title="Send a POST request to the server.">httpPost</a></li>
 480         <li><a href="#httpPut" title="Send a PUT request to the server.">httpPut</a></li>
 481         <li><a href="#httpRead" title="Read data from a HTTP connection.">httpRead</a></li>
 482         <li><a href="#httpRead2" title="Read data from a HTTP connection.">httpRead2</a></li>
 483         <li><a href="#httpReadRequest" title="Read a HTTP request from a connection.">httpReadRequest</a></li>
 484         <li><a href="#httpReconnect" title="Reconnect to a HTTP server.">httpReconnect</a></li>
 485         <li><a href="#httpReconnect2" title="Reconnect to a HTTP server with timeout and optional
 486 cancel.">httpReconnect2</a></li>
 487         <li><a href="#httpSeparate" title="Separate a Universal Resource Identifier into its
 488 components.">httpSeparate</a></li>
 489         <li><a href="#httpSeparate2" title="Separate a Universal Resource Identifier into its
 490 components.">httpSeparate2</a></li>
 491         <li><a href="#httpSeparateURI" title="Separate a Universal Resource Identifier into its
 492 components.">httpSeparateURI</a></li>
 493         <li><a href="#httpSetAuthString" title="Set the current authorization string.">httpSetAuthString</a></li>
 494         <li><a href="#httpSetCookie" title="Set the cookie value(s).">httpSetCookie</a></li>
 495         <li><a href="#httpSetCredentials" title="Set the credentials associated with an encrypted
 496 connection.">httpSetCredentials</a></li>
 497         <li><a href="#httpSetDefaultField" title="Set the default value of an HTTP header.">httpSetDefaultField</a></li>
 498         <li><a href="#httpSetExpect" title="Set the Expect: header in a request.">httpSetExpect</a></li>
 499         <li><a href="#httpSetField" title="Set the value of an HTTP header.">httpSetField</a></li>
 500         <li><a href="#httpSetLength" title="Set the content-length and content-encoding.">httpSetLength</a></li>
 501         <li><a href="#httpSetTimeout" title="Set read/write timeouts and an optional callback.">httpSetTimeout</a></li>
 502         <li><a href="#httpStatus" title="Return a short string describing a HTTP status code.">httpStatus</a></li>
 503         <li><a href="#httpTrace" title="Send an TRACE request to the server.">httpTrace</a></li>
 504         <li><a href="#httpUpdate" title="Update the current HTTP state for incoming data.">httpUpdate</a></li>
 505         <li><a href="#httpWait" title="Wait for data available on a connection.">httpWait</a></li>
 506         <li><a href="#httpWrite" title="Write data to a HTTP connection.">httpWrite</a></li>
 507         <li><a href="#httpWrite2" title="Write data to a HTTP connection.">httpWrite2</a></li>
 508         <li><a href="#httpWriteResponse" title="Write a HTTP response to a client connection.">httpWriteResponse</a></li>
 509         <li><a href="#ippAddBoolean" title="Add a boolean attribute to an IPP message.">ippAddBoolean</a></li>
 510         <li><a href="#ippAddBooleans" title="Add an array of boolean values.">ippAddBooleans</a></li>
 511         <li><a href="#ippAddCollection" title="Add a collection value.">ippAddCollection</a></li>
 512         <li><a href="#ippAddCollections" title="Add an array of collection values.">ippAddCollections</a></li>
 513         <li><a href="#ippAddDate" title="Add a date attribute to an IPP message.">ippAddDate</a></li>
 514         <li><a href="#ippAddInteger" title="Add a integer attribute to an IPP message.">ippAddInteger</a></li>
 515         <li><a href="#ippAddIntegers" title="Add an array of integer values.">ippAddIntegers</a></li>
 516         <li><a href="#ippAddOctetString" title="Add an octetString value to an IPP message.">ippAddOctetString</a></li>
 517         <li><a href="#ippAddOutOfBand" title="Add an out-of-band value to an IPP message.">ippAddOutOfBand</a></li>
 518         <li><a href="#ippAddRange" title="Add a range of values to an IPP message.">ippAddRange</a></li>
 519         <li><a href="#ippAddRanges" title="Add ranges of values to an IPP message.">ippAddRanges</a></li>
 520         <li><a href="#ippAddResolution" title="Add a resolution value to an IPP message.">ippAddResolution</a></li>
 521         <li><a href="#ippAddResolutions" title="Add resolution values to an IPP message.">ippAddResolutions</a></li>
 522         <li><a href="#ippAddSeparator" title="Add a group separator to an IPP message.">ippAddSeparator</a></li>
 523         <li><a href="#ippAddString" title="Add a language-encoded string to an IPP message.">ippAddString</a></li>
 524         <li><a href="#ippAddStringf" title="Add a formatted string to an IPP message.">ippAddStringf</a></li>
 525         <li><a href="#ippAddStringfv" title="Add a formatted string to an IPP message.">ippAddStringfv</a></li>
 526         <li><a href="#ippAddStrings" title="Add language-encoded strings to an IPP message.">ippAddStrings</a></li>
 527         <li><a href="#ippAttributeString" title="Convert the attribute's value to a string.">ippAttributeString</a></li>
 528         <li><a href="#ippContainsInteger" title="Determine whether an attribute contains the
 529 specified value or is within the list of ranges.">ippContainsInteger</a></li>
 530         <li><a href="#ippContainsString" title="Determine whether an attribute contains the
 531 specified string value.">ippContainsString</a></li>
 532         <li><a href="#ippCopyAttribute" title="Copy an attribute.">ippCopyAttribute</a></li>
 533         <li><a href="#ippCopyAttributes" title="Copy attributes from one IPP message to another.">ippCopyAttributes</a></li>
 534         <li><a href="#ippCreateRequestedArray" title="Create a CUPS array of attribute names from the
 535 given requested-attributes attribute.">ippCreateRequestedArray</a></li>
 536         <li><a href="#ippDateToTime" title="Convert from RFC 1903 Date/Time format to UNIX time
 537 in seconds.">ippDateToTime</a></li>
 538         <li><a href="#ippDelete" title="Delete an IPP message.">ippDelete</a></li>
 539         <li><a href="#ippDeleteAttribute" title="Delete a single attribute in an IPP message.">ippDeleteAttribute</a></li>
 540         <li><a href="#ippDeleteValues" title="Delete values in an attribute.">ippDeleteValues</a></li>
 541         <li><a href="#ippEnumString" title="Return a string corresponding to the enum value.">ippEnumString</a></li>
 542         <li><a href="#ippEnumValue" title="Return the value associated with a given enum string.">ippEnumValue</a></li>
 543         <li><a href="#ippErrorString" title="Return a name for the given status code.">ippErrorString</a></li>
 544         <li><a href="#ippErrorValue" title="Return a status code for the given name.">ippErrorValue</a></li>
 545         <li><a href="#ippFindAttribute" title="Find a named attribute in a request.">ippFindAttribute</a></li>
 546         <li><a href="#ippFindNextAttribute" title="Find the next named attribute in a request.">ippFindNextAttribute</a></li>
 547         <li><a href="#ippFirstAttribute" title="Return the first attribute in the message.">ippFirstAttribute</a></li>
 548         <li><a href="#ippGetBoolean" title="Get a boolean value for an attribute.">ippGetBoolean</a></li>
 549         <li><a href="#ippGetCollection" title="Get a collection value for an attribute.">ippGetCollection</a></li>
 550         <li><a href="#ippGetCount" title="Get the number of values in an attribute.">ippGetCount</a></li>
 551         <li><a href="#ippGetDate" title="Get a date value for an attribute.">ippGetDate</a></li>
 552         <li><a href="#ippGetGroupTag" title="Get the group associated with an attribute.">ippGetGroupTag</a></li>
 553         <li><a href="#ippGetInteger" title="Get the integer/enum value for an attribute.">ippGetInteger</a></li>
 554         <li><a href="#ippGetName" title="Get the attribute name.">ippGetName</a></li>
 555         <li><a href="#ippGetOperation" title="Get the operation ID in an IPP message.">ippGetOperation</a></li>
 556         <li><a href="#ippGetRange" title="Get a rangeOfInteger value from an attribute.">ippGetRange</a></li>
 557         <li><a href="#ippGetRequestId" title="Get the request ID from an IPP message.">ippGetRequestId</a></li>
 558         <li><a href="#ippGetResolution" title="Get a resolution value for an attribute.">ippGetResolution</a></li>
 559         <li><a href="#ippGetState" title="Get the IPP message state.">ippGetState</a></li>
 560         <li><a href="#ippGetStatusCode" title="Get the status code from an IPP response or event message.">ippGetStatusCode</a></li>
 561         <li><a href="#ippGetString" title="Return the value...">ippGetString</a></li>
 562         <li><a href="#ippGetValueTag" title="Get the value tag for an attribute.">ippGetValueTag</a></li>
 563         <li><a href="#ippGetVersion" title="Get the major and minor version number from an IPP message.">ippGetVersion</a></li>
 564         <li><a href="#ippLength" title="Compute the length of an IPP message.">ippLength</a></li>
 565         <li><a href="#ippNew" title="Allocate a new IPP message.">ippNew</a></li>
 566         <li><a href="#ippNewRequest" title="Allocate a new IPP request message.">ippNewRequest</a></li>
 567         <li><a href="#ippNewResponse" title="Allocate a new IPP response message.">ippNewResponse</a></li>
 568         <li><a href="#ippNextAttribute" title="Return the next attribute in the message.">ippNextAttribute</a></li>
 569         <li><a href="#ippOpString" title="Return a name for the given operation id.">ippOpString</a></li>
 570         <li><a href="#ippOpValue" title="Return an operation id for the given name.">ippOpValue</a></li>
 571         <li><a href="#ippPort" title="Return the default IPP port number.">ippPort</a></li>
 572         <li><a href="#ippRead" title="Read data for an IPP message from a HTTP connection.">ippRead</a></li>
 573         <li><a href="#ippReadFile" title="Read data for an IPP message from a file.">ippReadFile</a></li>
 574         <li><a href="#ippReadIO" title="Read data for an IPP message.">ippReadIO</a></li>
 575         <li><a href="#ippSetBoolean" title="Set a boolean value in an attribute.">ippSetBoolean</a></li>
 576         <li><a href="#ippSetCollection" title="Set a collection value in an attribute.">ippSetCollection</a></li>
 577         <li><a href="#ippSetDate" title="Set a date value in an attribute.">ippSetDate</a></li>
 578         <li><a href="#ippSetGroupTag" title="Set the group tag of an attribute.">ippSetGroupTag</a></li>
 579         <li><a href="#ippSetInteger" title="Set an integer or enum value in an attribute.">ippSetInteger</a></li>
 580         <li><a href="#ippSetName" title="Set the name of an attribute.">ippSetName</a></li>
 581         <li><a href="#ippSetOperation" title="Set the operation ID in an IPP request message.">ippSetOperation</a></li>
 582         <li><a href="#ippSetPort" title="Set the default port number.">ippSetPort</a></li>
 583         <li><a href="#ippSetRange" title="Set a rangeOfInteger value in an attribute.">ippSetRange</a></li>
 584         <li><a href="#ippSetRequestId" title="Set the request ID in an IPP message.">ippSetRequestId</a></li>
 585         <li><a href="#ippSetResolution" title="Set a resolution value in an attribute.">ippSetResolution</a></li>
 586         <li><a href="#ippSetState" title="Set the current state of the IPP message.">ippSetState</a></li>
 587         <li><a href="#ippSetStatusCode" title="Set the status code in an IPP response or event message.">ippSetStatusCode</a></li>
 588         <li><a href="#ippSetString" title="Set a string value in an attribute.">ippSetString</a></li>
 589         <li><a href="#ippSetStringf" title="Set a formatted string value of an attribute.">ippSetStringf</a></li>
 590         <li><a href="#ippSetStringfv" title="Set a formatted string value of an attribute.">ippSetStringfv</a></li>
 591         <li><a href="#ippSetValueTag" title="Set the value tag of an attribute.">ippSetValueTag</a></li>
 592         <li><a href="#ippSetVersion" title="Set the version number in an IPP message.">ippSetVersion</a></li>
 593         <li><a href="#ippTagString" title="Return the tag name corresponding to a tag value.">ippTagString</a></li>
 594         <li><a href="#ippTagValue" title="Return the tag value corresponding to a tag name.">ippTagValue</a></li>
 595         <li><a href="#ippTimeToDate" title="Convert from UNIX time to RFC 1903 format.">ippTimeToDate</a></li>
 596         <li><a href="#ippValidateAttribute" title="Validate the contents of an attribute.">ippValidateAttribute</a></li>
 597         <li><a href="#ippValidateAttributes" title="Validate all attributes in an IPP message.">ippValidateAttributes</a></li>
 598         <li><a href="#ippWrite" title="Write data for an IPP message to a HTTP connection.">ippWrite</a></li>
 599         <li><a href="#ippWriteFile" title="Write data for an IPP message to a file.">ippWriteFile</a></li>
 600         <li><a href="#ippWriteIO" title="Write data for an IPP message.">ippWriteIO</a></li>
 601 </ul></li>
 602 <li><a href="#TYPES">Data Types</a><ul class="code">
 603         <li><a href="#gss_auth_identity_desc" title="Local functions...">gss_auth_identity_desc</a></li>
 604         <li><a href="#http_addr_t" title="Socket address union, which
 605 makes using IPv6 and other
 606 address types easier and
 607 more portable. ">http_addr_t</a></li>
 608         <li><a href="#http_addrlist_t" title="Socket address list, which is
 609 used to enumerate all of the
 610 addresses that are associated
 611 with a hostname. ">http_addrlist_t</a></li>
 612         <li><a href="#http_auth_t" title="HTTP authentication types">http_auth_t</a></li>
 613         <li><a href="#http_credential_t" title="HTTP credential data ">http_credential_t</a></li>
 614         <li><a href="#http_encoding_t" title="HTTP transfer encoding values">http_encoding_t</a></li>
 615         <li><a href="#http_encryption_t" title="HTTP encryption values">http_encryption_t</a></li>
 616         <li><a href="#http_field_t" title="HTTP field names">http_field_t</a></li>
 617         <li><a href="#http_keepalive_t" title="HTTP keep-alive values">http_keepalive_t</a></li>
 618         <li><a href="#http_state_t" title="HTTP state values; states
 619 are server-oriented...">http_state_t</a></li>
 620         <li><a href="#http_t" title="HTTP connection type">http_t</a></li>
 621         <li><a href="#http_timeout_cb_t" title="HTTP timeout callback ">http_timeout_cb_t</a></li>
 622         <li><a href="#http_uri_coding_t" title="URI en/decode flags">http_uri_coding_t</a></li>
 623         <li><a href="#http_uri_status_t" title="URI separation status ">http_uri_status_t</a></li>
 624         <li><a href="#http_version_t" title="HTTP version numbers">http_version_t</a></li>
 625         <li><a href="#ipp_attribute_t" title="IPP attribute">ipp_attribute_t</a></li>
 626         <li><a href="#ipp_copycb_t" title="The following structures are PRIVATE starting with CUPS 1.6/OS X 10.8.
 627 Please use the new accessor functions available in CUPS 1.6 and later, as
 628 these definitions will be moved to a private header file in a future release.">ipp_copycb_t</a></li>
 629         <li><a href="#ipp_dstate_t" title="Document states">ipp_dstate_t</a></li>
 630         <li><a href="#ipp_finish_t" title="Job collation types">ipp_finish_t</a></li>
 631         <li><a href="#ipp_iocb_t" title="IPP IO Callback Function ">ipp_iocb_t</a></li>
 632         <li><a href="#ipp_jcollate_t" title="Job collation types">ipp_jcollate_t</a></li>
 633         <li><a href="#ipp_orient_t" title="Orientation values">ipp_orient_t</a></li>
 634         <li><a href="#ipp_pstate_t" title="Printer states">ipp_pstate_t</a></li>
 635         <li><a href="#ipp_quality_t" title="Qualities">ipp_quality_t</a></li>
 636         <li><a href="#ipp_res_t" title="Resolution units">ipp_res_t</a></li>
 637         <li><a href="#ipp_state_t" title="IPP states">ipp_state_t</a></li>
 638         <li><a href="#ipp_t" title="IPP request/response data">ipp_t</a></li>
 639         <li><a href="#ipp_uchar_t" title="Unsigned 8-bit integer/character">ipp_uchar_t</a></li>
 640 </ul></li>
 641 <li><a href="#STRUCTURES">Structures</a><ul class="code">
 642         <li><a href="#gss_auth_identity" title="Local functions...">gss_auth_identity</a></li>
 643         <li><a href="#http_addrlist_s" title="Socket address list, which is
 644 used to enumerate all of the
 645 addresses that are associated
 646 with a hostname. ">http_addrlist_s</a></li>
 647         <li><a href="#http_credential_s" title="HTTP credential data ">http_credential_s</a></li>
 648         <li><a href="#pollfd" title="User data (unused)">pollfd</a></li>
 649 </ul></li>
 650 <li><a href="#ENUMERATIONS">Constants</a><ul class="code">
 651         <li><a href="#http_auth_e" title="HTTP authentication types">http_auth_e</a></li>
 652         <li><a href="#http_encoding_e" title="HTTP transfer encoding values">http_encoding_e</a></li>
 653         <li><a href="#http_encryption_e" title="HTTP encryption values">http_encryption_e</a></li>
 654         <li><a href="#http_field_e" title="HTTP field names">http_field_e</a></li>
 655         <li><a href="#http_keepalive_e" title="HTTP keep-alive values">http_keepalive_e</a></li>
 656         <li><a href="#http_state_e" title="HTTP state values; states
 657 are server-oriented...">http_state_e</a></li>
 658         <li><a href="#http_status_e" title="HTTP status codes">http_status_e</a></li>
 659         <li><a href="#http_uri_coding_e" title="URI en/decode flags">http_uri_coding_e</a></li>
 660         <li><a href="#http_uri_status_e" title="URI separation status ">http_uri_status_e</a></li>
 661         <li><a href="#http_version_e" title="HTTP version numbers">http_version_e</a></li>
 662         <li><a href="#ipp_dstate_e" title="Document states">ipp_dstate_e</a></li>
 663         <li><a href="#ipp_finishings_e" title="Finishings">ipp_finishings_e</a></li>
 664         <li><a href="#ipp_jcollate_e" title="Job collation types">ipp_jcollate_e</a></li>
 665         <li><a href="#ipp_jstate_e" title="Job states">ipp_jstate_e</a></li>
 666         <li><a href="#ipp_op_e" title="IPP operations">ipp_op_e</a></li>
 667         <li><a href="#ipp_orient_e" title="Orientation values">ipp_orient_e</a></li>
 668         <li><a href="#ipp_pstate_e" title="Printer states">ipp_pstate_e</a></li>
 669         <li><a href="#ipp_quality_e" title="Qualities">ipp_quality_e</a></li>
 670         <li><a href="#ipp_res_e" title="Resolution units">ipp_res_e</a></li>
 671         <li><a href="#ipp_state_e" title="IPP states">ipp_state_e</a></li>
 672         <li><a href="#ipp_status_e" title="IPP status codes">ipp_status_e</a></li>
 673         <li><a href="#ipp_tag_e" title="Format tags for attributes">ipp_tag_e</a></li>
 674 </ul></li>
 675 </ul>
 676 <!--
 677   "$Id$"
 678
 679   HTTP and IPP API introduction for CUPS.
 680
 681   Copyright 2007-2012 by Apple Inc.
 682   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 683
 684   These coded instructions, statements, and computer programs are the
 685   property of Apple Inc. and are protected by Federal copyright
 686   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 687   which should have been included with this file.  If this file is
 688   file is missing or damaged, see the license at "http://www.cups.org/".
 689 -->
 690
 691 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
 692
 693 <p>The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP
 694 protocols and CUPS scheduler. They are typically used by monitoring and
 695 administration programs to perform specific functions not supported by the
 696 high-level CUPS API functions.</p>
 697
 698 <p>The HTTP APIs use an opaque structure called
 699 <a href='#http_t'><code>http_t</code></a> to manage connections to
 700 a particular HTTP or IPP server. The
 701 <a href='#httpConnectEncrypt'><code>httpConnectEncrypt</code></a> function is
 702 used to create an instance of this structure for a particular server.
 703 The constant <code>CUPS_HTTP_DEFAULT</code> can be used with all of the
 704 <code>cups</code> functions to refer to the default CUPS server - the functions
 705 create a per-thread <a href='#http_t'><code>http_t</code></a> as needed.</p>
 706
 707 <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>
 708
 709 <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>
 710
 711 <pre class='example'>
 712 <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS);
 713
 714 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
 715              NULL, "ipp://localhost/printers/");
 716 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
 717              NULL, cupsUser());
 718 </pre>
 719
 720 <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>
 721
 722 <pre class='example'>
 723 #include &lt;cups/cups.h&gt;
 724
 725
 726 <a href='#ipp_t'>ipp_t</a> *<a name='get_jobs'>get_jobs</a>(void)
 727 {
 728   <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS);
 729
 730   <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
 731                NULL, "ipp://localhost/printers/");
 732   <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
 733                NULL, cupsUser());
 734
 735   return (<a href='#cupsDoRequest'>cupsDoRequest</a>(CUPS_HTTP_DEFAULT, request, "/"));
 736 }
 737 </pre>
 738
 739 <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>
 740
 741 <pre class='example'>
 742 <a href='#ipp_t'>ipp_t</a> *response;
 743 <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr;
 744
 745 attr = <a href='#ippFindAttribute'>ippFindAttribute</a>(response, "printer-state", IPP_TAG_ENUM);
 746 </pre>
 747
 748 <p>You can also walk the list of attributes with a simple <code>for</code> loop like this:</p>
 749
 750 <pre class='example'>
 751 <a href='#ipp_t'>ipp_t</a> *response;
 752 <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr;
 753
 754 for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response))
 755   if (ippGetName(attr) == NULL)
 756     puts("--SEPARATOR--");
 757   else
 758     puts(ippGetName(attr));
 759 </pre>
 760
 761 <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>
 762
 763 <pre class='example'>
 764 <a href='#ipp_t'>ipp_t</a> *response = <a href='#get_jobs'>get_jobs</a>();
 765
 766 if (response != NULL)
 767 {
 768   <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr;
 769   const char *attrname;
 770   int job_id = 0;
 771   const char *job_name = NULL;
 772   const char *job_originating_user_name = NULL;
 773
 774   puts("Job ID  Owner             Title");
 775   puts("------  ----------------  ---------------------------------");
 776
 777   for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response))
 778   {
 779    /* Attributes without names are separators between jobs */
 780     attrname = ippGetName(attr);
 781     if (attrname == NULL)
 782     {
 783       if (job_id > 0)
 784       {
 785         if (job_name == NULL)
 786           job_name = "(withheld)";
 787
 788         if (job_originating_user_name == NULL)
 789           job_originating_user_name = "(withheld)";
 790
 791         printf("%5d  %-16s  %s\n", job_id, job_originating_user_name, job_name);
 792       }
 793
 794       job_id = 0;
 795       job_name = NULL;
 796       job_originating_user_name = NULL;
 797       continue;
 798     }
 799     else if (!strcmp(attrname, "job-id") &amp;&amp; ippGetValueTag(attr) == IPP_TAG_INTEGER)
 800       job_id = ippGetInteger(attr, 0);
 801     else if (!strcmp(attrname, "job-name") &amp;&amp; ippGetValueTag(attr) == IPP_TAG_NAME)
 802       job_name = ippGetString(attr, 0, NULL);
 803     else if (!strcmp(attrname, "job-originating-user-name") &amp;&amp;
 804              ippGetValueTag(attr) == IPP_TAG_NAME)
 805       job_originating_user_name = ippGetString(attr, 0, NULL);
 806   }
 807
 808   if (job_id > 0)
 809   {
 810     if (job_name == NULL)
 811       job_name = "(withheld)";
 812
 813     if (job_originating_user_name == NULL)
 814       job_originating_user_name = "(withheld)";
 815
 816     printf("%5d  %-16s  %s\n", job_id, job_originating_user_name, job_name);
 817   }
 818 }
 819 </pre>
 820
 821 <h3><a name='CREATING_URI_STRINGS'>Creating URI Strings</a></h3>
 822
 823 <p>To ensure proper encoding, the
 824 <a href='#httpAssembleURIf'><code>httpAssembleURIf</code></a> function must be
 825 used to format a "printer-uri" string for all printer-based requests:</p>
 826
 827 <pre class='example'>
 828 const char *name = "Foo";
 829 char uri[1024];
 830 <a href='#ipp_t'>ipp_t</a> *request;
 831
 832 <a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
 833                  ippPort(), "/printers/%s", name);
 834 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
 835 </pre>
 836
 837 <h3><a name='SENDING_REQUESTS_WITH_FILES'>Sending Requests with Files</a></h3>
 838
 839 <p>The <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> and
 840 <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> functions are
 841 used for requests involving files. The
 842 <a href='#cupsDoFileRequest'><code>cupsDoFileRequest</code></a> function
 843 attaches the named file to a request and is typically used when sending a print
 844 file or changing a printer's PPD file:</p>
 845
 846 <pre class='example'>
 847 const char *filename = "/usr/share/cups/data/testprint.ps";
 848 const char *name = "Foo";
 849 char uri[1024];
 850 char resource[1024];
 851 <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_PRINT_JOB);
 852 <a href='#ipp_t'>ipp_t</a> *response;
 853
 854 /* Use httpAssembleURIf for the printer-uri string */
 855 <a href='#httpAssembleURIf'>httpAssembleURIf</a>(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
 856                  ippPort(), "/printers/%s", name);
 857 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
 858 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
 859              NULL, cupsUser());
 860 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
 861              NULL, "testprint.ps");
 862
 863 /* Use snprintf for the resource path */
 864 snprintf(resource, sizeof(resource), "/printers/%s", name);
 865
 866 response = <a href='#cupsDoFileRequest'>cupsDoFileRequest</a>(CUPS_HTTP_DEFAULT, request, resource, filename);
 867 </pre>
 868
 869 <p>The <a href='#cupsDoIORequest'><code>cupsDoIORequest</code></a> function
 870 optionally attaches a file to the request and optionally saves a file in the
 871 response from the server. It is used when using a pipe for the request
 872 attachment or when using a request that returns a file, currently only
 873 <code>CUPS_GET_DOCUMENT</code> and <code>CUPS_GET_PPD</code>. For example,
 874 the following code will download the PPD file for the sample HP LaserJet
 875 printer driver:</p>
 876
 877 <pre class='example'>
 878 char tempfile[1024];
 879 int tempfd;
 880 <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD);
 881 <a href='#ipp_t'>ipp_t</a> *response;
 882
 883 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
 884              NULL, "laserjet.ppd");
 885
 886 tempfd = cupsTempFd(tempfile, sizeof(tempfile));
 887
 888 response = <a href='#cupsDoIORequest'>cupsDoIORequest</a>(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd);
 889 </pre>
 890
 891 <p>The example passes <code>-1</code> for the input file descriptor to specify
 892 that no file is to be attached to the request. The PPD file attached to the
 893 response is written to the temporary file descriptor we created using the
 894 <code>cupsTempFd</code> function.</p>
 895
 896 <h3><a name='ASYNCHRONOUS_REQUEST_PROCESSING'>Asynchronous Request Processing</a></h3>
 897
 898 <p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> and
 899 <a href='#cupsGetResponse'><code>cupsGetResponse</code></a> support
 900 asynchronous communications with the server. Unlike the other request
 901 functions, the IPP request is not automatically freed, so remember to
 902 free your request with the <a href='#ippDelete'><code>ippDelete</code></a>
 903 function.</p>
 904
 905 <p>File data is attached to the request using the
 906 <a href='#cupsWriteRequestData'><code>cupsWriteRequestData</code></a>
 907 function, while file data returned from the server is read using the
 908 <a href='#cupsReadResponseData'><code>cupsReadResponseData</code></a>
 909 function. We can rewrite the previous <code>CUPS_GET_PPD</code> example
 910 to use the asynchronous functions quite easily:</p>
 911
 912 <pre class='example'>
 913 char tempfile[1024];
 914 int tempfd;
 915 <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD);
 916 <a href='#ipp_t'>ipp_t</a> *response;
 917
 918 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
 919              NULL, "laserjet.ppd");
 920
 921 tempfd = cupsTempFd(tempfile, sizeof(tempfile));
 922
 923 if (<a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE)
 924 {
 925   response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/");
 926
 927   if (response != NULL)
 928   {
 929     ssize_t bytes;
 930     char buffer[8192];
 931
 932     while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
 933       write(tempfd, buffer, bytes);
 934   }
 935 }
 936
 937 /* Free the request! */
 938 <a href='#ippDelete'>ippDelete</a>(request);
 939 </pre>
 940
 941 <p>The <a href='#cupsSendRequest'><code>cupsSendRequest</code></a> function
 942 returns the initial HTTP request status, typically either
 943 <code>HTTP_CONTINUE</code> or <code>HTTP_UNAUTHORIZED</code>. The latter status
 944 is returned when the request requires authentication of some sort. The
 945 <a href='#cupsDoAuthentication'><code>cupsDoAuthentication</code></a> function
 946 must be called when your see <code>HTTP_UNAUTHORIZED</code> and the request
 947 re-sent. We can add authentication support to our example code by using a
 948 <code>do ... while</code> loop:</p>
 949
 950 <pre class='example'>
 951 char tempfile[1024];
 952 int tempfd;
 953 <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(CUPS_GET_PPD);
 954 <a href='#ipp_t'>ipp_t</a> *response;
 955 http_status_t status;
 956
 957 <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
 958              NULL, "laserjet.ppd");
 959
 960 tempfd = cupsTempFd(tempfile, sizeof(tempfile));
 961
 962 /* Loop for authentication */
 963 do
 964 {
 965   status = <a href='#cupsSendRequest'>cupsSendRequest</a>(CUPS_HTTP_DEFAULT, request, "/");
 966
 967   if (status == HTTP_UNAUTHORIZED)
 968   {
 969     /* Try to authenticate, break out of the loop if that fails */
 970     if (<a href='#cupsDoAuthentication'>cupsDoAuthentication</a>(CUPS_HTTP_DEFAULT, "POST", "/"))
 971       break;
 972   }
 973 }
 974 while (status != HTTP_CONTINUE &amp;&amp; status != HTTP_UNAUTHORIZED);
 975
 976 if (status == HTTP_CONTINUE)
 977 {
 978   response = <a href='#cupsGetResponse'>cupsGetResponse</a>(CUPS_HTTP_DEFAULT, "/");
 979
 980   if (response != NULL)
 981   {
 982     ssize_t bytes;
 983     char buffer[8192];
 984
 985     while ((bytes = <a href='#cupsReadResponseData'>cupsReadResponseData</a>(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
 986       write(tempfd, buffer, bytes);
 987   }
 988 }
 989
 990 /* Free the request! */
 991 <a href='#ippDelete'>ippDelete</a>(request);
 992 </pre>
 993 <h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
 994 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20/OS X 10.4&nbsp;</span><a name="cupsDoAuthentication">cupsDoAuthentication</a></h3>
 995 <p class="description">Authenticate a request.</p>
 996 <p class="code">
 997 int cupsDoAuthentication (<br>
 998 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
 999 &nbsp;&nbsp;&nbsp;&nbsp;const char *method,<br>
1000 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource<br>
1001 );</p>
1002 <h4 class="parameters">Parameters</h4>
1003 <dl>
1004 <dt>http</dt>
1005 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1006 <dt>method</dt>
1007 <dd class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</dd>
1008 <dt>resource</dt>
1009 <dd class="description">Resource path</dd>
1010 </dl>
1011 <h4 class="returnvalue">Return Value</h4>
1012 <p class="description">0 on success, -1 on error</p>
1013 <h4 class="discussion">Discussion</h4>
1014 <p class="discussion">This function should be called in response to a <code>HTTP_UNAUTHORIZED</code>
1015 status, prior to resubmitting your request.
1016
1017 </p>
1018 <h3 class="function"><a name="cupsDoFileRequest">cupsDoFileRequest</a></h3>
1019 <p class="description">Do an IPP request with a file.</p>
1020 <p class="code">
1021 <a href="#ipp_t">ipp_t</a> *cupsDoFileRequest (<br>
1022 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1023 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request,<br>
1024 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1025 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename<br>
1026 );</p>
1027 <h4 class="parameters">Parameters</h4>
1028 <dl>
1029 <dt>http</dt>
1030 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1031 <dt>request</dt>
1032 <dd class="description">IPP request</dd>
1033 <dt>resource</dt>
1034 <dd class="description">HTTP resource for POST</dd>
1035 <dt>filename</dt>
1036 <dd class="description">File to send or <code>NULL</code> for none</dd>
1037 </dl>
1038 <h4 class="returnvalue">Return Value</h4>
1039 <p class="description">Response data</p>
1040 <h4 class="discussion">Discussion</h4>
1041 <p class="discussion">This function sends the IPP request and attached file to the specified
1042 server, retrying and authenticating as necessary.  The request is freed with
1043 <a href="#ippDelete"><code>ippDelete</code></a>.</p>
1044 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="cupsDoIORequest">cupsDoIORequest</a></h3>
1045 <p class="description">Do an IPP request with file descriptors.</p>
1046 <p class="code">
1047 <a href="#ipp_t">ipp_t</a> *cupsDoIORequest (<br>
1048 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1049 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request,<br>
1050 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1051 &nbsp;&nbsp;&nbsp;&nbsp;int infile,<br>
1052 &nbsp;&nbsp;&nbsp;&nbsp;int outfile<br>
1053 );</p>
1054 <h4 class="parameters">Parameters</h4>
1055 <dl>
1056 <dt>http</dt>
1057 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1058 <dt>request</dt>
1059 <dd class="description">IPP request</dd>
1060 <dt>resource</dt>
1061 <dd class="description">HTTP resource for POST</dd>
1062 <dt>infile</dt>
1063 <dd class="description">File to read from or -1 for none</dd>
1064 <dt>outfile</dt>
1065 <dd class="description">File to write to or -1 for none</dd>
1066 </dl>
1067 <h4 class="returnvalue">Return Value</h4>
1068 <p class="description">Response data</p>
1069 <h4 class="discussion">Discussion</h4>
1070 <p class="discussion">This function sends the IPP request with the optional input file &quot;infile&quot; to
1071 the specified server, retrying and authenticating as necessary.  The request
1072 is freed with <a href="#ippDelete"><code>ippDelete</code></a>.<br>
1073 <br>
1074 If &quot;infile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
1075 all of the data from the file after the IPP request message.<br>
1076 <br>
1077 If &quot;outfile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
1078 all of the data after the IPP response message to the file.
1079
1080 </p>
1081 <h3 class="function"><a name="cupsDoRequest">cupsDoRequest</a></h3>
1082 <p class="description">Do an IPP request.</p>
1083 <p class="code">
1084 <a href="#ipp_t">ipp_t</a> *cupsDoRequest (<br>
1085 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1086 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request,<br>
1087 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource<br>
1088 );</p>
1089 <h4 class="parameters">Parameters</h4>
1090 <dl>
1091 <dt>http</dt>
1092 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1093 <dt>request</dt>
1094 <dd class="description">IPP request</dd>
1095 <dt>resource</dt>
1096 <dd class="description">HTTP resource for POST</dd>
1097 </dl>
1098 <h4 class="returnvalue">Return Value</h4>
1099 <p class="description">Response data</p>
1100 <h4 class="discussion">Discussion</h4>
1101 <p class="discussion">This function sends the IPP request to the specified server, retrying
1102 and authenticating as necessary.  The request is freed with <a href="#ippDelete"><code>ippDelete</code></a>.</p>
1103 <h3 class="function"><a name="cupsEncodeOptions">cupsEncodeOptions</a></h3>
1104 <p class="description">Encode printer options into IPP attributes.</p>
1105 <p class="code">
1106 void cupsEncodeOptions (<br>
1107 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
1108 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1109 &nbsp;&nbsp;&nbsp;&nbsp;cups_option_t *options<br>
1110 );</p>
1111 <h4 class="parameters">Parameters</h4>
1112 <dl>
1113 <dt>ipp</dt>
1114 <dd class="description">Request to add to</dd>
1115 <dt>num_options</dt>
1116 <dd class="description">Number of options</dd>
1117 <dt>options</dt>
1118 <dd class="description">Options</dd>
1119 </dl>
1120 <h4 class="discussion">Discussion</h4>
1121 <p class="discussion">This function adds operation, job, and then subscription attributes,
1122 in that order. Use the cupsEncodeOptions2() function to add attributes
1123 for a single group.</p>
1124 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsEncodeOptions2">cupsEncodeOptions2</a></h3>
1125 <p class="description">Encode printer options into IPP attributes for a group.</p>
1126 <p class="code">
1127 void cupsEncodeOptions2 (<br>
1128 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
1129 &nbsp;&nbsp;&nbsp;&nbsp;int num_options,<br>
1130 &nbsp;&nbsp;&nbsp;&nbsp;cups_option_t *options,<br>
1131 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group_tag<br>
1132 );</p>
1133 <h4 class="parameters">Parameters</h4>
1134 <dl>
1135 <dt>ipp</dt>
1136 <dd class="description">Request to add to</dd>
1137 <dt>num_options</dt>
1138 <dd class="description">Number of options</dd>
1139 <dt>options</dt>
1140 <dd class="description">Options</dd>
1141 <dt>group_tag</dt>
1142 <dd class="description">Group to encode</dd>
1143 </dl>
1144 <h4 class="discussion">Discussion</h4>
1145 <p class="discussion">This function only adds attributes for a single group. Call this
1146 function multiple times for each group, or use cupsEncodeOptions()
1147 to add the standard groups.
1148
1149 </p>
1150 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsGetDevices">cupsGetDevices</a></h3>
1151 <p class="description">Get available printer devices.</p>
1152 <p class="code">
1153 ipp_status_t cupsGetDevices (<br>
1154 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1155 &nbsp;&nbsp;&nbsp;&nbsp;int timeout,<br>
1156 &nbsp;&nbsp;&nbsp;&nbsp;const char *include_schemes,<br>
1157 &nbsp;&nbsp;&nbsp;&nbsp;const char *exclude_schemes,<br>
1158 &nbsp;&nbsp;&nbsp;&nbsp;cups_device_cb_t callback,<br>
1159 &nbsp;&nbsp;&nbsp;&nbsp;void *user_data<br>
1160 );</p>
1161 <h4 class="parameters">Parameters</h4>
1162 <dl>
1163 <dt>http</dt>
1164 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1165 <dt>timeout</dt>
1166 <dd class="description">Timeout in seconds or <code>CUPS_TIMEOUT_DEFAULT</code></dd>
1167 <dt>include_schemes</dt>
1168 <dd class="description">Comma-separated URI schemes to include or <code>CUPS_INCLUDE_ALL</code></dd>
1169 <dt>exclude_schemes</dt>
1170 <dd class="description">Comma-separated URI schemes to exclude or <code>CUPS_EXCLUDE_NONE</code></dd>
1171 <dt>callback</dt>
1172 <dd class="description">Callback function</dd>
1173 <dt>user_data</dt>
1174 <dd class="description">User data pointer</dd>
1175 </dl>
1176 <h4 class="returnvalue">Return Value</h4>
1177 <p class="description">Request status - <code>IPP_OK</code> on success.</p>
1178 <h4 class="discussion">Discussion</h4>
1179 <p class="discussion">This function sends a CUPS-Get-Devices request and streams the discovered
1180 devices to the specified callback function. The &quot;timeout&quot; parameter controls
1181 how long the request lasts, while the &quot;include_schemes&quot; and &quot;exclude_schemes&quot;
1182 parameters provide comma-delimited lists of backends to include or omit from
1183 the request respectively.
1184
1185 </p>
1186 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20/OS X 10.4&nbsp;</span><a name="cupsGetFd">cupsGetFd</a></h3>
1187 <p class="description">Get a file from the server.</p>
1188 <p class="code">
1189 http_status_t cupsGetFd (<br>
1190 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1191 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1192 &nbsp;&nbsp;&nbsp;&nbsp;int fd<br>
1193 );</p>
1194 <h4 class="parameters">Parameters</h4>
1195 <dl>
1196 <dt>http</dt>
1197 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1198 <dt>resource</dt>
1199 <dd class="description">Resource name</dd>
1200 <dt>fd</dt>
1201 <dd class="description">File descriptor</dd>
1202 </dl>
1203 <h4 class="returnvalue">Return Value</h4>
1204 <p class="description">HTTP status</p>
1205 <h4 class="discussion">Discussion</h4>
1206 <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
1207
1208 </p>
1209 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20/OS X 10.4&nbsp;</span><a name="cupsGetFile">cupsGetFile</a></h3>
1210 <p class="description">Get a file from the server.</p>
1211 <p class="code">
1212 http_status_t cupsGetFile (<br>
1213 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1214 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1215 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename<br>
1216 );</p>
1217 <h4 class="parameters">Parameters</h4>
1218 <dl>
1219 <dt>http</dt>
1220 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1221 <dt>resource</dt>
1222 <dd class="description">Resource name</dd>
1223 <dt>filename</dt>
1224 <dd class="description">Filename</dd>
1225 </dl>
1226 <h4 class="returnvalue">Return Value</h4>
1227 <p class="description">HTTP status</p>
1228 <h4 class="discussion">Discussion</h4>
1229 <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved.
1230
1231 </p>
1232 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsGetResponse">cupsGetResponse</a></h3>
1233 <p class="description">Get a response to an IPP request.</p>
1234 <p class="code">
1235 <a href="#ipp_t">ipp_t</a> *cupsGetResponse (<br>
1236 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1237 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource<br>
1238 );</p>
1239 <h4 class="parameters">Parameters</h4>
1240 <dl>
1241 <dt>http</dt>
1242 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1243 <dt>resource</dt>
1244 <dd class="description">HTTP resource for POST</dd>
1245 </dl>
1246 <h4 class="returnvalue">Return Value</h4>
1247 <p class="description">Response or <code>NULL</code> on HTTP error</p>
1248 <h4 class="discussion">Discussion</h4>
1249 <p class="discussion">Use this function to get the response for an IPP request sent using
1250 <a href="#cupsSendRequest"><code>cupsSendRequest</code></a>. For requests that return additional data, use
1251 <a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> after getting a successful response,
1252 otherwise call <a href="#httpFlush"><code>httpFlush</code></a> to complete the response processing.
1253
1254 </p>
1255 <h3 class="function"><a name="cupsLastError">cupsLastError</a></h3>
1256 <p class="description">Return the last IPP status code received on the current
1257 thread.</p>
1258 <p class="code">
1259 ipp_status_t cupsLastError (void);</p>
1260 <h4 class="returnvalue">Return Value</h4>
1261 <p class="description">IPP status code from last request</p>
1262 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="cupsLastErrorString">cupsLastErrorString</a></h3>
1263 <p class="description">Return the last IPP status-message received on the
1264 current thread.</p>
1265 <p class="code">
1266 const char *cupsLastErrorString (void);</p>
1267 <h4 class="returnvalue">Return Value</h4>
1268 <p class="description">status-message text from last request</p>
1269 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20/OS X 10.4&nbsp;</span><a name="cupsPutFd">cupsPutFd</a></h3>
1270 <p class="description">Put a file on the server.</p>
1271 <p class="code">
1272 http_status_t cupsPutFd (<br>
1273 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1274 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1275 &nbsp;&nbsp;&nbsp;&nbsp;int fd<br>
1276 );</p>
1277 <h4 class="parameters">Parameters</h4>
1278 <dl>
1279 <dt>http</dt>
1280 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1281 <dt>resource</dt>
1282 <dd class="description">Resource name</dd>
1283 <dt>fd</dt>
1284 <dd class="description">File descriptor</dd>
1285 </dl>
1286 <h4 class="returnvalue">Return Value</h4>
1287 <p class="description">HTTP status</p>
1288 <h4 class="discussion">Discussion</h4>
1289 <p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
1290 successfully.
1291
1292 </p>
1293 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.20/OS X 10.4&nbsp;</span><a name="cupsPutFile">cupsPutFile</a></h3>
1294 <p class="description">Put a file on the server.</p>
1295 <p class="code">
1296 http_status_t cupsPutFile (<br>
1297 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1298 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1299 &nbsp;&nbsp;&nbsp;&nbsp;const char *filename<br>
1300 );</p>
1301 <h4 class="parameters">Parameters</h4>
1302 <dl>
1303 <dt>http</dt>
1304 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1305 <dt>resource</dt>
1306 <dd class="description">Resource name</dd>
1307 <dt>filename</dt>
1308 <dd class="description">Filename</dd>
1309 </dl>
1310 <h4 class="returnvalue">Return Value</h4>
1311 <p class="description">HTTP status</p>
1312 <h4 class="discussion">Discussion</h4>
1313 <p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
1314 successfully.
1315
1316 </p>
1317 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsReadResponseData">cupsReadResponseData</a></h3>
1318 <p class="description">Read additional data after the IPP response.</p>
1319 <p class="code">
1320 ssize_t cupsReadResponseData (<br>
1321 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1322 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
1323 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
1324 );</p>
1325 <h4 class="parameters">Parameters</h4>
1326 <dl>
1327 <dt>http</dt>
1328 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1329 <dt>buffer</dt>
1330 <dd class="description">Buffer to use</dd>
1331 <dt>length</dt>
1332 <dd class="description">Number of bytes to read</dd>
1333 </dl>
1334 <h4 class="returnvalue">Return Value</h4>
1335 <p class="description">Bytes read, 0 on EOF, -1 on error</p>
1336 <h4 class="discussion">Discussion</h4>
1337 <p class="discussion">This function is used after <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to read the PPD or document
1338 files from <code>CUPS_GET_PPD</code> and <code>CUPS_GET_DOCUMENT</code> requests,
1339 respectively.
1340
1341 </p>
1342 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsSendRequest">cupsSendRequest</a></h3>
1343 <p class="description">Send an IPP request.</p>
1344 <p class="code">
1345 http_status_t cupsSendRequest (<br>
1346 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1347 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request,<br>
1348 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
1349 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
1350 );</p>
1351 <h4 class="parameters">Parameters</h4>
1352 <dl>
1353 <dt>http</dt>
1354 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1355 <dt>request</dt>
1356 <dd class="description">IPP request</dd>
1357 <dt>resource</dt>
1358 <dd class="description">Resource path</dd>
1359 <dt>length</dt>
1360 <dd class="description">Length of data to follow or <code>CUPS_LENGTH_VARIABLE</code></dd>
1361 </dl>
1362 <h4 class="returnvalue">Return Value</h4>
1363 <p class="description">Initial HTTP status</p>
1364 <h4 class="discussion">Discussion</h4>
1365 <p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write any additional data (document, PPD
1366 file, etc.) for the request, <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to get the IPP response,
1367 and <a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> to read any additional data following the
1368 response. Only one request can be sent/queued at a time per <code>http_t</code>
1369 connection.<br>
1370 <br>
1371 Returns the initial HTTP status code, which will be <code>HTTP_CONTINUE</code>
1372 on a successful send of the request.<br>
1373 <br>
1374 Note: Unlike <a href="#cupsDoFileRequest"><code>cupsDoFileRequest</code></a>, <a href="#cupsDoIORequest"><code>cupsDoIORequest</code></a>, and
1375 <a href="#cupsDoRequest"><code>cupsDoRequest</code></a>, the request is NOT freed with <a href="#ippDelete"><code>ippDelete</code></a>.
1376
1377 </p>
1378 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="cupsWriteRequestData">cupsWriteRequestData</a></h3>
1379 <p class="description">Write additional data after an IPP request.</p>
1380 <p class="code">
1381 http_status_t cupsWriteRequestData (<br>
1382 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1383 &nbsp;&nbsp;&nbsp;&nbsp;const char *buffer,<br>
1384 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
1385 );</p>
1386 <h4 class="parameters">Parameters</h4>
1387 <dl>
1388 <dt>http</dt>
1389 <dd class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></dd>
1390 <dt>buffer</dt>
1391 <dd class="description">Bytes to write</dd>
1392 <dt>length</dt>
1393 <dd class="description">Number of bytes to write</dd>
1394 </dl>
1395 <h4 class="returnvalue">Return Value</h4>
1396 <p class="description"><code>HTTP_CONTINUE</code> if OK or HTTP status on error</p>
1397 <h4 class="discussion">Discussion</h4>
1398 <p class="discussion">This function is used after <a href="#cupsSendRequest"><code>cupsSendRequest</code></a> to provide a PPD and
1399 after <a href="#cupsStartDocument"><code>cupsStartDocument</code></a> to provide a document file.
1400
1401 </p>
1402 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpAcceptConnection">httpAcceptConnection</a></h3>
1403 <p class="description">Accept a new HTTP client connection from the
1404 specified listening socket.</p>
1405 <p class="code">
1406 <a href="#http_t">http_t</a> *httpAcceptConnection (<br>
1407 &nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
1408 &nbsp;&nbsp;&nbsp;&nbsp;int blocking<br>
1409 );</p>
1410 <h4 class="parameters">Parameters</h4>
1411 <dl>
1412 <dt>fd</dt>
1413 <dd class="description">Listen socket file descriptor</dd>
1414 <dt>blocking</dt>
1415 <dd class="description">1 if the connection should be
1416 blocking, 0 otherwise</dd>
1417 </dl>
1418 <h4 class="returnvalue">Return Value</h4>
1419 <p class="description">HTTP connection or <code>NULL</code></p>
1420 <h3 class="function"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="httpAddCredential">httpAddCredential</a></h3>
1421 <p class="description">Allocates and adds a single credential to an array.</p>
1422 <p class="code">
1423 int httpAddCredential (<br>
1424 &nbsp;&nbsp;&nbsp;&nbsp;cups_array_t *credentials,<br>
1425 &nbsp;&nbsp;&nbsp;&nbsp;const void *data,<br>
1426 &nbsp;&nbsp;&nbsp;&nbsp;size_t datalen<br>
1427 );</p>
1428 <h4 class="parameters">Parameters</h4>
1429 <dl>
1430 <dt>credentials</dt>
1431 <dd class="description">Credentials array</dd>
1432 <dt>data</dt>
1433 <dd class="description">PEM-encoded X.509 data</dd>
1434 <dt>datalen</dt>
1435 <dd class="description">Length of data</dd>
1436 </dl>
1437 <h4 class="returnvalue">Return Value</h4>
1438 <p class="description">0 on success, -1 on error</p>
1439 <h4 class="discussion">Discussion</h4>
1440 <p class="discussion">Use <code>cupsArrayNew(NULL, NULL)</code> to create a credentials array.
1441
1442 </p>
1443 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrAny">httpAddrAny</a></h3>
1444 <p class="description">Check for the &quot;any&quot; address.</p>
1445 <p class="code">
1446 int httpAddrAny (<br>
1447 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr<br>
1448 );</p>
1449 <h4 class="parameters">Parameters</h4>
1450 <dl>
1451 <dt>addr</dt>
1452 <dd class="description">Address to check</dd>
1453 </dl>
1454 <h4 class="returnvalue">Return Value</h4>
1455 <p class="description">1 if &quot;any&quot;, 0 otherwise</p>
1456 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrEqual">httpAddrEqual</a></h3>
1457 <p class="description">Compare two addresses.</p>
1458 <p class="code">
1459 int httpAddrEqual (<br>
1460 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr1,<br>
1461 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr2<br>
1462 );</p>
1463 <h4 class="parameters">Parameters</h4>
1464 <dl>
1465 <dt>addr1</dt>
1466 <dd class="description">First address</dd>
1467 <dt>addr2</dt>
1468 <dd class="description">Second address</dd>
1469 </dl>
1470 <h4 class="returnvalue">Return Value</h4>
1471 <p class="description">1 if equal, 0 if not</p>
1472 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrLength">httpAddrLength</a></h3>
1473 <p class="description">Return the length of the address in bytes.</p>
1474 <p class="code">
1475 int httpAddrLength (<br>
1476 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr<br>
1477 );</p>
1478 <h4 class="parameters">Parameters</h4>
1479 <dl>
1480 <dt>addr</dt>
1481 <dd class="description">Address</dd>
1482 </dl>
1483 <h4 class="returnvalue">Return Value</h4>
1484 <p class="description">Length in bytes</p>
1485 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpAddrListen">httpAddrListen</a></h3>
1486 <p class="description">Create a listening socket bound to the specified
1487 address and port.</p>
1488 <p class="code">
1489 int httpAddrListen (<br>
1490 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_addr_t">http_addr_t</a> *addr,<br>
1491 &nbsp;&nbsp;&nbsp;&nbsp;int port<br>
1492 );</p>
1493 <h4 class="parameters">Parameters</h4>
1494 <dl>
1495 <dt>addr</dt>
1496 <dd class="description">Address to bind to</dd>
1497 <dt>port</dt>
1498 <dd class="description">Port number to bind to</dd>
1499 </dl>
1500 <h4 class="returnvalue">Return Value</h4>
1501 <p class="description">Socket or -1 on error</p>
1502 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrLocalhost">httpAddrLocalhost</a></h3>
1503 <p class="description">Check for the local loopback address.</p>
1504 <p class="code">
1505 int httpAddrLocalhost (<br>
1506 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr<br>
1507 );</p>
1508 <h4 class="parameters">Parameters</h4>
1509 <dl>
1510 <dt>addr</dt>
1511 <dd class="description">Address to check</dd>
1512 </dl>
1513 <h4 class="returnvalue">Return Value</h4>
1514 <p class="description">1 if local host, 0 otherwise</p>
1515 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrLookup">httpAddrLookup</a></h3>
1516 <p class="description">Lookup the hostname associated with the address.</p>
1517 <p class="code">
1518 char *httpAddrLookup (<br>
1519 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr,<br>
1520 &nbsp;&nbsp;&nbsp;&nbsp;char *name,<br>
1521 &nbsp;&nbsp;&nbsp;&nbsp;int namelen<br>
1522 );</p>
1523 <h4 class="parameters">Parameters</h4>
1524 <dl>
1525 <dt>addr</dt>
1526 <dd class="description">Address to lookup</dd>
1527 <dt>name</dt>
1528 <dd class="description">Host name buffer</dd>
1529 <dt>namelen</dt>
1530 <dd class="description">Size of name buffer</dd>
1531 </dl>
1532 <h4 class="returnvalue">Return Value</h4>
1533 <p class="description">Host name</p>
1534 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpAddrPort">httpAddrPort</a></h3>
1535 <p class="description">Get the port number associated with an address.</p>
1536 <p class="code">
1537 int httpAddrPort (<br>
1538 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_addr_t">http_addr_t</a> *addr<br>
1539 );</p>
1540 <h4 class="parameters">Parameters</h4>
1541 <dl>
1542 <dt>addr</dt>
1543 <dd class="description">Address</dd>
1544 </dl>
1545 <h4 class="returnvalue">Return Value</h4>
1546 <p class="description">Port number</p>
1547 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAddrString">httpAddrString</a></h3>
1548 <p class="description">Convert an address to a numeric string.</p>
1549 <p class="code">
1550 char *httpAddrString (<br>
1551 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#http_addr_t">http_addr_t</a> *addr,<br>
1552 &nbsp;&nbsp;&nbsp;&nbsp;char *s,<br>
1553 &nbsp;&nbsp;&nbsp;&nbsp;int slen<br>
1554 );</p>
1555 <h4 class="parameters">Parameters</h4>
1556 <dl>
1557 <dt>addr</dt>
1558 <dd class="description">Address to convert</dd>
1559 <dt>s</dt>
1560 <dd class="description">String buffer</dd>
1561 <dt>slen</dt>
1562 <dd class="description">Length of string</dd>
1563 </dl>
1564 <h4 class="returnvalue">Return Value</h4>
1565 <p class="description">Numeric address string</p>
1566 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAssembleURI">httpAssembleURI</a></h3>
1567 <p class="description">Assemble a uniform resource identifier from its
1568 components.</p>
1569 <p class="code">
1570 <a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURI (<br>
1571 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br>
1572 &nbsp;&nbsp;&nbsp;&nbsp;char *uri,<br>
1573 &nbsp;&nbsp;&nbsp;&nbsp;int urilen,<br>
1574 &nbsp;&nbsp;&nbsp;&nbsp;const char *scheme,<br>
1575 &nbsp;&nbsp;&nbsp;&nbsp;const char *username,<br>
1576 &nbsp;&nbsp;&nbsp;&nbsp;const char *host,<br>
1577 &nbsp;&nbsp;&nbsp;&nbsp;int port,<br>
1578 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource<br>
1579 );</p>
1580 <h4 class="parameters">Parameters</h4>
1581 <dl>
1582 <dt>encoding</dt>
1583 <dd class="description">Encoding flags</dd>
1584 <dt>uri</dt>
1585 <dd class="description">URI buffer</dd>
1586 <dt>urilen</dt>
1587 <dd class="description">Size of URI buffer</dd>
1588 <dt>scheme</dt>
1589 <dd class="description">Scheme name</dd>
1590 <dt>username</dt>
1591 <dd class="description">Username</dd>
1592 <dt>host</dt>
1593 <dd class="description">Hostname or address</dd>
1594 <dt>port</dt>
1595 <dd class="description">Port number</dd>
1596 <dt>resource</dt>
1597 <dd class="description">Resource</dd>
1598 </dl>
1599 <h4 class="returnvalue">Return Value</h4>
1600 <p class="description">URI status</p>
1601 <h4 class="discussion">Discussion</h4>
1602 <p class="discussion">This function escapes reserved characters in the URI depending on the
1603 value of the &quot;encoding&quot; argument.  You should use this function in
1604 place of traditional string functions whenever you need to create a
1605 URI string.
1606
1607 </p>
1608 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpAssembleURIf">httpAssembleURIf</a></h3>
1609 <p class="description">Assemble a uniform resource identifier from its
1610 components with a formatted resource.</p>
1611 <p class="code">
1612 <a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURIf (<br>
1613 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br>
1614 &nbsp;&nbsp;&nbsp;&nbsp;char *uri,<br>
1615 &nbsp;&nbsp;&nbsp;&nbsp;int urilen,<br>
1616 &nbsp;&nbsp;&nbsp;&nbsp;const char *scheme,<br>
1617 &nbsp;&nbsp;&nbsp;&nbsp;const char *username,<br>
1618 &nbsp;&nbsp;&nbsp;&nbsp;const char *host,<br>
1619 &nbsp;&nbsp;&nbsp;&nbsp;int port,<br>
1620 &nbsp;&nbsp;&nbsp;&nbsp;const char *resourcef,<br>
1621 &nbsp;&nbsp;&nbsp;&nbsp;...<br>
1622 );</p>
1623 <h4 class="parameters">Parameters</h4>
1624 <dl>
1625 <dt>encoding</dt>
1626 <dd class="description">Encoding flags</dd>
1627 <dt>uri</dt>
1628 <dd class="description">URI buffer</dd>
1629 <dt>urilen</dt>
1630 <dd class="description">Size of URI buffer</dd>
1631 <dt>scheme</dt>
1632 <dd class="description">Scheme name</dd>
1633 <dt>username</dt>
1634 <dd class="description">Username</dd>
1635 <dt>host</dt>
1636 <dd class="description">Hostname or address</dd>
1637 <dt>port</dt>
1638 <dd class="description">Port number</dd>
1639 <dt>resourcef</dt>
1640 <dd class="description">Printf-style resource</dd>
1641 <dt>...</dt>
1642 <dd class="description">Additional arguments as needed</dd>
1643 </dl>
1644 <h4 class="returnvalue">Return Value</h4>
1645 <p class="description">URI status</p>
1646 <h4 class="discussion">Discussion</h4>
1647 <p class="discussion">This function creates a formatted version of the resource string
1648 argument &quot;resourcef&quot; and escapes reserved characters in the URI
1649 depending on the value of the &quot;encoding&quot; argument.  You should use
1650 this function in place of traditional string functions whenever
1651 you need to create a URI string.
1652
1653 </p>
1654 <h3 class="function"><a name="httpAssembleUUID">httpAssembleUUID</a></h3>
1655 <p class="description">Assemble a name-based UUID URN conforming to RFC 4122.</p>
1656 <p class="code">
1657 char *httpAssembleUUID (<br>
1658 &nbsp;&nbsp;&nbsp;&nbsp;const char *server,<br>
1659 &nbsp;&nbsp;&nbsp;&nbsp;int port,<br>
1660 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
1661 &nbsp;&nbsp;&nbsp;&nbsp;int number,<br>
1662 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
1663 &nbsp;&nbsp;&nbsp;&nbsp;size_t bufsize<br>
1664 );</p>
1665 <h4 class="parameters">Parameters</h4>
1666 <dl>
1667 <dt>server</dt>
1668 <dd class="description">Server name</dd>
1669 <dt>port</dt>
1670 <dd class="description">Port number</dd>
1671 <dt>name</dt>
1672 <dd class="description">Object name or NULL</dd>
1673 <dt>number</dt>
1674 <dd class="description">Object number or 0</dd>
1675 <dt>buffer</dt>
1676 <dd class="description">String buffer</dd>
1677 <dt>bufsize</dt>
1678 <dd class="description">Size of buffer</dd>
1679 </dl>
1680 <h4 class="returnvalue">Return Value</h4>
1681 <p class="description">UUID string</p>
1682 <h4 class="discussion">Discussion</h4>
1683 <p class="discussion">This function creates a unique 128-bit identifying number using the server
1684 name, port number, random data, and optionally an object name and/or object
1685 number.  The result is formatted as a UUID URN as defined in RFC 4122.<br>
1686 <br>
1687 The buffer needs to be at least 46 bytes in size.</p>
1688 <h3 class="function"><a name="httpBlocking">httpBlocking</a></h3>
1689 <p class="description">Set blocking/non-blocking behavior on a connection.</p>
1690 <p class="code">
1691 void httpBlocking (<br>
1692 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1693 &nbsp;&nbsp;&nbsp;&nbsp;int b<br>
1694 );</p>
1695 <h4 class="parameters">Parameters</h4>
1696 <dl>
1697 <dt>http</dt>
1698 <dd class="description">Connection to server</dd>
1699 <dt>b</dt>
1700 <dd class="description">1 = blocking, 0 = non-blocking</dd>
1701 </dl>
1702 <h3 class="function"><a name="httpCheck">httpCheck</a></h3>
1703 <p class="description">Check to see if there is a pending response from the server.</p>
1704 <p class="code">
1705 int httpCheck (<br>
1706 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1707 );</p>
1708 <h4 class="parameters">Parameters</h4>
1709 <dl>
1710 <dt>http</dt>
1711 <dd class="description">Connection to server</dd>
1712 </dl>
1713 <h4 class="returnvalue">Return Value</h4>
1714 <p class="description">0 = no data, 1 = data available</p>
1715 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="httpClearCookie">httpClearCookie</a></h3>
1716 <p class="description">Clear the cookie value(s).</p>
1717 <p class="code">
1718 void httpClearCookie (<br>
1719 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1720 );</p>
1721 <h4 class="parameters">Parameters</h4>
1722 <dl>
1723 <dt>http</dt>
1724 <dd class="description">Connection to server</dd>
1725 </dl>
1726 <h3 class="function"><a name="httpClearFields">httpClearFields</a></h3>
1727 <p class="description">Clear HTTP request fields.</p>
1728 <p class="code">
1729 void httpClearFields (<br>
1730 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1731 );</p>
1732 <h4 class="parameters">Parameters</h4>
1733 <dl>
1734 <dt>http</dt>
1735 <dd class="description">Connection to server</dd>
1736 </dl>
1737 <h3 class="function"><a name="httpClose">httpClose</a></h3>
1738 <p class="description">Close an HTTP connection.</p>
1739 <p class="code">
1740 void httpClose (<br>
1741 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1742 );</p>
1743 <h4 class="parameters">Parameters</h4>
1744 <dl>
1745 <dt>http</dt>
1746 <dd class="description">Connection to server</dd>
1747 </dl>
1748 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpConnect">httpConnect</a></h3>
1749 <p class="description">Connect to a HTTP server.</p>
1750 <p class="code">
1751 <a href="#http_t">http_t</a> *httpConnect (<br>
1752 &nbsp;&nbsp;&nbsp;&nbsp;const char *host,<br>
1753 &nbsp;&nbsp;&nbsp;&nbsp;int port<br>
1754 );</p>
1755 <h4 class="parameters">Parameters</h4>
1756 <dl>
1757 <dt>host</dt>
1758 <dd class="description">Host to connect to</dd>
1759 <dt>port</dt>
1760 <dd class="description">Port number</dd>
1761 </dl>
1762 <h4 class="returnvalue">Return Value</h4>
1763 <p class="description">New HTTP connection</p>
1764 <h4 class="discussion">Discussion</h4>
1765 <p class="discussion">This function is deprecated - use <a href="#httpConnect2"><code>httpConnect2</code></a> instead.
1766
1767 </p>
1768 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpConnect2">httpConnect2</a></h3>
1769 <p class="description">Connect to a HTTP server.</p>
1770 <p class="code">
1771 <a href="#http_t">http_t</a> *httpConnect2 (<br>
1772 &nbsp;&nbsp;&nbsp;&nbsp;const char *host,<br>
1773 &nbsp;&nbsp;&nbsp;&nbsp;int port,<br>
1774 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_addrlist_t">http_addrlist_t</a> *addrlist,<br>
1775 &nbsp;&nbsp;&nbsp;&nbsp;int family,<br>
1776 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_encryption_t">http_encryption_t</a> encryption,<br>
1777 &nbsp;&nbsp;&nbsp;&nbsp;int blocking,<br>
1778 &nbsp;&nbsp;&nbsp;&nbsp;int msec,<br>
1779 &nbsp;&nbsp;&nbsp;&nbsp;int *cancel<br>
1780 );</p>
1781 <h4 class="parameters">Parameters</h4>
1782 <dl>
1783 <dt>host</dt>
1784 <dd class="description">Host to connect to</dd>
1785 <dt>port</dt>
1786 <dd class="description">Port number</dd>
1787 <dt>addrlist</dt>
1788 <dd class="description">List of addresses or NULL to lookup</dd>
1789 <dt>family</dt>
1790 <dd class="description">Address family to use or <code>AF_UNSPEC</code> for any</dd>
1791 <dt>encryption</dt>
1792 <dd class="description">Type of encryption to use</dd>
1793 <dt>blocking</dt>
1794 <dd class="description">1 for blocking connection, 0 for non-blocking</dd>
1795 <dt>msec</dt>
1796 <dd class="description">Connection timeout in milliseconds, 0 means don't connect</dd>
1797 <dt>cancel</dt>
1798 <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
1799 </dl>
1800 <h4 class="returnvalue">Return Value</h4>
1801 <p class="description">New HTTP connection</p>
1802 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpConnectEncrypt">httpConnectEncrypt</a></h3>
1803 <p class="description">Connect to a HTTP server using encryption.</p>
1804 <p class="code">
1805 <a href="#http_t">http_t</a> *httpConnectEncrypt (<br>
1806 &nbsp;&nbsp;&nbsp;&nbsp;const char *host,<br>
1807 &nbsp;&nbsp;&nbsp;&nbsp;int port,<br>
1808 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_encryption_t">http_encryption_t</a> encryption<br>
1809 );</p>
1810 <h4 class="parameters">Parameters</h4>
1811 <dl>
1812 <dt>host</dt>
1813 <dd class="description">Host to connect to</dd>
1814 <dt>port</dt>
1815 <dd class="description">Port number</dd>
1816 <dt>encryption</dt>
1817 <dd class="description">Type of encryption to use</dd>
1818 </dl>
1819 <h4 class="returnvalue">Return Value</h4>
1820 <p class="description">New HTTP connection</p>
1821 <h4 class="discussion">Discussion</h4>
1822 <p class="discussion">This function is now deprecated. Please use the <a href="#httpConnect2"><code>httpConnect2</code></a> function
1823 instead.
1824
1825 </p>
1826 <h3 class="function"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="httpCopyCredentials">httpCopyCredentials</a></h3>
1827 <p class="description">Copy the credentials associated with an encrypted
1828 connection.</p>
1829 <p class="code">
1830 int httpCopyCredentials (<br>
1831 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1832 &nbsp;&nbsp;&nbsp;&nbsp;cups_array_t **credentials<br>
1833 );</p>
1834 <h4 class="parameters">Parameters</h4>
1835 <dl>
1836 <dt>http</dt>
1837 <dd class="description">Connection to server</dd>
1838 <dt>credentials</dt>
1839 <dd class="description">Array of credentials</dd>
1840 </dl>
1841 <h4 class="returnvalue">Return Value</h4>
1842 <p class="description">Status of call (0 = success)</p>
1843 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpDecode64">httpDecode64</a></h3>
1844 <p class="description">Base64-decode a string.</p>
1845 <p class="code">
1846 char *httpDecode64 (<br>
1847 &nbsp;&nbsp;&nbsp;&nbsp;char *out,<br>
1848 &nbsp;&nbsp;&nbsp;&nbsp;const char *in<br>
1849 );</p>
1850 <h4 class="parameters">Parameters</h4>
1851 <dl>
1852 <dt>out</dt>
1853 <dd class="description">String to write to</dd>
1854 <dt>in</dt>
1855 <dd class="description">String to read from</dd>
1856 </dl>
1857 <h4 class="returnvalue">Return Value</h4>
1858 <p class="description">Decoded string</p>
1859 <h4 class="discussion">Discussion</h4>
1860 <p class="discussion">This function is deprecated. Use the httpDecode64_2() function instead
1861 which provides buffer length arguments.
1862
1863 </p>
1864 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21/OS X 10.4&nbsp;</span><a name="httpDecode64_2">httpDecode64_2</a></h3>
1865 <p class="description">Base64-decode a string.</p>
1866 <p class="code">
1867 char *httpDecode64_2 (<br>
1868 &nbsp;&nbsp;&nbsp;&nbsp;char *out,<br>
1869 &nbsp;&nbsp;&nbsp;&nbsp;int *outlen,<br>
1870 &nbsp;&nbsp;&nbsp;&nbsp;const char *in<br>
1871 );</p>
1872 <h4 class="parameters">Parameters</h4>
1873 <dl>
1874 <dt>out</dt>
1875 <dd class="description">String to write to</dd>
1876 <dt>outlen</dt>
1877 <dd class="description">Size of output string</dd>
1878 <dt>in</dt>
1879 <dd class="description">String to read from</dd>
1880 </dl>
1881 <h4 class="returnvalue">Return Value</h4>
1882 <p class="description">Decoded string</p>
1883 <h3 class="function"><a name="httpDelete">httpDelete</a></h3>
1884 <p class="description">Send a DELETE request to the server.</p>
1885 <p class="code">
1886 int httpDelete (<br>
1887 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1888 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
1889 );</p>
1890 <h4 class="parameters">Parameters</h4>
1891 <dl>
1892 <dt>http</dt>
1893 <dd class="description">Connection to server</dd>
1894 <dt>uri</dt>
1895 <dd class="description">URI to delete</dd>
1896 </dl>
1897 <h4 class="returnvalue">Return Value</h4>
1898 <p class="description">Status of call (0 = success)</p>
1899 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpEncode64">httpEncode64</a></h3>
1900 <p class="description">Base64-encode a string.</p>
1901 <p class="code">
1902 char *httpEncode64 (<br>
1903 &nbsp;&nbsp;&nbsp;&nbsp;char *out,<br>
1904 &nbsp;&nbsp;&nbsp;&nbsp;const char *in<br>
1905 );</p>
1906 <h4 class="parameters">Parameters</h4>
1907 <dl>
1908 <dt>out</dt>
1909 <dd class="description">String to write to</dd>
1910 <dt>in</dt>
1911 <dd class="description">String to read from</dd>
1912 </dl>
1913 <h4 class="returnvalue">Return Value</h4>
1914 <p class="description">Encoded string</p>
1915 <h4 class="discussion">Discussion</h4>
1916 <p class="discussion">This function is deprecated. Use the httpEncode64_2() function instead
1917 which provides buffer length arguments.
1918
1919 </p>
1920 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21/OS X 10.4&nbsp;</span><a name="httpEncode64_2">httpEncode64_2</a></h3>
1921 <p class="description">Base64-encode a string.</p>
1922 <p class="code">
1923 char *httpEncode64_2 (<br>
1924 &nbsp;&nbsp;&nbsp;&nbsp;char *out,<br>
1925 &nbsp;&nbsp;&nbsp;&nbsp;int outlen,<br>
1926 &nbsp;&nbsp;&nbsp;&nbsp;const char *in,<br>
1927 &nbsp;&nbsp;&nbsp;&nbsp;int inlen<br>
1928 );</p>
1929 <h4 class="parameters">Parameters</h4>
1930 <dl>
1931 <dt>out</dt>
1932 <dd class="description">String to write to</dd>
1933 <dt>outlen</dt>
1934 <dd class="description">Size of output string</dd>
1935 <dt>in</dt>
1936 <dd class="description">String to read from</dd>
1937 <dt>inlen</dt>
1938 <dd class="description">Size of input string</dd>
1939 </dl>
1940 <h4 class="returnvalue">Return Value</h4>
1941 <p class="description">Encoded string</p>
1942 <h3 class="function"><a name="httpEncryption">httpEncryption</a></h3>
1943 <p class="description">Set the required encryption on the link.</p>
1944 <p class="code">
1945 int httpEncryption (<br>
1946 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
1947 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_encryption_t">http_encryption_t</a> e<br>
1948 );</p>
1949 <h4 class="parameters">Parameters</h4>
1950 <dl>
1951 <dt>http</dt>
1952 <dd class="description">Connection to server</dd>
1953 <dt>e</dt>
1954 <dd class="description">New encryption preference</dd>
1955 </dl>
1956 <h4 class="returnvalue">Return Value</h4>
1957 <p class="description">-1 on error, 0 on success</p>
1958 <h3 class="function"><a name="httpError">httpError</a></h3>
1959 <p class="description">Get the last error on a connection.</p>
1960 <p class="code">
1961 int httpError (<br>
1962 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1963 );</p>
1964 <h4 class="parameters">Parameters</h4>
1965 <dl>
1966 <dt>http</dt>
1967 <dd class="description">Connection to server</dd>
1968 </dl>
1969 <h4 class="returnvalue">Return Value</h4>
1970 <p class="description">Error code (errno) value</p>
1971 <h3 class="function"><a name="httpFlush">httpFlush</a></h3>
1972 <p class="description">Flush data from a HTTP connection.</p>
1973 <p class="code">
1974 void httpFlush (<br>
1975 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1976 );</p>
1977 <h4 class="parameters">Parameters</h4>
1978 <dl>
1979 <dt>http</dt>
1980 <dd class="description">Connection to server</dd>
1981 </dl>
1982 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpFlushWrite">httpFlushWrite</a></h3>
1983 <p class="description">Flush data in write buffer.</p>
1984 <p class="code">
1985 int httpFlushWrite (<br>
1986 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
1987 );</p>
1988 <h4 class="parameters">Parameters</h4>
1989 <dl>
1990 <dt>http</dt>
1991 <dd class="description">Connection to server</dd>
1992 </dl>
1993 <h4 class="returnvalue">Return Value</h4>
1994 <p class="description">Bytes written or -1 on error</p>
1995 <h3 class="function"><a name="httpFreeCredentials">httpFreeCredentials</a></h3>
1996 <p class="description">Free an array of credentials.</p>
1997 <p class="code">
1998 void httpFreeCredentials (<br>
1999 &nbsp;&nbsp;&nbsp;&nbsp;cups_array_t *credentials<br>
2000 );</p>
2001 <h4 class="parameters">Parameters</h4>
2002 <dl>
2003 <dt>credentials</dt>
2004 <dd class="description">Array of credentials</dd>
2005 </dl>
2006 <h3 class="function"><a name="httpGet">httpGet</a></h3>
2007 <p class="description">Send a GET request to the server.</p>
2008 <p class="code">
2009 int httpGet (<br>
2010 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2011 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2012 );</p>
2013 <h4 class="parameters">Parameters</h4>
2014 <dl>
2015 <dt>http</dt>
2016 <dd class="description">Connection to server</dd>
2017 <dt>uri</dt>
2018 <dd class="description">URI to get</dd>
2019 </dl>
2020 <h4 class="returnvalue">Return Value</h4>
2021 <p class="description">Status of call (0 = success)</p>
2022 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="httpGetAuthString">httpGetAuthString</a></h3>
2023 <p class="description">Get the current authorization string.</p>
2024 <p class="code">
2025 char *httpGetAuthString (<br>
2026 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2027 );</p>
2028 <h4 class="parameters">Parameters</h4>
2029 <dl>
2030 <dt>http</dt>
2031 <dd class="description">Connection to server</dd>
2032 </dl>
2033 <h4 class="returnvalue">Return Value</h4>
2034 <p class="description">Authorization string</p>
2035 <h4 class="discussion">Discussion</h4>
2036 <p class="discussion">The authorization string is set by cupsDoAuthentication() and
2037 httpSetAuthString().  Use httpGetAuthString() to retrieve the
2038 string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION
2039 value.
2040
2041 </p>
2042 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetBlocking">httpGetBlocking</a></h3>
2043 <p class="description">Get the blocking/non-block state of a connection.</p>
2044 <p class="code">
2045 int httpGetBlocking (<br>
2046 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2047 );</p>
2048 <h4 class="parameters">Parameters</h4>
2049 <dl>
2050 <dt>http</dt>
2051 <dd class="description">Connection to server</dd>
2052 </dl>
2053 <h4 class="returnvalue">Return Value</h4>
2054 <p class="description">1 if blocking, 0 if non-blocking</p>
2055 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpGetContentEncoding">httpGetContentEncoding</a></h3>
2056 <p class="description">Get a common content encoding, if any, between
2057 the client and server.</p>
2058 <p class="code">
2059 const char *httpGetContentEncoding (<br>
2060 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2061 );</p>
2062 <h4 class="parameters">Parameters</h4>
2063 <dl>
2064 <dt>http</dt>
2065 <dd class="description">Connection to client/server</dd>
2066 </dl>
2067 <h4 class="returnvalue">Return Value</h4>
2068 <p class="description">Content-Coding value or
2069 <code>NULL</code> for the identity
2070 coding.</p>
2071 <h4 class="discussion">Discussion</h4>
2072 <p class="discussion">This function uses the value of the Accepts-Encoding HTTP header and must be
2073 called after receiving a response from the server or a request from the
2074 client.  The value returned can be use in subsequent requests (for clients)
2075 or in the response (for servers) in order to compress the content stream.
2076
2077 </p>
2078 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="httpGetCookie">httpGetCookie</a></h3>
2079 <p class="description">Get any cookie data from the response.</p>
2080 <p class="code">
2081 const char *httpGetCookie (<br>
2082 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2083 );</p>
2084 <h4 class="parameters">Parameters</h4>
2085 <dl>
2086 <dt>http</dt>
2087 <dd class="description">HTTP connecion</dd>
2088 </dl>
2089 <h4 class="returnvalue">Return Value</h4>
2090 <p class="description">Cookie data or NULL</p>
2091 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpGetDateString">httpGetDateString</a></h3>
2092 <p class="description">Get a formatted date/time string from a time value.</p>
2093 <p class="code">
2094 const char *httpGetDateString (<br>
2095 &nbsp;&nbsp;&nbsp;&nbsp;time_t t<br>
2096 );</p>
2097 <h4 class="parameters">Parameters</h4>
2098 <dl>
2099 <dt>t</dt>
2100 <dd class="description">UNIX time</dd>
2101 </dl>
2102 <h4 class="returnvalue">Return Value</h4>
2103 <p class="description">Date/time string</p>
2104 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetDateString2">httpGetDateString2</a></h3>
2105 <p class="description">Get a formatted date/time string from a time value.</p>
2106 <p class="code">
2107 const char *httpGetDateString2 (<br>
2108 &nbsp;&nbsp;&nbsp;&nbsp;time_t t,<br>
2109 &nbsp;&nbsp;&nbsp;&nbsp;char *s,<br>
2110 &nbsp;&nbsp;&nbsp;&nbsp;int slen<br>
2111 );</p>
2112 <h4 class="parameters">Parameters</h4>
2113 <dl>
2114 <dt>t</dt>
2115 <dd class="description">UNIX time</dd>
2116 <dt>s</dt>
2117 <dd class="description">String buffer</dd>
2118 <dt>slen</dt>
2119 <dd class="description">Size of string buffer</dd>
2120 </dl>
2121 <h4 class="returnvalue">Return Value</h4>
2122 <p class="description">Date/time string</p>
2123 <h3 class="function"><a name="httpGetDateTime">httpGetDateTime</a></h3>
2124 <p class="description">Get a time value from a formatted date/time string.</p>
2125 <p class="code">
2126 time_t httpGetDateTime (<br>
2127 &nbsp;&nbsp;&nbsp;&nbsp;const char *s<br>
2128 );</p>
2129 <h4 class="parameters">Parameters</h4>
2130 <dl>
2131 <dt>s</dt>
2132 <dd class="description">Date/time string</dd>
2133 </dl>
2134 <h4 class="returnvalue">Return Value</h4>
2135 <p class="description">UNIX time</p>
2136 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpGetExpect">httpGetExpect</a></h3>
2137 <p class="description">Get the value of the Expect header, if any.</p>
2138 <p class="code">
2139 http_status_t httpGetExpect (<br>
2140 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2141 );</p>
2142 <h4 class="parameters">Parameters</h4>
2143 <dl>
2144 <dt>http</dt>
2145 <dd class="description">Connection to client</dd>
2146 </dl>
2147 <h4 class="returnvalue">Return Value</h4>
2148 <p class="description">Expect: status, if any</p>
2149 <h4 class="discussion">Discussion</h4>
2150 <p class="discussion">Returns <code>HTTP_STATUS_NONE</code> if there is no Expect header, otherwise
2151 returns the expected HTTP status code, typically <code>HTTP_STATUS_CONTINUE</code>.
2152
2153 </p>
2154 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetFd">httpGetFd</a></h3>
2155 <p class="description">Get the file descriptor associated with a connection.</p>
2156 <p class="code">
2157 int httpGetFd (<br>
2158 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2159 );</p>
2160 <h4 class="parameters">Parameters</h4>
2161 <dl>
2162 <dt>http</dt>
2163 <dd class="description">Connection to server</dd>
2164 </dl>
2165 <h4 class="returnvalue">Return Value</h4>
2166 <p class="description">File descriptor or -1 if none</p>
2167 <h3 class="function"><a name="httpGetField">httpGetField</a></h3>
2168 <p class="description">Get a field value from a request/response.</p>
2169 <p class="code">
2170 const char *httpGetField (<br>
2171 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2172 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_field_t">http_field_t</a> field<br>
2173 );</p>
2174 <h4 class="parameters">Parameters</h4>
2175 <dl>
2176 <dt>http</dt>
2177 <dd class="description">Connection to server</dd>
2178 <dt>field</dt>
2179 <dd class="description">Field to get</dd>
2180 </dl>
2181 <h4 class="returnvalue">Return Value</h4>
2182 <p class="description">Field value</p>
2183 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpGetHostByName">httpGetHostByName</a></h3>
2184 <p class="description">Lookup a hostname or IPv4 address, and return
2185 address records for the specified name.</p>
2186 <p class="code">
2187 struct hostent *httpGetHostByName (<br>
2188 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
2189 );</p>
2190 <h4 class="parameters">Parameters</h4>
2191 <dl>
2192 <dt>name</dt>
2193 <dd class="description">Hostname or IP address</dd>
2194 </dl>
2195 <h4 class="returnvalue">Return Value</h4>
2196 <p class="description">Host entry</p>
2197 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetHostname">httpGetHostname</a></h3>
2198 <p class="description">Get the FQDN for the connection or local system.</p>
2199 <p class="code">
2200 const char *httpGetHostname (<br>
2201 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2202 &nbsp;&nbsp;&nbsp;&nbsp;char *s,<br>
2203 &nbsp;&nbsp;&nbsp;&nbsp;int slen<br>
2204 );</p>
2205 <h4 class="parameters">Parameters</h4>
2206 <dl>
2207 <dt>http</dt>
2208 <dd class="description">HTTP connection or NULL</dd>
2209 <dt>s</dt>
2210 <dd class="description">String buffer for name</dd>
2211 <dt>slen</dt>
2212 <dd class="description">Size of buffer</dd>
2213 </dl>
2214 <h4 class="returnvalue">Return Value</h4>
2215 <p class="description">FQDN for connection or system</p>
2216 <h4 class="discussion">Discussion</h4>
2217 <p class="discussion">When &quot;http&quot; points to a connected socket, return the hostname or
2218 address that was used in the call to httpConnect() or httpConnectEncrypt().
2219 Otherwise, return the FQDN for the local system using both gethostname()
2220 and gethostbyname() to get the local hostname with domain.
2221
2222 </p>
2223 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpGetLength">httpGetLength</a></h3>
2224 <p class="description">Get the amount of data remaining from the
2225 content-length or transfer-encoding fields.</p>
2226 <p class="code">
2227 int httpGetLength (<br>
2228 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2229 );</p>
2230 <h4 class="parameters">Parameters</h4>
2231 <dl>
2232 <dt>http</dt>
2233 <dd class="description">Connection to server</dd>
2234 </dl>
2235 <h4 class="returnvalue">Return Value</h4>
2236 <p class="description">Content length</p>
2237 <h4 class="discussion">Discussion</h4>
2238 <p class="discussion">This function is deprecated and will not return lengths larger than
2239 2^31 - 1; use httpGetLength2() instead.
2240
2241 </p>
2242 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetLength2">httpGetLength2</a></h3>
2243 <p class="description">Get the amount of data remaining from the
2244 content-length or transfer-encoding fields.</p>
2245 <p class="code">
2246 off_t httpGetLength2 (<br>
2247 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2248 );</p>
2249 <h4 class="parameters">Parameters</h4>
2250 <dl>
2251 <dt>http</dt>
2252 <dd class="description">Connection to server</dd>
2253 </dl>
2254 <h4 class="returnvalue">Return Value</h4>
2255 <p class="description">Content length</p>
2256 <h4 class="discussion">Discussion</h4>
2257 <p class="discussion">This function returns the complete content length, even for
2258 content larger than 2^31 - 1.
2259
2260 </p>
2261 <h3 class="function"><a name="httpGetState">httpGetState</a></h3>
2262 <p class="description">Get the current state of the HTTP request.</p>
2263 <p class="code">
2264 <a href="#http_state_t">http_state_t</a> httpGetState (<br>
2265 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2266 );</p>
2267 <h4 class="parameters">Parameters</h4>
2268 <dl>
2269 <dt>http</dt>
2270 <dd class="description">Connection to server</dd>
2271 </dl>
2272 <h4 class="returnvalue">Return Value</h4>
2273 <p class="description">HTTP state</p>
2274 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetStatus">httpGetStatus</a></h3>
2275 <p class="description">Get the status of the last HTTP request.</p>
2276 <p class="code">
2277 http_status_t httpGetStatus (<br>
2278 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2279 );</p>
2280 <h4 class="parameters">Parameters</h4>
2281 <dl>
2282 <dt>http</dt>
2283 <dd class="description">Connection to server</dd>
2284 </dl>
2285 <h4 class="returnvalue">Return Value</h4>
2286 <p class="description">HTTP status</p>
2287 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpGetSubField">httpGetSubField</a></h3>
2288 <p class="description">Get a sub-field value.</p>
2289 <p class="code">
2290 char *httpGetSubField (<br>
2291 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2292 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_field_t">http_field_t</a> field,<br>
2293 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
2294 &nbsp;&nbsp;&nbsp;&nbsp;char *value<br>
2295 );</p>
2296 <h4 class="parameters">Parameters</h4>
2297 <dl>
2298 <dt>http</dt>
2299 <dd class="description">Connection to server</dd>
2300 <dt>field</dt>
2301 <dd class="description">Field index</dd>
2302 <dt>name</dt>
2303 <dd class="description">Name of sub-field</dd>
2304 <dt>value</dt>
2305 <dd class="description">Value string</dd>
2306 </dl>
2307 <h4 class="returnvalue">Return Value</h4>
2308 <p class="description">Value or NULL</p>
2309 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpGetSubField2">httpGetSubField2</a></h3>
2310 <p class="description">Get a sub-field value.</p>
2311 <p class="code">
2312 char *httpGetSubField2 (<br>
2313 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2314 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_field_t">http_field_t</a> field,<br>
2315 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
2316 &nbsp;&nbsp;&nbsp;&nbsp;char *value,<br>
2317 &nbsp;&nbsp;&nbsp;&nbsp;int valuelen<br>
2318 );</p>
2319 <h4 class="parameters">Parameters</h4>
2320 <dl>
2321 <dt>http</dt>
2322 <dd class="description">Connection to server</dd>
2323 <dt>field</dt>
2324 <dd class="description">Field index</dd>
2325 <dt>name</dt>
2326 <dd class="description">Name of sub-field</dd>
2327 <dt>value</dt>
2328 <dd class="description">Value string</dd>
2329 <dt>valuelen</dt>
2330 <dd class="description">Size of value buffer</dd>
2331 </dl>
2332 <h4 class="returnvalue">Return Value</h4>
2333 <p class="description">Value or NULL</p>
2334 <h3 class="function"><a name="httpGetVersion">httpGetVersion</a></h3>
2335 <p class="description">Get the HTTP version at the other end.</p>
2336 <p class="code">
2337 <a href="#http_version_t">http_version_t</a> httpGetVersion (<br>
2338 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2339 );</p>
2340 <h4 class="parameters">Parameters</h4>
2341 <dl>
2342 <dt>http</dt>
2343 <dd class="description">Connection to server</dd>
2344 </dl>
2345 <h4 class="returnvalue">Return Value</h4>
2346 <p class="description">Version number</p>
2347 <h3 class="function"><a name="httpGets">httpGets</a></h3>
2348 <p class="description">Get a line of text from a HTTP connection.</p>
2349 <p class="code">
2350 char *httpGets (<br>
2351 &nbsp;&nbsp;&nbsp;&nbsp;char *line,<br>
2352 &nbsp;&nbsp;&nbsp;&nbsp;int length,<br>
2353 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2354 );</p>
2355 <h4 class="parameters">Parameters</h4>
2356 <dl>
2357 <dt>line</dt>
2358 <dd class="description">Line to read into</dd>
2359 <dt>length</dt>
2360 <dd class="description">Max length of buffer</dd>
2361 <dt>http</dt>
2362 <dd class="description">Connection to server</dd>
2363 </dl>
2364 <h4 class="returnvalue">Return Value</h4>
2365 <p class="description">Line or NULL</p>
2366 <h3 class="function"><a name="httpHead">httpHead</a></h3>
2367 <p class="description">Send a HEAD request to the server.</p>
2368 <p class="code">
2369 int httpHead (<br>
2370 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2371 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2372 );</p>
2373 <h4 class="parameters">Parameters</h4>
2374 <dl>
2375 <dt>http</dt>
2376 <dd class="description">Connection to server</dd>
2377 <dt>uri</dt>
2378 <dd class="description">URI for head</dd>
2379 </dl>
2380 <h4 class="returnvalue">Return Value</h4>
2381 <p class="description">Status of call (0 = success)</p>
2382 <h3 class="function"><a name="httpInitialize">httpInitialize</a></h3>
2383 <p class="description">Initialize the HTTP interface library and set the
2384 default HTTP proxy (if any).</p>
2385 <p class="code">
2386 void httpInitialize (void);</p>
2387 <h3 class="function"><a name="httpMD5">httpMD5</a></h3>
2388 <p class="description">Compute the MD5 sum of the username:group:password.</p>
2389 <p class="code">
2390 char *httpMD5 (<br>
2391 &nbsp;&nbsp;&nbsp;&nbsp;const char *username,<br>
2392 &nbsp;&nbsp;&nbsp;&nbsp;const char *realm,<br>
2393 &nbsp;&nbsp;&nbsp;&nbsp;const char *passwd,<br>
2394 &nbsp;&nbsp;&nbsp;&nbsp;char md5[33]<br>
2395 );</p>
2396 <h4 class="parameters">Parameters</h4>
2397 <dl>
2398 <dt>username</dt>
2399 <dd class="description">User name</dd>
2400 <dt>realm</dt>
2401 <dd class="description">Realm name</dd>
2402 <dt>passwd</dt>
2403 <dd class="description">Password string</dd>
2404 <dt>md5[33]</dt>
2405 <dd class="description">MD5 string</dd>
2406 </dl>
2407 <h4 class="returnvalue">Return Value</h4>
2408 <p class="description">MD5 sum</p>
2409 <h3 class="function"><a name="httpMD5Final">httpMD5Final</a></h3>
2410 <p class="description">Combine the MD5 sum of the username, group, and password
2411 with the server-supplied nonce value, method, and
2412 request-uri.</p>
2413 <p class="code">
2414 char *httpMD5Final (<br>
2415 &nbsp;&nbsp;&nbsp;&nbsp;const char *nonce,<br>
2416 &nbsp;&nbsp;&nbsp;&nbsp;const char *method,<br>
2417 &nbsp;&nbsp;&nbsp;&nbsp;const char *resource,<br>
2418 &nbsp;&nbsp;&nbsp;&nbsp;char md5[33]<br>
2419 );</p>
2420 <h4 class="parameters">Parameters</h4>
2421 <dl>
2422 <dt>nonce</dt>
2423 <dd class="description">Server nonce value</dd>
2424 <dt>method</dt>
2425 <dd class="description">METHOD (GET, POST, etc.)</dd>
2426 <dt>resource</dt>
2427 <dd class="description">Resource path</dd>
2428 <dt>md5[33]</dt>
2429 <dd class="description">MD5 sum</dd>
2430 </dl>
2431 <h4 class="returnvalue">Return Value</h4>
2432 <p class="description">New sum</p>
2433 <h3 class="function"><a name="httpMD5String">httpMD5String</a></h3>
2434 <p class="description">Convert an MD5 sum to a character string.</p>
2435 <p class="code">
2436 char *httpMD5String (<br>
2437 &nbsp;&nbsp;&nbsp;&nbsp;const unsigned char *sum,<br>
2438 &nbsp;&nbsp;&nbsp;&nbsp;char md5[33]<br>
2439 );</p>
2440 <h4 class="parameters">Parameters</h4>
2441 <dl>
2442 <dt>sum</dt>
2443 <dd class="description">MD5 sum data</dd>
2444 <dt>md5[33]</dt>
2445 <dd class="description">MD5 sum in hex</dd>
2446 </dl>
2447 <h4 class="returnvalue">Return Value</h4>
2448 <p class="description">MD5 sum in hex</p>
2449 <h3 class="function"><a name="httpOptions">httpOptions</a></h3>
2450 <p class="description">Send an OPTIONS request to the server.</p>
2451 <p class="code">
2452 int httpOptions (<br>
2453 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2454 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2455 );</p>
2456 <h4 class="parameters">Parameters</h4>
2457 <dl>
2458 <dt>http</dt>
2459 <dd class="description">Connection to server</dd>
2460 <dt>uri</dt>
2461 <dd class="description">URI for options</dd>
2462 </dl>
2463 <h4 class="returnvalue">Return Value</h4>
2464 <p class="description">Status of call (0 = success)</p>
2465 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpPeek">httpPeek</a></h3>
2466 <p class="description">Peek at data from a HTTP connection.</p>
2467 <p class="code">
2468 ssize_t httpPeek (<br>
2469 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2470 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
2471 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
2472 );</p>
2473 <h4 class="parameters">Parameters</h4>
2474 <dl>
2475 <dt>http</dt>
2476 <dd class="description">Connection to server</dd>
2477 <dt>buffer</dt>
2478 <dd class="description">Buffer for data</dd>
2479 <dt>length</dt>
2480 <dd class="description">Maximum number of bytes</dd>
2481 </dl>
2482 <h4 class="returnvalue">Return Value</h4>
2483 <p class="description">Number of bytes copied</p>
2484 <h4 class="discussion">Discussion</h4>
2485 <p class="discussion">This function copies available data from the given HTTP connection, reading
2486 a buffer as needed.  The data is still available for reading using
2487 <a href="#httpRead"><code>httpRead</code></a> or <a href="#httpRead2"><code>httpRead2</code></a>.<br>
2488 <br>
2489 For non-blocking connections the usual timeouts apply.
2490
2491 </p>
2492 <h3 class="function"><a name="httpPost">httpPost</a></h3>
2493 <p class="description">Send a POST request to the server.</p>
2494 <p class="code">
2495 int httpPost (<br>
2496 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2497 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2498 );</p>
2499 <h4 class="parameters">Parameters</h4>
2500 <dl>
2501 <dt>http</dt>
2502 <dd class="description">Connection to server</dd>
2503 <dt>uri</dt>
2504 <dd class="description">URI for post</dd>
2505 </dl>
2506 <h4 class="returnvalue">Return Value</h4>
2507 <p class="description">Status of call (0 = success)</p>
2508 <h3 class="function"><a name="httpPut">httpPut</a></h3>
2509 <p class="description">Send a PUT request to the server.</p>
2510 <p class="code">
2511 int httpPut (<br>
2512 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2513 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2514 );</p>
2515 <h4 class="parameters">Parameters</h4>
2516 <dl>
2517 <dt>http</dt>
2518 <dd class="description">Connection to server</dd>
2519 <dt>uri</dt>
2520 <dd class="description">URI to put</dd>
2521 </dl>
2522 <h4 class="returnvalue">Return Value</h4>
2523 <p class="description">Status of call (0 = success)</p>
2524 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpRead">httpRead</a></h3>
2525 <p class="description">Read data from a HTTP connection.</p>
2526 <p class="code">
2527 int httpRead (<br>
2528 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2529 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
2530 &nbsp;&nbsp;&nbsp;&nbsp;int length<br>
2531 );</p>
2532 <h4 class="parameters">Parameters</h4>
2533 <dl>
2534 <dt>http</dt>
2535 <dd class="description">Connection to server</dd>
2536 <dt>buffer</dt>
2537 <dd class="description">Buffer for data</dd>
2538 <dt>length</dt>
2539 <dd class="description">Maximum number of bytes</dd>
2540 </dl>
2541 <h4 class="returnvalue">Return Value</h4>
2542 <p class="description">Number of bytes read</p>
2543 <h4 class="discussion">Discussion</h4>
2544 <p class="discussion">This function is deprecated. Use the httpRead2() function which can
2545 read more than 2GB of data.
2546
2547 </p>
2548 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpRead2">httpRead2</a></h3>
2549 <p class="description">Read data from a HTTP connection.</p>
2550 <p class="code">
2551 ssize_t httpRead2 (<br>
2552 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2553 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
2554 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
2555 );</p>
2556 <h4 class="parameters">Parameters</h4>
2557 <dl>
2558 <dt>http</dt>
2559 <dd class="description">Connection to server</dd>
2560 <dt>buffer</dt>
2561 <dd class="description">Buffer for data</dd>
2562 <dt>length</dt>
2563 <dd class="description">Maximum number of bytes</dd>
2564 </dl>
2565 <h4 class="returnvalue">Return Value</h4>
2566 <p class="description">Number of bytes read</p>
2567 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpReadRequest">httpReadRequest</a></h3>
2568 <p class="description">Read a HTTP request from a connection.</p>
2569 <p class="code">
2570 <a href="#http_state_t">http_state_t</a> httpReadRequest (<br>
2571 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2572 &nbsp;&nbsp;&nbsp;&nbsp;char *uri,<br>
2573 &nbsp;&nbsp;&nbsp;&nbsp;size_t urilen<br>
2574 );</p>
2575 <h4 class="parameters">Parameters</h4>
2576 <dl>
2577 <dt>http</dt>
2578 <dd class="description">HTTP connection</dd>
2579 <dt>uri</dt>
2580 <dd class="description">URI buffer</dd>
2581 <dt>urilen</dt>
2582 <dd class="description">Size of URI buffer</dd>
2583 </dl>
2584 <h4 class="returnvalue">Return Value</h4>
2585 <p class="description">New state of connection</p>
2586 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpReconnect">httpReconnect</a></h3>
2587 <p class="description">Reconnect to a HTTP server.</p>
2588 <p class="code">
2589 int httpReconnect (<br>
2590 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2591 );</p>
2592 <h4 class="parameters">Parameters</h4>
2593 <dl>
2594 <dt>http</dt>
2595 <dd class="description">Connection to server</dd>
2596 </dl>
2597 <h4 class="returnvalue">Return Value</h4>
2598 <p class="description">0 on success, non-zero on failure</p>
2599 <h4 class="discussion">Discussion</h4>
2600 <p class="discussion">This function is deprecated. Please use the <a href="#httpReconnect2"><code>httpReconnect2</code></a> function
2601 instead.
2602
2603 </p>
2604 <h3 class="function"><a name="httpReconnect2">httpReconnect2</a></h3>
2605 <p class="description">Reconnect to a HTTP server with timeout and optional
2606 cancel.</p>
2607 <p class="code">
2608 int httpReconnect2 (<br>
2609 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2610 &nbsp;&nbsp;&nbsp;&nbsp;int msec,<br>
2611 &nbsp;&nbsp;&nbsp;&nbsp;int *cancel<br>
2612 );</p>
2613 <h4 class="parameters">Parameters</h4>
2614 <dl>
2615 <dt>http</dt>
2616 <dd class="description">Connection to server</dd>
2617 <dt>msec</dt>
2618 <dd class="description">Timeout in milliseconds</dd>
2619 <dt>cancel</dt>
2620 <dd class="description">Pointer to &quot;cancel&quot; variable</dd>
2621 </dl>
2622 <h4 class="returnvalue">Return Value</h4>
2623 <p class="description">0 on success, non-zero on failure</p>
2624 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpSeparate">httpSeparate</a></h3>
2625 <p class="description">Separate a Universal Resource Identifier into its
2626 components.</p>
2627 <p class="code">
2628 void httpSeparate (<br>
2629 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri,<br>
2630 &nbsp;&nbsp;&nbsp;&nbsp;char *scheme,<br>
2631 &nbsp;&nbsp;&nbsp;&nbsp;char *username,<br>
2632 &nbsp;&nbsp;&nbsp;&nbsp;char *host,<br>
2633 &nbsp;&nbsp;&nbsp;&nbsp;int *port,<br>
2634 &nbsp;&nbsp;&nbsp;&nbsp;char *resource<br>
2635 );</p>
2636 <h4 class="parameters">Parameters</h4>
2637 <dl>
2638 <dt>uri</dt>
2639 <dd class="description">Universal Resource Identifier</dd>
2640 <dt>scheme</dt>
2641 <dd class="description">Scheme [32] (http, https, etc.)</dd>
2642 <dt>username</dt>
2643 <dd class="description">Username [1024]</dd>
2644 <dt>host</dt>
2645 <dd class="description">Hostname [1024]</dd>
2646 <dt>port</dt>
2647 <dd class="description">Port number to use</dd>
2648 <dt>resource</dt>
2649 <dd class="description">Resource/filename [1024]</dd>
2650 </dl>
2651 <h4 class="discussion">Discussion</h4>
2652 <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead.
2653
2654 </p>
2655 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.21/OS X 10.4&nbsp;</span><a name="httpSeparate2">httpSeparate2</a></h3>
2656 <p class="description">Separate a Universal Resource Identifier into its
2657 components.</p>
2658 <p class="code">
2659 void httpSeparate2 (<br>
2660 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri,<br>
2661 &nbsp;&nbsp;&nbsp;&nbsp;char *scheme,<br>
2662 &nbsp;&nbsp;&nbsp;&nbsp;int schemelen,<br>
2663 &nbsp;&nbsp;&nbsp;&nbsp;char *username,<br>
2664 &nbsp;&nbsp;&nbsp;&nbsp;int usernamelen,<br>
2665 &nbsp;&nbsp;&nbsp;&nbsp;char *host,<br>
2666 &nbsp;&nbsp;&nbsp;&nbsp;int hostlen,<br>
2667 &nbsp;&nbsp;&nbsp;&nbsp;int *port,<br>
2668 &nbsp;&nbsp;&nbsp;&nbsp;char *resource,<br>
2669 &nbsp;&nbsp;&nbsp;&nbsp;int resourcelen<br>
2670 );</p>
2671 <h4 class="parameters">Parameters</h4>
2672 <dl>
2673 <dt>uri</dt>
2674 <dd class="description">Universal Resource Identifier</dd>
2675 <dt>scheme</dt>
2676 <dd class="description">Scheme (http, https, etc.)</dd>
2677 <dt>schemelen</dt>
2678 <dd class="description">Size of scheme buffer</dd>
2679 <dt>username</dt>
2680 <dd class="description">Username</dd>
2681 <dt>usernamelen</dt>
2682 <dd class="description">Size of username buffer</dd>
2683 <dt>host</dt>
2684 <dd class="description">Hostname</dd>
2685 <dt>hostlen</dt>
2686 <dd class="description">Size of hostname buffer</dd>
2687 <dt>port</dt>
2688 <dd class="description">Port number to use</dd>
2689 <dt>resource</dt>
2690 <dd class="description">Resource/filename</dd>
2691 <dt>resourcelen</dt>
2692 <dd class="description">Size of resource buffer</dd>
2693 </dl>
2694 <h4 class="discussion">Discussion</h4>
2695 <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead.
2696
2697
2698 </p>
2699 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpSeparateURI">httpSeparateURI</a></h3>
2700 <p class="description">Separate a Universal Resource Identifier into its
2701 components.</p>
2702 <p class="code">
2703 <a href="#http_uri_status_t">http_uri_status_t</a> httpSeparateURI (<br>
2704 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_uri_coding_t">http_uri_coding_t</a> decoding,<br>
2705 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri,<br>
2706 &nbsp;&nbsp;&nbsp;&nbsp;char *scheme,<br>
2707 &nbsp;&nbsp;&nbsp;&nbsp;int schemelen,<br>
2708 &nbsp;&nbsp;&nbsp;&nbsp;char *username,<br>
2709 &nbsp;&nbsp;&nbsp;&nbsp;int usernamelen,<br>
2710 &nbsp;&nbsp;&nbsp;&nbsp;char *host,<br>
2711 &nbsp;&nbsp;&nbsp;&nbsp;int hostlen,<br>
2712 &nbsp;&nbsp;&nbsp;&nbsp;int *port,<br>
2713 &nbsp;&nbsp;&nbsp;&nbsp;char *resource,<br>
2714 &nbsp;&nbsp;&nbsp;&nbsp;int resourcelen<br>
2715 );</p>
2716 <h4 class="parameters">Parameters</h4>
2717 <dl>
2718 <dt>decoding</dt>
2719 <dd class="description">Decoding flags</dd>
2720 <dt>uri</dt>
2721 <dd class="description">Universal Resource Identifier</dd>
2722 <dt>scheme</dt>
2723 <dd class="description">Scheme (http, https, etc.)</dd>
2724 <dt>schemelen</dt>
2725 <dd class="description">Size of scheme buffer</dd>
2726 <dt>username</dt>
2727 <dd class="description">Username</dd>
2728 <dt>usernamelen</dt>
2729 <dd class="description">Size of username buffer</dd>
2730 <dt>host</dt>
2731 <dd class="description">Hostname</dd>
2732 <dt>hostlen</dt>
2733 <dd class="description">Size of hostname buffer</dd>
2734 <dt>port</dt>
2735 <dd class="description">Port number to use</dd>
2736 <dt>resource</dt>
2737 <dd class="description">Resource/filename</dd>
2738 <dt>resourcelen</dt>
2739 <dd class="description">Size of resource buffer</dd>
2740 </dl>
2741 <h4 class="returnvalue">Return Value</h4>
2742 <p class="description">Result of separation</p>
2743 <h3 class="function"><span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span><a name="httpSetAuthString">httpSetAuthString</a></h3>
2744 <p class="description">Set the current authorization string.</p>
2745 <p class="code">
2746 void httpSetAuthString (<br>
2747 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2748 &nbsp;&nbsp;&nbsp;&nbsp;const char *scheme,<br>
2749 &nbsp;&nbsp;&nbsp;&nbsp;const char *data<br>
2750 );</p>
2751 <h4 class="parameters">Parameters</h4>
2752 <dl>
2753 <dt>http</dt>
2754 <dd class="description">Connection to server</dd>
2755 <dt>scheme</dt>
2756 <dd class="description">Auth scheme (NULL to clear it)</dd>
2757 <dt>data</dt>
2758 <dd class="description">Auth data (NULL for none)</dd>
2759 </dl>
2760 <h4 class="discussion">Discussion</h4>
2761 <p class="discussion">This function just stores a copy of the current authorization string in
2762 the HTTP connection object.  You must still call httpSetField() to set
2763 HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(),
2764 httpHead(), httpOptions(), httpPost, or httpPut().
2765
2766 </p>
2767 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="httpSetCookie">httpSetCookie</a></h3>
2768 <p class="description">Set the cookie value(s).</p>
2769 <p class="code">
2770 void httpSetCookie (<br>
2771 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2772 &nbsp;&nbsp;&nbsp;&nbsp;const char *cookie<br>
2773 );</p>
2774 <h4 class="parameters">Parameters</h4>
2775 <dl>
2776 <dt>http</dt>
2777 <dd class="description">Connection</dd>
2778 <dt>cookie</dt>
2779 <dd class="description">Cookie string</dd>
2780 </dl>
2781 <h3 class="function"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="httpSetCredentials">httpSetCredentials</a></h3>
2782 <p class="description">Set the credentials associated with an encrypted
2783 connection.</p>
2784 <p class="code">
2785 int httpSetCredentials (<br>
2786 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2787 &nbsp;&nbsp;&nbsp;&nbsp;cups_array_t *credentials<br>
2788 );</p>
2789 <h4 class="parameters">Parameters</h4>
2790 <dl>
2791 <dt>http</dt>
2792 <dd class="description">Connection to server</dd>
2793 <dt>credentials</dt>
2794 <dd class="description">Array of credentials</dd>
2795 </dl>
2796 <h4 class="returnvalue">Return Value</h4>
2797 <p class="description">Status of call (0 = success)</p>
2798 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpSetDefaultField">httpSetDefaultField</a></h3>
2799 <p class="description">Set the default value of an HTTP header.</p>
2800 <p class="code">
2801 void httpSetDefaultField (<br>
2802 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2803 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_field_t">http_field_t</a> field,<br>
2804 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
2805 );</p>
2806 <h4 class="parameters">Parameters</h4>
2807 <dl>
2808 <dt>http</dt>
2809 <dd class="description">Connection to server</dd>
2810 <dt>field</dt>
2811 <dd class="description">Field index</dd>
2812 <dt>value</dt>
2813 <dd class="description">Value</dd>
2814 </dl>
2815 <h4 class="discussion">Discussion</h4>
2816 <p class="discussion">Currently only HTTP_FIELD_ACCEPT_ENCODING, HTTP_FIELD_SERVER, and
2817 HTTP_FIELD_USER_AGENT can be set.
2818
2819 </p>
2820 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpSetExpect">httpSetExpect</a></h3>
2821 <p class="description">Set the Expect: header in a request.</p>
2822 <p class="code">
2823 void httpSetExpect (<br>
2824 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2825 &nbsp;&nbsp;&nbsp;&nbsp;http_status_t expect<br>
2826 );</p>
2827 <h4 class="parameters">Parameters</h4>
2828 <dl>
2829 <dt>http</dt>
2830 <dd class="description">Connection to server</dd>
2831 <dt>expect</dt>
2832 <dd class="description">HTTP status to expect
2833 (<code>HTTP_CONTINUE</code>)</dd>
2834 </dl>
2835 <h4 class="discussion">Discussion</h4>
2836 <p class="discussion">Currently only <code>HTTP_STATUS_CONTINUE</code> is supported for the &quot;expect&quot;
2837 argument.
2838
2839 </p>
2840 <h3 class="function"><a name="httpSetField">httpSetField</a></h3>
2841 <p class="description">Set the value of an HTTP header.</p>
2842 <p class="code">
2843 void httpSetField (<br>
2844 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2845 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_field_t">http_field_t</a> field,<br>
2846 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
2847 );</p>
2848 <h4 class="parameters">Parameters</h4>
2849 <dl>
2850 <dt>http</dt>
2851 <dd class="description">Connection to server</dd>
2852 <dt>field</dt>
2853 <dd class="description">Field index</dd>
2854 <dt>value</dt>
2855 <dd class="description">Value</dd>
2856 </dl>
2857 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpSetLength">httpSetLength</a></h3>
2858 <p class="description">Set the content-length and content-encoding.</p>
2859 <p class="code">
2860 void httpSetLength (<br>
2861 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2862 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
2863 );</p>
2864 <h4 class="parameters">Parameters</h4>
2865 <dl>
2866 <dt>http</dt>
2867 <dd class="description">Connection to server</dd>
2868 <dt>length</dt>
2869 <dd class="description">Length (0 for chunked)</dd>
2870 </dl>
2871 <h3 class="function"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="httpSetTimeout">httpSetTimeout</a></h3>
2872 <p class="description">Set read/write timeouts and an optional callback.</p>
2873 <p class="code">
2874 void httpSetTimeout (<br>
2875 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2876 &nbsp;&nbsp;&nbsp;&nbsp;double timeout,<br>
2877 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_timeout_cb_t">http_timeout_cb_t</a> cb,<br>
2878 &nbsp;&nbsp;&nbsp;&nbsp;void *user_data<br>
2879 );</p>
2880 <h4 class="parameters">Parameters</h4>
2881 <dl>
2882 <dt>http</dt>
2883 <dd class="description">Connection to server</dd>
2884 <dt>timeout</dt>
2885 <dd class="description">Number of seconds for timeout,
2886 must be greater than 0</dd>
2887 <dt>cb</dt>
2888 <dd class="description">Callback function or NULL</dd>
2889 <dt>user_data</dt>
2890 <dd class="description">User data pointer</dd>
2891 </dl>
2892 <h4 class="discussion">Discussion</h4>
2893 <p class="discussion">The optional timeout callback receives both the HTTP connection and a user
2894 data pointer and must return 1 to continue or 0 to error (time) out.
2895
2896 </p>
2897 <h3 class="function"><a name="httpStatus">httpStatus</a></h3>
2898 <p class="description">Return a short string describing a HTTP status code.</p>
2899 <p class="code">
2900 const char *httpStatus (<br>
2901 &nbsp;&nbsp;&nbsp;&nbsp;http_status_t status<br>
2902 );</p>
2903 <h4 class="parameters">Parameters</h4>
2904 <dl>
2905 <dt>status</dt>
2906 <dd class="description">HTTP status code</dd>
2907 </dl>
2908 <h4 class="returnvalue">Return Value</h4>
2909 <p class="description">Localized status string</p>
2910 <h4 class="discussion">Discussion</h4>
2911 <p class="discussion">The returned string is localized to the current POSIX locale and is based
2912 on the status strings defined in RFC 2616.</p>
2913 <h3 class="function"><a name="httpTrace">httpTrace</a></h3>
2914 <p class="description">Send an TRACE request to the server.</p>
2915 <p class="code">
2916 int httpTrace (<br>
2917 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2918 &nbsp;&nbsp;&nbsp;&nbsp;const char *uri<br>
2919 );</p>
2920 <h4 class="parameters">Parameters</h4>
2921 <dl>
2922 <dt>http</dt>
2923 <dd class="description">Connection to server</dd>
2924 <dt>uri</dt>
2925 <dd class="description">URI for trace</dd>
2926 </dl>
2927 <h4 class="returnvalue">Return Value</h4>
2928 <p class="description">Status of call (0 = success)</p>
2929 <h3 class="function"><a name="httpUpdate">httpUpdate</a></h3>
2930 <p class="description">Update the current HTTP state for incoming data.</p>
2931 <p class="code">
2932 http_status_t httpUpdate (<br>
2933 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http<br>
2934 );</p>
2935 <h4 class="parameters">Parameters</h4>
2936 <dl>
2937 <dt>http</dt>
2938 <dd class="description">Connection to server</dd>
2939 </dl>
2940 <h4 class="returnvalue">Return Value</h4>
2941 <p class="description">HTTP status</p>
2942 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="httpWait">httpWait</a></h3>
2943 <p class="description">Wait for data available on a connection.</p>
2944 <p class="code">
2945 int httpWait (<br>
2946 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2947 &nbsp;&nbsp;&nbsp;&nbsp;int msec<br>
2948 );</p>
2949 <h4 class="parameters">Parameters</h4>
2950 <dl>
2951 <dt>http</dt>
2952 <dd class="description">Connection to server</dd>
2953 <dt>msec</dt>
2954 <dd class="description">Milliseconds to wait</dd>
2955 </dl>
2956 <h4 class="returnvalue">Return Value</h4>
2957 <p class="description">1 if data is available, 0 otherwise</p>
2958 <h3 class="function"><span class="info">&nbsp;DEPRECATED&nbsp;</span><a name="httpWrite">httpWrite</a></h3>
2959 <p class="description">Write data to a HTTP connection.</p>
2960 <p class="code">
2961 int httpWrite (<br>
2962 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2963 &nbsp;&nbsp;&nbsp;&nbsp;const char *buffer,<br>
2964 &nbsp;&nbsp;&nbsp;&nbsp;int length<br>
2965 );</p>
2966 <h4 class="parameters">Parameters</h4>
2967 <dl>
2968 <dt>http</dt>
2969 <dd class="description">Connection to server</dd>
2970 <dt>buffer</dt>
2971 <dd class="description">Buffer for data</dd>
2972 <dt>length</dt>
2973 <dd class="description">Number of bytes to write</dd>
2974 </dl>
2975 <h4 class="returnvalue">Return Value</h4>
2976 <p class="description">Number of bytes written</p>
2977 <h4 class="discussion">Discussion</h4>
2978 <p class="discussion">This function is deprecated. Use the httpWrite2() function which can
2979 write more than 2GB of data.
2980
2981 </p>
2982 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="httpWrite2">httpWrite2</a></h3>
2983 <p class="description">Write data to a HTTP connection.</p>
2984 <p class="code">
2985 ssize_t httpWrite2 (<br>
2986 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
2987 &nbsp;&nbsp;&nbsp;&nbsp;const char *buffer,<br>
2988 &nbsp;&nbsp;&nbsp;&nbsp;size_t length<br>
2989 );</p>
2990 <h4 class="parameters">Parameters</h4>
2991 <dl>
2992 <dt>http</dt>
2993 <dd class="description">Connection to server</dd>
2994 <dt>buffer</dt>
2995 <dd class="description">Buffer for data</dd>
2996 <dt>length</dt>
2997 <dd class="description">Number of bytes to write</dd>
2998 </dl>
2999 <h4 class="returnvalue">Return Value</h4>
3000 <p class="description">Number of bytes written</p>
3001 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="httpWriteResponse">httpWriteResponse</a></h3>
3002 <p class="description">Write a HTTP response to a client connection.</p>
3003 <p class="code">
3004 int httpWriteResponse (<br>
3005 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
3006 &nbsp;&nbsp;&nbsp;&nbsp;http_status_t status<br>
3007 );</p>
3008 <h4 class="parameters">Parameters</h4>
3009 <dl>
3010 <dt>http</dt>
3011 <dd class="description">HTTP connection</dd>
3012 <dt>status</dt>
3013 <dd class="description">Status code</dd>
3014 </dl>
3015 <h4 class="returnvalue">Return Value</h4>
3016 <p class="description">0 on success, -1 on error</p>
3017 <h3 class="function"><a name="ippAddBoolean">ippAddBoolean</a></h3>
3018 <p class="description">Add a boolean attribute to an IPP message.</p>
3019 <p class="code">
3020 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean (<br>
3021 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3022 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3023 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3024 &nbsp;&nbsp;&nbsp;&nbsp;char value<br>
3025 );</p>
3026 <h4 class="parameters">Parameters</h4>
3027 <dl>
3028 <dt>ipp</dt>
3029 <dd class="description">IPP message</dd>
3030 <dt>group</dt>
3031 <dd class="description">IPP group</dd>
3032 <dt>name</dt>
3033 <dd class="description">Name of attribute</dd>
3034 <dt>value</dt>
3035 <dd class="description">Value of attribute</dd>
3036 </dl>
3037 <h4 class="returnvalue">Return Value</h4>
3038 <p class="description">New attribute</p>
3039 <h4 class="discussion">Discussion</h4>
3040 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3041 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3042 <br>
3043 The <code>group</code> parameter specifies the IPP attribute group tag: none
3044 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3045 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3046 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3047 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3048 <h3 class="function"><a name="ippAddBooleans">ippAddBooleans</a></h3>
3049 <p class="description">Add an array of boolean values.</p>
3050 <p class="code">
3051 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans (<br>
3052 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3053 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3054 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3055 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3056 &nbsp;&nbsp;&nbsp;&nbsp;const char *values<br>
3057 );</p>
3058 <h4 class="parameters">Parameters</h4>
3059 <dl>
3060 <dt>ipp</dt>
3061 <dd class="description">IPP message</dd>
3062 <dt>group</dt>
3063 <dd class="description">IPP group</dd>
3064 <dt>name</dt>
3065 <dd class="description">Name of attribute</dd>
3066 <dt>num_values</dt>
3067 <dd class="description">Number of values</dd>
3068 <dt>values</dt>
3069 <dd class="description">Values</dd>
3070 </dl>
3071 <h4 class="returnvalue">Return Value</h4>
3072 <p class="description">New attribute</p>
3073 <h4 class="discussion">Discussion</h4>
3074 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3075 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3076 <br>
3077 The <code>group</code> parameter specifies the IPP attribute group tag: none
3078 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3079 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3080 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3081 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3082 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="ippAddCollection">ippAddCollection</a></h3>
3083 <p class="description">Add a collection value.</p>
3084 <p class="code">
3085 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection (<br>
3086 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3087 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3088 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3089 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *value<br>
3090 );</p>
3091 <h4 class="parameters">Parameters</h4>
3092 <dl>
3093 <dt>ipp</dt>
3094 <dd class="description">IPP message</dd>
3095 <dt>group</dt>
3096 <dd class="description">IPP group</dd>
3097 <dt>name</dt>
3098 <dd class="description">Name of attribute</dd>
3099 <dt>value</dt>
3100 <dd class="description">Value</dd>
3101 </dl>
3102 <h4 class="returnvalue">Return Value</h4>
3103 <p class="description">New attribute</p>
3104 <h4 class="discussion">Discussion</h4>
3105 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3106 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3107 <br>
3108 The <code>group</code> parameter specifies the IPP attribute group tag: none
3109 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3110 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3111 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3112 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
3113
3114 </p>
3115 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="ippAddCollections">ippAddCollections</a></h3>
3116 <p class="description">Add an array of collection values.</p>
3117 <p class="code">
3118 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections (<br>
3119 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3120 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3121 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3122 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3123 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#ipp_t">ipp_t</a> **values<br>
3124 );</p>
3125 <h4 class="parameters">Parameters</h4>
3126 <dl>
3127 <dt>ipp</dt>
3128 <dd class="description">IPP message</dd>
3129 <dt>group</dt>
3130 <dd class="description">IPP group</dd>
3131 <dt>name</dt>
3132 <dd class="description">Name of attribute</dd>
3133 <dt>num_values</dt>
3134 <dd class="description">Number of values</dd>
3135 <dt>values</dt>
3136 <dd class="description">Values</dd>
3137 </dl>
3138 <h4 class="returnvalue">Return Value</h4>
3139 <p class="description">New attribute</p>
3140 <h4 class="discussion">Discussion</h4>
3141 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3142 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3143 <br>
3144 The <code>group</code> parameter specifies the IPP attribute group tag: none
3145 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3146 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3147 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3148 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
3149
3150 </p>
3151 <h3 class="function"><a name="ippAddDate">ippAddDate</a></h3>
3152 <p class="description">Add a date attribute to an IPP message.</p>
3153 <p class="code">
3154 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate (<br>
3155 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3156 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3157 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3158 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#ipp_uchar_t">ipp_uchar_t</a> *value<br>
3159 );</p>
3160 <h4 class="parameters">Parameters</h4>
3161 <dl>
3162 <dt>ipp</dt>
3163 <dd class="description">IPP message</dd>
3164 <dt>group</dt>
3165 <dd class="description">IPP group</dd>
3166 <dt>name</dt>
3167 <dd class="description">Name of attribute</dd>
3168 <dt>value</dt>
3169 <dd class="description">Value</dd>
3170 </dl>
3171 <h4 class="returnvalue">Return Value</h4>
3172 <p class="description">New attribute</p>
3173 <h4 class="discussion">Discussion</h4>
3174 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3175 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3176 <br>
3177 The <code>group</code> parameter specifies the IPP attribute group tag: none
3178 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3179 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3180 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3181 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3182 <h3 class="function"><a name="ippAddInteger">ippAddInteger</a></h3>
3183 <p class="description">Add a integer attribute to an IPP message.</p>
3184 <p class="code">
3185 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger (<br>
3186 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3187 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3188 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3189 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3190 &nbsp;&nbsp;&nbsp;&nbsp;int value<br>
3191 );</p>
3192 <h4 class="parameters">Parameters</h4>
3193 <dl>
3194 <dt>ipp</dt>
3195 <dd class="description">IPP message</dd>
3196 <dt>group</dt>
3197 <dd class="description">IPP group</dd>
3198 <dt>value_tag</dt>
3199 <dd class="description">Type of attribute</dd>
3200 <dt>name</dt>
3201 <dd class="description">Name of attribute</dd>
3202 <dt>value</dt>
3203 <dd class="description">Value of attribute</dd>
3204 </dl>
3205 <h4 class="returnvalue">Return Value</h4>
3206 <p class="description">New attribute</p>
3207 <h4 class="discussion">Discussion</h4>
3208 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3209 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3210 <br>
3211 The <code>group</code> parameter specifies the IPP attribute group tag: none
3212 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3213 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3214 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3215 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3216 <br>
3217 Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer
3218 (<code>IPP_TAG_INTEGER</code>).</p>
3219 <h3 class="function"><a name="ippAddIntegers">ippAddIntegers</a></h3>
3220 <p class="description">Add an array of integer values.</p>
3221 <p class="code">
3222 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers (<br>
3223 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3224 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3225 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3226 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3227 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3228 &nbsp;&nbsp;&nbsp;&nbsp;const int *values<br>
3229 );</p>
3230 <h4 class="parameters">Parameters</h4>
3231 <dl>
3232 <dt>ipp</dt>
3233 <dd class="description">IPP message</dd>
3234 <dt>group</dt>
3235 <dd class="description">IPP group</dd>
3236 <dt>value_tag</dt>
3237 <dd class="description">Type of attribute</dd>
3238 <dt>name</dt>
3239 <dd class="description">Name of attribute</dd>
3240 <dt>num_values</dt>
3241 <dd class="description">Number of values</dd>
3242 <dt>values</dt>
3243 <dd class="description">Values</dd>
3244 </dl>
3245 <h4 class="returnvalue">Return Value</h4>
3246 <p class="description">New attribute</p>
3247 <h4 class="discussion">Discussion</h4>
3248 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3249 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3250 <br>
3251 The <code>group</code> parameter specifies the IPP attribute group tag: none
3252 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3253 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3254 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3255 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3256 <br>
3257 Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer
3258 (<code>IPP_TAG_INTEGER</code>).</p>
3259 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippAddOctetString">ippAddOctetString</a></h3>
3260 <p class="description">Add an octetString value to an IPP message.</p>
3261 <p class="code">
3262 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString (<br>
3263 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3264 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3265 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3266 &nbsp;&nbsp;&nbsp;&nbsp;const void *data,<br>
3267 &nbsp;&nbsp;&nbsp;&nbsp;int datalen<br>
3268 );</p>
3269 <h4 class="parameters">Parameters</h4>
3270 <dl>
3271 <dt>ipp</dt>
3272 <dd class="description">IPP message</dd>
3273 <dt>group</dt>
3274 <dd class="description">IPP group</dd>
3275 <dt>name</dt>
3276 <dd class="description">Name of attribute</dd>
3277 <dt>data</dt>
3278 <dd class="description">octetString data</dd>
3279 <dt>datalen</dt>
3280 <dd class="description">Length of data in bytes</dd>
3281 </dl>
3282 <h4 class="returnvalue">Return Value</h4>
3283 <p class="description">New attribute</p>
3284 <h4 class="discussion">Discussion</h4>
3285 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3286 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3287 <br>
3288 The <code>group</code> parameter specifies the IPP attribute group tag: none
3289 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3290 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3291 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3292 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
3293
3294 </p>
3295 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippAddOutOfBand">ippAddOutOfBand</a></h3>
3296 <p class="description">Add an out-of-band value to an IPP message.</p>
3297 <p class="code">
3298 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOutOfBand (<br>
3299 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3300 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3301 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3302 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
3303 );</p>
3304 <h4 class="parameters">Parameters</h4>
3305 <dl>
3306 <dt>ipp</dt>
3307 <dd class="description">IPP message</dd>
3308 <dt>group</dt>
3309 <dd class="description">IPP group</dd>
3310 <dt>value_tag</dt>
3311 <dd class="description">Type of attribute</dd>
3312 <dt>name</dt>
3313 <dd class="description">Name of attribute</dd>
3314 </dl>
3315 <h4 class="returnvalue">Return Value</h4>
3316 <p class="description">New attribute</p>
3317 <h4 class="discussion">Discussion</h4>
3318 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3319 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3320 <br>
3321 The <code>group</code> parameter specifies the IPP attribute group tag: none
3322 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3323 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3324 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3325 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3326 <br>
3327 Supported out-of-band values include unsupported-value
3328 (<code>IPP_TAG_UNSUPPORTED_VALUE</code>), default (<code>IPP_TAG_DEFAULT</code>), unknown
3329 (<code>IPP_TAG_UNKNOWN</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable
3330 (<code>IPP_TAG_NOTSETTABLE</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), and
3331 admin-define (<code>IPP_TAG_ADMINDEFINE</code>).
3332
3333 </p>
3334 <h3 class="function"><a name="ippAddRange">ippAddRange</a></h3>
3335 <p class="description">Add a range of values to an IPP message.</p>
3336 <p class="code">
3337 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange (<br>
3338 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3339 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3340 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3341 &nbsp;&nbsp;&nbsp;&nbsp;int lower,<br>
3342 &nbsp;&nbsp;&nbsp;&nbsp;int upper<br>
3343 );</p>
3344 <h4 class="parameters">Parameters</h4>
3345 <dl>
3346 <dt>ipp</dt>
3347 <dd class="description">IPP message</dd>
3348 <dt>group</dt>
3349 <dd class="description">IPP group</dd>
3350 <dt>name</dt>
3351 <dd class="description">Name of attribute</dd>
3352 <dt>lower</dt>
3353 <dd class="description">Lower value</dd>
3354 <dt>upper</dt>
3355 <dd class="description">Upper value</dd>
3356 </dl>
3357 <h4 class="returnvalue">Return Value</h4>
3358 <p class="description">New attribute</p>
3359 <h4 class="discussion">Discussion</h4>
3360 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3361 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3362 <br>
3363 The <code>group</code> parameter specifies the IPP attribute group tag: none
3364 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3365 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3366 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3367 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3368 <br>
3369 The <code>lower</code> parameter must be less than or equal to the <code>upper</code> parameter.</p>
3370 <h3 class="function"><a name="ippAddRanges">ippAddRanges</a></h3>
3371 <p class="description">Add ranges of values to an IPP message.</p>
3372 <p class="code">
3373 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges (<br>
3374 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3375 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3376 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3377 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3378 &nbsp;&nbsp;&nbsp;&nbsp;const int *lower,<br>
3379 &nbsp;&nbsp;&nbsp;&nbsp;const int *upper<br>
3380 );</p>
3381 <h4 class="parameters">Parameters</h4>
3382 <dl>
3383 <dt>ipp</dt>
3384 <dd class="description">IPP message</dd>
3385 <dt>group</dt>
3386 <dd class="description">IPP group</dd>
3387 <dt>name</dt>
3388 <dd class="description">Name of attribute</dd>
3389 <dt>num_values</dt>
3390 <dd class="description">Number of values</dd>
3391 <dt>lower</dt>
3392 <dd class="description">Lower values</dd>
3393 <dt>upper</dt>
3394 <dd class="description">Upper values</dd>
3395 </dl>
3396 <h4 class="returnvalue">Return Value</h4>
3397 <p class="description">New attribute</p>
3398 <h4 class="discussion">Discussion</h4>
3399 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3400 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3401 <br>
3402 The <code>group</code> parameter specifies the IPP attribute group tag: none
3403 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3404 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3405 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3406 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3407 <h3 class="function"><a name="ippAddResolution">ippAddResolution</a></h3>
3408 <p class="description">Add a resolution value to an IPP message.</p>
3409 <p class="code">
3410 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution (<br>
3411 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3412 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3413 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3414 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_res_t">ipp_res_t</a> units,<br>
3415 &nbsp;&nbsp;&nbsp;&nbsp;int xres,<br>
3416 &nbsp;&nbsp;&nbsp;&nbsp;int yres<br>
3417 );</p>
3418 <h4 class="parameters">Parameters</h4>
3419 <dl>
3420 <dt>ipp</dt>
3421 <dd class="description">IPP message</dd>
3422 <dt>group</dt>
3423 <dd class="description">IPP group</dd>
3424 <dt>name</dt>
3425 <dd class="description">Name of attribute</dd>
3426 <dt>units</dt>
3427 <dd class="description">Units for resolution</dd>
3428 <dt>xres</dt>
3429 <dd class="description">X resolution</dd>
3430 <dt>yres</dt>
3431 <dd class="description">Y resolution</dd>
3432 </dl>
3433 <h4 class="returnvalue">Return Value</h4>
3434 <p class="description">New attribute</p>
3435 <h4 class="discussion">Discussion</h4>
3436 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3437 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3438 <br>
3439 The <code>group</code> parameter specifies the IPP attribute group tag: none
3440 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3441 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3442 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3443 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3444 <h3 class="function"><a name="ippAddResolutions">ippAddResolutions</a></h3>
3445 <p class="description">Add resolution values to an IPP message.</p>
3446 <p class="code">
3447 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions (<br>
3448 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3449 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3450 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3451 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3452 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_res_t">ipp_res_t</a> units,<br>
3453 &nbsp;&nbsp;&nbsp;&nbsp;const int *xres,<br>
3454 &nbsp;&nbsp;&nbsp;&nbsp;const int *yres<br>
3455 );</p>
3456 <h4 class="parameters">Parameters</h4>
3457 <dl>
3458 <dt>ipp</dt>
3459 <dd class="description">IPP message</dd>
3460 <dt>group</dt>
3461 <dd class="description">IPP group</dd>
3462 <dt>name</dt>
3463 <dd class="description">Name of attribute</dd>
3464 <dt>num_values</dt>
3465 <dd class="description">Number of values</dd>
3466 <dt>units</dt>
3467 <dd class="description">Units for resolution</dd>
3468 <dt>xres</dt>
3469 <dd class="description">X resolutions</dd>
3470 <dt>yres</dt>
3471 <dd class="description">Y resolutions</dd>
3472 </dl>
3473 <h4 class="returnvalue">Return Value</h4>
3474 <p class="description">New attribute</p>
3475 <h4 class="discussion">Discussion</h4>
3476 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3477 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3478 <br>
3479 The <code>group</code> parameter specifies the IPP attribute group tag: none
3480 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3481 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3482 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3483 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
3484 <h3 class="function"><a name="ippAddSeparator">ippAddSeparator</a></h3>
3485 <p class="description">Add a group separator to an IPP message.</p>
3486 <p class="code">
3487 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddSeparator (<br>
3488 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
3489 );</p>
3490 <h4 class="parameters">Parameters</h4>
3491 <dl>
3492 <dt>ipp</dt>
3493 <dd class="description">IPP message</dd>
3494 </dl>
3495 <h4 class="returnvalue">Return Value</h4>
3496 <p class="description">New attribute</p>
3497 <h4 class="discussion">Discussion</h4>
3498 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3499 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.</p>
3500 <h3 class="function"><a name="ippAddString">ippAddString</a></h3>
3501 <p class="description">Add a language-encoded string to an IPP message.</p>
3502 <p class="code">
3503 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString (<br>
3504 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3505 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3506 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3507 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3508 &nbsp;&nbsp;&nbsp;&nbsp;const char *language,<br>
3509 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
3510 );</p>
3511 <h4 class="parameters">Parameters</h4>
3512 <dl>
3513 <dt>ipp</dt>
3514 <dd class="description">IPP message</dd>
3515 <dt>group</dt>
3516 <dd class="description">IPP group</dd>
3517 <dt>value_tag</dt>
3518 <dd class="description">Type of attribute</dd>
3519 <dt>name</dt>
3520 <dd class="description">Name of attribute</dd>
3521 <dt>language</dt>
3522 <dd class="description">Language code</dd>
3523 <dt>value</dt>
3524 <dd class="description">Value</dd>
3525 </dl>
3526 <h4 class="returnvalue">Return Value</h4>
3527 <p class="description">New attribute</p>
3528 <h4 class="discussion">Discussion</h4>
3529 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3530 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3531 <br>
3532 The <code>group</code> parameter specifies the IPP attribute group tag: none
3533 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3534 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3535 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3536 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3537 <br>
3538 Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
3539 (<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
3540 (<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
3541 (<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage
3542 (<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme
3543 (<code>IPP_TAG_URISCHEME</code>).<br>
3544 <br>
3545 The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and
3546 textWithLanguage string values and must be <code>NULL</code> for all other string values.</p>
3547 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippAddStringf">ippAddStringf</a></h3>
3548 <p class="description">Add a formatted string to an IPP message.</p>
3549 <p class="code">
3550 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringf (<br>
3551 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3552 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3553 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3554 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3555 &nbsp;&nbsp;&nbsp;&nbsp;const char *language,<br>
3556 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
3557 &nbsp;&nbsp;&nbsp;&nbsp;...<br>
3558 );</p>
3559 <h4 class="parameters">Parameters</h4>
3560 <dl>
3561 <dt>ipp</dt>
3562 <dd class="description">IPP message</dd>
3563 <dt>group</dt>
3564 <dd class="description">IPP group</dd>
3565 <dt>value_tag</dt>
3566 <dd class="description">Type of attribute</dd>
3567 <dt>name</dt>
3568 <dd class="description">Name of attribute</dd>
3569 <dt>language</dt>
3570 <dd class="description">Language code (<code>NULL</code> for default)</dd>
3571 <dt>format</dt>
3572 <dd class="description">Printf-style format string</dd>
3573 <dt>...</dt>
3574 <dd class="description">Additional arguments as needed</dd>
3575 </dl>
3576 <h4 class="returnvalue">Return Value</h4>
3577 <p class="description">New attribute</p>
3578 <h4 class="discussion">Discussion</h4>
3579 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3580 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3581 <br>
3582 The <code>group</code> parameter specifies the IPP attribute group tag: none
3583 (<code>IPP_TAG_ZERO</code>, for member attributes), document
3584 (<code>IPP_TAG_DOCUMENT</code>), event notification
3585 (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
3586 printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>),
3587 or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3588 <br>
3589 Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
3590 (<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
3591 (<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
3592 (<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage
3593 (<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme
3594 (<code>IPP_TAG_URISCHEME</code>).<br>
3595 <br>
3596 The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage
3597 and textWithLanguage string values and must be <code>NULL</code> for all other
3598 string values.<br>
3599 <br>
3600 The <code>format</code> parameter uses formatting characters compatible with the
3601 printf family of standard functions.  Additional arguments follow it as
3602 needed.  The formatted string is truncated as needed to the maximum length of
3603 the corresponding value type.
3604
3605 </p>
3606 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippAddStringfv">ippAddStringfv</a></h3>
3607 <p class="description">Add a formatted string to an IPP message.</p>
3608 <p class="code">
3609 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringfv (<br>
3610 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3611 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3612 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3613 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3614 &nbsp;&nbsp;&nbsp;&nbsp;const char *language,<br>
3615 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
3616 &nbsp;&nbsp;&nbsp;&nbsp;va_list ap<br>
3617 );</p>
3618 <h4 class="parameters">Parameters</h4>
3619 <dl>
3620 <dt>ipp</dt>
3621 <dd class="description">IPP message</dd>
3622 <dt>group</dt>
3623 <dd class="description">IPP group</dd>
3624 <dt>value_tag</dt>
3625 <dd class="description">Type of attribute</dd>
3626 <dt>name</dt>
3627 <dd class="description">Name of attribute</dd>
3628 <dt>language</dt>
3629 <dd class="description">Language code (<code>NULL</code> for default)</dd>
3630 <dt>format</dt>
3631 <dd class="description">Printf-style format string</dd>
3632 <dt>ap</dt>
3633 <dd class="description">Additional arguments</dd>
3634 </dl>
3635 <h4 class="returnvalue">Return Value</h4>
3636 <p class="description">New attribute</p>
3637 <h4 class="discussion">Discussion</h4>
3638 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3639 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3640 <br>
3641 The <code>group</code> parameter specifies the IPP attribute group tag: none
3642 (<code>IPP_TAG_ZERO</code>, for member attributes), document
3643 (<code>IPP_TAG_DOCUMENT</code>), event notification
3644 (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
3645 printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>),
3646 or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3647 <br>
3648 Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
3649 (<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
3650 (<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
3651 (<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage
3652 (<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme
3653 (<code>IPP_TAG_URISCHEME</code>).<br>
3654 <br>
3655 The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage
3656 and textWithLanguage string values and must be <code>NULL</code> for all other
3657 string values.<br>
3658 <br>
3659 The <code>format</code> parameter uses formatting characters compatible with the
3660 printf family of standard functions.  Additional arguments are passed in the
3661 stdarg pointer <code>ap</code>.  The formatted string is truncated as needed to the
3662 maximum length of the corresponding value type.
3663
3664 </p>
3665 <h3 class="function"><a name="ippAddStrings">ippAddStrings</a></h3>
3666 <p class="description">Add language-encoded strings to an IPP message.</p>
3667 <p class="code">
3668 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings (<br>
3669 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3670 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group,<br>
3671 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag,<br>
3672 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
3673 &nbsp;&nbsp;&nbsp;&nbsp;int num_values,<br>
3674 &nbsp;&nbsp;&nbsp;&nbsp;const char *language,<br>
3675 &nbsp;&nbsp;&nbsp;&nbsp;const char *const *values<br>
3676 );</p>
3677 <h4 class="parameters">Parameters</h4>
3678 <dl>
3679 <dt>ipp</dt>
3680 <dd class="description">IPP message</dd>
3681 <dt>group</dt>
3682 <dd class="description">IPP group</dd>
3683 <dt>value_tag</dt>
3684 <dd class="description">Type of attribute</dd>
3685 <dt>name</dt>
3686 <dd class="description">Name of attribute</dd>
3687 <dt>num_values</dt>
3688 <dd class="description">Number of values</dd>
3689 <dt>language</dt>
3690 <dd class="description">Language code (<code>NULL</code> for default)</dd>
3691 <dt>values</dt>
3692 <dd class="description">Values</dd>
3693 </dl>
3694 <h4 class="returnvalue">Return Value</h4>
3695 <p class="description">New attribute</p>
3696 <h4 class="discussion">Discussion</h4>
3697 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
3698 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
3699 <br>
3700 The <code>group</code> parameter specifies the IPP attribute group tag: none
3701 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
3702 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
3703 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
3704 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
3705 <br>
3706 Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
3707 (<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
3708 (<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
3709 (<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage
3710 (<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme
3711 (<code>IPP_TAG_URISCHEME</code>).<br>
3712 <br>
3713 The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and
3714 textWithLanguage string values and must be <code>NULL</code> for all other string values.</p>
3715 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippAttributeString">ippAttributeString</a></h3>
3716 <p class="description">Convert the attribute's value to a string.</p>
3717 <p class="code">
3718 size_t ippAttributeString (<br>
3719 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
3720 &nbsp;&nbsp;&nbsp;&nbsp;char *buffer,<br>
3721 &nbsp;&nbsp;&nbsp;&nbsp;size_t bufsize<br>
3722 );</p>
3723 <h4 class="parameters">Parameters</h4>
3724 <dl>
3725 <dt>attr</dt>
3726 <dd class="description">Attribute</dd>
3727 <dt>buffer</dt>
3728 <dd class="description">String buffer or NULL</dd>
3729 <dt>bufsize</dt>
3730 <dd class="description">Size of string buffer</dd>
3731 </dl>
3732 <h4 class="returnvalue">Return Value</h4>
3733 <p class="description">Number of bytes less nul</p>
3734 <h4 class="discussion">Discussion</h4>
3735 <p class="discussion">Returns the number of bytes that would be written, not including the
3736 trailing nul. The buffer pointer can be NULL to get the required length,
3737 just like (v)snprintf.
3738
3739 </p>
3740 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippContainsInteger">ippContainsInteger</a></h3>
3741 <p class="description">Determine whether an attribute contains the
3742 specified value or is within the list of ranges.</p>
3743 <p class="code">
3744 int ippContainsInteger (<br>
3745 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
3746 &nbsp;&nbsp;&nbsp;&nbsp;int value<br>
3747 );</p>
3748 <h4 class="parameters">Parameters</h4>
3749 <dl>
3750 <dt>attr</dt>
3751 <dd class="description">Attribute</dd>
3752 <dt>value</dt>
3753 <dd class="description">Integer/enum value</dd>
3754 </dl>
3755 <h4 class="returnvalue">Return Value</h4>
3756 <p class="description">1 on a match, 0 on no match</p>
3757 <h4 class="discussion">Discussion</h4>
3758 <p class="discussion">Returns non-zero when the attribute contains either a matching integer or
3759 enum value, or the value falls within one of the rangeOfInteger values for
3760 the attribute.
3761
3762 </p>
3763 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippContainsString">ippContainsString</a></h3>
3764 <p class="description">Determine whether an attribute contains the
3765 specified string value.</p>
3766 <p class="code">
3767 int ippContainsString (<br>
3768 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
3769 &nbsp;&nbsp;&nbsp;&nbsp;const char *value<br>
3770 );</p>
3771 <h4 class="parameters">Parameters</h4>
3772 <dl>
3773 <dt>attr</dt>
3774 <dd class="description">Attribute</dd>
3775 <dt>value</dt>
3776 <dd class="description">String value</dd>
3777 </dl>
3778 <h4 class="returnvalue">Return Value</h4>
3779 <p class="description">1 on a match, 0 on no match</p>
3780 <h4 class="discussion">Discussion</h4>
3781 <p class="discussion">Returns non-zero when the attribute contains a matching charset, keyword,
3782 language, mimeMediaType, name, text, URI, or URI scheme value.
3783
3784 </p>
3785 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippCopyAttribute">ippCopyAttribute</a></h3>
3786 <p class="description">Copy an attribute.</p>
3787 <p class="code">
3788 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippCopyAttribute (<br>
3789 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *dst,<br>
3790 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *srcattr,<br>
3791 &nbsp;&nbsp;&nbsp;&nbsp;int quickcopy<br>
3792 );</p>
3793 <h4 class="parameters">Parameters</h4>
3794 <dl>
3795 <dt>dst</dt>
3796 <dd class="description">Destination IPP message</dd>
3797 <dt>srcattr</dt>
3798 <dd class="description">Attribute to copy</dd>
3799 <dt>quickcopy</dt>
3800 <dd class="description">1 for a referenced copy, 0 for normal</dd>
3801 </dl>
3802 <h4 class="returnvalue">Return Value</h4>
3803 <p class="description">New attribute</p>
3804 <h4 class="discussion">Discussion</h4>
3805 <p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message.
3806 When <code>quickcopy</code> is non-zero, a &quot;shallow&quot; reference copy of the attribute is
3807 created - this should only be done as long as the original source IPP message will
3808 not be freed for the life of the destination.
3809
3810 </p>
3811 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippCopyAttributes">ippCopyAttributes</a></h3>
3812 <p class="description">Copy attributes from one IPP message to another.</p>
3813 <p class="code">
3814 int ippCopyAttributes (<br>
3815 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *dst,<br>
3816 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *src,<br>
3817 &nbsp;&nbsp;&nbsp;&nbsp;int quickcopy,<br>
3818 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_copycb_t">ipp_copycb_t</a> cb,<br>
3819 &nbsp;&nbsp;&nbsp;&nbsp;void *context<br>
3820 );</p>
3821 <h4 class="parameters">Parameters</h4>
3822 <dl>
3823 <dt>dst</dt>
3824 <dd class="description">Destination IPP message</dd>
3825 <dt>src</dt>
3826 <dd class="description">Source IPP message</dd>
3827 <dt>quickcopy</dt>
3828 <dd class="description">1 for a referenced copy, 0 for normal</dd>
3829 <dt>cb</dt>
3830 <dd class="description">Copy callback or <code>NULL</code> for none</dd>
3831 <dt>context</dt>
3832 <dd class="description">Context pointer</dd>
3833 </dl>
3834 <h4 class="returnvalue">Return Value</h4>
3835 <p class="description">1 on success, 0 on error</p>
3836 <h4 class="discussion">Discussion</h4>
3837 <p class="discussion">Zero or more attributes are copied from the source IPP message, @code@ src, to the
3838 destination IPP message, <code>dst</code>. When <code>quickcopy</code> is non-zero, a &quot;shallow&quot;
3839 reference copy of the attribute is created - this should only be done as long as the
3840 original source IPP message will not be freed for the life of the destination.<br>
3841 <br>
3842 The <code>cb</code> and <code>context</code> parameters provide a generic way to &quot;filter&quot; the
3843 attributes that are copied - the function must return 1 to copy the attribute or
3844 0 to skip it. The function may also choose to do a partial copy of the source attribute
3845 itself.
3846
3847 </p>
3848 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippCreateRequestedArray">ippCreateRequestedArray</a></h3>
3849 <p class="description">Create a CUPS array of attribute names from the
3850 given requested-attributes attribute.</p>
3851 <p class="code">
3852 cups_array_t *ippCreateRequestedArray (<br>
3853 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request<br>
3854 );</p>
3855 <h4 class="parameters">Parameters</h4>
3856 <dl>
3857 <dt>request</dt>
3858 <dd class="description">IPP request</dd>
3859 </dl>
3860 <h4 class="returnvalue">Return Value</h4>
3861 <p class="description">CUPS array or <code>NULL</code> if all</p>
3862 <h4 class="discussion">Discussion</h4>
3863 <p class="discussion">This function creates a (sorted) CUPS array of attribute names matching the
3864 list of &quot;requested-attribute&quot; values supplied in an IPP request.  All IANA-
3865 registered values are supported in addition to the CUPS IPP extension
3866 attributes.<br>
3867 <br>
3868 The <code>request</code> parameter specifies the request message that was read from
3869 the client.
3870
3871 <code>NULL</code> is returned if all attributes should be returned.  Otherwise, the
3872 result is a sorted array of attribute names, where <code>cupsArrayFind(array,
3873 "attribute-name")</code> will return a non-NULL pointer.  The array must be freed
3874 using the <code>cupsArrayDelete</code> function.
3875
3876 </p>
3877 <h3 class="function"><a name="ippDateToTime">ippDateToTime</a></h3>
3878 <p class="description">Convert from RFC 1903 Date/Time format to UNIX time
3879 in seconds.</p>
3880 <p class="code">
3881 time_t ippDateToTime (<br>
3882 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#ipp_uchar_t">ipp_uchar_t</a> *date<br>
3883 );</p>
3884 <h4 class="parameters">Parameters</h4>
3885 <dl>
3886 <dt>date</dt>
3887 <dd class="description">RFC 1903 date info</dd>
3888 </dl>
3889 <h4 class="returnvalue">Return Value</h4>
3890 <p class="description">UNIX time value</p>
3891 <h3 class="function"><a name="ippDelete">ippDelete</a></h3>
3892 <p class="description">Delete an IPP message.</p>
3893 <p class="code">
3894 void ippDelete (<br>
3895 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
3896 );</p>
3897 <h4 class="parameters">Parameters</h4>
3898 <dl>
3899 <dt>ipp</dt>
3900 <dd class="description">IPP message</dd>
3901 </dl>
3902 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="ippDeleteAttribute">ippDeleteAttribute</a></h3>
3903 <p class="description">Delete a single attribute in an IPP message.</p>
3904 <p class="code">
3905 void ippDeleteAttribute (<br>
3906 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3907 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
3908 );</p>
3909 <h4 class="parameters">Parameters</h4>
3910 <dl>
3911 <dt>ipp</dt>
3912 <dd class="description">IPP message</dd>
3913 <dt>attr</dt>
3914 <dd class="description">Attribute to delete</dd>
3915 </dl>
3916 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippDeleteValues">ippDeleteValues</a></h3>
3917 <p class="description">Delete values in an attribute.</p>
3918 <p class="code">
3919 int ippDeleteValues (<br>
3920 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
3921 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
3922 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
3923 &nbsp;&nbsp;&nbsp;&nbsp;int count<br>
3924 );</p>
3925 <h4 class="parameters">Parameters</h4>
3926 <dl>
3927 <dt>ipp</dt>
3928 <dd class="description">IPP message</dd>
3929 <dt>attr</dt>
3930 <dd class="description">Attribute</dd>
3931 <dt>element</dt>
3932 <dd class="description">Index of first value to delete (0-based)</dd>
3933 <dt>count</dt>
3934 <dd class="description">Number of values to delete</dd>
3935 </dl>
3936 <h4 class="returnvalue">Return Value</h4>
3937 <p class="description">1 on success, 0 on failure</p>
3938 <h4 class="discussion">Discussion</h4>
3939 <p class="discussion">The <code>element</code> parameter specifies the first value to delete, starting at
3940 0. It must be less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br>
3941 <br>
3942 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
3943 <br>
3944 Deleting all values in an attribute deletes the attribute.
3945
3946 </p>
3947 <h3 class="function"><a name="ippEnumString">ippEnumString</a></h3>
3948 <p class="description">Return a string corresponding to the enum value.</p>
3949 <p class="code">
3950 const char *ippEnumString (<br>
3951 &nbsp;&nbsp;&nbsp;&nbsp;const char *attrname,<br>
3952 &nbsp;&nbsp;&nbsp;&nbsp;int enumvalue<br>
3953 );</p>
3954 <h4 class="parameters">Parameters</h4>
3955 <dl>
3956 <dt>attrname</dt>
3957 <dd class="description">Attribute name</dd>
3958 <dt>enumvalue</dt>
3959 <dd class="description">Enum value</dd>
3960 </dl>
3961 <h4 class="returnvalue">Return Value</h4>
3962 <p class="description">Enum string</p>
3963 <h3 class="function"><a name="ippEnumValue">ippEnumValue</a></h3>
3964 <p class="description">Return the value associated with a given enum string.</p>
3965 <p class="code">
3966 int ippEnumValue (<br>
3967 &nbsp;&nbsp;&nbsp;&nbsp;const char *attrname,<br>
3968 &nbsp;&nbsp;&nbsp;&nbsp;const char *enumstring<br>
3969 );</p>
3970 <h4 class="parameters">Parameters</h4>
3971 <dl>
3972 <dt>attrname</dt>
3973 <dd class="description">Attribute name</dd>
3974 <dt>enumstring</dt>
3975 <dd class="description">Enum string</dd>
3976 </dl>
3977 <h4 class="returnvalue">Return Value</h4>
3978 <p class="description">Enum value or -1 if unknown</p>
3979 <h3 class="function"><a name="ippErrorString">ippErrorString</a></h3>
3980 <p class="description">Return a name for the given status code.</p>
3981 <p class="code">
3982 const char *ippErrorString (<br>
3983 &nbsp;&nbsp;&nbsp;&nbsp;ipp_status_t error<br>
3984 );</p>
3985 <h4 class="parameters">Parameters</h4>
3986 <dl>
3987 <dt>error</dt>
3988 <dd class="description">Error status</dd>
3989 </dl>
3990 <h4 class="returnvalue">Return Value</h4>
3991 <p class="description">Text string</p>
3992 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippErrorValue">ippErrorValue</a></h3>
3993 <p class="description">Return a status code for the given name.</p>
3994 <p class="code">
3995 ipp_status_t ippErrorValue (<br>
3996 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
3997 );</p>
3998 <h4 class="parameters">Parameters</h4>
3999 <dl>
4000 <dt>name</dt>
4001 <dd class="description">Name</dd>
4002 </dl>
4003 <h4 class="returnvalue">Return Value</h4>
4004 <p class="description">IPP status code</p>
4005 <h3 class="function"><a name="ippFindAttribute">ippFindAttribute</a></h3>
4006 <p class="description">Find a named attribute in a request.</p>
4007 <p class="code">
4008 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute (<br>
4009 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4010 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
4011 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t type<br>
4012 );</p>
4013 <h4 class="parameters">Parameters</h4>
4014 <dl>
4015 <dt>ipp</dt>
4016 <dd class="description">IPP message</dd>
4017 <dt>name</dt>
4018 <dd class="description">Name of attribute</dd>
4019 <dt>type</dt>
4020 <dd class="description">Type of attribute</dd>
4021 </dl>
4022 <h4 class="returnvalue">Return Value</h4>
4023 <p class="description">Matching attribute</p>
4024 <h3 class="function"><a name="ippFindNextAttribute">ippFindNextAttribute</a></h3>
4025 <p class="description">Find the next named attribute in a request.</p>
4026 <p class="code">
4027 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute (<br>
4028 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4029 &nbsp;&nbsp;&nbsp;&nbsp;const char *name,<br>
4030 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t type<br>
4031 );</p>
4032 <h4 class="parameters">Parameters</h4>
4033 <dl>
4034 <dt>ipp</dt>
4035 <dd class="description">IPP message</dd>
4036 <dt>name</dt>
4037 <dd class="description">Name of attribute</dd>
4038 <dt>type</dt>
4039 <dd class="description">Type of attribute</dd>
4040 </dl>
4041 <h4 class="returnvalue">Return Value</h4>
4042 <p class="description">Matching attribute</p>
4043 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippFirstAttribute">ippFirstAttribute</a></h3>
4044 <p class="description">Return the first attribute in the message.</p>
4045 <p class="code">
4046 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFirstAttribute (<br>
4047 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4048 );</p>
4049 <h4 class="parameters">Parameters</h4>
4050 <dl>
4051 <dt>ipp</dt>
4052 <dd class="description">IPP message</dd>
4053 </dl>
4054 <h4 class="returnvalue">Return Value</h4>
4055 <p class="description">First attribute or <code>NULL</code> if none</p>
4056 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetBoolean">ippGetBoolean</a></h3>
4057 <p class="description">Get a boolean value for an attribute.</p>
4058 <p class="code">
4059 int ippGetBoolean (<br>
4060 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4061 &nbsp;&nbsp;&nbsp;&nbsp;int element<br>
4062 );</p>
4063 <h4 class="parameters">Parameters</h4>
4064 <dl>
4065 <dt>attr</dt>
4066 <dd class="description">IPP attribute</dd>
4067 <dt>element</dt>
4068 <dd class="description">Value number (0-based)</dd>
4069 </dl>
4070 <h4 class="returnvalue">Return Value</h4>
4071 <p class="description">Boolean value or -1 on error</p>
4072 <h4 class="discussion">Discussion</h4>
4073 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4074 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4075
4076 </p>
4077 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetCollection">ippGetCollection</a></h3>
4078 <p class="description">Get a collection value for an attribute.</p>
4079 <p class="code">
4080 <a href="#ipp_t">ipp_t</a> *ippGetCollection (<br>
4081 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4082 &nbsp;&nbsp;&nbsp;&nbsp;int element<br>
4083 );</p>
4084 <h4 class="parameters">Parameters</h4>
4085 <dl>
4086 <dt>attr</dt>
4087 <dd class="description">IPP attribute</dd>
4088 <dt>element</dt>
4089 <dd class="description">Value number (0-based)</dd>
4090 </dl>
4091 <h4 class="returnvalue">Return Value</h4>
4092 <p class="description">Collection value or <code>NULL</code> on error</p>
4093 <h4 class="discussion">Discussion</h4>
4094 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4095 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4096
4097 </p>
4098 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetCount">ippGetCount</a></h3>
4099 <p class="description">Get the number of values in an attribute.</p>
4100 <p class="code">
4101 int ippGetCount (<br>
4102 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
4103 );</p>
4104 <h4 class="parameters">Parameters</h4>
4105 <dl>
4106 <dt>attr</dt>
4107 <dd class="description">IPP attribute</dd>
4108 </dl>
4109 <h4 class="returnvalue">Return Value</h4>
4110 <p class="description">Number of values or -1 on error</p>
4111 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetDate">ippGetDate</a></h3>
4112 <p class="description">Get a date value for an attribute.</p>
4113 <p class="code">
4114 const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippGetDate (<br>
4115 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4116 &nbsp;&nbsp;&nbsp;&nbsp;int element<br>
4117 );</p>
4118 <h4 class="parameters">Parameters</h4>
4119 <dl>
4120 <dt>attr</dt>
4121 <dd class="description">IPP attribute</dd>
4122 <dt>element</dt>
4123 <dd class="description">Value number (0-based)</dd>
4124 </dl>
4125 <h4 class="returnvalue">Return Value</h4>
4126 <p class="description">Date value or <code>NULL</code></p>
4127 <h4 class="discussion">Discussion</h4>
4128 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4129 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4130
4131 </p>
4132 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetGroupTag">ippGetGroupTag</a></h3>
4133 <p class="description">Get the group associated with an attribute.</p>
4134 <p class="code">
4135 ipp_tag_t ippGetGroupTag (<br>
4136 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
4137 );</p>
4138 <h4 class="parameters">Parameters</h4>
4139 <dl>
4140 <dt>attr</dt>
4141 <dd class="description">IPP attribute</dd>
4142 </dl>
4143 <h4 class="returnvalue">Return Value</h4>
4144 <p class="description">Group tag or <code>IPP_TAG_ZERO</code> on error</p>
4145 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetInteger">ippGetInteger</a></h3>
4146 <p class="description">Get the integer/enum value for an attribute.</p>
4147 <p class="code">
4148 int ippGetInteger (<br>
4149 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4150 &nbsp;&nbsp;&nbsp;&nbsp;int element<br>
4151 );</p>
4152 <h4 class="parameters">Parameters</h4>
4153 <dl>
4154 <dt>attr</dt>
4155 <dd class="description">IPP attribute</dd>
4156 <dt>element</dt>
4157 <dd class="description">Value number (0-based)</dd>
4158 </dl>
4159 <h4 class="returnvalue">Return Value</h4>
4160 <p class="description">Value or -1 on error</p>
4161 <h4 class="discussion">Discussion</h4>
4162 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4163 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4164
4165 </p>
4166 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetName">ippGetName</a></h3>
4167 <p class="description">Get the attribute name.</p>
4168 <p class="code">
4169 const char *ippGetName (<br>
4170 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
4171 );</p>
4172 <h4 class="parameters">Parameters</h4>
4173 <dl>
4174 <dt>attr</dt>
4175 <dd class="description">IPP attribute</dd>
4176 </dl>
4177 <h4 class="returnvalue">Return Value</h4>
4178 <p class="description">Attribute name or <code>NULL</code> for separators</p>
4179 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetOperation">ippGetOperation</a></h3>
4180 <p class="description">Get the operation ID in an IPP message.</p>
4181 <p class="code">
4182 ipp_op_t ippGetOperation (<br>
4183 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4184 );</p>
4185 <h4 class="parameters">Parameters</h4>
4186 <dl>
4187 <dt>ipp</dt>
4188 <dd class="description">IPP request message</dd>
4189 </dl>
4190 <h4 class="returnvalue">Return Value</h4>
4191 <p class="description">Operation ID or -1 on error</p>
4192 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetRange">ippGetRange</a></h3>
4193 <p class="description">Get a rangeOfInteger value from an attribute.</p>
4194 <p class="code">
4195 int ippGetRange (<br>
4196 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4197 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4198 &nbsp;&nbsp;&nbsp;&nbsp;int *uppervalue<br>
4199 );</p>
4200 <h4 class="parameters">Parameters</h4>
4201 <dl>
4202 <dt>attr</dt>
4203 <dd class="description">IPP attribute</dd>
4204 <dt>element</dt>
4205 <dd class="description">Value number (0-based)</dd>
4206 <dt>uppervalue</dt>
4207 <dd class="description">Upper value of range</dd>
4208 </dl>
4209 <h4 class="returnvalue">Return Value</h4>
4210 <p class="description">Lower value of range or -1</p>
4211 <h4 class="discussion">Discussion</h4>
4212 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4213 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4214
4215 </p>
4216 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetRequestId">ippGetRequestId</a></h3>
4217 <p class="description">Get the request ID from an IPP message.</p>
4218 <p class="code">
4219 int ippGetRequestId (<br>
4220 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4221 );</p>
4222 <h4 class="parameters">Parameters</h4>
4223 <dl>
4224 <dt>ipp</dt>
4225 <dd class="description">IPP message</dd>
4226 </dl>
4227 <h4 class="returnvalue">Return Value</h4>
4228 <p class="description">Request ID or -1 on error</p>
4229 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetResolution">ippGetResolution</a></h3>
4230 <p class="description">Get a resolution value for an attribute.</p>
4231 <p class="code">
4232 int ippGetResolution (<br>
4233 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4234 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4235 &nbsp;&nbsp;&nbsp;&nbsp;int *yres,<br>
4236 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_res_t">ipp_res_t</a> *units<br>
4237 );</p>
4238 <h4 class="parameters">Parameters</h4>
4239 <dl>
4240 <dt>attr</dt>
4241 <dd class="description">IPP attribute</dd>
4242 <dt>element</dt>
4243 <dd class="description">Value number (0-based)</dd>
4244 <dt>yres</dt>
4245 <dd class="description">Vertical/feed resolution</dd>
4246 <dt>units</dt>
4247 <dd class="description">Units for resolution</dd>
4248 </dl>
4249 <h4 class="returnvalue">Return Value</h4>
4250 <p class="description">Horizontal/cross feed resolution or -1</p>
4251 <h4 class="discussion">Discussion</h4>
4252 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4253 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4254
4255 </p>
4256 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetState">ippGetState</a></h3>
4257 <p class="description">Get the IPP message state.</p>
4258 <p class="code">
4259 <a href="#ipp_state_t">ipp_state_t</a> ippGetState (<br>
4260 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4261 );</p>
4262 <h4 class="parameters">Parameters</h4>
4263 <dl>
4264 <dt>ipp</dt>
4265 <dd class="description">IPP message</dd>
4266 </dl>
4267 <h4 class="returnvalue">Return Value</h4>
4268 <p class="description">IPP message state value</p>
4269 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetStatusCode">ippGetStatusCode</a></h3>
4270 <p class="description">Get the status code from an IPP response or event message.</p>
4271 <p class="code">
4272 ipp_status_t ippGetStatusCode (<br>
4273 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4274 );</p>
4275 <h4 class="parameters">Parameters</h4>
4276 <dl>
4277 <dt>ipp</dt>
4278 <dd class="description">IPP response or event message</dd>
4279 </dl>
4280 <h4 class="returnvalue">Return Value</h4>
4281 <p class="description">Status code in IPP message</p>
4282 <h3 class="function"><a name="ippGetString">ippGetString</a></h3>
4283 <p class="description">Return the value...</p>
4284 <p class="code">
4285 const char *ippGetString (<br>
4286 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br>
4287 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4288 &nbsp;&nbsp;&nbsp;&nbsp;const char **language<br>
4289 );</p>
4290 <h4 class="parameters">Parameters</h4>
4291 <dl>
4292 <dt>attr</dt>
4293 <dd class="description">IPP attribute</dd>
4294 <dt>element</dt>
4295 <dd class="description">Value number (0-based)</dd>
4296 <dt>language</dt>
4297 <dd class="description">Language code (<code>NULL</code> for don't care)</dd>
4298 </dl>
4299 <h4 class="returnvalue">Return Value</h4>
4300 <p class="description">Get the string and optionally the language code for an attribute.</p>
4301 <p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to
4302 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1.
4303
4304 </p>
4305 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetValueTag">ippGetValueTag</a></h3>
4306 <p class="description">Get the value tag for an attribute.</p>
4307 <p class="code">
4308 ipp_tag_t ippGetValueTag (<br>
4309 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
4310 );</p>
4311 <h4 class="parameters">Parameters</h4>
4312 <dl>
4313 <dt>attr</dt>
4314 <dd class="description">IPP attribute</dd>
4315 </dl>
4316 <h4 class="returnvalue">Return Value</h4>
4317 <p class="description">Value tag or <code>IPP_TAG_ZERO</code> on error</p>
4318 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippGetVersion">ippGetVersion</a></h3>
4319 <p class="description">Get the major and minor version number from an IPP message.</p>
4320 <p class="code">
4321 int ippGetVersion (<br>
4322 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4323 &nbsp;&nbsp;&nbsp;&nbsp;int *minor<br>
4324 );</p>
4325 <h4 class="parameters">Parameters</h4>
4326 <dl>
4327 <dt>ipp</dt>
4328 <dd class="description">IPP message</dd>
4329 <dt>minor</dt>
4330 <dd class="description">Minor version number or <code>NULL</code></dd>
4331 </dl>
4332 <h4 class="returnvalue">Return Value</h4>
4333 <p class="description">Major version number or -1 on error</p>
4334 <h3 class="function"><a name="ippLength">ippLength</a></h3>
4335 <p class="description">Compute the length of an IPP message.</p>
4336 <p class="code">
4337 size_t ippLength (<br>
4338 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4339 );</p>
4340 <h4 class="parameters">Parameters</h4>
4341 <dl>
4342 <dt>ipp</dt>
4343 <dd class="description">IPP message</dd>
4344 </dl>
4345 <h4 class="returnvalue">Return Value</h4>
4346 <p class="description">Size of IPP message</p>
4347 <h3 class="function"><a name="ippNew">ippNew</a></h3>
4348 <p class="description">Allocate a new IPP message.</p>
4349 <p class="code">
4350 <a href="#ipp_t">ipp_t</a> *ippNew (void);</p>
4351 <h4 class="returnvalue">Return Value</h4>
4352 <p class="description">New IPP message</p>
4353 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippNewRequest">ippNewRequest</a></h3>
4354 <p class="description">Allocate a new IPP request message.</p>
4355 <p class="code">
4356 <a href="#ipp_t">ipp_t</a> *ippNewRequest (<br>
4357 &nbsp;&nbsp;&nbsp;&nbsp;ipp_op_t op<br>
4358 );</p>
4359 <h4 class="parameters">Parameters</h4>
4360 <dl>
4361 <dt>op</dt>
4362 <dd class="description">Operation code</dd>
4363 </dl>
4364 <h4 class="returnvalue">Return Value</h4>
4365 <p class="description">IPP request message</p>
4366 <h4 class="discussion">Discussion</h4>
4367 <p class="discussion">The new request message is initialized with the attributes-charset and
4368 attributes-natural-language attributes added. The
4369 attributes-natural-language value is derived from the current locale.
4370
4371 </p>
4372 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippNewResponse">ippNewResponse</a></h3>
4373 <p class="description">Allocate a new IPP response message.</p>
4374 <p class="code">
4375 <a href="#ipp_t">ipp_t</a> *ippNewResponse (<br>
4376 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *request<br>
4377 );</p>
4378 <h4 class="parameters">Parameters</h4>
4379 <dl>
4380 <dt>request</dt>
4381 <dd class="description">IPP request message</dd>
4382 </dl>
4383 <h4 class="returnvalue">Return Value</h4>
4384 <p class="description">IPP response message</p>
4385 <h4 class="discussion">Discussion</h4>
4386 <p class="discussion">The new response message is initialized with the same version-number,
4387 request-id, attributes-charset, and attributes-natural-language as the
4388 provided request message.  If the attributes-charset or
4389 attributes-natural-language attributes are missing from the request,
4390 &quot;utf-8&quot; and a value derived from the current locale are substituted,
4391 respectively.
4392
4393 </p>
4394 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippNextAttribute">ippNextAttribute</a></h3>
4395 <p class="description">Return the next attribute in the message.</p>
4396 <p class="code">
4397 <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippNextAttribute (<br>
4398 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4399 );</p>
4400 <h4 class="parameters">Parameters</h4>
4401 <dl>
4402 <dt>ipp</dt>
4403 <dd class="description">IPP message</dd>
4404 </dl>
4405 <h4 class="returnvalue">Return Value</h4>
4406 <p class="description">Next attribute or <code>NULL</code> if none</p>
4407 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippOpString">ippOpString</a></h3>
4408 <p class="description">Return a name for the given operation id.</p>
4409 <p class="code">
4410 const char *ippOpString (<br>
4411 &nbsp;&nbsp;&nbsp;&nbsp;ipp_op_t op<br>
4412 );</p>
4413 <h4 class="parameters">Parameters</h4>
4414 <dl>
4415 <dt>op</dt>
4416 <dd class="description">Operation ID</dd>
4417 </dl>
4418 <h4 class="returnvalue">Return Value</h4>
4419 <p class="description">Name</p>
4420 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippOpValue">ippOpValue</a></h3>
4421 <p class="description">Return an operation id for the given name.</p>
4422 <p class="code">
4423 ipp_op_t ippOpValue (<br>
4424 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
4425 );</p>
4426 <h4 class="parameters">Parameters</h4>
4427 <dl>
4428 <dt>name</dt>
4429 <dd class="description">Textual name</dd>
4430 </dl>
4431 <h4 class="returnvalue">Return Value</h4>
4432 <p class="description">Operation ID</p>
4433 <h3 class="function"><a name="ippPort">ippPort</a></h3>
4434 <p class="description">Return the default IPP port number.</p>
4435 <p class="code">
4436 int ippPort (void);</p>
4437 <h4 class="returnvalue">Return Value</h4>
4438 <p class="description">Port number</p>
4439 <h3 class="function"><a name="ippRead">ippRead</a></h3>
4440 <p class="description">Read data for an IPP message from a HTTP connection.</p>
4441 <p class="code">
4442 <a href="#ipp_state_t">ipp_state_t</a> ippRead (<br>
4443 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
4444 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4445 );</p>
4446 <h4 class="parameters">Parameters</h4>
4447 <dl>
4448 <dt>http</dt>
4449 <dd class="description">HTTP connection</dd>
4450 <dt>ipp</dt>
4451 <dd class="description">IPP data</dd>
4452 </dl>
4453 <h4 class="returnvalue">Return Value</h4>
4454 <p class="description">Current state</p>
4455 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="ippReadFile">ippReadFile</a></h3>
4456 <p class="description">Read data for an IPP message from a file.</p>
4457 <p class="code">
4458 <a href="#ipp_state_t">ipp_state_t</a> ippReadFile (<br>
4459 &nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
4460 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4461 );</p>
4462 <h4 class="parameters">Parameters</h4>
4463 <dl>
4464 <dt>fd</dt>
4465 <dd class="description">HTTP data</dd>
4466 <dt>ipp</dt>
4467 <dd class="description">IPP data</dd>
4468 </dl>
4469 <h4 class="returnvalue">Return Value</h4>
4470 <p class="description">Current state</p>
4471 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippReadIO">ippReadIO</a></h3>
4472 <p class="description">Read data for an IPP message.</p>
4473 <p class="code">
4474 <a href="#ipp_state_t">ipp_state_t</a> ippReadIO (<br>
4475 &nbsp;&nbsp;&nbsp;&nbsp;void *src,<br>
4476 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br>
4477 &nbsp;&nbsp;&nbsp;&nbsp;int blocking,<br>
4478 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *parent,<br>
4479 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
4480 );</p>
4481 <h4 class="parameters">Parameters</h4>
4482 <dl>
4483 <dt>src</dt>
4484 <dd class="description">Data source</dd>
4485 <dt>cb</dt>
4486 <dd class="description">Read callback function</dd>
4487 <dt>blocking</dt>
4488 <dd class="description">Use blocking IO?</dd>
4489 <dt>parent</dt>
4490 <dd class="description">Parent request, if any</dd>
4491 <dt>ipp</dt>
4492 <dd class="description">IPP data</dd>
4493 </dl>
4494 <h4 class="returnvalue">Return Value</h4>
4495 <p class="description">Current state</p>
4496 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetBoolean">ippSetBoolean</a></h3>
4497 <p class="description">Set a boolean value in an attribute.</p>
4498 <p class="code">
4499 int ippSetBoolean (<br>
4500 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4501 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4502 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4503 &nbsp;&nbsp;&nbsp;&nbsp;int boolvalue<br>
4504 );</p>
4505 <h4 class="parameters">Parameters</h4>
4506 <dl>
4507 <dt>ipp</dt>
4508 <dd class="description">IPP message</dd>
4509 <dt>attr</dt>
4510 <dd class="description">IPP attribute</dd>
4511 <dt>element</dt>
4512 <dd class="description">Value number (0-based)</dd>
4513 <dt>boolvalue</dt>
4514 <dd class="description">Boolean value</dd>
4515 </dl>
4516 <h4 class="returnvalue">Return Value</h4>
4517 <p class="description">1 on success, 0 on failure</p>
4518 <h4 class="discussion">Discussion</h4>
4519 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4520 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4521 <br>
4522 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4523 <br>
4524 The <code>element</code> parameter specifies which value to set from 0 to
4525 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4526
4527 </p>
4528 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetCollection">ippSetCollection</a></h3>
4529 <p class="description">Set a collection value in an attribute.</p>
4530 <p class="code">
4531 int ippSetCollection (<br>
4532 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4533 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4534 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4535 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *colvalue<br>
4536 );</p>
4537 <h4 class="parameters">Parameters</h4>
4538 <dl>
4539 <dt>ipp</dt>
4540 <dd class="description">IPP message</dd>
4541 <dt>attr</dt>
4542 <dd class="description">IPP attribute</dd>
4543 <dt>element</dt>
4544 <dd class="description">Value number (0-based)</dd>
4545 <dt>colvalue</dt>
4546 <dd class="description">Collection value</dd>
4547 </dl>
4548 <h4 class="returnvalue">Return Value</h4>
4549 <p class="description">1 on success, 0 on failure</p>
4550 <h4 class="discussion">Discussion</h4>
4551 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4552 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4553 <br>
4554 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4555 <br>
4556 The <code>element</code> parameter specifies which value to set from 0 to
4557 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4558
4559 </p>
4560 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetDate">ippSetDate</a></h3>
4561 <p class="description">Set a date value in an attribute.</p>
4562 <p class="code">
4563 int ippSetDate (<br>
4564 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4565 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4566 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4567 &nbsp;&nbsp;&nbsp;&nbsp;const <a href="#ipp_uchar_t">ipp_uchar_t</a> *datevalue<br>
4568 );</p>
4569 <h4 class="parameters">Parameters</h4>
4570 <dl>
4571 <dt>ipp</dt>
4572 <dd class="description">IPP message</dd>
4573 <dt>attr</dt>
4574 <dd class="description">IPP attribute</dd>
4575 <dt>element</dt>
4576 <dd class="description">Value number (0-based)</dd>
4577 <dt>datevalue</dt>
4578 <dd class="description">Date value</dd>
4579 </dl>
4580 <h4 class="returnvalue">Return Value</h4>
4581 <p class="description">1 on success, 0 on failure</p>
4582 <h4 class="discussion">Discussion</h4>
4583 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4584 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4585 <br>
4586 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4587 <br>
4588 The <code>element</code> parameter specifies which value to set from 0 to
4589 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4590
4591 </p>
4592 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetGroupTag">ippSetGroupTag</a></h3>
4593 <p class="description">Set the group tag of an attribute.</p>
4594 <p class="code">
4595 int ippSetGroupTag (<br>
4596 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4597 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4598 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t group_tag<br>
4599 );</p>
4600 <h4 class="parameters">Parameters</h4>
4601 <dl>
4602 <dt>ipp</dt>
4603 <dd class="description">IPP message</dd>
4604 <dt>attr</dt>
4605 <dd class="description">Attribute</dd>
4606 <dt>group_tag</dt>
4607 <dd class="description">Group tag</dd>
4608 </dl>
4609 <h4 class="returnvalue">Return Value</h4>
4610 <p class="description">1 on success, 0 on failure</p>
4611 <h4 class="discussion">Discussion</h4>
4612 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4613 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4614 <br>
4615 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4616 <br>
4617 The <code>group</code> parameter specifies the IPP attribute group tag: none
4618 (<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
4619 event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
4620 (<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
4621 (<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
4622
4623 </p>
4624 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetInteger">ippSetInteger</a></h3>
4625 <p class="description">Set an integer or enum value in an attribute.</p>
4626 <p class="code">
4627 int ippSetInteger (<br>
4628 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4629 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4630 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4631 &nbsp;&nbsp;&nbsp;&nbsp;int intvalue<br>
4632 );</p>
4633 <h4 class="parameters">Parameters</h4>
4634 <dl>
4635 <dt>ipp</dt>
4636 <dd class="description">IPP message</dd>
4637 <dt>attr</dt>
4638 <dd class="description">IPP attribute</dd>
4639 <dt>element</dt>
4640 <dd class="description">Value number (0-based)</dd>
4641 <dt>intvalue</dt>
4642 <dd class="description">Integer/enum value</dd>
4643 </dl>
4644 <h4 class="returnvalue">Return Value</h4>
4645 <p class="description">1 on success, 0 on failure</p>
4646 <h4 class="discussion">Discussion</h4>
4647 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4648 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4649 <br>
4650 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4651 <br>
4652 The <code>element</code> parameter specifies which value to set from 0 to
4653 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4654
4655 </p>
4656 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetName">ippSetName</a></h3>
4657 <p class="description">Set the name of an attribute.</p>
4658 <p class="code">
4659 int ippSetName (<br>
4660 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4661 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4662 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
4663 );</p>
4664 <h4 class="parameters">Parameters</h4>
4665 <dl>
4666 <dt>ipp</dt>
4667 <dd class="description">IPP message</dd>
4668 <dt>attr</dt>
4669 <dd class="description">IPP attribute</dd>
4670 <dt>name</dt>
4671 <dd class="description">Attribute name</dd>
4672 </dl>
4673 <h4 class="returnvalue">Return Value</h4>
4674 <p class="description">1 on success, 0 on failure</p>
4675 <h4 class="discussion">Discussion</h4>
4676 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4677 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4678 <br>
4679 The <code>attr</code> parameter may be modified as a result of setting the value.
4680
4681 </p>
4682 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetOperation">ippSetOperation</a></h3>
4683 <p class="description">Set the operation ID in an IPP request message.</p>
4684 <p class="code">
4685 int ippSetOperation (<br>
4686 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4687 &nbsp;&nbsp;&nbsp;&nbsp;ipp_op_t op<br>
4688 );</p>
4689 <h4 class="parameters">Parameters</h4>
4690 <dl>
4691 <dt>ipp</dt>
4692 <dd class="description">IPP request message</dd>
4693 <dt>op</dt>
4694 <dd class="description">Operation ID</dd>
4695 </dl>
4696 <h4 class="returnvalue">Return Value</h4>
4697 <p class="description">1 on success, 0 on failure</p>
4698 <h4 class="discussion">Discussion</h4>
4699 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4700 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
4701
4702 </p>
4703 <h3 class="function"><a name="ippSetPort">ippSetPort</a></h3>
4704 <p class="description">Set the default port number.</p>
4705 <p class="code">
4706 void ippSetPort (<br>
4707 &nbsp;&nbsp;&nbsp;&nbsp;int p<br>
4708 );</p>
4709 <h4 class="parameters">Parameters</h4>
4710 <dl>
4711 <dt>p</dt>
4712 <dd class="description">Port number to use</dd>
4713 </dl>
4714 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetRange">ippSetRange</a></h3>
4715 <p class="description">Set a rangeOfInteger value in an attribute.</p>
4716 <p class="code">
4717 int ippSetRange (<br>
4718 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4719 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4720 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4721 &nbsp;&nbsp;&nbsp;&nbsp;int lowervalue,<br>
4722 &nbsp;&nbsp;&nbsp;&nbsp;int uppervalue<br>
4723 );</p>
4724 <h4 class="parameters">Parameters</h4>
4725 <dl>
4726 <dt>ipp</dt>
4727 <dd class="description">IPP message</dd>
4728 <dt>attr</dt>
4729 <dd class="description">IPP attribute</dd>
4730 <dt>element</dt>
4731 <dd class="description">Value number (0-based)</dd>
4732 <dt>lowervalue</dt>
4733 <dd class="description">Lower bound for range</dd>
4734 <dt>uppervalue</dt>
4735 <dd class="description">Upper bound for range</dd>
4736 </dl>
4737 <h4 class="returnvalue">Return Value</h4>
4738 <p class="description">1 on success, 0 on failure</p>
4739 <h4 class="discussion">Discussion</h4>
4740 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4741 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4742 <br>
4743 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4744 <br>
4745 The <code>element</code> parameter specifies which value to set from 0 to
4746 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4747
4748 </p>
4749 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetRequestId">ippSetRequestId</a></h3>
4750 <p class="description">Set the request ID in an IPP message.</p>
4751 <p class="code">
4752 int ippSetRequestId (<br>
4753 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4754 &nbsp;&nbsp;&nbsp;&nbsp;int request_id<br>
4755 );</p>
4756 <h4 class="parameters">Parameters</h4>
4757 <dl>
4758 <dt>ipp</dt>
4759 <dd class="description">IPP message</dd>
4760 <dt>request_id</dt>
4761 <dd class="description">Request ID</dd>
4762 </dl>
4763 <h4 class="returnvalue">Return Value</h4>
4764 <p class="description">1 on success, 0 on failure</p>
4765 <h4 class="discussion">Discussion</h4>
4766 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4767 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4768 <br>
4769 The <code>request_id</code> parameter must be greater than 0.
4770
4771 </p>
4772 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetResolution">ippSetResolution</a></h3>
4773 <p class="description">Set a resolution value in an attribute.</p>
4774 <p class="code">
4775 int ippSetResolution (<br>
4776 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4777 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4778 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4779 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_res_t">ipp_res_t</a> unitsvalue,<br>
4780 &nbsp;&nbsp;&nbsp;&nbsp;int xresvalue,<br>
4781 &nbsp;&nbsp;&nbsp;&nbsp;int yresvalue<br>
4782 );</p>
4783 <h4 class="parameters">Parameters</h4>
4784 <dl>
4785 <dt>ipp</dt>
4786 <dd class="description">IPP message</dd>
4787 <dt>attr</dt>
4788 <dd class="description">IPP attribute</dd>
4789 <dt>element</dt>
4790 <dd class="description">Value number (0-based)</dd>
4791 <dt>unitsvalue</dt>
4792 <dd class="description">Resolution units</dd>
4793 <dt>xresvalue</dt>
4794 <dd class="description">Horizontal/cross feed resolution</dd>
4795 <dt>yresvalue</dt>
4796 <dd class="description">Vertical/feed resolution</dd>
4797 </dl>
4798 <h4 class="returnvalue">Return Value</h4>
4799 <p class="description">1 on success, 0 on failure</p>
4800 <h4 class="discussion">Discussion</h4>
4801 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4802 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4803 <br>
4804 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4805 <br>
4806 The <code>element</code> parameter specifies which value to set from 0 to
4807 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4808
4809 </p>
4810 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetState">ippSetState</a></h3>
4811 <p class="description">Set the current state of the IPP message.</p>
4812 <p class="code">
4813 int ippSetState (<br>
4814 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4815 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_state_t">ipp_state_t</a> state<br>
4816 );</p>
4817 <h4 class="parameters">Parameters</h4>
4818 <dl>
4819 <dt>ipp</dt>
4820 <dd class="description">IPP message</dd>
4821 <dt>state</dt>
4822 <dd class="description">IPP state value</dd>
4823 </dl>
4824 <h4 class="returnvalue">Return Value</h4>
4825 <p class="description">1 on success, 0 on failure</p>
4826 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetStatusCode">ippSetStatusCode</a></h3>
4827 <p class="description">Set the status code in an IPP response or event message.</p>
4828 <p class="code">
4829 int ippSetStatusCode (<br>
4830 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4831 &nbsp;&nbsp;&nbsp;&nbsp;ipp_status_t status<br>
4832 );</p>
4833 <h4 class="parameters">Parameters</h4>
4834 <dl>
4835 <dt>ipp</dt>
4836 <dd class="description">IPP response or event message</dd>
4837 <dt>status</dt>
4838 <dd class="description">Status code</dd>
4839 </dl>
4840 <h4 class="returnvalue">Return Value</h4>
4841 <p class="description">1 on success, 0 on failure</p>
4842 <h4 class="discussion">Discussion</h4>
4843 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4844 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
4845
4846 </p>
4847 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetString">ippSetString</a></h3>
4848 <p class="description">Set a string value in an attribute.</p>
4849 <p class="code">
4850 int ippSetString (<br>
4851 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4852 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4853 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4854 &nbsp;&nbsp;&nbsp;&nbsp;const char *strvalue<br>
4855 );</p>
4856 <h4 class="parameters">Parameters</h4>
4857 <dl>
4858 <dt>ipp</dt>
4859 <dd class="description">IPP message</dd>
4860 <dt>attr</dt>
4861 <dd class="description">IPP attribute</dd>
4862 <dt>element</dt>
4863 <dd class="description">Value number (0-based)</dd>
4864 <dt>strvalue</dt>
4865 <dd class="description">String value</dd>
4866 </dl>
4867 <h4 class="returnvalue">Return Value</h4>
4868 <p class="description">1 on success, 0 on failure</p>
4869 <h4 class="discussion">Discussion</h4>
4870 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4871 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4872 <br>
4873 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4874 <br>
4875 The <code>element</code> parameter specifies which value to set from 0 to
4876 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.
4877
4878 </p>
4879 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippSetStringf">ippSetStringf</a></h3>
4880 <p class="description">Set a formatted string value of an attribute.</p>
4881 <p class="code">
4882 int ippSetStringf (<br>
4883 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4884 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4885 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4886 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
4887 &nbsp;&nbsp;&nbsp;&nbsp;...<br>
4888 );</p>
4889 <h4 class="parameters">Parameters</h4>
4890 <dl>
4891 <dt>ipp</dt>
4892 <dd class="description">IPP message</dd>
4893 <dt>attr</dt>
4894 <dd class="description">IPP attribute</dd>
4895 <dt>element</dt>
4896 <dd class="description">Value number (0-based)</dd>
4897 <dt>format</dt>
4898 <dd class="description">Printf-style format string</dd>
4899 <dt>...</dt>
4900 <dd class="description">Additional arguments as needed</dd>
4901 </dl>
4902 <h4 class="returnvalue">Return Value</h4>
4903 <p class="description">1 on success, 0 on failure</p>
4904 <h4 class="discussion">Discussion</h4>
4905 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4906 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4907 <br>
4908 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4909 <br>
4910 The <code>element</code> parameter specifies which value to set from 0 to
4911 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br>
4912 <br>
4913 The <code>format</code> parameter uses formatting characters compatible with the
4914 printf family of standard functions.  Additional arguments follow it as
4915 needed.  The formatted string is truncated as needed to the maximum length of
4916 the corresponding value type.
4917
4918 </p>
4919 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippSetStringfv">ippSetStringfv</a></h3>
4920 <p class="description">Set a formatted string value of an attribute.</p>
4921 <p class="code">
4922 int ippSetStringfv (<br>
4923 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4924 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4925 &nbsp;&nbsp;&nbsp;&nbsp;int element,<br>
4926 &nbsp;&nbsp;&nbsp;&nbsp;const char *format,<br>
4927 &nbsp;&nbsp;&nbsp;&nbsp;va_list ap<br>
4928 );</p>
4929 <h4 class="parameters">Parameters</h4>
4930 <dl>
4931 <dt>ipp</dt>
4932 <dd class="description">IPP message</dd>
4933 <dt>attr</dt>
4934 <dd class="description">IPP attribute</dd>
4935 <dt>element</dt>
4936 <dd class="description">Value number (0-based)</dd>
4937 <dt>format</dt>
4938 <dd class="description">Printf-style format string</dd>
4939 <dt>ap</dt>
4940 <dd class="description">Pointer to additional arguments</dd>
4941 </dl>
4942 <h4 class="returnvalue">Return Value</h4>
4943 <p class="description">1 on success, 0 on failure</p>
4944 <h4 class="discussion">Discussion</h4>
4945 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4946 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4947 <br>
4948 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4949 <br>
4950 The <code>element</code> parameter specifies which value to set from 0 to
4951 <a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>.<br>
4952 <br>
4953 The <code>format</code> parameter uses formatting characters compatible with the
4954 printf family of standard functions.  Additional arguments follow it as
4955 needed.  The formatted string is truncated as needed to the maximum length of
4956 the corresponding value type.
4957
4958 </p>
4959 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetValueTag">ippSetValueTag</a></h3>
4960 <p class="description">Set the value tag of an attribute.</p>
4961 <p class="code">
4962 int ippSetValueTag (<br>
4963 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
4964 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br>
4965 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t value_tag<br>
4966 );</p>
4967 <h4 class="parameters">Parameters</h4>
4968 <dl>
4969 <dt>ipp</dt>
4970 <dd class="description">IPP message</dd>
4971 <dt>attr</dt>
4972 <dd class="description">IPP attribute</dd>
4973 <dt>value_tag</dt>
4974 <dd class="description">Value tag</dd>
4975 </dl>
4976 <h4 class="returnvalue">Return Value</h4>
4977 <p class="description">1 on success, 0 on failure</p>
4978 <h4 class="discussion">Discussion</h4>
4979 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
4980 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
4981 <br>
4982 The <code>attr</code> parameter may be modified as a result of setting the value.<br>
4983 <br>
4984 Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger
4985 (<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name
4986 (<code>IPP_TAG_NAME</code>) or nameWithLanguage (<code>IPP_TAG_NAMELANG</code>) values, text
4987 (<code>IPP_TAG_TEXT</code>) values can be promoted to textWithLanguage
4988 (<code>IPP_TAG_TEXTLANG</code>) values, and all values can be demoted to the various
4989 out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other changes
4990 will be rejected.<br>
4991 <br>
4992 Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
4993 code in the &quot;attributes-natural-language&quot; attribute or, if not present, the language
4994 code for the current locale.
4995
4996 </p>
4997 <h3 class="function"><span class="info">&nbsp;CUPS 1.6/OS X 10.8&nbsp;</span><a name="ippSetVersion">ippSetVersion</a></h3>
4998 <p class="description">Set the version number in an IPP message.</p>
4999 <p class="code">
5000 int ippSetVersion (<br>
5001 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp,<br>
5002 &nbsp;&nbsp;&nbsp;&nbsp;int major,<br>
5003 &nbsp;&nbsp;&nbsp;&nbsp;int minor<br>
5004 );</p>
5005 <h4 class="parameters">Parameters</h4>
5006 <dl>
5007 <dt>ipp</dt>
5008 <dd class="description">IPP message</dd>
5009 <dt>major</dt>
5010 <dd class="description">Major version number (major.minor)</dd>
5011 <dt>minor</dt>
5012 <dd class="description">Minor version number (major.minor)</dd>
5013 </dl>
5014 <h4 class="returnvalue">Return Value</h4>
5015 <p class="description">1 on success, 0 on failure</p>
5016 <h4 class="discussion">Discussion</h4>
5017 <p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using
5018 the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or  <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
5019 <br>
5020 The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
5021
5022 </p>
5023 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="ippTagString">ippTagString</a></h3>
5024 <p class="description">Return the tag name corresponding to a tag value.</p>
5025 <p class="code">
5026 const char *ippTagString (<br>
5027 &nbsp;&nbsp;&nbsp;&nbsp;ipp_tag_t tag<br>
5028 );</p>
5029 <h4 class="parameters">Parameters</h4>
5030 <dl>
5031 <dt>tag</dt>
5032 <dd class="description">Tag value</dd>
5033 </dl>
5034 <h4 class="returnvalue">Return Value</h4>
5035 <p class="description">Tag name</p>
5036 <h4 class="discussion">Discussion</h4>
5037 <p class="discussion">The returned names are defined in RFC 2911 and 3382.
5038
5039 </p>
5040 <h3 class="function"><span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span><a name="ippTagValue">ippTagValue</a></h3>
5041 <p class="description">Return the tag value corresponding to a tag name.</p>
5042 <p class="code">
5043 ipp_tag_t ippTagValue (<br>
5044 &nbsp;&nbsp;&nbsp;&nbsp;const char *name<br>
5045 );</p>
5046 <h4 class="parameters">Parameters</h4>
5047 <dl>
5048 <dt>name</dt>
5049 <dd class="description">Tag name</dd>
5050 </dl>
5051 <h4 class="returnvalue">Return Value</h4>
5052 <p class="description">Tag value</p>
5053 <h4 class="discussion">Discussion</h4>
5054 <p class="discussion">The tag names are defined in RFC 2911 and 3382.
5055
5056 </p>
5057 <h3 class="function"><a name="ippTimeToDate">ippTimeToDate</a></h3>
5058 <p class="description">Convert from UNIX time to RFC 1903 format.</p>
5059 <p class="code">
5060 const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br>
5061 &nbsp;&nbsp;&nbsp;&nbsp;time_t t<br>
5062 );</p>
5063 <h4 class="parameters">Parameters</h4>
5064 <dl>
5065 <dt>t</dt>
5066 <dd class="description">UNIX time value</dd>
5067 </dl>
5068 <h4 class="returnvalue">Return Value</h4>
5069 <p class="description">RFC-1903 date/time data</p>
5070 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippValidateAttribute">ippValidateAttribute</a></h3>
5071 <p class="description">Validate the contents of an attribute.</p>
5072 <p class="code">
5073 int ippValidateAttribute (<br>
5074 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br>
5075 );</p>
5076 <h4 class="parameters">Parameters</h4>
5077 <dl>
5078 <dt>attr</dt>
5079 <dd class="description">Attribute</dd>
5080 </dl>
5081 <h4 class="returnvalue">Return Value</h4>
5082 <p class="description">1 if valid, 0 otherwise</p>
5083 <h4 class="discussion">Discussion</h4>
5084 <p class="discussion">This function validates the contents of an attribute based on the name and
5085 value tag.  1 is returned if the attribute is valid, 0 otherwise.  On
5086 failure, cupsLastErrorString() is set to a human-readable message.
5087
5088 </p>
5089 <h3 class="function"><span class="info">&nbsp;CUPS 1.7&nbsp;</span><a name="ippValidateAttributes">ippValidateAttributes</a></h3>
5090 <p class="description">Validate all attributes in an IPP message.</p>
5091 <p class="code">
5092 int ippValidateAttributes (<br>
5093 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
5094 );</p>
5095 <h4 class="parameters">Parameters</h4>
5096 <dl>
5097 <dt>ipp</dt>
5098 <dd class="description">IPP message</dd>
5099 </dl>
5100 <h4 class="returnvalue">Return Value</h4>
5101 <p class="description">1 if valid, 0 otherwise</p>
5102 <h4 class="discussion">Discussion</h4>
5103 <p class="discussion">This function validates the contents of the IPP message, including each
5104 attribute.  Like <a href="#ippValidateAttribute"><code>ippValidateAttribute</code></a>, cupsLastErrorString() is set
5105 to a human-readable message on failure.
5106
5107 </p>
5108 <h3 class="function"><a name="ippWrite">ippWrite</a></h3>
5109 <p class="description">Write data for an IPP message to a HTTP connection.</p>
5110 <p class="code">
5111 <a href="#ipp_state_t">ipp_state_t</a> ippWrite (<br>
5112 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_t">http_t</a> *http,<br>
5113 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
5114 );</p>
5115 <h4 class="parameters">Parameters</h4>
5116 <dl>
5117 <dt>http</dt>
5118 <dd class="description">HTTP connection</dd>
5119 <dt>ipp</dt>
5120 <dd class="description">IPP data</dd>
5121 </dl>
5122 <h4 class="returnvalue">Return Value</h4>
5123 <p class="description">Current state</p>
5124 <h3 class="function"><span class="info">&nbsp;CUPS 1.1.19/OS X 10.3&nbsp;</span><a name="ippWriteFile">ippWriteFile</a></h3>
5125 <p class="description">Write data for an IPP message to a file.</p>
5126 <p class="code">
5127 <a href="#ipp_state_t">ipp_state_t</a> ippWriteFile (<br>
5128 &nbsp;&nbsp;&nbsp;&nbsp;int fd,<br>
5129 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
5130 );</p>
5131 <h4 class="parameters">Parameters</h4>
5132 <dl>
5133 <dt>fd</dt>
5134 <dd class="description">HTTP data</dd>
5135 <dt>ipp</dt>
5136 <dd class="description">IPP data</dd>
5137 </dl>
5138 <h4 class="returnvalue">Return Value</h4>
5139 <p class="description">Current state</p>
5140 <h3 class="function"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ippWriteIO">ippWriteIO</a></h3>
5141 <p class="description">Write data for an IPP message.</p>
5142 <p class="code">
5143 <a href="#ipp_state_t">ipp_state_t</a> ippWriteIO (<br>
5144 &nbsp;&nbsp;&nbsp;&nbsp;void *dst,<br>
5145 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br>
5146 &nbsp;&nbsp;&nbsp;&nbsp;int blocking,<br>
5147 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *parent,<br>
5148 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#ipp_t">ipp_t</a> *ipp<br>
5149 );</p>
5150 <h4 class="parameters">Parameters</h4>
5151 <dl>
5152 <dt>dst</dt>
5153 <dd class="description">Destination</dd>
5154 <dt>cb</dt>
5155 <dd class="description">Write callback function</dd>
5156 <dt>blocking</dt>
5157 <dd class="description">Use blocking IO?</dd>
5158 <dt>parent</dt>
5159 <dd class="description">Parent IPP message</dd>
5160 <dt>ipp</dt>
5161 <dd class="description">IPP data</dd>
5162 </dl>
5163 <h4 class="returnvalue">Return Value</h4>
5164 <p class="description">Current state</p>
5165 <h2 class="title"><a name="TYPES">Data Types</a></h2>
5166 <h3 class="typedef"><a name="gss_auth_identity_desc">gss_auth_identity_desc</a></h3>
5167 <p class="description">Local functions...</p>
5168 <p class="code">
5169 typedef struct <a href="#gss_auth_identity">gss_auth_identity</a> gss_auth_identity_desc;
5170 </p>
5171 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="http_addr_t">http_addr_t</a></h3>
5172 <p class="description">Socket address union, which
5173 makes using IPv6 and other
5174 address types easier and
5175 more portable. </p>
5176 <p class="code">
5177 typedef union _http_addr_u / http_addr_t;
5178 </p>
5179 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="http_addrlist_t">http_addrlist_t</a></h3>
5180 <p class="description">Socket address list, which is
5181 used to enumerate all of the
5182 addresses that are associated
5183 with a hostname. </p>
5184 <p class="code">
5185 typedef struct <a href="#http_addrlist_s">http_addrlist_s</a> / http_addrlist_t;
5186 </p>
5187 <h3 class="typedef"><a name="http_auth_t">http_auth_t</a></h3>
5188 <p class="description">HTTP authentication types</p>
5189 <p class="code">
5190 typedef enum <a href="#http_auth_e">http_auth_e</a> http_auth_t;
5191 </p>
5192 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="http_credential_t">http_credential_t</a></h3>
5193 <p class="description">HTTP credential data </p>
5194 <p class="code">
5195 typedef struct <a href="#http_credential_s">http_credential_s</a> http_credential_t;
5196 </p>
5197 <h3 class="typedef"><a name="http_encoding_t">http_encoding_t</a></h3>
5198 <p class="description">HTTP transfer encoding values</p>
5199 <p class="code">
5200 typedef enum <a href="#http_encoding_e">http_encoding_e</a> http_encoding_t;
5201 </p>
5202 <h3 class="typedef"><a name="http_encryption_t">http_encryption_t</a></h3>
5203 <p class="description">HTTP encryption values</p>
5204 <p class="code">
5205 typedef enum <a href="#http_encryption_e">http_encryption_e</a> http_encryption_t;
5206 </p>
5207 <h3 class="typedef"><a name="http_field_t">http_field_t</a></h3>
5208 <p class="description">HTTP field names</p>
5209 <p class="code">
5210 typedef enum <a href="#http_field_e">http_field_e</a> http_field_t;
5211 </p>
5212 <h3 class="typedef"><a name="http_keepalive_t">http_keepalive_t</a></h3>
5213 <p class="description">HTTP keep-alive values</p>
5214 <p class="code">
5215 typedef enum <a href="#http_keepalive_e">http_keepalive_e</a> http_keepalive_t;
5216 </p>
5217 <h3 class="typedef"><a name="http_state_t">http_state_t</a></h3>
5218 <p class="description">HTTP state values; states
5219 are server-oriented...</p>
5220 <p class="code">
5221 typedef enum <a href="#http_state_e">http_state_e</a> http_state_t;
5222 </p>
5223 <h3 class="typedef"><a name="http_t">http_t</a></h3>
5224 <p class="description">HTTP connection type</p>
5225 <p class="code">
5226 typedef struct _http_s http_t;
5227 </p>
5228 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="http_timeout_cb_t">http_timeout_cb_t</a></h3>
5229 <p class="description">HTTP timeout callback </p>
5230 <p class="code">
5231 typedef int (*http_timeout_cb_t)(<a href="#http_t">http_t</a> *http, void *user_data);
5232 </p>
5233 <h3 class="typedef"><a name="http_uri_coding_t">http_uri_coding_t</a></h3>
5234 <p class="description">URI en/decode flags</p>
5235 <p class="code">
5236 typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t;
5237 </p>
5238 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="http_uri_status_t">http_uri_status_t</a></h3>
5239 <p class="description">URI separation status </p>
5240 <p class="code">
5241 typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t;
5242 </p>
5243 <h3 class="typedef"><a name="http_version_t">http_version_t</a></h3>
5244 <p class="description">HTTP version numbers</p>
5245 <p class="code">
5246 typedef enum <a href="#http_version_e">http_version_e</a> http_version_t;
5247 </p>
5248 <h3 class="typedef"><a name="ipp_attribute_t">ipp_attribute_t</a></h3>
5249 <p class="description">IPP attribute</p>
5250 <p class="code">
5251 typedef struct _ipp_attribute_s ipp_attribute_t;
5252 </p>
5253 <h3 class="typedef"><a name="ipp_copycb_t">ipp_copycb_t</a></h3>
5254 <p class="description">The following structures are PRIVATE starting with CUPS 1.6/OS X 10.8.
5255 Please use the new accessor functions available in CUPS 1.6 and later, as
5256 these definitions will be moved to a private header file in a future release.</p>
5257 <p class="code">
5258 typedef int (*ipp_copycb_t)(void *context, <a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);
5259 </p>
5260 <h3 class="typedef"><a name="ipp_dstate_t">ipp_dstate_t</a></h3>
5261 <p class="description">Document states</p>
5262 <p class="code">
5263 typedef enum <a href="#ipp_dstate_e">ipp_dstate_e</a> ipp_dstate_t;
5264 </p>
5265 <h3 class="typedef"><a name="ipp_finish_t">ipp_finish_t</a></h3>
5266 <p class="description">Job collation types</p>
5267 <p class="code">
5268 typedef enum <a href="#ipp_finishings_e">ipp_finishings_e</a> ipp_finish_t;
5269 </p>
5270 <h3 class="typedef"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="ipp_iocb_t">ipp_iocb_t</a></h3>
5271 <p class="description">IPP IO Callback Function </p>
5272 <p class="code">
5273 typedef ssize_t (*ipp_iocb_t)(void *context, <a href="#ipp_uchar_t">ipp_uchar_t</a> *buffer, size_t bytes);
5274 </p>
5275 <h3 class="typedef"><a name="ipp_jcollate_t">ipp_jcollate_t</a></h3>
5276 <p class="description">Job collation types</p>
5277 <p class="code">
5278 typedef enum <a href="#ipp_jcollate_e">ipp_jcollate_e</a> ipp_jcollate_t;
5279 </p>
5280 <h3 class="typedef"><a name="ipp_orient_t">ipp_orient_t</a></h3>
5281 <p class="description">Orientation values</p>
5282 <p class="code">
5283 typedef enum <a href="#ipp_orient_e">ipp_orient_e</a> ipp_orient_t;
5284 </p>
5285 <h3 class="typedef"><a name="ipp_pstate_t">ipp_pstate_t</a></h3>
5286 <p class="description">Printer states</p>
5287 <p class="code">
5288 typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t;
5289 </p>
5290 <h3 class="typedef"><a name="ipp_quality_t">ipp_quality_t</a></h3>
5291 <p class="description">Qualities</p>
5292 <p class="code">
5293 typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t;
5294 </p>
5295 <h3 class="typedef"><a name="ipp_res_t">ipp_res_t</a></h3>
5296 <p class="description">Resolution units</p>
5297 <p class="code">
5298 typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t;
5299 </p>
5300 <h3 class="typedef"><a name="ipp_state_t">ipp_state_t</a></h3>
5301 <p class="description">IPP states</p>
5302 <p class="code">
5303 typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t;
5304 </p>
5305 <h3 class="typedef"><a name="ipp_t">ipp_t</a></h3>
5306 <p class="description">IPP request/response data</p>
5307 <p class="code">
5308 typedef struct _ipp_s ipp_t;
5309 </p>
5310 <h3 class="typedef"><a name="ipp_uchar_t">ipp_uchar_t</a></h3>
5311 <p class="description">Unsigned 8-bit integer/character</p>
5312 <p class="code">
5313 typedef unsigned char ipp_uchar_t;
5314 </p>
5315 <h2 class="title"><a name="STRUCTURES">Structures</a></h2>
5316 <h3 class="struct"><a name="gss_auth_identity">gss_auth_identity</a></h3>
5317 <p class="description">Local functions...</p>
5318 <p class="code">struct gss_auth_identity {<br>
5319 &nbsp;&nbsp;&nbsp;&nbsp;gss_buffer_t *credentialsRef;<br>
5320 &nbsp;&nbsp;&nbsp;&nbsp;uint32_t flags;<br>
5321 &nbsp;&nbsp;&nbsp;&nbsp;char *password;<br>
5322 &nbsp;&nbsp;&nbsp;&nbsp;char *realm;<br>
5323 &nbsp;&nbsp;&nbsp;&nbsp;uint32_t type;<br>
5324 &nbsp;&nbsp;&nbsp;&nbsp;char *username;<br>
5325 };</p>
5326 <h4 class="members">Members</h4>
5327 <dl>
5328 <dt>credentialsRef </dt>
5329 <dt>flags </dt>
5330 <dt>password </dt>
5331 <dt>realm </dt>
5332 <dt>type </dt>
5333 <dt>username </dt>
5334 </dl>
5335 <h3 class="struct"><span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span><a name="http_addrlist_s">http_addrlist_s</a></h3>
5336 <p class="description">Socket address list, which is
5337 used to enumerate all of the
5338 addresses that are associated
5339 with a hostname. </p>
5340 <p class="code">struct http_addrlist_s {<br>
5341 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#http_addr_t">http_addr_t</a> addr;<br>
5342 &nbsp;&nbsp;&nbsp;&nbsp;struct <a href="#http_addrlist_s">http_addrlist_s</a> *next;<br>
5343 };</p>
5344 <h4 class="members">Members</h4>
5345 <dl>
5346 <dt>addr </dt>
5347 <dd class="description">Address</dd>
5348 <dt>next </dt>
5349 <dd class="description">Pointer to next address in list</dd>
5350 </dl>
5351 <h3 class="struct"><span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span><a name="http_credential_s">http_credential_s</a></h3>
5352 <p class="description">HTTP credential data </p>
5353 <p class="code">struct http_credential_s {<br>
5354 &nbsp;&nbsp;&nbsp;&nbsp;void *data;<br>
5355 &nbsp;&nbsp;&nbsp;&nbsp;size_t datalen;<br>
5356 };</p>
5357 <h4 class="members">Members</h4>
5358 <dl>
5359 <dt>data </dt>
5360 <dd class="description">Pointer to credential data</dd>
5361 <dt>datalen </dt>
5362 <dd class="description">Credential length</dd>
5363 </dl>
5364 <h3 class="struct"><a name="pollfd">pollfd</a></h3>
5365 <p class="description">User data (unused)</p>
5366 <p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br>
5367 &nbsp;&nbsp;&nbsp;&nbsp;void) context;<br>
5368 &nbsp;&nbsp;&nbsp;&nbsp;void) timeout;<br>
5369 };</p>
5370 <h4 class="members">Members</h4>
5371 <dl>
5372 <dt>context </dt>
5373 <dt>timeout </dt>
5374 </dl>
5375 <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2>
5376 <h3 class="enumeration"><a name="http_auth_e">http_auth_e</a></h3>
5377 <p class="description">HTTP authentication types</p>
5378 <h4 class="constants">Constants</h4>
5379 <dl>
5380 <dt>HTTP_AUTH_BASIC </dt>
5381 <dd class="description">Basic authentication in use</dd>
5382 <dt>HTTP_AUTH_MD5 </dt>
5383 <dd class="description">Digest authentication in use</dd>
5384 <dt>HTTP_AUTH_MD5_INT </dt>
5385 <dd class="description">Digest authentication in use for body</dd>
5386 <dt>HTTP_AUTH_MD5_SESS </dt>
5387 <dd class="description">MD5-session authentication in use</dd>
5388 <dt>HTTP_AUTH_MD5_SESS_INT </dt>
5389 <dd class="description">MD5-session authentication in use for body</dd>
5390 <dt>HTTP_AUTH_NEGOTIATE <span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span></dt>
5391 <dd class="description">GSSAPI authentication in use </dd>
5392 <dt>HTTP_AUTH_NONE </dt>
5393 <dd class="description">No authentication in use</dd>
5394 </dl>
5395 <h3 class="enumeration"><a name="http_encoding_e">http_encoding_e</a></h3>
5396 <p class="description">HTTP transfer encoding values</p>
5397 <h4 class="constants">Constants</h4>
5398 <dl>
5399 <dt>HTTP_ENCODING_CHUNKED </dt>
5400 <dd class="description">Data is chunked</dd>
5401 <dt>HTTP_ENCODING_FIELDS </dt>
5402 <dd class="description">Sending HTTP fields</dd>
5403 <dt>HTTP_ENCODING_LENGTH </dt>
5404 <dd class="description">Data is sent with Content-Length</dd>
5405 </dl>
5406 <h3 class="enumeration"><a name="http_encryption_e">http_encryption_e</a></h3>
5407 <p class="description">HTTP encryption values</p>
5408 <h4 class="constants">Constants</h4>
5409 <dl>
5410 <dt>HTTP_ENCRYPTION_ALWAYS </dt>
5411 <dd class="description">Always encrypt (SSL)</dd>
5412 <dt>HTTP_ENCRYPTION_IF_REQUESTED </dt>
5413 <dd class="description">Encrypt if requested (TLS upgrade)</dd>
5414 <dt>HTTP_ENCRYPTION_NEVER </dt>
5415 <dd class="description">Never encrypt</dd>
5416 <dt>HTTP_ENCRYPTION_REQUIRED </dt>
5417 <dd class="description">Encryption is required (TLS upgrade)</dd>
5418 </dl>
5419 <h3 class="enumeration"><a name="http_field_e">http_field_e</a></h3>
5420 <p class="description">HTTP field names</p>
5421 <h4 class="constants">Constants</h4>
5422 <dl>
5423 <dt>HTTP_FIELD_ACCEPT_ENCODING <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5424 <dd class="description">Accepting-Encoding field </dd>
5425 <dt>HTTP_FIELD_ACCEPT_LANGUAGE </dt>
5426 <dd class="description">Accept-Language field</dd>
5427 <dt>HTTP_FIELD_ACCEPT_RANGES </dt>
5428 <dd class="description">Accept-Ranges field</dd>
5429 <dt>HTTP_FIELD_ALLOW <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5430 <dd class="description">Allow field </dd>
5431 <dt>HTTP_FIELD_AUTHORIZATION </dt>
5432 <dd class="description">Authorization field</dd>
5433 <dt>HTTP_FIELD_CONNECTION </dt>
5434 <dd class="description">Connection field</dd>
5435 <dt>HTTP_FIELD_CONTENT_ENCODING </dt>
5436 <dd class="description">Content-Encoding field</dd>
5437 <dt>HTTP_FIELD_CONTENT_LANGUAGE </dt>
5438 <dd class="description">Content-Language field</dd>
5439 <dt>HTTP_FIELD_CONTENT_LENGTH </dt>
5440 <dd class="description">Content-Length field</dd>
5441 <dt>HTTP_FIELD_CONTENT_LOCATION </dt>
5442 <dd class="description">Content-Location field</dd>
5443 <dt>HTTP_FIELD_CONTENT_MD5 </dt>
5444 <dd class="description">Content-MD5 field</dd>
5445 <dt>HTTP_FIELD_CONTENT_RANGE </dt>
5446 <dd class="description">Content-Range field</dd>
5447 <dt>HTTP_FIELD_CONTENT_TYPE </dt>
5448 <dd class="description">Content-Type field</dd>
5449 <dt>HTTP_FIELD_CONTENT_VERSION </dt>
5450 <dd class="description">Content-Version field</dd>
5451 <dt>HTTP_FIELD_DATE </dt>
5452 <dd class="description">Date field</dd>
5453 <dt>HTTP_FIELD_HOST </dt>
5454 <dd class="description">Host field</dd>
5455 <dt>HTTP_FIELD_IF_MODIFIED_SINCE </dt>
5456 <dd class="description">If-Modified-Since field</dd>
5457 <dt>HTTP_FIELD_IF_UNMODIFIED_SINCE </dt>
5458 <dd class="description">If-Unmodified-Since field</dd>
5459 <dt>HTTP_FIELD_KEEP_ALIVE </dt>
5460 <dd class="description">Keep-Alive field</dd>
5461 <dt>HTTP_FIELD_LAST_MODIFIED </dt>
5462 <dd class="description">Last-Modified field</dd>
5463 <dt>HTTP_FIELD_LINK </dt>
5464 <dd class="description">Link field</dd>
5465 <dt>HTTP_FIELD_LOCATION </dt>
5466 <dd class="description">Location field</dd>
5467 <dt>HTTP_FIELD_MAX </dt>
5468 <dd class="description">Maximum field index</dd>
5469 <dt>HTTP_FIELD_RANGE </dt>
5470 <dd class="description">Range field</dd>
5471 <dt>HTTP_FIELD_REFERER </dt>
5472 <dd class="description">Referer field</dd>
5473 <dt>HTTP_FIELD_RETRY_AFTER </dt>
5474 <dd class="description">Retry-After field</dd>
5475 <dt>HTTP_FIELD_SERVER <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5476 <dd class="description">Server field </dd>
5477 <dt>HTTP_FIELD_TRANSFER_ENCODING </dt>
5478 <dd class="description">Transfer-Encoding field</dd>
5479 <dt>HTTP_FIELD_UNKNOWN </dt>
5480 <dd class="description">Unknown field</dd>
5481 <dt>HTTP_FIELD_UPGRADE </dt>
5482 <dd class="description">Upgrade field</dd>
5483 <dt>HTTP_FIELD_USER_AGENT </dt>
5484 <dd class="description">User-Agent field</dd>
5485 <dt>HTTP_FIELD_WWW_AUTHENTICATE </dt>
5486 <dd class="description">WWW-Authenticate field</dd>
5487 </dl>
5488 <h3 class="enumeration"><a name="http_keepalive_e">http_keepalive_e</a></h3>
5489 <p class="description">HTTP keep-alive values</p>
5490 <h4 class="constants">Constants</h4>
5491 <dl>
5492 <dt>HTTP_KEEPALIVE_OFF </dt>
5493 <dd class="description">No keep alive support</dd>
5494 <dt>HTTP_KEEPALIVE_ON </dt>
5495 <dd class="description">Use keep alive</dd>
5496 </dl>
5497 <h3 class="enumeration"><a name="http_state_e">http_state_e</a></h3>
5498 <p class="description">HTTP state values; states
5499 are server-oriented...</p>
5500 <h4 class="constants">Constants</h4>
5501 <dl>
5502 <dt>HTTP_STATE_CONNECT </dt>
5503 <dd class="description">CONNECT command, waiting for blank line</dd>
5504 <dt>HTTP_STATE_DELETE </dt>
5505 <dd class="description">DELETE command, waiting for blank line</dd>
5506 <dt>HTTP_STATE_ERROR </dt>
5507 <dd class="description">Error on socket</dd>
5508 <dt>HTTP_STATE_GET </dt>
5509 <dd class="description">GET command, waiting for blank line</dd>
5510 <dt>HTTP_STATE_GET_SEND </dt>
5511 <dd class="description">GET command, sending data</dd>
5512 <dt>HTTP_STATE_HEAD </dt>
5513 <dd class="description">HEAD command, waiting for blank line</dd>
5514 <dt>HTTP_STATE_OPTIONS </dt>
5515 <dd class="description">OPTIONS command, waiting for blank line</dd>
5516 <dt>HTTP_STATE_POST </dt>
5517 <dd class="description">POST command, waiting for blank line</dd>
5518 <dt>HTTP_STATE_POST_RECV </dt>
5519 <dd class="description">POST command, receiving data</dd>
5520 <dt>HTTP_STATE_POST_SEND </dt>
5521 <dd class="description">POST command, sending data</dd>
5522 <dt>HTTP_STATE_PUT </dt>
5523 <dd class="description">PUT command, waiting for blank line</dd>
5524 <dt>HTTP_STATE_PUT_RECV </dt>
5525 <dd class="description">PUT command, receiving data</dd>
5526 <dt>HTTP_STATE_STATUS </dt>
5527 <dd class="description">Command complete, sending status</dd>
5528 <dt>HTTP_STATE_TRACE </dt>
5529 <dd class="description">TRACE command, waiting for blank line</dd>
5530 <dt>HTTP_STATE_UNKNOWN_METHOD <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5531 <dd class="description">Unknown request method, waiting for blank line </dd>
5532 <dt>HTTP_STATE_UNKNOWN_VERSION <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5533 <dd class="description">Unknown request method, waiting for blank line </dd>
5534 <dt>HTTP_STATE_WAITING </dt>
5535 <dd class="description">Waiting for command</dd>
5536 </dl>
5537 <h3 class="enumeration"><a name="http_status_e">http_status_e</a></h3>
5538 <p class="description">HTTP status codes</p>
5539 <h4 class="constants">Constants</h4>
5540 <dl>
5541 <dt>CUPS_STATUS_AUTHORIZATION_CANCELED <span class="info">&nbsp;CUPS 1.4&nbsp;</span></dt>
5542 <dd class="description">User canceled authorization </dd>
5543 <dt>CUPS_STATUS_PKI_ERROR <span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span></dt>
5544 <dd class="description">Error negotiating a secure connection </dd>
5545 <dt>HTTP_STATUS_ACCEPTED </dt>
5546 <dd class="description">DELETE command was successful</dd>
5547 <dt>HTTP_STATUS_BAD_GATEWAY </dt>
5548 <dd class="description">Bad gateway</dd>
5549 <dt>HTTP_STATUS_BAD_REQUEST </dt>
5550 <dd class="description">Bad request</dd>
5551 <dt>HTTP_STATUS_CONFLICT </dt>
5552 <dd class="description">Request is self-conflicting</dd>
5553 <dt>HTTP_STATUS_CONTINUE </dt>
5554 <dd class="description">Everything OK, keep going...</dd>
5555 <dt>HTTP_STATUS_CREATED </dt>
5556 <dd class="description">PUT command was successful</dd>
5557 <dt>HTTP_STATUS_ERROR </dt>
5558 <dd class="description">An error response from httpXxxx()</dd>
5559 <dt>HTTP_STATUS_EXPECTATION_FAILED </dt>
5560 <dd class="description">The expectation given in an Expect header field was not met</dd>
5561 <dt>HTTP_STATUS_FORBIDDEN </dt>
5562 <dd class="description">Forbidden to access this URI</dd>
5563 <dt>HTTP_STATUS_GATEWAY_TIMEOUT </dt>
5564 <dd class="description">Gateway connection timed out</dd>
5565 <dt>HTTP_STATUS_GONE </dt>
5566 <dd class="description">Server has gone away</dd>
5567 <dt>HTTP_STATUS_LENGTH_REQUIRED </dt>
5568 <dd class="description">A content length or encoding is required</dd>
5569 <dt>HTTP_STATUS_METHOD_NOT_ALLOWED </dt>
5570 <dd class="description">Method is not allowed</dd>
5571 <dt>HTTP_STATUS_MOVED_PERMANENTLY </dt>
5572 <dd class="description">Document has moved permanently</dd>
5573 <dt>HTTP_STATUS_MOVED_TEMPORARILY </dt>
5574 <dd class="description">Document has moved temporarily</dd>
5575 <dt>HTTP_STATUS_MULTIPLE_CHOICES </dt>
5576 <dd class="description">Multiple files match request</dd>
5577 <dt>HTTP_STATUS_NONE <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
5578 <dd class="description">No Expect value </dd>
5579 <dt>HTTP_STATUS_NOT_ACCEPTABLE </dt>
5580 <dd class="description">Not Acceptable</dd>
5581 <dt>HTTP_STATUS_NOT_AUTHORITATIVE </dt>
5582 <dd class="description">Information isn't authoritative</dd>
5583 <dt>HTTP_STATUS_NOT_FOUND </dt>
5584 <dd class="description">URI was not found</dd>
5585 <dt>HTTP_STATUS_NOT_IMPLEMENTED </dt>
5586 <dd class="description">Feature not implemented</dd>
5587 <dt>HTTP_STATUS_NOT_MODIFIED </dt>
5588 <dd class="description">File not modified</dd>
5589 <dt>HTTP_STATUS_NOT_SUPPORTED </dt>
5590 <dd class="description">HTTP version not supported</dd>
5591 <dt>HTTP_STATUS_NO_CONTENT </dt>
5592 <dd class="description">Successful command, no new data</dd>
5593 <dt>HTTP_STATUS_OK </dt>
5594 <dd class="description">OPTIONS/GET/HEAD/POST/TRACE command was successful</dd>
5595 <dt>HTTP_STATUS_PARTIAL_CONTENT </dt>
5596 <dd class="description">Only a partial file was recieved/sent</dd>
5597 <dt>HTTP_STATUS_PAYMENT_REQUIRED </dt>
5598 <dd class="description">Payment required</dd>
5599 <dt>HTTP_STATUS_PRECONDITION </dt>
5600 <dd class="description">Precondition failed</dd>
5601 <dt>HTTP_STATUS_PROXY_AUTHENTICATION </dt>
5602 <dd class="description">Proxy Authentication is Required</dd>
5603 <dt>HTTP_STATUS_REQUESTED_RANGE </dt>
5604 <dd class="description">The requested range is not satisfiable</dd>
5605 <dt>HTTP_STATUS_REQUEST_TIMEOUT </dt>
5606 <dd class="description">Request timed out</dd>
5607 <dt>HTTP_STATUS_REQUEST_TOO_LARGE </dt>
5608 <dd class="description">Request entity too large</dd>
5609 <dt>HTTP_STATUS_RESET_CONTENT </dt>
5610 <dd class="description">Content was reset/recreated</dd>
5611 <dt>HTTP_STATUS_SEE_OTHER </dt>
5612 <dd class="description">See this other link...</dd>
5613 <dt>HTTP_STATUS_SERVER_ERROR </dt>
5614 <dd class="description">Internal server error</dd>
5615 <dt>HTTP_STATUS_SERVICE_UNAVAILABLE </dt>
5616 <dd class="description">Service is unavailable</dd>
5617 <dt>HTTP_STATUS_SWITCHING_PROTOCOLS </dt>
5618 <dd class="description">HTTP upgrade to TLS/SSL</dd>
5619 <dt>HTTP_STATUS_UNAUTHORIZED </dt>
5620 <dd class="description">Unauthorized to access host</dd>
5621 <dt>HTTP_STATUS_UNSUPPORTED_MEDIATYPE </dt>
5622 <dd class="description">The requested media type is unsupported</dd>
5623 <dt>HTTP_STATUS_UPGRADE_REQUIRED </dt>
5624 <dd class="description">Upgrade to SSL/TLS required</dd>
5625 <dt>HTTP_STATUS_URI_TOO_LONG </dt>
5626 <dd class="description">URI too long</dd>
5627 <dt>HTTP_STATUS_USE_PROXY </dt>
5628 <dd class="description">Must use a proxy to access this URI</dd>
5629 </dl>
5630 <h3 class="enumeration"><a name="http_uri_coding_e">http_uri_coding_e</a></h3>
5631 <p class="description">URI en/decode flags</p>
5632 <h4 class="constants">Constants</h4>
5633 <dl>
5634 <dt>HTTP_URI_CODING_ALL </dt>
5635 <dd class="description">En/decode everything</dd>
5636 <dt>HTTP_URI_CODING_HOSTNAME </dt>
5637 <dd class="description">En/decode the hostname portion</dd>
5638 <dt>HTTP_URI_CODING_MOST </dt>
5639 <dd class="description">En/decode all but the query</dd>
5640 <dt>HTTP_URI_CODING_NONE </dt>
5641 <dd class="description">Don't en/decode anything</dd>
5642 <dt>HTTP_URI_CODING_QUERY </dt>
5643 <dd class="description">En/decode the query portion</dd>
5644 <dt>HTTP_URI_CODING_RESOURCE </dt>
5645 <dd class="description">En/decode the resource portion</dd>
5646 <dt>HTTP_URI_CODING_USERNAME </dt>
5647 <dd class="description">En/decode the username portion</dd>
5648 </dl>
5649 <h3 class="enumeration"><span class="info">&nbsp;CUPS 1.2&nbsp;</span><a name="http_uri_status_e">http_uri_status_e</a></h3>
5650 <p class="description">URI separation status </p>
5651 <h4 class="constants">Constants</h4>
5652 <dl>
5653 <dt>HTTP_URI_STATUS_BAD_ARGUMENTS </dt>
5654 <dd class="description">Bad arguments to function (error)</dd>
5655 <dt>HTTP_URI_STATUS_BAD_HOSTNAME </dt>
5656 <dd class="description">Bad hostname in URI (error)</dd>
5657 <dt>HTTP_URI_STATUS_BAD_PORT </dt>
5658 <dd class="description">Bad port number in URI (error)</dd>
5659 <dt>HTTP_URI_STATUS_BAD_RESOURCE </dt>
5660 <dd class="description">Bad resource in URI (error)</dd>
5661 <dt>HTTP_URI_STATUS_BAD_SCHEME </dt>
5662 <dd class="description">Bad scheme in URI (error)</dd>
5663 <dt>HTTP_URI_STATUS_BAD_URI </dt>
5664 <dd class="description">Bad/empty URI (error)</dd>
5665 <dt>HTTP_URI_STATUS_BAD_USERNAME </dt>
5666 <dd class="description">Bad username in URI (error)</dd>
5667 <dt>HTTP_URI_STATUS_MISSING_RESOURCE </dt>
5668 <dd class="description">Missing resource in URI (warning)</dd>
5669 <dt>HTTP_URI_STATUS_MISSING_SCHEME </dt>
5670 <dd class="description">Missing scheme in URI (warning)</dd>
5671 <dt>HTTP_URI_STATUS_OK </dt>
5672 <dd class="description">URI decoded OK</dd>
5673 <dt>HTTP_URI_STATUS_OVERFLOW </dt>
5674 <dd class="description">URI buffer for httpAssembleURI is too small</dd>
5675 <dt>HTTP_URI_STATUS_UNKNOWN_SCHEME </dt>
5676 <dd class="description">Unknown scheme in URI (warning)</dd>
5677 </dl>
5678 <h3 class="enumeration"><a name="http_version_e">http_version_e</a></h3>
5679 <p class="description">HTTP version numbers</p>
5680 <h4 class="constants">Constants</h4>
5681 <dl>
5682 <dt>HTTP_VERSION_0_9 </dt>
5683 <dd class="description">HTTP/0.9</dd>
5684 <dt>HTTP_VERSION_1_0 </dt>
5685 <dd class="description">HTTP/1.0</dd>
5686 <dt>HTTP_VERSION_1_1 </dt>
5687 <dd class="description">HTTP/1.1</dd>
5688 </dl>
5689 <h3 class="enumeration"><a name="ipp_dstate_e">ipp_dstate_e</a></h3>
5690 <p class="description">Document states</p>
5691 <h4 class="constants">Constants</h4>
5692 <dl>
5693 <dt>IPP_DOCUMENT_ABORTED </dt>
5694 <dd class="description">Document is aborted</dd>
5695 <dt>IPP_DOCUMENT_CANCELED </dt>
5696 <dd class="description">Document is canceled</dd>
5697 <dt>IPP_DOCUMENT_COMPLETED </dt>
5698 <dd class="description">Document is completed</dd>
5699 <dt>IPP_DOCUMENT_PENDING </dt>
5700 <dd class="description">Document is pending</dd>
5701 <dt>IPP_DOCUMENT_PROCESSING </dt>
5702 <dd class="description">Document is processing</dd>
5703 </dl>
5704 <h3 class="enumeration"><a name="ipp_finishings_e">ipp_finishings_e</a></h3>
5705 <p class="description">Finishings</p>
5706 <h4 class="constants">Constants</h4>
5707 <dl>
5708 <dt>IPP_FINISHINGS_BALE </dt>
5709 <dd class="description">Bale (any type)</dd>
5710 <dt>IPP_FINISHINGS_BIND </dt>
5711 <dd class="description">Bind</dd>
5712 <dt>IPP_FINISHINGS_BIND_BOTTOM </dt>
5713 <dd class="description">Bind on bottom</dd>
5714 <dt>IPP_FINISHINGS_BIND_LEFT </dt>
5715 <dd class="description">Bind on left</dd>
5716 <dt>IPP_FINISHINGS_BIND_RIGHT </dt>
5717 <dd class="description">Bind on right</dd>
5718 <dt>IPP_FINISHINGS_BIND_TOP </dt>
5719 <dd class="description">Bind on top</dd>
5720 <dt>IPP_FINISHINGS_BOOKLET_MAKER </dt>
5721 <dd class="description">Fold to make booklet</dd>
5722 <dt>IPP_FINISHINGS_COVER </dt>
5723 <dd class="description">Add cover</dd>
5724 <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_LEFT </dt>
5725 <dd class="description">Punch 1 hole bottom left</dd>
5726 <dt>IPP_FINISHINGS_CUPS_PUNCH_BOTTOM_RIGHT </dt>
5727 <dd class="description">Punch 1 hole bottom right</dd>
5728 <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_BOTTOM </dt>
5729 <dd class="description">Punch 2 holes bottom edge</dd>
5730 <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_LEFT </dt>
5731 <dd class="description">Punch 2 holes left side</dd>
5732 <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_RIGHT </dt>
5733 <dd class="description">Punch 2 holes right side</dd>
5734 <dt>IPP_FINISHINGS_CUPS_PUNCH_DUAL_TOP </dt>
5735 <dd class="description">Punch 2 holes top edge</dd>
5736 <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_BOTTOM </dt>
5737 <dd class="description">Punch 4 holes bottom edge</dd>
5738 <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_LEFT </dt>
5739 <dd class="description">Punch 4 holes left side</dd>
5740 <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_RIGHT </dt>
5741 <dd class="description">Punch 4 holes right side</dd>
5742 <dt>IPP_FINISHINGS_CUPS_PUNCH_QUAD_TOP </dt>
5743 <dd class="description">Punch 4 holes top edge</dd>
5744 <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_LEFT </dt>
5745 <dd class="description">Punch 1 hole top left</dd>
5746 <dt>IPP_FINISHINGS_CUPS_PUNCH_TOP_RIGHT </dt>
5747 <dd class="description">Punch 1 hole top right</dd>
5748 <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_BOTTOM </dt>
5749 <dd class="description">Punch 3 holes bottom edge</dd>
5750 <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_LEFT </dt>
5751 <dd class="description">Punch 3 holes left side</dd>
5752 <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_RIGHT </dt>
5753 <dd class="description">Punch 3 holes right side</dd>
5754 <dt>IPP_FINISHINGS_CUPS_PUNCH_TRIPLE_TOP </dt>
5755 <dd class="description">Punch 3 holes top edge</dd>
5756 <dt>IPP_FINISHINGS_EDGE_STITCH </dt>
5757 <dd class="description">Stitch along any side</dd>
5758 <dt>IPP_FINISHINGS_EDGE_STITCH_BOTTOM </dt>
5759 <dd class="description">Stitch along bottom edge</dd>
5760 <dt>IPP_FINISHINGS_EDGE_STITCH_LEFT </dt>
5761 <dd class="description">Stitch along left side</dd>
5762 <dt>IPP_FINISHINGS_EDGE_STITCH_RIGHT </dt>
5763 <dd class="description">Stitch along right side</dd>
5764 <dt>IPP_FINISHINGS_EDGE_STITCH_TOP </dt>
5765 <dd class="description">Stitch along top edge</dd>
5766 <dt>IPP_FINISHINGS_FOLD </dt>
5767 <dd class="description">Fold (any type)</dd>
5768 <dt>IPP_FINISHINGS_JOB_OFFSET </dt>
5769 <dd class="description">Offset for binding (any type)</dd>
5770 <dt>IPP_FINISHINGS_NONE </dt>
5771 <dd class="description">No finishing</dd>
5772 <dt>IPP_FINISHINGS_PUNCH </dt>
5773 <dd class="description">Punch (any location/count)</dd>
5774 <dt>IPP_FINISHINGS_SADDLE_STITCH </dt>
5775 <dd class="description">Staple interior</dd>
5776 <dt>IPP_FINISHINGS_STAPLE </dt>
5777 <dd class="description">Staple (any location)</dd>
5778 <dt>IPP_FINISHINGS_STAPLE_BOTTOM_LEFT </dt>
5779 <dd class="description">Staple bottom left corner</dd>
5780 <dt>IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT </dt>
5781 <dd class="description">Staple bottom right corner</dd>
5782 <dt>IPP_FINISHINGS_STAPLE_DUAL_BOTTOM </dt>
5783 <dd class="description">Two staples on bottom</dd>
5784 <dt>IPP_FINISHINGS_STAPLE_DUAL_LEFT </dt>
5785 <dd class="description">Two staples on left</dd>
5786 <dt>IPP_FINISHINGS_STAPLE_DUAL_RIGHT </dt>
5787 <dd class="description">Two staples on right</dd>
5788 <dt>IPP_FINISHINGS_STAPLE_DUAL_TOP </dt>
5789 <dd class="description">Two staples on top</dd>
5790 <dt>IPP_FINISHINGS_STAPLE_TOP_LEFT </dt>
5791 <dd class="description">Staple top left corner</dd>
5792 <dt>IPP_FINISHINGS_STAPLE_TOP_RIGHT </dt>
5793 <dd class="description">Staple top right corner</dd>
5794 <dt>IPP_FINISHINGS_TRIM </dt>
5795 <dd class="description">Trim (any type)</dd>
5796 <dt>IPP_FINISHINGS_TRIM_AFTER_COPIES </dt>
5797 <dd class="description">Trim output after each copy</dd>
5798 <dt>IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS </dt>
5799 <dd class="description">Trim output after each document</dd>
5800 <dt>IPP_FINISHINGS_TRIM_AFTER_JOB </dt>
5801 <dd class="description">Trim output after job</dd>
5802 <dt>IPP_FINISHINGS_TRIM_AFTER_PAGES </dt>
5803 <dd class="description">Trim output after each page</dd>
5804 </dl>
5805 <h3 class="enumeration"><a name="ipp_jcollate_e">ipp_jcollate_e</a></h3>
5806 <p class="description">Job collation types</p>
5807 <h4 class="constants">Constants</h4>
5808 <dl>
5809 <dt>IPP_JCOLLATE_COLLATED_DOCUMENTS </dt>
5810 <dt>IPP_JCOLLATE_UNCOLLATED_DOCUMENTS </dt>
5811 <dt>IPP_JCOLLATE_UNCOLLATED_SHEETS </dt>
5812 </dl>
5813 <h3 class="enumeration"><a name="ipp_jstate_e">ipp_jstate_e</a></h3>
5814 <p class="description">Job states</p>
5815 <h4 class="constants">Constants</h4>
5816 <dl>
5817 <dt>IPP_JSTATE_ABORTED </dt>
5818 <dd class="description">Job has aborted due to error</dd>
5819 <dt>IPP_JSTATE_CANCELED </dt>
5820 <dd class="description">Job has been canceled</dd>
5821 <dt>IPP_JSTATE_COMPLETED </dt>
5822 <dd class="description">Job has completed successfully</dd>
5823 <dt>IPP_JSTATE_HELD </dt>
5824 <dd class="description">Job is held for printing</dd>
5825 <dt>IPP_JSTATE_PENDING </dt>
5826 <dd class="description">Job is waiting to be printed</dd>
5827 <dt>IPP_JSTATE_PROCESSING </dt>
5828 <dd class="description">Job is currently printing</dd>
5829 <dt>IPP_JSTATE_STOPPED </dt>
5830 <dd class="description">Job has been stopped</dd>
5831 </dl>
5832 <h3 class="enumeration"><a name="ipp_op_e">ipp_op_e</a></h3>
5833 <p class="description">IPP operations</p>
5834 <h4 class="constants">Constants</h4>
5835 <dl>
5836 <dt>IPP_OP_CANCEL_JOB </dt>
5837 <dd class="description">Cancel a job</dd>
5838 <dt>IPP_OP_CANCEL_JOBS </dt>
5839 <dd class="description">Cancel-Jobs</dd>
5840 <dt>IPP_OP_CANCEL_MY_JOBS </dt>
5841 <dd class="description">Cancel-My-Jobs</dd>
5842 <dt>IPP_OP_CANCEL_SUBSCRIPTION <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5843 <dd class="description">Cancel a subscription </dd>
5844 <dt>IPP_OP_CLOSE_JOB </dt>
5845 <dd class="description">Close-Job</dd>
5846 <dt>IPP_OP_CREATE_JOB </dt>
5847 <dd class="description">Create an empty print job</dd>
5848 <dt>IPP_OP_CREATE_JOB_SUBSCRIPTION <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5849 <dd class="description">Create a job subscription </dd>
5850 <dt>IPP_OP_CREATE_PRINTER_SUBSCRIPTION <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5851 <dd class="description">Create a printer subscription </dd>
5852 <dt>IPP_OP_CUPS_ACCEPT_JOBS </dt>
5853 <dd class="description">Accept new jobs on a printer</dd>
5854 <dt>IPP_OP_CUPS_ADD_MODIFY_CLASS </dt>
5855 <dd class="description">Add or modify a class</dd>
5856 <dt>IPP_OP_CUPS_ADD_MODIFY_PRINTER </dt>
5857 <dd class="description">Add or modify a printer</dd>
5858 <dt>IPP_OP_CUPS_AUTHENTICATE_JOB <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5859 <dd class="description">Authenticate a job </dd>
5860 <dt>IPP_OP_CUPS_DELETE_CLASS </dt>
5861 <dd class="description">Delete a class</dd>
5862 <dt>IPP_OP_CUPS_DELETE_PRINTER </dt>
5863 <dd class="description">Delete a printer</dd>
5864 <dt>IPP_OP_CUPS_GET_CLASSES <span class="info">&nbsp;DEPRECATED&nbsp;</span></dt>
5865 <dd class="description">Get a list of classes </dd>
5866 <dt>IPP_OP_CUPS_GET_DEFAULT </dt>
5867 <dd class="description">Get the default printer</dd>
5868 <dt>IPP_OP_CUPS_GET_DEVICES </dt>
5869 <dd class="description">Get a list of supported devices</dd>
5870 <dt>IPP_OP_CUPS_GET_DOCUMENT <span class="info">&nbsp;CUPS 1.4/OS X 10.6&nbsp;</span></dt>
5871 <dd class="description">Get a document file </dd>
5872 <dt>IPP_OP_CUPS_GET_PPD <span class="info">&nbsp;CUPS 1.3/OS X 10.5&nbsp;</span></dt>
5873 <dd class="description">Get a PPD file </dd>
5874 <dt>IPP_OP_CUPS_GET_PPDS </dt>
5875 <dd class="description">Get a list of supported drivers</dd>
5876 <dt>IPP_OP_CUPS_GET_PRINTERS </dt>
5877 <dd class="description">Get a list of printers and/or classes</dd>
5878 <dt>IPP_OP_CUPS_INVALID </dt>
5879 <dd class="description">Invalid operation name for <a href="#ippOpValue"><code>ippOpValue</code></a></dd>
5880 <dt>IPP_OP_CUPS_MOVE_JOB </dt>
5881 <dd class="description">Move a job to a different printer</dd>
5882 <dt>IPP_OP_CUPS_REJECT_JOBS </dt>
5883 <dd class="description">Reject new jobs on a printer</dd>
5884 <dt>IPP_OP_CUPS_SET_DEFAULT </dt>
5885 <dd class="description">Set the default printer</dd>
5886 <dt>IPP_OP_DISABLE_PRINTER </dt>
5887 <dd class="description">Stop a printer</dd>
5888 <dt>IPP_OP_ENABLE_PRINTER </dt>
5889 <dd class="description">Start a printer</dd>
5890 <dt>IPP_OP_GET_JOBS </dt>
5891 <dd class="description">Get a list of jobs</dd>
5892 <dt>IPP_OP_GET_JOB_ATTRIBUTES </dt>
5893 <dd class="description">Get job attributes</dd>
5894 <dt>IPP_OP_GET_NOTIFICATIONS <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5895 <dd class="description">Get notification events </dd>
5896 <dt>IPP_OP_GET_PRINTER_ATTRIBUTES </dt>
5897 <dd class="description">Get printer attributes</dd>
5898 <dt>IPP_OP_GET_PRINTER_SUPPORTED_VALUES </dt>
5899 <dd class="description">Get supported attribute values</dd>
5900 <dt>IPP_OP_GET_SUBSCRIPTIONS <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5901 <dd class="description">Get list of subscriptions </dd>
5902 <dt>IPP_OP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5903 <dd class="description">Get subscription attributes </dd>
5904 <dt>IPP_OP_HOLD_JOB </dt>
5905 <dd class="description">Hold a job for printing</dd>
5906 <dt>IPP_OP_IDENTIFY_PRINTER </dt>
5907 <dd class="description">Identify-Printer (proposed IPP JPS3)</dd>
5908 <dt>IPP_OP_PAUSE_PRINTER </dt>
5909 <dd class="description">Stop a printer</dd>
5910 <dt>IPP_OP_PRINT_JOB </dt>
5911 <dd class="description">Print a single file</dd>
5912 <dt>IPP_OP_PURGE_JOBS </dt>
5913 <dd class="description">Cancel all jobs</dd>
5914 <dt>IPP_OP_RELEASE_JOB </dt>
5915 <dd class="description">Release a job for printing</dd>
5916 <dt>IPP_OP_RENEW_SUBSCRIPTION <span class="info">&nbsp;CUPS 1.2/OS X 10.5&nbsp;</span></dt>
5917 <dd class="description">Renew a printer subscription </dd>
5918 <dt>IPP_OP_RESTART_JOB </dt>
5919 <dd class="description">Reprint a job</dd>
5920 <dt>IPP_OP_RESUBMIT_JOB </dt>
5921 <dd class="description">Resubmit-Job</dd>
5922 <dt>IPP_OP_RESUME_PRINTER </dt>
5923 <dd class="description">Start a printer</dd>
5924 <dt>IPP_OP_SEND_DOCUMENT </dt>
5925 <dd class="description">Add a file to a job</dd>
5926 <dt>IPP_OP_SET_JOB_ATTRIBUTES </dt>
5927 <dd class="description">Set job attributes</dd>
5928 <dt>IPP_OP_VALIDATE_DOCUMENT </dt>
5929 <dd class="description">Validate-Document (proposed IPP JPS3)</dd>
5930 <dt>IPP_OP_VALIDATE_JOB </dt>
5931 <dd class="description">Validate job options</dd>
5932 </dl>
5933 <h3 class="enumeration"><a name="ipp_orient_e">ipp_orient_e</a></h3>
5934 <p class="description">Orientation values</p>
5935 <h4 class="constants">Constants</h4>
5936 <dl>
5937 <dt>IPP_ORIENT_LANDSCAPE </dt>
5938 <dd class="description">90 degrees counter-clockwise</dd>
5939 <dt>IPP_ORIENT_PORTRAIT </dt>
5940 <dd class="description">No rotation</dd>
5941 <dt>IPP_ORIENT_REVERSE_LANDSCAPE </dt>
5942 <dd class="description">90 degrees clockwise</dd>
5943 <dt>IPP_ORIENT_REVERSE_PORTRAIT </dt>
5944 <dd class="description">180 degrees</dd>
5945 </dl>
5946 <h3 class="enumeration"><a name="ipp_pstate_e">ipp_pstate_e</a></h3>
5947 <p class="description">Printer states</p>
5948 <h4 class="constants">Constants</h4>
5949 <dl>
5950 <dt>IPP_PSTATE_IDLE </dt>
5951 <dd class="description">Printer is idle</dd>
5952 <dt>IPP_PSTATE_PROCESSING </dt>
5953 <dd class="description">Printer is working</dd>
5954 <dt>IPP_PSTATE_STOPPED </dt>
5955 <dd class="description">Printer is stopped</dd>
5956 </dl>
5957 <h3 class="enumeration"><a name="ipp_quality_e">ipp_quality_e</a></h3>
5958 <p class="description">Qualities</p>
5959 <h4 class="constants">Constants</h4>
5960 <dl>
5961 <dt>IPP_QUALITY_DRAFT </dt>
5962 <dd class="description">Draft quality</dd>
5963 <dt>IPP_QUALITY_HIGH </dt>
5964 <dd class="description">High quality</dd>
5965 <dt>IPP_QUALITY_NORMAL </dt>
5966 <dd class="description">Normal quality</dd>
5967 </dl>
5968 <h3 class="enumeration"><a name="ipp_res_e">ipp_res_e</a></h3>
5969 <p class="description">Resolution units</p>
5970 <h4 class="constants">Constants</h4>
5971 <dl>
5972 <dt>IPP_RES_PER_CM </dt>
5973 <dd class="description">Pixels per centimeter</dd>
5974 <dt>IPP_RES_PER_INCH </dt>
5975 <dd class="description">Pixels per inch</dd>
5976 </dl>
5977 <h3 class="enumeration"><a name="ipp_state_e">ipp_state_e</a></h3>
5978 <p class="description">IPP states</p>
5979 <h4 class="constants">Constants</h4>
5980 <dl>
5981 <dt>IPP_STATE_ATTRIBUTE </dt>
5982 <dd class="description">One or more attributes need to be sent/received</dd>
5983 <dt>IPP_STATE_DATA </dt>
5984 <dd class="description">IPP request data needs to be sent/received</dd>
5985 <dt>IPP_STATE_ERROR </dt>
5986 <dd class="description">An error occurred</dd>
5987 <dt>IPP_STATE_HEADER </dt>
5988 <dd class="description">The request header needs to be sent/received</dd>
5989 <dt>IPP_STATE_IDLE </dt>
5990 <dd class="description">Nothing is happening/request completed</dd>
5991 </dl>
5992 <h3 class="enumeration"><a name="ipp_status_e">ipp_status_e</a></h3>
5993 <p class="description">IPP status codes</p>
5994 <h4 class="constants">Constants</h4>
5995 <dl>
5996 <dt>IPP_STATUS_CUPS_INVALID </dt>
5997 <dd class="description">Invalid status name for <a href="#ippErrorValue"><code>ippErrorValue</code></a></dd>
5998 <dt>IPP_STATUS_CUPS_SEE_OTHER </dt>
5999 <dd class="description">cups-see-other</dd>
6000 <dt>IPP_STATUS_ERROR_ATTRIBUTES_NOT_SETTABLE </dt>
6001 <dd class="description">client-error-attributes-not-settable</dd>
6002 <dt>IPP_STATUS_ERROR_ATTRIBUTES_OR_VALUES </dt>
6003 <dd class="description">client-error-attributes-or-values-not-supported</dd>
6004 <dt>IPP_STATUS_ERROR_BAD_REQUEST </dt>
6005 <dd class="description">client-error-bad-request</dd>
6006 <dt>IPP_STATUS_ERROR_BUSY </dt>
6007 <dd class="description">server-error-busy</dd>
6008 <dt>IPP_STATUS_ERROR_CHARSET </dt>
6009 <dd class="description">client-error-charset-not-supported</dd>
6010 <dt>IPP_STATUS_ERROR_COMPRESSION_ERROR </dt>
6011 <dd class="description">client-error-compression-error</dd>
6012 <dt>IPP_STATUS_ERROR_COMPRESSION_NOT_SUPPORTED </dt>
6013 <dd class="description">client-error-compression-not-supported</dd>
6014 <dt>IPP_STATUS_ERROR_CONFLICTING </dt>
6015 <dd class="description">client-error-conflicting-attributes</dd>
6016 <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_AUTHORIZATION_FAILED <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
6017 <dd class="description">cups-error-account-authorization-failed </dd>
6018 <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_CLOSED <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
6019 <dd class="description">cups-error-account-closed </dd>
6020 <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_INFO_NEEDED <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
6021 <dd class="description">cups-error-account-info-needed </dd>
6022 <dt>IPP_STATUS_ERROR_CUPS_ACCOUNT_LIMIT_REACHED <span class="info">&nbsp;CUPS 1.7&nbsp;</span></dt>
6023 <dd class="description">cups-error-account-limit-reached </dd>
6024 <dt>IPP_STATUS_ERROR_CUPS_AUTHENTICATION_CANCELED <span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span></dt>
6025 <dd class="description">cups-authentication-canceled - Authentication canceled by user </dd>
6026 <dt>IPP_STATUS_ERROR_CUPS_PKI <span class="info">&nbsp;CUPS 1.5/OS X 10.7&nbsp;</span></dt>
6027 <dd class="description">cups-pki-error - Error negotiating a secure connection </dd>
6028 <dt>IPP_STATUS_ERROR_CUPS_UPGRADE_REQUIRED </dt>
6029 <dd class="description">cups-upgrade-required - TLS upgrade required</dd>
6030 <dt>IPP_STATUS_ERROR_DEVICE </dt>
6031 <dd class="description">server-error-device-error</dd>
6032 <dt>IPP_STATUS_ERROR_DOCUMENT_ACCESS </dt>
6033 <dd class="description">client-error-document-access-error</dd>
6034 <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_ERROR </dt>
6035 <dd class="description">client-error-document-format-error</dd>
6036 <dt>IPP_STATUS_ERROR_DOCUMENT_FORMAT_NOT_SUPPORTED </dt>
6037 <dd class="description">client-error-document-format-not-supported</dd>
6038 <dt>IPP_STATUS_ERROR_DOCUMENT_PASSWORD </dt>
6039 <dd class="description">client-error-document-password-error</dd>
6040 <dt>IPP_STATUS_ERROR_DOCUMENT_PERMISSION </dt>
6041 <dd class="description">client-error-document-permission-error</dd>
6042 <dt>IPP_STATUS_ERROR_DOCUMENT_SECURITY </dt>
6043 <dd class="description">client-error-document-security-error</dd>
6044 <dt>IPP_STATUS_ERROR_DOCUMENT_UNPRINTABLE </dt>
6045 <dd class="description">client-error-document-unprintable-error</dd>
6046 <dt>IPP_STATUS_ERROR_FORBIDDEN </dt>
6047 <dd class="description">client-error-forbidden</dd>
6048 <dt>IPP_STATUS_ERROR_GONE </dt>
6049 <dd class="description">client-error-gone</dd>
6050 <dt>IPP_STATUS_ERROR_IGNORED_ALL_SUBSCRIPTIONS </dt>
6051 <dd class="description">client-error-ignored-all-subscriptions</dd>
6052 <dt>IPP_STATUS_ERROR_INTERNAL </dt>
6053 <dd class="description">server-error-internal-error</dd>
6054 <dt>IPP_STATUS_ERROR_JOB_CANCELED </dt>
6055 <dd class="description">server-error-job-canceled</dd>
6056 <dt>IPP_STATUS_ERROR_MULTIPLE_JOBS_NOT_SUPPORTED </dt>
6057 <dd class="description">server-error-multiple-document-jobs-not-supported</dd>
6058 <dt>IPP_STATUS_ERROR_NOT_ACCEPTING_JOBS </dt>
6059 <dd class="description">server-error-not-accepting-jobs</dd>
6060 <dt>IPP_STATUS_ERROR_NOT_AUTHENTICATED </dt>
6061 <dd class="description">client-error-not-authenticated</dd>
6062 <dt>IPP_STATUS_ERROR_NOT_AUTHORIZED </dt>
6063 <dd class="description">client-error-not-authorized</dd>
6064 <dt>IPP_STATUS_ERROR_NOT_FOUND </dt>
6065 <dd class="description">client-error-not-found</dd>
6066 <dt>IPP_STATUS_ERROR_NOT_POSSIBLE </dt>
6067 <dd class="description">client-error-not-possible</dd>
6068 <dt>IPP_STATUS_ERROR_OPERATION_NOT_SUPPORTED </dt>
6069 <dd class="description">server-error-operation-not-supported</dd>
6070 <dt>IPP_STATUS_ERROR_PRINTER_IS_DEACTIVATED </dt>
6071 <dd class="description">server-error-printer-is-deactivated</dd>
6072 <dt>IPP_STATUS_ERROR_REQUEST_ENTITY </dt>
6073 <dd class="description">client-error-request-entity-too-large</dd>
6074 <dt>IPP_STATUS_ERROR_REQUEST_VALUE </dt>
6075 <dd class="description">client-error-request-value-too-long</dd>
6076 <dt>IPP_STATUS_ERROR_SERVICE_UNAVAILABLE </dt>
6077 <dd class="description">server-error-service-unavailable</dd>
6078 <dt>IPP_STATUS_ERROR_TEMPORARY </dt>
6079 <dd class="description">server-error-temporary-error</dd>
6080 <dt>IPP_STATUS_ERROR_TIMEOUT </dt>
6081 <dd class="description">client-error-timeout</dd>
6082 <dt>IPP_STATUS_ERROR_TOO_MANY_DOCUMENTS </dt>
6083 <dd class="description">server-error-too-many-documents</dd>
6084 <dt>IPP_STATUS_ERROR_TOO_MANY_JOBS </dt>
6085 <dd class="description">server-error-too-many-jobs</dd>
6086 <dt>IPP_STATUS_ERROR_TOO_MANY_SUBSCRIPTIONS </dt>
6087 <dd class="description">client-error-too-many-subscriptions</dd>
6088 <dt>IPP_STATUS_ERROR_URI_SCHEME </dt>
6089 <dd class="description">client-error-uri-scheme-not-supported</dd>
6090 <dt>IPP_STATUS_ERROR_VERSION_NOT_SUPPORTED </dt>
6091 <dd class="description">server-error-version-not-supported</dd>
6092 <dt>IPP_STATUS_OK </dt>
6093 <dd class="description">successful-ok</dd>
6094 <dt>IPP_STATUS_OK_CONFLICTING </dt>
6095 <dd class="description">successful-ok-conflicting-attributes</dd>
6096 <dt>IPP_STATUS_OK_EVENTS_COMPLETE </dt>
6097 <dd class="description">successful-ok-events-complete</dd>
6098 <dt>IPP_STATUS_OK_IGNORED_OR_SUBSTITUTED </dt>
6099 <dd class="description">successful-ok-ignored-or-substituted-attributes</dd>
6100 <dt>IPP_STATUS_OK_IGNORED_SUBSCRIPTIONS </dt>
6101 <dd class="description">successful-ok-ignored-subscriptions</dd>
6102 <dt>IPP_STATUS_OK_TOO_MANY_EVENTS </dt>
6103 <dd class="description">successful-ok-too-many-events</dd>
6104 </dl>
6105 <h3 class="enumeration"><a name="ipp_tag_e">ipp_tag_e</a></h3>
6106 <p class="description">Format tags for attributes</p>
6107 <h4 class="constants">Constants</h4>
6108 <dl>
6109 <dt>IPP_TAG_ADMINDEFINE </dt>
6110 <dd class="description">Admin-defined value</dd>
6111 <dt>IPP_TAG_BEGIN_COLLECTION </dt>
6112 <dd class="description">Beginning of collection value</dd>
6113 <dt>IPP_TAG_BOOLEAN </dt>
6114 <dd class="description">Boolean value</dd>
6115 <dt>IPP_TAG_CHARSET </dt>
6116 <dd class="description">Character set value</dd>
6117 <dt>IPP_TAG_CUPS_INVALID </dt>
6118 <dd class="description">Invalid tag name for <a href="#ippTagValue"><code>ippTagValue</code></a></dd>
6119 <dt>IPP_TAG_DATE </dt>
6120 <dd class="description">Date/time value</dd>
6121 <dt>IPP_TAG_DEFAULT </dt>
6122 <dd class="description">Default value</dd>
6123 <dt>IPP_TAG_DELETEATTR </dt>
6124 <dd class="description">Delete-attribute value</dd>
6125 <dt>IPP_TAG_DOCUMENT </dt>
6126 <dd class="description">Document group</dd>
6127 <dt>IPP_TAG_END </dt>
6128 <dd class="description">End-of-attributes</dd>
6129 <dt>IPP_TAG_END_COLLECTION </dt>
6130 <dd class="description">End of collection value</dd>
6131 <dt>IPP_TAG_ENUM </dt>
6132 <dd class="description">Enumeration value</dd>
6133 <dt>IPP_TAG_EVENT_NOTIFICATION </dt>
6134 <dd class="description">Event group</dd>
6135 <dt>IPP_TAG_EXTENSION </dt>
6136 <dd class="description">Extension point for 32-bit tags</dd>
6137 <dt>IPP_TAG_INTEGER </dt>
6138 <dd class="description">Integer value</dd>
6139 <dt>IPP_TAG_JOB </dt>
6140 <dd class="description">Job group</dd>
6141 <dt>IPP_TAG_KEYWORD </dt>
6142 <dd class="description">Keyword value</dd>
6143 <dt>IPP_TAG_LANGUAGE </dt>
6144 <dd class="description">Language value</dd>
6145 <dt>IPP_TAG_MEMBERNAME </dt>
6146 <dd class="description">Collection member name value</dd>
6147 <dt>IPP_TAG_MIMETYPE </dt>
6148 <dd class="description">MIME media type value</dd>
6149 <dt>IPP_TAG_NAME </dt>
6150 <dd class="description">Name value</dd>
6151 <dt>IPP_TAG_NAMELANG </dt>
6152 <dd class="description">Name-with-language value</dd>
6153 <dt>IPP_TAG_NOTSETTABLE </dt>
6154 <dd class="description">Not-settable value</dd>
6155 <dt>IPP_TAG_NOVALUE </dt>
6156 <dd class="description">No-value value</dd>
6157 <dt>IPP_TAG_OPERATION </dt>
6158 <dd class="description">Operation group</dd>
6159 <dt>IPP_TAG_PRINTER </dt>
6160 <dd class="description">Printer group</dd>
6161 <dt>IPP_TAG_RANGE </dt>
6162 <dd class="description">Range value</dd>
6163 <dt>IPP_TAG_RESOLUTION </dt>
6164 <dd class="description">Resolution value</dd>
6165 <dt>IPP_TAG_STRING </dt>
6166 <dd class="description">Octet string value</dd>
6167 <dt>IPP_TAG_SUBSCRIPTION </dt>
6168 <dd class="description">Subscription group</dd>
6169 <dt>IPP_TAG_TEXT </dt>
6170 <dd class="description">Text value</dd>
6171 <dt>IPP_TAG_TEXTLANG </dt>
6172 <dd class="description">Text-with-language value</dd>
6173 <dt>IPP_TAG_UNKNOWN </dt>
6174 <dd class="description">Unknown value</dd>
6175 <dt>IPP_TAG_UNSUPPORTED_GROUP </dt>
6176 <dd class="description">Unsupported attributes group</dd>
6177 <dt>IPP_TAG_UNSUPPORTED_VALUE </dt>
6178 <dd class="description">Unsupported value</dd>
6179 <dt>IPP_TAG_URI </dt>
6180 <dd class="description">URI value</dd>
6181 <dt>IPP_TAG_URISCHEME </dt>
6182 <dd class="description">URI scheme value</dd>
6183 <dt>IPP_TAG_ZERO </dt>
6184 <dd class="description">Zero tag - used for separators</dd>
6185 </dl>
6186 </div>
6187 </body>
6188 </html>