]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/cupspm.html
Merge pull request #1319 from weblate/weblate-cups-cups
[thirdparty/cups.git] / doc / help / cupspm.html
CommitLineData
73721e3e 1<!DOCTYPE html>
b47dab17 2<html lang="en-US">
798d6e29 3<!-- SECTION: Programming -->
b47dab17
MS
4<head>
5<title>CUPS Programming Manual</title>
6<meta name="keywords" content="Programming">
7<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
b6008d6b 8<meta name="generator" content="codedoc v3.8">
b47dab17
MS
9<meta name="author" content="Michael R Sweet">
10<meta name="language" content="en-US">
b6008d6b 11<meta name="copyright" content="Copyright © 2020-2025 by OpenPrinting. All Rights Reserved.">
af268786 12<meta name="version" content="2.5.0">
b47dab17
MS
13<style type="text/css"><!--
14body {
15 background: white;
16 color: black;
798d6e29 17 font-family: sans-serif;
b47dab17 18 font-size: 12pt;
798d6e29 19}
b47dab17
MS
20a {
21 color: black;
22}
23a:link, a:visited {
24 color: #00f;
25}
26a:link:hover, a:visited:hover, a:active {
27 color: #c0c;
28}
29body, p, h1, h2, h3, h4, h5, h6 {
30 font-family: sans-serif;
31 line-height: 1.4;
32}
33h1, h2, h3, h4, h5, h6 {
bea505c3 34 font-weight: bold;
b47dab17
MS
35 page-break-inside: avoid;
36}
37h1 {
38 font-size: 250%;
798d6e29
MS
39 margin: 0;
40}
b47dab17 41h2 {
798d6e29
MS
42 font-size: 250%;
43 margin-top: 1.5em;
44}
b47dab17
MS
45h3 {
46 font-size: 200%;
798d6e29
MS
47 margin-bottom: 0.5em;
48 margin-top: 1.5em;
49}
b47dab17
MS
50h4 {
51 font-size: 150%;
798d6e29
MS
52 margin-bottom: 0.5em;
53 margin-top: 1.5em;
54}
b47dab17
MS
55h5 {
56 font-size: 125%;
798d6e29
MS
57 margin-bottom: 0.5em;
58 margin-top: 1.5em;
59}
b47dab17 60h6 {
798d6e29 61 font-size: 110%;
b47dab17
MS
62 margin-bottom: 0.5em;
63 margin-top: 1.5em;
798d6e29 64}
b47dab17
MS
65img.title {
66 width: 256px;
798d6e29 67}
b47dab17
MS
68div.header h1, div.header p {
69 text-align: center;
798d6e29 70}
b47dab17
MS
71div.contents, div.body, div.footer {
72 page-break-before: always;
798d6e29 73}
b47dab17
MS
74.class, .enumeration, .function, .struct, .typedef, .union {
75 border-bottom: solid 2px gray;
bea505c3 76}
798d6e29
MS
77.description {
78 margin-top: 0.5em;
79}
798d6e29 80.function {
798d6e29
MS
81 margin-bottom: 0;
82}
798d6e29
MS
83blockquote {
84 border: solid thin gray;
b47dab17
MS
85 box-shadow: 3px 3px 5px rgba(127,127,127,0.25);
86 margin: 1em 0;
87 padding: 10px;
798d6e29
MS
88 page-break-inside: avoid;
89}
0350eba5
MS
90blockquote :first-child {
91 margin-top: 0;
92}
93blockquote :first-child {
94 margin-bottom: 0;
95}
798d6e29 96p code, li code, p.code, pre, ul.code li {
798d6e29 97 font-family: monospace;
798d6e29
MS
98 hyphens: manual;
99 -webkit-hyphens: manual;
798d6e29
MS
100}
101p.code, pre, ul.code li {
b47dab17
MS
102 background: rgba(127,127,127,0.25);
103 border: thin dotted gray;
798d6e29 104 padding: 10px;
b47dab17 105 page-break-inside: avoid;
bea505c3 106}
b47dab17
MS
107pre {
108 white-space: pre-wrap;
798d6e29
MS
109}
110a:link, a:visited {
111 text-decoration: none;
112}
113span.info {
114 background: black;
115 border: solid thin black;
116 color: white;
117 font-size: 80%;
118 font-style: italic;
119 font-weight: bold;
120 white-space: nowrap;
121}
b47dab17 122h1 span.info, h2 span.info, h3 span.info, h4 span.info {
98d88c8d
MS
123 border-top-left-radius: 10px;
124 border-top-right-radius: 10px;
798d6e29 125 float: right;
98d88c8d 126 padding: 3px 6px;
798d6e29
MS
127}
128ul.code, ul.contents, ul.subcontents {
129 list-style-type: none;
130 margin: 0;
131 padding-left: 0;
132}
133ul.code li {
134 margin: 0;
135}
136ul.contents > li {
137 margin-top: 1em;
138}
139ul.contents li ul.code, ul.contents li ul.subcontents {
140 padding-left: 2em;
141}
b47dab17
MS
142table {
143 border-collapse: collapse;
144 border-spacing: 0;
145}
146td {
147 border: solid 1px gray;
148 padding: 5px 10px;
149 vertical-align: top;
150}
151td.left {
152 text-align: left;
153}
154td.center {
155 text-align: center;
156}
157td.right {
158 text-align: right;
159}
160th {
161 border-bottom: solid 2px gray;
162 padding: 1px 5px;
163 text-align: center;
164 vertical-align: bottom;
165}
166tr:nth-child(even) {
167 background: rgba(127,127,127,0.25);
168}
98d88c8d
MS
169table.list {
170 border-collapse: collapse;
171 width: 100%;
798d6e29 172}
98d88c8d 173table.list th {
b47dab17 174 border-bottom: none;
98d88c8d
MS
175 border-right: 2px solid gray;
176 font-family: monospace;
b47dab17 177 font-weight: normal;
98d88c8d
MS
178 padding: 5px 10px 5px 2px;
179 text-align: right;
180 vertical-align: top;
798d6e29 181}
98d88c8d 182table.list td {
b47dab17 183 border: none;
98d88c8d
MS
184 padding: 5px 2px 5px 10px;
185 text-align: left;
186 vertical-align: top;
798d6e29 187}
b47dab17
MS
188h2.title, h3.title {
189 border-bottom: solid 2px gray;
190}
191/* Syntax highlighting */
192span.comment {
193 color: darkgreen;
bea505c3 194}
b47dab17 195span.directive {
0350eba5 196 color: red;
bea505c3 197}
b47dab17
MS
198span.number {
199 color: brown;
200}
201span.reserved {
0350eba5 202 color: blue;
b47dab17
MS
203}
204span.string {
205 color: magenta;
206}
207/* Dark mode overrides */
208@media (prefers-color-scheme: dark) {
209 body {
210 background: black;
211 color: #ccc;
212 }
213 a {
214 color: #ccc;
215 }
216 a:link, a:visited {
217 color: #66f;
218 }
219 a:link:hover, a:visited:hover, a:active {
220 color: #f06;
221 }
222}
223/* Show contents on left side in web browser */
224@media screen and (min-width: 800px) {
225 div.contents {
226 border-right: solid thin gray;
227 bottom: 0px;
228 box-shadow: 3px 3px 5px rgba(127,127,127,0.5);
229 font-size: 10pt;
230 left: 0px;
231 overflow: scroll;
232 padding: 1%;
233 position: fixed;
234 top: 0px;
235 width: 18%;
236 }
237 div.contents h2.title {
238 margin-top: 0px;
239 }
240 div.header, div.body, div.footer {
241 margin-left: 20%;
242 padding: 1% 2%;
243 }
244}
245/* Center title page content vertically */
246@media print {
247 div.header {
248 padding-top: 33%;
249 }
798d6e29
MS
250}
251--></style>
b47dab17
MS
252</head>
253<body>
254<div class="header">
255<h1 class="title">CUPS Programming Manual</h1>
256<p>Michael R Sweet</p>
b6008d6b 257<p>Copyright © 2020-2025 by OpenPrinting. All Rights Reserved.</p>
b47dab17
MS
258</div>
259<div class="contents">
260<h2 class="title">Contents</h2>
261<ul class="contents">
262<li><a href="#introduction">Introduction</a><ul class="subcontents">
263<li><a href="#guidelines">Guidelines</a></li>
264<li><a href="#terms-used-in-this-document">Terms Used in This Document</a></li>
265<li><a href="#compiling-programs-that-use-the-cups-api">Compiling Programs That Use the CUPS API</a></li>
266</ul></li>
267<li><a href="#working-with-destinations">Working with Destinations</a><ul class="subcontents">
268<li><a href="#finding-available-destinations">Finding Available Destinations</a></li>
269<li><a href="#basic-destination-information">Basic Destination Information</a></li>
270<li><a href="#detailed-destination-information">Detailed Destination Information</a></li>
271<li><a href="#submitting-a-print-job">Submitting a Print Job</a></li>
272</ul></li>
273<li><a href="#sending-ipp-requests">Sending IPP Requests</a><ul class="subcontents">
274<li><a href="#connecting-to-the-scheduler-or-printer">Connecting to the Scheduler or Printer</a></li>
275<li><a href="#creating-an-ipp-request">Creating an IPP Request</a></li>
276<li><a href="#sending-the-ipp-request">Sending the IPP Request</a></li>
277<li><a href="#processing-the-ipp-response">Processing the IPP Response</a></li>
278<li><a href="#authentication">Authentication</a></li>
279</ul></li>
81a89f7c
MS
280<li><a href="#ipp-data-file-api">IPP Data File API</a><ul class="subcontents">
281<li><a href="#creating-an-ipp-data-file">Creating an IPP Data File</a></li>
282<li><a href="#reading-a-data-file">Reading a Data File</a></li>
283<li><a href="#variables">Variables</a></li>
284<li><a href="#writing-ipp-data-files">Writing IPP Data Files</a></li>
285</ul></li>
b47dab17
MS
286<li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
287<li><a href="#cupsAddDest">cupsAddDest</a></li>
288<li><a href="#cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></li>
af268786 289<li><a href="#cupsAddDestMediaOptions2">cupsAddDestMediaOptions2</a></li>
b47dab17
MS
290<li><a href="#cupsAddIntegerOption">cupsAddIntegerOption</a></li>
291<li><a href="#cupsAddOption">cupsAddOption</a></li>
af268786 292<li><a href="#cupsAreCredentialsValidForName">cupsAreCredentialsValidForName</a></li>
b47dab17 293<li><a href="#cupsArrayAdd">cupsArrayAdd</a></li>
af268786 294<li><a href="#cupsArrayAddStrings">cupsArrayAddStrings</a></li>
b47dab17 295<li><a href="#cupsArrayClear">cupsArrayClear</a></li>
b47dab17
MS
296<li><a href="#cupsArrayDelete">cupsArrayDelete</a></li>
297<li><a href="#cupsArrayDup">cupsArrayDup</a></li>
298<li><a href="#cupsArrayFind">cupsArrayFind</a></li>
af268786
MS
299<li><a href="#cupsArrayGetCount">cupsArrayGetCount</a></li>
300<li><a href="#cupsArrayGetCurrent">cupsArrayGetCurrent</a></li>
301<li><a href="#cupsArrayGetElement">cupsArrayGetElement</a></li>
302<li><a href="#cupsArrayGetFirst">cupsArrayGetFirst</a></li>
b47dab17
MS
303<li><a href="#cupsArrayGetIndex">cupsArrayGetIndex</a></li>
304<li><a href="#cupsArrayGetInsert">cupsArrayGetInsert</a></li>
af268786
MS
305<li><a href="#cupsArrayGetLast">cupsArrayGetLast</a></li>
306<li><a href="#cupsArrayGetNext">cupsArrayGetNext</a></li>
307<li><a href="#cupsArrayGetPrev">cupsArrayGetPrev</a></li>
308<li><a href="#cupsArrayGetUserData">cupsArrayGetUserData</a></li>
b47dab17 309<li><a href="#cupsArrayInsert">cupsArrayInsert</a></li>
b47dab17 310<li><a href="#cupsArrayNew3">cupsArrayNew3</a></li>
af268786 311<li><a href="#cupsArrayNewStrings">cupsArrayNewStrings</a></li>
b47dab17
MS
312<li><a href="#cupsArrayRemove">cupsArrayRemove</a></li>
313<li><a href="#cupsArrayRestore">cupsArrayRestore</a></li>
314<li><a href="#cupsArraySave">cupsArraySave</a></li>
b47dab17 315<li><a href="#cupsCancelDestJob">cupsCancelDestJob</a></li>
af268786 316<li><a href="#cupsCharsetToUTF8">cupsCharsetToUTF8</a></li>
b47dab17
MS
317<li><a href="#cupsCheckDestSupported">cupsCheckDestSupported</a></li>
318<li><a href="#cupsCloseDestJob">cupsCloseDestJob</a></li>
af268786
MS
319<li><a href="#cupsConcatString">cupsConcatString</a></li>
320<li><a href="#cupsCondBroadcast">cupsCondBroadcast</a></li>
321<li><a href="#cupsCondDestroy">cupsCondDestroy</a></li>
322<li><a href="#cupsCondInit">cupsCondInit</a></li>
323<li><a href="#cupsCondWait">cupsCondWait</a></li>
b47dab17 324<li><a href="#cupsConnectDest">cupsConnectDest</a></li>
af268786
MS
325<li><a href="#cupsCopyCredentials">cupsCopyCredentials</a></li>
326<li><a href="#cupsCopyCredentialsKey">cupsCopyCredentialsKey</a></li>
b6008d6b 327<li><a href="#cupsCopyCredentialsPublicKey">cupsCopyCredentialsPublicKey</a></li>
af268786 328<li><a href="#cupsCopyCredentialsRequest">cupsCopyCredentialsRequest</a></li>
b47dab17
MS
329<li><a href="#cupsCopyDest">cupsCopyDest</a></li>
330<li><a href="#cupsCopyDestConflicts">cupsCopyDestConflicts</a></li>
331<li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li>
0350eba5 332<li><a href="#cupsCopyDestInfo2">cupsCopyDestInfo2</a></li>
af268786
MS
333<li><a href="#cupsCopyString">cupsCopyString</a></li>
334<li><a href="#cupsCreateCredentials">cupsCreateCredentials</a></li>
335<li><a href="#cupsCreateCredentialsRequest">cupsCreateCredentialsRequest</a></li>
b47dab17 336<li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li>
af268786
MS
337<li><a href="#cupsCreateTempFd">cupsCreateTempFd</a></li>
338<li><a href="#cupsCreateTempFile">cupsCreateTempFile</a></li>
339<li><a href="#cupsDNSSDAssembleFullName">cupsDNSSDAssembleFullName</a></li>
340<li><a href="#cupsDNSSDBrowseDelete">cupsDNSSDBrowseDelete</a></li>
341<li><a href="#cupsDNSSDBrowseGetContext">cupsDNSSDBrowseGetContext</a></li>
342<li><a href="#cupsDNSSDBrowseNew">cupsDNSSDBrowseNew</a></li>
0350eba5 343<li><a href="#cupsDNSSDCopyComputerName">cupsDNSSDCopyComputerName</a></li>
af268786
MS
344<li><a href="#cupsDNSSDCopyHostName">cupsDNSSDCopyHostName</a></li>
345<li><a href="#cupsDNSSDDecodeTXT">cupsDNSSDDecodeTXT</a></li>
346<li><a href="#cupsDNSSDDelete">cupsDNSSDDelete</a></li>
347<li><a href="#cupsDNSSDGetConfigChanges">cupsDNSSDGetConfigChanges</a></li>
348<li><a href="#cupsDNSSDNew">cupsDNSSDNew</a></li>
349<li><a href="#cupsDNSSDQueryDelete">cupsDNSSDQueryDelete</a></li>
350<li><a href="#cupsDNSSDQueryGetContext">cupsDNSSDQueryGetContext</a></li>
351<li><a href="#cupsDNSSDQueryNew">cupsDNSSDQueryNew</a></li>
352<li><a href="#cupsDNSSDResolveDelete">cupsDNSSDResolveDelete</a></li>
353<li><a href="#cupsDNSSDResolveGetContext">cupsDNSSDResolveGetContext</a></li>
354<li><a href="#cupsDNSSDResolveNew">cupsDNSSDResolveNew</a></li>
355<li><a href="#cupsDNSSDSeparateFullName">cupsDNSSDSeparateFullName</a></li>
356<li><a href="#cupsDNSSDServiceAdd">cupsDNSSDServiceAdd</a></li>
357<li><a href="#cupsDNSSDServiceDelete">cupsDNSSDServiceDelete</a></li>
358<li><a href="#cupsDNSSDServiceGetContext">cupsDNSSDServiceGetContext</a></li>
359<li><a href="#cupsDNSSDServiceGetName">cupsDNSSDServiceGetName</a></li>
360<li><a href="#cupsDNSSDServiceNew">cupsDNSSDServiceNew</a></li>
361<li><a href="#cupsDNSSDServicePublish">cupsDNSSDServicePublish</a></li>
362<li><a href="#cupsDNSSDServiceSetLocation">cupsDNSSDServiceSetLocation</a></li>
b47dab17
MS
363<li><a href="#cupsDirClose">cupsDirClose</a></li>
364<li><a href="#cupsDirOpen">cupsDirOpen</a></li>
365<li><a href="#cupsDirRead">cupsDirRead</a></li>
366<li><a href="#cupsDirRewind">cupsDirRewind</a></li>
367<li><a href="#cupsDoAuthentication">cupsDoAuthentication</a></li>
af268786
MS
368<li><a href="#cupsDoFileRequest">cupsDoFileRequest</a></li>
369<li><a href="#cupsDoIORequest">cupsDoIORequest</a></li>
370<li><a href="#cupsDoRequest">cupsDoRequest</a></li>
b47dab17
MS
371<li><a href="#cupsEncodeOption">cupsEncodeOption</a></li>
372<li><a href="#cupsEncodeOptions">cupsEncodeOptions</a></li>
373<li><a href="#cupsEncodeOptions2">cupsEncodeOptions2</a></li>
374<li><a href="#cupsEncryption">cupsEncryption</a></li>
375<li><a href="#cupsEnumDests">cupsEnumDests</a></li>
376<li><a href="#cupsFileClose">cupsFileClose</a></li>
b47dab17
MS
377<li><a href="#cupsFileEOF">cupsFileEOF</a></li>
378<li><a href="#cupsFileFind">cupsFileFind</a></li>
379<li><a href="#cupsFileFlush">cupsFileFlush</a></li>
380<li><a href="#cupsFileGetChar">cupsFileGetChar</a></li>
381<li><a href="#cupsFileGetConf">cupsFileGetConf</a></li>
382<li><a href="#cupsFileGetLine">cupsFileGetLine</a></li>
383<li><a href="#cupsFileGets">cupsFileGets</a></li>
af268786 384<li><a href="#cupsFileIsCompressed">cupsFileIsCompressed</a></li>
b47dab17
MS
385<li><a href="#cupsFileLock">cupsFileLock</a></li>
386<li><a href="#cupsFileNumber">cupsFileNumber</a></li>
387<li><a href="#cupsFileOpen">cupsFileOpen</a></li>
388<li><a href="#cupsFileOpenFd">cupsFileOpenFd</a></li>
389<li><a href="#cupsFilePeekChar">cupsFilePeekChar</a></li>
390<li><a href="#cupsFilePrintf">cupsFilePrintf</a></li>
391<li><a href="#cupsFilePutChar">cupsFilePutChar</a></li>
392<li><a href="#cupsFilePutConf">cupsFilePutConf</a></li>
393<li><a href="#cupsFilePuts">cupsFilePuts</a></li>
394<li><a href="#cupsFileRead">cupsFileRead</a></li>
395<li><a href="#cupsFileRewind">cupsFileRewind</a></li>
396<li><a href="#cupsFileSeek">cupsFileSeek</a></li>
397<li><a href="#cupsFileStderr">cupsFileStderr</a></li>
398<li><a href="#cupsFileStdin">cupsFileStdin</a></li>
399<li><a href="#cupsFileStdout">cupsFileStdout</a></li>
400<li><a href="#cupsFileTell">cupsFileTell</a></li>
401<li><a href="#cupsFileUnlock">cupsFileUnlock</a></li>
402<li><a href="#cupsFileWrite">cupsFileWrite</a></li>
403<li><a href="#cupsFindDestDefault">cupsFindDestDefault</a></li>
404<li><a href="#cupsFindDestReady">cupsFindDestReady</a></li>
405<li><a href="#cupsFindDestSupported">cupsFindDestSupported</a></li>
406<li><a href="#cupsFinishDestDocument">cupsFinishDestDocument</a></li>
af268786
MS
407<li><a href="#cupsFormDecode">cupsFormDecode</a></li>
408<li><a href="#cupsFormEncode">cupsFormEncode</a></li>
0350eba5
MS
409<li><a href="#cupsFormatString">cupsFormatString</a></li>
410<li><a href="#cupsFormatStringv">cupsFormatStringv</a></li>
b47dab17
MS
411<li><a href="#cupsFreeDestInfo">cupsFreeDestInfo</a></li>
412<li><a href="#cupsFreeDests">cupsFreeDests</a></li>
413<li><a href="#cupsFreeJobs">cupsFreeJobs</a></li>
414<li><a href="#cupsFreeOptions">cupsFreeOptions</a></li>
0350eba5 415<li><a href="#cupsGetClock">cupsGetClock</a></li>
af268786
MS
416<li><a href="#cupsGetCredentialsExpiration">cupsGetCredentialsExpiration</a></li>
417<li><a href="#cupsGetCredentialsInfo">cupsGetCredentialsInfo</a></li>
418<li><a href="#cupsGetCredentialsTrust">cupsGetCredentialsTrust</a></li>
b47dab17
MS
419<li><a href="#cupsGetDest">cupsGetDest</a></li>
420<li><a href="#cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></li>
af268786 421<li><a href="#cupsGetDestMediaByIndex2">cupsGetDestMediaByIndex2</a></li>
b47dab17 422<li><a href="#cupsGetDestMediaByName">cupsGetDestMediaByName</a></li>
af268786 423<li><a href="#cupsGetDestMediaByName2">cupsGetDestMediaByName2</a></li>
b47dab17 424<li><a href="#cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></li>
af268786 425<li><a href="#cupsGetDestMediaBySize2">cupsGetDestMediaBySize2</a></li>
b47dab17
MS
426<li><a href="#cupsGetDestMediaCount">cupsGetDestMediaCount</a></li>
427<li><a href="#cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></li>
af268786 428<li><a href="#cupsGetDestMediaDefault2">cupsGetDestMediaDefault2</a></li>
b47dab17
MS
429<li><a href="#cupsGetDestWithURI">cupsGetDestWithURI</a></li>
430<li><a href="#cupsGetDests2">cupsGetDests2</a></li>
af268786
MS
431<li><a href="#cupsGetEncryption">cupsGetEncryption</a></li>
432<li><a href="#cupsGetError">cupsGetError</a></li>
433<li><a href="#cupsGetErrorString">cupsGetErrorString</a></li>
434<li><a href="#cupsGetFd">cupsGetFd</a></li>
435<li><a href="#cupsGetFile">cupsGetFile</a></li>
b47dab17
MS
436<li><a href="#cupsGetIntegerOption">cupsGetIntegerOption</a></li>
437<li><a href="#cupsGetJobs2">cupsGetJobs2</a></li>
438<li><a href="#cupsGetNamedDest">cupsGetNamedDest</a></li>
439<li><a href="#cupsGetOption">cupsGetOption</a></li>
440<li><a href="#cupsGetPassword2">cupsGetPassword2</a></li>
af268786
MS
441<li><a href="#cupsGetRand">cupsGetRand</a></li>
442<li><a href="#cupsGetResponse">cupsGetResponse</a></li>
443<li><a href="#cupsGetServer">cupsGetServer</a></li>
444<li><a href="#cupsGetUser">cupsGetUser</a></li>
445<li><a href="#cupsGetUserAgent">cupsGetUserAgent</a></li>
446<li><a href="#cupsHMACData">cupsHMACData</a></li>
447<li><a href="#cupsHashData">cupsHashData</a></li>
448<li><a href="#cupsHashString">cupsHashString</a></li>
0350eba5 449<li><a href="#cupsJSONAdd">cupsJSONAdd</a></li>
af268786
MS
450<li><a href="#cupsJSONDelete">cupsJSONDelete</a></li>
451<li><a href="#cupsJSONExportFile">cupsJSONExportFile</a></li>
452<li><a href="#cupsJSONExportString">cupsJSONExportString</a></li>
453<li><a href="#cupsJSONFind">cupsJSONFind</a></li>
454<li><a href="#cupsJSONGetChild">cupsJSONGetChild</a></li>
455<li><a href="#cupsJSONGetCount">cupsJSONGetCount</a></li>
456<li><a href="#cupsJSONGetKey">cupsJSONGetKey</a></li>
457<li><a href="#cupsJSONGetNumber">cupsJSONGetNumber</a></li>
458<li><a href="#cupsJSONGetParent">cupsJSONGetParent</a></li>
459<li><a href="#cupsJSONGetSibling">cupsJSONGetSibling</a></li>
460<li><a href="#cupsJSONGetString">cupsJSONGetString</a></li>
461<li><a href="#cupsJSONGetType">cupsJSONGetType</a></li>
462<li><a href="#cupsJSONImportFile">cupsJSONImportFile</a></li>
463<li><a href="#cupsJSONImportString">cupsJSONImportString</a></li>
464<li><a href="#cupsJSONImportURL">cupsJSONImportURL</a></li>
465<li><a href="#cupsJSONNew">cupsJSONNew</a></li>
466<li><a href="#cupsJSONNewKey">cupsJSONNewKey</a></li>
467<li><a href="#cupsJSONNewNumber">cupsJSONNewNumber</a></li>
468<li><a href="#cupsJSONNewString">cupsJSONNewString</a></li>
469<li><a href="#cupsJWTDelete">cupsJWTDelete</a></li>
470<li><a href="#cupsJWTExportString">cupsJWTExportString</a></li>
471<li><a href="#cupsJWTGetAlgorithm">cupsJWTGetAlgorithm</a></li>
472<li><a href="#cupsJWTGetClaimNumber">cupsJWTGetClaimNumber</a></li>
473<li><a href="#cupsJWTGetClaimString">cupsJWTGetClaimString</a></li>
474<li><a href="#cupsJWTGetClaimType">cupsJWTGetClaimType</a></li>
475<li><a href="#cupsJWTGetClaimValue">cupsJWTGetClaimValue</a></li>
476<li><a href="#cupsJWTGetClaims">cupsJWTGetClaims</a></li>
477<li><a href="#cupsJWTGetHeaderNumber">cupsJWTGetHeaderNumber</a></li>
478<li><a href="#cupsJWTGetHeaderString">cupsJWTGetHeaderString</a></li>
479<li><a href="#cupsJWTGetHeaderType">cupsJWTGetHeaderType</a></li>
480<li><a href="#cupsJWTGetHeaderValue">cupsJWTGetHeaderValue</a></li>
481<li><a href="#cupsJWTGetHeaders">cupsJWTGetHeaders</a></li>
482<li><a href="#cupsJWTHasValidSignature">cupsJWTHasValidSignature</a></li>
483<li><a href="#cupsJWTImportString">cupsJWTImportString</a></li>
b6008d6b 484<li><a href="#cupsJWTLoadCredentials">cupsJWTLoadCredentials</a></li>
af268786
MS
485<li><a href="#cupsJWTMakePrivateKey">cupsJWTMakePrivateKey</a></li>
486<li><a href="#cupsJWTMakePublicKey">cupsJWTMakePublicKey</a></li>
487<li><a href="#cupsJWTNew">cupsJWTNew</a></li>
488<li><a href="#cupsJWTSetClaimNumber">cupsJWTSetClaimNumber</a></li>
489<li><a href="#cupsJWTSetClaimString">cupsJWTSetClaimString</a></li>
490<li><a href="#cupsJWTSetClaimValue">cupsJWTSetClaimValue</a></li>
491<li><a href="#cupsJWTSetHeaderNumber">cupsJWTSetHeaderNumber</a></li>
492<li><a href="#cupsJWTSetHeaderString">cupsJWTSetHeaderString</a></li>
493<li><a href="#cupsJWTSetHeaderValue">cupsJWTSetHeaderValue</a></li>
494<li><a href="#cupsJWTSign">cupsJWTSign</a></li>
495<li><a href="#cupsLangDefault">cupsLangDefault</a></li>
496<li><a href="#cupsLangEncoding">cupsLangEncoding</a></li>
497<li><a href="#cupsLangFlush">cupsLangFlush</a></li>
498<li><a href="#cupsLangFree">cupsLangFree</a></li>
499<li><a href="#cupsLangGet">cupsLangGet</a></li>
500<li><a href="#cupsLastError">cupsLastError</a></li>
501<li><a href="#cupsLastErrorString">cupsLastErrorString</a></li>
b47dab17 502<li><a href="#cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></li>
0350eba5 503<li><a href="#cupsLocalizeDestMedia2">cupsLocalizeDestMedia2</a></li>
b47dab17
MS
504<li><a href="#cupsLocalizeDestOption">cupsLocalizeDestOption</a></li>
505<li><a href="#cupsLocalizeDestValue">cupsLocalizeDestValue</a></li>
af268786
MS
506<li><a href="#cupsMutexDestroy">cupsMutexDestroy</a></li>
507<li><a href="#cupsMutexInit">cupsMutexInit</a></li>
508<li><a href="#cupsMutexLock">cupsMutexLock</a></li>
509<li><a href="#cupsMutexUnlock">cupsMutexUnlock</a></li>
510<li><a href="#cupsNotifySubject">cupsNotifySubject</a></li>
511<li><a href="#cupsNotifyText">cupsNotifyText</a></li>
0350eba5
MS
512<li><a href="#cupsOAuthClearTokens">cupsOAuthClearTokens</a></li>
513<li><a href="#cupsOAuthCopyAccessToken">cupsOAuthCopyAccessToken</a></li>
514<li><a href="#cupsOAuthCopyClientId">cupsOAuthCopyClientId</a></li>
515<li><a href="#cupsOAuthCopyRefreshToken">cupsOAuthCopyRefreshToken</a></li>
516<li><a href="#cupsOAuthCopyUserId">cupsOAuthCopyUserId</a></li>
517<li><a href="#cupsOAuthGetAuthorizationCode">cupsOAuthGetAuthorizationCode</a></li>
518<li><a href="#cupsOAuthGetClientId">cupsOAuthGetClientId</a></li>
05d62fc2 519<li><a href="#cupsOAuthGetJWKS">cupsOAuthGetJWKS</a></li>
0350eba5
MS
520<li><a href="#cupsOAuthGetMetadata">cupsOAuthGetMetadata</a></li>
521<li><a href="#cupsOAuthGetTokens">cupsOAuthGetTokens</a></li>
05d62fc2 522<li><a href="#cupsOAuthGetUserId">cupsOAuthGetUserId</a></li>
0350eba5
MS
523<li><a href="#cupsOAuthMakeAuthorizationURL">cupsOAuthMakeAuthorizationURL</a></li>
524<li><a href="#cupsOAuthMakeBase64Random">cupsOAuthMakeBase64Random</a></li>
525<li><a href="#cupsOAuthSaveClientData">cupsOAuthSaveClientData</a></li>
526<li><a href="#cupsOAuthSaveTokens">cupsOAuthSaveTokens</a></li>
b47dab17 527<li><a href="#cupsParseOptions">cupsParseOptions</a></li>
0350eba5 528<li><a href="#cupsParseOptions2">cupsParseOptions2</a></li>
af268786
MS
529<li><a href="#cupsPutFd">cupsPutFd</a></li>
530<li><a href="#cupsPutFile">cupsPutFile</a></li>
531<li><a href="#cupsRWDestroy">cupsRWDestroy</a></li>
532<li><a href="#cupsRWInit">cupsRWInit</a></li>
533<li><a href="#cupsRWLockRead">cupsRWLockRead</a></li>
534<li><a href="#cupsRWLockWrite">cupsRWLockWrite</a></li>
535<li><a href="#cupsRWUnlock">cupsRWUnlock</a></li>
b47dab17 536<li><a href="#cupsRasterClose">cupsRasterClose</a></li>
af268786
MS
537<li><a href="#cupsRasterGetErrorString">cupsRasterGetErrorString</a></li>
538<li><a href="#cupsRasterInitHeader">cupsRasterInitHeader</a></li>
b47dab17
MS
539<li><a href="#cupsRasterOpen">cupsRasterOpen</a></li>
540<li><a href="#cupsRasterOpenIO">cupsRasterOpenIO</a></li>
541<li><a href="#cupsRasterReadHeader">cupsRasterReadHeader</a></li>
542<li><a href="#cupsRasterReadHeader2">cupsRasterReadHeader2</a></li>
543<li><a href="#cupsRasterReadPixels">cupsRasterReadPixels</a></li>
544<li><a href="#cupsRasterWriteHeader">cupsRasterWriteHeader</a></li>
545<li><a href="#cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></li>
546<li><a href="#cupsRasterWritePixels">cupsRasterWritePixels</a></li>
af268786 547<li><a href="#cupsReadResponseData">cupsReadResponseData</a></li>
b47dab17
MS
548<li><a href="#cupsRemoveDest">cupsRemoveDest</a></li>
549<li><a href="#cupsRemoveOption">cupsRemoveOption</a></li>
af268786
MS
550<li><a href="#cupsSaveCredentials">cupsSaveCredentials</a></li>
551<li><a href="#cupsSendRequest">cupsSendRequest</a></li>
b47dab17
MS
552<li><a href="#cupsServer">cupsServer</a></li>
553<li><a href="#cupsSetClientCertCB">cupsSetClientCertCB</a></li>
0350eba5 554<li><a href="#cupsSetClientCredentials">cupsSetClientCredentials</a></li>
b47dab17
MS
555<li><a href="#cupsSetCredentials">cupsSetCredentials</a></li>
556<li><a href="#cupsSetDefaultDest">cupsSetDefaultDest</a></li>
557<li><a href="#cupsSetDests2">cupsSetDests2</a></li>
558<li><a href="#cupsSetEncryption">cupsSetEncryption</a></li>
af268786 559<li><a href="#cupsSetOAuthCB">cupsSetOAuthCB</a></li>
b47dab17
MS
560<li><a href="#cupsSetPasswordCB2">cupsSetPasswordCB2</a></li>
561<li><a href="#cupsSetServer">cupsSetServer</a></li>
562<li><a href="#cupsSetServerCertCB">cupsSetServerCertCB</a></li>
563<li><a href="#cupsSetServerCredentials">cupsSetServerCredentials</a></li>
564<li><a href="#cupsSetUser">cupsSetUser</a></li>
565<li><a href="#cupsSetUserAgent">cupsSetUserAgent</a></li>
af268786 566<li><a href="#cupsSignCredentialsRequest">cupsSignCredentialsRequest</a></li>
b47dab17 567<li><a href="#cupsStartDestDocument">cupsStartDestDocument</a></li>
af268786
MS
568<li><a href="#cupsTempFd">cupsTempFd</a></li>
569<li><a href="#cupsTempFile">cupsTempFile</a></li>
570<li><a href="#cupsTempFile2">cupsTempFile2</a></li>
571<li><a href="#cupsThreadCancel">cupsThreadCancel</a></li>
572<li><a href="#cupsThreadCreate">cupsThreadCreate</a></li>
573<li><a href="#cupsThreadDetach">cupsThreadDetach</a></li>
574<li><a href="#cupsThreadWait">cupsThreadWait</a></li>
575<li><a href="#cupsUTF32ToUTF8">cupsUTF32ToUTF8</a></li>
576<li><a href="#cupsUTF8ToCharset">cupsUTF8ToCharset</a></li>
577<li><a href="#cupsUTF8ToUTF32">cupsUTF8ToUTF32</a></li>
578<li><a href="#cupsUser">cupsUser</a></li>
579<li><a href="#cupsUserAgent">cupsUserAgent</a></li>
580<li><a href="#cupsWriteRequestData">cupsWriteRequestData</a></li>
b47dab17 581<li><a href="#httpAcceptConnection">httpAcceptConnection</a></li>
b47dab17
MS
582<li><a href="#httpAddrClose">httpAddrClose</a></li>
583<li><a href="#httpAddrConnect2">httpAddrConnect2</a></li>
584<li><a href="#httpAddrCopyList">httpAddrCopyList</a></li>
b47dab17 585<li><a href="#httpAddrFreeList">httpAddrFreeList</a></li>
af268786
MS
586<li><a href="#httpAddrGetFamily">httpAddrGetFamily</a></li>
587<li><a href="#httpAddrGetLength">httpAddrGetLength</a></li>
b47dab17 588<li><a href="#httpAddrGetList">httpAddrGetList</a></li>
af268786
MS
589<li><a href="#httpAddrGetPort">httpAddrGetPort</a></li>
590<li><a href="#httpAddrGetString">httpAddrGetString</a></li>
591<li><a href="#httpAddrIsAny">httpAddrIsAny</a></li>
592<li><a href="#httpAddrIsEqual">httpAddrIsEqual</a></li>
593<li><a href="#httpAddrIsLocalhost">httpAddrIsLocalhost</a></li>
b47dab17 594<li><a href="#httpAddrListen">httpAddrListen</a></li>
b47dab17 595<li><a href="#httpAddrLookup">httpAddrLookup</a></li>
af268786 596<li><a href="#httpAddrSetPort">httpAddrSetPort</a></li>
b47dab17
MS
597<li><a href="#httpAssembleURI">httpAssembleURI</a></li>
598<li><a href="#httpAssembleURIf">httpAssembleURIf</a></li>
599<li><a href="#httpAssembleUUID">httpAssembleUUID</a></li>
600<li><a href="#httpBlocking">httpBlocking</a></li>
601<li><a href="#httpCheck">httpCheck</a></li>
602<li><a href="#httpClearCookie">httpClearCookie</a></li>
603<li><a href="#httpClearFields">httpClearFields</a></li>
604<li><a href="#httpClose">httpClose</a></li>
b47dab17 605<li><a href="#httpConnect2">httpConnect2</a></li>
0350eba5
MS
606<li><a href="#httpConnectAgain">httpConnectAgain</a></li>
607<li><a href="#httpConnectURI">httpConnectURI</a></li>
af268786
MS
608<li><a href="#httpCopyPeerCredentials">httpCopyPeerCredentials</a></li>
609<li><a href="#httpDecode64_3">httpDecode64_3</a></li>
610<li><a href="#httpEncode64_3">httpEncode64_3</a></li>
b47dab17
MS
611<li><a href="#httpFieldValue">httpFieldValue</a></li>
612<li><a href="#httpFlush">httpFlush</a></li>
613<li><a href="#httpFlushWrite">httpFlushWrite</a></li>
b47dab17
MS
614<li><a href="#httpGetActivity">httpGetActivity</a></li>
615<li><a href="#httpGetAddress">httpGetAddress</a></li>
616<li><a href="#httpGetAuthString">httpGetAuthString</a></li>
617<li><a href="#httpGetBlocking">httpGetBlocking</a></li>
618<li><a href="#httpGetContentEncoding">httpGetContentEncoding</a></li>
619<li><a href="#httpGetCookie">httpGetCookie</a></li>
05d62fc2 620<li><a href="#httpGetCookieValue">httpGetCookieValue</a></li>
b47dab17
MS
621<li><a href="#httpGetDateString2">httpGetDateString2</a></li>
622<li><a href="#httpGetDateTime">httpGetDateTime</a></li>
623<li><a href="#httpGetEncryption">httpGetEncryption</a></li>
af268786 624<li><a href="#httpGetError">httpGetError</a></li>
b47dab17
MS
625<li><a href="#httpGetExpect">httpGetExpect</a></li>
626<li><a href="#httpGetFd">httpGetFd</a></li>
627<li><a href="#httpGetField">httpGetField</a></li>
628<li><a href="#httpGetHostname">httpGetHostname</a></li>
629<li><a href="#httpGetKeepAlive">httpGetKeepAlive</a></li>
630<li><a href="#httpGetLength2">httpGetLength2</a></li>
631<li><a href="#httpGetPending">httpGetPending</a></li>
632<li><a href="#httpGetReady">httpGetReady</a></li>
633<li><a href="#httpGetRemaining">httpGetRemaining</a></li>
05d62fc2 634<li><a href="#httpGetSecurity">httpGetSecurity</a></li>
b47dab17
MS
635<li><a href="#httpGetState">httpGetState</a></li>
636<li><a href="#httpGetStatus">httpGetStatus</a></li>
637<li><a href="#httpGetSubField2">httpGetSubField2</a></li>
638<li><a href="#httpGetVersion">httpGetVersion</a></li>
af268786 639<li><a href="#httpGets2">httpGets2</a></li>
b47dab17
MS
640<li><a href="#httpInitialize">httpInitialize</a></li>
641<li><a href="#httpIsChunked">httpIsChunked</a></li>
642<li><a href="#httpIsEncrypted">httpIsEncrypted</a></li>
af268786
MS
643<li><a href="#httpMD5">httpMD5</a></li>
644<li><a href="#httpMD5Final">httpMD5Final</a></li>
645<li><a href="#httpMD5String">httpMD5String</a></li>
b47dab17 646<li><a href="#httpPeek">httpPeek</a></li>
b47dab17
MS
647<li><a href="#httpRead2">httpRead2</a></li>
648<li><a href="#httpReadRequest">httpReadRequest</a></li>
b47dab17 649<li><a href="#httpResolveHostname">httpResolveHostname</a></li>
af268786 650<li><a href="#httpResolveURI">httpResolveURI</a></li>
b47dab17
MS
651<li><a href="#httpSeparateURI">httpSeparateURI</a></li>
652<li><a href="#httpSetAuthString">httpSetAuthString</a></li>
af268786 653<li><a href="#httpSetBlocking">httpSetBlocking</a></li>
b47dab17 654<li><a href="#httpSetCookie">httpSetCookie</a></li>
b47dab17 655<li><a href="#httpSetDefaultField">httpSetDefaultField</a></li>
af268786 656<li><a href="#httpSetEncryption">httpSetEncryption</a></li>
b47dab17
MS
657<li><a href="#httpSetExpect">httpSetExpect</a></li>
658<li><a href="#httpSetField">httpSetField</a></li>
659<li><a href="#httpSetKeepAlive">httpSetKeepAlive</a></li>
660<li><a href="#httpSetLength">httpSetLength</a></li>
661<li><a href="#httpSetTimeout">httpSetTimeout</a></li>
662<li><a href="#httpShutdown">httpShutdown</a></li>
663<li><a href="#httpStateString">httpStateString</a></li>
af268786 664<li><a href="#httpStatusString">httpStatusString</a></li>
b47dab17
MS
665<li><a href="#httpURIStatusString">httpURIStatusString</a></li>
666<li><a href="#httpUpdate">httpUpdate</a></li>
667<li><a href="#httpWait">httpWait</a></li>
668<li><a href="#httpWrite2">httpWrite2</a></li>
af268786 669<li><a href="#httpWriteRequest">httpWriteRequest</a></li>
b47dab17
MS
670<li><a href="#httpWriteResponse">httpWriteResponse</a></li>
671<li><a href="#ippAddBoolean">ippAddBoolean</a></li>
672<li><a href="#ippAddBooleans">ippAddBooleans</a></li>
673<li><a href="#ippAddCollection">ippAddCollection</a></li>
674<li><a href="#ippAddCollections">ippAddCollections</a></li>
af268786 675<li><a href="#ippAddCredentialsString">ippAddCredentialsString</a></li>
b47dab17
MS
676<li><a href="#ippAddDate">ippAddDate</a></li>
677<li><a href="#ippAddInteger">ippAddInteger</a></li>
678<li><a href="#ippAddIntegers">ippAddIntegers</a></li>
679<li><a href="#ippAddOctetString">ippAddOctetString</a></li>
680<li><a href="#ippAddOutOfBand">ippAddOutOfBand</a></li>
681<li><a href="#ippAddRange">ippAddRange</a></li>
682<li><a href="#ippAddRanges">ippAddRanges</a></li>
683<li><a href="#ippAddResolution">ippAddResolution</a></li>
684<li><a href="#ippAddResolutions">ippAddResolutions</a></li>
685<li><a href="#ippAddSeparator">ippAddSeparator</a></li>
686<li><a href="#ippAddString">ippAddString</a></li>
687<li><a href="#ippAddStringf">ippAddStringf</a></li>
688<li><a href="#ippAddStringfv">ippAddStringfv</a></li>
689<li><a href="#ippAddStrings">ippAddStrings</a></li>
690<li><a href="#ippAttributeString">ippAttributeString</a></li>
691<li><a href="#ippContainsInteger">ippContainsInteger</a></li>
692<li><a href="#ippContainsString">ippContainsString</a></li>
693<li><a href="#ippCopyAttribute">ippCopyAttribute</a></li>
694<li><a href="#ippCopyAttributes">ippCopyAttributes</a></li>
af268786 695<li><a href="#ippCopyCredentialsString">ippCopyCredentialsString</a></li>
b47dab17
MS
696<li><a href="#ippCreateRequestedArray">ippCreateRequestedArray</a></li>
697<li><a href="#ippDateToTime">ippDateToTime</a></li>
698<li><a href="#ippDelete">ippDelete</a></li>
699<li><a href="#ippDeleteAttribute">ippDeleteAttribute</a></li>
700<li><a href="#ippDeleteValues">ippDeleteValues</a></li>
701<li><a href="#ippEnumString">ippEnumString</a></li>
702<li><a href="#ippEnumValue">ippEnumValue</a></li>
703<li><a href="#ippErrorString">ippErrorString</a></li>
704<li><a href="#ippErrorValue">ippErrorValue</a></li>
af268786
MS
705<li><a href="#ippFileClose">ippFileClose</a></li>
706<li><a href="#ippFileDelete">ippFileDelete</a></li>
707<li><a href="#ippFileExpandVars">ippFileExpandVars</a></li>
708<li><a href="#ippFileGetAttribute">ippFileGetAttribute</a></li>
709<li><a href="#ippFileGetAttributes">ippFileGetAttributes</a></li>
710<li><a href="#ippFileGetFilename">ippFileGetFilename</a></li>
711<li><a href="#ippFileGetLineNumber">ippFileGetLineNumber</a></li>
712<li><a href="#ippFileGetVar">ippFileGetVar</a></li>
713<li><a href="#ippFileNew">ippFileNew</a></li>
714<li><a href="#ippFileOpen">ippFileOpen</a></li>
715<li><a href="#ippFileRead">ippFileRead</a></li>
716<li><a href="#ippFileReadCollection">ippFileReadCollection</a></li>
717<li><a href="#ippFileReadToken">ippFileReadToken</a></li>
718<li><a href="#ippFileRestorePosition">ippFileRestorePosition</a></li>
719<li><a href="#ippFileSavePosition">ippFileSavePosition</a></li>
720<li><a href="#ippFileSetAttributes">ippFileSetAttributes</a></li>
721<li><a href="#ippFileSetGroupTag">ippFileSetGroupTag</a></li>
722<li><a href="#ippFileSetVar">ippFileSetVar</a></li>
723<li><a href="#ippFileSetVarf">ippFileSetVarf</a></li>
724<li><a href="#ippFileWriteAttributes">ippFileWriteAttributes</a></li>
725<li><a href="#ippFileWriteComment">ippFileWriteComment</a></li>
726<li><a href="#ippFileWriteToken">ippFileWriteToken</a></li>
727<li><a href="#ippFileWriteTokenf">ippFileWriteTokenf</a></li>
b47dab17
MS
728<li><a href="#ippFindAttribute">ippFindAttribute</a></li>
729<li><a href="#ippFindNextAttribute">ippFindNextAttribute</a></li>
b47dab17
MS
730<li><a href="#ippGetBoolean">ippGetBoolean</a></li>
731<li><a href="#ippGetCollection">ippGetCollection</a></li>
732<li><a href="#ippGetCount">ippGetCount</a></li>
733<li><a href="#ippGetDate">ippGetDate</a></li>
af268786 734<li><a href="#ippGetFirstAttribute">ippGetFirstAttribute</a></li>
b47dab17
MS
735<li><a href="#ippGetGroupTag">ippGetGroupTag</a></li>
736<li><a href="#ippGetInteger">ippGetInteger</a></li>
af268786 737<li><a href="#ippGetLength">ippGetLength</a></li>
b47dab17 738<li><a href="#ippGetName">ippGetName</a></li>
af268786 739<li><a href="#ippGetNextAttribute">ippGetNextAttribute</a></li>
b47dab17
MS
740<li><a href="#ippGetOctetString">ippGetOctetString</a></li>
741<li><a href="#ippGetOperation">ippGetOperation</a></li>
af268786 742<li><a href="#ippGetPort">ippGetPort</a></li>
b47dab17
MS
743<li><a href="#ippGetRange">ippGetRange</a></li>
744<li><a href="#ippGetRequestId">ippGetRequestId</a></li>
745<li><a href="#ippGetResolution">ippGetResolution</a></li>
746<li><a href="#ippGetState">ippGetState</a></li>
747<li><a href="#ippGetStatusCode">ippGetStatusCode</a></li>
748<li><a href="#ippGetString">ippGetString</a></li>
749<li><a href="#ippGetValueTag">ippGetValueTag</a></li>
750<li><a href="#ippGetVersion">ippGetVersion</a></li>
b47dab17
MS
751<li><a href="#ippNew">ippNew</a></li>
752<li><a href="#ippNewRequest">ippNewRequest</a></li>
753<li><a href="#ippNewResponse">ippNewResponse</a></li>
b47dab17
MS
754<li><a href="#ippOpString">ippOpString</a></li>
755<li><a href="#ippOpValue">ippOpValue</a></li>
b47dab17
MS
756<li><a href="#ippRead">ippRead</a></li>
757<li><a href="#ippReadFile">ippReadFile</a></li>
758<li><a href="#ippReadIO">ippReadIO</a></li>
af268786
MS
759<li><a href="#ippRestore">ippRestore</a></li>
760<li><a href="#ippSave">ippSave</a></li>
b47dab17
MS
761<li><a href="#ippSetBoolean">ippSetBoolean</a></li>
762<li><a href="#ippSetCollection">ippSetCollection</a></li>
763<li><a href="#ippSetDate">ippSetDate</a></li>
764<li><a href="#ippSetGroupTag">ippSetGroupTag</a></li>
765<li><a href="#ippSetInteger">ippSetInteger</a></li>
766<li><a href="#ippSetName">ippSetName</a></li>
767<li><a href="#ippSetOctetString">ippSetOctetString</a></li>
768<li><a href="#ippSetOperation">ippSetOperation</a></li>
769<li><a href="#ippSetPort">ippSetPort</a></li>
770<li><a href="#ippSetRange">ippSetRange</a></li>
771<li><a href="#ippSetRequestId">ippSetRequestId</a></li>
772<li><a href="#ippSetResolution">ippSetResolution</a></li>
773<li><a href="#ippSetState">ippSetState</a></li>
774<li><a href="#ippSetStatusCode">ippSetStatusCode</a></li>
775<li><a href="#ippSetString">ippSetString</a></li>
776<li><a href="#ippSetStringf">ippSetStringf</a></li>
777<li><a href="#ippSetStringfv">ippSetStringfv</a></li>
778<li><a href="#ippSetValueTag">ippSetValueTag</a></li>
779<li><a href="#ippSetVersion">ippSetVersion</a></li>
780<li><a href="#ippStateString">ippStateString</a></li>
781<li><a href="#ippTagString">ippTagString</a></li>
782<li><a href="#ippTagValue">ippTagValue</a></li>
783<li><a href="#ippTimeToDate">ippTimeToDate</a></li>
784<li><a href="#ippValidateAttribute">ippValidateAttribute</a></li>
785<li><a href="#ippValidateAttributes">ippValidateAttributes</a></li>
786<li><a href="#ippWrite">ippWrite</a></li>
787<li><a href="#ippWriteFile">ippWriteFile</a></li>
788<li><a href="#ippWriteIO">ippWriteIO</a></li>
af268786
MS
789<li><a href="#pwgFormatSizeName">pwgFormatSizeName</a></li>
790<li><a href="#pwgInitSize">pwgInitSize</a></li>
791<li><a href="#pwgMediaForLegacy">pwgMediaForLegacy</a></li>
792<li><a href="#pwgMediaForPPD">pwgMediaForPPD</a></li>
793<li><a href="#pwgMediaForPWG">pwgMediaForPWG</a></li>
794<li><a href="#pwgMediaForSize">pwgMediaForSize</a></li>
b47dab17
MS
795</ul></li>
796<li><a href="#TYPES">Data Types</a><ul class="subcontents">
af268786 797<li><a href="#cups_acopy_cb_t">cups_acopy_cb_t</a></li>
b47dab17 798<li><a href="#cups_adv_t">cups_adv_t</a></li>
af268786
MS
799<li><a href="#cups_afree_cb_t">cups_afree_cb_t</a></li>
800<li><a href="#cups_ahash_cb_t">cups_ahash_cb_t</a></li>
801<li><a href="#cups_array_cb_t">cups_array_cb_t</a></li>
b47dab17
MS
802<li><a href="#cups_array_t">cups_array_t</a></li>
803<li><a href="#cups_bool_t">cups_bool_t</a></li>
af268786 804<li><a href="#cups_cert_san_cb_t">cups_cert_san_cb_t</a></li>
b47dab17 805<li><a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a></li>
af268786
MS
806<li><a href="#cups_cond_t">cups_cond_t</a></li>
807<li><a href="#cups_credpurpose_t">cups_credpurpose_t</a></li>
808<li><a href="#cups_credtype_t">cups_credtype_t</a></li>
809<li><a href="#cups_credusage_t">cups_credusage_t</a></li>
b47dab17
MS
810<li><a href="#cups_cspace_t">cups_cspace_t</a></li>
811<li><a href="#cups_cut_t">cups_cut_t</a></li>
af268786 812<li><a href="#cups_dbcs_t">cups_dbcs_t</a></li>
b47dab17
MS
813<li><a href="#cups_dentry_t">cups_dentry_t</a></li>
814<li><a href="#cups_dest_cb_t">cups_dest_cb_t</a></li>
af268786 815<li><a href="#cups_dest_flags_t">cups_dest_flags_t</a></li>
b47dab17
MS
816<li><a href="#cups_dest_t">cups_dest_t</a></li>
817<li><a href="#cups_dinfo_t">cups_dinfo_t</a></li>
818<li><a href="#cups_dir_t">cups_dir_t</a></li>
af268786
MS
819<li><a href="#cups_dnssd_browse_cb_t">cups_dnssd_browse_cb_t</a></li>
820<li><a href="#cups_dnssd_error_cb_t">cups_dnssd_error_cb_t</a></li>
821<li><a href="#cups_dnssd_flags_t">cups_dnssd_flags_t</a></li>
822<li><a href="#cups_dnssd_query_cb_t">cups_dnssd_query_cb_t</a></li>
823<li><a href="#cups_dnssd_query_t">cups_dnssd_query_t</a></li>
824<li><a href="#cups_dnssd_resolve_cb_t">cups_dnssd_resolve_cb_t</a></li>
825<li><a href="#cups_dnssd_resolve_t">cups_dnssd_resolve_t</a></li>
826<li><a href="#cups_dnssd_browse_t">cups_dnssd_browse_t</a></li>
827<li><a href="#cups_dnssd_service_cb_t">cups_dnssd_service_cb_t</a></li>
828<li><a href="#cups_dnssd_service_t">cups_dnssd_service_t</a></li>
829<li><a href="#cups_dnssd_t">cups_dnssd_t</a></li>
b47dab17
MS
830<li><a href="#cups_edge_t">cups_edge_t</a></li>
831<li><a href="#cups_file_t">cups_file_t</a></li>
832<li><a href="#cups_job_t">cups_job_t</a></li>
833<li><a href="#cups_jog_t">cups_jog_t</a></li>
af268786
MS
834<li><a href="#cups_json_t">cups_json_t</a></li>
835<li><a href="#cups_jtype_t">cups_jtype_t</a></li>
836<li><a href="#cups_jwa_t">cups_jwa_t</a></li>
837<li><a href="#cups_jws_format_t">cups_jws_format_t</a></li>
838<li><a href="#cups_jwt_t">cups_jwt_t</a></li>
839<li><a href="#cups_lang_t">cups_lang_t</a></li>
840<li><a href="#cups_media_flags_t">cups_media_flags_t</a></li>
841<li><a href="#cups_media_t">cups_media_t</a></li>
842<li><a href="#cups_mutex_t">cups_mutex_t</a></li>
843<li><a href="#cups_oauth_cb_t">cups_oauth_cb_t</a></li>
0350eba5 844<li><a href="#cups_ogrant_t">cups_ogrant_t</a></li>
b47dab17
MS
845<li><a href="#cups_option_t">cups_option_t</a></li>
846<li><a href="#cups_order_t">cups_order_t</a></li>
847<li><a href="#cups_orient_t">cups_orient_t</a></li>
848<li><a href="#cups_page_header2_t">cups_page_header2_t</a></li>
849<li><a href="#cups_page_header_t">cups_page_header_t</a></li>
850<li><a href="#cups_password_cb2_t">cups_password_cb2_t</a></li>
851<li><a href="#cups_ptype_t">cups_ptype_t</a></li>
af268786
MS
852<li><a href="#cups_raster_cb_t">cups_raster_cb_t</a></li>
853<li><a href="#cups_raster_mode_t">cups_raster_mode_t</a></li>
b47dab17 854<li><a href="#cups_raster_t">cups_raster_t</a></li>
af268786
MS
855<li><a href="#cups_rwlock_t">cups_rwlock_t</a></li>
856<li><a href="#cups_sbcs_t">cups_sbcs_t</a></li>
b47dab17
MS
857<li><a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a></li>
858<li><a href="#cups_size_t">cups_size_t</a></li>
af268786
MS
859<li><a href="#cups_thread_func_t">cups_thread_func_t</a></li>
860<li><a href="#cups_thread_key_t">cups_thread_key_t</a></li>
861<li><a href="#cups_thread_t">cups_thread_t</a></li>
862<li><a href="#cups_ucs2_t">cups_ucs2_t</a></li>
863<li><a href="#cups_ucs4_t">cups_ucs4_t</a></li>
864<li><a href="#cups_utf32_t">cups_utf32_t</a></li>
865<li><a href="#cups_utf8_t">cups_utf8_t</a></li>
866<li><a href="#cups_vbcs_t">cups_vbcs_t</a></li>
867<li><a href="#cups_whichjobs_t">cups_whichjobs_t</a></li>
b47dab17
MS
868<li><a href="#http_addr_t">http_addr_t</a></li>
869<li><a href="#http_encoding_t">http_encoding_t</a></li>
870<li><a href="#http_encryption_t">http_encryption_t</a></li>
871<li><a href="#http_field_t">http_field_t</a></li>
872<li><a href="#http_keepalive_t">http_keepalive_t</a></li>
af268786
MS
873<li><a href="#http_resolve_cb_t">http_resolve_cb_t</a></li>
874<li><a href="#http_resolve_t">http_resolve_t</a></li>
b47dab17
MS
875<li><a href="#http_state_t">http_state_t</a></li>
876<li><a href="#http_t">http_t</a></li>
877<li><a href="#http_timeout_cb_t">http_timeout_cb_t</a></li>
878<li><a href="#http_trust_t">http_trust_t</a></li>
879<li><a href="#http_uri_coding_t">http_uri_coding_t</a></li>
880<li><a href="#http_uri_status_t">http_uri_status_t</a></li>
881<li><a href="#ipp_attribute_t">ipp_attribute_t</a></li>
af268786
MS
882<li><a href="#ipp_copy_cb_t">ipp_copy_cb_t</a></li>
883<li><a href="#ipp_fattr_cb_t">ipp_fattr_cb_t</a></li>
884<li><a href="#ipp_ferror_cb_t">ipp_ferror_cb_t</a></li>
885<li><a href="#ipp_file_t">ipp_file_t</a></li>
886<li><a href="#ipp_ftoken_cb_t">ipp_ftoken_cb_t</a></li>
887<li><a href="#ipp_io_cb_t">ipp_io_cb_t</a></li>
888<li><a href="#ipp_jstate_t">ipp_jstate_t</a></li>
889<li><a href="#ipp_op_t">ipp_op_t</a></li>
b47dab17
MS
890<li><a href="#ipp_orient_t">ipp_orient_t</a></li>
891<li><a href="#ipp_pstate_t">ipp_pstate_t</a></li>
892<li><a href="#ipp_quality_t">ipp_quality_t</a></li>
893<li><a href="#ipp_res_t">ipp_res_t</a></li>
894<li><a href="#ipp_rstate_t">ipp_rstate_t</a></li>
895<li><a href="#ipp_sstate_t">ipp_sstate_t</a></li>
896<li><a href="#ipp_state_t">ipp_state_t</a></li>
897<li><a href="#ipp_t">ipp_t</a></li>
898<li><a href="#pwg_media_t">pwg_media_t</a></li>
899</ul></li>
900<li><a href="#STRUCTURES">Structures</a><ul class="subcontents">
901<li><a href="#cups_dentry_s">cups_dentry_s</a></li>
902<li><a href="#cups_dest_s">cups_dest_s</a></li>
903<li><a href="#cups_job_s">cups_job_s</a></li>
af268786
MS
904<li><a href="#cups_lang_s">cups_lang_s</a></li>
905<li><a href="#cups_media_s">cups_media_s</a></li>
b47dab17
MS
906<li><a href="#cups_option_s">cups_option_s</a></li>
907<li><a href="#cups_page_header2_s">cups_page_header2_s</a></li>
908<li><a href="#cups_page_header_s">cups_page_header_s</a></li>
909<li><a href="#cups_size_s">cups_size_s</a></li>
910<li><a href="#pwg_media_s">pwg_media_s</a></li>
911</ul></li>
912<li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents">
913<li><a href="#cups_adv_e">cups_adv_e</a></li>
914<li><a href="#cups_bool_e">cups_bool_e</a></li>
af268786
MS
915<li><a href="#cups_credpurpose_e">cups_credpurpose_e</a></li>
916<li><a href="#cups_credtype_e">cups_credtype_e</a></li>
917<li><a href="#cups_credusage_e">cups_credusage_e</a></li>
b47dab17
MS
918<li><a href="#cups_cspace_e">cups_cspace_e</a></li>
919<li><a href="#cups_cut_e">cups_cut_e</a></li>
af268786
MS
920<li><a href="#cups_dest_flags_e">cups_dest_flags_e</a></li>
921<li><a href="#cups_dnssd_flags_e">cups_dnssd_flags_e</a></li>
922<li><a href="#cups_dnssd_rrtype_e">cups_dnssd_rrtype_e</a></li>
b47dab17
MS
923<li><a href="#cups_edge_e">cups_edge_e</a></li>
924<li><a href="#cups_jog_e">cups_jog_e</a></li>
af268786
MS
925<li><a href="#cups_jtype_e">cups_jtype_e</a></li>
926<li><a href="#cups_jwa_e">cups_jwa_e</a></li>
927<li><a href="#cups_jws_format_e">cups_jws_format_e</a></li>
928<li><a href="#cups_media_flags_e">cups_media_flags_e</a></li>
0350eba5 929<li><a href="#cups_ogrant_e">cups_ogrant_e</a></li>
b47dab17
MS
930<li><a href="#cups_order_e">cups_order_e</a></li>
931<li><a href="#cups_orient_e">cups_orient_e</a></li>
932<li><a href="#cups_ptype_e">cups_ptype_e</a></li>
af268786
MS
933<li><a href="#cups_raster_mode_e">cups_raster_mode_e</a></li>
934<li><a href="#cups_whichjobs_e">cups_whichjobs_e</a></li>
b47dab17
MS
935<li><a href="#http_encoding_e">http_encoding_e</a></li>
936<li><a href="#http_encryption_e">http_encryption_e</a></li>
937<li><a href="#http_field_e">http_field_e</a></li>
938<li><a href="#http_keepalive_e">http_keepalive_e</a></li>
af268786 939<li><a href="#http_resolve_e">http_resolve_e</a></li>
b47dab17
MS
940<li><a href="#http_state_e">http_state_e</a></li>
941<li><a href="#http_status_e">http_status_e</a></li>
942<li><a href="#http_trust_e">http_trust_e</a></li>
943<li><a href="#http_uri_coding_e">http_uri_coding_e</a></li>
944<li><a href="#http_uri_status_e">http_uri_status_e</a></li>
945<li><a href="#ipp_finishings_e">ipp_finishings_e</a></li>
946<li><a href="#ipp_jstate_e">ipp_jstate_e</a></li>
947<li><a href="#ipp_op_e">ipp_op_e</a></li>
948<li><a href="#ipp_orient_e">ipp_orient_e</a></li>
949<li><a href="#ipp_pstate_e">ipp_pstate_e</a></li>
950<li><a href="#ipp_quality_e">ipp_quality_e</a></li>
951<li><a href="#ipp_res_e">ipp_res_e</a></li>
952<li><a href="#ipp_rstate_e">ipp_rstate_e</a></li>
953<li><a href="#ipp_sstate_e">ipp_sstate_e</a></li>
954<li><a href="#ipp_state_e">ipp_state_e</a></li>
955<li><a href="#ipp_status_e">ipp_status_e</a></li>
956<li><a href="#ipp_tag_e">ipp_tag_e</a></li>
957</ul></li>
958</ul>
959</div>
960<div class="body">
961<blockquote>
d6b36f7f 962<p>Please <a href="https://github.com/openprinting/cups/issues">file issues on GitHub</a> to provide feedback on this document.</p>
798d6e29 963</blockquote>
b47dab17
MS
964<h2 class="title" id="introduction">Introduction</h2>
965<p>CUPS provides the &quot;cups&quot; library to talk to the different parts of CUPS and with Internet Printing Protocol (IPP) printers. The &quot;cups&quot; library functions are accessed by including the <code>&lt;cups/cups.h&gt;</code> header.</p>
966<p>CUPS is based on the Internet Printing Protocol (&quot;IPP&quot;), which allows clients (applications) to communicate with a server (the scheduler, printers, etc.) to get a list of destinations, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure <code>http_t</code>. The <code>CUPS_HTTP_DEFAULT</code> constant can be used when you want to talk to the CUPS scheduler.</p>
967<h3 class="title" id="guidelines">Guidelines</h3>
968<p>When writing software (other than printer drivers) that uses the &quot;cups&quot; library:</p>
969<ul>
970<li><p>Do not use undocumented or deprecated APIs,</p>
971</li>
972<li><p>Do not rely on pre-configured printers,</p>
973</li>
974<li><p>Do not assume that printers support specific features or formats, and</p>
975</li>
976<li><p>Do not rely on implementation details (PPDs, etc.)</p>
977</li>
798d6e29 978</ul>
b47dab17
MS
979<p>CUPS is designed to insulate users and developers from the implementation details of printers and file formats. The goal is to allow an application to supply a print file in a standard format with the user intent (&quot;print four copies, two-sided on A4 media, and staple each copy&quot;) and have the printing system manage the printer communication and format conversion needed.</p>
980<p>Similarly, printer and job management applications can use standard query operations to obtain the status information in a common, generic form and use standard management operations to control the state of those printers and jobs.</p>
981<blockquote>
982<p><strong>Note:</strong></p>
d6b36f7f 983<p>CUPS printer drivers necessarily depend on specific file formats and certain implementation details of the CUPS software. Please consult the Postscript and raster printer driver developer documentation on the <a href="https://openprinting.github.io/cups">OpenPrinting CUPS website</a> for more information.</p>
73721e3e 984</blockquote>
b47dab17
MS
985<h3 class="title" id="terms-used-in-this-document">Terms Used in This Document</h3>
986<p>A <em>Destination</em> is a printer or print queue that accepts print jobs. A <em>Print Job</em> is a collection of one or more documents that are processed by a destination using options supplied when creating the job. A <em>Document</em> is a file (JPEG image, PDF file, etc.) suitable for printing. An <em>Option</em> controls some aspect of printing, such as the media used. <em>Media</em> is the sheets or roll that is printed on. An <em>Attribute</em> is an option encoded for an Internet Printing Protocol (IPP) request.</p>
987<h3 class="title" id="compiling-programs-that-use-the-cups-api">Compiling Programs That Use the CUPS API</h3>
d6b36f7f 988<p>The CUPS libraries can be used from any C, C++, or Objective-C program. The method of compiling against the libraries varies depending on the operating system and installation of CUPS. The following sections show how to compile a simple program (shown below) in two common environments.</p>
b47dab17 989<p>The following simple program lists the available destinations:</p>
81a89f7c
MS
990<pre><code class="language-c"><span class="directive">#include &lt;stdio.h&gt;</span>
991<span class="directive">#include &lt;cups/cups.h&gt;</span>
798d6e29 992
81a89f7c 993<span class="reserved">int</span> print_dest(<span class="reserved">void</span> *user_data, <span class="reserved">unsigned</span> flags, cups_dest_t *dest)
798d6e29 994{
81a89f7c
MS
995 <span class="reserved">if</span> (dest-&gt;instance)
996 printf(<span class="string">&quot;%s/%s\n&quot;</span>, dest-&gt;name, dest-&gt;instance);
997 <span class="reserved">else</span>
798d6e29
MS
998 puts(dest-&gt;name);
999
81a89f7c 1000 <span class="reserved">return</span> (<span class="number">1</span>);
798d6e29
MS
1001}
1002
81a89f7c 1003<span class="reserved">int</span> main(<span class="reserved">void</span>)
798d6e29 1004{
81a89f7c 1005 cupsEnumDests(CUPS_DEST_FLAGS_NONE, <span class="number">1000</span>, NULL, <span class="number">0</span>, <span class="number">0</span>, print_dest, NULL);
798d6e29 1006
81a89f7c 1007 <span class="reserved">return</span> (<span class="number">0</span>);
798d6e29
MS
1008}
1009</code></pre>
b47dab17
MS
1010<h4 id="compiling-with-xcode">Compiling with Xcode</h4>
1011<p>In Xcode, choose <em>New Project...</em> from the <em>File</em> menu (or press SHIFT+CMD+N), then select the <em>Command Line Tool</em> under the macOS Application project type. Click <em>Next</em> and enter a name for the project, for example &quot;firstcups&quot;. Click <em>Next</em> and choose a project directory. The click <em>Next</em> to create the project.</p>
1012<p>In the project window, click on the <em>Build Phases</em> group and expand the <em>Link Binary with Libraries</em> section. Click <em>+</em>, type &quot;libcups&quot; to show the library, and then double-click on <code>libcups.tbd</code>.</p>
1013<p>Finally, click on the <code>main.c</code> file in the sidebar and copy the example program to the file. Build and run (CMD+R) to see the list of destinations.</p>
1014<h4 id="compiling-with-gcc">Compiling with GCC</h4>
1015<p>From the command-line, create a file called <code>simple.c</code> using your favorite editor, copy the example to this file, and save. Then run the following command to compile it with GCC and run it:</p>
81a89f7c 1016<pre><code>gcc -o simple `pkg-config --cflags cups` simple.c `pkg-config --libs cups`
798d6e29
MS
1017./simple
1018</code></pre>
81a89f7c 1019<p>The <code>pkg-config</code> command provides the compiler flags (<code>pkg-config --cflags cups</code>) and libraries (<code>pkg-config --libs cups</code>) needed for the local system.</p>
b47dab17
MS
1020<h2 class="title" id="working-with-destinations">Working with Destinations</h2>
1021<p>Destinations, which in CUPS represent individual printers or classes (collections or pools) of printers, are represented by the <code>cups_dest_t</code> structure which includes the name (<code>name</code>), instance (<code>instance</code>, saved options/settings), whether the destination is the default for the user (<code>is_default</code>), and the options and basic information associated with that destination (<code>num_options</code> and <code>options</code>).</p>
1022<p>Historically destinations have been manually maintained by the administrator of a system or network, but CUPS also supports dynamic discovery of destinations on the current network.</p>
1023<h3 class="title" id="finding-available-destinations">Finding Available Destinations</h3>
81a89f7c
MS
1024<p>The <a href="#cupsEnumDests"><code>cupsEnumDests</code></a> function finds all of the available destinations:</p>
1025<pre><code class="language-c"><span class="reserved">int</span>
1026cupsEnumDests(<span class="reserved">unsigned</span> flags, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel,
1027 cups_ptype_t type, cups_ptype_t mask,
1028 cups_dest_cb_t cb, <span class="reserved">void</span> *user_data)
798d6e29 1029</code></pre>
b47dab17
MS
1030<p>The <code>flags</code> argument specifies enumeration options, which at present must be <code>CUPS_DEST_FLAGS_NONE</code>.</p>
1031<p>The <code>msec</code> argument specifies the maximum amount of time that should be used for enumeration in milliseconds - interactive applications should keep this value to 5000 or less when run on the main thread.</p>
1032<p>The <code>cancel</code> argument points to an integer variable that, when set to a non-zero value, will cause enumeration to stop as soon as possible. It can be <code>NULL</code> if not needed.</p>
af268786 1033<p>The <code>type</code> and <code>mask</code> arguments are bitfields that allow the caller to filter the destinations based on categories and/or capabilities. The destination's &quot;printer-type&quot; value is masked by the <code>mask</code> value and compared to the <code>type</code> value when filtering. For example, to only enumerate destinations that are hosted on the local system, pass <code>CUPS_PTYPE_LOCAL</code> for the <code>type</code> argument and <code>CUPS_PTYPE_DISCOVERED</code> for the <code>mask</code> argument. The following constants can be used for filtering:</p>
b47dab17 1034<ul>
af268786 1035<li><p><code>CUPS_PTYPE_CLASS</code>: A collection of destinations.</p>
b47dab17 1036</li>
af268786 1037<li><p><code>CUPS_PTYPE_FAX</code>: A facsimile device.</p>
b47dab17 1038</li>
af268786 1039<li><p><code>CUPS_PTYPE_LOCAL</code>: A local printer or class. This constant has the value 0 (no bits set) and is only used for the <code>type</code> argument and is paired with the <code>CUPS_PTYPE_REMOTE</code> or <code>CUPS_PTYPE_DISCOVERED</code> constant passed in the <code>mask</code> argument.</p>
b47dab17 1040</li>
af268786 1041<li><p><code>CUPS_PTYPE_REMOTE</code>: A remote (shared) printer or class.</p>
b47dab17 1042</li>
af268786 1043<li><p><code>CUPS_PTYPE_DISCOVERED</code>: An available network printer or class.</p>
b47dab17 1044</li>
af268786 1045<li><p><code>CUPS_PTYPE_BW</code>: Can do B&amp;W printing.</p>
b47dab17 1046</li>
af268786 1047<li><p><code>CUPS_PTYPE_COLOR</code>: Can do color printing.</p>
b47dab17 1048</li>
af268786 1049<li><p><code>CUPS_PTYPE_DUPLEX</code>: Can do two-sided printing.</p>
b47dab17 1050</li>
af268786 1051<li><p><code>CUPS_PTYPE_STAPLE</code>: Can staple output.</p>
b47dab17 1052</li>
af268786 1053<li><p><code>CUPS_PTYPE_COLLATE</code>: Can quickly collate copies.</p>
b47dab17 1054</li>
af268786 1055<li><p><code>CUPS_PTYPE_PUNCH</code>: Can punch output.</p>
b47dab17 1056</li>
af268786 1057<li><p><code>CUPS_PTYPE_COVER</code>: Can cover output.</p>
b47dab17 1058</li>
af268786 1059<li><p><code>CUPS_PTYPE_BIND</code>: Can bind output.</p>
b47dab17 1060</li>
af268786 1061<li><p><code>CUPS_PTYPE_SORT</code>: Can sort output (mailboxes, etc.)</p>
b47dab17 1062</li>
af268786 1063<li><p><code>CUPS_PTYPE_SMALL</code>: Can print on Letter/Legal/A4-size media.</p>
b47dab17 1064</li>
af268786 1065<li><p><code>CUPS_PTYPE_MEDIUM</code>: Can print on Tabloid/B/C/A3/A2-size media.</p>
b47dab17 1066</li>
af268786 1067<li><p><code>CUPS_PTYPE_LARGE</code>: Can print on D/E/A1/A0-size media.</p>
b47dab17 1068</li>
af268786 1069<li><p><code>CUPS_PTYPE_VARIABLE</code>: Can print on rolls and custom-size media.</p>
b47dab17 1070</li>
798d6e29 1071</ul>
b47dab17 1072<p>The <code>cb</code> argument specifies a function to call for every destination that is found:</p>
81a89f7c
MS
1073<pre><code class="language-c"><span class="reserved">typedef</span> <span class="reserved">int</span> (*cups_dest_cb_t)(<span class="reserved">void</span> *user_data,
1074 <span class="reserved">unsigned</span> flags,
798d6e29
MS
1075 cups_dest_t *dest);
1076</code></pre>
b47dab17
MS
1077<p>The callback function receives a copy of the <code>user_data</code> argument along with a bitfield (<code>flags</code>) and the destination that was found. The <code>flags</code> argument can have any of the following constant (bit) values set:</p>
1078<ul>
1079<li><p><code>CUPS_DEST_FLAGS_MORE</code>: There are more destinations coming.</p>
1080</li>
1081<li><p><code>CUPS_DEST_FLAGS_REMOVED</code>: The destination has gone away and should be removed from the list of destinations a user can select.</p>
1082</li>
81a89f7c 1083<li><p><code>CUPS_DEST_FLAGS_ERROR</code>: An error occurred. The reason for the error can be found by calling the <a href="#cupsGetError"><code>cupsGetError</code></a> and/or <a href="#cupsGetErrorString"><code>cupsGetErrorString</code></a> functions.</p>
b47dab17 1084</li>
798d6e29 1085</ul>
81a89f7c 1086<p>The callback function returns <code>0</code> to stop enumeration or <code>1</code> to continue.</p>
b47dab17
MS
1087<blockquote>
1088<p><strong>Note:</strong></p>
1089<p>The callback function will likely be called multiple times for the same destination, so it is up to the caller to suppress any duplicate destinations.</p>
718ee2ff 1090</blockquote>
b47dab17 1091<p>The following example shows how to use <code>cupsEnumDests</code> to get a filtered array of destinations:</p>
81a89f7c 1092<pre><code class="language-c"><span class="reserved">typedef</span> <span class="reserved">struct</span>
798d6e29 1093{
81a89f7c 1094 <span class="reserved">int</span> num_dests;
798d6e29
MS
1095 cups_dest_t *dests;
1096} my_user_data_t;
1097
81a89f7c
MS
1098<span class="reserved">int</span>
1099my_dest_cb(my_user_data_t *user_data, <span class="reserved">unsigned</span> flags,
798d6e29
MS
1100 cups_dest_t *dest)
1101{
81a89f7c 1102 <span class="reserved">if</span> (flags &amp; CUPS_DEST_FLAGS_REMOVED)
798d6e29 1103 {
81a89f7c
MS
1104 <span class="comment">/*</span>
1105<span class="comment"> * Remove destination from array...</span>
1106<span class="comment"> */</span>
798d6e29
MS
1107
1108 user_data-&gt;num_dests =
1109 cupsRemoveDest(dest-&gt;name, dest-&gt;instance,
1110 user_data-&gt;num_dests,
1111 &amp;(user_data-&gt;dests));
1112 }
81a89f7c 1113 <span class="reserved">else</span>
798d6e29 1114 {
81a89f7c
MS
1115 <span class="comment">/*</span>
1116<span class="comment"> * Add destination to array...</span>
1117<span class="comment"> */</span>
798d6e29
MS
1118
1119 user_data-&gt;num_dests =
1120 cupsCopyDest(dest, user_data-&gt;num_dests,
1121 &amp;(user_data-&gt;dests));
1122 }
1123
81a89f7c 1124 <span class="reserved">return</span> (<span class="number">1</span>);
798d6e29
MS
1125}
1126
81a89f7c 1127<span class="reserved">int</span>
798d6e29
MS
1128my_get_dests(cups_ptype_t type, cups_ptype_t mask,
1129 cups_dest_t **dests)
1130{
81a89f7c 1131 my_user_data_t user_data = { <span class="number">0</span>, NULL };
798d6e29 1132
81a89f7c 1133 <span class="reserved">if</span> (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, <span class="number">1000</span>, NULL, type,
798d6e29
MS
1134 mask, (cups_dest_cb_t)my_dest_cb,
1135 &amp;user_data))
1136 {
81a89f7c
MS
1137 <span class="comment">/*</span>
1138<span class="comment"> * An error occurred, free all of the destinations and</span>
1139<span class="comment"> * return...</span>
1140<span class="comment"> */</span>
798d6e29 1141
83c55b4b 1142 cupsFreeDests(user_data.num_dests, user_data.dests);
798d6e29
MS
1143
1144 *dests = NULL;
1145
81a89f7c 1146 <span class="reserved">return</span> (<span class="number">0</span>);
798d6e29
MS
1147 }
1148
81a89f7c
MS
1149 <span class="comment">/*</span>
1150<span class="comment"> * Return the destination array...</span>
1151<span class="comment"> */</span>
798d6e29
MS
1152
1153 *dests = user_data.dests;
1154
81a89f7c 1155 <span class="reserved">return</span> (user_data.num_dests);
798d6e29
MS
1156}
1157</code></pre>
b47dab17
MS
1158<h3 class="title" id="basic-destination-information">Basic Destination Information</h3>
1159<p>The <code>num_options</code> and <code>options</code> members of the <code>cups_dest_t</code> structure provide basic attributes about the destination in addition to the user default options and values for that destination. The following names are predefined for various destination attributes:</p>
1160<ul>
1161<li><p>&quot;auth-info-required&quot;: The type of authentication required for printing to this destination: &quot;none&quot;, &quot;username,password&quot;, &quot;domain,username,password&quot;, or &quot;negotiate&quot; (Kerberos).</p>
1162</li>
1163<li><p>&quot;printer-info&quot;: The human-readable description of the destination such as &quot;My Laser Printer&quot;.</p>
1164</li>
1165<li><p>&quot;printer-is-accepting-jobs&quot;: &quot;true&quot; if the destination is accepting new jobs, &quot;false&quot; otherwise.</p>
1166</li>
1167<li><p>&quot;printer-is-shared&quot;: &quot;true&quot; if the destination is being shared with other computers, &quot;false&quot; otherwise.</p>
1168</li>
1169<li><p>&quot;printer-location&quot;: The human-readable location of the destination such as &quot;Lab 4&quot;.</p>
1170</li>
1171<li><p>&quot;printer-make-and-model&quot;: The human-readable make and model of the destination such as &quot;ExampleCorp LaserPrinter 4000 Series&quot;.</p>
1172</li>
1173<li><p>&quot;printer-state&quot;: &quot;3&quot; if the destination is idle, &quot;4&quot; if the destination is printing a job, and &quot;5&quot; if the destination is stopped.</p>
1174</li>
1175<li><p>&quot;printer-state-change-time&quot;: The UNIX time when the destination entered the current state.</p>
1176</li>
1177<li><p>&quot;printer-state-reasons&quot;: Additional comma-delimited state keywords for the destination such as &quot;media-tray-empty-error&quot; and &quot;toner-low-warning&quot;.</p>
1178</li>
1179<li><p>&quot;printer-type&quot;: The <code>cups_ptype_t</code> value associated with the destination.</p>
1180</li>
1181<li><p>&quot;printer-uri-supported&quot;: The URI associated with the destination; if not set, this destination was discovered but is not yet setup as a local printer.</p>
1182</li>
798d6e29 1183</ul>
81a89f7c
MS
1184<p>Use the <a href="#cupsGetOption"><code>cupsGetOption</code></a> function to retrieve the value. For example, the following code gets the make and model of a destination:</p>
1185<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *model = cupsGetOption(<span class="string">&quot;printer-make-and-model&quot;</span>,
798d6e29
MS
1186 dest-&gt;num_options,
1187 dest-&gt;options);
1188</code></pre>
b47dab17 1189<h3 class="title" id="detailed-destination-information">Detailed Destination Information</h3>
81a89f7c
MS
1190<p>Once a destination has been chosen, the <a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a> function can be used to gather detailed information about the destination:</p>
1191<pre><code class="language-c">cups_dinfo_t *
798d6e29
MS
1192cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
1193</code></pre>
b47dab17
MS
1194<p>The <code>http</code> argument specifies a connection to the CUPS scheduler and is typically the constant <code>CUPS_HTTP_DEFAULT</code>. The <code>dest</code> argument specifies the destination to query.</p>
1195<p>The <code>cups_dinfo_t</code> structure that is returned contains a snapshot of the supported options and their supported, ready, and default values. It also can report constraints between different options and values, and recommend changes to resolve those constraints.</p>
1196<h4 id="getting-supported-options-and-values">Getting Supported Options and Values</h4>
81a89f7c
MS
1197<p>The <a href="#cupsCheckDestSupported"><code>cupsCheckDestSupported</code></a> function can be used to test whether a particular option or option and value is supported:</p>
1198<pre><code class="language-c"><span class="reserved">int</span>
798d6e29
MS
1199cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
1200 cups_dinfo_t *info,
81a89f7c
MS
1201 <span class="reserved">const</span> <span class="reserved">char</span> *option,
1202 <span class="reserved">const</span> <span class="reserved">char</span> *value);
798d6e29 1203</code></pre>
b47dab17
MS
1204<p>The <code>option</code> argument specifies the name of the option to check. The following constants can be used to check the various standard options:</p>
1205<ul>
1206<li><p><code>CUPS_COPIES</code>: Controls the number of copies that are produced.</p>
1207</li>
1208<li><p><code>CUPS_FINISHINGS</code>: A comma-delimited list of integer constants that control the finishing processes that are applied to the job, including stapling, punching, and folding.</p>
1209</li>
1210<li><p><code>CUPS_MEDIA</code>: Controls the media size that is used, typically one of the following: <code>CUPS_MEDIA_3X5</code>, <code>CUPS_MEDIA_4X6</code>, <code>CUPS_MEDIA_5X7</code>, <code>CUPS_MEDIA_8X10</code>, <code>CUPS_MEDIA_A3</code>, <code>CUPS_MEDIA_A4</code>, <code>CUPS_MEDIA_A5</code>, <code>CUPS_MEDIA_A6</code>, <code>CUPS_MEDIA_ENV10</code>, <code>CUPS_MEDIA_ENVDL</code>, <code>CUPS_MEDIA_LEGAL</code>, <code>CUPS_MEDIA_LETTER</code>, <code>CUPS_MEDIA_PHOTO_L</code>, <code>CUPS_MEDIA_SUPERBA3</code>, or <code>CUPS_MEDIA_TABLOID</code>.</p>
1211</li>
1212<li><p><code>CUPS_MEDIA_SOURCE</code>: Controls where the media is pulled from, typically either <code>CUPS_MEDIA_SOURCE_AUTO</code> or <code>CUPS_MEDIA_SOURCE_MANUAL</code>.</p>
1213</li>
1214<li><p><code>CUPS_MEDIA_TYPE</code>: Controls the type of media that is used, typically one of the following: <code>CUPS_MEDIA_TYPE_AUTO</code>, <code>CUPS_MEDIA_TYPE_ENVELOPE</code>, <code>CUPS_MEDIA_TYPE_LABELS</code>, <code>CUPS_MEDIA_TYPE_LETTERHEAD</code>, <code>CUPS_MEDIA_TYPE_PHOTO</code>, <code>CUPS_MEDIA_TYPE_PHOTO_GLOSSY</code>, <code>CUPS_MEDIA_TYPE_PHOTO_MATTE</code>, <code>CUPS_MEDIA_TYPE_PLAIN</code>, or <code>CUPS_MEDIA_TYPE_TRANSPARENCY</code>.</p>
1215</li>
1216<li><p><code>CUPS_NUMBER_UP</code>: Controls the number of document pages that are placed on each media side.</p>
1217</li>
1218<li><p><code>CUPS_ORIENTATION</code>: Controls the orientation of document pages placed on the media: <code>CUPS_ORIENTATION_PORTRAIT</code> or <code>CUPS_ORIENTATION_LANDSCAPE</code>.</p>
1219</li>
1220<li><p><code>CUPS_PRINT_COLOR_MODE</code>: Controls whether the output is in color (<code>CUPS_PRINT_COLOR_MODE_COLOR</code>), grayscale (<code>CUPS_PRINT_COLOR_MODE_MONOCHROME</code>), or either (<code>CUPS_PRINT_COLOR_MODE_AUTO</code>).</p>
1221</li>
1222<li><p><code>CUPS_PRINT_QUALITY</code>: Controls the generate quality of the output: <code>CUPS_PRINT_QUALITY_DRAFT</code>, <code>CUPS_PRINT_QUALITY_NORMAL</code>, or <code>CUPS_PRINT_QUALITY_HIGH</code>.</p>
1223</li>
1224<li><p><code>CUPS_SIDES</code>: Controls whether prints are placed on one or both sides of the media: <code>CUPS_SIDES_ONE_SIDED</code>, <code>CUPS_SIDES_TWO_SIDED_PORTRAIT</code>, or <code>CUPS_SIDES_TWO_SIDED_LANDSCAPE</code>.</p>
1225</li>
798d6e29 1226</ul>
b47dab17 1227<p>If the <code>value</code> argument is <code>NULL</code>, the <code>cupsCheckDestSupported</code> function returns whether the option is supported by the destination. Otherwise, the function returns whether the specified value of the option is supported.</p>
81a89f7c
MS
1228<p>The <a href="#cupsFindDestSupported"><code>cupsFindDestSupported</code></a> function returns the IPP attribute containing the supported values for a given option:</p>
1229<pre><code class="language-c">ipp_attribute_t *
1230cupsFindDestSupported(http_t *http, cups_dest_t *dest,
1231 cups_dinfo_t *dinfo,
1232 <span class="reserved">const</span> <span class="reserved">char</span> *option);
798d6e29 1233</code></pre>
b47dab17 1234<p>For example, the following code prints the supported finishing processes for a destination, if any, to the standard output:</p>
81a89f7c 1235<pre><code class="language-c">cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT,
798d6e29
MS
1236 dest);
1237
81a89f7c 1238<span class="reserved">if</span> (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info,
798d6e29
MS
1239 CUPS_FINISHINGS, NULL))
1240{
1241 ipp_attribute_t *finishings =
1242 cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
1243 CUPS_FINISHINGS);
81a89f7c 1244 <span class="reserved">int</span> i, count = ippGetCount(finishings);
798d6e29 1245
81a89f7c
MS
1246 puts(<span class="string">&quot;finishings supported:&quot;</span>);
1247 <span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
1248 {
1249 <span class="reserved">int</span> val = ippGetInteger(finishings, i);
1250 printf(<span class="string">&quot; %d (%s)\n&quot;</span>, val,
1251 ippEnumString(<span class="string">&quot;finishings&quot;</span>, val));
1252}
1253<span class="reserved">else</span>
1254{
1255 puts(<span class="string">&quot;finishings not supported.&quot;</span>);
798d6e29 1256}
798d6e29 1257</code></pre>
b47dab17 1258<p>The &quot;job-creation-attributes&quot; option can be queried to get a list of supported options. For example, the following code prints the list of supported options to the standard output:</p>
81a89f7c 1259<pre><code class="language-c">ipp_attribute_t *attrs =
798d6e29 1260 cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
81a89f7c
MS
1261 <span class="string">&quot;job-creation-attributes&quot;</span>);
1262<span class="reserved">int</span> i, count = ippGetCount(attrs);
798d6e29 1263
81a89f7c 1264<span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
798d6e29
MS
1265 puts(ippGetString(attrs, i, NULL));
1266</code></pre>
b47dab17 1267<h4 id="getting-default-values">Getting Default Values</h4>
81a89f7c
MS
1268<p>There are two sets of default values - user defaults that are available via the <code>num_options</code> and <code>options</code> members of the <code>cups_dest_t</code> structure, and destination defaults that available via the <code>cups_dinfo_t</code> structure and the <a href="#cupsFindDestDefault"><code>cupsFindDestDefault</code></a> function which returns the IPP attribute containing the default value(s) for a given option:</p>
1269<pre><code class="language-c">ipp_attribute_t *
798d6e29
MS
1270cupsFindDestDefault(http_t *http, cups_dest_t *dest,
1271 cups_dinfo_t *dinfo,
81a89f7c 1272 <span class="reserved">const</span> <span class="reserved">char</span> *option);
798d6e29 1273</code></pre>
81a89f7c
MS
1274<p>The user defaults from <a href="#cupsGetOption"><code>cupsGetOption</code></a> should always take preference over the destination defaults. For example, the following code prints the default finishings value(s) to the standard output:</p>
1275<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *def_value =
798d6e29
MS
1276 cupsGetOption(CUPS_FINISHINGS, dest-&gt;num_options,
1277 dest-&gt;options);
1278ipp_attribute_t *def_attr =
1279 cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info,
1280 CUPS_FINISHINGS);
1281
81a89f7c 1282<span class="reserved">if</span> (def_value != NULL)
798d6e29 1283{
81a89f7c 1284 printf(<span class="string">&quot;Default finishings: %s\n&quot;</span>, def_value);
798d6e29 1285}
81a89f7c 1286<span class="reserved">else</span>
798d6e29 1287{
81a89f7c 1288 <span class="reserved">int</span> i, count = ippGetCount(def_attr);
798d6e29 1289
81a89f7c
MS
1290 printf(<span class="string">&quot;Default finishings: %d&quot;</span>,
1291 ippGetInteger(def_attr, <span class="number">0</span>));
1292 <span class="reserved">for</span> (i = <span class="number">1</span>; i &lt; count; i ++)
1293 printf(<span class="string">&quot;,%d&quot;</span>, ippGetInteger(def_attr, i));
1294 putchar(<span class="string">'\n'</span>);
798d6e29
MS
1295}
1296</code></pre>
b47dab17
MS
1297<h4 id="getting-ready-loaded-values">Getting Ready (Loaded) Values</h4>
1298<p>The finishings and media options also support queries for the ready, or loaded, values. For example, a printer may have punch and staple finishers installed but be out of staples - the supported values will list both punch and staple finishing processes but the ready values will only list the punch processes. Similarly, a printer may support hundreds of different sizes of media but only have a single size loaded at any given time - the ready values are limited to the media that is actually in the printer.</p>
81a89f7c
MS
1299<p>The <a href="#cupsFindDestReady"><code>cupsFindDestReady</code></a> function finds the IPP attribute containing the ready values for a given option:</p>
1300<pre><code class="language-c">ipp_attribute_t *
798d6e29 1301cupsFindDestReady(http_t *http, cups_dest_t *dest,
81a89f7c 1302 cups_dinfo_t *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option);
798d6e29 1303</code></pre>
b47dab17 1304<p>For example, the following code lists the ready finishing processes:</p>
81a89f7c 1305<pre><code class="language-c">ipp_attribute_t *ready_finishings =
798d6e29
MS
1306 cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info,
1307 CUPS_FINISHINGS);
1308
81a89f7c 1309<span class="reserved">if</span> (ready_finishings != NULL)
798d6e29 1310{
81a89f7c 1311 <span class="reserved">int</span> i, count = ippGetCount(ready_finishings);
798d6e29 1312
81a89f7c
MS
1313 puts(<span class="string">&quot;finishings ready:&quot;</span>);
1314 <span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
1315 {
1316 <span class="reserved">int</span> val = ippGetInteger(ready_finishings, i);
1317 printf(<span class="string">&quot; %d (%s)\n&quot;</span>, val,
1318 ippEnumString(<span class="string">&quot;finishings&quot;</span>, val));
1319}
1320<span class="reserved">else</span>
1321{
1322 puts(<span class="string">&quot;no finishings are ready.&quot;</span>);
798d6e29 1323}
798d6e29 1324</code></pre>
81a89f7c
MS
1325<h4 id="media-options">Media Options</h4>
1326<p>CUPS provides functions for querying the dimensions, margins, color, source (tray/roll), and type for each of the supported media size options. The <code>cups_media_t</code> structure is used to describe media:</p>
1327<pre><code class="language-c"><span class="reserved">typedef</span> <span class="reserved">struct</span> cups_media_s
798d6e29 1328{
81a89f7c
MS
1329 <span class="reserved">char</span> media[<span class="number">128</span>];
1330 <span class="reserved">char</span> color[<span class="number">128</span>];
1331 <span class="reserved">char</span> source[<span class="number">128</span>];
1332 <span class="reserved">char</span> type[<span class="number">128</span>];
1333 <span class="reserved">int</span> width, length;
1334 <span class="reserved">int</span> bottom, left, right, top;
1335} cups_media_t;
798d6e29 1336</code></pre>
81a89f7c 1337<p>The &quot;media&quot; member specifies a PWG self-describing media size name such as &quot;na_letter_8.5x11in&quot;, &quot;iso_a4_210x297mm&quot;, etc. The &quot;color&quot; member specifies a PWG media color name such as &quot;white&quot;, &quot;blue&quot;, etc. The &quot;source&quot; member specifies a standard keyword for the paper tray or roll such as &quot;tray-1&quot;, &quot;manual&quot;, &quot;by-pass-tray&quot; (multi-purpose tray), etc. The &quot;type&quot; member specifies a PWG media type name such as &quot;stationery&quot; (plain paper), &quot;photographic&quot;, &quot;envelope&quot;, &quot;transparency&quot;, etc.</p>
b47dab17 1338<p>The <code>width</code> and <code>length</code> members specify the dimensions of the media in hundredths of millimeters (1/2540th of an inch). The <code>bottom</code>, <code>left</code>, <code>right</code>, and <code>top</code> members specify the margins of the printable area, also in hundredths of millimeters.</p>
81a89f7c
MS
1339<p>The <a href="#cupsGetDestMediaByName2"><code>cupsGetDestMediaByName2</code></a> and <a href="#cupsGetDestMediaBySize2"><code>cupsGetDestMediaBySize2</code></a> functions lookup the media information using a standard media size name or dimensions in hundredths of millimeters:</p>
1340<pre><code class="language-c"><span class="reserved">bool</span>
1341cupsGetDestMediaByName2(http_t *http, cups_dest_t *dest,
1342 cups_dinfo_t *dinfo,
1343 <span class="reserved">const</span> <span class="reserved">char</span> *name,
1344 <span class="reserved">unsigned</span> flags, cups_media_t *media);
798d6e29 1345
81a89f7c
MS
1346<span class="reserved">bool</span>
1347cupsGetDestMediaBySize2(http_t *http, cups_dest_t *dest,
1348 cups_dinfo_t *dinfo,
1349 <span class="reserved">int</span> width, <span class="reserved">int</span> length,
1350 <span class="reserved">unsigned</span> flags, cups_media_t *media);
798d6e29 1351</code></pre>
81a89f7c 1352<p>The <code>name</code>, <code>width</code>, and <code>length</code> arguments specify the size to lookup. The <code>flags</code> argument specifies a bitfield controlling various lookup options:</p>
b47dab17
MS
1353<ul>
1354<li><p><code>CUPS_MEDIA_FLAGS_DEFAULT</code>: Find the closest size supported by the printer.</p>
1355</li>
1356<li><p><code>CUPS_MEDIA_FLAGS_BORDERLESS</code>: Find a borderless size.</p>
1357</li>
1358<li><p><code>CUPS_MEDIA_FLAGS_DUPLEX</code>: Find a size compatible with two-sided printing.</p>
1359</li>
1360<li><p><code>CUPS_MEDIA_FLAGS_EXACT</code>: Find an exact match for the size.</p>
1361</li>
1362<li><p><code>CUPS_MEDIA_FLAGS_READY</code>: If the printer supports media sensing or configuration of the media in each tray/source, find the size amongst the &quot;ready&quot; media.</p>
1363</li>
798d6e29 1364</ul>
81a89f7c 1365<p>If a matching size is found for the destination, the size information is stored in the structure pointed to by the <code>media</code> argument and <code>true</code> is returned. Otherwise <code>false</code> is returned.</p>
b47dab17 1366<p>For example, the following code prints the margins for two-sided printing on US Letter media:</p>
81a89f7c 1367<pre><code class="language-c">cups_media_t media:
798d6e29 1368
81a89f7c
MS
1369<span class="reserved">if</span> (cupsGetDestMediaByName2(CUPS_HTTP_DEFAULT, dest, info,
1370 CUPS_MEDIA_LETTER,
1371 CUPS_MEDIA_FLAGS_DUPLEX, &amp;size))
1372{
1373 puts(<span class="string">&quot;Margins for duplex US Letter:&quot;</span>);
1374 printf(<span class="string">&quot; Bottom: %.2fin\n&quot;</span>, media.bottom / <span class="number">2540.0</span>);
1375 printf(<span class="string">&quot; Left: %.2fin\n&quot;</span>, media.left / <span class="number">2540.0</span>);
1376 printf(<span class="string">&quot; Right: %.2fin\n&quot;</span>, media.right / <span class="number">2540.0</span>);
1377 printf(<span class="string">&quot; Top: %.2fin\n&quot;</span>, media.top / <span class="number">2540.0</span>);
1378}
1379<span class="reserved">else</span>
798d6e29 1380{
81a89f7c
MS
1381 puts(<span class="string">&quot;Margins for duplex US Letter are not available.&quot;</span>);
1382}
798d6e29 1383</code></pre>
81a89f7c
MS
1384<p>You can also enumerate all of the sizes that match a given <code>flags</code> value using the <a href="#cupsGetDestMediaByIndex2"><code>cupsGetDestMediaByIndex2</code></a> and <a href="#cupsGetDestMediaCount"><code>cupsGetDestMediaCount</code></a> functions:</p>
1385<pre><code class="language-c"><span class="reserved">bool</span>
1386cupsGetDestMediaByIndex2(http_t *http, cups_dest_t *dest,
1387 cups_dinfo_t *dinfo, size_t n,
1388 <span class="reserved">unsigned</span> flags, cups_media_t *media);
798d6e29 1389
81a89f7c 1390<span class="reserved">int</span>
798d6e29 1391cupsGetDestMediaCount(http_t *http, cups_dest_t *dest,
81a89f7c 1392 cups_dinfo_t *dinfo, <span class="reserved">unsigned</span> flags);
798d6e29 1393</code></pre>
b47dab17 1394<p>For example, the following code prints the list of ready media and corresponding margins:</p>
81a89f7c
MS
1395<pre><code class="language-c">cups_media_t media;
1396size_t i;
1397size_t count = (size_t)cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
1398 dest, info,
1399 CUPS_MEDIA_FLAGS_READY);
798d6e29 1400
81a89f7c 1401<span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
798d6e29 1402{
81a89f7c
MS
1403 <span class="reserved">if</span> (cupsGetDestMediaByIndex2(CUPS_HTTP_DEFAULT, dest, info,
1404 i, CUPS_MEDIA_FLAGS_READY,
1405 &amp;media))
798d6e29 1406 {
81a89f7c
MS
1407 printf(<span class="string">&quot;%s:\n&quot;</span>, media.name);
1408 printf(<span class="string">&quot; Width: %.2fin\n&quot;</span>, media.width / <span class="number">2540.0</span>);
1409 printf(<span class="string">&quot; Length: %.2fin\n&quot;</span>, media.length / <span class="number">2540.0</span>);
1410 printf(<span class="string">&quot; Bottom: %.2fin\n&quot;</span>, media.bottom / <span class="number">2540.0</span>);
1411 printf(<span class="string">&quot; Left: %.2fin\n&quot;</span>, media.left / <span class="number">2540.0</span>);
1412 printf(<span class="string">&quot; Right: %.2fin\n&quot;</span>, media.right / <span class="number">2540.0</span>);
1413 printf(<span class="string">&quot; Top: %.2fin\n&quot;</span>, media.top / <span class="number">2540.0</span>);
798d6e29
MS
1414 }
1415}
1416</code></pre>
81a89f7c
MS
1417<p>Finally, the <a href="#cupsGetDestMediaDefault2"><code>cupsGetDestMediaDefault2</code></a> function returns the default media:</p>
1418<pre><code class="language-c"><span class="reserved">int</span>
1419cupsGetDestMediaDefault2(http_t *http, cups_dest_t *dest,
1420 cups_dinfo_t *dinfo, <span class="reserved">unsigned</span> flags,
1421 cups_media_t *media);
798d6e29 1422</code></pre>
b47dab17 1423<h4 id="localizing-options-and-values">Localizing Options and Values</h4>
81a89f7c
MS
1424<p>CUPS provides three functions to get localized, human-readable strings in the user's current locale for options and values: <a href="#cupsLocalizeDestMedia2"><code>cupsLocalizeDestMedia2</code></a>, <a href="#cupsLocalizeDestOption"><code>cupsLocalizeDestOption</code></a>, and <a href="#cupsLocalizeDestValue"><code>cupsLocalizeDestValue</code></a>:</p>
1425<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *
1426cupsLocalizeDestMedia2(http_t *http, cups_dest_t *dest,
1427 cups_dinfo_t *info, <span class="reserved">unsigned</span> flags,
1428 cups_media_t *media);
798d6e29 1429
81a89f7c 1430<span class="reserved">const</span> <span class="reserved">char</span> *
798d6e29
MS
1431cupsLocalizeDestOption(http_t *http, cups_dest_t *dest,
1432 cups_dinfo_t *info,
81a89f7c 1433 <span class="reserved">const</span> <span class="reserved">char</span> *option);
798d6e29 1434
81a89f7c 1435<span class="reserved">const</span> <span class="reserved">char</span> *
798d6e29
MS
1436cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
1437 cups_dinfo_t *info,
81a89f7c
MS
1438 <span class="reserved">const</span> <span class="reserved">char</span> *option, <span class="reserved">const</span> <span class="reserved">char</span> *value);
1439</code></pre>
1440<blockquote>
1441<p><strong>Note:</strong></p>
1442<p>These functions require a valid <code>http_t</code> connection to work. Use the <a href="#cupsConnectDest"><code>cupsConnectDest</code></a> function to connect to the destination for its localization information.</p>
1443</blockquote>
1444<p>For example, the following code will list the localized media names for a destination:</p>
1445<pre><code class="language-c"><span class="reserved">char</span> resource[<span class="number">256</span>];
1446http_t *http = cupsConnectDest(dest, CUPS_DEST_FLAGS_NONE,
1447 <span class="comment">/*msec*/</span><span class="number">30000</span>, <span class="comment">/*cancel*/</span>NULL,
1448 resource, <span class="reserved">sizeof</span>(resource),
1449 <span class="comment">/*dest_cb*/</span>NULL, <span class="comment">/*user_data*/</span>NULL);
1450
1451size_t i;
1452size_t count = (size_t)cupsGetDestMediaCount(http, dest, info,
1453 CUPS_MEDIA_FLAGS_DEFAULT);
1454cups_media_t media;
1455<span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
1456{
1457 <span class="reserved">if</span> (cupsGetDestMediaByIndex2(http, dest, info, i,
1458 CUPS_MEDIA_FLAGS_DEFAULT, &amp;media))
1459 printf(<span class="string">&quot;%s: %s\n&quot;</span>, media.name,
1460 cupsLocalizeDestMedia2(http, dest, info,
1461 CUPS_MEDIA_FLAGS_DEFAULT, &amp;media));
1462}
798d6e29 1463</code></pre>
b47dab17 1464<h3 class="title" id="submitting-a-print-job">Submitting a Print Job</h3>
81a89f7c
MS
1465<p>Once you are ready to submit a print job, you create a job using the <a href="#cupsCreateDestJob"><code>cupsCreateDestJob</code></a> function:</p>
1466<pre><code class="language-c">ipp_status_t
798d6e29 1467cupsCreateDestJob(http_t *http, cups_dest_t *dest,
81a89f7c
MS
1468 cups_dinfo_t *info, <span class="reserved">int</span> *job_id,
1469 <span class="reserved">const</span> <span class="reserved">char</span> *title, <span class="reserved">int</span> num_options,
798d6e29
MS
1470 cups_option_t *options);
1471</code></pre>
b47dab17
MS
1472<p>The <code>title</code> argument specifies a name for the print job such as &quot;My Document&quot;. The <code>num_options</code> and <code>options</code> arguments specify the options for the print job which are allocated using the <code>cupsAddOption</code> function.</p>
1473<p>When successful, the job's numeric identifier is stored in the integer pointed to by the <code>job_id</code> argument and <code>IPP_STATUS_OK</code> is returned. Otherwise, an IPP error status is returned.</p>
1474<p>For example, the following code creates a new job that will print 42 copies of a two-sided US Letter document:</p>
81a89f7c
MS
1475<pre><code class="language-c"><span class="reserved">int</span> job_id = <span class="number">0</span>;
1476<span class="reserved">int</span> num_options = <span class="number">0</span>;
798d6e29
MS
1477cups_option_t *options = NULL;
1478
81a89f7c 1479num_options = cupsAddOption(CUPS_COPIES, <span class="string">&quot;42&quot;</span>,
798d6e29
MS
1480 num_options, &amp;options);
1481num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER,
1482 num_options, &amp;options);
1483num_options = cupsAddOption(CUPS_SIDES,
1484 CUPS_SIDES_TWO_SIDED_PORTRAIT,
1485 num_options, &amp;options);
1486
81a89f7c
MS
1487<span class="reserved">if</span> (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info,
1488 &amp;job_id, <span class="string">&quot;My Document&quot;</span>, num_options,
798d6e29 1489 options) == IPP_STATUS_OK)
81a89f7c
MS
1490 printf(<span class="string">&quot;Created job: %d\n&quot;</span>, job_id);
1491<span class="reserved">else</span>
1492 printf(<span class="string">&quot;Unable to create job: %s\n&quot;</span>,
1493 cupsGetErrorString());
798d6e29 1494</code></pre>
81a89f7c
MS
1495<p>Once the job is created, you submit documents for the job using the <a href="#cupsStartDestDocument"><code>cupsStartDestDocument</code></a>, <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a>, and <a href="#cupsFinishDestDocument"><code>cupsFinishDestDocument</code></a> functions:</p>
1496<pre><code class="language-c">http_status_t
798d6e29 1497cupsStartDestDocument(http_t *http, cups_dest_t *dest,
81a89f7c
MS
1498 cups_dinfo_t *info, <span class="reserved">int</span> job_id,
1499 <span class="reserved">const</span> <span class="reserved">char</span> *docname,
1500 <span class="reserved">const</span> <span class="reserved">char</span> *format,
1501 <span class="reserved">int</span> num_options,
798d6e29 1502 cups_option_t *options,
81a89f7c 1503 <span class="reserved">int</span> last_document);
798d6e29
MS
1504
1505http_status_t
81a89f7c 1506cupsWriteRequestData(http_t *http, <span class="reserved">const</span> <span class="reserved">char</span> *buffer,
798d6e29
MS
1507 size_t length);
1508
1509ipp_status_t
1510cupsFinishDestDocument(http_t *http, cups_dest_t *dest,
1511 cups_dinfo_t *info);
1512</code></pre>
b47dab17
MS
1513<p>The <code>docname</code> argument specifies the name of the document, typically the original filename. The <code>format</code> argument specifies the MIME media type of the document, including the following constants:</p>
1514<ul>
81a89f7c
MS
1515<li><p><code>CUPS_FORMAT_AUTO</code>: &quot;application/octet-stream&quot;</p>
1516</li>
b47dab17
MS
1517<li><p><code>CUPS_FORMAT_JPEG</code>: &quot;image/jpeg&quot;</p>
1518</li>
1519<li><p><code>CUPS_FORMAT_PDF</code>: &quot;application/pdf&quot;</p>
1520</li>
b47dab17
MS
1521<li><p><code>CUPS_FORMAT_TEXT</code>: &quot;text/plain&quot;</p>
1522</li>
798d6e29 1523</ul>
b47dab17
MS
1524<p>The <code>num_options</code> and <code>options</code> arguments specify per-document print options, which at present must be 0 and <code>NULL</code>. The <code>last_document</code> argument specifies whether this is the last document in the job.</p>
1525<p>For example, the following code submits a PDF file to the job that was just created:</p>
81a89f7c 1526<pre><code class="language-c">FILE *fp = fopen(<span class="string">&quot;filename.pdf&quot;</span>, <span class="string">&quot;rb&quot;</span>);
798d6e29 1527size_t bytes;
81a89f7c 1528<span class="reserved">char</span> buffer[<span class="number">65536</span>];
798d6e29 1529
81a89f7c
MS
1530<span class="reserved">if</span> (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info,
1531 job_id, <span class="string">&quot;filename.pdf&quot;</span>, <span class="number">0</span>, NULL,
1532 <span class="number">1</span>) == HTTP_STATUS_CONTINUE)
798d6e29 1533{
81a89f7c
MS
1534 <span class="reserved">while</span> ((bytes = fread(buffer, <span class="number">1</span>, <span class="reserved">sizeof</span>(buffer), fp)) &gt; <span class="number">0</span>)
1535 {
1536 <span class="reserved">if</span> (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer,
798d6e29 1537 bytes) != HTTP_STATUS_CONTINUE)
81a89f7c
MS
1538 <span class="reserved">break</span>;
1539 }
798d6e29 1540
81a89f7c 1541 <span class="reserved">if</span> (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest,
798d6e29 1542 info) == IPP_STATUS_OK)
81a89f7c
MS
1543 puts(<span class="string">&quot;Document send succeeded.&quot;</span>);
1544 <span class="reserved">else</span>
1545 printf(<span class="string">&quot;Document send failed: %s\n&quot;</span>,
1546 cupsGetErrorString());
798d6e29
MS
1547}
1548
1549fclose(fp);
1550</code></pre>
b47dab17
MS
1551<h2 class="title" id="sending-ipp-requests">Sending IPP Requests</h2>
1552<p>CUPS provides a rich API for sending IPP requests to the scheduler or printers, typically from management or utility applications whose primary purpose is not to send print jobs.</p>
1553<h3 class="title" id="connecting-to-the-scheduler-or-printer">Connecting to the Scheduler or Printer</h3>
81a89f7c
MS
1554<p>The connection to the scheduler or printer is represented by the HTTP connection type <code>http_t</code>. The <a href="#cupsConnectDest"><code>cupsConnectDest</code></a> function connects to the scheduler or printer associated with the destination:</p>
1555<pre><code class="language-c">http_t *
1556cupsConnectDest(cups_dest_t *dest, <span class="reserved">unsigned</span> flags, <span class="reserved">int</span> msec,
1557 <span class="reserved">int</span> *cancel, <span class="reserved">char</span> *resource,
b0fb2d75 1558 size_t resourcesize, cups_dest_cb_t cb,
81a89f7c 1559 <span class="reserved">void</span> *user_data);
b0fb2d75 1560</code></pre>
b47dab17
MS
1561<p>The <code>dest</code> argument specifies the destination to connect to.</p>
1562<p>The <code>flags</code> argument specifies whether you want to connect to the scheduler (<code>CUPS_DEST_FLAGS_NONE</code>) or device/printer (<code>CUPS_DEST_FLAGS_DEVICE</code>) associated with the destination.</p>
1563<p>The <code>msec</code> argument specifies how long you are willing to wait for the connection to be established in milliseconds. Specify a value of <code>-1</code> to wait indefinitely.</p>
1564<p>The <code>cancel</code> argument specifies the address of an integer variable that can be set to a non-zero value to cancel the connection. Specify a value of <code>NULL</code> to not provide a cancel variable.</p>
1565<p>The <code>resource</code> and <code>resourcesize</code> arguments specify the address and size of a character string array to hold the path to use when sending an IPP request.</p>
81a89f7c 1566<p>The <code>cb</code> and <code>user_data</code> arguments specify a destination callback function that returns 1 to continue connecting or 0 to stop. The destination callback works the same way as the one used for the <a href="#cupsEnumDests"><code>cupsEnumDests</code></a> function.</p>
b47dab17
MS
1567<p>On success, a HTTP connection is returned that can be used to send IPP requests and get IPP responses.</p>
1568<p>For example, the following code connects to the printer associated with a destination with a 30 second timeout:</p>
81a89f7c 1569<pre><code class="language-c"><span class="reserved">char</span> resource[<span class="number">256</span>];
b0fb2d75 1570http_t *http = cupsConnectDest(dest, CUPS_DEST_FLAGS_DEVICE,
81a89f7c
MS
1571 <span class="number">30000</span>, <span class="comment">/*cancel*/</span>NULL, resource,
1572 <span class="reserved">sizeof</span>(resource),
1573 <span class="comment">/*cb*/</span>NULL, <span class="comment">/*user_data*/</span>NULL);
b0fb2d75 1574</code></pre>
b47dab17
MS
1575<h3 class="title" id="creating-an-ipp-request">Creating an IPP Request</h3>
1576<p>IPP requests are represented by the IPP message type <code>ipp_t</code> and each IPP attribute in the request is representing using the type <code>ipp_attribute_t</code>. Each IPP request includes an operation code (<code>IPP_OP_CREATE_JOB</code>, <code>IPP_OP_GET_PRINTER_ATTRIBUTES</code>, etc.) and a 32-bit integer identifier.</p>
1577<p>The <code>ippNewRequest</code> function creates a new IPP request:</p>
81a89f7c 1578<pre><code class="language-c">ipp_t *
b0fb2d75
MS
1579ippNewRequest(ipp_op_t op);
1580</code></pre>
b47dab17 1581<p>The <code>op</code> argument specifies the IPP operation code for the request. For example, the following code creates an IPP Get-Printer-Attributes request:</p>
81a89f7c 1582<pre><code class="language-c">ipp_t *request = ippNewRequest(IPP_OP_GET_PRINTER_ATTRIBUTES);
b0fb2d75 1583</code></pre>
b47dab17
MS
1584<p>The request identifier is automatically set to a unique value for the current process.</p>
1585<p>Each IPP request starts with two IPP attributes, &quot;attributes-charset&quot; and &quot;attributes-natural-language&quot;, followed by IPP attribute(s) that specify the target of the operation. The <code>ippNewRequest</code> automatically adds the correct &quot;attributes-charset&quot; and &quot;attributes-natural-language&quot; attributes, but you must add the target attribute(s). For example, the following code adds the &quot;printer-uri&quot; attribute to the IPP Get-Printer-Attributes request to specify which printer is being queried:</p>
81a89f7c 1586<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *printer_uri = cupsGetOption(<span class="string">&quot;device-uri&quot;</span>,
b0fb2d75
MS
1587 dest-&gt;num_options,
1588 dest-&gt;options);
1589
1590ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI,
81a89f7c
MS
1591 <span class="string">&quot;printer-uri&quot;</span>, <span class="comment">/*language*/</span>NULL, printer_uri);
1592```c
b6008d6b
MS
1593
1594&gt; **Note:**
1595&gt;
1596&gt; If we wanted to query the scheduler instead of the device, we would look
1597&gt; up the <span class="string">&quot;printer-uri-supported&quot;</span> option instead of the <span class="string">&quot;device-uri&quot;</span> value.
1598
1599The [`ippAddString`](@@) function adds the <span class="string">&quot;printer-uri&quot;</span> attribute to the IPP
1600request. The `IPP_TAG_OPERATION` argument specifies that the attribute is part
1601of the operation. The `IPP_TAG_URI` argument specifies that the value is a
1602Universal Resource Identifier (URI) string. The `NULL` argument specifies there
1603is no language (English, French, Japanese, etc.) associated with the string, <span class="reserved">and</span>
1604the `printer_uri` argument specifies the string value.
1605
1606The IPP Get-Printer-Attributes request also supports an IPP attribute called
1607<span class="string">&quot;requested-attributes&quot;</span> that lists the attributes <span class="reserved">and</span> values you are interested
1608in. For example, the following code requests the printer state attributes:
1609
1610```c
1611<span class="reserved">static</span> <span class="reserved">const</span> <span class="reserved">char</span> * <span class="reserved">const</span> requested_attributes[] =
b0fb2d75 1612{
81a89f7c
MS
1613 <span class="string">&quot;printer-state&quot;</span>,
1614 <span class="string">&quot;printer-state-message&quot;</span>,
1615 <span class="string">&quot;printer-state-reasons&quot;</span>
b0fb2d75
MS
1616};
1617
1618ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
81a89f7c 1619 <span class="string">&quot;requested-attributes&quot;</span>, <span class="number">3</span>, <span class="comment">/*language*/</span>NULL,
b0fb2d75
MS
1620 requested_attributes);
1621</code></pre>
81a89f7c 1622<p>The <a href="#ippAddStrings"><code>ippAddStrings</code></a> function adds an attribute with one or more strings, in this case three. The <code>IPP_TAG_KEYWORD</code> argument specifies that the strings are keyword values, which are used for attribute names. All strings use the same language (<code>NULL</code> for none), and the attribute will contain the three strings in the array <code>requested_attributes</code>.</p>
b47dab17
MS
1623<p>CUPS provides many functions to adding attributes of different types:</p>
1624<ul>
81a89f7c 1625<li><p><a href="#ippAddBoolean"><code>ippAddBoolean</code></a> adds a boolean (<code>IPP_TAG_BOOLEAN</code>) attribute with one value.</p>
b47dab17 1626</li>
81a89f7c 1627<li><p><a href="#ippAddInteger"><code>ippAddInteger</code></a> adds an enum (<code>IPP_TAG_ENUM</code>) or integer (<code>IPP_TAG_INTEGER</code>) attribute with one value.</p>
b47dab17 1628</li>
81a89f7c 1629<li><p><a href="#ippAddIntegers"><code>ippAddIntegers</code></a> adds an enum or integer attribute with one or more values.</p>
b47dab17 1630</li>
81a89f7c 1631<li><p><a href="#ippAddOctetString"><code>ippAddOctetString</code></a> adds an octetString attribute with one value.</p>
b47dab17 1632</li>
81a89f7c 1633<li><p><a href="#ippAddOutOfBand"><code>ippAddOutOfBand</code></a> adds a admin-defined (<code>IPP_TAG_ADMINDEFINE</code>), default (<code>IPP_TAG_DEFAULT</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable (<code>IPP_TAG_NOTSETTABLE</code>), unknown (<code>IPP_TAG_UNKNOWN</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_VALUE</code>) out-of-band attribute.</p>
b47dab17 1634</li>
81a89f7c 1635<li><p><a href="#ippAddRange"><code>ippAddRange</code></a> adds a rangeOfInteger attribute with one range.</p>
b47dab17 1636</li>
81a89f7c 1637<li><p><a href="#ippAddRanges"><code>ippAddRanges</code></a> adds a rangeOfInteger attribute with one or more ranges.</p>
b47dab17 1638</li>
81a89f7c 1639<li><p><a href="#ippAddResolution"><code>ippAddResolution</code></a> adds a resolution attribute with one resolution.</p>
b47dab17 1640</li>
81a89f7c 1641<li><p><a href="#ippAddResolutions"><code>ippAddResolutions</code></a> adds a resolution attribute with one or more resolutions.</p>
b47dab17 1642</li>
81a89f7c 1643<li><p><a href="#ippAddString"><code>ippAddString</code></a> adds a charset (<code>IPP_TAG_CHARSET</code>), keyword (<code>IPP_TAG_KEYWORD</code>), mimeMediaType (<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code> and <code>IPP_TAG_NAMELANG</code>), naturalLanguage (<code>IPP_TAG_NATURAL_LANGUAGE</code>), text (<code>IPP_TAG_TEXT</code> and <code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), or uriScheme (<code>IPP_TAG_URISCHEME</code>) attribute with one value.</p>
b47dab17 1644</li>
81a89f7c 1645<li><p><a href="#ippAddStrings"><code>ippAddStrings</code></a> adds a charset, keyword, mimeMediaType, name, naturalLanguage, text, uri, or uriScheme attribute with one or more values.</p>
b47dab17 1646</li>
b0fb2d75 1647</ul>
b47dab17 1648<h3 class="title" id="sending-the-ipp-request">Sending the IPP Request</h3>
81a89f7c
MS
1649<p>Once you have created the IPP request, you can send it using the <a href="#cupsDoRequest"><code>cupsDoRequest</code></a> function. For example, the following code sends the IPP Get-Printer-Attributes request to the destination and saves the response:</p>
1650<pre><code class="language-c">ipp_t *response = cupsDoRequest(http, request, resource);
b0fb2d75 1651</code></pre>
81a89f7c
MS
1652<p>For requests like Send-Document that include a file, the <a href="#cupsDoFileRequest"><code>cupsDoFileRequest</code></a> function should be used:</p>
1653<pre><code class="language-c">ipp_t *response = cupsDoFileRequest(http, request, resource,
b0fb2d75
MS
1654 filename);
1655</code></pre>
b47dab17 1656<p>Both <code>cupsDoRequest</code> and <code>cupsDoFileRequest</code> free the IPP request. If a valid IPP response is received, it is stored in a new IPP message (<code>ipp_t</code>) and returned to the caller. Otherwise <code>NULL</code> is returned.</p>
81a89f7c
MS
1657<p>The status from the most recent request can be queried using the <a href="#cupsGetError"><code>cupsGetError</code></a> function, for example:</p>
1658<pre><code class="language-c"><span class="reserved">if</span> (cupsGetError() &gt;= IPP_STATUS_ERROR_BAD_REQUEST)
b0fb2d75 1659{
81a89f7c 1660 <span class="comment">/* request failed */</span>
b0fb2d75
MS
1661}
1662</code></pre>
81a89f7c
MS
1663<p>A human-readable error message is also available using the <code>cupsGetErrorString</code> function:</p>
1664<pre><code class="language-c"><span class="reserved">if</span> (cupsGetError() &gt;= IPP_STATUS_ERROR_BAD_REQUEST)
b0fb2d75 1665{
81a89f7c
MS
1666 <span class="comment">/* request failed */</span>
1667 printf(<span class="string">&quot;Request failed: %s\n&quot;</span>, cupsGetErrorString());
b0fb2d75
MS
1668}
1669</code></pre>
b47dab17
MS
1670<h3 class="title" id="processing-the-ipp-response">Processing the IPP Response</h3>
1671<p>Each response to an IPP request is also an IPP message (<code>ipp_t</code>) with its own IPP attributes (<code>ipp_attribute_t</code>) that includes a status code (<code>IPP_STATUS_OK</code>, <code>IPP_STATUS_ERROR_BAD_REQUEST</code>, etc.) and the corresponding 32-bit integer identifier from the request.</p>
1672<p>For example, the following code finds the printer state attributes and prints their values:</p>
81a89f7c 1673<pre><code class="language-c">ipp_attribute_t *attr;
b0fb2d75 1674
81a89f7c 1675<span class="reserved">if</span> ((attr = ippFindAttribute(response, <span class="string">&quot;printer-state&quot;</span>,
b0fb2d75
MS
1676 IPP_TAG_ENUM)) != NULL)
1677{
81a89f7c
MS
1678 printf(<span class="string">&quot;printer-state=%s\n&quot;</span>,
1679 ippEnumString(<span class="string">&quot;printer-state&quot;</span>, ippGetInteger(attr, <span class="number">0</span>)));
b0fb2d75 1680}
81a89f7c
MS
1681<span class="reserved">else</span>
1682 puts(<span class="string">&quot;printer-state=unknown&quot;</span>);
b0fb2d75 1683
81a89f7c 1684<span class="reserved">if</span> ((attr = ippFindAttribute(response, <span class="string">&quot;printer-state-message&quot;</span>,
b0fb2d75
MS
1685 IPP_TAG_TEXT)) != NULL)
1686{
81a89f7c
MS
1687 printf(<span class="string">&quot;printer-state-message=\&quot;%s\&quot;\n&quot;</span>,
1688 ippGetString(attr, <span class="number">0</span>, NULL)));
b0fb2d75
MS
1689}
1690
81a89f7c 1691<span class="reserved">if</span> ((attr = ippFindAttribute(response, <span class="string">&quot;printer-state-reasons&quot;</span>,
b0fb2d75
MS
1692 IPP_TAG_KEYWORD)) != NULL)
1693{
81a89f7c 1694 <span class="reserved">int</span> i, count = ippGetCount(attr);
b0fb2d75 1695
81a89f7c
MS
1696 puts(<span class="string">&quot;printer-state-reasons=&quot;</span>);
1697 <span class="reserved">for</span> (i = <span class="number">0</span>; i &lt; count; i ++)
1698 printf(<span class="string">&quot; %s\n&quot;</span>, ippGetString(attr, i, NULL)));
b0fb2d75
MS
1699}
1700</code></pre>
81a89f7c
MS
1701<p>The <a href="#ippGetCount"><code>ippGetCount</code></a> function returns the number of values in an attribute.</p>
1702<p>The <a href="#ippGetInteger"><code>ippGetInteger</code></a> and <a href="#ippGetString"><code>ippGetString</code></a> functions return a single integer or string value from an attribute.</p>
1703<p>The <a href="#ippEnumString"><code>ippEnumString</code></a> function converts a enum value to its keyword (string) equivalent.</p>
1704<p>Once you are done using the IPP response message, free it using the <a href="#ippDelete"><code>ippDelete</code></a> function:</p>
1705<pre><code class="language-c">ippDelete(response);
b0fb2d75 1706</code></pre>
b47dab17 1707<h3 class="title" id="authentication">Authentication</h3>
81a89f7c
MS
1708<p>CUPS normally handles authentication through the console. GUI applications should set a password callback using the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> function:</p>
1709<pre><code class="language-c"><span class="reserved">void</span>
1710cupsSetPasswordCB2(cups_password_cb2_t cb, <span class="reserved">void</span> *user_data);
b0fb2d75 1711</code></pre>
81a89f7c
MS
1712<p>The password callback will be called when needed and is responsible for setting the current user name using <a href="#cupsSetUser"><code>cupsSetUser</code></a> and returning a string:</p>
1713<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *
1714cups_password_cb2(<span class="reserved">const</span> <span class="reserved">char</span> *prompt, http_t *http,
1715 <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource,
1716 <span class="reserved">void</span> *user_data);
b0fb2d75 1717</code></pre>
b47dab17 1718<p>The <code>prompt</code> argument is a string from CUPS that should be displayed to the user.</p>
81a89f7c 1719<p>The <code>http</code> argument is the connection hosting the request that is being authenticated. The password callback can call the <a href="#httpGetField"><code>httpGetField</code></a> and <a href="#httpGetSubField"><code>httpGetSubField</code></a> functions to look for additional details concerning the authentication challenge.</p>
b47dab17
MS
1720<p>The <code>method</code> argument specifies the HTTP method used for the request and is typically &quot;POST&quot;.</p>
1721<p>The <code>resource</code> argument specifies the path used for the request.</p>
1722<p>The <code>user_data</code> argument provides the user data pointer from the <code>cupsSetPasswordCB2</code> call.</p>
81a89f7c
MS
1723<h2 class="title" id="ipp-data-file-api">IPP Data File API</h2>
1724<p>The IPP data file API provides functions to read and write IPP attributes and other commands or data using a common base format that supports tools such as <code>ipptool</code> and <code>ippeveprinter</code>.</p>
1725<h3 class="title" id="creating-an-ipp-data-file">Creating an IPP Data File</h3>
1726<p>The <a href="#ippFileNew"><code>ippFileNew</code></a> function creates a new IPP data file (<code>ipp_file_t</code>) object:</p>
1727<pre><code class="language-c">ipp_file_t *parent = NULL;
1728<span class="reserved">void</span> *data;
1729ipp_file_t *file = ippFileNew(parent, attr_cb, error_cb, data);
1730</code></pre>
1731<p>The &quot;parent&quot; IPP data file pointer is typically used to support nested files and is normally <code>NULL</code> for a new file. The &quot;data&quot; argument supplies your application data to the callbacks. The &quot;attr_cb&quot; callback function is used to filter IPP attributes; return <code>true</code> to include the attribute and <code>false</code> to ignore it:</p>
1732<pre><code class="language-c"><span class="reserved">bool</span>
1733attr_cb(ipp_file_t *file, <span class="reserved">void</span> *cb_data, <span class="reserved">const</span> <span class="reserved">char</span> *name)
1734{
1735 ... determine whether to use an attribute named <span class="string">&quot;name&quot;</span> ...
1736}
1737</code></pre>
1738<p>The &quot;error_cb&quot; callback function is used to record/report errors when reading the file:</p>
1739<pre><code class="language-c"><span class="reserved">bool</span>
1740error_cb(ipp_file_t *file, <span class="reserved">void</span> *cb_data, <span class="reserved">const</span> <span class="reserved">char</span> *error)
1741{
1742 ... display/record error <span class="reserved">and</span> <span class="reserved">return</span> `<span class="reserved">true</span>` to <span class="reserved">continue</span> <span class="reserved">or</span> `<span class="reserved">false</span>` to stop ...
1743}
1744</code></pre>
1745<h3 class="title" id="reading-a-data-file">Reading a Data File</h3>
1746<p>The <a href="#ippFileOpen"><code>ippFileOpen</code></a> function opens the specified data file and <a href="#ippFileRead"><code>ippFileRead</code></a> reads from it:</p>
1747<pre><code class="language-c"><span class="reserved">if</span> (ippFileOpen(file, <span class="string">&quot;somefile&quot;</span>, <span class="string">&quot;r&quot;</span>))
1748{
1749 <span class="comment">// Opened successfully, now read it...</span>
1750 ippFileRead(file, token_cb, <span class="comment">/*with_groups*/</span><span class="reserved">false</span>);
1751 ippFileClose(file);
1752}
1753</code></pre>
1754<p>The token callback function passed to <code>ippFileRead</code> handles custom directives in your data file:</p>
1755<pre><code class="language-c"><span class="reserved">bool</span>
1756token_cb(ipp_file_t *file, <span class="reserved">void</span> *cb_data, <span class="reserved">const</span> <span class="reserved">char</span> *token)
1757{
1758 ... handle token, <span class="reserved">return</span> `<span class="reserved">true</span>` to <span class="reserved">continue</span> <span class="reserved">or</span> `<span class="reserved">false</span>` to stop ...
1759}
1760</code></pre>
1761<p>The &quot;token&quot; parameter contains the token to be processed. The callback can use the <a href="#ippFileReadToken"><code>ippFileReadToken</code></a> function to read additional tokens from the file and the <a href="#ippFileExpandToken"><code>ippFileExpandToken</code></a> function to expand any variables in the token string. Return <code>false</code> to stop reading the file and <code>true</code> to continue. The default <code>NULL</code> callback reports an unknown token error through the error callback end returns <code>false</code>.</p>
1762<p>Once read, you call the <a href="#ippFileGetAttributes"><code>ippFileGetAttributes</code></a> function to get the IPP attributes from the file.</p>
1763<h3 class="title" id="variables">Variables</h3>
1764<p>Each IPP data file object has associated variables that can be used when reading the file. The default set of variables is:</p>
1765<ul>
1766<li><p>&quot;date-current&quot;: Current date in ISO-8601 format</p>
1767</li>
1768<li><p>&quot;date-start&quot;: Start date (when file opened) in ISO-8601 format</p>
1769</li>
1770<li><p>&quot;filename&quot;: Associated data/document filename, if any</p>
1771</li>
1772<li><p>&quot;filetype&quot;: MIME media type of associated data/document filename, if any</p>
1773</li>
1774<li><p>&quot;hostname&quot;: Hostname or IP address from the &quot;uri&quot; value, if any</p>
1775</li>
1776<li><p>&quot;port&quot;: Port number from the &quot;uri&quot; value, if any</p>
1777</li>
1778<li><p>&quot;resource&quot;: Resource path from the &quot;uri&quot; value, if any</p>
1779</li>
1780<li><p>&quot;scheme&quot;: URI scheme from the &quot;uri&quot; value, if any</p>
1781</li>
1782<li><p>&quot;uri&quot;: URI, if any</p>
1783</li>
1784<li><p>&quot;uriuser&quot;: Username from the &quot;uri&quot; value, if any</p>
1785</li>
1786<li><p>&quot;uripassword&quot;: Password from the &quot;uri&quot; value, if any</p>
1787</li>
1788<li><p>&quot;user&quot;: Current login user</p>
1789</li>
1790</ul>
1791<p>The <a href="#ippFileGetVar"><code>ippFileGetVar</code></a>, <a href="#ippFileSetVar"><code>ippFileSetVar</code></a>, and <a href="#ippFileSetVarf"><code>ippFileSetVarf</code></a> functions get and set file variables, respectively.</p>
1792<h3 class="title" id="writing-ipp-data-files">Writing IPP Data Files</h3>
1793<p>As when reading an IPP data file, the <a href="#ippFileNew"><code>ippFileNew</code></a> function creates a new file object, <a href="#ippFileOpen"><code>ippFileOpen</code></a> opens the file, and <a href="#ippFileClose"><code>ippFileClose</code></a> closes the file. However, you call <a href="#ippFileWriteAttributes"><code>ippFileWriteAttributes</code></a> to write the attributes in an IPP message (<code>ipp_t</code>), <a href="#ippFileWriteComment"><code>ippFileWriteComment</code></a> to write a comment in the file, and <a href="#ippWriteToken"><code>ippWriteToken</code></a> or <a href="#ippWriteTokenf"><code>ippWriteTokenf</code></a> to write a token or value to the file.</p>
b47dab17 1794<h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
798d6e29 1795<h3 class="function"><a id="cupsAddDest">cupsAddDest</a></h3>
b47dab17 1796<p class="description">Add a destination to the list of destinations.</p>
798d6e29 1797<p class="code">
0350eba5 1798<span class="reserved">int</span> cupsAddDest(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *instance, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
98d88c8d
MS
1799<h4 class="parameters">Parameters</h4>
1800<table class="list"><tbody>
1801<tr><th>name</th>
b47dab17 1802<td class="description">Destination name</td></tr>
98d88c8d 1803<tr><th>instance</th>
b47dab17 1804<td class="description">Instance name or <code>NULL</code> for none/primary</td></tr>
98d88c8d 1805<tr><th>num_dests</th>
b47dab17 1806<td class="description">Number of destinations</td></tr>
98d88c8d 1807<tr><th>dests</th>
b47dab17 1808<td class="description">Destinations</td></tr>
98d88c8d 1809</tbody></table>
798d6e29 1810<h4 class="returnvalue">Return Value</h4>
b47dab17 1811<p class="description">New number of destinations</p>
798d6e29 1812<h4 class="discussion">Discussion</h4>
b47dab17 1813<p class="discussion">This function cannot be used to add a new class or printer queue,
798d6e29
MS
1814it only adds a new container of saved options for the named
1815destination or instance.<br>
1816<br>
1817If the named destination already exists, the destination list is
1818returned unchanged. Adding a new instance of a destination creates
1819a copy of that destination's options.<br>
1820<br>
05d62fc2 1821Use the <a href="#cupsSetDests"><code>cupsSetDests</code></a> function to save the updated list of
798d6e29 1822destinations to the user's lpoptions file.</p>
b6008d6b 1823<h3 class="function"><span class="info">&#160;CUPS 2.3&#160;</span><a id="cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></h3>
b47dab17 1824<p class="description">Add the option corresponding to the specified media size.</p>
63b75fbe 1825<p class="code">
0350eba5 1826<span class="reserved">int</span> cupsAddDestMediaOptions(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
63b75fbe
MS
1827<h4 class="parameters">Parameters</h4>
1828<table class="list"><tbody>
1829<tr><th>http</th>
b47dab17 1830<td class="description">Connection to destination</td></tr>
63b75fbe 1831<tr><th>dest</th>
b47dab17 1832<td class="description">Destination</td></tr>
63b75fbe 1833<tr><th>dinfo</th>
b47dab17 1834<td class="description">Destination information</td></tr>
63b75fbe 1835<tr><th>flags</th>
b47dab17 1836<td class="description">Media matching flags</td></tr>
63b75fbe 1837<tr><th>size</th>
b47dab17 1838<td class="description">Media size</td></tr>
63b75fbe 1839<tr><th>num_options</th>
b47dab17 1840<td class="description">Current number of options</td></tr>
63b75fbe 1841<tr><th>options</th>
b47dab17 1842<td class="description">Options</td></tr>
63b75fbe
MS
1843</tbody></table>
1844<h4 class="returnvalue">Return Value</h4>
b47dab17 1845<p class="description">New number of options</p>
af268786
MS
1846<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsAddDestMediaOptions2">cupsAddDestMediaOptions2</a></h3>
1847<p class="description">Add the options corresponding to the specified media information.</p>
1848<p class="code">
0350eba5 1849<span class="reserved">int</span> cupsAddDestMediaOptions2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
af268786
MS
1850<h4 class="parameters">Parameters</h4>
1851<table class="list"><tbody>
1852<tr><th>http</th>
1853<td class="description">Connection to destination</td></tr>
1854<tr><th>dest</th>
1855<td class="description">Destination</td></tr>
1856<tr><th>dinfo</th>
1857<td class="description">Destination information</td></tr>
1858<tr><th>flags</th>
1859<td class="description">Media matching flags</td></tr>
1860<tr><th>media</th>
1861<td class="description">Media information</td></tr>
1862<tr><th>num_options</th>
1863<td class="description">Current number of options</td></tr>
1864<tr><th>options</th>
1865<td class="description">Options</td></tr>
1866</tbody></table>
1867<h4 class="returnvalue">Return Value</h4>
1868<p class="description">New number of options</p>
b6008d6b 1869<h3 class="function"><span class="info">&#160;CUPS 2.2.4&#160;</span><a id="cupsAddIntegerOption">cupsAddIntegerOption</a></h3>
b47dab17 1870<p class="description">Add an integer option to an option array.</p>
798d6e29 1871<p class="code">
0350eba5 1872<span class="reserved">int</span> cupsAddIntegerOption(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> value, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
98d88c8d
MS
1873<h4 class="parameters">Parameters</h4>
1874<table class="list"><tbody>
1875<tr><th>name</th>
b47dab17 1876<td class="description">Name of option</td></tr>
98d88c8d 1877<tr><th>value</th>
b47dab17 1878<td class="description">Value of option</td></tr>
98d88c8d 1879<tr><th>num_options</th>
b47dab17 1880<td class="description">Number of options</td></tr>
98d88c8d 1881<tr><th>options</th>
b47dab17 1882<td class="description">Pointer to options</td></tr>
98d88c8d 1883</tbody></table>
798d6e29 1884<h4 class="returnvalue">Return Value</h4>
b47dab17 1885<p class="description">Number of options</p>
798d6e29 1886<h4 class="discussion">Discussion</h4>
b47dab17 1887<p class="discussion">New option arrays can be initialized simply by passing 0 for the
53af7f21 1888&quot;num_options&quot; parameter.
798d6e29
MS
1889
1890</p>
53af7f21 1891<h3 class="function"><a id="cupsAddOption">cupsAddOption</a></h3>
b47dab17 1892<p class="description">Add an option to an option array.</p>
798d6e29 1893<p class="code">
0350eba5 1894<span class="reserved">int</span> cupsAddOption(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
98d88c8d
MS
1895<h4 class="parameters">Parameters</h4>
1896<table class="list"><tbody>
1897<tr><th>name</th>
b47dab17 1898<td class="description">Name of option</td></tr>
98d88c8d 1899<tr><th>value</th>
b47dab17 1900<td class="description">Value of option</td></tr>
98d88c8d 1901<tr><th>num_options</th>
b47dab17 1902<td class="description">Number of options</td></tr>
98d88c8d 1903<tr><th>options</th>
b47dab17 1904<td class="description">Pointer to options</td></tr>
98d88c8d 1905</tbody></table>
798d6e29 1906<h4 class="returnvalue">Return Value</h4>
b47dab17 1907<p class="description">Number of options</p>
798d6e29 1908<h4 class="discussion">Discussion</h4>
b47dab17 1909<p class="discussion">New option arrays can be initialized simply by passing 0 for the
53af7f21 1910&quot;num_options&quot; parameter.</p>
af268786
MS
1911<h3 class="function"><a id="cupsAreCredentialsValidForName">cupsAreCredentialsValidForName</a></h3>
1912<p class="description">Return whether the credentials are valid
1913 for the given name.</p>
1914<p class="code">
0350eba5 1915<span class="reserved">bool</span> cupsAreCredentialsValidForName(<span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *credentials);</p>
af268786
MS
1916<h4 class="parameters">Parameters</h4>
1917<table class="list"><tbody>
1918<tr><th>common_name</th>
1919<td class="description">Name to check</td></tr>
1920<tr><th>credentials</th>
1921<td class="description">Credentials</td></tr>
1922</tbody></table>
1923<h4 class="returnvalue">Return Value</h4>
1924<p class="description"><code>true</code> if valid, <code>false</code> otherwise</p>
b6008d6b 1925<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayAdd">cupsArrayAdd</a></h3>
b47dab17
MS
1926<p class="description">Add an element to the array.</p>
1927<p class="code">
0350eba5 1928<span class="reserved">int</span> cupsArrayAdd(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">void</span> *e);</p>
b47dab17
MS
1929<h4 class="parameters">Parameters</h4>
1930<table class="list"><tbody>
1931<tr><th>a</th>
1932<td class="description">Array</td></tr>
1933<tr><th>e</th>
1934<td class="description">Element</td></tr>
1935</tbody></table>
1936<h4 class="returnvalue">Return Value</h4>
1937<p class="description">1 on success, 0 on failure</p>
1938<h4 class="discussion">Discussion</h4>
1939<p class="discussion">When adding an element to a sorted array, non-unique elements are
1940appended at the end of the run of identical elements. For unsorted arrays,
1941the element is appended to the end of the array.
1942
1943</p>
af268786
MS
1944<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayAddStrings">cupsArrayAddStrings</a></h3>
1945<p class="description">Add zero or more delimited strings to an array.</p>
b47dab17 1946<p class="code">
0350eba5 1947<span class="reserved">bool</span> cupsArrayAddStrings(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">const</span> <span class="reserved">char</span> *s, <span class="reserved">char</span> delim);</p>
b47dab17
MS
1948<h4 class="parameters">Parameters</h4>
1949<table class="list"><tbody>
1950<tr><th>a</th>
1951<td class="description">Array</td></tr>
af268786
MS
1952<tr><th>s</th>
1953<td class="description">Delimited strings or NULL</td></tr>
1954<tr><th>delim</th>
1955<td class="description">Delimiter character</td></tr>
b47dab17 1956</tbody></table>
af268786
MS
1957<h4 class="returnvalue">Return Value</h4>
1958<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
b47dab17 1959<h4 class="discussion">Discussion</h4>
af268786
MS
1960<p class="discussion">Note: The array MUST be created using the <a href="#_cupsArrayNewStrings"><code>_cupsArrayNewStrings</code></a>
1961function. Duplicate strings are NOT added. If the string pointer &quot;s&quot; is NULL
1962or the empty string, no strings are added to the array.
b47dab17
MS
1963
1964</p>
b6008d6b 1965<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayClear">cupsArrayClear</a></h3>
af268786 1966<p class="description">Clear the array.</p>
b47dab17 1967<p class="code">
0350eba5 1968<span class="reserved">void</span> cupsArrayClear(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
1969<h4 class="parameters">Parameters</h4>
1970<table class="list"><tbody>
1971<tr><th>a</th>
1972<td class="description">Array</td></tr>
1973</tbody></table>
b47dab17 1974<h4 class="discussion">Discussion</h4>
af268786
MS
1975<p class="discussion">This function is equivalent to removing all elements in the array.
1976The caller is responsible for freeing the memory used by the
1977elements themselves.
b47dab17
MS
1978
1979</p>
b6008d6b 1980<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayDelete">cupsArrayDelete</a></h3>
b47dab17
MS
1981<p class="description">Free all memory used by the array.</p>
1982<p class="code">
0350eba5 1983<span class="reserved">void</span> cupsArrayDelete(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
1984<h4 class="parameters">Parameters</h4>
1985<table class="list"><tbody>
1986<tr><th>a</th>
1987<td class="description">Array</td></tr>
1988</tbody></table>
1989<h4 class="discussion">Discussion</h4>
1990<p class="discussion">The caller is responsible for freeing the memory used by the
1991elements themselves.
1992
1993</p>
b6008d6b 1994<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayDup">cupsArrayDup</a></h3>
b47dab17
MS
1995<p class="description">Duplicate the array.</p>
1996<p class="code">
1997<a href="#cups_array_t">cups_array_t</a> *cupsArrayDup(<a href="#cups_array_t">cups_array_t</a> *a);</p>
1998<h4 class="parameters">Parameters</h4>
1999<table class="list"><tbody>
2000<tr><th>a</th>
2001<td class="description">Array</td></tr>
2002</tbody></table>
2003<h4 class="returnvalue">Return Value</h4>
2004<p class="description">Duplicate array</p>
b6008d6b 2005<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayFind">cupsArrayFind</a></h3>
b47dab17
MS
2006<p class="description">Find an element in the array.</p>
2007<p class="code">
0350eba5 2008<span class="reserved">void</span> *cupsArrayFind(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">void</span> *e);</p>
b47dab17
MS
2009<h4 class="parameters">Parameters</h4>
2010<table class="list"><tbody>
2011<tr><th>a</th>
2012<td class="description">Array</td></tr>
2013<tr><th>e</th>
2014<td class="description">Element</td></tr>
2015</tbody></table>
2016<h4 class="returnvalue">Return Value</h4>
2017<p class="description">Element found or <code>NULL</code></p>
af268786
MS
2018<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetCount">cupsArrayGetCount</a></h3>
2019<p class="description">Get the number of elements in the array.</p>
2020<p class="code">
0350eba5 2021<span class="reserved">int</span> cupsArrayGetCount(<a href="#cups_array_t">cups_array_t</a> *a);</p>
af268786
MS
2022<h4 class="parameters">Parameters</h4>
2023<table class="list"><tbody>
2024<tr><th>a</th>
2025<td class="description">Array</td></tr>
2026</tbody></table>
2027<h4 class="returnvalue">Return Value</h4>
2028<p class="description">Number of elements</p>
2029<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetCurrent">cupsArrayGetCurrent</a></h3>
2030<p class="description">Return the current element in the array.</p>
2031<p class="code">
0350eba5 2032<span class="reserved">void</span> *cupsArrayGetCurrent(<a href="#cups_array_t">cups_array_t</a> *a);</p>
af268786
MS
2033<h4 class="parameters">Parameters</h4>
2034<table class="list"><tbody>
2035<tr><th>a</th>
2036<td class="description">Array</td></tr>
2037</tbody></table>
2038<h4 class="returnvalue">Return Value</h4>
2039<p class="description">Element</p>
2040<h4 class="discussion">Discussion</h4>
2041<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
2042<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
2043
2044</p>
2045<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetElement">cupsArrayGetElement</a></h3>
2046<p class="description">Get the N-th element in the array.</p>
2047<p class="code">
0350eba5 2048<span class="reserved">void</span> *cupsArrayGetElement(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">int</span> n);</p>
af268786
MS
2049<h4 class="parameters">Parameters</h4>
2050<table class="list"><tbody>
2051<tr><th>a</th>
2052<td class="description">Array</td></tr>
2053<tr><th>n</th>
2054<td class="description">Index into array, starting at 0</td></tr>
2055</tbody></table>
2056<h4 class="returnvalue">Return Value</h4>
2057<p class="description">N-th element or <code>NULL</code></p>
2058<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetFirst">cupsArrayGetFirst</a></h3>
b47dab17
MS
2059<p class="description">Get the first element in the array.</p>
2060<p class="code">
0350eba5 2061<span class="reserved">void</span> *cupsArrayGetFirst(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2062<h4 class="parameters">Parameters</h4>
2063<table class="list"><tbody>
2064<tr><th>a</th>
2065<td class="description">Array</td></tr>
2066</tbody></table>
2067<h4 class="returnvalue">Return Value</h4>
2068<p class="description">First element or <code>NULL</code> if the array is empty</p>
b6008d6b 2069<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="cupsArrayGetIndex">cupsArrayGetIndex</a></h3>
b47dab17
MS
2070<p class="description">Get the index of the current element.</p>
2071<p class="code">
0350eba5 2072<span class="reserved">int</span> cupsArrayGetIndex(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2073<h4 class="parameters">Parameters</h4>
2074<table class="list"><tbody>
2075<tr><th>a</th>
2076<td class="description">Array</td></tr>
2077</tbody></table>
2078<h4 class="returnvalue">Return Value</h4>
2079<p class="description">Index of the current element, starting at 0</p>
2080<h4 class="discussion">Discussion</h4>
2081<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
2082<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
2083
2084</p>
b6008d6b 2085<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="cupsArrayGetInsert">cupsArrayGetInsert</a></h3>
b47dab17
MS
2086<p class="description">Get the index of the last inserted element.</p>
2087<p class="code">
0350eba5 2088<span class="reserved">int</span> cupsArrayGetInsert(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2089<h4 class="parameters">Parameters</h4>
2090<table class="list"><tbody>
2091<tr><th>a</th>
2092<td class="description">Array</td></tr>
2093</tbody></table>
2094<h4 class="returnvalue">Return Value</h4>
2095<p class="description">Index of the last inserted element, starting at 0</p>
af268786
MS
2096<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetLast">cupsArrayGetLast</a></h3>
2097<p class="description">Get the last element in the array.</p>
b47dab17 2098<p class="code">
0350eba5 2099<span class="reserved">void</span> *cupsArrayGetLast(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2100<h4 class="parameters">Parameters</h4>
2101<table class="list"><tbody>
2102<tr><th>a</th>
2103<td class="description">Array</td></tr>
b47dab17
MS
2104</tbody></table>
2105<h4 class="returnvalue">Return Value</h4>
af268786
MS
2106<p class="description">Last element or <code>NULL</code> if the array is empty</p>
2107<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetNext">cupsArrayGetNext</a></h3>
2108<p class="description">Get the next element in the array.</p>
b47dab17 2109<p class="code">
0350eba5 2110<span class="reserved">void</span> *cupsArrayGetNext(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2111<h4 class="parameters">Parameters</h4>
2112<table class="list"><tbody>
2113<tr><th>a</th>
2114<td class="description">Array</td></tr>
b47dab17
MS
2115</tbody></table>
2116<h4 class="returnvalue">Return Value</h4>
af268786 2117<p class="description">Next element or <code>NULL</code></p>
b47dab17 2118<h4 class="discussion">Discussion</h4>
af268786
MS
2119<p class="discussion">This function is equivalent to &quot;cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)&quot;.<br>
2120<br>
2121The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
2122<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
2123to set the current element.
b47dab17
MS
2124
2125</p>
af268786
MS
2126<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetPrev">cupsArrayGetPrev</a></h3>
2127<p class="description">Get the previous element in the array.</p>
b47dab17 2128<p class="code">
0350eba5 2129<span class="reserved">void</span> *cupsArrayGetPrev(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2130<h4 class="parameters">Parameters</h4>
2131<table class="list"><tbody>
2132<tr><th>a</th>
2133<td class="description">Array</td></tr>
2134</tbody></table>
2135<h4 class="returnvalue">Return Value</h4>
af268786
MS
2136<p class="description">Previous element or <code>NULL</code></p>
2137<h4 class="discussion">Discussion</h4>
2138<p class="discussion">This function is equivalent to &quot;cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)&quot;.<br>
2139<br>
2140The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
2141<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
2142to set the current element.
2143
2144</p>
2145<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayGetUserData">cupsArrayGetUserData</a></h3>
2146<p class="description">Return the user data for an array.</p>
b47dab17 2147<p class="code">
0350eba5 2148<span class="reserved">void</span> *cupsArrayGetUserData(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2149<h4 class="parameters">Parameters</h4>
2150<table class="list"><tbody>
af268786
MS
2151<tr><th>a</th>
2152<td class="description">Array</td></tr>
b47dab17
MS
2153</tbody></table>
2154<h4 class="returnvalue">Return Value</h4>
af268786 2155<p class="description">User data</p>
b6008d6b 2156<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayInsert">cupsArrayInsert</a></h3>
af268786 2157<p class="description">Insert an element in the array.</p>
b47dab17 2158<p class="code">
0350eba5 2159<span class="reserved">int</span> cupsArrayInsert(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">void</span> *e);</p>
b47dab17
MS
2160<h4 class="parameters">Parameters</h4>
2161<table class="list"><tbody>
af268786
MS
2162<tr><th>a</th>
2163<td class="description">Array</td></tr>
2164<tr><th>e</th>
2165<td class="description">Element</td></tr>
b47dab17
MS
2166</tbody></table>
2167<h4 class="returnvalue">Return Value</h4>
af268786 2168<p class="description">0 on failure, 1 on success</p>
b47dab17 2169<h4 class="discussion">Discussion</h4>
af268786
MS
2170<p class="discussion">When inserting an element in a sorted array, non-unique elements are
2171inserted at the beginning of the run of identical elements. For unsorted
2172arrays, the element is inserted at the beginning of the array.
b47dab17
MS
2173
2174</p>
b6008d6b 2175<h3 class="function"><span class="info">&#160;CUPS 1.5&#160;</span><a id="cupsArrayNew3">cupsArrayNew3</a></h3>
af268786 2176<p class="description">Create a new array with optional compare, hash, copy, and/or free callbacks.</p>
b47dab17 2177<p class="code">
0350eba5 2178<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3(<a href="#cups_array_cb_t">cups_array_cb_t</a> f, <span class="reserved">void</span> *d, <a href="#cups_ahash_cb_t">cups_ahash_cb_t</a> h, <span class="reserved">int</span> hsize, <a href="#cups_acopy_cb_t">cups_acopy_cb_t</a> cf, <a href="#cups_afree_cb_t">cups_afree_cb_t</a> ff);</p>
b47dab17
MS
2179<h4 class="parameters">Parameters</h4>
2180<table class="list"><tbody>
2181<tr><th>f</th>
af268786 2182<td class="description">Comparison callback or <code>NULL</code> for an unsorted array</td></tr>
b47dab17
MS
2183<tr><th>d</th>
2184<td class="description">User data or <code>NULL</code></td></tr>
2185<tr><th>h</th>
af268786 2186<td class="description">Hash callback or <code>NULL</code> for unhashed lookups</td></tr>
b47dab17
MS
2187<tr><th>hsize</th>
2188<td class="description">Hash size (&gt;= 0)</td></tr>
2189<tr><th>cf</th>
af268786 2190<td class="description">Copy callback</td></tr>
b47dab17 2191<tr><th>ff</th>
af268786 2192<td class="description">Free callback</td></tr>
b47dab17
MS
2193</tbody></table>
2194<h4 class="returnvalue">Return Value</h4>
2195<p class="description">Array</p>
2196<h4 class="discussion">Discussion</h4>
af268786
MS
2197<p class="discussion">This function creates a new array with optional compare, hash, copy, and free
2198callbacks. The comparison callback (&quot;f&quot;) is used to create a sorted array.
2199The callback receives pointers to two elements and the user data pointer
2200(&quot;d&quot;).<br>
b47dab17 2201<br>
af268786 2202The hash callback (&quot;h&quot;) is used to implement cached lookups with the
b47dab17
MS
2203specified hash size (&quot;hsize&quot;).<br>
2204<br>
af268786
MS
2205The copy callback (&quot;cf&quot;) is used to automatically copy/retain elements when
2206added or the array is duplicated with <a href="#cupsArrayDup"><code>cupsArrayDup</code></a>.<br>
b47dab17 2207<br>
af268786
MS
2208The free callback (&quot;cf&quot;) is used to automatically free/release elements when
2209removed with <a href="#cupsArrayRemove"><code>cupsArrayRemove</code></a> or the array is deleted with
2210<a href="#cupsArrayDelete"><code>cupsArrayDelete</code></a>.
b47dab17
MS
2211
2212</p>
af268786
MS
2213<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsArrayNewStrings">cupsArrayNewStrings</a></h3>
2214<p class="description">Create a new array of delimited strings.</p>
b47dab17 2215<p class="code">
0350eba5 2216<a href="#cups_array_t">cups_array_t</a> *cupsArrayNewStrings(<span class="reserved">const</span> <span class="reserved">char</span> *s, <span class="reserved">char</span> delim);</p>
b47dab17
MS
2217<h4 class="parameters">Parameters</h4>
2218<table class="list"><tbody>
af268786
MS
2219<tr><th>s</th>
2220<td class="description">Delimited strings or <code>NULL</code></td></tr>
2221<tr><th>delim</th>
2222<td class="description">Delimiter character</td></tr>
b47dab17
MS
2223</tbody></table>
2224<h4 class="returnvalue">Return Value</h4>
af268786 2225<p class="description">Array</p>
b47dab17 2226<h4 class="discussion">Discussion</h4>
af268786
MS
2227<p class="discussion">This function creates a new array of strings that are delimited by the
2228specified character. The array automatically manages copies of the strings
2229passed. If the string pointer &quot;s&quot; is <code>NULL</code> or the empty string, no strings
2230are added to the newly created array.
b47dab17
MS
2231
2232</p>
b6008d6b 2233<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayRemove">cupsArrayRemove</a></h3>
b47dab17
MS
2234<p class="description">Remove an element from the array.</p>
2235<p class="code">
0350eba5 2236<span class="reserved">int</span> cupsArrayRemove(<a href="#cups_array_t">cups_array_t</a> *a, <span class="reserved">void</span> *e);</p>
b47dab17
MS
2237<h4 class="parameters">Parameters</h4>
2238<table class="list"><tbody>
2239<tr><th>a</th>
2240<td class="description">Array</td></tr>
2241<tr><th>e</th>
2242<td class="description">Element</td></tr>
2243</tbody></table>
2244<h4 class="returnvalue">Return Value</h4>
2245<p class="description">1 on success, 0 on failure</p>
2246<h4 class="discussion">Discussion</h4>
2247<p class="discussion">If more than one element matches &quot;e&quot;, only the first matching element is
2248removed.<br>
2249<br>
2250The caller is responsible for freeing the memory used by the
2251removed element.
2252
2253</p>
b6008d6b 2254<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArrayRestore">cupsArrayRestore</a></h3>
b47dab17
MS
2255<p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p>
2256<p class="code">
0350eba5 2257<span class="reserved">void</span> *cupsArrayRestore(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2258<h4 class="parameters">Parameters</h4>
2259<table class="list"><tbody>
2260<tr><th>a</th>
2261<td class="description">Array</td></tr>
2262</tbody></table>
2263<h4 class="returnvalue">Return Value</h4>
2264<p class="description">New current element</p>
b6008d6b 2265<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsArraySave">cupsArraySave</a></h3>
b47dab17
MS
2266<p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p>
2267<p class="code">
0350eba5 2268<span class="reserved">int</span> cupsArraySave(<a href="#cups_array_t">cups_array_t</a> *a);</p>
b47dab17
MS
2269<h4 class="parameters">Parameters</h4>
2270<table class="list"><tbody>
2271<tr><th>a</th>
2272<td class="description">Array</td></tr>
2273</tbody></table>
2274<h4 class="returnvalue">Return Value</h4>
2275<p class="description">1 on success, 0 on failure</p>
2276<h4 class="discussion">Discussion</h4>
2277<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
2278<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
2279to set the current element.<br>
2280<br>
2281The save/restore stack is guaranteed to be at least 32 elements deep.
2282
2283</p>
b6008d6b 2284<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCancelDestJob">cupsCancelDestJob</a></h3>
b47dab17 2285<p class="description">Cancel a job on a destination.</p>
98d88c8d 2286<p class="code">
0350eba5 2287ipp_status_t cupsCancelDestJob(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <span class="reserved">int</span> job_id);</p>
98d88c8d
MS
2288<h4 class="parameters">Parameters</h4>
2289<table class="list"><tbody>
2290<tr><th>http</th>
b47dab17 2291<td class="description">Connection to destination</td></tr>
98d88c8d 2292<tr><th>dest</th>
b47dab17 2293<td class="description">Destination</td></tr>
98d88c8d 2294<tr><th>job_id</th>
b47dab17 2295<td class="description">Job ID</td></tr>
98d88c8d
MS
2296</tbody></table>
2297<h4 class="returnvalue">Return Value</h4>
b47dab17 2298<p class="description">Status of cancel operation</p>
98d88c8d 2299<h4 class="discussion">Discussion</h4>
b47dab17 2300<p class="discussion">The &quot;job_id&quot; is the number returned by cupsCreateDestJob.<br>
798d6e29
MS
2301<br>
2302Returns <code>IPP_STATUS_OK</code> on success and
98d88c8d 2303<code>IPP_STATUS_ERROR_NOT_AUTHORIZED</code> or
798d6e29
MS
2304<code>IPP_STATUS_ERROR_FORBIDDEN</code> on failure.
2305
798d6e29 2306</p>
af268786
MS
2307<h3 class="function"><a id="cupsCharsetToUTF8">cupsCharsetToUTF8</a></h3>
2308<p class="description">Convert legacy character set to UTF-8.</p>
2309<p class="code">
0350eba5 2310<span class="reserved">int</span> cupsCharsetToUTF8(<a href="#cups_utf8_t">cups_utf8_t</a> *dest, <span class="reserved">const</span> <span class="reserved">char</span> *src, <span class="reserved">const</span> <span class="reserved">int</span> maxout, <span class="reserved">const</span> <a href="#cups_encoding_t">cups_encoding_t</a> encoding);</p>
af268786
MS
2311<h4 class="parameters">Parameters</h4>
2312<table class="list"><tbody>
2313<tr><th>dest</th>
2314<td class="description">Target string</td></tr>
2315<tr><th>src</th>
2316<td class="description">Source string</td></tr>
2317<tr><th>maxout</th>
2318<td class="description">Max output</td></tr>
2319<tr><th>encoding</th>
2320<td class="description">Encoding</td></tr>
2321</tbody></table>
2322<h4 class="returnvalue">Return Value</h4>
2323<p class="description">Count or -1 on error</p>
b6008d6b 2324<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCheckDestSupported">cupsCheckDestSupported</a></h3>
b47dab17 2325<p class="description">Check that the option and value are supported
af268786 2326 by the destination.</p>
798d6e29 2327<p class="code">
0350eba5 2328<span class="reserved">int</span> cupsCheckDestSupported(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
98d88c8d
MS
2329<h4 class="parameters">Parameters</h4>
2330<table class="list"><tbody>
2331<tr><th>http</th>
b47dab17 2332<td class="description">Connection to destination</td></tr>
98d88c8d 2333<tr><th>dest</th>
b47dab17 2334<td class="description">Destination</td></tr>
98d88c8d 2335<tr><th>dinfo</th>
b47dab17 2336<td class="description">Destination information</td></tr>
98d88c8d 2337<tr><th>option</th>
b47dab17 2338<td class="description">Option</td></tr>
98d88c8d 2339<tr><th>value</th>
b47dab17 2340<td class="description">Value or <code>NULL</code></td></tr>
98d88c8d 2341</tbody></table>
798d6e29 2342<h4 class="returnvalue">Return Value</h4>
b47dab17 2343<p class="description">1 if supported, 0 otherwise</p>
798d6e29 2344<h4 class="discussion">Discussion</h4>
b47dab17 2345<p class="discussion">Returns 1 if supported, 0 otherwise.
798d6e29
MS
2346
2347</p>
b6008d6b 2348<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCloseDestJob">cupsCloseDestJob</a></h3>
b47dab17 2349<p class="description">Close a job and start printing.</p>
798d6e29 2350<p class="code">
0350eba5 2351ipp_status_t cupsCloseDestJob(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *info, <span class="reserved">int</span> job_id);</p>
98d88c8d
MS
2352<h4 class="parameters">Parameters</h4>
2353<table class="list"><tbody>
2354<tr><th>http</th>
b47dab17 2355<td class="description">Connection to destination</td></tr>
98d88c8d 2356<tr><th>dest</th>
b47dab17 2357<td class="description">Destination</td></tr>
98d88c8d 2358<tr><th>info</th>
b47dab17 2359<td class="description">Destination information</td></tr>
98d88c8d 2360<tr><th>job_id</th>
b47dab17 2361<td class="description">Job ID</td></tr>
98d88c8d 2362</tbody></table>
798d6e29 2363<h4 class="returnvalue">Return Value</h4>
b47dab17 2364<p class="description">IPP status code</p>
798d6e29 2365<h4 class="discussion">Discussion</h4>
b47dab17 2366<p class="discussion">Use when the last call to cupsStartDocument passed 0 for &quot;last_document&quot;.
798d6e29
MS
2367&quot;job_id&quot; is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code>
2368on success.
2369
2370</p>
0350eba5
MS
2371<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsConcatString">cupsConcatString</a></h3>
2372<p class="description">Safely concatenate two UTF-8 strings.</p>
af268786 2373<p class="code">
0350eba5 2374size_t cupsConcatString(<span class="reserved">char</span> *dst, <span class="reserved">const</span> <span class="reserved">char</span> *src, size_t dstsize);</p>
af268786
MS
2375<h4 class="parameters">Parameters</h4>
2376<table class="list"><tbody>
2377<tr><th>dst</th>
2378<td class="description">Destination string</td></tr>
2379<tr><th>src</th>
2380<td class="description">Source string</td></tr>
2381<tr><th>dstsize</th>
2382<td class="description">Size of destination string buffer</td></tr>
2383</tbody></table>
2384<h4 class="returnvalue">Return Value</h4>
2385<p class="description">Length of string</p>
2386<h3 class="function"><a id="cupsCondBroadcast">cupsCondBroadcast</a></h3>
2387<p class="description">Wake up waiting threads.</p>
2388<p class="code">
0350eba5 2389<span class="reserved">void</span> cupsCondBroadcast(<a href="#cups_cond_t">cups_cond_t</a> *cond);</p>
af268786
MS
2390<h4 class="parameters">Parameters</h4>
2391<table class="list"><tbody>
2392<tr><th>cond</th>
2393<td class="description">Condition</td></tr>
2394</tbody></table>
2395<h3 class="function"><a id="cupsCondDestroy">cupsCondDestroy</a></h3>
2396<p class="description">Destroy a condition variable.</p>
2397<p class="code">
0350eba5 2398<span class="reserved">void</span> cupsCondDestroy(<a href="#cups_cond_t">cups_cond_t</a> *cond);</p>
af268786
MS
2399<h4 class="parameters">Parameters</h4>
2400<table class="list"><tbody>
2401<tr><th>cond</th>
2402<td class="description">Condition</td></tr>
2403</tbody></table>
2404<h3 class="function"><a id="cupsCondInit">cupsCondInit</a></h3>
2405<p class="description">Initialize a condition variable.</p>
2406<p class="code">
0350eba5 2407<span class="reserved">void</span> cupsCondInit(<a href="#cups_cond_t">cups_cond_t</a> *cond);</p>
af268786
MS
2408<h4 class="parameters">Parameters</h4>
2409<table class="list"><tbody>
2410<tr><th>cond</th>
2411<td class="description">Condition</td></tr>
2412</tbody></table>
2413<h3 class="function"><a id="cupsCondWait">cupsCondWait</a></h3>
2414<p class="description">Wait for a condition with optional timeout.</p>
2415<p class="code">
0350eba5 2416<span class="reserved">void</span> cupsCondWait(<a href="#cups_cond_t">cups_cond_t</a> *cond, <a href="#cups_mutex_t">cups_mutex_t</a> *mutex, <span class="reserved">double</span> timeout);</p>
af268786
MS
2417<h4 class="parameters">Parameters</h4>
2418<table class="list"><tbody>
2419<tr><th>cond</th>
2420<td class="description">Condition</td></tr>
2421<tr><th>mutex</th>
2422<td class="description">Mutex</td></tr>
2423<tr><th>timeout</th>
2424<td class="description">Timeout in seconds (<code>0</code> or negative for none)</td></tr>
2425</tbody></table>
b6008d6b 2426<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsConnectDest">cupsConnectDest</a></h3>
b47dab17 2427<p class="description">Open a connection to the destination.</p>
98d88c8d 2428<p class="code">
0350eba5 2429<a href="#http_t">http_t</a> *cupsConnectDest(<a href="#cups_dest_t">cups_dest_t</a> *dest, <span class="reserved">unsigned</span> flags, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel, <span class="reserved">char</span> *resource, size_t resourcesize, <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
98d88c8d
MS
2430<h4 class="parameters">Parameters</h4>
2431<table class="list"><tbody>
2432<tr><th>dest</th>
b47dab17 2433<td class="description">Destination</td></tr>
98d88c8d 2434<tr><th>flags</th>
b47dab17 2435<td class="description">Connection flags</td></tr>
98d88c8d 2436<tr><th>msec</th>
b47dab17 2437<td class="description">Timeout in milliseconds</td></tr>
98d88c8d 2438<tr><th>cancel</th>
b47dab17 2439<td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
98d88c8d 2440<tr><th>resource</th>
b47dab17 2441<td class="description">Resource buffer</td></tr>
98d88c8d 2442<tr><th>resourcesize</th>
b47dab17 2443<td class="description">Size of resource buffer</td></tr>
98d88c8d 2444<tr><th>cb</th>
b47dab17 2445<td class="description">Callback function</td></tr>
98d88c8d 2446<tr><th>user_data</th>
b47dab17 2447<td class="description">User data pointer</td></tr>
98d88c8d
MS
2448</tbody></table>
2449<h4 class="returnvalue">Return Value</h4>
b47dab17 2450<p class="description">Connection to destination or <code>NULL</code></p>
98d88c8d 2451<h4 class="discussion">Discussion</h4>
b47dab17 2452<p class="discussion">Connect to the destination, returning a new <code>http_t</code> connection object
98d88c8d
MS
2453and optionally the resource path to use for the destination. These calls
2454will block until a connection is made, the timeout expires, the integer
2455pointed to by &quot;cancel&quot; is non-zero, or the callback function (or block)
2456returns 0. The caller is responsible for calling <a href="#httpClose"><code>httpClose</code></a> on the
b0fb2d75
MS
2457returned connection.<br>
2458<br>
699fe020 2459Starting with CUPS 2.2.4, the caller can pass <code>CUPS_DEST_FLAGS_DEVICE</code>
b0fb2d75
MS
2460for the &quot;flags&quot; argument to connect directly to the device associated with
2461the destination. Otherwise, the connection is made to the CUPS scheduler
2462associated with the destination.
798d6e29
MS
2463
2464</p>
af268786
MS
2465<h3 class="function"><a id="cupsCopyCredentials">cupsCopyCredentials</a></h3>
2466<p class="description"></p>
798d6e29 2467<p class="code">
0350eba5 2468<span class="reserved">char</span> *cupsCopyCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name);</p>
98d88c8d
MS
2469<h4 class="parameters">Parameters</h4>
2470<table class="list"><tbody>
af268786
MS
2471<tr><th>path</th>
2472<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2473<tr><th>common_name</th>
2474<td class="description">Common name</td></tr>
98d88c8d 2475</tbody></table>
798d6e29 2476<h4 class="returnvalue">Return Value</h4>
af268786
MS
2477<p class="description">Copy the X.509 certificate chain to a string.</p>
2478<h3 class="function"><a id="cupsCopyCredentialsKey">cupsCopyCredentialsKey</a></h3>
2479<p class="description"></p>
798d6e29 2480<p class="code">
0350eba5 2481<span class="reserved">char</span> *cupsCopyCredentialsKey(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name);</p>
98d88c8d
MS
2482<h4 class="parameters">Parameters</h4>
2483<table class="list"><tbody>
af268786
MS
2484<tr><th>path</th>
2485<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2486<tr><th>common_name</th>
2487<td class="description">Common name</td></tr>
2488</tbody></table>
2489<h4 class="returnvalue">Return Value</h4>
2490<p class="description">Copy the private key to a string.</p>
b6008d6b
MS
2491<h3 class="function"><a id="cupsCopyCredentialsPublicKey">cupsCopyCredentialsPublicKey</a></h3>
2492<p class="description">Copy the public key for a X.509 certificate request.</p>
2493<p class="code">
2494<span class="reserved">char</span> *cupsCopyCredentialsPublicKey(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name);</p>
2495<h4 class="parameters">Parameters</h4>
2496<table class="list"><tbody>
2497<tr><th>path</th>
2498<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2499<tr><th>common_name</th>
2500<td class="description">Common name</td></tr>
2501</tbody></table>
2502<h4 class="returnvalue">Return Value</h4>
2503<p class="description">PEM-encoded public key</p>
af268786 2504<h3 class="function"><a id="cupsCopyCredentialsRequest">cupsCopyCredentialsRequest</a></h3>
b6008d6b 2505<p class="description">Copy the X.509 certificate signing request to a string.</p>
af268786 2506<p class="code">
0350eba5 2507<span class="reserved">char</span> *cupsCopyCredentialsRequest(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name);</p>
af268786
MS
2508<h4 class="parameters">Parameters</h4>
2509<table class="list"><tbody>
2510<tr><th>path</th>
2511<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2512<tr><th>common_name</th>
2513<td class="description">Common name</td></tr>
2514</tbody></table>
2515<h4 class="returnvalue">Return Value</h4>
b6008d6b
MS
2516<p class="description">PEM-encoded X.509 certificate signing request</p>
2517<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCopyDest">cupsCopyDest</a></h3>
af268786
MS
2518<p class="description">Copy a destination.</p>
2519<p class="code">
0350eba5 2520<span class="reserved">int</span> cupsCopyDest(<a href="#cups_dest_t">cups_dest_t</a> *dest, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
af268786
MS
2521<h4 class="parameters">Parameters</h4>
2522<table class="list"><tbody>
2523<tr><th>dest</th>
2524<td class="description">Destination to copy</td></tr>
2525<tr><th>num_dests</th>
2526<td class="description">Number of destinations</td></tr>
2527<tr><th>dests</th>
2528<td class="description">Destination array</td></tr>
2529</tbody></table>
2530<h4 class="returnvalue">Return Value</h4>
2531<p class="description">New number of destinations</p>
2532<h4 class="discussion">Discussion</h4>
2533<p class="discussion">Make a copy of the destination to an array of destinations (or just a single
2534copy) - for use with the cupsEnumDests* functions. The caller is responsible
2535for calling cupsFreeDests() on the returned object(s).
2536
2537</p>
b6008d6b 2538<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3>
af268786
MS
2539<p class="description">Get conflicts and resolutions for a new
2540 option/value pair.</p>
2541<p class="code">
0350eba5 2542<span class="reserved">int</span> cupsCopyDestConflicts(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options, <span class="reserved">const</span> <span class="reserved">char</span> *new_option, <span class="reserved">const</span> <span class="reserved">char</span> *new_value, <span class="reserved">int</span> *num_conflicts, <a href="#cups_option_t">cups_option_t</a> **conflicts, <span class="reserved">int</span> *num_resolved, <a href="#cups_option_t">cups_option_t</a> **resolved);</p>
af268786
MS
2543<h4 class="parameters">Parameters</h4>
2544<table class="list"><tbody>
2545<tr><th>http</th>
b47dab17 2546<td class="description">Connection to destination</td></tr>
98d88c8d 2547<tr><th>dest</th>
b47dab17 2548<td class="description">Destination</td></tr>
98d88c8d 2549<tr><th>dinfo</th>
b47dab17 2550<td class="description">Destination information</td></tr>
98d88c8d 2551<tr><th>num_options</th>
b47dab17 2552<td class="description">Number of current options</td></tr>
98d88c8d 2553<tr><th>options</th>
b47dab17 2554<td class="description">Current options</td></tr>
98d88c8d 2555<tr><th>new_option</th>
b47dab17 2556<td class="description">New option</td></tr>
98d88c8d 2557<tr><th>new_value</th>
b47dab17 2558<td class="description">New value</td></tr>
98d88c8d 2559<tr><th>num_conflicts</th>
b47dab17 2560<td class="description">Number of conflicting options</td></tr>
98d88c8d 2561<tr><th>conflicts</th>
b47dab17 2562<td class="description">Conflicting options</td></tr>
98d88c8d 2563<tr><th>num_resolved</th>
b47dab17 2564<td class="description">Number of options to resolve</td></tr>
98d88c8d 2565<tr><th>resolved</th>
b47dab17 2566<td class="description">Resolved options</td></tr>
98d88c8d 2567</tbody></table>
798d6e29 2568<h4 class="returnvalue">Return Value</h4>
b47dab17 2569<p class="description">1 if there is a conflict, 0 if none, -1 on error</p>
798d6e29 2570<h4 class="discussion">Discussion</h4>
b47dab17 2571<p class="discussion">&quot;num_options&quot; and &quot;options&quot; represent the currently selected options by the
798d6e29
MS
2572user. &quot;new_option&quot; and &quot;new_value&quot; are the setting the user has just
2573changed.<br>
2574<br>
2575Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
2576there was an unrecoverable error such as a resolver loop.<br>
2577<br>
2578If &quot;num_conflicts&quot; and &quot;conflicts&quot; are not <code>NULL</code>, they are set to
2579contain the list of conflicting option/value pairs. Similarly, if
2580&quot;num_resolved&quot; and &quot;resolved&quot; are not <code>NULL</code> they will be set to the
2581list of changes needed to resolve the conflict.<br>
2582<br>
2583If cupsCopyDestConflicts returns 1 but &quot;num_resolved&quot; and &quot;resolved&quot; are set
2584to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved.
2585
2586</p>
0350eba5 2587<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCopyDestInfo">cupsCopyDestInfo</a></h3>
b47dab17 2588<p class="description">Get the supported values/capabilities for the
af268786 2589 destination.</p>
798d6e29 2590<p class="code">
98d88c8d 2591<a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest);</p>
798d6e29 2592<h4 class="parameters">Parameters</h4>
98d88c8d
MS
2593<table class="list"><tbody>
2594<tr><th>http</th>
b47dab17 2595<td class="description">Connection to destination</td></tr>
98d88c8d 2596<tr><th>dest</th>
b47dab17 2597<td class="description">Destination</td></tr>
98d88c8d 2598</tbody></table>
798d6e29 2599<h4 class="returnvalue">Return Value</h4>
b47dab17 2600<p class="description">Destination information</p>
798d6e29 2601<h4 class="discussion">Discussion</h4>
b47dab17 2602<p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return
798d6e29
MS
2603value. <code>NULL</code> is returned on error.
2604
2605</p>
0350eba5
MS
2606<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsCopyDestInfo2">cupsCopyDestInfo2</a></h3>
2607<p class="description">Get the supported values/capabilities for the
2608 destination.</p>
2609<p class="code">
2610<a href="#cups_dinfo_t">cups_dinfo_t</a> *cupsCopyDestInfo2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dest_flags_t">cups_dest_flags_t</a> dflags);</p>
2611<h4 class="parameters">Parameters</h4>
2612<table class="list"><tbody>
2613<tr><th>http</th>
2614<td class="description">Connection to destination</td></tr>
2615<tr><th>dest</th>
2616<td class="description">Destination</td></tr>
2617<tr><th>dflags</th>
2618<td class="description">Destination flags</td></tr>
2619</tbody></table>
2620<h4 class="returnvalue">Return Value</h4>
2621<p class="description">Destination information</p>
2622<h4 class="discussion">Discussion</h4>
2623<p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return
2624value. <code>NULL</code> is returned on error.
2625
2626</p>
2627<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsCopyString">cupsCopyString</a></h3>
2628<p class="description">Safely copy a UTF-8 string.</p>
af268786 2629<p class="code">
0350eba5 2630size_t cupsCopyString(<span class="reserved">char</span> *dst, <span class="reserved">const</span> <span class="reserved">char</span> *src, size_t dstsize);</p>
af268786
MS
2631<h4 class="parameters">Parameters</h4>
2632<table class="list"><tbody>
2633<tr><th>dst</th>
2634<td class="description">Destination string</td></tr>
2635<tr><th>src</th>
2636<td class="description">Source string</td></tr>
2637<tr><th>dstsize</th>
2638<td class="description">Size of destination string buffer</td></tr>
2639</tbody></table>
2640<h4 class="returnvalue">Return Value</h4>
2641<p class="description">Length of string</p>
2642<h3 class="function"><a id="cupsCreateCredentials">cupsCreateCredentials</a></h3>
2643<p class="description">Make an X.509 certificate and private key pair.</p>
2644<p class="code">
0350eba5 2645<span class="reserved">bool</span> cupsCreateCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">bool</span> ca_cert, <a href="#cups_credpurpose_t">cups_credpurpose_t</a> purpose, <a href="#cups_credtype_t">cups_credtype_t</a> type, <a href="#cups_credusage_t">cups_credusage_t</a> usage, <span class="reserved">const</span> <span class="reserved">char</span> *organization, <span class="reserved">const</span> <span class="reserved">char</span> *org_unit, <span class="reserved">const</span> <span class="reserved">char</span> *locality, <span class="reserved">const</span> <span class="reserved">char</span> *state_province, <span class="reserved">const</span> <span class="reserved">char</span> *country, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *email, size_t num_alt_names, <span class="reserved">const</span> <span class="reserved">char</span> *const *alt_names, <span class="reserved">const</span> <span class="reserved">char</span> *root_name, time_t expiration_date);</p>
af268786
MS
2646<h4 class="parameters">Parameters</h4>
2647<table class="list"><tbody>
2648<tr><th>path</th>
2649<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2650<tr><th>ca_cert</th>
2651<td class="description"><code>true</code> to create a CA certificate, <code>false</code> for a client/server certificate</td></tr>
2652<tr><th>purpose</th>
2653<td class="description">Credential purposes</td></tr>
2654<tr><th>type</th>
2655<td class="description">Credential type</td></tr>
2656<tr><th>usage</th>
2657<td class="description">Credential usages</td></tr>
2658<tr><th>organization</th>
2659<td class="description">Organization or <code>NULL</code> to use common name</td></tr>
2660<tr><th>org_unit</th>
2661<td class="description">Organizational unit or <code>NULL</code> for none</td></tr>
2662<tr><th>locality</th>
2663<td class="description">City/town or <code>NULL</code> for &quot;Unknown&quot;</td></tr>
2664<tr><th>state_province</th>
2665<td class="description">State/province or <code>NULL</code> for &quot;Unknown&quot;</td></tr>
2666<tr><th>country</th>
2667<td class="description">Country or <code>NULL</code> for locale-based default</td></tr>
2668<tr><th>common_name</th>
2669<td class="description">Common name</td></tr>
2670<tr><th>email</th>
2671<td class="description">Email address or <code>NULL</code> for none</td></tr>
2672<tr><th>num_alt_names</th>
2673<td class="description">Number of subject alternate names</td></tr>
2674<tr><th>alt_names</th>
2675<td class="description">Subject Alternate Names</td></tr>
2676<tr><th>root_name</th>
2677<td class="description">Root certificate/domain name or <code>NULL</code> for site/self-signed</td></tr>
2678<tr><th>expiration_date</th>
2679<td class="description">Expiration date</td></tr>
2680</tbody></table>
2681<h4 class="returnvalue">Return Value</h4>
2682<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
2683<h4 class="discussion">Discussion</h4>
2684<p class="discussion">This function creates an X.509 certificate and private key pair. The
2685certificate and key are stored in the directory &quot;path&quot; or, if &quot;path&quot; is
2686<code>NULL</code>, in a per-user or system-wide (when running as root) certificate/key
2687store. The generated certificate is signed by the named root certificate or,
2688if &quot;root_name&quot; is <code>NULL</code>, a site-wide default root certificate. When
2689&quot;root_name&quot; is <code>NULL</code> and there is no site-wide default root certificate, a
2690self-signed certificate is generated instead.<br>
2691<br>
2692The &quot;ca_cert&quot; argument specifies whether a CA certificate should be created.<br>
2693<br>
2694The &quot;purpose&quot; argument specifies the purpose(s) used for the credentials as a
2695bitwise OR of the following constants:
2696
2697</p><ul>
2698<li><code>CUPS_CREDPURPOSE_SERVER_AUTH</code> for validating TLS servers,
2699</li>
2700<li><code>CUPS_CREDPURPOSE_CLIENT_AUTH</code> for validating TLS clients,
2701</li>
2702<li><code>CUPS_CREDPURPOSE_CODE_SIGNING</code> for validating compiled code,
2703</li>
2704<li><code>CUPS_CREDPURPOSE_EMAIL_PROTECTION</code> for validating email messages,
2705</li>
2706<li><code>CUPS_CREDPURPOSE_TIME_STAMPING</code> for signing timestamps to objects, and/or
2707</li>
2708<li><code>CUPS_CREDPURPOSE_OCSP_SIGNING</code> for Online Certificate Status Protocol
2709 message signing.</li>
2710</ul>
2711<p class="discussion">The &quot;type&quot; argument specifies the type of credentials using one of the
2712following constants:
2713
2714</p><ul>
2715<li><code>CUPS_CREDTYPE_DEFAULT</code>: default type (RSA-3072 or P-384),
2716</li>
2717<li><code>CUPS_CREDTYPE_RSA_2048_SHA256</code>: RSA with 2048-bit keys and SHA-256 hash,
2718</li>
2719<li><code>CUPS_CREDTYPE_RSA_3072_SHA256</code>: RSA with 3072-bit keys and SHA-256 hash,
2720</li>
2721<li><code>CUPS_CREDTYPE_RSA_4096_SHA256</code>: RSA with 4096-bit keys and SHA-256 hash,
2722</li>
2723<li><code>CUPS_CREDTYPE_ECDSA_P256_SHA256</code>: ECDSA using the P-256 curve with SHA-256 hash,
2724</li>
2725<li><code>CUPS_CREDTYPE_ECDSA_P384_SHA256</code>: ECDSA using the P-384 curve with SHA-256 hash, or
2726</li>
2727<li><code>CUPS_CREDTYPE_ECDSA_P521_SHA256</code>: ECDSA using the P-521 curve with SHA-256 hash.</li>
2728</ul>
2729<p class="discussion">The &quot;usage&quot; argument specifies the usage(s) for the credentials as a bitwise
2730OR of the following constants:
2731
2732</p><ul>
2733<li><code>CUPS_CREDUSAGE_DIGITAL_SIGNATURE</code>: digital signatures,
2734</li>
2735<li><code>CUPS_CREDUSAGE_NON_REPUDIATION</code>: non-repudiation/content commitment,
2736</li>
2737<li><code>CUPS_CREDUSAGE_KEY_ENCIPHERMENT</code>: key encipherment,
2738</li>
2739<li><code>CUPS_CREDUSAGE_DATA_ENCIPHERMENT</code>: data encipherment,
2740</li>
2741<li><code>CUPS_CREDUSAGE_KEY_AGREEMENT</code>: key agreement,
2742</li>
2743<li><code>CUPS_CREDUSAGE_KEY_CERT_SIGN</code>: key certicate signing,
2744</li>
2745<li><code>CUPS_CREDUSAGE_CRL_SIGN</code>: certificate revocation list signing,
2746</li>
2747<li><code>CUPS_CREDUSAGE_ENCIPHER_ONLY</code>: encipherment only,
2748</li>
2749<li><code>CUPS_CREDUSAGE_DECIPHER_ONLY</code>: decipherment only,
2750</li>
2751<li><code>CUPS_CREDUSAGE_DEFAULT_CA</code>: defaults for CA certificates,
2752</li>
2753<li><code>CUPS_CREDUSAGE_DEFAULT_TLS</code>: defaults for TLS certificates, and/or
2754</li>
2755<li><code>CUPS_CREDUSAGE_ALL</code>: all usages.</li>
2756</ul>
2757<p class="discussion">The &quot;organization&quot;, &quot;org_unit&quot;, &quot;locality&quot;, &quot;state_province&quot;, and &quot;country&quot;
2758arguments specify information about the identity and geolocation of the
2759issuer.<br>
2760<br>
2761The &quot;common_name&quot; argument specifies the common name and the &quot;num_alt_names&quot;
2762and &quot;alt_names&quot; arguments specify a list of DNS hostnames for the
2763certificate.<br>
2764<br>
2765The &quot;expiration_date&quot; argument specifies the expiration date and time as a
2766Unix <code>time_t</code> value in seconds.</p>
2767<h3 class="function"><a id="cupsCreateCredentialsRequest">cupsCreateCredentialsRequest</a></h3>
2768<p class="description">Make an X.509 Certificate Signing Request.</p>
2769<p class="code">
0350eba5 2770<span class="reserved">bool</span> cupsCreateCredentialsRequest(<span class="reserved">const</span> <span class="reserved">char</span> *path, <a href="#cups_credpurpose_t">cups_credpurpose_t</a> purpose, <a href="#cups_credtype_t">cups_credtype_t</a> type, <a href="#cups_credusage_t">cups_credusage_t</a> usage, <span class="reserved">const</span> <span class="reserved">char</span> *organization, <span class="reserved">const</span> <span class="reserved">char</span> *org_unit, <span class="reserved">const</span> <span class="reserved">char</span> *locality, <span class="reserved">const</span> <span class="reserved">char</span> *state_province, <span class="reserved">const</span> <span class="reserved">char</span> *country, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *email, size_t num_alt_names, <span class="reserved">const</span> <span class="reserved">char</span> *const *alt_names);</p>
af268786
MS
2771<h4 class="parameters">Parameters</h4>
2772<table class="list"><tbody>
2773<tr><th>path</th>
2774<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
2775<tr><th>purpose</th>
2776<td class="description">Credential purposes</td></tr>
2777<tr><th>type</th>
2778<td class="description">Credential type</td></tr>
2779<tr><th>usage</th>
2780<td class="description">Credential usages</td></tr>
2781<tr><th>organization</th>
2782<td class="description">Organization or <code>NULL</code> to use common name</td></tr>
2783<tr><th>org_unit</th>
2784<td class="description">Organizational unit or <code>NULL</code> for none</td></tr>
2785<tr><th>locality</th>
2786<td class="description">City/town or <code>NULL</code> for &quot;Unknown&quot;</td></tr>
2787<tr><th>state_province</th>
2788<td class="description">State/province or <code>NULL</code> for &quot;Unknown&quot;</td></tr>
2789<tr><th>country</th>
2790<td class="description">Country or <code>NULL</code> for locale-based default</td></tr>
2791<tr><th>common_name</th>
2792<td class="description">Common name</td></tr>
2793<tr><th>email</th>
2794<td class="description">Email address or <code>NULL</code> for none</td></tr>
2795<tr><th>num_alt_names</th>
2796<td class="description">Number of subject alternate names</td></tr>
2797<tr><th>alt_names</th>
2798<td class="description">Subject Alternate Names</td></tr>
2799</tbody></table>
2800<h4 class="returnvalue">Return Value</h4>
2801<p class="description"><code>true</code> on success, <code>false</code> on error</p>
2802<h4 class="discussion">Discussion</h4>
2803<p class="discussion">This function creates an X.509 certificate signing request (CSR) and
2804associated private key. The CSR and key are stored in the directory &quot;path&quot;
2805or, if &quot;path&quot; is <code>NULL</code>, in a per-user or system-wide (when running as root)
2806certificate/key store.<br>
2807<br>
2808The &quot;purpose&quot; argument specifies the purpose(s) used for the credentials as a
2809bitwise OR of the following constants:
2810
2811</p><ul>
2812<li><code>CUPS_CREDPURPOSE_SERVER_AUTH</code> for validating TLS servers,
2813</li>
2814<li><code>CUPS_CREDPURPOSE_CLIENT_AUTH</code> for validating TLS clients,
2815</li>
2816<li><code>CUPS_CREDPURPOSE_CODE_SIGNING</code> for validating compiled code,
2817</li>
2818<li><code>CUPS_CREDPURPOSE_EMAIL_PROTECTION</code> for validating email messages,
2819</li>
2820<li><code>CUPS_CREDPURPOSE_TIME_STAMPING</code> for signing timestamps to objects, and/or
2821</li>
2822<li><code>CUPS_CREDPURPOSE_OCSP_SIGNING</code> for Online Certificate Status Protocol
2823 message signing.</li>
2824</ul>
2825<p class="discussion">The &quot;type&quot; argument specifies the type of credentials using one of the
2826following constants:
2827
2828</p><ul>
2829<li><code>CUPS_CREDTYPE_DEFAULT</code>: default type (RSA-3072 or P-384),
2830</li>
2831<li><code>CUPS_CREDTYPE_RSA_2048_SHA256</code>: RSA with 2048-bit keys and SHA-256 hash,
2832</li>
2833<li><code>CUPS_CREDTYPE_RSA_3072_SHA256</code>: RSA with 3072-bit keys and SHA-256 hash,
2834</li>
2835<li><code>CUPS_CREDTYPE_RSA_4096_SHA256</code>: RSA with 4096-bit keys and SHA-256 hash,
2836</li>
2837<li><code>CUPS_CREDTYPE_ECDSA_P256_SHA256</code>: ECDSA using the P-256 curve with SHA-256 hash,
2838</li>
2839<li><code>CUPS_CREDTYPE_ECDSA_P384_SHA256</code>: ECDSA using the P-384 curve with SHA-256 hash, or
2840</li>
2841<li><code>CUPS_CREDTYPE_ECDSA_P521_SHA256</code>: ECDSA using the P-521 curve with SHA-256 hash.</li>
2842</ul>
2843<p class="discussion">The &quot;usage&quot; argument specifies the usage(s) for the credentials as a bitwise
2844OR of the following constants:
2845
2846</p><ul>
2847<li><code>CUPS_CREDUSAGE_DIGITAL_SIGNATURE</code>: digital signatures,
2848</li>
2849<li><code>CUPS_CREDUSAGE_NON_REPUDIATION</code>: non-repudiation/content commitment,
2850</li>
2851<li><code>CUPS_CREDUSAGE_KEY_ENCIPHERMENT</code>: key encipherment,
2852</li>
2853<li><code>CUPS_CREDUSAGE_DATA_ENCIPHERMENT</code>: data encipherment,
2854</li>
2855<li><code>CUPS_CREDUSAGE_KEY_AGREEMENT</code>: key agreement,
2856</li>
2857<li><code>CUPS_CREDUSAGE_KEY_CERT_SIGN</code>: key certicate signing,
2858</li>
2859<li><code>CUPS_CREDUSAGE_CRL_SIGN</code>: certificate revocation list signing,
2860</li>
2861<li><code>CUPS_CREDUSAGE_ENCIPHER_ONLY</code>: encipherment only,
2862</li>
2863<li><code>CUPS_CREDUSAGE_DECIPHER_ONLY</code>: decipherment only,
2864</li>
2865<li><code>CUPS_CREDUSAGE_DEFAULT_CA</code>: defaults for CA certificates,
2866</li>
2867<li><code>CUPS_CREDUSAGE_DEFAULT_TLS</code>: defaults for TLS certificates, and/or
2868</li>
2869<li><code>CUPS_CREDUSAGE_ALL</code>: all usages.</li>
2870</ul>
2871<p class="discussion">The &quot;organization&quot;, &quot;org_unit&quot;, &quot;locality&quot;, &quot;state_province&quot;, and &quot;country&quot;
2872arguments specify information about the identity and geolocation of the
2873issuer.<br>
2874<br>
2875The &quot;common_name&quot; argument specifies the common name and the &quot;num_alt_names&quot;
2876and &quot;alt_names&quot; arguments specify a list of DNS hostnames for the
2877certificate.</p>
b6008d6b 2878<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsCreateDestJob">cupsCreateDestJob</a></h3>
b47dab17 2879<p class="description">Create a job on a destination.</p>
798d6e29 2880<p class="code">
0350eba5 2881ipp_status_t cupsCreateDestJob(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *info, <span class="reserved">int</span> *job_id, <span class="reserved">const</span> <span class="reserved">char</span> *title, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
98d88c8d
MS
2882<h4 class="parameters">Parameters</h4>
2883<table class="list"><tbody>
2884<tr><th>http</th>
b47dab17 2885<td class="description">Connection to destination</td></tr>
98d88c8d 2886<tr><th>dest</th>
b47dab17 2887<td class="description">Destination</td></tr>
98d88c8d 2888<tr><th>info</th>
b47dab17 2889<td class="description">Destination information</td></tr>
98d88c8d 2890<tr><th>job_id</th>
b47dab17 2891<td class="description">Job ID or 0 on error</td></tr>
98d88c8d 2892<tr><th>title</th>
b47dab17 2893<td class="description">Job name</td></tr>
98d88c8d 2894<tr><th>num_options</th>
b47dab17 2895<td class="description">Number of job options</td></tr>
98d88c8d 2896<tr><th>options</th>
b47dab17
MS
2897<td class="description">Job options</td></tr>
2898</tbody></table>
2899<h4 class="returnvalue">Return Value</h4>
2900<p class="description">IPP status code</p>
2901<h4 class="discussion">Discussion</h4>
2902<p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID
2903in the variable pointed to by &quot;job_id&quot;.
2904
2905</p>
af268786
MS
2906<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsCreateTempFd">cupsCreateTempFd</a></h3>
2907<p class="description">Creates a temporary file descriptor.</p>
b47dab17 2908<p class="code">
0350eba5 2909<span class="reserved">int</span> cupsCreateTempFd(<span class="reserved">const</span> <span class="reserved">char</span> *prefix, <span class="reserved">const</span> <span class="reserved">char</span> *suffix, <span class="reserved">char</span> *filename, size_t len);</p>
b47dab17
MS
2910<h4 class="parameters">Parameters</h4>
2911<table class="list"><tbody>
af268786
MS
2912<tr><th>prefix</th>
2913<td class="description">Filename prefix or <code>NULL</code> for none</td></tr>
2914<tr><th>suffix</th>
2915<td class="description">Filename suffix or <code>NULL</code> for none</td></tr>
2916<tr><th>filename</th>
2917<td class="description">Pointer to buffer</td></tr>
2918<tr><th>len</th>
2919<td class="description">Size of buffer</td></tr>
b47dab17 2920</tbody></table>
af268786
MS
2921<h4 class="returnvalue">Return Value</h4>
2922<p class="description">New file descriptor or <code>-1</code> on error</p>
2923<h4 class="discussion">Discussion</h4>
2924<p class="discussion">This function creates a temporary file and associated descriptor. The unique
2925temporary filename uses the &quot;prefix&quot; and &quot;suffix&quot; arguments and is returned
2926in the &quot;filename&quot; buffer. The temporary file is opened for reading and
2927writing.
2928
2929</p>
2930<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsCreateTempFile">cupsCreateTempFile</a></h3>
2931<p class="description">Creates a temporary CUPS file.</p>
b47dab17 2932<p class="code">
0350eba5 2933<a href="#cups_file_t">cups_file_t</a> *cupsCreateTempFile(<span class="reserved">const</span> <span class="reserved">char</span> *prefix, <span class="reserved">const</span> <span class="reserved">char</span> *suffix, <span class="reserved">char</span> *filename, size_t len);</p>
b47dab17
MS
2934<h4 class="parameters">Parameters</h4>
2935<table class="list"><tbody>
af268786
MS
2936<tr><th>prefix</th>
2937<td class="description">Filename prefix or <code>NULL</code> for none</td></tr>
2938<tr><th>suffix</th>
2939<td class="description">Filename suffix or <code>NULL</code> for none</td></tr>
2940<tr><th>filename</th>
2941<td class="description">Pointer to buffer</td></tr>
2942<tr><th>len</th>
2943<td class="description">Size of buffer</td></tr>
b47dab17
MS
2944</tbody></table>
2945<h4 class="returnvalue">Return Value</h4>
af268786
MS
2946<p class="description">CUPS file or <code>NULL</code> on error</p>
2947<h4 class="discussion">Discussion</h4>
2948<p class="discussion">This function creates a temporary file and returns a CUPS file for it. The
2949unique temporary filename uses the &quot;prefix&quot; and &quot;suffix&quot; arguments and is
2950returned in the &quot;filename&quot; buffer. The temporary file is opened for writing.
2951
2952</p>
2953<h3 class="function"><a id="cupsDNSSDAssembleFullName">cupsDNSSDAssembleFullName</a></h3>
2954<p class="description">Create a full service name from the instance
2955 name, registration type, and domain.</p>
b47dab17 2956<p class="code">
0350eba5 2957<span class="reserved">bool</span> cupsDNSSDAssembleFullName(<span class="reserved">char</span> *fullname, size_t fullsize, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *type, <span class="reserved">const</span> <span class="reserved">char</span> *domain);</p>
b47dab17
MS
2958<h4 class="parameters">Parameters</h4>
2959<table class="list"><tbody>
af268786
MS
2960<tr><th>fullname</th>
2961<td class="description">Buffer for full name</td></tr>
2962<tr><th>fullsize</th>
2963<td class="description">Size of buffer</td></tr>
2964<tr><th>name</th>
2965<td class="description">Service instance name</td></tr>
2966<tr><th>type</th>
2967<td class="description">Registration type</td></tr>
2968<tr><th>domain</th>
2969<td class="description">Domain</td></tr>
b47dab17
MS
2970</tbody></table>
2971<h4 class="returnvalue">Return Value</h4>
af268786
MS
2972<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
2973<h4 class="discussion">Discussion</h4>
2974<p class="discussion">This function combines an instance name (&quot;Example Name&quot;), registration type
2975(&quot;_ipp._tcp&quot;), and domain (&quot;local.&quot;) to create a properly escaped full
2976service name (&quot;Example032Name._ipp._tcp.local.&quot;).</p>
2977<h3 class="function"><a id="cupsDNSSDBrowseDelete">cupsDNSSDBrowseDelete</a></h3>
2978<p class="description">Cancel and delete a browse request.</p>
b47dab17 2979<p class="code">
0350eba5 2980<span class="reserved">void</span> cupsDNSSDBrowseDelete(<a href="#cups_dnssd_browse_t">cups_dnssd_browse_t</a> *browse);</p>
b47dab17
MS
2981<h4 class="parameters">Parameters</h4>
2982<table class="list"><tbody>
af268786
MS
2983<tr><th>browse</th>
2984<td class="description">Browse request</td></tr>
b47dab17 2985</tbody></table>
af268786
MS
2986<h3 class="function"><a id="cupsDNSSDBrowseGetContext">cupsDNSSDBrowseGetContext</a></h3>
2987<p class="description">Get the DNS-SD context for the browse request.</p>
b47dab17 2988<p class="code">
af268786 2989<a href="#cups_dnssd_t">cups_dnssd_t</a> *cupsDNSSDBrowseGetContext(<a href="#cups_dnssd_browse_t">cups_dnssd_browse_t</a> *browse);</p>
b47dab17
MS
2990<h4 class="parameters">Parameters</h4>
2991<table class="list"><tbody>
af268786
MS
2992<tr><th>browse</th>
2993<td class="description">Browse request</td></tr>
b47dab17
MS
2994</tbody></table>
2995<h4 class="returnvalue">Return Value</h4>
af268786
MS
2996<p class="description">Context or <code>NULL</code></p>
2997<h3 class="function"><a id="cupsDNSSDBrowseNew">cupsDNSSDBrowseNew</a></h3>
2998<p class="description">Create a new DNS-SD browse request.</p>
2999<p class="code">
0350eba5 3000<a href="#cups_dnssd_browse_t">cups_dnssd_browse_t</a> *cupsDNSSDBrowseNew(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, uint32_t if_index, <span class="reserved">const</span> <span class="reserved">char</span> *types, <span class="reserved">const</span> <span class="reserved">char</span> *domain, <a href="#cups_dnssd_browse_cb_t">cups_dnssd_browse_cb_t</a> browse_cb, <span class="reserved">void</span> *cb_data);</p>
af268786
MS
3001<h4 class="parameters">Parameters</h4>
3002<table class="list"><tbody>
3003<tr><th>dnssd</th>
3004<td class="description">DNS-SD context</td></tr>
3005<tr><th>if_index</th>
0350eba5 3006<td class="description">Interface index, <code>CUPS_DNSSD_IF_INDEX_ANY</code>, or <code>CUPS_DNSSD_IF_INDEX_LOCAL</code></td></tr>
af268786
MS
3007<tr><th>types</th>
3008<td class="description">Service types</td></tr>
3009<tr><th>domain</th>
3010<td class="description">Domain name or <code>NULL</code> for default</td></tr>
3011<tr><th>browse_cb</th>
3012<td class="description">Browse callback function</td></tr>
3013<tr><th>cb_data</th>
3014<td class="description">Browse callback data</td></tr>
3015</tbody></table>
3016<h4 class="returnvalue">Return Value</h4>
3017<p class="description">Browse request or <code>NULL</code> on error</p>
b47dab17 3018<h4 class="discussion">Discussion</h4>
af268786
MS
3019<p class="discussion">This function creates a new DNS-SD browse request for the specified service
3020types and optional domain and interface index. The &quot;types&quot; argument can be a
3021single service type (&quot;_ipp._tcp&quot;) or a service type and comma-delimited list
3022of sub-types (&quot;_ipp._tcp,_print,_universal&quot;).<br>
3023<br>
3024Newly discovered services are reported using the required browse callback
3025function, with the &quot;flags&quot; argument set to <code>CUPS_DNSSD_FLAGS_ADD</code> for newly
3026discovered services, <code>CUPS_DNSSD_FLAGS_NONE</code> for removed services, or
3027<code>CUPS_DNSSD_FLAGS_ERROR</code> on an error:
3028
3029<pre>
3030void
3031browse_cb(
3032 cups_dnssd_browse_t *browse,
3033 void *cb_data,
3034 cups_dnssd_flags_t flags,
3035 uint32_t if_index,
3036 const char *name,
3037 const char *regtype,
3038 const char *domain)
3039{
3040 // Process added/removed service
3041}
3042</pre>
b47dab17 3043</p>
0350eba5
MS
3044<h3 class="function"><a id="cupsDNSSDCopyComputerName">cupsDNSSDCopyComputerName</a></h3>
3045<p class="description">Copy the current human-readable name for the system.</p>
3046<p class="code">
3047<span class="reserved">char</span> *cupsDNSSDCopyComputerName(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
3048<h4 class="parameters">Parameters</h4>
3049<table class="list"><tbody>
3050<tr><th>dnssd</th>
3051<td class="description">DNS-SD context</td></tr>
3052<tr><th>buffer</th>
3053<td class="description">Computer name buffer</td></tr>
3054<tr><th>bufsize</th>
3055<td class="description">Size of computer name buffer (at least 128 bytes)</td></tr>
3056</tbody></table>
3057<h4 class="returnvalue">Return Value</h4>
3058<p class="description">Computer name or <code>NULL</code> on error</p>
3059<h4 class="discussion">Discussion</h4>
3060<p class="discussion">This function copies the current human-readable name (&quot;My Computer&quot;) to the
3061provided buffer. The &quot;dnssd&quot; parameter is a DNS-SD context created with
3062<a href="#cupsDNSSDNew"><code>cupsDNSSDNew</code></a>. The &quot;buffer&quot; parameter points to a character array of
3063at least 128 bytes and the &quot;bufsize&quot; parameter specifies the actual size of
3064the array.</p>
af268786
MS
3065<h3 class="function"><a id="cupsDNSSDCopyHostName">cupsDNSSDCopyHostName</a></h3>
3066<p class="description">Copy the current mDNS hostname for the system.</p>
b47dab17 3067<p class="code">
0350eba5 3068<span class="reserved">char</span> *cupsDNSSDCopyHostName(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
b47dab17
MS
3069<h4 class="parameters">Parameters</h4>
3070<table class="list"><tbody>
af268786
MS
3071<tr><th>dnssd</th>
3072<td class="description">DNS-SD context</td></tr>
3073<tr><th>buffer</th>
3074<td class="description">Hostname buffer</td></tr>
3075<tr><th>bufsize</th>
3076<td class="description">Size of hostname buffer (at least 70 bytes)</td></tr>
b47dab17
MS
3077</tbody></table>
3078<h4 class="returnvalue">Return Value</h4>
af268786
MS
3079<p class="description">mDNS hostname or <code>NULL</code> on error</p>
3080<h4 class="discussion">Discussion</h4>
3081<p class="discussion">This function copies the current mDNS hostname (&quot;hostname.local&quot;) to the
3082provided buffer. The &quot;dnssd&quot; parameter is a DNS-SD context created with
3083<a href="#cupsDNSSDNew"><code>cupsDNSSDNew</code></a>. The &quot;buffer&quot; parameter points to a character array of
3084at least 70 bytes and the &quot;bufsize&quot; parameter specifies the actual size of
3085the array.</p>
3086<h3 class="function"><a id="cupsDNSSDDecodeTXT">cupsDNSSDDecodeTXT</a></h3>
3087<p class="description">Decode a TXT record into key/value pairs.</p>
b47dab17 3088<p class="code">
0350eba5 3089<span class="reserved">int</span> cupsDNSSDDecodeTXT(<span class="reserved">const</span> <span class="reserved">unsigned</span> <span class="reserved">char</span> *txtrec, uint16_t txtlen, <a href="#cups_option_t">cups_option_t</a> **txt);</p>
b47dab17
MS
3090<h4 class="parameters">Parameters</h4>
3091<table class="list"><tbody>
af268786
MS
3092<tr><th>txtrec</th>
3093<td class="description">TXT record data</td></tr>
3094<tr><th>txtlen</th>
3095<td class="description">TXT record length</td></tr>
3096<tr><th>txt</th>
3097<td class="description">Key/value pairs</td></tr>
b47dab17 3098</tbody></table>
af268786
MS
3099<h4 class="returnvalue">Return Value</h4>
3100<p class="description">Number of key/value pairs</p>
b47dab17 3101<h4 class="discussion">Discussion</h4>
af268786
MS
3102<p class="discussion">This function converts the DNS TXT record encoding of key/value pairs into
3103<code>cups_option_t</code> elements that can be accessed using the <a href="#cupsGetOption"><code>cupsGetOption</code></a>
3104function and freed using the <a href="#cupsFreeOptions"><code>cupsFreeOptions</code></a> function.</p>
3105<h3 class="function"><a id="cupsDNSSDDelete">cupsDNSSDDelete</a></h3>
3106<p class="description">Delete a DNS-SD context and all its requests.</p>
b47dab17 3107<p class="code">
0350eba5 3108<span class="reserved">void</span> cupsDNSSDDelete(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd);</p>
b47dab17
MS
3109<h4 class="parameters">Parameters</h4>
3110<table class="list"><tbody>
af268786
MS
3111<tr><th>dnssd</th>
3112<td class="description">DNS-SD context</td></tr>
b47dab17 3113</tbody></table>
af268786
MS
3114<h3 class="function"><a id="cupsDNSSDGetConfigChanges">cupsDNSSDGetConfigChanges</a></h3>
3115<p class="description">Get the number of host name/network
3116 configuration changes seen.</p>
b47dab17 3117<p class="code">
af268786
MS
3118size_t cupsDNSSDGetConfigChanges(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd);</p>
3119<h4 class="parameters">Parameters</h4>
3120<table class="list"><tbody>
3121<tr><th>dnssd</th>
3122<td class="description">DNS-SD context</td></tr>
3123</tbody></table>
b47dab17 3124<h4 class="returnvalue">Return Value</h4>
af268786 3125<p class="description">Number of host name changes</p>
b47dab17 3126<h4 class="discussion">Discussion</h4>
af268786
MS
3127<p class="discussion">This function returns the number of host name or network configuration
3128changes that have been seen since the context was created. The value can be
3129used to track when local services need to be updated. Registered services
3130will also get a callback with the <code>CUPS_DNSSD_FLAGS_HOST_CHANGE</code> bit set in
3131the &quot;flags&quot; argument for host name changes and/or
3132<code>CUPS_DNSSD_FLAGS_NETWORK_CHANGE</code> for network changes.</p>
3133<h3 class="function"><a id="cupsDNSSDNew">cupsDNSSDNew</a></h3>
3134<p class="description">Create a new DNS-SD context.</p>
b47dab17 3135<p class="code">
0350eba5 3136<a href="#cups_dnssd_t">cups_dnssd_t</a> *cupsDNSSDNew(<a href="#cups_dnssd_error_cb_t">cups_dnssd_error_cb_t</a> error_cb, <span class="reserved">void</span> *cb_data);</p>
b47dab17
MS
3137<h4 class="parameters">Parameters</h4>
3138<table class="list"><tbody>
af268786
MS
3139<tr><th>error_cb</th>
3140<td class="description">Error callback function</td></tr>
3141<tr><th>cb_data</th>
3142<td class="description">Error callback data</td></tr>
b47dab17
MS
3143</tbody></table>
3144<h4 class="returnvalue">Return Value</h4>
af268786 3145<p class="description">DNS-SD context</p>
b47dab17 3146<h4 class="discussion">Discussion</h4>
af268786
MS
3147<p class="discussion">This function creates a new DNS-SD context for browsing, querying, resolving,
3148and/or registering services. Call <a href="#cupsDNSSDDelete"><code>cupsDNSSDDelete</code></a> to stop any pending
3149browses, queries, or resolves, unregister any services, and free the DNS-SD
3150context.</p>
3151<h3 class="function"><a id="cupsDNSSDQueryDelete">cupsDNSSDQueryDelete</a></h3>
3152<p class="description">Cancel and delete a query request.</p>
b47dab17 3153<p class="code">
0350eba5 3154<span class="reserved">void</span> cupsDNSSDQueryDelete(<a href="#cups_dnssd_query_t">cups_dnssd_query_t</a> *query);</p>
b47dab17
MS
3155<h4 class="parameters">Parameters</h4>
3156<table class="list"><tbody>
af268786
MS
3157<tr><th>query</th>
3158<td class="description">Query request</td></tr>
b47dab17 3159</tbody></table>
af268786
MS
3160<h3 class="function"><a id="cupsDNSSDQueryGetContext">cupsDNSSDQueryGetContext</a></h3>
3161<p class="description">Get the DNS-SD context for the query request.</p>
b47dab17 3162<p class="code">
af268786 3163<a href="#cups_dnssd_t">cups_dnssd_t</a> *cupsDNSSDQueryGetContext(<a href="#cups_dnssd_query_t">cups_dnssd_query_t</a> *query);</p>
b47dab17
MS
3164<h4 class="parameters">Parameters</h4>
3165<table class="list"><tbody>
af268786
MS
3166<tr><th>query</th>
3167<td class="description">Query request</td></tr>
b47dab17
MS
3168</tbody></table>
3169<h4 class="returnvalue">Return Value</h4>
af268786
MS
3170<p class="description">DNS-SD context or <code>NULL</code></p>
3171<h3 class="function"><a id="cupsDNSSDQueryNew">cupsDNSSDQueryNew</a></h3>
3172<p class="description">Create a new query request.</p>
b47dab17 3173<p class="code">
0350eba5 3174<a href="#cups_dnssd_query_t">cups_dnssd_query_t</a> *cupsDNSSDQueryNew(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, uint32_t if_index, <span class="reserved">const</span> <span class="reserved">char</span> *fullname, uint16_t rrtype, <a href="#cups_dnssd_query_cb_t">cups_dnssd_query_cb_t</a> query_cb, <span class="reserved">void</span> *cb_data);</p>
b47dab17
MS
3175<h4 class="parameters">Parameters</h4>
3176<table class="list"><tbody>
af268786
MS
3177<tr><th>dnssd</th>
3178<td class="description">DNS-SD context</td></tr>
3179<tr><th>if_index</th>
0350eba5 3180<td class="description">Interface index or <code>CUPS_DNSSD_IF_INDEX_ANY</code> or <code>CUPS_DNSSD_IF_INDEX_LOCAL</code></td></tr>
af268786
MS
3181<tr><th>fullname</th>
3182<td class="description">Full DNS name including types and domain</td></tr>
3183<tr><th>rrtype</th>
3184<td class="description">Record type to query (<code>CUPS_DNSSD_RRTYPE_TXT</code>, etc.)</td></tr>
3185<tr><th>query_cb</th>
3186<td class="description">Query callback function</td></tr>
3187<tr><th>cb_data</th>
3188<td class="description">Query callback data</td></tr>
b47dab17
MS
3189</tbody></table>
3190<h4 class="returnvalue">Return Value</h4>
af268786 3191<p class="description">Query request or <code>NULL</code> on error</p>
b47dab17 3192<h4 class="discussion">Discussion</h4>
af268786
MS
3193<p class="discussion">This function creates a new DNS-SD query request for the specified full
3194service name and DNS record type. The &quot;fullname&quot; parameter specifies the
3195full DNS name of the service (instance name, type, and domain) being queried.
3196Responses to the query are reported using the required query callback
3197function with the &quot;flags&quot; argument set to <code>CUPS_DNSSD_FLAGS_NONE</code> on success
3198or <code>CUPS_DNSSD_FLAGS_ERROR</code> on error:
b47dab17 3199
af268786
MS
3200<pre>
3201void
3202query_cb(
3203 cups_dnssd_query_t *query,
3204 void *cb_data,
3205 cups_dnssd_flags_t flags,
3206 uint32_t if_index,
3207 const char *fullname,
3208 uint16_t rrtype,
3209 const void *qdata,
3210 uint16_t qlen)
3211{
3212 // Process query record
3213}
3214</pre>
b47dab17 3215</p>
af268786
MS
3216<h3 class="function"><a id="cupsDNSSDResolveDelete">cupsDNSSDResolveDelete</a></h3>
3217<p class="description">Cancel and free a resolve request.</p>
b47dab17 3218<p class="code">
0350eba5 3219<span class="reserved">void</span> cupsDNSSDResolveDelete(<a href="#cups_dnssd_resolve_t">cups_dnssd_resolve_t</a> *res);</p>
b47dab17
MS
3220<h4 class="parameters">Parameters</h4>
3221<table class="list"><tbody>
af268786
MS
3222<tr><th>res</th>
3223<td class="description">Resolve request</td></tr>
b47dab17 3224</tbody></table>
af268786
MS
3225<h3 class="function"><a id="cupsDNSSDResolveGetContext">cupsDNSSDResolveGetContext</a></h3>
3226<p class="description">Get the DNS-SD context for the resolve request.</p>
b47dab17 3227<p class="code">
af268786 3228<a href="#cups_dnssd_t">cups_dnssd_t</a> *cupsDNSSDResolveGetContext(<a href="#cups_dnssd_resolve_t">cups_dnssd_resolve_t</a> *resolve);</p>
b47dab17
MS
3229<h4 class="parameters">Parameters</h4>
3230<table class="list"><tbody>
af268786
MS
3231<tr><th>resolve</th>
3232<td class="description">Resolve request</td></tr>
b47dab17
MS
3233</tbody></table>
3234<h4 class="returnvalue">Return Value</h4>
af268786
MS
3235<p class="description">DNS-SD context or <code>NULL</code></p>
3236<h3 class="function"><a id="cupsDNSSDResolveNew">cupsDNSSDResolveNew</a></h3>
3237<p class="description">Create a new DNS-SD resolve request.</p>
b47dab17 3238<p class="code">
0350eba5 3239<a href="#cups_dnssd_resolve_t">cups_dnssd_resolve_t</a> *cupsDNSSDResolveNew(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, uint32_t if_index, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *type, <span class="reserved">const</span> <span class="reserved">char</span> *domain, <a href="#cups_dnssd_resolve_cb_t">cups_dnssd_resolve_cb_t</a> resolve_cb, <span class="reserved">void</span> *cb_data);</p>
b47dab17
MS
3240<h4 class="parameters">Parameters</h4>
3241<table class="list"><tbody>
af268786
MS
3242<tr><th>dnssd</th>
3243<td class="description">DNS-SD context</td></tr>
3244<tr><th>if_index</th>
0350eba5 3245<td class="description">Interface index or <code>CUPS_DNSSD_IF_INDEX_ANY</code> or <code>CUPS_DNSSD_IF_INDEX_LOCAL</code></td></tr>
af268786
MS
3246<tr><th>name</th>
3247<td class="description">Service name</td></tr>
3248<tr><th>type</th>
3249<td class="description">Service type</td></tr>
3250<tr><th>domain</th>
3251<td class="description">Domain name or <code>NULL</code> for default</td></tr>
3252<tr><th>resolve_cb</th>
3253<td class="description">Resolve callback function</td></tr>
3254<tr><th>cb_data</th>
3255<td class="description">Resolve callback data</td></tr>
3256</tbody></table>
3257<h4 class="returnvalue">Return Value</h4>
3258<p class="description">Resolve request or <code>NULL</code> on error</p>
3259<h4 class="discussion">Discussion</h4>
3260<p class="discussion">This function creates a new DNS-SD resolver for the specified instance name,
3261service type, and optional domain and interface index. Resikved services
3262are reported using the required resolve callback function, with the &quot;flags&quot;
3263argument set to <code>CUPS_DNSSD_FLAGS_NONE</code> on success or
3264<code>CUPS_DNSSD_FLAGS_ERROR</code> on error:
3265
3266<pre>
3267void
3268resolve_cb(
3269 cups_dnssd_resolve_t *resolve,
3270 void *cb_data,
3271 cups_dnssd_flags_t flags,
3272 uint32_t if_index,
3273 const char *fullname,
3274 const char *host,
3275 uint16_t port,
05d62fc2 3276 int num_txt,
af268786
MS
3277 cups_option_t *txt)
3278{
3279 // Process resolved service
3280}
3281</pre>
3282</p>
3283<h3 class="function"><a id="cupsDNSSDSeparateFullName">cupsDNSSDSeparateFullName</a></h3>
3284<p class="description">Separate a full service name into an instance
3285 name, registration type, and domain.</p>
3286<p class="code">
0350eba5 3287<span class="reserved">bool</span> cupsDNSSDSeparateFullName(<span class="reserved">const</span> <span class="reserved">char</span> *fullname, <span class="reserved">char</span> *name, size_t namesize, <span class="reserved">char</span> *type, size_t typesize, <span class="reserved">char</span> *domain, size_t domainsize);</p>
af268786
MS
3288<h4 class="parameters">Parameters</h4>
3289<table class="list"><tbody>
3290<tr><th>fullname</th>
3291<td class="description">Full service name</td></tr>
3292<tr><th>name</th>
3293<td class="description">Instance name buffer</td></tr>
3294<tr><th>namesize</th>
3295<td class="description">Size of instance name buffer</td></tr>
3296<tr><th>type</th>
3297<td class="description">Registration type buffer</td></tr>
3298<tr><th>typesize</th>
3299<td class="description">Size of registration type buffer</td></tr>
3300<tr><th>domain</th>
3301<td class="description">Domain name buffer</td></tr>
3302<tr><th>domainsize</th>
3303<td class="description">Size of domain name buffer</td></tr>
b47dab17
MS
3304</tbody></table>
3305<h4 class="returnvalue">Return Value</h4>
af268786
MS
3306<p class="description"><code>true</code> on success, <code>false</code> on error</p>
3307<h4 class="discussion">Discussion</h4>
3308<p class="discussion">This function separates a full service name such as
3309&quot;Example032Name._ipp._tcp.local.&quot;) into its instance name (&quot;Example Name&quot;),
3310registration type (&quot;_ipp._tcp&quot;), and domain (&quot;local.&quot;).</p>
3311<h3 class="function"><a id="cupsDNSSDServiceAdd">cupsDNSSDServiceAdd</a></h3>
3312<p class="description">Add a service instance.</p>
b47dab17 3313<p class="code">
0350eba5 3314<span class="reserved">bool</span> cupsDNSSDServiceAdd(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service, <span class="reserved">const</span> <span class="reserved">char</span> *types, <span class="reserved">const</span> <span class="reserved">char</span> *domain, <span class="reserved">const</span> <span class="reserved">char</span> *host, uint16_t port, <span class="reserved">int</span> num_txt, <a href="#cups_option_t">cups_option_t</a> *txt);</p>
b47dab17
MS
3315<h4 class="parameters">Parameters</h4>
3316<table class="list"><tbody>
af268786
MS
3317<tr><th>service</th>
3318<td class="description">Service</td></tr>
3319<tr><th>types</th>
3320<td class="description">Service types</td></tr>
3321<tr><th>domain</th>
3322<td class="description">Domain name or <code>NULL</code> for default</td></tr>
3323<tr><th>host</th>
3324<td class="description">Host name or <code>NULL</code> for default</td></tr>
3325<tr><th>port</th>
3326<td class="description">Port number or <code>0</code> for none</td></tr>
3327<tr><th>num_txt</th>
3328<td class="description">Number of TXT record values</td></tr>
3329<tr><th>txt</th>
3330<td class="description">TXT record values</td></tr>
b47dab17
MS
3331</tbody></table>
3332<h4 class="returnvalue">Return Value</h4>
af268786 3333<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
b47dab17 3334<h4 class="discussion">Discussion</h4>
af268786
MS
3335<p class="discussion">This function adds a service instance for the specified service types,
3336domain, host, and port. The &quot;types&quot; argument can be a single service type
3337(&quot;_ipp._tcp&quot;) or a service type and comma-delimited list of sub-types
3338(&quot;_ipp._tcp,_print,_universal&quot;).<br>
3339<br>
3340Call the <a href="#cupsDNSSDServicePublish"><code>cupsDNSSDServicePublish</code></a> function after all service instances
3341have been added.</p>
3342<h3 class="function"><a id="cupsDNSSDServiceDelete">cupsDNSSDServiceDelete</a></h3>
3343<p class="description">Cancel and free a service registration.</p>
b47dab17 3344<p class="code">
0350eba5 3345<span class="reserved">void</span> cupsDNSSDServiceDelete(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service);</p>
b47dab17
MS
3346<h4 class="parameters">Parameters</h4>
3347<table class="list"><tbody>
af268786
MS
3348<tr><th>service</th>
3349<td class="description">Service</td></tr>
b47dab17 3350</tbody></table>
af268786
MS
3351<h3 class="function"><a id="cupsDNSSDServiceGetContext">cupsDNSSDServiceGetContext</a></h3>
3352<p class="description">Get the DNS-SD context for the service
3353 registration.</p>
b47dab17 3354<p class="code">
af268786 3355<a href="#cups_dnssd_t">cups_dnssd_t</a> *cupsDNSSDServiceGetContext(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service);</p>
b47dab17
MS
3356<h4 class="parameters">Parameters</h4>
3357<table class="list"><tbody>
af268786
MS
3358<tr><th>service</th>
3359<td class="description">Service registration</td></tr>
b47dab17
MS
3360</tbody></table>
3361<h4 class="returnvalue">Return Value</h4>
af268786
MS
3362<p class="description">DNS-SD context or <code>NULL</code></p>
3363<h3 class="function"><a id="cupsDNSSDServiceGetName">cupsDNSSDServiceGetName</a></h3>
3364<p class="description">Get the service instance name for the service registration.</p>
b47dab17 3365<p class="code">
0350eba5 3366<span class="reserved">const</span> <span class="reserved">char</span> *cupsDNSSDServiceGetName(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service);</p>
b47dab17
MS
3367<h4 class="parameters">Parameters</h4>
3368<table class="list"><tbody>
af268786
MS
3369<tr><th>service</th>
3370<td class="description">Service registration</td></tr>
b47dab17
MS
3371</tbody></table>
3372<h4 class="returnvalue">Return Value</h4>
af268786
MS
3373<p class="description">Service instance name</p>
3374<h3 class="function"><a id="cupsDNSSDServiceNew">cupsDNSSDServiceNew</a></h3>
3375<p class="description">Create a new named service.</p>
b47dab17 3376<p class="code">
0350eba5 3377<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *cupsDNSSDServiceNew(<a href="#cups_dnssd_t">cups_dnssd_t</a> *dnssd, uint32_t if_index, <span class="reserved">const</span> <span class="reserved">char</span> *name, <a href="#cups_dnssd_service_cb_t">cups_dnssd_service_cb_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
b47dab17
MS
3378<h4 class="parameters">Parameters</h4>
3379<table class="list"><tbody>
af268786
MS
3380<tr><th>dnssd</th>
3381<td class="description">DNS-SD context</td></tr>
3382<tr><th>if_index</th>
0350eba5 3383<td class="description">Interface index, <code>CUPS_DNSSD_IF_INDEX_ANY</code>, or <code>CUPS_DNSSD_IF_INDEX_LOCAL</code></td></tr>
af268786
MS
3384<tr><th>name</th>
3385<td class="description">Name of service</td></tr>
3386<tr><th>cb</th>
3387<td class="description">Service registration callback function</td></tr>
3388<tr><th>cb_data</th>
3389<td class="description">Service registration callback data</td></tr>
b47dab17
MS
3390</tbody></table>
3391<h4 class="returnvalue">Return Value</h4>
af268786 3392<p class="description">Service or <code>NULL</code> on error</p>
b47dab17 3393<h4 class="discussion">Discussion</h4>
af268786
MS
3394<p class="discussion">This function creates a new DNS-SD service registration for the given service
3395instance name and interface. Specific services using the name are added
3396using the <a href="#cupsDNSSDServiceAdd"><code>cupsDNSSDServiceAdd</code></a> function.<br>
b47dab17 3397<br>
af268786
MS
3398The required service callback is called for select events, with the &quot;flags&quot;
3399argument set to <code>CUPS_DNSSD_FLAGS_NONE</code> for a successful registration,
3400<code>CUPS_DNSSD_FLAGS_COLLISION</code> when there is a name collision, or
3401<code>CUPS_DNSSD_FLAGS_ERROR</code> when there is a problem completing the service
3402registration.</p>
3403<h3 class="function"><a id="cupsDNSSDServicePublish">cupsDNSSDServicePublish</a></h3>
3404<p class="description">Publish a service.</p>
b47dab17 3405<p class="code">
0350eba5 3406<span class="reserved">bool</span> cupsDNSSDServicePublish(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service);</p>
b47dab17
MS
3407<h4 class="parameters">Parameters</h4>
3408<table class="list"><tbody>
af268786
MS
3409<tr><th>service</th>
3410<td class="description">Service</td></tr>
b47dab17
MS
3411</tbody></table>
3412<h4 class="returnvalue">Return Value</h4>
af268786 3413<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
b47dab17 3414<h4 class="discussion">Discussion</h4>
af268786
MS
3415<p class="discussion">This function publishes the DNS-SD services added using the
3416<a href="#cupsDNSSDServiceAdd"><code>cupsDNSSDServiceAdd</code></a> function.</p>
3417<h3 class="function"><a id="cupsDNSSDServiceSetLocation">cupsDNSSDServiceSetLocation</a></h3>
3418<p class="description">Set the geolocation (LOC record) of a
3419 service.</p>
b47dab17 3420<p class="code">
0350eba5 3421<span class="reserved">bool</span> cupsDNSSDServiceSetLocation(<a href="#cups_dnssd_service_t">cups_dnssd_service_t</a> *service, <span class="reserved">const</span> <span class="reserved">char</span> *geo_uri);</p>
b47dab17
MS
3422<h4 class="parameters">Parameters</h4>
3423<table class="list"><tbody>
af268786
MS
3424<tr><th>service</th>
3425<td class="description">Service</td></tr>
3426<tr><th>geo_uri</th>
3427<td class="description">Geolocation as a 'geo:' URI</td></tr>
b47dab17
MS
3428</tbody></table>
3429<h4 class="returnvalue">Return Value</h4>
af268786
MS
3430<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
3431<h4 class="discussion">Discussion</h4>
3432<p class="discussion">This function sets the geolocation of a service using a 'geo:' URI (RFC 5870)
3433of the form
3434'geo:LATITUDE,LONGITUDE[,ALTITUDE][;crs=CRSLABEL][;u=UNCERTAINTY]'. The
3435specified coordinates and uncertainty are converted into a DNS LOC record
3436for the service name label. Only the &quot;wgs84&quot; CRSLABEL string is supported.<br>
3437<br>
3438You must call this function prior to <a href="#cupsDNSSDServiceAdd"><code>cupsDNSSDServiceAdd</code></a>.</p>
b6008d6b 3439<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsDirClose">cupsDirClose</a></h3>
af268786 3440<p class="description">Close a directory.</p>
b47dab17 3441<p class="code">
0350eba5 3442<span class="reserved">void</span> cupsDirClose(<a href="#cups_dir_t">cups_dir_t</a> *dp);</p>
b47dab17
MS
3443<h4 class="parameters">Parameters</h4>
3444<table class="list"><tbody>
af268786
MS
3445<tr><th>dp</th>
3446<td class="description">Directory pointer</td></tr>
b47dab17 3447</tbody></table>
b6008d6b 3448<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsDirOpen">cupsDirOpen</a></h3>
af268786 3449<p class="description">Open a directory.</p>
b47dab17 3450<p class="code">
0350eba5 3451<a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen(<span class="reserved">const</span> <span class="reserved">char</span> *directory);</p>
b47dab17
MS
3452<h4 class="parameters">Parameters</h4>
3453<table class="list"><tbody>
af268786
MS
3454<tr><th>directory</th>
3455<td class="description">Directory name</td></tr>
b47dab17
MS
3456</tbody></table>
3457<h4 class="returnvalue">Return Value</h4>
af268786 3458<p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p>
b6008d6b 3459<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsDirRead">cupsDirRead</a></h3>
af268786 3460<p class="description">Read the next directory entry.</p>
b47dab17 3461<p class="code">
af268786 3462<a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead(<a href="#cups_dir_t">cups_dir_t</a> *dp);</p>
b47dab17
MS
3463<h4 class="parameters">Parameters</h4>
3464<table class="list"><tbody>
af268786
MS
3465<tr><th>dp</th>
3466<td class="description">Directory pointer</td></tr>
3467</tbody></table>
3468<h4 class="returnvalue">Return Value</h4>
3469<p class="description">Directory entry or <code>NULL</code> when there are no more</p>
b6008d6b 3470<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsDirRewind">cupsDirRewind</a></h3>
af268786
MS
3471<p class="description">Rewind to the start of the directory.</p>
3472<p class="code">
0350eba5 3473<span class="reserved">void</span> cupsDirRewind(<a href="#cups_dir_t">cups_dir_t</a> *dp);</p>
af268786
MS
3474<h4 class="parameters">Parameters</h4>
3475<table class="list"><tbody>
3476<tr><th>dp</th>
3477<td class="description">Directory pointer</td></tr>
3478</tbody></table>
b6008d6b 3479<h3 class="function"><span class="info">&#160;CUPS 1.1.20&#160;</span><a id="cupsDoAuthentication">cupsDoAuthentication</a></h3>
af268786
MS
3480<p class="description">Authenticate a request.</p>
3481<p class="code">
0350eba5 3482<span class="reserved">int</span> cupsDoAuthentication(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource);</p>
af268786
MS
3483<h4 class="parameters">Parameters</h4>
3484<table class="list"><tbody>
3485<tr><th>http</th>
3486<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
3487<tr><th>method</th>
3488<td class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</td></tr>
3489<tr><th>resource</th>
3490<td class="description">Resource path</td></tr>
3491</tbody></table>
3492<h4 class="returnvalue">Return Value</h4>
3493<p class="description">0 on success, -1 on error</p>
3494<h4 class="discussion">Discussion</h4>
3495<p class="discussion">This function should be called in response to a <code>HTTP_STATUS_UNAUTHORIZED</code>
3496status, prior to resubmitting your request.
3497
3498</p>
3499<h3 class="function"><a id="cupsDoFileRequest">cupsDoFileRequest</a></h3>
3500<p class="description">Do an IPP request with a file.</p>
3501<p class="code">
0350eba5 3502<a href="#ipp_t">ipp_t</a> *cupsDoFileRequest(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *request, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">const</span> <span class="reserved">char</span> *filename);</p>
af268786
MS
3503<h4 class="parameters">Parameters</h4>
3504<table class="list"><tbody>
3505<tr><th>http</th>
3506<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
3507<tr><th>request</th>
3508<td class="description">IPP request</td></tr>
3509<tr><th>resource</th>
3510<td class="description">HTTP resource for POST</td></tr>
3511<tr><th>filename</th>
3512<td class="description">File to send or <code>NULL</code> for none</td></tr>
3513</tbody></table>
3514<h4 class="returnvalue">Return Value</h4>
3515<p class="description">Response data</p>
3516<h4 class="discussion">Discussion</h4>
3517<p class="discussion">This function sends the IPP request and attached file to the specified
3518server, retrying and authenticating as necessary. The request is freed with
3519<a href="#ippDelete"><code>ippDelete</code></a>.</p>
b6008d6b 3520<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="cupsDoIORequest">cupsDoIORequest</a></h3>
af268786
MS
3521<p class="description">Do an IPP request with file descriptors.</p>
3522<p class="code">
0350eba5 3523<a href="#ipp_t">ipp_t</a> *cupsDoIORequest(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *request, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">int</span> infile, <span class="reserved">int</span> outfile);</p>
af268786
MS
3524<h4 class="parameters">Parameters</h4>
3525<table class="list"><tbody>
3526<tr><th>http</th>
3527<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
3528<tr><th>request</th>
3529<td class="description">IPP request</td></tr>
3530<tr><th>resource</th>
3531<td class="description">HTTP resource for POST</td></tr>
3532<tr><th>infile</th>
3533<td class="description">File to read from or -1 for none</td></tr>
3534<tr><th>outfile</th>
3535<td class="description">File to write to or -1 for none</td></tr>
3536</tbody></table>
3537<h4 class="returnvalue">Return Value</h4>
3538<p class="description">Response data</p>
3539<h4 class="discussion">Discussion</h4>
3540<p class="discussion">This function sends the IPP request with the optional input file &quot;infile&quot; to
3541the specified server, retrying and authenticating as necessary. The request
3542is freed with <a href="#ippDelete"><code>ippDelete</code></a>.<br>
3543<br>
3544If &quot;infile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
3545all of the data from the file after the IPP request message.<br>
3546<br>
3547If &quot;outfile&quot; is a valid file descriptor, <code>cupsDoIORequest</code> copies
3548all of the data after the IPP response message to the file.
3549
3550</p>
3551<h3 class="function"><a id="cupsDoRequest">cupsDoRequest</a></h3>
3552<p class="description">Do an IPP request.</p>
3553<p class="code">
0350eba5 3554<a href="#ipp_t">ipp_t</a> *cupsDoRequest(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *request, <span class="reserved">const</span> <span class="reserved">char</span> *resource);</p>
af268786
MS
3555<h4 class="parameters">Parameters</h4>
3556<table class="list"><tbody>
3557<tr><th>http</th>
3558<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
3559<tr><th>request</th>
3560<td class="description">IPP request</td></tr>
3561<tr><th>resource</th>
3562<td class="description">HTTP resource for POST</td></tr>
3563</tbody></table>
3564<h4 class="returnvalue">Return Value</h4>
3565<p class="description">Response data</p>
3566<h4 class="discussion">Discussion</h4>
3567<p class="discussion">This function sends the IPP request to the specified server, retrying
3568and authenticating as necessary. The request is freed with <a href="#ippDelete"><code>ippDelete</code></a>.</p>
b6008d6b 3569<h3 class="function"><span class="info">&#160;CUPS 2.3&#160;</span><a id="cupsEncodeOption">cupsEncodeOption</a></h3>
af268786
MS
3570<p class="description">Encode a single option into an IPP attribute.</p>
3571<p class="code">
0350eba5 3572<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsEncodeOption(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
3573<h4 class="parameters">Parameters</h4>
3574<table class="list"><tbody>
3575<tr><th>ipp</th>
3576<td class="description">IPP request/response</td></tr>
3577<tr><th>group_tag</th>
3578<td class="description">Attribute group</td></tr>
3579<tr><th>name</th>
3580<td class="description">Option name</td></tr>
b47dab17 3581<tr><th>value</th>
af268786 3582<td class="description">Option string value</td></tr>
b47dab17
MS
3583</tbody></table>
3584<h4 class="returnvalue">Return Value</h4>
af268786
MS
3585<p class="description">New attribute or <code>NULL</code> on error</p>
3586<h3 class="function"><a id="cupsEncodeOptions">cupsEncodeOptions</a></h3>
3587<p class="description">Encode printer options into IPP attributes.</p>
3588<p class="code">
0350eba5 3589<span class="reserved">void</span> cupsEncodeOptions(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
af268786
MS
3590<h4 class="parameters">Parameters</h4>
3591<table class="list"><tbody>
3592<tr><th>ipp</th>
3593<td class="description">IPP request/response</td></tr>
3594<tr><th>num_options</th>
3595<td class="description">Number of options</td></tr>
3596<tr><th>options</th>
3597<td class="description">Options</td></tr>
3598</tbody></table>
b47dab17 3599<h4 class="discussion">Discussion</h4>
af268786
MS
3600<p class="discussion">This function adds operation, job, and then subscription attributes,
3601in that order. Use the <a href="#cupsEncodeOptions2"><code>cupsEncodeOptions2</code></a> function to add attributes
3602for a single group.</p>
b6008d6b 3603<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsEncodeOptions2">cupsEncodeOptions2</a></h3>
af268786
MS
3604<p class="description">Encode printer options into IPP attributes for a group.</p>
3605<p class="code">
0350eba5 3606<span class="reserved">void</span> cupsEncodeOptions2(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options, ipp_tag_t group_tag);</p>
af268786
MS
3607<h4 class="parameters">Parameters</h4>
3608<table class="list"><tbody>
3609<tr><th>ipp</th>
3610<td class="description">IPP request/response</td></tr>
3611<tr><th>num_options</th>
3612<td class="description">Number of options</td></tr>
3613<tr><th>options</th>
3614<td class="description">Options</td></tr>
3615<tr><th>group_tag</th>
3616<td class="description">Group to encode</td></tr>
3617</tbody></table>
3618<h4 class="discussion">Discussion</h4>
3619<p class="discussion">This function only adds attributes for a single group. Call this
3620function multiple times for each group, or use <a href="#cupsEncodeOptions"><code>cupsEncodeOptions</code></a>
3621to add the standard groups.
3622
3623</p>
3624<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsEncryption">cupsEncryption</a></h3>
3625<p class="description">Get the current encryption settings.</p>
3626<p class="code">
0350eba5 3627<a href="#http_encryption_t">http_encryption_t</a> cupsEncryption(<span class="reserved">void</span>);</p>
af268786
MS
3628<h4 class="returnvalue">Return Value</h4>
3629<p class="description">Encryption settings</p>
b6008d6b 3630<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsEnumDests">cupsEnumDests</a></h3>
af268786
MS
3631<p class="description">Enumerate available destinations with a callback function.</p>
3632<p class="code">
0350eba5 3633<span class="reserved">int</span> cupsEnumDests(<span class="reserved">unsigned</span> flags, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel, <a href="#cups_ptype_t">cups_ptype_t</a> type, <a href="#cups_ptype_t">cups_ptype_t</a> mask, <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
af268786
MS
3634<h4 class="parameters">Parameters</h4>
3635<table class="list"><tbody>
3636<tr><th>flags</th>
3637<td class="description">Enumeration flags</td></tr>
3638<tr><th>msec</th>
3639<td class="description">Timeout in milliseconds, -1 for indefinite</td></tr>
3640<tr><th>cancel</th>
3641<td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
3642<tr><th>type</th>
3643<td class="description">Printer type bits</td></tr>
3644<tr><th>mask</th>
3645<td class="description">Mask for printer type bits</td></tr>
3646<tr><th>cb</th>
3647<td class="description">Callback function</td></tr>
3648<tr><th>user_data</th>
3649<td class="description">User data</td></tr>
3650</tbody></table>
3651<h4 class="returnvalue">Return Value</h4>
3652<p class="description">1 on success, 0 on failure</p>
3653<h4 class="discussion">Discussion</h4>
3654<p class="discussion">Destinations are enumerated from one or more sources. The callback function
3655receives the <code>user_data</code> pointer and the destination pointer which can
3656be used as input to the <a href="#cupsCopyDest"><code>cupsCopyDest</code></a> function. The function must
3657return 1 to continue enumeration or 0 to stop.<br>
3658<br>
3659The <code>type</code> and <code>mask</code> arguments allow the caller to filter the
3660destinations that are enumerated. Passing 0 for both will enumerate all
3661printers. The constant <code>CUPS_PTYPE_DISCOVERED</code> is used to filter on
3662destinations that are available but have not yet been added locally.<br>
3663<br>
3664Enumeration happens on the current thread and does not return until all
3665destinations have been enumerated or the callback function returns 0.<br>
3666<br>
3667Note: The callback function will likely receive multiple updates for the same
3668destinations - it is up to the caller to suppress any duplicate destinations.
3669
3670</p>
b6008d6b 3671<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileClose">cupsFileClose</a></h3>
af268786
MS
3672<p class="description">Close a CUPS file.</p>
3673<p class="code">
0350eba5 3674<span class="reserved">int</span> cupsFileClose(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3675<h4 class="parameters">Parameters</h4>
3676<table class="list"><tbody>
3677<tr><th>fp</th>
3678<td class="description">CUPS file</td></tr>
3679</tbody></table>
3680<h4 class="returnvalue">Return Value</h4>
3681<p class="description">0 on success, -1 on error</p>
b6008d6b 3682<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileEOF">cupsFileEOF</a></h3>
af268786
MS
3683<p class="description">Return the end-of-file status.</p>
3684<p class="code">
0350eba5 3685<span class="reserved">int</span> cupsFileEOF(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3686<h4 class="parameters">Parameters</h4>
3687<table class="list"><tbody>
3688<tr><th>fp</th>
3689<td class="description">CUPS file</td></tr>
3690</tbody></table>
3691<h4 class="returnvalue">Return Value</h4>
3692<p class="description">1 on end of file, 0 otherwise</p>
b6008d6b 3693<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileFind">cupsFileFind</a></h3>
af268786
MS
3694<p class="description">Find a file using the specified path.</p>
3695<p class="code">
0350eba5 3696<span class="reserved">const</span> <span class="reserved">char</span> *cupsFileFind(<span class="reserved">const</span> <span class="reserved">char</span> *filename, <span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">int</span> executable, <span class="reserved">char</span> *buffer, <span class="reserved">int</span> bufsize);</p>
af268786
MS
3697<h4 class="parameters">Parameters</h4>
3698<table class="list"><tbody>
3699<tr><th>filename</th>
3700<td class="description">File to find</td></tr>
3701<tr><th>path</th>
3702<td class="description">Colon/semicolon-separated path</td></tr>
3703<tr><th>executable</th>
3704<td class="description">1 = executable files, 0 = any file/dir</td></tr>
3705<tr><th>buffer</th>
3706<td class="description">Filename buffer</td></tr>
3707<tr><th>bufsize</th>
3708<td class="description">Size of filename buffer</td></tr>
3709</tbody></table>
3710<h4 class="returnvalue">Return Value</h4>
3711<p class="description">Full path to file or <code>NULL</code> if not found</p>
3712<h4 class="discussion">Discussion</h4>
3713<p class="discussion">This function allows the paths in the path string to be separated by
3714colons (UNIX standard) or semicolons (Windows standard) and stores the
3715result in the buffer supplied. If the file cannot be found in any of
3716the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only
3717matches the current directory.
3718
3719</p>
b6008d6b 3720<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileFlush">cupsFileFlush</a></h3>
af268786
MS
3721<p class="description">Flush pending output.</p>
3722<p class="code">
0350eba5 3723<span class="reserved">int</span> cupsFileFlush(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3724<h4 class="parameters">Parameters</h4>
3725<table class="list"><tbody>
3726<tr><th>fp</th>
3727<td class="description">CUPS file</td></tr>
3728</tbody></table>
3729<h4 class="returnvalue">Return Value</h4>
3730<p class="description">0 on success, -1 on error</p>
b6008d6b 3731<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileGetChar">cupsFileGetChar</a></h3>
af268786
MS
3732<p class="description">Get a single character from a file.</p>
3733<p class="code">
0350eba5 3734<span class="reserved">int</span> cupsFileGetChar(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3735<h4 class="parameters">Parameters</h4>
3736<table class="list"><tbody>
3737<tr><th>fp</th>
3738<td class="description">CUPS file</td></tr>
3739</tbody></table>
3740<h4 class="returnvalue">Return Value</h4>
3741<p class="description">Character or -1 on end of file</p>
b6008d6b 3742<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileGetConf">cupsFileGetConf</a></h3>
af268786
MS
3743<p class="description">Get a line from a configuration file.</p>
3744<p class="code">
0350eba5 3745<span class="reserved">char</span> *cupsFileGetConf(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">char</span> *buf, size_t buflen, <span class="reserved">char</span> **value, <span class="reserved">int</span> *linenum);</p>
af268786
MS
3746<h4 class="parameters">Parameters</h4>
3747<table class="list"><tbody>
3748<tr><th>fp</th>
3749<td class="description">CUPS file</td></tr>
3750<tr><th>buf</th>
3751<td class="description">String buffer</td></tr>
3752<tr><th>buflen</th>
3753<td class="description">Size of string buffer</td></tr>
3754<tr><th>value</th>
3755<td class="description">Pointer to value</td></tr>
3756<tr><th>linenum</th>
3757<td class="description">Current line number</td></tr>
3758</tbody></table>
3759<h4 class="returnvalue">Return Value</h4>
3760<p class="description">Line read or <code>NULL</code> on end of file or error</p>
b6008d6b 3761<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileGetLine">cupsFileGetLine</a></h3>
af268786
MS
3762<p class="description">Get a CR and/or LF-terminated line that may
3763 contain binary data.</p>
3764<p class="code">
0350eba5 3765size_t cupsFileGetLine(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">char</span> *buf, size_t buflen);</p>
af268786
MS
3766<h4 class="parameters">Parameters</h4>
3767<table class="list"><tbody>
3768<tr><th>fp</th>
3769<td class="description">File to read from</td></tr>
3770<tr><th>buf</th>
3771<td class="description">Buffer</td></tr>
3772<tr><th>buflen</th>
3773<td class="description">Size of buffer</td></tr>
3774</tbody></table>
3775<h4 class="returnvalue">Return Value</h4>
3776<p class="description">Number of bytes on line or 0 on end of file</p>
3777<h4 class="discussion">Discussion</h4>
3778<p class="discussion">This function differs from <a href="#cupsFileGets"><code>cupsFileGets</code></a> in that the trailing CR
3779and LF are preserved, as is any binary data on the line. The buffer is
3780nul-terminated, however you should use the returned length to determine
3781the number of bytes on the line.
3782
3783</p>
b6008d6b 3784<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileGets">cupsFileGets</a></h3>
af268786
MS
3785<p class="description">Get a CR and/or LF-terminated line.</p>
3786<p class="code">
0350eba5 3787<span class="reserved">char</span> *cupsFileGets(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">char</span> *buf, size_t buflen);</p>
af268786
MS
3788<h4 class="parameters">Parameters</h4>
3789<table class="list"><tbody>
3790<tr><th>fp</th>
3791<td class="description">CUPS file</td></tr>
3792<tr><th>buf</th>
3793<td class="description">String buffer</td></tr>
3794<tr><th>buflen</th>
3795<td class="description">Size of string buffer</td></tr>
3796</tbody></table>
3797<h4 class="returnvalue">Return Value</h4>
3798<p class="description">Line read or <code>NULL</code> on end of file or error</p>
3799<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsFileIsCompressed">cupsFileIsCompressed</a></h3>
3800<p class="description">Return whether a file is compressed.</p>
3801<p class="code">
0350eba5 3802<span class="reserved">bool</span> cupsFileIsCompressed(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3803<h4 class="parameters">Parameters</h4>
3804<table class="list"><tbody>
3805<tr><th>fp</th>
3806<td class="description">CUPS file</td></tr>
3807</tbody></table>
3808<h4 class="returnvalue">Return Value</h4>
3809<p class="description"><code>true</code> if file is compressed, <code>false</code> otherwise</p>
b6008d6b 3810<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileLock">cupsFileLock</a></h3>
af268786
MS
3811<p class="description">Temporarily lock access to a file.</p>
3812<p class="code">
0350eba5 3813<span class="reserved">int</span> cupsFileLock(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">int</span> block);</p>
af268786
MS
3814<h4 class="parameters">Parameters</h4>
3815<table class="list"><tbody>
3816<tr><th>fp</th>
3817<td class="description">CUPS file</td></tr>
3818<tr><th>block</th>
3819<td class="description">1 to wait for the lock, 0 to fail right away</td></tr>
3820</tbody></table>
3821<h4 class="returnvalue">Return Value</h4>
3822<p class="description">0 on success, -1 on error</p>
b6008d6b 3823<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileNumber">cupsFileNumber</a></h3>
af268786
MS
3824<p class="description">Return the file descriptor associated with a CUPS file.</p>
3825<p class="code">
0350eba5 3826<span class="reserved">int</span> cupsFileNumber(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3827<h4 class="parameters">Parameters</h4>
3828<table class="list"><tbody>
3829<tr><th>fp</th>
3830<td class="description">CUPS file</td></tr>
3831</tbody></table>
3832<h4 class="returnvalue">Return Value</h4>
3833<p class="description">File descriptor</p>
b6008d6b 3834<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileOpen">cupsFileOpen</a></h3>
af268786
MS
3835<p class="description">Open a CUPS file.</p>
3836<p class="code">
0350eba5 3837<a href="#cups_file_t">cups_file_t</a> *cupsFileOpen(<span class="reserved">const</span> <span class="reserved">char</span> *filename, <span class="reserved">const</span> <span class="reserved">char</span> *mode);</p>
af268786
MS
3838<h4 class="parameters">Parameters</h4>
3839<table class="list"><tbody>
3840<tr><th>filename</th>
3841<td class="description">Name of file</td></tr>
3842<tr><th>mode</th>
3843<td class="description">Open mode</td></tr>
3844</tbody></table>
3845<h4 class="returnvalue">Return Value</h4>
3846<p class="description">CUPS file or <code>NULL</code> if the file or socket cannot be opened</p>
3847<h4 class="discussion">Discussion</h4>
3848<p class="discussion">The &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, overwriting any
3849existing file, &quot;a&quot; to append to an existing file or create a new file,
3850or &quot;s&quot; to open a socket connection.<br>
3851<br>
3852When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
3853supplied which enables Flate compression of the file. Compression is
3854not supported for the &quot;a&quot; (append) mode.<br>
3855<br>
0350eba5
MS
3856When opening for writing (&quot;w&quot;) or append (&quot;a&quot;), an optional 'm###' suffix
3857can be used to set the permissions of the opened file.<br>
3858<br>
af268786
MS
3859When opening a socket connection, the filename is a string of the form
3860&quot;address:port&quot; or &quot;hostname:port&quot;. The socket will make an IPv4 or IPv6
3861connection as needed, generally preferring IPv6 connections when there is
3862a choice.
3863
3864</p>
b6008d6b 3865<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileOpenFd">cupsFileOpenFd</a></h3>
af268786
MS
3866<p class="description">Open a CUPS file using a file descriptor.</p>
3867<p class="code">
0350eba5 3868<a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd(<span class="reserved">int</span> fd, <span class="reserved">const</span> <span class="reserved">char</span> *mode);</p>
af268786
MS
3869<h4 class="parameters">Parameters</h4>
3870<table class="list"><tbody>
3871<tr><th>fd</th>
3872<td class="description">File descriptor</td></tr>
3873<tr><th>mode</th>
3874<td class="description">Open mode</td></tr>
3875</tbody></table>
3876<h4 class="returnvalue">Return Value</h4>
3877<p class="description">CUPS file or <code>NULL</code> if the file could not be opened</p>
3878<h4 class="discussion">Discussion</h4>
3879<p class="discussion">The &quot;mode&quot; parameter can be &quot;r&quot; to read, &quot;w&quot; to write, &quot;a&quot; to append,
3880or &quot;s&quot; to treat the file descriptor as a bidirectional socket connection.<br>
3881<br>
3882When opening for writing (&quot;w&quot;), an optional number from 1 to 9 can be
3883supplied which enables Flate compression of the file. Compression is
3884not supported for the &quot;a&quot; (append) mode.
3885
3886</p>
b6008d6b 3887<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFilePeekChar">cupsFilePeekChar</a></h3>
af268786
MS
3888<p class="description">Peek at the next character from a file.</p>
3889<p class="code">
0350eba5 3890<span class="reserved">int</span> cupsFilePeekChar(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
3891<h4 class="parameters">Parameters</h4>
3892<table class="list"><tbody>
3893<tr><th>fp</th>
3894<td class="description">CUPS file</td></tr>
3895</tbody></table>
3896<h4 class="returnvalue">Return Value</h4>
3897<p class="description">Character or -1 on end of file</p>
b6008d6b 3898<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFilePrintf">cupsFilePrintf</a></h3>
af268786
MS
3899<p class="description">Write a formatted string.</p>
3900<p class="code">
0350eba5 3901<span class="reserved">int</span> cupsFilePrintf(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">const</span> <span class="reserved">char</span> *format, ...);</p>
af268786
MS
3902<h4 class="parameters">Parameters</h4>
3903<table class="list"><tbody>
3904<tr><th>fp</th>
3905<td class="description">CUPS file</td></tr>
3906<tr><th>format</th>
3907<td class="description">Printf-style format string</td></tr>
3908<tr><th>...</th>
3909<td class="description">Additional args as necessary</td></tr>
3910</tbody></table>
3911<h4 class="returnvalue">Return Value</h4>
3912<p class="description">Number of bytes written or -1 on error</p>
b6008d6b 3913<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFilePutChar">cupsFilePutChar</a></h3>
af268786
MS
3914<p class="description">Write a character.</p>
3915<p class="code">
0350eba5 3916<span class="reserved">int</span> cupsFilePutChar(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">int</span> c);</p>
af268786
MS
3917<h4 class="parameters">Parameters</h4>
3918<table class="list"><tbody>
3919<tr><th>fp</th>
3920<td class="description">CUPS file</td></tr>
3921<tr><th>c</th>
3922<td class="description">Character to write</td></tr>
3923</tbody></table>
3924<h4 class="returnvalue">Return Value</h4>
3925<p class="description">0 on success, -1 on error</p>
b6008d6b 3926<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsFilePutConf">cupsFilePutConf</a></h3>
af268786
MS
3927<p class="description">Write a configuration line.</p>
3928<p class="code">
0350eba5 3929ssize_t cupsFilePutConf(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">const</span> <span class="reserved">char</span> *directive, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
3930<h4 class="parameters">Parameters</h4>
3931<table class="list"><tbody>
3932<tr><th>fp</th>
3933<td class="description">CUPS file</td></tr>
3934<tr><th>directive</th>
3935<td class="description">Directive</td></tr>
3936<tr><th>value</th>
3937<td class="description">Value</td></tr>
3938</tbody></table>
3939<h4 class="returnvalue">Return Value</h4>
3940<p class="description">Number of bytes written or -1 on error</p>
3941<h4 class="discussion">Discussion</h4>
3942<p class="discussion">This function handles any comment escaping of the value.
3943
3944</p>
b6008d6b 3945<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFilePuts">cupsFilePuts</a></h3>
af268786
MS
3946<p class="description">Write a string.</p>
3947<p class="code">
0350eba5 3948<span class="reserved">int</span> cupsFilePuts(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">const</span> <span class="reserved">char</span> *s);</p>
af268786
MS
3949<h4 class="parameters">Parameters</h4>
3950<table class="list"><tbody>
3951<tr><th>fp</th>
3952<td class="description">CUPS file</td></tr>
3953<tr><th>s</th>
3954<td class="description">String to write</td></tr>
3955</tbody></table>
3956<h4 class="returnvalue">Return Value</h4>
3957<p class="description">Number of bytes written or -1 on error</p>
3958<h4 class="discussion">Discussion</h4>
3959<p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string.
3960
3961</p>
b6008d6b 3962<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileRead">cupsFileRead</a></h3>
af268786
MS
3963<p class="description">Read from a file.</p>
3964<p class="code">
0350eba5 3965ssize_t cupsFileRead(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">char</span> *buf, size_t bytes);</p>
af268786
MS
3966<h4 class="parameters">Parameters</h4>
3967<table class="list"><tbody>
3968<tr><th>fp</th>
3969<td class="description">CUPS file</td></tr>
3970<tr><th>buf</th>
3971<td class="description">Buffer</td></tr>
3972<tr><th>bytes</th>
3973<td class="description">Number of bytes to read</td></tr>
3974</tbody></table>
3975<h4 class="returnvalue">Return Value</h4>
3976<p class="description">Number of bytes read or -1 on error</p>
b6008d6b 3977<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileRewind">cupsFileRewind</a></h3>
af268786
MS
3978<p class="description">Set the current file position to the beginning of the
3979 file.</p>
3980<p class="code">
3981off_t cupsFileRewind(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
3982<h4 class="parameters">Parameters</h4>
3983<table class="list"><tbody>
3984<tr><th>fp</th>
3985<td class="description">CUPS file</td></tr>
3986</tbody></table>
3987<h4 class="returnvalue">Return Value</h4>
3988<p class="description">New file position or -1 on error</p>
b6008d6b 3989<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileSeek">cupsFileSeek</a></h3>
af268786
MS
3990<p class="description">Seek in a file.</p>
3991<p class="code">
3992off_t cupsFileSeek(<a href="#cups_file_t">cups_file_t</a> *fp, off_t pos);</p>
3993<h4 class="parameters">Parameters</h4>
3994<table class="list"><tbody>
3995<tr><th>fp</th>
3996<td class="description">CUPS file</td></tr>
3997<tr><th>pos</th>
3998<td class="description">Position in file</td></tr>
3999</tbody></table>
4000<h4 class="returnvalue">Return Value</h4>
4001<p class="description">New file position or -1 on error</p>
b6008d6b 4002<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileStderr">cupsFileStderr</a></h3>
af268786
MS
4003<p class="description">Return a CUPS file associated with stderr.</p>
4004<p class="code">
0350eba5 4005<a href="#cups_file_t">cups_file_t</a> *cupsFileStderr(<span class="reserved">void</span>);</p>
af268786
MS
4006<h4 class="returnvalue">Return Value</h4>
4007<p class="description">CUPS file</p>
b6008d6b 4008<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileStdin">cupsFileStdin</a></h3>
af268786
MS
4009<p class="description">Return a CUPS file associated with stdin.</p>
4010<p class="code">
0350eba5 4011<a href="#cups_file_t">cups_file_t</a> *cupsFileStdin(<span class="reserved">void</span>);</p>
af268786
MS
4012<h4 class="returnvalue">Return Value</h4>
4013<p class="description">CUPS file</p>
b6008d6b 4014<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileStdout">cupsFileStdout</a></h3>
af268786
MS
4015<p class="description">Return a CUPS file associated with stdout.</p>
4016<p class="code">
0350eba5 4017<a href="#cups_file_t">cups_file_t</a> *cupsFileStdout(<span class="reserved">void</span>);</p>
af268786
MS
4018<h4 class="returnvalue">Return Value</h4>
4019<p class="description">CUPS file</p>
b6008d6b 4020<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileTell">cupsFileTell</a></h3>
af268786
MS
4021<p class="description">Return the current file position.</p>
4022<p class="code">
4023off_t cupsFileTell(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
4024<h4 class="parameters">Parameters</h4>
4025<table class="list"><tbody>
4026<tr><th>fp</th>
4027<td class="description">CUPS file</td></tr>
4028</tbody></table>
4029<h4 class="returnvalue">Return Value</h4>
4030<p class="description">File position</p>
b6008d6b 4031<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileUnlock">cupsFileUnlock</a></h3>
af268786
MS
4032<p class="description">Unlock access to a file.</p>
4033<p class="code">
0350eba5 4034<span class="reserved">int</span> cupsFileUnlock(<a href="#cups_file_t">cups_file_t</a> *fp);</p>
af268786
MS
4035<h4 class="parameters">Parameters</h4>
4036<table class="list"><tbody>
4037<tr><th>fp</th>
4038<td class="description">CUPS file</td></tr>
4039</tbody></table>
4040<h4 class="returnvalue">Return Value</h4>
4041<p class="description">0 on success, -1 on error</p>
b6008d6b 4042<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsFileWrite">cupsFileWrite</a></h3>
af268786
MS
4043<p class="description">Write to a file.</p>
4044<p class="code">
0350eba5 4045ssize_t cupsFileWrite(<a href="#cups_file_t">cups_file_t</a> *fp, <span class="reserved">const</span> <span class="reserved">char</span> *buf, size_t bytes);</p>
af268786
MS
4046<h4 class="parameters">Parameters</h4>
4047<table class="list"><tbody>
4048<tr><th>fp</th>
4049<td class="description">CUPS file</td></tr>
4050<tr><th>buf</th>
4051<td class="description">Buffer</td></tr>
4052<tr><th>bytes</th>
4053<td class="description">Number of bytes to write</td></tr>
4054</tbody></table>
4055<h4 class="returnvalue">Return Value</h4>
4056<p class="description">Number of bytes written or -1 on error</p>
b6008d6b 4057<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsFindDestDefault">cupsFindDestDefault</a></h3>
af268786
MS
4058<p class="description">Find the default value(s) for the given option.</p>
4059<p class="code">
0350eba5 4060<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestDefault(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option);</p>
af268786
MS
4061<h4 class="parameters">Parameters</h4>
4062<table class="list"><tbody>
4063<tr><th>http</th>
4064<td class="description">Connection to destination</td></tr>
4065<tr><th>dest</th>
4066<td class="description">Destination</td></tr>
4067<tr><th>dinfo</th>
4068<td class="description">Destination information</td></tr>
4069<tr><th>option</th>
4070<td class="description">Option/attribute name</td></tr>
4071</tbody></table>
4072<h4 class="returnvalue">Return Value</h4>
4073<p class="description">Default attribute or <code>NULL</code> for none</p>
4074<h4 class="discussion">Discussion</h4>
4075<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
4076<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
4077<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
4078<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
4079functions to inspect the default value(s) as needed.
4080
4081</p>
b6008d6b 4082<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsFindDestReady">cupsFindDestReady</a></h3>
af268786
MS
4083<p class="description">Find the default value(s) for the given option.</p>
4084<p class="code">
0350eba5 4085<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestReady(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option);</p>
af268786
MS
4086<h4 class="parameters">Parameters</h4>
4087<table class="list"><tbody>
4088<tr><th>http</th>
4089<td class="description">Connection to destination</td></tr>
4090<tr><th>dest</th>
4091<td class="description">Destination</td></tr>
4092<tr><th>dinfo</th>
4093<td class="description">Destination information</td></tr>
4094<tr><th>option</th>
4095<td class="description">Option/attribute name</td></tr>
4096</tbody></table>
4097<h4 class="returnvalue">Return Value</h4>
4098<p class="description">Default attribute or <code>NULL</code> for none</p>
4099<h4 class="discussion">Discussion</h4>
4100<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
4101<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
4102<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
4103<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
4104functions to inspect the default value(s) as needed.
4105
4106</p>
b6008d6b 4107<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsFindDestSupported">cupsFindDestSupported</a></h3>
af268786
MS
4108<p class="description">Find the default value(s) for the given option.</p>
4109<p class="code">
0350eba5 4110<a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsFindDestSupported(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option);</p>
af268786
MS
4111<h4 class="parameters">Parameters</h4>
4112<table class="list"><tbody>
4113<tr><th>http</th>
4114<td class="description">Connection to destination</td></tr>
4115<tr><th>dest</th>
4116<td class="description">Destination</td></tr>
4117<tr><th>dinfo</th>
4118<td class="description">Destination information</td></tr>
4119<tr><th>option</th>
4120<td class="description">Option/attribute name</td></tr>
4121</tbody></table>
4122<h4 class="returnvalue">Return Value</h4>
4123<p class="description">Default attribute or <code>NULL</code> for none</p>
4124<h4 class="discussion">Discussion</h4>
4125<p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
4126<code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
4127<code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
4128<code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
4129functions to inspect the default value(s) as needed.
4130
4131</p>
b6008d6b 4132<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsFinishDestDocument">cupsFinishDestDocument</a></h3>
af268786
MS
4133<p class="description">Finish the current document.</p>
4134<p class="code">
4135ipp_status_t cupsFinishDestDocument(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *info);</p>
4136<h4 class="parameters">Parameters</h4>
4137<table class="list"><tbody>
4138<tr><th>http</th>
4139<td class="description">Connection to destination</td></tr>
4140<tr><th>dest</th>
4141<td class="description">Destination</td></tr>
4142<tr><th>info</th>
4143<td class="description">Destination information</td></tr>
4144</tbody></table>
4145<h4 class="returnvalue">Return Value</h4>
4146<p class="description">Status of document submission</p>
4147<h4 class="discussion">Discussion</h4>
4148<p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success.
4149
4150</p>
4151<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsFormDecode">cupsFormDecode</a></h3>
4152<p class="description">Decode URL-encoded form data.</p>
4153<p class="code">
0350eba5 4154<span class="reserved">int</span> cupsFormDecode(<span class="reserved">const</span> <span class="reserved">char</span> *data, <a href="#cups_option_t">cups_option_t</a> **vars);</p>
af268786
MS
4155<h4 class="parameters">Parameters</h4>
4156<table class="list"><tbody>
4157<tr><th>data</th>
4158<td class="description">URL-encoded form data</td></tr>
4159<tr><th>vars</th>
4160<td class="description">Array of variables</td></tr>
4161</tbody></table>
4162<h4 class="returnvalue">Return Value</h4>
4163<p class="description">Number of variables</p>
4164<h4 class="discussion">Discussion</h4>
4165<p class="discussion">This function decodes URL-encoded form data, returning the number of
4166variables and a pointer to a <a href="#cups_option_t"><code>cups_option_t</code></a> array of the variables.<br>
4167<br>
4168Use the <a href="#cupsFreeOptions"><code>cupsFreeOptions</code></a> function to return the memory used when you
4169are done with the form variables.
4170
4171</p>
4172<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsFormEncode">cupsFormEncode</a></h3>
4173<p class="description">Encode options as URL-encoded form data.</p>
4174<p class="code">
0350eba5 4175<span class="reserved">char</span> *cupsFormEncode(<span class="reserved">const</span> <span class="reserved">char</span> *url, <span class="reserved">int</span> num_vars, <a href="#cups_option_t">cups_option_t</a> *vars);</p>
af268786
MS
4176<h4 class="parameters">Parameters</h4>
4177<table class="list"><tbody>
4178<tr><th>url</th>
4179<td class="description">URL or <code>NULL</code> for none</td></tr>
4180<tr><th>num_vars</th>
4181<td class="description">Number of variables</td></tr>
4182<tr><th>vars</th>
4183<td class="description">Variables</td></tr>
4184</tbody></table>
4185<h4 class="returnvalue">Return Value</h4>
4186<p class="description">URL-encoded form data</p>
4187<h4 class="discussion">Discussion</h4>
4188<p class="discussion">This function encodes a CUPS options array as URL-encoded form data with an
4189optional URL prefix, returning an allocated string.<br>
4190<br>
4191Use <code>free</code> to return the memory used for the string.
4192
0350eba5
MS
4193</p>
4194<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsFormatString">cupsFormatString</a></h3>
4195<p class="description">Format a UTF-8 string into a fixed size buffer.</p>
4196<p class="code">
4197ssize_t cupsFormatString(<span class="reserved">char</span> *buffer, size_t bufsize, <span class="reserved">const</span> <span class="reserved">char</span> *format, ...);</p>
4198<h4 class="parameters">Parameters</h4>
4199<table class="list"><tbody>
4200<tr><th>buffer</th>
4201<td class="description">Output buffer</td></tr>
4202<tr><th>bufsize</th>
4203<td class="description">Size of output buffer</td></tr>
4204<tr><th>format</th>
4205<td class="description"><code>printf</code>-style format string</td></tr>
4206<tr><th>...</th>
4207<td class="description">Additional arguments</td></tr>
4208</tbody></table>
4209<h4 class="returnvalue">Return Value</h4>
4210<p class="description">Number of bytes formatted</p>
4211<h4 class="discussion">Discussion</h4>
4212<p class="discussion">This function formats a UTF-8 string into a fixed size buffer, escaping
4213special/control characters as needed so they can be safely displayed or
4214logged.
4215
4216</p>
4217<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsFormatStringv">cupsFormatStringv</a></h3>
4218<p class="description">Format a UTF-8 string into a fixed size buffer (<code>va_list</code> version).</p>
4219<p class="code">
4220ssize_t cupsFormatStringv(<span class="reserved">char</span> *buffer, size_t bufsize, <span class="reserved">const</span> <span class="reserved">char</span> *format, va_list ap);</p>
4221<h4 class="parameters">Parameters</h4>
4222<table class="list"><tbody>
4223<tr><th>buffer</th>
4224<td class="description">Output buffer</td></tr>
4225<tr><th>bufsize</th>
4226<td class="description">Size of output buffer</td></tr>
4227<tr><th>format</th>
4228<td class="description">printf-style format string</td></tr>
4229<tr><th>ap</th>
4230<td class="description">Pointer to additional arguments</td></tr>
4231</tbody></table>
4232<h4 class="returnvalue">Return Value</h4>
4233<p class="description">Number of bytes formatted</p>
4234<h4 class="discussion">Discussion</h4>
4235<p class="discussion">This function formats a UTF-8 string into a fixed size buffer using a
4236variable argument pointer, escaping special/control characters as needed so
4237they can be safely displayed or logged.
4238
af268786 4239</p>
b6008d6b 4240<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsFreeDestInfo">cupsFreeDestInfo</a></h3>
af268786
MS
4241<p class="description">Free destination information obtained using
4242 <a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p>
4243<p class="code">
0350eba5 4244<span class="reserved">void</span> cupsFreeDestInfo(<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo);</p>
af268786
MS
4245<h4 class="parameters">Parameters</h4>
4246<table class="list"><tbody>
4247<tr><th>dinfo</th>
4248<td class="description">Destination information</td></tr>
4249</tbody></table>
4250<h3 class="function"><a id="cupsFreeDests">cupsFreeDests</a></h3>
4251<p class="description">Free the memory used by the list of destinations.</p>
4252<p class="code">
0350eba5 4253<span class="reserved">void</span> cupsFreeDests(<span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
af268786
MS
4254<h4 class="parameters">Parameters</h4>
4255<table class="list"><tbody>
4256<tr><th>num_dests</th>
4257<td class="description">Number of destinations</td></tr>
4258<tr><th>dests</th>
4259<td class="description">Destinations</td></tr>
4260</tbody></table>
4261<h3 class="function"><a id="cupsFreeJobs">cupsFreeJobs</a></h3>
4262<p class="description">Free memory used by job data.</p>
4263<p class="code">
0350eba5 4264<span class="reserved">void</span> cupsFreeJobs(<span class="reserved">int</span> num_jobs, <a href="#cups_job_t">cups_job_t</a> *jobs);</p>
af268786
MS
4265<h4 class="parameters">Parameters</h4>
4266<table class="list"><tbody>
4267<tr><th>num_jobs</th>
4268<td class="description">Number of jobs</td></tr>
4269<tr><th>jobs</th>
4270<td class="description">Jobs</td></tr>
4271</tbody></table>
4272<h3 class="function"><a id="cupsFreeOptions">cupsFreeOptions</a></h3>
4273<p class="description">Free all memory used by options.</p>
4274<p class="code">
0350eba5 4275<span class="reserved">void</span> cupsFreeOptions(<span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
af268786
MS
4276<h4 class="parameters">Parameters</h4>
4277<table class="list"><tbody>
4278<tr><th>num_options</th>
4279<td class="description">Number of options</td></tr>
4280<tr><th>options</th>
4281<td class="description">Pointer to options</td></tr>
4282</tbody></table>
0350eba5
MS
4283<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetClock">cupsGetClock</a></h3>
4284<p class="description">Get a monotonic clock value in seconds.</p>
4285<p class="code">
4286<span class="reserved">double</span> cupsGetClock(<span class="reserved">void</span>);</p>
4287<h4 class="returnvalue">Return Value</h4>
4288<p class="description">Elapsed seconds</p>
4289<h4 class="discussion">Discussion</h4>
4290<p class="discussion">This function returns a monotonically increasing clock value in seconds. The
4291first call will always return 0.0. Subsequent calls will return the number
4292of seconds that have elapsed since the first call, regardless of system time
4293changes, sleep, etc. The sub-second accuracy varies based on the operating
4294system and hardware but is typically 10ms or better.
4295
4296</p>
af268786
MS
4297<h3 class="function"><a id="cupsGetCredentialsExpiration">cupsGetCredentialsExpiration</a></h3>
4298<p class="description">Return the expiration date of the credentials.</p>
4299<p class="code">
0350eba5 4300time_t cupsGetCredentialsExpiration(<span class="reserved">const</span> <span class="reserved">char</span> *credentials);</p>
af268786
MS
4301<h4 class="parameters">Parameters</h4>
4302<table class="list"><tbody>
4303<tr><th>credentials</th>
4304<td class="description">Credentials</td></tr>
4305</tbody></table>
4306<h4 class="returnvalue">Return Value</h4>
4307<p class="description">Expiration date of credentials</p>
4308<h3 class="function"><a id="cupsGetCredentialsInfo">cupsGetCredentialsInfo</a></h3>
4309<p class="description">Return a string describing the credentials.</p>
4310<p class="code">
0350eba5 4311<span class="reserved">char</span> *cupsGetCredentialsInfo(<span class="reserved">const</span> <span class="reserved">char</span> *credentials, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
af268786
MS
4312<h4 class="parameters">Parameters</h4>
4313<table class="list"><tbody>
4314<tr><th>credentials</th>
4315<td class="description">Credentials</td></tr>
4316<tr><th>buffer</th>
4317<td class="description">Buffer</td></tr>
4318<tr><th>bufsize</th>
4319<td class="description">Size of buffer</td></tr>
4320</tbody></table>
4321<h4 class="returnvalue">Return Value</h4>
4322<p class="description">Credentials description or <code>NULL</code> on error</p>
4323<h3 class="function"><a id="cupsGetCredentialsTrust">cupsGetCredentialsTrust</a></h3>
4324<p class="description">Return the trust of credentials.</p>
4325<p class="code">
0350eba5 4326<a href="#http_trust_t">http_trust_t</a> cupsGetCredentialsTrust(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *credentials, <span class="reserved">bool</span> require_ca);</p>
af268786
MS
4327<h4 class="parameters">Parameters</h4>
4328<table class="list"><tbody>
4329<tr><th>path</th>
4330<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
4331<tr><th>common_name</th>
4332<td class="description">Common name for trust lookup</td></tr>
4333<tr><th>credentials</th>
4334<td class="description">Credentials</td></tr>
0350eba5
MS
4335<tr><th>require_ca</th>
4336<td class="description">Require a CA-signed certificate?</td></tr>
af268786
MS
4337</tbody></table>
4338<h4 class="returnvalue">Return Value</h4>
4339<p class="description">Level of trust</p>
0350eba5
MS
4340<h4 class="discussion">Discussion</h4>
4341<p class="discussion">This function determines the level of trust for the supplied credentials.
4342The &quot;path&quot; parameter specifies the certificate/key store for known
4343credentials and certificate authorities. The &quot;common_name&quot; parameter
4344specifies the FQDN of the service being accessed such as
4345&quot;printer.example.com&quot;. The &quot;credentials&quot; parameter provides the credentials
4346being evaluated, which are usually obtained with the
4347<a href="#httpCopyPeerCredentials"><code>httpCopyPeerCredentials</code></a> function. The &quot;require_ca&quot; parameter
4348specifies whether a CA-signed certificate is required for trust.<br>
4349<br>
4350The <code>AllowAnyRoot</code>, <code>AllowExpiredCerts</code>, <code>TrustOnFirstUse</code>, and
4351<code>ValidateCerts</code> options in the &quot;client.conf&quot; file (or corresponding
4352preferences file on macOS) control the trust policy, which defaults to
4353AllowAnyRoot=Yes, AllowExpiredCerts=No, TrustOnFirstUse=Yes, and
4354ValidateCerts=No. When the &quot;require_ca&quot; parameter is <code>true</code> the AllowAnyRoot
4355and TrustOnFirstUse policies are turned off (&quot;No&quot;).<br>
4356<br>
4357The returned trust value can be one of the following:
4358
4359</p><ul>
4360<li><code>HTTP_TRUST_OK</code>: Credentials are OK/trusted
4361</li>
4362<li><code>HTTP_TRUST_INVALID</code>: Credentials are invalid
4363</li>
4364<li><code>HTTP_TRUST_EXPIRED</code>: Credentials are expired
4365</li>
4366<li><code>HTTP_TRUST_RENEWED</code>: Credentials have been renewed
4367</li>
4368<li><code>HTTP_TRUST_UNKNOWN</code>: Credentials are unknown/new</li>
4369</ul>
af268786
MS
4370<h3 class="function"><a id="cupsGetDest">cupsGetDest</a></h3>
4371<p class="description">Get the named destination from the list.</p>
4372<p class="code">
0350eba5 4373<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *instance, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
af268786
MS
4374<h4 class="parameters">Parameters</h4>
4375<table class="list"><tbody>
4376<tr><th>name</th>
4377<td class="description">Destination name or <code>NULL</code> for the default destination</td></tr>
4378<tr><th>instance</th>
4379<td class="description">Instance name or <code>NULL</code></td></tr>
4380<tr><th>num_dests</th>
4381<td class="description">Number of destinations</td></tr>
4382<tr><th>dests</th>
4383<td class="description">Destinations</td></tr>
4384</tbody></table>
4385<h4 class="returnvalue">Return Value</h4>
4386<p class="description">Destination pointer or <code>NULL</code></p>
4387<h4 class="discussion">Discussion</h4>
4388<p class="discussion">Use the <a href="#cupsEnumDests"><code>cupsEnumDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
4389list of supported destinations for the current user.</p>
b6008d6b 4390<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3>
af268786
MS
4391<p class="description">Get a media name, dimension, and margins for a
4392 specific size.</p>
4393<p class="code">
0350eba5 4394<span class="reserved">int</span> cupsGetDestMediaByIndex(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">int</span> n, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
af268786
MS
4395<h4 class="parameters">Parameters</h4>
4396<table class="list"><tbody>
4397<tr><th>http</th>
4398<td class="description">Connection to destination</td></tr>
4399<tr><th>dest</th>
4400<td class="description">Destination</td></tr>
4401<tr><th>dinfo</th>
4402<td class="description">Destination information</td></tr>
4403<tr><th>n</th>
4404<td class="description">Media size number (0-based)</td></tr>
4405<tr><th>flags</th>
4406<td class="description">Media flags</td></tr>
4407<tr><th>size</th>
4408<td class="description">Media size information</td></tr>
4409</tbody></table>
4410<h4 class="returnvalue">Return Value</h4>
4411<p class="description">1 on success, 0 on failure</p>
4412<h4 class="discussion">Discussion</h4>
4413<p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For
4414example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
4415borderless size supported by the printer.
4416
4417</p>
4418<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetDestMediaByIndex2">cupsGetDestMediaByIndex2</a></h3>
4419<p class="description">Get specific media information.</p>
4420<p class="code">
0350eba5 4421<span class="reserved">bool</span> cupsGetDestMediaByIndex2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, size_t n, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media);</p>
af268786
MS
4422<h4 class="parameters">Parameters</h4>
4423<table class="list"><tbody>
4424<tr><th>http</th>
4425<td class="description">Connection to destination</td></tr>
4426<tr><th>dest</th>
4427<td class="description">Destination</td></tr>
4428<tr><th>dinfo</th>
4429<td class="description">Destination information</td></tr>
4430<tr><th>n</th>
4431<td class="description">Media number (0-based)</td></tr>
4432<tr><th>flags</th>
4433<td class="description">Media flags</td></tr>
4434<tr><th>media</th>
4435<td class="description">Media information</td></tr>
4436</tbody></table>
4437<h4 class="returnvalue">Return Value</h4>
4438<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
4439<h4 class="discussion">Discussion</h4>
4440<p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For
4441example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
4442borderless size supported by the printer.
4443
4444</p>
b6008d6b 4445<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3>
af268786
MS
4446<p class="description">Get media names, dimensions, and margins.</p>
4447<p class="code">
0350eba5 4448<span class="reserved">int</span> cupsGetDestMediaByName(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
af268786
MS
4449<h4 class="parameters">Parameters</h4>
4450<table class="list"><tbody>
4451<tr><th>http</th>
4452<td class="description">Connection to destination</td></tr>
4453<tr><th>dest</th>
4454<td class="description">Destination</td></tr>
4455<tr><th>dinfo</th>
4456<td class="description">Destination information</td></tr>
4457<tr><th>name</th>
4458<td class="description">Media name</td></tr>
4459<tr><th>flags</th>
4460<td class="description">Media matching flags</td></tr>
4461<tr><th>size</th>
4462<td class="description">Media size information</td></tr>
4463</tbody></table>
4464<h4 class="returnvalue">Return Value</h4>
4465<p class="description">1 on match, 0 on failure</p>
4466<h4 class="discussion">Discussion</h4>
4467<p class="discussion">The &quot;media&quot; string is a PWG media name. &quot;Flags&quot; provides some matching
4468guidance (multiple flags can be combined):<br>
4469<br>
4470CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
4471CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
4472CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
4473CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
4474CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
4475 size amongst the &quot;ready&quot; media.<br>
4476<br>
4477The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
4478<br>
4479Returns 1 when there is a match and 0 if there is not a match.
4480
4481</p>
b6008d6b 4482<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsGetDestMediaByName2">cupsGetDestMediaByName2</a></h3>
af268786
MS
4483<p class="description">Get media names, dimensions, and margins.</p>
4484<p class="code">
0350eba5 4485<span class="reserved">bool</span> cupsGetDestMediaByName2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media);</p>
af268786
MS
4486<h4 class="parameters">Parameters</h4>
4487<table class="list"><tbody>
4488<tr><th>http</th>
4489<td class="description">Connection to destination</td></tr>
4490<tr><th>dest</th>
4491<td class="description">Destination</td></tr>
4492<tr><th>dinfo</th>
4493<td class="description">Destination information</td></tr>
4494<tr><th>name</th>
4495<td class="description">Media name</td></tr>
4496<tr><th>flags</th>
4497<td class="description">Media matching flags</td></tr>
4498<tr><th>media</th>
4499<td class="description">Media information</td></tr>
4500</tbody></table>
4501<h4 class="returnvalue">Return Value</h4>
4502<p class="description"><code>true</code> on match, <code>false</code> on failure</p>
4503<h4 class="discussion">Discussion</h4>
4504<p class="discussion">The &quot;media&quot; string is a PWG media name. &quot;Flags&quot; provides some matching
4505guidance (multiple flags can be combined):<br>
4506<br>
4507CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
4508CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
4509CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
4510CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
4511CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
4512 size amongst the &quot;ready&quot; media.<br>
4513<br>
4514The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
4515<br>
4516Returns <code>true</code> when there is a match and <code>false</code> if there is not a match.
4517
4518</p>
b6008d6b 4519<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3>
af268786
MS
4520<p class="description">Get media names, dimensions, and margins.</p>
4521<p class="code">
0350eba5 4522<span class="reserved">int</span> cupsGetDestMediaBySize(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">int</span> width, <span class="reserved">int</span> length, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
af268786
MS
4523<h4 class="parameters">Parameters</h4>
4524<table class="list"><tbody>
4525<tr><th>http</th>
4526<td class="description">Connection to destination</td></tr>
4527<tr><th>dest</th>
4528<td class="description">Destination</td></tr>
4529<tr><th>dinfo</th>
4530<td class="description">Destination information</td></tr>
4531<tr><th>width</th>
4532<td class="description">Media width in hundredths of
4533 of millimeters</td></tr>
4534<tr><th>length</th>
4535<td class="description">Media length in hundredths of
4536 of millimeters</td></tr>
4537<tr><th>flags</th>
4538<td class="description">Media matching flags</td></tr>
4539<tr><th>size</th>
4540<td class="description">Media size information</td></tr>
4541</tbody></table>
4542<h4 class="returnvalue">Return Value</h4>
4543<p class="description">1 on match, 0 on failure</p>
4544<h4 class="discussion">Discussion</h4>
4545<p class="discussion">&quot;Width&quot; and &quot;length&quot; are the dimensions in hundredths of millimeters.
4546&quot;Flags&quot; provides some matching guidance (multiple flags can be combined):<br>
4547<br>
4548CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
4549CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
4550CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
4551CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
4552CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
4553 size amongst the &quot;ready&quot; media.<br>
4554<br>
4555The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
4556<br>
4557Returns 1 when there is a match and 0 if there is not a match.
4558
4559</p>
4560<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetDestMediaBySize2">cupsGetDestMediaBySize2</a></h3>
4561<p class="description">Get media names, dimensions, and margins.</p>
4562<p class="code">
0350eba5 4563<span class="reserved">bool</span> cupsGetDestMediaBySize2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">int</span> width, <span class="reserved">int</span> length, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media);</p>
af268786
MS
4564<h4 class="parameters">Parameters</h4>
4565<table class="list"><tbody>
4566<tr><th>http</th>
4567<td class="description">Connection to destination</td></tr>
4568<tr><th>dest</th>
4569<td class="description">Destination</td></tr>
4570<tr><th>dinfo</th>
4571<td class="description">Destination information</td></tr>
4572<tr><th>width</th>
4573<td class="description">Media width in hundredths of millimeters</td></tr>
4574<tr><th>length</th>
4575<td class="description">Media length in hundredths of millimeters</td></tr>
4576<tr><th>flags</th>
4577<td class="description">Media matching flags</td></tr>
4578<tr><th>media</th>
4579<td class="description">Media information</td></tr>
4580</tbody></table>
4581<h4 class="returnvalue">Return Value</h4>
4582<p class="description"><code>true</code> on match, <code>false</code> on failure</p>
4583<h4 class="discussion">Discussion</h4>
4584<p class="discussion">&quot;Width&quot; and &quot;length&quot; are the dimensions in hundredths of millimeters.
4585&quot;Flags&quot; provides some matching guidance (multiple flags can be combined):<br>
4586<br>
4587CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
4588CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
4589CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
4590CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
4591CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
4592 size amongst the &quot;ready&quot; media.<br>
4593<br>
4594The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
4595<br>
4596Returns <code>true</code> when there is a match and <code>false</code> if there is not a match.
4597
4598</p>
b6008d6b 4599<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3>
af268786
MS
4600<p class="description">Get the number of sizes supported by a
4601 destination.</p>
4602<p class="code">
0350eba5 4603<span class="reserved">int</span> cupsGetDestMediaCount(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags);</p>
af268786
MS
4604<h4 class="parameters">Parameters</h4>
4605<table class="list"><tbody>
4606<tr><th>http</th>
4607<td class="description">Connection to destination</td></tr>
4608<tr><th>dest</th>
4609<td class="description">Destination</td></tr>
4610<tr><th>dinfo</th>
4611<td class="description">Destination information</td></tr>
4612<tr><th>flags</th>
4613<td class="description">Media flags</td></tr>
4614</tbody></table>
4615<h4 class="returnvalue">Return Value</h4>
4616<p class="description">Number of sizes</p>
4617<h4 class="discussion">Discussion</h4>
4618<p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are
4619counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return
4620the number of borderless sizes.
4621
4622</p>
b6008d6b 4623<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3>
af268786
MS
4624<p class="description">Get the default size for a destination.</p>
4625<p class="code">
0350eba5 4626<span class="reserved">int</span> cupsGetDestMediaDefault(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
af268786
MS
4627<h4 class="parameters">Parameters</h4>
4628<table class="list"><tbody>
4629<tr><th>http</th>
4630<td class="description">Connection to destination</td></tr>
4631<tr><th>dest</th>
4632<td class="description">Destination</td></tr>
4633<tr><th>dinfo</th>
4634<td class="description">Destination information</td></tr>
4635<tr><th>flags</th>
4636<td class="description">Media flags</td></tr>
4637<tr><th>size</th>
4638<td class="description">Media size information</td></tr>
4639</tbody></table>
4640<h4 class="returnvalue">Return Value</h4>
4641<p class="description">1 on success, 0 on failure</p>
4642<h4 class="discussion">Discussion</h4>
4643<p class="discussion">The <code>flags</code> parameter determines which default size is returned. For
4644example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
4645borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
4646
4647</p>
4648<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetDestMediaDefault2">cupsGetDestMediaDefault2</a></h3>
4649<p class="description">Get the default size for a destination.</p>
4650<p class="code">
0350eba5 4651<span class="reserved">bool</span> cupsGetDestMediaDefault2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media);</p>
af268786
MS
4652<h4 class="parameters">Parameters</h4>
4653<table class="list"><tbody>
4654<tr><th>http</th>
4655<td class="description">Connection to destination</td></tr>
4656<tr><th>dest</th>
4657<td class="description">Destination</td></tr>
4658<tr><th>dinfo</th>
4659<td class="description">Destination information</td></tr>
4660<tr><th>flags</th>
4661<td class="description">Media flags</td></tr>
4662<tr><th>media</th>
4663<td class="description">Media information</td></tr>
4664</tbody></table>
4665<h4 class="returnvalue">Return Value</h4>
4666<p class="description"><code>true</code> on match, <code>false</code> on failure</p>
4667<h4 class="discussion">Discussion</h4>
4668<p class="discussion">The <code>flags</code> parameter determines which default size is returned. For
4669example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
4670borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
4671
4672</p>
b6008d6b 4673<h3 class="function"><span class="info">&#160;CUPS 2.0&#160;</span><a id="cupsGetDestWithURI">cupsGetDestWithURI</a></h3>
af268786
MS
4674<p class="description">Get a destination associated with a URI.</p>
4675<p class="code">
0350eba5 4676<a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *uri);</p>
af268786
MS
4677<h4 class="parameters">Parameters</h4>
4678<table class="list"><tbody>
4679<tr><th>name</th>
4680<td class="description">Desired printer name or <code>NULL</code></td></tr>
4681<tr><th>uri</th>
4682<td class="description">URI for the printer</td></tr>
4683</tbody></table>
4684<h4 class="returnvalue">Return Value</h4>
4685<p class="description">Destination or <code>NULL</code></p>
4686<h4 class="discussion">Discussion</h4>
4687<p class="discussion">&quot;name&quot; is the desired name for the printer. If <code>NULL</code>, a name will be
4688created using the URI.<br>
4689<br>
4690&quot;uri&quot; is the &quot;ipp&quot; or &quot;ipps&quot; URI for the printer.
4691
4692</p>
b6008d6b 4693<h3 class="function"><span class="info">&#160;CUPS 1.1.21&#160;</span><a id="cupsGetDests2">cupsGetDests2</a></h3>
af268786
MS
4694<p class="description">Get the list of destinations from the specified server.</p>
4695<p class="code">
0350eba5 4696<span class="reserved">int</span> cupsGetDests2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
af268786
MS
4697<h4 class="parameters">Parameters</h4>
4698<table class="list"><tbody>
4699<tr><th>http</th>
4700<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4701<tr><th>dests</th>
4702<td class="description">Destinations</td></tr>
4703</tbody></table>
4704<h4 class="returnvalue">Return Value</h4>
4705<p class="description">Number of destinations</p>
4706<h4 class="discussion">Discussion</h4>
4707<p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
4708&quot;printer-info&quot;, &quot;printer-is-accepting-jobs&quot;, &quot;printer-is-shared&quot;,
4709&quot;printer-make-and-model&quot;, &quot;printer-state&quot;, &quot;printer-state-change-time&quot;,
4710&quot;printer-state-reasons&quot;, &quot;printer-type&quot;, and &quot;printer-uri-supported&quot;
4711attributes as options.<br>
4712<br>
4713CUPS 1.4 adds the &quot;marker-change-time&quot;, &quot;marker-colors&quot;,
4714&quot;marker-high-levels&quot;, &quot;marker-levels&quot;, &quot;marker-low-levels&quot;, &quot;marker-message&quot;,
4715&quot;marker-names&quot;, &quot;marker-types&quot;, and &quot;printer-commands&quot; attributes as options.<br>
4716<br>
4717CUPS 2.2 adds accessible IPP printers to the list of destinations that can
4718be used. The &quot;printer-uri-supported&quot; option will be present for those IPP
4719printers that have been recently used.<br>
4720<br>
4721Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
4722the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
4723
4724</p>
4725<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetEncryption">cupsGetEncryption</a></h3>
4726<p class="description">Get the current encryption settings.</p>
4727<p class="code">
0350eba5 4728<a href="#http_encryption_t">http_encryption_t</a> cupsGetEncryption(<span class="reserved">void</span>);</p>
af268786
MS
4729<h4 class="returnvalue">Return Value</h4>
4730<p class="description">Encryption settings</p>
4731<h4 class="discussion">Discussion</h4>
4732<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
4733environment variable, then the ~/.cups/client.conf file, and finally the
4734/etc/cups/client.conf file. If not set, the default is
4735<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
4736<br>
4737Note: The current encryption setting is tracked separately for each thread
4738in a program. Multi-threaded programs that override the setting via the
4739<a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same
4740setting to be used.
4741
4742</p>
4743<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetError">cupsGetError</a></h3>
4744<p class="description">Return the last IPP status code received on the current thread.</p>
4745<p class="code">
0350eba5 4746ipp_status_t cupsGetError(<span class="reserved">void</span>);</p>
af268786
MS
4747<h4 class="returnvalue">Return Value</h4>
4748<p class="description">IPP status code from last request</p>
4749<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetErrorString">cupsGetErrorString</a></h3>
4750<p class="description">Return the last IPP status-message received on the current thread.</p>
4751<p class="code">
0350eba5 4752<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetErrorString(<span class="reserved">void</span>);</p>
af268786
MS
4753<h4 class="returnvalue">Return Value</h4>
4754<p class="description">status-message text from last request</p>
b6008d6b 4755<h3 class="function"><span class="info">&#160;CUPS 1.1.20&#160;</span><a id="cupsGetFd">cupsGetFd</a></h3>
af268786
MS
4756<p class="description">Get a file from the server.</p>
4757<p class="code">
0350eba5 4758http_status_t cupsGetFd(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">int</span> fd);</p>
af268786
MS
4759<h4 class="parameters">Parameters</h4>
4760<table class="list"><tbody>
4761<tr><th>http</th>
4762<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4763<tr><th>resource</th>
4764<td class="description">Resource name</td></tr>
4765<tr><th>fd</th>
4766<td class="description">File descriptor</td></tr>
4767</tbody></table>
4768<h4 class="returnvalue">Return Value</h4>
4769<p class="description">HTTP status</p>
4770<h4 class="discussion">Discussion</h4>
4771<p class="discussion">This function returns <code>HTTP_STATUS_OK</code> when the file is successfully retrieved.
4772
4773</p>
b6008d6b 4774<h3 class="function"><span class="info">&#160;CUPS 1.1.20&#160;</span><a id="cupsGetFile">cupsGetFile</a></h3>
af268786
MS
4775<p class="description">Get a file from the server.</p>
4776<p class="code">
0350eba5 4777http_status_t cupsGetFile(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">const</span> <span class="reserved">char</span> *filename);</p>
af268786
MS
4778<h4 class="parameters">Parameters</h4>
4779<table class="list"><tbody>
4780<tr><th>http</th>
4781<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4782<tr><th>resource</th>
4783<td class="description">Resource name</td></tr>
4784<tr><th>filename</th>
4785<td class="description">Filename</td></tr>
4786</tbody></table>
4787<h4 class="returnvalue">Return Value</h4>
4788<p class="description">HTTP status</p>
4789<h4 class="discussion">Discussion</h4>
4790<p class="discussion">This function returns <code>HTTP_STATUS_OK</code> when the file is successfully retrieved.
4791
4792</p>
b6008d6b 4793<h3 class="function"><span class="info">&#160;CUPS 2.2.4&#160;</span><a id="cupsGetIntegerOption">cupsGetIntegerOption</a></h3>
af268786
MS
4794<p class="description">Get an integer option value.</p>
4795<p class="code">
0350eba5 4796<span class="reserved">int</span> cupsGetIntegerOption(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
af268786
MS
4797<h4 class="parameters">Parameters</h4>
4798<table class="list"><tbody>
4799<tr><th>name</th>
4800<td class="description">Name of option</td></tr>
4801<tr><th>num_options</th>
4802<td class="description">Number of options</td></tr>
4803<tr><th>options</th>
4804<td class="description">Options</td></tr>
4805</tbody></table>
4806<h4 class="returnvalue">Return Value</h4>
4807<p class="description">Option value or <code>INT_MIN</code></p>
4808<h4 class="discussion">Discussion</h4>
4809<p class="discussion">INT_MIN is returned when the option does not exist, is not an integer, or
4810exceeds the range of values for the &quot;int&quot; type.
4811
4812</p>
b6008d6b 4813<h3 class="function"><span class="info">&#160;CUPS 1.1.21&#160;</span><a id="cupsGetJobs2">cupsGetJobs2</a></h3>
af268786
MS
4814<p class="description">Get the jobs from the specified server.</p>
4815<p class="code">
0350eba5 4816<span class="reserved">int</span> cupsGetJobs2(<a href="#http_t">http_t</a> *http, <a href="#cups_job_t">cups_job_t</a> **jobs, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> myjobs, <span class="reserved">int</span> whichjobs);</p>
af268786
MS
4817<h4 class="parameters">Parameters</h4>
4818<table class="list"><tbody>
4819<tr><th>http</th>
4820<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4821<tr><th>jobs</th>
4822<td class="description">Job data</td></tr>
4823<tr><th>name</th>
4824<td class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</td></tr>
4825<tr><th>myjobs</th>
4826<td class="description">0 = all users, 1 = mine</td></tr>
4827<tr><th>whichjobs</th>
4828<td class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></td></tr>
4829</tbody></table>
4830<h4 class="returnvalue">Return Value</h4>
4831<p class="description">Number of jobs</p>
4832<h4 class="discussion">Discussion</h4>
4833<p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
4834of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
4835pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
4836jobs that are stopped, canceled, aborted, or completed.
4837
4838</p>
b6008d6b 4839<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsGetNamedDest">cupsGetNamedDest</a></h3>
af268786
MS
4840<p class="description">Get options for the named destination.</p>
4841<p class="code">
0350eba5 4842<a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *instance);</p>
af268786
MS
4843<h4 class="parameters">Parameters</h4>
4844<table class="list"><tbody>
4845<tr><th>http</th>
4846<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4847<tr><th>name</th>
4848<td class="description">Destination name or <code>NULL</code> for the default destination</td></tr>
4849<tr><th>instance</th>
4850<td class="description">Instance name or <code>NULL</code></td></tr>
4851</tbody></table>
4852<h4 class="returnvalue">Return Value</h4>
4853<p class="description">Destination or <code>NULL</code></p>
4854<h4 class="discussion">Discussion</h4>
4855<p class="discussion">This function is optimized for retrieving a single destination and should
4856be used instead of <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you
4857either know the name of the destination or want to print to the default
4858destination. If <code>NULL</code> is returned, the destination does not exist or
4859there is no default destination.<br>
4860<br>
4861If &quot;http&quot; is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
4862server will be used.<br>
4863<br>
4864If &quot;name&quot; is <code>NULL</code>, the default printer for the current user will be
4865returned.<br>
4866<br>
4867The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
4868&quot;num_dests&quot; value of 1.
4869
4870</p>
4871<h3 class="function"><a id="cupsGetOption">cupsGetOption</a></h3>
4872<p class="description">Get an option value.</p>
4873<p class="code">
0350eba5 4874<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetOption(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
af268786
MS
4875<h4 class="parameters">Parameters</h4>
4876<table class="list"><tbody>
4877<tr><th>name</th>
4878<td class="description">Name of option</td></tr>
4879<tr><th>num_options</th>
4880<td class="description">Number of options</td></tr>
4881<tr><th>options</th>
4882<td class="description">Options</td></tr>
4883</tbody></table>
4884<h4 class="returnvalue">Return Value</h4>
4885<p class="description">Option value or <code>NULL</code></p>
b6008d6b 4886<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsGetPassword2">cupsGetPassword2</a></h3>
af268786
MS
4887<p class="description">Get a password from the user using the current
4888 password callback.</p>
4889<p class="code">
0350eba5 4890<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetPassword2(<span class="reserved">const</span> <span class="reserved">char</span> *prompt, <a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource);</p>
af268786
MS
4891<h4 class="parameters">Parameters</h4>
4892<table class="list"><tbody>
4893<tr><th>prompt</th>
4894<td class="description">Prompt string</td></tr>
4895<tr><th>http</th>
4896<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4897<tr><th>method</th>
4898<td class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</td></tr>
4899<tr><th>resource</th>
4900<td class="description">Resource path</td></tr>
4901</tbody></table>
4902<h4 class="returnvalue">Return Value</h4>
4903<p class="description">Password</p>
4904<h4 class="discussion">Discussion</h4>
4905<p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
4906user does not provide a password.<br>
4907<br>
4908Note: The current password callback function is tracked separately for each
4909thread in a program. Multi-threaded programs that override the setting via
4910the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> function need to do so in each thread for the
4911same function to be used.
b47dab17
MS
4912
4913</p>
af268786
MS
4914<h3 class="function"><a id="cupsGetRand">cupsGetRand</a></h3>
4915<p class="description">Return a 32-bit pseudo-random number.</p>
b47dab17 4916<p class="code">
0350eba5 4917<span class="reserved">unsigned</span> cupsGetRand(<span class="reserved">void</span>);</p>
af268786
MS
4918<h4 class="returnvalue">Return Value</h4>
4919<p class="description">Random number</p>
4920<h4 class="discussion">Discussion</h4>
4921<p class="discussion">This function returns a 32-bit pseudo-random number suitable for use as
4922one-time identifiers or nonces. The random numbers are generated/seeded
4923using system entropy.</p>
b6008d6b 4924<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsGetResponse">cupsGetResponse</a></h3>
af268786
MS
4925<p class="description">Get a response to an IPP request.</p>
4926<p class="code">
0350eba5 4927<a href="#ipp_t">ipp_t</a> *cupsGetResponse(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *resource);</p>
b47dab17
MS
4928<h4 class="parameters">Parameters</h4>
4929<table class="list"><tbody>
af268786
MS
4930<tr><th>http</th>
4931<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
4932<tr><th>resource</th>
4933<td class="description">HTTP resource for POST</td></tr>
98d88c8d 4934</tbody></table>
798d6e29 4935<h4 class="returnvalue">Return Value</h4>
af268786 4936<p class="description">Response or <code>NULL</code> on HTTP error</p>
798d6e29 4937<h4 class="discussion">Discussion</h4>
af268786
MS
4938<p class="discussion">Use this function to get the response for an IPP request sent using
4939<a href="#cupsSendRequest"><code>cupsSendRequest</code></a>. For requests that return additional data, use
4940<a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> after getting a successful response,
4941otherwise call <a href="#httpFlush"><code>httpFlush</code></a> to complete the response processing.
798d6e29
MS
4942
4943</p>
af268786
MS
4944<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetServer">cupsGetServer</a></h3>
4945<p class="description">Return the hostname/address of the current server.</p>
798d6e29 4946<p class="code">
0350eba5 4947<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetServer(<span class="reserved">void</span>);</p>
af268786
MS
4948<h4 class="returnvalue">Return Value</h4>
4949<p class="description">Server name</p>
4950<h4 class="discussion">Discussion</h4>
4951<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
4952~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
4953set, the default is the local system - either &quot;localhost&quot; or a domain socket
4954path.<br>
4955<br>
4956The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
4957address, or a domain socket pathname.<br>
4958<br>
4959Note: The current server is tracked separately for each thread in a program.
4960Multi-threaded programs that override the server via the
4961<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
4962server to be used.
4963
4964</p>
4965<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetUser">cupsGetUser</a></h3>
4966<p class="description">Return the current user's name.</p>
4967<p class="code">
0350eba5 4968<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetUser(<span class="reserved">void</span>);</p>
af268786
MS
4969<h4 class="returnvalue">Return Value</h4>
4970<p class="description">User name</p>
4971<h4 class="discussion">Discussion</h4>
4972<p class="discussion">Note: The current user name is tracked separately for each thread in a
4973program. Multi-threaded programs that override the user name with the
4974<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
4975name to be used.
4976
4977</p>
4978<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsGetUserAgent">cupsGetUserAgent</a></h3>
4979<p class="description">Return the default HTTP User-Agent string.</p>
4980<p class="code">
0350eba5 4981<span class="reserved">const</span> <span class="reserved">char</span> *cupsGetUserAgent(<span class="reserved">void</span>);</p>
af268786
MS
4982<h4 class="returnvalue">Return Value</h4>
4983<p class="description">User-Agent string</p>
4984<h3 class="function"><a id="cupsHMACData">cupsHMACData</a></h3>
4985<p class="description">Perform a HMAC function on the given data.</p>
4986<p class="code">
0350eba5 4987ssize_t cupsHMACData(<span class="reserved">const</span> <span class="reserved">char</span> *algorithm, <span class="reserved">const</span> <span class="reserved">unsigned</span> <span class="reserved">char</span> *key, size_t keylen, <span class="reserved">const</span> <span class="reserved">void</span> *data, size_t datalen, <span class="reserved">unsigned</span> <span class="reserved">char</span> *hmac, size_t hmacsize);</p>
98d88c8d
MS
4988<h4 class="parameters">Parameters</h4>
4989<table class="list"><tbody>
af268786
MS
4990<tr><th>algorithm</th>
4991<td class="description">Hash algorithm</td></tr>
4992<tr><th>key</th>
4993<td class="description">Key</td></tr>
4994<tr><th>keylen</th>
4995<td class="description">Length of key</td></tr>
4996<tr><th>data</th>
4997<td class="description">Data to hash</td></tr>
4998<tr><th>datalen</th>
4999<td class="description">Length of data to hash</td></tr>
5000<tr><th>hmac</th>
5001<td class="description">HMAC buffer</td></tr>
5002<tr><th>hmacsize</th>
5003<td class="description">Size of HMAC buffer</td></tr>
98d88c8d 5004</tbody></table>
798d6e29 5005<h4 class="returnvalue">Return Value</h4>
af268786
MS
5006<p class="description">The length of the HMAC or <code>-1</code> on error</p>
5007<h4 class="discussion">Discussion</h4>
5008<p class="discussion">This function performs a HMAC function on the given data with the given key.
5009The &quot;algorithm&quot; argument can be any of the registered, non-deprecated IPP
5010hash algorithms for the &quot;job-password-encryption&quot; attribute, including
5011&quot;sha&quot; for SHA-1, &quot;sha2-256&quot; for SHA2-256, etc.<br>
5012<br>
5013The &quot;hmac&quot; argument points to a buffer of &quot;hmacsize&quot; bytes and should be at
5014least 64 bytes in length for all of the supported algorithms.<br>
5015<br>
5016The returned HMAC is binary data.</p>
5017<h3 class="function"><a id="cupsHashData">cupsHashData</a></h3>
5018<p class="description">Perform a hash function on the given data.</p>
ddf2ec73 5019<p class="code">
0350eba5 5020ssize_t cupsHashData(<span class="reserved">const</span> <span class="reserved">char</span> *algorithm, <span class="reserved">const</span> <span class="reserved">void</span> *data, size_t datalen, <span class="reserved">unsigned</span> <span class="reserved">char</span> *hash, size_t hashsize);</p>
ddf2ec73
MS
5021<h4 class="parameters">Parameters</h4>
5022<table class="list"><tbody>
af268786
MS
5023<tr><th>algorithm</th>
5024<td class="description">Algorithm name</td></tr>
5025<tr><th>data</th>
5026<td class="description">Data to hash</td></tr>
5027<tr><th>datalen</th>
5028<td class="description">Length of data to hash</td></tr>
5029<tr><th>hash</th>
5030<td class="description">Hash buffer</td></tr>
5031<tr><th>hashsize</th>
5032<td class="description">Size of hash buffer</td></tr>
ddf2ec73
MS
5033</tbody></table>
5034<h4 class="returnvalue">Return Value</h4>
af268786
MS
5035<p class="description">Size of hash or -1 on error</p>
5036<h4 class="discussion">Discussion</h4>
5037<p class="discussion">This function performs a hash function on the given data. The &quot;algorithm&quot;
5038argument can be any of the registered, non-deprecated IPP hash algorithms for
5039the &quot;job-password-encryption&quot; attribute, including &quot;sha&quot; for SHA-1,
5040&quot;sha2-256&quot; for SHA2-256, etc.<br>
5041<br>
5042The &quot;hash&quot; argument points to a buffer of &quot;hashsize&quot; bytes and should be at
5043least 64 bytes in length for all of the supported algorithms.<br>
5044<br>
5045The returned hash is binary data.</p>
5046<h3 class="function"><a id="cupsHashString">cupsHashString</a></h3>
5047<p class="description">Format a hash value as a hexadecimal string.</p>
98d88c8d 5048<p class="code">
0350eba5 5049<span class="reserved">const</span> <span class="reserved">char</span> *cupsHashString(<span class="reserved">const</span> <span class="reserved">unsigned</span> <span class="reserved">char</span> *hash, size_t hashsize, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
98d88c8d
MS
5050<h4 class="parameters">Parameters</h4>
5051<table class="list"><tbody>
af268786
MS
5052<tr><th>hash</th>
5053<td class="description">Hash</td></tr>
5054<tr><th>hashsize</th>
5055<td class="description">Size of hash</td></tr>
5056<tr><th>buffer</th>
5057<td class="description">String buffer</td></tr>
5058<tr><th>bufsize</th>
5059<td class="description">Size of string buffer</td></tr>
98d88c8d 5060</tbody></table>
b47dab17 5061<h4 class="returnvalue">Return Value</h4>
af268786
MS
5062<p class="description">Formatted string</p>
5063<h4 class="discussion">Discussion</h4>
5064<p class="discussion">The passed buffer must be at least 2 * hashsize + 1 characters in length.</p>
0350eba5
MS
5065<h3 class="function"><a id="cupsJSONAdd">cupsJSONAdd</a></h3>
5066<p class="description">Add a node to a JSON node.</p>
5067<p class="code">
5068<span class="reserved">void</span> cupsJSONAdd(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <a href="#cups_json_t">cups_json_t</a> *node);</p>
5069<h4 class="parameters">Parameters</h4>
5070<table class="list"><tbody>
5071<tr><th>parent</th>
5072<td class="description">Parent JSON node</td></tr>
5073<tr><th>after</th>
5074<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
5075<tr><th>node</th>
5076<td class="description">JSON node to add</td></tr>
5077</tbody></table>
5078<h4 class="discussion">Discussion</h4>
5079<p class="discussion">This function adds an existing JSON node as a child of other JSON node.
5080The &quot;parent&quot; argument specifies the node to add to. The &quot;after&quot; argument
5081specifies a child of the parent node or <code>NULL</code> to append to the end of the
5082children.<br>
5083<br>
5084Note: The node being added must not already be the child of another parent.</p>
af268786
MS
5085<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONDelete">cupsJSONDelete</a></h3>
5086<p class="description">Delete a JSON node and all of its children.</p>
98d88c8d 5087<p class="code">
0350eba5 5088<span class="reserved">void</span> cupsJSONDelete(<a href="#cups_json_t">cups_json_t</a> *json);</p>
af268786
MS
5089<h4 class="parameters">Parameters</h4>
5090<table class="list"><tbody>
5091<tr><th>json</th>
5092<td class="description">JSON node</td></tr>
5093</tbody></table>
5094<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONExportFile">cupsJSONExportFile</a></h3>
5095<p class="description">Save a JSON node tree to a file.</p>
5096<p class="code">
0350eba5 5097<span class="reserved">bool</span> cupsJSONExportFile(<a href="#cups_json_t">cups_json_t</a> *json, <span class="reserved">const</span> <span class="reserved">char</span> *filename);</p>
af268786
MS
5098<h4 class="parameters">Parameters</h4>
5099<table class="list"><tbody>
5100<tr><th>json</th>
5101<td class="description">JSON root node</td></tr>
5102<tr><th>filename</th>
5103<td class="description">JSON filename</td></tr>
5104</tbody></table>
b47dab17 5105<h4 class="returnvalue">Return Value</h4>
af268786
MS
5106<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
5107<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONExportString">cupsJSONExportString</a></h3>
5108<p class="description">Save a JSON node tree to a string.</p>
b47dab17 5109<p class="code">
0350eba5 5110<span class="reserved">char</span> *cupsJSONExportString(<a href="#cups_json_t">cups_json_t</a> *json);</p>
af268786
MS
5111<h4 class="parameters">Parameters</h4>
5112<table class="list"><tbody>
5113<tr><th>json</th>
5114<td class="description">JSON root node</td></tr>
5115</tbody></table>
b47dab17 5116<h4 class="returnvalue">Return Value</h4>
af268786
MS
5117<p class="description">JSON string or <code>NULL</code> on error</p>
5118<h4 class="discussion">Discussion</h4>
5119<p class="discussion">This function saves a JSON node tree to an allocated string. The resulting
5120string must be freed using the <code>free</code> function.
5121
5122</p>
5123<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONFind">cupsJSONFind</a></h3>
5124<p class="description">Find the value(s) associated with a given key.</p>
b47dab17 5125<p class="code">
0350eba5 5126<a href="#cups_json_t">cups_json_t</a> *cupsJSONFind(<a href="#cups_json_t">cups_json_t</a> *json, <span class="reserved">const</span> <span class="reserved">char</span> *key);</p>
af268786
MS
5127<h4 class="parameters">Parameters</h4>
5128<table class="list"><tbody>
5129<tr><th>json</th>
5130<td class="description">JSON object node</td></tr>
5131<tr><th>key</th>
5132<td class="description">Object key</td></tr>
5133</tbody></table>
b47dab17 5134<h4 class="returnvalue">Return Value</h4>
af268786
MS
5135<p class="description">JSON value or <code>NULL</code></p>
5136<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetChild">cupsJSONGetChild</a></h3>
5137<p class="description">Get the first child node of an array or object node.</p>
b47dab17 5138<p class="code">
af268786 5139<a href="#cups_json_t">cups_json_t</a> *cupsJSONGetChild(<a href="#cups_json_t">cups_json_t</a> *json, size_t n);</p>
98d88c8d
MS
5140<h4 class="parameters">Parameters</h4>
5141<table class="list"><tbody>
af268786
MS
5142<tr><th>json</th>
5143<td class="description">JSON array or object node</td></tr>
5144<tr><th>n</th>
5145<td class="description">Child node number (starting at <code>0</code>)</td></tr>
98d88c8d 5146</tbody></table>
b47dab17 5147<h4 class="returnvalue">Return Value</h4>
af268786
MS
5148<p class="description">First child node or <code>NULL</code></p>
5149<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetCount">cupsJSONGetCount</a></h3>
5150<p class="description">Get the number of child nodes.</p>
798d6e29 5151<p class="code">
af268786 5152size_t cupsJSONGetCount(<a href="#cups_json_t">cups_json_t</a> *json);</p>
b47dab17
MS
5153<h4 class="parameters">Parameters</h4>
5154<table class="list"><tbody>
af268786
MS
5155<tr><th>json</th>
5156<td class="description">JSON array or object node</td></tr>
b47dab17 5157</tbody></table>
798d6e29 5158<h4 class="returnvalue">Return Value</h4>
af268786
MS
5159<p class="description">Number of child nodes</p>
5160<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetKey">cupsJSONGetKey</a></h3>
5161<p class="description">Get the key string, if any.</p>
798d6e29 5162<p class="code">
0350eba5 5163<span class="reserved">const</span> <span class="reserved">char</span> *cupsJSONGetKey(<a href="#cups_json_t">cups_json_t</a> *json);</p>
98d88c8d
MS
5164<h4 class="parameters">Parameters</h4>
5165<table class="list"><tbody>
af268786
MS
5166<tr><th>json</th>
5167<td class="description">JSON string node</td></tr>
98d88c8d 5168</tbody></table>
798d6e29 5169<h4 class="returnvalue">Return Value</h4>
af268786
MS
5170<p class="description">String value</p>
5171<h4 class="discussion">Discussion</h4>
5172<p class="discussion">This function returns the key string for a JSON key node or <code>NULL</code> if
5173the node is not a key.
5174
5175</p>
5176<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetNumber">cupsJSONGetNumber</a></h3>
5177<p class="description">Get the number value, if any.</p>
798d6e29 5178<p class="code">
0350eba5 5179<span class="reserved">double</span> cupsJSONGetNumber(<a href="#cups_json_t">cups_json_t</a> *json);</p>
98d88c8d
MS
5180<h4 class="parameters">Parameters</h4>
5181<table class="list"><tbody>
af268786
MS
5182<tr><th>json</th>
5183<td class="description">JSON number node</td></tr>
98d88c8d 5184</tbody></table>
798d6e29 5185<h4 class="returnvalue">Return Value</h4>
af268786 5186<p class="description">Number value</p>
798d6e29 5187<h4 class="discussion">Discussion</h4>
af268786
MS
5188<p class="discussion">This function returns the number value for a JSON number node or <code>0.0</code> if
5189the node is not a number.
798d6e29
MS
5190
5191</p>
af268786
MS
5192<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetParent">cupsJSONGetParent</a></h3>
5193<p class="description">Get the parent node, if any.</p>
798d6e29 5194<p class="code">
af268786 5195<a href="#cups_json_t">cups_json_t</a> *cupsJSONGetParent(<a href="#cups_json_t">cups_json_t</a> *json);</p>
98d88c8d
MS
5196<h4 class="parameters">Parameters</h4>
5197<table class="list"><tbody>
af268786
MS
5198<tr><th>json</th>
5199<td class="description">JSON node</td></tr>
98d88c8d 5200</tbody></table>
798d6e29 5201<h4 class="returnvalue">Return Value</h4>
af268786
MS
5202<p class="description">Parent node or <code>NULL</code> if none</p>
5203<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetSibling">cupsJSONGetSibling</a></h3>
5204<p class="description">Get the next sibling node, if any.</p>
5205<p class="code">
5206<a href="#cups_json_t">cups_json_t</a> *cupsJSONGetSibling(<a href="#cups_json_t">cups_json_t</a> *json);</p>
5207<h4 class="parameters">Parameters</h4>
5208<table class="list"><tbody>
5209<tr><th>json</th>
5210<td class="description">JSON node</td></tr>
5211</tbody></table>
5212<h4 class="returnvalue">Return Value</h4>
5213<p class="description">Sibling node or <code>NULL</code> if none</p>
5214<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetString">cupsJSONGetString</a></h3>
5215<p class="description">Get the string value, if any.</p>
5216<p class="code">
0350eba5 5217<span class="reserved">const</span> <span class="reserved">char</span> *cupsJSONGetString(<a href="#cups_json_t">cups_json_t</a> *json);</p>
af268786
MS
5218<h4 class="parameters">Parameters</h4>
5219<table class="list"><tbody>
5220<tr><th>json</th>
5221<td class="description">JSON string node</td></tr>
5222</tbody></table>
5223<h4 class="returnvalue">Return Value</h4>
5224<p class="description">String value</p>
798d6e29 5225<h4 class="discussion">Discussion</h4>
af268786
MS
5226<p class="discussion">This function returns the string value for a JSON string node or <code>NULL</code> if
5227the node is not a string.
798d6e29
MS
5228
5229</p>
af268786
MS
5230<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONGetType">cupsJSONGetType</a></h3>
5231<p class="description">Get the type of a JSON node.</p>
798d6e29 5232<p class="code">
af268786 5233<a href="#cups_jtype_t">cups_jtype_t</a> cupsJSONGetType(<a href="#cups_json_t">cups_json_t</a> *json);</p>
98d88c8d
MS
5234<h4 class="parameters">Parameters</h4>
5235<table class="list"><tbody>
af268786
MS
5236<tr><th>json</th>
5237<td class="description">JSON node</td></tr>
98d88c8d 5238</tbody></table>
798d6e29 5239<h4 class="returnvalue">Return Value</h4>
af268786
MS
5240<p class="description">JSON node type</p>
5241<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONImportFile">cupsJSONImportFile</a></h3>
5242<p class="description">Load a JSON object file.</p>
5243<p class="code">
0350eba5 5244<a href="#cups_json_t">cups_json_t</a> *cupsJSONImportFile(<span class="reserved">const</span> <span class="reserved">char</span> *filename);</p>
af268786
MS
5245<h4 class="parameters">Parameters</h4>
5246<table class="list"><tbody>
5247<tr><th>filename</th>
5248<td class="description">JSON filename</td></tr>
5249</tbody></table>
5250<h4 class="returnvalue">Return Value</h4>
5251<p class="description">Root JSON object node</p>
5252<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONImportString">cupsJSONImportString</a></h3>
5253<p class="description">Load a JSON object from a string.</p>
5254<p class="code">
0350eba5 5255<a href="#cups_json_t">cups_json_t</a> *cupsJSONImportString(<span class="reserved">const</span> <span class="reserved">char</span> *s);</p>
af268786
MS
5256<h4 class="parameters">Parameters</h4>
5257<table class="list"><tbody>
5258<tr><th>s</th>
5259<td class="description">JSON string</td></tr>
5260</tbody></table>
5261<h4 class="returnvalue">Return Value</h4>
5262<p class="description">Root JSON object node</p>
5263<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONImportURL">cupsJSONImportURL</a></h3>
5264<p class="description">Load a JSON object from a URL.</p>
5265<p class="code">
0350eba5 5266<a href="#cups_json_t">cups_json_t</a> *cupsJSONImportURL(<span class="reserved">const</span> <span class="reserved">char</span> *url, time_t *last_modified);</p>
af268786
MS
5267<h4 class="parameters">Parameters</h4>
5268<table class="list"><tbody>
5269<tr><th>url</th>
5270<td class="description">URL</td></tr>
5271<tr><th>last_modified</th>
5272<td class="description">Last modified date/time or <code>NULL</code></td></tr>
5273</tbody></table>
5274<h4 class="returnvalue">Return Value</h4>
5275<p class="description">Root JSON object node</p>
798d6e29 5276<h4 class="discussion">Discussion</h4>
af268786
MS
5277<p class="discussion">This function loads a JSON object from a URL. The &quot;url&quot; can be a &quot;http:&quot; or
5278&quot;https:&quot; URL. The &quot;last_modified&quot; argument provides a pointer to a <code>time_t</code>
5279variable with the last modified date and time from a previous load. If
5280<code>NULL</code> or the variable has a value of 0, the JSON is loaded unconditionally
5281from the URL.<br>
5282<br>
5283On success, a pointer to the root JSON object node is returned and the
5284&quot;last_modified&quot; variable, if not <code>NULL</code>, is updated to the Last-Modified
5285date and time returned by the server. Otherwise, <code>NULL</code> is returned with
5286the <a href="#cupsGetError"><code>cupsGetError</code></a> value set to <code>IPP_STATUS_OK_EVENTS_COMPLETE</code> if
5287the JSON data has not been updated since the &quot;last_modified&quot; date and time
5288or a suitable <code>IPP_STATUS_ERROR_</code> value if an error occurred.
798d6e29
MS
5289
5290</p>
af268786
MS
5291<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONNew">cupsJSONNew</a></h3>
5292<p class="description">Create a new JSON node.</p>
5293<p class="code">
5294<a href="#cups_json_t">cups_json_t</a> *cupsJSONNew(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <a href="#cups_jtype_t">cups_jtype_t</a> type);</p>
5295<h4 class="parameters">Parameters</h4>
5296<table class="list"><tbody>
5297<tr><th>parent</th>
5298<td class="description">Parent JSON node or <code>NULL</code> for a root node</td></tr>
5299<tr><th>after</th>
5300<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
5301<tr><th>type</th>
5302<td class="description">JSON node type</td></tr>
5303</tbody></table>
5304<h4 class="returnvalue">Return Value</h4>
5305<p class="description">JSON node</p>
5306<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONNewKey">cupsJSONNewKey</a></h3>
5307<p class="description">Create a new JSON key node.</p>
5308<p class="code">
0350eba5 5309<a href="#cups_json_t">cups_json_t</a> *cupsJSONNewKey(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
5310<h4 class="parameters">Parameters</h4>
5311<table class="list"><tbody>
5312<tr><th>parent</th>
5313<td class="description">Parent JSON node or <code>NULL</code> for a root node</td></tr>
5314<tr><th>after</th>
5315<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
5316<tr><th>value</th>
5317<td class="description">Key string</td></tr>
5318</tbody></table>
5319<h4 class="returnvalue">Return Value</h4>
5320<p class="description">JSON node</p>
5321<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONNewNumber">cupsJSONNewNumber</a></h3>
5322<p class="description">Create a new JSON number node.</p>
5323<p class="code">
0350eba5 5324<a href="#cups_json_t">cups_json_t</a> *cupsJSONNewNumber(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <span class="reserved">double</span> value);</p>
af268786
MS
5325<h4 class="parameters">Parameters</h4>
5326<table class="list"><tbody>
5327<tr><th>parent</th>
5328<td class="description">Parent JSON node or <code>NULL</code> for a root node</td></tr>
5329<tr><th>after</th>
5330<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
5331<tr><th>value</th>
5332<td class="description">Number value</td></tr>
5333</tbody></table>
5334<h4 class="returnvalue">Return Value</h4>
5335<p class="description">JSON node</p>
5336<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJSONNewString">cupsJSONNewString</a></h3>
5337<p class="description">Create a new JSON string node.</p>
5338<p class="code">
0350eba5 5339<a href="#cups_json_t">cups_json_t</a> *cupsJSONNewString(<a href="#cups_json_t">cups_json_t</a> *parent, <a href="#cups_json_t">cups_json_t</a> *after, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
5340<h4 class="parameters">Parameters</h4>
5341<table class="list"><tbody>
5342<tr><th>parent</th>
5343<td class="description">Parent JSON node or <code>NULL</code> for a root node</td></tr>
5344<tr><th>after</th>
5345<td class="description">Previous sibling node or <code>NULL</code> to append to the end</td></tr>
5346<tr><th>value</th>
5347<td class="description">String value</td></tr>
5348</tbody></table>
5349<h4 class="returnvalue">Return Value</h4>
5350<p class="description">JSON node</p>
5351<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTDelete">cupsJWTDelete</a></h3>
5352<p class="description">Free the memory used for a JSON Web Token.</p>
5353<p class="code">
0350eba5 5354<span class="reserved">void</span> cupsJWTDelete(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt);</p>
af268786
MS
5355<h4 class="parameters">Parameters</h4>
5356<table class="list"><tbody>
5357<tr><th>jwt</th>
5358<td class="description">JWT object</td></tr>
5359</tbody></table>
5360<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTExportString">cupsJWTExportString</a></h3>
5361<p class="description">Export a JWT with the JWS Compact or JWS JSON (Flattened) Serialization format.</p>
798d6e29 5362<p class="code">
0350eba5 5363<span class="reserved">char</span> *cupsJWTExportString(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <a href="#cups_jws_format_t">cups_jws_format_t</a> format);</p>
98d88c8d
MS
5364<h4 class="parameters">Parameters</h4>
5365<table class="list"><tbody>
af268786
MS
5366<tr><th>jwt</th>
5367<td class="description">JWT object</td></tr>
5368<tr><th>format</th>
5369<td class="description">JWS serialization format</td></tr>
98d88c8d 5370</tbody></table>
798d6e29 5371<h4 class="returnvalue">Return Value</h4>
af268786 5372<p class="description">JWT/JWS Serialization string</p>
798d6e29 5373<h4 class="discussion">Discussion</h4>
af268786
MS
5374<p class="discussion">This function exports a JWT to a JWS Compact or JWS JSON Serialization
5375string. The JSON output is always the &quot;flattened&quot; format since the JWT
5376only contains a single signature.<br>
5377<br>
5378The return value must be freed using the <code>free</code> function.
798d6e29 5379
798d6e29 5380</p>
af268786
MS
5381<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetAlgorithm">cupsJWTGetAlgorithm</a></h3>
5382<p class="description">Get the signature algorithm used by a JSON Web Token.</p>
798d6e29 5383<p class="code">
af268786 5384<a href="#cups_jwa_t">cups_jwa_t</a> cupsJWTGetAlgorithm(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt);</p>
798d6e29 5385<h4 class="parameters">Parameters</h4>
98d88c8d 5386<table class="list"><tbody>
af268786
MS
5387<tr><th>jwt</th>
5388<td class="description">JWT object</td></tr>
98d88c8d 5389</tbody></table>
af268786
MS
5390<h4 class="returnvalue">Return Value</h4>
5391<p class="description">Signature algorithm</p>
5392<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetClaimNumber">cupsJWTGetClaimNumber</a></h3>
5393<p class="description">Get the number value of a claim.</p>
798d6e29 5394<p class="code">
0350eba5 5395<span class="reserved">double</span> cupsJWTGetClaimNumber(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim);</p>
798d6e29 5396<h4 class="parameters">Parameters</h4>
98d88c8d 5397<table class="list"><tbody>
af268786
MS
5398<tr><th>jwt</th>
5399<td class="description">JWT object</td></tr>
5400<tr><th>claim</th>
5401<td class="description">Claim name</td></tr>
98d88c8d 5402</tbody></table>
af268786
MS
5403<h4 class="returnvalue">Return Value</h4>
5404<p class="description">Number value</p>
5405<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetClaimString">cupsJWTGetClaimString</a></h3>
5406<p class="description">Get the string value of a claim.</p>
98d88c8d 5407<p class="code">
0350eba5 5408<span class="reserved">const</span> <span class="reserved">char</span> *cupsJWTGetClaimString(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim);</p>
98d88c8d
MS
5409<h4 class="parameters">Parameters</h4>
5410<table class="list"><tbody>
af268786
MS
5411<tr><th>jwt</th>
5412<td class="description">JWT object</td></tr>
5413<tr><th>claim</th>
5414<td class="description">Claim name</td></tr>
98d88c8d 5415</tbody></table>
af268786
MS
5416<h4 class="returnvalue">Return Value</h4>
5417<p class="description">String value</p>
5418<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetClaimType">cupsJWTGetClaimType</a></h3>
5419<p class="description">Get the value type of a claim.</p>
798d6e29 5420<p class="code">
0350eba5 5421<a href="#cups_jtype_t">cups_jtype_t</a> cupsJWTGetClaimType(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim);</p>
98d88c8d
MS
5422<h4 class="parameters">Parameters</h4>
5423<table class="list"><tbody>
af268786
MS
5424<tr><th>jwt</th>
5425<td class="description">JWT object</td></tr>
5426<tr><th>claim</th>
5427<td class="description">Claim name</td></tr>
98d88c8d 5428</tbody></table>
798d6e29 5429<h4 class="returnvalue">Return Value</h4>
af268786
MS
5430<p class="description">JSON value type</p>
5431<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetClaimValue">cupsJWTGetClaimValue</a></h3>
5432<p class="description">Get the value node of a claim.</p>
798d6e29 5433<p class="code">
0350eba5 5434<a href="#cups_json_t">cups_json_t</a> *cupsJWTGetClaimValue(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim);</p>
98d88c8d
MS
5435<h4 class="parameters">Parameters</h4>
5436<table class="list"><tbody>
af268786
MS
5437<tr><th>jwt</th>
5438<td class="description">JWT object</td></tr>
5439<tr><th>claim</th>
5440<td class="description">Claim name</td></tr>
98d88c8d 5441</tbody></table>
798d6e29 5442<h4 class="returnvalue">Return Value</h4>
af268786
MS
5443<p class="description">JSON value node</p>
5444<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetClaims">cupsJWTGetClaims</a></h3>
5445<p class="description">Get the JWT claims as a JSON object.</p>
798d6e29 5446<p class="code">
af268786 5447<a href="#cups_json_t">cups_json_t</a> *cupsJWTGetClaims(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt);</p>
98d88c8d
MS
5448<h4 class="parameters">Parameters</h4>
5449<table class="list"><tbody>
af268786
MS
5450<tr><th>jwt</th>
5451<td class="description">JWT object</td></tr>
98d88c8d 5452</tbody></table>
798d6e29 5453<h4 class="returnvalue">Return Value</h4>
af268786
MS
5454<p class="description">JSON object</p>
5455<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetHeaderNumber">cupsJWTGetHeaderNumber</a></h3>
5456<p class="description">Get the number value of a protected header.</p>
798d6e29 5457<p class="code">
0350eba5 5458<span class="reserved">double</span> cupsJWTGetHeaderNumber(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header);</p>
98d88c8d
MS
5459<h4 class="parameters">Parameters</h4>
5460<table class="list"><tbody>
af268786
MS
5461<tr><th>jwt</th>
5462<td class="description">JWT object</td></tr>
5463<tr><th>header</th>
5464<td class="description">Header name</td></tr>
98d88c8d 5465</tbody></table>
798d6e29 5466<h4 class="returnvalue">Return Value</h4>
af268786
MS
5467<p class="description">Number value</p>
5468<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetHeaderString">cupsJWTGetHeaderString</a></h3>
5469<p class="description">Get the string value of a protected header.</p>
798d6e29 5470<p class="code">
0350eba5 5471<span class="reserved">const</span> <span class="reserved">char</span> *cupsJWTGetHeaderString(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header);</p>
98d88c8d
MS
5472<h4 class="parameters">Parameters</h4>
5473<table class="list"><tbody>
af268786
MS
5474<tr><th>jwt</th>
5475<td class="description">JWT object</td></tr>
5476<tr><th>header</th>
5477<td class="description">Header name</td></tr>
98d88c8d 5478</tbody></table>
798d6e29 5479<h4 class="returnvalue">Return Value</h4>
af268786
MS
5480<p class="description">String value</p>
5481<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetHeaderType">cupsJWTGetHeaderType</a></h3>
5482<p class="description">Get the value type of a protected header.</p>
798d6e29 5483<p class="code">
0350eba5 5484<a href="#cups_jtype_t">cups_jtype_t</a> cupsJWTGetHeaderType(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header);</p>
98d88c8d
MS
5485<h4 class="parameters">Parameters</h4>
5486<table class="list"><tbody>
af268786
MS
5487<tr><th>jwt</th>
5488<td class="description">JWT object</td></tr>
5489<tr><th>header</th>
5490<td class="description">Header name</td></tr>
98d88c8d 5491</tbody></table>
798d6e29 5492<h4 class="returnvalue">Return Value</h4>
af268786
MS
5493<p class="description">JSON value type</p>
5494<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetHeaderValue">cupsJWTGetHeaderValue</a></h3>
5495<p class="description">Get the value node of a protected header.</p>
798d6e29 5496<p class="code">
0350eba5 5497<a href="#cups_json_t">cups_json_t</a> *cupsJWTGetHeaderValue(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header);</p>
798d6e29 5498<h4 class="parameters">Parameters</h4>
98d88c8d 5499<table class="list"><tbody>
af268786
MS
5500<tr><th>jwt</th>
5501<td class="description">JWT object</td></tr>
5502<tr><th>header</th>
5503<td class="description">Header name</td></tr>
98d88c8d 5504</tbody></table>
798d6e29 5505<h4 class="returnvalue">Return Value</h4>
af268786
MS
5506<p class="description">JSON value node</p>
5507<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTGetHeaders">cupsJWTGetHeaders</a></h3>
5508<p class="description">Get the JWT protected headers as a JSON object.</p>
98d88c8d 5509<p class="code">
af268786 5510<a href="#cups_json_t">cups_json_t</a> *cupsJWTGetHeaders(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt);</p>
98d88c8d
MS
5511<h4 class="parameters">Parameters</h4>
5512<table class="list"><tbody>
af268786
MS
5513<tr><th>jwt</th>
5514<td class="description">JWT object</td></tr>
98d88c8d
MS
5515</tbody></table>
5516<h4 class="returnvalue">Return Value</h4>
af268786
MS
5517<p class="description">JSON object</p>
5518<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTHasValidSignature">cupsJWTHasValidSignature</a></h3>
5519<p class="description">Determine whether the JWT has a valid signature.</p>
798d6e29 5520<p class="code">
0350eba5 5521<span class="reserved">bool</span> cupsJWTHasValidSignature(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <a href="#cups_json_t">cups_json_t</a> *jwk);</p>
98d88c8d
MS
5522<h4 class="parameters">Parameters</h4>
5523<table class="list"><tbody>
af268786
MS
5524<tr><th>jwt</th>
5525<td class="description">JWT object</td></tr>
5526<tr><th>jwk</th>
5527<td class="description">JWK key set</td></tr>
98d88c8d 5528</tbody></table>
798d6e29 5529<h4 class="returnvalue">Return Value</h4>
af268786
MS
5530<p class="description"><code>true</code> if value, <code>false</code> otherwise</p>
5531<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTImportString">cupsJWTImportString</a></h3>
5532<p class="description">Import a JSON Web Token or JSON Web Signature.</p>
798d6e29 5533<p class="code">
0350eba5 5534<a href="#cups_jwt_t">cups_jwt_t</a> *cupsJWTImportString(<span class="reserved">const</span> <span class="reserved">char</span> *s, <a href="#cups_jws_format_t">cups_jws_format_t</a> format);</p>
98d88c8d
MS
5535<h4 class="parameters">Parameters</h4>
5536<table class="list"><tbody>
af268786
MS
5537<tr><th>s</th>
5538<td class="description">JWS string</td></tr>
5539<tr><th>format</th>
5540<td class="description">JWS serialization format</td></tr>
5541</tbody></table>
5542<h4 class="returnvalue">Return Value</h4>
5543<p class="description">JWT object</p>
b6008d6b
MS
5544<h3 class="function"><a id="cupsJWTLoadCredentials">cupsJWTLoadCredentials</a></h3>
5545<p class="description">Load X.509 credentials and private key into a JSON Web Key for signing.</p>
5546<p class="code">
5547<a href="#cups_json_t">cups_json_t</a> *cupsJWTLoadCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name);</p>
5548<h4 class="parameters">Parameters</h4>
5549<table class="list"><tbody>
5550<tr><th>path</th>
5551<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
5552<tr><th>common_name</th>
5553<td class="description">Common name</td></tr>
5554</tbody></table>
5555<h4 class="returnvalue">Return Value</h4>
5556<p class="description">JSON Web Key of <code>NULL</code> on error</p>
af268786
MS
5557<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTMakePrivateKey">cupsJWTMakePrivateKey</a></h3>
5558<p class="description">Make a JSON Web Key for encryption and signing.</p>
5559<p class="code">
5560<a href="#cups_json_t">cups_json_t</a> *cupsJWTMakePrivateKey(<a href="#cups_jwa_t">cups_jwa_t</a> alg);</p>
5561<h4 class="parameters">Parameters</h4>
5562<table class="list"><tbody>
5563<tr><th>alg</th>
5564<td class="description">Signing/encryption algorithm</td></tr>
98d88c8d 5565</tbody></table>
798d6e29 5566<h4 class="returnvalue">Return Value</h4>
af268786 5567<p class="description">Private JSON Web Key or <code>NULL</code> on error</p>
798d6e29 5568<h4 class="discussion">Discussion</h4>
af268786
MS
5569<p class="discussion">This function makes a JSON Web Key (JWK) for the specified JWS/JWE algorithm
5570for use when signing or encrypting JSON Web Tokens. The resulting JWK
5571<em>must not</em> be provided to clients - instead, call <a href="#cupsJWTMakePublicKey"><code>cupsJWTMakePublicKey</code></a>
5572to produce a public key subset suitable for verification and decryption.
798d6e29
MS
5573
5574</p>
af268786
MS
5575<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTMakePublicKey">cupsJWTMakePublicKey</a></h3>
5576<p class="description">Make a JSON Web Key for decryption and verification.</p>
798d6e29 5577<p class="code">
af268786 5578<a href="#cups_json_t">cups_json_t</a> *cupsJWTMakePublicKey(<a href="#cups_json_t">cups_json_t</a> *jwk);</p>
98d88c8d
MS
5579<h4 class="parameters">Parameters</h4>
5580<table class="list"><tbody>
af268786
MS
5581<tr><th>jwk</th>
5582<td class="description">Private JSON Web Key</td></tr>
98d88c8d 5583</tbody></table>
798d6e29 5584<h4 class="returnvalue">Return Value</h4>
af268786 5585<p class="description">Public JSON Web Key or <code>NULL</code> on error</p>
798d6e29 5586<h4 class="discussion">Discussion</h4>
af268786
MS
5587<p class="discussion">This function makes a public JSON Web Key (JWK) from the specified private
5588JWK suitable for use when decrypting or verifying a JWE/JWS message.
798d6e29
MS
5589
5590</p>
af268786
MS
5591<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTNew">cupsJWTNew</a></h3>
5592<p class="description">Create a new, empty JSON Web Token.</p>
798d6e29 5593<p class="code">
05d62fc2 5594<a href="#cups_jwt_t">cups_jwt_t</a> *cupsJWTNew(<span class="reserved">const</span> <span class="reserved">char</span> *type, <a href="#cups_json_t">cups_json_t</a> *claims);</p>
98d88c8d
MS
5595<h4 class="parameters">Parameters</h4>
5596<table class="list"><tbody>
af268786
MS
5597<tr><th>type</th>
5598<td class="description">JWT type or <code>NULL</code> for default (&quot;JWT&quot;)</td></tr>
05d62fc2
MS
5599<tr><th>claims</th>
5600<td class="description">JSON claims or <code>NULL</code> for empty</td></tr>
98d88c8d 5601</tbody></table>
798d6e29 5602<h4 class="returnvalue">Return Value</h4>
af268786
MS
5603<p class="description">JWT object</p>
5604<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetClaimNumber">cupsJWTSetClaimNumber</a></h3>
5605<p class="description">Set a claim number.</p>
798d6e29 5606<p class="code">
0350eba5 5607<span class="reserved">void</span> cupsJWTSetClaimNumber(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim, <span class="reserved">double</span> value);</p>
98d88c8d
MS
5608<h4 class="parameters">Parameters</h4>
5609<table class="list"><tbody>
af268786
MS
5610<tr><th>jwt</th>
5611<td class="description">JWT object</td></tr>
5612<tr><th>claim</th>
5613<td class="description">Claim name</td></tr>
5614<tr><th>value</th>
5615<td class="description">Number value</td></tr>
5616</tbody></table>
5617<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetClaimString">cupsJWTSetClaimString</a></h3>
5618<p class="description">Set a claim string.</p>
5619<p class="code">
0350eba5 5620<span class="reserved">void</span> cupsJWTSetClaimString(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
5621<h4 class="parameters">Parameters</h4>
5622<table class="list"><tbody>
5623<tr><th>jwt</th>
5624<td class="description">JWT object</td></tr>
5625<tr><th>claim</th>
5626<td class="description">Claim name</td></tr>
5627<tr><th>value</th>
5628<td class="description">String value</td></tr>
5629</tbody></table>
5630<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetClaimValue">cupsJWTSetClaimValue</a></h3>
5631<p class="description">Set a claim value.</p>
5632<p class="code">
0350eba5 5633<span class="reserved">void</span> cupsJWTSetClaimValue(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *claim, <a href="#cups_json_t">cups_json_t</a> *value);</p>
af268786
MS
5634<h4 class="parameters">Parameters</h4>
5635<table class="list"><tbody>
5636<tr><th>jwt</th>
5637<td class="description">JWT object</td></tr>
5638<tr><th>claim</th>
5639<td class="description">Claim name</td></tr>
5640<tr><th>value</th>
5641<td class="description">JSON value node</td></tr>
5642</tbody></table>
5643<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetHeaderNumber">cupsJWTSetHeaderNumber</a></h3>
5644<p class="description">Set a protected header number.</p>
5645<p class="code">
0350eba5 5646<span class="reserved">void</span> cupsJWTSetHeaderNumber(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header, <span class="reserved">double</span> value);</p>
af268786
MS
5647<h4 class="parameters">Parameters</h4>
5648<table class="list"><tbody>
5649<tr><th>jwt</th>
5650<td class="description">JWT object</td></tr>
5651<tr><th>header</th>
5652<td class="description">Header name</td></tr>
5653<tr><th>value</th>
5654<td class="description">Number value</td></tr>
5655</tbody></table>
5656<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetHeaderString">cupsJWTSetHeaderString</a></h3>
5657<p class="description">Set a protected header string.</p>
5658<p class="code">
0350eba5 5659<span class="reserved">void</span> cupsJWTSetHeaderString(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
5660<h4 class="parameters">Parameters</h4>
5661<table class="list"><tbody>
5662<tr><th>jwt</th>
5663<td class="description">JWT object</td></tr>
5664<tr><th>header</th>
5665<td class="description">Header name</td></tr>
5666<tr><th>value</th>
5667<td class="description">String value</td></tr>
5668</tbody></table>
5669<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSetHeaderValue">cupsJWTSetHeaderValue</a></h3>
5670<p class="description">Set a protected header value.</p>
5671<p class="code">
0350eba5 5672<span class="reserved">void</span> cupsJWTSetHeaderValue(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <span class="reserved">const</span> <span class="reserved">char</span> *header, <a href="#cups_json_t">cups_json_t</a> *value);</p>
af268786
MS
5673<h4 class="parameters">Parameters</h4>
5674<table class="list"><tbody>
5675<tr><th>jwt</th>
5676<td class="description">JWT object</td></tr>
5677<tr><th>header</th>
5678<td class="description">Header name</td></tr>
5679<tr><th>value</th>
5680<td class="description">JSON value node</td></tr>
5681</tbody></table>
5682<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsJWTSign">cupsJWTSign</a></h3>
5683<p class="description">Sign a JSON Web Token, creating a JSON Web Signature.</p>
5684<p class="code">
0350eba5 5685<span class="reserved">bool</span> cupsJWTSign(<a href="#cups_jwt_t">cups_jwt_t</a> *jwt, <a href="#cups_jwa_t">cups_jwa_t</a> alg, <a href="#cups_json_t">cups_json_t</a> *jwk);</p>
af268786
MS
5686<h4 class="parameters">Parameters</h4>
5687<table class="list"><tbody>
5688<tr><th>jwt</th>
5689<td class="description">JWT object</td></tr>
5690<tr><th>alg</th>
5691<td class="description">Signing algorithm</td></tr>
5692<tr><th>jwk</th>
5693<td class="description">JWK key set</td></tr>
98d88c8d 5694</tbody></table>
798d6e29 5695<h4 class="returnvalue">Return Value</h4>
af268786
MS
5696<p class="description"><code>true</code> on success, <code>false</code> on error</p>
5697<h3 class="function"><a id="cupsLangDefault">cupsLangDefault</a></h3>
5698<p class="description">Return the default language.</p>
5699<p class="code">
0350eba5 5700<a href="#cups_lang_t">cups_lang_t</a> *cupsLangDefault(<span class="reserved">void</span>);</p>
af268786
MS
5701<h4 class="returnvalue">Return Value</h4>
5702<p class="description">Language data</p>
5703<h3 class="function"><a id="cupsLangEncoding">cupsLangEncoding</a></h3>
5704<p class="description">Return the character encoding (us-ascii, etc.)
5705 for the given language.</p>
5706<p class="code">
0350eba5 5707<span class="reserved">const</span> <span class="reserved">char</span> *cupsLangEncoding(<a href="#cups_lang_t">cups_lang_t</a> *lang);</p>
af268786
MS
5708<h4 class="parameters">Parameters</h4>
5709<table class="list"><tbody>
5710<tr><th>lang</th>
5711<td class="description">Language data</td></tr>
5712</tbody></table>
5713<h4 class="returnvalue">Return Value</h4>
5714<p class="description">Character encoding</p>
5715<h3 class="function"><a id="cupsLangFlush">cupsLangFlush</a></h3>
5716<p class="description">Flush all language data out of the cache.</p>
5717<p class="code">
0350eba5 5718<span class="reserved">void</span> cupsLangFlush(<span class="reserved">void</span>);</p>
af268786
MS
5719<h3 class="function"><a id="cupsLangFree">cupsLangFree</a></h3>
5720<p class="description">Free language data.</p>
5721<p class="code">
0350eba5 5722<span class="reserved">void</span> cupsLangFree(<a href="#cups_lang_t">cups_lang_t</a> *lang);</p>
af268786
MS
5723<h4 class="parameters">Parameters</h4>
5724<table class="list"><tbody>
5725<tr><th>lang</th>
5726<td class="description">Language to free</td></tr>
5727</tbody></table>
798d6e29 5728<h4 class="discussion">Discussion</h4>
af268786
MS
5729<p class="discussion">This does not actually free anything; use <a href="#cupsLangFlush"><code>cupsLangFlush</code></a> for that.</p>
5730<h3 class="function"><a id="cupsLangGet">cupsLangGet</a></h3>
5731<p class="description">Get a language.</p>
5732<p class="code">
0350eba5 5733<a href="#cups_lang_t">cups_lang_t</a> *cupsLangGet(<span class="reserved">const</span> <span class="reserved">char</span> *language);</p>
af268786
MS
5734<h4 class="parameters">Parameters</h4>
5735<table class="list"><tbody>
5736<tr><th>language</th>
5737<td class="description">Language or locale</td></tr>
5738</tbody></table>
5739<h4 class="returnvalue">Return Value</h4>
5740<p class="description">Language data</p>
5741<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsLastError">cupsLastError</a></h3>
5742<p class="description">Return the last IPP status code received on the current thread.</p>
5743<p class="code">
0350eba5 5744ipp_status_t cupsLastError(<span class="reserved">void</span>);</p>
af268786
MS
5745<h4 class="returnvalue">Return Value</h4>
5746<p class="description">IPP status code from last request</p>
5747<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsLastErrorString">cupsLastErrorString</a></h3>
5748<p class="description">Return the last IPP status-message received on the current thread.</p>
5749<p class="code">
0350eba5 5750<span class="reserved">const</span> <span class="reserved">char</span> *cupsLastErrorString(<span class="reserved">void</span>);</p>
af268786
MS
5751<h4 class="returnvalue">Return Value</h4>
5752<p class="description">status-message text from last request</p>
b6008d6b 5753<h3 class="function"><span class="info">&#160;CUPS 2.0&#160;</span><a id="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3>
b47dab17 5754<p class="description">Get the localized string for a destination media
af268786 5755 size.</p>
798d6e29 5756<p class="code">
0350eba5 5757<span class="reserved">const</span> <span class="reserved">char</span> *cupsLocalizeDestMedia(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
98d88c8d
MS
5758<h4 class="parameters">Parameters</h4>
5759<table class="list"><tbody>
5760<tr><th>http</th>
b47dab17 5761<td class="description">Connection to destination</td></tr>
98d88c8d 5762<tr><th>dest</th>
b47dab17 5763<td class="description">Destination</td></tr>
98d88c8d 5764<tr><th>dinfo</th>
b47dab17 5765<td class="description">Destination information</td></tr>
98d88c8d 5766<tr><th>flags</th>
b47dab17 5767<td class="description">Media flags</td></tr>
98d88c8d 5768<tr><th>size</th>
b47dab17 5769<td class="description">Media size</td></tr>
98d88c8d 5770</tbody></table>
798d6e29 5771<h4 class="returnvalue">Return Value</h4>
b47dab17 5772<p class="description">Localized string</p>
798d6e29 5773<h4 class="discussion">Discussion</h4>
0350eba5
MS
5774<p class="discussion">This function returns the localized string for the specified media size
5775information.<br>
5776<br>
5777The returned string is stored in the destination information and will become
5778invalid if the destination information is deleted.
5779
5780</p>
5781<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsLocalizeDestMedia2">cupsLocalizeDestMedia2</a></h3>
5782<p class="description">Get the localized string for a destination media.</p>
5783<p class="code">
5784<span class="reserved">const</span> <span class="reserved">char</span> *cupsLocalizeDestMedia2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">unsigned</span> flags, <a href="#cups_media_t">cups_media_t</a> *media);</p>
5785<h4 class="parameters">Parameters</h4>
5786<table class="list"><tbody>
5787<tr><th>http</th>
5788<td class="description">Connection to destination</td></tr>
5789<tr><th>dest</th>
5790<td class="description">Destination</td></tr>
5791<tr><th>dinfo</th>
5792<td class="description">Destination information</td></tr>
5793<tr><th>flags</th>
5794<td class="description">Media flags</td></tr>
5795<tr><th>media</th>
5796<td class="description">Media</td></tr>
5797</tbody></table>
5798<h4 class="returnvalue">Return Value</h4>
5799<p class="description">Localized string</p>
5800<h4 class="discussion">Discussion</h4>
5801<p class="discussion">This function returns the localized string for the specified media
5802information.<br>
5803<br>
5804The returned string is stored in the destination information and will become
798d6e29
MS
5805invalid if the destination information is deleted.
5806
5807</p>
b6008d6b 5808<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3>
b47dab17 5809<p class="description">Get the localized string for a destination
af268786 5810 option.</p>
798d6e29 5811<p class="code">
0350eba5 5812<span class="reserved">const</span> <span class="reserved">char</span> *cupsLocalizeDestOption(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option);</p>
98d88c8d
MS
5813<h4 class="parameters">Parameters</h4>
5814<table class="list"><tbody>
5815<tr><th>http</th>
b47dab17 5816<td class="description">Connection to destination</td></tr>
98d88c8d 5817<tr><th>dest</th>
b47dab17 5818<td class="description">Destination</td></tr>
98d88c8d 5819<tr><th>dinfo</th>
b47dab17 5820<td class="description">Destination information</td></tr>
98d88c8d 5821<tr><th>option</th>
b47dab17 5822<td class="description">Option to localize</td></tr>
98d88c8d 5823</tbody></table>
798d6e29 5824<h4 class="returnvalue">Return Value</h4>
b47dab17 5825<p class="description">Localized string</p>
798d6e29 5826<h4 class="discussion">Discussion</h4>
b47dab17 5827<p class="discussion">The returned string is stored in the destination information and will become
798d6e29
MS
5828invalid if the destination information is deleted.
5829
5830</p>
b6008d6b 5831<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3>
b47dab17 5832<p class="description">Get the localized string for a destination
af268786 5833 option+value pair.</p>
798d6e29 5834<p class="code">
0350eba5 5835<span class="reserved">const</span> <span class="reserved">char</span> *cupsLocalizeDestValue(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo, <span class="reserved">const</span> <span class="reserved">char</span> *option, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
98d88c8d
MS
5836<h4 class="parameters">Parameters</h4>
5837<table class="list"><tbody>
5838<tr><th>http</th>
b47dab17 5839<td class="description">Connection to destination</td></tr>
98d88c8d 5840<tr><th>dest</th>
b47dab17 5841<td class="description">Destination</td></tr>
98d88c8d 5842<tr><th>dinfo</th>
b47dab17 5843<td class="description">Destination information</td></tr>
98d88c8d 5844<tr><th>option</th>
b47dab17 5845<td class="description">Option to localize</td></tr>
98d88c8d 5846<tr><th>value</th>
b47dab17 5847<td class="description">Value to localize</td></tr>
98d88c8d 5848</tbody></table>
798d6e29 5849<h4 class="returnvalue">Return Value</h4>
b47dab17 5850<p class="description">Localized string</p>
798d6e29 5851<h4 class="discussion">Discussion</h4>
b47dab17 5852<p class="discussion">The returned string is stored in the destination information and will become
798d6e29
MS
5853invalid if the destination information is deleted.
5854
5855</p>
af268786
MS
5856<h3 class="function"><a id="cupsMutexDestroy">cupsMutexDestroy</a></h3>
5857<p class="description">Destroy a mutex.</p>
798d6e29 5858<p class="code">
0350eba5 5859<span class="reserved">void</span> cupsMutexDestroy(<a href="#cups_mutex_t">cups_mutex_t</a> *mutex);</p>
98d88c8d
MS
5860<h4 class="parameters">Parameters</h4>
5861<table class="list"><tbody>
af268786
MS
5862<tr><th>mutex</th>
5863<td class="description">Mutex</td></tr>
5864</tbody></table>
5865<h3 class="function"><a id="cupsMutexInit">cupsMutexInit</a></h3>
5866<p class="description">Initialize a mutex.</p>
5867<p class="code">
0350eba5 5868<span class="reserved">void</span> cupsMutexInit(<a href="#cups_mutex_t">cups_mutex_t</a> *mutex);</p>
af268786
MS
5869<h4 class="parameters">Parameters</h4>
5870<table class="list"><tbody>
5871<tr><th>mutex</th>
5872<td class="description">Mutex</td></tr>
5873</tbody></table>
5874<h3 class="function"><a id="cupsMutexLock">cupsMutexLock</a></h3>
5875<p class="description">Lock a mutex.</p>
5876<p class="code">
0350eba5 5877<span class="reserved">void</span> cupsMutexLock(<a href="#cups_mutex_t">cups_mutex_t</a> *mutex);</p>
af268786
MS
5878<h4 class="parameters">Parameters</h4>
5879<table class="list"><tbody>
5880<tr><th>mutex</th>
5881<td class="description">Mutex</td></tr>
5882</tbody></table>
5883<h3 class="function"><a id="cupsMutexUnlock">cupsMutexUnlock</a></h3>
5884<p class="description">Unlock a mutex.</p>
5885<p class="code">
0350eba5 5886<span class="reserved">void</span> cupsMutexUnlock(<a href="#cups_mutex_t">cups_mutex_t</a> *mutex);</p>
af268786
MS
5887<h4 class="parameters">Parameters</h4>
5888<table class="list"><tbody>
5889<tr><th>mutex</th>
5890<td class="description">Mutex</td></tr>
5891</tbody></table>
b6008d6b 5892<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsNotifySubject">cupsNotifySubject</a></h3>
af268786
MS
5893<p class="description">Return the subject for the given notification message.</p>
5894<p class="code">
0350eba5 5895<span class="reserved">char</span> *cupsNotifySubject(<a href="#cups_lang_t">cups_lang_t</a> *lang, <a href="#ipp_t">ipp_t</a> *event);</p>
af268786
MS
5896<h4 class="parameters">Parameters</h4>
5897<table class="list"><tbody>
5898<tr><th>lang</th>
5899<td class="description">Language data</td></tr>
5900<tr><th>event</th>
5901<td class="description">Event data</td></tr>
98d88c8d 5902</tbody></table>
798d6e29 5903<h4 class="returnvalue">Return Value</h4>
af268786
MS
5904<p class="description">Subject string or <code>NULL</code></p>
5905<h4 class="discussion">Discussion</h4>
5906<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
5907
5908</p>
b6008d6b 5909<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsNotifyText">cupsNotifyText</a></h3>
af268786
MS
5910<p class="description">Return the text for the given notification message.</p>
5911<p class="code">
0350eba5 5912<span class="reserved">char</span> *cupsNotifyText(<a href="#cups_lang_t">cups_lang_t</a> *lang, <a href="#ipp_t">ipp_t</a> *event);</p>
af268786
MS
5913<h4 class="parameters">Parameters</h4>
5914<table class="list"><tbody>
5915<tr><th>lang</th>
5916<td class="description">Language data</td></tr>
5917<tr><th>event</th>
5918<td class="description">Event data</td></tr>
5919</tbody></table>
5920<h4 class="returnvalue">Return Value</h4>
5921<p class="description">Message text or <code>NULL</code></p>
5922<h4 class="discussion">Discussion</h4>
5923<p class="discussion">The returned string must be freed by the caller using <code>free</code>.
5924
5925</p>
05d62fc2 5926<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthClearTokens">cupsOAuthClearTokens</a></h3>
0350eba5
MS
5927<p class="description">Clear any cached authorization information.</p>
5928<p class="code">
5929<span class="reserved">void</span> cupsOAuthClearTokens(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri);</p>
5930<h4 class="parameters">Parameters</h4>
5931<table class="list"><tbody>
5932<tr><th>auth_uri</th>
5933<td class="description">Authorization server URI</td></tr>
5934<tr><th>resource_uri</th>
5935<td class="description">Resource server URI</td></tr>
5936</tbody></table>
5937<h4 class="discussion">Discussion</h4>
5938<p class="discussion">This function clears cached authorization information for the given
05d62fc2
MS
5939Authorization Server &quot;auth_uri&quot; and Resource &quot;resource_uri&quot; combination.
5940
5941</p>
5942<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthCopyAccessToken">cupsOAuthCopyAccessToken</a></h3>
0350eba5
MS
5943<p class="description">Get a cached access token.</p>
5944<p class="code">
5945<span class="reserved">char</span> *cupsOAuthCopyAccessToken(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, time_t *access_expires);</p>
5946<h4 class="parameters">Parameters</h4>
5947<table class="list"><tbody>
5948<tr><th>auth_uri</th>
5949<td class="description">Authorization Server URI</td></tr>
5950<tr><th>resource_uri</th>
5951<td class="description">Resource URI</td></tr>
5952<tr><th>access_expires</th>
5953<td class="description">Access expiration time or <code>NULL</code> for don't care</td></tr>
5954</tbody></table>
5955<h4 class="returnvalue">Return Value</h4>
5956<p class="description">Access token</p>
5957<h4 class="discussion">Discussion</h4>
5958<p class="discussion">This function makes a copy of a cached access token and any
5959associated expiration time for the given Authorization Server &quot;auth_uri&quot; and
5960Resource &quot;resource_uri&quot; combination. The returned access token must be freed
5961using the <code>free</code> function.<br>
5962<br>
05d62fc2
MS
5963<code>NULL</code> is returned if no token is cached.
5964
5965</p>
5966<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthCopyClientId">cupsOAuthCopyClientId</a></h3>
0350eba5
MS
5967<p class="description">Get the cached <code>client_id</code> value.</p>
5968<p class="code">
5969<span class="reserved">char</span> *cupsOAuthCopyClientId(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri);</p>
5970<h4 class="parameters">Parameters</h4>
5971<table class="list"><tbody>
5972<tr><th>auth_uri</th>
5973<td class="description">Authorization Server URI</td></tr>
5974<tr><th>redirect_uri</th>
5975<td class="description">Redirection URI</td></tr>
5976</tbody></table>
5977<h4 class="returnvalue">Return Value</h4>
5978<p class="description"><code>client_id</code> value</p>
5979<h4 class="discussion">Discussion</h4>
5980<p class="discussion">This function makes a copy of the cached <code>client_id</code> value for a given
5981Authorization Server &quot;auth_uri&quot; and Redirection URI &quot;resource_uri&quot;. The
5982returned value must be freed using the <code>free</code> function.<br>
5983<br>
05d62fc2
MS
5984<code>NULL</code> is returned if no <code>client_id</code> is cached.
5985
5986</p>
5987<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthCopyRefreshToken">cupsOAuthCopyRefreshToken</a></h3>
0350eba5
MS
5988<p class="description">Get a cached refresh token.</p>
5989<p class="code">
5990<span class="reserved">char</span> *cupsOAuthCopyRefreshToken(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri);</p>
5991<h4 class="parameters">Parameters</h4>
5992<table class="list"><tbody>
5993<tr><th>auth_uri</th>
5994<td class="description">Authorization Server URI</td></tr>
5995<tr><th>resource_uri</th>
5996<td class="description">Resource URI</td></tr>
5997</tbody></table>
5998<h4 class="returnvalue">Return Value</h4>
5999<p class="description">Refresh token</p>
6000<h4 class="discussion">Discussion</h4>
6001<p class="discussion">This function makes a copy of a cached refresh token for the given
6002given Authorization Server &quot;auth_uri&quot; and Resource &quot;resource_uri&quot;
6003combination. The returned refresh token must be freed using the <code>free</code>
6004function.<br>
6005<br>
05d62fc2
MS
6006<code>NULL</code> is returned if no refresh token is cached.
6007
6008</p>
6009<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthCopyUserId">cupsOAuthCopyUserId</a></h3>
0350eba5
MS
6010<p class="description">Get cached user identification information.</p>
6011<p class="code">
6012<a href="#cups_jwt_t">cups_jwt_t</a> *cupsOAuthCopyUserId(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri);</p>
6013<h4 class="parameters">Parameters</h4>
6014<table class="list"><tbody>
6015<tr><th>auth_uri</th>
6016<td class="description">Authorization Server URI</td></tr>
6017<tr><th>resource_uri</th>
6018<td class="description">Resource URI</td></tr>
6019</tbody></table>
6020<h4 class="returnvalue">Return Value</h4>
6021<p class="description">Identification information</p>
6022<h4 class="discussion">Discussion</h4>
6023<p class="discussion">This function makes a copy of cached user identification information for the
6024given Authorization Server &quot;auth_uri&quot; and Resource &quot;resource_uri&quot;
6025combination. The returned user information must be freed using the
6026<a href="#cupsJWTDelete"><code>cupsJWTDelete</code></a> function.<br>
6027<br>
05d62fc2
MS
6028<code>NULL</code> is returned if no identification information is cached.
6029
6030</p>
6031<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetAuthorizationCode">cupsOAuthGetAuthorizationCode</a></h3>
0350eba5
MS
6032<p class="description">Authorize access using a web browser.</p>
6033<p class="code">
6034<span class="reserved">char</span> *cupsOAuthGetAuthorizationCode(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, <span class="reserved">const</span> <span class="reserved">char</span> *scopes, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri);</p>
6035<h4 class="parameters">Parameters</h4>
6036<table class="list"><tbody>
6037<tr><th>auth_uri</th>
6038<td class="description">Authorization Server URI</td></tr>
6039<tr><th>metadata</th>
6040<td class="description">Authorization Server metadata</td></tr>
6041<tr><th>resource_uri</th>
6042<td class="description">Resource URI</td></tr>
6043<tr><th>scopes</th>
6044<td class="description">Space-delimited scopes</td></tr>
6045<tr><th>redirect_uri</th>
6046<td class="description">Redirect URI or <code>NULL</code> for default</td></tr>
6047</tbody></table>
6048<h4 class="returnvalue">Return Value</h4>
6049<p class="description">Authorization code or <code>NULL</code> on error</p>
6050<h4 class="discussion">Discussion</h4>
6051<p class="discussion">This function performs a local/&quot;native&quot; OAuth authorization flow to obtain an
6052authorization code for use with the <a href="#cupsOAuthGetTokens"><code>cupsOAuthGetTokens</code></a> function.<br>
6053<br>
6054The &quot;auth_uri&quot; parameter specifies the URI for the OAuth Authorization
6055Server. The &quot;metadata&quot; parameter specifies the Authorization Server metadata
6056as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
6057<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
6058<br>
6059The &quot;resource_uri&quot; parameter specifies the URI for a resource (printer, web
6060file, etc.) that you which to access.<br>
6061<br>
6062The &quot;scopes&quot; parameter specifies zero or more whitespace-delimited scope
6063names to request during authorization. The list of supported scope names are
05d62fc2 6064available from the Authorization Server metadata, for example:
0350eba5
MS
6065
6066<pre>
6067cups_json_t *metadata = cupsOAuthGetMetadata(auth_uri);
6068cups_json_t *scopes_supported = cupsJSONFind(metadata, &quot;scopes_supported&quot;);
6069</pre>
6070
05d62fc2
MS
6071The &quot;redirect_uri&quot; parameter specifies a 'http:' URL with a listen address,
6072port, and path to use. If <code>NULL</code>, 127.0.0.1 on a random port is used with a
6073path of &quot;/&quot;.<br>
6074<br>
6075The returned authorization code must be freed using the <code>free</code> function.
6076
6077</p>
6078<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetClientId">cupsOAuthGetClientId</a></h3>
0350eba5
MS
6079<p class="description">Register a client application and get its ID.</p>
6080<p class="code">
6081<span class="reserved">char</span> *cupsOAuthGetClientId(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri, <span class="reserved">const</span> <span class="reserved">char</span> *logo_uri, <span class="reserved">const</span> <span class="reserved">char</span> *tos_uri);</p>
6082<h4 class="parameters">Parameters</h4>
6083<table class="list"><tbody>
6084<tr><th>auth_uri</th>
6085<td class="description">Authorization Server URI</td></tr>
6086<tr><th>metadata</th>
6087<td class="description">Authorization Server metadata</td></tr>
6088<tr><th>redirect_uri</th>
6089<td class="description">Redirection URL</td></tr>
6090<tr><th>logo_uri</th>
6091<td class="description">Logo URL or <code>NULL</code> for none</td></tr>
6092<tr><th>tos_uri</th>
6093<td class="description">Terms-of-service URL or <code>NULL</code> for none</td></tr>
6094</tbody></table>
6095<h4 class="returnvalue">Return Value</h4>
6096<p class="description"><code>client_id</code> string or <code>NULL</code> on error</p>
6097<h4 class="discussion">Discussion</h4>
6098<p class="discussion">This function registers a client application with the specified OAuth
6099Authorization Server.<br>
6100<br>
6101The &quot;auth_uri&quot; parameter specifies the URI for the OAuth Authorization
6102Server. The &quot;metadata&quot; parameter specifies the Authorization Server metadata
6103as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
6104<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
6105<br>
6106The &quot;redirect_uri&quot; argument specifies the URL to use for providing
6107authorization results to a WWW application.<br>
6108<br>
6109The &quot;logo_uri&quot; argument specifies a public URL for the logo of your
6110application, while the &quot;tos_uri&quot; specifies a public URL for the terms of
6111service for your application.<br>
6112<br>
6113The returned &quot;client_id&quot; string must be freed using the <code>free</code> function.<br>
6114<br>
6115<em>Note</em>: This function should only be used to register WWW applications. The
6116<a href="#cupsOAuthGetAuthorizationCode"><code>cupsOAuthGetAuthorizationCode</code></a> function handles registration of
05d62fc2
MS
6117local/&quot;native&quot; applications for you.
6118
6119</p>
6120<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetJWKS">cupsOAuthGetJWKS</a></h3>
6121<p class="description">Get the JWT key set for an Authorization Server.</p>
6122<p class="code">
6123<a href="#cups_json_t">cups_json_t</a> *cupsOAuthGetJWKS(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata);</p>
6124<h4 class="parameters">Parameters</h4>
6125<table class="list"><tbody>
6126<tr><th>auth_uri</th>
6127<td class="description">Authorization server URI</td></tr>
6128<tr><th>metadata</th>
6129<td class="description">Server metadata</td></tr>
6130</tbody></table>
6131<h4 class="returnvalue">Return Value</h4>
6132<p class="description">JWKS or <code>NULL</code> on error</p>
6133<h4 class="discussion">Discussion</h4>
6134<p class="discussion">This function gets the JWT key set for the specified Authorization Server
6135&quot;auth_uri&quot;. The &quot;metadata&quot; value is obtained using the
6136<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a> function. The returned key set is cached
6137per-user for better performance and must be freed using the
6138<a href="#cupsJSONDelete"><code>cupsJSONDelete</code></a> function.<br>
6139<br>
6140The key set is typically used to validate JWT bearer tokens using the
6141<a href="#cupsJWTHasValidSignature"><code>cupsJWTHasValidSignature</code></a> function.
6142
6143</p>
6144<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetMetadata">cupsOAuthGetMetadata</a></h3>
0350eba5
MS
6145<p class="description">Get the metadata for an Authorization Server.</p>
6146<p class="code">
6147<a href="#cups_json_t">cups_json_t</a> *cupsOAuthGetMetadata(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri);</p>
6148<h4 class="parameters">Parameters</h4>
6149<table class="list"><tbody>
6150<tr><th>auth_uri</th>
6151<td class="description">Authorization Server URI</td></tr>
6152</tbody></table>
6153<h4 class="returnvalue">Return Value</h4>
6154<p class="description">JSON metadata or <code>NULL</code> on error</p>
6155<h4 class="discussion">Discussion</h4>
05d62fc2
MS
6156<p class="discussion">This function gets the RFC 8414 or Open ID Connect metadata for the specified
6157OAuth Authorization Server URI &quot;auth_uri&quot;.<br>
0350eba5 6158<br>
05d62fc2
MS
6159The returned metadata is cached per-user for better performance and must be
6160freed using the <a href="#cupsJSONDelete"><code>cupsJSONDelete</code></a> function.
6161
6162</p>
6163<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetTokens">cupsOAuthGetTokens</a></h3>
0350eba5
MS
6164<p class="description">Obtain access and refresh tokens.</p>
6165<p class="code">
6166<span class="reserved">char</span> *cupsOAuthGetTokens(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, <span class="reserved">const</span> <span class="reserved">char</span> *grant_code, <a href="#cups_ogrant_t">cups_ogrant_t</a> grant_type, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri, time_t *access_expires);</p>
6167<h4 class="parameters">Parameters</h4>
6168<table class="list"><tbody>
6169<tr><th>auth_uri</th>
6170<td class="description">Authorization Server URI</td></tr>
6171<tr><th>metadata</th>
6172<td class="description">Authorization Server metadata</td></tr>
6173<tr><th>resource_uri</th>
6174<td class="description">Resource URI</td></tr>
6175<tr><th>grant_code</th>
6176<td class="description">Authorization code or refresh token</td></tr>
6177<tr><th>grant_type</th>
6178<td class="description">Grant code type</td></tr>
6179<tr><th>redirect_uri</th>
6180<td class="description">Redirect URI</td></tr>
6181<tr><th>access_expires</th>
6182<td class="description">Expiration time for access token</td></tr>
6183</tbody></table>
6184<h4 class="returnvalue">Return Value</h4>
6185<p class="description">Access token or <code>NULL</code> on error</p>
6186<h4 class="discussion">Discussion</h4>
6187<p class="discussion">This function obtains a access and refresh tokens from an OAuth Authorization
6188Server. OpenID Authorization Servers also provide user identification
6189information.<br>
6190<br>
6191The &quot;auth_uri&quot; parameter specifies the URI for the OAuth Authorization
6192Server. The &quot;metadata&quot; parameter specifies the Authorization Server metadata
6193as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
6194<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
6195<br>
6196The &quot;resource_uri&quot; parameter specifies the URI for a resource (printer, web
6197file, etc.) that you which to access.<br>
6198<br>
6199The &quot;grant_code&quot; parameter specifies the code or token to use while the
6200&quot;grant_type&quot; parameter specifies the type of code:
6201
6202</p><ul>
6203<li><code>CUPS_OGRANT_AUTHORIZATION_CODE</code>: A user authorization grant code.
6204</li>
6205<li><code>CUPS_OGRANT_DEVICE_CODE</code>: A device authorization grant code.
6206</li>
6207<li><code>CUPS_OGRANT_REFRESH_TOKEN</code>: A refresh token.</li>
6208</ul>
6209<p class="discussion">The &quot;redirect_uri&quot; specifies the redirection URI used to obtain the code. The
6210constant <code>CUPS_OAUTH_REDIRECT_URI</code> should be used for codes obtained using
6211the <a href="#cupsOAuthGetAuthorizationCode"><code>cupsOAuthGetAuthorizationCode</code></a> function.<br>
6212<br>
6213When successful, the access token and expiration time are returned. The
6214access token must be freed using the <code>free</code> function. The new refresh token
6215and any user ID information can be obtained using the
6216<a href="#cupsOAuthCopyRefreshToken"><code>cupsOAuthCopyRefreshToken</code></a> and <a href="#cupsOAuthCopyUserId"><code>cupsOAuthCopyUserId</code></a> functions
05d62fc2
MS
6217respectively.
6218
6219</p>
6220<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthGetUserId">cupsOAuthGetUserId</a></h3>
6221<p class="description">Get the user ID token associated with the given access token.</p>
6222<p class="code">
6223<a href="#cups_jwt_t">cups_jwt_t</a> *cupsOAuthGetUserId(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *access_token);</p>
6224<h4 class="parameters">Parameters</h4>
6225<table class="list"><tbody>
6226<tr><th>auth_uri</th>
6227<td class="description">Authorization Server URL</td></tr>
6228<tr><th>metadata</th>
6229<td class="description">Authorization Server metadata</td></tr>
6230<tr><th>access_token</th>
6231<td class="description">Access (Bearer) token</td></tr>
6232</tbody></table>
6233<h4 class="returnvalue">Return Value</h4>
6234<p class="description">Identification information or <code>NULL</code> if none</p>
6235<h4 class="discussion">Discussion</h4>
6236<p class="discussion">This function retrieves the user ID token associated with a given access
6237token. The user ID information is cached until the token expires to minimize
6238the overhead of communicating with the Authorization Server.
6239
6240</p>
6241<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthMakeAuthorizationURL">cupsOAuthMakeAuthorizationURL</a></h3>
0350eba5
MS
6242<p class="description">Make an authorization URL.</p>
6243<p class="code">
6244<span class="reserved">char</span> *cupsOAuthMakeAuthorizationURL(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <a href="#cups_json_t">cups_json_t</a> *metadata, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, <span class="reserved">const</span> <span class="reserved">char</span> *scopes, <span class="reserved">const</span> <span class="reserved">char</span> *client_id, <span class="reserved">const</span> <span class="reserved">char</span> *code_verifier, <span class="reserved">const</span> <span class="reserved">char</span> *nonce, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri, <span class="reserved">const</span> <span class="reserved">char</span> *state);</p>
6245<h4 class="parameters">Parameters</h4>
6246<table class="list"><tbody>
6247<tr><th>auth_uri</th>
6248<td class="description">Authorization Server URI</td></tr>
6249<tr><th>metadata</th>
6250<td class="description">Authorization Server metadata</td></tr>
6251<tr><th>resource_uri</th>
6252<td class="description">Resource URI</td></tr>
6253<tr><th>scopes</th>
6254<td class="description">Space-delimited scope(s)</td></tr>
6255<tr><th>client_id</th>
6256<td class="description">Client ID</td></tr>
6257<tr><th>code_verifier</th>
6258<td class="description">Code verifier string</td></tr>
6259<tr><th>nonce</th>
6260<td class="description">Nonce</td></tr>
6261<tr><th>redirect_uri</th>
6262<td class="description">Redirection URI</td></tr>
6263<tr><th>state</th>
6264<td class="description">State</td></tr>
6265</tbody></table>
6266<h4 class="returnvalue">Return Value</h4>
6267<p class="description">Authorization URL</p>
6268<h4 class="discussion">Discussion</h4>
6269<p class="discussion">This function makes an authorization URL for the specified authorization
6270server and resource.<br>
6271<br>
6272The &quot;auth_uri&quot; parameter specifies the URI for the OAuth Authorization
6273Server. The &quot;metadata&quot; parameter specifies the Authorization Server metadata
6274as obtained using <a href="#cupsOAuthCopyMetadata"><code>cupsOAuthCopyMetadata</code></a> and/or
6275<a href="#cupsOAuthGetMetadata"><code>cupsOAuthGetMetadata</code></a>.<br>
6276<br>
6277The &quot;resource_uri&quot; parameter specifies the URI for a resource (printer, web
6278file, etc.) that you which to access.<br>
6279<br>
6280The &quot;scopes&quot; parameter specifies zero or more whitespace-delimited scope
6281names to request during authorization. The list of supported scope names are
6282available from the Authorization Server metadata, for example:
6283
6284<pre>
6285cups_json_t *metadata = cupsOAuthGetMetadata(auth_uri);
6286cups_json_t *scopes_supported = cupsJSONFind(metadata, &quot;scopes_supported&quot;);
6287</pre>
6288
6289The &quot;client_id&quot; parameter specifies the client identifier obtained using
6290<a href="#cupsOAuthCopyClientId"><code>cupsOAuthCopyClientId</code></a> and/or <a href="#cupsOAuthGetClientId"><code>cupsOAuthGetClientId</code></a>.<br>
6291<br>
6292The &quot;client_id&quot; parameter is the string returned by
6293<a href="#cupsOAuthCopyClientId"><code>cupsOAuthCopyClientId</code></a> or <a href="#cupsOAuthGetClientId"><code>cupsOAuthGetClientId</code></a>.<br>
6294<br>
6295The &quot;code_verifier&quot; parameter specifies a random Base64URL-encoded string
6296that is used by the Proof Key for Code Exchange [RFC7636] extension to help
6297secure the authorization flow. The <a href="#cupsOAuthMakeBase64Random"><code>cupsOAuthMakeBase64Random</code></a> function
6298can be used to generate this string.<br>
6299<br>
6300The &quot;nonce&quot; parameter specifies a random Base64URL-encoded string that is
6301used by OpenID to validate the ID token. The <a href="#cupsOAuthMakeBase64Random"><code>cupsOAuthMakeBase64Random</code></a>
6302function can be used to generate this string.<br>
6303<br>
6304The &quot;redirect_uri&quot; parameter specifies the URI that will receive the
6305authorization grant code.<br>
6306<br>
6307The &quot;state&quot; parameter is a unique (random) identifier for the authorization
05d62fc2
MS
6308request. It is provided to the redirection URI as a form parameter.
6309
6310</p>
6311<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthMakeBase64Random">cupsOAuthMakeBase64Random</a></h3>
0350eba5
MS
6312<p class="description">Make a random data string.</p>
6313<p class="code">
6314<span class="reserved">char</span> *cupsOAuthMakeBase64Random(size_t len);</p>
6315<h4 class="parameters">Parameters</h4>
6316<table class="list"><tbody>
6317<tr><th>len</th>
6318<td class="description">Number of bytes</td></tr>
6319</tbody></table>
6320<h4 class="returnvalue">Return Value</h4>
6321<p class="description">Random string</p>
6322<h4 class="discussion">Discussion</h4>
6323<p class="discussion">This function creates a string containing random data that has been Base64URL
6324encoded. &quot;len&quot; specifies the number of random bytes to include in the string.
05d62fc2
MS
6325The returned string must be freed using the <code>free</code> function.
6326
6327</p>
6328<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthSaveClientData">cupsOAuthSaveClientData</a></h3>
0350eba5
MS
6329<p class="description">Save client_id and client_secret values.</p>
6330<p class="code">
6331<span class="reserved">void</span> cupsOAuthSaveClientData(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *redirect_uri, <span class="reserved">const</span> <span class="reserved">char</span> *client_id, <span class="reserved">const</span> <span class="reserved">char</span> *client_secret);</p>
6332<h4 class="parameters">Parameters</h4>
6333<table class="list"><tbody>
6334<tr><th>auth_uri</th>
6335<td class="description">Authorization Server URI</td></tr>
6336<tr><th>redirect_uri</th>
6337<td class="description">Redirection URI</td></tr>
6338<tr><th>client_id</th>
6339<td class="description">client_id or <code>NULL</code> to delete</td></tr>
6340<tr><th>client_secret</th>
6341<td class="description">client_secret value or <code>NULL</code> for none</td></tr>
6342</tbody></table>
6343<h4 class="discussion">Discussion</h4>
6344<p class="discussion">This function saves the &quot;client_id&quot; and &quot;client_secret&quot; values for the given
6345Authorization Server &quot;auth_uri&quot; and redirection URI &quot;redirect_uri&quot;. If the
6346&quot;client_id&quot; is <code>NULL</code> then any saved values are deleted from the per-user
05d62fc2
MS
6347store.
6348
6349</p>
6350<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsOAuthSaveTokens">cupsOAuthSaveTokens</a></h3>
0350eba5
MS
6351<p class="description">Save authorization and refresh tokens.</p>
6352<p class="code">
6353<span class="reserved">void</span> cupsOAuthSaveTokens(<span class="reserved">const</span> <span class="reserved">char</span> *auth_uri, <span class="reserved">const</span> <span class="reserved">char</span> *resource_uri, <span class="reserved">const</span> <span class="reserved">char</span> *access_token, time_t access_expires, <span class="reserved">const</span> <span class="reserved">char</span> *user_id, <span class="reserved">const</span> <span class="reserved">char</span> *refresh_token);</p>
6354<h4 class="parameters">Parameters</h4>
6355<table class="list"><tbody>
6356<tr><th>auth_uri</th>
6357<td class="description">Authorization Server URI</td></tr>
6358<tr><th>resource_uri</th>
6359<td class="description">Resource URI</td></tr>
6360<tr><th>access_token</th>
6361<td class="description">Access token or <code>NULL</code> to delete</td></tr>
6362<tr><th>access_expires</th>
6363<td class="description">Access expiration time</td></tr>
6364<tr><th>user_id</th>
6365<td class="description">User ID or <code>NULL</code> to delete</td></tr>
6366<tr><th>refresh_token</th>
6367<td class="description">Refresh token or <code>NULL</code> to delete</td></tr>
6368</tbody></table>
6369<h4 class="discussion">Discussion</h4>
6370<p class="discussion">This function saves the access token &quot;access_token&quot;, user ID &quot;user_id&quot;, and
6371refresh token &quot;refresh_token&quot; values for the given Authorization Server
6372&quot;auth_uri&quot; and resource &quot;resource_uri&quot;. Specifying <code>NULL</code> for any of the
05d62fc2
MS
6373values will delete the corresponding saved values from the per-user store.
6374
6375</p>
798d6e29 6376<h3 class="function"><a id="cupsParseOptions">cupsParseOptions</a></h3>
b47dab17 6377<p class="description">Parse options from a command-line argument.</p>
798d6e29 6378<p class="code">
0350eba5 6379<span class="reserved">int</span> cupsParseOptions(<span class="reserved">const</span> <span class="reserved">char</span> *arg, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
98d88c8d
MS
6380<h4 class="parameters">Parameters</h4>
6381<table class="list"><tbody>
6382<tr><th>arg</th>
b47dab17 6383<td class="description">Argument to parse</td></tr>
98d88c8d 6384<tr><th>num_options</th>
b47dab17 6385<td class="description">Number of options</td></tr>
98d88c8d 6386<tr><th>options</th>
b47dab17 6387<td class="description">Options found</td></tr>
98d88c8d 6388</tbody></table>
798d6e29 6389<h4 class="returnvalue">Return Value</h4>
b47dab17 6390<p class="description">Number of options found</p>
798d6e29 6391<h4 class="discussion">Discussion</h4>
b47dab17 6392<p class="discussion">This function converts space-delimited name/value pairs according
798d6e29
MS
6393to the PAPI text option ABNF specification. Collection values
6394(&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
6395intact - use <code>cupsParseOptions</code> on the value to extract the
6396collection attributes.</p>
0350eba5
MS
6397<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsParseOptions2">cupsParseOptions2</a></h3>
6398<p class="description">Parse options from a command-line argument.</p>
6399<p class="code">
6400<span class="reserved">int</span> cupsParseOptions2(<span class="reserved">const</span> <span class="reserved">char</span> *arg, <span class="reserved">const</span> <span class="reserved">char</span> **end, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
6401<h4 class="parameters">Parameters</h4>
6402<table class="list"><tbody>
6403<tr><th>arg</th>
6404<td class="description">Argument to parse</td></tr>
6405<tr><th>end</th>
6406<td class="description">Pointer to end of options or <code>NULL</code> for &quot;don't care&quot;</td></tr>
6407<tr><th>num_options</th>
6408<td class="description">Number of options</td></tr>
6409<tr><th>options</th>
6410<td class="description">Options found</td></tr>
6411</tbody></table>
6412<h4 class="returnvalue">Return Value</h4>
6413<p class="description">Number of options found</p>
6414<h4 class="discussion">Discussion</h4>
6415<p class="discussion">This function converts space-delimited name/value pairs according
6416to the PAPI text option ABNF specification. Collection values
6417(&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
6418intact - use <code>cupsParseOptions</code> on the value to extract the
6419collection attributes.<br>
6420<br>
6421The &quot;end&quot; argument, if not <code>NULL</code>, receives a pointer to the end of the
6422options.
6423
6424</p>
b6008d6b 6425<h3 class="function"><span class="info">&#160;CUPS 1.1.20&#160;</span><a id="cupsPutFd">cupsPutFd</a></h3>
af268786
MS
6426<p class="description">Put a file on the server.</p>
6427<p class="code">
0350eba5 6428http_status_t cupsPutFd(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">int</span> fd);</p>
af268786
MS
6429<h4 class="parameters">Parameters</h4>
6430<table class="list"><tbody>
6431<tr><th>http</th>
6432<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
6433<tr><th>resource</th>
6434<td class="description">Resource name</td></tr>
6435<tr><th>fd</th>
6436<td class="description">File descriptor</td></tr>
6437</tbody></table>
6438<h4 class="returnvalue">Return Value</h4>
6439<p class="description">HTTP status</p>
6440<h4 class="discussion">Discussion</h4>
6441<p class="discussion">This function returns <code>HTTP_STATUS_CREATED</code> when the file is stored
6442successfully.
6443
6444</p>
b6008d6b 6445<h3 class="function"><span class="info">&#160;CUPS 1.1.20&#160;</span><a id="cupsPutFile">cupsPutFile</a></h3>
af268786
MS
6446<p class="description">Put a file on the server.</p>
6447<p class="code">
0350eba5 6448http_status_t cupsPutFile(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">const</span> <span class="reserved">char</span> *filename);</p>
af268786
MS
6449<h4 class="parameters">Parameters</h4>
6450<table class="list"><tbody>
6451<tr><th>http</th>
6452<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
6453<tr><th>resource</th>
6454<td class="description">Resource name</td></tr>
6455<tr><th>filename</th>
6456<td class="description">Filename</td></tr>
6457</tbody></table>
6458<h4 class="returnvalue">Return Value</h4>
6459<p class="description">HTTP status</p>
6460<h4 class="discussion">Discussion</h4>
6461<p class="discussion">This function returns <code>HTTP_CREATED</code> when the file is stored
6462successfully.
6463
6464</p>
6465<h3 class="function"><a id="cupsRWDestroy">cupsRWDestroy</a></h3>
6466<p class="description">Destroy a reader/writer lock.</p>
6467<p class="code">
0350eba5 6468<span class="reserved">void</span> cupsRWDestroy(<a href="#cups_rwlock_t">cups_rwlock_t</a> *rwlock);</p>
af268786
MS
6469<h4 class="parameters">Parameters</h4>
6470<table class="list"><tbody>
6471<tr><th>rwlock</th>
6472<td class="description">Reader/writer lock</td></tr>
6473</tbody></table>
6474<h3 class="function"><a id="cupsRWInit">cupsRWInit</a></h3>
6475<p class="description">Initialize a reader/writer lock.</p>
6476<p class="code">
0350eba5 6477<span class="reserved">void</span> cupsRWInit(<a href="#cups_rwlock_t">cups_rwlock_t</a> *rwlock);</p>
af268786
MS
6478<h4 class="parameters">Parameters</h4>
6479<table class="list"><tbody>
6480<tr><th>rwlock</th>
6481<td class="description">Reader/writer lock</td></tr>
6482</tbody></table>
6483<h3 class="function"><a id="cupsRWLockRead">cupsRWLockRead</a></h3>
6484<p class="description">Acquire a reader/writer lock for reading.</p>
6485<p class="code">
0350eba5 6486<span class="reserved">void</span> cupsRWLockRead(<a href="#cups_rwlock_t">cups_rwlock_t</a> *rwlock);</p>
af268786
MS
6487<h4 class="parameters">Parameters</h4>
6488<table class="list"><tbody>
6489<tr><th>rwlock</th>
6490<td class="description">Reader/writer lock</td></tr>
6491</tbody></table>
6492<h3 class="function"><a id="cupsRWLockWrite">cupsRWLockWrite</a></h3>
6493<p class="description">Acquire a reader/writer lock for writing.</p>
6494<p class="code">
0350eba5 6495<span class="reserved">void</span> cupsRWLockWrite(<a href="#cups_rwlock_t">cups_rwlock_t</a> *rwlock);</p>
af268786
MS
6496<h4 class="parameters">Parameters</h4>
6497<table class="list"><tbody>
6498<tr><th>rwlock</th>
6499<td class="description">Reader/writer lock</td></tr>
6500</tbody></table>
6501<h3 class="function"><a id="cupsRWUnlock">cupsRWUnlock</a></h3>
6502<p class="description">Release a reader/writer lock.</p>
6503<p class="code">
0350eba5 6504<span class="reserved">void</span> cupsRWUnlock(<a href="#cups_rwlock_t">cups_rwlock_t</a> *rwlock);</p>
af268786
MS
6505<h4 class="parameters">Parameters</h4>
6506<table class="list"><tbody>
6507<tr><th>rwlock</th>
6508<td class="description">Reader/writer lock</td></tr>
6509</tbody></table>
b47dab17
MS
6510<h3 class="function"><a id="cupsRasterClose">cupsRasterClose</a></h3>
6511<p class="description">Close a raster stream.</p>
6512<p class="code">
0350eba5 6513<span class="reserved">void</span> cupsRasterClose(<a href="#cups_raster_t">cups_raster_t</a> *r);</p>
b47dab17
MS
6514<h4 class="parameters">Parameters</h4>
6515<table class="list"><tbody>
6516<tr><th>r</th>
6517<td class="description">Stream to close</td></tr>
6518</tbody></table>
6519<h4 class="discussion">Discussion</h4>
6520<p class="discussion">The file descriptor associated with the raster stream must be closed
6521separately as needed.</p>
af268786 6522<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsRasterGetErrorString">cupsRasterGetErrorString</a></h3>
b47dab17
MS
6523<p class="description">Return the last error from a raster function.</p>
6524<p class="code">
0350eba5 6525<span class="reserved">const</span> <span class="reserved">char</span> *cupsRasterGetErrorString(<span class="reserved">void</span>);</p>
b47dab17 6526<h4 class="returnvalue">Return Value</h4>
af268786 6527<p class="description">Last error</p>
b47dab17 6528<h4 class="discussion">Discussion</h4>
af268786 6529<p class="discussion">If there are no recent errors, NULL is returned.
b47dab17
MS
6530
6531</p>
af268786 6532<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsRasterInitHeader">cupsRasterInitHeader</a></h3>
b47dab17
MS
6533<p class="description">Initialize a page header for PWG Raster output.</p>
6534<p class="code">
0350eba5 6535<span class="reserved">bool</span> cupsRasterInitHeader(<a href="#cups_page_header2_t">cups_page_header2_t</a> *h, <a href="#cups_media_t">cups_media_t</a> *media, <span class="reserved">const</span> <span class="reserved">char</span> *optimize, <a href="#ipp_quality_t">ipp_quality_t</a> quality, <span class="reserved">const</span> <span class="reserved">char</span> *intent, <a href="#ipp_orient_t">ipp_orient_t</a> orientation, <span class="reserved">const</span> <span class="reserved">char</span> *sides, <span class="reserved">const</span> <span class="reserved">char</span> *type, <span class="reserved">int</span> xdpi, <span class="reserved">int</span> ydpi, <span class="reserved">const</span> <span class="reserved">char</span> *sheet_back);</p>
b47dab17
MS
6536<h4 class="parameters">Parameters</h4>
6537<table class="list"><tbody>
6538<tr><th>h</th>
6539<td class="description">Page header</td></tr>
6540<tr><th>media</th>
af268786
MS
6541<td class="description">Media information</td></tr>
6542<tr><th>optimize</th>
6543<td class="description">IPP &quot;print-content-optimize&quot; value</td></tr>
6544<tr><th>quality</th>
6545<td class="description">IPP &quot;print-quality&quot; value</td></tr>
6546<tr><th>intent</th>
6547<td class="description">IPP &quot;print-rendering-intent&quot; value</td></tr>
6548<tr><th>orientation</th>
6549<td class="description">IPP &quot;orientation-requested&quot; value</td></tr>
6550<tr><th>sides</th>
6551<td class="description">IPP &quot;sides&quot; value</td></tr>
b47dab17
MS
6552<tr><th>type</th>
6553<td class="description">PWG raster type string</td></tr>
6554<tr><th>xdpi</th>
6555<td class="description">Cross-feed direction (horizontal) resolution</td></tr>
6556<tr><th>ydpi</th>
6557<td class="description">Feed direction (vertical) resolution</td></tr>
b47dab17
MS
6558<tr><th>sheet_back</th>
6559<td class="description">Transform for back side or <code>NULL</code> for none</td></tr>
6560</tbody></table>
6561<h4 class="returnvalue">Return Value</h4>
af268786 6562<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
b47dab17 6563<h4 class="discussion">Discussion</h4>
af268786
MS
6564<p class="discussion">The &quot;media&quot; argument specifies the media to use. The &quot;optimize&quot;, &quot;quality&quot;,
6565&quot;intent&quot;, &quot;orientation&quot;, and &quot;sides&quot; arguments specify additional IPP Job
6566Template attribute values that are reflected in the raster header.<br>
b47dab17
MS
6567<br>
6568The &quot;type&quot; argument specifies a &quot;pwg-raster-document-type-supported&quot; value
af268786
MS
6569that controls the color space and bit depth of the raster data. Supported
6570values include:
6571
6572</p><ul>
6573<li>&quot;adobe-rgb_8&quot;: 8-bit per component (24-bit) AdobeRGB
6574</li>
6575<li>&quot;adobe-rgb_16&quot;: 16-bit per component (48-bit) AdobeRGB
6576</li>
6577<li>&quot;black_1&quot;: 1-bit black (K)
6578</li>
6579<li>&quot;black_8&quot;: 8-bit black (K)
6580</li>
6581<li>&quot;black_16&quot;: 16-bit black (K)
6582</li>
6583<li>&quot;cmyk_8&quot;: 8-bit per component (32-bit) CMYK
6584</li>
6585<li>&quot;cmyk_16&quot;: 16-bit per component (64-bit) CMYK
6586</li>
6587<li>&quot;device1_8&quot; to &quot;device15_8&quot;: 8-bit per component DeviceN
6588</li>
6589<li>&quot;device1_16&quot; to &quot;device15_16&quot;: 16-bit per component DeviceN
6590</li>
6591<li>&quot;rgb_8&quot;: 8-bit per component (24-bit) DeviceRGB
6592</li>
6593<li>&quot;rgb_16&quot;: 16-bit per component (32-bit) DeviceRGB
6594</li>
6595<li>&quot;sgray_1&quot;: 1-bit sGray
6596</li>
6597<li>&quot;sgray_8&quot;: 8-bit sGray
6598</li>
6599<li>&quot;sgray_16&quot;: 16-bit sGray
6600</li>
6601<li>&quot;srgb_8&quot;: 8-bit per component (24-bit) sRGB
6602</li>
6603<li>&quot;srgb_16&quot;: 16-bit per component (48-bit) sRGB</li>
6604</ul>
6605<p class="discussion">The &quot;xres&quot; and &quot;yres&quot; arguments specify the raster resolution in dots per
b47dab17
MS
6606inch.<br>
6607<br>
6608The &quot;sheet_back&quot; argument specifies a &quot;pwg-raster-document-sheet-back&quot; value
6609to apply for the back side of a page. Pass <code>NULL</code> for the front side.
6610
6611</p>
6612<h3 class="function"><a id="cupsRasterOpen">cupsRasterOpen</a></h3>
6613<p class="description">Open a raster stream using a file descriptor.</p>
6614<p class="code">
0350eba5 6615<a href="#cups_raster_t">cups_raster_t</a> *cupsRasterOpen(<span class="reserved">int</span> fd, cups_mode_t mode);</p>
b47dab17
MS
6616<h4 class="parameters">Parameters</h4>
6617<table class="list"><tbody>
6618<tr><th>fd</th>
6619<td class="description">File descriptor</td></tr>
6620<tr><th>mode</th>
6621<td class="description">Mode - <code>CUPS_RASTER_READ</code>,
6622<code>CUPS_RASTER_WRITE</code>,
6623<code>CUPS_RASTER_WRITE_COMPRESSED</code>,
6624or <code>CUPS_RASTER_WRITE_PWG</code></td></tr>
6625</tbody></table>
6626<h4 class="returnvalue">Return Value</h4>
6627<p class="description">New stream</p>
6628<h4 class="discussion">Discussion</h4>
6629<p class="discussion">This function associates a raster stream with the given file descriptor.
6630For most printer driver filters, &quot;fd&quot; will be 0 (stdin). For most raster
6631image processor (RIP) filters that generate raster data, &quot;fd&quot; will be 1
6632(stdout).<br>
6633<br>
6634When writing raster data, the <code>CUPS_RASTER_WRITE</code>,
6635<code>CUPS_RASTER_WRITE_COMPRESS</code>, or <code>CUPS_RASTER_WRITE_PWG</code> mode can
6636be used - compressed and PWG output is generally 25-50% smaller but adds a
6637100-300% execution time overhead.</p>
6638<h3 class="function"><a id="cupsRasterOpenIO">cupsRasterOpenIO</a></h3>
6639<p class="description">Open a raster stream using a callback function.</p>
6640<p class="code">
0350eba5 6641<a href="#cups_raster_t">cups_raster_t</a> *cupsRasterOpenIO(<a href="#cups_raster_cb_t">cups_raster_cb_t</a> iocb, <span class="reserved">void</span> *ctx, <a href="#cups_raster_mode_t">cups_raster_mode_t</a> mode);</p>
b47dab17
MS
6642<h4 class="parameters">Parameters</h4>
6643<table class="list"><tbody>
6644<tr><th>iocb</th>
6645<td class="description">Read/write callback</td></tr>
6646<tr><th>ctx</th>
6647<td class="description">Context pointer for callback</td></tr>
6648<tr><th>mode</th>
6649<td class="description">Mode - <code>CUPS_RASTER_READ</code>,
6650<code>CUPS_RASTER_WRITE</code>,
6651<code>CUPS_RASTER_WRITE_COMPRESSED</code>,
6652or <code>CUPS_RASTER_WRITE_PWG</code></td></tr>
6653</tbody></table>
6654<h4 class="returnvalue">Return Value</h4>
6655<p class="description">New stream</p>
6656<h4 class="discussion">Discussion</h4>
6657<p class="discussion">This function associates a raster stream with the given callback function and
6658context pointer.<br>
6659<br>
6660When writing raster data, the <code>CUPS_RASTER_WRITE</code>,
6661<code>CUPS_RASTER_WRITE_COMPRESS</code>, or <code>CUPS_RASTER_WRITE_PWG</code> mode can
6662be used - compressed and PWG output is generally 25-50% smaller but adds a
6663100-300% execution time overhead.</p>
6664<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsRasterReadHeader">cupsRasterReadHeader</a></h3>
6665<p class="description">Read a raster page header and store it in a
af268786 6666 version 1 page header structure.</p>
b47dab17 6667<p class="code">
0350eba5 6668<span class="reserved">unsigned</span> cupsRasterReadHeader(<a href="#cups_raster_t">cups_raster_t</a> *r, <a href="#cups_page_header_t">cups_page_header_t</a> *h);</p>
b47dab17
MS
6669<h4 class="parameters">Parameters</h4>
6670<table class="list"><tbody>
6671<tr><th>r</th>
6672<td class="description">Raster stream</td></tr>
6673<tr><th>h</th>
6674<td class="description">Pointer to header data</td></tr>
6675</tbody></table>
6676<h4 class="returnvalue">Return Value</h4>
6677<p class="description">1 on success, 0 on failure/end-of-file</p>
6678<h4 class="discussion">Discussion</h4>
6679<p class="discussion">This function is deprecated. Use <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a> instead.<br>
6680<br>
6681Version 1 page headers were used in CUPS 1.0 and 1.1 and contain a subset
6682of the version 2 page header data. This function handles reading version 2
6683page headers and copying only the version 1 data into the provided buffer.
6684
6685</p>
b6008d6b 6686<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsRasterReadHeader2">cupsRasterReadHeader2</a></h3>
b47dab17 6687<p class="description">Read a raster page header and store it in a
af268786 6688 version 2 page header structure.</p>
b47dab17 6689<p class="code">
0350eba5 6690<span class="reserved">unsigned</span> cupsRasterReadHeader2(<a href="#cups_raster_t">cups_raster_t</a> *r, <a href="#cups_page_header2_t">cups_page_header2_t</a> *h);</p>
b47dab17
MS
6691<h4 class="parameters">Parameters</h4>
6692<table class="list"><tbody>
6693<tr><th>r</th>
6694<td class="description">Raster stream</td></tr>
6695<tr><th>h</th>
6696<td class="description">Pointer to header data</td></tr>
6697</tbody></table>
6698<h4 class="returnvalue">Return Value</h4>
6699<p class="description">1 on success, 0 on failure/end-of-file</p>
6700<h3 class="function"><a id="cupsRasterReadPixels">cupsRasterReadPixels</a></h3>
6701<p class="description">Read raster pixels.</p>
6702<p class="code">
0350eba5 6703<span class="reserved">unsigned</span> cupsRasterReadPixels(<a href="#cups_raster_t">cups_raster_t</a> *r, <span class="reserved">unsigned</span> <span class="reserved">char</span> *p, <span class="reserved">unsigned</span> len);</p>
b47dab17
MS
6704<h4 class="parameters">Parameters</h4>
6705<table class="list"><tbody>
6706<tr><th>r</th>
6707<td class="description">Raster stream</td></tr>
6708<tr><th>p</th>
6709<td class="description">Pointer to pixel buffer</td></tr>
6710<tr><th>len</th>
6711<td class="description">Number of bytes to read</td></tr>
6712</tbody></table>
6713<h4 class="returnvalue">Return Value</h4>
6714<p class="description">Number of bytes read</p>
6715<h4 class="discussion">Discussion</h4>
6716<p class="discussion">For best performance, filters should read one or more whole lines.
6717The &quot;cupsBytesPerLine&quot; value from the page header can be used to allocate
6718the line buffer and as the number of bytes to read.</p>
6719<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsRasterWriteHeader">cupsRasterWriteHeader</a></h3>
6720<p class="description">Write a raster page header from a version 1 page
af268786 6721 header structure.</p>
b47dab17 6722<p class="code">
0350eba5 6723<span class="reserved">unsigned</span> cupsRasterWriteHeader(<a href="#cups_raster_t">cups_raster_t</a> *r, <a href="#cups_page_header_t">cups_page_header_t</a> *h);</p>
b47dab17
MS
6724<h4 class="parameters">Parameters</h4>
6725<table class="list"><tbody>
6726<tr><th>r</th>
6727<td class="description">Raster stream</td></tr>
6728<tr><th>h</th>
6729<td class="description">Raster page header</td></tr>
6730</tbody></table>
6731<h4 class="returnvalue">Return Value</h4>
6732<p class="description">1 on success, 0 on failure</p>
6733<h4 class="discussion">Discussion</h4>
6734<p class="discussion">This function is deprecated. Use <a href="#cupsRasterWriteHeader2"><code>cupsRasterWriteHeader2</code></a> instead.
6735
6736</p>
b6008d6b 6737<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></h3>
b47dab17 6738<p class="description">Write a raster page header from a version 2
af268786 6739 page header structure.</p>
b47dab17 6740<p class="code">
0350eba5 6741<span class="reserved">unsigned</span> cupsRasterWriteHeader2(<a href="#cups_raster_t">cups_raster_t</a> *r, <a href="#cups_page_header2_t">cups_page_header2_t</a> *h);</p>
b47dab17
MS
6742<h4 class="parameters">Parameters</h4>
6743<table class="list"><tbody>
6744<tr><th>r</th>
6745<td class="description">Raster stream</td></tr>
6746<tr><th>h</th>
6747<td class="description">Raster page header</td></tr>
6748</tbody></table>
6749<h4 class="returnvalue">Return Value</h4>
6750<p class="description">1 on success, 0 on failure</p>
6751<h4 class="discussion">Discussion</h4>
6752<p class="discussion">The page header can be initialized using <a href="#cupsRasterInitPWGHeader"><code>cupsRasterInitPWGHeader</code></a>.
6753
6754</p>
6755<h3 class="function"><a id="cupsRasterWritePixels">cupsRasterWritePixels</a></h3>
6756<p class="description">Write raster pixels.</p>
6757<p class="code">
0350eba5 6758<span class="reserved">unsigned</span> cupsRasterWritePixels(<a href="#cups_raster_t">cups_raster_t</a> *r, <span class="reserved">unsigned</span> <span class="reserved">char</span> *p, <span class="reserved">unsigned</span> len);</p>
b47dab17
MS
6759<h4 class="parameters">Parameters</h4>
6760<table class="list"><tbody>
6761<tr><th>r</th>
6762<td class="description">Raster stream</td></tr>
6763<tr><th>p</th>
6764<td class="description">Bytes to write</td></tr>
6765<tr><th>len</th>
6766<td class="description">Number of bytes to write</td></tr>
6767</tbody></table>
6768<h4 class="returnvalue">Return Value</h4>
6769<p class="description">Number of bytes written</p>
6770<h4 class="discussion">Discussion</h4>
6771<p class="discussion">For best performance, filters should write one or more whole lines.
6772The &quot;cupsBytesPerLine&quot; value from the page header can be used to allocate
6773the line buffer and as the number of bytes to write.</p>
b6008d6b 6774<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsReadResponseData">cupsReadResponseData</a></h3>
af268786
MS
6775<p class="description">Read additional data after the IPP response.</p>
6776<p class="code">
0350eba5 6777ssize_t cupsReadResponseData(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *buffer, size_t length);</p>
af268786
MS
6778<h4 class="parameters">Parameters</h4>
6779<table class="list"><tbody>
6780<tr><th>http</th>
6781<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
6782<tr><th>buffer</th>
6783<td class="description">Buffer to use</td></tr>
6784<tr><th>length</th>
6785<td class="description">Number of bytes to read</td></tr>
6786</tbody></table>
6787<h4 class="returnvalue">Return Value</h4>
6788<p class="description">Bytes read, 0 on EOF, -1 on error</p>
6789<h4 class="discussion">Discussion</h4>
6790<p class="discussion">This function is used after <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to read the PPD or document
6791files from <code>CUPS_GET_PPD</code> and <code>CUPS_GET_DOCUMENT</code> requests,
6792respectively.
6793
6794</p>
b6008d6b 6795<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="cupsRemoveDest">cupsRemoveDest</a></h3>
b47dab17 6796<p class="description">Remove a destination from the destination list.</p>
798d6e29 6797<p class="code">
0350eba5 6798<span class="reserved">int</span> cupsRemoveDest(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *instance, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
98d88c8d
MS
6799<h4 class="parameters">Parameters</h4>
6800<table class="list"><tbody>
6801<tr><th>name</th>
b47dab17 6802<td class="description">Destination name</td></tr>
98d88c8d 6803<tr><th>instance</th>
b47dab17 6804<td class="description">Instance name or <code>NULL</code></td></tr>
98d88c8d 6805<tr><th>num_dests</th>
b47dab17 6806<td class="description">Number of destinations</td></tr>
98d88c8d 6807<tr><th>dests</th>
b47dab17 6808<td class="description">Destinations</td></tr>
98d88c8d 6809</tbody></table>
798d6e29 6810<h4 class="returnvalue">Return Value</h4>
b47dab17 6811<p class="description">New number of destinations</p>
798d6e29 6812<h4 class="discussion">Discussion</h4>
b47dab17 6813<p class="discussion">Removing a destination/instance does not delete the class or printer
798d6e29
MS
6814queue, merely the lpoptions for that destination/instance. Use the
6815<a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
6816options for the user.
6817
6818</p>
b6008d6b 6819<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cupsRemoveOption">cupsRemoveOption</a></h3>
b47dab17 6820<p class="description">Remove an option from an option array.</p>
798d6e29 6821<p class="code">
0350eba5 6822<span class="reserved">int</span> cupsRemoveOption(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
af268786
MS
6823<h4 class="parameters">Parameters</h4>
6824<table class="list"><tbody>
6825<tr><th>name</th>
6826<td class="description">Option name</td></tr>
6827<tr><th>num_options</th>
6828<td class="description">Current number of options</td></tr>
6829<tr><th>options</th>
6830<td class="description">Options</td></tr>
6831</tbody></table>
6832<h4 class="returnvalue">Return Value</h4>
6833<p class="description">New number of options</p>
6834<h3 class="function"><a id="cupsSaveCredentials">cupsSaveCredentials</a></h3>
6835<p class="description">Save the credentials associated with a printer/server.</p>
6836<p class="code">
0350eba5 6837<span class="reserved">bool</span> cupsSaveCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *credentials, <span class="reserved">const</span> <span class="reserved">char</span> *key);</p>
af268786
MS
6838<h4 class="parameters">Parameters</h4>
6839<table class="list"><tbody>
6840<tr><th>path</th>
6841<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
6842<tr><th>common_name</th>
6843<td class="description">Common name for certificate</td></tr>
6844<tr><th>credentials</th>
0350eba5 6845<td class="description">PEM-encoded certificate chain or <code>NULL</code> to remove</td></tr>
af268786
MS
6846<tr><th>key</th>
6847<td class="description">PEM-encoded private key or <code>NULL</code> for none</td></tr>
6848</tbody></table>
6849<h4 class="returnvalue">Return Value</h4>
6850<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
6851<h4 class="discussion">Discussion</h4>
6852<p class="discussion">This function saves the the PEM-encoded X.509 certificate chain string and
6853private key (if not <code>NULL</code>) to the directory &quot;path&quot; or, if &quot;path&quot; is <code>NULL</code>,
6854in a per-user or system-wide (when running as root) certificate/key store.</p>
b6008d6b 6855<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsSendRequest">cupsSendRequest</a></h3>
af268786
MS
6856<p class="description">Send an IPP request.</p>
6857<p class="code">
0350eba5 6858http_status_t cupsSendRequest(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *request, <span class="reserved">const</span> <span class="reserved">char</span> *resource, size_t length);</p>
98d88c8d
MS
6859<h4 class="parameters">Parameters</h4>
6860<table class="list"><tbody>
af268786
MS
6861<tr><th>http</th>
6862<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
6863<tr><th>request</th>
6864<td class="description">IPP request</td></tr>
6865<tr><th>resource</th>
6866<td class="description">Resource path</td></tr>
6867<tr><th>length</th>
6868<td class="description">Length of data to follow or <code>CUPS_LENGTH_VARIABLE</code></td></tr>
98d88c8d 6869</tbody></table>
798d6e29 6870<h4 class="returnvalue">Return Value</h4>
af268786
MS
6871<p class="description">Initial HTTP status</p>
6872<h4 class="discussion">Discussion</h4>
6873<p class="discussion">Use <a href="#cupsWriteRequestData"><code>cupsWriteRequestData</code></a> to write any additional data (document, PPD
6874file, etc.) for the request, <a href="#cupsGetResponse"><code>cupsGetResponse</code></a> to get the IPP response,
6875and <a href="#cupsReadResponseData"><code>cupsReadResponseData</code></a> to read any additional data following the
6876response. Only one request can be sent/queued at a time per <code>http_t</code>
6877connection.<br>
6878<br>
6879Returns the initial HTTP status code, which will be <code>HTTP_STATUS_CONTINUE</code>
6880on a successful send of the request.<br>
6881<br>
6882Note: Unlike <a href="#cupsDoFileRequest"><code>cupsDoFileRequest</code></a>, <a href="#cupsDoIORequest"><code>cupsDoIORequest</code></a>, and
6883<a href="#cupsDoRequest"><code>cupsDoRequest</code></a>, the request is NOT freed with <a href="#ippDelete"><code>ippDelete</code></a>.
6884
6885</p>
6886<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsServer">cupsServer</a></h3>
b47dab17 6887<p class="description">Return the hostname/address of the current server.</p>
798d6e29 6888<p class="code">
0350eba5 6889<span class="reserved">const</span> <span class="reserved">char</span> *cupsServer(<span class="reserved">void</span>);</p>
798d6e29 6890<h4 class="returnvalue">Return Value</h4>
b47dab17 6891<p class="description">Server name</p>
798d6e29 6892<h4 class="discussion">Discussion</h4>
b47dab17 6893<p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
798d6e29
MS
6894~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
6895set, the default is the local system - either &quot;localhost&quot; or a domain socket
6896path.<br>
6897<br>
6898The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
6899address, or a domain socket pathname.<br>
6900<br>
6901Note: The current server is tracked separately for each thread in a program.
6902Multi-threaded programs that override the server via the
6903<a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
af268786
MS
6904server to be used.
6905
6906</p>
6907<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
b47dab17 6908<p class="description">Set the client certificate callback.</p>
798d6e29 6909<p class="code">
0350eba5 6910<span class="reserved">void</span> cupsSetClientCertCB(<a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
798d6e29 6911<h4 class="parameters">Parameters</h4>
98d88c8d
MS
6912<table class="list"><tbody>
6913<tr><th>cb</th>
b47dab17 6914<td class="description">Callback function</td></tr>
98d88c8d 6915<tr><th>user_data</th>
b47dab17 6916<td class="description">User data pointer</td></tr>
98d88c8d
MS
6917</tbody></table>
6918<h4 class="discussion">Discussion</h4>
b47dab17 6919<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
798d6e29
MS
6920<br>
6921Note: The current certificate callback is tracked separately for each thread
6922in a program. Multi-threaded programs that override the callback need to do
6923so in each thread for the same callback to be used.
6924
0350eba5
MS
6925</p>
6926<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cupsSetClientCredentials">cupsSetClientCredentials</a></h3>
6927<p class="description">Set the default credentials to be used for TLS connections.</p>
6928<p class="code">
6929<span class="reserved">bool</span> cupsSetClientCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *credentials, <span class="reserved">const</span> <span class="reserved">char</span> *key);</p>
6930<h4 class="parameters">Parameters</h4>
6931<table class="list"><tbody>
6932<tr><th>credentials</th>
6933<td class="description">PEM-encoded X.509 credentials string</td></tr>
6934<tr><th>key</th>
6935<td class="description">PEM-encoded private key</td></tr>
6936</tbody></table>
6937<h4 class="returnvalue">Return Value</h4>
6938<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
6939<h4 class="discussion">Discussion</h4>
6940<p class="discussion">Note: The default credentials are tracked separately for each thread in a
6941program. Multi-threaded programs that override the setting need to do so in
6942each thread for the same setting to be used.
6943
798d6e29 6944</p>
af268786 6945<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsSetCredentials">cupsSetCredentials</a></h3>
b47dab17 6946<p class="description">Set the default credentials to be used for SSL/TLS
af268786 6947 connections.</p>
798d6e29 6948<p class="code">
0350eba5 6949<span class="reserved">int</span> cupsSetCredentials(<a href="#cups_array_t">cups_array_t</a> *credentials);</p>
798d6e29 6950<h4 class="parameters">Parameters</h4>
98d88c8d
MS
6951<table class="list"><tbody>
6952<tr><th>credentials</th>
b47dab17 6953<td class="description">Array of credentials</td></tr>
98d88c8d 6954</tbody></table>
798d6e29 6955<h4 class="returnvalue">Return Value</h4>
b47dab17 6956<p class="description">Status of call (0 = success)</p>
b6008d6b 6957<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
b47dab17 6958<p class="description">Set the default destination.</p>
98d88c8d 6959<p class="code">
0350eba5 6960<span class="reserved">void</span> cupsSetDefaultDest(<span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *instance, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
98d88c8d
MS
6961<h4 class="parameters">Parameters</h4>
6962<table class="list"><tbody>
6963<tr><th>name</th>
b47dab17 6964<td class="description">Destination name</td></tr>
98d88c8d 6965<tr><th>instance</th>
b47dab17 6966<td class="description">Instance name or <code>NULL</code></td></tr>
98d88c8d 6967<tr><th>num_dests</th>
b47dab17 6968<td class="description">Number of destinations</td></tr>
98d88c8d 6969<tr><th>dests</th>
b47dab17 6970<td class="description">Destinations</td></tr>
98d88c8d 6971</tbody></table>
b6008d6b 6972<h3 class="function"><span class="info">&#160;CUPS 1.1.21&#160;</span><a id="cupsSetDests2">cupsSetDests2</a></h3>
b47dab17 6973<p class="description">Save the list of destinations for the specified server.</p>
798d6e29 6974<p class="code">
0350eba5 6975<span class="reserved">int</span> cupsSetDests2(<a href="#http_t">http_t</a> *http, <span class="reserved">int</span> num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
98d88c8d
MS
6976<h4 class="parameters">Parameters</h4>
6977<table class="list"><tbody>
6978<tr><th>http</th>
b47dab17 6979<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
98d88c8d 6980<tr><th>num_dests</th>
b47dab17 6981<td class="description">Number of destinations</td></tr>
98d88c8d 6982<tr><th>dests</th>
b47dab17 6983<td class="description">Destinations</td></tr>
98d88c8d 6984</tbody></table>
798d6e29 6985<h4 class="returnvalue">Return Value</h4>
b47dab17 6986<p class="description">0 on success, -1 on error</p>
798d6e29 6987<h4 class="discussion">Discussion</h4>
b47dab17 6988<p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
798d6e29
MS
6989as root and ~/.cups/lpoptions when run as a normal user.
6990
6991</p>
6992<h3 class="function"><a id="cupsSetEncryption">cupsSetEncryption</a></h3>
b47dab17 6993<p class="description">Set the encryption preference.</p>
798d6e29 6994<p class="code">
0350eba5 6995<span class="reserved">void</span> cupsSetEncryption(<a href="#http_encryption_t">http_encryption_t</a> e);</p>
798d6e29 6996<h4 class="parameters">Parameters</h4>
98d88c8d
MS
6997<table class="list"><tbody>
6998<tr><th>e</th>
b47dab17 6999<td class="description">New encryption preference</td></tr>
98d88c8d
MS
7000</tbody></table>
7001<h4 class="discussion">Discussion</h4>
b47dab17 7002<p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
798d6e29
MS
7003environment variable, then the ~/.cups/client.conf file, and finally the
7004/etc/cups/client.conf file. If not set, the default is
7005<code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
7006<br>
7007Note: The current encryption setting is tracked separately for each thread
7008in a program. Multi-threaded programs that override the setting need to do
7009so in each thread for the same setting to be used.</p>
af268786
MS
7010<h3 class="function"><span class="info">&#160;CUPS 2.4&#160;</span><a id="cupsSetOAuthCB">cupsSetOAuthCB</a></h3>
7011<p class="description">Set the OAuth 2.0 callback for CUPS.</p>
7012<p class="code">
0350eba5 7013<span class="reserved">void</span> cupsSetOAuthCB(<a href="#cups_oauth_cb_t">cups_oauth_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
af268786
MS
7014<h4 class="parameters">Parameters</h4>
7015<table class="list"><tbody>
7016<tr><th>cb</th>
7017<td class="description">Callback function</td></tr>
7018<tr><th>user_data</th>
7019<td class="description">User data pointer</td></tr>
7020</tbody></table>
7021<h4 class="discussion">Discussion</h4>
7022<p class="discussion">This function sets the OAuth 2.0 callback for the various CUPS APIs that
7023send HTTP requests. Pass <code>NULL</code> to restore the default (console-based)
7024callback.<br>
7025<br>
7026The OAuth callback receives the HTTP connection, realm name, scope name (if
7027any), resource path, and the &quot;user_data&quot; pointer for each request that
7028requires an OAuth access token. The function then returns either the Bearer
7029token string or <code>NULL</code> if no authorization could be obtained.<br>
7030<br>
7031Beyond reusing the Bearer token for subsequent requests on the same HTTP
7032connection, no caching of the token is done by the CUPS library. The
7033callback can determine whether to refresh a cached token by examining any
7034existing token returned by the <a href="#httpGetAuthString"><code>httpGetAuthString</code></a> function.<br>
7035<br>
7036Note: The current OAuth callback is tracked separately for each thread in a
7037program. Multi-threaded programs that override the callback need to do so in
7038each thread for the same callback to be used.
7039
7040</p>
b6008d6b 7041<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
b47dab17 7042<p class="description">Set the advanced password callback for CUPS.</p>
798d6e29 7043<p class="code">
0350eba5 7044<span class="reserved">void</span> cupsSetPasswordCB2(<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb, <span class="reserved">void</span> *user_data);</p>
798d6e29 7045<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7046<table class="list"><tbody>
7047<tr><th>cb</th>
b47dab17 7048<td class="description">Callback function</td></tr>
98d88c8d 7049<tr><th>user_data</th>
b47dab17 7050<td class="description">User data pointer</td></tr>
98d88c8d
MS
7051</tbody></table>
7052<h4 class="discussion">Discussion</h4>
b47dab17 7053<p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
798d6e29
MS
7054reads the password from the console. Programs should call either this
7055function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
7056by a program per thread.<br>
7057<br>
7058Note: The current password callback is tracked separately for each thread
7059in a program. Multi-threaded programs that override the callback need to do
7060so in each thread for the same callback to be used.
7061
7062</p>
7063<h3 class="function"><a id="cupsSetServer">cupsSetServer</a></h3>
b47dab17 7064<p class="description">Set the default server name and port.</p>
798d6e29 7065<p class="code">
0350eba5 7066<span class="reserved">void</span> cupsSetServer(<span class="reserved">const</span> <span class="reserved">char</span> *server);</p>
798d6e29 7067<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7068<table class="list"><tbody>
7069<tr><th>server</th>
b47dab17 7070<td class="description">Server name</td></tr>
98d88c8d
MS
7071</tbody></table>
7072<h4 class="discussion">Discussion</h4>
b47dab17 7073<p class="discussion">The &quot;server&quot; string can be a fully-qualified hostname, a numeric
798d6e29
MS
7074IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
7075addresses can be optionally followed by a colon and port number to override
7076the default port 631, e.g. &quot;hostname:8631&quot;. Pass <code>NULL</code> to restore the
7077default server name and port.<br>
7078<br>
7079Note: The current server is tracked separately for each thread in a program.
7080Multi-threaded programs that override the server need to do so in each
7081thread for the same server to be used.</p>
af268786 7082<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
b47dab17 7083<p class="description">Set the server certificate callback.</p>
798d6e29 7084<p class="code">
0350eba5 7085<span class="reserved">void</span> cupsSetServerCertCB(<a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
798d6e29 7086<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7087<table class="list"><tbody>
7088<tr><th>cb</th>
b47dab17 7089<td class="description">Callback function</td></tr>
98d88c8d 7090<tr><th>user_data</th>
b47dab17 7091<td class="description">User data pointer</td></tr>
98d88c8d
MS
7092</tbody></table>
7093<h4 class="discussion">Discussion</h4>
b47dab17 7094<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
798d6e29
MS
7095<br>
7096Note: The current credentials callback is tracked separately for each thread
7097in a program. Multi-threaded programs that override the callback need to do
7098so in each thread for the same callback to be used.
7099
7100</p>
af268786 7101<h3 class="function"><a id="cupsSetServerCredentials">cupsSetServerCredentials</a></h3>
b47dab17 7102<p class="description">Set the default server credentials.</p>
798d6e29 7103<p class="code">
0350eba5 7104<span class="reserved">int</span> cupsSetServerCredentials(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">int</span> auto_create);</p>
98d88c8d
MS
7105<h4 class="parameters">Parameters</h4>
7106<table class="list"><tbody>
7107<tr><th>path</th>
af268786 7108<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
98d88c8d 7109<tr><th>common_name</th>
b47dab17 7110<td class="description">Default common name for server</td></tr>
98d88c8d 7111<tr><th>auto_create</th>
af268786 7112<td class="description"><code>true</code> = automatically create self-signed certificates</td></tr>
98d88c8d 7113</tbody></table>
798d6e29 7114<h4 class="returnvalue">Return Value</h4>
af268786 7115<p class="description"><code>1</code> on success, <code>0</code> on failure</p>
798d6e29 7116<h4 class="discussion">Discussion</h4>
b47dab17 7117<p class="discussion">Note: The server credentials are used by all threads in the running process.
af268786 7118This function is threadsafe.</p>
798d6e29 7119<h3 class="function"><a id="cupsSetUser">cupsSetUser</a></h3>
b47dab17 7120<p class="description">Set the default user name.</p>
798d6e29 7121<p class="code">
0350eba5 7122<span class="reserved">void</span> cupsSetUser(<span class="reserved">const</span> <span class="reserved">char</span> *user);</p>
798d6e29 7123<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7124<table class="list"><tbody>
7125<tr><th>user</th>
b47dab17 7126<td class="description">User name</td></tr>
98d88c8d
MS
7127</tbody></table>
7128<h4 class="discussion">Discussion</h4>
b47dab17 7129<p class="discussion">Pass <code>NULL</code> to restore the default user name.<br>
798d6e29
MS
7130<br>
7131Note: The current user name is tracked separately for each thread in a
7132program. Multi-threaded programs that override the user name need to do so
7133in each thread for the same user name to be used.</p>
b6008d6b 7134<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="cupsSetUserAgent">cupsSetUserAgent</a></h3>
b47dab17 7135<p class="description">Set the default HTTP User-Agent string.</p>
798d6e29 7136<p class="code">
0350eba5 7137<span class="reserved">void</span> cupsSetUserAgent(<span class="reserved">const</span> <span class="reserved">char</span> *user_agent);</p>
798d6e29 7138<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7139<table class="list"><tbody>
7140<tr><th>user_agent</th>
b47dab17 7141<td class="description">User-Agent string or <code>NULL</code></td></tr>
98d88c8d
MS
7142</tbody></table>
7143<h4 class="discussion">Discussion</h4>
b47dab17 7144<p class="discussion">Setting the string to NULL forces the default value containing the CUPS
798d6e29
MS
7145version, IPP version, and operating system version and architecture.
7146
7147</p>
af268786
MS
7148<h3 class="function"><a id="cupsSignCredentialsRequest">cupsSignCredentialsRequest</a></h3>
7149<p class="description">Sign an X.509 certificate signing request to produce an X.509 certificate chain.</p>
7150<p class="code">
0350eba5 7151<span class="reserved">bool</span> cupsSignCredentialsRequest(<span class="reserved">const</span> <span class="reserved">char</span> *path, <span class="reserved">const</span> <span class="reserved">char</span> *common_name, <span class="reserved">const</span> <span class="reserved">char</span> *request, <span class="reserved">const</span> <span class="reserved">char</span> *root_name, <a href="#cups_credpurpose_t">cups_credpurpose_t</a> allowed_purpose, <a href="#cups_credusage_t">cups_credusage_t</a> allowed_usage, <a href="#cups_cert_san_cb_t">cups_cert_san_cb_t</a> cb, <span class="reserved">void</span> *cb_data, time_t expiration_date);</p>
af268786
MS
7152<h4 class="parameters">Parameters</h4>
7153<table class="list"><tbody>
7154<tr><th>path</th>
7155<td class="description">Directory path for certificate/key store or <code>NULL</code> for default</td></tr>
7156<tr><th>common_name</th>
7157<td class="description">Common name to use</td></tr>
7158<tr><th>request</th>
7159<td class="description">PEM-encoded CSR</td></tr>
7160<tr><th>root_name</th>
7161<td class="description">Root certificate</td></tr>
7162<tr><th>allowed_purpose</th>
7163<td class="description">Allowed credential purpose(s)</td></tr>
7164<tr><th>allowed_usage</th>
7165<td class="description">Allowed credential usage(s)</td></tr>
7166<tr><th>cb</th>
7167<td class="description">subjectAltName callback or <code>NULL</code> to allow just .local</td></tr>
7168<tr><th>cb_data</th>
7169<td class="description">Callback data</td></tr>
7170<tr><th>expiration_date</th>
7171<td class="description">Certificate expiration date</td></tr>
7172</tbody></table>
7173<h4 class="returnvalue">Return Value</h4>
7174<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
7175<h4 class="discussion">Discussion</h4>
7176<p class="discussion">This function creates an X.509 certificate from a signing request. The
7177certificate is stored in the directory &quot;path&quot; or, if &quot;path&quot; is <code>NULL</code>, in a
7178per-user or system-wide (when running as root) certificate/key store. The
7179generated certificate is signed by the named root certificate or, if
7180&quot;root_name&quot; is <code>NULL</code>, a site-wide default root certificate. When
7181&quot;root_name&quot; is <code>NULL</code> and there is no site-wide default root certificate, a
7182self-signed certificate is generated instead.<br>
7183<br>
7184The &quot;allowed_purpose&quot; argument specifies the allowed purpose(s) used for the
7185credentials as a bitwise OR of the following constants:
7186
7187</p><ul>
7188<li><code>CUPS_CREDPURPOSE_SERVER_AUTH</code> for validating TLS servers,
7189</li>
7190<li><code>CUPS_CREDPURPOSE_CLIENT_AUTH</code> for validating TLS clients,
7191</li>
7192<li><code>CUPS_CREDPURPOSE_CODE_SIGNING</code> for validating compiled code,
7193</li>
7194<li><code>CUPS_CREDPURPOSE_EMAIL_PROTECTION</code> for validating email messages,
7195</li>
7196<li><code>CUPS_CREDPURPOSE_TIME_STAMPING</code> for signing timestamps to objects, and/or
7197</li>
7198<li><code>CUPS_CREDPURPOSE_OCSP_SIGNING</code> for Online Certificate Status Protocol
7199 message signing.</li>
7200</ul>
7201<p class="discussion">The &quot;allowed_usage&quot; argument specifies the allowed usage(s) for the
7202credentials as a bitwise OR of the following constants:
7203
7204</p><ul>
7205<li><code>CUPS_CREDUSAGE_DIGITAL_SIGNATURE</code>: digital signatures,
7206</li>
7207<li><code>CUPS_CREDUSAGE_NON_REPUDIATION</code>: non-repudiation/content commitment,
7208</li>
7209<li><code>CUPS_CREDUSAGE_KEY_ENCIPHERMENT</code>: key encipherment,
7210</li>
7211<li><code>CUPS_CREDUSAGE_DATA_ENCIPHERMENT</code>: data encipherment,
7212</li>
7213<li><code>CUPS_CREDUSAGE_KEY_AGREEMENT</code>: key agreement,
7214</li>
7215<li><code>CUPS_CREDUSAGE_KEY_CERT_SIGN</code>: key certicate signing,
7216</li>
7217<li><code>CUPS_CREDUSAGE_CRL_SIGN</code>: certificate revocation list signing,
7218</li>
7219<li><code>CUPS_CREDUSAGE_ENCIPHER_ONLY</code>: encipherment only,
7220</li>
7221<li><code>CUPS_CREDUSAGE_DECIPHER_ONLY</code>: decipherment only,
7222</li>
7223<li><code>CUPS_CREDUSAGE_DEFAULT_CA</code>: defaults for CA certificates,
7224</li>
7225<li><code>CUPS_CREDUSAGE_DEFAULT_TLS</code>: defaults for TLS certificates, and/or
7226</li>
7227<li><code>CUPS_CREDUSAGE_ALL</code>: all usages.</li>
7228</ul>
7229<p class="discussion">The &quot;cb&quot; and &quot;cb_data&quot; arguments specify a function and its data that are
7230used to validate any subjectAltName values in the signing request:
7231
7232<pre>
7233bool san_cb(const char *common_name, const char *alt_name, void *cb_data) {
7234 ... return true if OK and false if not ...
7235}
7236</pre>
7237
7238If <code>NULL</code>, a default validation function is used that allows &quot;localhost&quot; and
7239variations of the common name.<br>
7240<br>
7241The &quot;expiration_date&quot; argument specifies the expiration date and time as a
7242Unix <code>time_t</code> value in seconds.</p>
b6008d6b 7243<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="cupsStartDestDocument">cupsStartDestDocument</a></h3>
b47dab17 7244<p class="description">Start a new document.</p>
798d6e29 7245<p class="code">
0350eba5 7246http_status_t cupsStartDestDocument(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, <a href="#cups_dinfo_t">cups_dinfo_t</a> *info, <span class="reserved">int</span> job_id, <span class="reserved">const</span> <span class="reserved">char</span> *docname, <span class="reserved">const</span> <span class="reserved">char</span> *format, <span class="reserved">int</span> num_options, <a href="#cups_option_t">cups_option_t</a> *options, <span class="reserved">int</span> last_document);</p>
98d88c8d
MS
7247<h4 class="parameters">Parameters</h4>
7248<table class="list"><tbody>
7249<tr><th>http</th>
b47dab17 7250<td class="description">Connection to destination</td></tr>
98d88c8d 7251<tr><th>dest</th>
b47dab17 7252<td class="description">Destination</td></tr>
98d88c8d 7253<tr><th>info</th>
b47dab17 7254<td class="description">Destination information</td></tr>
98d88c8d 7255<tr><th>job_id</th>
b47dab17 7256<td class="description">Job ID</td></tr>
98d88c8d 7257<tr><th>docname</th>
b47dab17 7258<td class="description">Document name</td></tr>
98d88c8d 7259<tr><th>format</th>
b47dab17 7260<td class="description">Document format</td></tr>
98d88c8d 7261<tr><th>num_options</th>
b47dab17 7262<td class="description">Number of document options</td></tr>
98d88c8d 7263<tr><th>options</th>
b47dab17 7264<td class="description">Document options</td></tr>
98d88c8d 7265<tr><th>last_document</th>
b47dab17 7266<td class="description">1 if this is the last document</td></tr>
98d88c8d 7267</tbody></table>
798d6e29 7268<h4 class="returnvalue">Return Value</h4>
b47dab17 7269<p class="description">Status of document creation</p>
798d6e29 7270<h4 class="discussion">Discussion</h4>
b47dab17 7271<p class="discussion">&quot;job_id&quot; is the job ID returned by cupsCreateDestJob. &quot;docname&quot; is the name
798d6e29
MS
7272of the document/file being printed, &quot;format&quot; is the MIME media type for the
7273document (see CUPS_FORMAT_xxx constants), and &quot;num_options&quot; and &quot;options&quot;
7274are the options do be applied to the document. &quot;last_document&quot; should be 1
7275if this is the last document to be submitted in the job. Returns
7276<code>HTTP_CONTINUE</code> on success.
7277
798d6e29 7278</p>
af268786
MS
7279<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsTempFd">cupsTempFd</a></h3>
7280<p class="description">Create a temporary file descriptor.</p>
7281<p class="code">
0350eba5 7282<span class="reserved">int</span> cupsTempFd(<span class="reserved">char</span> *filename, <span class="reserved">int</span> len);</p>
af268786
MS
7283<h4 class="parameters">Parameters</h4>
7284<table class="list"><tbody>
7285<tr><th>filename</th>
7286<td class="description">Pointer to buffer</td></tr>
7287<tr><th>len</th>
7288<td class="description">Size of buffer</td></tr>
7289</tbody></table>
7290<h4 class="returnvalue">Return Value</h4>
7291<p class="description">New file descriptor or -1 on error</p>
7292<h4 class="discussion">Discussion</h4>
7293<p class="discussion">This function creates a temporary file descriptor and places the filename in
7294the &quot;filename&quot; buffer. The temporary file descriptor is opened for reading
7295and writing.<br>
7296<br>
7297</p><blockquote>
7298Note: This function is deprecated. Use the <a href="#cupsCreateTempFd"><code>cupsCreateTempFd</code></a>
7299function instead.</blockquote>
7300
7301</p>
7302<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsTempFile">cupsTempFile</a></h3>
7303<p class="description">Generate a temporary filename (deprecated).</p>
7304<p class="code">
0350eba5 7305<span class="reserved">char</span> *cupsTempFile(<span class="reserved">char</span> *filename, <span class="reserved">int</span> len);</p>
af268786
MS
7306<h4 class="parameters">Parameters</h4>
7307<table class="list"><tbody>
7308<tr><th>filename</th>
7309<td class="description">Pointer to buffer */</td></tr>
7310<tr><th>len</th>
7311<td class="description">Size of buffer</td></tr>
7312</tbody></table>
7313<h4 class="returnvalue">Return Value</h4>
7314<p class="description"><code>NULL</code> (error)</p>
7315<h4 class="discussion">Discussion</h4>
7316<p class="discussion">This function is deprecated and no longer generates a temporary filename.
7317Use <a href="#cupsCreateTempFd"><code>cupsCreateTempFd</code></a> or <a href="#cupsCreateTempFile2"><code>cupsCreateTempFile2</code></a> instead.
7318
7319</p>
7320<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsTempFile2">cupsTempFile2</a></h3>
7321<p class="description">Creates a temporary CUPS file.</p>
7322<p class="code">
0350eba5 7323<a href="#cups_file_t">cups_file_t</a> *cupsTempFile2(<span class="reserved">char</span> *filename, <span class="reserved">int</span> len);</p>
af268786
MS
7324<h4 class="parameters">Parameters</h4>
7325<table class="list"><tbody>
7326<tr><th>filename</th>
7327<td class="description">Pointer to buffer</td></tr>
7328<tr><th>len</th>
7329<td class="description">Size of buffer</td></tr>
7330</tbody></table>
7331<h4 class="returnvalue">Return Value</h4>
7332<p class="description">CUPS file or <code>NULL</code> on error</p>
7333<h4 class="discussion">Discussion</h4>
7334<p class="discussion">This function creates a temporary CUPS file and places the filename in the
7335&quot;filename&quot; buffer. The temporary file is opened for writing.<br>
7336<br>
7337</p><blockquote>
7338Note: This function is deprecated. Use the <a href="#cupsCreateTempFile"><code>cupsCreateTempFile</code></a>
7339function instead.</blockquote>
7340
7341</p>
7342<h3 class="function"><a id="cupsThreadCancel">cupsThreadCancel</a></h3>
7343<p class="description">Cancel (kill) a thread.</p>
7344<p class="code">
0350eba5 7345<span class="reserved">void</span> cupsThreadCancel(<a href="#cups_thread_t">cups_thread_t</a> thread);</p>
af268786
MS
7346<h4 class="parameters">Parameters</h4>
7347<table class="list"><tbody>
7348<tr><th>thread</th>
7349<td class="description">Thread ID</td></tr>
7350</tbody></table>
7351<h3 class="function"><a id="cupsThreadCreate">cupsThreadCreate</a></h3>
7352<p class="description">Create a thread.</p>
7353<p class="code">
0350eba5 7354<a href="#cups_thread_t">cups_thread_t</a> cupsThreadCreate(<a href="#cups_thread_func_t">cups_thread_func_t</a> func, <span class="reserved">void</span> *arg);</p>
af268786
MS
7355<h4 class="parameters">Parameters</h4>
7356<table class="list"><tbody>
7357<tr><th>func</th>
7358<td class="description">Entry point</td></tr>
7359<tr><th>arg</th>
7360<td class="description">Entry point context</td></tr>
7361</tbody></table>
7362<h4 class="returnvalue">Return Value</h4>
7363<p class="description">Thread ID or <code>CUPS_THREAD_INVALID</code> on failure</p>
7364<h3 class="function"><a id="cupsThreadDetach">cupsThreadDetach</a></h3>
7365<p class="description">Tell the OS that the thread is running independently.</p>
7366<p class="code">
0350eba5 7367<span class="reserved">void</span> cupsThreadDetach(<a href="#cups_thread_t">cups_thread_t</a> thread);</p>
af268786
MS
7368<h4 class="parameters">Parameters</h4>
7369<table class="list"><tbody>
7370<tr><th>thread</th>
7371<td class="description">Thread ID</td></tr>
7372</tbody></table>
7373<h3 class="function"><a id="cupsThreadWait">cupsThreadWait</a></h3>
7374<p class="description">Wait for a thread to exit.</p>
7375<p class="code">
0350eba5 7376<span class="reserved">void</span> *cupsThreadWait(<a href="#cups_thread_t">cups_thread_t</a> thread);</p>
af268786
MS
7377<h4 class="parameters">Parameters</h4>
7378<table class="list"><tbody>
7379<tr><th>thread</th>
7380<td class="description">Thread ID</td></tr>
7381</tbody></table>
7382<h4 class="returnvalue">Return Value</h4>
7383<p class="description">Return value</p>
7384<h3 class="function"><a id="cupsUTF32ToUTF8">cupsUTF32ToUTF8</a></h3>
7385<p class="description">Convert UTF-32 to UTF-8.</p>
7386<p class="code">
0350eba5 7387<span class="reserved">int</span> cupsUTF32ToUTF8(<a href="#cups_utf8_t">cups_utf8_t</a> *dest, <span class="reserved">const</span> <a href="#cups_utf32_t">cups_utf32_t</a> *src, <span class="reserved">const</span> <span class="reserved">int</span> maxout);</p>
af268786
MS
7388<h4 class="parameters">Parameters</h4>
7389<table class="list"><tbody>
7390<tr><th>dest</th>
7391<td class="description">Target string</td></tr>
7392<tr><th>src</th>
7393<td class="description">Source string</td></tr>
7394<tr><th>maxout</th>
7395<td class="description">Max output</td></tr>
7396</tbody></table>
7397<h4 class="returnvalue">Return Value</h4>
7398<p class="description">Count or -1 on error</p>
7399<h4 class="discussion">Discussion</h4>
7400<p class="discussion">32-bit UTF-32 (actually 21-bit) maps to UTF-8 as follows...<br>
7401<br>
7402 UTF-32 char UTF-8 char(s)
7403 --------------------------------------------------
7404 0 to 127 = 0xxxxxxx (US-ASCII)
7405 128 to 2047 = 110xxxxx 10yyyyyy
7406 2048 to 65535 = 1110xxxx 10yyyyyy 10zzzzzz
7407 &gt; 65535 = 11110xxx 10yyyyyy 10zzzzzz 10xxxxxx<br>
7408<br>
7409UTF-32 prohibits chars beyond Plane 16 (&gt; 0x10ffff) in UCS-4,
7410which would convert to five- or six-octet UTF-8 sequences...</p>
7411<h3 class="function"><a id="cupsUTF8ToCharset">cupsUTF8ToCharset</a></h3>
7412<p class="description">Convert UTF-8 to legacy character set.</p>
7413<p class="code">
0350eba5 7414<span class="reserved">int</span> cupsUTF8ToCharset(<span class="reserved">char</span> *dest, <span class="reserved">const</span> <a href="#cups_utf8_t">cups_utf8_t</a> *src, <span class="reserved">const</span> <span class="reserved">int</span> maxout, <span class="reserved">const</span> <a href="#cups_encoding_t">cups_encoding_t</a> encoding);</p>
af268786
MS
7415<h4 class="parameters">Parameters</h4>
7416<table class="list"><tbody>
7417<tr><th>dest</th>
7418<td class="description">Target string</td></tr>
7419<tr><th>src</th>
7420<td class="description">Source string</td></tr>
7421<tr><th>maxout</th>
7422<td class="description">Max output</td></tr>
7423<tr><th>encoding</th>
7424<td class="description">Encoding</td></tr>
7425</tbody></table>
7426<h4 class="returnvalue">Return Value</h4>
7427<p class="description">Count or -1 on error</p>
7428<h3 class="function"><a id="cupsUTF8ToUTF32">cupsUTF8ToUTF32</a></h3>
7429<p class="description">Convert UTF-8 to UTF-32.</p>
7430<p class="code">
0350eba5 7431<span class="reserved">int</span> cupsUTF8ToUTF32(<a href="#cups_utf32_t">cups_utf32_t</a> *dest, <span class="reserved">const</span> <a href="#cups_utf8_t">cups_utf8_t</a> *src, <span class="reserved">const</span> <span class="reserved">int</span> maxout);</p>
af268786
MS
7432<h4 class="parameters">Parameters</h4>
7433<table class="list"><tbody>
7434<tr><th>dest</th>
7435<td class="description">Target string</td></tr>
7436<tr><th>src</th>
7437<td class="description">Source string</td></tr>
7438<tr><th>maxout</th>
7439<td class="description">Max output</td></tr>
7440</tbody></table>
7441<h4 class="returnvalue">Return Value</h4>
7442<p class="description">Count or -1 on error</p>
7443<h4 class="discussion">Discussion</h4>
7444<p class="discussion">32-bit UTF-32 (actually 21-bit) maps to UTF-8 as follows...<br>
7445<br>
7446 UTF-32 char UTF-8 char(s)
7447 --------------------------------------------------
7448 0 to 127 = 0xxxxxxx (US-ASCII)
7449 128 to 2047 = 110xxxxx 10yyyyyy
7450 2048 to 65535 = 1110xxxx 10yyyyyy 10zzzzzz
7451 &gt; 65535 = 11110xxx 10yyyyyy 10zzzzzz 10xxxxxx<br>
7452<br>
7453UTF-32 prohibits chars beyond Plane 16 (&gt; 0x10ffff) in UCS-4,
7454which would convert to five- or six-octet UTF-8 sequences...</p>
7455<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsUser">cupsUser</a></h3>
b47dab17 7456<p class="description">Return the current user's name.</p>
798d6e29 7457<p class="code">
0350eba5 7458<span class="reserved">const</span> <span class="reserved">char</span> *cupsUser(<span class="reserved">void</span>);</p>
798d6e29 7459<h4 class="returnvalue">Return Value</h4>
b47dab17 7460<p class="description">User name</p>
798d6e29 7461<h4 class="discussion">Discussion</h4>
b47dab17 7462<p class="discussion">Note: The current user name is tracked separately for each thread in a
798d6e29
MS
7463program. Multi-threaded programs that override the user name with the
7464<a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
af268786
MS
7465name to be used.
7466
7467</p>
7468<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="cupsUserAgent">cupsUserAgent</a></h3>
b47dab17 7469<p class="description">Return the default HTTP User-Agent string.</p>
798d6e29 7470<p class="code">
0350eba5 7471<span class="reserved">const</span> <span class="reserved">char</span> *cupsUserAgent(<span class="reserved">void</span>);</p>
798d6e29 7472<h4 class="returnvalue">Return Value</h4>
b47dab17 7473<p class="description">User-Agent string</p>
b6008d6b 7474<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="cupsWriteRequestData">cupsWriteRequestData</a></h3>
af268786
MS
7475<p class="description">Write additional data after an IPP request.</p>
7476<p class="code">
0350eba5 7477http_status_t cupsWriteRequestData(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *buffer, size_t length);</p>
af268786
MS
7478<h4 class="parameters">Parameters</h4>
7479<table class="list"><tbody>
7480<tr><th>http</th>
7481<td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
7482<tr><th>buffer</th>
7483<td class="description">Bytes to write</td></tr>
7484<tr><th>length</th>
7485<td class="description">Number of bytes to write</td></tr>
7486</tbody></table>
7487<h4 class="returnvalue">Return Value</h4>
7488<p class="description"><code>HTTP_STATUS_CONTINUE</code> if OK or HTTP status on error</p>
7489<h4 class="discussion">Discussion</h4>
7490<p class="discussion">This function is used after <a href="#cupsSendRequest"><code>cupsSendRequest</code></a> to provide a PPD and
7491after <a href="#cupsStartDocument"><code>cupsStartDocument</code></a> to provide a document file.
7492
7493</p>
b6008d6b 7494<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpAcceptConnection">httpAcceptConnection</a></h3>
af268786 7495<p class="description">Accept a new HTTP client connection.</p>
798d6e29 7496<p class="code">
0350eba5 7497<a href="#http_t">http_t</a> *httpAcceptConnection(<span class="reserved">int</span> fd, <span class="reserved">int</span> blocking);</p>
798d6e29 7498<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7499<table class="list"><tbody>
7500<tr><th>fd</th>
b47dab17 7501<td class="description">Listen socket file descriptor</td></tr>
98d88c8d 7502<tr><th>blocking</th>
af268786 7503<td class="description">1 if the connection should be blocking, 0 otherwise</td></tr>
98d88c8d 7504</tbody></table>
798d6e29 7505<h4 class="returnvalue">Return Value</h4>
b47dab17 7506<p class="description">HTTP connection or <code>NULL</code></p>
798d6e29 7507<h4 class="discussion">Discussion</h4>
af268786
MS
7508<p class="discussion">This function accepts a new HTTP client connection from the specified
7509listening socket &quot;fd&quot;. The &quot;blocking&quot; argument specifies whether the new
7510HTTP connection is blocking.
798d6e29
MS
7511
7512</p>
798d6e29 7513<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpAddrClose">httpAddrClose</a></h3>
b47dab17 7514<p class="description">Close a socket created by <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> or
af268786 7515 <a href="#httpAddrListen"><code>httpAddrListen</code></a>.</p>
798d6e29 7516<p class="code">
0350eba5 7517<span class="reserved">int</span> httpAddrClose(<a href="#http_addr_t">http_addr_t</a> *addr, <span class="reserved">int</span> fd);</p>
798d6e29 7518<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7519<table class="list"><tbody>
7520<tr><th>addr</th>
b47dab17 7521<td class="description">Listen address or <code>NULL</code></td></tr>
98d88c8d 7522<tr><th>fd</th>
b47dab17 7523<td class="description">Socket file descriptor</td></tr>
98d88c8d 7524</tbody></table>
798d6e29 7525<h4 class="returnvalue">Return Value</h4>
b47dab17 7526<p class="description">0 on success, -1 on failure</p>
798d6e29 7527<h4 class="discussion">Discussion</h4>
b47dab17 7528<p class="discussion">Pass <code>NULL</code> for sockets created with <a href="#httpAddrConnect2"><code>httpAddrConnect2</code></a> and the
98d88c8d
MS
7529listen address for sockets created with <a href="#httpAddrListen"><code>httpAddrListen</code></a>. This function
7530ensures that domain sockets are removed when closed.
798d6e29
MS
7531
7532</p>
b6008d6b 7533<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpAddrConnect2">httpAddrConnect2</a></h3>
b47dab17 7534<p class="description">Connect to any of the addresses in the list with a
af268786 7535 timeout and optional cancel.</p>
798d6e29 7536<p class="code">
0350eba5 7537<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrConnect2(<a href="#http_addrlist_t">http_addrlist_t</a> *addrlist, <span class="reserved">int</span> *sock, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel);</p>
98d88c8d
MS
7538<h4 class="parameters">Parameters</h4>
7539<table class="list"><tbody>
7540<tr><th>addrlist</th>
b47dab17 7541<td class="description">List of potential addresses</td></tr>
98d88c8d 7542<tr><th>sock</th>
b47dab17 7543<td class="description">Socket</td></tr>
98d88c8d 7544<tr><th>msec</th>
b47dab17 7545<td class="description">Timeout in milliseconds</td></tr>
98d88c8d 7546<tr><th>cancel</th>
b47dab17 7547<td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
98d88c8d 7548</tbody></table>
798d6e29 7549<h4 class="returnvalue">Return Value</h4>
b47dab17 7550<p class="description">Connected address or NULL on failure</p>
b6008d6b 7551<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpAddrCopyList">httpAddrCopyList</a></h3>
b47dab17 7552<p class="description">Copy an address list.</p>
798d6e29 7553<p class="code">
98d88c8d 7554<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrCopyList(<a href="#http_addrlist_t">http_addrlist_t</a> *src);</p>
798d6e29 7555<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7556<table class="list"><tbody>
7557<tr><th>src</th>
b47dab17 7558<td class="description">Source address list</td></tr>
98d88c8d 7559</tbody></table>
798d6e29 7560<h4 class="returnvalue">Return Value</h4>
b47dab17 7561<p class="description">New address list or <code>NULL</code> on error</p>
b6008d6b 7562<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpAddrFreeList">httpAddrFreeList</a></h3>
af268786 7563<p class="description">Free an address list.</p>
798d6e29 7564<p class="code">
0350eba5 7565<span class="reserved">void</span> httpAddrFreeList(<a href="#http_addrlist_t">http_addrlist_t</a> *addrlist);</p>
798d6e29 7566<h4 class="parameters">Parameters</h4>
98d88c8d 7567<table class="list"><tbody>
af268786
MS
7568<tr><th>addrlist</th>
7569<td class="description">Address list to free</td></tr>
98d88c8d 7570</tbody></table>
af268786 7571<h3 class="function"><a id="httpAddrGetFamily">httpAddrGetFamily</a></h3>
b47dab17 7572<p class="description">Get the address family of an address.</p>
798d6e29 7573<p class="code">
0350eba5 7574<span class="reserved">int</span> httpAddrGetFamily(<a href="#http_addr_t">http_addr_t</a> *addr);</p>
af268786
MS
7575<h4 class="parameters">Parameters</h4>
7576<table class="list"><tbody>
7577<tr><th>addr</th>
7578<td class="description">Address</td></tr>
7579</tbody></table>
7580<h4 class="returnvalue">Return Value</h4>
7581<p class="description">Address family</p>
7582<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrGetLength">httpAddrGetLength</a></h3>
7583<p class="description">Return the length of the address in bytes.</p>
7584<p class="code">
0350eba5 7585size_t httpAddrGetLength(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr);</p>
af268786
MS
7586<h4 class="parameters">Parameters</h4>
7587<table class="list"><tbody>
7588<tr><th>addr</th>
7589<td class="description">Address</td></tr>
7590</tbody></table>
7591<h4 class="returnvalue">Return Value</h4>
7592<p class="description">Length in bytes</p>
b6008d6b 7593<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpAddrGetList">httpAddrGetList</a></h3>
af268786
MS
7594<p class="description">Get a list of addresses for a hostname.</p>
7595<p class="code">
0350eba5 7596<a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrGetList(<span class="reserved">const</span> <span class="reserved">char</span> *hostname, <span class="reserved">int</span> family, <span class="reserved">const</span> <span class="reserved">char</span> *service);</p>
af268786
MS
7597<h4 class="parameters">Parameters</h4>
7598<table class="list"><tbody>
7599<tr><th>hostname</th>
7600<td class="description">Hostname, IP address, or NULL for passive listen address</td></tr>
7601<tr><th>family</th>
7602<td class="description">Address family or AF_UNSPEC</td></tr>
7603<tr><th>service</th>
7604<td class="description">Service name or port number</td></tr>
7605</tbody></table>
7606<h4 class="returnvalue">Return Value</h4>
7607<p class="description">List of addresses or NULL</p>
7608<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrGetPort">httpAddrGetPort</a></h3>
7609<p class="description">Get the port number associated with an address.</p>
7610<p class="code">
0350eba5 7611<span class="reserved">int</span> httpAddrGetPort(<a href="#http_addr_t">http_addr_t</a> *addr);</p>
798d6e29 7612<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7613<table class="list"><tbody>
7614<tr><th>addr</th>
b47dab17 7615<td class="description">Address</td></tr>
98d88c8d 7616</tbody></table>
798d6e29 7617<h4 class="returnvalue">Return Value</h4>
af268786
MS
7618<p class="description">Port number</p>
7619<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrGetString">httpAddrGetString</a></h3>
7620<p class="description">Convert an address to a numeric string.</p>
7621<p class="code">
0350eba5 7622<span class="reserved">char</span> *httpAddrGetString(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr, <span class="reserved">char</span> *s, size_t slen);</p>
af268786
MS
7623<h4 class="parameters">Parameters</h4>
7624<table class="list"><tbody>
7625<tr><th>addr</th>
7626<td class="description">Address to convert</td></tr>
7627<tr><th>s</th>
7628<td class="description">String buffer</td></tr>
7629<tr><th>slen</th>
7630<td class="description">Length of string</td></tr>
7631</tbody></table>
7632<h4 class="returnvalue">Return Value</h4>
7633<p class="description">Numeric address string</p>
7634<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrIsAny">httpAddrIsAny</a></h3>
7635<p class="description">Check for the &quot;any&quot; address.</p>
798d6e29 7636<p class="code">
0350eba5 7637<span class="reserved">bool</span> httpAddrIsAny(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr);</p>
798d6e29 7638<h4 class="parameters">Parameters</h4>
98d88c8d 7639<table class="list"><tbody>
af268786
MS
7640<tr><th>addr</th>
7641<td class="description">Address to check</td></tr>
98d88c8d 7642</tbody></table>
af268786
MS
7643<h4 class="returnvalue">Return Value</h4>
7644<p class="description"><code>true</code> if &quot;any&quot; address, <code>false</code> otherwise</p>
7645<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrIsEqual">httpAddrIsEqual</a></h3>
7646<p class="description">Compare two addresses.</p>
798d6e29 7647<p class="code">
0350eba5 7648<span class="reserved">bool</span> httpAddrIsEqual(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr1, <span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr2);</p>
98d88c8d
MS
7649<h4 class="parameters">Parameters</h4>
7650<table class="list"><tbody>
af268786
MS
7651<tr><th>addr1</th>
7652<td class="description">First address</td></tr>
7653<tr><th>addr2</th>
7654<td class="description">Second address</td></tr>
98d88c8d 7655</tbody></table>
798d6e29 7656<h4 class="returnvalue">Return Value</h4>
af268786
MS
7657<p class="description"><code>true</code> if equal, <code>false</code> if not</p>
7658<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrIsLocalhost">httpAddrIsLocalhost</a></h3>
7659<p class="description">Check for the local loopback address.</p>
798d6e29 7660<p class="code">
0350eba5 7661<span class="reserved">bool</span> httpAddrIsLocalhost(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr);</p>
798d6e29 7662<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7663<table class="list"><tbody>
7664<tr><th>addr</th>
af268786 7665<td class="description">Address to check</td></tr>
98d88c8d 7666</tbody></table>
798d6e29 7667<h4 class="returnvalue">Return Value</h4>
af268786 7668<p class="description"><code>true</code> if local host, <code>false</code> otherwise</p>
b6008d6b 7669<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpAddrListen">httpAddrListen</a></h3>
b47dab17 7670<p class="description">Create a listening socket bound to the specified
af268786 7671 address and port.</p>
798d6e29 7672<p class="code">
0350eba5 7673<span class="reserved">int</span> httpAddrListen(<a href="#http_addr_t">http_addr_t</a> *addr, <span class="reserved">int</span> port);</p>
798d6e29 7674<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7675<table class="list"><tbody>
7676<tr><th>addr</th>
b47dab17 7677<td class="description">Address to bind to</td></tr>
98d88c8d 7678<tr><th>port</th>
b47dab17 7679<td class="description">Port number to bind to</td></tr>
98d88c8d 7680</tbody></table>
798d6e29 7681<h4 class="returnvalue">Return Value</h4>
b47dab17 7682<p class="description">Socket or -1 on error</p>
b6008d6b 7683<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpAddrLookup">httpAddrLookup</a></h3>
b47dab17 7684<p class="description">Lookup the hostname associated with the address.</p>
798d6e29 7685<p class="code">
0350eba5 7686<span class="reserved">char</span> *httpAddrLookup(<span class="reserved">const</span> <a href="#http_addr_t">http_addr_t</a> *addr, <span class="reserved">char</span> *name, <span class="reserved">int</span> namelen);</p>
98d88c8d
MS
7687<h4 class="parameters">Parameters</h4>
7688<table class="list"><tbody>
7689<tr><th>addr</th>
b47dab17 7690<td class="description">Address to lookup</td></tr>
98d88c8d 7691<tr><th>name</th>
b47dab17 7692<td class="description">Host name buffer</td></tr>
98d88c8d 7693<tr><th>namelen</th>
b47dab17 7694<td class="description">Size of name buffer</td></tr>
98d88c8d 7695</tbody></table>
798d6e29 7696<h4 class="returnvalue">Return Value</h4>
b47dab17 7697<p class="description">Host name</p>
af268786
MS
7698<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpAddrSetPort">httpAddrSetPort</a></h3>
7699<p class="description">Set the port number associated with an address.</p>
798d6e29 7700<p class="code">
0350eba5 7701<span class="reserved">void</span> httpAddrSetPort(<a href="#http_addr_t">http_addr_t</a> *addr, <span class="reserved">int</span> port);</p>
798d6e29 7702<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7703<table class="list"><tbody>
7704<tr><th>addr</th>
b47dab17 7705<td class="description">Address</td></tr>
af268786
MS
7706<tr><th>port</th>
7707<td class="description">Port</td></tr>
98d88c8d 7708</tbody></table>
b6008d6b 7709<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpAssembleURI">httpAssembleURI</a></h3>
b47dab17 7710<p class="description">Assemble a uniform resource identifier from its
af268786 7711 components.</p>
798d6e29 7712<p class="code">
0350eba5 7713<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURI(<a href="#http_uri_coding_t">http_uri_coding_t</a> encoding, <span class="reserved">char</span> *uri, <span class="reserved">int</span> urilen, <span class="reserved">const</span> <span class="reserved">char</span> *scheme, <span class="reserved">const</span> <span class="reserved">char</span> *username, <span class="reserved">const</span> <span class="reserved">char</span> *host, <span class="reserved">int</span> port, <span class="reserved">const</span> <span class="reserved">char</span> *resource);</p>
98d88c8d
MS
7714<h4 class="parameters">Parameters</h4>
7715<table class="list"><tbody>
7716<tr><th>encoding</th>
b47dab17 7717<td class="description">Encoding flags</td></tr>
98d88c8d 7718<tr><th>uri</th>
b47dab17 7719<td class="description">URI buffer</td></tr>
98d88c8d 7720<tr><th>urilen</th>
b47dab17 7721<td class="description">Size of URI buffer</td></tr>
98d88c8d 7722<tr><th>scheme</th>
b47dab17 7723<td class="description">Scheme name</td></tr>
98d88c8d 7724<tr><th>username</th>
b47dab17 7725<td class="description">Username</td></tr>
98d88c8d 7726<tr><th>host</th>
b47dab17 7727<td class="description">Hostname or address</td></tr>
98d88c8d 7728<tr><th>port</th>
b47dab17 7729<td class="description">Port number</td></tr>
98d88c8d 7730<tr><th>resource</th>
b47dab17 7731<td class="description">Resource</td></tr>
98d88c8d 7732</tbody></table>
798d6e29 7733<h4 class="returnvalue">Return Value</h4>
b47dab17 7734<p class="description">URI status</p>
798d6e29 7735<h4 class="discussion">Discussion</h4>
b47dab17 7736<p class="discussion">This function escapes reserved characters in the URI depending on the
798d6e29
MS
7737value of the &quot;encoding&quot; argument. You should use this function in
7738place of traditional string functions whenever you need to create a
7739URI string.
7740
7741</p>
b6008d6b 7742<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpAssembleURIf">httpAssembleURIf</a></h3>
af268786 7743<p class="description">Assemble a uniform resource identifier from its components with a formatted resource.</p>
798d6e29 7744<p class="code">
0350eba5 7745<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURIf(<a href="#http_uri_coding_t">http_uri_coding_t</a> encoding, <span class="reserved">char</span> *uri, <span class="reserved">int</span> urilen, <span class="reserved">const</span> <span class="reserved">char</span> *scheme, <span class="reserved">const</span> <span class="reserved">char</span> *username, <span class="reserved">const</span> <span class="reserved">char</span> *host, <span class="reserved">int</span> port, <span class="reserved">const</span> <span class="reserved">char</span> *resourcef, ...);</p>
98d88c8d
MS
7746<h4 class="parameters">Parameters</h4>
7747<table class="list"><tbody>
7748<tr><th>encoding</th>
b47dab17 7749<td class="description">Encoding flags</td></tr>
98d88c8d 7750<tr><th>uri</th>
b47dab17 7751<td class="description">URI buffer</td></tr>
98d88c8d 7752<tr><th>urilen</th>
b47dab17 7753<td class="description">Size of URI buffer</td></tr>
98d88c8d 7754<tr><th>scheme</th>
b47dab17 7755<td class="description">Scheme name</td></tr>
98d88c8d 7756<tr><th>username</th>
b47dab17 7757<td class="description">Username</td></tr>
98d88c8d 7758<tr><th>host</th>
b47dab17 7759<td class="description">Hostname or address</td></tr>
98d88c8d 7760<tr><th>port</th>
b47dab17 7761<td class="description">Port number</td></tr>
98d88c8d 7762<tr><th>resourcef</th>
b47dab17 7763<td class="description">Printf-style resource</td></tr>
98d88c8d 7764<tr><th>...</th>
b47dab17 7765<td class="description">Additional arguments as needed</td></tr>
98d88c8d 7766</tbody></table>
798d6e29 7767<h4 class="returnvalue">Return Value</h4>
b47dab17 7768<p class="description">URI status</p>
798d6e29 7769<h4 class="discussion">Discussion</h4>
b47dab17 7770<p class="discussion">This function creates a formatted version of the resource string
798d6e29
MS
7771argument &quot;resourcef&quot; and escapes reserved characters in the URI
7772depending on the value of the &quot;encoding&quot; argument. You should use
7773this function in place of traditional string functions whenever
7774you need to create a URI string.
7775
7776</p>
b6008d6b 7777<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpAssembleUUID">httpAssembleUUID</a></h3>
b47dab17 7778<p class="description">Assemble a name-based UUID URN conforming to RFC 4122.</p>
798d6e29 7779<p class="code">
0350eba5 7780<span class="reserved">char</span> *httpAssembleUUID(<span class="reserved">const</span> <span class="reserved">char</span> *server, <span class="reserved">int</span> port, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> number, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
98d88c8d
MS
7781<h4 class="parameters">Parameters</h4>
7782<table class="list"><tbody>
7783<tr><th>server</th>
b47dab17 7784<td class="description">Server name</td></tr>
98d88c8d 7785<tr><th>port</th>
b47dab17 7786<td class="description">Port number</td></tr>
98d88c8d 7787<tr><th>name</th>
b47dab17 7788<td class="description">Object name or NULL</td></tr>
98d88c8d 7789<tr><th>number</th>
b47dab17 7790<td class="description">Object number or 0</td></tr>
98d88c8d 7791<tr><th>buffer</th>
b47dab17 7792<td class="description">String buffer</td></tr>
98d88c8d 7793<tr><th>bufsize</th>
b47dab17 7794<td class="description">Size of buffer</td></tr>
98d88c8d 7795</tbody></table>
798d6e29 7796<h4 class="returnvalue">Return Value</h4>
b47dab17 7797<p class="description">UUID string</p>
798d6e29 7798<h4 class="discussion">Discussion</h4>
b47dab17 7799<p class="discussion">This function creates a unique 128-bit identifying number using the server
798d6e29
MS
7800name, port number, random data, and optionally an object name and/or object
7801number. The result is formatted as a UUID URN as defined in RFC 4122.<br>
7802<br>
7803The buffer needs to be at least 46 bytes in size.
7804
7805</p>
af268786 7806<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="httpBlocking">httpBlocking</a></h3>
b47dab17 7807<p class="description">Set blocking/non-blocking behavior on a connection.</p>
798d6e29 7808<p class="code">
0350eba5 7809<span class="reserved">void</span> httpBlocking(<a href="#http_t">http_t</a> *http, <span class="reserved">int</span> b);</p>
798d6e29 7810<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7811<table class="list"><tbody>
7812<tr><th>http</th>
b47dab17 7813<td class="description">HTTP connection</td></tr>
98d88c8d 7814<tr><th>b</th>
b47dab17 7815<td class="description">1 = blocking, 0 = non-blocking</td></tr>
98d88c8d 7816</tbody></table>
af268786 7817<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="httpCheck">httpCheck</a></h3>
b47dab17 7818<p class="description">Check to see if there is a pending response from the server.</p>
798d6e29 7819<p class="code">
0350eba5 7820<span class="reserved">int</span> httpCheck(<a href="#http_t">http_t</a> *http);</p>
798d6e29 7821<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7822<table class="list"><tbody>
7823<tr><th>http</th>
b47dab17 7824<td class="description">HTTP connection</td></tr>
98d88c8d 7825</tbody></table>
798d6e29 7826<h4 class="returnvalue">Return Value</h4>
b47dab17 7827<p class="description">0 = no data, 1 = data available</p>
b6008d6b 7828<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="httpClearCookie">httpClearCookie</a></h3>
b47dab17 7829<p class="description">Clear the cookie value(s).</p>
798d6e29 7830<p class="code">
0350eba5 7831<span class="reserved">void</span> httpClearCookie(<a href="#http_t">http_t</a> *http);</p>
798d6e29 7832<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7833<table class="list"><tbody>
7834<tr><th>http</th>
b47dab17 7835<td class="description">HTTP connection</td></tr>
98d88c8d 7836</tbody></table>
798d6e29 7837<h3 class="function"><a id="httpClearFields">httpClearFields</a></h3>
af268786 7838<p class="description">Clear HTTP request/response fields.</p>
798d6e29 7839<p class="code">
0350eba5 7840<span class="reserved">void</span> httpClearFields(<a href="#http_t">http_t</a> *http);</p>
798d6e29 7841<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7842<table class="list"><tbody>
7843<tr><th>http</th>
b47dab17 7844<td class="description">HTTP connection</td></tr>
98d88c8d 7845</tbody></table>
798d6e29 7846<h3 class="function"><a id="httpClose">httpClose</a></h3>
af268786 7847<p class="description">Close a HTTP connection.</p>
798d6e29 7848<p class="code">
0350eba5 7849<span class="reserved">void</span> httpClose(<a href="#http_t">http_t</a> *http);</p>
798d6e29 7850<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7851<table class="list"><tbody>
7852<tr><th>http</th>
b47dab17 7853<td class="description">HTTP connection</td></tr>
98d88c8d 7854</tbody></table>
b6008d6b 7855<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpConnect2">httpConnect2</a></h3>
b47dab17 7856<p class="description">Connect to a HTTP server.</p>
798d6e29 7857<p class="code">
0350eba5 7858<a href="#http_t">http_t</a> *httpConnect2(<span class="reserved">const</span> <span class="reserved">char</span> *host, <span class="reserved">int</span> port, <a href="#http_addrlist_t">http_addrlist_t</a> *addrlist, <span class="reserved">int</span> family, <a href="#http_encryption_t">http_encryption_t</a> encryption, <span class="reserved">int</span> blocking, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel);</p>
98d88c8d
MS
7859<h4 class="parameters">Parameters</h4>
7860<table class="list"><tbody>
7861<tr><th>host</th>
b47dab17 7862<td class="description">Host to connect to</td></tr>
98d88c8d 7863<tr><th>port</th>
b47dab17 7864<td class="description">Port number</td></tr>
98d88c8d 7865<tr><th>addrlist</th>
b47dab17 7866<td class="description">List of addresses or <code>NULL</code> to lookup</td></tr>
98d88c8d 7867<tr><th>family</th>
b47dab17 7868<td class="description">Address family to use or <code>AF_UNSPEC</code> for any</td></tr>
98d88c8d 7869<tr><th>encryption</th>
b47dab17 7870<td class="description">Type of encryption to use</td></tr>
98d88c8d 7871<tr><th>blocking</th>
b47dab17 7872<td class="description">1 for blocking connection, 0 for non-blocking</td></tr>
98d88c8d 7873<tr><th>msec</th>
b47dab17 7874<td class="description">Connection timeout in milliseconds, 0 means don't connect</td></tr>
98d88c8d 7875<tr><th>cancel</th>
b47dab17 7876<td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
98d88c8d 7877</tbody></table>
798d6e29 7878<h4 class="returnvalue">Return Value</h4>
b47dab17 7879<p class="description">New HTTP connection</p>
af268786
MS
7880<h4 class="discussion">Discussion</h4>
7881<p class="discussion">This function creates a connection to a HTTP server. The &quot;host&quot; and &quot;port&quot;
7882arguments specify a hostname or IP address and port number to use while the
7883&quot;addrlist&quot; argument specifies a list of addresses to use or <code>NULL</code> to do a
7884fresh lookup. The &quot;family&quot; argument specifies the address family to use -
7885<code>AF_UNSPEC</code> to try both IPv4 and IPv6, <code>AF_INET</code> for IPv4, or <code>AF_INET6</code> for
7886IPv6.<br>
7887<br>
7888The &quot;encryption&quot; argument specifies whether to encrypt the connection and the
7889&quot;blocking&quot; argument specifies whether to use blocking behavior when reading
7890or writing data.<br>
7891<br>
7892The &quot;msec&quot; argument specifies how long to try to connect to the server or <code>0</code>
7893to just create an unconnected <code>http_t</code> object. The &quot;cancel&quot; argument
7894specifies an integer variable that can be set to a non-zero value to cancel
7895the connection process.
7896
0350eba5
MS
7897</p>
7898<h3 class="function"><a id="httpConnectAgain">httpConnectAgain</a></h3>
7899<p class="description">Reconnect to a HTTP server with timeout and optional cancel variable.</p>
7900<p class="code">
7901<span class="reserved">bool</span> httpConnectAgain(<a href="#http_t">http_t</a> *http, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel);</p>
7902<h4 class="parameters">Parameters</h4>
7903<table class="list"><tbody>
7904<tr><th>http</th>
7905<td class="description">HTTP connection</td></tr>
7906<tr><th>msec</th>
7907<td class="description">Timeout in milliseconds</td></tr>
7908<tr><th>cancel</th>
7909<td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
7910</tbody></table>
7911<h4 class="returnvalue">Return Value</h4>
7912<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
7913<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpConnectURI">httpConnectURI</a></h3>
7914<p class="description">Connect to a HTTP service using a URI.</p>
7915<p class="code">
7916<a href="#http_t">http_t</a> *httpConnectURI(<span class="reserved">const</span> <span class="reserved">char</span> *uri, <span class="reserved">char</span> *host, size_t hsize, <span class="reserved">int</span> *port, <span class="reserved">char</span> *resource, size_t rsize, <span class="reserved">bool</span> blocking, <span class="reserved">int</span> msec, <span class="reserved">int</span> *cancel, <span class="reserved">bool</span> require_ca);</p>
7917<h4 class="parameters">Parameters</h4>
7918<table class="list"><tbody>
7919<tr><th>uri</th>
7920<td class="description">Service to connect to</td></tr>
7921<tr><th>host</th>
7922<td class="description">Host name buffer (<code>NULL</code> for don't care)</td></tr>
7923<tr><th>hsize</th>
7924<td class="description">Size of host name buffer</td></tr>
7925<tr><th>port</th>
7926<td class="description">Port number (<code>NULL</code> for don't care)</td></tr>
7927<tr><th>resource</th>
7928<td class="description">Resource path buffer (<code>NULL</code> for don't care)</td></tr>
7929<tr><th>rsize</th>
7930<td class="description">Size of resource path buffer</td></tr>
7931<tr><th>blocking</th>
7932<td class="description"><code>true</code> for blocking connection, <code>false</code> for non-blocking</td></tr>
7933<tr><th>msec</th>
7934<td class="description">Connection timeout in milliseconds, <code>0</code> means don't connect</td></tr>
7935<tr><th>cancel</th>
7936<td class="description">Pointer to &quot;cancel&quot; variable or <code>NULL</code> for none</td></tr>
7937<tr><th>require_ca</th>
7938<td class="description"><code>true</code> to require a CA-signed X.509 certificate</td></tr>
7939</tbody></table>
7940<h4 class="returnvalue">Return Value</h4>
7941<p class="description">New HTTP connection</p>
7942<h4 class="discussion">Discussion</h4>
7943<p class="discussion">This function creates a connection to a HTTP server. The &quot;uri&quot; argument
7944specifies a &quot;http&quot;, &quot;https&quot;, &quot;ipp&quot;, or &quot;ipps&quot; URI for the service.<br>
7945<br>
7946The resource path for the service is returned in the buffer pointed to by
7947the &quot;resource&quot; argument of size &quot;rsize&quot;.<br>
7948<br>
7949The &quot;msec&quot; argument specifies how long to try to connect to the server or <code>0</code>
7950to just create an unconnected <code>http_t</code> object. The &quot;cancel&quot; argument
7951specifies an integer variable that can be set to a non-zero value to cancel
7952the connection process.<br>
7953<br>
7954The &quot;require_ca&quot; argument specifies whether to verify that the service
7955connection is using a CA-signed X.509 certificate.
7956
af268786
MS
7957</p>
7958<h3 class="function"><a id="httpCopyPeerCredentials">httpCopyPeerCredentials</a></h3>
7959<p class="description">Copy the credentials associated with the peer in an encrypted connection.</p>
798d6e29 7960<p class="code">
0350eba5 7961<span class="reserved">char</span> *httpCopyPeerCredentials(<a href="#http_t">http_t</a> *http);</p>
798d6e29 7962<h4 class="parameters">Parameters</h4>
98d88c8d
MS
7963<table class="list"><tbody>
7964<tr><th>http</th>
b47dab17 7965<td class="description">Connection to server</td></tr>
98d88c8d 7966</tbody></table>
798d6e29 7967<h4 class="returnvalue">Return Value</h4>
af268786
MS
7968<p class="description">PEM-encoded X.509 certificate chain or <code>NULL</code></p>
7969<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpDecode64_3">httpDecode64_3</a></h3>
b47dab17 7970<p class="description">Base64-decode a string.</p>
798d6e29 7971<p class="code">
0350eba5 7972<span class="reserved">char</span> *httpDecode64_3(<span class="reserved">char</span> *out, size_t *outlen, <span class="reserved">const</span> <span class="reserved">char</span> *in, <span class="reserved">const</span> <span class="reserved">char</span> **end);</p>
98d88c8d
MS
7973<h4 class="parameters">Parameters</h4>
7974<table class="list"><tbody>
7975<tr><th>out</th>
b47dab17 7976<td class="description">String to write to</td></tr>
98d88c8d 7977<tr><th>outlen</th>
b47dab17 7978<td class="description">Size of output string</td></tr>
98d88c8d 7979<tr><th>in</th>
b47dab17 7980<td class="description">String to read from</td></tr>
af268786
MS
7981<tr><th>end</th>
7982<td class="description">Pointer to end of Base64 data (<code>NULL</code> if don't care)</td></tr>
98d88c8d 7983</tbody></table>
798d6e29 7984<h4 class="returnvalue">Return Value</h4>
af268786 7985<p class="description">Decoded string or <code>NULL</code> on error</p>
98d88c8d 7986<h4 class="discussion">Discussion</h4>
af268786
MS
7987<p class="discussion">This function decodes a Base64 string as defined by RFC 4648. The caller
7988must initialize &quot;outlen&quot; to the maximum size of the decoded string. On
7989return &quot;outlen&quot; contains the decoded length of the string and &quot;end&quot; (if not
7990<code>NULL</code>) points to the end of the Base64 data that has been decoded.<br>
7991<br>
7992This function always reserves one byte in the output buffer for a nul
7993terminating character, even if the result is not a regular string. Callers
7994should ensure that the output buffer is at least one byte larger than the
7995expected size, for example 33 bytes for a SHA-256 hash which is 32 bytes in
7996length.<br>
7997<br>
7998This function supports both Base64 and Base64url strings.
98d88c8d
MS
7999
8000</p>
af268786 8001<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpEncode64_3">httpEncode64_3</a></h3>
b47dab17 8002<p class="description">Base64-encode a string.</p>
798d6e29 8003<p class="code">
0350eba5 8004<span class="reserved">char</span> *httpEncode64_3(<span class="reserved">char</span> *out, size_t outlen, <span class="reserved">const</span> <span class="reserved">char</span> *in, size_t inlen, <span class="reserved">bool</span> url);</p>
98d88c8d
MS
8005<h4 class="parameters">Parameters</h4>
8006<table class="list"><tbody>
8007<tr><th>out</th>
b47dab17 8008<td class="description">String to write to</td></tr>
98d88c8d 8009<tr><th>outlen</th>
b47dab17 8010<td class="description">Maximum size of output string</td></tr>
98d88c8d 8011<tr><th>in</th>
b47dab17 8012<td class="description">String to read from</td></tr>
98d88c8d 8013<tr><th>inlen</th>
b47dab17 8014<td class="description">Size of input string</td></tr>
af268786
MS
8015<tr><th>url</th>
8016<td class="description"><code>true</code> for Base64url, <code>false</code> for Base64</td></tr>
98d88c8d 8017</tbody></table>
798d6e29 8018<h4 class="returnvalue">Return Value</h4>
b47dab17 8019<p class="description">Encoded string</p>
af268786
MS
8020<h4 class="discussion">Discussion</h4>
8021<p class="discussion">This function encodes a Base64 string as defined by RFC 4648. The &quot;url&quot;
8022parameter controls whether the original Base64 (&quot;url&quot; = <code>false</code>) or the
8023Base64url (&quot;url&quot; = <code>true</code>) alphabet is used.
8024
8025</p>
798d6e29 8026<h3 class="function"><a id="httpFieldValue">httpFieldValue</a></h3>
af268786 8027<p class="description">Return the HTTP field enumeration value for a field name.</p>
798d6e29 8028<p class="code">
0350eba5 8029<a href="#http_field_t">http_field_t</a> httpFieldValue(<span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
798d6e29 8030<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8031<table class="list"><tbody>
8032<tr><th>name</th>
b47dab17 8033<td class="description">String name</td></tr>
98d88c8d 8034</tbody></table>
798d6e29 8035<h4 class="returnvalue">Return Value</h4>
b47dab17 8036<p class="description">Field index</p>
798d6e29 8037<h3 class="function"><a id="httpFlush">httpFlush</a></h3>
b47dab17 8038<p class="description">Flush data read from a HTTP connection.</p>
798d6e29 8039<p class="code">
0350eba5 8040<span class="reserved">void</span> httpFlush(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8041<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8042<table class="list"><tbody>
8043<tr><th>http</th>
b47dab17 8044<td class="description">HTTP connection</td></tr>
98d88c8d 8045</tbody></table>
b6008d6b 8046<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpFlushWrite">httpFlushWrite</a></h3>
b47dab17 8047<p class="description">Flush data written to a HTTP connection.</p>
798d6e29 8048<p class="code">
0350eba5 8049<span class="reserved">int</span> httpFlushWrite(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8050<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8051<table class="list"><tbody>
8052<tr><th>http</th>
b47dab17 8053<td class="description">HTTP connection</td></tr>
98d88c8d 8054</tbody></table>
798d6e29 8055<h4 class="returnvalue">Return Value</h4>
b47dab17 8056<p class="description">Bytes written or -1 on error</p>
798d6e29 8057<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetActivity">httpGetActivity</a></h3>
b47dab17 8058<p class="description">Get the most recent activity for a connection.</p>
798d6e29 8059<p class="code">
98d88c8d 8060time_t httpGetActivity(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8061<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8062<table class="list"><tbody>
8063<tr><th>http</th>
b47dab17 8064<td class="description">HTTP connection</td></tr>
98d88c8d 8065</tbody></table>
798d6e29 8066<h4 class="returnvalue">Return Value</h4>
b47dab17 8067<p class="description">Time of last read or write</p>
798d6e29 8068<h4 class="discussion">Discussion</h4>
b47dab17 8069<p class="discussion">The return value is the time in seconds of the last read or write.
798d6e29
MS
8070
8071</p>
8072<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetAddress">httpGetAddress</a></h3>
b47dab17 8073<p class="description">Get the address of the connected peer of a connection.</p>
798d6e29 8074<p class="code">
98d88c8d 8075<a href="#http_addr_t">http_addr_t</a> *httpGetAddress(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8076<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8077<table class="list"><tbody>
8078<tr><th>http</th>
b47dab17 8079<td class="description">HTTP connection</td></tr>
98d88c8d 8080</tbody></table>
798d6e29 8081<h4 class="returnvalue">Return Value</h4>
b47dab17 8082<p class="description">Connected address or <code>NULL</code></p>
798d6e29 8083<h4 class="discussion">Discussion</h4>
b47dab17 8084<p class="discussion">For connections created with <a href="#httpConnect2"><code>httpConnect2</code></a>, the address is for the
65bebeac
MS
8085server. For connections created with <a href="#httpAccept"><code>httpAccept</code></a>, the address is for
8086the client.<br>
8087<br>
8088Returns <code>NULL</code> if the socket is currently unconnected.
798d6e29
MS
8089
8090</p>
b6008d6b 8091<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="httpGetAuthString">httpGetAuthString</a></h3>
b47dab17 8092<p class="description">Get the current authorization string.</p>
798d6e29 8093<p class="code">
0350eba5 8094<span class="reserved">char</span> *httpGetAuthString(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8095<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8096<table class="list"><tbody>
8097<tr><th>http</th>
b47dab17 8098<td class="description">HTTP connection</td></tr>
98d88c8d 8099</tbody></table>
798d6e29 8100<h4 class="returnvalue">Return Value</h4>
b47dab17 8101<p class="description">Authorization string</p>
798d6e29 8102<h4 class="discussion">Discussion</h4>
b47dab17 8103<p class="discussion">The authorization string is set by <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> and
65bebeac
MS
8104<a href="#httpSetAuthString"><code>httpSetAuthString</code></a>. Use <a href="#httpGetAuthString"><code>httpGetAuthString</code></a> to retrieve the
8105string to use with <a href="#httpSetField"><code>httpSetField</code></a> for the
8106<code>HTTP_FIELD_AUTHORIZATION</code> value.
798d6e29
MS
8107
8108</p>
b6008d6b 8109<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetBlocking">httpGetBlocking</a></h3>
af268786 8110<p class="description">Get the blocking/non-blocking state of a connection.</p>
798d6e29 8111<p class="code">
0350eba5 8112<span class="reserved">int</span> httpGetBlocking(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8113<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8114<table class="list"><tbody>
8115<tr><th>http</th>
b47dab17 8116<td class="description">HTTP connection</td></tr>
98d88c8d 8117</tbody></table>
798d6e29 8118<h4 class="returnvalue">Return Value</h4>
b47dab17 8119<p class="description">1 if blocking, 0 if non-blocking</p>
b6008d6b 8120<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpGetContentEncoding">httpGetContentEncoding</a></h3>
b47dab17 8121<p class="description">Get a common content encoding, if any, between
af268786 8122 the client and server.</p>
798d6e29 8123<p class="code">
0350eba5 8124<span class="reserved">const</span> <span class="reserved">char</span> *httpGetContentEncoding(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8125<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8126<table class="list"><tbody>
8127<tr><th>http</th>
b47dab17 8128<td class="description">HTTP connection</td></tr>
98d88c8d 8129</tbody></table>
798d6e29 8130<h4 class="returnvalue">Return Value</h4>
af268786 8131<p class="description">Content-Coding value or <code>NULL</code> for the identity coding.</p>
798d6e29 8132<h4 class="discussion">Discussion</h4>
b47dab17 8133<p class="discussion">This function uses the value of the Accepts-Encoding HTTP header and must be
798d6e29
MS
8134called after receiving a response from the server or a request from the
8135client. The value returned can be use in subsequent requests (for clients)
8136or in the response (for servers) in order to compress the content stream.
8137
8138</p>
b6008d6b 8139<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="httpGetCookie">httpGetCookie</a></h3>
05d62fc2 8140<p class="description">Get cookie data from the HTTP connection.</p>
798d6e29 8141<p class="code">
0350eba5 8142<span class="reserved">const</span> <span class="reserved">char</span> *httpGetCookie(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8143<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8144<table class="list"><tbody>
8145<tr><th>http</th>
b47dab17 8146<td class="description">HTTP connection</td></tr>
98d88c8d 8147</tbody></table>
798d6e29 8148<h4 class="returnvalue">Return Value</h4>
b47dab17 8149<p class="description">Cookie data or <code>NULL</code></p>
05d62fc2
MS
8150<h4 class="discussion">Discussion</h4>
8151<p class="discussion">This function returns any HTTP &quot;Set-Cookie:&quot; or &quot;Cookie:&quot; header data for the
8152given HTTP connection as described in RFC 6265. Use the
8153<a href="#httpGetCookieValue"><code>httpGetCookieValue</code></a> to get the value of a named &quot;Cookie:&quot; value.
8154
8155</p>
8156<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpGetCookieValue">httpGetCookieValue</a></h3>
8157<p class="description">Get the value of a named cookie from the HTTP connection.</p>
8158<p class="code">
8159<span class="reserved">char</span> *httpGetCookieValue(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
8160<h4 class="parameters">Parameters</h4>
8161<table class="list"><tbody>
8162<tr><th>http</th>
8163<td class="description">HTTP connection</td></tr>
8164<tr><th>name</th>
8165<td class="description">Cookie name</td></tr>
8166<tr><th>buffer</th>
8167<td class="description">Value buffer</td></tr>
8168<tr><th>bufsize</th>
8169<td class="description">Size of value buffer</td></tr>
8170</tbody></table>
8171<h4 class="returnvalue">Return Value</h4>
8172<p class="description">Cookie value or <code>NULL</code> if not present</p>
8173<h4 class="discussion">Discussion</h4>
8174<p class="discussion">This function copies the value of a named cookie in the HTTP &quot;Cookie:&quot; header
8175for the given HTTP connection as described in RFC 6265. Use the
8176<a href="#httpGetCookie"><code>httpGetCookie</code></a> function to get the original &quot;Cookie:&quot; string.
8177
8178</p>
b6008d6b 8179<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetDateString2">httpGetDateString2</a></h3>
b47dab17 8180<p class="description">Get a formatted date/time string from a time value.</p>
798d6e29 8181<p class="code">
0350eba5 8182<span class="reserved">const</span> <span class="reserved">char</span> *httpGetDateString2(time_t t, <span class="reserved">char</span> *s, <span class="reserved">int</span> slen);</p>
98d88c8d
MS
8183<h4 class="parameters">Parameters</h4>
8184<table class="list"><tbody>
8185<tr><th>t</th>
b47dab17 8186<td class="description">Time in seconds</td></tr>
98d88c8d 8187<tr><th>s</th>
b47dab17 8188<td class="description">String buffer</td></tr>
98d88c8d 8189<tr><th>slen</th>
b47dab17 8190<td class="description">Size of string buffer</td></tr>
98d88c8d 8191</tbody></table>
798d6e29 8192<h4 class="returnvalue">Return Value</h4>
b47dab17 8193<p class="description">Date/time string</p>
798d6e29 8194<h3 class="function"><a id="httpGetDateTime">httpGetDateTime</a></h3>
b47dab17 8195<p class="description">Get a time value from a formatted date/time string.</p>
798d6e29 8196<p class="code">
0350eba5 8197time_t httpGetDateTime(<span class="reserved">const</span> <span class="reserved">char</span> *s);</p>
798d6e29 8198<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8199<table class="list"><tbody>
8200<tr><th>s</th>
b47dab17 8201<td class="description">Date/time string</td></tr>
98d88c8d 8202</tbody></table>
798d6e29 8203<h4 class="returnvalue">Return Value</h4>
b47dab17 8204<p class="description">Time in seconds</p>
b6008d6b 8205<h3 class="function"><span class="info">&#160;CUPS 2.0&#160;</span><a id="httpGetEncryption">httpGetEncryption</a></h3>
b47dab17 8206<p class="description">Get the current encryption mode of a connection.</p>
798d6e29 8207<p class="code">
98d88c8d 8208<a href="#http_encryption_t">http_encryption_t</a> httpGetEncryption(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8209<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8210<table class="list"><tbody>
8211<tr><th>http</th>
b47dab17 8212<td class="description">HTTP connection</td></tr>
98d88c8d 8213</tbody></table>
798d6e29 8214<h4 class="returnvalue">Return Value</h4>
b47dab17 8215<p class="description">Current encryption mode</p>
798d6e29 8216<h4 class="discussion">Discussion</h4>
b47dab17 8217<p class="discussion">This function returns the encryption mode for the connection. Use the
798d6e29
MS
8218<a href="#httpIsEncrypted"><code>httpIsEncrypted</code></a> function to determine whether a TLS session has
8219been established.
8220
8221</p>
af268786
MS
8222<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpGetError">httpGetError</a></h3>
8223<p class="description">Get the last error on a connection.</p>
8224<p class="code">
0350eba5 8225<span class="reserved">int</span> httpGetError(<a href="#http_t">http_t</a> *http);</p>
af268786
MS
8226<h4 class="parameters">Parameters</h4>
8227<table class="list"><tbody>
8228<tr><th>http</th>
8229<td class="description">HTTP connection</td></tr>
8230</tbody></table>
8231<h4 class="returnvalue">Return Value</h4>
8232<p class="description">Error code (errno) value</p>
b6008d6b 8233<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpGetExpect">httpGetExpect</a></h3>
b47dab17 8234<p class="description">Get the value of the Expect header, if any.</p>
798d6e29 8235<p class="code">
98d88c8d 8236http_status_t httpGetExpect(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8237<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8238<table class="list"><tbody>
8239<tr><th>http</th>
b47dab17 8240<td class="description">HTTP connection</td></tr>
98d88c8d 8241</tbody></table>
798d6e29 8242<h4 class="returnvalue">Return Value</h4>
b47dab17 8243<p class="description">Expect: status, if any</p>
798d6e29 8244<h4 class="discussion">Discussion</h4>
b47dab17 8245<p class="discussion">Returns <code>HTTP_STATUS_NONE</code> if there is no Expect header, otherwise
798d6e29
MS
8246returns the expected HTTP status code, typically <code>HTTP_STATUS_CONTINUE</code>.
8247
8248</p>
b6008d6b 8249<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetFd">httpGetFd</a></h3>
b47dab17 8250<p class="description">Get the file descriptor associated with a connection.</p>
798d6e29 8251<p class="code">
0350eba5 8252<span class="reserved">int</span> httpGetFd(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8253<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8254<table class="list"><tbody>
8255<tr><th>http</th>
b47dab17 8256<td class="description">HTTP connection</td></tr>
98d88c8d 8257</tbody></table>
798d6e29 8258<h4 class="returnvalue">Return Value</h4>
b47dab17 8259<p class="description">File descriptor or -1 if none</p>
798d6e29 8260<h3 class="function"><a id="httpGetField">httpGetField</a></h3>
b47dab17 8261<p class="description">Get a field value from a request/response.</p>
798d6e29 8262<p class="code">
0350eba5 8263<span class="reserved">const</span> <span class="reserved">char</span> *httpGetField(<a href="#http_t">http_t</a> *http, <a href="#http_field_t">http_field_t</a> field);</p>
798d6e29 8264<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8265<table class="list"><tbody>
8266<tr><th>http</th>
b47dab17 8267<td class="description">HTTP connection</td></tr>
98d88c8d 8268<tr><th>field</th>
b47dab17 8269<td class="description">Field to get</td></tr>
98d88c8d 8270</tbody></table>
798d6e29 8271<h4 class="returnvalue">Return Value</h4>
b47dab17 8272<p class="description">Field value</p>
b6008d6b 8273<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetHostname">httpGetHostname</a></h3>
b47dab17 8274<p class="description">Get the FQDN for the connection or local system.</p>
798d6e29 8275<p class="code">
0350eba5 8276<span class="reserved">const</span> <span class="reserved">char</span> *httpGetHostname(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *s, <span class="reserved">int</span> slen);</p>
98d88c8d
MS
8277<h4 class="parameters">Parameters</h4>
8278<table class="list"><tbody>
8279<tr><th>http</th>
b47dab17 8280<td class="description">HTTP connection or NULL</td></tr>
98d88c8d 8281<tr><th>s</th>
b47dab17 8282<td class="description">String buffer for name</td></tr>
98d88c8d 8283<tr><th>slen</th>
b47dab17 8284<td class="description">Size of buffer</td></tr>
98d88c8d 8285</tbody></table>
798d6e29 8286<h4 class="returnvalue">Return Value</h4>
b47dab17 8287<p class="description">FQDN for connection or system</p>
798d6e29 8288<h4 class="discussion">Discussion</h4>
b47dab17 8289<p class="discussion">When &quot;http&quot; points to a connected socket, return the hostname or
798d6e29
MS
8290address that was used in the call to httpConnect() or httpConnectEncrypt(),
8291or the address of the client for the connection from httpAcceptConnection().
8292Otherwise, return the FQDN for the local system using both gethostname()
8293and gethostbyname() to get the local hostname with domain.
8294
8295</p>
8296<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetKeepAlive">httpGetKeepAlive</a></h3>
b47dab17 8297<p class="description">Get the current Keep-Alive state of the connection.</p>
798d6e29 8298<p class="code">
98d88c8d 8299<a href="#http_keepalive_t">http_keepalive_t</a> httpGetKeepAlive(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8300<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8301<table class="list"><tbody>
8302<tr><th>http</th>
b47dab17 8303<td class="description">HTTP connection</td></tr>
98d88c8d 8304</tbody></table>
798d6e29 8305<h4 class="returnvalue">Return Value</h4>
b47dab17 8306<p class="description">Keep-Alive state</p>
b6008d6b 8307<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetLength2">httpGetLength2</a></h3>
af268786 8308<p class="description">Get the amount of data remaining from the Content-Length or Transfer-Encoding fields.</p>
798d6e29 8309<p class="code">
98d88c8d 8310off_t httpGetLength2(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8311<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8312<table class="list"><tbody>
8313<tr><th>http</th>
b47dab17 8314<td class="description">HTTP connection</td></tr>
98d88c8d 8315</tbody></table>
798d6e29 8316<h4 class="returnvalue">Return Value</h4>
b47dab17 8317<p class="description">Content length</p>
798d6e29 8318<h4 class="discussion">Discussion</h4>
b47dab17 8319<p class="discussion">This function returns the complete content length, even for
798d6e29
MS
8320content larger than 2^31 - 1.
8321
8322</p>
8323<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetPending">httpGetPending</a></h3>
b47dab17 8324<p class="description">Get the number of bytes that are buffered for writing.</p>
798d6e29 8325<p class="code">
98d88c8d 8326size_t httpGetPending(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8327<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8328<table class="list"><tbody>
8329<tr><th>http</th>
b47dab17 8330<td class="description">HTTP connection</td></tr>
98d88c8d 8331</tbody></table>
798d6e29 8332<h4 class="returnvalue">Return Value</h4>
b47dab17 8333<p class="description">Number of bytes buffered</p>
798d6e29 8334<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetReady">httpGetReady</a></h3>
b47dab17 8335<p class="description">Get the number of bytes that can be read without blocking.</p>
798d6e29 8336<p class="code">
98d88c8d 8337size_t httpGetReady(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8338<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8339<table class="list"><tbody>
8340<tr><th>http</th>
b47dab17 8341<td class="description">HTTP connection</td></tr>
98d88c8d 8342</tbody></table>
798d6e29 8343<h4 class="returnvalue">Return Value</h4>
b47dab17 8344<p class="description">Number of bytes available</p>
798d6e29 8345<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpGetRemaining">httpGetRemaining</a></h3>
af268786 8346<p class="description">Get the number of remaining bytes in the message body or current chunk.</p>
798d6e29 8347<p class="code">
98d88c8d 8348size_t httpGetRemaining(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8349<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8350<table class="list"><tbody>
8351<tr><th>http</th>
b47dab17 8352<td class="description">HTTP connection</td></tr>
98d88c8d 8353</tbody></table>
798d6e29 8354<h4 class="returnvalue">Return Value</h4>
b47dab17 8355<p class="description">Remaining bytes</p>
798d6e29 8356<h4 class="discussion">Discussion</h4>
b47dab17 8357<p class="discussion">The <a href="#httpIsChunked"><code>httpIsChunked</code></a> function can be used to determine whether the
798d6e29
MS
8358message body is chunked or fixed-length.
8359
05d62fc2
MS
8360</p>
8361<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpGetSecurity">httpGetSecurity</a></h3>
8362<p class="description">Get the TLS version and cipher suite used by a connection.</p>
8363<p class="code">
8364<span class="reserved">const</span> <span class="reserved">char</span> *httpGetSecurity(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
8365<h4 class="parameters">Parameters</h4>
8366<table class="list"><tbody>
8367<tr><th>http</th>
8368<td class="description">HTTP connection</td></tr>
8369<tr><th>buffer</th>
8370<td class="description">String buffer</td></tr>
8371<tr><th>bufsize</th>
8372<td class="description">Size of buffer</td></tr>
8373</tbody></table>
8374<h4 class="returnvalue">Return Value</h4>
8375<p class="description">Security information or <code>NULL</code> if not encrypted</p>
8376<h4 class="discussion">Discussion</h4>
8377<p class="discussion">This function gets the TLS version and cipher suite being used by a
8378connection, if any. The string is copied to &quot;buffer&quot; and is of the form
8379&quot;TLS/major.minor CipherSuite&quot;. If not encrypted, the buffer is cleared to
8380the empty string.
8381
798d6e29
MS
8382</p>
8383<h3 class="function"><a id="httpGetState">httpGetState</a></h3>
b47dab17 8384<p class="description">Get the current state of the HTTP request.</p>
798d6e29 8385<p class="code">
98d88c8d 8386<a href="#http_state_t">http_state_t</a> httpGetState(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8387<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8388<table class="list"><tbody>
8389<tr><th>http</th>
b47dab17 8390<td class="description">HTTP connection</td></tr>
98d88c8d 8391</tbody></table>
798d6e29 8392<h4 class="returnvalue">Return Value</h4>
b47dab17 8393<p class="description">HTTP state</p>
b6008d6b 8394<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetStatus">httpGetStatus</a></h3>
b47dab17 8395<p class="description">Get the status of the last HTTP request.</p>
798d6e29 8396<p class="code">
98d88c8d 8397http_status_t httpGetStatus(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8398<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8399<table class="list"><tbody>
8400<tr><th>http</th>
b47dab17 8401<td class="description">HTTP connection</td></tr>
98d88c8d 8402</tbody></table>
798d6e29 8403<h4 class="returnvalue">Return Value</h4>
b47dab17 8404<p class="description">HTTP status</p>
b6008d6b 8405<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpGetSubField2">httpGetSubField2</a></h3>
b47dab17 8406<p class="description">Get a sub-field value.</p>
798d6e29 8407<p class="code">
0350eba5 8408<span class="reserved">char</span> *httpGetSubField2(<a href="#http_t">http_t</a> *http, <a href="#http_field_t">http_field_t</a> field, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">char</span> *value, <span class="reserved">int</span> valuelen);</p>
98d88c8d
MS
8409<h4 class="parameters">Parameters</h4>
8410<table class="list"><tbody>
8411<tr><th>http</th>
b47dab17 8412<td class="description">HTTP connection</td></tr>
98d88c8d 8413<tr><th>field</th>
b47dab17 8414<td class="description">Field index</td></tr>
98d88c8d 8415<tr><th>name</th>
b47dab17 8416<td class="description">Name of sub-field</td></tr>
98d88c8d 8417<tr><th>value</th>
b47dab17 8418<td class="description">Value string</td></tr>
98d88c8d 8419<tr><th>valuelen</th>
b47dab17 8420<td class="description">Size of value buffer</td></tr>
98d88c8d 8421</tbody></table>
798d6e29 8422<h4 class="returnvalue">Return Value</h4>
b47dab17 8423<p class="description">Value or <code>NULL</code></p>
798d6e29 8424<h3 class="function"><a id="httpGetVersion">httpGetVersion</a></h3>
b47dab17 8425<p class="description">Get the HTTP version at the other end.</p>
798d6e29 8426<p class="code">
98d88c8d 8427<a href="#http_version_t">http_version_t</a> httpGetVersion(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8428<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8429<table class="list"><tbody>
8430<tr><th>http</th>
b47dab17 8431<td class="description">HTTP connection</td></tr>
98d88c8d 8432</tbody></table>
798d6e29 8433<h4 class="returnvalue">Return Value</h4>
b47dab17 8434<p class="description">Version number</p>
af268786 8435<h3 class="function"><a id="httpGets2">httpGets2</a></h3>
b47dab17 8436<p class="description">Get a line of text from a HTTP connection.</p>
798d6e29 8437<p class="code">
0350eba5 8438<span class="reserved">char</span> *httpGets2(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *line, size_t length);</p>
98d88c8d
MS
8439<h4 class="parameters">Parameters</h4>
8440<table class="list"><tbody>
af268786
MS
8441<tr><th>http</th>
8442<td class="description">HTTP connection</td></tr>
98d88c8d 8443<tr><th>line</th>
b47dab17 8444<td class="description">Line to read into</td></tr>
98d88c8d 8445<tr><th>length</th>
b47dab17 8446<td class="description">Max length of buffer</td></tr>
98d88c8d 8447</tbody></table>
798d6e29 8448<h4 class="returnvalue">Return Value</h4>
b47dab17 8449<p class="description">Line or <code>NULL</code></p>
798d6e29 8450<h3 class="function"><a id="httpInitialize">httpInitialize</a></h3>
b47dab17 8451<p class="description">Initialize the HTTP interface library and set the
af268786 8452 default HTTP proxy (if any).</p>
98d88c8d 8453<p class="code">
0350eba5 8454<span class="reserved">void</span> httpInitialize(<span class="reserved">void</span>);</p>
798d6e29 8455<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpIsChunked">httpIsChunked</a></h3>
b47dab17 8456<p class="description">Report whether a message body is chunked.</p>
798d6e29 8457<p class="code">
0350eba5 8458<span class="reserved">int</span> httpIsChunked(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8459<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8460<table class="list"><tbody>
8461<tr><th>http</th>
b47dab17 8462<td class="description">HTTP connection</td></tr>
98d88c8d 8463</tbody></table>
798d6e29 8464<h4 class="returnvalue">Return Value</h4>
b47dab17 8465<p class="description">1 if chunked, 0 if not</p>
798d6e29 8466<h4 class="discussion">Discussion</h4>
b47dab17 8467<p class="discussion">This function returns non-zero if the message body is composed of
798d6e29
MS
8468variable-length chunks.
8469
8470</p>
8471<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpIsEncrypted">httpIsEncrypted</a></h3>
b47dab17 8472<p class="description">Report whether a connection is encrypted.</p>
798d6e29 8473<p class="code">
0350eba5 8474<span class="reserved">int</span> httpIsEncrypted(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8475<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8476<table class="list"><tbody>
8477<tr><th>http</th>
b47dab17 8478<td class="description">HTTP connection</td></tr>
98d88c8d 8479</tbody></table>
798d6e29 8480<h4 class="returnvalue">Return Value</h4>
b47dab17 8481<p class="description">1 if encrypted, 0 if not</p>
798d6e29 8482<h4 class="discussion">Discussion</h4>
b47dab17 8483<p class="discussion">This function returns non-zero if the connection is currently encrypted.
798d6e29
MS
8484
8485</p>
af268786
MS
8486<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="httpMD5">httpMD5</a></h3>
8487<p class="description">Compute the MD5 sum of the username:group:password.</p>
798d6e29 8488<p class="code">
0350eba5 8489<span class="reserved">char</span> *httpMD5(<span class="reserved">const</span> <span class="reserved">char</span> *username, <span class="reserved">const</span> <span class="reserved">char</span> *realm, <span class="reserved">const</span> <span class="reserved">char</span> *passwd, <span class="reserved">char</span> md5[33]);</p>
98d88c8d
MS
8490<h4 class="parameters">Parameters</h4>
8491<table class="list"><tbody>
af268786
MS
8492<tr><th>username</th>
8493<td class="description">User name</td></tr>
8494<tr><th>realm</th>
8495<td class="description">Realm name</td></tr>
8496<tr><th>passwd</th>
8497<td class="description">Password string</td></tr>
8498<tr><th>md5[33]</th>
8499<td class="description">MD5 string</td></tr>
98d88c8d 8500</tbody></table>
798d6e29 8501<h4 class="returnvalue">Return Value</h4>
af268786
MS
8502<p class="description">MD5 sum</p>
8503<h4 class="discussion">Discussion</h4>
8504<p class="discussion">The function was used for HTTP Digest authentication. Since CUPS 2.4.0
8505it produces an empty string. Please use <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> instead.
8506
8507</p>
8508<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="httpMD5Final">httpMD5Final</a></h3>
8509<p class="description">Combine the MD5 sum of the username, group, and password
8510 with the server-supplied nonce value, method, and
8511 request-uri.</p>
798d6e29 8512<p class="code">
0350eba5 8513<span class="reserved">char</span> *httpMD5Final(<span class="reserved">const</span> <span class="reserved">char</span> *nonce, <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *resource, <span class="reserved">char</span> md5[33]);</p>
798d6e29 8514<h4 class="parameters">Parameters</h4>
98d88c8d 8515<table class="list"><tbody>
af268786
MS
8516<tr><th>nonce</th>
8517<td class="description">Server nonce value</td></tr>
8518<tr><th>method</th>
8519<td class="description">METHOD (GET, POST, etc.)</td></tr>
8520<tr><th>resource</th>
8521<td class="description">Resource path</td></tr>
8522<tr><th>md5[33]</th>
8523<td class="description">MD5 sum</td></tr>
98d88c8d 8524</tbody></table>
798d6e29 8525<h4 class="returnvalue">Return Value</h4>
af268786
MS
8526<p class="description">New sum</p>
8527<h4 class="discussion">Discussion</h4>
8528<p class="discussion">The function was used for HTTP Digest authentication. Since CUPS 2.4.0
8529it produces an empty string. Please use <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> instead.
8530
8531</p>
8532<h3 class="function"><span class="info">&#160;DEPRECATED&#160;</span><a id="httpMD5String">httpMD5String</a></h3>
8533<p class="description">Convert an MD5 sum to a character string.</p>
8534<p class="code">
0350eba5 8535<span class="reserved">char</span> *httpMD5String(<span class="reserved">const</span> <span class="reserved">unsigned</span> <span class="reserved">char</span> *sum, <span class="reserved">char</span> md5[33]);</p>
af268786
MS
8536<h4 class="parameters">Parameters</h4>
8537<table class="list"><tbody>
8538<tr><th>sum</th>
8539<td class="description">MD5 sum data</td></tr>
8540<tr><th>md5[33]</th>
8541<td class="description">MD5 sum in hex</td></tr>
8542</tbody></table>
8543<h4 class="returnvalue">Return Value</h4>
8544<p class="description">MD5 sum in hex</p>
8545<h4 class="discussion">Discussion</h4>
8546<p class="discussion">The function was used for HTTP Digest authentication. Since CUPS 2.4.0
8547it produces an empty string. Please use <a href="#cupsDoAuthentication"><code>cupsDoAuthentication</code></a> instead.
8548
8549</p>
b6008d6b 8550<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpPeek">httpPeek</a></h3>
b47dab17 8551<p class="description">Peek at data from a HTTP connection.</p>
798d6e29 8552<p class="code">
0350eba5 8553ssize_t httpPeek(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *buffer, size_t length);</p>
98d88c8d
MS
8554<h4 class="parameters">Parameters</h4>
8555<table class="list"><tbody>
8556<tr><th>http</th>
b47dab17 8557<td class="description">HTTP connection</td></tr>
98d88c8d 8558<tr><th>buffer</th>
b47dab17 8559<td class="description">Buffer for data</td></tr>
98d88c8d 8560<tr><th>length</th>
b47dab17 8561<td class="description">Maximum number of bytes</td></tr>
98d88c8d 8562</tbody></table>
798d6e29 8563<h4 class="returnvalue">Return Value</h4>
b47dab17 8564<p class="description">Number of bytes copied</p>
798d6e29 8565<h4 class="discussion">Discussion</h4>
b47dab17 8566<p class="discussion">This function copies available data from the given HTTP connection, reading
798d6e29 8567a buffer as needed. The data is still available for reading using
65bebeac 8568<a href="#httpRead2"><code>httpRead2</code></a>.<br>
798d6e29
MS
8569<br>
8570For non-blocking connections the usual timeouts apply.
8571
8572</p>
b6008d6b 8573<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpRead2">httpRead2</a></h3>
b47dab17 8574<p class="description">Read data from a HTTP connection.</p>
798d6e29 8575<p class="code">
0350eba5 8576ssize_t httpRead2(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *buffer, size_t length);</p>
98d88c8d
MS
8577<h4 class="parameters">Parameters</h4>
8578<table class="list"><tbody>
8579<tr><th>http</th>
b47dab17 8580<td class="description">HTTP connection</td></tr>
98d88c8d 8581<tr><th>buffer</th>
b47dab17 8582<td class="description">Buffer for data</td></tr>
98d88c8d 8583<tr><th>length</th>
b47dab17 8584<td class="description">Maximum number of bytes</td></tr>
98d88c8d 8585</tbody></table>
798d6e29 8586<h4 class="returnvalue">Return Value</h4>
b47dab17 8587<p class="description">Number of bytes read</p>
b6008d6b 8588<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpReadRequest">httpReadRequest</a></h3>
b47dab17 8589<p class="description">Read a HTTP request from a connection.</p>
798d6e29 8590<p class="code">
0350eba5 8591<a href="#http_state_t">http_state_t</a> httpReadRequest(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *uri, size_t urilen);</p>
98d88c8d
MS
8592<h4 class="parameters">Parameters</h4>
8593<table class="list"><tbody>
8594<tr><th>http</th>
b47dab17 8595<td class="description">HTTP connection</td></tr>
98d88c8d 8596<tr><th>uri</th>
b47dab17 8597<td class="description">URI buffer</td></tr>
98d88c8d 8598<tr><th>urilen</th>
b47dab17 8599<td class="description">Size of URI buffer</td></tr>
98d88c8d 8600</tbody></table>
798d6e29 8601<h4 class="returnvalue">Return Value</h4>
b47dab17 8602<p class="description">New state of connection</p>
798d6e29 8603<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpResolveHostname">httpResolveHostname</a></h3>
b47dab17 8604<p class="description">Resolve the hostname of the HTTP connection
af268786 8605 address.</p>
798d6e29 8606<p class="code">
0350eba5 8607<span class="reserved">const</span> <span class="reserved">char</span> *httpResolveHostname(<a href="#http_t">http_t</a> *http, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
98d88c8d
MS
8608<h4 class="parameters">Parameters</h4>
8609<table class="list"><tbody>
8610<tr><th>http</th>
b47dab17 8611<td class="description">HTTP connection</td></tr>
98d88c8d 8612<tr><th>buffer</th>
b47dab17 8613<td class="description">Hostname buffer</td></tr>
98d88c8d 8614<tr><th>bufsize</th>
b47dab17 8615<td class="description">Size of buffer</td></tr>
98d88c8d 8616</tbody></table>
798d6e29 8617<h4 class="returnvalue">Return Value</h4>
b47dab17 8618<p class="description">Resolved hostname or <code>NULL</code></p>
af268786
MS
8619<h3 class="function"><a id="httpResolveURI">httpResolveURI</a></h3>
8620<p class="description">Resolve a DNS-SD URI.</p>
798d6e29 8621<p class="code">
0350eba5 8622<span class="reserved">const</span> <span class="reserved">char</span> *httpResolveURI(<span class="reserved">const</span> <span class="reserved">char</span> *uri, <span class="reserved">char</span> *resolved_uri, size_t resolved_size, <a href="#http_resolve_t">http_resolve_t</a> options, <a href="#http_resolve_cb_t">http_resolve_cb_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
98d88c8d
MS
8623<h4 class="parameters">Parameters</h4>
8624<table class="list"><tbody>
af268786
MS
8625<tr><th>uri</th>
8626<td class="description">DNS-SD URI</td></tr>
8627<tr><th>resolved_uri</th>
8628<td class="description">Buffer for resolved URI</td></tr>
8629<tr><th>resolved_size</th>
8630<td class="description">Size of URI buffer</td></tr>
8631<tr><th>options</th>
8632<td class="description">Resolve options</td></tr>
8633<tr><th>cb</th>
8634<td class="description">Continue callback function</td></tr>
8635<tr><th>cb_data</th>
8636<td class="description">Context pointer for callback</td></tr>
98d88c8d 8637</tbody></table>
798d6e29 8638<h4 class="returnvalue">Return Value</h4>
af268786
MS
8639<p class="description">Resolved URI</p>
8640<h4 class="discussion">Discussion</h4>
8641<p class="discussion">This function resolves a DNS-SD URI of the form
8642&quot;scheme://service-instance-name._protocol._tcp.domain/...&quot;. The &quot;options&quot;
8643parameter specifies a bitfield of resolution options including:
8644
8645</p><ul>
8646<li><code>HTTP_RESOLVE_DEFAULT</code>: Use default options
8647</li>
8648<li><code>HTTP_RESOLVE_FQDN</code>: Resolve the fully-qualified domain name instead of an IP address
8649</li>
8650<li><code>HTTP_RESOLVE_FAXOUT</code>: Resolve the FaxOut service instead of Print (IPP/IPPS)</li>
8651</ul>
8652<p class="discussion">The &quot;cb&quot; parameter specifies a callback that allows resolution to be
8653terminated. The callback is provided the &quot;cb_data&quot; value and returns a
8654<code>bool</code> value that is <code>true</code> to continue and <code>false</code> to stop. If no callback
8655is specified (&quot;cb&quot; is <code>NULL</code>), then this function will block up to 90 seconds
8656to resolve the specified URI.</p>
b6008d6b 8657<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpSeparateURI">httpSeparateURI</a></h3>
b47dab17 8658<p class="description">Separate a Universal Resource Identifier into its
af268786 8659 components.</p>
798d6e29 8660<p class="code">
0350eba5 8661<a href="#http_uri_status_t">http_uri_status_t</a> httpSeparateURI(<a href="#http_uri_coding_t">http_uri_coding_t</a> decoding, <span class="reserved">const</span> <span class="reserved">char</span> *uri, <span class="reserved">char</span> *scheme, <span class="reserved">int</span> schemelen, <span class="reserved">char</span> *username, <span class="reserved">int</span> usernamelen, <span class="reserved">char</span> *host, <span class="reserved">int</span> hostlen, <span class="reserved">int</span> *port, <span class="reserved">char</span> *resource, <span class="reserved">int</span> resourcelen);</p>
98d88c8d
MS
8662<h4 class="parameters">Parameters</h4>
8663<table class="list"><tbody>
8664<tr><th>decoding</th>
b47dab17 8665<td class="description">Decoding flags</td></tr>
98d88c8d 8666<tr><th>uri</th>
b47dab17 8667<td class="description">Universal Resource Identifier</td></tr>
98d88c8d 8668<tr><th>scheme</th>
b47dab17 8669<td class="description">Scheme (http, https, etc.)</td></tr>
98d88c8d 8670<tr><th>schemelen</th>
b47dab17 8671<td class="description">Size of scheme buffer</td></tr>
98d88c8d 8672<tr><th>username</th>
b47dab17 8673<td class="description">Username</td></tr>
98d88c8d 8674<tr><th>usernamelen</th>
b47dab17 8675<td class="description">Size of username buffer</td></tr>
98d88c8d 8676<tr><th>host</th>
b47dab17 8677<td class="description">Hostname</td></tr>
98d88c8d 8678<tr><th>hostlen</th>
b47dab17 8679<td class="description">Size of hostname buffer</td></tr>
98d88c8d 8680<tr><th>port</th>
b47dab17 8681<td class="description">Port number to use</td></tr>
98d88c8d 8682<tr><th>resource</th>
b47dab17 8683<td class="description">Resource/filename</td></tr>
98d88c8d 8684<tr><th>resourcelen</th>
b47dab17 8685<td class="description">Size of resource buffer</td></tr>
98d88c8d 8686</tbody></table>
798d6e29 8687<h4 class="returnvalue">Return Value</h4>
b47dab17 8688<p class="description">Result of separation</p>
b6008d6b 8689<h3 class="function"><span class="info">&#160;CUPS 1.3&#160;</span><a id="httpSetAuthString">httpSetAuthString</a></h3>
b47dab17 8690<p class="description">Set the current authorization string.</p>
98d88c8d 8691<p class="code">
0350eba5 8692<span class="reserved">void</span> httpSetAuthString(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *scheme, <span class="reserved">const</span> <span class="reserved">char</span> *data);</p>
98d88c8d
MS
8693<h4 class="parameters">Parameters</h4>
8694<table class="list"><tbody>
8695<tr><th>http</th>
b47dab17 8696<td class="description">HTTP connection</td></tr>
98d88c8d 8697<tr><th>scheme</th>
b47dab17 8698<td class="description">Auth scheme (NULL to clear it)</td></tr>
98d88c8d 8699<tr><th>data</th>
b47dab17 8700<td class="description">Auth data (NULL for none)</td></tr>
98d88c8d
MS
8701</tbody></table>
8702<h4 class="discussion">Discussion</h4>
b47dab17 8703<p class="discussion">This function just stores a copy of the current authorization string in
65bebeac
MS
8704the HTTP connection object. You must still call <a href="#httpSetField"><code>httpSetField</code></a> to set
8705<code>HTTP_FIELD_AUTHORIZATION</code> prior to issuing a HTTP request using
af268786 8706<a href="#httpWriteRequest"><code>httpWriteRequest</code></a>.
798d6e29
MS
8707
8708</p>
af268786
MS
8709<h3 class="function"><a id="httpSetBlocking">httpSetBlocking</a></h3>
8710<p class="description">Set blocking/non-blocking behavior on a connection.</p>
8711<p class="code">
0350eba5 8712<span class="reserved">void</span> httpSetBlocking(<a href="#http_t">http_t</a> *http, <span class="reserved">bool</span> b);</p>
af268786
MS
8713<h4 class="parameters">Parameters</h4>
8714<table class="list"><tbody>
8715<tr><th>http</th>
8716<td class="description">HTTP connection</td></tr>
8717<tr><th>b</th>
8718<td class="description"><code>true</code> for blocking, <code>false</code> for non-blocking</td></tr>
8719</tbody></table>
b6008d6b 8720<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="httpSetCookie">httpSetCookie</a></h3>
05d62fc2 8721<p class="description">Add Set-Cookie value(s).</p>
798d6e29 8722<p class="code">
0350eba5 8723<span class="reserved">void</span> httpSetCookie(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *cookie);</p>
798d6e29 8724<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8725<table class="list"><tbody>
8726<tr><th>http</th>
05d62fc2 8727<td class="description">HTTP cnnection</td></tr>
98d88c8d 8728<tr><th>cookie</th>
b47dab17 8729<td class="description">Cookie string</td></tr>
98d88c8d 8730</tbody></table>
05d62fc2
MS
8731<h4 class="discussion">Discussion</h4>
8732<p class="discussion">This function adds one or more Set-Cookie header values that will be sent to
8733the client with the <a href="#httpWriteResponse"><code>httpWriteResponse</code></a> function. Each value conforms
8734to the format defined in RFC 6265. Multiple values can be passed in the
8735&quot;cookie&quot; string separated by a newline character.<br>
8736<br>
8737Call the <a href="#httpClearCookies"><code>httpClearCookies</code></a> function to clear all Set-Cookie values.
8738
8739</p>
b6008d6b 8740<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpSetDefaultField">httpSetDefaultField</a></h3>
b47dab17 8741<p class="description">Set the default value of an HTTP header.</p>
98d88c8d 8742<p class="code">
0350eba5 8743<span class="reserved">void</span> httpSetDefaultField(<a href="#http_t">http_t</a> *http, <a href="#http_field_t">http_field_t</a> field, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
98d88c8d
MS
8744<h4 class="parameters">Parameters</h4>
8745<table class="list"><tbody>
8746<tr><th>http</th>
b47dab17 8747<td class="description">HTTP connection</td></tr>
98d88c8d 8748<tr><th>field</th>
b47dab17 8749<td class="description">Field index</td></tr>
98d88c8d 8750<tr><th>value</th>
b47dab17 8751<td class="description">Value</td></tr>
98d88c8d
MS
8752</tbody></table>
8753<h4 class="discussion">Discussion</h4>
b47dab17 8754<p class="discussion">Currently only <code>HTTP_FIELD_ACCEPT_ENCODING</code>, <code>HTTP_FIELD_SERVER</code>,
798d6e29
MS
8755and <code>HTTP_FIELD_USER_AGENT</code> can be set.
8756
8757</p>
af268786
MS
8758<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpSetEncryption">httpSetEncryption</a></h3>
8759<p class="description">Set the required encryption on the link.</p>
8760<p class="code">
0350eba5 8761<span class="reserved">bool</span> httpSetEncryption(<a href="#http_t">http_t</a> *http, <a href="#http_encryption_t">http_encryption_t</a> e);</p>
af268786
MS
8762<h4 class="parameters">Parameters</h4>
8763<table class="list"><tbody>
8764<tr><th>http</th>
8765<td class="description">HTTP connection</td></tr>
8766<tr><th>e</th>
8767<td class="description">New encryption preference</td></tr>
8768</tbody></table>
8769<h4 class="returnvalue">Return Value</h4>
8770<p class="description"><code>true</code> on success, <code>false</code> on error</p>
b6008d6b 8771<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpSetExpect">httpSetExpect</a></h3>
b47dab17 8772<p class="description">Set the Expect: header in a request.</p>
798d6e29 8773<p class="code">
0350eba5 8774<span class="reserved">void</span> httpSetExpect(<a href="#http_t">http_t</a> *http, http_status_t expect);</p>
798d6e29 8775<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8776<table class="list"><tbody>
8777<tr><th>http</th>
b47dab17 8778<td class="description">HTTP connection</td></tr>
98d88c8d 8779<tr><th>expect</th>
af268786 8780<td class="description">HTTP status to expect (<code>HTTP_STATUS_CONTINUE</code>)</td></tr>
98d88c8d
MS
8781</tbody></table>
8782<h4 class="discussion">Discussion</h4>
b47dab17 8783<p class="discussion">Currently only <code>HTTP_STATUS_CONTINUE</code> is supported for the &quot;expect&quot;
798d6e29
MS
8784argument.
8785
8786</p>
8787<h3 class="function"><a id="httpSetField">httpSetField</a></h3>
b47dab17 8788<p class="description">Set the value of an HTTP header.</p>
798d6e29 8789<p class="code">
0350eba5 8790<span class="reserved">void</span> httpSetField(<a href="#http_t">http_t</a> *http, <a href="#http_field_t">http_field_t</a> field, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
98d88c8d
MS
8791<h4 class="parameters">Parameters</h4>
8792<table class="list"><tbody>
8793<tr><th>http</th>
b47dab17 8794<td class="description">HTTP connection</td></tr>
98d88c8d 8795<tr><th>field</th>
b47dab17 8796<td class="description">Field index</td></tr>
98d88c8d 8797<tr><th>value</th>
b47dab17 8798<td class="description">Value</td></tr>
98d88c8d
MS
8799</tbody></table>
8800<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpSetKeepAlive">httpSetKeepAlive</a></h3>
b47dab17 8801<p class="description">Set the current Keep-Alive state of a connection.</p>
98d88c8d 8802<p class="code">
0350eba5 8803<span class="reserved">void</span> httpSetKeepAlive(<a href="#http_t">http_t</a> *http, <a href="#http_keepalive_t">http_keepalive_t</a> keep_alive);</p>
98d88c8d
MS
8804<h4 class="parameters">Parameters</h4>
8805<table class="list"><tbody>
8806<tr><th>http</th>
b47dab17 8807<td class="description">HTTP connection</td></tr>
98d88c8d 8808<tr><th>keep_alive</th>
b47dab17 8809<td class="description">New Keep-Alive value</td></tr>
98d88c8d 8810</tbody></table>
b6008d6b 8811<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpSetLength">httpSetLength</a></h3>
b47dab17 8812<p class="description">Set the content-length and content-encoding.</p>
98d88c8d 8813<p class="code">
0350eba5 8814<span class="reserved">void</span> httpSetLength(<a href="#http_t">http_t</a> *http, size_t length);</p>
98d88c8d
MS
8815<h4 class="parameters">Parameters</h4>
8816<table class="list"><tbody>
8817<tr><th>http</th>
b47dab17 8818<td class="description">HTTP connection</td></tr>
98d88c8d 8819<tr><th>length</th>
b47dab17 8820<td class="description">Length (0 for chunked)</td></tr>
98d88c8d 8821</tbody></table>
b6008d6b 8822<h3 class="function"><span class="info">&#160;CUPS 1.5&#160;</span><a id="httpSetTimeout">httpSetTimeout</a></h3>
b47dab17 8823<p class="description">Set read/write timeouts and an optional callback.</p>
98d88c8d 8824<p class="code">
0350eba5 8825<span class="reserved">void</span> httpSetTimeout(<a href="#http_t">http_t</a> *http, <span class="reserved">double</span> timeout, <a href="#http_timeout_cb_t">http_timeout_cb_t</a> cb, <span class="reserved">void</span> *user_data);</p>
98d88c8d
MS
8826<h4 class="parameters">Parameters</h4>
8827<table class="list"><tbody>
8828<tr><th>http</th>
b47dab17 8829<td class="description">HTTP connection</td></tr>
98d88c8d 8830<tr><th>timeout</th>
af268786 8831<td class="description">Number of seconds for timeout, must be greater than <code>0.0</code></td></tr>
98d88c8d 8832<tr><th>cb</th>
b47dab17 8833<td class="description">Callback function or <code>NULL</code></td></tr>
98d88c8d 8834<tr><th>user_data</th>
b47dab17 8835<td class="description">User data pointer</td></tr>
98d88c8d
MS
8836</tbody></table>
8837<h4 class="discussion">Discussion</h4>
b47dab17 8838<p class="discussion">The optional timeout callback receives both the HTTP connection and a user
798d6e29
MS
8839data pointer and must return 1 to continue or 0 to error (time) out.
8840
8841</p>
98d88c8d 8842<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpShutdown">httpShutdown</a></h3>
b47dab17 8843<p class="description">Shutdown one side of an HTTP connection.</p>
798d6e29 8844<p class="code">
0350eba5 8845<span class="reserved">void</span> httpShutdown(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8846<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8847<table class="list"><tbody>
8848<tr><th>http</th>
b47dab17 8849<td class="description">HTTP connection</td></tr>
98d88c8d 8850</tbody></table>
798d6e29 8851<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpStateString">httpStateString</a></h3>
b47dab17 8852<p class="description">Return the string describing a HTTP state value.</p>
798d6e29 8853<p class="code">
0350eba5 8854<span class="reserved">const</span> <span class="reserved">char</span> *httpStateString(<a href="#http_state_t">http_state_t</a> state);</p>
798d6e29 8855<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8856<table class="list"><tbody>
8857<tr><th>state</th>
b47dab17 8858<td class="description">HTTP state value</td></tr>
98d88c8d 8859</tbody></table>
798d6e29 8860<h4 class="returnvalue">Return Value</h4>
b47dab17 8861<p class="description">State string</p>
af268786 8862<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpStatusString">httpStatusString</a></h3>
b47dab17 8863<p class="description">Return a short string describing a HTTP status code.</p>
798d6e29 8864<p class="code">
0350eba5 8865<span class="reserved">const</span> <span class="reserved">char</span> *httpStatusString(http_status_t status);</p>
798d6e29 8866<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8867<table class="list"><tbody>
8868<tr><th>status</th>
b47dab17 8869<td class="description">HTTP status code</td></tr>
98d88c8d 8870</tbody></table>
798d6e29 8871<h4 class="returnvalue">Return Value</h4>
b47dab17 8872<p class="description">Localized status string</p>
798d6e29 8873<h4 class="discussion">Discussion</h4>
b47dab17 8874<p class="discussion">The returned string is localized to the current POSIX locale and is based
af268786
MS
8875on the status strings defined in RFC 7231.
8876
8877</p>
798d6e29 8878<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpURIStatusString">httpURIStatusString</a></h3>
b47dab17 8879<p class="description">Return a string describing a URI status code.</p>
798d6e29 8880<p class="code">
0350eba5 8881<span class="reserved">const</span> <span class="reserved">char</span> *httpURIStatusString(<a href="#http_uri_status_t">http_uri_status_t</a> status);</p>
798d6e29 8882<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8883<table class="list"><tbody>
8884<tr><th>status</th>
b47dab17 8885<td class="description">URI status code</td></tr>
98d88c8d 8886</tbody></table>
798d6e29 8887<h4 class="returnvalue">Return Value</h4>
b47dab17 8888<p class="description">Localized status string</p>
798d6e29 8889<h3 class="function"><a id="httpUpdate">httpUpdate</a></h3>
b47dab17 8890<p class="description">Update the current HTTP state for incoming data.</p>
798d6e29 8891<p class="code">
98d88c8d 8892http_status_t httpUpdate(<a href="#http_t">http_t</a> *http);</p>
798d6e29 8893<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8894<table class="list"><tbody>
8895<tr><th>http</th>
b47dab17 8896<td class="description">HTTP connection</td></tr>
98d88c8d 8897</tbody></table>
798d6e29 8898<h4 class="returnvalue">Return Value</h4>
b47dab17 8899<p class="description">HTTP status</p>
b6008d6b 8900<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="httpWait">httpWait</a></h3>
b47dab17 8901<p class="description">Wait for data available on a connection.</p>
798d6e29 8902<p class="code">
0350eba5 8903<span class="reserved">int</span> httpWait(<a href="#http_t">http_t</a> *http, <span class="reserved">int</span> msec);</p>
798d6e29 8904<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8905<table class="list"><tbody>
8906<tr><th>http</th>
b47dab17 8907<td class="description">HTTP connection</td></tr>
98d88c8d 8908<tr><th>msec</th>
b47dab17 8909<td class="description">Milliseconds to wait</td></tr>
98d88c8d 8910</tbody></table>
798d6e29 8911<h4 class="returnvalue">Return Value</h4>
b47dab17 8912<p class="description">1 if data is available, 0 otherwise</p>
b6008d6b 8913<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="httpWrite2">httpWrite2</a></h3>
b47dab17 8914<p class="description">Write data to a HTTP connection.</p>
798d6e29 8915<p class="code">
0350eba5 8916ssize_t httpWrite2(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *buffer, size_t length);</p>
98d88c8d
MS
8917<h4 class="parameters">Parameters</h4>
8918<table class="list"><tbody>
8919<tr><th>http</th>
b47dab17 8920<td class="description">HTTP connection</td></tr>
98d88c8d 8921<tr><th>buffer</th>
b47dab17 8922<td class="description">Buffer for data</td></tr>
98d88c8d 8923<tr><th>length</th>
b47dab17 8924<td class="description">Number of bytes to write</td></tr>
98d88c8d 8925</tbody></table>
798d6e29 8926<h4 class="returnvalue">Return Value</h4>
b47dab17 8927<p class="description">Number of bytes written</p>
af268786
MS
8928<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="httpWriteRequest">httpWriteRequest</a></h3>
8929<p class="description">Send a HTTP request.</p>
8930<p class="code">
0350eba5 8931<span class="reserved">bool</span> httpWriteRequest(<a href="#http_t">http_t</a> *http, <span class="reserved">const</span> <span class="reserved">char</span> *method, <span class="reserved">const</span> <span class="reserved">char</span> *uri);</p>
af268786
MS
8932<h4 class="parameters">Parameters</h4>
8933<table class="list"><tbody>
8934<tr><th>http</th>
8935<td class="description">HTTP connection</td></tr>
8936<tr><th>method</th>
8937<td class="description">Method string (&quot;GET&quot;, &quot;POST&quot;, etc.)</td></tr>
8938<tr><th>uri</th>
8939<td class="description">URI</td></tr>
8940</tbody></table>
8941<h4 class="returnvalue">Return Value</h4>
8942<p class="description"><code>true</code> on success, <code>false</code> on error</p>
b6008d6b 8943<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="httpWriteResponse">httpWriteResponse</a></h3>
b47dab17 8944<p class="description">Write a HTTP response to a client connection.</p>
798d6e29 8945<p class="code">
0350eba5 8946<span class="reserved">int</span> httpWriteResponse(<a href="#http_t">http_t</a> *http, http_status_t status);</p>
798d6e29 8947<h4 class="parameters">Parameters</h4>
98d88c8d
MS
8948<table class="list"><tbody>
8949<tr><th>http</th>
b47dab17 8950<td class="description">HTTP connection</td></tr>
98d88c8d 8951<tr><th>status</th>
b47dab17 8952<td class="description">Status code</td></tr>
98d88c8d 8953</tbody></table>
798d6e29 8954<h4 class="returnvalue">Return Value</h4>
b47dab17 8955<p class="description">0 on success, -1 on error</p>
798d6e29 8956<h3 class="function"><a id="ippAddBoolean">ippAddBoolean</a></h3>
b47dab17 8957<p class="description">Add a boolean attribute to an IPP message.</p>
798d6e29 8958<p class="code">
0350eba5 8959<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">char</span> value);</p>
98d88c8d
MS
8960<h4 class="parameters">Parameters</h4>
8961<table class="list"><tbody>
8962<tr><th>ipp</th>
b47dab17 8963<td class="description">IPP message</td></tr>
98d88c8d 8964<tr><th>group</th>
b47dab17 8965<td class="description">IPP group</td></tr>
98d88c8d 8966<tr><th>name</th>
b47dab17 8967<td class="description">Name of attribute</td></tr>
98d88c8d 8968<tr><th>value</th>
b47dab17 8969<td class="description">Value of attribute</td></tr>
98d88c8d 8970</tbody></table>
798d6e29 8971<h4 class="returnvalue">Return Value</h4>
b47dab17 8972<p class="description">New attribute</p>
798d6e29 8973<h4 class="discussion">Discussion</h4>
af268786 8974<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
8975the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
8976<br>
af268786 8977The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
8978(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
8979event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
8980(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
8981(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
8982<h3 class="function"><a id="ippAddBooleans">ippAddBooleans</a></h3>
b47dab17 8983<p class="description">Add an array of boolean values.</p>
798d6e29 8984<p class="code">
0350eba5 8985<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <span class="reserved">const</span> <span class="reserved">char</span> *values);</p>
98d88c8d
MS
8986<h4 class="parameters">Parameters</h4>
8987<table class="list"><tbody>
8988<tr><th>ipp</th>
b47dab17 8989<td class="description">IPP message</td></tr>
98d88c8d 8990<tr><th>group</th>
b47dab17 8991<td class="description">IPP group</td></tr>
98d88c8d 8992<tr><th>name</th>
b47dab17 8993<td class="description">Name of attribute</td></tr>
98d88c8d 8994<tr><th>num_values</th>
b47dab17 8995<td class="description">Number of values</td></tr>
98d88c8d 8996<tr><th>values</th>
b47dab17 8997<td class="description">Values</td></tr>
98d88c8d 8998</tbody></table>
798d6e29 8999<h4 class="returnvalue">Return Value</h4>
b47dab17 9000<p class="description">New attribute</p>
798d6e29 9001<h4 class="discussion">Discussion</h4>
af268786 9002<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9003the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9004<br>
af268786 9005The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9006(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9007event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9008(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9009(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
b6008d6b 9010<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="ippAddCollection">ippAddCollection</a></h3>
b47dab17 9011<p class="description">Add a collection value.</p>
798d6e29 9012<p class="code">
0350eba5 9013<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <a href="#ipp_t">ipp_t</a> *value);</p>
98d88c8d
MS
9014<h4 class="parameters">Parameters</h4>
9015<table class="list"><tbody>
9016<tr><th>ipp</th>
b47dab17 9017<td class="description">IPP message</td></tr>
98d88c8d 9018<tr><th>group</th>
b47dab17 9019<td class="description">IPP group</td></tr>
98d88c8d 9020<tr><th>name</th>
b47dab17 9021<td class="description">Name of attribute</td></tr>
98d88c8d 9022<tr><th>value</th>
b47dab17 9023<td class="description">Value</td></tr>
98d88c8d 9024</tbody></table>
798d6e29 9025<h4 class="returnvalue">Return Value</h4>
b47dab17 9026<p class="description">New attribute</p>
798d6e29 9027<h4 class="discussion">Discussion</h4>
af268786 9028<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9029the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9030<br>
af268786 9031The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9032(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9033event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9034(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9035(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
9036
9037</p>
b6008d6b 9038<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="ippAddCollections">ippAddCollections</a></h3>
b47dab17 9039<p class="description">Add an array of collection values.</p>
798d6e29 9040<p class="code">
0350eba5 9041<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <span class="reserved">const</span> <a href="#ipp_t">ipp_t</a> **values);</p>
98d88c8d
MS
9042<h4 class="parameters">Parameters</h4>
9043<table class="list"><tbody>
9044<tr><th>ipp</th>
b47dab17 9045<td class="description">IPP message</td></tr>
98d88c8d 9046<tr><th>group</th>
b47dab17 9047<td class="description">IPP group</td></tr>
98d88c8d 9048<tr><th>name</th>
b47dab17 9049<td class="description">Name of attribute</td></tr>
98d88c8d 9050<tr><th>num_values</th>
b47dab17 9051<td class="description">Number of values</td></tr>
98d88c8d 9052<tr><th>values</th>
b47dab17 9053<td class="description">Values</td></tr>
98d88c8d 9054</tbody></table>
798d6e29 9055<h4 class="returnvalue">Return Value</h4>
b47dab17 9056<p class="description">New attribute</p>
798d6e29 9057<h4 class="discussion">Discussion</h4>
af268786
MS
9058<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
9059the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9060<br>
9061The &quot;group&quot; parameter specifies the IPP attribute group tag: none
9062(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9063event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9064(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9065(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
9066
9067</p>
9068<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippAddCredentialsString">ippAddCredentialsString</a></h3>
9069<p class="description">Add a credentials string attribute to an IPP message.</p>
9070<p class="code">
0350eba5 9071<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCredentialsString(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *credentials);</p>
af268786
MS
9072<h4 class="parameters">Parameters</h4>
9073<table class="list"><tbody>
9074<tr><th>ipp</th>
9075<td class="description">IPP message</td></tr>
9076<tr><th>group</th>
9077<td class="description">IPP group</td></tr>
9078<tr><th>name</th>
9079<td class="description">Attribute name</td></tr>
9080<tr><th>credentials</th>
9081<td class="description">Credentials string</td></tr>
9082</tbody></table>
9083<h4 class="returnvalue">Return Value</h4>
9084<p class="description">New attribute</p>
9085<h4 class="discussion">Discussion</h4>
9086<p class="discussion">This function adds a 1setOf text attribute to an IPP message corresponding to
9087the specified credentials string.<br>
9088<br>
9089The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9090the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9091<br>
af268786 9092The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9093(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9094event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9095(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9096(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
9097
9098</p>
9099<h3 class="function"><a id="ippAddDate">ippAddDate</a></h3>
b47dab17 9100<p class="description">Add a dateTime attribute to an IPP message.</p>
798d6e29 9101<p class="code">
0350eba5 9102<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <a href="#ipp_uchar_t">ipp_uchar_t</a> *value);</p>
98d88c8d
MS
9103<h4 class="parameters">Parameters</h4>
9104<table class="list"><tbody>
9105<tr><th>ipp</th>
b47dab17 9106<td class="description">IPP message</td></tr>
98d88c8d 9107<tr><th>group</th>
b47dab17 9108<td class="description">IPP group</td></tr>
98d88c8d 9109<tr><th>name</th>
b47dab17 9110<td class="description">Name of attribute</td></tr>
98d88c8d 9111<tr><th>value</th>
b47dab17 9112<td class="description">Value</td></tr>
98d88c8d 9113</tbody></table>
798d6e29 9114<h4 class="returnvalue">Return Value</h4>
b47dab17 9115<p class="description">New attribute</p>
798d6e29 9116<h4 class="discussion">Discussion</h4>
af268786 9117<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9118the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9119<br>
af268786 9120The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9121(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9122event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9123(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9124(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
9125<h3 class="function"><a id="ippAddInteger">ippAddInteger</a></h3>
b47dab17 9126<p class="description">Add a integer attribute to an IPP message.</p>
798d6e29 9127<p class="code">
0350eba5 9128<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> value);</p>
98d88c8d
MS
9129<h4 class="parameters">Parameters</h4>
9130<table class="list"><tbody>
9131<tr><th>ipp</th>
b47dab17 9132<td class="description">IPP message</td></tr>
98d88c8d 9133<tr><th>group</th>
b47dab17 9134<td class="description">IPP group</td></tr>
98d88c8d 9135<tr><th>value_tag</th>
b47dab17 9136<td class="description">Type of attribute</td></tr>
98d88c8d 9137<tr><th>name</th>
b47dab17 9138<td class="description">Name of attribute</td></tr>
98d88c8d 9139<tr><th>value</th>
b47dab17 9140<td class="description">Value of attribute</td></tr>
98d88c8d 9141</tbody></table>
798d6e29 9142<h4 class="returnvalue">Return Value</h4>
b47dab17 9143<p class="description">New attribute</p>
798d6e29 9144<h4 class="discussion">Discussion</h4>
af268786
MS
9145<p class="discussion">This function adds an integer or enum attribute to an IPP message.<br>
9146<br>
9147The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9148the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9149<br>
af268786 9150The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9151(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9152event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9153(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9154(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9155<br>
9156Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer
9157(<code>IPP_TAG_INTEGER</code>).</p>
9158<h3 class="function"><a id="ippAddIntegers">ippAddIntegers</a></h3>
b47dab17 9159<p class="description">Add an array of integer values.</p>
798d6e29 9160<p class="code">
0350eba5 9161<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <span class="reserved">const</span> <span class="reserved">int</span> *values);</p>
98d88c8d
MS
9162<h4 class="parameters">Parameters</h4>
9163<table class="list"><tbody>
9164<tr><th>ipp</th>
b47dab17 9165<td class="description">IPP message</td></tr>
98d88c8d 9166<tr><th>group</th>
b47dab17 9167<td class="description">IPP group</td></tr>
98d88c8d 9168<tr><th>value_tag</th>
b47dab17 9169<td class="description">Type of attribute</td></tr>
98d88c8d 9170<tr><th>name</th>
b47dab17 9171<td class="description">Name of attribute</td></tr>
98d88c8d 9172<tr><th>num_values</th>
b47dab17 9173<td class="description">Number of values</td></tr>
98d88c8d 9174<tr><th>values</th>
b47dab17 9175<td class="description">Values</td></tr>
98d88c8d 9176</tbody></table>
798d6e29 9177<h4 class="returnvalue">Return Value</h4>
b47dab17 9178<p class="description">New attribute</p>
798d6e29 9179<h4 class="discussion">Discussion</h4>
af268786 9180<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9181the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9182<br>
af268786 9183The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9184(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9185event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9186(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9187(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9188<br>
9189Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer
9190(<code>IPP_TAG_INTEGER</code>).</p>
b6008d6b 9191<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippAddOctetString">ippAddOctetString</a></h3>
b47dab17 9192<p class="description">Add an octetString value to an IPP message.</p>
798d6e29 9193<p class="code">
0350eba5 9194<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">void</span> *data, <span class="reserved">int</span> datalen);</p>
98d88c8d
MS
9195<h4 class="parameters">Parameters</h4>
9196<table class="list"><tbody>
9197<tr><th>ipp</th>
b47dab17 9198<td class="description">IPP message</td></tr>
98d88c8d 9199<tr><th>group</th>
b47dab17 9200<td class="description">IPP group</td></tr>
98d88c8d 9201<tr><th>name</th>
b47dab17 9202<td class="description">Name of attribute</td></tr>
98d88c8d 9203<tr><th>data</th>
b47dab17 9204<td class="description">octetString data</td></tr>
98d88c8d 9205<tr><th>datalen</th>
b47dab17 9206<td class="description">Length of data in bytes</td></tr>
98d88c8d 9207</tbody></table>
798d6e29 9208<h4 class="returnvalue">Return Value</h4>
b47dab17 9209<p class="description">New attribute</p>
798d6e29 9210<h4 class="discussion">Discussion</h4>
af268786 9211<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9212the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9213<br>
af268786 9214The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9215(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9216event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9217(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9218(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
9219
9220</p>
b6008d6b 9221<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippAddOutOfBand">ippAddOutOfBand</a></h3>
b47dab17 9222<p class="description">Add an out-of-band value to an IPP message.</p>
798d6e29 9223<p class="code">
0350eba5 9224<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOutOfBand(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
98d88c8d
MS
9225<h4 class="parameters">Parameters</h4>
9226<table class="list"><tbody>
9227<tr><th>ipp</th>
b47dab17 9228<td class="description">IPP message</td></tr>
98d88c8d 9229<tr><th>group</th>
b47dab17 9230<td class="description">IPP group</td></tr>
98d88c8d 9231<tr><th>value_tag</th>
b47dab17 9232<td class="description">Type of attribute</td></tr>
98d88c8d 9233<tr><th>name</th>
b47dab17 9234<td class="description">Name of attribute</td></tr>
98d88c8d 9235</tbody></table>
798d6e29 9236<h4 class="returnvalue">Return Value</h4>
b47dab17 9237<p class="description">New attribute</p>
798d6e29 9238<h4 class="discussion">Discussion</h4>
af268786 9239<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9240the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9241<br>
af268786 9242The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9243(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9244event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9245(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9246(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9247<br>
9248Supported out-of-band values include unsupported-value
9249(<code>IPP_TAG_UNSUPPORTED_VALUE</code>), default (<code>IPP_TAG_DEFAULT</code>), unknown
9250(<code>IPP_TAG_UNKNOWN</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable
9251(<code>IPP_TAG_NOTSETTABLE</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), and
9252admin-define (<code>IPP_TAG_ADMINDEFINE</code>).
9253
9254</p>
9255<h3 class="function"><a id="ippAddRange">ippAddRange</a></h3>
b47dab17 9256<p class="description">Add a range of values to an IPP message.</p>
798d6e29 9257<p class="code">
0350eba5 9258<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> lower, <span class="reserved">int</span> upper);</p>
98d88c8d
MS
9259<h4 class="parameters">Parameters</h4>
9260<table class="list"><tbody>
9261<tr><th>ipp</th>
b47dab17 9262<td class="description">IPP message</td></tr>
98d88c8d 9263<tr><th>group</th>
b47dab17 9264<td class="description">IPP group</td></tr>
98d88c8d 9265<tr><th>name</th>
b47dab17 9266<td class="description">Name of attribute</td></tr>
98d88c8d 9267<tr><th>lower</th>
b47dab17 9268<td class="description">Lower value</td></tr>
98d88c8d 9269<tr><th>upper</th>
b47dab17 9270<td class="description">Upper value</td></tr>
98d88c8d 9271</tbody></table>
798d6e29 9272<h4 class="returnvalue">Return Value</h4>
b47dab17 9273<p class="description">New attribute</p>
798d6e29 9274<h4 class="discussion">Discussion</h4>
af268786 9275<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9276the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9277<br>
af268786 9278The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9279(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9280event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9281(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9282(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9283<br>
af268786 9284The &quot;lower&quot; parameter must be less than or equal to the &quot;upper&quot; parameter.</p>
798d6e29 9285<h3 class="function"><a id="ippAddRanges">ippAddRanges</a></h3>
b47dab17 9286<p class="description">Add ranges of values to an IPP message.</p>
798d6e29 9287<p class="code">
0350eba5 9288<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <span class="reserved">const</span> <span class="reserved">int</span> *lower, <span class="reserved">const</span> <span class="reserved">int</span> *upper);</p>
98d88c8d
MS
9289<h4 class="parameters">Parameters</h4>
9290<table class="list"><tbody>
9291<tr><th>ipp</th>
b47dab17 9292<td class="description">IPP message</td></tr>
98d88c8d 9293<tr><th>group</th>
b47dab17 9294<td class="description">IPP group</td></tr>
98d88c8d 9295<tr><th>name</th>
b47dab17 9296<td class="description">Name of attribute</td></tr>
98d88c8d 9297<tr><th>num_values</th>
b47dab17 9298<td class="description">Number of values</td></tr>
98d88c8d 9299<tr><th>lower</th>
b47dab17 9300<td class="description">Lower values</td></tr>
98d88c8d 9301<tr><th>upper</th>
b47dab17 9302<td class="description">Upper values</td></tr>
98d88c8d 9303</tbody></table>
798d6e29 9304<h4 class="returnvalue">Return Value</h4>
b47dab17 9305<p class="description">New attribute</p>
798d6e29 9306<h4 class="discussion">Discussion</h4>
af268786 9307<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9308the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9309<br>
af268786 9310The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9311(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9312event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9313(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9314(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
9315<h3 class="function"><a id="ippAddResolution">ippAddResolution</a></h3>
b47dab17 9316<p class="description">Add a resolution value to an IPP message.</p>
798d6e29 9317<p class="code">
0350eba5 9318<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <a href="#ipp_res_t">ipp_res_t</a> units, <span class="reserved">int</span> xres, <span class="reserved">int</span> yres);</p>
98d88c8d
MS
9319<h4 class="parameters">Parameters</h4>
9320<table class="list"><tbody>
9321<tr><th>ipp</th>
b47dab17 9322<td class="description">IPP message</td></tr>
98d88c8d 9323<tr><th>group</th>
b47dab17 9324<td class="description">IPP group</td></tr>
98d88c8d 9325<tr><th>name</th>
b47dab17 9326<td class="description">Name of attribute</td></tr>
98d88c8d 9327<tr><th>units</th>
b47dab17 9328<td class="description">Units for resolution</td></tr>
98d88c8d 9329<tr><th>xres</th>
b47dab17 9330<td class="description">X resolution</td></tr>
98d88c8d 9331<tr><th>yres</th>
b47dab17 9332<td class="description">Y resolution</td></tr>
98d88c8d 9333</tbody></table>
798d6e29 9334<h4 class="returnvalue">Return Value</h4>
b47dab17 9335<p class="description">New attribute</p>
798d6e29 9336<h4 class="discussion">Discussion</h4>
af268786 9337<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9338the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9339<br>
af268786 9340The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9341(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9342event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9343(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9344(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
9345<h3 class="function"><a id="ippAddResolutions">ippAddResolutions</a></h3>
b47dab17 9346<p class="description">Add resolution values to an IPP message.</p>
798d6e29 9347<p class="code">
0350eba5 9348<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <a href="#ipp_res_t">ipp_res_t</a> units, <span class="reserved">const</span> <span class="reserved">int</span> *xres, <span class="reserved">const</span> <span class="reserved">int</span> *yres);</p>
98d88c8d
MS
9349<h4 class="parameters">Parameters</h4>
9350<table class="list"><tbody>
9351<tr><th>ipp</th>
b47dab17 9352<td class="description">IPP message</td></tr>
98d88c8d 9353<tr><th>group</th>
b47dab17 9354<td class="description">IPP group</td></tr>
98d88c8d 9355<tr><th>name</th>
b47dab17 9356<td class="description">Name of attribute</td></tr>
98d88c8d 9357<tr><th>num_values</th>
b47dab17 9358<td class="description">Number of values</td></tr>
98d88c8d 9359<tr><th>units</th>
b47dab17 9360<td class="description">Units for resolution</td></tr>
98d88c8d 9361<tr><th>xres</th>
b47dab17 9362<td class="description">X resolutions</td></tr>
98d88c8d 9363<tr><th>yres</th>
b47dab17 9364<td class="description">Y resolutions</td></tr>
98d88c8d 9365</tbody></table>
798d6e29 9366<h4 class="returnvalue">Return Value</h4>
b47dab17 9367<p class="description">New attribute</p>
798d6e29 9368<h4 class="discussion">Discussion</h4>
af268786 9369<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9370the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9371<br>
af268786 9372The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9373(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9374event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9375(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9376(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p>
9377<h3 class="function"><a id="ippAddSeparator">ippAddSeparator</a></h3>
b47dab17 9378<p class="description">Add a group separator to an IPP message.</p>
798d6e29 9379<p class="code">
98d88c8d 9380<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddSeparator(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 9381<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9382<table class="list"><tbody>
9383<tr><th>ipp</th>
b47dab17 9384<td class="description">IPP message</td></tr>
98d88c8d 9385</tbody></table>
798d6e29 9386<h4 class="returnvalue">Return Value</h4>
b47dab17 9387<p class="description">New attribute</p>
798d6e29 9388<h4 class="discussion">Discussion</h4>
af268786 9389<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9390the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.</p>
9391<h3 class="function"><a id="ippAddString">ippAddString</a></h3>
b47dab17 9392<p class="description">Add a language-encoded string to an IPP message.</p>
798d6e29 9393<p class="code">
0350eba5 9394<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *language, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
98d88c8d
MS
9395<h4 class="parameters">Parameters</h4>
9396<table class="list"><tbody>
9397<tr><th>ipp</th>
b47dab17 9398<td class="description">IPP message</td></tr>
98d88c8d 9399<tr><th>group</th>
b47dab17 9400<td class="description">IPP group</td></tr>
98d88c8d 9401<tr><th>value_tag</th>
b47dab17 9402<td class="description">Type of attribute</td></tr>
98d88c8d 9403<tr><th>name</th>
b47dab17 9404<td class="description">Name of attribute</td></tr>
98d88c8d 9405<tr><th>language</th>
b47dab17 9406<td class="description">Language code</td></tr>
98d88c8d 9407<tr><th>value</th>
b47dab17 9408<td class="description">Value</td></tr>
98d88c8d 9409</tbody></table>
798d6e29 9410<h4 class="returnvalue">Return Value</h4>
b47dab17 9411<p class="description">New attribute</p>
798d6e29 9412<h4 class="discussion">Discussion</h4>
af268786 9413<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9414the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9415<br>
af268786 9416The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9417(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9418event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9419(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9420(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9421<br>
9422Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
9423(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
9424(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
af268786
MS
9425(<code>IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
9426(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
9427(`IPP_TAG_URISCHEME`).
9428
9429The "language" parameter must be non-`NULL` for nameWithLanguage and
9430textWithLanguage string values and must be `NULL` for all other string values.</code></p>
b6008d6b 9431<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippAddStringf">ippAddStringf</a></h3>
b47dab17 9432<p class="description">Add a formatted string to an IPP message.</p>
798d6e29 9433<p class="code">
0350eba5 9434<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringf(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *language, <span class="reserved">const</span> <span class="reserved">char</span> *format, ...);</p>
98d88c8d
MS
9435<h4 class="parameters">Parameters</h4>
9436<table class="list"><tbody>
9437<tr><th>ipp</th>
b47dab17 9438<td class="description">IPP message</td></tr>
98d88c8d 9439<tr><th>group</th>
b47dab17 9440<td class="description">IPP group</td></tr>
98d88c8d 9441<tr><th>value_tag</th>
b47dab17 9442<td class="description">Type of attribute</td></tr>
98d88c8d 9443<tr><th>name</th>
b47dab17 9444<td class="description">Name of attribute</td></tr>
98d88c8d 9445<tr><th>language</th>
b47dab17 9446<td class="description">Language code (<code>NULL</code> for default)</td></tr>
98d88c8d 9447<tr><th>format</th>
b47dab17 9448<td class="description">Printf-style format string</td></tr>
98d88c8d 9449<tr><th>...</th>
b47dab17 9450<td class="description">Additional arguments as needed</td></tr>
98d88c8d 9451</tbody></table>
798d6e29 9452<h4 class="returnvalue">Return Value</h4>
b47dab17 9453<p class="description">New attribute</p>
798d6e29 9454<h4 class="discussion">Discussion</h4>
af268786 9455<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9456the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9457<br>
af268786 9458The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9459(<code>IPP_TAG_ZERO</code>, for member attributes), document
9460(<code>IPP_TAG_DOCUMENT</code>), event notification
9461(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
9462printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>),
9463or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9464<br>
9465Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
9466(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
9467(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
af268786
MS
9468(<code>IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
9469(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
9470(`IPP_TAG_URISCHEME`).
9471
9472The "language" parameter must be non-`NULL` for nameWithLanguage
9473and textWithLanguage string values and must be `NULL` for all other
9474string values.
9475
9476The "format" parameter uses formatting characters compatible with the
798d6e29
MS
9477printf family of standard functions. Additional arguments follow it as
9478needed. The formatted string is truncated as needed to the maximum length of
9479the corresponding value type.
9480
b6008d6b
MS
9481</code>since CUPS 1.7@</p>
9482<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippAddStringfv">ippAddStringfv</a></h3>
b47dab17 9483<p class="description">Add a formatted string to an IPP message.</p>
798d6e29 9484<p class="code">
0350eba5 9485<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStringfv(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *language, <span class="reserved">const</span> <span class="reserved">char</span> *format, va_list ap);</p>
98d88c8d
MS
9486<h4 class="parameters">Parameters</h4>
9487<table class="list"><tbody>
9488<tr><th>ipp</th>
b47dab17 9489<td class="description">IPP message</td></tr>
98d88c8d 9490<tr><th>group</th>
b47dab17 9491<td class="description">IPP group</td></tr>
98d88c8d 9492<tr><th>value_tag</th>
b47dab17 9493<td class="description">Type of attribute</td></tr>
98d88c8d 9494<tr><th>name</th>
b47dab17 9495<td class="description">Name of attribute</td></tr>
98d88c8d 9496<tr><th>language</th>
b47dab17 9497<td class="description">Language code (<code>NULL</code> for default)</td></tr>
98d88c8d 9498<tr><th>format</th>
b47dab17 9499<td class="description">Printf-style format string</td></tr>
98d88c8d 9500<tr><th>ap</th>
b47dab17 9501<td class="description">Additional arguments</td></tr>
98d88c8d 9502</tbody></table>
798d6e29 9503<h4 class="returnvalue">Return Value</h4>
b47dab17 9504<p class="description">New attribute</p>
798d6e29 9505<h4 class="discussion">Discussion</h4>
af268786 9506<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9507the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9508<br>
af268786 9509The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9510(<code>IPP_TAG_ZERO</code>, for member attributes), document
9511(<code>IPP_TAG_DOCUMENT</code>), event notification
9512(<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation (<code>IPP_TAG_OPERATION</code>),
9513printer (<code>IPP_TAG_PRINTER</code>), subscription (<code>IPP_TAG_SUBSCRIPTION</code>),
9514or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9515<br>
9516Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
9517(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
9518(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
af268786
MS
9519(<code>IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
9520(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
9521(`IPP_TAG_URISCHEME`).
9522
9523The "language" parameter must be non-`NULL` for nameWithLanguage
9524and textWithLanguage string values and must be `NULL` for all other
9525string values.
9526
9527The "format" parameter uses formatting characters compatible with the
798d6e29 9528printf family of standard functions. Additional arguments are passed in the
af268786 9529stdarg pointer "ap". The formatted string is truncated as needed to the
798d6e29
MS
9530maximum length of the corresponding value type.
9531
b6008d6b 9532</code>since CUPS 1.7@</p>
798d6e29 9533<h3 class="function"><a id="ippAddStrings">ippAddStrings</a></h3>
b47dab17 9534<p class="description">Add language-encoded strings to an IPP message.</p>
798d6e29 9535<p class="code">
0350eba5 9536<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group, ipp_tag_t value_tag, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> num_values, <span class="reserved">const</span> <span class="reserved">char</span> *language, <span class="reserved">const</span> <span class="reserved">char</span> *const *values);</p>
98d88c8d
MS
9537<h4 class="parameters">Parameters</h4>
9538<table class="list"><tbody>
9539<tr><th>ipp</th>
b47dab17 9540<td class="description">IPP message</td></tr>
98d88c8d 9541<tr><th>group</th>
b47dab17 9542<td class="description">IPP group</td></tr>
98d88c8d 9543<tr><th>value_tag</th>
b47dab17 9544<td class="description">Type of attribute</td></tr>
98d88c8d 9545<tr><th>name</th>
b47dab17 9546<td class="description">Name of attribute</td></tr>
98d88c8d 9547<tr><th>num_values</th>
b47dab17 9548<td class="description">Number of values</td></tr>
98d88c8d 9549<tr><th>language</th>
b47dab17 9550<td class="description">Language code (<code>NULL</code> for default)</td></tr>
98d88c8d 9551<tr><th>values</th>
b47dab17 9552<td class="description">Values</td></tr>
98d88c8d 9553</tbody></table>
798d6e29 9554<h4 class="returnvalue">Return Value</h4>
b47dab17 9555<p class="description">New attribute</p>
798d6e29 9556<h4 class="discussion">Discussion</h4>
af268786 9557<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
9558the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
9559<br>
af268786 9560The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
9561(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
9562event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
9563(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
9564(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br>
9565<br>
9566Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword
9567(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType
9568(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage
af268786
MS
9569(<code>IPP_TAG_NAMELANG), text (`IPP_TAG_TEXT`), textWithLanguage
9570(`IPP_TAG_TEXTLANG`), uri (`IPP_TAG_URI`), and uriScheme
9571(`IPP_TAG_URISCHEME`).
9572
9573The "language" parameter must be non-`NULL` for nameWithLanguage and
9574textWithLanguage string values and must be `NULL` for all other string values.</code></p>
b6008d6b 9575<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippAttributeString">ippAttributeString</a></h3>
b47dab17 9576<p class="description">Convert the attribute's value to a string.</p>
798d6e29 9577<p class="code">
0350eba5 9578size_t ippAttributeString(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">char</span> *buffer, size_t bufsize);</p>
98d88c8d
MS
9579<h4 class="parameters">Parameters</h4>
9580<table class="list"><tbody>
9581<tr><th>attr</th>
b47dab17 9582<td class="description">Attribute</td></tr>
98d88c8d 9583<tr><th>buffer</th>
b47dab17 9584<td class="description">String buffer or NULL</td></tr>
98d88c8d 9585<tr><th>bufsize</th>
b47dab17 9586<td class="description">Size of string buffer</td></tr>
98d88c8d 9587</tbody></table>
798d6e29 9588<h4 class="returnvalue">Return Value</h4>
b47dab17 9589<p class="description">Number of bytes less nul</p>
798d6e29 9590<h4 class="discussion">Discussion</h4>
b47dab17 9591<p class="discussion">Returns the number of bytes that would be written, not including the
798d6e29
MS
9592trailing nul. The buffer pointer can be NULL to get the required length,
9593just like (v)snprintf.
9594
9595</p>
b6008d6b 9596<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippContainsInteger">ippContainsInteger</a></h3>
b47dab17 9597<p class="description">Determine whether an attribute contains the
af268786 9598 specified value or is within the list of ranges.</p>
798d6e29 9599<p class="code">
0350eba5 9600<span class="reserved">int</span> ippContainsInteger(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> value);</p>
798d6e29 9601<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9602<table class="list"><tbody>
9603<tr><th>attr</th>
b47dab17 9604<td class="description">Attribute</td></tr>
98d88c8d 9605<tr><th>value</th>
b47dab17 9606<td class="description">Integer/enum value</td></tr>
98d88c8d 9607</tbody></table>
798d6e29 9608<h4 class="returnvalue">Return Value</h4>
b47dab17 9609<p class="description">1 on a match, 0 on no match</p>
798d6e29 9610<h4 class="discussion">Discussion</h4>
b47dab17 9611<p class="discussion">Returns non-zero when the attribute contains either a matching integer or
798d6e29
MS
9612enum value, or the value falls within one of the rangeOfInteger values for
9613the attribute.
9614
9615</p>
b6008d6b 9616<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippContainsString">ippContainsString</a></h3>
b47dab17 9617<p class="description">Determine whether an attribute contains the
af268786 9618 specified string value.</p>
798d6e29 9619<p class="code">
0350eba5 9620<span class="reserved">int</span> ippContainsString(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
798d6e29 9621<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9622<table class="list"><tbody>
9623<tr><th>attr</th>
b47dab17 9624<td class="description">Attribute</td></tr>
98d88c8d 9625<tr><th>value</th>
b47dab17 9626<td class="description">String value</td></tr>
98d88c8d 9627</tbody></table>
798d6e29 9628<h4 class="returnvalue">Return Value</h4>
b47dab17 9629<p class="description">1 on a match, 0 on no match</p>
798d6e29 9630<h4 class="discussion">Discussion</h4>
b47dab17 9631<p class="discussion">Returns non-zero when the attribute contains a matching charset, keyword,
65bebeac 9632naturalLanguage, mimeMediaType, name, text, uri, or uriScheme value.
798d6e29
MS
9633
9634</p>
b6008d6b 9635<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippCopyAttribute">ippCopyAttribute</a></h3>
b47dab17 9636<p class="description">Copy an attribute.</p>
798d6e29 9637<p class="code">
0350eba5 9638<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippCopyAttribute(<a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *srcattr, <span class="reserved">int</span> quickcopy);</p>
98d88c8d
MS
9639<h4 class="parameters">Parameters</h4>
9640<table class="list"><tbody>
9641<tr><th>dst</th>
b47dab17 9642<td class="description">Destination IPP message</td></tr>
98d88c8d 9643<tr><th>srcattr</th>
b47dab17 9644<td class="description">Attribute to copy</td></tr>
98d88c8d 9645<tr><th>quickcopy</th>
b47dab17 9646<td class="description">1 for a referenced copy, 0 for normal</td></tr>
98d88c8d 9647</tbody></table>
798d6e29 9648<h4 class="returnvalue">Return Value</h4>
b47dab17 9649<p class="description">New attribute</p>
798d6e29 9650<h4 class="discussion">Discussion</h4>
b47dab17 9651<p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message.
af268786 9652When &quot;quickcopy&quot; is non-zero, a &quot;shallow&quot; reference copy of the attribute is
798d6e29
MS
9653created - this should only be done as long as the original source IPP message will
9654not be freed for the life of the destination.
9655
9656</p>
b6008d6b 9657<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippCopyAttributes">ippCopyAttributes</a></h3>
b47dab17 9658<p class="description">Copy attributes from one IPP message to another.</p>
798d6e29 9659<p class="code">
0350eba5 9660<span class="reserved">int</span> ippCopyAttributes(<a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_t">ipp_t</a> *src, <span class="reserved">int</span> quickcopy, <a href="#ipp_copy_cb_t">ipp_copy_cb_t</a> cb, <span class="reserved">void</span> *context);</p>
98d88c8d
MS
9661<h4 class="parameters">Parameters</h4>
9662<table class="list"><tbody>
9663<tr><th>dst</th>
b47dab17 9664<td class="description">Destination IPP message</td></tr>
98d88c8d 9665<tr><th>src</th>
b47dab17 9666<td class="description">Source IPP message</td></tr>
98d88c8d 9667<tr><th>quickcopy</th>
b47dab17 9668<td class="description">1 for a referenced copy, 0 for normal</td></tr>
98d88c8d 9669<tr><th>cb</th>
b47dab17 9670<td class="description">Copy callback or <code>NULL</code> for none</td></tr>
98d88c8d 9671<tr><th>context</th>
b47dab17 9672<td class="description">Context pointer</td></tr>
98d88c8d 9673</tbody></table>
798d6e29 9674<h4 class="returnvalue">Return Value</h4>
b47dab17 9675<p class="description">1 on success, 0 on error</p>
798d6e29 9676<h4 class="discussion">Discussion</h4>
af268786
MS
9677<p class="discussion">Zero or more attributes are copied from the source IPP message &quot;src&quot; to the
9678destination IPP message &quot;dst&quot;. When &quot;quickcopy&quot; is non-zero, a &quot;shallow&quot;
9679reference copy of the attribute is created - this should only be done as long
9680as the original source IPP message will not be freed for the life of the
9681destination.<br>
798d6e29 9682<br>
af268786 9683The &quot;cb&quot; and &quot;context&quot; parameters provide a generic way to &quot;filter&quot; the
798d6e29
MS
9684attributes that are copied - the function must return 1 to copy the attribute or
96850 to skip it. The function may also choose to do a partial copy of the source attribute
9686itself.
9687
9688</p>
af268786
MS
9689<h3 class="function"><a id="ippCopyCredentialsString">ippCopyCredentialsString</a></h3>
9690<p class="description">Copy a credentials value from an IPP attribute.</p>
9691<p class="code">
0350eba5 9692<span class="reserved">char</span> *ippCopyCredentialsString(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
af268786
MS
9693<h4 class="parameters">Parameters</h4>
9694<table class="list"><tbody>
9695<tr><th>attr</th>
9696<td class="description">Attribute</td></tr>
9697</tbody></table>
9698<h4 class="returnvalue">Return Value</h4>
9699<p class="description">Combined string or <code>NULL</code> on error</p>
9700<h4 class="discussion">Discussion</h4>
9701<p class="discussion">This function concatenates the 1setOf text credential values of an attribute,
9702separated by newlines. The returned string must be freed using the <code>free</code>
9703function.</p>
b6008d6b 9704<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippCreateRequestedArray">ippCreateRequestedArray</a></h3>
b47dab17 9705<p class="description">Create a CUPS array of attribute names from the
af268786 9706 given requested-attributes attribute.</p>
798d6e29 9707<p class="code">
b47dab17 9708<a href="#cups_array_t">cups_array_t</a> *ippCreateRequestedArray(<a href="#ipp_t">ipp_t</a> *request);</p>
798d6e29 9709<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9710<table class="list"><tbody>
9711<tr><th>request</th>
b47dab17 9712<td class="description">IPP request</td></tr>
98d88c8d 9713</tbody></table>
798d6e29 9714<h4 class="returnvalue">Return Value</h4>
b47dab17 9715<p class="description">CUPS array or <code>NULL</code> if all</p>
798d6e29 9716<h4 class="discussion">Discussion</h4>
b47dab17 9717<p class="discussion">This function creates a (sorted) CUPS array of attribute names matching the
798d6e29
MS
9718list of &quot;requested-attribute&quot; values supplied in an IPP request. All IANA-
9719registered values are supported in addition to the CUPS IPP extension
9720attributes.<br>
9721<br>
9722The <code>request</code> parameter specifies the request message that was read from
9723the client.
9724
9725<code>NULL</code> is returned if all attributes should be returned. Otherwise, the
9726result is a sorted array of attribute names, where <code>cupsArrayFind(array,
9727"attribute-name")</code> will return a non-NULL pointer. The array must be freed
9728using the <code>cupsArrayDelete</code> function.
9729
9730</p>
9731<h3 class="function"><a id="ippDateToTime">ippDateToTime</a></h3>
b47dab17 9732<p class="description">Convert from RFC 2579 Date/Time format to time in
af268786 9733 seconds.</p>
798d6e29 9734<p class="code">
0350eba5 9735time_t ippDateToTime(<span class="reserved">const</span> <a href="#ipp_uchar_t">ipp_uchar_t</a> *date);</p>
798d6e29 9736<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9737<table class="list"><tbody>
9738<tr><th>date</th>
b47dab17 9739<td class="description">RFC 2579 date info</td></tr>
98d88c8d 9740</tbody></table>
798d6e29 9741<h4 class="returnvalue">Return Value</h4>
b47dab17 9742<p class="description">UNIX time value</p>
798d6e29 9743<h3 class="function"><a id="ippDelete">ippDelete</a></h3>
b47dab17 9744<p class="description">Delete an IPP message.</p>
798d6e29 9745<p class="code">
0350eba5 9746<span class="reserved">void</span> ippDelete(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 9747<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9748<table class="list"><tbody>
9749<tr><th>ipp</th>
b47dab17 9750<td class="description">IPP message</td></tr>
98d88c8d 9751</tbody></table>
b6008d6b 9752<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="ippDeleteAttribute">ippDeleteAttribute</a></h3>
b47dab17 9753<p class="description">Delete a single attribute in an IPP message.</p>
98d88c8d 9754<p class="code">
0350eba5 9755<span class="reserved">void</span> ippDeleteAttribute(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
98d88c8d
MS
9756<h4 class="parameters">Parameters</h4>
9757<table class="list"><tbody>
9758<tr><th>ipp</th>
b47dab17 9759<td class="description">IPP message</td></tr>
98d88c8d 9760<tr><th>attr</th>
b47dab17 9761<td class="description">Attribute to delete</td></tr>
98d88c8d 9762</tbody></table>
b6008d6b 9763<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippDeleteValues">ippDeleteValues</a></h3>
b47dab17 9764<p class="description">Delete values in an attribute.</p>
798d6e29 9765<p class="code">
0350eba5 9766<span class="reserved">int</span> ippDeleteValues(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">int</span> count);</p>
98d88c8d
MS
9767<h4 class="parameters">Parameters</h4>
9768<table class="list"><tbody>
9769<tr><th>ipp</th>
b47dab17 9770<td class="description">IPP message</td></tr>
98d88c8d 9771<tr><th>attr</th>
b47dab17 9772<td class="description">Attribute</td></tr>
98d88c8d 9773<tr><th>element</th>
b47dab17 9774<td class="description">Index of first value to delete (0-based)</td></tr>
98d88c8d 9775<tr><th>count</th>
b47dab17 9776<td class="description">Number of values to delete</td></tr>
98d88c8d 9777</tbody></table>
798d6e29 9778<h4 class="returnvalue">Return Value</h4>
b47dab17 9779<p class="description">1 on success, 0 on failure</p>
798d6e29 9780<h4 class="discussion">Discussion</h4>
af268786
MS
9781<p class="discussion">This function deletes one or more values in an attribute. The &quot;element&quot;
9782parameter specifies the first value to delete, starting at 0. It must be
9783less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br>
798d6e29 9784<br>
af268786
MS
9785The &quot;attr&quot; parameter may be modified as a result of setting the value,
9786which will set the variable to <code>NULL</code>.<br>
798d6e29
MS
9787<br>
9788Deleting all values in an attribute deletes the attribute.
9789
9790</p>
9791<h3 class="function"><a id="ippEnumString">ippEnumString</a></h3>
b47dab17 9792<p class="description">Return a string corresponding to the enum value.</p>
798d6e29 9793<p class="code">
0350eba5 9794<span class="reserved">const</span> <span class="reserved">char</span> *ippEnumString(<span class="reserved">const</span> <span class="reserved">char</span> *attrname, <span class="reserved">int</span> enumvalue);</p>
798d6e29 9795<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9796<table class="list"><tbody>
9797<tr><th>attrname</th>
b47dab17 9798<td class="description">Attribute name</td></tr>
98d88c8d 9799<tr><th>enumvalue</th>
b47dab17 9800<td class="description">Enum value</td></tr>
98d88c8d 9801</tbody></table>
798d6e29 9802<h4 class="returnvalue">Return Value</h4>
b47dab17 9803<p class="description">Enum string</p>
798d6e29 9804<h3 class="function"><a id="ippEnumValue">ippEnumValue</a></h3>
b47dab17 9805<p class="description">Return the value associated with a given enum string.</p>
798d6e29 9806<p class="code">
0350eba5 9807<span class="reserved">int</span> ippEnumValue(<span class="reserved">const</span> <span class="reserved">char</span> *attrname, <span class="reserved">const</span> <span class="reserved">char</span> *enumstring);</p>
798d6e29 9808<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9809<table class="list"><tbody>
9810<tr><th>attrname</th>
b47dab17 9811<td class="description">Attribute name</td></tr>
98d88c8d 9812<tr><th>enumstring</th>
b47dab17 9813<td class="description">Enum string</td></tr>
98d88c8d 9814</tbody></table>
798d6e29 9815<h4 class="returnvalue">Return Value</h4>
b47dab17 9816<p class="description">Enum value or -1 if unknown</p>
798d6e29 9817<h3 class="function"><a id="ippErrorString">ippErrorString</a></h3>
b47dab17 9818<p class="description">Return a name for the given status code.</p>
798d6e29 9819<p class="code">
0350eba5 9820<span class="reserved">const</span> <span class="reserved">char</span> *ippErrorString(ipp_status_t error);</p>
798d6e29 9821<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9822<table class="list"><tbody>
9823<tr><th>error</th>
b47dab17 9824<td class="description">Error status</td></tr>
98d88c8d 9825</tbody></table>
798d6e29 9826<h4 class="returnvalue">Return Value</h4>
b47dab17 9827<p class="description">Text string</p>
b6008d6b 9828<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippErrorValue">ippErrorValue</a></h3>
b47dab17 9829<p class="description">Return a status code for the given name.</p>
798d6e29 9830<p class="code">
0350eba5 9831ipp_status_t ippErrorValue(<span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
798d6e29 9832<h4 class="parameters">Parameters</h4>
98d88c8d
MS
9833<table class="list"><tbody>
9834<tr><th>name</th>
b47dab17 9835<td class="description">Name</td></tr>
98d88c8d 9836</tbody></table>
798d6e29 9837<h4 class="returnvalue">Return Value</h4>
b47dab17 9838<p class="description">IPP status code</p>
af268786
MS
9839<h3 class="function"><a id="ippFileClose">ippFileClose</a></h3>
9840<p class="description">Close an IPP data file.</p>
9841<p class="code">
0350eba5 9842<span class="reserved">bool</span> ippFileClose(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
9843<h4 class="parameters">Parameters</h4>
9844<table class="list"><tbody>
9845<tr><th>file</th>
9846<td class="description">IPP data file</td></tr>
9847</tbody></table>
9848<h4 class="returnvalue">Return Value</h4>
9849<p class="description"><code>true</code> on success, <code>false</code> on error</p>
9850<h4 class="discussion">Discussion</h4>
9851<p class="discussion">This function closes the current IPP data file. The <code>ipp_file_t</code> object can
9852be reused for another file as needed.</p>
9853<h3 class="function"><a id="ippFileDelete">ippFileDelete</a></h3>
9854<p class="description">Close an IPP data file and free all memory.</p>
9855<p class="code">
0350eba5 9856<span class="reserved">bool</span> ippFileDelete(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
9857<h4 class="parameters">Parameters</h4>
9858<table class="list"><tbody>
9859<tr><th>file</th>
9860<td class="description">IPP data file</td></tr>
9861</tbody></table>
9862<h4 class="returnvalue">Return Value</h4>
9863<p class="description"><code>true</code> on success, <code>false</code> on error</p>
9864<h4 class="discussion">Discussion</h4>
9865<p class="discussion">This function closes an IPP data file, if necessary, and frees all memory
9866associated with it.</p>
9867<h3 class="function"><a id="ippFileExpandVars">ippFileExpandVars</a></h3>
9868<p class="description">Expand IPP data file and environment variables in a string.</p>
9869<p class="code">
0350eba5 9870size_t ippFileExpandVars(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">char</span> *dst, <span class="reserved">const</span> <span class="reserved">char</span> *src, size_t dstsize);</p>
af268786
MS
9871<h4 class="parameters">Parameters</h4>
9872<table class="list"><tbody>
9873<tr><th>file</th>
9874<td class="description">IPP data file</td></tr>
9875<tr><th>dst</th>
9876<td class="description">Destination buffer</td></tr>
9877<tr><th>src</th>
9878<td class="description">Source string</td></tr>
9879<tr><th>dstsize</th>
9880<td class="description">Size of destination buffer</td></tr>
9881</tbody></table>
9882<h4 class="returnvalue">Return Value</h4>
9883<p class="description">Required size for expanded variables</p>
9884<h4 class="discussion">Discussion</h4>
9885<p class="discussion">This function expands IPP data file variables of the form &quot;$name&quot; and
9886environment variables of the form &quot;$ENV[name]&quot; in the source string to the
9887destination string. The</p>
9888<h3 class="function"><a id="ippFileGetAttribute">ippFileGetAttribute</a></h3>
9889<p class="description">Get a single named attribute from an IPP data file.</p>
9890<p class="code">
0350eba5 9891<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFileGetAttribute(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t value_tag);</p>
af268786
MS
9892<h4 class="parameters">Parameters</h4>
9893<table class="list"><tbody>
9894<tr><th>file</th>
9895<td class="description">IPP data file</td></tr>
9896<tr><th>name</th>
9897<td class="description">Attribute name</td></tr>
9898<tr><th>value_tag</th>
9899<td class="description">Value tag or <code>IPP_TAG_ZERO</code> for any</td></tr>
9900</tbody></table>
9901<h4 class="returnvalue">Return Value</h4>
9902<p class="description">Attribute or <code>NULL</code> if none</p>
9903<h4 class="discussion">Discussion</h4>
9904<p class="discussion">This function finds the first occurence of a named attribute in the current
9905IPP attributes in the specified data file. Unlike
9906<a href="#ippFileGetAttributes"><code>ippFileGetAttributes</code></a>, this function does not clear the attribute
9907state.</p>
9908<h3 class="function"><a id="ippFileGetAttributes">ippFileGetAttributes</a></h3>
9909<p class="description">Get the current set of attributes from an IPP data file.</p>
9910<p class="code">
9911<a href="#ipp_t">ipp_t</a> *ippFileGetAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
9912<h4 class="parameters">Parameters</h4>
9913<table class="list"><tbody>
9914<tr><th>file</th>
9915<td class="description">IPP data file</td></tr>
9916</tbody></table>
9917<h4 class="returnvalue">Return Value</h4>
9918<p class="description">IPP attributes</p>
9919<h4 class="discussion">Discussion</h4>
9920<p class="discussion">This function gets the current set of attributes from an IPP data file.</p>
9921<h3 class="function"><a id="ippFileGetFilename">ippFileGetFilename</a></h3>
9922<p class="description">Get the filename for an IPP data file.</p>
9923<p class="code">
0350eba5 9924<span class="reserved">const</span> <span class="reserved">char</span> *ippFileGetFilename(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
9925<h4 class="parameters">Parameters</h4>
9926<table class="list"><tbody>
9927<tr><th>file</th>
9928<td class="description">IPP data file</td></tr>
9929</tbody></table>
9930<h4 class="returnvalue">Return Value</h4>
9931<p class="description">Filename</p>
9932<h4 class="discussion">Discussion</h4>
9933<p class="discussion">This function returns the filename associated with an IPP data file.</p>
9934<h3 class="function"><a id="ippFileGetLineNumber">ippFileGetLineNumber</a></h3>
9935<p class="description">Get the current line number in an IPP data file.</p>
9936<p class="code">
0350eba5 9937<span class="reserved">int</span> ippFileGetLineNumber(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
9938<h4 class="parameters">Parameters</h4>
9939<table class="list"><tbody>
9940<tr><th>file</th>
9941<td class="description">IPP data file</td></tr>
9942</tbody></table>
9943<h4 class="returnvalue">Return Value</h4>
9944<p class="description">Line number</p>
9945<h4 class="discussion">Discussion</h4>
9946<p class="discussion">This function returns the current line number in an IPP data file.</p>
9947<h3 class="function"><a id="ippFileGetVar">ippFileGetVar</a></h3>
9948<p class="description">Get the value of an IPP data file variable.</p>
9949<p class="code">
0350eba5 9950<span class="reserved">const</span> <span class="reserved">char</span> *ippFileGetVar(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
af268786
MS
9951<h4 class="parameters">Parameters</h4>
9952<table class="list"><tbody>
9953<tr><th>file</th>
9954<td class="description">IPP data file</td></tr>
9955<tr><th>name</th>
9956<td class="description">Variable name</td></tr>
9957</tbody></table>
9958<h4 class="returnvalue">Return Value</h4>
9959<p class="description">Variable value or <code>NULL</code> if none.</p>
9960<h4 class="discussion">Discussion</h4>
9961<p class="discussion">This function returns the value of an IPP data file variable. <code>NULL</code> is
9962returned if the variable is not set.</p>
9963<h3 class="function"><a id="ippFileNew">ippFileNew</a></h3>
9964<p class="description">Create a new IPP data file object for reading or writing.</p>
9965<p class="code">
0350eba5 9966<a href="#ipp_file_t">ipp_file_t</a> *ippFileNew(<a href="#ipp_file_t">ipp_file_t</a> *parent, <a href="#ipp_fattr_cb_t">ipp_fattr_cb_t</a> attr_cb, <a href="#ipp_ferror_cb_t">ipp_ferror_cb_t</a> error_cb, <span class="reserved">void</span> *cb_data);</p>
af268786
MS
9967<h4 class="parameters">Parameters</h4>
9968<table class="list"><tbody>
9969<tr><th>parent</th>
9970<td class="description">Parent data file or <code>NULL</code> for none</td></tr>
9971<tr><th>attr_cb</th>
9972<td class="description">Attribute filtering callback, if any</td></tr>
9973<tr><th>error_cb</th>
9974<td class="description">Error reporting callback, if any</td></tr>
9975<tr><th>cb_data</th>
9976<td class="description">Callback data, if any</td></tr>
9977</tbody></table>
9978<h4 class="returnvalue">Return Value</h4>
9979<p class="description">IPP data file</p>
9980<h4 class="discussion">Discussion</h4>
9981<p class="discussion">This function opens an IPP data file for reading (mode=&quot;r&quot;) or writing
9982(mode=&quot;w&quot;). If the &quot;parent&quot; argument is not <code>NULL</code>, all variables from the
9983parent data file are copied to the new file.</p>
9984<h3 class="function"><a id="ippFileOpen">ippFileOpen</a></h3>
9985<p class="description">Open an IPP data file for reading or writing.</p>
9986<p class="code">
0350eba5 9987<span class="reserved">bool</span> ippFileOpen(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *filename, <span class="reserved">const</span> <span class="reserved">char</span> *mode);</p>
af268786
MS
9988<h4 class="parameters">Parameters</h4>
9989<table class="list"><tbody>
9990<tr><th>file</th>
9991<td class="description">IPP data file</td></tr>
9992<tr><th>filename</th>
9993<td class="description">Filename to open</td></tr>
9994<tr><th>mode</th>
9995<td class="description">Open mode - &quot;r&quot; to read and &quot;w&quot; to write</td></tr>
9996</tbody></table>
9997<h4 class="returnvalue">Return Value</h4>
9998<p class="description"><code>true</code> on success, <code>false</code> on error</p>
9999<h4 class="discussion">Discussion</h4>
10000<p class="discussion">This function opens an IPP data file for reading (mode=&quot;r&quot;) or writing
10001(mode=&quot;w&quot;). If the &quot;parent&quot; argument is not <code>NULL</code>, all variables from the
10002parent data file are copied to the new file.</p>
10003<h3 class="function"><a id="ippFileRead">ippFileRead</a></h3>
10004<p class="description">Read an IPP data file.</p>
10005<p class="code">
0350eba5 10006<span class="reserved">bool</span> ippFileRead(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_ftoken_cb_t">ipp_ftoken_cb_t</a> token_cb, <span class="reserved">bool</span> with_groups);</p>
af268786
MS
10007<h4 class="parameters">Parameters</h4>
10008<table class="list"><tbody>
10009<tr><th>file</th>
10010<td class="description">IPP data file</td></tr>
10011<tr><th>token_cb</th>
10012<td class="description">Token callback</td></tr>
10013<tr><th>with_groups</th>
10014<td class="description">Read attributes with GROUP directives</td></tr>
10015</tbody></table>
10016<h4 class="returnvalue">Return Value</h4>
10017<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10018<h3 class="function"><a id="ippFileReadCollection">ippFileReadCollection</a></h3>
10019<p class="description">Read a collection from an IPP data file.</p>
10020<p class="code">
10021<a href="#ipp_t">ipp_t</a> *ippFileReadCollection(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
10022<h4 class="parameters">Parameters</h4>
10023<table class="list"><tbody>
10024<tr><th>file</th>
10025<td class="description">IPP data file</td></tr>
10026</tbody></table>
10027<h4 class="returnvalue">Return Value</h4>
10028<p class="description">Collection value</p>
10029<h4 class="discussion">Discussion</h4>
10030<p class="discussion">This function reads a collection value from an IPP data file. Collection
10031values are surrounded by curly braces (&quot;{&quot; and &quot;}&quot;) and have &quot;MEMBER&quot;
10032directives to define member attributes in the collection.</p>
10033<h3 class="function"><a id="ippFileReadToken">ippFileReadToken</a></h3>
10034<p class="description">Read a token from an IPP data file.</p>
10035<p class="code">
0350eba5 10036<span class="reserved">bool</span> ippFileReadToken(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">char</span> *token, size_t tokensize);</p>
af268786
MS
10037<h4 class="parameters">Parameters</h4>
10038<table class="list"><tbody>
10039<tr><th>file</th>
10040<td class="description">IPP data file</td></tr>
10041<tr><th>token</th>
10042<td class="description">Token buffer</td></tr>
10043<tr><th>tokensize</th>
10044<td class="description">Size of token buffer</td></tr>
10045</tbody></table>
10046<h4 class="returnvalue">Return Value</h4>
10047<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10048<h4 class="discussion">Discussion</h4>
10049<p class="discussion">This function reads a single token or value from an IPP data file, skipping
10050comments and whitespace as needed.</p>
10051<h3 class="function"><a id="ippFileRestorePosition">ippFileRestorePosition</a></h3>
10052<p class="description">Restore the previous position in an IPP data file.</p>
10053<p class="code">
0350eba5 10054<span class="reserved">bool</span> ippFileRestorePosition(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
10055<h4 class="parameters">Parameters</h4>
10056<table class="list"><tbody>
10057<tr><th>file</th>
10058<td class="description">IPP data file</td></tr>
10059</tbody></table>
10060<h4 class="returnvalue">Return Value</h4>
10061<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
10062<h4 class="discussion">Discussion</h4>
10063<p class="discussion">This function restores the previous position in an IPP data file that is open
10064for reading.</p>
10065<h3 class="function"><a id="ippFileSavePosition">ippFileSavePosition</a></h3>
10066<p class="description">Save the current position in an IPP data file.</p>
10067<p class="code">
0350eba5 10068<span class="reserved">bool</span> ippFileSavePosition(<a href="#ipp_file_t">ipp_file_t</a> *file);</p>
af268786
MS
10069<h4 class="parameters">Parameters</h4>
10070<table class="list"><tbody>
10071<tr><th>file</th>
10072<td class="description">IPP data file</td></tr>
10073</tbody></table>
10074<h4 class="returnvalue">Return Value</h4>
10075<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
10076<h4 class="discussion">Discussion</h4>
10077<p class="discussion">This function saves the current position in an IPP data file that is open
10078for reading.</p>
10079<h3 class="function"><a id="ippFileSetAttributes">ippFileSetAttributes</a></h3>
10080<p class="description">Set the attributes for an IPP data file.</p>
10081<p class="code">
0350eba5 10082<span class="reserved">bool</span> ippFileSetAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_t">ipp_t</a> *attrs);</p>
af268786
MS
10083<h4 class="parameters">Parameters</h4>
10084<table class="list"><tbody>
10085<tr><th>file</th>
10086<td class="description">IPP data file</td></tr>
10087<tr><th>attrs</th>
10088<td class="description">IPP attributes</td></tr>
10089</tbody></table>
10090<h4 class="returnvalue">Return Value</h4>
10091<p class="description"><code>true</code> on success, <code>false</code> otherwise</p>
10092<h4 class="discussion">Discussion</h4>
10093<p class="discussion">This function sets the current set of attributes for an IPP data file,
10094typically an empty collection created with <a href="#ippNew"><code>ippNew</code></a>.</p>
10095<h3 class="function"><a id="ippFileSetGroupTag">ippFileSetGroupTag</a></h3>
10096<p class="description">Set the group tag for an IPP data file.</p>
10097<p class="code">
0350eba5 10098<span class="reserved">bool</span> ippFileSetGroupTag(<a href="#ipp_file_t">ipp_file_t</a> *file, ipp_tag_t group_tag);</p>
af268786
MS
10099<h4 class="parameters">Parameters</h4>
10100<table class="list"><tbody>
10101<tr><th>file</th>
10102<td class="description">IPP data file</td></tr>
10103<tr><th>group_tag</th>
10104<td class="description">Group tag</td></tr>
10105</tbody></table>
10106<h4 class="returnvalue">Return Value</h4>
10107<p class="description"><code>true</code> on success, <code>false</code> otherwise</p>
10108<h4 class="discussion">Discussion</h4>
10109<p class="discussion">This function sets the group tag associated with attributes that are read
10110from an IPP data file.</p>
10111<h3 class="function"><a id="ippFileSetVar">ippFileSetVar</a></h3>
10112<p class="description">Set an IPP data file variable to a constant value.</p>
10113<p class="code">
0350eba5 10114<span class="reserved">bool</span> ippFileSetVar(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
af268786
MS
10115<h4 class="parameters">Parameters</h4>
10116<table class="list"><tbody>
10117<tr><th>file</th>
10118<td class="description">IPP data file</td></tr>
10119<tr><th>name</th>
10120<td class="description">Variable name</td></tr>
10121<tr><th>value</th>
10122<td class="description">Value</td></tr>
10123</tbody></table>
10124<h4 class="returnvalue">Return Value</h4>
10125<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
10126<h4 class="discussion">Discussion</h4>
10127<p class="discussion">This function sets an IPP data file variable to a constant value. Setting
10128the &quot;uri&quot; variable also initializes the &quot;scheme&quot;, &quot;uriuser&quot;, &quot;hostname&quot;,
10129&quot;port&quot;, and &quot;resource&quot; variables.</p>
10130<h3 class="function"><a id="ippFileSetVarf">ippFileSetVarf</a></h3>
10131<p class="description">Set an IPP data file variable to a formatted value.</p>
10132<p class="code">
0350eba5 10133<span class="reserved">bool</span> ippFileSetVarf(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">const</span> <span class="reserved">char</span> *value, ...);</p>
af268786
MS
10134<h4 class="parameters">Parameters</h4>
10135<table class="list"><tbody>
10136<tr><th>file</th>
10137<td class="description">IPP data file</td></tr>
10138<tr><th>name</th>
10139<td class="description">Variable name</td></tr>
10140<tr><th>value</th>
10141<td class="description">Printf-style value</td></tr>
10142<tr><th>...</th>
10143<td class="description">Additional arguments as needed</td></tr>
10144</tbody></table>
10145<h4 class="returnvalue">Return Value</h4>
10146<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10147<h4 class="discussion">Discussion</h4>
10148<p class="discussion">This function sets an IPP data file variable to a formatted value. Setting
10149the &quot;uri&quot; variable also initializes the &quot;scheme&quot;, &quot;uriuser&quot;, &quot;hostname&quot;,
10150&quot;port&quot;, and &quot;resource&quot; variables.</p>
10151<h3 class="function"><a id="ippFileWriteAttributes">ippFileWriteAttributes</a></h3>
10152<p class="description">Write an IPP message to an IPP data file.</p>
10153<p class="code">
0350eba5 10154<span class="reserved">bool</span> ippFileWriteAttributes(<a href="#ipp_file_t">ipp_file_t</a> *file, <a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">bool</span> with_groups);</p>
af268786
MS
10155<h4 class="parameters">Parameters</h4>
10156<table class="list"><tbody>
10157<tr><th>file</th>
10158<td class="description">IPP data file</td></tr>
10159<tr><th>ipp</th>
10160<td class="description">IPP attributes to write</td></tr>
10161<tr><th>with_groups</th>
10162<td class="description"><code>true</code> to include GROUPs, <code>false</code> otherwise</td></tr>
10163</tbody></table>
10164<h4 class="returnvalue">Return Value</h4>
10165<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10166<h4 class="discussion">Discussion</h4>
10167<p class="discussion">This function writes an IPP message to an IPP data file using the attribute
10168filter specified in the call to <a href="#ippFileOpen"><code>ippFileOpen</code></a>. If &quot;with_group&quot; is
10169<code>true</code>, &quot;GROUP&quot; directives are written as necessary to place the attributes
10170in the correct groups.</p>
10171<h3 class="function"><a id="ippFileWriteComment">ippFileWriteComment</a></h3>
10172<p class="description">Write a comment to an IPP data file.</p>
10173<p class="code">
0350eba5 10174<span class="reserved">bool</span> ippFileWriteComment(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *comment, ...);</p>
af268786
MS
10175<h4 class="parameters">Parameters</h4>
10176<table class="list"><tbody>
10177<tr><th>file</th>
10178<td class="description">IPP data file</td></tr>
10179<tr><th>comment</th>
10180<td class="description">Printf-style comment string</td></tr>
10181<tr><th>...</th>
10182<td class="description">Additional arguments as needed</td></tr>
10183</tbody></table>
10184<h4 class="returnvalue">Return Value</h4>
10185<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10186<h4 class="discussion">Discussion</h4>
10187<p class="discussion">This function writes a comment to an IPP data file. Every line in the string
10188is prefixed with the &quot;#&quot; character and indented as needed.</p>
10189<h3 class="function"><a id="ippFileWriteToken">ippFileWriteToken</a></h3>
10190<p class="description">Write a token or value string to an IPP data file.</p>
10191<p class="code">
0350eba5 10192<span class="reserved">bool</span> ippFileWriteToken(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *token);</p>
af268786
MS
10193<h4 class="parameters">Parameters</h4>
10194<table class="list"><tbody>
10195<tr><th>file</th>
10196<td class="description">IPP data file</td></tr>
10197<tr><th>token</th>
10198<td class="description">Token/value string</td></tr>
10199</tbody></table>
10200<h4 class="returnvalue">Return Value</h4>
10201<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10202<h4 class="discussion">Discussion</h4>
10203<p class="discussion">This function writes a token or value string to an IPP data file, quoting
10204and indenting the string as needed.</p>
10205<h3 class="function"><a id="ippFileWriteTokenf">ippFileWriteTokenf</a></h3>
10206<p class="description">Write a formatted token or value string to an IPP data file.</p>
10207<p class="code">
0350eba5 10208<span class="reserved">bool</span> ippFileWriteTokenf(<a href="#ipp_file_t">ipp_file_t</a> *file, <span class="reserved">const</span> <span class="reserved">char</span> *token, ...);</p>
af268786
MS
10209<h4 class="parameters">Parameters</h4>
10210<table class="list"><tbody>
10211<tr><th>file</th>
10212<td class="description">IPP data file</td></tr>
10213<tr><th>token</th>
10214<td class="description">Printf-style token/value string</td></tr>
10215<tr><th>...</th>
10216<td class="description">Additional arguments as needed</td></tr>
10217</tbody></table>
10218<h4 class="returnvalue">Return Value</h4>
10219<p class="description"><code>true</code> on success, <code>false</code> on error</p>
10220<h4 class="discussion">Discussion</h4>
10221<p class="discussion">This function writes a formatted token or value string to an IPP data file,
10222quoting and indenting the string as needed.</p>
798d6e29 10223<h3 class="function"><a id="ippFindAttribute">ippFindAttribute</a></h3>
b47dab17 10224<p class="description">Find a named attribute in a request.</p>
798d6e29 10225<p class="code">
0350eba5 10226<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t type);</p>
98d88c8d
MS
10227<h4 class="parameters">Parameters</h4>
10228<table class="list"><tbody>
10229<tr><th>ipp</th>
b47dab17 10230<td class="description">IPP message</td></tr>
98d88c8d 10231<tr><th>name</th>
b47dab17 10232<td class="description">Name of attribute</td></tr>
98d88c8d 10233<tr><th>type</th>
b47dab17 10234<td class="description">Type of attribute</td></tr>
98d88c8d 10235</tbody></table>
798d6e29 10236<h4 class="returnvalue">Return Value</h4>
b47dab17 10237<p class="description">Matching attribute</p>
798d6e29 10238<h4 class="discussion">Discussion</h4>
af268786
MS
10239<p class="discussion">This function finds the first occurrence of a named attribute in an IPP
10240message. The attribute name can contain a hierarchical list of attribute and
10241member names separated by slashes, for example &quot;media-col/media-size&quot;.</p>
798d6e29 10242<h3 class="function"><a id="ippFindNextAttribute">ippFindNextAttribute</a></h3>
b47dab17 10243<p class="description">Find the next named attribute in a request.</p>
798d6e29 10244<p class="code">
0350eba5 10245<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">const</span> <span class="reserved">char</span> *name, ipp_tag_t type);</p>
98d88c8d
MS
10246<h4 class="parameters">Parameters</h4>
10247<table class="list"><tbody>
10248<tr><th>ipp</th>
b47dab17 10249<td class="description">IPP message</td></tr>
98d88c8d 10250<tr><th>name</th>
b47dab17 10251<td class="description">Name of attribute</td></tr>
98d88c8d 10252<tr><th>type</th>
b47dab17 10253<td class="description">Type of attribute</td></tr>
98d88c8d 10254</tbody></table>
798d6e29 10255<h4 class="returnvalue">Return Value</h4>
b47dab17 10256<p class="description">Matching attribute</p>
798d6e29 10257<h4 class="discussion">Discussion</h4>
af268786
MS
10258<p class="discussion">This function finds the next named attribute in an IPP message. The
10259attribute name can contain a hierarchical list of attribute and member names
10260separated by slashes, for example &quot;media-col/media-size&quot;.</p>
b6008d6b 10261<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetBoolean">ippGetBoolean</a></h3>
b47dab17 10262<p class="description">Get a boolean value for an attribute.</p>
798d6e29 10263<p class="code">
0350eba5 10264<span class="reserved">int</span> ippGetBoolean(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element);</p>
798d6e29 10265<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10266<table class="list"><tbody>
10267<tr><th>attr</th>
b47dab17 10268<td class="description">IPP attribute</td></tr>
98d88c8d 10269<tr><th>element</th>
b47dab17 10270<td class="description">Value number (0-based)</td></tr>
98d88c8d 10271</tbody></table>
798d6e29 10272<h4 class="returnvalue">Return Value</h4>
b47dab17 10273<p class="description">Boolean value or 0 on error</p>
798d6e29 10274<h4 class="discussion">Discussion</h4>
af268786 10275<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10276<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10277
10278</p>
b6008d6b 10279<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetCollection">ippGetCollection</a></h3>
b47dab17 10280<p class="description">Get a collection value for an attribute.</p>
798d6e29 10281<p class="code">
0350eba5 10282<a href="#ipp_t">ipp_t</a> *ippGetCollection(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element);</p>
798d6e29 10283<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10284<table class="list"><tbody>
10285<tr><th>attr</th>
b47dab17 10286<td class="description">IPP attribute</td></tr>
98d88c8d 10287<tr><th>element</th>
b47dab17 10288<td class="description">Value number (0-based)</td></tr>
98d88c8d 10289</tbody></table>
798d6e29 10290<h4 class="returnvalue">Return Value</h4>
b47dab17 10291<p class="description">Collection value or <code>NULL</code> on error</p>
798d6e29 10292<h4 class="discussion">Discussion</h4>
af268786 10293<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10294<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10295
10296</p>
b6008d6b 10297<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetCount">ippGetCount</a></h3>
b47dab17 10298<p class="description">Get the number of values in an attribute.</p>
798d6e29 10299<p class="code">
0350eba5 10300<span class="reserved">int</span> ippGetCount(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
798d6e29 10301<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10302<table class="list"><tbody>
10303<tr><th>attr</th>
b47dab17 10304<td class="description">IPP attribute</td></tr>
98d88c8d 10305</tbody></table>
798d6e29 10306<h4 class="returnvalue">Return Value</h4>
b47dab17 10307<p class="description">Number of values or 0 on error</p>
b6008d6b 10308<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetDate">ippGetDate</a></h3>
b47dab17 10309<p class="description">Get a dateTime value for an attribute.</p>
798d6e29 10310<p class="code">
0350eba5 10311<span class="reserved">const</span> <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippGetDate(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element);</p>
798d6e29 10312<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10313<table class="list"><tbody>
10314<tr><th>attr</th>
b47dab17 10315<td class="description">IPP attribute</td></tr>
98d88c8d 10316<tr><th>element</th>
b47dab17 10317<td class="description">Value number (0-based)</td></tr>
98d88c8d 10318</tbody></table>
798d6e29 10319<h4 class="returnvalue">Return Value</h4>
b47dab17 10320<p class="description">dateTime value or <code>NULL</code></p>
798d6e29 10321<h4 class="discussion">Discussion</h4>
af268786 10322<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10323<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10324
10325</p>
af268786
MS
10326<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippGetFirstAttribute">ippGetFirstAttribute</a></h3>
10327<p class="description">Return the first attribute in the message.</p>
10328<p class="code">
10329<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippGetFirstAttribute(<a href="#ipp_t">ipp_t</a> *ipp);</p>
10330<h4 class="parameters">Parameters</h4>
10331<table class="list"><tbody>
10332<tr><th>ipp</th>
10333<td class="description">IPP message</td></tr>
10334</tbody></table>
10335<h4 class="returnvalue">Return Value</h4>
10336<p class="description">First attribute or <code>NULL</code> if none</p>
b6008d6b 10337<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetGroupTag">ippGetGroupTag</a></h3>
b47dab17 10338<p class="description">Get the group associated with an attribute.</p>
798d6e29 10339<p class="code">
98d88c8d 10340ipp_tag_t ippGetGroupTag(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
798d6e29 10341<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10342<table class="list"><tbody>
10343<tr><th>attr</th>
b47dab17 10344<td class="description">IPP attribute</td></tr>
98d88c8d 10345</tbody></table>
798d6e29 10346<h4 class="returnvalue">Return Value</h4>
b47dab17 10347<p class="description">Group tag or <code>IPP_TAG_ZERO</code> on error</p>
b6008d6b 10348<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetInteger">ippGetInteger</a></h3>
b47dab17 10349<p class="description">Get the integer/enum value for an attribute.</p>
798d6e29 10350<p class="code">
0350eba5 10351<span class="reserved">int</span> ippGetInteger(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element);</p>
798d6e29 10352<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10353<table class="list"><tbody>
10354<tr><th>attr</th>
b47dab17 10355<td class="description">IPP attribute</td></tr>
98d88c8d 10356<tr><th>element</th>
b47dab17 10357<td class="description">Value number (0-based)</td></tr>
98d88c8d 10358</tbody></table>
798d6e29 10359<h4 class="returnvalue">Return Value</h4>
b47dab17 10360<p class="description">Value or 0 on error</p>
798d6e29 10361<h4 class="discussion">Discussion</h4>
af268786 10362<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10363<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10364
10365</p>
af268786
MS
10366<h3 class="function"><a id="ippGetLength">ippGetLength</a></h3>
10367<p class="description">Compute the length of an IPP message.</p>
10368<p class="code">
10369size_t ippGetLength(<a href="#ipp_t">ipp_t</a> *ipp);</p>
10370<h4 class="parameters">Parameters</h4>
10371<table class="list"><tbody>
10372<tr><th>ipp</th>
10373<td class="description">IPP message</td></tr>
10374</tbody></table>
10375<h4 class="returnvalue">Return Value</h4>
10376<p class="description">Size of IPP message</p>
b6008d6b 10377<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetName">ippGetName</a></h3>
b47dab17 10378<p class="description">Get the attribute name.</p>
798d6e29 10379<p class="code">
0350eba5 10380<span class="reserved">const</span> <span class="reserved">char</span> *ippGetName(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
798d6e29 10381<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10382<table class="list"><tbody>
10383<tr><th>attr</th>
b47dab17 10384<td class="description">IPP attribute</td></tr>
98d88c8d 10385</tbody></table>
798d6e29 10386<h4 class="returnvalue">Return Value</h4>
b47dab17 10387<p class="description">Attribute name or <code>NULL</code> for separators</p>
af268786
MS
10388<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippGetNextAttribute">ippGetNextAttribute</a></h3>
10389<p class="description">Return the next attribute in the message.</p>
10390<p class="code">
10391<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippGetNextAttribute(<a href="#ipp_t">ipp_t</a> *ipp);</p>
10392<h4 class="parameters">Parameters</h4>
10393<table class="list"><tbody>
10394<tr><th>ipp</th>
10395<td class="description">IPP message</td></tr>
10396</tbody></table>
10397<h4 class="returnvalue">Return Value</h4>
10398<p class="description">Next attribute or <code>NULL</code> if none</p>
b6008d6b 10399<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippGetOctetString">ippGetOctetString</a></h3>
b47dab17 10400<p class="description">Get an octetString value from an IPP attribute.</p>
798d6e29 10401<p class="code">
0350eba5 10402<span class="reserved">void</span> *ippGetOctetString(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element, <span class="reserved">int</span> *datalen);</p>
98d88c8d
MS
10403<h4 class="parameters">Parameters</h4>
10404<table class="list"><tbody>
10405<tr><th>attr</th>
b47dab17 10406<td class="description">IPP attribute</td></tr>
98d88c8d 10407<tr><th>element</th>
b47dab17 10408<td class="description">Value number (0-based)</td></tr>
98d88c8d 10409<tr><th>datalen</th>
b47dab17 10410<td class="description">Length of octetString data</td></tr>
98d88c8d 10411</tbody></table>
798d6e29 10412<h4 class="returnvalue">Return Value</h4>
b47dab17 10413<p class="description">Pointer to octetString data</p>
798d6e29 10414<h4 class="discussion">Discussion</h4>
af268786 10415<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10416<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10417
10418</p>
b6008d6b 10419<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetOperation">ippGetOperation</a></h3>
b47dab17 10420<p class="description">Get the operation ID in an IPP message.</p>
798d6e29 10421<p class="code">
af268786 10422<a href="#ipp_op_t">ipp_op_t</a> ippGetOperation(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10423<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10424<table class="list"><tbody>
10425<tr><th>ipp</th>
b47dab17 10426<td class="description">IPP request message</td></tr>
98d88c8d 10427</tbody></table>
798d6e29 10428<h4 class="returnvalue">Return Value</h4>
b47dab17 10429<p class="description">Operation ID or 0 on error</p>
af268786
MS
10430<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippGetPort">ippGetPort</a></h3>
10431<p class="description">Return the default IPP port number.</p>
10432<p class="code">
0350eba5 10433<span class="reserved">int</span> ippGetPort(<span class="reserved">void</span>);</p>
af268786
MS
10434<h4 class="returnvalue">Return Value</h4>
10435<p class="description">Port number</p>
b6008d6b 10436<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetRange">ippGetRange</a></h3>
b47dab17 10437<p class="description">Get a rangeOfInteger value from an attribute.</p>
798d6e29 10438<p class="code">
0350eba5 10439<span class="reserved">int</span> ippGetRange(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element, <span class="reserved">int</span> *uppervalue);</p>
98d88c8d
MS
10440<h4 class="parameters">Parameters</h4>
10441<table class="list"><tbody>
10442<tr><th>attr</th>
b47dab17 10443<td class="description">IPP attribute</td></tr>
98d88c8d 10444<tr><th>element</th>
b47dab17 10445<td class="description">Value number (0-based)</td></tr>
98d88c8d 10446<tr><th>uppervalue</th>
b47dab17 10447<td class="description">Upper value of range</td></tr>
98d88c8d 10448</tbody></table>
798d6e29 10449<h4 class="returnvalue">Return Value</h4>
b47dab17 10450<p class="description">Lower value of range or 0</p>
798d6e29 10451<h4 class="discussion">Discussion</h4>
af268786 10452<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10453<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10454
10455</p>
b6008d6b 10456<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetRequestId">ippGetRequestId</a></h3>
b47dab17 10457<p class="description">Get the request ID from an IPP message.</p>
798d6e29 10458<p class="code">
0350eba5 10459<span class="reserved">int</span> ippGetRequestId(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10460<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10461<table class="list"><tbody>
10462<tr><th>ipp</th>
b47dab17 10463<td class="description">IPP message</td></tr>
98d88c8d 10464</tbody></table>
798d6e29 10465<h4 class="returnvalue">Return Value</h4>
b47dab17 10466<p class="description">Request ID or 0 on error</p>
b6008d6b 10467<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetResolution">ippGetResolution</a></h3>
b47dab17 10468<p class="description">Get a resolution value for an attribute.</p>
798d6e29 10469<p class="code">
0350eba5 10470<span class="reserved">int</span> ippGetResolution(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element, <span class="reserved">int</span> *yres, <a href="#ipp_res_t">ipp_res_t</a> *units);</p>
98d88c8d
MS
10471<h4 class="parameters">Parameters</h4>
10472<table class="list"><tbody>
10473<tr><th>attr</th>
b47dab17 10474<td class="description">IPP attribute</td></tr>
98d88c8d 10475<tr><th>element</th>
b47dab17 10476<td class="description">Value number (0-based)</td></tr>
98d88c8d 10477<tr><th>yres</th>
b47dab17 10478<td class="description">Vertical/feed resolution</td></tr>
98d88c8d 10479<tr><th>units</th>
b47dab17 10480<td class="description">Units for resolution</td></tr>
98d88c8d 10481</tbody></table>
798d6e29 10482<h4 class="returnvalue">Return Value</h4>
b47dab17 10483<p class="description">Horizontal/cross feed resolution or 0</p>
798d6e29 10484<h4 class="discussion">Discussion</h4>
af268786 10485<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10486<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10487
10488</p>
b6008d6b 10489<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetState">ippGetState</a></h3>
b47dab17 10490<p class="description">Get the IPP message state.</p>
798d6e29 10491<p class="code">
98d88c8d 10492<a href="#ipp_state_t">ipp_state_t</a> ippGetState(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10493<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10494<table class="list"><tbody>
10495<tr><th>ipp</th>
b47dab17 10496<td class="description">IPP message</td></tr>
98d88c8d 10497</tbody></table>
798d6e29 10498<h4 class="returnvalue">Return Value</h4>
b47dab17 10499<p class="description">IPP message state value</p>
b6008d6b 10500<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetStatusCode">ippGetStatusCode</a></h3>
b47dab17 10501<p class="description">Get the status code from an IPP response or event message.</p>
798d6e29 10502<p class="code">
98d88c8d 10503ipp_status_t ippGetStatusCode(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10504<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10505<table class="list"><tbody>
10506<tr><th>ipp</th>
b47dab17 10507<td class="description">IPP response or event message</td></tr>
98d88c8d 10508</tbody></table>
798d6e29 10509<h4 class="returnvalue">Return Value</h4>
b47dab17 10510<p class="description">Status code in IPP message</p>
798d6e29 10511<h3 class="function"><a id="ippGetString">ippGetString</a></h3>
b47dab17 10512<p class="description"></p>
98d88c8d 10513<p class="code">
0350eba5 10514<span class="reserved">const</span> <span class="reserved">char</span> *ippGetString(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <span class="reserved">char</span> **language);</p>
98d88c8d
MS
10515<h4 class="parameters">Parameters</h4>
10516<table class="list"><tbody>
10517<tr><th>attr</th>
b47dab17 10518<td class="description">IPP attribute</td></tr>
98d88c8d 10519<tr><th>element</th>
b47dab17 10520<td class="description">Value number (0-based)</td></tr>
98d88c8d 10521<tr><th>language</th>
b47dab17 10522<td class="description">Language code (<code>NULL</code> for don't care)</td></tr>
98d88c8d 10523</tbody></table>
798d6e29 10524<h4 class="returnvalue">Return Value</h4>
b47dab17 10525<p class="description">Get the string and optionally the language code for an attribute.</p>
af268786 10526<p class="discussion">The &quot;element&quot; parameter specifies which value to get from 0 to
65bebeac 10527<code>ippGetCount(attr)</code> - 1.
798d6e29
MS
10528
10529</p>
b6008d6b 10530<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetValueTag">ippGetValueTag</a></h3>
b47dab17 10531<p class="description">Get the value tag for an attribute.</p>
798d6e29 10532<p class="code">
98d88c8d 10533ipp_tag_t ippGetValueTag(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
798d6e29 10534<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10535<table class="list"><tbody>
10536<tr><th>attr</th>
b47dab17 10537<td class="description">IPP attribute</td></tr>
98d88c8d 10538</tbody></table>
798d6e29 10539<h4 class="returnvalue">Return Value</h4>
b47dab17 10540<p class="description">Value tag or <code>IPP_TAG_ZERO</code> on error</p>
b6008d6b 10541<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippGetVersion">ippGetVersion</a></h3>
b47dab17 10542<p class="description">Get the major and minor version number from an IPP message.</p>
798d6e29 10543<p class="code">
0350eba5 10544<span class="reserved">int</span> ippGetVersion(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">int</span> *minor);</p>
798d6e29 10545<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10546<table class="list"><tbody>
10547<tr><th>ipp</th>
b47dab17 10548<td class="description">IPP message</td></tr>
98d88c8d 10549<tr><th>minor</th>
b47dab17 10550<td class="description">Minor version number or <code>NULL</code> for don't care</td></tr>
98d88c8d 10551</tbody></table>
798d6e29 10552<h4 class="returnvalue">Return Value</h4>
b47dab17 10553<p class="description">Major version number or 0 on error</p>
798d6e29 10554<h3 class="function"><a id="ippNew">ippNew</a></h3>
b47dab17 10555<p class="description">Allocate a new IPP message.</p>
798d6e29 10556<p class="code">
0350eba5 10557<a href="#ipp_t">ipp_t</a> *ippNew(<span class="reserved">void</span>);</p>
798d6e29 10558<h4 class="returnvalue">Return Value</h4>
b47dab17 10559<p class="description">New IPP message</p>
b6008d6b 10560<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippNewRequest">ippNewRequest</a></h3>
b47dab17 10561<p class="description">Allocate a new IPP request message.</p>
798d6e29 10562<p class="code">
af268786 10563<a href="#ipp_t">ipp_t</a> *ippNewRequest(<a href="#ipp_op_t">ipp_op_t</a> op);</p>
798d6e29 10564<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10565<table class="list"><tbody>
10566<tr><th>op</th>
b47dab17 10567<td class="description">Operation code</td></tr>
98d88c8d 10568</tbody></table>
798d6e29 10569<h4 class="returnvalue">Return Value</h4>
b47dab17 10570<p class="description">IPP request message</p>
798d6e29 10571<h4 class="discussion">Discussion</h4>
b47dab17 10572<p class="discussion">The new request message is initialized with the &quot;attributes-charset&quot; and
65bebeac
MS
10573&quot;attributes-natural-language&quot; attributes added. The
10574&quot;attributes-natural-language&quot; value is derived from the current locale.
798d6e29
MS
10575
10576</p>
b6008d6b 10577<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippNewResponse">ippNewResponse</a></h3>
b47dab17 10578<p class="description">Allocate a new IPP response message.</p>
798d6e29 10579<p class="code">
98d88c8d 10580<a href="#ipp_t">ipp_t</a> *ippNewResponse(<a href="#ipp_t">ipp_t</a> *request);</p>
798d6e29 10581<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10582<table class="list"><tbody>
10583<tr><th>request</th>
b47dab17 10584<td class="description">IPP request message</td></tr>
98d88c8d 10585</tbody></table>
798d6e29 10586<h4 class="returnvalue">Return Value</h4>
b47dab17 10587<p class="description">IPP response message</p>
798d6e29 10588<h4 class="discussion">Discussion</h4>
b47dab17 10589<p class="discussion">The new response message is initialized with the same &quot;version-number&quot;,
65bebeac
MS
10590&quot;request-id&quot;, &quot;attributes-charset&quot;, and &quot;attributes-natural-language&quot; as the
10591provided request message. If the &quot;attributes-charset&quot; or
10592&quot;attributes-natural-language&quot; attributes are missing from the request,
10593'utf-8' and a value derived from the current locale are substituted,
798d6e29
MS
10594respectively.
10595
10596</p>
b6008d6b 10597<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippOpString">ippOpString</a></h3>
b47dab17 10598<p class="description">Return a name for the given operation id.</p>
798d6e29 10599<p class="code">
0350eba5 10600<span class="reserved">const</span> <span class="reserved">char</span> *ippOpString(<a href="#ipp_op_t">ipp_op_t</a> op);</p>
798d6e29 10601<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10602<table class="list"><tbody>
10603<tr><th>op</th>
b47dab17 10604<td class="description">Operation ID</td></tr>
98d88c8d 10605</tbody></table>
798d6e29 10606<h4 class="returnvalue">Return Value</h4>
b47dab17 10607<p class="description">Name</p>
b6008d6b 10608<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippOpValue">ippOpValue</a></h3>
b47dab17 10609<p class="description">Return an operation id for the given name.</p>
798d6e29 10610<p class="code">
0350eba5 10611<a href="#ipp_op_t">ipp_op_t</a> ippOpValue(<span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
798d6e29 10612<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10613<table class="list"><tbody>
10614<tr><th>name</th>
b47dab17 10615<td class="description">Textual name</td></tr>
98d88c8d 10616</tbody></table>
798d6e29 10617<h4 class="returnvalue">Return Value</h4>
b47dab17 10618<p class="description">Operation ID</p>
798d6e29 10619<h3 class="function"><a id="ippRead">ippRead</a></h3>
b47dab17 10620<p class="description">Read data for an IPP message from a HTTP connection.</p>
798d6e29 10621<p class="code">
98d88c8d 10622<a href="#ipp_state_t">ipp_state_t</a> ippRead(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10623<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10624<table class="list"><tbody>
10625<tr><th>http</th>
b47dab17 10626<td class="description">HTTP connection</td></tr>
98d88c8d 10627<tr><th>ipp</th>
b47dab17 10628<td class="description">IPP data</td></tr>
98d88c8d 10629</tbody></table>
798d6e29 10630<h4 class="returnvalue">Return Value</h4>
b47dab17 10631<p class="description">Current state</p>
b6008d6b 10632<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="ippReadFile">ippReadFile</a></h3>
b47dab17 10633<p class="description">Read data for an IPP message from a file.</p>
798d6e29 10634<p class="code">
0350eba5 10635<a href="#ipp_state_t">ipp_state_t</a> ippReadFile(<span class="reserved">int</span> fd, <a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 10636<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10637<table class="list"><tbody>
10638<tr><th>fd</th>
b47dab17 10639<td class="description">HTTP data</td></tr>
98d88c8d 10640<tr><th>ipp</th>
b47dab17 10641<td class="description">IPP data</td></tr>
98d88c8d 10642</tbody></table>
798d6e29 10643<h4 class="returnvalue">Return Value</h4>
b47dab17 10644<p class="description">Current state</p>
b6008d6b 10645<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippReadIO">ippReadIO</a></h3>
b47dab17 10646<p class="description">Read data for an IPP message.</p>
798d6e29 10647<p class="code">
0350eba5 10648<a href="#ipp_state_t">ipp_state_t</a> ippReadIO(<span class="reserved">void</span> *src, <a href="#ipp_io_cb_t">ipp_io_cb_t</a> cb, <span class="reserved">int</span> blocking, <a href="#ipp_t">ipp_t</a> *parent, <a href="#ipp_t">ipp_t</a> *ipp);</p>
98d88c8d
MS
10649<h4 class="parameters">Parameters</h4>
10650<table class="list"><tbody>
10651<tr><th>src</th>
b47dab17 10652<td class="description">Data source</td></tr>
98d88c8d 10653<tr><th>cb</th>
b47dab17 10654<td class="description">Read callback function</td></tr>
98d88c8d 10655<tr><th>blocking</th>
b47dab17 10656<td class="description">Use blocking IO?</td></tr>
98d88c8d 10657<tr><th>parent</th>
b47dab17 10658<td class="description">Parent request, if any</td></tr>
98d88c8d 10659<tr><th>ipp</th>
b47dab17 10660<td class="description">IPP data</td></tr>
98d88c8d 10661</tbody></table>
798d6e29 10662<h4 class="returnvalue">Return Value</h4>
b47dab17 10663<p class="description">Current state</p>
af268786
MS
10664<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippRestore">ippRestore</a></h3>
10665<p class="description">Restore a previously saved find position.</p>
10666<p class="code">
0350eba5 10667<span class="reserved">void</span> ippRestore(<a href="#ipp_t">ipp_t</a> *ipp);</p>
af268786
MS
10668<h4 class="parameters">Parameters</h4>
10669<table class="list"><tbody>
10670<tr><th>ipp</th>
10671<td class="description">IPP message</td></tr>
10672</tbody></table>
10673<h3 class="function"><span class="info">&#160;CUPS 2.5&#160;</span><a id="ippSave">ippSave</a></h3>
10674<p class="description">Save the current find position.</p>
10675<p class="code">
0350eba5 10676<span class="reserved">void</span> ippSave(<a href="#ipp_t">ipp_t</a> *ipp);</p>
af268786
MS
10677<h4 class="parameters">Parameters</h4>
10678<table class="list"><tbody>
10679<tr><th>ipp</th>
10680<td class="description">IPP message</td></tr>
10681</tbody></table>
b6008d6b 10682<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetBoolean">ippSetBoolean</a></h3>
b47dab17 10683<p class="description">Set a boolean value in an attribute.</p>
798d6e29 10684<p class="code">
0350eba5 10685<span class="reserved">int</span> ippSetBoolean(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">int</span> boolvalue);</p>
98d88c8d
MS
10686<h4 class="parameters">Parameters</h4>
10687<table class="list"><tbody>
10688<tr><th>ipp</th>
b47dab17 10689<td class="description">IPP message</td></tr>
98d88c8d 10690<tr><th>attr</th>
b47dab17 10691<td class="description">IPP attribute</td></tr>
98d88c8d 10692<tr><th>element</th>
b47dab17 10693<td class="description">Value number (0-based)</td></tr>
98d88c8d 10694<tr><th>boolvalue</th>
b47dab17 10695<td class="description">Boolean value</td></tr>
98d88c8d 10696</tbody></table>
798d6e29 10697<h4 class="returnvalue">Return Value</h4>
b47dab17 10698<p class="description">1 on success, 0 on failure</p>
798d6e29 10699<h4 class="discussion">Discussion</h4>
af268786 10700<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10701the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10702<br>
af268786 10703The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10704<br>
af268786 10705The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10706<code>ippGetCount(attr)</code>.
798d6e29
MS
10707
10708</p>
b6008d6b 10709<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetCollection">ippSetCollection</a></h3>
b47dab17 10710<p class="description">Set a collection value in an attribute.</p>
798d6e29 10711<p class="code">
0350eba5 10712<span class="reserved">int</span> ippSetCollection(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <a href="#ipp_t">ipp_t</a> *colvalue);</p>
98d88c8d
MS
10713<h4 class="parameters">Parameters</h4>
10714<table class="list"><tbody>
10715<tr><th>ipp</th>
b47dab17 10716<td class="description">IPP message</td></tr>
98d88c8d 10717<tr><th>attr</th>
b47dab17 10718<td class="description">IPP attribute</td></tr>
98d88c8d 10719<tr><th>element</th>
b47dab17 10720<td class="description">Value number (0-based)</td></tr>
98d88c8d 10721<tr><th>colvalue</th>
b47dab17 10722<td class="description">Collection value</td></tr>
98d88c8d 10723</tbody></table>
798d6e29 10724<h4 class="returnvalue">Return Value</h4>
b47dab17 10725<p class="description">1 on success, 0 on failure</p>
798d6e29 10726<h4 class="discussion">Discussion</h4>
af268786 10727<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10728the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10729<br>
af268786 10730The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10731<br>
af268786 10732The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10733<code>ippGetCount(attr)</code>.
798d6e29
MS
10734
10735</p>
b6008d6b 10736<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetDate">ippSetDate</a></h3>
b47dab17 10737<p class="description">Set a dateTime value in an attribute.</p>
798d6e29 10738<p class="code">
0350eba5 10739<span class="reserved">int</span> ippSetDate(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <a href="#ipp_uchar_t">ipp_uchar_t</a> *datevalue);</p>
98d88c8d
MS
10740<h4 class="parameters">Parameters</h4>
10741<table class="list"><tbody>
10742<tr><th>ipp</th>
b47dab17 10743<td class="description">IPP message</td></tr>
98d88c8d 10744<tr><th>attr</th>
b47dab17 10745<td class="description">IPP attribute</td></tr>
98d88c8d 10746<tr><th>element</th>
b47dab17 10747<td class="description">Value number (0-based)</td></tr>
98d88c8d 10748<tr><th>datevalue</th>
b47dab17 10749<td class="description">dateTime value</td></tr>
98d88c8d 10750</tbody></table>
798d6e29 10751<h4 class="returnvalue">Return Value</h4>
b47dab17 10752<p class="description">1 on success, 0 on failure</p>
798d6e29 10753<h4 class="discussion">Discussion</h4>
af268786 10754<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10755the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10756<br>
af268786 10757The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10758<br>
af268786 10759The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10760<code>ippGetCount(attr)</code>.
798d6e29
MS
10761
10762</p>
b6008d6b 10763<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetGroupTag">ippSetGroupTag</a></h3>
b47dab17 10764<p class="description">Set the group tag of an attribute.</p>
798d6e29 10765<p class="code">
0350eba5 10766<span class="reserved">int</span> ippSetGroupTag(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, ipp_tag_t group_tag);</p>
98d88c8d
MS
10767<h4 class="parameters">Parameters</h4>
10768<table class="list"><tbody>
10769<tr><th>ipp</th>
b47dab17 10770<td class="description">IPP message</td></tr>
98d88c8d 10771<tr><th>attr</th>
b47dab17 10772<td class="description">Attribute</td></tr>
98d88c8d 10773<tr><th>group_tag</th>
b47dab17 10774<td class="description">Group tag</td></tr>
98d88c8d 10775</tbody></table>
798d6e29 10776<h4 class="returnvalue">Return Value</h4>
b47dab17 10777<p class="description">1 on success, 0 on failure</p>
798d6e29 10778<h4 class="discussion">Discussion</h4>
af268786 10779<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10780the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10781<br>
af268786 10782The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10783<br>
af268786 10784The &quot;group&quot; parameter specifies the IPP attribute group tag: none
798d6e29
MS
10785(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>),
10786event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation
10787(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription
10788(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).
10789
10790</p>
b6008d6b 10791<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetInteger">ippSetInteger</a></h3>
b47dab17 10792<p class="description">Set an integer or enum value in an attribute.</p>
798d6e29 10793<p class="code">
0350eba5 10794<span class="reserved">int</span> ippSetInteger(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">int</span> intvalue);</p>
98d88c8d
MS
10795<h4 class="parameters">Parameters</h4>
10796<table class="list"><tbody>
10797<tr><th>ipp</th>
b47dab17 10798<td class="description">IPP message</td></tr>
98d88c8d 10799<tr><th>attr</th>
b47dab17 10800<td class="description">IPP attribute</td></tr>
98d88c8d 10801<tr><th>element</th>
b47dab17 10802<td class="description">Value number (0-based)</td></tr>
98d88c8d 10803<tr><th>intvalue</th>
b47dab17 10804<td class="description">Integer/enum value</td></tr>
98d88c8d 10805</tbody></table>
798d6e29 10806<h4 class="returnvalue">Return Value</h4>
b47dab17 10807<p class="description">1 on success, 0 on failure</p>
798d6e29 10808<h4 class="discussion">Discussion</h4>
af268786 10809<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10810the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10811<br>
af268786 10812The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10813<br>
af268786 10814The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10815<code>ippGetCount(attr)</code>.
798d6e29
MS
10816
10817</p>
b6008d6b 10818<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetName">ippSetName</a></h3>
b47dab17 10819<p class="description">Set the name of an attribute.</p>
798d6e29 10820<p class="code">
0350eba5 10821<span class="reserved">int</span> ippSetName(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
98d88c8d
MS
10822<h4 class="parameters">Parameters</h4>
10823<table class="list"><tbody>
10824<tr><th>ipp</th>
b47dab17 10825<td class="description">IPP message</td></tr>
98d88c8d 10826<tr><th>attr</th>
b47dab17 10827<td class="description">IPP attribute</td></tr>
98d88c8d 10828<tr><th>name</th>
b47dab17 10829<td class="description">Attribute name</td></tr>
98d88c8d 10830</tbody></table>
798d6e29 10831<h4 class="returnvalue">Return Value</h4>
b47dab17 10832<p class="description">1 on success, 0 on failure</p>
798d6e29 10833<h4 class="discussion">Discussion</h4>
af268786 10834<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10835the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10836<br>
af268786 10837The &quot;attr&quot; parameter may be modified as a result of setting the value.
798d6e29
MS
10838
10839</p>
b6008d6b 10840<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippSetOctetString">ippSetOctetString</a></h3>
b47dab17 10841<p class="description">Set an octetString value in an IPP attribute.</p>
798d6e29 10842<p class="code">
0350eba5 10843<span class="reserved">int</span> ippSetOctetString(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <span class="reserved">void</span> *data, <span class="reserved">int</span> datalen);</p>
98d88c8d
MS
10844<h4 class="parameters">Parameters</h4>
10845<table class="list"><tbody>
10846<tr><th>ipp</th>
b47dab17 10847<td class="description">IPP message</td></tr>
98d88c8d 10848<tr><th>attr</th>
b47dab17 10849<td class="description">IPP attribute</td></tr>
98d88c8d 10850<tr><th>element</th>
b47dab17 10851<td class="description">Value number (0-based)</td></tr>
98d88c8d 10852<tr><th>data</th>
b47dab17 10853<td class="description">Pointer to octetString data</td></tr>
98d88c8d 10854<tr><th>datalen</th>
b47dab17 10855<td class="description">Length of octetString data</td></tr>
98d88c8d 10856</tbody></table>
798d6e29 10857<h4 class="returnvalue">Return Value</h4>
b47dab17 10858<p class="description">1 on success, 0 on failure</p>
798d6e29 10859<h4 class="discussion">Discussion</h4>
af268786 10860<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10861the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10862<br>
af268786 10863The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10864<br>
af268786 10865The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10866<code>ippGetCount(attr)</code>.
798d6e29
MS
10867
10868</p>
b6008d6b 10869<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetOperation">ippSetOperation</a></h3>
b47dab17 10870<p class="description">Set the operation ID in an IPP request message.</p>
798d6e29 10871<p class="code">
0350eba5 10872<span class="reserved">int</span> ippSetOperation(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_op_t">ipp_op_t</a> op);</p>
798d6e29 10873<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10874<table class="list"><tbody>
10875<tr><th>ipp</th>
b47dab17 10876<td class="description">IPP request message</td></tr>
98d88c8d 10877<tr><th>op</th>
b47dab17 10878<td class="description">Operation ID</td></tr>
98d88c8d 10879</tbody></table>
798d6e29 10880<h4 class="returnvalue">Return Value</h4>
b47dab17 10881<p class="description">1 on success, 0 on failure</p>
798d6e29 10882<h4 class="discussion">Discussion</h4>
af268786 10883<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10884the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
10885
10886</p>
10887<h3 class="function"><a id="ippSetPort">ippSetPort</a></h3>
b47dab17 10888<p class="description">Set the default port number.</p>
798d6e29 10889<p class="code">
0350eba5 10890<span class="reserved">void</span> ippSetPort(<span class="reserved">int</span> p);</p>
798d6e29 10891<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10892<table class="list"><tbody>
10893<tr><th>p</th>
b47dab17 10894<td class="description">Port number to use</td></tr>
98d88c8d 10895</tbody></table>
b6008d6b 10896<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetRange">ippSetRange</a></h3>
b47dab17 10897<p class="description">Set a rangeOfInteger value in an attribute.</p>
798d6e29 10898<p class="code">
0350eba5 10899<span class="reserved">int</span> ippSetRange(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">int</span> lowervalue, <span class="reserved">int</span> uppervalue);</p>
98d88c8d
MS
10900<h4 class="parameters">Parameters</h4>
10901<table class="list"><tbody>
10902<tr><th>ipp</th>
b47dab17 10903<td class="description">IPP message</td></tr>
98d88c8d 10904<tr><th>attr</th>
b47dab17 10905<td class="description">IPP attribute</td></tr>
98d88c8d 10906<tr><th>element</th>
b47dab17 10907<td class="description">Value number (0-based)</td></tr>
98d88c8d 10908<tr><th>lowervalue</th>
b47dab17 10909<td class="description">Lower bound for range</td></tr>
98d88c8d 10910<tr><th>uppervalue</th>
b47dab17 10911<td class="description">Upper bound for range</td></tr>
98d88c8d 10912</tbody></table>
798d6e29 10913<h4 class="returnvalue">Return Value</h4>
b47dab17 10914<p class="description">1 on success, 0 on failure</p>
798d6e29 10915<h4 class="discussion">Discussion</h4>
af268786 10916<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10917the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10918<br>
af268786 10919The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10920<br>
af268786 10921The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10922<code>ippGetCount(attr)</code>.
798d6e29
MS
10923
10924</p>
b6008d6b 10925<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetRequestId">ippSetRequestId</a></h3>
b47dab17 10926<p class="description">Set the request ID in an IPP message.</p>
798d6e29 10927<p class="code">
0350eba5 10928<span class="reserved">int</span> ippSetRequestId(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">int</span> request_id);</p>
798d6e29 10929<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10930<table class="list"><tbody>
10931<tr><th>ipp</th>
b47dab17 10932<td class="description">IPP message</td></tr>
98d88c8d 10933<tr><th>request_id</th>
b47dab17 10934<td class="description">Request ID</td></tr>
98d88c8d 10935</tbody></table>
798d6e29 10936<h4 class="returnvalue">Return Value</h4>
b47dab17 10937<p class="description">1 on success, 0 on failure</p>
798d6e29 10938<h4 class="discussion">Discussion</h4>
af268786 10939<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10940the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10941<br>
10942The <code>request_id</code> parameter must be greater than 0.
10943
10944</p>
b6008d6b 10945<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetResolution">ippSetResolution</a></h3>
b47dab17 10946<p class="description">Set a resolution value in an attribute.</p>
798d6e29 10947<p class="code">
0350eba5 10948<span class="reserved">int</span> ippSetResolution(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <a href="#ipp_res_t">ipp_res_t</a> unitsvalue, <span class="reserved">int</span> xresvalue, <span class="reserved">int</span> yresvalue);</p>
98d88c8d
MS
10949<h4 class="parameters">Parameters</h4>
10950<table class="list"><tbody>
10951<tr><th>ipp</th>
b47dab17 10952<td class="description">IPP message</td></tr>
98d88c8d 10953<tr><th>attr</th>
b47dab17 10954<td class="description">IPP attribute</td></tr>
98d88c8d 10955<tr><th>element</th>
b47dab17 10956<td class="description">Value number (0-based)</td></tr>
98d88c8d 10957<tr><th>unitsvalue</th>
b47dab17 10958<td class="description">Resolution units</td></tr>
98d88c8d 10959<tr><th>xresvalue</th>
b47dab17 10960<td class="description">Horizontal/cross feed resolution</td></tr>
98d88c8d 10961<tr><th>yresvalue</th>
b47dab17 10962<td class="description">Vertical/feed resolution</td></tr>
98d88c8d 10963</tbody></table>
798d6e29 10964<h4 class="returnvalue">Return Value</h4>
b47dab17 10965<p class="description">1 on success, 0 on failure</p>
798d6e29 10966<h4 class="discussion">Discussion</h4>
af268786 10967<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
10968the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
10969<br>
af268786 10970The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 10971<br>
af268786 10972The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 10973<code>ippGetCount(attr)</code>.
798d6e29
MS
10974
10975</p>
b6008d6b 10976<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetState">ippSetState</a></h3>
b47dab17 10977<p class="description">Set the current state of the IPP message.</p>
798d6e29 10978<p class="code">
0350eba5 10979<span class="reserved">int</span> ippSetState(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_state_t">ipp_state_t</a> state);</p>
798d6e29 10980<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10981<table class="list"><tbody>
10982<tr><th>ipp</th>
b47dab17 10983<td class="description">IPP message</td></tr>
98d88c8d 10984<tr><th>state</th>
b47dab17 10985<td class="description">IPP state value</td></tr>
98d88c8d 10986</tbody></table>
798d6e29 10987<h4 class="returnvalue">Return Value</h4>
b47dab17 10988<p class="description">1 on success, 0 on failure</p>
b6008d6b 10989<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetStatusCode">ippSetStatusCode</a></h3>
b47dab17 10990<p class="description">Set the status code in an IPP response or event message.</p>
798d6e29 10991<p class="code">
0350eba5 10992<span class="reserved">int</span> ippSetStatusCode(<a href="#ipp_t">ipp_t</a> *ipp, ipp_status_t status);</p>
798d6e29 10993<h4 class="parameters">Parameters</h4>
98d88c8d
MS
10994<table class="list"><tbody>
10995<tr><th>ipp</th>
b47dab17 10996<td class="description">IPP response or event message</td></tr>
98d88c8d 10997<tr><th>status</th>
b47dab17 10998<td class="description">Status code</td></tr>
98d88c8d 10999</tbody></table>
798d6e29 11000<h4 class="returnvalue">Return Value</h4>
b47dab17 11001<p class="description">1 on success, 0 on failure</p>
798d6e29 11002<h4 class="discussion">Discussion</h4>
af268786 11003<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11004the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.
11005
11006</p>
b6008d6b 11007<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetString">ippSetString</a></h3>
b47dab17 11008<p class="description">Set a string value in an attribute.</p>
798d6e29 11009<p class="code">
0350eba5 11010<span class="reserved">int</span> ippSetString(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <span class="reserved">char</span> *strvalue);</p>
98d88c8d
MS
11011<h4 class="parameters">Parameters</h4>
11012<table class="list"><tbody>
11013<tr><th>ipp</th>
b47dab17 11014<td class="description">IPP message</td></tr>
98d88c8d 11015<tr><th>attr</th>
b47dab17 11016<td class="description">IPP attribute</td></tr>
98d88c8d 11017<tr><th>element</th>
b47dab17 11018<td class="description">Value number (0-based)</td></tr>
98d88c8d 11019<tr><th>strvalue</th>
b47dab17 11020<td class="description">String value</td></tr>
98d88c8d 11021</tbody></table>
798d6e29 11022<h4 class="returnvalue">Return Value</h4>
b47dab17 11023<p class="description">1 on success, 0 on failure</p>
798d6e29 11024<h4 class="discussion">Discussion</h4>
af268786 11025<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11026the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
11027<br>
af268786 11028The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 11029<br>
af268786 11030The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 11031<code>ippGetCount(attr)</code>.
798d6e29
MS
11032
11033</p>
b6008d6b 11034<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippSetStringf">ippSetStringf</a></h3>
b47dab17 11035<p class="description">Set a formatted string value of an attribute.</p>
798d6e29 11036<p class="code">
0350eba5 11037<span class="reserved">int</span> ippSetStringf(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <span class="reserved">char</span> *format, ...);</p>
98d88c8d
MS
11038<h4 class="parameters">Parameters</h4>
11039<table class="list"><tbody>
11040<tr><th>ipp</th>
b47dab17 11041<td class="description">IPP message</td></tr>
98d88c8d 11042<tr><th>attr</th>
b47dab17 11043<td class="description">IPP attribute</td></tr>
98d88c8d 11044<tr><th>element</th>
b47dab17 11045<td class="description">Value number (0-based)</td></tr>
98d88c8d 11046<tr><th>format</th>
b47dab17 11047<td class="description">Printf-style format string</td></tr>
98d88c8d 11048<tr><th>...</th>
b47dab17 11049<td class="description">Additional arguments as needed</td></tr>
98d88c8d 11050</tbody></table>
798d6e29 11051<h4 class="returnvalue">Return Value</h4>
b47dab17 11052<p class="description">1 on success, 0 on failure</p>
798d6e29 11053<h4 class="discussion">Discussion</h4>
af268786 11054<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11055the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
11056<br>
af268786 11057The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 11058<br>
af268786 11059The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 11060<code>ippGetCount(attr)</code>.<br>
798d6e29 11061<br>
af268786 11062The &quot;format&quot; parameter uses formatting characters compatible with the
798d6e29
MS
11063printf family of standard functions. Additional arguments follow it as
11064needed. The formatted string is truncated as needed to the maximum length of
11065the corresponding value type.
11066
11067</p>
b6008d6b 11068<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippSetStringfv">ippSetStringfv</a></h3>
b47dab17 11069<p class="description">Set a formatted string value of an attribute.</p>
798d6e29 11070<p class="code">
0350eba5 11071<span class="reserved">int</span> ippSetStringfv(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, <span class="reserved">int</span> element, <span class="reserved">const</span> <span class="reserved">char</span> *format, va_list ap);</p>
98d88c8d
MS
11072<h4 class="parameters">Parameters</h4>
11073<table class="list"><tbody>
11074<tr><th>ipp</th>
b47dab17 11075<td class="description">IPP message</td></tr>
98d88c8d 11076<tr><th>attr</th>
b47dab17 11077<td class="description">IPP attribute</td></tr>
98d88c8d 11078<tr><th>element</th>
b47dab17 11079<td class="description">Value number (0-based)</td></tr>
98d88c8d 11080<tr><th>format</th>
b47dab17 11081<td class="description">Printf-style format string</td></tr>
98d88c8d 11082<tr><th>ap</th>
b47dab17 11083<td class="description">Pointer to additional arguments</td></tr>
98d88c8d 11084</tbody></table>
798d6e29 11085<h4 class="returnvalue">Return Value</h4>
b47dab17 11086<p class="description">1 on success, 0 on failure</p>
798d6e29 11087<h4 class="discussion">Discussion</h4>
af268786 11088<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11089the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
11090<br>
af268786 11091The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29 11092<br>
af268786 11093The &quot;element&quot; parameter specifies which value to set from 0 to
65bebeac 11094<code>ippGetCount(attr)</code>.<br>
798d6e29 11095<br>
af268786 11096The &quot;format&quot; parameter uses formatting characters compatible with the
798d6e29
MS
11097printf family of standard functions. Additional arguments follow it as
11098needed. The formatted string is truncated as needed to the maximum length of
11099the corresponding value type.
11100
11101</p>
b6008d6b 11102<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetValueTag">ippSetValueTag</a></h3>
b47dab17 11103<p class="description">Set the value tag of an attribute.</p>
798d6e29 11104<p class="code">
0350eba5 11105<span class="reserved">int</span> ippSetValueTag(<a href="#ipp_t">ipp_t</a> *ipp, <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr, ipp_tag_t value_tag);</p>
98d88c8d
MS
11106<h4 class="parameters">Parameters</h4>
11107<table class="list"><tbody>
11108<tr><th>ipp</th>
b47dab17 11109<td class="description">IPP message</td></tr>
98d88c8d 11110<tr><th>attr</th>
b47dab17 11111<td class="description">IPP attribute</td></tr>
98d88c8d 11112<tr><th>value_tag</th>
b47dab17 11113<td class="description">Value tag</td></tr>
98d88c8d 11114</tbody></table>
798d6e29 11115<h4 class="returnvalue">Return Value</h4>
b47dab17 11116<p class="description">1 on success, 0 on failure</p>
798d6e29 11117<h4 class="discussion">Discussion</h4>
af268786 11118<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11119the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
11120<br>
af268786 11121The &quot;attr&quot; parameter may be modified as a result of setting the value.<br>
798d6e29
MS
11122<br>
11123Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger
11124(<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name
11125(<code>IPP_TAG_NAME</code>) or nameWithLanguage (<code>IPP_TAG_NAMELANG</code>) values, text
11126(<code>IPP_TAG_TEXT</code>) values can be promoted to textWithLanguage
11127(<code>IPP_TAG_TEXTLANG</code>) values, and all values can be demoted to the various
af268786
MS
11128out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other
11129changes will be rejected.<br>
798d6e29
MS
11130<br>
11131Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
11132code in the &quot;attributes-natural-language&quot; attribute or, if not present, the language
11133code for the current locale.
11134
11135</p>
b6008d6b 11136<h3 class="function"><span class="info">&#160;CUPS 1.6&#160;</span><a id="ippSetVersion">ippSetVersion</a></h3>
b47dab17 11137<p class="description">Set the version number in an IPP message.</p>
798d6e29 11138<p class="code">
0350eba5 11139<span class="reserved">int</span> ippSetVersion(<a href="#ipp_t">ipp_t</a> *ipp, <span class="reserved">int</span> major, <span class="reserved">int</span> minor);</p>
98d88c8d
MS
11140<h4 class="parameters">Parameters</h4>
11141<table class="list"><tbody>
11142<tr><th>ipp</th>
b47dab17 11143<td class="description">IPP message</td></tr>
98d88c8d 11144<tr><th>major</th>
b47dab17 11145<td class="description">Major version number (major.minor)</td></tr>
98d88c8d 11146<tr><th>minor</th>
b47dab17 11147<td class="description">Minor version number (major.minor)</td></tr>
98d88c8d 11148</tbody></table>
798d6e29 11149<h4 class="returnvalue">Return Value</h4>
b47dab17 11150<p class="description">1 on success, 0 on failure</p>
798d6e29 11151<h4 class="discussion">Discussion</h4>
af268786 11152<p class="discussion">The &quot;ipp&quot; parameter refers to an IPP message previously created using
798d6e29
MS
11153the <a href="#ippNew"><code>ippNew</code></a>, <a href="#ippNewRequest"><code>ippNewRequest</code></a>, or <a href="#ippNewResponse"><code>ippNewResponse</code></a> functions.<br>
11154<br>
11155The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
11156
11157</p>
11158<h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="ippStateString">ippStateString</a></h3>
b47dab17 11159<p class="description">Return the name corresponding to a state value.</p>
798d6e29 11160<p class="code">
0350eba5 11161<span class="reserved">const</span> <span class="reserved">char</span> *ippStateString(<a href="#ipp_state_t">ipp_state_t</a> state);</p>
798d6e29 11162<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11163<table class="list"><tbody>
11164<tr><th>state</th>
b47dab17 11165<td class="description">State value</td></tr>
98d88c8d 11166</tbody></table>
798d6e29 11167<h4 class="returnvalue">Return Value</h4>
b47dab17 11168<p class="description">State name</p>
b6008d6b 11169<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="ippTagString">ippTagString</a></h3>
b47dab17 11170<p class="description">Return the tag name corresponding to a tag value.</p>
798d6e29 11171<p class="code">
0350eba5 11172<span class="reserved">const</span> <span class="reserved">char</span> *ippTagString(ipp_tag_t tag);</p>
798d6e29 11173<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11174<table class="list"><tbody>
11175<tr><th>tag</th>
b47dab17 11176<td class="description">Tag value</td></tr>
98d88c8d 11177</tbody></table>
798d6e29 11178<h4 class="returnvalue">Return Value</h4>
b47dab17 11179<p class="description">Tag name</p>
798d6e29 11180<h4 class="discussion">Discussion</h4>
b47dab17 11181<p class="discussion">The returned names are defined in RFC 8011 and the IANA IPP Registry.
798d6e29
MS
11182
11183</p>
b6008d6b 11184<h3 class="function"><span class="info">&#160;CUPS 1.4&#160;</span><a id="ippTagValue">ippTagValue</a></h3>
b47dab17 11185<p class="description">Return the tag value corresponding to a tag name.</p>
798d6e29 11186<p class="code">
0350eba5 11187ipp_tag_t ippTagValue(<span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
798d6e29 11188<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11189<table class="list"><tbody>
11190<tr><th>name</th>
b47dab17 11191<td class="description">Tag name</td></tr>
98d88c8d 11192</tbody></table>
798d6e29 11193<h4 class="returnvalue">Return Value</h4>
b47dab17 11194<p class="description">Tag value</p>
798d6e29 11195<h4 class="discussion">Discussion</h4>
b47dab17 11196<p class="discussion">The tag names are defined in RFC 8011 and the IANA IPP Registry.
798d6e29
MS
11197
11198</p>
11199<h3 class="function"><a id="ippTimeToDate">ippTimeToDate</a></h3>
b47dab17 11200<p class="description">Convert from time in seconds to RFC 2579 format.</p>
798d6e29 11201<p class="code">
0350eba5 11202<span class="reserved">const</span> <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate(time_t t);</p>
798d6e29 11203<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11204<table class="list"><tbody>
11205<tr><th>t</th>
b47dab17 11206<td class="description">Time in seconds</td></tr>
98d88c8d 11207</tbody></table>
798d6e29 11208<h4 class="returnvalue">Return Value</h4>
b47dab17 11209<p class="description">RFC-2579 date/time data</p>
b6008d6b 11210<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippValidateAttribute">ippValidateAttribute</a></h3>
b47dab17 11211<p class="description">Validate the contents of an attribute.</p>
798d6e29 11212<p class="code">
0350eba5 11213<span class="reserved">int</span> ippValidateAttribute(<a href="#ipp_attribute_t">ipp_attribute_t</a> *attr);</p>
798d6e29 11214<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11215<table class="list"><tbody>
11216<tr><th>attr</th>
b47dab17 11217<td class="description">Attribute</td></tr>
98d88c8d 11218</tbody></table>
798d6e29 11219<h4 class="returnvalue">Return Value</h4>
b47dab17 11220<p class="description">1 if valid, 0 otherwise</p>
798d6e29 11221<h4 class="discussion">Discussion</h4>
b47dab17 11222<p class="discussion">This function validates the contents of an attribute based on the name and
798d6e29 11223value tag. 1 is returned if the attribute is valid, 0 otherwise. On
be6cfd68 11224failure, <a href="#cupsGetErrorString"><code>cupsGetErrorString</code></a> is set to a human-readable message.
798d6e29
MS
11225
11226</p>
b6008d6b 11227<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="ippValidateAttributes">ippValidateAttributes</a></h3>
b47dab17 11228<p class="description">Validate all attributes in an IPP message.</p>
798d6e29 11229<p class="code">
0350eba5 11230<span class="reserved">int</span> ippValidateAttributes(<a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 11231<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11232<table class="list"><tbody>
11233<tr><th>ipp</th>
b47dab17 11234<td class="description">IPP message</td></tr>
98d88c8d 11235</tbody></table>
798d6e29 11236<h4 class="returnvalue">Return Value</h4>
b47dab17 11237<p class="description">1 if valid, 0 otherwise</p>
798d6e29 11238<h4 class="discussion">Discussion</h4>
b47dab17 11239<p class="discussion">This function validates the contents of the IPP message, including each
be6cfd68 11240attribute. Like <a href="#ippValidateAttribute"><code>ippValidateAttribute</code></a>, <a href="#cupsGetErrorString"><code>cupsGetErrorString</code></a> is
65bebeac 11241set to a human-readable message on failure.
798d6e29
MS
11242
11243</p>
11244<h3 class="function"><a id="ippWrite">ippWrite</a></h3>
b47dab17 11245<p class="description">Write data for an IPP message to a HTTP connection.</p>
798d6e29 11246<p class="code">
98d88c8d 11247<a href="#ipp_state_t">ipp_state_t</a> ippWrite(<a href="#http_t">http_t</a> *http, <a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 11248<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11249<table class="list"><tbody>
11250<tr><th>http</th>
b47dab17 11251<td class="description">HTTP connection</td></tr>
98d88c8d 11252<tr><th>ipp</th>
b47dab17 11253<td class="description">IPP data</td></tr>
98d88c8d 11254</tbody></table>
798d6e29 11255<h4 class="returnvalue">Return Value</h4>
b47dab17 11256<p class="description">Current state</p>
b6008d6b 11257<h3 class="function"><span class="info">&#160;CUPS 1.1.19&#160;</span><a id="ippWriteFile">ippWriteFile</a></h3>
b47dab17 11258<p class="description">Write data for an IPP message to a file.</p>
798d6e29 11259<p class="code">
0350eba5 11260<a href="#ipp_state_t">ipp_state_t</a> ippWriteFile(<span class="reserved">int</span> fd, <a href="#ipp_t">ipp_t</a> *ipp);</p>
798d6e29 11261<h4 class="parameters">Parameters</h4>
98d88c8d
MS
11262<table class="list"><tbody>
11263<tr><th>fd</th>
b47dab17 11264<td class="description">HTTP data</td></tr>
98d88c8d 11265<tr><th>ipp</th>
b47dab17 11266<td class="description">IPP data</td></tr>
98d88c8d 11267</tbody></table>
798d6e29 11268<h4 class="returnvalue">Return Value</h4>
b47dab17 11269<p class="description">Current state</p>
b6008d6b 11270<h3 class="function"><span class="info">&#160;CUPS 1.2&#160;</span><a id="ippWriteIO">ippWriteIO</a></h3>
b47dab17 11271<p class="description">Write data for an IPP message.</p>
798d6e29 11272<p class="code">
0350eba5 11273<a href="#ipp_state_t">ipp_state_t</a> ippWriteIO(<span class="reserved">void</span> *dst, <a href="#ipp_io_cb_t">ipp_io_cb_t</a> cb, <span class="reserved">int</span> blocking, <a href="#ipp_t">ipp_t</a> *parent, <a href="#ipp_t">ipp_t</a> *ipp);</p>
98d88c8d
MS
11274<h4 class="parameters">Parameters</h4>
11275<table class="list"><tbody>
11276<tr><th>dst</th>
b47dab17 11277<td class="description">Destination</td></tr>
98d88c8d 11278<tr><th>cb</th>
b47dab17 11279<td class="description">Write callback function</td></tr>
98d88c8d 11280<tr><th>blocking</th>
b47dab17 11281<td class="description">Use blocking IO?</td></tr>
98d88c8d 11282<tr><th>parent</th>
b47dab17 11283<td class="description">Parent IPP message</td></tr>
98d88c8d 11284<tr><th>ipp</th>
b47dab17 11285<td class="description">IPP data</td></tr>
98d88c8d 11286</tbody></table>
798d6e29 11287<h4 class="returnvalue">Return Value</h4>
b47dab17 11288<p class="description">Current state</p>
b6008d6b 11289<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgFormatSizeName">pwgFormatSizeName</a></h3>
af268786
MS
11290<p class="description">Generate a PWG self-describing media size name.</p>
11291<p class="code">
0350eba5 11292<span class="reserved">int</span> pwgFormatSizeName(<span class="reserved">char</span> *keyword, size_t keysize, <span class="reserved">const</span> <span class="reserved">char</span> *prefix, <span class="reserved">const</span> <span class="reserved">char</span> *name, <span class="reserved">int</span> width, <span class="reserved">int</span> length, <span class="reserved">const</span> <span class="reserved">char</span> *units);</p>
af268786
MS
11293<h4 class="parameters">Parameters</h4>
11294<table class="list"><tbody>
11295<tr><th>keyword</th>
11296<td class="description">Keyword buffer</td></tr>
11297<tr><th>keysize</th>
11298<td class="description">Size of keyword buffer</td></tr>
11299<tr><th>prefix</th>
11300<td class="description">Prefix for PWG size or <code>NULL</code> for automatic</td></tr>
11301<tr><th>name</th>
11302<td class="description">Size name or <code>NULL</code></td></tr>
11303<tr><th>width</th>
11304<td class="description">Width of page in 2540ths</td></tr>
11305<tr><th>length</th>
11306<td class="description">Length of page in 2540ths</td></tr>
11307<tr><th>units</th>
11308<td class="description">Units - &quot;in&quot;, &quot;mm&quot;, or <code>NULL</code> for automatic</td></tr>
11309</tbody></table>
11310<h4 class="returnvalue">Return Value</h4>
11311<p class="description">1 on success, 0 on failure</p>
11312<h4 class="discussion">Discussion</h4>
11313<p class="discussion">This function generates a PWG self-describing media size name of the form
11314&quot;prefix_name_WIDTHxLENGTHunits&quot;. The prefix is typically &quot;custom&quot; or &quot;roll&quot;
11315for user-supplied sizes but can also be &quot;disc&quot;, &quot;iso&quot;, &quot;jis&quot;, &quot;jpn&quot;, &quot;na&quot;,
11316&quot;oe&quot;, &quot;om&quot;, &quot;prc&quot;, or &quot;roc&quot;. A value of <code>NULL</code> automatically chooses
11317&quot;oe&quot; or &quot;om&quot; depending on the units.<br>
11318<br>
11319The size name may only contain lowercase letters, numbers, &quot;-&quot;, and &quot;.&quot;. If
11320<code>NULL</code> is passed, the size name will contain the formatted dimensions.<br>
11321<br>
11322The width and length are specified in hundredths of millimeters, equivalent
11323to 1/100000th of a meter or 1/2540th of an inch. The width, length, and
11324units used for the generated size name are calculated automatically if the
11325units string is <code>NULL</code>, otherwise inches (&quot;in&quot;) or millimeters (&quot;mm&quot;)
11326are used.
11327
11328</p>
b6008d6b 11329<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgInitSize">pwgInitSize</a></h3>
af268786
MS
11330<p class="description">Initialize a pwg_size_t structure using IPP Job Template
11331 attributes.</p>
11332<p class="code">
0350eba5 11333<span class="reserved">int</span> pwgInitSize(<a href="#pwg_size_t">pwg_size_t</a> *size, <a href="#ipp_t">ipp_t</a> *job, <span class="reserved">int</span> *margins_set);</p>
af268786
MS
11334<h4 class="parameters">Parameters</h4>
11335<table class="list"><tbody>
11336<tr><th>size</th>
11337<td class="description">Size to initialize</td></tr>
11338<tr><th>job</th>
11339<td class="description">Job template attributes</td></tr>
11340<tr><th>margins_set</th>
11341<td class="description">1 if margins were set, 0 otherwise</td></tr>
11342</tbody></table>
11343<h4 class="returnvalue">Return Value</h4>
11344<p class="description">1 if size was initialized, 0 otherwise</p>
11345<h4 class="discussion">Discussion</h4>
11346<p class="discussion">This function initializes a pwg_size_t structure from an IPP &quot;media&quot; or
11347&quot;media-col&quot; attribute in the specified IPP message. 0 is returned if neither
11348attribute is found in the message or the values are not valid.<br>
11349<br>
11350The &quot;margins_set&quot; variable is initialized to 1 if any &quot;media-xxx-margin&quot;
11351member attribute was specified in the &quot;media-col&quot; Job Template attribute,
11352otherwise it is initialized to 0.
11353
11354</p>
b6008d6b 11355<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgMediaForLegacy">pwgMediaForLegacy</a></h3>
af268786
MS
11356<p class="description">Find a PWG media size by ISO/IPP legacy name.</p>
11357<p class="code">
0350eba5 11358<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForLegacy(<span class="reserved">const</span> <span class="reserved">char</span> *legacy);</p>
af268786
MS
11359<h4 class="parameters">Parameters</h4>
11360<table class="list"><tbody>
11361<tr><th>legacy</th>
11362<td class="description">Legacy size name</td></tr>
11363</tbody></table>
11364<h4 class="returnvalue">Return Value</h4>
11365<p class="description">Matching size or NULL</p>
11366<h4 class="discussion">Discussion</h4>
11367<p class="discussion">The &quot;name&quot; argument specifies the legacy ISO media size name, for example
11368&quot;iso-a4&quot; or &quot;na-letter&quot;.
11369
11370</p>
b6008d6b 11371<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgMediaForPPD">pwgMediaForPPD</a></h3>
af268786
MS
11372<p class="description">Find a PWG media size by Adobe PPD name.</p>
11373<p class="code">
0350eba5 11374<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPPD(<span class="reserved">const</span> <span class="reserved">char</span> *ppd);</p>
af268786
MS
11375<h4 class="parameters">Parameters</h4>
11376<table class="list"><tbody>
11377<tr><th>ppd</th>
11378<td class="description">PPD size name</td></tr>
11379</tbody></table>
11380<h4 class="returnvalue">Return Value</h4>
11381<p class="description">Matching size or NULL</p>
11382<h4 class="discussion">Discussion</h4>
11383<p class="discussion">The &quot;ppd&quot; argument specifies an Adobe page size name as defined in Table B.1
11384of the Adobe PostScript Printer Description File Format Specification Version
113854.3.<br>
11386<br>
11387If the name is non-standard, the returned PWG media size is stored in
11388thread-local storage and is overwritten by each call to the function in the
11389thread. Custom names can be of the form &quot;Custom.WIDTHxLENGTH[units]&quot; or
11390&quot;WIDTHxLENGTH[units]&quot;.
11391
11392</p>
b6008d6b 11393<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgMediaForPWG">pwgMediaForPWG</a></h3>
af268786
MS
11394<p class="description">Find a PWG media size by 5101.1 self-describing name.</p>
11395<p class="code">
0350eba5 11396<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForPWG(<span class="reserved">const</span> <span class="reserved">char</span> *pwg);</p>
af268786
MS
11397<h4 class="parameters">Parameters</h4>
11398<table class="list"><tbody>
11399<tr><th>pwg</th>
11400<td class="description">PWG size name</td></tr>
11401</tbody></table>
11402<h4 class="returnvalue">Return Value</h4>
11403<p class="description">Matching size or NULL</p>
11404<h4 class="discussion">Discussion</h4>
11405<p class="discussion">The &quot;pwg&quot; argument specifies a self-describing media size name of the form
11406&quot;prefix_name_WIDTHxLENGTHunits&quot; as defined in PWG 5101.1.<br>
11407<br>
11408If the name is non-standard, the returned PWG media size is stored in
11409thread-local storage and is overwritten by each call to the function in the
11410thread.
11411
11412</p>
b6008d6b 11413<h3 class="function"><span class="info">&#160;CUPS 1.7&#160;</span><a id="pwgMediaForSize">pwgMediaForSize</a></h3>
af268786
MS
11414<p class="description">Get the PWG media size for the given dimensions.</p>
11415<p class="code">
0350eba5 11416<a href="#pwg_media_t">pwg_media_t</a> *pwgMediaForSize(<span class="reserved">int</span> width, <span class="reserved">int</span> length);</p>
af268786
MS
11417<h4 class="parameters">Parameters</h4>
11418<table class="list"><tbody>
11419<tr><th>width</th>
11420<td class="description">Width in hundredths of millimeters</td></tr>
11421<tr><th>length</th>
11422<td class="description">Length in hundredths of millimeters</td></tr>
11423</tbody></table>
11424<h4 class="returnvalue">Return Value</h4>
11425<p class="description">PWG media name</p>
11426<h4 class="discussion">Discussion</h4>
11427<p class="discussion">The &quot;width&quot; and &quot;length&quot; are in hundredths of millimeters, equivalent to
114281/100000th of a meter or 1/2540th of an inch.<br>
11429<br>
11430If the dimensions are non-standard, the returned PWG media size is stored in
11431thread-local storage and is overwritten by each call to the function in the
11432thread.
11433
11434</p>
b47dab17 11435<h2 class="title"><a id="TYPES">Data Types</a></h2>
af268786 11436<h3 class="typedef"><a id="cups_acopy_cb_t">cups_acopy_cb_t</a></h3>
b47dab17
MS
11437<p class="description">Array element copy function</p>
11438<p class="code">
af268786 11439typedef void *(*)(void *element, void *data)cups_acopy_cb_t;
b47dab17
MS
11440</p>
11441<h3 class="typedef"><a id="cups_adv_t">cups_adv_t</a></h3>
11442<p class="description">AdvanceMedia attribute values</p>
11443<p class="code">
11444typedef enum <a href="#cups_adv_e">cups_adv_e</a> cups_adv_t;
11445</p>
af268786 11446<h3 class="typedef"><a id="cups_afree_cb_t">cups_afree_cb_t</a></h3>
b47dab17
MS
11447<p class="description">Array element free function</p>
11448<p class="code">
af268786 11449typedef void(*)(void *element, void *data)cups_afree_cb_t;
b47dab17 11450</p>
af268786 11451<h3 class="typedef"><a id="cups_ahash_cb_t">cups_ahash_cb_t</a></h3>
b47dab17
MS
11452<p class="description">Array hash function</p>
11453<p class="code">
af268786 11454typedef int(*)(void *element, void *data)cups_ahash_cb_t;
b47dab17 11455</p>
af268786 11456<h3 class="typedef"><a id="cups_array_cb_t">cups_array_cb_t</a></h3>
b47dab17
MS
11457<p class="description">Array comparison function</p>
11458<p class="code">
af268786 11459typedef int(*)(void *first, void *second, void *data)cups_array_cb_t;
b47dab17
MS
11460</p>
11461<h3 class="typedef"><a id="cups_array_t">cups_array_t</a></h3>
11462<p class="description">CUPS array type</p>
11463<p class="code">
11464typedef struct _cups_array_s cups_array_t;
11465</p>
11466<h3 class="typedef"><a id="cups_bool_t">cups_bool_t</a></h3>
11467<p class="description">Boolean type</p>
11468<p class="code">
11469typedef enum <a href="#cups_bool_e">cups_bool_e</a> cups_bool_t;
11470</p>
af268786
MS
11471<h3 class="typedef"><a id="cups_cert_san_cb_t">cups_cert_san_cb_t</a></h3>
11472<p class="description">Certificate signing subjectAltName callback</p>
11473<p class="code">
11474typedef bool(*)(const char *common_name, const char *subject_alt_name, void *user_data)cups_cert_san_cb_t;
b47dab17 11475</p>
af268786
MS
11476<h3 class="typedef"><a id="cups_client_cert_cb_t"><span class="info">&#160;DEPRECATED&#160;</span>cups_client_cert_cb_t</a></h3>
11477<p class="description">Client credentials callback </p>
b47dab17
MS
11478<p class="code">
11479typedef int(*)(http_t *http, void *tls, <a href="#cups_array_t">cups_array_t</a> *distinguished_names, void *user_data)cups_client_cert_cb_t;
11480</p>
af268786
MS
11481<h3 class="typedef"><a id="cups_cond_t">cups_cond_t</a></h3>
11482<p class="description">Condition variable</p>
11483<p class="code">
11484typedef pthread_cond_t cups_cond_t;
11485</p>
11486<h3 class="typedef"><a id="cups_credpurpose_t">cups_credpurpose_t</a></h3>
11487<p class="description">Combined X.509 credential purposes for <a href="#cupsCreateCredentials"><code>cupsCreateCredentials</code></a> and <a href="#cupsCreateCredentialsRequest"><code>cupsCreateCredentialsRequest</code></a></p>
11488<p class="code">
11489typedef unsigned cups_credpurpose_t;
11490</p>
11491<h3 class="typedef"><a id="cups_credtype_t">cups_credtype_t</a></h3>
11492<p class="description">X.509 credential types for <a href="#cupsCreateCredentials"><code>cupsCreateCredentials</code></a> and <a href="#cupsCreateCredentialsRequest"><code>cupsCreateCredentialsRequest</code></a></p>
11493<p class="code">
11494typedef enum <a href="#cups_credtype_e">cups_credtype_e</a> cups_credtype_t;
11495</p>
11496<h3 class="typedef"><a id="cups_credusage_t">cups_credusage_t</a></h3>
11497<p class="description">Combined X.509 keyUsage flags for <a href="#cupsCreateCredentials"><code>cupsCreateCredentials</code></a> and <a href="#cupsCreateCredentialsRequest"><code>cupsCreateCredentialsRequest</code></a></p>
11498<p class="code">
11499typedef unsigned cups_credusage_t;
11500</p>
b47dab17
MS
11501<h3 class="typedef"><a id="cups_cspace_t">cups_cspace_t</a></h3>
11502<p class="description">cupsColorSpace attribute values</p>
11503<p class="code">
11504typedef enum <a href="#cups_cspace_e">cups_cspace_e</a> cups_cspace_t;
798d6e29 11505</p>
b47dab17
MS
11506<h3 class="typedef"><a id="cups_cut_t">cups_cut_t</a></h3>
11507<p class="description">CutMedia attribute values</p>
11508<p class="code">
11509typedef enum <a href="#cups_cut_e">cups_cut_e</a> cups_cut_t;
11510</p>
af268786
MS
11511<h3 class="typedef"><a id="cups_dbcs_t">cups_dbcs_t</a></h3>
11512<p class="description">DBCS Legacy 16-bit unit</p>
11513<p class="code">
11514typedef unsigned short cups_dbcs_t;
11515</p>
b47dab17
MS
11516<h3 class="typedef"><a id="cups_dentry_t">cups_dentry_t</a></h3>
11517<p class="description">Directory entry type</p>
11518<p class="code">
11519typedef struct <a href="#cups_dentry_s">cups_dentry_s</a> cups_dentry_t;
798d6e29 11520</p>
b6008d6b 11521<h3 class="typedef"><a id="cups_dest_cb_t"><span class="info">&#160;CUPS 1.6&#160;</span>cups_dest_cb_t</a></h3>
af268786 11522<p class="description">Destination enumeration callback </p>
b47dab17 11523<p class="code">
798d6e29
MS
11524typedef int(*)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest)cups_dest_cb_t;
11525</p>
af268786
MS
11526<h3 class="typedef"><a id="cups_dest_flags_t">cups_dest_flags_t</a></h3>
11527<p class="description">Combined flags for <a href="#cupsConnectDest"><code>cupsConnectDest</code></a> and <a href="#cupsEnumDests"><code>cupsEnumDests</code></a></p>
11528<p class="code">
11529typedef unsigned cups_dest_flags_t;
11530</p>
b47dab17
MS
11531<h3 class="typedef"><a id="cups_dest_t">cups_dest_t</a></h3>
11532<p class="description">Destination</p>
11533<p class="code">
798d6e29
MS
11534typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t;
11535</p>
b6008d6b 11536<h3 class="typedef"><a id="cups_dinfo_t"><span class="info">&#160;CUPS 1.6&#160;</span>cups_dinfo_t</a></h3>
af268786 11537<p class="description">Destination capability and status information </p>
b47dab17 11538<p class="code">
798d6e29 11539typedef struct _cups_dinfo_s cups_dinfo_t;
798d6e29 11540</p>
b47dab17
MS
11541<h3 class="typedef"><a id="cups_dir_t">cups_dir_t</a></h3>
11542<p class="description">Directory type</p>
11543<p class="code">
11544typedef struct _cups_dir_s cups_dir_t;
11545</p>
af268786
MS
11546<h3 class="typedef"><a id="cups_dnssd_browse_cb_t">cups_dnssd_browse_cb_t</a></h3>
11547<p class="description">DNS-SD browse callback</p>
11548<p class="code">
11549typedef void(*)(cups_dnssd_browse_t *browse, void *cb_data, <a href="#cups_dnssd_flags_t">cups_dnssd_flags_t</a> flags, uint32_t if_index, const char *name, const char *regtype, const char *domain)cups_dnssd_browse_cb_t;
11550</p>
11551<h3 class="typedef"><a id="cups_dnssd_error_cb_t">cups_dnssd_error_cb_t</a></h3>
11552<p class="description">DNS-SD error callback</p>
11553<p class="code">
11554typedef void(*)(void *cb_data, const char *message)cups_dnssd_error_cb_t;
11555</p>
11556<h3 class="typedef"><a id="cups_dnssd_flags_t">cups_dnssd_flags_t</a></h3>
11557<p class="description">DNS-SD callback flag bitmask</p>
11558<p class="code">
11559typedef unsigned cups_dnssd_flags_t;
11560</p>
11561<h3 class="typedef"><a id="cups_dnssd_query_cb_t">cups_dnssd_query_cb_t</a></h3>
11562<p class="description">DNS-SD query callback</p>
11563<p class="code">
11564typedef void(*)(cups_dnssd_query_t *query, void *cb_data, <a href="#cups_dnssd_flags_t">cups_dnssd_flags_t</a> flags, uint32_t if_index, const char *fullname, uint16_t rrtype, const void *qdata, uint16_t qlen) cups_dnssd_query_cb_t;
11565</p>
11566<h3 class="typedef"><a id="cups_dnssd_query_t">cups_dnssd_query_t</a></h3>
11567<p class="description">DNS query request</p>
11568<p class="code">
11569typedef struct _cups_dnssd_query_s cups_dnssd_query_t;
11570</p>
11571<h3 class="typedef"><a id="cups_dnssd_resolve_cb_t">cups_dnssd_resolve_cb_t</a></h3>
11572<p class="description">DNS-SD resolve callback</p>
11573<p class="code">
11574typedef void(*)(cups_dnssd_resolve_t *res, void *cb_data, <a href="#cups_dnssd_flags_t">cups_dnssd_flags_t</a> flags, uint32_t if_index, const char *fullname, const char *host, uint16_t port, int num_txt, <a href="#cups_option_t">cups_option_t</a> *txt)cups_dnssd_resolve_cb_t;
11575</p>
11576<h3 class="typedef"><a id="cups_dnssd_resolve_t">cups_dnssd_resolve_t</a></h3>
11577<p class="description">DNS resolve request</p>
11578<p class="code">
11579typedef struct _cups_dnssd_resolve_s cups_dnssd_resolve_t;
11580</p>
11581<h3 class="typedef"><a id="cups_dnssd_browse_t">cups_dnssd_browse_t</a></h3>
11582<p class="description">DNS record type values</p>
11583<p class="code">
11584typedef typedef struct _cups_dnssd_browse_s cups_dnssd_browse_t;
11585</p>
11586<h3 class="typedef"><a id="cups_dnssd_service_cb_t">cups_dnssd_service_cb_t</a></h3>
11587<p class="description">DNS-SD service registration callback</p>
11588<p class="code">
11589typedef void(*)(cups_dnssd_service_t *service, void *cb_data, <a href="#cups_dnssd_flags_t">cups_dnssd_flags_t</a> flags) cups_dnssd_service_cb_t;
11590</p>
11591<h3 class="typedef"><a id="cups_dnssd_service_t">cups_dnssd_service_t</a></h3>
11592<p class="description">DNS service registration</p>
11593<p class="code">
11594typedef struct _cups_dnssd_service_s cups_dnssd_service_t;
11595</p>
11596<h3 class="typedef"><a id="cups_dnssd_t">cups_dnssd_t</a></h3>
11597<p class="description">DNS-SD context</p>
11598<p class="code">
11599typedef struct _cups_dnssd_s cups_dnssd_t;
11600</p>
b47dab17
MS
11601<h3 class="typedef"><a id="cups_edge_t">cups_edge_t</a></h3>
11602<p class="description">LeadingEdge attribute values</p>
11603<p class="code">
11604typedef enum <a href="#cups_edge_e">cups_edge_e</a> cups_edge_t;
11605</p>
11606<h3 class="typedef"><a id="cups_file_t">cups_file_t</a></h3>
11607<p class="description">CUPS file type</p>
11608<p class="code">
11609typedef struct _cups_file_s cups_file_t;
11610</p>
11611<h3 class="typedef"><a id="cups_job_t">cups_job_t</a></h3>
af268786 11612<p class="description">Job information</p>
b47dab17 11613<p class="code">
798d6e29 11614typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t;
798d6e29 11615</p>
b47dab17
MS
11616<h3 class="typedef"><a id="cups_jog_t">cups_jog_t</a></h3>
11617<p class="description">Jog attribute values</p>
11618<p class="code">
11619typedef enum <a href="#cups_jog_e">cups_jog_e</a> cups_jog_t;
11620</p>
af268786
MS
11621<h3 class="typedef"><a id="cups_json_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_json_t</a></h3>
11622<p class="description">JSON node </p>
11623<p class="code">
11624typedef struct _cups_json_s cups_json_t;
11625</p>
11626<h3 class="typedef"><a id="cups_jtype_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jtype_t</a></h3>
11627<p class="description">JSON node type </p>
11628<p class="code">
11629typedef enum <a href="#cups_jtype_e">cups_jtype_e</a> cups_jtype_t;
11630</p>
11631<h3 class="typedef"><a id="cups_jwa_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jwa_t</a></h3>
11632<p class="description">JSON Web Algorithms </p>
11633<p class="code">
11634typedef enum <a href="#cups_jwa_e">cups_jwa_e</a> cups_jwa_t;
11635</p>
11636<h3 class="typedef"><a id="cups_jws_format_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jws_format_t</a></h3>
11637<p class="description">JSON Web Signature Formats </p>
11638<p class="code">
11639typedef enum <a href="#cups_jws_format_e">cups_jws_format_e</a> cups_jws_format_t;
11640</p>
11641<h3 class="typedef"><a id="cups_jwt_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jwt_t</a></h3>
11642<p class="description">JSON Web Token </p>
11643<p class="code">
11644typedef struct _cups_jwt_s cups_jwt_t;
11645</p>
11646<h3 class="typedef"><a id="cups_lang_t">cups_lang_t</a></h3>
11647<p class="description">Language Cache Structure</p>
11648<p class="code">
11649typedef struct <a href="#cups_lang_s">cups_lang_s</a> cups_lang_t;
11650</p>
11651<h3 class="typedef"><a id="cups_media_flags_t">cups_media_flags_t</a></h3>
11652<p class="description">Combined flags for <a href="#cupsGetDestMediaByName"><code>cupsGetDestMediaByName</code></a> and <a href="#cupsGetDestMediaBySize"><code>cupsGetDestMediaBySize</code></a></p>
11653<p class="code">
11654typedef unsigned cups_media_flags_t;
11655</p>
11656<h3 class="typedef"><a id="cups_media_t"><span class="info">&#160;CUPS 2.5&#160;</span>cups_media_t</a></h3>
11657<p class="description">Media information </p>
b47dab17 11658<p class="code">
af268786
MS
11659typedef struct <a href="#cups_media_s">cups_media_s</a> cups_media_t;
11660</p>
11661<h3 class="typedef"><a id="cups_mutex_t">cups_mutex_t</a></h3>
11662<p class="description">Mutual exclusion lock</p>
11663<p class="code">
11664typedef pthread_mutex_t cups_mutex_t;
11665</p>
11666<h3 class="typedef"><a id="cups_oauth_cb_t"><span class="info">&#160;CUPS 2.4&#160;</span>cups_oauth_cb_t</a></h3>
11667<p class="description">OAuth callback </p>
11668<p class="code">
11669typedef const char *(*)(http_t *http, const char *realm, const char *scope, const char *resource, void *user_data)cups_oauth_cb_t;
b47dab17 11670</p>
0350eba5
MS
11671<h3 class="typedef"><a id="cups_ogrant_t">cups_ogrant_t</a></h3>
11672<p class="description">OAuth Grant Types</p>
11673<p class="code">
11674typedef enum <a href="#cups_ogrant_e">cups_ogrant_e</a> cups_ogrant_t;
11675</p>
b47dab17
MS
11676<h3 class="typedef"><a id="cups_option_t">cups_option_t</a></h3>
11677<p class="description">Printer Options</p>
11678<p class="code">
798d6e29
MS
11679typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t;
11680</p>
b47dab17
MS
11681<h3 class="typedef"><a id="cups_order_t">cups_order_t</a></h3>
11682<p class="description">cupsColorOrder attribute values</p>
11683<p class="code">
11684typedef enum <a href="#cups_order_e">cups_order_e</a> cups_order_t;
11685</p>
11686<h3 class="typedef"><a id="cups_orient_t">cups_orient_t</a></h3>
11687<p class="description">Orientation attribute values</p>
11688<p class="code">
11689typedef enum <a href="#cups_orient_e">cups_orient_e</a> cups_orient_t;
11690</p>
b6008d6b 11691<h3 class="typedef"><a id="cups_page_header2_t"><span class="info">&#160;CUPS 1.2&#160;</span>cups_page_header2_t</a></h3>
b47dab17
MS
11692<p class="description">Version 2 page header </p>
11693<p class="code">
11694typedef struct <a href="#cups_page_header2_s">cups_page_header2_s</a> cups_page_header2_t;
11695</p>
11696<h3 class="typedef"><a id="cups_page_header_t"><span class="info">&#160;DEPRECATED&#160;</span>cups_page_header_t</a></h3>
11697<p class="description">Version 1 page header </p>
11698<p class="code">
11699typedef struct <a href="#cups_page_header_s">cups_page_header_s</a> cups_page_header_t;
11700</p>
b6008d6b 11701<h3 class="typedef"><a id="cups_password_cb2_t"><span class="info">&#160;CUPS 1.4&#160;</span>cups_password_cb2_t</a></h3>
af268786 11702<p class="description">New password callback </p>
b47dab17 11703<p class="code">
798d6e29 11704typedef const char *(*)(const char *prompt, <a href="#http_t">http_t</a> *http, const char *method, const char *resource, void *user_data)cups_password_cb2_t;
798d6e29 11705</p>
b47dab17 11706<h3 class="typedef"><a id="cups_ptype_t">cups_ptype_t</a></h3>
af268786 11707<p class="description">Combined printer type/capability flags</p>
b47dab17 11708<p class="code">
798d6e29
MS
11709typedef unsigned cups_ptype_t;
11710</p>
af268786 11711<h3 class="typedef"><a id="cups_raster_cb_t">cups_raster_cb_t</a></h3>
b47dab17
MS
11712<p class="description">cupsRasterOpenIO callback function</p>
11713<p class="code">
af268786
MS
11714typedef ssize_t(*)(void *ctx, unsigned char *buffer, size_t length) cups_raster_cb_t;
11715</p>
11716<h3 class="typedef"><a id="cups_raster_mode_t">cups_raster_mode_t</a></h3>
11717<p class="description">cupsRasterOpen modes</p>
11718<p class="code">
11719typedef enum <a href="#cups_raster_mode_e">cups_raster_mode_e</a> cups_raster_mode_t;
b47dab17
MS
11720</p>
11721<h3 class="typedef"><a id="cups_raster_t">cups_raster_t</a></h3>
11722<p class="description">Raster stream data</p>
11723<p class="code">
11724typedef struct _cups_raster_s cups_raster_t;
11725</p>
af268786
MS
11726<h3 class="typedef"><a id="cups_rwlock_t">cups_rwlock_t</a></h3>
11727<p class="description">Reader/writer lock</p>
11728<p class="code">
11729typedef pthread_rwlock_t cups_rwlock_t;
11730</p>
11731<h3 class="typedef"><a id="cups_sbcs_t">cups_sbcs_t</a></h3>
11732<p class="description">SBCS Legacy 8-bit unit</p>
11733<p class="code">
11734typedef unsigned char cups_sbcs_t;
798d6e29 11735</p>
af268786
MS
11736<h3 class="typedef"><a id="cups_server_cert_cb_t"><span class="info">&#160;DEPRECATED&#160;</span>cups_server_cert_cb_t</a></h3>
11737<p class="description">Server credentials callback </p>
b47dab17
MS
11738<p class="code">
11739typedef int(*)(http_t *http, void *tls, <a href="#cups_array_t">cups_array_t</a> *certs, void *user_data)cups_server_cert_cb_t;
798d6e29 11740</p>
af268786 11741<h3 class="typedef"><a id="cups_size_t"><span class="info">&#160;DEPRECATED&#160;</span>cups_size_t</a></h3>
b47dab17
MS
11742<p class="description">Media Size </p>
11743<p class="code">
798d6e29 11744typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t;
798d6e29 11745</p>
af268786
MS
11746<h3 class="typedef"><a id="cups_thread_func_t">cups_thread_func_t</a></h3>
11747<p class="description">Thread function</p>
11748<p class="code">
11749typedef void *(*)(void *arg)cups_thread_func_t;
11750</p>
11751<h3 class="typedef"><a id="cups_thread_key_t">cups_thread_key_t</a></h3>
11752<p class="description">Thread data key</p>
11753<p class="code">
11754typedef pthread_key_t cups_thread_key_t;
11755</p>
11756<h3 class="typedef"><a id="cups_thread_t">cups_thread_t</a></h3>
11757<p class="description">Thread identifier</p>
11758<p class="code">
11759typedef pthread_t cups_thread_t;
11760</p>
11761<h3 class="typedef"><a id="cups_ucs2_t">cups_ucs2_t</a></h3>
11762<p class="description">UCS-2 Unicode/ISO-10646 unit</p>
11763<p class="code">
11764typedef unsigned short cups_ucs2_t;
11765</p>
11766<h3 class="typedef"><a id="cups_ucs4_t">cups_ucs4_t</a></h3>
11767<p class="description">UCS-4 Unicode/ISO-10646 unit</p>
11768<p class="code">
11769typedef unsigned long cups_ucs4_t;
11770</p>
11771<h3 class="typedef"><a id="cups_utf32_t">cups_utf32_t</a></h3>
11772<p class="description">UTF-32 Unicode/ISO-10646 unit</p>
11773<p class="code">
11774typedef unsigned long cups_utf32_t;
11775</p>
11776<h3 class="typedef"><a id="cups_utf8_t">cups_utf8_t</a></h3>
11777<p class="description">UTF-8 Unicode/ISO-10646 unit</p>
11778<p class="code">
11779typedef unsigned char cups_utf8_t;
11780</p>
11781<h3 class="typedef"><a id="cups_vbcs_t">cups_vbcs_t</a></h3>
11782<p class="description">VBCS Legacy 32-bit unit</p>
11783<p class="code">
11784typedef unsigned long cups_vbcs_t;
11785</p>
11786<h3 class="typedef"><a id="cups_whichjobs_t">cups_whichjobs_t</a></h3>
11787<p class="description">Which jobs for <a href="#cupsGetJobs"><code>cupsGetJobs</code></a></p>
11788<p class="code">
11789typedef enum <a href="#cups_whichjobs_e">cups_whichjobs_e</a> cups_whichjobs_t;
11790</p>
0350eba5 11791<h3 class="typedef"><a id="http_addr_t"><span class="info">&#160;CUPS 1.2&#160;</span>http_addr_t</a></h3>
af268786 11792<p class="description">Socket address union, which makes using IPv6 and other address types easier and more portable. </p>
b47dab17 11793<p class="code">
af268786 11794typedef union _http_addr_u http_addr_t;
798d6e29 11795</p>
b47dab17
MS
11796<h3 class="typedef"><a id="http_encoding_t">http_encoding_t</a></h3>
11797<p class="description">HTTP transfer encoding values</p>
11798<p class="code">
798d6e29
MS
11799typedef enum <a href="#http_encoding_e">http_encoding_e</a> http_encoding_t;
11800</p>
b47dab17
MS
11801<h3 class="typedef"><a id="http_encryption_t">http_encryption_t</a></h3>
11802<p class="description">HTTP encryption values</p>
11803<p class="code">
798d6e29
MS
11804typedef enum <a href="#http_encryption_e">http_encryption_e</a> http_encryption_t;
11805</p>
b47dab17
MS
11806<h3 class="typedef"><a id="http_field_t">http_field_t</a></h3>
11807<p class="description">HTTP field names</p>
11808<p class="code">
798d6e29
MS
11809typedef enum <a href="#http_field_e">http_field_e</a> http_field_t;
11810</p>
b47dab17
MS
11811<h3 class="typedef"><a id="http_keepalive_t">http_keepalive_t</a></h3>
11812<p class="description">HTTP keep-alive values</p>
11813<p class="code">
798d6e29
MS
11814typedef enum <a href="#http_keepalive_e">http_keepalive_e</a> http_keepalive_t;
11815</p>
af268786
MS
11816<h3 class="typedef"><a id="http_resolve_cb_t"><span class="info">&#160;CUPS 2.5&#160;</span>http_resolve_cb_t</a></h3>
11817<p class="description"><a href="#httpResolveURI"><code>httpResolveURI</code></a> callback </p>
11818<p class="code">
11819typedef bool(*)(void *data)http_resolve_cb_t;
11820</p>
11821<h3 class="typedef"><a id="http_resolve_t">http_resolve_t</a></h3>
11822<p class="description"><a href="#httpResolveURI"><code>httpResolveURI</code></a> options bitfield</p>
11823<p class="code">
11824typedef unsigned http_resolve_t;
11825</p>
b47dab17 11826<h3 class="typedef"><a id="http_state_t">http_state_t</a></h3>
af268786 11827<p class="description">HTTP state values; states are server-oriented...</p>
b47dab17 11828<p class="code">
798d6e29
MS
11829typedef enum <a href="#http_state_e">http_state_e</a> http_state_t;
11830</p>
b47dab17
MS
11831<h3 class="typedef"><a id="http_t">http_t</a></h3>
11832<p class="description">HTTP connection type</p>
11833<p class="code">
798d6e29
MS
11834typedef struct _http_s http_t;
11835</p>
0350eba5 11836<h3 class="typedef"><a id="http_timeout_cb_t"><span class="info">&#160;CUPS 1.5&#160;</span>http_timeout_cb_t</a></h3>
b47dab17
MS
11837<p class="description">HTTP timeout callback </p>
11838<p class="code">
798d6e29
MS
11839typedef int(*)(http_t *http, void *user_data)http_timeout_cb_t;
11840</p>
b47dab17
MS
11841<h3 class="typedef"><a id="http_trust_t"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span>http_trust_t</a></h3>
11842<p class="description">Level of trust for credentials </p>
11843<p class="code">
798d6e29
MS
11844typedef enum <a href="#http_trust_e">http_trust_e</a> http_trust_t;
11845</p>
b47dab17
MS
11846<h3 class="typedef"><a id="http_uri_coding_t">http_uri_coding_t</a></h3>
11847<p class="description">URI en/decode flags</p>
11848<p class="code">
798d6e29
MS
11849typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t;
11850</p>
b47dab17
MS
11851<h3 class="typedef"><a id="http_uri_status_t"><span class="info">&#160;CUPS 1.2&#160;</span>http_uri_status_t</a></h3>
11852<p class="description">URI separation status </p>
11853<p class="code">
798d6e29 11854typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t;
798d6e29 11855</p>
b47dab17
MS
11856<h3 class="typedef"><a id="ipp_attribute_t">ipp_attribute_t</a></h3>
11857<p class="description">IPP attribute</p>
11858<p class="code">
798d6e29
MS
11859typedef struct _ipp_attribute_s ipp_attribute_t;
11860</p>
b6008d6b 11861<h3 class="typedef"><a id="ipp_copy_cb_t"><span class="info">&#160;CUPS 1.6&#160;</span>ipp_copy_cb_t</a></h3>
b47dab17
MS
11862<p class="description">ippCopyAttributes callback function </p>
11863<p class="code">
af268786
MS
11864typedef int(*)(void *context, <a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr)ipp_copy_cb_t;
11865</p>
11866<h3 class="typedef"><a id="ipp_fattr_cb_t">ipp_fattr_cb_t</a></h3>
11867<p class="description">IPP data file attribute callback</p>
11868<p class="code">
11869typedef bool(*)(ipp_file_t *file, void *cb_data, const char *name)ipp_fattr_cb_t;
11870</p>
11871<h3 class="typedef"><a id="ipp_ferror_cb_t">ipp_ferror_cb_t</a></h3>
11872<p class="description">IPP data file error callback</p>
11873<p class="code">
11874typedef bool(*)(ipp_file_t *file, void *cb_data, const char *error)ipp_ferror_cb_t;
11875</p>
11876<h3 class="typedef"><a id="ipp_file_t">ipp_file_t</a></h3>
11877<p class="description">IPP data file</p>
11878<p class="code">
11879typedef struct _ipp_file_s ipp_file_t;
11880</p>
11881<h3 class="typedef"><a id="ipp_ftoken_cb_t">ipp_ftoken_cb_t</a></h3>
11882<p class="description">IPP data file token callback</p>
11883<p class="code">
11884typedef bool(*)(ipp_file_t *file, void *cb_data, const char *token)ipp_ftoken_cb_t;
798d6e29 11885</p>
b6008d6b 11886<h3 class="typedef"><a id="ipp_io_cb_t"><span class="info">&#160;CUPS 1.2&#160;</span>ipp_io_cb_t</a></h3>
b47dab17
MS
11887<p class="description">ippReadIO/ippWriteIO callback function </p>
11888<p class="code">
af268786
MS
11889typedef ssize_t(*)(void *context, ipp_uchar_t *buffer, size_t bytes) ipp_io_cb_t;
11890</p>
11891<h3 class="typedef"><a id="ipp_jstate_t">ipp_jstate_t</a></h3>
11892<p class="description">Job states</p>
11893<p class="code">
11894typedef enum <a href="#ipp_jstate_e">ipp_jstate_e</a> ipp_jstate_t;
11895</p>
11896<h3 class="typedef"><a id="ipp_op_t">ipp_op_t</a></h3>
11897<p class="description">IPP operations</p>
11898<p class="code">
11899typedef enum <a href="#ipp_op_e">ipp_op_e</a> ipp_op_t;
798d6e29 11900</p>
b47dab17
MS
11901<h3 class="typedef"><a id="ipp_orient_t">ipp_orient_t</a></h3>
11902<p class="description">Orientation values</p>
11903<p class="code">
798d6e29
MS
11904typedef enum <a href="#ipp_orient_e">ipp_orient_e</a> ipp_orient_t;
11905</p>
b47dab17
MS
11906<h3 class="typedef"><a id="ipp_pstate_t">ipp_pstate_t</a></h3>
11907<p class="description">Printer state values</p>
11908<p class="code">
798d6e29
MS
11909typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t;
11910</p>
b47dab17
MS
11911<h3 class="typedef"><a id="ipp_quality_t">ipp_quality_t</a></h3>
11912<p class="description">Print quality values</p>
11913<p class="code">
798d6e29
MS
11914typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t;
11915</p>
b47dab17
MS
11916<h3 class="typedef"><a id="ipp_res_t">ipp_res_t</a></h3>
11917<p class="description">Resolution units</p>
11918<p class="code">
798d6e29 11919typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t;
06a5a4d3 11920</p>
b47dab17
MS
11921<h3 class="typedef"><a id="ipp_rstate_t">ipp_rstate_t</a></h3>
11922<p class="description">resource-state values</p>
11923<p class="code">
06a5a4d3
MS
11924typedef enum <a href="#ipp_rstate_e">ipp_rstate_e</a> ipp_rstate_t;
11925</p>
b47dab17
MS
11926<h3 class="typedef"><a id="ipp_sstate_t">ipp_sstate_t</a></h3>
11927<p class="description">system-state values</p>
11928<p class="code">
06a5a4d3 11929typedef enum <a href="#ipp_sstate_e">ipp_sstate_e</a> ipp_sstate_t;
798d6e29 11930</p>
b47dab17
MS
11931<h3 class="typedef"><a id="ipp_state_t">ipp_state_t</a></h3>
11932<p class="description">ipp_t state values</p>
11933<p class="code">
798d6e29
MS
11934typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t;
11935</p>
b47dab17
MS
11936<h3 class="typedef"><a id="ipp_t">ipp_t</a></h3>
11937<p class="description">IPP request/response data</p>
11938<p class="code">
798d6e29 11939typedef struct _ipp_s ipp_t;
798d6e29 11940</p>
b47dab17
MS
11941<h3 class="typedef"><a id="pwg_media_t">pwg_media_t</a></h3>
11942<p class="description">Common media size data</p>
11943<p class="code">
11944typedef struct <a href="#pwg_media_s">pwg_media_s</a> pwg_media_t;
11945</p>
11946<h2 class="title"><a id="STRUCTURES">Structures</a></h2>
11947<h3 class="struct"><a id="cups_dentry_s">cups_dentry_s</a></h3>
11948<p class="description">Directory entry type</p>
0350eba5
MS
11949<p class="code"><span class="reserved">struct</span> cups_dentry_s {<br>
11950&#160;&#160;&#160;&#160;<span class="reserved">struct</span> stat fileinfo;<br>
11951&#160;&#160;&#160;&#160;<span class="reserved">char</span> filename[260];<br>
b47dab17
MS
11952};</p>
11953<h4 class="members">Members</h4>
11954<table class="list"><tbody>
11955<tr><th>fileinfo </th>
11956<td class="description">File information</td></tr>
11957<tr><th>filename[260] </th>
11958<td class="description">File name</td></tr>
11959</tbody></table>
798d6e29 11960<h3 class="struct"><a id="cups_dest_s">cups_dest_s</a></h3>
b47dab17 11961<p class="description">Destination</p>
0350eba5
MS
11962<p class="code"><span class="reserved">struct</span> cups_dest_s {<br>
11963&#160;&#160;&#160;&#160;<span class="reserved">char</span> *name, *instance;<br>
11964&#160;&#160;&#160;&#160;<span class="reserved">int</span> is_default;<br>
11965&#160;&#160;&#160;&#160;<span class="reserved">int</span> num_options;<br>
798d6e29
MS
11966&#160;&#160;&#160;&#160;<a href="#cups_option_t">cups_option_t</a> *options;<br>
11967};</p>
11968<h4 class="members">Members</h4>
98d88c8d
MS
11969<table class="list"><tbody>
11970<tr><th>instance </th>
af268786 11971<td class="description">Local instance name or <code>NULL</code></td></tr>
98d88c8d 11972<tr><th>is_default </th>
b47dab17 11973<td class="description">Is this printer the default?</td></tr>
98d88c8d 11974<tr><th>num_options </th>
b47dab17 11975<td class="description">Number of options</td></tr>
98d88c8d 11976<tr><th>options </th>
b47dab17 11977<td class="description">Options</td></tr>
98d88c8d 11978</tbody></table>
798d6e29 11979<h3 class="struct"><a id="cups_job_s">cups_job_s</a></h3>
af268786 11980<p class="description">Job information</p>
0350eba5 11981<p class="code"><span class="reserved">struct</span> cups_job_s {<br>
798d6e29
MS
11982&#160;&#160;&#160;&#160;time_t completed_time;<br>
11983&#160;&#160;&#160;&#160;time_t creation_time;<br>
0350eba5
MS
11984&#160;&#160;&#160;&#160;<span class="reserved">char</span> *dest;<br>
11985&#160;&#160;&#160;&#160;<span class="reserved">char</span> *format;<br>
11986&#160;&#160;&#160;&#160;<span class="reserved">int</span> id;<br>
11987&#160;&#160;&#160;&#160;<span class="reserved">int</span> priority;<br>
798d6e29 11988&#160;&#160;&#160;&#160;time_t processing_time;<br>
0350eba5 11989&#160;&#160;&#160;&#160;<span class="reserved">int</span> size;<br>
af268786 11990&#160;&#160;&#160;&#160;<a href="#ipp_jstate_t">ipp_jstate_t</a> state;<br>
0350eba5
MS
11991&#160;&#160;&#160;&#160;<span class="reserved">char</span> *title;<br>
11992&#160;&#160;&#160;&#160;<span class="reserved">char</span> *user;<br>
798d6e29
MS
11993};</p>
11994<h4 class="members">Members</h4>
98d88c8d
MS
11995<table class="list"><tbody>
11996<tr><th>completed_time </th>
b47dab17 11997<td class="description">Time the job was completed</td></tr>
98d88c8d 11998<tr><th>creation_time </th>
b47dab17 11999<td class="description">Time the job was created</td></tr>
98d88c8d 12000<tr><th>dest </th>
b47dab17 12001<td class="description">Printer or class name</td></tr>
98d88c8d 12002<tr><th>format </th>
b47dab17 12003<td class="description">Document format</td></tr>
98d88c8d 12004<tr><th>id </th>
b47dab17 12005<td class="description">The job ID</td></tr>
98d88c8d 12006<tr><th>priority </th>
b47dab17 12007<td class="description">Priority (1-100)</td></tr>
98d88c8d 12008<tr><th>processing_time </th>
b47dab17 12009<td class="description">Time the job was processed</td></tr>
98d88c8d 12010<tr><th>size </th>
b47dab17 12011<td class="description">Size in kilobytes</td></tr>
98d88c8d 12012<tr><th>state </th>
b47dab17 12013<td class="description">Job state</td></tr>
98d88c8d 12014<tr><th>title </th>
b47dab17 12015<td class="description">Title/job name</td></tr>
98d88c8d 12016<tr><th>user </th>
b47dab17 12017<td class="description">User that submitted the job</td></tr>
98d88c8d 12018</tbody></table>
af268786
MS
12019<h3 class="struct"><a id="cups_lang_s">cups_lang_s</a></h3>
12020<p class="description">Language Cache Structure</p>
0350eba5 12021<p class="code"><span class="reserved">struct</span> cups_lang_s {<br>
af268786 12022&#160;&#160;&#160;&#160;<a href="#cups_encoding_t">cups_encoding_t</a> encoding;<br>
0350eba5
MS
12023&#160;&#160;&#160;&#160;<span class="reserved">char</span> language[16];<br>
12024&#160;&#160;&#160;&#160;<span class="reserved">struct</span> <a href="#cups_lang_s">cups_lang_s</a> *next;<br>
12025&#160;&#160;&#160;&#160;<span class="reserved">int</span> used;<br>
af268786
MS
12026};</p>
12027<h4 class="members">Members</h4>
12028<table class="list"><tbody>
12029<tr><th>encoding </th>
12030<td class="description">Text encoding</td></tr>
12031<tr><th>language[16] </th>
12032<td class="description">Language/locale name</td></tr>
12033<tr><th>next </th>
12034<td class="description">Next language in cache</td></tr>
12035<tr><th>used </th>
12036<td class="description">Number of times this entry has been used.</td></tr>
12037</tbody></table>
12038<h3 class="struct"><span class="info">&#160;CUPS 2.5&#160;</span><a id="cups_media_s">cups_media_s</a></h3>
12039<p class="description">Media information </p>
0350eba5
MS
12040<p class="code"><span class="reserved">struct</span> cups_media_s {<br>
12041&#160;&#160;&#160;&#160;<span class="reserved">int</span> width, length, bottom, left, right, top;<br>
12042&#160;&#160;&#160;&#160;<span class="reserved">char</span> media[128], color[128], source[128], type[128];<br>
af268786
MS
12043};</p>
12044<h4 class="members">Members</h4>
12045<table class="list"><tbody>
12046<tr><th>top </th>
12047<td class="description">Top margin in hundredths of millimeters</td></tr>
12048<tr><th>type[128] </th>
12049<td class="description">Media type (blank for any/auto)</td></tr>
12050</tbody></table>
798d6e29 12051<h3 class="struct"><a id="cups_option_s">cups_option_s</a></h3>
b47dab17 12052<p class="description">Printer Options</p>
0350eba5
MS
12053<p class="code"><span class="reserved">struct</span> cups_option_s {<br>
12054&#160;&#160;&#160;&#160;<span class="reserved">char</span> *name;<br>
12055&#160;&#160;&#160;&#160;<span class="reserved">char</span> *value;<br>
798d6e29
MS
12056};</p>
12057<h4 class="members">Members</h4>
98d88c8d
MS
12058<table class="list"><tbody>
12059<tr><th>name </th>
b47dab17 12060<td class="description">Name of option</td></tr>
98d88c8d 12061<tr><th>value </th>
b47dab17
MS
12062<td class="description">Value of option</td></tr>
12063</tbody></table>
b6008d6b 12064<h3 class="struct"><span class="info">&#160;CUPS 1.2&#160;</span><a id="cups_page_header2_s">cups_page_header2_s</a></h3>
b47dab17 12065<p class="description">Version 2 page header </p>
0350eba5
MS
12066<p class="code"><span class="reserved">struct</span> cups_page_header2_s {<br>
12067&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> AdvanceDistance;<br>
b47dab17
MS
12068&#160;&#160;&#160;&#160;<a href="#cups_adv_t">cups_adv_t</a> AdvanceMedia;<br>
12069&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Collate;<br>
12070&#160;&#160;&#160;&#160;<a href="#cups_cut_t">cups_cut_t</a> CutMedia;<br>
12071&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Duplex;<br>
0350eba5
MS
12072&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> HWResolution[2];<br>
12073&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> ImagingBoundingBox[4];<br>
b47dab17
MS
12074&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> InsertSheet;<br>
12075&#160;&#160;&#160;&#160;<a href="#cups_jog_t">cups_jog_t</a> Jog;<br>
12076&#160;&#160;&#160;&#160;<a href="#cups_edge_t">cups_edge_t</a> LeadingEdge;<br>
12077&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> ManualFeed;<br>
0350eba5
MS
12078&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> Margins[2];<br>
12079&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaClass[64];<br>
12080&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaColor[64];<br>
12081&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> MediaPosition;<br>
12082&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaType[64];<br>
12083&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> MediaWeight;<br>
b47dab17
MS
12084&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> MirrorPrint;<br>
12085&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> NegativePrint;<br>
0350eba5 12086&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> NumCopies;<br>
b47dab17
MS
12087&#160;&#160;&#160;&#160;<a href="#cups_orient_t">cups_orient_t</a> Orientation;<br>
12088&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> OutputFaceUp;<br>
0350eba5
MS
12089&#160;&#160;&#160;&#160;<span class="reserved">char</span> OutputType[64];<br>
12090&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> PageSize[2];<br>
b47dab17
MS
12091&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Separations;<br>
12092&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> TraySwitch;<br>
12093&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Tumble;<br>
0350eba5
MS
12094&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBitsPerColor;<br>
12095&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBitsPerPixel;<br>
12096&#160;&#160;&#160;&#160;<span class="reserved">float</span> cupsBorderlessScalingFactor;<br>
12097&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBytesPerLine;<br>
b47dab17
MS
12098&#160;&#160;&#160;&#160;<a href="#cups_order_t">cups_order_t</a> cupsColorOrder;<br>
12099&#160;&#160;&#160;&#160;<a href="#cups_cspace_t">cups_cspace_t</a> cupsColorSpace;<br>
0350eba5
MS
12100&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsCompression;<br>
12101&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsHeight;<br>
12102&#160;&#160;&#160;&#160;<span class="reserved">float</span> cupsImagingBBox[4];<br>
12103&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsInteger[16];<br>
12104&#160;&#160;&#160;&#160;<span class="reserved">char</span> cupsMarkerType[64];<br>
12105&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsMediaType;<br>
12106&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsNumColors;<br>
12107&#160;&#160;&#160;&#160;<span class="reserved">char</span> cupsPageSizeName[64];<br>
12108&#160;&#160;&#160;&#160;<span class="reserved">float</span> cupsPageSize[2];<br>
12109&#160;&#160;&#160;&#160;<span class="reserved">float</span> cupsReal[16];<br>
12110&#160;&#160;&#160;&#160;<span class="reserved">char</span> cupsRenderingIntent[64];<br>
12111&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowCount;<br>
12112&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowFeed;<br>
12113&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowStep;<br>
12114&#160;&#160;&#160;&#160;<span class="reserved">char</span> cupsString[16][64];<br>
12115&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsWidth;<br>
b47dab17
MS
12116};</p>
12117<h4 class="members">Members</h4>
12118<table class="list"><tbody>
12119<tr><th>AdvanceDistance </th>
12120<td class="description">AdvanceDistance value in points</td></tr>
12121<tr><th>AdvanceMedia </th>
12122<td class="description">AdvanceMedia value (<a href="#cups_adv_t"><code>cups_adv_t</code></a>)</td></tr>
12123<tr><th>Collate </th>
12124<td class="description">Collated copies value</td></tr>
12125<tr><th>CutMedia </th>
12126<td class="description">CutMedia value (<a href="#cups_cut_t"><code>cups_cut_t</code></a>)</td></tr>
12127<tr><th>Duplex </th>
12128<td class="description">Duplexed (double-sided) value</td></tr>
12129<tr><th>HWResolution[2] </th>
12130<td class="description">Resolution in dots-per-inch</td></tr>
12131<tr><th>ImagingBoundingBox[4] </th>
12132<td class="description">Pixel region that is painted (points, left, bottom, right, top)</td></tr>
12133<tr><th>InsertSheet </th>
12134<td class="description">InsertSheet value</td></tr>
12135<tr><th>Jog </th>
12136<td class="description">Jog value (<a href="#cups_jog_t"><code>cups_jog_t</code></a>)</td></tr>
12137<tr><th>LeadingEdge </th>
12138<td class="description">LeadingEdge value (<a href="#cups_edge_t"><code>cups_edge_t</code></a>)</td></tr>
12139<tr><th>ManualFeed </th>
12140<td class="description">ManualFeed value</td></tr>
12141<tr><th>Margins[2] </th>
12142<td class="description">Lower-lefthand margins in points</td></tr>
12143<tr><th>MediaClass[64] </th>
12144<td class="description">MediaClass string</td></tr>
12145<tr><th>MediaColor[64] </th>
12146<td class="description">MediaColor string</td></tr>
12147<tr><th>MediaPosition </th>
12148<td class="description">MediaPosition value</td></tr>
12149<tr><th>MediaType[64] </th>
12150<td class="description">MediaType string</td></tr>
12151<tr><th>MediaWeight </th>
12152<td class="description">MediaWeight value in grams/m^2</td></tr>
12153<tr><th>MirrorPrint </th>
12154<td class="description">MirrorPrint value</td></tr>
12155<tr><th>NegativePrint </th>
12156<td class="description">NegativePrint value</td></tr>
12157<tr><th>NumCopies </th>
12158<td class="description">Number of copies to produce</td></tr>
12159<tr><th>Orientation </th>
12160<td class="description">Orientation value (<a href="#cups_orient_t"><code>cups_orient_t</code></a>)</td></tr>
12161<tr><th>OutputFaceUp </th>
12162<td class="description">OutputFaceUp value</td></tr>
12163<tr><th>OutputType[64] </th>
12164<td class="description">OutputType string</td></tr>
12165<tr><th>PageSize[2] </th>
12166<td class="description">Width and length of page in points</td></tr>
12167<tr><th>Separations </th>
12168<td class="description">Separations value</td></tr>
12169<tr><th>TraySwitch </th>
12170<td class="description">TraySwitch value</td></tr>
12171<tr><th>Tumble </th>
12172<td class="description">Tumble value</td></tr>
12173<tr><th>cupsBitsPerColor </th>
12174<td class="description">Number of bits for each color</td></tr>
12175<tr><th>cupsBitsPerPixel </th>
12176<td class="description">Number of bits for each pixel</td></tr>
b6008d6b 12177<tr><th>cupsBorderlessScalingFactor <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12178<td class="description">Scaling that was applied to page data </td></tr>
12179<tr><th>cupsBytesPerLine </th>
12180<td class="description">Number of bytes per line</td></tr>
12181<tr><th>cupsColorOrder </th>
12182<td class="description">Order of colors</td></tr>
12183<tr><th>cupsColorSpace </th>
12184<td class="description">True colorspace</td></tr>
12185<tr><th>cupsCompression </th>
12186<td class="description">Device compression to use</td></tr>
12187<tr><th>cupsHeight </th>
12188<td class="description">Height of page image in pixels</td></tr>
b6008d6b 12189<tr><th>cupsImagingBBox[4] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12190<td class="description">Floating point ImagingBoundingBox
12191(scaling factor not applied, left,
12192bottom, right, top) </td></tr>
b6008d6b 12193<tr><th>cupsInteger[16] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17 12194<td class="description">User-defined integer values </td></tr>
b6008d6b 12195<tr><th>cupsMarkerType[64] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12196<td class="description">Ink/toner type </td></tr>
12197<tr><th>cupsMediaType </th>
12198<td class="description">Media type code</td></tr>
b6008d6b 12199<tr><th>cupsNumColors <span class="info">&#160;CUPS 1.2&#160;</span></th>
d6b36f7f 12200<td class="description">Number of color components </td></tr>
b6008d6b 12201<tr><th>cupsPageSizeName[64] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17 12202<td class="description">PageSize name </td></tr>
b6008d6b 12203<tr><th>cupsPageSize[2] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12204<td class="description">Floating point PageSize (scaling *
12205factor not applied) </td></tr>
b6008d6b 12206<tr><th>cupsReal[16] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17 12207<td class="description">User-defined floating-point values </td></tr>
b6008d6b 12208<tr><th>cupsRenderingIntent[64] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12209<td class="description">Color rendering intent </td></tr>
12210<tr><th>cupsRowCount </th>
12211<td class="description">Rows per band</td></tr>
12212<tr><th>cupsRowFeed </th>
12213<td class="description">Feed between bands</td></tr>
12214<tr><th>cupsRowStep </th>
12215<td class="description">Spacing between lines</td></tr>
b6008d6b 12216<tr><th>cupsString[16][64] <span class="info">&#160;CUPS 1.2&#160;</span></th>
b47dab17
MS
12217<td class="description">User-defined string values </td></tr>
12218<tr><th>cupsWidth </th>
12219<td class="description">Width of page image in pixels</td></tr>
12220</tbody></table>
12221<h3 class="struct"><span class="info">&#160;DEPRECATED&#160;</span><a id="cups_page_header_s">cups_page_header_s</a></h3>
12222<p class="description">Version 1 page header </p>
0350eba5
MS
12223<p class="code"><span class="reserved">struct</span> cups_page_header_s {<br>
12224&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> AdvanceDistance;<br>
b47dab17
MS
12225&#160;&#160;&#160;&#160;<a href="#cups_adv_t">cups_adv_t</a> AdvanceMedia;<br>
12226&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Collate;<br>
12227&#160;&#160;&#160;&#160;<a href="#cups_cut_t">cups_cut_t</a> CutMedia;<br>
12228&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Duplex;<br>
0350eba5
MS
12229&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> HWResolution[2];<br>
12230&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> ImagingBoundingBox[4];<br>
b47dab17
MS
12231&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> InsertSheet;<br>
12232&#160;&#160;&#160;&#160;<a href="#cups_jog_t">cups_jog_t</a> Jog;<br>
12233&#160;&#160;&#160;&#160;<a href="#cups_edge_t">cups_edge_t</a> LeadingEdge;<br>
12234&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> ManualFeed;<br>
0350eba5
MS
12235&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> Margins[2];<br>
12236&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaClass[64];<br>
12237&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaColor[64];<br>
12238&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> MediaPosition;<br>
12239&#160;&#160;&#160;&#160;<span class="reserved">char</span> MediaType[64];<br>
12240&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> MediaWeight;<br>
b47dab17
MS
12241&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> MirrorPrint;<br>
12242&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> NegativePrint;<br>
0350eba5 12243&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> NumCopies;<br>
b47dab17
MS
12244&#160;&#160;&#160;&#160;<a href="#cups_orient_t">cups_orient_t</a> Orientation;<br>
12245&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> OutputFaceUp;<br>
0350eba5
MS
12246&#160;&#160;&#160;&#160;<span class="reserved">char</span> OutputType[64];<br>
12247&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> PageSize[2];<br>
b47dab17
MS
12248&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Separations;<br>
12249&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> TraySwitch;<br>
12250&#160;&#160;&#160;&#160;<a href="#cups_bool_t">cups_bool_t</a> Tumble;<br>
0350eba5
MS
12251&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBitsPerColor;<br>
12252&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBitsPerPixel;<br>
12253&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsBytesPerLine;<br>
b47dab17
MS
12254&#160;&#160;&#160;&#160;<a href="#cups_order_t">cups_order_t</a> cupsColorOrder;<br>
12255&#160;&#160;&#160;&#160;<a href="#cups_cspace_t">cups_cspace_t</a> cupsColorSpace;<br>
0350eba5
MS
12256&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsCompression;<br>
12257&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsHeight;<br>
12258&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsMediaType;<br>
12259&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowCount;<br>
12260&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowFeed;<br>
12261&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsRowStep;<br>
12262&#160;&#160;&#160;&#160;<span class="reserved">unsigned</span> cupsWidth;<br>
b47dab17
MS
12263};</p>
12264<h4 class="members">Members</h4>
12265<table class="list"><tbody>
12266<tr><th>AdvanceDistance </th>
12267<td class="description">AdvanceDistance value in points</td></tr>
12268<tr><th>AdvanceMedia </th>
12269<td class="description">AdvanceMedia value (<a href="#cups_adv_t"><code>cups_adv_t</code></a>)</td></tr>
12270<tr><th>Collate </th>
12271<td class="description">Collated copies value</td></tr>
12272<tr><th>CutMedia </th>
12273<td class="description">CutMedia value (<a href="#cups_cut_t"><code>cups_cut_t</code></a>)</td></tr>
12274<tr><th>Duplex </th>
12275<td class="description">Duplexed (double-sided) value</td></tr>
12276<tr><th>HWResolution[2] </th>
12277<td class="description">Resolution in dots-per-inch</td></tr>
12278<tr><th>ImagingBoundingBox[4] </th>
12279<td class="description">Pixel region that is painted (points, left, bottom, right, top)</td></tr>
12280<tr><th>InsertSheet </th>
12281<td class="description">InsertSheet value</td></tr>
12282<tr><th>Jog </th>
12283<td class="description">Jog value (<a href="#cups_jog_t"><code>cups_jog_t</code></a>)</td></tr>
12284<tr><th>LeadingEdge </th>
12285<td class="description">LeadingEdge value (<a href="#cups_edge_t"><code>cups_edge_t</code></a>)</td></tr>
12286<tr><th>ManualFeed </th>
12287<td class="description">ManualFeed value</td></tr>
12288<tr><th>Margins[2] </th>
12289<td class="description">Lower-lefthand margins in points</td></tr>
12290<tr><th>MediaClass[64] </th>
12291<td class="description">MediaClass string</td></tr>
12292<tr><th>MediaColor[64] </th>
12293<td class="description">MediaColor string</td></tr>
12294<tr><th>MediaPosition </th>
12295<td class="description">MediaPosition value</td></tr>
12296<tr><th>MediaType[64] </th>
12297<td class="description">MediaType string</td></tr>
12298<tr><th>MediaWeight </th>
12299<td class="description">MediaWeight value in grams/m^2</td></tr>
12300<tr><th>MirrorPrint </th>
12301<td class="description">MirrorPrint value</td></tr>
12302<tr><th>NegativePrint </th>
12303<td class="description">NegativePrint value</td></tr>
12304<tr><th>NumCopies </th>
12305<td class="description">Number of copies to produce</td></tr>
12306<tr><th>Orientation </th>
12307<td class="description">Orientation value (<a href="#cups_orient_t"><code>cups_orient_t</code></a>)</td></tr>
12308<tr><th>OutputFaceUp </th>
12309<td class="description">OutputFaceUp value</td></tr>
12310<tr><th>OutputType[64] </th>
12311<td class="description">OutputType string</td></tr>
12312<tr><th>PageSize[2] </th>
12313<td class="description">Width and length of page in points</td></tr>
12314<tr><th>Separations </th>
12315<td class="description">Separations value</td></tr>
12316<tr><th>TraySwitch </th>
12317<td class="description">TraySwitch value</td></tr>
12318<tr><th>Tumble </th>
12319<td class="description">Tumble value</td></tr>
12320<tr><th>cupsBitsPerColor </th>
12321<td class="description">Number of bits for each color</td></tr>
12322<tr><th>cupsBitsPerPixel </th>
12323<td class="description">Number of bits for each pixel</td></tr>
12324<tr><th>cupsBytesPerLine </th>
12325<td class="description">Number of bytes per line</td></tr>
12326<tr><th>cupsColorOrder </th>
12327<td class="description">Order of colors</td></tr>
12328<tr><th>cupsColorSpace </th>
12329<td class="description">True colorspace</td></tr>
12330<tr><th>cupsCompression </th>
12331<td class="description">Device compression to use</td></tr>
12332<tr><th>cupsHeight </th>
12333<td class="description">Height of page image in pixels</td></tr>
12334<tr><th>cupsMediaType </th>
12335<td class="description">Media type code</td></tr>
12336<tr><th>cupsRowCount </th>
12337<td class="description">Rows per band</td></tr>
12338<tr><th>cupsRowFeed </th>
12339<td class="description">Feed between bands</td></tr>
12340<tr><th>cupsRowStep </th>
12341<td class="description">Spacing between lines</td></tr>
12342<tr><th>cupsWidth </th>
12343<td class="description">Width of page image in pixels</td></tr>
98d88c8d 12344</tbody></table>
af268786 12345<h3 class="struct"><span class="info">&#160;DEPRECATED&#160;</span><a id="cups_size_s">cups_size_s</a></h3>
b47dab17 12346<p class="description">Media Size </p>
0350eba5
MS
12347<p class="code"><span class="reserved">struct</span> cups_size_s {<br>
12348&#160;&#160;&#160;&#160;<span class="reserved">char</span> media[128];<br>
12349&#160;&#160;&#160;&#160;<span class="reserved">int</span> width, length, bottom, left, right, top;<br>
798d6e29
MS
12350};</p>
12351<h4 class="members">Members</h4>
98d88c8d
MS
12352<table class="list"><tbody>
12353<tr><th>media[128] </th>
b47dab17 12354<td class="description">Media name to use</td></tr>
98d88c8d 12355<tr><th>top </th>
af268786 12356<td class="description">Top margin in hundredths of millimeters</td></tr>
98d88c8d 12357</tbody></table>
b47dab17
MS
12358<h3 class="struct"><a id="pwg_media_s">pwg_media_s</a></h3>
12359<p class="description">Common media size data</p>
0350eba5
MS
12360<p class="code"><span class="reserved">struct</span> pwg_media_s {<br>
12361&#160;&#160;&#160;&#160;<span class="reserved">int</span> width, length;<br>
12362&#160;&#160;&#160;&#160;<span class="reserved">const</span> <span class="reserved">char</span> *pwg, *legacy, *ppd;<br>
b47dab17
MS
12363};</p>
12364<h4 class="members">Members</h4>
12365<table class="list"><tbody>
12366<tr><th>length </th>
12367<td class="description">Length in 2540ths</td></tr>
12368<tr><th>ppd </th>
12369<td class="description">Standard Adobe PPD name</td></tr>
12370</tbody></table>
12371<h2 class="title"><a id="ENUMERATIONS">Constants</a></h2>
12372<h3 class="enumeration"><a id="cups_adv_e">cups_adv_e</a></h3>
12373<p class="description">AdvanceMedia attribute values</p>
12374<h4 class="constants">Constants</h4>
12375<table class="list"><tbody>
12376<tr><th>CUPS_ADVANCE_FILE </th><td class="description">Advance the roll after this file</td></tr>
12377<tr><th>CUPS_ADVANCE_JOB </th><td class="description">Advance the roll after this job</td></tr>
12378<tr><th>CUPS_ADVANCE_NONE </th><td class="description">Never advance the roll</td></tr>
12379<tr><th>CUPS_ADVANCE_PAGE </th><td class="description">Advance the roll after this page</td></tr>
12380<tr><th>CUPS_ADVANCE_SET </th><td class="description">Advance the roll after this set</td></tr>
12381</tbody></table>
12382<h3 class="enumeration"><a id="cups_bool_e">cups_bool_e</a></h3>
12383<p class="description">Boolean type</p>
12384<h4 class="constants">Constants</h4>
12385<table class="list"><tbody>
12386<tr><th>CUPS_FALSE </th><td class="description">Logical false</td></tr>
12387<tr><th>CUPS_TRUE </th><td class="description">Logical true</td></tr>
12388</tbody></table>
af268786
MS
12389<h3 class="enumeration"><a id="cups_credpurpose_e">cups_credpurpose_e</a></h3>
12390<p class="description">X.509 credential purposes</p>
12391<h4 class="constants">Constants</h4>
12392<table class="list"><tbody>
12393<tr><th>CUPS_CREDPURPOSE_ALL </th><td class="description">All purposes</td></tr>
12394<tr><th>CUPS_CREDPURPOSE_CLIENT_AUTH </th><td class="description">clientAuth</td></tr>
12395<tr><th>CUPS_CREDPURPOSE_CODE_SIGNING </th><td class="description">codeSigning</td></tr>
12396<tr><th>CUPS_CREDPURPOSE_EMAIL_PROTECTION </th><td class="description">emailProtection</td></tr>
12397<tr><th>CUPS_CREDPURPOSE_OCSP_SIGNING </th><td class="description">OCSPSigning</td></tr>
12398<tr><th>CUPS_CREDPURPOSE_SERVER_AUTH </th><td class="description">serverAuth</td></tr>
12399<tr><th>CUPS_CREDPURPOSE_TIME_STAMPING </th><td class="description">timeStamping</td></tr>
12400</tbody></table>
12401<h3 class="enumeration"><a id="cups_credtype_e">cups_credtype_e</a></h3>
12402<p class="description">X.509 credential types for <a href="#cupsCreateCredentials"><code>cupsCreateCredentials</code></a> and <a href="#cupsCreateCredentialsRequest"><code>cupsCreateCredentialsRequest</code></a></p>
12403<h4 class="constants">Constants</h4>
12404<table class="list"><tbody>
12405<tr><th>CUPS_CREDTYPE_DEFAULT </th><td class="description">Default type</td></tr>
12406<tr><th>CUPS_CREDTYPE_ECDSA_P256_SHA256 </th><td class="description">ECDSA using the P-256 curve with SHA-256 hash</td></tr>
12407<tr><th>CUPS_CREDTYPE_ECDSA_P384_SHA256 </th><td class="description">ECDSA using the P-384 curve with SHA-256 hash</td></tr>
12408<tr><th>CUPS_CREDTYPE_ECDSA_P521_SHA256 </th><td class="description">ECDSA using the P-521 curve with SHA-256 hash</td></tr>
12409<tr><th>CUPS_CREDTYPE_RSA_2048_SHA256 </th><td class="description">RSA with 2048-bit keys and SHA-256 hash</td></tr>
12410<tr><th>CUPS_CREDTYPE_RSA_3072_SHA256 </th><td class="description">RSA with 3072-bit keys and SHA-256 hash</td></tr>
12411<tr><th>CUPS_CREDTYPE_RSA_4096_SHA256 </th><td class="description">RSA with 4096-bit keys and SHA-256 hash</td></tr>
12412</tbody></table>
12413<h3 class="enumeration"><a id="cups_credusage_e">cups_credusage_e</a></h3>
12414<p class="description">X.509 keyUsage flags</p>
12415<h4 class="constants">Constants</h4>
12416<table class="list"><tbody>
12417<tr><th>CUPS_CREDUSAGE_ALL </th><td class="description">All keyUsage flags</td></tr>
12418<tr><th>CUPS_CREDUSAGE_CRL_SIGN </th><td class="description">cRLSign</td></tr>
12419<tr><th>CUPS_CREDUSAGE_DATA_ENCIPHERMENT </th><td class="description">dataEncipherment</td></tr>
12420<tr><th>CUPS_CREDUSAGE_DECIPHER_ONLY </th><td class="description">decipherOnly</td></tr>
12421<tr><th>CUPS_CREDUSAGE_DEFAULT_CA </th><td class="description">Defaults for CA certs</td></tr>
12422<tr><th>CUPS_CREDUSAGE_DEFAULT_TLS </th><td class="description">Defaults for TLS certs</td></tr>
12423<tr><th>CUPS_CREDUSAGE_DIGITAL_SIGNATURE </th><td class="description">digitalSignature</td></tr>
12424<tr><th>CUPS_CREDUSAGE_ENCIPHER_ONLY </th><td class="description">encipherOnly</td></tr>
12425<tr><th>CUPS_CREDUSAGE_KEY_AGREEMENT </th><td class="description">keyAgreement</td></tr>
12426<tr><th>CUPS_CREDUSAGE_KEY_CERT_SIGN </th><td class="description">keyCertSign</td></tr>
12427<tr><th>CUPS_CREDUSAGE_KEY_ENCIPHERMENT </th><td class="description">keyEncipherment</td></tr>
12428<tr><th>CUPS_CREDUSAGE_NON_REPUDIATION </th><td class="description">nonRepudiation/contentCommitment</td></tr>
12429</tbody></table>
b47dab17
MS
12430<h3 class="enumeration"><a id="cups_cspace_e">cups_cspace_e</a></h3>
12431<p class="description">cupsColorSpace attribute values</p>
12432<h4 class="constants">Constants</h4>
12433<table class="list"><tbody>
12434<tr><th>CUPS_CSPACE_ADOBERGB <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">Red, green, blue (Adobe RGB) </td></tr>
b6008d6b
MS
12435<tr><th>CUPS_CSPACE_CIELab <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">CIE Lab </td></tr>
12436<tr><th>CUPS_CSPACE_CIEXYZ <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">CIE XYZ </td></tr>
b47dab17
MS
12437<tr><th>CUPS_CSPACE_CMY </th><td class="description">Cyan, magenta, yellow (DeviceCMY)</td></tr>
12438<tr><th>CUPS_CSPACE_CMYK </th><td class="description">Cyan, magenta, yellow, black (DeviceCMYK)</td></tr>
12439<tr><th>CUPS_CSPACE_DEVICE1 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 1 color </td></tr>
12440<tr><th>CUPS_CSPACE_DEVICE2 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 2 colors </td></tr>
12441<tr><th>CUPS_CSPACE_DEVICE3 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 3 colors </td></tr>
12442<tr><th>CUPS_CSPACE_DEVICE4 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 4 colors </td></tr>
12443<tr><th>CUPS_CSPACE_DEVICE5 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 5 colors </td></tr>
12444<tr><th>CUPS_CSPACE_DEVICE6 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 6 colors </td></tr>
12445<tr><th>CUPS_CSPACE_DEVICE7 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 7 colors </td></tr>
12446<tr><th>CUPS_CSPACE_DEVICE8 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 8 colors </td></tr>
12447<tr><th>CUPS_CSPACE_DEVICE9 <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 9 colors </td></tr>
12448<tr><th>CUPS_CSPACE_DEVICEA <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 10 colors </td></tr>
12449<tr><th>CUPS_CSPACE_DEVICEB <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 11 colors </td></tr>
12450<tr><th>CUPS_CSPACE_DEVICEC <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 12 colors </td></tr>
12451<tr><th>CUPS_CSPACE_DEVICED <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 13 colors </td></tr>
12452<tr><th>CUPS_CSPACE_DEVICEE <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 14 colors </td></tr>
12453<tr><th>CUPS_CSPACE_DEVICEF <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">DeviceN, 15 colors </td></tr>
12454<tr><th>CUPS_CSPACE_GMCK <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Gold, magenta, yellow, black </td></tr>
12455<tr><th>CUPS_CSPACE_GMCS <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Gold, magenta, yellow, silver </td></tr>
12456<tr><th>CUPS_CSPACE_GOLD <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Gold foil </td></tr>
b6008d6b
MS
12457<tr><th>CUPS_CSPACE_ICC1 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 1 color </td></tr>
12458<tr><th>CUPS_CSPACE_ICC2 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 2 colors </td></tr>
12459<tr><th>CUPS_CSPACE_ICC3 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 3 colors </td></tr>
12460<tr><th>CUPS_CSPACE_ICC4 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 4 colors </td></tr>
12461<tr><th>CUPS_CSPACE_ICC5 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 5 colors </td></tr>
12462<tr><th>CUPS_CSPACE_ICC6 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 6 colors </td></tr>
12463<tr><th>CUPS_CSPACE_ICC7 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 7 colors </td></tr>
12464<tr><th>CUPS_CSPACE_ICC8 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 8 colors </td></tr>
12465<tr><th>CUPS_CSPACE_ICC9 <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 9 colors </td></tr>
12466<tr><th>CUPS_CSPACE_ICCA <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 10 colors </td></tr>
12467<tr><th>CUPS_CSPACE_ICCB <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 11 colors </td></tr>
12468<tr><th>CUPS_CSPACE_ICCC <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 12 colors </td></tr>
12469<tr><th>CUPS_CSPACE_ICCD <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 13 colors </td></tr>
12470<tr><th>CUPS_CSPACE_ICCE <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 14 colors </td></tr>
12471<tr><th>CUPS_CSPACE_ICCF <span class="info">&#160;CUPS 1.1.19&#160;</span></th><td class="description">ICC-based, 15 colors </td></tr>
b47dab17
MS
12472<tr><th>CUPS_CSPACE_K </th><td class="description">Black (DeviceK)</td></tr>
12473<tr><th>CUPS_CSPACE_KCMY <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Black, cyan, magenta, yellow </td></tr>
12474<tr><th>CUPS_CSPACE_KCMYcm <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Black, cyan, magenta, yellow, light-cyan, light-magenta </td></tr>
12475<tr><th>CUPS_CSPACE_RGB </th><td class="description">Red, green, blue (DeviceRGB, sRGB by default)</td></tr>
12476<tr><th>CUPS_CSPACE_RGBA </th><td class="description">Red, green, blue, alpha (DeviceRGB, sRGB by default)</td></tr>
b6008d6b 12477<tr><th>CUPS_CSPACE_RGBW <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Red, green, blue, white (DeviceRGB, sRGB by default) </td></tr>
b47dab17
MS
12478<tr><th>CUPS_CSPACE_SILVER <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Silver foil </td></tr>
12479<tr><th>CUPS_CSPACE_SRGB <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">Red, green, blue (sRGB) </td></tr>
12480<tr><th>CUPS_CSPACE_SW <span class="info">&#160;CUPS 1.4.5&#160;</span></th><td class="description">Luminance (gamma 2.2) </td></tr>
12481<tr><th>CUPS_CSPACE_W </th><td class="description">Luminance (DeviceGray, gamma 2.2 by default)</td></tr>
12482<tr><th>CUPS_CSPACE_WHITE <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">White ink (as black) </td></tr>
12483<tr><th>CUPS_CSPACE_YMC <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Yellow, magenta, cyan </td></tr>
12484<tr><th>CUPS_CSPACE_YMCK <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Yellow, magenta, cyan, black </td></tr>
12485</tbody></table>
12486<h3 class="enumeration"><a id="cups_cut_e">cups_cut_e</a></h3>
12487<p class="description">CutMedia attribute values</p>
12488<h4 class="constants">Constants</h4>
12489<table class="list"><tbody>
12490<tr><th>CUPS_CUT_FILE </th><td class="description">Cut the roll after this file</td></tr>
12491<tr><th>CUPS_CUT_JOB </th><td class="description">Cut the roll after this job</td></tr>
12492<tr><th>CUPS_CUT_NONE </th><td class="description">Never cut the roll</td></tr>
12493<tr><th>CUPS_CUT_PAGE </th><td class="description">Cut the roll after this page</td></tr>
12494<tr><th>CUPS_CUT_SET </th><td class="description">Cut the roll after this set</td></tr>
12495</tbody></table>
af268786
MS
12496<h3 class="enumeration"><a id="cups_dest_flags_e">cups_dest_flags_e</a></h3>
12497<p class="description">Flags for <a href="#cupsConnectDest"><code>cupsConnectDest</code></a> and <a href="#cupsEnumDests"><code>cupsEnumDests</code></a></p>
12498<h4 class="constants">Constants</h4>
12499<table class="list"><tbody>
12500<tr><th>CUPS_DEST_FLAGS_CANCELED </th><td class="description">Operation was canceled</td></tr>
12501<tr><th>CUPS_DEST_FLAGS_CONNECTING </th><td class="description">A connection is being established</td></tr>
12502<tr><th>CUPS_DEST_FLAGS_DEVICE </th><td class="description">For <a href="#cupsConnectDest"><code>cupsConnectDest</code></a>: Connect to device</td></tr>
12503<tr><th>CUPS_DEST_FLAGS_ERROR </th><td class="description">An error occurred</td></tr>
12504<tr><th>CUPS_DEST_FLAGS_MORE </th><td class="description">There are more destinations</td></tr>
12505<tr><th>CUPS_DEST_FLAGS_NONE </th><td class="description">No flags are set</td></tr>
12506<tr><th>CUPS_DEST_FLAGS_REMOVED </th><td class="description">The destination has gone away</td></tr>
12507<tr><th>CUPS_DEST_FLAGS_RESOLVING </th><td class="description">The destination address is being resolved</td></tr>
12508<tr><th>CUPS_DEST_FLAGS_UNCONNECTED </th><td class="description">There is no connection</td></tr>
12509</tbody></table>
12510<h3 class="enumeration"><a id="cups_dnssd_flags_e">cups_dnssd_flags_e</a></h3>
12511<p class="description">DNS-SD callback flag values</p>
12512<h4 class="constants">Constants</h4>
12513<table class="list"><tbody>
12514<tr><th>CUPS_DNSSD_FLAGS_ADD </th><td class="description">Added (removed if not set)</td></tr>
12515<tr><th>CUPS_DNSSD_FLAGS_COLLISION </th><td class="description">Collision occurred</td></tr>
12516<tr><th>CUPS_DNSSD_FLAGS_ERROR </th><td class="description">Error occurred</td></tr>
12517<tr><th>CUPS_DNSSD_FLAGS_HOST_CHANGE </th><td class="description">Host name changed</td></tr>
12518<tr><th>CUPS_DNSSD_FLAGS_MORE </th><td class="description">More coming</td></tr>
12519<tr><th>CUPS_DNSSD_FLAGS_NETWORK_CHANGE </th><td class="description">Network connection changed</td></tr>
12520<tr><th>CUPS_DNSSD_FLAGS_NONE </th><td class="description">No flags</td></tr>
12521</tbody></table>
12522<h3 class="enumeration"><a id="cups_dnssd_rrtype_e">cups_dnssd_rrtype_e</a></h3>
12523<p class="description">DNS record type values</p>
12524<h4 class="constants">Constants</h4>
12525<table class="list"><tbody>
12526<tr><th>CUPS_DNSSD_RRTYPE_A </th><td class="description">Host address</td></tr>
12527<tr><th>CUPS_DNSSD_RRTYPE_AAAA </th><td class="description">IPv6 Address.</td></tr>
12528<tr><th>CUPS_DNSSD_RRTYPE_ANY </th><td class="description">Wildcard match</td></tr>
12529<tr><th>CUPS_DNSSD_RRTYPE_CERT </th><td class="description">Certification record</td></tr>
12530<tr><th>CUPS_DNSSD_RRTYPE_CNAME </th><td class="description">Canonical name</td></tr>
12531<tr><th>CUPS_DNSSD_RRTYPE_DHCID </th><td class="description">DHCP Client Identifier</td></tr>
12532<tr><th>CUPS_DNSSD_RRTYPE_DNSKEY </th><td class="description">DNSKEY</td></tr>
12533<tr><th>CUPS_DNSSD_RRTYPE_HTTPS </th><td class="description">HTTPS Service Binding</td></tr>
12534<tr><th>CUPS_DNSSD_RRTYPE_KEY </th><td class="description">Security key</td></tr>
12535<tr><th>CUPS_DNSSD_RRTYPE_KX </th><td class="description">Key Exchange</td></tr>
12536<tr><th>CUPS_DNSSD_RRTYPE_LOC </th><td class="description">Location Information.</td></tr>
12537<tr><th>CUPS_DNSSD_RRTYPE_NS </th><td class="description">Name server</td></tr>
12538<tr><th>CUPS_DNSSD_RRTYPE_PTR </th><td class="description">Domain name pointer</td></tr>
12539<tr><th>CUPS_DNSSD_RRTYPE_RRSIG </th><td class="description">RRSIG</td></tr>
12540<tr><th>CUPS_DNSSD_RRTYPE_RT </th><td class="description">Router</td></tr>
12541<tr><th>CUPS_DNSSD_RRTYPE_SIG </th><td class="description">Security signature</td></tr>
12542<tr><th>CUPS_DNSSD_RRTYPE_SPF </th><td class="description">Sender Policy Framework for E-Mail</td></tr>
12543<tr><th>CUPS_DNSSD_RRTYPE_TXT </th><td class="description">One or more text strings</td></tr>
12544<tr><th>CUPS_DNSSD_RRTYPE_WKS </th><td class="description">Well known service</td></tr>
12545</tbody></table>
b47dab17
MS
12546<h3 class="enumeration"><a id="cups_edge_e">cups_edge_e</a></h3>
12547<p class="description">LeadingEdge attribute values</p>
12548<h4 class="constants">Constants</h4>
12549<table class="list"><tbody>
12550<tr><th>CUPS_EDGE_BOTTOM </th><td class="description">Leading edge is the bottom of the page</td></tr>
12551<tr><th>CUPS_EDGE_LEFT </th><td class="description">Leading edge is the left of the page</td></tr>
12552<tr><th>CUPS_EDGE_RIGHT </th><td class="description">Leading edge is the right of the page</td></tr>
12553<tr><th>CUPS_EDGE_TOP </th><td class="description">Leading edge is the top of the page</td></tr>
12554</tbody></table>
12555<h3 class="enumeration"><a id="cups_jog_e">cups_jog_e</a></h3>
12556<p class="description">Jog attribute values</p>
12557<h4 class="constants">Constants</h4>
12558<table class="list"><tbody>
12559<tr><th>CUPS_JOG_FILE </th><td class="description">Move pages after this file</td></tr>
12560<tr><th>CUPS_JOG_JOB </th><td class="description">Move pages after this job</td></tr>
12561<tr><th>CUPS_JOG_NONE </th><td class="description">Never move pages</td></tr>
12562<tr><th>CUPS_JOG_SET </th><td class="description">Move pages after this set</td></tr>
12563</tbody></table>
af268786
MS
12564<h3 class="enumeration"><a id="cups_jtype_e"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jtype_e</a></h3>
12565<p class="description">JSON node type </p>
b47dab17
MS
12566<h4 class="constants">Constants</h4>
12567<table class="list"><tbody>
af268786
MS
12568<tr><th>CUPS_JTYPE_ARRAY </th><td class="description">Array value</td></tr>
12569<tr><th>CUPS_JTYPE_FALSE </th><td class="description">Boolean false value</td></tr>
12570<tr><th>CUPS_JTYPE_KEY </th><td class="description">Object key (string)</td></tr>
12571<tr><th>CUPS_JTYPE_NULL </th><td class="description">Null value</td></tr>
12572<tr><th>CUPS_JTYPE_NUMBER </th><td class="description">Number value</td></tr>
12573<tr><th>CUPS_JTYPE_OBJECT </th><td class="description">Object value</td></tr>
12574<tr><th>CUPS_JTYPE_STRING </th><td class="description">String value</td></tr>
12575<tr><th>CUPS_JTYPE_TRUE </th><td class="description">Boolean true value</td></tr>
12576</tbody></table>
12577<h3 class="enumeration"><a id="cups_jwa_e"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jwa_e</a></h3>
12578<p class="description">JSON Web Algorithms </p>
12579<h4 class="constants">Constants</h4>
12580<table class="list"><tbody>
12581<tr><th>CUPS_JWA_ES256 </th><td class="description">ECDSA using P-256 and SHA-256</td></tr>
12582<tr><th>CUPS_JWA_ES384 </th><td class="description">ECDSA using P-384 and SHA-384</td></tr>
12583<tr><th>CUPS_JWA_ES512 </th><td class="description">ECDSA using P-521 and SHA-512</td></tr>
12584<tr><th>CUPS_JWA_HS256 </th><td class="description">HMAC using SHA-256</td></tr>
12585<tr><th>CUPS_JWA_HS384 </th><td class="description">HMAC using SHA-384</td></tr>
12586<tr><th>CUPS_JWA_HS512 </th><td class="description">HMAC using SHA-512</td></tr>
12587<tr><th>CUPS_JWA_NONE </th><td class="description">No algorithm</td></tr>
12588<tr><th>CUPS_JWA_RS256 </th><td class="description">RSASSA-PKCS1-v1_5 using SHA-256</td></tr>
12589<tr><th>CUPS_JWA_RS384 </th><td class="description">RSASSA-PKCS1-v1_5 using SHA-384</td></tr>
12590<tr><th>CUPS_JWA_RS512 </th><td class="description">RSASSA-PKCS1-v1_5 using SHA-512</td></tr>
12591</tbody></table>
12592<h3 class="enumeration"><a id="cups_jws_format_e"><span class="info">&#160;CUPS 2.5&#160;</span>cups_jws_format_e</a></h3>
12593<p class="description">JSON Web Signature Formats </p>
12594<h4 class="constants">Constants</h4>
12595<table class="list"><tbody>
12596<tr><th>CUPS_JWS_FORMAT_COMPACT </th><td class="description">JWS Compact Serialization</td></tr>
12597<tr><th>CUPS_JWS_FORMAT_JSON </th><td class="description">JWS JSON Serialization</td></tr>
12598</tbody></table>
12599<h3 class="enumeration"><a id="cups_media_flags_e">cups_media_flags_e</a></h3>
12600<p class="description">Flags for <a href="#cupsGetDestMediaByName"><code>cupsGetDestMediaByName</code></a> and <a href="#cupsGetDestMediaBySize"><code>cupsGetDestMediaBySize</code></a></p>
12601<h4 class="constants">Constants</h4>
12602<table class="list"><tbody>
12603<tr><th>CUPS_MEDIA_FLAGS_BORDERLESS </th><td class="description">Find a borderless size</td></tr>
12604<tr><th>CUPS_MEDIA_FLAGS_DEFAULT </th><td class="description">Find the closest size supported by the printer</td></tr>
12605<tr><th>CUPS_MEDIA_FLAGS_DUPLEX </th><td class="description">Find a size compatible with 2-sided printing</td></tr>
12606<tr><th>CUPS_MEDIA_FLAGS_EXACT </th><td class="description">Find an exact match for the size</td></tr>
12607<tr><th>CUPS_MEDIA_FLAGS_READY </th><td class="description">If the printer supports media sensing, find the size amongst the &quot;ready&quot; media.</td></tr>
b47dab17 12608</tbody></table>
0350eba5
MS
12609<h3 class="enumeration"><a id="cups_ogrant_e">cups_ogrant_e</a></h3>
12610<p class="description">OAuth Grant Types</p>
12611<h4 class="constants">Constants</h4>
12612<table class="list"><tbody>
12613<tr><th>CUPS_OGRANT_AUTHORIZATION_CODE </th><td class="description">Authorization code</td></tr>
12614<tr><th>CUPS_OGRANT_DEVICE_CODE </th><td class="description">Device code</td></tr>
12615<tr><th>CUPS_OGRANT_REFRESH_TOKEN </th><td class="description">Refresh token</td></tr>
12616</tbody></table>
b47dab17
MS
12617<h3 class="enumeration"><a id="cups_order_e">cups_order_e</a></h3>
12618<p class="description">cupsColorOrder attribute values</p>
12619<h4 class="constants">Constants</h4>
12620<table class="list"><tbody>
12621<tr><th>CUPS_ORDER_BANDED </th><td class="description">CCC MMM YYY KKK ...</td></tr>
12622<tr><th>CUPS_ORDER_CHUNKED </th><td class="description">CMYK CMYK CMYK ...</td></tr>
12623<tr><th>CUPS_ORDER_PLANAR </th><td class="description">CCC ... MMM ... YYY ... KKK ...</td></tr>
12624</tbody></table>
12625<h3 class="enumeration"><a id="cups_orient_e">cups_orient_e</a></h3>
12626<p class="description">Orientation attribute values</p>
12627<h4 class="constants">Constants</h4>
12628<table class="list"><tbody>
12629<tr><th>CUPS_ORIENT_0 </th><td class="description">Don't rotate the page</td></tr>
12630<tr><th>CUPS_ORIENT_180 </th><td class="description">Turn the page upside down</td></tr>
12631<tr><th>CUPS_ORIENT_270 </th><td class="description">Rotate the page clockwise</td></tr>
12632<tr><th>CUPS_ORIENT_90 </th><td class="description">Rotate the page counter-clockwise</td></tr>
12633</tbody></table>
12634<h3 class="enumeration"><a id="cups_ptype_e">cups_ptype_e</a></h3>
af268786
MS
12635<p class="description">Printer type/capability flags</p>
12636<h4 class="constants">Constants</h4>
12637<table class="list"><tbody>
12638<tr><th>CUPS_PTYPE_AUTHENTICATED </th><td class="description">Printer requires authentication</td></tr>
12639<tr><th>CUPS_PTYPE_BIND </th><td class="description">Can bind output</td></tr>
12640<tr><th>CUPS_PTYPE_BW </th><td class="description">Can do B&amp;W printing</td></tr>
12641<tr><th>CUPS_PTYPE_CLASS </th><td class="description">Printer class</td></tr>
12642<tr><th>CUPS_PTYPE_COLLATE </th><td class="description">Can quickly collate copies</td></tr>
12643<tr><th>CUPS_PTYPE_COLOR </th><td class="description">Can do color printing</td></tr>
12644<tr><th>CUPS_PTYPE_COMMANDS </th><td class="description">Printer supports maintenance commands</td></tr>
12645<tr><th>CUPS_PTYPE_COPIES </th><td class="description">Can do copies in hardware</td></tr>
12646<tr><th>CUPS_PTYPE_COVER </th><td class="description">Can cover output</td></tr>
12647<tr><th>CUPS_PTYPE_DEFAULT </th><td class="description">Default printer on network</td></tr>
12648<tr><th>CUPS_PTYPE_DISCOVERED </th><td class="description">Printer was discovered</td></tr>
12649<tr><th>CUPS_PTYPE_DUPLEX </th><td class="description">Can do two-sided printing</td></tr>
12650<tr><th>CUPS_PTYPE_FAX </th><td class="description">Fax queue</td></tr>
12651<tr><th>CUPS_PTYPE_FOLD <span class="info">&#160;CUPS 2.5&#160;</span></th><td class="description">Can fold output </td></tr>
12652<tr><th>CUPS_PTYPE_LARGE </th><td class="description">Can print on D/E/A1/A0-size media</td></tr>
12653<tr><th>CUPS_PTYPE_LOCAL </th><td class="description">Local printer or class</td></tr>
12654<tr><th>CUPS_PTYPE_MEDIUM </th><td class="description">Can print on Tabloid/B/C/A3/A2-size media</td></tr>
12655<tr><th>CUPS_PTYPE_MFP </th><td class="description">Printer with scanning capabilities</td></tr>
12656<tr><th>CUPS_PTYPE_NOT_SHARED </th><td class="description">Printer is not shared</td></tr>
12657<tr><th>CUPS_PTYPE_PUNCH </th><td class="description">Can punch output</td></tr>
12658<tr><th>CUPS_PTYPE_REJECTING </th><td class="description">Printer is rejecting jobs</td></tr>
12659<tr><th>CUPS_PTYPE_REMOTE </th><td class="description">Remote printer or class</td></tr>
12660<tr><th>CUPS_PTYPE_SCANNER </th><td class="description">Scanner-only device</td></tr>
12661<tr><th>CUPS_PTYPE_SMALL </th><td class="description">Can print on Letter/Legal/A4-size media</td></tr>
12662<tr><th>CUPS_PTYPE_SORT </th><td class="description">Can sort output</td></tr>
12663<tr><th>CUPS_PTYPE_STAPLE </th><td class="description">Can staple output</td></tr>
12664<tr><th>CUPS_PTYPE_VARIABLE </th><td class="description">Can print on rolls and custom-size media</td></tr>
12665</tbody></table>
12666<h3 class="enumeration"><a id="cups_raster_mode_e">cups_raster_mode_e</a></h3>
12667<p class="description">cupsRasterOpen modes</p>
12668<h4 class="constants">Constants</h4>
12669<table class="list"><tbody>
12670<tr><th>CUPS_RASTER_READ </th><td class="description">Open stream for reading</td></tr>
12671<tr><th>CUPS_RASTER_WRITE </th><td class="description">Open stream for writing</td></tr>
b6008d6b
MS
12672<tr><th>CUPS_RASTER_WRITE_COMPRESSED <span class="info">&#160;CUPS 1.3&#160;</span></th><td class="description">Open stream for compressed writing </td></tr>
12673<tr><th>CUPS_RASTER_WRITE_PWG <span class="info">&#160;CUPS 1.5&#160;</span></th><td class="description">Open stream for compressed writing in PWG Raster mode </td></tr>
af268786
MS
12674</tbody></table>
12675<h3 class="enumeration"><a id="cups_whichjobs_e">cups_whichjobs_e</a></h3>
12676<p class="description">Which jobs for <a href="#cupsGetJobs"><code>cupsGetJobs</code></a></p>
b47dab17
MS
12677<h4 class="constants">Constants</h4>
12678<table class="list"><tbody>
af268786
MS
12679<tr><th>CUPS_WHICHJOBS_ACTIVE </th><td class="description">Pending/held/processing jobs</td></tr>
12680<tr><th>CUPS_WHICHJOBS_ALL </th><td class="description">All jobs</td></tr>
12681<tr><th>CUPS_WHICHJOBS_COMPLETED </th><td class="description">Completed/canceled/aborted jobs</td></tr>
b47dab17
MS
12682</tbody></table>
12683<h3 class="enumeration"><a id="http_encoding_e">http_encoding_e</a></h3>
12684<p class="description">HTTP transfer encoding values</p>
12685<h4 class="constants">Constants</h4>
12686<table class="list"><tbody>
12687<tr><th>HTTP_ENCODING_CHUNKED </th><td class="description">Data is chunked</td></tr>
12688<tr><th>HTTP_ENCODING_FIELDS </th><td class="description">Sending HTTP fields</td></tr>
12689<tr><th>HTTP_ENCODING_LENGTH </th><td class="description">Data is sent with Content-Length</td></tr>
12690</tbody></table>
12691<h3 class="enumeration"><a id="http_encryption_e">http_encryption_e</a></h3>
12692<p class="description">HTTP encryption values</p>
12693<h4 class="constants">Constants</h4>
12694<table class="list"><tbody>
af268786 12695<tr><th>HTTP_ENCRYPTION_ALWAYS </th><td class="description">Always encrypt (HTTPS)</td></tr>
b47dab17
MS
12696<tr><th>HTTP_ENCRYPTION_IF_REQUESTED </th><td class="description">Encrypt if requested (TLS upgrade)</td></tr>
12697<tr><th>HTTP_ENCRYPTION_NEVER </th><td class="description">Never encrypt</td></tr>
12698<tr><th>HTTP_ENCRYPTION_REQUIRED </th><td class="description">Encryption is required (TLS upgrade)</td></tr>
12699</tbody></table>
12700<h3 class="enumeration"><a id="http_field_e">http_field_e</a></h3>
12701<p class="description">HTTP field names</p>
12702<h4 class="constants">Constants</h4>
12703<table class="list"><tbody>
0350eba5
MS
12704<tr><th>HTTP_FIELD_ACCEPT <span class="info">&#160;CUPS 2.5&#160;</span></th><td class="description">Accept field </td></tr>
12705<tr><th>HTTP_FIELD_ACCEPT_ENCODING <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">Accepting-Encoding field </td></tr>
b47dab17
MS
12706<tr><th>HTTP_FIELD_ACCEPT_LANGUAGE </th><td class="description">Accept-Language field</td></tr>
12707<tr><th>HTTP_FIELD_ACCEPT_RANGES </th><td class="description">Accept-Ranges field</td></tr>
af268786
MS
12708<tr><th>HTTP_FIELD_ACCESS_CONTROL_ALLOW_CREDENTIALS <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Allow-Credentials field </td></tr>
12709<tr><th>HTTP_FIELD_ACCESS_CONTROL_ALLOW_HEADERS <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Allow-Headers field </td></tr>
12710<tr><th>HTTP_FIELD_ACCESS_CONTROL_ALLOW_METHODS <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Allow-Methods field </td></tr>
12711<tr><th>HTTP_FIELD_ACCESS_CONTROL_ALLOW_ORIGIN <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Allow-Origin field </td></tr>
12712<tr><th>HTTP_FIELD_ACCESS_CONTROL_EXPOSE_HEADERS <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Expose-Headers field </td></tr>
12713<tr><th>HTTP_FIELD_ACCESS_CONTROL_MAX_AGE <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Max-Age field </td></tr>
12714<tr><th>HTTP_FIELD_ACCESS_CONTROL_REQUEST_HEADERS <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Request-Headers field </td></tr>
12715<tr><th>HTTP_FIELD_ACCESS_CONTROL_REQUEST_METHOD <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">CORS/Fetch Access-Control-Request-Method field </td></tr>
0350eba5 12716<tr><th>HTTP_FIELD_ALLOW <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">Allow field </td></tr>
af268786 12717<tr><th>HTTP_FIELD_AUTHENTICATION_INFO <span class="info">&#160;CUPS 2.2.9&#160;</span></th><td class="description">Authentication-Info field </td></tr>
b47dab17
MS
12718<tr><th>HTTP_FIELD_AUTHORIZATION </th><td class="description">Authorization field</td></tr>
12719<tr><th>HTTP_FIELD_CONNECTION </th><td class="description">Connection field</td></tr>
12720<tr><th>HTTP_FIELD_CONTENT_ENCODING </th><td class="description">Content-Encoding field</td></tr>
12721<tr><th>HTTP_FIELD_CONTENT_LANGUAGE </th><td class="description">Content-Language field</td></tr>
12722<tr><th>HTTP_FIELD_CONTENT_LENGTH </th><td class="description">Content-Length field</td></tr>
12723<tr><th>HTTP_FIELD_CONTENT_LOCATION </th><td class="description">Content-Location field</td></tr>
12724<tr><th>HTTP_FIELD_CONTENT_MD5 </th><td class="description">Content-MD5 field</td></tr>
12725<tr><th>HTTP_FIELD_CONTENT_RANGE </th><td class="description">Content-Range field</td></tr>
12726<tr><th>HTTP_FIELD_CONTENT_TYPE </th><td class="description">Content-Type field</td></tr>
12727<tr><th>HTTP_FIELD_CONTENT_VERSION </th><td class="description">Content-Version field</td></tr>
12728<tr><th>HTTP_FIELD_DATE </th><td class="description">Date field</td></tr>
12729<tr><th>HTTP_FIELD_HOST </th><td class="description">Host field</td></tr>
12730<tr><th>HTTP_FIELD_IF_MODIFIED_SINCE </th><td class="description">If-Modified-Since field</td></tr>
12731<tr><th>HTTP_FIELD_IF_UNMODIFIED_SINCE </th><td class="description">If-Unmodified-Since field</td></tr>
12732<tr><th>HTTP_FIELD_KEEP_ALIVE </th><td class="description">Keep-Alive field</td></tr>
12733<tr><th>HTTP_FIELD_LAST_MODIFIED </th><td class="description">Last-Modified field</td></tr>
12734<tr><th>HTTP_FIELD_LINK </th><td class="description">Link field</td></tr>
12735<tr><th>HTTP_FIELD_LOCATION </th><td class="description">Location field</td></tr>
12736<tr><th>HTTP_FIELD_MAX </th><td class="description">Maximum field index</td></tr>
af268786
MS
12737<tr><th>HTTP_FIELD_OPTIONAL_WWW_AUTHENTICATE <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">RFC 8053 Optional-WWW-Authenticate field </td></tr>
12738<tr><th>HTTP_FIELD_ORIGIN <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">RFC 6454 Origin field </td></tr>
12739<tr><th>HTTP_FIELD_OSCORE <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">RFC 8613 OSCORE field </td></tr>
b47dab17
MS
12740<tr><th>HTTP_FIELD_RANGE </th><td class="description">Range field</td></tr>
12741<tr><th>HTTP_FIELD_REFERER </th><td class="description">Referer field</td></tr>
12742<tr><th>HTTP_FIELD_RETRY_AFTER </th><td class="description">Retry-After field</td></tr>
0350eba5 12743<tr><th>HTTP_FIELD_SERVER <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">Server field </td></tr>
af268786 12744<tr><th>HTTP_FIELD_STRICT_TRANSPORT_SECURITY <span class="info">&#160;CUPS 2.4&#160;</span></th><td class="description">HSTS Strict-Transport-Security field </td></tr>
b47dab17
MS
12745<tr><th>HTTP_FIELD_TRANSFER_ENCODING </th><td class="description">Transfer-Encoding field</td></tr>
12746<tr><th>HTTP_FIELD_UNKNOWN </th><td class="description">Unknown field</td></tr>
12747<tr><th>HTTP_FIELD_UPGRADE </th><td class="description">Upgrade field</td></tr>
12748<tr><th>HTTP_FIELD_USER_AGENT </th><td class="description">User-Agent field</td></tr>
12749<tr><th>HTTP_FIELD_WWW_AUTHENTICATE </th><td class="description">WWW-Authenticate field</td></tr>
12750</tbody></table>
12751<h3 class="enumeration"><a id="http_keepalive_e">http_keepalive_e</a></h3>
12752<p class="description">HTTP keep-alive values</p>
12753<h4 class="constants">Constants</h4>
12754<table class="list"><tbody>
12755<tr><th>HTTP_KEEPALIVE_OFF </th><td class="description">No keep alive support</td></tr>
12756<tr><th>HTTP_KEEPALIVE_ON </th><td class="description">Use keep alive</td></tr>
12757</tbody></table>
af268786
MS
12758<h3 class="enumeration"><a id="http_resolve_e">http_resolve_e</a></h3>
12759<p class="description"><a href="#httpResolveURI"><code>httpResolveURI</code></a> options bit values</p>
12760<h4 class="constants">Constants</h4>
12761<table class="list"><tbody>
12762<tr><th>HTTP_RESOLVE_DEFAULT </th><td class="description">Resolve with default options</td></tr>
12763<tr><th>HTTP_RESOLVE_FAXOUT </th><td class="description">Resolve FaxOut service instead of Print</td></tr>
12764<tr><th>HTTP_RESOLVE_FQDN </th><td class="description">Resolve to a FQDN</td></tr>
12765</tbody></table>
b47dab17 12766<h3 class="enumeration"><a id="http_state_e">http_state_e</a></h3>
af268786 12767<p class="description">HTTP state values; states are server-oriented...</p>
b47dab17
MS
12768<h4 class="constants">Constants</h4>
12769<table class="list"><tbody>
12770<tr><th>HTTP_STATE_CONNECT </th><td class="description">CONNECT command, waiting for blank line</td></tr>
12771<tr><th>HTTP_STATE_DELETE </th><td class="description">DELETE command, waiting for blank line</td></tr>
12772<tr><th>HTTP_STATE_ERROR </th><td class="description">Error on socket</td></tr>
12773<tr><th>HTTP_STATE_GET </th><td class="description">GET command, waiting for blank line</td></tr>
12774<tr><th>HTTP_STATE_GET_SEND </th><td class="description">GET command, sending data</td></tr>
12775<tr><th>HTTP_STATE_HEAD </th><td class="description">HEAD command, waiting for blank line</td></tr>
12776<tr><th>HTTP_STATE_OPTIONS </th><td class="description">OPTIONS command, waiting for blank line</td></tr>
12777<tr><th>HTTP_STATE_POST </th><td class="description">POST command, waiting for blank line</td></tr>
12778<tr><th>HTTP_STATE_POST_RECV </th><td class="description">POST command, receiving data</td></tr>
12779<tr><th>HTTP_STATE_POST_SEND </th><td class="description">POST command, sending data</td></tr>
12780<tr><th>HTTP_STATE_PUT </th><td class="description">PUT command, waiting for blank line</td></tr>
12781<tr><th>HTTP_STATE_PUT_RECV </th><td class="description">PUT command, receiving data</td></tr>
12782<tr><th>HTTP_STATE_STATUS </th><td class="description">Command complete, sending status</td></tr>
12783<tr><th>HTTP_STATE_TRACE </th><td class="description">TRACE command, waiting for blank line</td></tr>
0350eba5
MS
12784<tr><th>HTTP_STATE_UNKNOWN_METHOD <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">Unknown request method, waiting for blank line </td></tr>
12785<tr><th>HTTP_STATE_UNKNOWN_VERSION <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">Unknown request method, waiting for blank line </td></tr>
b47dab17
MS
12786<tr><th>HTTP_STATE_WAITING </th><td class="description">Waiting for command</td></tr>
12787</tbody></table>
12788<h3 class="enumeration"><a id="http_status_e">http_status_e</a></h3>
12789<p class="description">HTTP status codes</p>
12790<h4 class="constants">Constants</h4>
12791<table class="list"><tbody>
12792<tr><th>HTTP_STATUS_ACCEPTED </th><td class="description">DELETE command was successful</td></tr>
af268786 12793<tr><th>HTTP_STATUS_ALREADY_REPORTED </th><td class="description">Already reported (WebDAV)</td></tr>
b47dab17
MS
12794<tr><th>HTTP_STATUS_BAD_GATEWAY </th><td class="description">Bad gateway</td></tr>
12795<tr><th>HTTP_STATUS_BAD_REQUEST </th><td class="description">Bad request</td></tr>
12796<tr><th>HTTP_STATUS_CONFLICT </th><td class="description">Request is self-conflicting</td></tr>
af268786 12797<tr><th>HTTP_STATUS_CONTENT_TOO_LARGE </th><td class="description">Content too large</td></tr>
b47dab17
MS
12798<tr><th>HTTP_STATUS_CONTINUE </th><td class="description">Everything OK, keep going...</td></tr>
12799<tr><th>HTTP_STATUS_CREATED </th><td class="description">PUT command was successful</td></tr>
12800<tr><th>HTTP_STATUS_CUPS_AUTHORIZATION_CANCELED <span class="info">&#160;CUPS 1.4&#160;</span></th><td class="description">User canceled authorization </td></tr>
0350eba5 12801<tr><th>HTTP_STATUS_CUPS_PKI_ERROR <span class="info">&#160;CUPS 1.5&#160;</span></th><td class="description">Error negotiating a secure connection </td></tr>
b47dab17
MS
12802<tr><th>HTTP_STATUS_ERROR </th><td class="description">An error response from httpXxxx()</td></tr>
12803<tr><th>HTTP_STATUS_EXPECTATION_FAILED </th><td class="description">The expectation given in an Expect header field was not met</td></tr>
af268786 12804<tr><th>HTTP_STATUS_FAILED_DEPENDENCY </th><td class="description">Failed dependency (WebDAV)</td></tr>
b47dab17
MS
12805<tr><th>HTTP_STATUS_FORBIDDEN </th><td class="description">Forbidden to access this URI</td></tr>
12806<tr><th>HTTP_STATUS_FOUND </th><td class="description">Document was found at a different URI</td></tr>
12807<tr><th>HTTP_STATUS_GATEWAY_TIMEOUT </th><td class="description">Gateway connection timed out</td></tr>
12808<tr><th>HTTP_STATUS_GONE </th><td class="description">Server has gone away</td></tr>
af268786 12809<tr><th>HTTP_STATUS_INSUFFICIENT_STORAGE </th><td class="description">Insufficient storage (WebDAV)</td></tr>
b47dab17 12810<tr><th>HTTP_STATUS_LENGTH_REQUIRED </th><td class="description">A content length or encoding is required</td></tr>
af268786
MS
12811<tr><th>HTTP_STATUS_LOCKED </th><td class="description">Locked (WebDAV)</td></tr>
12812<tr><th>HTTP_STATUS_LOOP_DETECTED </th><td class="description">Loop detected (WebDAV)</td></tr>
b47dab17 12813<tr><th>HTTP_STATUS_METHOD_NOT_ALLOWED </th><td class="description">Method is not allowed</td></tr>
af268786 12814<tr><th>HTTP_STATUS_MISDIRECTED_REQUEST </th><td class="description">Misdirected request</td></tr>
b47dab17
MS
12815<tr><th>HTTP_STATUS_MOVED_PERMANENTLY </th><td class="description">Document has moved permanently</td></tr>
12816<tr><th>HTTP_STATUS_MULTIPLE_CHOICES </th><td class="description">Multiple files match request</td></tr>
af268786
MS
12817<tr><th>HTTP_STATUS_MULTI_STATUS </th><td class="description">Multiple status codes (WebDAV)</td></tr>
12818<tr><th>HTTP_STATUS_NETWORK_AUTHENTICATION_REQUIRED </th><td class="description">Network Authentication Required (WebDAV)</td></tr>
0350eba5 12819<tr><th>HTTP_STATUS_NONE <span class="info">&#160;CUPS 1.7&#160;</span></th><td class="description">No Expect value </td></tr>
b47dab17
MS
12820<tr><th>HTTP_STATUS_NOT_ACCEPTABLE </th><td class="description">Not Acceptable</td></tr>
12821<tr><th>HTTP_STATUS_NOT_AUTHORITATIVE </th><td class="description">Information isn't authoritative</td></tr>
12822<tr><th>HTTP_STATUS_NOT_FOUND </th><td class="description">URI was not found</td></tr>
12823<tr><th>HTTP_STATUS_NOT_IMPLEMENTED </th><td class="description">Feature not implemented</td></tr>
12824<tr><th>HTTP_STATUS_NOT_MODIFIED </th><td class="description">File not modified</td></tr>
12825<tr><th>HTTP_STATUS_NOT_SUPPORTED </th><td class="description">HTTP version not supported</td></tr>
12826<tr><th>HTTP_STATUS_NO_CONTENT </th><td class="description">Successful command, no new data</td></tr>
12827<tr><th>HTTP_STATUS_OK </th><td class="description">OPTIONS/GET/HEAD/POST/TRACE command was successful</td></tr>
12828<tr><th>HTTP_STATUS_PARTIAL_CONTENT </th><td class="description">Only a partial file was received/sent</td></tr>
12829<tr><th>HTTP_STATUS_PAYMENT_REQUIRED </th><td class="description">Payment required</td></tr>
af268786 12830<tr><th>HTTP_STATUS_PERMANENT_REDIRECT </th><td class="description">Permanent redirection</td></tr>
b47dab17 12831<tr><th>HTTP_STATUS_PRECONDITION </th><td class="description">Precondition failed</td></tr>
af268786 12832<tr><th>HTTP_STATUS_PRECONDITION_REQUIRED </th><td class="description">Precondition required (WebDAV)</td></tr>
b47dab17 12833<tr><th>HTTP_STATUS_PROXY_AUTHENTICATION </th><td class="description">Proxy Authentication is Required</td></tr>
af268786
MS
12834<tr><th>HTTP_STATUS_RANGE_NOT_SATISFIABLE </th><td class="description">The requested range is not satisfiable</td></tr>
12835<tr><th>HTTP_STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE </th><td class="description">Request Header Fields Too Large (WebDAV)</td></tr>
b47dab17 12836<tr><th>HTTP_STATUS_REQUEST_TIMEOUT </th><td class="description">Request timed out</td></tr>
b47dab17
MS
12837<tr><th>HTTP_STATUS_RESET_CONTENT </th><td class="description">Content was reset/recreated</td></tr>
12838<tr><th>HTTP_STATUS_SEE_OTHER </th><td class="description">See this other link</td></tr>
12839<tr><th>HTTP_STATUS_SERVER_ERROR </th><td class="description">Internal server error</td></tr>
12840<tr><th>HTTP_STATUS_SERVICE_UNAVAILABLE </th><td class="description">Service is unavailable</td></tr>
12841<tr><th>HTTP_STATUS_SWITCHING_PROTOCOLS </th><td class="description">HTTP upgrade to TLS/SSL</td></tr>
12842<tr><th>HTTP_STATUS_TEMPORARY_REDIRECT </th><td class="description">Temporary redirection</td></tr>
af268786
MS
12843<tr><th>HTTP_STATUS_TOO_EARLY </th><td class="description">Too early (WebDAV)</td></tr>
12844<tr><th>HTTP_STATUS_TOO_MANY_REQUESTS </th><td class="description">Too many requests (WebDAV)</td></tr>
b47dab17 12845<tr><th>HTTP_STATUS_UNAUTHORIZED </th><td class="description">Unauthorized to access host</td></tr>
af268786
MS
12846<tr><th>HTTP_STATUS_UNAVAILABLE_FOR_LEGAL_REASONS </th><td class="description">Unavailable For Legal Reasons (RFC 7725)</td></tr>
12847<tr><th>HTTP_STATUS_UNPROCESSABLE_CONTENT </th><td class="description">Unprocessable content</td></tr>
12848<tr><th>HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE </th><td class="description">The requested media type is unsupported</td></tr>
b47dab17
MS
12849<tr><th>HTTP_STATUS_UPGRADE_REQUIRED </th><td class="description">Upgrade to SSL/TLS required</td></tr>
12850<tr><th>HTTP_STATUS_URI_TOO_LONG </th><td class="description">URI too long</td></tr>
12851<tr><th>HTTP_STATUS_USE_PROXY </th><td class="description">Must use a proxy to access this URI</td></tr>
12852</tbody></table>
12853<h3 class="enumeration"><a id="http_trust_e"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span>http_trust_e</a></h3>
12854<p class="description">Level of trust for credentials </p>
12855<h4 class="constants">Constants</h4>
12856<table class="list"><tbody>
12857<tr><th>HTTP_TRUST_CHANGED </th><td class="description">Credentials have changed</td></tr>
12858<tr><th>HTTP_TRUST_EXPIRED </th><td class="description">Credentials are expired</td></tr>
12859<tr><th>HTTP_TRUST_INVALID </th><td class="description">Credentials are invalid</td></tr>
12860<tr><th>HTTP_TRUST_OK </th><td class="description">Credentials are OK/trusted</td></tr>
12861<tr><th>HTTP_TRUST_RENEWED </th><td class="description">Credentials have been renewed</td></tr>
12862<tr><th>HTTP_TRUST_UNKNOWN </th><td class="description">Credentials are unknown/new</td></tr>
12863</tbody></table>
12864<h3 class="enumeration"><a id="http_uri_coding_e">http_uri_coding_e</a></h3>
12865<p class="description">URI en/decode flags</p>
12866<h4 class="constants">Constants</h4>
12867<table class="list"><tbody>
12868<tr><th>HTTP_URI_CODING_ALL </th><td class="description">En/decode everything</td></tr>
12869<tr><th>HTTP_URI_CODING_HOSTNAME </th><td class="description">En/decode the hostname portion</td></tr>
12870<tr><th>HTTP_URI_CODING_MOST </th><td class="description">En/decode all but the query</td></tr>
12871<tr><th>HTTP_URI_CODING_NONE </th><td class="description">Don't en/decode anything</td></tr>
12872<tr><th>HTTP_URI_CODING_QUERY </th><td class="description">En/decode the query portion</td></tr>
12873<tr><th>HTTP_URI_CODING_RESOURCE </th><td class="description">En/decode the resource portion</td></tr>
12874<tr><th>HTTP_URI_CODING_RFC6874 </th><td class="description">Use RFC 6874 address format</td></tr>
12875<tr><th>HTTP_URI_CODING_USERNAME </th><td class="description">En/decode the username portion</td></tr>
12876</tbody></table>
12877<h3 class="enumeration"><a id="http_uri_status_e"><span class="info">&#160;CUPS 1.2&#160;</span>http_uri_status_e</a></h3>
12878<p class="description">URI separation status </p>
12879<h4 class="constants">Constants</h4>
12880<table class="list"><tbody>
12881<tr><th>HTTP_URI_STATUS_BAD_ARGUMENTS </th><td class="description">Bad arguments to function (error)</td></tr>
12882<tr><th>HTTP_URI_STATUS_BAD_HOSTNAME </th><td class="description">Bad hostname in URI (error)</td></tr>
12883<tr><th>HTTP_URI_STATUS_BAD_PORT </th><td class="description">Bad port number in URI (error)</td></tr>
12884<tr><th>HTTP_URI_STATUS_BAD_RESOURCE </th><td class="description">Bad resource in URI (error)</td></tr>
12885<tr><th>HTTP_URI_STATUS_BAD_SCHEME </th><td class="description">Bad scheme in URI (error)</td></tr>
12886<tr><th>HTTP_URI_STATUS_BAD_URI </th><td class="description">Bad/empty URI (error)</td></tr>
12887<tr><th>HTTP_URI_STATUS_BAD_USERNAME </th><td class="description">Bad username in URI (error)</td></tr>
12888<tr><th>HTTP_URI_STATUS_MISSING_RESOURCE </th><td class="description">Missing resource in URI (warning)</td></tr>
12889<tr><th>HTTP_URI_STATUS_MISSING_SCHEME </th><td class="description">Missing scheme in URI (warning)</td></tr>
12890<tr><th>HTTP_URI_STATUS_OK </th><td class="description">URI decoded OK</td></tr>
12891<tr><th>HTTP_URI_STATUS_OVERFLOW </th><td class="description">URI buffer for httpAssembleURI is too small</td></tr>
12892<tr><th>HTTP_URI_STATUS_UNKNOWN_SCHEME </th><td class="description">Unknown scheme in URI (warning)</td></tr>
12893</tbody></table>
12894<h3 class="enumeration"><a id="ipp_finishings_e">ipp_finishings_e</a></h3>
12895<p class="description">Finishings values</p>
12896<h4 class="constants">Constants</h4>
12897<table class="list"><tbody>
12898<tr><th>IPP_FINISHINGS_BALE </th><td class="description">Bale (any type)</td></tr>
12899<tr><th>IPP_FINISHINGS_BIND </th><td class="description">Bind</td></tr>
12900<tr><th>IPP_FINISHINGS_BIND_BOTTOM </th><td class="description">Bind on bottom</td></tr>
12901<tr><th>IPP_FINISHINGS_BIND_LEFT </th><td class="description">Bind on left</td></tr>
12902<tr><th>IPP_FINISHINGS_BIND_RIGHT </th><td class="description">Bind on right</td></tr>
12903<tr><th>IPP_FINISHINGS_BIND_TOP </th><td class="description">Bind on top</td></tr>
12904<tr><th>IPP_FINISHINGS_BOOKLET_MAKER </th><td class="description">Fold to make booklet</td></tr>
12905<tr><th>IPP_FINISHINGS_COAT </th><td class="description">Apply protective liquid or powder coating</td></tr>
12906<tr><th>IPP_FINISHINGS_COVER </th><td class="description">Add cover</td></tr>
12907<tr><th>IPP_FINISHINGS_EDGE_STITCH </th><td class="description">Stitch along any side</td></tr>
12908<tr><th>IPP_FINISHINGS_EDGE_STITCH_BOTTOM </th><td class="description">Stitch along bottom edge</td></tr>
12909<tr><th>IPP_FINISHINGS_EDGE_STITCH_LEFT </th><td class="description">Stitch along left side</td></tr>
12910<tr><th>IPP_FINISHINGS_EDGE_STITCH_RIGHT </th><td class="description">Stitch along right side</td></tr>
12911<tr><th>IPP_FINISHINGS_EDGE_STITCH_TOP </th><td class="description">Stitch along top edge</td></tr>
12912<tr><th>IPP_FINISHINGS_FOLD </th><td class="description">Fold (any type)</td></tr>
12913<tr><th>IPP_FINISHINGS_FOLD_ACCORDION </th><td class="description">Accordion-fold the paper vertically into four sections</td></tr>
12914<tr><th>IPP_FINISHINGS_FOLD_DOUBLE_GATE </th><td class="description">Fold the top and bottom quarters of the paper towards the midline, then fold in half vertically</td></tr>
12915<tr><th>IPP_FINISHINGS_FOLD_ENGINEERING_Z </th><td class="description">Fold the paper vertically into two small sections and one larger, forming an elongated Z</td></tr>
12916<tr><th>IPP_FINISHINGS_FOLD_GATE </th><td class="description">Fold the top and bottom quarters of the paper towards the midline</td></tr>
12917<tr><th>IPP_FINISHINGS_FOLD_HALF </th><td class="description">Fold the paper in half vertically</td></tr>
12918<tr><th>IPP_FINISHINGS_FOLD_HALF_Z </th><td class="description">Fold the paper in half horizontally, then Z-fold the paper vertically</td></tr>
12919<tr><th>IPP_FINISHINGS_FOLD_LEFT_GATE </th><td class="description">Fold the top quarter of the paper towards the midline</td></tr>
12920<tr><th>IPP_FINISHINGS_FOLD_LETTER </th><td class="description">Fold the paper into three sections vertically; sometimes also known as a C fold</td></tr>
12921<tr><th>IPP_FINISHINGS_FOLD_PARALLEL </th><td class="description">Fold the paper in half vertically two times, yielding four sections</td></tr>
12922<tr><th>IPP_FINISHINGS_FOLD_POSTER </th><td class="description">Fold the paper in half horizontally and vertically; sometimes also called a cross fold</td></tr>
12923<tr><th>IPP_FINISHINGS_FOLD_RIGHT_GATE </th><td class="description">Fold the bottom quarter of the paper towards the midline</td></tr>
12924<tr><th>IPP_FINISHINGS_FOLD_Z </th><td class="description">Fold the paper vertically into three sections, forming a Z</td></tr>
12925<tr><th>IPP_FINISHINGS_JOG_OFFSET </th><td class="description">Offset for binding (any type)</td></tr>
12926<tr><th>IPP_FINISHINGS_LAMINATE </th><td class="description">Apply protective (solid) material</td></tr>
12927<tr><th>IPP_FINISHINGS_NONE </th><td class="description">No finishing</td></tr>
12928<tr><th>IPP_FINISHINGS_PUNCH </th><td class="description">Punch (any location/count)</td></tr>
12929<tr><th>IPP_FINISHINGS_PUNCH_BOTTOM_LEFT </th><td class="description">Punch 1 hole bottom left</td></tr>
12930<tr><th>IPP_FINISHINGS_PUNCH_BOTTOM_RIGHT </th><td class="description">Punch 1 hole bottom right</td></tr>
12931<tr><th>IPP_FINISHINGS_PUNCH_DUAL_BOTTOM </th><td class="description">Punch 2 holes bottom edge</td></tr>
12932<tr><th>IPP_FINISHINGS_PUNCH_DUAL_LEFT </th><td class="description">Punch 2 holes left side</td></tr>
12933<tr><th>IPP_FINISHINGS_PUNCH_DUAL_RIGHT </th><td class="description">Punch 2 holes right side</td></tr>
12934<tr><th>IPP_FINISHINGS_PUNCH_DUAL_TOP </th><td class="description">Punch 2 holes top edge</td></tr>
12935<tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_BOTTOM </th><td class="description">Punch multiple holes bottom edge</td></tr>
12936<tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_LEFT </th><td class="description">Punch multiple holes left side</td></tr>
12937<tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_RIGHT </th><td class="description">Punch multiple holes right side</td></tr>
12938<tr><th>IPP_FINISHINGS_PUNCH_MULTIPLE_TOP </th><td class="description">Punch multiple holes top edge</td></tr>
12939<tr><th>IPP_FINISHINGS_PUNCH_QUAD_BOTTOM </th><td class="description">Punch 4 holes bottom edge</td></tr>
12940<tr><th>IPP_FINISHINGS_PUNCH_QUAD_LEFT </th><td class="description">Punch 4 holes left side</td></tr>
12941<tr><th>IPP_FINISHINGS_PUNCH_QUAD_RIGHT </th><td class="description">Punch 4 holes right side</td></tr>
12942<tr><th>IPP_FINISHINGS_PUNCH_QUAD_TOP </th><td class="description">Punch 4 holes top edge</td></tr>
12943<tr><th>IPP_FINISHINGS_PUNCH_TOP_LEFT </th><td class="description">Punch 1 hole top left</td></tr>
12944<tr><th>IPP_FINISHINGS_PUNCH_TOP_RIGHT </th><td class="description">Punch 1 hole top right</td></tr>
12945<tr><th>IPP_FINISHINGS_PUNCH_TRIPLE_BOTTOM </th><td class="description">Punch 3 holes bottom edge</td></tr>
12946<tr><th>IPP_FINISHINGS_PUNCH_TRIPLE_LEFT </th><td class="description">Punch 3 holes left side</td></tr>
12947<tr><th>IPP_FINISHINGS_PUNCH_TRIPLE_RIGHT </th><td class="description">Punch 3 holes right side</td></tr>
12948<tr><th>IPP_FINISHINGS_PUNCH_TRIPLE_TOP </th><td class="description">Punch 3 holes top edge</td></tr>
12949<tr><th>IPP_FINISHINGS_SADDLE_STITCH </th><td class="description">Staple interior</td></tr>
12950<tr><th>IPP_FINISHINGS_STAPLE </th><td class="description">Staple (any location/method)</td></tr>
12951<tr><th>IPP_FINISHINGS_STAPLE_BOTTOM_LEFT </th><td class="description">Staple bottom left corner</td></tr>
12952<tr><th>IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT </th><td class="description">Staple bottom right corner</td></tr>
12953<tr><th>IPP_FINISHINGS_STAPLE_DUAL_BOTTOM </th><td class="description">Two staples on bottom</td></tr>
12954<tr><th>IPP_FINISHINGS_STAPLE_DUAL_LEFT </th><td class="description">Two staples on left</td></tr>
12955<tr><th>IPP_FINISHINGS_STAPLE_DUAL_RIGHT </th><td class="description">Two staples on right</td></tr>
12956<tr><th>IPP_FINISHINGS_STAPLE_DUAL_TOP </th><td class="description">Two staples on top</td></tr>
12957<tr><th>IPP_FINISHINGS_STAPLE_TOP_LEFT </th><td class="description">Staple top left corner</td></tr>
12958<tr><th>IPP_FINISHINGS_STAPLE_TOP_RIGHT </th><td class="description">Staple top right corner</td></tr>
12959<tr><th>IPP_FINISHINGS_STAPLE_TRIPLE_BOTTOM </th><td class="description">Three staples on bottom</td></tr>
12960<tr><th>IPP_FINISHINGS_STAPLE_TRIPLE_LEFT </th><td class="description">Three staples on left</td></tr>
12961<tr><th>IPP_FINISHINGS_STAPLE_TRIPLE_RIGHT </th><td class="description">Three staples on right</td></tr>
12962<tr><th>IPP_FINISHINGS_STAPLE_TRIPLE_TOP </th><td class="description">Three staples on top</td></tr>
12963<tr><th>IPP_FINISHINGS_TRIM </th><td class="description">Trim (any type)</td></tr>
12964<tr><th>IPP_FINISHINGS_TRIM_AFTER_COPIES </th><td class="description">Trim output after each copy</td></tr>
12965<tr><th>IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS </th><td class="description">Trim output after each document</td></tr>
12966<tr><th>IPP_FINISHINGS_TRIM_AFTER_JOB </th><td class="description">Trim output after job</td></tr>
12967<tr><th>IPP_FINISHINGS_TRIM_AFTER_PAGES </th><td class="description">Trim output after each page</td></tr>
12968</tbody></table>
12969<h3 class="enumeration"><a id="ipp_jstate_e">ipp_jstate_e</a></h3>
12970<p class="description">Job states</p>
12971<h4 class="constants">Constants</h4>
12972<table class="list"><tbody>
12973<tr><th>IPP_JSTATE_ABORTED </th><td class="description">Job has aborted due to error</td></tr>
12974<tr><th>IPP_JSTATE_CANCELED </th><td class="description">Job has been canceled</td></tr>
12975<tr><th>IPP_JSTATE_COMPLETED </th><td class="description">Job has completed successfully</td></tr>
12976<tr><th>IPP_JSTATE_HELD </th><td class="description">Job is held for printing</td></tr>
12977<tr><th>IPP_JSTATE_PENDING </th><td class="description">Job is waiting to be printed</td></tr>
12978<tr><th>IPP_JSTATE_PROCESSING </th><td class="description">Job is currently printing</td></tr>
12979<tr><th>IPP_JSTATE_STOPPED </th><td class="description">Job has been stopped</td></tr>
12980</tbody></table>
12981<h3 class="enumeration"><a id="ipp_op_e">ipp_op_e</a></h3>
12982<p class="description">IPP operations</p>
12983<h4 class="constants">Constants</h4>
12984<table class="list"><tbody>
12985<tr><th>IPP_OP_ALLOCATE_PRINTER_RESOURCES </th><td class="description">Allocate-Printer-Resources: Use resources for a printer.</td></tr>
12986<tr><th>IPP_OP_CANCEL_CURRENT_JOB </th><td class="description">Cancel-Current-Job: Cancel the current job</td></tr>
12987<tr><th>IPP_OP_CANCEL_JOB </th><td class="description">Cancel-Job: Cancel a job</td></tr>
12988<tr><th>IPP_OP_CANCEL_JOBS </th><td class="description">Cancel-Jobs: Cancel all jobs (administrative)</td></tr>
12989<tr><th>IPP_OP_CANCEL_MY_JOBS </th><td class="description">Cancel-My-Jobs: Cancel a user's jobs</td></tr>
12990<tr><th>IPP_OP_CANCEL_RESOURCE </th><td class="description">Cancel-Resource: Uninstall a resource.</td></tr>
b6008d6b 12991<tr><th>IPP_OP_CANCEL_SUBSCRIPTION <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Cancel-Subscription: Cancel a subscription </td></tr>
b47dab17
MS
12992<tr><th>IPP_OP_CLOSE_JOB </th><td class="description">Close-Job: Close a job and start printing</td></tr>
12993<tr><th>IPP_OP_CREATE_JOB </th><td class="description">Create-Job: Create an empty print job</td></tr>
b6008d6b 12994<tr><th>IPP_OP_CREATE_JOB_SUBSCRIPTIONS <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Create-Job-Subscriptions: Create one of more job subscriptions </td></tr>
b47dab17 12995<tr><th>IPP_OP_CREATE_PRINTER </th><td class="description">Create-Printer: Create a new service.</td></tr>
b6008d6b 12996<tr><th>IPP_OP_CREATE_PRINTER_SUBSCRIPTIONS <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Create-Printer-Subscriptions: Create one or more printer subscriptions </td></tr>
b47dab17
MS
12997<tr><th>IPP_OP_CREATE_RESOURCE </th><td class="description">Create-Resource: Create a new (empty) resource.</td></tr>
12998<tr><th>IPP_OP_CREATE_RESOURCE_SUBSCRIPTIONS </th><td class="description">Create-Resource-Subscriptions: Create event subscriptions for a resource.</td></tr>
12999<tr><th>IPP_OP_CREATE_SYSTEM_SUBSCRIPTIONS </th><td class="description">Create-System-Subscriptions: Create event subscriptions for a system.</td></tr>
13000<tr><th>IPP_OP_CUPS_ADD_MODIFY_CLASS </th><td class="description">CUPS-Add-Modify-Class: Add or modify a class</td></tr>
13001<tr><th>IPP_OP_CUPS_ADD_MODIFY_PRINTER </th><td class="description">CUPS-Add-Modify-Printer: Add or modify a printer</td></tr>
b6008d6b 13002<tr><th>IPP_OP_CUPS_AUTHENTICATE_JOB <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">CUPS-Authenticate-Job: Authenticate a job </td></tr>
b47dab17
MS
13003<tr><th>IPP_OP_CUPS_CREATE_LOCAL_PRINTER <span class="info">&#160;CUPS 2.2&#160;</span></th><td class="description">CUPS-Create-Local-Printer: Create a local (temporary) printer </td></tr>
13004<tr><th>IPP_OP_CUPS_DELETE_CLASS </th><td class="description">CUPS-Delete-Class: Delete a class</td></tr>
13005<tr><th>IPP_OP_CUPS_DELETE_PRINTER </th><td class="description">CUPS-Delete-Printer: Delete a printer</td></tr>
13006<tr><th>IPP_OP_CUPS_GET_DEFAULT </th><td class="description">CUPS-Get-Default: Get the default printer</td></tr>
13007<tr><th>IPP_OP_CUPS_GET_DEVICES <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">CUPS-Get-Devices: Get a list of supported devices </td></tr>
b6008d6b 13008<tr><th>IPP_OP_CUPS_GET_DOCUMENT <span class="info">&#160;CUPS 1.4&#160;</span></th><td class="description">CUPS-Get-Document: Get a document file </td></tr>
b47dab17
MS
13009<tr><th>IPP_OP_CUPS_GET_PPD <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">CUPS-Get-PPD: Get a PPD file </td></tr>
13010<tr><th>IPP_OP_CUPS_GET_PPDS <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">CUPS-Get-PPDs: Get a list of supported drivers </td></tr>
13011<tr><th>IPP_OP_CUPS_GET_PRINTERS </th><td class="description">CUPS-Get-Printers: Get a list of printers and/or classes</td></tr>
13012<tr><th>IPP_OP_CUPS_INVALID </th><td class="description">Invalid operation name for <a href="#ippOpValue"><code>ippOpValue</code></a></td></tr>
13013<tr><th>IPP_OP_CUPS_MOVE_JOB </th><td class="description">CUPS-Move-Job: Move a job to a different printer</td></tr>
13014<tr><th>IPP_OP_CUPS_SET_DEFAULT </th><td class="description">CUPS-Set-Default: Set the default printer</td></tr>
13015<tr><th>IPP_OP_DEALLOCATE_PRINTER_RESOURCES </th><td class="description">Deallocate-Printer-Resources: Stop using resources for a printer.</td></tr>
13016<tr><th>IPP_OP_DELETE_PRINTER </th><td class="description">Delete-Printer: Delete an existing service.</td></tr>
13017<tr><th>IPP_OP_DISABLE_ALL_PRINTERS </th><td class="description">Disable-All-Printers: Stop accepting new jobs on all services.</td></tr>
13018<tr><th>IPP_OP_DISABLE_PRINTER </th><td class="description">Disable-Printer: Reject new jobs for a printer</td></tr>
13019<tr><th>IPP_OP_ENABLE_ALL_PRINTERS </th><td class="description">Enable-All-Printers: Start accepting new jobs on all services.</td></tr>
13020<tr><th>IPP_OP_ENABLE_PRINTER </th><td class="description">Enable-Printer: Accept new jobs for a printer</td></tr>
13021<tr><th>IPP_OP_GET_JOBS </th><td class="description">Get-Jobs: Get a list of jobs</td></tr>
13022<tr><th>IPP_OP_GET_JOB_ATTRIBUTES </th><td class="description">Get-Job-Attribute: Get information about a job</td></tr>
b6008d6b 13023<tr><th>IPP_OP_GET_NOTIFICATIONS <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Get-Notifications: Get notification events </td></tr>
b47dab17
MS
13024<tr><th>IPP_OP_GET_PRINTERS </th><td class="description">Get-Printers: Get a list of services.</td></tr>
13025<tr><th>IPP_OP_GET_PRINTER_ATTRIBUTES </th><td class="description">Get-Printer-Attributes: Get information about a printer</td></tr>
13026<tr><th>IPP_OP_GET_PRINTER_SUPPORTED_VALUES </th><td class="description">Get-Printer-Supported-Values: Get supported values</td></tr>
b6008d6b
MS
13027<tr><th>IPP_OP_GET_SUBSCRIPTIONS <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Get-Subscriptions: Get list of subscriptions </td></tr>
13028<tr><th>IPP_OP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Get-Subscription-Attributes: Get subscription information </td></tr>
b47dab17
MS
13029<tr><th>IPP_OP_GET_SYSTEM_ATTRIBUTES </th><td class="description">Get-System-Attributes: Get system object attributes.</td></tr>
13030<tr><th>IPP_OP_GET_SYSTEM_SUPPORTED_VALUES </th><td class="description">Get-System-Supported-Values: Get supported values for system object attributes.</td></tr>
13031<tr><th>IPP_OP_HOLD_JOB </th><td class="description">Hold-Job: Hold a job for printing</td></tr>
13032<tr><th>IPP_OP_HOLD_NEW_JOBS </th><td class="description">Hold-New-Jobs: Hold new jobs</td></tr>
13033<tr><th>IPP_OP_IDENTIFY_PRINTER </th><td class="description">Identify-Printer: Make the printer beep, flash, or display a message for identification</td></tr>
13034<tr><th>IPP_OP_INSTALL_RESOURCE </th><td class="description">Install-Resource: Install a resource.</td></tr>
13035<tr><th>IPP_OP_PAUSE_ALL_PRINTERS </th><td class="description">Pause-All-Printers: Stop all services immediately.</td></tr>
13036<tr><th>IPP_OP_PAUSE_ALL_PRINTERS_AFTER_CURRENT_JOB </th><td class="description">Pause-All-Printers-After-Current-Job: Stop all services after processing the current jobs.</td></tr>
13037<tr><th>IPP_OP_PAUSE_PRINTER </th><td class="description">Pause-Printer: Stop a printer</td></tr>
13038<tr><th>IPP_OP_PAUSE_PRINTER_AFTER_CURRENT_JOB </th><td class="description">Pause-Printer-After-Current-Job: Stop printer after the current job</td></tr>
13039<tr><th>IPP_OP_PRINT_JOB </th><td class="description">Print-Job: Print a single file</td></tr>
13040<tr><th>IPP_OP_PROMOTE_JOB </th><td class="description">Promote-Job: Promote a job to print sooner</td></tr>
13041<tr><th>IPP_OP_REGISTER_OUTPUT_DEVICE </th><td class="description">Register-Output-Device: Register a remote service.</td></tr>
13042<tr><th>IPP_OP_RELEASE_HELD_NEW_JOBS </th><td class="description">Release-Held-New-Jobs: Release new jobs that were previously held</td></tr>
13043<tr><th>IPP_OP_RELEASE_JOB </th><td class="description">Release-Job: Release a job for printing</td></tr>
b6008d6b 13044<tr><th>IPP_OP_RENEW_SUBSCRIPTION <span class="info">&#160;CUPS 1.2&#160;</span></th><td class="description">Renew-Subscription: Renew a printer subscription </td></tr>
b47dab17
MS
13045<tr><th>IPP_OP_RESTART_JOB <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">Restart-Job: Reprint a job </td></tr>
13046<tr><th>IPP_OP_RESTART_SYSTEM </th><td class="description">Restart-System: Restart all services.</td></tr>
13047<tr><th>IPP_OP_RESUME_ALL_PRINTERS </th><td class="description">Resume-All-Printers: Start job processing on all services.</td></tr>
13048<tr><th>IPP_OP_RESUME_JOB </th><td class="description">Resume-Job: Resume the current job</td></tr>
13049<tr><th>IPP_OP_RESUME_PRINTER </th><td class="description">Resume-Printer: Start a printer</td></tr>
13050<tr><th>IPP_OP_SCHEDULE_JOB_AFTER </th><td class="description">Schedule-Job-After: Schedule a job to print after another</td></tr>
13051<tr><th>IPP_OP_SEND_DOCUMENT </th><td class="description">Send-Document: Add a file to a job</td></tr>
13052<tr><th>IPP_OP_SEND_RESOURCE_DATA </th><td class="description">Send-Resource-Data: Upload the data for a resource.</td></tr>
13053<tr><th>IPP_OP_SET_JOB_ATTRIBUTES </th><td class="description">Set-Job-Attributes: Set job values</td></tr>
13054<tr><th>IPP_OP_SET_PRINTER_ATTRIBUTES </th><td class="description">Set-Printer-Attributes: Set printer values</td></tr>
13055<tr><th>IPP_OP_SET_RESOURCE_ATTRIBUTES </th><td class="description">Set-Resource-Attributes: Set resource object attributes.</td></tr>
13056<tr><th>IPP_OP_SET_SYSTEM_ATTRIBUTES </th><td class="description">Set-System-Attributes: Set system object attributes.</td></tr>
13057<tr><th>IPP_OP_SHUTDOWN_ALL_PRINTERS </th><td class="description">Shutdown-All-Printers: Shutdown all services.</td></tr>
13058<tr><th>IPP_OP_SHUTDOWN_ONE_PRINTER </th><td class="description">Shutdown-One-Printer: Shutdown a service.</td></tr>
13059<tr><th>IPP_OP_STARTUP_ALL_PRINTERS </th><td class="description">Startup-All-Printers: Startup all services.</td></tr>
13060<tr><th>IPP_OP_STARTUP_ONE_PRINTER </th><td class="description">Startup-One-Printer: Start a service.</td></tr>
13061<tr><th>IPP_OP_SUSPEND_CURRENT_JOB </th><td class="description">Suspend-Current-Job: Suspend the current job</td></tr>
13062<tr><th>IPP_OP_VALIDATE_JOB </th><td class="description">Validate-Job: Validate job values prior to submission</td></tr>
13063</tbody></table>
13064<h3 class="enumeration"><a id="ipp_orient_e">ipp_orient_e</a></h3>
13065<p class="description">Orientation values</p>
13066<h4 class="constants">Constants</h4>
13067<table class="list"><tbody>
13068<tr><th>IPP_ORIENT_LANDSCAPE </th><td class="description">90 degrees counter-clockwise</td></tr>
13069<tr><th>IPP_ORIENT_NONE </th><td class="description">No rotation</td></tr>
13070<tr><th>IPP_ORIENT_PORTRAIT </th><td class="description">No rotation</td></tr>
13071<tr><th>IPP_ORIENT_REVERSE_LANDSCAPE </th><td class="description">90 degrees clockwise</td></tr>
13072<tr><th>IPP_ORIENT_REVERSE_PORTRAIT </th><td class="description">180 degrees</td></tr>
13073</tbody></table>
13074<h3 class="enumeration"><a id="ipp_pstate_e">ipp_pstate_e</a></h3>
13075<p class="description">Printer state values</p>
13076<h4 class="constants">Constants</h4>
13077<table class="list"><tbody>
13078<tr><th>IPP_PSTATE_IDLE </th><td class="description">Printer is idle</td></tr>
13079<tr><th>IPP_PSTATE_PROCESSING </th><td class="description">Printer is working</td></tr>
13080<tr><th>IPP_PSTATE_STOPPED </th><td class="description">Printer is stopped</td></tr>
13081</tbody></table>
13082<h3 class="enumeration"><a id="ipp_quality_e">ipp_quality_e</a></h3>
13083<p class="description">Print quality values</p>
13084<h4 class="constants">Constants</h4>
13085<table class="list"><tbody>
13086<tr><th>IPP_QUALITY_DRAFT </th><td class="description">Draft quality</td></tr>
13087<tr><th>IPP_QUALITY_HIGH </th><td class="description">High quality</td></tr>
13088<tr><th>IPP_QUALITY_NORMAL </th><td class="description">Normal quality</td></tr>
13089</tbody></table>
13090<h3 class="enumeration"><a id="ipp_res_e">ipp_res_e</a></h3>
13091<p class="description">Resolution units</p>
13092<h4 class="constants">Constants</h4>
13093<table class="list"><tbody>
13094<tr><th>IPP_RES_PER_CM </th><td class="description">Pixels per centimeter</td></tr>
13095<tr><th>IPP_RES_PER_INCH </th><td class="description">Pixels per inch</td></tr>
13096</tbody></table>
13097<h3 class="enumeration"><a id="ipp_rstate_e">ipp_rstate_e</a></h3>
13098<p class="description">resource-state values</p>
13099<h4 class="constants">Constants</h4>
13100<table class="list"><tbody>
13101<tr><th>IPP_RSTATE_ABORTED </th><td class="description">Resource has been aborted and is pending deletion.</td></tr>
13102<tr><th>IPP_RSTATE_AVAILABLE </th><td class="description">Resource is available for installation.</td></tr>
13103<tr><th>IPP_RSTATE_CANCELED </th><td class="description">Resource has been canceled and is pending deletion.</td></tr>
13104<tr><th>IPP_RSTATE_INSTALLED </th><td class="description">Resource is installed.</td></tr>
13105<tr><th>IPP_RSTATE_PENDING </th><td class="description">Resource is created but has no data yet.</td></tr>
13106</tbody></table>
13107<h3 class="enumeration"><a id="ipp_sstate_e">ipp_sstate_e</a></h3>
13108<p class="description">system-state values</p>
13109<h4 class="constants">Constants</h4>
13110<table class="list"><tbody>
13111<tr><th>IPP_SSTATE_IDLE </th><td class="description">At least one printer is idle and none are processing a job.</td></tr>
13112<tr><th>IPP_SSTATE_PROCESSING </th><td class="description">At least one printer is processing a job.</td></tr>
13113<tr><th>IPP_SSTATE_STOPPED </th><td class="description">All printers are stopped.</td></tr>
13114</tbody></table>
13115<h3 class="enumeration"><a id="ipp_state_e">ipp_state_e</a></h3>
13116<p class="description">ipp_t state values</p>
13117<h4 class="constants">Constants</h4>
13118<table class="list"><tbody>
13119<tr><th>IPP_STATE_ATTRIBUTE </th><td class="description">One or more attributes need to be sent/received</td></tr>
13120<tr><th>IPP_STATE_DATA </th><td class="description">IPP request data needs to be sent/received</td></tr>
13121<tr><th>IPP_STATE_ERROR </th><td class="description">An error occurred</td></tr>
13122<tr><th>IPP_STATE_HEADER </th><td class="description">The request header needs to be sent/received</td></tr>
13123<tr><th>IPP_STATE_IDLE </th><td class="description">Nothing is happening/request completed</td></tr>
13124</tbody></table>
13125<h3 class="enumeration"><a id="ipp_status_e">ipp_status_e</a></h3>
13126<p class="description">IPP status code values</p>
13127<h4 class="constants">Constants</h4>
13128<table class="list"><tbody>
13129<tr><th>IPP_STATUS_CUPS_INVALID </th><td class="description">Invalid status name for <a href="#ippErrorValue"><code>ippErrorValue</code></a></td></tr>
13130<tr><th>IPP_STATUS_ERROR_ACCOUNT_AUTHORIZATION_FAILED </th><td class="description">client-error-account-authorization-failed</td></tr>
13131<tr><th>IPP_STATUS_ERROR_ACCOUNT_CLOSED </th><td class="description">client-error-account-closed</td></tr>
13132<tr><th>IPP_STATUS_ERROR_ACCOUNT_INFO_NEEDED </th><td class="description">client-error-account-info-needed</td></tr>
13133<tr><th>IPP_STATUS_ERROR_ACCOUNT_LIMIT_REACHED </th><td class="description">client-error-account-limit-reached</td></tr>
13134<tr><th>IPP_STATUS_ERROR_ATTRIBUTES_NOT_SETTABLE </th><td class="description">client-error-attributes-not-settable</td></tr>
13135<tr><th>IPP_STATUS_ERROR_ATTRIBUTES_OR_VALUES </th><td class="description">client-error-attributes-or-values-not-supported</td></tr>
13136<tr><th>IPP_STATUS_ERROR_BAD_REQUEST </th><td class="description">client-error-bad-request</td></tr>
13137<tr><th>IPP_STATUS_ERROR_BUSY </th><td class="description">server-error-busy</td></tr>
13138<tr><th>IPP_STATUS_ERROR_CHARSET </th><td class="description">client-error-charset-not-supported</td></tr>
13139<tr><th>IPP_STATUS_ERROR_COMPRESSION_ERROR </th><td class="description">client-error-compression-error</td></tr>
13140<tr><th>IPP_STATUS_ERROR_COMPRESSION_NOT_SUPPORTED </th><td class="description">client-error-compression-not-supported</td></tr>
13141<tr><th>IPP_STATUS_ERROR_CONFLICTING </th><td class="description">client-error-conflicting-attributes</td></tr>
13142<tr><th>IPP_STATUS_ERROR_CUPS_ACCOUNT_AUTHORIZATION_FAILED <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">cups-error-account-authorization-failed </td></tr>
13143<tr><th>IPP_STATUS_ERROR_CUPS_ACCOUNT_CLOSED </th><td class="description">cups-error-account-closed @deprecate@</td></tr>
13144<tr><th>IPP_STATUS_ERROR_CUPS_ACCOUNT_INFO_NEEDED <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">cups-error-account-info-needed </td></tr>
13145<tr><th>IPP_STATUS_ERROR_CUPS_ACCOUNT_LIMIT_REACHED <span class="info">&#160;DEPRECATED&#160;</span></th><td class="description">cups-error-account-limit-reached </td></tr>
b6008d6b 13146<tr><th>IPP_STATUS_ERROR_CUPS_AUTHENTICATION_CANCELED <span class="info">&#160;CUPS 1.5&#160;</span></th><td class="description">cups-authentication-canceled - Authentication canceled by user </td></tr>
0350eba5 13147<tr><th>IPP_STATUS_ERROR_CUPS_OAUTH </th><td class="description">cups-oauth - OAuth error</td></tr>
b6008d6b
MS
13148<tr><th>IPP_STATUS_ERROR_CUPS_PKI <span class="info">&#160;CUPS 1.5&#160;</span></th><td class="description">cups-pki-error - Error negotiating a secure connection </td></tr>
13149<tr><th>IPP_STATUS_ERROR_CUPS_UPGRADE_REQUIRED <span class="info">&#160;CUPS 1.5&#160;</span></th><td class="description">cups-upgrade-required - TLS upgrade required </td></tr>
b47dab17
MS
13150<tr><th>IPP_STATUS_ERROR_DEVICE </th><td class="description">server-error-device-error</td></tr>
13151<tr><th>IPP_STATUS_ERROR_DOCUMENT_ACCESS </th><td class="description">client-error-document-access-error</td></tr>
13152<tr><th>IPP_STATUS_ERROR_DOCUMENT_FORMAT_ERROR </th><td class="description">client-error-document-format-error</td></tr>
13153<tr><th>IPP_STATUS_ERROR_DOCUMENT_FORMAT_NOT_SUPPORTED </th><td class="description">client-error-document-format-not-supported</td></tr>
13154<tr><th>IPP_STATUS_ERROR_DOCUMENT_PASSWORD </th><td class="description">client-error-document-password-error</td></tr>
13155<tr><th>IPP_STATUS_ERROR_DOCUMENT_PERMISSION </th><td class="description">client-error-document-permission-error</td></tr>
13156<tr><th>IPP_STATUS_ERROR_DOCUMENT_SECURITY </th><td class="description">client-error-document-security-error</td></tr>
13157<tr><th>IPP_STATUS_ERROR_DOCUMENT_UNPRINTABLE </th><td class="description">client-error-document-unprintable-error</td></tr>
13158<tr><th>IPP_STATUS_ERROR_FORBIDDEN </th><td class="description">client-error-forbidden</td></tr>
13159<tr><th>IPP_STATUS_ERROR_GONE </th><td class="description">client-error-gone</td></tr>
13160<tr><th>IPP_STATUS_ERROR_IGNORED_ALL_SUBSCRIPTIONS </th><td class="description">client-error-ignored-all-subscriptions</td></tr>
13161<tr><th>IPP_STATUS_ERROR_INTERNAL </th><td class="description">server-error-internal-error</td></tr>
13162<tr><th>IPP_STATUS_ERROR_JOB_CANCELED </th><td class="description">server-error-job-canceled</td></tr>
13163<tr><th>IPP_STATUS_ERROR_MULTIPLE_JOBS_NOT_SUPPORTED </th><td class="description">server-error-multiple-document-jobs-not-supported</td></tr>
13164<tr><th>IPP_STATUS_ERROR_NOT_ACCEPTING_JOBS </th><td class="description">server-error-not-accepting-jobs</td></tr>
13165<tr><th>IPP_STATUS_ERROR_NOT_AUTHENTICATED </th><td class="description">client-error-not-authenticated</td></tr>
13166<tr><th>IPP_STATUS_ERROR_NOT_AUTHORIZED </th><td class="description">client-error-not-authorized</td></tr>
13167<tr><th>IPP_STATUS_ERROR_NOT_FETCHABLE </th><td class="description">client-error-not-fetchable</td></tr>
13168<tr><th>IPP_STATUS_ERROR_NOT_FOUND </th><td class="description">client-error-not-found</td></tr>
13169<tr><th>IPP_STATUS_ERROR_NOT_POSSIBLE </th><td class="description">client-error-not-possible</td></tr>
13170<tr><th>IPP_STATUS_ERROR_OPERATION_NOT_SUPPORTED </th><td class="description">server-error-operation-not-supported</td></tr>
13171<tr><th>IPP_STATUS_ERROR_PRINTER_IS_DEACTIVATED </th><td class="description">server-error-printer-is-deactivated</td></tr>
13172<tr><th>IPP_STATUS_ERROR_REQUEST_ENTITY </th><td class="description">client-error-request-entity-too-large</td></tr>
13173<tr><th>IPP_STATUS_ERROR_REQUEST_VALUE </th><td class="description">client-error-request-value-too-long</td></tr>
13174<tr><th>IPP_STATUS_ERROR_SERVICE_UNAVAILABLE </th><td class="description">server-error-service-unavailable</td></tr>
13175<tr><th>IPP_STATUS_ERROR_TEMPORARY </th><td class="description">server-error-temporary-error</td></tr>
13176<tr><th>IPP_STATUS_ERROR_TIMEOUT </th><td class="description">client-error-timeout</td></tr>
13177<tr><th>IPP_STATUS_ERROR_TOO_MANY_DOCUMENTS </th><td class="description">server-error-too-many-documents</td></tr>
13178<tr><th>IPP_STATUS_ERROR_TOO_MANY_JOBS </th><td class="description">server-error-too-many-jobs</td></tr>
13179<tr><th>IPP_STATUS_ERROR_TOO_MANY_SUBSCRIPTIONS </th><td class="description">client-error-too-many-subscriptions</td></tr>
13180<tr><th>IPP_STATUS_ERROR_URI_SCHEME </th><td class="description">client-error-uri-scheme-not-supported</td></tr>
13181<tr><th>IPP_STATUS_ERROR_VERSION_NOT_SUPPORTED </th><td class="description">server-error-version-not-supported</td></tr>
13182<tr><th>IPP_STATUS_OK </th><td class="description">successful-ok</td></tr>
13183<tr><th>IPP_STATUS_OK_CONFLICTING </th><td class="description">successful-ok-conflicting-attributes</td></tr>
13184<tr><th>IPP_STATUS_OK_EVENTS_COMPLETE </th><td class="description">successful-ok-events-complete</td></tr>
13185<tr><th>IPP_STATUS_OK_IGNORED_OR_SUBSTITUTED </th><td class="description">successful-ok-ignored-or-substituted-attributes</td></tr>
13186<tr><th>IPP_STATUS_OK_IGNORED_SUBSCRIPTIONS </th><td class="description">successful-ok-ignored-subscriptions</td></tr>
13187<tr><th>IPP_STATUS_OK_TOO_MANY_EVENTS </th><td class="description">successful-ok-too-many-events</td></tr>
13188</tbody></table>
13189<h3 class="enumeration"><a id="ipp_tag_e">ipp_tag_e</a></h3>
13190<p class="description">Value and group tag values for attributes</p>
13191<h4 class="constants">Constants</h4>
13192<table class="list"><tbody>
13193<tr><th>IPP_TAG_ADMINDEFINE </th><td class="description">Admin-defined value</td></tr>
13194<tr><th>IPP_TAG_BOOLEAN </th><td class="description">Boolean value</td></tr>
13195<tr><th>IPP_TAG_CHARSET </th><td class="description">Character set value</td></tr>
13196<tr><th>IPP_TAG_CUPS_INVALID </th><td class="description">Invalid tag name for <a href="#ippTagValue"><code>ippTagValue</code></a></td></tr>
13197<tr><th>IPP_TAG_DATE </th><td class="description">Date/time value</td></tr>
13198<tr><th>IPP_TAG_DEFAULT </th><td class="description">Default value</td></tr>
13199<tr><th>IPP_TAG_DELETEATTR </th><td class="description">Delete-attribute value</td></tr>
13200<tr><th>IPP_TAG_DOCUMENT </th><td class="description">Document group</td></tr>
13201<tr><th>IPP_TAG_END </th><td class="description">End-of-attributes</td></tr>
13202<tr><th>IPP_TAG_ENUM </th><td class="description">Enumeration value</td></tr>
13203<tr><th>IPP_TAG_EVENT_NOTIFICATION </th><td class="description">Event group</td></tr>
0350eba5 13204<tr><th>IPP_TAG_EXTENSION </th><td class="description">Extension point for 32-bit tags (part of value)</td></tr>
b47dab17
MS
13205<tr><th>IPP_TAG_INTEGER </th><td class="description">Integer value</td></tr>
13206<tr><th>IPP_TAG_JOB </th><td class="description">Job group</td></tr>
13207<tr><th>IPP_TAG_KEYWORD </th><td class="description">Keyword value</td></tr>
13208<tr><th>IPP_TAG_LANGUAGE </th><td class="description">Language value</td></tr>
13209<tr><th>IPP_TAG_MIMETYPE </th><td class="description">MIME media type value</td></tr>
13210<tr><th>IPP_TAG_NAME </th><td class="description">Name value</td></tr>
13211<tr><th>IPP_TAG_NAMELANG </th><td class="description">Name-with-language value</td></tr>
13212<tr><th>IPP_TAG_NOTSETTABLE </th><td class="description">Not-settable value</td></tr>
13213<tr><th>IPP_TAG_NOVALUE </th><td class="description">No-value value</td></tr>
13214<tr><th>IPP_TAG_OPERATION </th><td class="description">Operation group</td></tr>
13215<tr><th>IPP_TAG_PRINTER </th><td class="description">Printer group</td></tr>
13216<tr><th>IPP_TAG_RANGE </th><td class="description">Range value</td></tr>
13217<tr><th>IPP_TAG_RESOLUTION </th><td class="description">Resolution value</td></tr>
13218<tr><th>IPP_TAG_RESOURCE </th><td class="description">Resource group</td></tr>
13219<tr><th>IPP_TAG_STRING </th><td class="description">Octet string value</td></tr>
13220<tr><th>IPP_TAG_SUBSCRIPTION </th><td class="description">Subscription group</td></tr>
13221<tr><th>IPP_TAG_SYSTEM </th><td class="description">System group</td></tr>
13222<tr><th>IPP_TAG_TEXT </th><td class="description">Text value</td></tr>
13223<tr><th>IPP_TAG_TEXTLANG </th><td class="description">Text-with-language value</td></tr>
13224<tr><th>IPP_TAG_UNKNOWN </th><td class="description">Unknown value</td></tr>
13225<tr><th>IPP_TAG_UNSUPPORTED_GROUP </th><td class="description">Unsupported attributes group</td></tr>
13226<tr><th>IPP_TAG_UNSUPPORTED_VALUE </th><td class="description">Unsupported value</td></tr>
13227<tr><th>IPP_TAG_URI </th><td class="description">URI value</td></tr>
13228<tr><th>IPP_TAG_URISCHEME </th><td class="description">URI scheme value</td></tr>
13229<tr><th>IPP_TAG_ZERO </th><td class="description">Zero tag - used for separators</td></tr>
13230</tbody></table>
13231</div>
13232</body>
798d6e29 13233</html>