1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- SECTION: Programming --> 4<head> 5 <title>CGI API </title> 6 <meta name="keywords" content="Programming"> 7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 8 <meta name="creator" content="Mini-XML v2.7"> 9<style type="text/css"><!-- 10BODY { 11 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 12} 13 14H1, H2, H3, H4, H5, H6, P, TD, TH { 15 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 16} 17 18KBD { 19 font-family: monaco, courier, monospace; 20 font-weight: bold; 21} 22 23PRE { 24 font-family: monaco, courier, monospace; 25} 26 27PRE.command { 28 border: dotted thin #7f7f7f; 29 margin-left: 36pt; 30 padding: 10px; 31} 32 33P.compact { 34 margin: 0; 35} 36 37P.example { 38 font-style: italic; 39 margin-left: 36pt; 40} 41 42DL.man DD { 43 margin-left: 5em; 44} 45 46DL.man DT { 47 margin-left: 0; 48} 49 50PRE.man { 51 margin: 0; 52} 53 54PRE.example { 55 background: #eeeeee; 56 border: dotted thin #999999; 57 margin-left: 36pt; 58 padding: 10pt; 59} 60 61PRE.command EM, PRE.example EM { 62 font-family: lucida grande, geneva, helvetica, arial, sans-serif; 63} 64 65P.command { 66 font-family: monaco, courier, monospace; 67 margin-left: 36pt; 68} 69 70P.formula { 71 font-style: italic; 72 margin-left: 36pt; 73} 74 75BLOCKQUOTE { 76 background: #eeeeee; 77 border: solid thin #999999; 78 padding: 10pt; 79} 80 81A IMG { 82 border: none; 83} 84 85A:link:hover IMG { 86 background: #f0f0f0; 87 border-radius: 10px; 88 -moz-border-radius: 10px; 89} 90 91A:link, A:visited { 92 font-weight: inherit; 93 text-decoration: none; 94} 95 96A:link:hover, A:visited:hover, A:active { 97 text-decoration: underline; 98} 99 100SUB, SUP { 101 font-size: 50%; 102} 103 104TR.data, TD.data, TR.data TD { 105 margin-top: 10pt; 106 padding: 5pt; 107 border-bottom: solid 1pt #999999; 108} 109 110TR.data TH { 111 border-bottom: solid 1pt #999999; 112 padding-top: 10pt; 113 padding-left: 5pt; 114 text-align: left; 115} 116 117DIV.table TABLE { 118 border: solid thin #999999; 119 border-collapse: collapse; 120 border-spacing: 0; 121 margin-left: auto; 122 margin-right: auto; 123} 124 125DIV.table CAPTION { 126 caption-side: top; 127 font-size: 120%; 128 font-style: italic; 129 font-weight: bold; 130 margin-left: auto; 131 margin-right: auto; 132} 133 134DIV.table TABLE TD { 135 border: solid thin #cccccc; 136 padding-top: 5pt; 137} 138 139DIV.table TABLE TH { 140 background: #cccccc; 141 border: none; 142 border-bottom: solid thin #999999; 143} 144 145DIV.figure TABLE { 146 margin-left: auto; 147 margin-right: auto; 148} 149 150DIV.figure CAPTION { 151 caption-side: bottom; 152 font-size: 120%; 153 font-style: italic; 154 font-weight: bold; 155 margin-left: auto; 156 margin-right: auto; 157} 158 159TH.label { 160 text-align: right; 161 vertical-align: top; 162} 163 164TH.sublabel { 165 text-align: right; 166 font-weight: normal; 167} 168 169HR { 170 border: solid thin; 171} 172 173SPAN.info { 174 background: black; 175 border: thin solid black; 176 color: white; 177 font-size: 80%; 178 font-style: italic; 179 font-weight: bold; 180 white-space: nowrap; 181} 182 183H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { 184 float: right; 185 font-size: 100%; 186} 187 188H1.title { 189} 190 191H2.title, H3.title { 192 border-bottom: solid 2pt #000000; 193} 194 195DIV.indent, TABLE.indent { 196 margin-top: 2em; 197 margin-left: auto; 198 margin-right: auto; 199 width: 90%; 200} 201 202TABLE.indent { 203 border-collapse: collapse; 204} 205 206TABLE.indent TD, TABLE.indent TH { 207 padding: 0; 208} 209 210TABLE.list { 211 border-collapse: collapse; 212 margin-left: auto; 213 margin-right: auto; 214 width: 90%; 215} 216 217TABLE.list TH { 218 background: white; 219 border-bottom: solid thin #cccccc; 220 color: #444444; 221 padding-top: 10pt; 222 padding-left: 5pt; 223 text-align: left; 224 vertical-align: bottom; 225 white-space: nowrap; 226} 227 228TABLE.list TH A { 229 color: #4444cc; 230} 231 232TABLE.list TD { 233 border-bottom: solid thin #eeeeee; 234 padding-top: 5pt; 235 padding-left: 5pt; 236} 237 238TABLE.list TR:nth-child(even) { 239 background: #f8f8f8; 240} 241 242TABLE.list TR:nth-child(odd) { 243 background: #f4f4f4; 244} 245 246DT { 247 margin-left: 36pt; 248 margin-top: 12pt; 249} 250 251DD { 252 margin-left: 54pt; 253} 254 255DL.category DT { 256 font-weight: bold; 257} 258 259P.summary { 260 margin-left: 36pt; 261 font-family: monaco, courier, monospace; 262} 263 264DIV.summary TABLE { 265 border: solid thin #999999; 266 border-collapse: collapse; 267 border-spacing: 0; 268 margin: 10px; 269} 270 271DIV.summary TABLE TD, DIV.summary TABLE TH { 272 border: solid thin #999999; 273 padding: 5px; 274 text-align: left; 275 vertical-align: top; 276} 277 278DIV.summary TABLE THEAD TH { 279 background: #eeeeee; 280} 281 282/* API documentation styles... */ 283div.body h1 { 284 margin: 0; 285} 286div.body h2 { 287 margin-top: 1.5em; 288} 289div.body h3, div.body h4, div.body h5 { 290 margin-bottom: 0.5em; 291 margin-top: 1.5em; 292} 293.class, .enumeration, .function, .struct, .typedef, .union { 294 border-bottom: solid thin #999999; 295 margin-bottom: 0; 296 margin-top: 2em; 297} 298.description { 299 margin-top: 0.5em; 300} 301code, p.code, pre, ul.code li { 302 font-family: monaco, courier, monospace; 303 font-size: 90%; 304} 305ul.code, ul.contents, ul.subcontents { 306 list-style-type: none; 307 margin: 0; 308 padding-left: 0; 309} 310ul.code li { 311 margin: 0; 312} 313ul.contents > li { 314 margin-top: 1em; 315} 316ul.contents li ul.code, ul.contents li ul.subcontents { 317 padding-left: 2em; 318} 319div.body dl { 320 margin-left: 0; 321 margin-top: 0; 322} 323div.body dt { 324 font-style: italic; 325 margin-left: 0; 326 margin-top: 0; 327} 328div.body dd { 329 margin-bottom: 0.5em; 330} 331 332/* This is just for the HTML files generated with the framedhelp target */ 333div.contents { 334 background: #e8e8e8; 335 border: solid thin black; 336 padding: 10px; 337} 338div.contents h1 { 339 font-size: 110%; 340} 341div.contents h2 { 342 font-size: 100%; 343} 344div.contents ul.contents { 345 font-size: 80%; 346} 347div.contents ul.subcontents li { 348 margin-left: 1em; 349 text-indent: -1em; 350} 351--></style> 352</head> 353<body> 354<div class='body'> 355<!-- 356 "$Id: api-array.header 8087 2008-10-27 21:37:05Z mike $" 357 358 CGI API header for CUPS. 359 360 Copyright 2009 by Apple Inc. 361 362 These coded instructions, statements, and computer programs are the 363 property of Apple Inc. and are protected by Federal copyright 364 law. Distribution and use rights are outlined in the file "LICENSE.txt" 365 which should have been included with this file. If this file is 366 file is missing or damaged, see the license at "http://www.cups.org/". 367--> 368 369<h1 class='title'>CGI API</h1> 370 371<div class='summary'><table summary='General Information'> 372<thead> 373<tr> 374 <th>Header</th> 375 <th>cups/cgi.h</th> 376</tr> 377</thead> 378<tbody> 379<tr> 380 <th>Library</th> 381 <td>-lcupscgi</td> 382</tr> 383<tr> 384 <th>See Also</th> 385 <td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a></td> 386</tr> 387</tbody> 388</table></div> 389<h2 class="title">Contents</h2> 390<ul class="contents"> 391<li><a href="#OVERVIEW">Overview</a></li> 392<li><a href="#FUNCTIONS">Functions</a><ul class="code"> 393 <li><a href="#cgiCheckVariables" title="Check for the presence of "required" variables.">cgiCheckVariables</a></li> 394 <li><a href="#cgiClearVariables" title="Clear all form variables.">cgiClearVariables</a></li> 395 <li><a href="#cgiCompileSearch" title="Compile a search string.">cgiCompileSearch</a></li> 396 <li><a href="#cgiCopyTemplateFile" title="Copy a template file and replace all the 397'{variable}' strings with the variable value.">cgiCopyTemplateFile</a></li> 398 <li><a href="#cgiCopyTemplateLang" title="Copy a template file using a language...">cgiCopyTemplateLang</a></li> 399 <li><a href="#cgiDoSearch" title="Do a search of some text.">cgiDoSearch</a></li> 400 <li><a href="#cgiEndHTML" title="End a HTML page.">cgiEndHTML</a></li> 401 <li><a href="#cgiEndMultipart" title="End the delivery of a multipart web page.">cgiEndMultipart</a></li> 402 <li><a href="#cgiFormEncode" title="Encode a string as a form variable.">cgiFormEncode</a></li> 403 <li><a href="#cgiFreeSearch" title="Free a compiled search context.">cgiFreeSearch</a></li> 404 <li><a href="#cgiGetArray" title="Get an element from a form array.">cgiGetArray</a></li> 405 <li><a href="#cgiGetAttributes" title="Get the list of attributes that are needed 406by the template file.">cgiGetAttributes</a></li> 407 <li><a href="#cgiGetCookie" title="Get a cookie value.">cgiGetCookie</a></li> 408 <li><a href="#cgiGetFile" title="Get the file (if any) that was submitted in the form.">cgiGetFile</a></li> 409 <li><a href="#cgiGetIPPObjects" title="Get the objects in an IPP response.">cgiGetIPPObjects</a></li> 410 <li><a href="#cgiGetSize" title="Get the size of a form array value.">cgiGetSize</a></li> 411 <li><a href="#cgiGetTemplateDir" title="Get the templates directory...">cgiGetTemplateDir</a></li> 412 <li><a href="#cgiGetVariable" title="Get a CGI variable from the database.">cgiGetVariable</a></li> 413 <li><a href="#cgiInitialize" title="Initialize the CGI variable "database".">cgiInitialize</a></li> 414 <li><a href="#cgiIsPOST" title="Determine whether this page was POSTed.">cgiIsPOST</a></li> 415 <li><a href="#cgiMoveJobs" title="Move one or more jobs.">cgiMoveJobs</a></li> 416 <li><a href="#cgiPrintCommand" title="Print a CUPS command job.">cgiPrintCommand</a></li> 417 <li><a href="#cgiPrintTestPage" title="Print a test page.">cgiPrintTestPage</a></li> 418 <li><a href="#cgiRewriteURL" title="Rewrite a printer URI into a web browser URL...">cgiRewriteURL</a></li> 419 <li><a href="#cgiSetArray" title="Set array element N to the specified string.">cgiSetArray</a></li> 420 <li><a href="#cgiSetCookie" title="Set a cookie value.">cgiSetCookie</a></li> 421 <li><a href="#cgiSetIPPObjectVars" title="Set CGI variables from an IPP object.">cgiSetIPPObjectVars</a></li> 422 <li><a href="#cgiSetIPPVars" title="Set CGI variables from an IPP response.">cgiSetIPPVars</a></li> 423 <li><a href="#cgiSetServerVersion" title="Set the server name and CUPS version...">cgiSetServerVersion</a></li> 424 <li><a href="#cgiSetSize" title="Set the array size.">cgiSetSize</a></li> 425 <li><a href="#cgiSetVariable" title="Set a CGI variable in the database.">cgiSetVariable</a></li> 426 <li><a href="#cgiShowIPPError" title="Show the last IPP error message.">cgiShowIPPError</a></li> 427 <li><a href="#cgiShowJobs" title="Show print jobs.">cgiShowJobs</a></li> 428 <li><a href="#cgiStartHTML" title="Start a HTML page.">cgiStartHTML</a></li> 429 <li><a href="#cgiStartMultipart" title="Start a multipart delivery of a web page.">cgiStartMultipart</a></li> 430 <li><a href="#cgiSupportsMultipart" title="Does the browser support multi-part documents?">cgiSupportsMultipart</a></li> 431 <li><a href="#cgiText" title="Return localized text.">cgiText</a></li> 432 <li><a href="#helpDeleteIndex" title="Delete an index, freeing all memory used.">helpDeleteIndex</a></li> 433 <li><a href="#helpFindNode" title="Find a node in an index.">helpFindNode</a></li> 434 <li><a href="#helpLoadIndex" title="Load a help index from disk.">helpLoadIndex</a></li> 435 <li><a href="#helpSaveIndex" title="Save a help index to disk.">helpSaveIndex</a></li> 436 <li><a href="#helpSearchIndex" title="Search an index.">helpSearchIndex</a></li> 437</ul></li> 438<li><a href="#TYPES">Data Types</a><ul class="code"> 439 <li><a href="#cgi_file_t" title="Uploaded file data">cgi_file_t</a></li> 440 <li><a href="#help_index_t" title="Help index structure">help_index_t</a></li> 441 <li><a href="#help_node_t" title="Help node structure...">help_node_t</a></li> 442 <li><a href="#help_word_t" title="Help word structure...">help_word_t</a></li> 443</ul></li> 444<li><a href="#STRUCTURES">Structures</a><ul class="code"> 445 <li><a href="#cgi_file_s" title="Uploaded file data">cgi_file_s</a></li> 446 <li><a href="#help_index_s" title="Help index structure">help_index_s</a></li> 447 <li><a href="#help_node_s" title="Help node structure...">help_node_s</a></li> 448 <li><a href="#help_word_s" title="Help word structure...">help_word_s</a></li> 449</ul></li> 450</ul> 451<!-- 452 "$Id: api-array.shtml 7616 2008-05-28 00:34:13Z mike $" 453 454 CGI API introduction for CUPS. 455 456 Copyright 2009 by Apple Inc. 457 458 These coded instructions, statements, and computer programs are the 459 property of Apple Inc. and are protected by Federal copyright 460 law. Distribution and use rights are outlined in the file "LICENSE.txt" 461 which should have been included with this file. If this file is 462 file is missing or damaged, see the license at "http://www.cups.org/". 463--> 464 465<h2 class='title'><a name='OVERVIEW'>Overview</a></h2> 466 467<p>The CGI API provides Common Gateway Interface functions for CUPS.</p> 468<h2 class="title"><a name="FUNCTIONS">Functions</a></h2> 469<h3 class="function"><a name="cgiCheckVariables">cgiCheckVariables</a></h3> 470<p class="description">Check for the presence of "required" variables.</p> 471<p class="code"> 472int cgiCheckVariables (<br> 473 const char *names<br> 474);</p> 475<h4 class="parameters">Parameters</h4> 476<dl> 477<dt>names</dt> 478<dd class="description">Variables to look for</dd> 479</dl> 480<h4 class="returnvalue">Return Value</h4> 481<p class="description">1 if all variables present, 0 otherwise</p> 482<h4 class="discussion">Discussion</h4> 483<p class="discussion">Names may be separated by spaces and/or commas.</p> 484<h3 class="function"><a name="cgiClearVariables">cgiClearVariables</a></h3> 485<p class="description">Clear all form variables.</p> 486<p class="code"> 487void cgiClearVariables (void);</p> 488<h3 class="function"><a name="cgiCompileSearch">cgiCompileSearch</a></h3> 489<p class="description">Compile a search string.</p> 490<p class="code"> 491void *cgiCompileSearch (<br> 492 const char *query<br> 493);</p> 494<h4 class="parameters">Parameters</h4> 495<dl> 496<dt>query</dt> 497<dd class="description">Query string</dd> 498</dl> 499<h4 class="returnvalue">Return Value</h4> 500<p class="description">Search context</p> 501<h3 class="function"><a name="cgiCopyTemplateFile">cgiCopyTemplateFile</a></h3> 502<p class="description">Copy a template file and replace all the 503'{variable}' strings with the variable value.</p> 504<p class="code"> 505void cgiCopyTemplateFile (<br> 506 FILE *out,<br> 507 const char *tmpl<br> 508);</p> 509<h4 class="parameters">Parameters</h4> 510<dl> 511<dt>out</dt> 512<dd class="description">Output file</dd> 513<dt>tmpl</dt> 514<dd class="description">Template file to read</dd> 515</dl> 516<h3 class="function"><a name="cgiCopyTemplateLang">cgiCopyTemplateLang</a></h3> 517<p class="description">Copy a template file using a language...</p> 518<p class="code"> 519void cgiCopyTemplateLang (<br> 520 const char *tmpl<br> 521);</p> 522<h4 class="parameters">Parameters</h4> 523<dl> 524<dt>tmpl</dt> 525<dd class="description">Base filename</dd> 526</dl> 527<h3 class="function"><a name="cgiDoSearch">cgiDoSearch</a></h3> 528<p class="description">Do a search of some text.</p> 529<p class="code"> 530int cgiDoSearch (<br> 531 void *search,<br> 532 const char *text<br> 533);</p> 534<h4 class="parameters">Parameters</h4> 535<dl> 536<dt>search</dt> 537<dd class="description">Search context</dd> 538<dt>text</dt> 539<dd class="description">Text to search</dd> 540</dl> 541<h4 class="returnvalue">Return Value</h4> 542<p class="description">Number of matches</p> 543<h3 class="function"><a name="cgiEndHTML">cgiEndHTML</a></h3> 544<p class="description">End a HTML page.</p> 545<p class="code"> 546void cgiEndHTML (void);</p> 547<h3 class="function"><a name="cgiEndMultipart">cgiEndMultipart</a></h3> 548<p class="description">End the delivery of a multipart web page.</p> 549<p class="code"> 550void cgiEndMultipart (void);</p> 551<h3 class="function"><a name="cgiFormEncode">cgiFormEncode</a></h3> 552<p class="description">Encode a string as a form variable.</p> 553<p class="code"> 554char *cgiFormEncode (<br> 555 char *dst,<br> 556 const char *src,<br> 557 size_t dstsize<br> 558);</p> 559<h4 class="parameters">Parameters</h4> 560<dl> 561<dt>dst</dt> 562<dd class="description">Destination string</dd> 563<dt>src</dt> 564<dd class="description">Source string</dd> 565<dt>dstsize</dt> 566<dd class="description">Size of destination string</dd> 567</dl> 568<h4 class="returnvalue">Return Value</h4> 569<p class="description">Destination string</p> 570<h3 class="function"><a name="cgiFreeSearch">cgiFreeSearch</a></h3> 571<p class="description">Free a compiled search context.</p> 572<p class="code"> 573void cgiFreeSearch (<br> 574 void *search<br> 575);</p> 576<h4 class="parameters">Parameters</h4> 577<dl> 578<dt>search</dt> 579<dd class="description">Search context</dd> 580</dl> 581<h3 class="function"><a name="cgiGetArray">cgiGetArray</a></h3> 582<p class="description">Get an element from a form array.</p> 583<p class="code"> 584const char *cgiGetArray (<br> 585 const char *name,<br> 586 int element<br> 587);</p> 588<h4 class="parameters">Parameters</h4> 589<dl> 590<dt>name</dt> 591<dd class="description">Name of array variable</dd> 592<dt>element</dt> 593<dd class="description">Element number (0 to N)</dd> 594</dl> 595<h4 class="returnvalue">Return Value</h4> 596<p class="description">Element value or NULL</p> 597<h3 class="function"><a name="cgiGetAttributes">cgiGetAttributes</a></h3> 598<p class="description">Get the list of attributes that are needed 599by the template file.</p> 600<p class="code"> 601void cgiGetAttributes (<br> 602 ipp_t *request,<br> 603 const char *tmpl<br> 604);</p> 605<h4 class="parameters">Parameters</h4> 606<dl> 607<dt>request</dt> 608<dd class="description">IPP request</dd> 609<dt>tmpl</dt> 610<dd class="description">Base filename</dd> 611</dl> 612<h3 class="function"><a name="cgiGetCookie">cgiGetCookie</a></h3> 613<p class="description">Get a cookie value.</p> 614<p class="code"> 615const char *cgiGetCookie (<br> 616 const char *name<br> 617);</p> 618<h4 class="parameters">Parameters</h4> 619<dl> 620<dt>name</dt> 621<dd class="description">Name of cookie</dd> 622</dl> 623<h4 class="returnvalue">Return Value</h4> 624<p class="description">Value or NULL</p> 625<h3 class="function"><a name="cgiGetFile">cgiGetFile</a></h3> 626<p class="description">Get the file (if any) that was submitted in the form.</p> 627<p class="code"> 628const <a href="#cgi_file_t">cgi_file_t</a> *cgiGetFile (void);</p> 629<h4 class="returnvalue">Return Value</h4> 630<p class="description">Attached file or NULL</p> 631<h3 class="function"><a name="cgiGetIPPObjects">cgiGetIPPObjects</a></h3> 632<p class="description">Get the objects in an IPP response.</p> 633<p class="code"> 634cups_array_t *cgiGetIPPObjects (<br> 635 ipp_t *response,<br> 636 void *search<br> 637);</p> 638<h4 class="parameters">Parameters</h4> 639<dl> 640<dt>response</dt> 641<dd class="description">IPP response</dd> 642<dt>search</dt> 643<dd class="description">Search filter</dd> 644</dl> 645<h4 class="returnvalue">Return Value</h4> 646<p class="description">Array of objects</p> 647<h3 class="function"><a name="cgiGetSize">cgiGetSize</a></h3> 648<p class="description">Get the size of a form array value.</p> 649<p class="code"> 650int cgiGetSize (<br> 651 const char *name<br> 652);</p> 653<h4 class="parameters">Parameters</h4> 654<dl> 655<dt>name</dt> 656<dd class="description">Name of variable</dd> 657</dl> 658<h4 class="returnvalue">Return Value</h4> 659<p class="description">Number of elements</p> 660<h3 class="function"><a name="cgiGetTemplateDir">cgiGetTemplateDir</a></h3> 661<p class="description">Get the templates directory...</p> 662<p class="code"> 663char *cgiGetTemplateDir (void);</p> 664<h4 class="returnvalue">Return Value</h4> 665<p class="description">Template directory</p> 666<h3 class="function"><a name="cgiGetVariable">cgiGetVariable</a></h3> 667<p class="description">Get a CGI variable from the database.</p> 668<p class="code"> 669const char *cgiGetVariable (<br> 670 const char *name<br> 671);</p> 672<h4 class="parameters">Parameters</h4> 673<dl> 674<dt>name</dt> 675<dd class="description">Name of variable</dd> 676</dl> 677<h4 class="returnvalue">Return Value</h4> 678<p class="description">Value of variable</p> 679<h4 class="discussion">Discussion</h4> 680<p class="discussion">Returns NULL if the variable doesn't exist. If the variable is an 681array of values, returns the last element.</p> 682<h3 class="function"><a name="cgiInitialize">cgiInitialize</a></h3> 683<p class="description">Initialize the CGI variable "database".</p> 684<p class="code"> 685int cgiInitialize (void);</p> 686<h4 class="returnvalue">Return Value</h4> 687<p class="description">Non-zero if there was form data</p> 688<h3 class="function"><a name="cgiIsPOST">cgiIsPOST</a></h3> 689<p class="description">Determine whether this page was POSTed.</p> 690<p class="code"> 691int cgiIsPOST (void);</p> 692<h4 class="returnvalue">Return Value</h4> 693<p class="description">1 if POST, 0 if GET</p> 694<h3 class="function"><a name="cgiMoveJobs">cgiMoveJobs</a></h3> 695<p class="description">Move one or more jobs.</p> 696<p class="code"> 697void cgiMoveJobs (<br> 698 http_t *http,<br> 699 const char *dest,<br> 700 int job_id<br> 701);</p> 702<h4 class="parameters">Parameters</h4> 703<dl> 704<dt>http</dt> 705<dd class="description">Connection to server</dd> 706<dt>dest</dt> 707<dd class="description">Destination or NULL</dd> 708<dt>job_id</dt> 709<dd class="description">Job ID or 0 for all</dd> 710</dl> 711<h4 class="discussion">Discussion</h4> 712<p class="discussion">At least one of dest or job_id must be non-zero/NULL.</p> 713<h3 class="function"><a name="cgiPrintCommand">cgiPrintCommand</a></h3> 714<p class="description">Print a CUPS command job.</p> 715<p class="code"> 716void cgiPrintCommand (<br> 717 http_t *http,<br> 718 const char *dest,<br> 719 const char *command,<br> 720 const char *title<br> 721);</p> 722<h4 class="parameters">Parameters</h4> 723<dl> 724<dt>http</dt> 725<dd class="description">Connection to server</dd> 726<dt>dest</dt> 727<dd class="description">Destination printer</dd> 728<dt>command</dt> 729<dd class="description">Command to send</dd> 730<dt>title</dt> 731<dd class="description">Page/job title</dd> 732</dl> 733<h3 class="function"><a name="cgiPrintTestPage">cgiPrintTestPage</a></h3> 734<p class="description">Print a test page.</p> 735<p class="code"> 736void cgiPrintTestPage (<br> 737 http_t *http,<br> 738 const char *dest<br> 739);</p> 740<h4 class="parameters">Parameters</h4> 741<dl> 742<dt>http</dt> 743<dd class="description">Connection to server</dd> 744<dt>dest</dt> 745<dd class="description">Destination printer/class</dd> 746</dl> 747<h3 class="function"><a name="cgiRewriteURL">cgiRewriteURL</a></h3> 748<p class="description">Rewrite a printer URI into a web browser URL...</p> 749<p class="code"> 750char *cgiRewriteURL (<br> 751 const char *uri,<br> 752 char *url,<br> 753 int urlsize,<br> 754 const char *newresource<br> 755);</p> 756<h4 class="parameters">Parameters</h4> 757<dl> 758<dt>uri</dt> 759<dd class="description">Current URI</dd> 760<dt>url</dt> 761<dd class="description">New URL</dd> 762<dt>urlsize</dt> 763<dd class="description">Size of URL buffer</dd> 764<dt>newresource</dt> 765<dd class="description">Replacement resource</dd> 766</dl> 767<h4 class="returnvalue">Return Value</h4> 768<p class="description">New URL</p> 769<h3 class="function"><a name="cgiSetArray">cgiSetArray</a></h3> 770<p class="description">Set array element N to the specified string.</p> 771<p class="code"> 772void cgiSetArray (<br> 773 const char *name,<br> 774 int element,<br> 775 const char *value<br> 776);</p> 777<h4 class="parameters">Parameters</h4> 778<dl> 779<dt>name</dt> 780<dd class="description">Name of variable</dd> 781<dt>element</dt> 782<dd class="description">Element number (0 to N)</dd> 783<dt>value</dt> 784<dd class="description">Value of variable</dd> 785</dl> 786<h4 class="discussion">Discussion</h4> 787<p class="discussion">If the variable array is smaller than (element + 1), the intervening 788elements are set to NULL.</p> 789<h3 class="function"><a name="cgiSetCookie">cgiSetCookie</a></h3> 790<p class="description">Set a cookie value.</p> 791<p class="code"> 792void cgiSetCookie (<br> 793 const char *name,<br> 794 const char *value,<br> 795 const char *path,<br> 796 const char *domain,<br> 797 time_t expires,<br> 798 int secure<br> 799);</p> 800<h4 class="parameters">Parameters</h4> 801<dl> 802<dt>name</dt> 803<dd class="description">Name</dd> 804<dt>value</dt> 805<dd class="description">Value</dd> 806<dt>path</dt> 807<dd class="description">Path (typically "/")</dd> 808<dt>domain</dt> 809<dd class="description">Domain name</dd> 810<dt>expires</dt> 811<dd class="description">Expiration date (0 for session)</dd> 812<dt>secure</dt> 813<dd class="description">Require SSL</dd> 814</dl> 815<h3 class="function"><a name="cgiSetIPPObjectVars">cgiSetIPPObjectVars</a></h3> 816<p class="description">Set CGI variables from an IPP object.</p> 817<p class="code"> 818ipp_attribute_t *cgiSetIPPObjectVars (<br> 819 ipp_attribute_t *obj,<br> 820 const char *prefix,<br> 821 int element<br> 822);</p> 823<h4 class="parameters">Parameters</h4> 824<dl> 825<dt>obj</dt> 826<dd class="description">Response data to be copied...</dd> 827<dt>prefix</dt> 828<dd class="description">Prefix for name or NULL</dd> 829<dt>element</dt> 830<dd class="description">Parent element number</dd> 831</dl> 832<h4 class="returnvalue">Return Value</h4> 833<p class="description">Next object</p> 834<h3 class="function"><a name="cgiSetIPPVars">cgiSetIPPVars</a></h3> 835<p class="description">Set CGI variables from an IPP response.</p> 836<p class="code"> 837int cgiSetIPPVars (<br> 838 ipp_t *response,<br> 839 const char *filter_name,<br> 840 const char *filter_value,<br> 841 const char *prefix,<br> 842 int parent_el<br> 843);</p> 844<h4 class="parameters">Parameters</h4> 845<dl> 846<dt>response</dt> 847<dd class="description">Response data to be copied...</dd> 848<dt>filter_name</dt> 849<dd class="description">Filter name</dd> 850<dt>filter_value</dt> 851<dd class="description">Filter value</dd> 852<dt>prefix</dt> 853<dd class="description">Prefix for name or NULL</dd> 854<dt>parent_el</dt> 855<dd class="description">Parent element number</dd> 856</dl> 857<h4 class="returnvalue">Return Value</h4> 858<p class="description">Maximum number of elements</p> 859<h3 class="function"><a name="cgiSetServerVersion">cgiSetServerVersion</a></h3> 860<p class="description">Set the server name and CUPS version...</p> 861<p class="code"> 862void cgiSetServerVersion (void);</p> 863<h3 class="function"><a name="cgiSetSize">cgiSetSize</a></h3> 864<p class="description">Set the array size.</p> 865<p class="code"> 866void cgiSetSize (<br> 867 const char *name,<br> 868 int size<br> 869);</p> 870<h4 class="parameters">Parameters</h4> 871<dl> 872<dt>name</dt> 873<dd class="description">Name of variable</dd> 874<dt>size</dt> 875<dd class="description">Number of elements (0 to N)</dd> 876</dl> 877<h3 class="function"><a name="cgiSetVariable">cgiSetVariable</a></h3> 878<p class="description">Set a CGI variable in the database.</p> 879<p class="code"> 880void cgiSetVariable (<br> 881 const char *name,<br> 882 const char *value<br> 883);</p> 884<h4 class="parameters">Parameters</h4> 885<dl> 886<dt>name</dt> 887<dd class="description">Name of variable</dd> 888<dt>value</dt> 889<dd class="description">Value of variable</dd> 890</dl> 891<h4 class="discussion">Discussion</h4> 892<p class="discussion">If the variable is an array, this truncates the array to a single element.</p> 893<h3 class="function"><a name="cgiShowIPPError">cgiShowIPPError</a></h3> 894<p class="description">Show the last IPP error message.</p> 895<p class="code"> 896void cgiShowIPPError (<br> 897 const char *message<br> 898);</p> 899<h4 class="parameters">Parameters</h4> 900<dl> 901<dt>message</dt> 902<dd class="description">Contextual message</dd> 903</dl> 904<h4 class="discussion">Discussion</h4> 905<p class="discussion">The caller must still call cgiStartHTML() and cgiEndHTML().</p> 906<h3 class="function"><a name="cgiShowJobs">cgiShowJobs</a></h3> 907<p class="description">Show print jobs.</p> 908<p class="code"> 909void cgiShowJobs (<br> 910 http_t *http,<br> 911 const char *dest<br> 912);</p> 913<h4 class="parameters">Parameters</h4> 914<dl> 915<dt>http</dt> 916<dd class="description">Connection to server</dd> 917<dt>dest</dt> 918<dd class="description">Destination name or NULL</dd> 919</dl> 920<h3 class="function"><a name="cgiStartHTML">cgiStartHTML</a></h3> 921<p class="description">Start a HTML page.</p> 922<p class="code"> 923void cgiStartHTML (<br> 924 const char *title<br> 925);</p> 926<h4 class="parameters">Parameters</h4> 927<dl> 928<dt>title</dt> 929<dd class="description">Title of page</dd> 930</dl> 931<h3 class="function"><a name="cgiStartMultipart">cgiStartMultipart</a></h3> 932<p class="description">Start a multipart delivery of a web page.</p> 933<p class="code"> 934void cgiStartMultipart (void);</p> 935<h3 class="function"><a name="cgiSupportsMultipart">cgiSupportsMultipart</a></h3> 936<p class="description">Does the browser support multi-part documents?</p> 937<p class="code"> 938int cgiSupportsMultipart (void);</p> 939<h4 class="returnvalue">Return Value</h4> 940<p class="description">1 if multi-part supported, 0 otherwise</p> 941<h3 class="function"><a name="cgiText">cgiText</a></h3> 942<p class="description">Return localized text.</p> 943<p class="code"> 944const char *cgiText (<br> 945 const char *message<br> 946);</p> 947<h4 class="parameters">Parameters</h4> 948<dl> 949<dt>message</dt> 950<dd class="description">Message</dd> 951</dl> 952<h4 class="returnvalue">Return Value</h4> 953<p class="description">Localized message</p> 954<h3 class="function"><a name="helpDeleteIndex">helpDeleteIndex</a></h3> 955<p class="description">Delete an index, freeing all memory used.</p> 956<p class="code"> 957void helpDeleteIndex (<br> 958 <a href="#help_index_t">help_index_t</a> *hi<br> 959);</p> 960<h4 class="parameters">Parameters</h4> 961<dl> 962<dt>hi</dt> 963<dd class="description">Help index</dd> 964</dl> 965<h3 class="function"><a name="helpFindNode">helpFindNode</a></h3> 966<p class="description">Find a node in an index.</p> 967<p class="code"> 968<a href="#help_node_t">help_node_t</a> *helpFindNode (<br> 969 <a href="#help_index_t">help_index_t</a> *hi,<br> 970 const char *filename,<br> 971 const char *anchor<br> 972);</p> 973<h4 class="parameters">Parameters</h4> 974<dl> 975<dt>hi</dt> 976<dd class="description">Index</dd> 977<dt>filename</dt> 978<dd class="description">Filename</dd> 979<dt>anchor</dt> 980<dd class="description">Anchor</dd> 981</dl> 982<h4 class="returnvalue">Return Value</h4> 983<p class="description">Node pointer or NULL</p> 984<h3 class="function"><a name="helpLoadIndex">helpLoadIndex</a></h3> 985<p class="description">Load a help index from disk.</p> 986<p class="code"> 987<a href="#help_index_t">help_index_t</a> *helpLoadIndex (<br> 988 const char *hifile,<br> 989 const char *directory<br> 990);</p> 991<h4 class="parameters">Parameters</h4> 992<dl> 993<dt>hifile</dt> 994<dd class="description">Index filename</dd> 995<dt>directory</dt> 996<dd class="description">Directory that is indexed</dd> 997</dl> 998<h4 class="returnvalue">Return Value</h4> 999<p class="description">Index pointer or NULL</p> 1000<h3 class="function"><a name="helpSaveIndex">helpSaveIndex</a></h3> 1001<p class="description">Save a help index to disk.</p> 1002<p class="code"> 1003int helpSaveIndex (<br> 1004 <a href="#help_index_t">help_index_t</a> *hi,<br> 1005 const char *hifile<br> 1006);</p> 1007<h4 class="parameters">Parameters</h4> 1008<dl> 1009<dt>hi</dt> 1010<dd class="description">Index</dd> 1011<dt>hifile</dt> 1012<dd class="description">Index filename</dd> 1013</dl> 1014<h4 class="returnvalue">Return Value</h4> 1015<p class="description">0 on success, -1 on error</p> 1016<h3 class="function"><a name="helpSearchIndex">helpSearchIndex</a></h3> 1017<p class="description">Search an index.</p> 1018<p class="code"> 1019<a href="#help_index_t">help_index_t</a> *helpSearchIndex (<br> 1020 <a href="#help_index_t">help_index_t</a> *hi,<br> 1021 const char *query,<br> 1022 const char *section,<br> 1023 const char *filename<br> 1024);</p> 1025<h4 class="parameters">Parameters</h4> 1026<dl> 1027<dt>hi</dt> 1028<dd class="description">Index</dd> 1029<dt>query</dt> 1030<dd class="description">Query string</dd> 1031<dt>section</dt> 1032<dd class="description">Limit search to this section</dd> 1033<dt>filename</dt> 1034<dd class="description">Limit search to this file</dd> 1035</dl> 1036<h4 class="returnvalue">Return Value</h4> 1037<p class="description">Search index</p> 1038<h2 class="title"><a name="TYPES">Data Types</a></h2> 1039<h3 class="typedef"><a name="cgi_file_t">cgi_file_t</a></h3> 1040<p class="description">Uploaded file data</p> 1041<p class="code"> 1042typedef struct <a href="#cgi_file_s">cgi_file_s</a> cgi_file_t; 1043</p> 1044<h3 class="typedef"><a name="help_index_t">help_index_t</a></h3> 1045<p class="description">Help index structure</p> 1046<p class="code"> 1047typedef struct <a href="#help_index_s">help_index_s</a> help_index_t; 1048</p> 1049<h3 class="typedef"><a name="help_node_t">help_node_t</a></h3> 1050<p class="description">Help node structure...</p> 1051<p class="code"> 1052typedef struct <a href="#help_node_s">help_node_s</a> help_node_t; 1053</p> 1054<h3 class="typedef"><a name="help_word_t">help_word_t</a></h3> 1055<p class="description">Help word structure...</p> 1056<p class="code"> 1057typedef struct <a href="#help_word_s">help_word_s</a> help_word_t; 1058</p> 1059<h2 class="title"><a name="STRUCTURES">Structures</a></h2> 1060<h3 class="struct"><a name="cgi_file_s">cgi_file_s</a></h3> 1061<p class="description">Uploaded file data</p> 1062<p class="code">struct cgi_file_s {<br> 1063 size_t filesize;<br> 1064 char tempfile[1024], *name, *filename, *mimetype;<br> 1065};</p> 1066<h4 class="members">Members</h4> 1067<dl> 1068<dt>filesize </dt> 1069<dd class="description">Size of uploaded file</dd> 1070<dt>mimetype </dt> 1071<dd class="description">MIME media type</dd> 1072</dl> 1073<h3 class="struct"><a name="help_index_s">help_index_s</a></h3> 1074<p class="description">Help index structure</p> 1075<p class="code">struct help_index_s {<br> 1076 cups_array_t *nodes;<br> 1077 int search;<br> 1078 cups_array_t *sorted;<br> 1079};</p> 1080<h4 class="members">Members</h4> 1081<dl> 1082<dt>nodes </dt> 1083<dd class="description">Nodes sorted by filename</dd> 1084<dt>search </dt> 1085<dd class="description">1 = search index, 0 = normal</dd> 1086<dt>sorted </dt> 1087<dd class="description">Nodes sorted by score + text</dd> 1088</dl> 1089<h3 class="struct"><a name="help_node_s">help_node_s</a></h3> 1090<p class="description">Help node structure...</p> 1091<p class="code">struct help_node_s {<br> 1092 char *anchor;<br> 1093 char *filename;<br> 1094 size_t length;<br> 1095 time_t mtime;<br> 1096 off_t offset;<br> 1097 int score;<br> 1098 char *section;<br> 1099 char *text;<br> 1100 cups_array_t *words;<br> 1101};</p> 1102<h4 class="members">Members</h4> 1103<dl> 1104<dt>anchor </dt> 1105<dd class="description">Anchor name (NULL if none)</dd> 1106<dt>filename </dt> 1107<dd class="description">Filename, relative to help dir</dd> 1108<dt>length </dt> 1109<dd class="description">Length in bytes</dd> 1110<dt>mtime </dt> 1111<dd class="description">Last modification time</dd> 1112<dt>offset </dt> 1113<dd class="description">Offset in file</dd> 1114<dt>score </dt> 1115<dd class="description">Search score</dd> 1116<dt>section </dt> 1117<dd class="description">Section name (NULL if none)</dd> 1118<dt>text </dt> 1119<dd class="description">Text in anchor</dd> 1120<dt>words </dt> 1121<dd class="description">Words after this node</dd> 1122</dl> 1123<h3 class="struct"><a name="help_word_s">help_word_s</a></h3> 1124<p class="description">Help word structure...</p> 1125<p class="code">struct help_word_s {<br> 1126 int count;<br> 1127 char *text;<br> 1128};</p> 1129<h4 class="members">Members</h4> 1130<dl> 1131<dt>count </dt> 1132<dd class="description">Number of occurrences</dd> 1133<dt>text </dt> 1134<dd class="description">Word text</dd> 1135</dl> 1136</div> 1137</body> 1138</html> 1139