Merge pull request #5621 from zdohnal/cgigetarray-sigsegv
[thirdparty/cups.git] / doc / help / cupspm.html
1 <!DOCTYPE html>
2 <html>
3 <!-- SECTION: Programming -->
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">
8 <meta name="creator" content="codedoc v3.2">
9 <meta name="author" content="Michael R Sweet">
10 <meta name="copyright" content="Copyright &#xa9; 2007-2019 by Apple Inc. All Rights Reserved.">
11 <meta name="version" content="2.3.0">
12 <style type="text/css"><!--
13 body, p, h1, h2, h3, h4, h5, h6 {
14 font-family: sans-serif;
15 line-height: 1.4;
16 }
17 h1, h2, h3, h4, h5, h6 {
18 font-weight: bold;
19 page-break-inside: avoid;
20 }
21 h1 {
22 font-size: 250%;
23 margin: 0;
24 }
25 h2 {
26 font-size: 250%;
27 margin-top: 1.5em;
28 }
29 h3 {
30 font-size: 200%;
31 margin-bottom: 0.5em;
32 margin-top: 1.5em;
33 }
34 h4 {
35 font-size: 150%;
36 margin-bottom: 0.5em;
37 margin-top: 1.5em;
38 }
39 h5 {
40 font-size: 125%;
41 margin-bottom: 0.5em;
42 margin-top: 1.5em;
43 }
44 h6 {
45 font-size: 110%;
46 margin-bottom: 0.5em;
47 margin-top: 1.5em;
48 }
49 div.header h1, div.header p {
50 text-align: center;
51 }
52 div.contents, div.body, div.footer {
53 page-break-before: always;
54 }
55 .class, .enumeration, .function, .struct, .typedef, .union {
56 border-bottom: solid 2px gray;
57 }
58 .description {
59 margin-top: 0.5em;
60 }
61 .function {
62 margin-bottom: 0;
63 }
64 blockquote {
65 border: solid thin gray;
66 box-shadow: 3px 3px 5px rgba(0,0,0,0.5);
67 padding: 0px 10px;
68 page-break-inside: avoid;
69 }
70 p code, li code, p.code, pre, ul.code li {
71 font-family: monospace;
72 hyphens: manual;
73 -webkit-hyphens: manual;
74 }
75 p.code, pre, ul.code li {
76 background: rgba(127,127,127,0.1);
77 border: thin dotted gray;
78 padding: 10px;
79 page-break-inside: avoid;
80 }
81 a:link, a:visited {
82 text-decoration: none;
83 }
84 span.info {
85 background: black;
86 border: solid thin black;
87 color: white;
88 font-size: 80%;
89 font-style: italic;
90 font-weight: bold;
91 white-space: nowrap;
92 }
93 h1 span.info, h2 span.info, h3 span.info, h4 span.info {
94 border-top-left-radius: 10px;
95 border-top-right-radius: 10px;
96 float: right;
97 padding: 3px 6px;
98 }
99 ul.code, ul.contents, ul.subcontents {
100 list-style-type: none;
101 margin: 0;
102 padding-left: 0;
103 }
104 ul.code li {
105 margin: 0;
106 }
107 ul.contents > li {
108 margin-top: 1em;
109 }
110 ul.contents li ul.code, ul.contents li ul.subcontents {
111 padding-left: 2em;
112 }
113 table {
114 border-collapse: collapse;
115 border-spacing: 0;
116 }
117 td {
118 border: solid 1px #666;
119 padding: 5px 10px;
120 vertical-align: top;
121 }
122 td.left {
123 text-align: left;
124 }
125 td.center {
126 text-align: center;
127 }
128 td.right {
129 text-align: right;
130 }
131 th {
132 border-bottom: solid 2px #000;
133 padding: 1px 5px;
134 text-align: center;
135 vertical-align: bottom;
136 }
137 tr:nth-child(even) {
138 background: rgba(127,127,127,0.1);n}
139 table.list {
140 border-collapse: collapse;
141 width: 100%;
142 }
143 table.list th {
144 border-bottom: none;
145 border-right: 2px solid gray;
146 font-family: monospace;
147 padding: 5px 10px 5px 2px;
148 text-align: right;
149 vertical-align: top;
150 }
151 table.list td {
152 border: none;
153 padding: 5px 2px 5px 10px;
154 text-align: left;
155 vertical-align: top;
156 }
157 h2.title, h3.title {
158 border-bottom: solid 2px black;
159 }
160 --></style>
161 </head>
162 <body>
163 <div class="header">
164 <h1 class="title">CUPS Programming Manual</h1>
165 <p>Michael R Sweet</p>
166 <p>Copyright &#xa9; 2007-2019 by Apple Inc. All Rights Reserved.</p>
167 </div>
168 <div class="contents">
169 <h2 class="title">Contents</h2>
170 <ul class="contents">
171 <li><a href="#introduction">Introduction</a><ul class="subcontents">
172 <li><a href="#guidelines">Guidelines</a></li>
173 <li><a href="#terms-used-in-this-document">Terms Used in This Document</a></li>
174 <li><a href="#compiling-programs-that-use-the-cups-api">Compiling Programs That Use the CUPS API</a></li>
175 </ul></li>
176 <li><a href="#working-with-destinations">Working with Destinations</a><ul class="subcontents">
177 <li><a href="#finding-available-destinations">Finding Available Destinations</a></li>
178 <li><a href="#basic-destination-information">Basic Destination Information</a></li>
179 <li><a href="#detailed-destination-information">Detailed Destination Information</a></li>
180 <li><a href="#submitting-a-print-job">Submitting a Print Job</a></li>
181 </ul></li>
182 <li><a href="#sending-ipp-requests">Sending IPP Requests</a><ul class="subcontents">
183 <li><a href="#connecting-to-the-scheduler-or-printer">Connecting to the Scheduler or Printer</a></li>
184 <li><a href="#creating-an-ipp-request">Creating an IPP Request</a></li>
185 <li><a href="#sending-the-ipp-request">Sending the IPP Request</a></li>
186 <li><a href="#processing-the-ipp-response">Processing the IPP Response</a></li>
187 <li><a href="#authentication">Authentication</a></li>
188 </ul></li>
189 <li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
190 <li><a href="#cupsAddDest">cupsAddDest</a></li>
191 <li><a href="#cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></li>
192 <li><a href="#cupsAddIntegerOption">cupsAddIntegerOption</a></li>
193 <li><a href="#cupsAddOption">cupsAddOption</a></li>
194 <li><a href="#cupsCancelDestJob">cupsCancelDestJob</a></li>
195 <li><a href="#cupsCheckDestSupported">cupsCheckDestSupported</a></li>
196 <li><a href="#cupsCloseDestJob">cupsCloseDestJob</a></li>
197 <li><a href="#cupsConnectDest">cupsConnectDest</a></li>
198 <li><a href="#cupsCopyDest">cupsCopyDest</a></li>
199 <li><a href="#cupsCopyDestConflicts">cupsCopyDestConflicts</a></li>
200 <li><a href="#cupsCopyDestInfo">cupsCopyDestInfo</a></li>
201 <li><a href="#cupsCreateDestJob">cupsCreateDestJob</a></li>
202 <li><a href="#cupsDoAuthentication">cupsDoAuthentication</a></li>
203 <li><a href="#cupsEncodeOption">cupsEncodeOption</a></li>
204 <li><a href="#cupsEncodeOptions">cupsEncodeOptions</a></li>
205 <li><a href="#cupsEncodeOptions2">cupsEncodeOptions2</a></li>
206 <li><a href="#cupsEncryption">cupsEncryption</a></li>
207 <li><a href="#cupsEnumDests">cupsEnumDests</a></li>
208 <li><a href="#cupsFindDestDefault">cupsFindDestDefault</a></li>
209 <li><a href="#cupsFindDestReady">cupsFindDestReady</a></li>
210 <li><a href="#cupsFindDestSupported">cupsFindDestSupported</a></li>
211 <li><a href="#cupsFinishDestDocument">cupsFinishDestDocument</a></li>
212 <li><a href="#cupsFreeDestInfo">cupsFreeDestInfo</a></li>
213 <li><a href="#cupsFreeDests">cupsFreeDests</a></li>
214 <li><a href="#cupsFreeJobs">cupsFreeJobs</a></li>
215 <li><a href="#cupsFreeOptions">cupsFreeOptions</a></li>
216 <li><a href="#cupsGetDest">cupsGetDest</a></li>
217 <li><a href="#cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></li>
218 <li><a href="#cupsGetDestMediaByName">cupsGetDestMediaByName</a></li>
219 <li><a href="#cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></li>
220 <li><a href="#cupsGetDestMediaCount">cupsGetDestMediaCount</a></li>
221 <li><a href="#cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></li>
222 <li><a href="#cupsGetDestWithURI">cupsGetDestWithURI</a></li>
223 <li><a href="#cupsGetDests2">cupsGetDests2</a></li>
224 <li><a href="#cupsGetIntegerOption">cupsGetIntegerOption</a></li>
225 <li><a href="#cupsGetJobs2">cupsGetJobs2</a></li>
226 <li><a href="#cupsGetNamedDest">cupsGetNamedDest</a></li>
227 <li><a href="#cupsGetOption">cupsGetOption</a></li>
228 <li><a href="#cupsGetPassword2">cupsGetPassword2</a></li>
229 <li><a href="#cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></li>
230 <li><a href="#cupsLocalizeDestOption">cupsLocalizeDestOption</a></li>
231 <li><a href="#cupsLocalizeDestValue">cupsLocalizeDestValue</a></li>
232 <li><a href="#cupsMakeServerCredentials">cupsMakeServerCredentials</a></li>
233 <li><a href="#cupsParseOptions">cupsParseOptions</a></li>
234 <li><a href="#cupsRemoveDest">cupsRemoveDest</a></li>
235 <li><a href="#cupsRemoveOption">cupsRemoveOption</a></li>
236 <li><a href="#cupsServer">cupsServer</a></li>
237 <li><a href="#cupsSetClientCertCB">cupsSetClientCertCB</a></li>
238 <li><a href="#cupsSetCredentials">cupsSetCredentials</a></li>
239 <li><a href="#cupsSetDefaultDest">cupsSetDefaultDest</a></li>
240 <li><a href="#cupsSetDests2">cupsSetDests2</a></li>
241 <li><a href="#cupsSetEncryption">cupsSetEncryption</a></li>
242 <li><a href="#cupsSetPasswordCB2">cupsSetPasswordCB2</a></li>
243 <li><a href="#cupsSetServer">cupsSetServer</a></li>
244 <li><a href="#cupsSetServerCertCB">cupsSetServerCertCB</a></li>
245 <li><a href="#cupsSetServerCredentials">cupsSetServerCredentials</a></li>
246 <li><a href="#cupsSetUser">cupsSetUser</a></li>
247 <li><a href="#cupsSetUserAgent">cupsSetUserAgent</a></li>
248 <li><a href="#cupsStartDestDocument">cupsStartDestDocument</a></li>
249 <li><a href="#cupsUser">cupsUser</a></li>
250 <li><a href="#cupsUserAgent">cupsUserAgent</a></li>
251 <li><a href="#httpAcceptConnection">httpAcceptConnection</a></li>
252 <li><a href="#httpAddCredential">httpAddCredential</a></li>
253 <li><a href="#httpAddrAny">httpAddrAny</a></li>
254 <li><a href="#httpAddrClose">httpAddrClose</a></li>
255 <li><a href="#httpAddrConnect2">httpAddrConnect2</a></li>
256 <li><a href="#httpAddrCopyList">httpAddrCopyList</a></li>
257 <li><a href="#httpAddrEqual">httpAddrEqual</a></li>
258 <li><a href="#httpAddrFamily">httpAddrFamily</a></li>
259 <li><a href="#httpAddrFreeList">httpAddrFreeList</a></li>
260 <li><a href="#httpAddrGetList">httpAddrGetList</a></li>
261 <li><a href="#httpAddrLength">httpAddrLength</a></li>
262 <li><a href="#httpAddrListen">httpAddrListen</a></li>
263 <li><a href="#httpAddrLocalhost">httpAddrLocalhost</a></li>
264 <li><a href="#httpAddrLookup">httpAddrLookup</a></li>
265 <li><a href="#httpAddrPort">httpAddrPort</a></li>
266 <li><a href="#httpAddrString">httpAddrString</a></li>
267 <li><a href="#httpAssembleURI">httpAssembleURI</a></li>
268 <li><a href="#httpAssembleURIf">httpAssembleURIf</a></li>
269 <li><a href="#httpAssembleUUID">httpAssembleUUID</a></li>
270 <li><a href="#httpBlocking">httpBlocking</a></li>
271 <li><a href="#httpCheck">httpCheck</a></li>
272 <li><a href="#httpClearCookie">httpClearCookie</a></li>
273 <li><a href="#httpClearFields">httpClearFields</a></li>
274 <li><a href="#httpClose">httpClose</a></li>
275 <li><a href="#httpCompareCredentials">httpCompareCredentials</a></li>
276 <li><a href="#httpConnect2">httpConnect2</a></li>
277 <li><a href="#httpCopyCredentials">httpCopyCredentials</a></li>
278 <li><a href="#httpCredentialsAreValidForName">httpCredentialsAreValidForName</a></li>
279 <li><a href="#httpCredentialsGetExpiration">httpCredentialsGetExpiration</a></li>
280 <li><a href="#httpCredentialsGetTrust">httpCredentialsGetTrust</a></li>
281 <li><a href="#httpCredentialsString">httpCredentialsString</a></li>
282 <li><a href="#httpDecode64_2">httpDecode64_2</a></li>
283 <li><a href="#httpDelete">httpDelete</a></li>
284 <li><a href="#httpEncode64_2">httpEncode64_2</a></li>
285 <li><a href="#httpEncryption">httpEncryption</a></li>
286 <li><a href="#httpError">httpError</a></li>
287 <li><a href="#httpFieldValue">httpFieldValue</a></li>
288 <li><a href="#httpFlush">httpFlush</a></li>
289 <li><a href="#httpFlushWrite">httpFlushWrite</a></li>
290 <li><a href="#httpFreeCredentials">httpFreeCredentials</a></li>
291 <li><a href="#httpGet">httpGet</a></li>
292 <li><a href="#httpGetActivity">httpGetActivity</a></li>
293 <li><a href="#httpGetAddress">httpGetAddress</a></li>
294 <li><a href="#httpGetAuthString">httpGetAuthString</a></li>
295 <li><a href="#httpGetBlocking">httpGetBlocking</a></li>
296 <li><a href="#httpGetContentEncoding">httpGetContentEncoding</a></li>
297 <li><a href="#httpGetCookie">httpGetCookie</a></li>
298 <li><a href="#httpGetDateString2">httpGetDateString2</a></li>
299 <li><a href="#httpGetDateTime">httpGetDateTime</a></li>
300 <li><a href="#httpGetEncryption">httpGetEncryption</a></li>
301 <li><a href="#httpGetExpect">httpGetExpect</a></li>
302 <li><a href="#httpGetFd">httpGetFd</a></li>
303 <li><a href="#httpGetField">httpGetField</a></li>
304 <li><a href="#httpGetHostname">httpGetHostname</a></li>
305 <li><a href="#httpGetKeepAlive">httpGetKeepAlive</a></li>
306 <li><a href="#httpGetLength2">httpGetLength2</a></li>
307 <li><a href="#httpGetPending">httpGetPending</a></li>
308 <li><a href="#httpGetReady">httpGetReady</a></li>
309 <li><a href="#httpGetRemaining">httpGetRemaining</a></li>
310 <li><a href="#httpGetState">httpGetState</a></li>
311 <li><a href="#httpGetStatus">httpGetStatus</a></li>
312 <li><a href="#httpGetSubField2">httpGetSubField2</a></li>
313 <li><a href="#httpGetVersion">httpGetVersion</a></li>
314 <li><a href="#httpGets">httpGets</a></li>
315 <li><a href="#httpHead">httpHead</a></li>
316 <li><a href="#httpInitialize">httpInitialize</a></li>
317 <li><a href="#httpIsChunked">httpIsChunked</a></li>
318 <li><a href="#httpIsEncrypted">httpIsEncrypted</a></li>
319 <li><a href="#httpLoadCredentials">httpLoadCredentials</a></li>
320 <li><a href="#httpOptions">httpOptions</a></li>
321 <li><a href="#httpPeek">httpPeek</a></li>
322 <li><a href="#httpPost">httpPost</a></li>
323 <li><a href="#httpPut">httpPut</a></li>
324 <li><a href="#httpRead2">httpRead2</a></li>
325 <li><a href="#httpReadRequest">httpReadRequest</a></li>
326 <li><a href="#httpReconnect2">httpReconnect2</a></li>
327 <li><a href="#httpResolveHostname">httpResolveHostname</a></li>
328 <li><a href="#httpSaveCredentials">httpSaveCredentials</a></li>
329 <li><a href="#httpSeparateURI">httpSeparateURI</a></li>
330 <li><a href="#httpSetAuthString">httpSetAuthString</a></li>
331 <li><a href="#httpSetCookie">httpSetCookie</a></li>
332 <li><a href="#httpSetCredentials">httpSetCredentials</a></li>
333 <li><a href="#httpSetDefaultField">httpSetDefaultField</a></li>
334 <li><a href="#httpSetExpect">httpSetExpect</a></li>
335 <li><a href="#httpSetField">httpSetField</a></li>
336 <li><a href="#httpSetKeepAlive">httpSetKeepAlive</a></li>
337 <li><a href="#httpSetLength">httpSetLength</a></li>
338 <li><a href="#httpSetTimeout">httpSetTimeout</a></li>
339 <li><a href="#httpShutdown">httpShutdown</a></li>
340 <li><a href="#httpStateString">httpStateString</a></li>
341 <li><a href="#httpStatus">httpStatus</a></li>
342 <li><a href="#httpURIStatusString">httpURIStatusString</a></li>
343 <li><a href="#httpUpdate">httpUpdate</a></li>
344 <li><a href="#httpWait">httpWait</a></li>
345 <li><a href="#httpWrite2">httpWrite2</a></li>
346 <li><a href="#httpWriteResponse">httpWriteResponse</a></li>
347 <li><a href="#ippAddBoolean">ippAddBoolean</a></li>
348 <li><a href="#ippAddBooleans">ippAddBooleans</a></li>
349 <li><a href="#ippAddCollection">ippAddCollection</a></li>
350 <li><a href="#ippAddCollections">ippAddCollections</a></li>
351 <li><a href="#ippAddDate">ippAddDate</a></li>
352 <li><a href="#ippAddInteger">ippAddInteger</a></li>
353 <li><a href="#ippAddIntegers">ippAddIntegers</a></li>
354 <li><a href="#ippAddOctetString">ippAddOctetString</a></li>
355 <li><a href="#ippAddOutOfBand">ippAddOutOfBand</a></li>
356 <li><a href="#ippAddRange">ippAddRange</a></li>
357 <li><a href="#ippAddRanges">ippAddRanges</a></li>
358 <li><a href="#ippAddResolution">ippAddResolution</a></li>
359 <li><a href="#ippAddResolutions">ippAddResolutions</a></li>
360 <li><a href="#ippAddSeparator">ippAddSeparator</a></li>
361 <li><a href="#ippAddString">ippAddString</a></li>
362 <li><a href="#ippAddStringf">ippAddStringf</a></li>
363 <li><a href="#ippAddStringfv">ippAddStringfv</a></li>
364 <li><a href="#ippAddStrings">ippAddStrings</a></li>
365 <li><a href="#ippAttributeString">ippAttributeString</a></li>
366 <li><a href="#ippContainsInteger">ippContainsInteger</a></li>
367 <li><a href="#ippContainsString">ippContainsString</a></li>
368 <li><a href="#ippCopyAttribute">ippCopyAttribute</a></li>
369 <li><a href="#ippCopyAttributes">ippCopyAttributes</a></li>
370 <li><a href="#ippCreateRequestedArray">ippCreateRequestedArray</a></li>
371 <li><a href="#ippDateToTime">ippDateToTime</a></li>
372 <li><a href="#ippDelete">ippDelete</a></li>
373 <li><a href="#ippDeleteAttribute">ippDeleteAttribute</a></li>
374 <li><a href="#ippDeleteValues">ippDeleteValues</a></li>
375 <li><a href="#ippEnumString">ippEnumString</a></li>
376 <li><a href="#ippEnumValue">ippEnumValue</a></li>
377 <li><a href="#ippErrorString">ippErrorString</a></li>
378 <li><a href="#ippErrorValue">ippErrorValue</a></li>
379 <li><a href="#ippFindAttribute">ippFindAttribute</a></li>
380 <li><a href="#ippFindNextAttribute">ippFindNextAttribute</a></li>
381 <li><a href="#ippFirstAttribute">ippFirstAttribute</a></li>
382 <li><a href="#ippGetBoolean">ippGetBoolean</a></li>
383 <li><a href="#ippGetCollection">ippGetCollection</a></li>
384 <li><a href="#ippGetCount">ippGetCount</a></li>
385 <li><a href="#ippGetDate">ippGetDate</a></li>
386 <li><a href="#ippGetGroupTag">ippGetGroupTag</a></li>
387 <li><a href="#ippGetInteger">ippGetInteger</a></li>
388 <li><a href="#ippGetName">ippGetName</a></li>
389 <li><a href="#ippGetOctetString">ippGetOctetString</a></li>
390 <li><a href="#ippGetOperation">ippGetOperation</a></li>
391 <li><a href="#ippGetRange">ippGetRange</a></li>
392 <li><a href="#ippGetRequestId">ippGetRequestId</a></li>
393 <li><a href="#ippGetResolution">ippGetResolution</a></li>
394 <li><a href="#ippGetState">ippGetState</a></li>
395 <li><a href="#ippGetStatusCode">ippGetStatusCode</a></li>
396 <li><a href="#ippGetString">ippGetString</a></li>
397 <li><a href="#ippGetValueTag">ippGetValueTag</a></li>
398 <li><a href="#ippGetVersion">ippGetVersion</a></li>
399 <li><a href="#ippLength">ippLength</a></li>
400 <li><a href="#ippNew">ippNew</a></li>
401 <li><a href="#ippNewRequest">ippNewRequest</a></li>
402 <li><a href="#ippNewResponse">ippNewResponse</a></li>
403 <li><a href="#ippNextAttribute">ippNextAttribute</a></li>
404 <li><a href="#ippOpString">ippOpString</a></li>
405 <li><a href="#ippOpValue">ippOpValue</a></li>
406 <li><a href="#ippPort">ippPort</a></li>
407 <li><a href="#ippRead">ippRead</a></li>
408 <li><a href="#ippReadFile">ippReadFile</a></li>
409 <li><a href="#ippReadIO">ippReadIO</a></li>
410 <li><a href="#ippSetBoolean">ippSetBoolean</a></li>
411 <li><a href="#ippSetCollection">ippSetCollection</a></li>
412 <li><a href="#ippSetDate">ippSetDate</a></li>
413 <li><a href="#ippSetGroupTag">ippSetGroupTag</a></li>
414 <li><a href="#ippSetInteger">ippSetInteger</a></li>
415 <li><a href="#ippSetName">ippSetName</a></li>
416 <li><a href="#ippSetOctetString">ippSetOctetString</a></li>
417 <li><a href="#ippSetOperation">ippSetOperation</a></li>
418 <li><a href="#ippSetPort">ippSetPort</a></li>
419 <li><a href="#ippSetRange">ippSetRange</a></li>
420 <li><a href="#ippSetRequestId">ippSetRequestId</a></li>
421 <li><a href="#ippSetResolution">ippSetResolution</a></li>
422 <li><a href="#ippSetState">ippSetState</a></li>
423 <li><a href="#ippSetStatusCode">ippSetStatusCode</a></li>
424 <li><a href="#ippSetString">ippSetString</a></li>
425 <li><a href="#ippSetStringf">ippSetStringf</a></li>
426 <li><a href="#ippSetStringfv">ippSetStringfv</a></li>
427 <li><a href="#ippSetValueTag">ippSetValueTag</a></li>
428 <li><a href="#ippSetVersion">ippSetVersion</a></li>
429 <li><a href="#ippStateString">ippStateString</a></li>
430 <li><a href="#ippTagString">ippTagString</a></li>
431 <li><a href="#ippTagValue">ippTagValue</a></li>
432 <li><a href="#ippTimeToDate">ippTimeToDate</a></li>
433 <li><a href="#ippValidateAttribute">ippValidateAttribute</a></li>
434 <li><a href="#ippValidateAttributes">ippValidateAttributes</a></li>
435 <li><a href="#ippWrite">ippWrite</a></li>
436 <li><a href="#ippWriteFile">ippWriteFile</a></li>
437 <li><a href="#ippWriteIO">ippWriteIO</a></li>
438 </ul></li>
439 <li><a href="#TYPES">Data Types</a><ul class="subcontents">
440 <li><a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a></li>
441 <li><a href="#cups_dest_cb_t">cups_dest_cb_t</a></li>
442 <li><a href="#cups_dest_t">cups_dest_t</a></li>
443 <li><a href="#cups_dinfo_t">cups_dinfo_t</a></li>
444 <li><a href="#cups_job_t">cups_job_t</a></li>
445 <li><a href="#cups_option_t">cups_option_t</a></li>
446 <li><a href="#cups_password_cb2_t">cups_password_cb2_t</a></li>
447 <li><a href="#cups_ptype_t">cups_ptype_t</a></li>
448 <li><a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a></li>
449 <li><a href="#cups_size_t">cups_size_t</a></li>
450 <li><a href="#http_addr_t">http_addr_t</a></li>
451 <li><a href="#http_encoding_t">http_encoding_t</a></li>
452 <li><a href="#http_encryption_t">http_encryption_t</a></li>
453 <li><a href="#http_field_t">http_field_t</a></li>
454 <li><a href="#http_keepalive_t">http_keepalive_t</a></li>
455 <li><a href="#http_state_t">http_state_t</a></li>
456 <li><a href="#http_t">http_t</a></li>
457 <li><a href="#http_timeout_cb_t">http_timeout_cb_t</a></li>
458 <li><a href="#http_trust_t">http_trust_t</a></li>
459 <li><a href="#http_uri_coding_t">http_uri_coding_t</a></li>
460 <li><a href="#http_uri_status_t">http_uri_status_t</a></li>
461 <li><a href="#ipp_attribute_t">ipp_attribute_t</a></li>
462 <li><a href="#ipp_copycb_t">ipp_copycb_t</a></li>
463 <li><a href="#ipp_iocb_t">ipp_iocb_t</a></li>
464 <li><a href="#ipp_orient_t">ipp_orient_t</a></li>
465 <li><a href="#ipp_pstate_t">ipp_pstate_t</a></li>
466 <li><a href="#ipp_quality_t">ipp_quality_t</a></li>
467 <li><a href="#ipp_res_t">ipp_res_t</a></li>
468 <li><a href="#ipp_rstate_t">ipp_rstate_t</a></li>
469 <li><a href="#ipp_sstate_t">ipp_sstate_t</a></li>
470 <li><a href="#ipp_state_t">ipp_state_t</a></li>
471 <li><a href="#ipp_t">ipp_t</a></li>
472 </ul></li>
473 <li><a href="#STRUCTURES">Structures</a><ul class="subcontents">
474 <li><a href="#cups_dest_s">cups_dest_s</a></li>
475 <li><a href="#cups_job_s">cups_job_s</a></li>
476 <li><a href="#cups_option_s">cups_option_s</a></li>
477 <li><a href="#cups_size_s">cups_size_s</a></li>
478 </ul></li>
479 <li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents">
480 <li><a href="#cups_ptype_e">cups_ptype_e</a></li>
481 <li><a href="#http_encoding_e">http_encoding_e</a></li>
482 <li><a href="#http_encryption_e">http_encryption_e</a></li>
483 <li><a href="#http_field_e">http_field_e</a></li>
484 <li><a href="#http_keepalive_e">http_keepalive_e</a></li>
485 <li><a href="#http_state_e">http_state_e</a></li>
486 <li><a href="#http_status_e">http_status_e</a></li>
487 <li><a href="#http_trust_e">http_trust_e</a></li>
488 <li><a href="#http_uri_coding_e">http_uri_coding_e</a></li>
489 <li><a href="#http_uri_status_e">http_uri_status_e</a></li>
490 <li><a href="#ipp_finishings_e">ipp_finishings_e</a></li>
491 <li><a href="#ipp_jstate_e">ipp_jstate_e</a></li>
492 <li><a href="#ipp_op_e">ipp_op_e</a></li>
493 <li><a href="#ipp_orient_e">ipp_orient_e</a></li>
494 <li><a href="#ipp_pstate_e">ipp_pstate_e</a></li>
495 <li><a href="#ipp_quality_e">ipp_quality_e</a></li>
496 <li><a href="#ipp_res_e">ipp_res_e</a></li>
497 <li><a href="#ipp_rstate_e">ipp_rstate_e</a></li>
498 <li><a href="#ipp_sstate_e">ipp_sstate_e</a></li>
499 <li><a href="#ipp_state_e">ipp_state_e</a></li>
500 <li><a href="#ipp_status_e">ipp_status_e</a></li>
501 <li><a href="#ipp_tag_e">ipp_tag_e</a></li>
502 </ul></li>
503 </ul>
504 </div>
505 <div class="body">
506 <blockquote>
507 <p>Please <a href="https://github.com/apple/cups/issues">file issues on Github</a> to provide feedback on this document.</p>
508 </blockquote>
509 <h2 class="title" id="introduction">Introduction</h2>
510 <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>
511 <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>
512 <h3 class="title" id="guidelines">Guidelines</h3>
513 <p>When writing software (other than printer drivers) that uses the &quot;cups&quot; library:</p>
514 <ul>
515 <li> <p>Do not use undocumented or deprecated APIs,</p>
516 </li>
517 <li> <p>Do not rely on pre-configured printers,</p>
518 </li>
519 <li> <p>Do not assume that printers support specific features or formats, and</p>
520 </li>
521 <li> <p>Do not rely on implementation details (PPDs, etc.)</p>
522 </li>
523 </ul>
524 <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>
525 <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>
526 <blockquote>
527 <p><strong>Note:</strong></p>
528 <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 <a href="https://www.cups.org/documentation.html">CUPS.org</a> for more information.</p>
529 </blockquote>
530 <h3 class="title" id="terms-used-in-this-document">Terms Used in This Document</h3>
531 <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>
532 <h3 class="title" id="compiling-programs-that-use-the-cups-api">Compiling Programs That Use the CUPS API</h3>
533 <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>
534 <p>The following simple program lists the available destinations:</p>
535 <pre><code>#include &lt;stdio.h&gt;
536 #include &lt;cups/cups.h&gt;
537
538 int print_dest(void *user_data, unsigned flags, cups_dest_t *dest)
539 {
540 if (dest-&gt;instance)
541 printf(&quot;%s/%s\n&quot;, dest-&gt;name, dest-&gt;instance);
542 else
543 puts(dest-&gt;name);
544
545 return (1);
546 }
547
548 int main(void)
549 {
550 cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, 0, 0, print_dest, NULL);
551
552 return (0);
553 }
554 </code></pre>
555 <h4 id="compiling-with-xcode">Compiling with Xcode</h4>
556 <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>
557 <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>
558 <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>
559 <h4 id="compiling-with-gcc">Compiling with GCC</h4>
560 <p>From the command-line, create a file called <code>sample.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>
561 <pre><code>gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
562 ./simple
563 </code></pre>
564 <p>The <code>cups-config</code> command provides the compiler flags (<code>cups-config --cflags</code>) and libraries (<code>cups-config --libs</code>) needed for the local system.</p>
565 <h2 class="title" id="working-with-destinations">Working with Destinations</h2>
566 <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>
567 <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>
568 <h3 class="title" id="finding-available-destinations">Finding Available Destinations</h3>
569 <p>The <code>cupsEnumDests</code> function finds all of the available destinations:</p>
570 <pre><code> int
571 cupsEnumDests(unsigned flags, int msec, int *cancel,
572 cups_ptype_t type, cups_ptype_t mask,
573 cups_dest_cb_t cb, void *user_data)
574 </code></pre>
575 <p>The <code>flags</code> argument specifies enumeration options, which at present must be <code>CUPS_DEST_FLAGS_NONE</code>.</p>
576 <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>
577 <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>
578 <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_PRINTER_LOCAL</code> for the <code>type</code> argument and <code>CUPS_PRINTER_DISCOVERED</code> for the <code>mask</code> argument. The following constants can be used for filtering:</p>
579 <ul>
580 <li> <p><code>CUPS_PRINTER_CLASS</code>: A collection of destinations.</p>
581 </li>
582 <li> <p><code>CUPS_PRINTER_FAX</code>: A facsimile device.</p>
583 </li>
584 <li> <p><code>CUPS_PRINTER_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_PRINTER_REMOTE</code> or <code>CUPS_PRINTER_DISCOVERED</code> constant passed in the <code>mask</code> argument.</p>
585 </li>
586 <li> <p><code>CUPS_PRINTER_REMOTE</code>: A remote (shared) printer or class.</p>
587 </li>
588 <li> <p><code>CUPS_PRINTER_DISCOVERED</code>: An available network printer or class.</p>
589 </li>
590 <li> <p><code>CUPS_PRINTER_BW</code>: Can do B&amp;W printing.</p>
591 </li>
592 <li> <p><code>CUPS_PRINTER_COLOR</code>: Can do color printing.</p>
593 </li>
594 <li> <p><code>CUPS_PRINTER_DUPLEX</code>: Can do two-sided printing.</p>
595 </li>
596 <li> <p><code>CUPS_PRINTER_STAPLE</code>: Can staple output.</p>
597 </li>
598 <li> <p><code>CUPS_PRINTER_COLLATE</code>: Can quickly collate copies.</p>
599 </li>
600 <li> <p><code>CUPS_PRINTER_PUNCH</code>: Can punch output.</p>
601 </li>
602 <li> <p><code>CUPS_PRINTER_COVER</code>: Can cover output.</p>
603 </li>
604 <li> <p><code>CUPS_PRINTER_BIND</code>: Can bind output.</p>
605 </li>
606 <li> <p><code>CUPS_PRINTER_SORT</code>: Can sort output (mailboxes, etc.)</p>
607 </li>
608 <li> <p><code>CUPS_PRINTER_SMALL</code>: Can print on Letter/Legal/A4-size media.</p>
609 </li>
610 <li> <p><code>CUPS_PRINTER_MEDIUM</code>: Can print on Tabloid/B/C/A3/A2-size media.</p>
611 </li>
612 <li> <p><code>CUPS_PRINTER_LARGE</code>: Can print on D/E/A1/A0-size media.</p>
613 </li>
614 <li> <p><code>CUPS_PRINTER_VARIABLE</code>: Can print on rolls and custom-size media.</p>
615 </li>
616 </ul>
617 <p>The <code>cb</code> argument specifies a function to call for every destination that is found:</p>
618 <pre><code>typedef int (*cups_dest_cb_t)(void *user_data,
619 unsigned flags,
620 cups_dest_t *dest);
621 </code></pre>
622 <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>
623 <ul>
624 <li> <p><code>CUPS_DEST_FLAGS_MORE</code>: There are more destinations coming.</p>
625 </li>
626 <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>
627 </li>
628 <li> <p><code>CUPS_DEST_FLAGS_ERROR</code>: An error occurred. The reason for the error can be found by calling the <code>cupsLastError</code> and/or <code>cupsLastErrorString</code> functions.</p>
629 </li>
630 </ul>
631 <p>The callback function returns 0 to stop enumeration or 1 to continue.</p>
632 <blockquote>
633 <p><strong>Note:</strong></p>
634 <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>
635 </blockquote>
636 <p>The following example shows how to use <code>cupsEnumDests</code> to get a filtered array of destinations:</p>
637 <pre><code>typedef struct
638 {
639 int num_dests;
640 cups_dest_t *dests;
641 } my_user_data_t;
642
643 int
644 my_dest_cb(my_user_data_t *user_data, unsigned flags,
645 cups_dest_t *dest)
646 {
647 if (flags &amp; CUPS_DEST_FLAGS_REMOVED)
648 {
649 /*
650 * Remove destination from array...
651 */
652
653 user_data-&gt;num_dests =
654 cupsRemoveDest(dest-&gt;name, dest-&gt;instance,
655 user_data-&gt;num_dests,
656 &amp;(user_data-&gt;dests));
657 }
658 else
659 {
660 /*
661 * Add destination to array...
662 */
663
664 user_data-&gt;num_dests =
665 cupsCopyDest(dest, user_data-&gt;num_dests,
666 &amp;(user_data-&gt;dests));
667 }
668
669 return (1);
670 }
671
672 int
673 my_get_dests(cups_ptype_t type, cups_ptype_t mask,
674 cups_dest_t **dests)
675 {
676 my_user_data_t user_data = { 0, NULL };
677
678 if (!cupsEnumDests(CUPS_DEST_FLAGS_NONE, 1000, NULL, type,
679 mask, (cups_dest_cb_t)my_dest_cb,
680 &amp;user_data))
681 {
682 /*
683 * An error occurred, free all of the destinations and
684 * return...
685 */
686
687 cupsFreeDests(user_data.num_dests, user_dasta.dests);
688
689 *dests = NULL;
690
691 return (0);
692 }
693
694 /*
695 * Return the destination array...
696 */
697
698 *dests = user_data.dests;
699
700 return (user_data.num_dests);
701 }
702 </code></pre>
703 <h3 class="title" id="basic-destination-information">Basic Destination Information</h3>
704 <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>
705 <ul>
706 <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>
707 </li>
708 <li> <p>&quot;printer-info&quot;: The human-readable description of the destination such as &quot;My Laser Printer&quot;.</p>
709 </li>
710 <li> <p>&quot;printer-is-accepting-jobs&quot;: &quot;true&quot; if the destination is accepting new jobs, &quot;false&quot; otherwise.</p>
711 </li>
712 <li> <p>&quot;printer-is-shared&quot;: &quot;true&quot; if the destination is being shared with other computers, &quot;false&quot; otherwise.</p>
713 </li>
714 <li> <p>&quot;printer-location&quot;: The human-readable location of the destination such as &quot;Lab 4&quot;.</p>
715 </li>
716 <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>
717 </li>
718 <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>
719 </li>
720 <li> <p>&quot;printer-state-change-time&quot;: The UNIX time when the destination entered the current state.</p>
721 </li>
722 <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>
723 </li>
724 <li> <p>&quot;printer-type&quot;: The <code>cups_ptype_t</code> value associated with the destination.</p>
725 </li>
726 <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>
727 </li>
728 </ul>
729 <p>Use the <code>cupsGetOption</code> function to retrieve the value. For example, the following code gets the make and model of a destination:</p>
730 <pre><code>const char *model = cupsGetOption(&quot;printer-make-and-model&quot;,
731 dest-&gt;num_options,
732 dest-&gt;options);
733 </code></pre>
734 <h3 class="title" id="detailed-destination-information">Detailed Destination Information</h3>
735 <p>Once a destination has been chosen, the <code>cupsCopyDestInfo</code> function can be used to gather detailed information about the destination:</p>
736 <pre><code>cups_dinfo_t *
737 cupsCopyDestInfo(http_t *http, cups_dest_t *dest);
738 </code></pre>
739 <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>
740 <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>
741 <h4 id="getting-supported-options-and-values">Getting Supported Options and Values</h4>
742 <p>The <code>cupsCheckDestSupported</code> function can be used to test whether a particular option or option and value is supported:</p>
743 <pre><code>int
744 cupsCheckDestSupported(http_t *http, cups_dest_t *dest,
745 cups_dinfo_t *info,
746 const char *option,
747 const char *value);
748 </code></pre>
749 <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>
750 <ul>
751 <li> <p><code>CUPS_COPIES</code>: Controls the number of copies that are produced.</p>
752 </li>
753 <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>
754 </li>
755 <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>
756 </li>
757 <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>
758 </li>
759 <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>
760 </li>
761 <li> <p><code>CUPS_NUMBER_UP</code>: Controls the number of document pages that are placed on each media side.</p>
762 </li>
763 <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>
764 </li>
765 <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>
766 </li>
767 <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>
768 </li>
769 <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>
770 </li>
771 </ul>
772 <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>
773 <p>The <code>cupsFindDestSupported</code> function returns the IPP attribute containing the supported values for a given option:</p>
774 <pre><code> ipp_attribute_t *
775 cupsFindDestSupported(http_t *http, cups_dest_t *dest,
776 cups_dinfo_t *dinfo,
777 const char *option);
778 </code></pre>
779 <p>For example, the following code prints the supported finishing processes for a destination, if any, to the standard output:</p>
780 <pre><code>cups_dinfo_t *info = cupsCopyDestInfo(CUPS_HTTP_DEFAULT,
781 dest);
782
783 if (cupsCheckDestSupported(CUPS_HTTP_DEFAULT, dest, info,
784 CUPS_FINISHINGS, NULL))
785 {
786 ipp_attribute_t *finishings =
787 cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
788 CUPS_FINISHINGS);
789 int i, count = ippGetCount(finishings);
790
791 puts(&quot;finishings supported:&quot;);
792 for (i = 0; i &lt; count; i ++)
793 printf(&quot; %d\n&quot;, ippGetInteger(finishings, i));
794 }
795 else
796 puts(&quot;finishings not supported.&quot;);
797 </code></pre>
798 <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>
799 <pre><code>ipp_attribute_t *attrs =
800 cupsFindDestSupported(CUPS_HTTP_DEFAULT, dest, info,
801 &quot;job-creation-attributes&quot;);
802 int i, count = ippGetCount(attrs);
803
804 for (i = 0; i &lt; count; i ++)
805 puts(ippGetString(attrs, i, NULL));
806 </code></pre>
807 <h4 id="getting-default-values">Getting Default Values</h4>
808 <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 <code>cupsFindDestDefault</code> function which returns the IPP attribute containing the default value(s) for a given option:</p>
809 <pre><code>ipp_attribute_t *
810 cupsFindDestDefault(http_t *http, cups_dest_t *dest,
811 cups_dinfo_t *dinfo,
812 const char *option);
813 </code></pre>
814 <p>The user defaults from <code>cupsGetOption</code> should always take preference over the destination defaults. For example, the following code prints the default finishings value(s) to the standard output:</p>
815 <pre><code>const char *def_value =
816 cupsGetOption(CUPS_FINISHINGS, dest-&gt;num_options,
817 dest-&gt;options);
818 ipp_attribute_t *def_attr =
819 cupsFindDestDefault(CUPS_HTTP_DEFAULT, dest, info,
820 CUPS_FINISHINGS);
821
822 if (def_value != NULL)
823 {
824 printf(&quot;Default finishings: %s\n&quot;, def_value);
825 }
826 else
827 {
828 int i, count = ippGetCount(def_attr);
829
830 printf(&quot;Default finishings: %d&quot;,
831 ippGetInteger(def_attr, 0));
832 for (i = 1; i &lt; count; i ++)
833 printf(&quot;,%d&quot;, ippGetInteger(def_attr, i));
834 putchar('\n');
835 }
836 </code></pre>
837 <h4 id="getting-ready-loaded-values">Getting Ready (Loaded) Values</h4>
838 <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>
839 <p>The <code>cupsFindDestReady</code> function finds the IPP attribute containing the ready values for a given option:</p>
840 <pre><code>ipp_attribute_t *
841 cupsFindDestReady(http_t *http, cups_dest_t *dest,
842 cups_dinfo_t *dinfo, const char *option);
843 </code></pre>
844 <p>For example, the following code lists the ready finishing processes:</p>
845 <pre><code>ipp_attribute_t *ready_finishings =
846 cupsFindDestReady(CUPS_HTTP_DEFAULT, dest, info,
847 CUPS_FINISHINGS);
848
849 if (ready_finishings != NULL)
850 {
851 int i, count = ippGetCount(ready_finishings);
852
853 puts(&quot;finishings ready:&quot;);
854 for (i = 0; i &lt; count; i ++)
855 printf(&quot; %d\n&quot;, ippGetInteger(ready_finishings, i));
856 }
857 else
858 puts(&quot;no finishings are ready.&quot;);
859 </code></pre>
860 <h4 id="media-size-options">Media Size Options</h4>
861 <p>CUPS provides functions for querying the dimensions and margins for each of the supported media size options. The <code>cups_size_t</code> structure is used to describe a media size:</p>
862 <pre><code>typedef struct cups_size_s
863 {
864 char media[128];
865 int width, length;
866 int bottom, left, right, top;
867 } cups_size_t;
868 </code></pre>
869 <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>
870 <p>The <code>cupsGetDestMediaByName</code> and <code>cupsGetDestMediaBySize</code> functions lookup the media size information using a standard media size name or dimensions in hundredths of millimeters:</p>
871 <pre><code>int
872 cupsGetDestMediaByName(http_t *http, cups_dest_t *dest,
873 cups_dinfo_t *dinfo,
874 const char *media,
875 unsigned flags, cups_size_t *size);
876
877 int
878 cupsGetDestMediaBySize(http_t *http, cups_dest_t *dest,
879 cups_dinfo_t *dinfo,
880 int width, int length,
881 unsigned flags, cups_size_t *size);
882 </code></pre>
883 <p>The <code>media</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>
884 <ul>
885 <li> <p><code>CUPS_MEDIA_FLAGS_DEFAULT</code>: Find the closest size supported by the printer.</p>
886 </li>
887 <li> <p><code>CUPS_MEDIA_FLAGS_BORDERLESS</code>: Find a borderless size.</p>
888 </li>
889 <li> <p><code>CUPS_MEDIA_FLAGS_DUPLEX</code>: Find a size compatible with two-sided printing.</p>
890 </li>
891 <li> <p><code>CUPS_MEDIA_FLAGS_EXACT</code>: Find an exact match for the size.</p>
892 </li>
893 <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>
894 </li>
895 </ul>
896 <p>If a matching size is found for the destination, the size information is stored in the structure pointed to by the <code>size</code> argument and 1 is returned. Otherwise 0 is returned.</p>
897 <p>For example, the following code prints the margins for two-sided printing on US Letter media:</p>
898 <pre><code>cups_size_t size;
899
900 if (cupsGetDestMediaByName(CUPS_HTTP_DEFAULT, dest, info,
901 CUPS_MEDIA_LETTER,
902 CUPS_MEDIA_FLAGS_DUPLEX, &amp;size))
903 {
904 puts(&quot;Margins for duplex US Letter:&quot;);
905 printf(&quot; Bottom: %.2fin\n&quot;, size.bottom / 2540.0);
906 printf(&quot; Left: %.2fin\n&quot;, size.left / 2540.0);
907 printf(&quot; Right: %.2fin\n&quot;, size.right / 2540.0);
908 printf(&quot; Top: %.2fin\n&quot;, size.top / 2540.0);
909 }
910 else
911 puts(&quot;Margins for duplex US Letter are not available.&quot;);
912 </code></pre>
913 <p>You can also enumerate all of the sizes that match a given <code>flags</code> value using the <code>cupsGetDestMediaByIndex</code> and <code>cupsGetDestMediaCount</code> functions:</p>
914 <pre><code>int
915 cupsGetDestMediaByIndex(http_t *http, cups_dest_t *dest,
916 cups_dinfo_t *dinfo, int n,
917 unsigned flags, cups_size_t *size);
918
919 int
920 cupsGetDestMediaCount(http_t *http, cups_dest_t *dest,
921 cups_dinfo_t *dinfo, unsigned flags);
922 </code></pre>
923 <p>For example, the following code prints the list of ready media and corresponding margins:</p>
924 <pre><code>cups_size_t size;
925 int i;
926 int count = cupsGetDestMediaCount(CUPS_HTTP_DEFAULT,
927 dest, info,
928 CUPS_MEDIA_FLAGS_READY);
929
930 for (i = 0; i &lt; count; i ++)
931 {
932 if (cupsGetDestMediaByIndex(CUPS_HTTP_DEFAULT, dest, info,
933 i, CUPS_MEDIA_FLAGS_READY,
934 &amp;size))
935 {
936 printf(&quot;%s:\n&quot;, size.name);
937 printf(&quot; Width: %.2fin\n&quot;, size.width / 2540.0);
938 printf(&quot; Length: %.2fin\n&quot;, size.length / 2540.0);
939 printf(&quot; Bottom: %.2fin\n&quot;, size.bottom / 2540.0);
940 printf(&quot; Left: %.2fin\n&quot;, size.left / 2540.0);
941 printf(&quot; Right: %.2fin\n&quot;, size.right / 2540.0);
942 printf(&quot; Top: %.2fin\n&quot;, size.top / 2540.0);
943 }
944 }
945 </code></pre>
946 <p>Finally, the <code>cupsGetDestMediaDefault</code> function returns the default media size:</p>
947 <pre><code>int
948 cupsGetDestMediaDefault(http_t *http, cups_dest_t *dest,
949 cups_dinfo_t *dinfo, unsigned flags,
950 cups_size_t *size);
951 </code></pre>
952 <h4 id="localizing-options-and-values">Localizing Options and Values</h4>
953 <p>CUPS provides three functions to get localized, human-readable strings in the user's current locale for options and values: <code>cupsLocalizeDestMedia</code>, <code>cupsLocalizeDestOption</code>, and <code>cupsLocalizeDestValue</code>:</p>
954 <pre><code>const char *
955 cupsLocalizeDestMedia(http_t *http, cups_dest_t *dest,
956 cups_dinfo_t *info, unsigned flags,
957 cups_size_t *size);
958
959 const char *
960 cupsLocalizeDestOption(http_t *http, cups_dest_t *dest,
961 cups_dinfo_t *info,
962 const char *option);
963
964 const char *
965 cupsLocalizeDestValue(http_t *http, cups_dest_t *dest,
966 cups_dinfo_t *info,
967 const char *option, const char *value);
968 </code></pre>
969 <h3 class="title" id="submitting-a-print-job">Submitting a Print Job</h3>
970 <p>Once you are ready to submit a print job, you create a job using the <code>cupsCreateDestJob</code> function:</p>
971 <pre><code>ipp_status_t
972 cupsCreateDestJob(http_t *http, cups_dest_t *dest,
973 cups_dinfo_t *info, int *job_id,
974 const char *title, int num_options,
975 cups_option_t *options);
976 </code></pre>
977 <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>
978 <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>
979 <p>For example, the following code creates a new job that will print 42 copies of a two-sided US Letter document:</p>
980 <pre><code>int job_id = 0;
981 int num_options = 0;
982 cups_option_t *options = NULL;
983
984 num_options = cupsAddOption(CUPS_COPIES, &quot;42&quot;,
985 num_options, &amp;options);
986 num_options = cupsAddOption(CUPS_MEDIA, CUPS_MEDIA_LETTER,
987 num_options, &amp;options);
988 num_options = cupsAddOption(CUPS_SIDES,
989 CUPS_SIDES_TWO_SIDED_PORTRAIT,
990 num_options, &amp;options);
991
992 if (cupsCreateDestJob(CUPS_HTTP_DEFAULT, dest, info,
993 &amp;job_id, &quot;My Document&quot;, num_options,
994 options) == IPP_STATUS_OK)
995 printf(&quot;Created job: %d\n&quot;, job_id);
996 else
997 printf(&quot;Unable to create job: %s\n&quot;,
998 cupsLastErrorString());
999 </code></pre>
1000 <p>Once the job is created, you submit documents for the job using the <code>cupsStartDestDocument</code>, <code>cupsWriteRequestData</code>, and <code>cupsFinishDestDocument</code> functions:</p>
1001 <pre><code>http_status_t
1002 cupsStartDestDocument(http_t *http, cups_dest_t *dest,
1003 cups_dinfo_t *info, int job_id,
1004 const char *docname,
1005 const char *format,
1006 int num_options,
1007 cups_option_t *options,
1008 int last_document);
1009
1010 http_status_t
1011 cupsWriteRequestData(http_t *http, const char *buffer,
1012 size_t length);
1013
1014 ipp_status_t
1015 cupsFinishDestDocument(http_t *http, cups_dest_t *dest,
1016 cups_dinfo_t *info);
1017 </code></pre>
1018 <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>
1019 <ul>
1020 <li> <p><code>CUPS_FORMAT_JPEG</code>: &quot;image/jpeg&quot;</p>
1021 </li>
1022 <li> <p><code>CUPS_FORMAT_PDF</code>: &quot;application/pdf&quot;</p>
1023 </li>
1024 <li> <p><code>CUPS_FORMAT_POSTSCRIPT</code>: &quot;application/postscript&quot;</p>
1025 </li>
1026 <li> <p><code>CUPS_FORMAT_TEXT</code>: &quot;text/plain&quot;</p>
1027 </li>
1028 </ul>
1029 <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>
1030 <p>For example, the following code submits a PDF file to the job that was just created:</p>
1031 <pre><code>FILE *fp = fopen(&quot;filename.pdf&quot;, &quot;rb&quot;);
1032 size_t bytes;
1033 char buffer[65536];
1034
1035 if (cupsStartDestDocument(CUPS_HTTP_DEFAULT, dest, info,
1036 job_id, &quot;filename.pdf&quot;, 0, NULL,
1037 1) == HTTP_STATUS_CONTINUE)
1038 {
1039 while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) &gt; 0)
1040 if (cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer,
1041 bytes) != HTTP_STATUS_CONTINUE)
1042 break;
1043
1044 if (cupsFinishDestDocument(CUPS_HTTP_DEFAULT, dest,
1045 info) == IPP_STATUS_OK)
1046 puts(&quot;Document send succeeded.&quot;);
1047 else
1048 printf(&quot;Document send failed: %s\n&quot;,
1049 cupsLastErrorString());
1050 }
1051
1052 fclose(fp);
1053 </code></pre>
1054 <h2 class="title" id="sending-ipp-requests">Sending IPP Requests</h2>
1055 <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>
1056 <h3 class="title" id="connecting-to-the-scheduler-or-printer">Connecting to the Scheduler or Printer</h3>
1057 <p>The connection to the scheduler or printer is represented by the HTTP connection type <code>http_t</code>. The <code>cupsConnectDest</code> function connects to the scheduler or printer associated with the destination:</p>
1058 <pre><code>http_t *
1059 cupsConnectDest(cups_dest_t *dest, unsigned flags, int msec,
1060 int *cancel, char *resource,
1061 size_t resourcesize, cups_dest_cb_t cb,
1062 void *user_data);
1063 </code></pre>
1064 <p>The <code>dest</code> argument specifies the destination to connect to.</p>
1065 <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>
1066 <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>
1067 <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>
1068 <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>
1069 <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 work the same way as the one used for the <code>cupsEnumDests</code> function.</p>
1070 <p>On success, a HTTP connection is returned that can be used to send IPP requests and get IPP responses.</p>
1071 <p>For example, the following code connects to the printer associated with a destination with a 30 second timeout:</p>
1072 <pre><code>char resource[256];
1073 http_t *http = cupsConnectDest(dest, CUPS_DEST_FLAGS_DEVICE,
1074 30000, NULL, resource,
1075 sizeof(resource), NULL, NULL);
1076 </code></pre>
1077 <h3 class="title" id="creating-an-ipp-request">Creating an IPP Request</h3>
1078 <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>
1079 <p>The <code>ippNewRequest</code> function creates a new IPP request:</p>
1080 <pre><code>ipp_t *
1081 ippNewRequest(ipp_op_t op);
1082 </code></pre>
1083 <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>
1084 <pre><code>ipp_t *request = ippNewRequest(IPP_OP_GET_PRINTER_ATTRIBUTES);
1085 </code></pre>
1086 <p>The request identifier is automatically set to a unique value for the current process.</p>
1087 <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>
1088 <pre><code>const char *printer_uri = cupsGetOption(&quot;device-uri&quot;,
1089 dest-&gt;num_options,
1090 dest-&gt;options);
1091
1092 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI,
1093 &quot;printer-uri&quot;, NULL, printer_uri);
1094 </code></pre>
1095 <blockquote>
1096 <p><strong>Note:</strong></p>
1097 <p>If we wanted to query the scheduler instead of the device, we would look up the &quot;printer-uri-supported&quot; option instead of the &quot;device-uri&quot; value.</p>
1098 </blockquote>
1099 <p>The <code>ippAddString</code> function adds the &quot;printer-uri&quot; attribute the the IPP request. The <code>IPP_TAG_OPERATION</code> argument specifies that the attribute is part of the operation. The <code>IPP_TAG_URI</code> argument specifies that the value is a Universal Resource Identifier (URI) string. The <code>NULL</code> argument specifies there is no language (English, French, Japanese, etc.) associated with the string, and the <code>printer_uri</code> argument specifies the string value.</p>
1100 <p>The IPP Get-Printer-Attributes request also supports an IPP attribute called &quot;requested-attributes&quot; that lists the attributes and values you are interested in. For example, the following code requests the printer state attributes:</p>
1101 <pre><code>static const char * const requested_attributes[] =
1102 {
1103 &quot;printer-state&quot;,
1104 &quot;printer-state-message&quot;,
1105 &quot;printer-state-reasons&quot;
1106 };
1107
1108 ippAddStrings(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
1109 &quot;requested-attributes&quot;, 3, NULL,
1110 requested_attributes);
1111 </code></pre>
1112 <p>The <code>ippAddStrings</code> 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>), and the attribute will contain the three strings in the array <code>requested_attributes</code>.</p>
1113 <p>CUPS provides many functions to adding attributes of different types:</p>
1114 <ul>
1115 <li> <p><code>ippAddBoolean</code> adds a boolean (<code>IPP_TAG_BOOLEAN</code>) attribute with one value.</p>
1116 </li>
1117 <li> <p><code>ippAddInteger</code> adds an enum (<code>IPP_TAG_ENUM</code>) or integer (<code>IPP_TAG_INTEGER</code>) attribute with one value.</p>
1118 </li>
1119 <li> <p><code>ippAddIntegers</code> adds an enum or integer attribute with one or more values.</p>
1120 </li>
1121 <li> <p><code>ippAddOctetString</code> adds an octetString attribute with one value.</p>
1122 </li>
1123 <li> <p><code>ippAddOutOfBand</code> 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>
1124 </li>
1125 <li> <p><code>ippAddRange</code> adds a rangeOfInteger attribute with one range.</p>
1126 </li>
1127 <li> <p><code>ippAddRanges</code> adds a rangeOfInteger attribute with one or more ranges.</p>
1128 </li>
1129 <li> <p><code>ippAddResolution</code> adds a resolution attribute with one resolution.</p>
1130 </li>
1131 <li> <p><code>ippAddResolutions</code> adds a resolution attribute with one or more resolutions.</p>
1132 </li>
1133 <li> <p><code>ippAddString</code> 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>
1134 </li>
1135 <li> <p><code>ippAddStrings</code> adds a charset, keyword, mimeMediaType, name, naturalLanguage, text, uri, or uriScheme attribute with one or more values.</p>
1136 </li>
1137 </ul>
1138 <h3 class="title" id="sending-the-ipp-request">Sending the IPP Request</h3>
1139 <p>Once you have created the IPP request, you can send it using the <code>cupsDoRequest</code> function. For example, the following code sends the IPP Get-Printer-Attributes request to the destination and saves the response:</p>
1140 <pre><code>ipp_t *response = cupsDoRequest(http, request, resource);
1141 </code></pre>
1142 <p>For requests like Send-Document that include a file, the <code>cupsDoFileRequest</code> function should be used:</p>
1143 <pre><code>ipp_t *response = cupsDoFileRequest(http, request, resource,
1144 filename);
1145 </code></pre>
1146 <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>
1147 <p>The status from the most recent request can be queried using the <code>cupsLastError</code> function, for example:</p>
1148 <pre><code>if (cupsLastError() &gt;= IPP_STATUS_ERROR_BAD_REQUEST)
1149 {
1150 /* request failed */
1151 }
1152 </code></pre>
1153 <p>A human-readable error message is also available using the <code>cupsLastErrorString</code> function:</p>
1154 <pre><code>if (cupsLastError() &gt;= IPP_STATUS_ERROR_BAD_REQUEST)
1155 {
1156 /* request failed */
1157 printf(&quot;Request failed: %s\n&quot;, cupsLastErrorString());
1158 }
1159 </code></pre>
1160 <h3 class="title" id="processing-the-ipp-response">Processing the IPP Response</h3>
1161 <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>
1162 <p>For example, the following code finds the printer state attributes and prints their values:</p>
1163 <pre><code>ipp_attribute_t *attr;
1164
1165 if ((attr = ippFindAttribute(response, &quot;printer-state&quot;,
1166 IPP_TAG_ENUM)) != NULL)
1167 {
1168 printf(&quot;printer-state=%s\n&quot;,
1169 ippEnumString(&quot;printer-state&quot;, ippGetInteger(attr, 0)));
1170 }
1171 else
1172 puts(&quot;printer-state=unknown&quot;);
1173
1174 if ((attr = ippFindAttribute(response, &quot;printer-state-message&quot;,
1175 IPP_TAG_TEXT)) != NULL)
1176 {
1177 printf(&quot;printer-state-message=\&quot;%s\&quot;\n&quot;,
1178 ippGetString(attr, 0, NULL)));
1179 }
1180
1181 if ((attr = ippFindAttribute(response, &quot;printer-state-reasons&quot;,
1182 IPP_TAG_KEYWORD)) != NULL)
1183 {
1184 int i, count = ippGetCount(attr);
1185
1186 puts(&quot;printer-state-reasons=&quot;);
1187 for (i = 0; i &lt; count; i ++)
1188 printf(&quot; %s\n&quot;, ippGetString(attr, i, NULL)));
1189 }
1190 </code></pre>
1191 <p>The <code>ippGetCount</code> function returns the number of values in an attribute.</p>
1192 <p>The <code>ippGetInteger</code> and <code>ippGetString</code> functions return a single integer or string value from an attribute.</p>
1193 <p>The <code>ippEnumString</code> function converts a enum value to its keyword (string) equivalent.</p>
1194 <p>Once you are done using the IPP response message, free it using the <code>ippDelete</code> function:</p>
1195 <pre><code>ippDelete(response);
1196 </code></pre>
1197 <h3 class="title" id="authentication">Authentication</h3>
1198 <p>CUPS normally handles authentication through the console. GUI applications should set a password callback using the <code>cupsSetPasswordCB2</code> function:</p>
1199 <pre><code>void
1200 cupsSetPasswordCB2(cups_password_cb2_t cb, void *user_data);
1201 </code></pre>
1202 <p>The password callback will be called when needed and is responsible for setting the current user name using <code>cupsSetUser</code> and returning a string:</p>
1203 <pre><code>const char *
1204 cups_password_cb2(const char *prompt, http_t *http,
1205 const char *method, const char *resource,
1206 void *user_data);
1207 </code></pre>
1208 <p>The <code>prompt</code> argument is a string from CUPS that should be displayed to the user.</p>
1209 <p>The <code>http</code> argument is the connection hosting the request that is being authenticated. The password callback can call the <code>httpGetField</code> and <code>httpGetSubField</code> functions to look for additional details concerning the authentication challenge.</p>
1210 <p>The <code>method</code> argument specifies the HTTP method used for the request and is typically &quot;POST&quot;.</p>
1211 <p>The <code>resource</code> argument specifies the path used for the request.</p>
1212 <p>The <code>user_data</code> argument provides the user data pointer from the <code>cupsSetPasswordCB2</code> call.</p>
1213 <h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
1214 <h3 class="function"><a id="cupsAddDest">cupsAddDest</a></h3>
1215 <p class="description">Add a destination to the list of destinations.</p>
1216 <p class="code">
1217 int cupsAddDest(const char *name, const char *instance, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
1218 <h4 class="parameters">Parameters</h4>
1219 <table class="list"><tbody>
1220 <tr><th>name</th>
1221 <td class="description">Destination name</td></tr>
1222 <tr><th>instance</th>
1223 <td class="description">Instance name or <code>NULL</code> for none/primary</td></tr>
1224 <tr><th>num_dests</th>
1225 <td class="description">Number of destinations</td></tr>
1226 <tr><th>dests</th>
1227 <td class="description">Destinations</td></tr>
1228 </tbody></table>
1229 <h4 class="returnvalue">Return Value</h4>
1230 <p class="description">New number of destinations</p>
1231 <h4 class="discussion">Discussion</h4>
1232 <p class="discussion">This function cannot be used to add a new class or printer queue,
1233 it only adds a new container of saved options for the named
1234 destination or instance.<br>
1235 <br>
1236 If the named destination already exists, the destination list is
1237 returned unchanged. Adding a new instance of a destination creates
1238 a copy of that destination's options.<br>
1239 <br>
1240 Use the <a href="#cupsSaveDests"><code>cupsSaveDests</code></a> function to save the updated list of
1241 destinations to the user's lpoptions file.</p>
1242 <h3 class="function"><span class="info">&#160;CUPS 2.3/macOS 10.14&#160;</span><a id="cupsAddDestMediaOptions">cupsAddDestMediaOptions</a></h3>
1243 <p class="description">Add the option corresponding to the specified media size.</p>
1244 <p class="code">
1245 int 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, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
1246 <h4 class="parameters">Parameters</h4>
1247 <table class="list"><tbody>
1248 <tr><th>http</th>
1249 <td class="description">Connection to destination</td></tr>
1250 <tr><th>dest</th>
1251 <td class="description">Destination</td></tr>
1252 <tr><th>dinfo</th>
1253 <td class="description">Destination information</td></tr>
1254 <tr><th>flags</th>
1255 <td class="description">Media matching flags</td></tr>
1256 <tr><th>size</th>
1257 <td class="description">Media size</td></tr>
1258 <tr><th>num_options</th>
1259 <td class="description">Current number of options</td></tr>
1260 <tr><th>options</th>
1261 <td class="description">Options</td></tr>
1262 </tbody></table>
1263 <h4 class="returnvalue">Return Value</h4>
1264 <p class="description">New number of options</p>
1265 <h3 class="function"><span class="info">&#160;CUPS 2.2.4/macOS 10.13&#160;</span><a id="cupsAddIntegerOption">cupsAddIntegerOption</a></h3>
1266 <p class="description">Add an integer option to an option array.</p>
1267 <p class="code">
1268 int cupsAddIntegerOption(const char *name, int value, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
1269 <h4 class="parameters">Parameters</h4>
1270 <table class="list"><tbody>
1271 <tr><th>name</th>
1272 <td class="description">Name of option</td></tr>
1273 <tr><th>value</th>
1274 <td class="description">Value of option</td></tr>
1275 <tr><th>num_options</th>
1276 <td class="description">Number of options</td></tr>
1277 <tr><th>options</th>
1278 <td class="description">Pointer to options</td></tr>
1279 </tbody></table>
1280 <h4 class="returnvalue">Return Value</h4>
1281 <p class="description">Number of options</p>
1282 <h4 class="discussion">Discussion</h4>
1283 <p class="discussion">New option arrays can be initialized simply by passing 0 for the
1284 &quot;num_options&quot; parameter.
1285
1286 </p>
1287 <h3 class="function"><a id="cupsAddOption">cupsAddOption</a></h3>
1288 <p class="description">Add an option to an option array.</p>
1289 <p class="code">
1290 int cupsAddOption(const char *name, const char *value, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
1291 <h4 class="parameters">Parameters</h4>
1292 <table class="list"><tbody>
1293 <tr><th>name</th>
1294 <td class="description">Name of option</td></tr>
1295 <tr><th>value</th>
1296 <td class="description">Value of option</td></tr>
1297 <tr><th>num_options</th>
1298 <td class="description">Number of options</td></tr>
1299 <tr><th>options</th>
1300 <td class="description">Pointer to options</td></tr>
1301 </tbody></table>
1302 <h4 class="returnvalue">Return Value</h4>
1303 <p class="description">Number of options</p>
1304 <h4 class="discussion">Discussion</h4>
1305 <p class="discussion">New option arrays can be initialized simply by passing 0 for the
1306 &quot;num_options&quot; parameter.</p>
1307 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCancelDestJob">cupsCancelDestJob</a></h3>
1308 <p class="description">Cancel a job on a destination.</p>
1309 <p class="code">
1310 ipp_status_t cupsCancelDestJob(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> *dest, int job_id);</p>
1311 <h4 class="parameters">Parameters</h4>
1312 <table class="list"><tbody>
1313 <tr><th>http</th>
1314 <td class="description">Connection to destination</td></tr>
1315 <tr><th>dest</th>
1316 <td class="description">Destination</td></tr>
1317 <tr><th>job_id</th>
1318 <td class="description">Job ID</td></tr>
1319 </tbody></table>
1320 <h4 class="returnvalue">Return Value</h4>
1321 <p class="description">Status of cancel operation</p>
1322 <h4 class="discussion">Discussion</h4>
1323 <p class="discussion">The &quot;job_id&quot; is the number returned by cupsCreateDestJob.<br>
1324 <br>
1325 Returns <code>IPP_STATUS_OK</code> on success and
1326 <code>IPP_STATUS_ERROR_NOT_AUTHORIZED</code> or
1327 <code>IPP_STATUS_ERROR_FORBIDDEN</code> on failure.
1328
1329 </p>
1330 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCheckDestSupported">cupsCheckDestSupported</a></h3>
1331 <p class="description">Check that the option and value are supported
1332 by the destination.</p>
1333 <p class="code">
1334 int 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, const char *option, const char *value);</p>
1335 <h4 class="parameters">Parameters</h4>
1336 <table class="list"><tbody>
1337 <tr><th>http</th>
1338 <td class="description">Connection to destination</td></tr>
1339 <tr><th>dest</th>
1340 <td class="description">Destination</td></tr>
1341 <tr><th>dinfo</th>
1342 <td class="description">Destination information</td></tr>
1343 <tr><th>option</th>
1344 <td class="description">Option</td></tr>
1345 <tr><th>value</th>
1346 <td class="description">Value or <code>NULL</code></td></tr>
1347 </tbody></table>
1348 <h4 class="returnvalue">Return Value</h4>
1349 <p class="description">1 if supported, 0 otherwise</p>
1350 <h4 class="discussion">Discussion</h4>
1351 <p class="discussion">Returns 1 if supported, 0 otherwise.
1352
1353 </p>
1354 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCloseDestJob">cupsCloseDestJob</a></h3>
1355 <p class="description">Close a job and start printing.</p>
1356 <p class="code">
1357 ipp_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, int job_id);</p>
1358 <h4 class="parameters">Parameters</h4>
1359 <table class="list"><tbody>
1360 <tr><th>http</th>
1361 <td class="description">Connection to destination</td></tr>
1362 <tr><th>dest</th>
1363 <td class="description">Destination</td></tr>
1364 <tr><th>info</th>
1365 <td class="description">Destination information</td></tr>
1366 <tr><th>job_id</th>
1367 <td class="description">Job ID</td></tr>
1368 </tbody></table>
1369 <h4 class="returnvalue">Return Value</h4>
1370 <p class="description">IPP status code</p>
1371 <h4 class="discussion">Discussion</h4>
1372 <p class="discussion">Use when the last call to cupsStartDocument passed 0 for &quot;last_document&quot;.
1373 &quot;job_id&quot; is the job ID returned by cupsCreateDestJob. Returns <code>IPP_STATUS_OK</code>
1374 on success.
1375
1376 </p>
1377 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsConnectDest">cupsConnectDest</a></h3>
1378 <p class="description">Open a connection to the destination.</p>
1379 <p class="code">
1380 <a href="#http_t">http_t</a> *cupsConnectDest(<a href="#cups_dest_t">cups_dest_t</a> *dest, unsigned flags, int msec, int *cancel, char *resource, size_t resourcesize, <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb, void *user_data);</p>
1381 <h4 class="parameters">Parameters</h4>
1382 <table class="list"><tbody>
1383 <tr><th>dest</th>
1384 <td class="description">Destination</td></tr>
1385 <tr><th>flags</th>
1386 <td class="description">Connection flags</td></tr>
1387 <tr><th>msec</th>
1388 <td class="description">Timeout in milliseconds</td></tr>
1389 <tr><th>cancel</th>
1390 <td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
1391 <tr><th>resource</th>
1392 <td class="description">Resource buffer</td></tr>
1393 <tr><th>resourcesize</th>
1394 <td class="description">Size of resource buffer</td></tr>
1395 <tr><th>cb</th>
1396 <td class="description">Callback function</td></tr>
1397 <tr><th>user_data</th>
1398 <td class="description">User data pointer</td></tr>
1399 </tbody></table>
1400 <h4 class="returnvalue">Return Value</h4>
1401 <p class="description">Connection to destination or <code>NULL</code></p>
1402 <h4 class="discussion">Discussion</h4>
1403 <p class="discussion">Connect to the destination, returning a new <code>http_t</code> connection object
1404 and optionally the resource path to use for the destination. These calls
1405 will block until a connection is made, the timeout expires, the integer
1406 pointed to by &quot;cancel&quot; is non-zero, or the callback function (or block)
1407 returns 0. The caller is responsible for calling <a href="#httpClose"><code>httpClose</code></a> on the
1408 returned connection.<br>
1409 <br>
1410 Starting with CUPS 2.2.4, the caller can pass <code>CUPS_DEST_FLAGS_DEVICE</code>
1411 for the &quot;flags&quot; argument to connect directly to the device associated with
1412 the destination. Otherwise, the connection is made to the CUPS scheduler
1413 associated with the destination.
1414
1415 </p>
1416 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCopyDest">cupsCopyDest</a></h3>
1417 <p class="description">Copy a destination.</p>
1418 <p class="code">
1419 int cupsCopyDest(<a href="#cups_dest_t">cups_dest_t</a> *dest, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
1420 <h4 class="parameters">Parameters</h4>
1421 <table class="list"><tbody>
1422 <tr><th>dest</th>
1423 <td class="description">Destination to copy</td></tr>
1424 <tr><th>num_dests</th>
1425 <td class="description">Number of destinations</td></tr>
1426 <tr><th>dests</th>
1427 <td class="description">Destination array</td></tr>
1428 </tbody></table>
1429 <h4 class="returnvalue">Return Value</h4>
1430 <p class="description">New number of destinations</p>
1431 <h4 class="discussion">Discussion</h4>
1432 <p class="discussion">Make a copy of the destination to an array of destinations (or just a single
1433 copy) - for use with the cupsEnumDests* functions. The caller is responsible
1434 for calling cupsFreeDests() on the returned object(s).
1435
1436 </p>
1437 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCopyDestConflicts">cupsCopyDestConflicts</a></h3>
1438 <p class="description">Get conflicts and resolutions for a new
1439 option/value pair.</p>
1440 <p class="code">
1441 int 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, int num_options, <a href="#cups_option_t">cups_option_t</a> *options, const char *new_option, const char *new_value, int *num_conflicts, <a href="#cups_option_t">cups_option_t</a> **conflicts, int *num_resolved, <a href="#cups_option_t">cups_option_t</a> **resolved);</p>
1442 <h4 class="parameters">Parameters</h4>
1443 <table class="list"><tbody>
1444 <tr><th>http</th>
1445 <td class="description">Connection to destination</td></tr>
1446 <tr><th>dest</th>
1447 <td class="description">Destination</td></tr>
1448 <tr><th>dinfo</th>
1449 <td class="description">Destination information</td></tr>
1450 <tr><th>num_options</th>
1451 <td class="description">Number of current options</td></tr>
1452 <tr><th>options</th>
1453 <td class="description">Current options</td></tr>
1454 <tr><th>new_option</th>
1455 <td class="description">New option</td></tr>
1456 <tr><th>new_value</th>
1457 <td class="description">New value</td></tr>
1458 <tr><th>num_conflicts</th>
1459 <td class="description">Number of conflicting options</td></tr>
1460 <tr><th>conflicts</th>
1461 <td class="description">Conflicting options</td></tr>
1462 <tr><th>num_resolved</th>
1463 <td class="description">Number of options to resolve</td></tr>
1464 <tr><th>resolved</th>
1465 <td class="description">Resolved options</td></tr>
1466 </tbody></table>
1467 <h4 class="returnvalue">Return Value</h4>
1468 <p class="description">1 if there is a conflict, 0 if none, -1 on error</p>
1469 <h4 class="discussion">Discussion</h4>
1470 <p class="discussion">&quot;num_options&quot; and &quot;options&quot; represent the currently selected options by the
1471 user. &quot;new_option&quot; and &quot;new_value&quot; are the setting the user has just
1472 changed.<br>
1473 <br>
1474 Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
1475 there was an unrecoverable error such as a resolver loop.<br>
1476 <br>
1477 If &quot;num_conflicts&quot; and &quot;conflicts&quot; are not <code>NULL</code>, they are set to
1478 contain the list of conflicting option/value pairs. Similarly, if
1479 &quot;num_resolved&quot; and &quot;resolved&quot; are not <code>NULL</code> they will be set to the
1480 list of changes needed to resolve the conflict.<br>
1481 <br>
1482 If cupsCopyDestConflicts returns 1 but &quot;num_resolved&quot; and &quot;resolved&quot; are set
1483 to 0 and <code>NULL</code>, respectively, then the conflict cannot be resolved.
1484
1485 </p>
1486 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCopyDestInfo">cupsCopyDestInfo</a></h3>
1487 <p class="description">Get the supported values/capabilities for the
1488 destination.</p>
1489 <p class="code">
1490 <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>
1491 <h4 class="parameters">Parameters</h4>
1492 <table class="list"><tbody>
1493 <tr><th>http</th>
1494 <td class="description">Connection to destination</td></tr>
1495 <tr><th>dest</th>
1496 <td class="description">Destination</td></tr>
1497 </tbody></table>
1498 <h4 class="returnvalue">Return Value</h4>
1499 <p class="description">Destination information</p>
1500 <h4 class="discussion">Discussion</h4>
1501 <p class="discussion">The caller is responsible for calling <a href="#cupsFreeDestInfo"><code>cupsFreeDestInfo</code></a> on the return
1502 value. <code>NULL</code> is returned on error.
1503
1504 </p>
1505 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsCreateDestJob">cupsCreateDestJob</a></h3>
1506 <p class="description">Create a job on a destination.</p>
1507 <p class="code">
1508 ipp_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, int *job_id, const char *title, int num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
1509 <h4 class="parameters">Parameters</h4>
1510 <table class="list"><tbody>
1511 <tr><th>http</th>
1512 <td class="description">Connection to destination</td></tr>
1513 <tr><th>dest</th>
1514 <td class="description">Destination</td></tr>
1515 <tr><th>info</th>
1516 <td class="description">Destination information</td></tr>
1517 <tr><th>job_id</th>
1518 <td class="description">Job ID or 0 on error</td></tr>
1519 <tr><th>title</th>
1520 <td class="description">Job name</td></tr>
1521 <tr><th>num_options</th>
1522 <td class="description">Number of job options</td></tr>
1523 <tr><th>options</th>
1524 <td class="description">Job options</td></tr>
1525 </tbody></table>
1526 <h4 class="returnvalue">Return Value</h4>
1527 <p class="description">IPP status code</p>
1528 <h4 class="discussion">Discussion</h4>
1529 <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success, saving the job ID
1530 in the variable pointed to by &quot;job_id&quot;.
1531
1532 </p>
1533 <h3 class="function"><span class="info">&#160;CUPS 1.1.20/macOS 10.4&#160;</span><a id="cupsDoAuthentication">cupsDoAuthentication</a></h3>
1534 <p class="description">Authenticate a request.</p>
1535 <p class="code">
1536 int cupsDoAuthentication(<a href="#http_t">http_t</a> *http, const char *method, const char *resource);</p>
1537 <h4 class="parameters">Parameters</h4>
1538 <table class="list"><tbody>
1539 <tr><th>http</th>
1540 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
1541 <tr><th>method</th>
1542 <td class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</td></tr>
1543 <tr><th>resource</th>
1544 <td class="description">Resource path</td></tr>
1545 </tbody></table>
1546 <h4 class="returnvalue">Return Value</h4>
1547 <p class="description">0 on success, -1 on error</p>
1548 <h4 class="discussion">Discussion</h4>
1549 <p class="discussion">This function should be called in response to a <code>HTTP_STATUS_UNAUTHORIZED</code>
1550 status, prior to resubmitting your request.
1551
1552 </p>
1553 <h3 class="function"><span class="info">&#160;CUPS 2.3/macOS 10.14&#160;</span><a id="cupsEncodeOption">cupsEncodeOption</a></h3>
1554 <p class="description">Encode a single option into an IPP attribute.</p>
1555 <p class="code">
1556 <a href="#ipp_attribute_t">ipp_attribute_t</a> *cupsEncodeOption(<a href="#ipp_t">ipp_t</a> *ipp, ipp_tag_t group_tag, const char *name, const char *value);</p>
1557 <h4 class="parameters">Parameters</h4>
1558 <table class="list"><tbody>
1559 <tr><th>ipp</th>
1560 <td class="description">IPP request/response</td></tr>
1561 <tr><th>group_tag</th>
1562 <td class="description">Attribute group</td></tr>
1563 <tr><th>name</th>
1564 <td class="description">Option name</td></tr>
1565 <tr><th>value</th>
1566 <td class="description">Option string value</td></tr>
1567 </tbody></table>
1568 <h4 class="returnvalue">Return Value</h4>
1569 <p class="description">New attribute or <code>NULL</code> on error</p>
1570 <h3 class="function"><a id="cupsEncodeOptions">cupsEncodeOptions</a></h3>
1571 <p class="description">Encode printer options into IPP attributes.</p>
1572 <p class="code">
1573 void cupsEncodeOptions(<a href="#ipp_t">ipp_t</a> *ipp, int num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
1574 <h4 class="parameters">Parameters</h4>
1575 <table class="list"><tbody>
1576 <tr><th>ipp</th>
1577 <td class="description">IPP request/response</td></tr>
1578 <tr><th>num_options</th>
1579 <td class="description">Number of options</td></tr>
1580 <tr><th>options</th>
1581 <td class="description">Options</td></tr>
1582 </tbody></table>
1583 <h4 class="discussion">Discussion</h4>
1584 <p class="discussion">This function adds operation, job, and then subscription attributes,
1585 in that order. Use the <a href="#cupsEncodeOptions2"><code>cupsEncodeOptions2</code></a> function to add attributes
1586 for a single group.</p>
1587 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsEncodeOptions2">cupsEncodeOptions2</a></h3>
1588 <p class="description">Encode printer options into IPP attributes for a group.</p>
1589 <p class="code">
1590 void cupsEncodeOptions2(<a href="#ipp_t">ipp_t</a> *ipp, int num_options, <a href="#cups_option_t">cups_option_t</a> *options, ipp_tag_t group_tag);</p>
1591 <h4 class="parameters">Parameters</h4>
1592 <table class="list"><tbody>
1593 <tr><th>ipp</th>
1594 <td class="description">IPP request/response</td></tr>
1595 <tr><th>num_options</th>
1596 <td class="description">Number of options</td></tr>
1597 <tr><th>options</th>
1598 <td class="description">Options</td></tr>
1599 <tr><th>group_tag</th>
1600 <td class="description">Group to encode</td></tr>
1601 </tbody></table>
1602 <h4 class="discussion">Discussion</h4>
1603 <p class="discussion">This function only adds attributes for a single group. Call this
1604 function multiple times for each group, or use <a href="#cupsEncodeOptions"><code>cupsEncodeOptions</code></a>
1605 to add the standard groups.
1606
1607 </p>
1608 <h3 class="function"><a id="cupsEncryption">cupsEncryption</a></h3>
1609 <p class="description">Get the current encryption settings.</p>
1610 <p class="code">
1611 <a href="#http_encryption_t">http_encryption_t</a> cupsEncryption(void);</p>
1612 <h4 class="returnvalue">Return Value</h4>
1613 <p class="description">Encryption settings</p>
1614 <h4 class="discussion">Discussion</h4>
1615 <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
1616 environment variable, then the ~/.cups/client.conf file, and finally the
1617 /etc/cups/client.conf file. If not set, the default is
1618 <code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
1619 <br>
1620 Note: The current encryption setting is tracked separately for each thread
1621 in a program. Multi-threaded programs that override the setting via the
1622 <a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same
1623 setting to be used.</p>
1624 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsEnumDests">cupsEnumDests</a></h3>
1625 <p class="description">Enumerate available destinations with a callback function.</p>
1626 <p class="code">
1627 int cupsEnumDests(unsigned flags, int msec, int *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, void *user_data);</p>
1628 <h4 class="parameters">Parameters</h4>
1629 <table class="list"><tbody>
1630 <tr><th>flags</th>
1631 <td class="description">Enumeration flags</td></tr>
1632 <tr><th>msec</th>
1633 <td class="description">Timeout in milliseconds, -1 for indefinite</td></tr>
1634 <tr><th>cancel</th>
1635 <td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
1636 <tr><th>type</th>
1637 <td class="description">Printer type bits</td></tr>
1638 <tr><th>mask</th>
1639 <td class="description">Mask for printer type bits</td></tr>
1640 <tr><th>cb</th>
1641 <td class="description">Callback function</td></tr>
1642 <tr><th>user_data</th>
1643 <td class="description">User data</td></tr>
1644 </tbody></table>
1645 <h4 class="returnvalue">Return Value</h4>
1646 <p class="description">1 on success, 0 on failure</p>
1647 <h4 class="discussion">Discussion</h4>
1648 <p class="discussion">Destinations are enumerated from one or more sources. The callback function
1649 receives the <code>user_data</code> pointer and the destination pointer which can
1650 be used as input to the <a href="#cupsCopyDest"><code>cupsCopyDest</code></a> function. The function must
1651 return 1 to continue enumeration or 0 to stop.<br>
1652 <br>
1653 The <code>type</code> and <code>mask</code> arguments allow the caller to filter the
1654 destinations that are enumerated. Passing 0 for both will enumerate all
1655 printers. The constant <code>CUPS_PRINTER_DISCOVERED</code> is used to filter on
1656 destinations that are available but have not yet been added locally.<br>
1657 <br>
1658 Enumeration happens on the current thread and does not return until all
1659 destinations have been enumerated or the callback function returns 0.<br>
1660 <br>
1661 Note: The callback function will likely receive multiple updates for the same
1662 destinations - it is up to the caller to suppress any duplicate destinations.
1663
1664 </p>
1665 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestDefault">cupsFindDestDefault</a></h3>
1666 <p class="description">Find the default value(s) for the given option.</p>
1667 <p class="code">
1668 <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, const char *option);</p>
1669 <h4 class="parameters">Parameters</h4>
1670 <table class="list"><tbody>
1671 <tr><th>http</th>
1672 <td class="description">Connection to destination</td></tr>
1673 <tr><th>dest</th>
1674 <td class="description">Destination</td></tr>
1675 <tr><th>dinfo</th>
1676 <td class="description">Destination information</td></tr>
1677 <tr><th>option</th>
1678 <td class="description">Option/attribute name</td></tr>
1679 </tbody></table>
1680 <h4 class="returnvalue">Return Value</h4>
1681 <p class="description">Default attribute or <code>NULL</code> for none</p>
1682 <h4 class="discussion">Discussion</h4>
1683 <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1684 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1685 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1686 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1687 functions to inspect the default value(s) as needed.
1688
1689 </p>
1690 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestReady">cupsFindDestReady</a></h3>
1691 <p class="description">Find the default value(s) for the given option.</p>
1692 <p class="code">
1693 <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, const char *option);</p>
1694 <h4 class="parameters">Parameters</h4>
1695 <table class="list"><tbody>
1696 <tr><th>http</th>
1697 <td class="description">Connection to destination</td></tr>
1698 <tr><th>dest</th>
1699 <td class="description">Destination</td></tr>
1700 <tr><th>dinfo</th>
1701 <td class="description">Destination information</td></tr>
1702 <tr><th>option</th>
1703 <td class="description">Option/attribute name</td></tr>
1704 </tbody></table>
1705 <h4 class="returnvalue">Return Value</h4>
1706 <p class="description">Default attribute or <code>NULL</code> for none</p>
1707 <h4 class="discussion">Discussion</h4>
1708 <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1709 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1710 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1711 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1712 functions to inspect the default value(s) as needed.
1713
1714 </p>
1715 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsFindDestSupported">cupsFindDestSupported</a></h3>
1716 <p class="description">Find the default value(s) for the given option.</p>
1717 <p class="code">
1718 <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, const char *option);</p>
1719 <h4 class="parameters">Parameters</h4>
1720 <table class="list"><tbody>
1721 <tr><th>http</th>
1722 <td class="description">Connection to destination</td></tr>
1723 <tr><th>dest</th>
1724 <td class="description">Destination</td></tr>
1725 <tr><th>dinfo</th>
1726 <td class="description">Destination information</td></tr>
1727 <tr><th>option</th>
1728 <td class="description">Option/attribute name</td></tr>
1729 </tbody></table>
1730 <h4 class="returnvalue">Return Value</h4>
1731 <p class="description">Default attribute or <code>NULL</code> for none</p>
1732 <h4 class="discussion">Discussion</h4>
1733 <p class="discussion">The returned value is an IPP attribute. Use the <code>ippGetBoolean</code>,
1734 <code>ippGetCollection</code>, <code>ippGetCount</code>, <code>ippGetDate</code>,
1735 <code>ippGetInteger</code>, <code>ippGetOctetString</code>, <code>ippGetRange</code>,
1736 <code>ippGetResolution</code>, <code>ippGetString</code>, and <code>ippGetValueTag</code>
1737 functions to inspect the default value(s) as needed.
1738
1739 </p>
1740 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsFinishDestDocument">cupsFinishDestDocument</a></h3>
1741 <p class="description">Finish the current document.</p>
1742 <p class="code">
1743 ipp_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>
1744 <h4 class="parameters">Parameters</h4>
1745 <table class="list"><tbody>
1746 <tr><th>http</th>
1747 <td class="description">Connection to destination</td></tr>
1748 <tr><th>dest</th>
1749 <td class="description">Destination</td></tr>
1750 <tr><th>info</th>
1751 <td class="description">Destination information</td></tr>
1752 </tbody></table>
1753 <h4 class="returnvalue">Return Value</h4>
1754 <p class="description">Status of document submission</p>
1755 <h4 class="discussion">Discussion</h4>
1756 <p class="discussion">Returns <code>IPP_STATUS_OK</code> or <code>IPP_STATUS_OK_SUBST</code> on success.
1757
1758 </p>
1759 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsFreeDestInfo">cupsFreeDestInfo</a></h3>
1760 <p class="description">Free destination information obtained using
1761 <a href="#cupsCopyDestInfo"><code>cupsCopyDestInfo</code></a>.</p>
1762 <p class="code">
1763 void cupsFreeDestInfo(<a href="#cups_dinfo_t">cups_dinfo_t</a> *dinfo);</p>
1764 <h4 class="parameters">Parameters</h4>
1765 <table class="list"><tbody>
1766 <tr><th>dinfo</th>
1767 <td class="description">Destination information</td></tr>
1768 </tbody></table>
1769 <h3 class="function"><a id="cupsFreeDests">cupsFreeDests</a></h3>
1770 <p class="description">Free the memory used by the list of destinations.</p>
1771 <p class="code">
1772 void cupsFreeDests(int num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
1773 <h4 class="parameters">Parameters</h4>
1774 <table class="list"><tbody>
1775 <tr><th>num_dests</th>
1776 <td class="description">Number of destinations</td></tr>
1777 <tr><th>dests</th>
1778 <td class="description">Destinations</td></tr>
1779 </tbody></table>
1780 <h3 class="function"><a id="cupsFreeJobs">cupsFreeJobs</a></h3>
1781 <p class="description">Free memory used by job data.</p>
1782 <p class="code">
1783 void cupsFreeJobs(int num_jobs, <a href="#cups_job_t">cups_job_t</a> *jobs);</p>
1784 <h4 class="parameters">Parameters</h4>
1785 <table class="list"><tbody>
1786 <tr><th>num_jobs</th>
1787 <td class="description">Number of jobs</td></tr>
1788 <tr><th>jobs</th>
1789 <td class="description">Jobs</td></tr>
1790 </tbody></table>
1791 <h3 class="function"><a id="cupsFreeOptions">cupsFreeOptions</a></h3>
1792 <p class="description">Free all memory used by options.</p>
1793 <p class="code">
1794 void cupsFreeOptions(int num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
1795 <h4 class="parameters">Parameters</h4>
1796 <table class="list"><tbody>
1797 <tr><th>num_options</th>
1798 <td class="description">Number of options</td></tr>
1799 <tr><th>options</th>
1800 <td class="description">Pointer to options</td></tr>
1801 </tbody></table>
1802 <h3 class="function"><a id="cupsGetDest">cupsGetDest</a></h3>
1803 <p class="description">Get the named destination from the list.</p>
1804 <p class="code">
1805 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDest(const char *name, const char *instance, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
1806 <h4 class="parameters">Parameters</h4>
1807 <table class="list"><tbody>
1808 <tr><th>name</th>
1809 <td class="description">Destination name or <code>NULL</code> for the default destination</td></tr>
1810 <tr><th>instance</th>
1811 <td class="description">Instance name or <code>NULL</code></td></tr>
1812 <tr><th>num_dests</th>
1813 <td class="description">Number of destinations</td></tr>
1814 <tr><th>dests</th>
1815 <td class="description">Destinations</td></tr>
1816 </tbody></table>
1817 <h4 class="returnvalue">Return Value</h4>
1818 <p class="description">Destination pointer or <code>NULL</code></p>
1819 <h4 class="discussion">Discussion</h4>
1820 <p class="discussion">Use the <a href="#cupsEnumDests"><code>cupsEnumDests</code></a> or <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> functions to get a
1821 list of supported destinations for the current user.</p>
1822 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaByIndex">cupsGetDestMediaByIndex</a></h3>
1823 <p class="description">Get a media name, dimension, and margins for a
1824 specific size.</p>
1825 <p class="code">
1826 int 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, int n, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
1827 <h4 class="parameters">Parameters</h4>
1828 <table class="list"><tbody>
1829 <tr><th>http</th>
1830 <td class="description">Connection to destination</td></tr>
1831 <tr><th>dest</th>
1832 <td class="description">Destination</td></tr>
1833 <tr><th>dinfo</th>
1834 <td class="description">Destination information</td></tr>
1835 <tr><th>n</th>
1836 <td class="description">Media size number (0-based)</td></tr>
1837 <tr><th>flags</th>
1838 <td class="description">Media flags</td></tr>
1839 <tr><th>size</th>
1840 <td class="description">Media size information</td></tr>
1841 </tbody></table>
1842 <h4 class="returnvalue">Return Value</h4>
1843 <p class="description">1 on success, 0 on failure</p>
1844 <h4 class="discussion">Discussion</h4>
1845 <p class="discussion">The <code>flags</code> parameter determines which set of media are indexed. For
1846 example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will get the Nth
1847 borderless size supported by the printer.
1848
1849 </p>
1850 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsGetDestMediaByName">cupsGetDestMediaByName</a></h3>
1851 <p class="description">Get media names, dimensions, and margins.</p>
1852 <p class="code">
1853 int 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, const char *media, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
1854 <h4 class="parameters">Parameters</h4>
1855 <table class="list"><tbody>
1856 <tr><th>http</th>
1857 <td class="description">Connection to destination</td></tr>
1858 <tr><th>dest</th>
1859 <td class="description">Destination</td></tr>
1860 <tr><th>dinfo</th>
1861 <td class="description">Destination information</td></tr>
1862 <tr><th>media</th>
1863 <td class="description">Media name</td></tr>
1864 <tr><th>flags</th>
1865 <td class="description">Media matching flags</td></tr>
1866 <tr><th>size</th>
1867 <td class="description">Media size information</td></tr>
1868 </tbody></table>
1869 <h4 class="returnvalue">Return Value</h4>
1870 <p class="description">1 on match, 0 on failure</p>
1871 <h4 class="discussion">Discussion</h4>
1872 <p class="discussion">The &quot;media&quot; string is a PWG media name. &quot;Flags&quot; provides some matching
1873 guidance (multiple flags can be combined):<br>
1874 <br>
1875 CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
1876 CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
1877 CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
1878 CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
1879 CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
1880 size amongst the &quot;ready&quot; media.<br>
1881 <br>
1882 The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
1883 <br>
1884 Returns 1 when there is a match and 0 if there is not a match.
1885
1886 </p>
1887 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsGetDestMediaBySize">cupsGetDestMediaBySize</a></h3>
1888 <p class="description">Get media names, dimensions, and margins.</p>
1889 <p class="code">
1890 int 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, int width, int length, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
1891 <h4 class="parameters">Parameters</h4>
1892 <table class="list"><tbody>
1893 <tr><th>http</th>
1894 <td class="description">Connection to destination</td></tr>
1895 <tr><th>dest</th>
1896 <td class="description">Destination</td></tr>
1897 <tr><th>dinfo</th>
1898 <td class="description">Destination information</td></tr>
1899 <tr><th>width</th>
1900 <td class="description">Media width in hundredths of
1901 of millimeters</td></tr>
1902 <tr><th>length</th>
1903 <td class="description">Media length in hundredths of
1904 of millimeters</td></tr>
1905 <tr><th>flags</th>
1906 <td class="description">Media matching flags</td></tr>
1907 <tr><th>size</th>
1908 <td class="description">Media size information</td></tr>
1909 </tbody></table>
1910 <h4 class="returnvalue">Return Value</h4>
1911 <p class="description">1 on match, 0 on failure</p>
1912 <h4 class="discussion">Discussion</h4>
1913 <p class="discussion">&quot;Width&quot; and &quot;length&quot; are the dimensions in hundredths of millimeters.
1914 &quot;Flags&quot; provides some matching guidance (multiple flags can be combined):<br>
1915 <br>
1916 CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
1917 CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
1918 CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
1919 CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
1920 CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
1921 size amongst the &quot;ready&quot; media.<br>
1922 <br>
1923 The matching result (if any) is returned in the &quot;cups_size_t&quot; structure.<br>
1924 <br>
1925 Returns 1 when there is a match and 0 if there is not a match.
1926
1927 </p>
1928 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaCount">cupsGetDestMediaCount</a></h3>
1929 <p class="description">Get the number of sizes supported by a
1930 destination.</p>
1931 <p class="code">
1932 int 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, unsigned flags);</p>
1933 <h4 class="parameters">Parameters</h4>
1934 <table class="list"><tbody>
1935 <tr><th>http</th>
1936 <td class="description">Connection to destination</td></tr>
1937 <tr><th>dest</th>
1938 <td class="description">Destination</td></tr>
1939 <tr><th>dinfo</th>
1940 <td class="description">Destination information</td></tr>
1941 <tr><th>flags</th>
1942 <td class="description">Media flags</td></tr>
1943 </tbody></table>
1944 <h4 class="returnvalue">Return Value</h4>
1945 <p class="description">Number of sizes</p>
1946 <h4 class="discussion">Discussion</h4>
1947 <p class="discussion">The <code>flags</code> parameter determines the set of media sizes that are
1948 counted. For example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return
1949 the number of borderless sizes.
1950
1951 </p>
1952 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsGetDestMediaDefault">cupsGetDestMediaDefault</a></h3>
1953 <p class="description">Get the default size for a destination.</p>
1954 <p class="code">
1955 int 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, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
1956 <h4 class="parameters">Parameters</h4>
1957 <table class="list"><tbody>
1958 <tr><th>http</th>
1959 <td class="description">Connection to destination</td></tr>
1960 <tr><th>dest</th>
1961 <td class="description">Destination</td></tr>
1962 <tr><th>dinfo</th>
1963 <td class="description">Destination information</td></tr>
1964 <tr><th>flags</th>
1965 <td class="description">Media flags</td></tr>
1966 <tr><th>size</th>
1967 <td class="description">Media size information</td></tr>
1968 </tbody></table>
1969 <h4 class="returnvalue">Return Value</h4>
1970 <p class="description">1 on success, 0 on failure</p>
1971 <h4 class="discussion">Discussion</h4>
1972 <p class="discussion">The <code>flags</code> parameter determines which default size is returned. For
1973 example, passing <code>CUPS_MEDIA_FLAGS_BORDERLESS</code> will return the default
1974 borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
1975
1976 </p>
1977 <h3 class="function"><span class="info">&#160;CUPS 2.0/macOS 10.10&#160;</span><a id="cupsGetDestWithURI">cupsGetDestWithURI</a></h3>
1978 <p class="description">Get a destination associated with a URI.</p>
1979 <p class="code">
1980 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetDestWithURI(const char *name, const char *uri);</p>
1981 <h4 class="parameters">Parameters</h4>
1982 <table class="list"><tbody>
1983 <tr><th>name</th>
1984 <td class="description">Desired printer name or <code>NULL</code></td></tr>
1985 <tr><th>uri</th>
1986 <td class="description">URI for the printer</td></tr>
1987 </tbody></table>
1988 <h4 class="returnvalue">Return Value</h4>
1989 <p class="description">Destination or <code>NULL</code></p>
1990 <h4 class="discussion">Discussion</h4>
1991 <p class="discussion">&quot;name&quot; is the desired name for the printer. If <code>NULL</code>, a name will be
1992 created using the URI.<br>
1993 <br>
1994 &quot;uri&quot; is the &quot;ipp&quot; or &quot;ipps&quot; URI for the printer.
1995
1996 </p>
1997 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsGetDests2">cupsGetDests2</a></h3>
1998 <p class="description">Get the list of destinations from the specified server.</p>
1999 <p class="code">
2000 int cupsGetDests2(<a href="#http_t">http_t</a> *http, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
2001 <h4 class="parameters">Parameters</h4>
2002 <table class="list"><tbody>
2003 <tr><th>http</th>
2004 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
2005 <tr><th>dests</th>
2006 <td class="description">Destinations</td></tr>
2007 </tbody></table>
2008 <h4 class="returnvalue">Return Value</h4>
2009 <p class="description">Number of destinations</p>
2010 <h4 class="discussion">Discussion</h4>
2011 <p class="discussion">Starting with CUPS 1.2, the returned list of destinations include the
2012 &quot;printer-info&quot;, &quot;printer-is-accepting-jobs&quot;, &quot;printer-is-shared&quot;,
2013 &quot;printer-make-and-model&quot;, &quot;printer-state&quot;, &quot;printer-state-change-time&quot;,
2014 &quot;printer-state-reasons&quot;, &quot;printer-type&quot;, and &quot;printer-uri-supported&quot;
2015 attributes as options.<br>
2016 <br>
2017 CUPS 1.4 adds the &quot;marker-change-time&quot;, &quot;marker-colors&quot;,
2018 &quot;marker-high-levels&quot;, &quot;marker-levels&quot;, &quot;marker-low-levels&quot;, &quot;marker-message&quot;,
2019 &quot;marker-names&quot;, &quot;marker-types&quot;, and &quot;printer-commands&quot; attributes as options.<br>
2020 <br>
2021 CUPS 2.2 adds accessible IPP printers to the list of destinations that can
2022 be used. The &quot;printer-uri-supported&quot; option will be present for those IPP
2023 printers that have been recently used.<br>
2024 <br>
2025 Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and
2026 the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.
2027
2028 </p>
2029 <h3 class="function"><span class="info">&#160;CUPS 2.2.4/macOS 10.13&#160;</span><a id="cupsGetIntegerOption">cupsGetIntegerOption</a></h3>
2030 <p class="description">Get an integer option value.</p>
2031 <p class="code">
2032 int cupsGetIntegerOption(const char *name, int num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
2033 <h4 class="parameters">Parameters</h4>
2034 <table class="list"><tbody>
2035 <tr><th>name</th>
2036 <td class="description">Name of option</td></tr>
2037 <tr><th>num_options</th>
2038 <td class="description">Number of options</td></tr>
2039 <tr><th>options</th>
2040 <td class="description">Options</td></tr>
2041 </tbody></table>
2042 <h4 class="returnvalue">Return Value</h4>
2043 <p class="description">Option value or <code>INT_MIN</code></p>
2044 <h4 class="discussion">Discussion</h4>
2045 <p class="discussion">INT_MIN is returned when the option does not exist, is not an integer, or
2046 exceeds the range of values for the &quot;int&quot; type.
2047
2048 </p>
2049 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsGetJobs2">cupsGetJobs2</a></h3>
2050 <p class="description">Get the jobs from the specified server.</p>
2051 <p class="code">
2052 int cupsGetJobs2(<a href="#http_t">http_t</a> *http, <a href="#cups_job_t">cups_job_t</a> **jobs, const char *name, int myjobs, int whichjobs);</p>
2053 <h4 class="parameters">Parameters</h4>
2054 <table class="list"><tbody>
2055 <tr><th>http</th>
2056 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
2057 <tr><th>jobs</th>
2058 <td class="description">Job data</td></tr>
2059 <tr><th>name</th>
2060 <td class="description"><code>NULL</code> = all destinations, otherwise show jobs for named destination</td></tr>
2061 <tr><th>myjobs</th>
2062 <td class="description">0 = all users, 1 = mine</td></tr>
2063 <tr><th>whichjobs</th>
2064 <td class="description"><code>CUPS_WHICHJOBS_ALL</code>, <code>CUPS_WHICHJOBS_ACTIVE</code>, or <code>CUPS_WHICHJOBS_COMPLETED</code></td></tr>
2065 </tbody></table>
2066 <h4 class="returnvalue">Return Value</h4>
2067 <p class="description">Number of jobs</p>
2068 <h4 class="discussion">Discussion</h4>
2069 <p class="discussion">A &quot;whichjobs&quot; value of <code>CUPS_WHICHJOBS_ALL</code> returns all jobs regardless
2070 of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are
2071 pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns
2072 jobs that are stopped, canceled, aborted, or completed.
2073
2074 </p>
2075 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetNamedDest">cupsGetNamedDest</a></h3>
2076 <p class="description">Get options for the named destination.</p>
2077 <p class="code">
2078 <a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest(<a href="#http_t">http_t</a> *http, const char *name, const char *instance);</p>
2079 <h4 class="parameters">Parameters</h4>
2080 <table class="list"><tbody>
2081 <tr><th>http</th>
2082 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
2083 <tr><th>name</th>
2084 <td class="description">Destination name or <code>NULL</code> for the default destination</td></tr>
2085 <tr><th>instance</th>
2086 <td class="description">Instance name or <code>NULL</code></td></tr>
2087 </tbody></table>
2088 <h4 class="returnvalue">Return Value</h4>
2089 <p class="description">Destination or <code>NULL</code></p>
2090 <h4 class="discussion">Discussion</h4>
2091 <p class="discussion">This function is optimized for retrieving a single destination and should
2092 be used instead of <a href="#cupsGetDests2"><code>cupsGetDests2</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> when you
2093 either know the name of the destination or want to print to the default
2094 destination. If <code>NULL</code> is returned, the destination does not exist or
2095 there is no default destination.<br>
2096 <br>
2097 If &quot;http&quot; is <code>CUPS_HTTP_DEFAULT</code>, the connection to the default print
2098 server will be used.<br>
2099 <br>
2100 If &quot;name&quot; is <code>NULL</code>, the default printer for the current user will be
2101 returned.<br>
2102 <br>
2103 The returned destination must be freed using <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> with a
2104 &quot;num_dests&quot; value of 1.
2105
2106 </p>
2107 <h3 class="function"><a id="cupsGetOption">cupsGetOption</a></h3>
2108 <p class="description">Get an option value.</p>
2109 <p class="code">
2110 const char *cupsGetOption(const char *name, int num_options, <a href="#cups_option_t">cups_option_t</a> *options);</p>
2111 <h4 class="parameters">Parameters</h4>
2112 <table class="list"><tbody>
2113 <tr><th>name</th>
2114 <td class="description">Name of option</td></tr>
2115 <tr><th>num_options</th>
2116 <td class="description">Number of options</td></tr>
2117 <tr><th>options</th>
2118 <td class="description">Options</td></tr>
2119 </tbody></table>
2120 <h4 class="returnvalue">Return Value</h4>
2121 <p class="description">Option value or <code>NULL</code></p>
2122 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsGetPassword2">cupsGetPassword2</a></h3>
2123 <p class="description">Get a password from the user using the current
2124 password callback.</p>
2125 <p class="code">
2126 const char *cupsGetPassword2(const char *prompt, <a href="#http_t">http_t</a> *http, const char *method, const char *resource);</p>
2127 <h4 class="parameters">Parameters</h4>
2128 <table class="list"><tbody>
2129 <tr><th>prompt</th>
2130 <td class="description">Prompt string</td></tr>
2131 <tr><th>http</th>
2132 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
2133 <tr><th>method</th>
2134 <td class="description">Request method (&quot;GET&quot;, &quot;POST&quot;, &quot;PUT&quot;)</td></tr>
2135 <tr><th>resource</th>
2136 <td class="description">Resource path</td></tr>
2137 </tbody></table>
2138 <h4 class="returnvalue">Return Value</h4>
2139 <p class="description">Password</p>
2140 <h4 class="discussion">Discussion</h4>
2141 <p class="discussion">Uses the current password callback function. Returns <code>NULL</code> if the
2142 user does not provide a password.<br>
2143 <br>
2144 Note: The current password callback function is tracked separately for each
2145 thread in a program. Multi-threaded programs that override the setting via
2146 the <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> function need to do so in each thread for the
2147 same function to be used.
2148
2149 </p>
2150 <h3 class="function"><span class="info">&#160;CUPS 2.0/macOS 10.10&#160;</span><a id="cupsLocalizeDestMedia">cupsLocalizeDestMedia</a></h3>
2151 <p class="description">Get the localized string for a destination media
2152 size.</p>
2153 <p class="code">
2154 const char *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, unsigned flags, <a href="#cups_size_t">cups_size_t</a> *size);</p>
2155 <h4 class="parameters">Parameters</h4>
2156 <table class="list"><tbody>
2157 <tr><th>http</th>
2158 <td class="description">Connection to destination</td></tr>
2159 <tr><th>dest</th>
2160 <td class="description">Destination</td></tr>
2161 <tr><th>dinfo</th>
2162 <td class="description">Destination information</td></tr>
2163 <tr><th>flags</th>
2164 <td class="description">Media flags</td></tr>
2165 <tr><th>size</th>
2166 <td class="description">Media size</td></tr>
2167 </tbody></table>
2168 <h4 class="returnvalue">Return Value</h4>
2169 <p class="description">Localized string</p>
2170 <h4 class="discussion">Discussion</h4>
2171 <p class="discussion">The returned string is stored in the destination information and will become
2172 invalid if the destination information is deleted.
2173
2174 </p>
2175 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsLocalizeDestOption">cupsLocalizeDestOption</a></h3>
2176 <p class="description">Get the localized string for a destination
2177 option.</p>
2178 <p class="code">
2179 const char *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, const char *option);</p>
2180 <h4 class="parameters">Parameters</h4>
2181 <table class="list"><tbody>
2182 <tr><th>http</th>
2183 <td class="description">Connection to destination</td></tr>
2184 <tr><th>dest</th>
2185 <td class="description">Destination</td></tr>
2186 <tr><th>dinfo</th>
2187 <td class="description">Destination information</td></tr>
2188 <tr><th>option</th>
2189 <td class="description">Option to localize</td></tr>
2190 </tbody></table>
2191 <h4 class="returnvalue">Return Value</h4>
2192 <p class="description">Localized string</p>
2193 <h4 class="discussion">Discussion</h4>
2194 <p class="discussion">The returned string is stored in the destination information and will become
2195 invalid if the destination information is deleted.
2196
2197 </p>
2198 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsLocalizeDestValue">cupsLocalizeDestValue</a></h3>
2199 <p class="description">Get the localized string for a destination
2200 option+value pair.</p>
2201 <p class="code">
2202 const char *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, const char *option, const char *value);</p>
2203 <h4 class="parameters">Parameters</h4>
2204 <table class="list"><tbody>
2205 <tr><th>http</th>
2206 <td class="description">Connection to destination</td></tr>
2207 <tr><th>dest</th>
2208 <td class="description">Destination</td></tr>
2209 <tr><th>dinfo</th>
2210 <td class="description">Destination information</td></tr>
2211 <tr><th>option</th>
2212 <td class="description">Option to localize</td></tr>
2213 <tr><th>value</th>
2214 <td class="description">Value to localize</td></tr>
2215 </tbody></table>
2216 <h4 class="returnvalue">Return Value</h4>
2217 <p class="description">Localized string</p>
2218 <h4 class="discussion">Discussion</h4>
2219 <p class="discussion">The returned string is stored in the destination information and will become
2220 invalid if the destination information is deleted.
2221
2222 </p>
2223 <h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="cupsMakeServerCredentials">cupsMakeServerCredentials</a></h3>
2224 <p class="description">Make a self-signed certificate and private key pair.</p>
2225 <p class="code">
2226 int cupsMakeServerCredentials(const char *path, const char *common_name, int num_alt_names, const char **alt_names, time_t expiration_date);</p>
2227 <h4 class="parameters">Parameters</h4>
2228 <table class="list"><tbody>
2229 <tr><th>path</th>
2230 <td class="description">Keychain path or <code>NULL</code> for default</td></tr>
2231 <tr><th>common_name</th>
2232 <td class="description">Common name</td></tr>
2233 <tr><th>num_alt_names</th>
2234 <td class="description">Number of subject alternate names</td></tr>
2235 <tr><th>alt_names</th>
2236 <td class="description">Subject Alternate Names</td></tr>
2237 <tr><th>expiration_date</th>
2238 <td class="description">Expiration date</td></tr>
2239 </tbody></table>
2240 <h4 class="returnvalue">Return Value</h4>
2241 <p class="description">1 on success, 0 on failure</p>
2242 <h3 class="function"><a id="cupsParseOptions">cupsParseOptions</a></h3>
2243 <p class="description">Parse options from a command-line argument.</p>
2244 <p class="code">
2245 int cupsParseOptions(const char *arg, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
2246 <h4 class="parameters">Parameters</h4>
2247 <table class="list"><tbody>
2248 <tr><th>arg</th>
2249 <td class="description">Argument to parse</td></tr>
2250 <tr><th>num_options</th>
2251 <td class="description">Number of options</td></tr>
2252 <tr><th>options</th>
2253 <td class="description">Options found</td></tr>
2254 </tbody></table>
2255 <h4 class="returnvalue">Return Value</h4>
2256 <p class="description">Number of options found</p>
2257 <h4 class="discussion">Discussion</h4>
2258 <p class="discussion">This function converts space-delimited name/value pairs according
2259 to the PAPI text option ABNF specification. Collection values
2260 (&quot;name={a=... b=... c=...}&quot;) are stored with the curley brackets
2261 intact - use <code>cupsParseOptions</code> on the value to extract the
2262 collection attributes.</p>
2263 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsRemoveDest">cupsRemoveDest</a></h3>
2264 <p class="description">Remove a destination from the destination list.</p>
2265 <p class="code">
2266 int cupsRemoveDest(const char *name, const char *instance, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> **dests);</p>
2267 <h4 class="parameters">Parameters</h4>
2268 <table class="list"><tbody>
2269 <tr><th>name</th>
2270 <td class="description">Destination name</td></tr>
2271 <tr><th>instance</th>
2272 <td class="description">Instance name or <code>NULL</code></td></tr>
2273 <tr><th>num_dests</th>
2274 <td class="description">Number of destinations</td></tr>
2275 <tr><th>dests</th>
2276 <td class="description">Destinations</td></tr>
2277 </tbody></table>
2278 <h4 class="returnvalue">Return Value</h4>
2279 <p class="description">New number of destinations</p>
2280 <h4 class="discussion">Discussion</h4>
2281 <p class="discussion">Removing a destination/instance does not delete the class or printer
2282 queue, merely the lpoptions for that destination/instance. Use the
2283 <a href="#cupsSetDests"><code>cupsSetDests</code></a> or <a href="#cupsSetDests2"><code>cupsSetDests2</code></a> functions to save the new
2284 options for the user.
2285
2286 </p>
2287 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="cupsRemoveOption">cupsRemoveOption</a></h3>
2288 <p class="description">Remove an option from an option array.</p>
2289 <p class="code">
2290 int cupsRemoveOption(const char *name, int num_options, <a href="#cups_option_t">cups_option_t</a> **options);</p>
2291 <h4 class="parameters">Parameters</h4>
2292 <table class="list"><tbody>
2293 <tr><th>name</th>
2294 <td class="description">Option name</td></tr>
2295 <tr><th>num_options</th>
2296 <td class="description">Current number of options</td></tr>
2297 <tr><th>options</th>
2298 <td class="description">Options</td></tr>
2299 </tbody></table>
2300 <h4 class="returnvalue">Return Value</h4>
2301 <p class="description">New number of options</p>
2302 <h3 class="function"><a id="cupsServer">cupsServer</a></h3>
2303 <p class="description">Return the hostname/address of the current server.</p>
2304 <p class="code">
2305 const char *cupsServer(void);</p>
2306 <h4 class="returnvalue">Return Value</h4>
2307 <p class="description">Server name</p>
2308 <h4 class="discussion">Discussion</h4>
2309 <p class="discussion">The default server comes from the CUPS_SERVER environment variable, then the
2310 ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
2311 set, the default is the local system - either &quot;localhost&quot; or a domain socket
2312 path.<br>
2313 <br>
2314 The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
2315 address, or a domain socket pathname.<br>
2316 <br>
2317 Note: The current server is tracked separately for each thread in a program.
2318 Multi-threaded programs that override the server via the
2319 <a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same
2320 server to be used.</p>
2321 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetClientCertCB">cupsSetClientCertCB</a></h3>
2322 <p class="description">Set the client certificate callback.</p>
2323 <p class="code">
2324 void cupsSetClientCertCB(<a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb, void *user_data);</p>
2325 <h4 class="parameters">Parameters</h4>
2326 <table class="list"><tbody>
2327 <tr><th>cb</th>
2328 <td class="description">Callback function</td></tr>
2329 <tr><th>user_data</th>
2330 <td class="description">User data pointer</td></tr>
2331 </tbody></table>
2332 <h4 class="discussion">Discussion</h4>
2333 <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
2334 <br>
2335 Note: The current certificate callback is tracked separately for each thread
2336 in a program. Multi-threaded programs that override the callback need to do
2337 so in each thread for the same callback to be used.
2338
2339 </p>
2340 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetCredentials">cupsSetCredentials</a></h3>
2341 <p class="description">Set the default credentials to be used for SSL/TLS
2342 connections.</p>
2343 <p class="code">
2344 int cupsSetCredentials(cups_array_t *credentials);</p>
2345 <h4 class="parameters">Parameters</h4>
2346 <table class="list"><tbody>
2347 <tr><th>credentials</th>
2348 <td class="description">Array of credentials</td></tr>
2349 </tbody></table>
2350 <h4 class="returnvalue">Return Value</h4>
2351 <p class="description">Status of call (0 = success)</p>
2352 <h4 class="discussion">Discussion</h4>
2353 <p class="discussion">Note: The default credentials are tracked separately for each thread in a
2354 program. Multi-threaded programs that override the setting need to do so in
2355 each thread for the same setting to be used.
2356
2357 </p>
2358 <h3 class="function"><span class="info">&#160;CUPS 1.3/macOS 10.5&#160;</span><a id="cupsSetDefaultDest">cupsSetDefaultDest</a></h3>
2359 <p class="description">Set the default destination.</p>
2360 <p class="code">
2361 void cupsSetDefaultDest(const char *name, const char *instance, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
2362 <h4 class="parameters">Parameters</h4>
2363 <table class="list"><tbody>
2364 <tr><th>name</th>
2365 <td class="description">Destination name</td></tr>
2366 <tr><th>instance</th>
2367 <td class="description">Instance name or <code>NULL</code></td></tr>
2368 <tr><th>num_dests</th>
2369 <td class="description">Number of destinations</td></tr>
2370 <tr><th>dests</th>
2371 <td class="description">Destinations</td></tr>
2372 </tbody></table>
2373 <h3 class="function"><span class="info">&#160;CUPS 1.1.21/macOS 10.4&#160;</span><a id="cupsSetDests2">cupsSetDests2</a></h3>
2374 <p class="description">Save the list of destinations for the specified server.</p>
2375 <p class="code">
2376 int cupsSetDests2(<a href="#http_t">http_t</a> *http, int num_dests, <a href="#cups_dest_t">cups_dest_t</a> *dests);</p>
2377 <h4 class="parameters">Parameters</h4>
2378 <table class="list"><tbody>
2379 <tr><th>http</th>
2380 <td class="description">Connection to server or <code>CUPS_HTTP_DEFAULT</code></td></tr>
2381 <tr><th>num_dests</th>
2382 <td class="description">Number of destinations</td></tr>
2383 <tr><th>dests</th>
2384 <td class="description">Destinations</td></tr>
2385 </tbody></table>
2386 <h4 class="returnvalue">Return Value</h4>
2387 <p class="description">0 on success, -1 on error</p>
2388 <h4 class="discussion">Discussion</h4>
2389 <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run
2390 as root and ~/.cups/lpoptions when run as a normal user.
2391
2392 </p>
2393 <h3 class="function"><a id="cupsSetEncryption">cupsSetEncryption</a></h3>
2394 <p class="description">Set the encryption preference.</p>
2395 <p class="code">
2396 void cupsSetEncryption(<a href="#http_encryption_t">http_encryption_t</a> e);</p>
2397 <h4 class="parameters">Parameters</h4>
2398 <table class="list"><tbody>
2399 <tr><th>e</th>
2400 <td class="description">New encryption preference</td></tr>
2401 </tbody></table>
2402 <h4 class="discussion">Discussion</h4>
2403 <p class="discussion">The default encryption setting comes from the CUPS_ENCRYPTION
2404 environment variable, then the ~/.cups/client.conf file, and finally the
2405 /etc/cups/client.conf file. If not set, the default is
2406 <code>HTTP_ENCRYPTION_IF_REQUESTED</code>.<br>
2407 <br>
2408 Note: The current encryption setting is tracked separately for each thread
2409 in a program. Multi-threaded programs that override the setting need to do
2410 so in each thread for the same setting to be used.</p>
2411 <h3 class="function"><span class="info">&#160;CUPS 1.4/macOS 10.6&#160;</span><a id="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3>
2412 <p class="description">Set the advanced password callback for CUPS.</p>
2413 <p class="code">
2414 void cupsSetPasswordCB2(<a href="#cups_password_cb2_t">cups_password_cb2_t</a> cb, void *user_data);</p>
2415 <h4 class="parameters">Parameters</h4>
2416 <table class="list"><tbody>
2417 <tr><th>cb</th>
2418 <td class="description">Callback function</td></tr>
2419 <tr><th>user_data</th>
2420 <td class="description">User data pointer</td></tr>
2421 </tbody></table>
2422 <h4 class="discussion">Discussion</h4>
2423 <p class="discussion">Pass <code>NULL</code> to restore the default (console) password callback, which
2424 reads the password from the console. Programs should call either this
2425 function or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a>, as only one callback can be registered
2426 by a program per thread.<br>
2427 <br>
2428 Note: The current password callback is tracked separately for each thread
2429 in a program. Multi-threaded programs that override the callback need to do
2430 so in each thread for the same callback to be used.
2431
2432 </p>
2433 <h3 class="function"><a id="cupsSetServer">cupsSetServer</a></h3>
2434 <p class="description">Set the default server name and port.</p>
2435 <p class="code">
2436 void cupsSetServer(const char *server);</p>
2437 <h4 class="parameters">Parameters</h4>
2438 <table class="list"><tbody>
2439 <tr><th>server</th>
2440 <td class="description">Server name</td></tr>
2441 </tbody></table>
2442 <h4 class="discussion">Discussion</h4>
2443 <p class="discussion">The &quot;server&quot; string can be a fully-qualified hostname, a numeric
2444 IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
2445 addresses can be optionally followed by a colon and port number to override
2446 the default port 631, e.g. &quot;hostname:8631&quot;. Pass <code>NULL</code> to restore the
2447 default server name and port.<br>
2448 <br>
2449 Note: The current server is tracked separately for each thread in a program.
2450 Multi-threaded programs that override the server need to do so in each
2451 thread for the same server to be used.</p>
2452 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="cupsSetServerCertCB">cupsSetServerCertCB</a></h3>
2453 <p class="description">Set the server certificate callback.</p>
2454 <p class="code">
2455 void cupsSetServerCertCB(<a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb, void *user_data);</p>
2456 <h4 class="parameters">Parameters</h4>
2457 <table class="list"><tbody>
2458 <tr><th>cb</th>
2459 <td class="description">Callback function</td></tr>
2460 <tr><th>user_data</th>
2461 <td class="description">User data pointer</td></tr>
2462 </tbody></table>
2463 <h4 class="discussion">Discussion</h4>
2464 <p class="discussion">Pass <code>NULL</code> to restore the default callback.<br>
2465 <br>
2466 Note: The current credentials callback is tracked separately for each thread
2467 in a program. Multi-threaded programs that override the callback need to do
2468 so in each thread for the same callback to be used.
2469
2470 </p>
2471 <h3 class="function"><span class="info">&#160;CUPS 2.0/macOS 10.10&#160;</span><a id="cupsSetServerCredentials">cupsSetServerCredentials</a></h3>
2472 <p class="description">Set the default server credentials.</p>
2473 <p class="code">
2474 int cupsSetServerCredentials(const char *path, const char *common_name, int auto_create);</p>
2475 <h4 class="parameters">Parameters</h4>
2476 <table class="list"><tbody>
2477 <tr><th>path</th>
2478 <td class="description">Keychain path or <code>NULL</code> for default</td></tr>
2479 <tr><th>common_name</th>
2480 <td class="description">Default common name for server</td></tr>
2481 <tr><th>auto_create</th>
2482 <td class="description">1 = automatically create self-signed certificates</td></tr>
2483 </tbody></table>
2484 <h4 class="returnvalue">Return Value</h4>
2485 <p class="description">1 on success, 0 on failure</p>
2486 <h4 class="discussion">Discussion</h4>
2487 <p class="discussion">Note: The server credentials are used by all threads in the running process.
2488 This function is threadsafe.
2489
2490 </p>
2491 <h3 class="function"><a id="cupsSetUser">cupsSetUser</a></h3>
2492 <p class="description">Set the default user name.</p>
2493 <p class="code">
2494 void cupsSetUser(const char *user);</p>
2495 <h4 class="parameters">Parameters</h4>
2496 <table class="list"><tbody>
2497 <tr><th>user</th>
2498 <td class="description">User name</td></tr>
2499 </tbody></table>
2500 <h4 class="discussion">Discussion</h4>
2501 <p class="discussion">Pass <code>NULL</code> to restore the default user name.<br>
2502 <br>
2503 Note: The current user name is tracked separately for each thread in a
2504 program. Multi-threaded programs that override the user name need to do so
2505 in each thread for the same user name to be used.</p>
2506 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsSetUserAgent">cupsSetUserAgent</a></h3>
2507 <p class="description">Set the default HTTP User-Agent string.</p>
2508 <p class="code">
2509 void cupsSetUserAgent(const char *user_agent);</p>
2510 <h4 class="parameters">Parameters</h4>
2511 <table class="list"><tbody>
2512 <tr><th>user_agent</th>
2513 <td class="description">User-Agent string or <code>NULL</code></td></tr>
2514 </tbody></table>
2515 <h4 class="discussion">Discussion</h4>
2516 <p class="discussion">Setting the string to NULL forces the default value containing the CUPS
2517 version, IPP version, and operating system version and architecture.
2518
2519 </p>
2520 <h3 class="function"><span class="info">&#160;CUPS 1.6/macOS 10.8&#160;</span><a id="cupsStartDestDocument">cupsStartDestDocument</a></h3>
2521 <p class="description">Start a new document.</p>
2522 <p class="code">
2523 http_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, int job_id, const char *docname, const char *format, int num_options, <a href="#cups_option_t">cups_option_t</a> *options, int last_document);</p>
2524 <h4 class="parameters">Parameters</h4>
2525 <table class="list"><tbody>
2526 <tr><th>http</th>
2527 <td class="description">Connection to destination</td></tr>
2528 <tr><th>dest</th>
2529 <td class="description">Destination</td></tr>
2530 <tr><th>info</th>
2531 <td class="description">Destination information</td></tr>
2532 <tr><th>job_id</th>
2533 <td class="description">Job ID</td></tr>
2534 <tr><th>docname</th>
2535 <td class="description">Document name</td></tr>
2536 <tr><th>format</th>
2537 <td class="description">Document format</td></tr>
2538 <tr><th>num_options</th>
2539 <td class="description">Number of document options</td></tr>
2540 <tr><th>options</th>
2541 <td class="description">Document options</td></tr>
2542 <tr><th>last_document</th>
2543 <td class="description">1 if this is the last document</td></tr>
2544 </tbody></table>
2545 <h4 class="returnvalue">Return Value</h4>
2546 <p class="description">Status of document creation</p>
2547 <h4 class="discussion">Discussion</h4>
2548 <p class="discussion">&quot;job_id&quot; is the job ID returned by cupsCreateDestJob. &quot;docname&quot; is the name
2549 of the document/file being printed, &quot;format&quot; is the MIME media type for the
2550 document (see CUPS_FORMAT_xxx constants), and &quot;num_options&quot; and &quot;options&quot;
2551 are the options do be applied to the document. &quot;last_document&quot; should be 1
2552 if this is the last document to be submitted in the job. Returns
2553 <code>HTTP_CONTINUE</code> on success.
2554
2555 </p>
2556 <h3 class="function"><a id="cupsUser">cupsUser</a></h3>
2557 <p class="description">Return the current user's name.</p>
2558 <p class="code">
2559 const char *cupsUser(void);</p>
2560 <h4 class="returnvalue">Return Value</h4>
2561 <p class="description">User name</p>
2562 <h4 class="discussion">Discussion</h4>
2563 <p class="discussion">Note: The current user name is tracked separately for each thread in a
2564 program. Multi-threaded programs that override the user name with the
2565 <a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user
2566 name to be used.</p>
2567 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="cupsUserAgent">cupsUserAgent</a></h3>
2568 <p class="description">Return the default HTTP User-Agent string.</p>
2569 <p class="code">
2570 const char *cupsUserAgent(void);</p>
2571 <h4 class="returnvalue">Return Value</h4>
2572 <p class="description">User-Agent string</p>
2573 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="httpAcceptConnection">httpAcceptConnection</a></h3>
2574 <p class="description">Accept a new HTTP client connection from the
2575 specified listening socket.</p>
2576 <p class="code">
2577 <a href="#http_t">http_t</a> *httpAcceptConnection(int fd, int blocking);</p>
2578 <h4 class="parameters">Parameters</h4>
2579 <table class="list"><tbody>
2580 <tr><th>fd</th>
2581 <td class="description">Listen socket file descriptor</td></tr>
2582 <tr><th>blocking</th>
2583 <td class="description">1 if the connection should be
2584 blocking, 0 otherwise</td></tr>
2585 </tbody></table>
2586 <h4 class="returnvalue">Return Value</h4>
2587 <p class="description">HTTP connection or <code>NULL</code></p>
2588 <h3 class="function"><span class="info">&#160;CUPS 1.5/macOS 10.7&#160;</span><a id="httpAddCredential">httpAddCredential</a></h3>
2589 <p class="description">Allocates and adds a single credential to an array.</p>
2590 <p class="code">
2591 int httpAddCredential(cups_array_t *credentials, const void *data, size_t datalen);</p>
2592 <h4 class="parameters">Parameters</h4>
2593 <table class="list"><tbody>
2594 <tr><th>credentials</th>
2595 <td class="description">Credentials array</td></tr>
2596 <tr><th>data</th>
2597 <td class="description">PEM-encoded X.509 data</td></tr>
2598 <tr><th>datalen</th>
2599 <td class="description">Length of data</td></tr>
2600 </tbody></table>
2601 <h4 class="returnvalue">Return Value</h4>
2602 <p class="description">0 on success, -1 on error</p>
2603 <h4 class="discussion">Discussion</h4>
2604 <p class="discussion">Use <code>cupsArrayNew(NULL, NULL)</code> to create a credentials array.
2605
2606 </p>
2607 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="httpAddrAny">httpAddrAny</a></h3>
2608 <p class="description">Check for the &quot;any&quot; address.</p>
2609 <p class="code">
2610 int httpAddrAny(const <a href="#http_addr_t">http_addr_t</a> *addr);</p>
2611 <h4 class="parameters">Parameters</h4>
2612 <table class="list"><tbody>
2613 <tr><th>addr</th>
2614 <td class="description">Address to check</td></tr>
2615 </tbody></table>
2616 <h4 class="returnvalue">Return Value</h4>
2617 <p class="description">1 if &quot;any&quot;, 0 otherwise</p>
2618 <h3 class="function"><span class="info">&#160;CUPS 2.0/OS 10.10&#160;</span><a id="httpAddrClose">httpAddrClose</a></h3>
2619 <p class="description">Close a socket created by <a href="#httpAddrConnect"><code>httpAddrConnect</code></a> or
2620 <a href="#httpAddrListen"><code>httpAddrListen</code></a>.</p>
2621 <p class="code">
2622 int httpAddrClose(<a href="#http_addr_t">http_addr_t</a> *addr, int fd);</p>
2623 <h4 class="parameters">Parameters</h4>
2624 <table class="list"><tbody>
2625 <tr><th>addr</th>
2626 <td class="description">Listen address or <code>NULL</code></td></tr>
2627 <tr><th>fd</th>
2628 <td class="description">Socket file descriptor</td></tr>
2629 </tbody></table>
2630 <h4 class="returnvalue">Return Value</h4>
2631 <p class="description">0 on success, -1 on failure</p>
2632 <h4 class="discussion">Discussion</h4>
2633 <p class="discussion">Pass <code>NULL</code> for sockets created with <a href="#httpAddrConnect2"><code>httpAddrConnect2</code></a> and the
2634 listen address for sockets created with <a href="#httpAddrListen"><code>httpAddrListen</code></a>. This function
2635 ensures that domain sockets are removed when closed.
2636
2637 </p>
2638 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="httpAddrConnect2">httpAddrConnect2</a></h3>
2639 <p class="description">Connect to any of the addresses in the list with a
2640 timeout and optional cancel.</p>
2641 <p class="code">
2642 <a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrConnect2(<a href="#http_addrlist_t">http_addrlist_t</a> *addrlist, int *sock, int msec, int *cancel);</p>
2643 <h4 class="parameters">Parameters</h4>
2644 <table class="list"><tbody>
2645 <tr><th>addrlist</th>
2646 <td class="description">List of potential addresses</td></tr>
2647 <tr><th>sock</th>
2648 <td class="description">Socket</td></tr>
2649 <tr><th>msec</th>
2650 <td class="description">Timeout in milliseconds</td></tr>
2651 <tr><th>cancel</th>
2652 <td class="description">Pointer to &quot;cancel&quot; variable</td></tr>
2653 </tbody></table>
2654 <h4 class="returnvalue">Return Value</h4>
2655 <p class="description">Connected address or NULL on failure</p>
2656 <h3 class="function"><span class="info">&#160;CUPS 1.7/macOS 10.9&#160;</span><a id="httpAddrCopyList">httpAddrCopyList</a></h3>
2657 <p class="description">Copy an address list.</p>
2658 <p class="code">
2659 <a href="#http_addrlist_t">http_addrlist_t</a> *httpAddrCopyList(<a href="#http_addrlist_t">http_addrlist_t</a> *src);</p>
2660 <h4 class="parameters">Parameters</h4>
2661 <table class="list"><tbody>
2662 <tr><th>src</th>
2663 <td class="description">Source address list</td></tr>
2664 </tbody></table>
2665 <h4 class="returnvalue">Return Value</h4>
2666 <p class="description">New address list or <code>NULL</code> on error</p>
2667 <h3 class="function"><span class="info">&#160;CUPS 1.2/macOS 10.5&#160;</span><a id="httpAddrEqual">httpAddrEqual</a></h3>
2668 <p class="description">Compare two addresses.</p>
2669 <p class="code">
2670 int httpAddrEqual(const <a href="#http_addr_t">http_addr_t</a> *addr1, const <a href="#http_addr_t">http_addr_t</a> *addr2);</p>
2671 <h4 class="parameters">Parameters</h4>
2672 <table class="list"><tbody>
2673 <tr><th>addr1</th>
2674 <td class="description">First address</td></tr>
2675 <tr><th>addr2</th>
2676 <td class="description">Second address</td></tr>
2677 </tbody></table>
2678 <h4 class="returnvalue">Return Value</h4>
2679 <p class=