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