diff options
Diffstat (limited to 'doc')
30 files changed, 2181 insertions, 1414 deletions
diff --git a/doc/Makefile b/doc/Makefile index 74177297..014074ab 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile 9484 2011-01-17 05:41:04Z mike $" +# "$Id: Makefile 9483 2011-01-17 05:40:28Z mike $" # # Documentation makefile for CUPS. # @@ -73,6 +73,8 @@ HELPFILES = \ help/man-cupstestdsc.html \ help/man-cupstestppd.html \ help/man-filter.html \ + help/man-ipptool.html \ + help/man-ipptoolfile.html \ help/man-lp.html \ help/man-lpadmin.html \ help/man-lpc.html \ @@ -197,6 +199,8 @@ install-languages: fi; \ done +install-langbundle: + # # Install programs... @@ -244,6 +248,8 @@ uninstall-languages: $(RMDIR) $(DOCDIR)/$$lang; \ done +install-langbundle: + # # Install the docset bits locally... diff --git a/doc/cups-printable.css b/doc/cups-printable.css index cc11262f..42ea2bee 100644 --- a/doc/cups-printable.css +++ b/doc/cups-printable.css @@ -16,7 +16,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { diff --git a/doc/cups.css b/doc/cups.css index 51c4f4c3..815c193c 100644 --- a/doc/cups.css +++ b/doc/cups.css @@ -19,8 +19,11 @@ PRE { } PRE.command { + background: #f0f0f0; + border: dotted thin #7f7f7f; color: #7f0000; margin-left: 36pt; + padding: 10px; } P.example { diff --git a/doc/es/index.html.in b/doc/es/index.html.in index 5afb0d0c..5afb0d0c 100755..100644 --- a/doc/es/index.html.in +++ b/doc/es/index.html.in diff --git a/doc/help/api-array.html b/doc/help/api-array.html index 8d381495..7f22251b 100644 --- a/doc/help/api-array.html +++ b/doc/help/api-array.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Array API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Array API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-array.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-array.html 9772 2011-05-12 05:46:30Z mike $" - Array API header for the Common UNIX Printing System (CUPS). + Array API header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -373,41 +376,44 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> -<li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li> -<li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li> + <li><a href="#MANAGING_ARRAYS">Managing Arrays</a></li> + <li><a href="#FINDING_AND_ENUMERATING">Finding and Enumerating Elements</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsArrayAdd" title="Add an element to the array.">cupsArrayAdd</a></li> -<li><a href="#cupsArrayClear" title="Clear the array.">cupsArrayClear</a></li> -<li><a href="#cupsArrayCount" title="Get the number of elements in the array.">cupsArrayCount</a></li> -<li><a href="#cupsArrayCurrent" title="Return the current element in the array.">cupsArrayCurrent</a></li> -<li><a href="#cupsArrayDelete" title="Free all memory used by the array.">cupsArrayDelete</a></li> -<li><a href="#cupsArrayDup" title="Duplicate the array.">cupsArrayDup</a></li> -<li><a href="#cupsArrayFind" title="Find an element in the array.">cupsArrayFind</a></li> -<li><a href="#cupsArrayFirst" title="Get the first element in the array.">cupsArrayFirst</a></li> -<li><a href="#cupsArrayGetIndex" title="Get the index of the current element.">cupsArrayGetIndex</a></li> -<li><a href="#cupsArrayGetInsert" title="Get the index of the last inserted element.">cupsArrayGetInsert</a></li> -<li><a href="#cupsArrayIndex" title="Get the N-th element in the array.">cupsArrayIndex</a></li> -<li><a href="#cupsArrayInsert" title="Insert an element in the array.">cupsArrayInsert</a></li> -<li><a href="#cupsArrayLast" title="Get the last element in the array.">cupsArrayLast</a></li> -<li><a href="#cupsArrayNew" title="Create a new array.">cupsArrayNew</a></li> -<li><a href="#cupsArrayNew2" title="Create a new array with hash.">cupsArrayNew2</a></li> -<li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li> -<li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li> -<li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li> -<li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li> -<li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li> -<li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li> + <li><a href="#cupsArrayAdd" title="Add an element to the array.">cupsArrayAdd</a></li> + <li><a href="#cupsArrayClear" title="Clear the array.">cupsArrayClear</a></li> + <li><a href="#cupsArrayCount" title="Get the number of elements in the array.">cupsArrayCount</a></li> + <li><a href="#cupsArrayCurrent" title="Return the current element in the array.">cupsArrayCurrent</a></li> + <li><a href="#cupsArrayDelete" title="Free all memory used by the array.">cupsArrayDelete</a></li> + <li><a href="#cupsArrayDup" title="Duplicate the array.">cupsArrayDup</a></li> + <li><a href="#cupsArrayFind" title="Find an element in the array.">cupsArrayFind</a></li> + <li><a href="#cupsArrayFirst" title="Get the first element in the array.">cupsArrayFirst</a></li> + <li><a href="#cupsArrayGetIndex" title="Get the index of the current element.">cupsArrayGetIndex</a></li> + <li><a href="#cupsArrayGetInsert" title="Get the index of the last inserted element.">cupsArrayGetInsert</a></li> + <li><a href="#cupsArrayIndex" title="Get the N-th element in the array.">cupsArrayIndex</a></li> + <li><a href="#cupsArrayInsert" title="Insert an element in the array.">cupsArrayInsert</a></li> + <li><a href="#cupsArrayLast" title="Get the last element in the array.">cupsArrayLast</a></li> + <li><a href="#cupsArrayNew" title="Create a new array.">cupsArrayNew</a></li> + <li><a href="#cupsArrayNew2" title="Create a new array with hash.">cupsArrayNew2</a></li> + <li><a href="#cupsArrayNew3" title="Create a new array with hash and/or free function.">cupsArrayNew3</a></li> + <li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li> + <li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li> + <li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li> + <li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li> + <li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li> + <li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> + <li><a href="#cups_acopy_func_t" title="Array element copy function">cups_acopy_func_t</a></li> + <li><a href="#cups_afree_func_t" title="Array element free function">cups_afree_func_t</a></li> <li><a href="#cups_ahash_func_t" title="Array hash function">cups_ahash_func_t</a></li> <li><a href="#cups_array_func_t" title="Array comparison function">cups_array_func_t</a></li> <li><a href="#cups_array_t" title="CUPS array type">cups_array_t</a></li> </ul></li> +</ul> <!-- - "$Id: api-array.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-array.html 9772 2011-05-12 05:46:30Z mike $" Array API introduction for CUPS. @@ -439,8 +445,9 @@ data.</p> <h3><a name='MANAGING_ARRAYS'>Managing Arrays</a></h3> <p>Arrays are created using either the -<a href='#cupsArrayNew'><code>cupsArrayNew</code></a> or -<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a> functions. The +<a href='#cupsArrayNew'><code>cupsArrayNew</code></a>, +<a href='#cupsArrayNew2'><code>cupsArrayNew2</code></a>, or +<a href='#cupsArrayNew2'><code>cupsArrayNew3</code></a> functions. The first function creates a new array with the specified callback function and user data pointer:</p> @@ -477,7 +484,7 @@ static int compare_func(void *first, void *second, void *user_data); static int hash_func(void *element, void *user_data); void *user_data; -<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE); +<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew2'>cupsArrayNew2</a>(compare_func, user_data, hash_func, HASH_SIZE); </pre> <p>The hash function (type @@ -488,6 +495,25 @@ element and is called whenever you look up an element in the array with only limited by available memory, but generally should not be larger than 16384 to realize any performance improvement.</p> +<p>The <a href='#cupsArrayNew3'><code>cupsArrayNew3</code></a> function adds +copy and free callbacks to support basic memory management of elements:</p> + +<pre class='example'> +#include <cups/array.h> + +#define HASH_SIZE 512 /* Size of hash table */ + +static int compare_func(void *first, void *second, void *user_data); +static void *copy_func(void *element, void *user_data); +static void free_func(void *element, void *user_data); +static int hash_func(void *element, void *user_data); + +void *user_data; +<a href='#cups_array_t'>cups_array_t</a> *array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, NULL, 0, copy_func, free_func); + +<a href='#cups_array_t'>cups_array_t</a> *hash_array = <a href='#cupsArrayNew3'>cupsArrayNew3</a>(compare_func, user_data, hash_func, HASH_SIZE, copy_func, free_func); +</pre> + <p>Once you have created the array, you add elements using the <a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> <a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> functions. @@ -536,8 +562,7 @@ example:</p> <p>Finally, you free the memory used by the array using the <a href='#cupsArrayDelete'><code>cupsArrayDelete</code></a> function. All of the memory for the array and hash table (if any) is freed, however <em>CUPS -does not free the elements</em> - if necessary, you must allocate and free the -elements yourself.</p> +does not free the elements unless you provide copy and free functions</em>.</p> <h3><a name='FINDING_AND_ENUMERATING'>Finding and Enumerating Elements</a></h3> @@ -849,6 +874,50 @@ The hash function ("h") is used to implement cached lookups with the specified hash size ("hsize"). </p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cupsArrayNew3">cupsArrayNew3</a></h3> +<p class="description">Create a new array with hash and/or free function.</p> +<p class="code"> +<a href="#cups_array_t">cups_array_t</a> *cupsArrayNew3 (<br> + <a href="#cups_array_func_t">cups_array_func_t</a> f,<br> + void *d,<br> + <a href="#cups_ahash_func_t">cups_ahash_func_t</a> h,<br> + int hsize,<br> + <a href="#cups_acopy_func_t">cups_acopy_func_t</a> cf,<br> + <a href="#cups_afree_func_t">cups_afree_func_t</a> ff<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>f</dt> +<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd> +<dt>d</dt> +<dd class="description">User data or <code>NULL</code></dd> +<dt>h</dt> +<dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd> +<dt>hsize</dt> +<dd class="description">Hash size (>= 0)</dd> +<dt>cf</dt> +<dd class="description">Copy function</dd> +<dt>ff</dt> +<dd class="description">Free function</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Array</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The comparison function ("f") is used to create a sorted array. The function +receives pointers to two elements and the user data pointer ("d") - the user +data pointer argument can safely be omitted when not required so functions +like <code>strcmp</code> can be used for sorted string arrays.<br> +<br> +The hash function ("h") is used to implement cached lookups with the +specified hash size ("hsize").<br> +<br> +The copy function ("cf") is used to automatically copy/retain elements when +added or the array is copied.<br> +<br> +The free function ("cf") is used to automatically free/release elements when +removed or the array is deleted. + +</p> <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayNext">cupsArrayNext</a></h3> <p class="description">Get the next element in the array.</p> <p class="code"> @@ -963,6 +1032,16 @@ void *cupsArrayUserData (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">User data</p> <h2 class="title"><a name="TYPES">Data Types</a></h2> +<h3 class="typedef"><a name="cups_acopy_func_t">cups_acopy_func_t</a></h3> +<p class="description">Array element copy function</p> +<p class="code"> +typedef void *(*cups_acopy_func_t)(void *element, void *data); +</p> +<h3 class="typedef"><a name="cups_afree_func_t">cups_afree_func_t</a></h3> +<p class="description">Array element free function</p> +<p class="code"> +typedef void (*cups_afree_func_t)(void *element, void *data); +</p> <h3 class="typedef"><a name="cups_ahash_func_t">cups_ahash_func_t</a></h3> <p class="description">Array hash function</p> <p class="code"> diff --git a/doc/help/api-cgi.html b/doc/help/api-cgi.html index 5a0a99e6..5c07e58a 100644 --- a/doc/help/api-cgi.html +++ b/doc/help/api-cgi.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>CGI API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>CGI API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-cgi.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-cgi.html 9740 2011-05-04 06:26:22Z mike $" CGI API header for CUPS. @@ -373,53 +376,52 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cgiCheckVariables" title="Check for the presence of "required" variables.">cgiCheckVariables</a></li> -<li><a href="#cgiClearVariables" title="Clear all form variables.">cgiClearVariables</a></li> -<li><a href="#cgiCompileSearch" title="Compile a search string.">cgiCompileSearch</a></li> -<li><a href="#cgiCopyTemplateFile" title="Copy a template file and replace all the + <li><a href="#cgiCheckVariables" title="Check for the presence of "required" variables.">cgiCheckVariables</a></li> + <li><a href="#cgiClearVariables" title="Clear all form variables.">cgiClearVariables</a></li> + <li><a href="#cgiCompileSearch" title="Compile a search string.">cgiCompileSearch</a></li> + <li><a href="#cgiCopyTemplateFile" title="Copy a template file and replace all the '{variable}' strings with the variable value.">cgiCopyTemplateFile</a></li> -<li><a href="#cgiCopyTemplateLang" title="Copy a template file using a language...">cgiCopyTemplateLang</a></li> -<li><a href="#cgiDoSearch" title="Do a search of some text.">cgiDoSearch</a></li> -<li><a href="#cgiEndHTML" title="End a HTML page.">cgiEndHTML</a></li> -<li><a href="#cgiEndMultipart" title="End the delivery of a multipart web page.">cgiEndMultipart</a></li> -<li><a href="#cgiFormEncode" title="Encode a string as a form variable.">cgiFormEncode</a></li> -<li><a href="#cgiFreeSearch" title="Free a compiled search context.">cgiFreeSearch</a></li> -<li><a href="#cgiGetArray" title="Get an element from a form array.">cgiGetArray</a></li> -<li><a href="#cgiGetAttributes" title="Get the list of attributes that are needed + <li><a href="#cgiCopyTemplateLang" title="Copy a template file using a language...">cgiCopyTemplateLang</a></li> + <li><a href="#cgiDoSearch" title="Do a search of some text.">cgiDoSearch</a></li> + <li><a href="#cgiEndHTML" title="End a HTML page.">cgiEndHTML</a></li> + <li><a href="#cgiEndMultipart" title="End the delivery of a multipart web page.">cgiEndMultipart</a></li> + <li><a href="#cgiFormEncode" title="Encode a string as a form variable.">cgiFormEncode</a></li> + <li><a href="#cgiFreeSearch" title="Free a compiled search context.">cgiFreeSearch</a></li> + <li><a href="#cgiGetArray" title="Get an element from a form array.">cgiGetArray</a></li> + <li><a href="#cgiGetAttributes" title="Get the list of attributes that are needed by the template file.">cgiGetAttributes</a></li> -<li><a href="#cgiGetCookie" title="Get a cookie value.">cgiGetCookie</a></li> -<li><a href="#cgiGetFile" title="Get the file (if any) that was submitted in the form.">cgiGetFile</a></li> -<li><a href="#cgiGetIPPObjects" title="Get the objects in an IPP response.">cgiGetIPPObjects</a></li> -<li><a href="#cgiGetSize" title="Get the size of a form array value.">cgiGetSize</a></li> -<li><a href="#cgiGetTemplateDir" title="Get the templates directory...">cgiGetTemplateDir</a></li> -<li><a href="#cgiGetVariable" title="Get a CGI variable from the database.">cgiGetVariable</a></li> -<li><a href="#cgiInitialize" title="Initialize the CGI variable "database".">cgiInitialize</a></li> -<li><a href="#cgiIsPOST" title="Determine whether this page was POSTed.">cgiIsPOST</a></li> -<li><a href="#cgiMoveJobs" title="Move one or more jobs.">cgiMoveJobs</a></li> -<li><a href="#cgiPrintCommand" title="Print a CUPS command job.">cgiPrintCommand</a></li> -<li><a href="#cgiPrintTestPage" title="Print a test page.">cgiPrintTestPage</a></li> -<li><a href="#cgiRewriteURL" title="Rewrite a printer URI into a web browser URL...">cgiRewriteURL</a></li> -<li><a href="#cgiSetArray" title="Set array element N to the specified string.">cgiSetArray</a></li> -<li><a href="#cgiSetCookie" title="Set a cookie value.">cgiSetCookie</a></li> -<li><a href="#cgiSetIPPObjectVars" title="Set CGI variables from an IPP object.">cgiSetIPPObjectVars</a></li> -<li><a href="#cgiSetIPPVars" title="Set CGI variables from an IPP response.">cgiSetIPPVars</a></li> -<li><a href="#cgiSetServerVersion" title="Set the server name and CUPS version...">cgiSetServerVersion</a></li> -<li><a href="#cgiSetSize" title="Set the array size.">cgiSetSize</a></li> -<li><a href="#cgiSetVariable" title="Set a CGI variable in the database.">cgiSetVariable</a></li> -<li><a href="#cgiShowIPPError" title="Show the last IPP error message.">cgiShowIPPError</a></li> -<li><a href="#cgiShowJobs" title="Show print jobs.">cgiShowJobs</a></li> -<li><a href="#cgiStartHTML" title="Start a HTML page.">cgiStartHTML</a></li> -<li><a href="#cgiStartMultipart" title="Start a multipart delivery of a web page.">cgiStartMultipart</a></li> -<li><a href="#cgiSupportsMultipart" title="Does the browser support multi-part documents?">cgiSupportsMultipart</a></li> -<li><a href="#cgiText" title="Return localized text.">cgiText</a></li> -<li><a href="#helpDeleteIndex" title="Delete an index, freeing all memory used.">helpDeleteIndex</a></li> -<li><a href="#helpFindNode" title="Find a node in an index.">helpFindNode</a></li> -<li><a href="#helpLoadIndex" title="Load a help index from disk.">helpLoadIndex</a></li> -<li><a href="#helpSaveIndex" title="Save a help index to disk.">helpSaveIndex</a></li> -<li><a href="#helpSearchIndex" title="Search an index.">helpSearchIndex</a></li> + <li><a href="#cgiGetCookie" title="Get a cookie value.">cgiGetCookie</a></li> + <li><a href="#cgiGetFile" title="Get the file (if any) that was submitted in the form.">cgiGetFile</a></li> + <li><a href="#cgiGetIPPObjects" title="Get the objects in an IPP response.">cgiGetIPPObjects</a></li> + <li><a href="#cgiGetSize" title="Get the size of a form array value.">cgiGetSize</a></li> + <li><a href="#cgiGetTemplateDir" title="Get the templates directory...">cgiGetTemplateDir</a></li> + <li><a href="#cgiGetVariable" title="Get a CGI variable from the database.">cgiGetVariable</a></li> + <li><a href="#cgiInitialize" title="Initialize the CGI variable "database".">cgiInitialize</a></li> + <li><a href="#cgiIsPOST" title="Determine whether this page was POSTed.">cgiIsPOST</a></li> + <li><a href="#cgiMoveJobs" title="Move one or more jobs.">cgiMoveJobs</a></li> + <li><a href="#cgiPrintCommand" title="Print a CUPS command job.">cgiPrintCommand</a></li> + <li><a href="#cgiPrintTestPage" title="Print a test page.">cgiPrintTestPage</a></li> + <li><a href="#cgiRewriteURL" title="Rewrite a printer URI into a web browser URL...">cgiRewriteURL</a></li> + <li><a href="#cgiSetArray" title="Set array element N to the specified string.">cgiSetArray</a></li> + <li><a href="#cgiSetCookie" title="Set a cookie value.">cgiSetCookie</a></li> + <li><a href="#cgiSetIPPObjectVars" title="Set CGI variables from an IPP object.">cgiSetIPPObjectVars</a></li> + <li><a href="#cgiSetIPPVars" title="Set CGI variables from an IPP response.">cgiSetIPPVars</a></li> + <li><a href="#cgiSetServerVersion" title="Set the server name and CUPS version...">cgiSetServerVersion</a></li> + <li><a href="#cgiSetSize" title="Set the array size.">cgiSetSize</a></li> + <li><a href="#cgiSetVariable" title="Set a CGI variable in the database.">cgiSetVariable</a></li> + <li><a href="#cgiShowIPPError" title="Show the last IPP error message.">cgiShowIPPError</a></li> + <li><a href="#cgiShowJobs" title="Show print jobs.">cgiShowJobs</a></li> + <li><a href="#cgiStartHTML" title="Start a HTML page.">cgiStartHTML</a></li> + <li><a href="#cgiStartMultipart" title="Start a multipart delivery of a web page.">cgiStartMultipart</a></li> + <li><a href="#cgiSupportsMultipart" title="Does the browser support multi-part documents?">cgiSupportsMultipart</a></li> + <li><a href="#cgiText" title="Return localized text.">cgiText</a></li> + <li><a href="#helpDeleteIndex" title="Delete an index, freeing all memory used.">helpDeleteIndex</a></li> + <li><a href="#helpFindNode" title="Find a node in an index.">helpFindNode</a></li> + <li><a href="#helpLoadIndex" title="Load a help index from disk.">helpLoadIndex</a></li> + <li><a href="#helpSaveIndex" title="Save a help index to disk.">helpSaveIndex</a></li> + <li><a href="#helpSearchIndex" title="Search an index.">helpSearchIndex</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#cgi_file_t" title="Uploaded file data">cgi_file_t</a></li> @@ -433,8 +435,9 @@ by the template file.">cgiGetAttributes</a></li> <li><a href="#help_node_s" title="Help node structure...">help_node_s</a></li> <li><a href="#help_word_s" title="Help word structure...">help_word_s</a></li> </ul></li> +</ul> <!-- - "$Id: api-cgi.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-cgi.html 9740 2011-05-04 06:26:22Z mike $" CGI API introduction for CUPS. diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html index d12cbc60..2dd40830 100644 --- a/doc/help/api-cups.html +++ b/doc/help/api-cups.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>CUPS API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>CUPS API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-cups.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" - CUPS API header for the Common UNIX Printing System (CUPS). + CUPS API header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -379,85 +382,88 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> -<li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li> -<li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li> -<li><a href="#OPTIONS">Options</a></li> -<li><a href="#PRINT_JOBS">Print Jobs</a></li> -<li><a href="#ERROR_HANDLING">Error Handling</a></li> -<li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li> + <li><a href="#CLIENTS_AND_SERVERS">Clients and Servers</a></li> + <li><a href="#PRINTERS_AND_CLASSES">Printers and Classes</a></li> + <li><a href="#OPTIONS">Options</a></li> + <li><a href="#PRINT_JOBS">Print Jobs</a></li> + <li><a href="#ERROR_HANDLING">Error Handling</a></li> + <li><a href="#PASSWORDS_AND_AUTHENTICATION">Passwords and Authentication</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li> -<li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li> -<li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li> -<li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li> -<li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li> -<li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li> -<li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li> -<li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li> -<li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li> -<li><a href="#cupsEncryption" title="Get the current encryption settings.">cupsEncryption</a></li> -<li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li> -<li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li> -<li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li> -<li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li> -<li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li> -<li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li> -<li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li> -<li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li> -<li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li> -<li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li> -<li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li> -<li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li> -<li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li> -<li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li> -<li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li> -<li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li> -<li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified + <li><a href="#appleGetPaperSize" title="Get the default paper size.">appleGetPaperSize</a></li> + <li><a href="#cupsAddDest" title="Add a destination to the list of destinations.">cupsAddDest</a></li> + <li><a href="#cupsAddOption" title="Add an option to an option array.">cupsAddOption</a></li> + <li><a href="#cupsAdminCreateWindowsPPD" title="Create the Windows PPD file for a printer.">cupsAdminCreateWindowsPPD</a></li> + <li><a href="#cupsAdminExportSamba" title="Export a printer to Samba.">cupsAdminExportSamba</a></li> + <li><a href="#cupsAdminGetServerSettings" title="Get settings from the server.">cupsAdminGetServerSettings</a></li> + <li><a href="#cupsAdminSetServerSettings" title="Set settings on the server.">cupsAdminSetServerSettings</a></li> + <li><a href="#cupsCancelJob" title="Cancel a print job on the default server.">cupsCancelJob</a></li> + <li><a href="#cupsCancelJob2" title="Cancel or purge a print job.">cupsCancelJob2</a></li> + <li><a href="#cupsCreateJob" title="Create an empty job for streaming.">cupsCreateJob</a></li> + <li><a href="#cupsEncryption" title="Get the current encryption settings.">cupsEncryption</a></li> + <li><a href="#cupsFinishDocument" title="Finish sending a document.">cupsFinishDocument</a></li> + <li><a href="#cupsFreeDests" title="Free the memory used by the list of destinations.">cupsFreeDests</a></li> + <li><a href="#cupsFreeJobs" title="Free memory used by job data.">cupsFreeJobs</a></li> + <li><a href="#cupsFreeOptions" title="Free all memory used by options.">cupsFreeOptions</a></li> + <li><a href="#cupsGetClasses" title="Get a list of printer classes from the default server.">cupsGetClasses</a></li> + <li><a href="#cupsGetDefault" title="Get the default printer or class for the default server.">cupsGetDefault</a></li> + <li><a href="#cupsGetDefault2" title="Get the default printer or class for the specified server.">cupsGetDefault2</a></li> + <li><a href="#cupsGetDest" title="Get the named destination from the list.">cupsGetDest</a></li> + <li><a href="#cupsGetDests" title="Get the list of destinations from the default server.">cupsGetDests</a></li> + <li><a href="#cupsGetDests2" title="Get the list of destinations from the specified server.">cupsGetDests2</a></li> + <li><a href="#cupsGetJobs" title="Get the jobs from the default server.">cupsGetJobs</a></li> + <li><a href="#cupsGetJobs2" title="Get the jobs from the specified server.">cupsGetJobs2</a></li> + <li><a href="#cupsGetNamedDest" title="Get options for the named destination.">cupsGetNamedDest</a></li> + <li><a href="#cupsGetOption" title="Get an option value.">cupsGetOption</a></li> + <li><a href="#cupsGetPPD" title="Get the PPD file for a printer on the default server.">cupsGetPPD</a></li> + <li><a href="#cupsGetPPD2" title="Get the PPD file for a printer from the specified server.">cupsGetPPD2</a></li> + <li><a href="#cupsGetPPD3" title="Get the PPD file for a printer on the specified server if it has changed.">cupsGetPPD3</a></li> -<li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li> -<li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced + <li><a href="#cupsGetPassword" title="Get a password from the user.">cupsGetPassword</a></li> + <li><a href="#cupsGetPassword2" title="Get a password from the user using the advanced password callback.">cupsGetPassword2</a></li> -<li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li> -<li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li> -<li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li> -<li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.) + <li><a href="#cupsGetPrinters" title="Get a list of printers from the default server.">cupsGetPrinters</a></li> + <li><a href="#cupsGetServerPPD" title="Get an available PPD file from the server.">cupsGetServerPPD</a></li> + <li><a href="#cupsLangDefault" title="Return the default language.">cupsLangDefault</a></li> + <li><a href="#cupsLangEncoding" title="Return the character encoding (us-ascii, etc.) for the given language.">cupsLangEncoding</a></li> -<li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li> -<li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li> -<li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li> -<li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li> -<li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li> -<li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li> -<li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li> -<li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li> -<li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li> -<li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified + <li><a href="#cupsLangFlush" title="Flush all language data out of the cache.">cupsLangFlush</a></li> + <li><a href="#cupsLangFree" title="Free language data.">cupsLangFree</a></li> + <li><a href="#cupsLangGet" title="Get a language.">cupsLangGet</a></li> + <li><a href="#cupsNotifySubject" title="Return the subject for the given notification message.">cupsNotifySubject</a></li> + <li><a href="#cupsNotifyText" title="Return the text for the given notification message.">cupsNotifyText</a></li> + <li><a href="#cupsParseOptions" title="Parse options from a command-line argument.">cupsParseOptions</a></li> + <li><a href="#cupsPrintFile" title="Print a file to a printer or class on the default server.">cupsPrintFile</a></li> + <li><a href="#cupsPrintFile2" title="Print a file to a printer or class on the specified server.">cupsPrintFile2</a></li> -<li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the + <li><a href="#cupsPrintFiles" title="Print one or more files to a printer or class on the default server.">cupsPrintFiles</a></li> -<li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the + <li><a href="#cupsPrintFiles2" title="Print one or more files to a printer or class on the specified server.">cupsPrintFiles2</a></li> -<li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li> -<li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li> -<li><a href="#cupsServer" title="Return the hostname/address of the current server.">cupsServer</a></li> -<li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li> -<li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li> -<li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li> -<li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li> -<li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li> -<li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li> -<li><a href="#cupsSetServer" title="Set the default server name and port.">cupsSetServer</a></li> -<li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li> -<li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li> -<li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li> -<li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li> -<li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li> -<li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li> + <li><a href="#cupsRemoveDest" title="Remove a destination from the destination list.">cupsRemoveDest</a></li> + <li><a href="#cupsRemoveOption" title="Remove an option from an option array.">cupsRemoveOption</a></li> + <li><a href="#cupsServer" title="Return the hostname/address of the current server.">cupsServer</a></li> + <li><a href="#cupsSetClientCertCB" title="Set the client certificate callback.">cupsSetClientCertCB</a></li> + <li><a href="#cupsSetCredentials" title="Set the default credentials to be used for SSL/TLS +connections.">cupsSetCredentials</a></li> + <li><a href="#cupsSetDefaultDest" title="Set the default destination.">cupsSetDefaultDest</a></li> + <li><a href="#cupsSetDests" title="Save the list of destinations for the default server.">cupsSetDests</a></li> + <li><a href="#cupsSetDests2" title="Save the list of destinations for the specified server.">cupsSetDests2</a></li> + <li><a href="#cupsSetEncryption" title="Set the encryption preference.">cupsSetEncryption</a></li> + <li><a href="#cupsSetPasswordCB" title="Set the password callback for CUPS.">cupsSetPasswordCB</a></li> + <li><a href="#cupsSetPasswordCB2" title="Set the advanced password callback for CUPS.">cupsSetPasswordCB2</a></li> + <li><a href="#cupsSetServer" title="Set the default server name and port.">cupsSetServer</a></li> + <li><a href="#cupsSetServerCertCB" title="Set the server certificate callback.">cupsSetServerCertCB</a></li> + <li><a href="#cupsSetUser" title="Set the default user name.">cupsSetUser</a></li> + <li><a href="#cupsStartDocument" title="Add a document to a job created with cupsCreateJob().">cupsStartDocument</a></li> + <li><a href="#cupsTempFd" title="Creates a temporary file.">cupsTempFd</a></li> + <li><a href="#cupsTempFile" title="Generates a temporary filename.">cupsTempFile</a></li> + <li><a href="#cupsTempFile2" title="Creates a temporary CUPS file.">cupsTempFile2</a></li> + <li><a href="#cupsUser" title="Return the current user's name.">cupsUser</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> + <li><a href="#cups_client_cert_cb_t" title="Client credentials callback ">cups_client_cert_cb_t</a></li> <li><a href="#cups_dest_t" title="Destination">cups_dest_t</a></li> <li><a href="#cups_device_cb_t" title="Device callback ">cups_device_cb_t</a></li> <li><a href="#cups_job_t" title="Job">cups_job_t</a></li> @@ -465,17 +471,23 @@ specified server.">cupsPrintFiles2</a></li> <li><a href="#cups_password_cb2_t" title="New password callback ">cups_password_cb2_t</a></li> <li><a href="#cups_password_cb_t" title="Password callback">cups_password_cb_t</a></li> <li><a href="#cups_ptype_t" title="Printer type/capability bits">cups_ptype_t</a></li> + <li><a href="#cups_server_cert_cb_t" title="Server credentials callback ">cups_server_cert_cb_t</a></li> </ul></li> <li><a href="#STRUCTURES">Structures</a><ul class="code"> <li><a href="#cups_dest_s" title="Destination">cups_dest_s</a></li> <li><a href="#cups_job_s" title="Job">cups_job_s</a></li> <li><a href="#cups_option_s" title="Printer Options">cups_option_s</a></li> </ul></li> +<li><a href="#VARIABLES">Variables</a><ul class="code"> + <li><a href="#CF_RETURNS_RETAINED" title="Get the Apple language identifier associated with a +locale ID.">CF_RETURNS_RETAINED</a></li> +</ul></li> <li><a href="#ENUMERATIONS">Constants</a><ul class="code"> <li><a href="#cups_ptype_e" title="Printer type/capability bit constants">cups_ptype_e</a></li> </ul></li> +</ul> <!-- - "$Id: api-cups.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" API introduction for CUPS. @@ -918,6 +930,22 @@ fields for the username and password. The username should default to the string returned by the <a href="#cupsUser"><code>cupsUser</code></a> function.</p> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> +<h3 class="function"><a name="appleGetPaperSize">appleGetPaperSize</a></h3> +<p class="description">Get the default paper size.</p> +<p class="code"> +char *appleGetPaperSize (<br> + char *name,<br> + int namesize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>name</dt> +<dd class="description">Paper size name buffer</dd> +<dt>namesize</dt> +<dd class="description">Size of buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Default paper size</p> <h3 class="function"><a name="cupsAddDest">cupsAddDest</a></h3> <p class="description">Add a destination to the list of destinations.</p> <p class="code"> @@ -1716,18 +1744,6 @@ cups_lang_t *cupsLangGet (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Language data</p> -<h3 class="function"><a name="cupsLastError">cupsLastError</a></h3> -<p class="description">Return the last IPP status code.</p> -<p class="code"> -ipp_status_t cupsLastError (void);</p> -<h4 class="returnvalue">Return Value</h4> -<p class="description">IPP status code from last request</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsLastErrorString">cupsLastErrorString</a></h3> -<p class="description">Return the last IPP status-message.</p> -<p class="code"> -const char *cupsLastErrorString (void);</p> -<h4 class="returnvalue">Return Value</h4> -<p class="description">status-message text from last request</p> <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3> <p class="description">Return the subject for the given notification message.</p> <p class="code"> @@ -1975,6 +1991,48 @@ Note: The current server is tracked separately for each thread in a program. Multi-threaded programs that override the server via the <a href="#cupsSetServer"><code>cupsSetServer</code></a> function need to do so in each thread for the same server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cupsSetClientCertCB">cupsSetClientCertCB</a></h3> +<p class="description">Set the client certificate callback.</p> +<p class="code"> +void cupsSetClientCertCB (<br> + <a href="#cups_client_cert_cb_t">cups_client_cert_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> +<br> +Note: The current certificate callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cupsSetCredentials">cupsSetCredentials</a></h3> +<p class="description">Set the default credentials to be used for SSL/TLS +connections.</p> +<p class="code"> +int cupsSetCredentials (<br> + cups_array_t *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> +<dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Status of call (0 = success)</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Note: The default credentials are tracked separately for each thread in a +program. Multi-threaded programs that override the setting need to do so in +each thread for the same setting to be used. + +</p> <h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> <p class="description">Set the default destination.</p> <p class="code"> @@ -2122,6 +2180,28 @@ default server name and port.<br> Note: The current server is tracked separately for each thread in a program. Multi-threaded programs that override the server need to do so in each thread for the same server to be used.</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cupsSetServerCertCB">cupsSetServerCertCB</a></h3> +<p class="description">Set the server certificate callback.</p> +<p class="code"> +void cupsSetServerCertCB (<br> + <a href="#cups_server_cert_cb_t">cups_server_cert_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Pass <code>NULL</code> to restore the default callback.<br> +<br> +Note: The current credentials callback is tracked separately for each thread +in a program. Multi-threaded programs that override the callback need to do +so in each thread for the same callback to be used. + +</p> <h3 class="function"><a name="cupsSetUser">cupsSetUser</a></h3> <p class="description">Set the default user name.</p> <p class="code"> @@ -2251,6 +2331,11 @@ program. Multi-threaded programs that override the user name with the <a href="#cupsSetUser"><code>cupsSetUser</code></a> function need to do so in each thread for the same user name to be used.</p> <h2 class="title"><a name="TYPES">Data Types</a></h2> +<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cups_client_cert_cb_t">cups_client_cert_cb_t</a></h3> +<p class="description">Client credentials callback </p> +<p class="code"> +typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data); +</p> <h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3> <p class="description">Destination</p> <p class="code"> @@ -2286,6 +2371,11 @@ typedef const char *(*cups_password_cb_t)(const char *prompt); <p class="code"> typedef unsigned cups_ptype_t; </p> +<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="cups_server_cert_cb_t">cups_server_cert_cb_t</a></h3> +<p class="description">Server credentials callback </p> +<p class="code"> +typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data); +</p> <h2 class="title"><a name="STRUCTURES">Structures</a></h2> <h3 class="struct"><a name="cups_dest_s">cups_dest_s</a></h3> <p class="description">Destination</p> @@ -2359,6 +2449,11 @@ typedef unsigned cups_ptype_t; <dt>value </dt> <dd class="description">Value of option</dd> </dl> +<h2 class="title"><a name="VARIABLES">Variables</a></h2> +<h3 class="variable"><a name="CF_RETURNS_RETAINED">CF_RETURNS_RETAINED</a></h3> +<p class="description">Get the Apple language identifier associated with a +locale ID.</p> +<p class="code">const char *locale) CF_RETURNS_RETAINED;</p> <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> <h3 class="enumeration"><a name="cups_ptype_e">cups_ptype_e</a></h3> <p class="description">Printer type/capability bit constants</p> diff --git a/doc/help/api-driver.html b/doc/help/api-driver.html index b021207c..1a3ee3ae 100644 --- a/doc/help/api-driver.html +++ b/doc/help/api-driver.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Printer Driver API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Printer Driver API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-driver.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-driver.html 9740 2011-05-04 06:26:22Z mike $" Driver API header for CUPS. @@ -373,40 +376,39 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsCMYKDelete" title="Delete a color separation.">cupsCMYKDelete</a></li> -<li><a href="#cupsCMYKDoBlack" title="Do a black separation...">cupsCMYKDoBlack</a></li> -<li><a href="#cupsCMYKDoCMYK" title="Do a CMYK separation...">cupsCMYKDoCMYK</a></li> -<li><a href="#cupsCMYKDoGray" title="Do a grayscale separation...">cupsCMYKDoGray</a></li> -<li><a href="#cupsCMYKDoRGB" title="Do an sRGB separation...">cupsCMYKDoRGB</a></li> -<li><a href="#cupsCMYKLoad" title="Load a CMYK color profile from PPD attributes.">cupsCMYKLoad</a></li> -<li><a href="#cupsCMYKNew" title="Create a new CMYK color separation.">cupsCMYKNew</a></li> -<li><a href="#cupsCMYKSetBlack" title="Set the transition range for CMY to black.">cupsCMYKSetBlack</a></li> -<li><a href="#cupsCMYKSetCurve" title="Set a color transform curve using points.">cupsCMYKSetCurve</a></li> -<li><a href="#cupsCMYKSetGamma" title="Set a color transform curve using gamma and density.">cupsCMYKSetGamma</a></li> -<li><a href="#cupsCMYKSetInkLimit" title="Set the limit on the amount of ink.">cupsCMYKSetInkLimit</a></li> -<li><a href="#cupsCMYKSetLtDk" title="Set light/dark ink transforms.">cupsCMYKSetLtDk</a></li> -<li><a href="#cupsCheckBytes" title="Check to see if all bytes are zero.">cupsCheckBytes</a></li> -<li><a href="#cupsCheckValue" title="Check to see if all bytes match the given value.">cupsCheckValue</a></li> -<li><a href="#cupsDitherDelete" title="Free a dithering buffer.">cupsDitherDelete</a></li> -<li><a href="#cupsDitherLine" title="Dither a line of pixels...">cupsDitherLine</a></li> -<li><a href="#cupsDitherNew" title="Create an error-diffusion dithering buffer.">cupsDitherNew</a></li> -<li><a href="#cupsFindAttr" title="Find a PPD attribute based on the colormodel, + <li><a href="#cupsCMYKDelete" title="Delete a color separation.">cupsCMYKDelete</a></li> + <li><a href="#cupsCMYKDoBlack" title="Do a black separation...">cupsCMYKDoBlack</a></li> + <li><a href="#cupsCMYKDoCMYK" title="Do a CMYK separation...">cupsCMYKDoCMYK</a></li> + <li><a href="#cupsCMYKDoGray" title="Do a grayscale separation...">cupsCMYKDoGray</a></li> + <li><a href="#cupsCMYKDoRGB" title="Do an sRGB separation...">cupsCMYKDoRGB</a></li> + <li><a href="#cupsCMYKLoad" title="Load a CMYK color profile from PPD attributes.">cupsCMYKLoad</a></li> + <li><a href="#cupsCMYKNew" title="Create a new CMYK color separation.">cupsCMYKNew</a></li> + <li><a href="#cupsCMYKSetBlack" title="Set the transition range for CMY to black.">cupsCMYKSetBlack</a></li> + <li><a href="#cupsCMYKSetCurve" title="Set a color transform curve using points.">cupsCMYKSetCurve</a></li> + <li><a href="#cupsCMYKSetGamma" title="Set a color transform curve using gamma and density.">cupsCMYKSetGamma</a></li> + <li><a href="#cupsCMYKSetInkLimit" title="Set the limit on the amount of ink.">cupsCMYKSetInkLimit</a></li> + <li><a href="#cupsCMYKSetLtDk" title="Set light/dark ink transforms.">cupsCMYKSetLtDk</a></li> + <li><a href="#cupsCheckBytes" title="Check to see if all bytes are zero.">cupsCheckBytes</a></li> + <li><a href="#cupsCheckValue" title="Check to see if all bytes match the given value.">cupsCheckValue</a></li> + <li><a href="#cupsDitherDelete" title="Free a dithering buffer.">cupsDitherDelete</a></li> + <li><a href="#cupsDitherLine" title="Dither a line of pixels...">cupsDitherLine</a></li> + <li><a href="#cupsDitherNew" title="Create an error-diffusion dithering buffer.">cupsDitherNew</a></li> + <li><a href="#cupsFindAttr" title="Find a PPD attribute based on the colormodel, media, and resolution.">cupsFindAttr</a></li> -<li><a href="#cupsLutDelete" title="Free the memory used by a lookup table.">cupsLutDelete</a></li> -<li><a href="#cupsLutLoad" title="Load a LUT from a PPD file.">cupsLutLoad</a></li> -<li><a href="#cupsLutNew" title="Make a lookup table from a list of pixel values.">cupsLutNew</a></li> -<li><a href="#cupsPackHorizontal" title="Pack pixels horizontally...">cupsPackHorizontal</a></li> -<li><a href="#cupsPackHorizontal2" title="Pack 2-bit pixels horizontally...">cupsPackHorizontal2</a></li> -<li><a href="#cupsPackHorizontalBit" title="Pack pixels horizontally by bit...">cupsPackHorizontalBit</a></li> -<li><a href="#cupsPackVertical" title="Pack pixels vertically...">cupsPackVertical</a></li> -<li><a href="#cupsRGBDelete" title="Delete a color separation.">cupsRGBDelete</a></li> -<li><a href="#cupsRGBDoGray" title="Do a grayscale separation...">cupsRGBDoGray</a></li> -<li><a href="#cupsRGBDoRGB" title="Do a RGB separation...">cupsRGBDoRGB</a></li> -<li><a href="#cupsRGBLoad" title="Load a RGB color profile from a PPD file.">cupsRGBLoad</a></li> -<li><a href="#cupsRGBNew" title="Create a new RGB color separation.">cupsRGBNew</a></li> + <li><a href="#cupsLutDelete" title="Free the memory used by a lookup table.">cupsLutDelete</a></li> + <li><a href="#cupsLutLoad" title="Load a LUT from a PPD file.">cupsLutLoad</a></li> + <li><a href="#cupsLutNew" title="Make a lookup table from a list of pixel values.">cupsLutNew</a></li> + <li><a href="#cupsPackHorizontal" title="Pack pixels horizontally...">cupsPackHorizontal</a></li> + <li><a href="#cupsPackHorizontal2" title="Pack 2-bit pixels horizontally...">cupsPackHorizontal2</a></li> + <li><a href="#cupsPackHorizontalBit" title="Pack pixels horizontally by bit...">cupsPackHorizontalBit</a></li> + <li><a href="#cupsPackVertical" title="Pack pixels vertically...">cupsPackVertical</a></li> + <li><a href="#cupsRGBDelete" title="Delete a color separation.">cupsRGBDelete</a></li> + <li><a href="#cupsRGBDoGray" title="Do a grayscale separation...">cupsRGBDoGray</a></li> + <li><a href="#cupsRGBDoRGB" title="Do a RGB separation...">cupsRGBDoRGB</a></li> + <li><a href="#cupsRGBLoad" title="Load a RGB color profile from a PPD file.">cupsRGBLoad</a></li> + <li><a href="#cupsRGBNew" title="Create a new RGB color separation.">cupsRGBNew</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#cups_cmyk_t" title="Simple CMYK lookup table">cups_cmyk_t</a></li> @@ -426,8 +428,9 @@ media, and resolution.">cupsFindAttr</a></li> <li><a href="#cups_scmy_lut[256]" title="sRGB gamma lookup table (inverted)">cups_scmy_lut[256]</a></li> <li><a href="#cups_srgb_lut[256]" title="sRGB gamma lookup table">cups_srgb_lut[256]</a></li> </ul></li> +</ul> <!-- - "$Id: api-driver.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-driver.html 9740 2011-05-04 06:26:22Z mike $" Driver API introduction for CUPS. diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html index ada05aba..430494a7 100644 --- a/doc/help/api-filedir.html +++ b/doc/help/api-filedir.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>File and Directory APIs</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>File and Directory APIs </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-filedir.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-filedir.html 9772 2011-05-12 05:46:30Z mike $" - File and Directory API header for the Common UNIX Printing System (CUPS). + File and Directory API header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -375,42 +378,41 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsDirClose" title="Close a directory.">cupsDirClose</a></li> -<li><a href="#cupsDirOpen" title="Open a directory.">cupsDirOpen</a></li> -<li><a href="#cupsDirRead" title="Read the next directory entry.">cupsDirRead</a></li> -<li><a href="#cupsDirRewind" title="Rewind to the start of the directory.">cupsDirRewind</a></li> -<li><a href="#cupsFileClose" title="Close a CUPS file.">cupsFileClose</a></li> -<li><a href="#cupsFileCompression" title="Return whether a file is compressed.">cupsFileCompression</a></li> -<li><a href="#cupsFileEOF" title="Return the end-of-file status.">cupsFileEOF</a></li> -<li><a href="#cupsFileFind" title="Find a file using the specified path.">cupsFileFind</a></li> -<li><a href="#cupsFileFlush" title="Flush pending output.">cupsFileFlush</a></li> -<li><a href="#cupsFileGetChar" title="Get a single character from a file.">cupsFileGetChar</a></li> -<li><a href="#cupsFileGetConf" title="Get a line from a configuration file...">cupsFileGetConf</a></li> -<li><a href="#cupsFileGetLine" title="Get a CR and/or LF-terminated line that may + <li><a href="#cupsDirClose" title="Close a directory.">cupsDirClose</a></li> + <li><a href="#cupsDirOpen" title="Open a directory.">cupsDirOpen</a></li> + <li><a href="#cupsDirRead" title="Read the next directory entry.">cupsDirRead</a></li> + <li><a href="#cupsDirRewind" title="Rewind to the start of the directory.">cupsDirRewind</a></li> + <li><a href="#cupsFileClose" title="Close a CUPS file.">cupsFileClose</a></li> + <li><a href="#cupsFileCompression" title="Return whether a file is compressed.">cupsFileCompression</a></li> + <li><a href="#cupsFileEOF" title="Return the end-of-file status.">cupsFileEOF</a></li> + <li><a href="#cupsFileFind" title="Find a file using the specified path.">cupsFileFind</a></li> + <li><a href="#cupsFileFlush" title="Flush pending output.">cupsFileFlush</a></li> + <li><a href="#cupsFileGetChar" title="Get a single character from a file.">cupsFileGetChar</a></li> + <li><a href="#cupsFileGetConf" title="Get a line from a configuration file.">cupsFileGetConf</a></li> + <li><a href="#cupsFileGetLine" title="Get a CR and/or LF-terminated line that may contain binary data.">cupsFileGetLine</a></li> -<li><a href="#cupsFileGets" title="Get a CR and/or LF-terminated line.">cupsFileGets</a></li> -<li><a href="#cupsFileLock" title="Temporarily lock access to a file.">cupsFileLock</a></li> -<li><a href="#cupsFileNumber" title="Return the file descriptor associated with a CUPS file.">cupsFileNumber</a></li> -<li><a href="#cupsFileOpen" title="Open a CUPS file.">cupsFileOpen</a></li> -<li><a href="#cupsFileOpenFd" title="Open a CUPS file using a file descriptor.">cupsFileOpenFd</a></li> -<li><a href="#cupsFilePeekChar" title="Peek at the next character from a file.">cupsFilePeekChar</a></li> -<li><a href="#cupsFilePrintf" title="Write a formatted string.">cupsFilePrintf</a></li> -<li><a href="#cupsFilePutChar" title="Write a character.">cupsFilePutChar</a></li> -<li><a href="#cupsFilePutConf" title="Write a configuration line.">cupsFilePutConf</a></li> -<li><a href="#cupsFilePuts" title="Write a string.">cupsFilePuts</a></li> -<li><a href="#cupsFileRead" title="Read from a file.">cupsFileRead</a></li> -<li><a href="#cupsFileRewind" title="Set the current file position to the beginning of the + <li><a href="#cupsFileGets" title="Get a CR and/or LF-terminated line.">cupsFileGets</a></li> + <li><a href="#cupsFileLock" title="Temporarily lock access to a file.">cupsFileLock</a></li> + <li><a href="#cupsFileNumber" title="Return the file descriptor associated with a CUPS file.">cupsFileNumber</a></li> + <li><a href="#cupsFileOpen" title="Open a CUPS file.">cupsFileOpen</a></li> + <li><a href="#cupsFileOpenFd" title="Open a CUPS file using a file descriptor.">cupsFileOpenFd</a></li> + <li><a href="#cupsFilePeekChar" title="Peek at the next character from a file.">cupsFilePeekChar</a></li> + <li><a href="#cupsFilePrintf" title="Write a formatted string.">cupsFilePrintf</a></li> + <li><a href="#cupsFilePutChar" title="Write a character.">cupsFilePutChar</a></li> + <li><a href="#cupsFilePutConf" title="Write a configuration line.">cupsFilePutConf</a></li> + <li><a href="#cupsFilePuts" title="Write a string.">cupsFilePuts</a></li> + <li><a href="#cupsFileRead" title="Read from a file.">cupsFileRead</a></li> + <li><a href="#cupsFileRewind" title="Set the current file position to the beginning of the file.">cupsFileRewind</a></li> -<li><a href="#cupsFileSeek" title="Seek in a file.">cupsFileSeek</a></li> -<li><a href="#cupsFileStderr" title="Return a CUPS file associated with stderr.">cupsFileStderr</a></li> -<li><a href="#cupsFileStdin" title="Return a CUPS file associated with stdin.">cupsFileStdin</a></li> -<li><a href="#cupsFileStdout" title="Return a CUPS file associated with stdout.">cupsFileStdout</a></li> -<li><a href="#cupsFileTell" title="Return the current file position.">cupsFileTell</a></li> -<li><a href="#cupsFileUnlock" title="Unlock access to a file.">cupsFileUnlock</a></li> -<li><a href="#cupsFileWrite" title="Write to a file.">cupsFileWrite</a></li> + <li><a href="#cupsFileSeek" title="Seek in a file.">cupsFileSeek</a></li> + <li><a href="#cupsFileStderr" title="Return a CUPS file associated with stderr.">cupsFileStderr</a></li> + <li><a href="#cupsFileStdin" title="Return a CUPS file associated with stdin.">cupsFileStdin</a></li> + <li><a href="#cupsFileStdout" title="Return a CUPS file associated with stdout.">cupsFileStdout</a></li> + <li><a href="#cupsFileTell" title="Return the current file position.">cupsFileTell</a></li> + <li><a href="#cupsFileUnlock" title="Unlock access to a file.">cupsFileUnlock</a></li> + <li><a href="#cupsFileWrite" title="Write to a file.">cupsFileWrite</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#cups_dentry_t" title="Directory entry type">cups_dentry_t</a></li> @@ -420,8 +422,9 @@ file.">cupsFileRewind</a></li> <li><a href="#STRUCTURES">Structures</a><ul class="code"> <li><a href="#cups_dentry_s" title="Directory entry type">cups_dentry_s</a></li> </ul></li> +</ul> <!-- - "$Id: api-filedir.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-filedir.html 9772 2011-05-12 05:46:30Z mike $" File and directory API introduction for CUPS. @@ -599,7 +602,7 @@ int cupsFileGetChar (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">Character or -1 on end of file</p> <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetConf">cupsFileGetConf</a></h3> -<p class="description">Get a line from a configuration file...</p> +<p class="description">Get a line from a configuration file.</p> <p class="code"> char *cupsFileGetConf (<br> <a href="#cups_file_t">cups_file_t</a> *fp,<br> diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 22a1ff40..3a9d1288 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Filter and Backend Programming</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Filter and Backend Programming </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,12 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-filter.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-filter.html 9799 2011-05-20 18:09:22Z mike $" - Filter and backend programming header for the Common UNIX Printing System - (CUPS). + Filter and backend programming header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -381,34 +383,35 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> -<li><a href="#SECURITY">Security Considerations</a></li> -<li><a href="#PERMISSIONS">File Permissions</a></li> -<li><a href="#TEMPFILES">Temporary Files</a></li> -<li><a href="#COPIES">Copy Generation</a></li> -<li><a href="#EXITCODES">Exit Codes</a></li> -<li><a href="#ENVIRONMENT">Environment Variables</a></li> -<li><a href="#MESSAGES">Communicating with the Scheduler</a></li> -<li><a href="#COMMUNICATING_BACKEND">Communicating with the Backend</a></li> -<li><a href="#COMMUNICATING_FILTER">Communicating with Filters</a></li> -<li><a href="#SNMP">Doing SNMP Queries with Network Printers</a></li> + <li><a href="#SECURITY">Security Considerations</a></li> + <li><a href="#SIGNALS">Canceled Jobs and Signal Handling</a></li> + <li><a href="#PERMISSIONS">File Permissions</a></li> + <li><a href="#TEMPFILES">Temporary Files</a></li> + <li><a href="#COPIES">Copy Generation</a></li> + <li><a href="#EXITCODES">Exit Codes</a></li> + <li><a href="#ENVIRONMENT">Environment Variables</a></li> + <li><a href="#MESSAGES">Communicating with the Scheduler</a></li> + <li><a href="#COMMUNICATING_BACKEND">Communicating with the Backend</a></li> + <li><a href="#COMMUNICATING_FILTER">Communicating with Filters</a></li> + <li><a href="#SNMP">Doing SNMP Queries with Network Printers</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsBackChannelRead" title="Read data from the backchannel.">cupsBackChannelRead</a></li> -<li><a href="#cupsBackChannelWrite" title="Write data to the backchannel.">cupsBackChannelWrite</a></li> -<li><a href="#cupsBackendDeviceURI" title="Get the device URI for a backend.">cupsBackendDeviceURI</a></li> -<li><a href="#cupsBackendReport" title="Write a device line from a backend.">cupsBackendReport</a></li> -<li><a href="#cupsSideChannelDoRequest" title="Send a side-channel command to a backend and wait for a response.">cupsSideChannelDoRequest</a></li> -<li><a href="#cupsSideChannelRead" title="Read a side-channel message.">cupsSideChannelRead</a></li> -<li><a href="#cupsSideChannelSNMPGet" title="Query a SNMP OID's value.">cupsSideChannelSNMPGet</a></li> -<li><a href="#cupsSideChannelSNMPWalk" title="Query multiple SNMP OID values.">cupsSideChannelSNMPWalk</a></li> -<li><a href="#cupsSideChannelWrite" title="Write a side-channel message.">cupsSideChannelWrite</a></li> + <li><a href="#cupsBackChannelRead" title="Read data from the backchannel.">cupsBackChannelRead</a></li> + <li><a href="#cupsBackChannelWrite" title="Write data to the backchannel.">cupsBackChannelWrite</a></li> + <li><a href="#cupsBackendDeviceURI" title="Get the device URI for a backend.">cupsBackendDeviceURI</a></li> + <li><a href="#cupsBackendReport" title="Write a device line from a backend.">cupsBackendReport</a></li> + <li><a href="#cupsSideChannelDoRequest" title="Send a side-channel command to a backend and wait for a response.">cupsSideChannelDoRequest</a></li> + <li><a href="#cupsSideChannelRead" title="Read a side-channel message.">cupsSideChannelRead</a></li> + <li><a href="#cupsSideChannelSNMPGet" title="Query a SNMP OID's value.">cupsSideChannelSNMPGet</a></li> + <li><a href="#cupsSideChannelSNMPWalk" title="Query multiple SNMP OID values.">cupsSideChannelSNMPWalk</a></li> + <li><a href="#cupsSideChannelWrite" title="Write a side-channel message.">cupsSideChannelWrite</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#cups_backend_t" title="Backend exit codes">cups_backend_t</a></li> <li><a href="#cups_sc_bidi_t" title="Bidirectional capabilities">cups_sc_bidi_t</a></li> <li><a href="#cups_sc_command_t" title="Request command codes">cups_sc_command_t</a></li> + <li><a href="#cups_sc_connected_t" title="Connectivity values">cups_sc_connected_t</a></li> <li><a href="#cups_sc_state_t" title="Printer state bits">cups_sc_state_t</a></li> <li><a href="#cups_sc_status_t" title="Response status codes">cups_sc_status_t</a></li> <li><a href="#cups_sc_walk_func_t" title="SNMP walk callback">cups_sc_walk_func_t</a></li> @@ -417,16 +420,17 @@ div.contents ul.subcontents li { <li><a href="#cups_backend_e" title="Backend exit codes">cups_backend_e</a></li> <li><a href="#cups_sc_bidi_e" title="Bidirectional capability values">cups_sc_bidi_e</a></li> <li><a href="#cups_sc_command_e" title="Request command codes">cups_sc_command_e</a></li> + <li><a href="#cups_sc_connected_e" title="Connectivity values">cups_sc_connected_e</a></li> <li><a href="#cups_sc_state_e" title="Printer state bits">cups_sc_state_e</a></li> <li><a href="#cups_sc_status_e" title="Response status codes">cups_sc_status_e</a></li> </ul></li> +</ul> <!-- - "$Id: api-filter.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-filter.html 9799 2011-05-20 18:09:22Z mike $" - Filter and backend programming introduction for the Common UNIX Printing - System (CUPS). + Filter and backend programming introduction for CUPS. - Copyright 2007-2009 by Apple Inc. + Copyright 2007-2011 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -507,6 +511,31 @@ that further limit file system access, even for backends running as root. On Mac OS X, for example, no backend may write to a user's home directory.</p> </blockquote> +<h3><a name="SIGNALS">Canceled Jobs and Signal Handling</a></h3> + +<p>The scheduler sends <code>SIGTERM</code> when a printing job is canceled or +held. Filters, backends, and port monitors <em>must</em> catch +<code>SIGTERM</code> and perform any cleanup necessary to produce a valid output +file or return the printer to a known good state. The recommended behavior is to +end the output on the current page, preferably on the current line or object +being printed.</p> + +<p>Filters and backends may also receive <code>SIGPIPE</code> when an upstream or downstream filter/backend exits with a non-zero status. Developers should generally ignore <code>SIGPIPE</code> at the beginning of <code>main()</code> with the following function call:</p> + +<pre class="example"> +#include <signal.h>> + +... + +int +main(int argc, char *argv[]) +{ + signal(SIGPIPE, SIG_IGN); + + ... +} +</pre> + <h3><a name="PERMISSIONS">File Permissions</a></h3> <p>For security reasons, CUPS will only run filters and backends that are owned @@ -629,7 +658,8 @@ prefix strings:</p> <dt>ATTR: attribute=value [attribute=value]</dt> <dd>Sets the named printer or job attribute(s). Typically this is used - to set the <code>marker-colors</code>, <code>marker-levels</code>, + to set the <code>marker-colors</code>, <code>marker-high-levels</code>, + <code>marker-levels</code>, <code>marker-low-levels</code>, <code>marker-message</code>, <code>marker-names</code>, <code>marker-types</code>, <code>printer-alert</code>, and <code>printer-alert-description</code> printer attributes. Standard @@ -679,23 +709,15 @@ prefix strings:</p> this is used to update installable options or default media settings based on the printer configuration.</dd> - <dt>STATE: printer-state-reason [printer-state-reason ...]</dt> <dt>STATE: + printer-state-reason [printer-state-reason ...]</dt> <dt>STATE: - printer-state-reason [printer-state-reason ...]</dt> - <dd>Sets, adds, or removes printer-state-reason keywords to the - current queue. Typically this is used to indicate persistent media, - ink, toner, and configuration conditions or errors on a printer. + <dd>Sets or clears printer-state-reason keywords for the current queue. + Typically this is used to indicate persistent media, ink, toner, and + configuration conditions or errors on a printer. <a href='#TABLE2'>Table 2</a> lists the standard state keywords - - use vendor-prefixed ("com.acme.foo") keywords for custom states. - - <blockquote><b>Note:</b> - - <p>"STATE:" messages often provide visible alerts to the user. For example, on - Mac OS X setting a printer-state-reason value with an "-error" or "-warning" - suffix will cause the printer's dock item to bounce if the corresponding reason - is localized with a cupsIPPReason keyword in the printer's PPD file.</p> - - </blockquote></dd> + use vendor-prefixed ("com.example.foo") keywords for custom states. See + <a href="#MANAGING_STATE">Managing Printer State in a Filter</a> for more + information. <dt>WARNING: message</dt> <dd>Sets the printer-state-message attribute and adds the specified @@ -784,59 +806,190 @@ the "DEBUG:" prefix string.</p> <tbody> <tr> <td>connecting-to-device</td> - <td>Connecting to printer but not printing yet</td> + <td>Connecting to printer but not printing yet.</td> </tr> <tr> <td>cover-open</td> - <td>A cover is open on the printer</td> + <td>The printer's cover is open.</td> </tr> <tr> <td>input-tray-missing</td> - <td>An input tray is missing from the printer</td> + <td>The paper tray is missing.</td> </tr> <tr> <td>marker-supply-empty</td> - <td>Out of ink</td> + <td>The printer is out of ink.</td> </tr> <tr> <td>marker-supply-low</td> - <td>Low on ink</td> + <td>The printer is almost out of ink.</td> </tr> <tr> <td>marker-waste-almost-full</td> - <td>Waste tank almost full</td> + <td>The printer's waste bin is almost full.</td> </tr> <tr> <td>marker-waste-full</td> - <td>Waste tank full</td> + <td>The printer's waste bin is full.</td> </tr> <tr> <td>media-empty</td> - <td>Out of media</td> + <td>The paper tray (any paper tray) is empty.</td> </tr> <tr> <td>media-jam</td> - <td>Media is jammed in the printer</td> + <td>There is a paper jam.</td> </tr> <tr> <td>media-low</td> - <td>Low on media</td> + <td>The paper tray (any paper tray) is almost empty.</td> +</tr> +<tr> + <td>media-needed</td> + <td>The paper tray needs to be filled (for a job that is printing).</td> </tr> <tr> <td>paused</td> - <td>Stop the printer</td> + <td>Stop the printer.</td> </tr> <tr> <td>timed-out</td> - <td>Unable to connect to printer</td> + <td>Unable to connect to printer.</td> </tr> <tr> <td>toner-empty</td> - <td>Out of toner</td> + <td>The printer is out of toner.</td> </tr> <tr> <td>toner-low</td> - <td>Low on toner</td> + <td>The printer is low on toner.</td> +</tr> +</tbody> +</table></div> + +<h4><a name="MANAGING_STATE">Managing Printer State in a Filter</a></h4> + +<p>Filters are responsible for managing the state keywords they set using +"STATE:" messages. Typically you will update <em>all</em> of the keywords that +are used by the filter at startup, for example:</p> + +<pre class="example"> +if (foo_condition != 0) + fputs("STATE: +com.example.foo\n", stderr); +else + fputs("STATE: -com.example.foo\n", stderr); + +if (bar_condition != 0) + fputs("STATE: +com.example.bar\n", stderr); +else + fputs("STATE: -com.example.bar\n", stderr); +</pre> + +<p>Then as conditions change, your filter sends "STATE: +keyword" or "STATE: +-keyword" messages as necessary to set or clear the corresponding keyword, +respectively.</p> + +<p>State keywords are often used to notify the user of issues that span across +jobs, for example "media-empty-warning" that indicates one or more paper trays +are empty. These keywords should not be cleared unless the corresponding issue +no longer exists.</p> + +<p>Filters should clear job-related keywords on startup and exit so that they +do not remain set between jobs. For example, "connecting-to-device" is a job +sub-state and not an issue that applies when a job is not printing.</p> + +<blockquote><b>Note:</b> + +<p>"STATE:" messages often provide visible alerts to the user. For example, +on Mac OS X setting a printer-state-reason value with an "-error" or +"-warning" suffix will cause the printer's dock item to bounce if the +corresponding reason is localized with a cupsIPPReason keyword in the +printer's PPD file.</p> + +<p>When providing a vendor-prefixed keyword, <em>always</em> provide the +corresponding standard keyword (if any) to allow clients to respond to the +condition correctly. For example, if you provide a vendor-prefixed keyword +for a low cyan ink condition ("com.example.cyan-ink-low") you must also set the +"marker-supply-low-warning" keyword. In such cases you should also refrain +from localizing the vendor-prefixed keyword in the PPD file - otherwise both +the generic and vendor-specific keyword will be shown in the user +interface.</p> + +</blockquote></dd> + +<h4><a name="REPORTING_SUPPLIES">Reporting Supply Levels</a></h4> + +<p>CUPS tracks several "marker-*" attributes for ink/toner supply level +reporting. These attributes allow applications to display the current supply +levels for a printer without printer-specific software. <a href="#TABLE3">Table 3</a> lists the marker attributes and what they represent.</p> + +<p>Filters set marker attributes by sending "ATTR:" messages to stderr. For +example, a filter supporting an inkjet printer with black and tri-color ink +cartridges would use the following to initialize the supply attributes:</p> + +<pre class="example"> +fputs("ATTR: marker-colors=#000000,#00FFFF#FF00FF#FFFF00\n", stderr); +fputs("ATTR: marker-low-levels=5,10\n", stderr); +fputs("ATTR: marker-names=Black,Tri-Color\n", stderr); +fputs("ATTR: marker-types=ink,ink\n", stderr); +</pre> + +<p>Then periodically the filter queries the printer for its current supply +levels and updates them with a separate "ATTR:" message:</p> + +<pre class="example"> +int black_level, tri_level; +... +fprintf(stderr, "ATTR: marker-levels=%d,%d\n", black_level, tri_level); +</pre> + +<div class='table'><table width='80%' summary='Table 3: Supply Level Attributes'> +<caption>Table 3: <a name='TABLE3'>Supply Level Attributes</a></caption> +<thead> +<tr> + <th>Attribute</th> + <th>Description</th> +</tr> +</thead> +<tbody> +<tr> + <td>marker-colors</td> + <td>A list of comma-separated colors; each color is either "none" or one or + more hex-encoded sRGB colors of the form "#RRGGBB".</td> +</tr> +<tr> + <td>marker-high-levels</td> + <td>A list of comma-separated "almost full" level values from 0 to 100; a + value of 100 should be used for supplies that are consumed/emptied like ink + cartridges.</td> +</tr> +<tr> + <td>marker-levels</td> + <td>A list of comma-separated level values for each supply. A value of -1 + indicates the level is unavailable, -2 indicates unknown, and -3 indicates + the level is unknown but has not yet reached capacity. Values from 0 to 100 + indicate the corresponding percentage.</td> +</tr> +<tr> + <td>marker-low-levels</td> + <td>A list of comma-separated "almost empty" level values from 0 to 100; a + value of 0 should be used for supplies that are filled like waste ink + tanks.</td> +</tr> +<tr> + <td>marker-message</td> + <td>A human-readable supply status message for the user like "12 pages of + ink remaining."</td> +</tr> +<tr> + <td>marker-names</td> + <td>A list of comma-separated supply names like "Cyan Ink", "Fuser", + etc.</td> +</tr> +<tr> + <td>marker-types</td> + <td>A list of comma-separated supply types; the types are listed in + <a href="#TABLE1">Table 1</a>.</td> </tr> </tbody> </table></div> @@ -846,7 +999,7 @@ the "DEBUG:" prefix string.</p> <p>Filters can communicate with the backend via the <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> and <a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> -functions. The +functions. The <a href="#cupsBackChannelRead"><code>cupsBackChannelRead</code></a> function reads data that has been sent back from the device and is typically used to obtain status and configuration information. For example, the following code @@ -893,6 +1046,38 @@ else data[0] = '\0'; </pre> +<h4><a name="DRAIN_OUTPUT">Forcing All Output to a Printer</a></h4> + +<p>The +<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a> +function allows you to tell the backend to send all pending data to the printer. +This is most often needed when sending query commands to the printer. For example:</p> + +<pre class="example"> +#include <cups/cups.h> +#include <cups/sidechannel.h> + +char data[1024]; +int datalen = sizeof(data); +<a href="#cups_sc_status_t">cups_sc_status_t</a> status; + +/* Flush pending output to stdout */ +fflush(stdout); + +/* Drain output to backend, waiting for up to 30 seconds */ +status = <a href="#cupsSideChannelDoRequest">cupsSideChannelDoRequest</a>(CUPS_SC_CMD_DRAIN_OUTPUT, data, &datalen, 30.0); + +/* Read the response if the output was sent */ +if (status == CUPS_SC_STATUS_OK) +{ + ssize_t bytes; + + /* Wait up to 10.0 seconds for back-channel data */ + bytes = cupsBackChannelRead(data, sizeof(data), 10.0); + /* do something with the data from the printer */ +} +</pre> + <h3><a name="COMMUNICATING_FILTER">Communicating with Filters</a></h3> <p>Backends communicate with filters using the reciprocal functions @@ -1312,6 +1497,11 @@ typedef enum <a href="#cups_sc_bidi_e">cups_sc_bidi_e</a> cups_sc_bidi_t; <p class="code"> typedef enum <a href="#cups_sc_command_e">cups_sc_command_e</a> cups_sc_command_t; </p> +<h3 class="typedef"><a name="cups_sc_connected_t">cups_sc_connected_t</a></h3> +<p class="description">Connectivity values</p> +<p class="code"> +typedef enum <a href="#cups_sc_connected_e">cups_sc_connected_e</a> cups_sc_connected_t; +</p> <h3 class="typedef"><a name="cups_sc_state_t">cups_sc_state_t</a></h3> <p class="description">Printer state bits</p> <p class="code"> @@ -1342,6 +1532,10 @@ typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datal <dd class="description">Job failed, hold job</dd> <dt>CUPS_BACKEND_OK </dt> <dd class="description">Job completed successfully</dd> +<dt>CUPS_BACKEND_RETRY </dt> +<dd class="description">Job failed, retry this job later</dd> +<dt>CUPS_BACKEND_RETRY_CURRENT </dt> +<dd class="description">Job failed, retry this job immediately</dd> <dt>CUPS_BACKEND_STOP </dt> <dd class="description">Job failed, stop queue</dd> </dl> @@ -1362,6 +1556,8 @@ typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datal <dd class="description">Drain all pending output</dd> <dt>CUPS_SC_CMD_GET_BIDI </dt> <dd class="description">Return bidirectional capabilities</dd> +<dt>CUPS_SC_CMD_GET_CONNECTED <span class="info"> CUPS 1.5/Mac OS X 10.7 </span></dt> +<dd class="description">Return whether the backend is "connected" to the printer </dd> <dt>CUPS_SC_CMD_GET_DEVICE_ID </dt> <dd class="description">Return the IEEE-1284 device ID</dd> <dt>CUPS_SC_CMD_GET_STATE </dt> @@ -1373,6 +1569,15 @@ typedef void (*cups_sc_walk_func_t)(const char *oid, const char *data, int datal <dt>CUPS_SC_CMD_SOFT_RESET </dt> <dd class="description">Do a soft reset</dd> </dl> +<h3 class="enumeration"><a name="cups_sc_connected_e">cups_sc_connected_e</a></h3> +<p class="description">Connectivity values</p> +<h4 class="constants">Constants</h4> +<dl> +<dt>CUPS_SC_CONNECTED </dt> +<dd class="description">Backend is "connected" to printer</dd> +<dt>CUPS_SC_NOT_CONNECTED </dt> +<dd class="description">Backend is not "connected" to printer</dd> +</dl> <h3 class="enumeration"><a name="cups_sc_state_e">cups_sc_state_e</a></h3> <p class="description">Printer state bits</p> <h4 class="constants">Constants</h4> diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html index 76c45bde..38a3e3fc 100644 --- a/doc/help/api-httpipp.html +++ b/doc/help/api-httpipp.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>HTTP and IPP APIs</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>HTTP and IPP APIs </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-httpipp.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-httpipp.html 9801 2011-05-21 04:02:41Z mike $" - HTTP and IPP API header for the Common UNIX Printing System (CUPS). + HTTP and IPP API header for CUPS. - Copyright 2007-2009 by Apple Inc. + Copyright 2007-2011 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -376,146 +379,155 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> -<li><a href="#CREATING_URI_STRINGS">Creating URI Strings</a></li> -<li><a href="#SENDING_REQUESTS_WITH_FILES">Sending Requests with Files</a></li> -<li><a href="#ASYNCHRONOUS_REQUEST_PROCESSING">Asynchronous Request Processing</a></li> + <li><a href="#CREATING_URI_STRINGS">Creating URI Strings</a></li> + <li><a href="#SENDING_REQUESTS_WITH_FILES">Sending Requests with Files</a></li> + <li><a href="#ASYNCHRONOUS_REQUEST_PROCESSING">Asynchronous Request Processing</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsDoAuthentication" title="Authenticate a request.">cupsDoAuthentication</a></li> -<li><a href="#cupsDoFileRequest" title="Do an IPP request with a file.">cupsDoFileRequest</a></li> -<li><a href="#cupsDoIORequest" title="Do an IPP request with file descriptors.">cupsDoIORequest</a></li> -<li><a href="#cupsDoRequest" title="Do an IPP request.">cupsDoRequest</a></li> -<li><a href="#cupsEncodeOptions" title="Encode printer options into IPP attributes.">cupsEncodeOptions</a></li> -<li><a href="#cupsEncodeOptions2" title="Encode printer options into IPP attributes for a group.">cupsEncodeOptions2</a></li> -<li><a href="#cupsGetDevices" title="Get available printer devices.">cupsGetDevices</a></li> -<li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li> -<li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li> -<li><a href="#cupsGetResponse" title="Get a response to an IPP request.">cupsGetResponse</a></li> -<li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li> -<li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li> -<li><a href="#cupsReadResponseData" title="Read additional data after the IPP response.">cupsReadResponseData</a></li> -<li><a href="#cupsSendRequest" title="Send an IPP request.">cupsSendRequest</a></li> -<li><a href="#cupsWriteRequestData" title="Write additional data after an IPP request.">cupsWriteRequestData</a></li> -<li><a href="#httpAddrAny" title="Check for the "any" address.">httpAddrAny</a></li> -<li><a href="#httpAddrEqual" title="Compare two addresses.">httpAddrEqual</a></li> -<li><a href="#httpAddrLength" title="Return the length of the address in bytes.">httpAddrLength</a></li> -<li><a href="#httpAddrLocalhost" title="Check for the local loopback address.">httpAddrLocalhost</a></li> -<li><a href="#httpAddrLookup" title="Lookup the hostname associated with the address.">httpAddrLookup</a></li> -<li><a href="#httpAddrString" title="Convert an address to a numeric string.">httpAddrString</a></li> -<li><a href="#httpAssembleURI" title="Assemble a uniform resource identifier from its + <li><a href="#cupsDoAuthentication" title="Authenticate a request.">cupsDoAuthentication</a></li> + <li><a href="#cupsDoFileRequest" title="Do an IPP request with a file.">cupsDoFileRequest</a></li> + <li><a href="#cupsDoIORequest" title="Do an IPP request with file descriptors.">cupsDoIORequest</a></li> + <li><a href="#cupsDoRequest" title="Do an IPP request.">cupsDoRequest</a></li> + <li><a href="#cupsEncodeOptions" title="Encode printer options into IPP attributes.">cupsEncodeOptions</a></li> + <li><a href="#cupsEncodeOptions2" title="Encode printer options into IPP attributes for a group.">cupsEncodeOptions2</a></li> + <li><a href="#cupsGetDevices" title="Get available printer devices.">cupsGetDevices</a></li> + <li><a href="#cupsGetFd" title="Get a file from the server.">cupsGetFd</a></li> + <li><a href="#cupsGetFile" title="Get a file from the server.">cupsGetFile</a></li> + <li><a href="#cupsGetResponse" title="Get a response to an IPP request.">cupsGetResponse</a></li> + <li><a href="#cupsLastError" title="Return the last IPP status code.">cupsLastError</a></li> + <li><a href="#cupsLastErrorString" title="Return the last IPP status-message.">cupsLastErrorString</a></li> + <li><a href="#cupsPutFd" title="Put a file on the server.">cupsPutFd</a></li> + <li><a href="#cupsPutFile" title="Put a file on the server.">cupsPutFile</a></li> + <li><a href="#cupsReadResponseData" title="Read additional data after the IPP response.">cupsReadResponseData</a></li> + <li><a href="#cupsSendRequest" title="Send an IPP request.">cupsSendRequest</a></li> + <li><a href="#cupsWriteRequestData" title="Write additional data after an IPP request.">cupsWriteRequestData</a></li> + <li><a href="#httpAddCredential" title="Allocates and adds a single credential to an array.">httpAddCredential</a></li> + <li><a href="#httpAddrAny" title="Check for the "any" address.">httpAddrAny</a></li> + <li><a href="#httpAddrEqual" title="Compare two addresses.">httpAddrEqual</a></li> + <li><a href="#httpAddrLength" title="Return the length of the address in bytes.">httpAddrLength</a></li> + <li><a href="#httpAddrLocalhost" title="Check for the local loopback address.">httpAddrLocalhost</a></li> + <li><a href="#httpAddrLookup" title="Lookup the hostname associated with the address.">httpAddrLookup</a></li> + <li><a href="#httpAddrString" title="Convert an address to a numeric string.">httpAddrString</a></li> + <li><a href="#httpAssembleURI" title="Assemble a uniform resource identifier from its components.">httpAssembleURI</a></li> -<li><a href="#httpAssembleURIf" title="Assemble a uniform resource identifier from its + <li><a href="#httpAssembleURIf" title="Assemble a uniform resource identifier from its components with a formatted resource.">httpAssembleURIf</a></li> -<li><a href="#httpBlocking" title="Set blocking/non-blocking behavior on a connection.">httpBlocking</a></li> -<li><a href="#httpCheck" title="Check to see if there is a pending response from the server.">httpCheck</a></li> -<li><a href="#httpClearCookie" title="Clear the cookie value(s).">httpClearCookie</a></li> -<li><a href="#httpClearFields" title="Clear HTTP request fields.">httpClearFields</a></li> -<li><a href="#httpClose" title="Close an HTTP connection.">httpClose</a></li> -<li><a href="#httpConnect" title="Connect to a HTTP server.">httpConnect</a></li> -<li><a href="#httpConnectEncrypt" title="Connect to a HTTP server using encryption.">httpConnectEncrypt</a></li> -<li><a href="#httpDecode64" title="Base64-decode a string.">httpDecode64</a></li> -<li><a href="#httpDecode64_2" title="Base64-decode a string.">httpDecode64_2</a></li> -<li><a href="#httpDelete" title="Send a DELETE request to the server.">httpDelete</a></li> -<li><a href="#httpEncode64" title="Base64-encode a string.">httpEncode64</a></li> -<li><a href="#httpEncode64_2" title="Base64-encode a string.">httpEncode64_2</a></li> -<li><a href="#httpEncryption" title="Set the required encryption on the link.">httpEncryption</a></li> -<li><a href="#httpError" title="Get the last error on a connection.">httpError</a></li> -<li><a href="#httpFlush" title="Flush data from a HTTP connection.">httpFlush</a></li> -<li><a href="#httpFlushWrite" title="Flush data in write buffer.">httpFlushWrite</a></li> -<li><a href="#httpGet" title="Send a GET request to the server.">httpGet</a></li> -<li><a href="#httpGetAuthString" title="Get the current authorization string.">httpGetAuthString</a></li> -<li><a href="#httpGetBlocking" title="Get the blocking/non-block state of a connection.">httpGetBlocking</a></li> -<li><a href="#httpGetCookie" title="Get any cookie data from the response.">httpGetCookie</a></li> -<li><a href="#httpGetDateString" title="Get a formatted date/time string from a time value.">httpGetDateString</a></li> -<li><a href="#httpGetDateString2" title="Get a formatted date/time string from a time value.">httpGetDateString2</a></li> -<li><a href="#httpGetDateTime" title="Get a time value from a formatted date/time string.">httpGetDateTime</a></li> -<li><a href="#httpGetFd" title="Get the file descriptor associated with a connection.">httpGetFd</a></li> -<li><a href="#httpGetField" title="Get a field value from a request/response.">httpGetField</a></li> -<li><a href="#httpGetHostByName" title="Lookup a hostname or IPv4 address, and return + <li><a href="#httpBlocking" title="Set blocking/non-blocking behavior on a connection.">httpBlocking</a></li> + <li><a href="#httpCheck" title="Check to see if there is a pending response from the server.">httpCheck</a></li> + <li><a href="#httpClearCookie" title="Clear the cookie value(s).">httpClearCookie</a></li> + <li><a href="#httpClearFields" title="Clear HTTP request fields.">httpClearFields</a></li> + <li><a href="#httpClose" title="Close an HTTP connection.">httpClose</a></li> + <li><a href="#httpConnect" title="Connect to a HTTP server.">httpConnect</a></li> + <li><a href="#httpConnectEncrypt" title="Connect to a HTTP server using encryption.">httpConnectEncrypt</a></li> + <li><a href="#httpCopyCredentials" title="Copy the credentials associated with an encrypted +connection.">httpCopyCredentials</a></li> + <li><a href="#httpDecode64" title="Base64-decode a string.">httpDecode64</a></li> + <li><a href="#httpDecode64_2" title="Base64-decode a string.">httpDecode64_2</a></li> + <li><a href="#httpDelete" title="Send a DELETE request to the server.">httpDelete</a></li> + <li><a href="#httpEncode64" title="Base64-encode a string.">httpEncode64</a></li> + <li><a href="#httpEncode64_2" title="Base64-encode a string.">httpEncode64_2</a></li> + <li><a href="#httpEncryption" title="Set the required encryption on the link.">httpEncryption</a></li> + <li><a href="#httpError" title="Get the last error on a connection.">httpError</a></li> + <li><a href="#httpFlush" title="Flush data from a HTTP connection.">httpFlush</a></li> + <li><a href="#httpFlushWrite" title="Flush data in write buffer.">httpFlushWrite</a></li> + <li><a href="#httpFreeCredentials" title="Free an array of credentials.">httpFreeCredentials</a></li> + <li><a href="#httpGet" title="Send a GET request to the server.">httpGet</a></li> + <li><a href="#httpGetAuthString" title="Get the current authorization string.">httpGetAuthString</a></li> + <li><a href="#httpGetBlocking" title="Get the blocking/non-block state of a connection.">httpGetBlocking</a></li> + <li><a href="#httpGetCookie" title="Get any cookie data from the response.">httpGetCookie</a></li> + <li><a href="#httpGetDateString" title="Get a formatted date/time string from a time value.">httpGetDateString</a></li> + <li><a href="#httpGetDateString2" title="Get a formatted date/time string from a time value.">httpGetDateString2</a></li> + <li><a href="#httpGetDateTime" title="Get a time value from a formatted date/time string.">httpGetDateTime</a></li> + <li><a href="#httpGetFd" title="Get the file descriptor associated with a connection.">httpGetFd</a></li> + <li><a href="#httpGetField" title="Get a field value from a request/response.">httpGetField</a></li> + <li><a href="#httpGetHostByName" title="Lookup a hostname or IPv4 address, and return address records for the specified name.">httpGetHostByName</a></li> -<li><a href="#httpGetHostname" title="Get the FQDN for the connection or local system.">httpGetHostname</a></li> -<li><a href="#httpGetLength" title="Get the amount of data remaining from the + <li><a href="#httpGetHostname" title="Get the FQDN for the connection or local system.">httpGetHostname</a></li> + <li><a href="#httpGetLength" title="Get the amount of data remaining from the content-length or transfer-encoding fields.">httpGetLength</a></li> -<li><a href="#httpGetLength2" title="Get the amount of data remaining from the + <li><a href="#httpGetLength2" title="Get the amount of data remaining from the content-length or transfer-encoding fields.">httpGetLength2</a></li> -<li><a href="#httpGetStatus" title="Get the status of the last HTTP request.">httpGetStatus</a></li> -<li><a href="#httpGetSubField" title="Get a sub-field value.">httpGetSubField</a></li> -<li><a href="#httpGetSubField2" title="Get a sub-field value.">httpGetSubField2</a></li> -<li><a href="#httpGets" title="Get a line of text from a HTTP connection.">httpGets</a></li> -<li><a href="#httpHead" title="Send a HEAD request to the server.">httpHead</a></li> -<li><a href="#httpInitialize" title="Initialize the HTTP interface library and set the + <li><a href="#httpGetStatus" title="Get the status of the last HTTP request.">httpGetStatus</a></li> + <li><a href="#httpGetSubField" title="Get a sub-field value.">httpGetSubField</a></li> + <li><a href="#httpGetSubField2" title="Get a sub-field value.">httpGetSubField2</a></li> + <li><a href="#httpGets" title="Get a line of text from a HTTP connection.">httpGets</a></li> + <li><a href="#httpHead" title="Send a HEAD request to the server.">httpHead</a></li> + <li><a href="#httpInitialize" title="Initialize the HTTP interface library and set the default HTTP proxy (if any).">httpInitialize</a></li> -<li><a href="#httpMD5" title="Compute the MD5 sum of the username:group:password.">httpMD5</a></li> -<li><a href="#httpMD5Final" title="Combine the MD5 sum of the username, group, and password + <li><a href="#httpMD5" title="Compute the MD5 sum of the username:group:password.">httpMD5</a></li> + <li><a href="#httpMD5Final" title="Combine the MD5 sum of the username, group, and password with the server-supplied nonce value, method, and request-uri.">httpMD5Final</a></li> -<li><a href="#httpMD5String" title="Convert an MD5 sum to a character string.">httpMD5String</a></li> -<li><a href="#httpOptions" title="Send an OPTIONS request to the server.">httpOptions</a></li> -<li><a href="#httpPost" title="Send a POST request to the server.">httpPost</a></li> -<li><a href="#httpPut" title="Send a PUT request to the server.">httpPut</a></li> -<li><a href="#httpRead" title="Read data from a HTTP connection.">httpRead</a></li> -<li><a href="#httpRead2" title="Read data from a HTTP connection.">httpRead2</a></li> -<li><a href="#httpReconnect" title="Reconnect to a HTTP server.">httpReconnect</a></li> -<li><a href="#httpSeparate" title="Separate a Universal Resource Identifier into its + <li><a href="#httpMD5String" title="Convert an MD5 sum to a character string.">httpMD5String</a></li> + <li><a href="#httpOptions" title="Send an OPTIONS request to the server.">httpOptions</a></li> + <li><a href="#httpPost" title="Send a POST request to the server.">httpPost</a></li> + <li><a href="#httpPut" title="Send a PUT request to the server.">httpPut</a></li> + <li><a href="#httpRead" title="Read data from a HTTP connection.">httpRead</a></li> + <li><a href="#httpRead2" title="Read data from a HTTP connection.">httpRead2</a></li> + <li><a href="#httpReconnect" title="Reconnect to a HTTP server.">httpReconnect</a></li> + <li><a href="#httpSeparate" title="Separate a Universal Resource Identifier into its components.">httpSeparate</a></li> -<li><a href="#httpSeparate2" title="Separate a Universal Resource Identifier into its + <li><a href="#httpSeparate2" title="Separate a Universal Resource Identifier into its components.">httpSeparate2</a></li> -<li><a href="#httpSeparateURI" title="Separate a Universal Resource Identifier into its + <li><a href="#httpSeparateURI" title="Separate a Universal Resource Identifier into its components.">httpSeparateURI</a></li> -<li><a href="#httpSetAuthString" title="Set the current authorization string.">httpSetAuthString</a></li> -<li><a href="#httpSetCookie" title="Set the cookie value(s).">httpSetCookie</a></li> -<li><a href="#httpSetExpect" title="Set the Expect: header in a request.">httpSetExpect</a></li> -<li><a href="#httpSetField" title="Set the value of an HTTP header.">httpSetField</a></li> -<li><a href="#httpSetLength" title="Set the content-length and content-encoding.">httpSetLength</a></li> -<li><a href="#httpStatus" title="Return a short string describing a HTTP status code.">httpStatus</a></li> -<li><a href="#httpTrace" title="Send an TRACE request to the server.">httpTrace</a></li> -<li><a href="#httpUpdate" title="Update the current HTTP state for incoming data.">httpUpdate</a></li> -<li><a href="#httpWait" title="Wait for data available on a connection.">httpWait</a></li> -<li><a href="#httpWrite" title="Write data to a HTTP connection.">httpWrite</a></li> -<li><a href="#httpWrite2" title="Write data to a HTTP connection.">httpWrite2</a></li> -<li><a href="#ippAddBoolean" title="Add a boolean attribute to an IPP message.">ippAddBoolean</a></li> -<li><a href="#ippAddBooleans" title="Add an array of boolean values.">ippAddBooleans</a></li> -<li><a href="#ippAddCollection" title="Add a collection value.">ippAddCollection</a></li> -<li><a href="#ippAddCollections" title="Add an array of collection values.">ippAddCollections</a></li> -<li><a href="#ippAddDate" title="Add a date attribute to an IPP message.">ippAddDate</a></li> -<li><a href="#ippAddInteger" title="Add a integer attribute to an IPP message.">ippAddInteger</a></li> -<li><a href="#ippAddIntegers" title="Add an array of integer values.">ippAddIntegers</a></li> -<li><a href="#ippAddOctetString" title="Add an octetString value to an IPP message.">ippAddOctetString</a></li> -<li><a href="#ippAddRange" title="Add a range of values to an IPP message.">ippAddRange</a></li> -<li><a href="#ippAddRanges" title="Add ranges of values to an IPP message.">ippAddRanges</a></li> -<li><a href="#ippAddResolution" title="Add a resolution value to an IPP message.">ippAddResolution</a></li> -<li><a href="#ippAddResolutions" title="Add resolution values to an IPP message.">ippAddResolutions</a></li> -<li><a href="#ippAddSeparator" title="Add a group separator to an IPP message.">ippAddSeparator</a></li> -<li><a href="#ippAddString" title="Add a language-encoded string to an IPP message.">ippAddString</a></li> -<li><a href="#ippAddStrings" title="Add language-encoded strings to an IPP message.">ippAddStrings</a></li> -<li><a href="#ippDateToTime" title="Convert from RFC 1903 Date/Time format to UNIX time + <li><a href="#httpSetAuthString" title="Set the current authorization string.">httpSetAuthString</a></li> + <li><a href="#httpSetCookie" title="Set the cookie value(s).">httpSetCookie</a></li> + <li><a href="#httpSetCredentials" title="Set the credentials associated with an encrypted +connection.">httpSetCredentials</a></li> + <li><a href="#httpSetExpect" title="Set the Expect: header in a request.">httpSetExpect</a></li> + <li><a href="#httpSetField" title="Set the value of an HTTP header.">httpSetField</a></li> + <li><a href="#httpSetLength" title="Set the content-length and content-encoding.">httpSetLength</a></li> + <li><a href="#httpSetTimeout" title="Set read/write timeouts and an optional callback.">httpSetTimeout</a></li> + <li><a href="#httpStatus" title="Return a short string describing a HTTP status code.">httpStatus</a></li> + <li><a href="#httpTrace" title="Send an TRACE request to the server.">httpTrace</a></li> + <li><a href="#httpUpdate" title="Update the current HTTP state for incoming data.">httpUpdate</a></li> + <li><a href="#httpWait" title="Wait for data available on a connection.">httpWait</a></li> + <li><a href="#httpWrite" title="Write data to a HTTP connection.">httpWrite</a></li> + <li><a href="#httpWrite2" title="Write data to a HTTP connection.">httpWrite2</a></li> + <li><a href="#ippAddBoolean" title="Add a boolean attribute to an IPP message.">ippAddBoolean</a></li> + <li><a href="#ippAddBooleans" title="Add an array of boolean values.">ippAddBooleans</a></li> + <li><a href="#ippAddCollection" title="Add a collection value.">ippAddCollection</a></li> + <li><a href="#ippAddCollections" title="Add an array of collection values.">ippAddCollections</a></li> + <li><a href="#ippAddDate" title="Add a date attribute to an IPP message.">ippAddDate</a></li> + <li><a href="#ippAddInteger" title="Add a integer attribute to an IPP message.">ippAddInteger</a></li> + <li><a href="#ippAddIntegers" title="Add an array of integer values.">ippAddIntegers</a></li> + <li><a href="#ippAddOctetString" title="Add an octetString value to an IPP message.">ippAddOctetString</a></li> + <li><a href="#ippAddRange" title="Add a range of values to an IPP message.">ippAddRange</a></li> + <li><a href="#ippAddRanges" title="Add ranges of values to an IPP message.">ippAddRanges</a></li> + <li><a href="#ippAddResolution" title="Add a resolution value to an IPP message.">ippAddResolution</a></li> + <li><a href="#ippAddResolutions" title="Add resolution values to an IPP message.">ippAddResolutions</a></li> + <li><a href="#ippAddSeparator" title="Add a group separator to an IPP message.">ippAddSeparator</a></li> + <li><a href="#ippAddString" title="Add a language-encoded string to an IPP message.">ippAddString</a></li> + <li><a href="#ippAddStrings" title="Add language-encoded strings to an IPP message.">ippAddStrings</a></li> + <li><a href="#ippDateToTime" title="Convert from RFC 1903 Date/Time format to UNIX time in seconds.">ippDateToTime</a></li> -<li><a href="#ippDelete" title="Delete an IPP message.">ippDelete</a></li> -<li><a href="#ippDeleteAttribute" title="Delete a single attribute in an IPP message.">ippDeleteAttribute</a></li> -<li><a href="#ippErrorString" title="Return a name for the given status code.">ippErrorString</a></li> -<li><a href="#ippErrorValue" title="Return a status code for the given name.">ippErrorValue</a></li> -<li><a href="#ippFindAttribute" title="Find a named attribute in a request...">ippFindAttribute</a></li> -<li><a href="#ippFindNextAttribute" title="Find the next named attribute in a request...">ippFindNextAttribute</a></li> -<li><a href="#ippLength" title="Compute the length of an IPP message.">ippLength</a></li> -<li><a href="#ippNew" title="Allocate a new IPP message.">ippNew</a></li> -<li><a href="#ippNewRequest" title="Allocate a new IPP request message.">ippNewRequest</a></li> -<li><a href="#ippOpString" title="Return a name for the given operation id.">ippOpString</a></li> -<li><a href="#ippOpValue" title="Return an operation id for the given name.">ippOpValue</a></li> -<li><a href="#ippPort" title="Return the default IPP port number.">ippPort</a></li> -<li><a href="#ippRead" title="Read data for an IPP message from a HTTP connection.">ippRead</a></li> -<li><a href="#ippReadFile" title="Read data for an IPP message from a file.">ippReadFile</a></li> -<li><a href="#ippReadIO" title="Read data for an IPP message.">ippReadIO</a></li> -<li><a href="#ippSetPort" title="Set the default port number.">ippSetPort</a></li> -<li><a href="#ippTagString" title="Return the tag name corresponding to a tag value.">ippTagString</a></li> -<li><a href="#ippTagValue" title="Return the tag value corresponding to a tag name.">ippTagValue</a></li> -<li><a href="#ippTimeToDate" title="Convert from UNIX time to RFC 1903 format.">ippTimeToDate</a></li> -<li><a href="#ippWrite" title="Write data for an IPP message to a HTTP connection.">ippWrite</a></li> -<li><a href="#ippWriteFile" title="Write data for an IPP message to a file.">ippWriteFile</a></li> -<li><a href="#ippWriteIO" title="Write data for an IPP message.">ippWriteIO</a></li> + <li><a href="#ippDelete" title="Delete an IPP message.">ippDelete</a></li> + <li><a href="#ippDeleteAttribute" title="Delete a single attribute in an IPP message.">ippDeleteAttribute</a></li> + <li><a href="#ippErrorString" title="Return a name for the given status code.">ippErrorString</a></li> + <li><a href="#ippErrorValue" title="Return a status code for the given name.">ippErrorValue</a></li> + <li><a href="#ippFindAttribute" title="Find a named attribute in a request...">ippFindAttribute</a></li> + <li><a href="#ippFindNextAttribute" title="Find the next named attribute in a request...">ippFindNextAttribute</a></li> + <li><a href="#ippLength" title="Compute the length of an IPP message.">ippLength</a></li> + <li><a href="#ippNew" title="Allocate a new IPP message.">ippNew</a></li> + <li><a href="#ippNewRequest" title="Allocate a new IPP request message.">ippNewRequest</a></li> + <li><a href="#ippOpString" title="Return a name for the given operation id.">ippOpString</a></li> + <li><a href="#ippOpValue" title="Return an operation id for the given name.">ippOpValue</a></li> + <li><a href="#ippPort" title="Return the default IPP port number.">ippPort</a></li> + <li><a href="#ippRead" title="Read data for an IPP message from a HTTP connection.">ippRead</a></li> + <li><a href="#ippReadFile" title="Read data for an IPP message from a file.">ippReadFile</a></li> + <li><a href="#ippReadIO" title="Read data for an IPP message.">ippReadIO</a></li> + <li><a href="#ippSetPort" title="Set the default port number.">ippSetPort</a></li> + <li><a href="#ippTagString" title="Return the tag name corresponding to a tag value.">ippTagString</a></li> + <li><a href="#ippTagValue" title="Return the tag value corresponding to a tag name.">ippTagValue</a></li> + <li><a href="#ippTimeToDate" title="Convert from UNIX time to RFC 1903 format.">ippTimeToDate</a></li> + <li><a href="#ippWrite" title="Write data for an IPP message to a HTTP connection.">ippWrite</a></li> + <li><a href="#ippWriteFile" title="Write data for an IPP message to a file.">ippWriteFile</a></li> + <li><a href="#ippWriteIO" title="Write data for an IPP message.">ippWriteIO</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> + <li><a href="#gss_auth_identity_desc" title="Local functions...">gss_auth_identity_desc</a></li> <li><a href="#http_addr_t" title="Socket address union, which makes using IPv6 and other address types easier and @@ -525,6 +537,7 @@ used to enumerate all of the addresses that are associated with a hostname. ">http_addrlist_t</a></li> <li><a href="#http_auth_t" title="HTTP authentication types">http_auth_t</a></li> + <li><a href="#http_credential_t" title="HTTP credential data ">http_credential_t</a></li> <li><a href="#http_encoding_t" title="HTTP transfer encoding values">http_encoding_t</a></li> <li><a href="#http_encryption_t" title="HTTP encryption values">http_encryption_t</a></li> <li><a href="#http_field_t" title="HTTP field names">http_field_t</a></li> @@ -533,6 +546,7 @@ with a hostname. ">http_addrlist_t</a></li> are server-oriented...">http_state_t</a></li> <li><a href="#http_status_t" title="HTTP status codes">http_status_t</a></li> <li><a href="#http_t" title="HTTP connection type">http_t</a></li> + <li><a href="#http_timeout_cb_t" title="HTTP timeout callback ">http_timeout_cb_t</a></li> <li><a href="#http_uri_coding_t" title="URI en/decode flags">http_uri_coding_t</a></li> <li><a href="#http_uri_status_t" title="URI separation status ">http_uri_status_t</a></li> <li><a href="#http_version_t" title="HTTP version numbers">http_version_t</a></li> @@ -553,10 +567,12 @@ are server-oriented...">http_state_t</a></li> <li><a href="#ipp_value_t" title="Attribute Value">ipp_value_t</a></li> </ul></li> <li><a href="#STRUCTURES">Structures</a><ul class="code"> + <li><a href="#gss_auth_identity" title="Local functions...">gss_auth_identity</a></li> <li><a href="#http_addrlist_s" title="Socket address list, which is used to enumerate all of the addresses that are associated with a hostname. ">http_addrlist_s</a></li> + <li><a href="#http_credential_s" title="HTTP credential data ">http_credential_s</a></li> <li><a href="#ipp_attribute_s" title="Attribute">ipp_attribute_s</a></li> <li><a href="#ipp_s" title="IPP Request/Response/Notification">ipp_s</a></li> </ul></li> @@ -587,8 +603,9 @@ are server-oriented...">http_state_e</a></li> <li><a href="#ipp_status_e" title="IPP status codes">ipp_status_e</a></li> <li><a href="#ipp_tag_e" title="Format tags for attributes">ipp_tag_e</a></li> </ul></li> +</ul> <!-- - "$Id: api-httpipp.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-httpipp.html 9801 2011-05-21 04:02:41Z mike $" HTTP and IPP API introduction for CUPS. @@ -1172,6 +1189,18 @@ cupsSendDocument() or cupsSendRequest(). For requests that return additional data, use httpRead() after getting a successful response. </p> +<h3 class="function"><a name="cupsLastError">cupsLastError</a></h3> +<p class="description">Return the last IPP status code.</p> +<p class="code"> +ipp_status_t cupsLastError (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">IPP status code from last request</p> +<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsLastErrorString">cupsLastErrorString</a></h3> +<p class="description">Return the last IPP status-message.</p> +<p class="code"> +const char *cupsLastErrorString (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">status-message text from last request</p> <h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="cupsPutFd">cupsPutFd</a></h3> <p class="description">Put a file on the server.</p> <p class="code"> @@ -1269,7 +1298,7 @@ files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively. <h4 class="discussion">Discussion</h4> <p class="discussion">Use httpWrite() to write any additional data (document, PPD file, etc.) for the request, cupsGetResponse() to get the IPP response, and httpRead() -to read any additional data following the response. Only one request can be +to read any additional data following the response. Only one request can be sent/queued at a time.<br> <br> Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the @@ -1300,6 +1329,29 @@ request is not freed. after <a href="#cupsStartDocument"><code>cupsStartDocument</code></a> to provide a document file. </p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="httpAddCredential">httpAddCredential</a></h3> +<p class="description">Allocates and adds a single credential to an array.</p> +<p class="code"> +int httpAddCredential (<br> + cups_array_t *credentials,<br> + const void *data,<br> + size_t datalen<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> +<dd class="description">Credentials array</dd> +<dt>data</dt> +<dd class="description">PEM-encoded X.509 data</dd> +<dt>datalen</dt> +<dd class="description">Length of data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">0 on success, -1 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Use <code>cupsArrayNew(NULL, NULL)</code> to create a credentials array. + +</p> <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrAny">httpAddrAny</a></h3> <p class="description">Check for the "any" address.</p> <p class="code"> @@ -1580,6 +1632,23 @@ void httpClose (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New HTTP connection</p> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="httpCopyCredentials">httpCopyCredentials</a></h3> +<p class="description">Copy the credentials associated with an encrypted +connection.</p> +<p class="code"> +int httpCopyCredentials (<br> + <a href="#http_t">http_t</a> *http,<br> + cups_array_t **credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +<dt>credentials</dt> +<dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Status of call (0 = success)</p> <h3 class="function"><span class="info"> DEPRECATED </span><a name="httpDecode64">httpDecode64</a></h3> <p class="description">Base64-decode a string.</p> <p class="code"> @@ -1732,6 +1801,17 @@ int httpFlushWrite (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Bytes written or -1 on error</p> +<h3 class="function"><a name="httpFreeCredentials">httpFreeCredentials</a></h3> +<p class="description">Free an array of credentials.</p> +<p class="code"> +void httpFreeCredentials (<br> + cups_array_t *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>credentials</dt> +<dd class="description">Array of credentials</dd> +</dl> <h3 class="function"><a name="httpGet">httpGet</a></h3> <p class="description">Send a GET request to the server.</p> <p class="code"> @@ -2369,6 +2449,23 @@ void httpSetCookie (<br> <dt>cookie</dt> <dd class="description">Cookie string</dd> </dl> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="httpSetCredentials">httpSetCredentials</a></h3> +<p class="description">Set the credentials associated with an encrypted +connection.</p> +<p class="code"> +int httpSetCredentials (<br> + <a href="#http_t">http_t</a> *http,<br> + cups_array_t *credentials<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +<dt>credentials</dt> +<dd class="description">Array of credentials</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Status of call (0 = success)</p> <h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpSetExpect">httpSetExpect</a></h3> <p class="description">Set the Expect: header in a request.</p> <p class="code"> @@ -2418,6 +2515,32 @@ void httpSetLength (<br> <dt>length</dt> <dd class="description">Length (0 for chunked)</dd> </dl> +<h3 class="function"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="httpSetTimeout">httpSetTimeout</a></h3> +<p class="description">Set read/write timeouts and an optional callback.</p> +<p class="code"> +void httpSetTimeout (<br> + <a href="#http_t">http_t</a> *http,<br> + double timeout,<br> + <a href="#http_timeout_cb_t">http_timeout_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +<dt>timeout</dt> +<dd class="description">Number of seconds for timeout, +must be greater than 0</dd> +<dt>cb</dt> +<dd class="description">Callback function or NULL</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The optional timeout callback receives both the HTTP connection and a user +data pointer and must return 1 to continue or 0 to error (time) out. + +</p> <h3 class="function"><a name="httpStatus">httpStatus</a></h3> <p class="description">Return a short string describing a HTTP status code.</p> <p class="code"> @@ -3246,6 +3369,11 @@ const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> <h2 class="title"><a name="TYPES">Data Types</a></h2> +<h3 class="typedef"><a name="gss_auth_identity_desc">gss_auth_identity_desc</a></h3> +<p class="description">Local functions...</p> +<p class="code"> +typedef struct <a href="#gss_auth_identity">gss_auth_identity</a> gss_auth_identity_desc; +</p> <h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="http_addr_t">http_addr_t</a></h3> <p class="description">Socket address union, which makes using IPv6 and other @@ -3267,6 +3395,11 @@ typedef struct <a href="#http_addrlist_s">http_addrlist_s</a> / http_addrlist_t; <p class="code"> typedef enum <a href="#http_auth_e">http_auth_e</a> http_auth_t; </p> +<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="http_credential_t">http_credential_t</a></h3> +<p class="description">HTTP credential data </p> +<p class="code"> +typedef struct <a href="#http_credential_s">http_credential_s</a> http_credential_t; +</p> <h3 class="typedef"><a name="http_encoding_t">http_encoding_t</a></h3> <p class="description">HTTP transfer encoding values</p> <p class="code"> @@ -3303,12 +3436,17 @@ typedef enum <a href="#http_status_e">http_status_e</a> http_status_t; <p class="code"> typedef struct _http_s http_t; </p> +<h3 class="typedef"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="http_timeout_cb_t">http_timeout_cb_t</a></h3> +<p class="description">HTTP timeout callback </p> +<p class="code"> +typedef int (*http_timeout_cb_t)(<a href="#http_t">http_t</a> *http, void *user_data); +</p> <h3 class="typedef"><a name="http_uri_coding_t">http_uri_coding_t</a></h3> <p class="description">URI en/decode flags</p> <p class="code"> typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t; </p> -<h3 class="typedef"><span class="info"> CUPS1.2 </span><a name="http_uri_status_t">http_uri_status_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2 </span><a name="http_uri_status_t">http_uri_status_t</a></h3> <p class="description">URI separation status </p> <p class="code"> typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t; @@ -3394,6 +3532,25 @@ typedef enum <a href="#ipp_tag_e">ipp_tag_e</a> ipp_tag_t; typedef union <a href="#ipp_value_u">ipp_value_u</a> ipp_value_t; </p> <h2 class="title"><a name="STRUCTURES">Structures</a></h2> +<h3 class="struct"><a name="gss_auth_identity">gss_auth_identity</a></h3> +<p class="description">Local functions...</p> +<p class="code">struct gss_auth_identity {<br> + gss_buffer_t *credentialsRef;<br> + uint32_t flags;<br> + char *password;<br> + char *realm;<br> + uint32_t type;<br> + char *username;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>credentialsRef </dt> +<dt>flags </dt> +<dt>password </dt> +<dt>realm </dt> +<dt>type </dt> +<dt>username </dt> +</dl> <h3 class="struct"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="http_addrlist_s">http_addrlist_s</a></h3> <p class="description">Socket address list, which is used to enumerate all of the @@ -3410,6 +3567,19 @@ with a hostname. </p> <dt>next </dt> <dd class="description">Pointer to next address in list</dd> </dl> +<h3 class="struct"><span class="info"> CUPS 1.5/Mac OS X 10.7 </span><a name="http_credential_s">http_credential_s</a></h3> +<p class="description">HTTP credential data </p> +<p class="code">struct http_credential_s {<br> + void *data;<br> + size_t datalen;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>data </dt> +<dd class="description">Pointer to credential data</dd> +<dt>datalen </dt> +<dd class="description">Credential length</dd> +</dl> <h3 class="struct"><a name="ipp_attribute_s">ipp_attribute_s</a></h3> <p class="description">Attribute</p> <p class="code">struct ipp_attribute_s {<br> @@ -3460,8 +3630,8 @@ with a hostname. </p> <dd class="description">Request header</dd> <dt>state </dt> <dd class="description">State of request</dd> -<dt>use </dt> -<dd class="description">Use count</dd> +<dt>use <span class="info"> CUPS 1.4.4/Mac OS X 10.6.? </span></dt> +<dd class="description">Use count </dd> </dl> <h2 class="title"><a name="UNIONS">Unions</a></h2> <h3 class="union"><a name="ipp_request_u">ipp_request_u</a></h3> @@ -3646,8 +3816,8 @@ are server-oriented...</p> <dl> <dt>HTTP_ACCEPTED </dt> <dd class="description">DELETE command was successful</dd> -<dt>HTTP_AUTHORIZATION_CANCELED </dt> -<dd class="description">User canceled authorization</dd> +<dt>HTTP_AUTHORIZATION_CANCELED <span class="info"> CUPS 1.4 </span></dt> +<dd class="description">User canceled authorization </dd> <dt>HTTP_BAD_GATEWAY </dt> <dd class="description">Bad gateway</dd> <dt>HTTP_BAD_REQUEST </dt> @@ -3698,6 +3868,8 @@ are server-oriented...</p> <dd class="description">Only a partial file was recieved/sent</dd> <dt>HTTP_PAYMENT_REQUIRED </dt> <dd class="description">Payment required</dd> +<dt>HTTP_PKI_ERROR <span class="info"> CUPS 1.5/Mac OS X 10.7 </span></dt> +<dd class="description">Error negotiating a secure connection </dd> <dt>HTTP_PRECONDITION </dt> <dd class="description">Precondition failed</dd> <dt>HTTP_PROXY_AUTHENTICATION </dt> @@ -3748,7 +3920,7 @@ are server-oriented...</p> <dt>HTTP_URI_CODING_USERNAME </dt> <dd class="description">En/decode the username portion</dd> </dl> -<h3 class="enumeration"><span class="info"> CUPS1.2 </span><a name="http_uri_status_e">http_uri_status_e</a></h3> +<h3 class="enumeration"><span class="info"> CUPS 1.2 </span><a name="http_uri_status_e">http_uri_status_e</a></h3> <p class="description">URI separation status </p> <h4 class="constants">Constants</h4> <dl> @@ -3906,8 +4078,14 @@ are server-oriented...</p> <dd class="description">Set the default printer</dd> <dt>IPP_CANCEL_JOB </dt> <dd class="description">Cancel a job</dd> +<dt>IPP_CANCEL_JOBS </dt> +<dd class="description">Cancel-Jobs</dd> +<dt>IPP_CANCEL_MY_JOBS </dt> +<dd class="description">Cancel-My-Jobs</dd> <dt>IPP_CANCEL_SUBSCRIPTION <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> <dd class="description">Cancel a subscription </dd> +<dt>IPP_CLOSE_JOB </dt> +<dd class="description">Close-Job</dd> <dt>IPP_CREATE_JOB </dt> <dd class="description">Create an empty print job</dd> <dt>IPP_CREATE_JOB_SUBSCRIPTION <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> @@ -3946,6 +4124,8 @@ are server-oriented...</p> <dd class="description">Renew a printer subscription </dd> <dt>IPP_RESTART_JOB </dt> <dd class="description">Reprint a job</dd> +<dt>IPP_RESUBMIT_JOB </dt> +<dd class="description">Resubmit-Job</dd> <dt>IPP_RESUME_PRINTER </dt> <dd class="description">Start a printer</dd> <dt>IPP_SEND_DOCUMENT </dt> @@ -4024,6 +4204,8 @@ are server-oriented...</p> <dd class="description">client-error-attributes-or-values-not-supported</dd> <dt>IPP_ATTRIBUTES_NOT_SETTABLE </dt> <dd class="description">client-error-attributes-not-settable</dd> +<dt>IPP_AUTHENTICATION_CANCELED <span class="info"> CUPS 1.5/Mac OS X 10.7 </span></dt> +<dd class="description">Authentication canceled by user </dd> <dt>IPP_BAD_REQUEST </dt> <dd class="description">client-error-bad-request</dd> <dt>IPP_CHARSET </dt> @@ -4084,6 +4266,8 @@ are server-oriented...</p> <dd class="description">successful-ok-too-many-events</dd> <dt>IPP_OPERATION_NOT_SUPPORTED </dt> <dd class="description">server-error-operation-not-supported</dd> +<dt>IPP_PKI_ERROR <span class="info"> CUPS 1.5/Mac OS X 10.7 </span></dt> +<dd class="description">Error negotiating a secure connection </dd> <dt>IPP_PRINTER_BUSY </dt> <dd class="description">server-error-busy</dd> <dt>IPP_PRINTER_IS_DEACTIVATED </dt> @@ -4102,6 +4286,8 @@ are server-oriented...</p> <dd class="description">client-error-timeout</dd> <dt>IPP_TOO_MANY_SUBSCRIPTIONS </dt> <dd class="description">client-error-too-many-subscriptions</dd> +<dt>IPP_UPGRADE_REQUIRED </dt> +<dd class="description">TLS upgrade required</dd> <dt>IPP_URI_SCHEME </dt> <dd class="description">client-error-uri-scheme-not-supported</dd> <dt>IPP_VERSION_NOT_SUPPORTED </dt> diff --git a/doc/help/api-mime.html b/doc/help/api-mime.html index 7d370aad..c2733764 100644 --- a/doc/help/api-mime.html +++ b/doc/help/api-mime.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>MIME API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>MIME API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-mime.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-mime.html 9772 2011-05-12 05:46:30Z mike $" MIME API header for CUPS. @@ -373,38 +376,43 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#mimeAddFilter" title="Add a filter to the current MIME database.">mimeAddFilter</a></li> -<li><a href="#mimeAddType" title="Add a MIME type to a database.">mimeAddType</a></li> -<li><a href="#mimeAddTypeRule" title="Add a detection rule for a file type.">mimeAddTypeRule</a></li> -<li><a href="#mimeDelete" title="Delete (free) a MIME database.">mimeDelete</a></li> -<li><a href="#mimeDeleteFilter" title="Delete a filter from the MIME database.">mimeDeleteFilter</a></li> -<li><a href="#mimeDeleteType" title="Delete a type from the MIME database.">mimeDeleteType</a></li> -<li><a href="#mimeFileType" title="Determine the type of a file.">mimeFileType</a></li> -<li><a href="#mimeFilter" title="Find the fastest way to convert from one type to another.">mimeFilter</a></li> -<li><a href="#mimeFilterLookup" title="Lookup a filter...">mimeFilterLookup</a></li> -<li><a href="#mimeFirstFilter" title="Get the first filter in the MIME database.">mimeFirstFilter</a></li> -<li><a href="#mimeFirstType" title="Get the first type in the MIME database.">mimeFirstType</a></li> -<li><a href="#mimeLoad" title="Create a new MIME database from disk.">mimeLoad</a></li> -<li><a href="#mimeLoadFilters" title="Load filter definitions from disk.">mimeLoadFilters</a></li> -<li><a href="#mimeLoadTypes" title="Load type definitions from disk.">mimeLoadTypes</a></li> -<li><a href="#mimeNextFilter" title="Get the next filter in the MIME database.">mimeNextFilter</a></li> -<li><a href="#mimeNextType" title="Get the next type in the MIME database.">mimeNextType</a></li> -<li><a href="#mimeNumFilters" title="MIME database">mimeNumFilters</a></li> -<li><a href="#mimeNumTypes" title="MIME database">mimeNumTypes</a></li> -<li><a href="#mimeType" title="Lookup a file type.">mimeType</a></li> + <li><a href="#mimeAddFilter" title="Add a filter to the current MIME database.">mimeAddFilter</a></li> + <li><a href="#mimeAddType" title="Add a MIME type to a database.">mimeAddType</a></li> + <li><a href="#mimeAddTypeRule" title="Add a detection rule for a file type.">mimeAddTypeRule</a></li> + <li><a href="#mimeDelete" title="Delete (free) a MIME database.">mimeDelete</a></li> + <li><a href="#mimeDeleteFilter" title="Delete a filter from the MIME database.">mimeDeleteFilter</a></li> + <li><a href="#mimeDeleteType" title="Delete a type from the MIME database.">mimeDeleteType</a></li> + <li><a href="#mimeFileType" title="Determine the type of a file.">mimeFileType</a></li> + <li><a href="#mimeFilter" title="Find the fastest way to convert from one type to another.">mimeFilter</a></li> + <li><a href="#mimeFilter2" title="Find the fastest way to convert from one type to another, +including file size.">mimeFilter2</a></li> + <li><a href="#mimeFilterLookup" title="Lookup a filter.">mimeFilterLookup</a></li> + <li><a href="#mimeFirstFilter" title="Get the first filter in the MIME database.">mimeFirstFilter</a></li> + <li><a href="#mimeFirstType" title="Get the first type in the MIME database.">mimeFirstType</a></li> + <li><a href="#mimeLoad" title="Create a new MIME database from disk.">mimeLoad</a></li> + <li><a href="#mimeLoadFilters" title="Load filter definitions from disk.">mimeLoadFilters</a></li> + <li><a href="#mimeLoadTypes" title="Load type definitions from disk.">mimeLoadTypes</a></li> + <li><a href="#mimeNew" title="Create a new, empty MIME database.">mimeNew</a></li> + <li><a href="#mimeNextFilter" title="Get the next filter in the MIME database.">mimeNextFilter</a></li> + <li><a href="#mimeNextType" title="Get the next type in the MIME database.">mimeNextType</a></li> + <li><a href="#mimeNumFilters" title="Next type">mimeNumFilters</a></li> + <li><a href="#mimeNumTypes" title="MIME database">mimeNumTypes</a></li> + <li><a href="#mimeSetErrorCallback" title="Set the callback for error messages.">mimeSetErrorCallback</a></li> + <li><a href="#mimeType" title="Lookup a file type.">mimeType</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> + <li><a href="#const" title="MIME Database">const</a></li> <li><a href="#mime_filter_t" title="MIME Conversion Filter Data">mime_filter_t</a></li> <li><a href="#mime_magic_t" title="MIME Magic Data">mime_magic_t</a></li> <li><a href="#mime_op_t" title="Types/structures...">mime_op_t</a></li> <li><a href="#mime_t" title="MIME Database">mime_t</a></li> <li><a href="#mime_type_t" title="MIME Type Data">mime_type_t</a></li> </ul></li> +</ul> <!-- - "$Id: api-mime.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-mime.html 9772 2011-05-12 05:46:30Z mike $" MIME API introduction for CUPS. @@ -429,7 +437,7 @@ div.contents ul.subcontents li { <a href="#mime_type_t">mime_type_t</a> *src,<br> <a href="#mime_type_t">mime_type_t</a> *dst,<br> int cost,<br> - const char *filter<br> + <a href="#const">const</a> char *filter<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -451,8 +459,8 @@ div.contents ul.subcontents li { <p class="code"> <a href="#mime_type_t">mime_type_t</a> *mimeAddType (<br> <a href="#mime_t">mime_t</a> *mime,<br> - const char *super,<br> - const char *type<br> + <a href="#const">const</a> char *super,<br> + <a href="#const">const</a> char *type<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -470,7 +478,7 @@ div.contents ul.subcontents li { <p class="code"> int mimeAddTypeRule (<br> <a href="#mime_type_t">mime_type_t</a> *mt,<br> - const char *rule<br> + <a href="#const">const</a> char *rule<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -525,8 +533,8 @@ void mimeDeleteType (<br> <p class="code"> <a href="#mime_type_t">mime_type_t</a> *mimeFileType (<br> <a href="#mime_t">mime_t</a> *mime,<br> - const char *pathname,<br> - const char *filename,<br> + <a href="#const">const</a> char *pathname,<br> + <a href="#const">const</a> char *filename,<br> int *compression<br> );</p> <h4 class="parameters">Parameters</h4> @@ -564,8 +572,34 @@ cups_array_t *mimeFilter (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Array of filters to run</p> +<h3 class="function"><a name="mimeFilter2">mimeFilter2</a></h3> +<p class="description">Find the fastest way to convert from one type to another, +including file size.</p> +<p class="code"> +cups_array_t *mimeFilter2 (<br> + <a href="#mime_t">mime_t</a> *mime,<br> + <a href="#mime_type_t">mime_type_t</a> *src,<br> + size_t srcsize,<br> + <a href="#mime_type_t">mime_type_t</a> *dst,<br> + int *cost<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>mime</dt> +<dd class="description">MIME database</dd> +<dt>src</dt> +<dd class="description">Source file type</dd> +<dt>srcsize</dt> +<dd class="description">Size of source file</dd> +<dt>dst</dt> +<dd class="description">Destination file type</dd> +<dt>cost</dt> +<dd class="description">Cost of filters</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Array of filters to run</p> <h3 class="function"><a name="mimeFilterLookup">mimeFilterLookup</a></h3> -<p class="description">Lookup a filter...</p> +<p class="description">Lookup a filter.</p> <p class="code"> <a href="#mime_filter_t">mime_filter_t</a> *mimeFilterLookup (<br> <a href="#mime_t">mime_t</a> *mime,<br> @@ -613,8 +647,8 @@ cups_array_t *mimeFilter (<br> <p class="description">Create a new MIME database from disk.</p> <p class="code"> <a href="#mime_t">mime_t</a> *mimeLoad (<br> - const char *pathname,<br> - const char *filterpath<br> + <a href="#const">const</a> char *pathname,<br> + <a href="#const">const</a> char *filterpath<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -633,8 +667,8 @@ create a MIME database from a single directory.</p> <p class="code"> <a href="#mime_t">mime_t</a> *mimeLoadFilters (<br> <a href="#mime_t">mime_t</a> *mime,<br> - const char *pathname,<br> - const char *filterpath<br> + <a href="#const">const</a> char *pathname,<br> + <a href="#const">const</a> char *filterpath<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -655,7 +689,7 @@ Use <a href="#mimeLoadTypes"><code>mimeLoadTypes</code></a> to load all types be <p class="code"> <a href="#mime_t">mime_t</a> *mimeLoadTypes (<br> <a href="#mime_t">mime_t</a> *mime,<br> - const char *pathname<br> + <a href="#const">const</a> char *pathname<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -669,6 +703,12 @@ Use <a href="#mimeLoadTypes"><code>mimeLoadTypes</code></a> to load all types be <h4 class="discussion">Discussion</h4> <p class="discussion">This function loads all of the .types files from the specified directory. Use <a href="#mimeLoadFilters"><code>mimeLoadFilters</code></a> to load all filters after you load the types.</p> +<h3 class="function"><a name="mimeNew">mimeNew</a></h3> +<p class="description">Create a new, empty MIME database.</p> +<p class="code"> +<a href="#mime_t">mime_t</a> *mimeNew (void);</p> +<h4 class="returnvalue">Return Value</h4> +<p class="description">MIME database</p> <h3 class="function"><a name="mimeNextFilter">mimeNextFilter</a></h3> <p class="description">Get the next filter in the MIME database.</p> <p class="code"> @@ -696,7 +736,7 @@ Use <a href="#mimeLoadFilters"><code>mimeLoadFilters</code></a> to load all filt <h4 class="returnvalue">Return Value</h4> <p class="description">Type or NULL</p> <h3 class="function"><a name="mimeNumFilters">mimeNumFilters</a></h3> -<p class="description">MIME database</p> +<p class="description">Next type</p> <p class="code"> int mimeNumFilters (<br> <a href="#mime_t">mime_t</a> *mime<br> @@ -721,13 +761,30 @@ int mimeNumTypes (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Get the number of types in a MIME database.</p> +<h3 class="function"><a name="mimeSetErrorCallback">mimeSetErrorCallback</a></h3> +<p class="description">Set the callback for error messages.</p> +<p class="code"> +void mimeSetErrorCallback (<br> + <a href="#mime_t">mime_t</a> *mime,<br> + mime_error_cb_t cb,<br> + void *ctx<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>mime</dt> +<dd class="description">MIME database</dd> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>ctx</dt> +<dd class="description">Context pointer for callback</dd> +</dl> <h3 class="function"><a name="mimeType">mimeType</a></h3> <p class="description">Lookup a file type.</p> <p class="code"> <a href="#mime_type_t">mime_type_t</a> *mimeType (<br> <a href="#mime_t">mime_t</a> *mime,<br> - const char *super,<br> - const char *type<br> + <a href="#const">const</a> char *super,<br> + <a href="#const">const</a> char *type<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -741,6 +798,11 @@ int mimeNumTypes (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">Matching file type definition</p> <h2 class="title"><a name="TYPES">Data Types</a></h2> +<h3 class="typedef"><a name="const">const</a></h3> +<p class="description">MIME Database</p> +<p class="code"> +typedef void (*constmime_error_cb_t)(void *; +</p> <h3 class="typedef"><a name="mime_filter_t">mime_filter_t</a></h3> <p class="description">MIME Conversion Filter Data</p> <p class="code"> diff --git a/doc/help/api-overview.html b/doc/help/api-overview.html index 3cb894a2..278df7ca 100644 --- a/doc/help/api-overview.html +++ b/doc/help/api-overview.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Introduction to CUPS Programming</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Introduction to CUPS Programming </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,12 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-overview.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-overview.html 9772 2011-05-12 05:46:30Z mike $" - Introduction to CUPS programming header for the Common UNIX Printing System - (CUPS). + Introduction to CUPS programming header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -393,15 +395,15 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#COMPILING">Compiling Programs</a><ul class="subcontents"> -<li><a href="#XCODE">Compiling with Xcode</a></li> -<li><a href="#COMMANDLINE">Compiling with GCC</a></li> + <li><a href="#XCODE">Compiling with Xcode</a></li> + <li><a href="#COMMANDLINE">Compiling with GCC</a></li> </ul></li> <li><a href="#WHERETOGO">Where to Go Next</a></li> +</ul> <!-- - "$Id: api-overview.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-overview.html 9772 2011-05-12 05:46:30Z mike $" Introduction to CUPS programming content for CUPS. diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html index 13535017..ae32165d 100644 --- a/doc/help/api-ppd.html +++ b/doc/help/api-ppd.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>PPD API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>PPD API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-ppd.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-ppd.html 9772 2011-05-12 05:46:30Z mike $" - PPD API header for the Common UNIX Printing System (CUPS). + PPD API header for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2011 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -375,65 +378,64 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a><ul class="subcontents"> -<li><a href="#LOADING">Loading a PPD File</a></li> -<li><a href="#OPTIONS_AND_GROUPS">Options and Groups</a></li> -<li><a href="#CONSTRAINTS">Constraints</a></li> -<li><a href="#PAGE_SIZES">Page Sizes</a></li> -<li><a href="#ATTRIBUTES">Attributes</a></li> + <li><a href="#LOADING">Loading a PPD File</a></li> + <li><a href="#OPTIONS_AND_GROUPS">Options and Groups</a></li> + <li><a href="#CONSTRAINTS">Constraints</a></li> + <li><a href="#PAGE_SIZES">Page Sizes</a></li> + <li><a href="#ATTRIBUTES">Attributes</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsGetConflicts" title="Get a list of conflicting options in a marked PPD.">cupsGetConflicts</a></li> -<li><a href="#cupsMarkOptions" title="Mark command-line options in a PPD file.">cupsMarkOptions</a></li> -<li><a href="#cupsResolveConflicts" title="Resolve conflicts in a marked PPD.">cupsResolveConflicts</a></li> -<li><a href="#ppdClose" title="Free all memory used by the PPD file.">ppdClose</a></li> -<li><a href="#ppdCollect" title="Collect all marked options that reside in the specified + <li><a href="#cupsGetConflicts" title="Get a list of conflicting options in a marked PPD.">cupsGetConflicts</a></li> + <li><a href="#cupsMarkOptions" title="Mark command-line options in a PPD file.">cupsMarkOptions</a></li> + <li><a href="#cupsResolveConflicts" title="Resolve conflicts in a marked PPD.">cupsResolveConflicts</a></li> + <li><a href="#ppdClose" title="Free all memory used by the PPD file.">ppdClose</a></li> + <li><a href="#ppdCollect" title="Collect all marked options that reside in the specified section.">ppdCollect</a></li> -<li><a href="#ppdCollect2" title="Collect all marked options that reside in the + <li><a href="#ppdCollect2" title="Collect all marked options that reside in the specified section and minimum order.">ppdCollect2</a></li> -<li><a href="#ppdConflicts" title="Check to see if there are any conflicts among the + <li><a href="#ppdConflicts" title="Check to see if there are any conflicts among the marked option choices.">ppdConflicts</a></li> -<li><a href="#ppdEmit" title="Emit code for marked options to a file.">ppdEmit</a></li> -<li><a href="#ppdEmitAfterOrder" title="Emit a subset of the code for marked options to a file.">ppdEmitAfterOrder</a></li> -<li><a href="#ppdEmitFd" title="Emit code for marked options to a file.">ppdEmitFd</a></li> -<li><a href="#ppdEmitJCL" title="Emit code for JCL options to a file.">ppdEmitJCL</a></li> -<li><a href="#ppdEmitJCLEnd" title="Emit JCLEnd code to a file.">ppdEmitJCLEnd</a></li> -<li><a href="#ppdEmitString" title="Get a string containing the code for marked options.">ppdEmitString</a></li> -<li><a href="#ppdErrorString" title="Returns the text assocated with a status.">ppdErrorString</a></li> -<li><a href="#ppdFindAttr" title="Find the first matching attribute.">ppdFindAttr</a></li> -<li><a href="#ppdFindChoice" title="Return a pointer to an option choice.">ppdFindChoice</a></li> -<li><a href="#ppdFindCustomOption" title="Find a custom option.">ppdFindCustomOption</a></li> -<li><a href="#ppdFindCustomParam" title="Find a parameter for a custom option.">ppdFindCustomParam</a></li> -<li><a href="#ppdFindMarkedChoice" title="Return the marked choice for the specified option.">ppdFindMarkedChoice</a></li> -<li><a href="#ppdFindNextAttr" title="Find the next matching attribute.">ppdFindNextAttr</a></li> -<li><a href="#ppdFindOption" title="Return a pointer to the specified option.">ppdFindOption</a></li> -<li><a href="#ppdFirstCustomParam" title="Return the first parameter for a custom option.">ppdFirstCustomParam</a></li> -<li><a href="#ppdFirstOption" title="Return the first option in the PPD file.">ppdFirstOption</a></li> -<li><a href="#ppdInstallableConflict" title="Test whether an option choice conflicts with + <li><a href="#ppdEmit" title="Emit code for marked options to a file.">ppdEmit</a></li> + <li><a href="#ppdEmitAfterOrder" title="Emit a subset of the code for marked options to a file.">ppdEmitAfterOrder</a></li> + <li><a href="#ppdEmitFd" title="Emit code for marked options to a file.">ppdEmitFd</a></li> + <li><a href="#ppdEmitJCL" title="Emit code for JCL options to a file.">ppdEmitJCL</a></li> + <li><a href="#ppdEmitJCLEnd" title="Emit JCLEnd code to a file.">ppdEmitJCLEnd</a></li> + <li><a href="#ppdEmitString" title="Get a string containing the code for marked options.">ppdEmitString</a></li> + <li><a href="#ppdErrorString" title="Returns the text assocated with a status.">ppdErrorString</a></li> + <li><a href="#ppdFindAttr" title="Find the first matching attribute.">ppdFindAttr</a></li> + <li><a href="#ppdFindChoice" title="Return a pointer to an option choice.">ppdFindChoice</a></li> + <li><a href="#ppdFindCustomOption" title="Find a custom option.">ppdFindCustomOption</a></li> + <li><a href="#ppdFindCustomParam" title="Find a parameter for a custom option.">ppdFindCustomParam</a></li> + <li><a href="#ppdFindMarkedChoice" title="Return the marked choice for the specified option.">ppdFindMarkedChoice</a></li> + <li><a href="#ppdFindNextAttr" title="Find the next matching attribute.">ppdFindNextAttr</a></li> + <li><a href="#ppdFindOption" title="Return a pointer to the specified option.">ppdFindOption</a></li> + <li><a href="#ppdFirstCustomParam" title="Return the first parameter for a custom option.">ppdFirstCustomParam</a></li> + <li><a href="#ppdFirstOption" title="Return the first option in the PPD file.">ppdFirstOption</a></li> + <li><a href="#ppdInstallableConflict" title="Test whether an option choice conflicts with an installable option.">ppdInstallableConflict</a></li> -<li><a href="#ppdIsMarked" title="Check to see if an option is marked.">ppdIsMarked</a></li> -<li><a href="#ppdLastError" title="Return the status from the last ppdOpen*().">ppdLastError</a></li> -<li><a href="#ppdLocalize" title="Localize the PPD file to the current locale.">ppdLocalize</a></li> -<li><a href="#ppdLocalizeAttr" title="Localize an attribute.">ppdLocalizeAttr</a></li> -<li><a href="#ppdLocalizeIPPReason" title="Get the localized version of a cupsIPPReason + <li><a href="#ppdIsMarked" title="Check to see if an option is marked.">ppdIsMarked</a></li> + <li><a href="#ppdLastError" title="Return the status from the last ppdOpen*().">ppdLastError</a></li> + <li><a href="#ppdLocalize" title="Localize the PPD file to the current locale.">ppdLocalize</a></li> + <li><a href="#ppdLocalizeAttr" title="Localize an attribute.">ppdLocalizeAttr</a></li> + <li><a href="#ppdLocalizeIPPReason" title="Get the localized version of a cupsIPPReason attribute.">ppdLocalizeIPPReason</a></li> -<li><a href="#ppdLocalizeMarkerName" title="Get the localized version of a marker-names + <li><a href="#ppdLocalizeMarkerName" title="Get the localized version of a marker-names attribute value.">ppdLocalizeMarkerName</a></li> -<li><a href="#ppdMarkDefaults" title="Mark all default options in the PPD file.">ppdMarkDefaults</a></li> -<li><a href="#ppdMarkOption" title="Mark an option in a PPD file and return the number of + <li><a href="#ppdMarkDefaults" title="Mark all default options in the PPD file.">ppdMarkDefaults</a></li> + <li><a href="#ppdMarkOption" title="Mark an option in a PPD file and return the number of conflicts.">ppdMarkOption</a></li> -<li><a href="#ppdNextCustomParam" title="Return the next parameter for a custom option.">ppdNextCustomParam</a></li> -<li><a href="#ppdNextOption" title="Return the next option in the PPD file.">ppdNextOption</a></li> -<li><a href="#ppdOpen" title="Read a PPD file into memory.">ppdOpen</a></li> -<li><a href="#ppdOpen2" title="Read a PPD file into memory.">ppdOpen2</a></li> -<li><a href="#ppdOpenFd" title="Read a PPD file into memory.">ppdOpenFd</a></li> -<li><a href="#ppdOpenFile" title="Read a PPD file into memory.">ppdOpenFile</a></li> -<li><a href="#ppdPageLength" title="Get the page length for the given size.">ppdPageLength</a></li> -<li><a href="#ppdPageSize" title="Get the page size record for the given size.">ppdPageSize</a></li> -<li><a href="#ppdPageSizeLimits" title="Return the custom page size limits.">ppdPageSizeLimits</a></li> -<li><a href="#ppdPageWidth" title="Get the page width for the given size.">ppdPageWidth</a></li> -<li><a href="#ppdSetConformance" title="Set the conformance level for PPD files.">ppdSetConformance</a></li> + <li><a href="#ppdNextCustomParam" title="Return the next parameter for a custom option.">ppdNextCustomParam</a></li> + <li><a href="#ppdNextOption" title="Return the next option in the PPD file.">ppdNextOption</a></li> + <li><a href="#ppdOpen" title="Read a PPD file into memory.">ppdOpen</a></li> + <li><a href="#ppdOpen2" title="Read a PPD file into memory.">ppdOpen2</a></li> + <li><a href="#ppdOpenFd" title="Read a PPD file into memory.">ppdOpenFd</a></li> + <li><a href="#ppdOpenFile" title="Read a PPD file into memory.">ppdOpenFile</a></li> + <li><a href="#ppdPageLength" title="Get the page length for the given size.">ppdPageLength</a></li> + <li><a href="#ppdPageSize" title="Get the page size record for the given size.">ppdPageSize</a></li> + <li><a href="#ppdPageSizeLimits" title="Return the custom page size limits.">ppdPageSizeLimits</a></li> + <li><a href="#ppdPageWidth" title="Get the page width for the given size.">ppdPageWidth</a></li> + <li><a href="#ppdSetConformance" title="Set the conformance level for PPD files.">ppdSetConformance</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#ppd_attr_t" title="PPD Attribute Structure ">ppd_attr_t</a></li> @@ -475,14 +477,14 @@ conflicts.">ppdMarkOption</a></li> </ul></li> <li><a href="#ENUMERATIONS">Constants</a><ul class="code"> <li><a href="#ppd_conform_e" title="Conformance Levels ">ppd_conform_e</a></li> - <li><a href="#ppd_cptype_e" title="Custom Parameter Type ">ppd_cptype_e</a></li> <li><a href="#ppd_cs_e" title="Colorspaces">ppd_cs_e</a></li> <li><a href="#ppd_section_e" title="Order dependency sections">ppd_section_e</a></li> <li><a href="#ppd_status_e" title="Status Codes ">ppd_status_e</a></li> <li><a href="#ppd_ui_e" title="UI Types">ppd_ui_e</a></li> </ul></li> +</ul> <!-- - "$Id: api-ppd.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-ppd.html 9772 2011-05-12 05:46:30Z mike $" PPD API introduction for CUPS. @@ -753,8 +755,9 @@ int cupsMarkOptions (<br> <p class="description">1 if conflicts exist, 0 otherwise</p> <h4 class="discussion">Discussion</h4> <p class="discussion">This function maps the IPP "finishings", "media", "mirror", -"multiple-document-handling", "output-bin", "printer-resolution", and -"sides" attributes to their corresponding PPD options and choices.</p> +"multiple-document-handling", "output-bin", "print-color-mode", +"print-quality", "printer-resolution", and "sides" attributes to their +corresponding PPD options and choices.</p> <h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsResolveConflicts">cupsResolveConflicts</a></h3> <p class="description">Resolve conflicts in a marked PPD.</p> <p class="code"> @@ -1587,7 +1590,7 @@ typedef union <a href="#ppd_cplimit_u">ppd_cplimit_u</a> ppd_cplimit_t; <h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cptype_t">ppd_cptype_t</a></h3> <p class="description">Custom Parameter Type </p> <p class="code"> -typedef enum <a href="#ppd_cptype_e">ppd_cptype_e</a> ppd_cptype_t; +typedef enum ppd_cptype_e ppd_cptype_t; </p> <h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cpvalue_t">ppd_cpvalue_t</a></h3> <p class="description">Custom Parameter Value </p> @@ -1805,7 +1808,6 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; char *product;<br> <a href="#ppd_profile_t">ppd_profile_t</a> *profiles;<br> char *protocols;<br> - void *pwg;<br> char *shortnickname;<br> <a href="#ppd_size_t">ppd_size_t</a> *sizes;<br> int throughput;<br> @@ -1888,8 +1890,6 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dd class="description">sRGB color profiles </dd> <dt>protocols <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> <dd class="description">Protocols (BCP, TBCP) string </dd> -<dt>pwg </dt> -<dd class="description">PWG to/from PPD mappings</dd> <dt>shortnickname </dt> <dd class="description">Short version of nickname</dd> <dt>sizes </dt> @@ -2086,27 +2086,6 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dt>PPD_CONFORM_STRICT </dt> <dd class="description">Require strict conformance</dd> </dl> -<h3 class="enumeration"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cptype_e">ppd_cptype_e</a></h3> -<p class="description">Custom Parameter Type </p> -<h4 class="constants">Constants</h4> -<dl> -<dt>PPD_CUSTOM_CURVE </dt> -<dd class="description">Curve value for f(x) = x^value</dd> -<dt>PPD_CUSTOM_INT </dt> -<dd class="description">Integer number value</dd> -<dt>PPD_CUSTOM_INVCURVE </dt> -<dd class="description">Curve value for f(x) = x^(1/value)</dd> -<dt>PPD_CUSTOM_PASSCODE </dt> -<dd class="description">String of (hidden) numbers</dd> -<dt>PPD_CUSTOM_PASSWORD </dt> -<dd class="description">String of (hidden) characters</dd> -<dt>PPD_CUSTOM_POINTS </dt> -<dd class="description">Measurement value in points</dd> -<dt>PPD_CUSTOM_REAL </dt> -<dd class="description">Real number value</dd> -<dt>PPD_CUSTOM_STRING </dt> -<dd class="description">String of characters</dd> -</dl> <h3 class="enumeration"><a name="ppd_cs_e">ppd_cs_e</a></h3> <p class="description">Colorspaces</p> <h4 class="constants">Constants</h4> @@ -2177,6 +2156,8 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dd class="description">Line longer than 255 chars</dd> <dt>PPD_MISSING_ASTERISK </dt> <dd class="description">Missing asterisk in column 0</dd> +<dt>PPD_MISSING_CLOSE_GROUP </dt> +<dd class="description">Missing CloseGroup</dd> <dt>PPD_MISSING_OPTION_KEYWORD </dt> <dd class="description">Missing option keyword</dd> <dt>PPD_MISSING_PPDADOBE4 </dt> diff --git a/doc/help/api-ppdc.html b/doc/help/api-ppdc.html index 4b95f6a5..cb15f61e 100644 --- a/doc/help/api-ppdc.html +++ b/doc/help/api-ppdc.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>PPD Compiler API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>PPD Compiler API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-ppdc.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-ppdc.html 9740 2011-05-04 06:26:22Z mike $" PPD Compiler API header for CUPS. @@ -373,28 +376,27 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#CLASSES">Classes</a><ul class="code"> -<li><a href="#ppdcArray" title="// Shared Array">ppdcArray</a></li> -<li><a href="#ppdcAttr" title="// Attribute">ppdcAttr</a></li> -<li><a href="#ppdcCatalog" title="// Translation catalog">ppdcCatalog</a></li> -<li><a href="#ppdcChoice" title="// Option Choice">ppdcChoice</a></li> -<li><a href="#ppdcConstraint" title="// Constraint">ppdcConstraint</a></li> -<li><a href="#ppdcDriver" title="// Printer Driver Data">ppdcDriver</a></li> -<li><a href="#ppdcFile" title="// File">ppdcFile</a></li> -<li><a href="#ppdcFilter" title="// Filter Program">ppdcFilter</a></li> -<li><a href="#ppdcFont" title="// Shared Font">ppdcFont</a></li> -<li><a href="#ppdcGroup" title="// Group of Options">ppdcGroup</a></li> -<li><a href="#ppdcInteger" title="// Shared integer">ppdcInteger</a></li> -<li><a href="#ppdcMediaSize" title="// Media Size">ppdcMediaSize</a></li> -<li><a href="#ppdcMessage" title="// Translation message">ppdcMessage</a></li> -<li><a href="#ppdcOption" title="// Option">ppdcOption</a></li> -<li><a href="#ppdcProfile" title="// Color Profile">ppdcProfile</a></li> -<li><a href="#ppdcShared" title="// Shared Data Value">ppdcShared</a></li> -<li><a href="#ppdcSource" title="// Source File">ppdcSource</a></li> -<li><a href="#ppdcString" title="// Shared String">ppdcString</a></li> -<li><a href="#ppdcVariable" title="// Variable Definition">ppdcVariable</a></li> + <li><a href="#ppdcArray" title="// Shared Array">ppdcArray</a></li> + <li><a href="#ppdcAttr" title="// Attribute">ppdcAttr</a></li> + <li><a href="#ppdcCatalog" title="// Translation catalog">ppdcCatalog</a></li> + <li><a href="#ppdcChoice" title="// Option Choice">ppdcChoice</a></li> + <li><a href="#ppdcConstraint" title="// Constraint">ppdcConstraint</a></li> + <li><a href="#ppdcDriver" title="// Printer Driver Data">ppdcDriver</a></li> + <li><a href="#ppdcFile" title="// File">ppdcFile</a></li> + <li><a href="#ppdcFilter" title="// Filter Program">ppdcFilter</a></li> + <li><a href="#ppdcFont" title="// Shared Font">ppdcFont</a></li> + <li><a href="#ppdcGroup" title="// Group of Options">ppdcGroup</a></li> + <li><a href="#ppdcInteger" title="// Shared integer">ppdcInteger</a></li> + <li><a href="#ppdcMediaSize" title="// Media Size">ppdcMediaSize</a></li> + <li><a href="#ppdcMessage" title="// Translation message">ppdcMessage</a></li> + <li><a href="#ppdcOption" title="// Option">ppdcOption</a></li> + <li><a href="#ppdcProfile" title="// Color Profile">ppdcProfile</a></li> + <li><a href="#ppdcShared" title="// Shared Data Value">ppdcShared</a></li> + <li><a href="#ppdcSource" title="// Source File">ppdcSource</a></li> + <li><a href="#ppdcString" title="// Shared String">ppdcString</a></li> + <li><a href="#ppdcVariable" title="// Variable Definition">ppdcVariable</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#ppdc_cs_t" title="">ppdc_cs_t</a></li> @@ -410,8 +412,9 @@ div.contents ul.subcontents li { <li><a href="#ppdcOptSection" title="// Option section">ppdcOptSection</a></li> <li><a href="#ppdcOptType" title="// Option type">ppdcOptType</a></li> </ul></li> +</ul> <!-- - "$Id: api-ppdc.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-ppdc.html 9740 2011-05-04 06:26:22Z mike $" PPD Compiler API introduction for CUPS. diff --git a/doc/help/api-raster.html b/doc/help/api-raster.html index b592be87..f193d07e 100644 --- a/doc/help/api-raster.html +++ b/doc/help/api-raster.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Raster API</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Raster API </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -338,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-raster.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-raster.html 9772 2011-05-12 05:46:30Z mike $" - Raster API header for the Common UNIX Printing System (CUPS). + Raster API documentation for CUPS. - Copyright 2008-2009 by Apple Inc. + Copyright 2008-2010 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -376,27 +379,27 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#OVERVIEW">Overview</a></li> <li><a href="#TASKS">Functions by Task</a><ul class="subcontents"> -<li><a href="#OPENCLOSE">Opening and Closing Raster Streams</a></li> -<li><a href="#READING">Reading Raster Streams</a></li> -<li><a href="#WRITING">Writing Raster Streams</a></li> + <li><a href="#OPENCLOSE">Opening and Closing Raster Streams</a></li> + <li><a href="#READING">Reading Raster Streams</a></li> + <li><a href="#WRITING">Writing Raster Streams</a></li> </ul></li> <li><a href="#FUNCTIONS">Functions</a><ul class="code"> -<li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li> -<li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li> -<li><a href="#cupsRasterOpen" title="Open a raster stream using a file descriptor.">cupsRasterOpen</a></li> -<li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a + <li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li> + <li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li> + <li><a href="#cupsRasterOpen" title="Open a raster stream using a file descriptor.">cupsRasterOpen</a></li> + <li><a href="#cupsRasterOpenIO" title="Open a raster stream using a callback function.">cupsRasterOpenIO</a></li> + <li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a version 1 page header structure.">cupsRasterReadHeader</a></li> -<li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a + <li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a version 2 page header structure.">cupsRasterReadHeader2</a></li> -<li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li> -<li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page + <li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li> + <li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page header structure.">cupsRasterWriteHeader</a></li> -<li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 + <li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 page header structure.">cupsRasterWriteHeader2</a></li> -<li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li> + <li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li> </ul></li> <li><a href="#TYPES">Data Types</a><ul class="code"> <li><a href="#cups_adv_t" title="AdvanceMedia attribute values">cups_adv_t</a></li> @@ -411,6 +414,7 @@ page header structure.">cupsRasterWriteHeader2</a></li> <li><a href="#cups_orient_t" title="Orientation attribute values">cups_orient_t</a></li> <li><a href="#cups_page_header2_t" title="Version 2 page header ">cups_page_header2_t</a></li> <li><a href="#cups_page_header_t" title="Version 1 page header ">cups_page_header_t</a></li> + <li><a href="#cups_raster_iocb_t" title="cupsRasterOpenIO callback function">cups_raster_iocb_t</a></li> <li><a href="#cups_raster_t" title="Raster stream data">cups_raster_t</a></li> </ul></li> <li><a href="#STRUCTURES">Structures</a><ul class="code"> @@ -428,8 +432,9 @@ page header structure.">cupsRasterWriteHeader2</a></li> <li><a href="#cups_order_e" title="cupsColorOrder attribute values">cups_order_e</a></li> <li><a href="#cups_orient_e" title="Orientation attribute values">cups_orient_e</a></li> </ul></li> +</ul> <!-- - "$Id: api-raster.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: api-raster.html 9772 2011-05-12 05:46:30Z mike $" Raster API introduction for CUPS. @@ -667,8 +672,9 @@ are supported. <dd class="description">File descriptor</dd> <dt>mode</dt> <dd class="description">Mode - <code>CUPS_RASTER_READ</code>, -<code>CUPS_RASTER_WRITE</code>, or -<code>CUPS_RASTER_WRITE_COMPRESSED</code></dd> +<code>CUPS_RASTER_WRITE</code>, +<code>CUPS_RASTER_WRITE_COMPRESSED</code>, +or <code>CUPS_RASTER_WRITE_PWG</code></dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New stream</p> @@ -678,9 +684,40 @@ For most printer driver filters, "fd" will be 0 (stdin). For most ras image processor (RIP) filters that generate raster data, "fd" will be 1 (stdout).<br> <br> -When writing raster data, the <code>CUPS_RASTER_WRITE</code> or -<code>CUPS_RASTER_WRITE_COMPRESS</code> mode can be used - compressed output is -generally 25-50% smaller but adds a 100-300% execution time overhead.</p> +When writing raster data, the <code>CUPS_RASTER_WRITE</code>, +<code>CUPS_RASTER_WRITE_COMPRESS</code>, or <code>CUPS_RASTER_WRITE_PWG</code> mode can +be used - compressed and PWG output is generally 25-50% smaller but adds a +100-300% execution time overhead.</p> +<h3 class="function"><a name="cupsRasterOpenIO">cupsRasterOpenIO</a></h3> +<p class="description">Open a raster stream using a callback function.</p> +<p class="code"> +<a href="#cups_raster_t">cups_raster_t</a> *cupsRasterOpenIO (<br> + <a href="#cups_raster_iocb_t">cups_raster_iocb_t</a> iocb,<br> + void *ctx,<br> + <a href="#cups_mode_t">cups_mode_t</a> mode<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>iocb</dt> +<dd class="description">Read/write callback</dd> +<dt>ctx</dt> +<dd class="description">Context pointer for callback</dd> +<dt>mode</dt> +<dd class="description">Mode - <code>CUPS_RASTER_READ</code>, +<code>CUPS_RASTER_WRITE</code>, +<code>CUPS_RASTER_WRITE_COMPRESSED</code>, +or <code>CUPS_RASTER_WRITE_PWG</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New stream</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">This function associates a raster stream with the given callback function and +context pointer.<br> +<br> +When writing raster data, the <code>CUPS_RASTER_WRITE</code>, +<code>CUPS_RASTER_WRITE_COMPRESS</code>, or <code>CUPS_RASTER_WRITE_PWG</code> mode can +be used - compressed and PWG output is generally 25-50% smaller but adds a +100-300% execution time overhead.</p> <h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsRasterReadHeader">cupsRasterReadHeader</a></h3> <p class="description">Read a raster page header and store it in a version 1 page header structure.</p> @@ -872,6 +909,11 @@ typedef struct <a href="#cups_page_header2_s">cups_page_header2_s</a> cups_page_ <p class="code"> typedef struct <a href="#cups_page_header_s">cups_page_header_s</a> cups_page_header_t; </p> +<h3 class="typedef"><a name="cups_raster_iocb_t">cups_raster_iocb_t</a></h3> +<p class="description">cupsRasterOpenIO callback function</p> +<p class="code"> +typedef ssize_t (*cups_raster_iocb_t)(void *ctx, unsigned char *buffer, size_t length); +</p> <h3 class="typedef"><a name="cups_raster_t">cups_raster_t</a></h3> <p class="description">Raster stream data</p> <p class="code"> @@ -1342,6 +1384,8 @@ factor not applied) </dd> <dd class="description">Open stream for writing</dd> <dt>CUPS_RASTER_WRITE_COMPRESSED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> <dd class="description">Open stream for compressed writing </dd> +<dt>CUPS_RASTER_WRITE_PWG <span class="info"> CUPS 1.5/Mac OS X 10.7 </span></dt> +<dd class="description">Open stream for compressed writing in PWG mode </dd> </dl> <h3 class="enumeration"><a name="cups_order_e">cups_order_e</a></h3> <p class="description">cupsColorOrder attribute values</p> diff --git a/doc/help/kerberos.html b/doc/help/kerberos.html index 82c9b5ff..cb8b88c2 100644 --- a/doc/help/kerberos.html +++ b/doc/help/kerberos.html @@ -8,11 +8,7 @@ <H1 CLASS="title">Using Kerberos Authentication</H1> -<P>CUPS allows you to use a Key Distribution Center (KDC) for authentication -on your local CUPS server and when printing to a remote authenticated queue. -This document describes how to configure CUPS to use Kerberos authentication -and provides links to the MIT help pages for configuring Kerberos on your -systems and network.</P> +<P>CUPS allows you to use a Key Distribution Center (KDC) for authentication on your local CUPS server and when printing to a remote authenticated queue. This document describes how to configure CUPS to use Kerberos authentication and provides links to the MIT help pages for configuring Kerberos on your systems and network.</P> <H2 CLASS="title"><A NAME="REQUIREMENTS">System Requirements</A></H2> @@ -23,42 +19,31 @@ systems and network.</P> <li>Heimdal Kerberos (any version) or MIT Kerberos (1.6.3 or newer)</li> - <li>Properly configured Domain Name System (DNS) - infrastructure:<ol type='a'> - <li>DNS server(s) with static IP addresses for all CUPS clients - and servers or configured to allow DHCP updates to the host - addresses</li> + <li>Properly configured Domain Name System (DNS) infrastructure (for your servers):<ol type='a'> + <li>DNS server(s) with static IP addresses for all CUPS servers or configured to allow DHCP updates to the host addresses and</li> <li>All CUPS clients and servers configured to use the same - DNS server(s)</li> +DNS server(s).</li> </ol></li> <li>Properly configured Kerberos infrastructure:<ol type='a'> - <li>KDC configured to allow CUPS clients and servers to obtain - Service Granting Tickets (SGTs) for the "ipp" service</li> - <li>LDAP-based user accounts - both OpenDirectory and - ActiveDirectory provide this with the KDC</li> - <li>CUPS clients and servers bound to the KDC and LDAP - server(s)</li> + <li>KDC configured to allow CUPS servers to obtain Service Granting Tickets (SGTs) for the "host" service,</li> + <li>LDAP-based user accounts - both OpenDirectory and ActiveDirectory provide this with the KDC, and</li> + <li>CUPS clients and servers bound to the same KDC and LDAP + server(s).</li> </ol></li> - <li>An "ipp" Service Granting Ticket (SGT) for every CUPS client and - server</li> + <li>A "host" Service Granting Ticket (SGT) for every CUPS server</li> </ol> <H2 CLASS="title"><A NAME="KRB5">Configuring Kerberos on Your System</A></H2> -<P>Before you can use Kerberos with CUPS, you will need to configure -Kerberos on your system and setup a system as a KDC. Because this -configuration is highly system and site-specific, please consult -the following on-line resources provided by the creators of Kerberos -at the Massachusetts Institute of Technology (MIT):</P> +<P>Before you can use Kerberos with CUPS, you will need to configure Kerberos on your system and setup a system as a KDC. Because this configuration is highly system and site-specific, please consult the following on-line resources provided by the creators of Kerberos at the Massachusetts Institute of Technology (MIT):</P> <UL> - <LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network - Authentication Protocol</A></LI> + <LI><A HREF="http://web.mit.edu/kerberos/">Kerberos: The Network Authentication Protocol</A></LI> <LI><A HREF="http://web.mit.edu/macdev/KfM/Common/Documentation/faq-osx.html">Kerberos on Mac OS X Frequently Asked Questions</A></LI> @@ -77,46 +62,28 @@ at the Massachusetts Institute of Technology (MIT):</P> <H2 CLASS="title"><A NAME="CUPS">Configuring CUPS to Use Kerberos</A></H2> -<P>Once you have configured Kerberos on your system(s), you can then -enable Kerberos authentication by selecting the <tt>Negotiate</tt> -authentication type. The simplest way to do this is using the -<tt>cupsctl(8)</tt> command:</P> +<P>Once youhave configured Kerberos on your system(s), you can then enable Kerberos authentication by selecting the <tt>Negotiate</tt> authentication type. The simplest way to do this is using the <tt>cupsctl(8)</tt> command on your server(s):</P> <PRE CLASS="command"> <KBD>cupsctl DefaultAuthType=Negotiate</KBD> </PRE> -<P>You can also enable Kerberos from the web interface by checking the -<VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change -Settings</VAR>:</P> +<P>You can also enable Kerberos from the web interface by checking the <VAR>Use Kerberos Authentication</VAR> box and clicking <VAR>Change Settings</VAR>:</P> <PRE CLASS="command"> -http://localhost:631/admin +http://server.example.com:631/admin </PRE> -<P>After you have enabled Kerberos authentication, use the built-in -"authenticated" policy or your own custom policies with the printers you -will be sharing. See <a href="policies.html">Managing Operation Policies</a> -for more information.</P> +<P>After you have enabled Kerberos authentication, use the built-in "authenticated" policy or your own custom policies with the printers you will be sharing. See <a href="policies.html">Managing Operation Policies</a> for more information.</P> <H2 CLASS="title"><A NAME="IMPLEMENT">Implementation Information</A></H2> -<P>CUPS implements Kerberos over HTTP using GSSAPI and the service name -"host". Because of limitations in the HTTP GSSAPI protocol extension, only -a single domain/KDC is supported for authentication.</P> - -<P>When doing printing tasks that require authentication, CUPS requests a -single-use "ticket" from your login session to authenticate who you are. -This ticket gives CUPS a username of the form "user@REALM", which is then -converted to just "user" for purposes of user and group checks.</P> - -<P>In order to support printing to a shared printer, CUPS has to ask the KDC -for a copy of your credentials (this is called delegation) that can be sent to -the remote server for authentication. Delegation only works when the system -has a stable hostname which maps to the current address of the system, which -is why you need a static IP address or DHCP that updates the DNS entry for your -system.</P> +<P>CUPS implements Kerberos over HTTP using GSSAPI and the service name "host". Because of limitations in the HTTP GSSAPI protocol extension, only a single domain/KDC is supported for authentication. The HTTP extension is described in <a href="http://tools.ietf.org/html/rfc4559">RFC 4559</a>.</P> + +<P>When doing printing tasks that require authentication, CUPS requests single-use "tickets" from your login session to authenticate who you are. These tickets give CUPS a username of the form "user@REALM", which is then converted to just "user" for purposes of user and group checks.</P> + +<P>In order to support printing to a shared printer, CUPS runs the IPP backend as the owner of the print job so it can obtain the necessary credentials.</P> </BODY> </HTML> diff --git a/doc/help/license.html b/doc/help/license.html index a86babdd..2b7c2460 100644 --- a/doc/help/license.html +++ b/doc/help/license.html @@ -8,7 +8,7 @@ <H1 CLASS="title">Software License Agreement</H1> -<P ALIGN="CENTER">Copyright 2007-2009 by Apple Inc.<BR> +<P ALIGN="CENTER">Copyright 2007-2011 by Apple Inc.<BR> 1 Infinite Loop<BR> Cupertino, CA 95014 USA<BR> <BR> @@ -21,12 +21,10 @@ and GNU Library General Public License ("LGPL"), Version 2, with exceptions for Apple operating systems and the OpenSSL toolkit. A copy of the exceptions and licenses follow this introduction.</P> -<P>The GNU LGPL applies to the CUPS and CUPS Imaging libraries -located in the "cups" and "filter" subdirectories of the CUPS -source distribution and in the "cups" include directory and -library files in the binary distributions. The GNU GPL applies to -the remainder of the CUPS distribution, including the "pdftops" -filter which is based upon Xpdf.</P> +<P>The GNU LGPL applies to the CUPS and CUPS Imaging libraries located in the +"cups" and "filter" subdirectories of the CUPS source distribution and the files +in the "test" subdirectory. The GNU GPL applies to the remainder of the CUPS +distribution.</P> <P>For those not familiar with the GNU GPL, the license basically allows you to:</P> @@ -525,7 +523,7 @@ when it starts in an interactive mode: Gnomovision version 69, Copyright (C) <VAR>year</VAR> <VAR>name of author</VAR> Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome -to redistribute it under certain conditions; type `show c' +to redistribute it under certain conditions; type `show c' for details. </PRE> @@ -542,7 +540,7 @@ necessary. Here is a sample; alter the names: <PRE> Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' -(which makes passes at compilers) written +(which makes passes at compilers) written by James Hacker. <VAR>signature of Ty Coon</VAR>, 1 April 1989 diff --git a/doc/help/postscript-driver.html b/doc/help/postscript-driver.html index c2b35b7e..501043c7 100644 --- a/doc/help/postscript-driver.html +++ b/doc/help/postscript-driver.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Developing PostScript Printer Drivers</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Developing PostScript Printer Drivers </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -337,6 +340,21 @@ div.contents ul.subcontents li { </head> <body> <div class='body'> +<!-- + "$Id: postscript-driver.html 9740 2011-05-04 06:26:22Z mike $" + + PostScript printer driver documentation for CUPS. + + Copyright 2007-2010 by Apple Inc. + Copyright 1997-2007 by Easy Software Products. + + These coded instructions, statements, and computer programs are the + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + <h1 class='title'>Developing PostScript Printer Drivers</h1> <p>This document describes how to develop printer drivers for PostScript printers. Topics include: <a href='#BASICS'>printer driver basics</a>, <a href='#CREATE'>creating new PPD files</a>, <a href='#IMPORT'>importing existing PPD files</a>, <a href='#FILTERS'>using custom filters</a>, <a href='#COLOR'>implementing color management</a>, and <a href='#MACOSX'>adding Mac OS X features</a>.</p> @@ -356,14 +374,14 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#BASICS">Printer Driver Basics</a></li> <li><a href="#CREATING">Creating New PPD Files</a><ul class="subcontents"> -<li><a href="#IMPORT">Importing Existing PPD Files</a></li> + <li><a href="#IMPORT">Importing Existing PPD Files</a></li> </ul></li> <li><a href="#FILTERS">Using Custom Filters</a></li> <li><a href="#COLOR">Implementing Color Management</a></li> <li><a href="#MACOSX">Adding Mac OS X Features</a></li> +</ul> <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2> <p>A CUPS PostScript printer driver consists of a PostScript Printer Description (PPD) file that describes the features and capabilities of the device, zero or more <em>filter</em> programs that prepare print data for the device, and zero or more support files for color management, online help, and so forth. The PPD file includes references to all of the filters and support files used by the driver.</p> diff --git a/doc/help/ppd-compiler.html b/doc/help/ppd-compiler.html index d0aedaf2..db891f17 100644 --- a/doc/help/ppd-compiler.html +++ b/doc/help/ppd-compiler.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Introduction to the PPD Compiler</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Introduction to the PPD Compiler </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -337,6 +340,21 @@ div.contents ul.subcontents li { </head> <body> <div class='body'> +<!-- + "$Id: ppd-compiler.html 9740 2011-05-04 06:26:22Z mike $" + + PPD compiler documentation for CUPS. + + Copyright 2007-2010 by Apple Inc. + Copyright 1997-2007 by Easy Software Products. + + These coded instructions, statements, and computer programs are the + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + <h1 class='title'>Introduction to the PPD Compiler</h1> <P>This document describes how to use the CUPS PostScript Printer Description @@ -358,21 +376,21 @@ that describe the features and capabilities of one or more printers.</P> </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#BASICS">The Basics</a></li> <li><a href="#DRV">Driver Information Files</a><ul class="subcontents"> -<li><a href="#SIMPLE">A Simple Example</a></li> -<li><a href="#GROUPING">Grouping and Inheritance</a></li> -<li><a href="#COLOR">Color Support</a></li> -<li><a href="#OPTIONS">Defining Custom Options and Option Groups</a></li> -<li><a href="#DEFINE">Defining Constants</a></li> -<li><a href="#CONDITIONAL">Conditional Statements</a></li> -<li><a href="#CONSTRAINTS">Defining Constraints</a></li> + <li><a href="#SIMPLE">A Simple Example</a></li> + <li><a href="#GROUPING">Grouping and Inheritance</a></li> + <li><a href="#COLOR">Color Support</a></li> + <li><a href="#OPTIONS">Defining Custom Options and Option Groups</a></li> + <li><a href="#DEFINE">Defining Constants</a></li> + <li><a href="#CONDITIONAL">Conditional Statements</a></li> + <li><a href="#CONSTRAINTS">Defining Constraints</a></li> </ul></li> <li><a href="#LOCALIZATION">Localization</a><ul class="subcontents"> -<li><a href="#PPDPO">The ppdpo Utility</a></li> -<li><a href="#PPDC_CATALOG">Using Message Catalogs with the PPD Compiler</a></li> + <li><a href="#PPDPO">The ppdpo Utility</a></li> + <li><a href="#PPDC_CATALOG">Using Message Catalogs with the PPD Compiler</a></li> </ul></li> +</ul> <h2 class='title'><a name='BASICS'>The Basics</a></h2> <P>The PPD compiler, <a href='man-ppdc.html'><code>ppdc(1)</code></a>, is a diff --git a/doc/help/raster-driver.html b/doc/help/raster-driver.html index bb133ace..2ec3f4e5 100644 --- a/doc/help/raster-driver.html +++ b/doc/help/raster-driver.html @@ -2,9 +2,10 @@ <html> <!-- SECTION: Programming --> <head> -<title>Developing Raster Printer Drivers</title> -<meta name="keywords" content="Programming"> -<meta name="creator" content="Mini-XML v2.7"> + <title>Developing Raster Printer Drivers </title> + <meta name="keywords" content="Programming"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> <style type="text/css"><!-- BODY { font-family: lucida grande, geneva, helvetica, arial, sans-serif; @@ -24,7 +25,9 @@ PRE { } PRE.command { + border: dotted thin #7f7f7f; margin-left: 36pt; + padding: 10px; } P.compact { @@ -337,6 +340,21 @@ div.contents ul.subcontents li { </head> <body> <div class='body'> +<!-- + "$Id: raster-driver.html 9740 2011-05-04 06:26:22Z mike $" + + Raster printer driver documentation for CUPS. + + Copyright 2007-2010 by Apple Inc. + Copyright 1997-2007 by Easy Software Products. + + These coded instructions, statements, and computer programs are the + property of Apple Inc. and are protected by Federal copyright + law. Distribution and use rights are outlined in the file "LICENSE.txt" + which should have been included with this file. If this file is + file is missing or damaged, see the license at "http://www.cups.org/". +--> + <h1 class='title'>Developing Raster Printer Drivers</h1> <p>This document describes how to develop printer drivers for raster printers. Topics include: <a href='#BASICS'>printer driver basics</a>, <a href='#CREATE'>creating new PPD files</a>, <a href='#FILTERS'>using filters</a>, <a href='#COLOR'>implementing color management</a>, and <a href='#MACOSX'>adding Mac OS X features</a>.</p> @@ -356,12 +374,12 @@ div.contents ul.subcontents li { </table></div> <h2 class="title">Contents</h2> <ul class="contents"> -<ul class="subcontents"> <li><a href="#BASICS">Printer Driver Basics</a></li> <li><a href="#CREATING">Creating New PPD Files</a></li> <li><a href="#FILTERS">Using Filters</a></li> <li><a href="#COLOR">Implementing Color Management</a></li> <li><a href="#MACOSX">Adding Mac OS X Features</a></li> +</ul> <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2> <p>A CUPS raster printer driver consists of a PostScript Printer Description (PPD) file that describes the features and capabilities of the device, one or more <em>filter</em> programs that prepare print data for the device, and zero or more support files for color management, online help, and so forth. The PPD file includes references to all of the filters and support files used by the driver.</p> diff --git a/doc/help/ref-cupsd-conf.html.in b/doc/help/ref-cupsd-conf.html.in index abeeeba7..736a0b3b 100644 --- a/doc/help/ref-cupsd-conf.html.in +++ b/doc/help/ref-cupsd-conf.html.in @@ -133,7 +133,7 @@ to the access log file. The following levels are defined:</P> <H3>Description</H3> <P>The <CODE>Allow</CODE> directive specifies a hostname, IP -address, or network that is allowed access to the server. +address, or network that is allowed access to the server. <CODE>Allow</CODE> directives are cumulative, so multiple <CODE>Allow</CODE> directives can be used to allow access for multiple hosts or networks.</P> @@ -1483,6 +1483,48 @@ the file is assumed to be relative to the <A HREF="#ServerRoot"><CODE>ServerRoot</CODE></A> directory.</P> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="JobPrivateAccess">JobPrivateAccess</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +JobPrivateAccess all +JobPrivateAccess default +JobPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM}+ +</PRE> + +<H3>Description</H3> + +<P>The <CODE>JobPrivateAccess</CODE> directive specifies the access list for a +job's private values. The "default" access list is "@OWNER @SYSTEM". "@ACL" maps +to the printer's requesting-user-name-allowed or requesting-user-name-denied +values.</P> + +<P>The <CODE>JobPrivateAccess</CODE> directive must appear inside a <A +HREF="#Policy"><CODE>Policy</CODE></A> section.</P> + + +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="JobPrivateValues">JobPrivateValues</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +JobPrivateValues all +JobPrivateValues default +JobPrivateValues none +JobPrivateValues attribute-name-1 [ ... attribute-name-N ] +</PRE> + +<H3>Description</H3> + +<P>The <CODE>JobPrivateValues</CODE> directive specifies the list of job values +to make private. The "default" values are "job-name", +"job-originating-host-name", and "job-originating-user-name".</P> + +<P>The <CODE>JobPrivateValues</CODE> directive must appear inside a <A +HREF="#Policy"><CODE>Policy</CODE></A> section.</P> + + <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="JobRetryInterval">JobRetryInterval</A></H2> <H3>Examples</H3> @@ -2650,7 +2692,7 @@ appear inside a <A HREF="#Location"><CODE>Location</CODE></A> or <H3>Examples</H3> <PRE CLASS="command"> -RIPCache 8m +RIPCache 128m RIPCache 1g RIPCache 2048k </PRE> @@ -2661,7 +2703,7 @@ RIPCache 2048k memory cache used by Raster Image Processor ("RIP") filters such as <CODE>imagetoraster</CODE> and <CODE>pstoraster</CODE>. The size can be suffixed with a "k" for kilobytes, "m" for megabytes, -or "g" for gigabytes. The default cache size is "8m", or 8 +or "g" for gigabytes. The default cache size is "128m", or 128 megabytes.</P> @@ -2740,6 +2782,7 @@ HREF="#ServerName"><CODE>ServerName</CODE></A>.</P> ServerAlias althost ServerAlias foo.example.com ServerAlias bar.example.com +ServerAlias one.example.com two.example.com ServerAlias * </PRE> @@ -2985,6 +3028,49 @@ on for secure connections. Multiple <CODE>SSLPort</CODE> lines can be specified to listen on multiple ports.</P> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="SubscriptionPrivateAccess">SubscriptionPrivateAccess</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +SubscriptionPrivateAccess all +SubscriptionPrivateAccess default +SubscriptionPrivateAccess {user|@group|@ACL|@OWNER|@SYSTEM}+ +</PRE> + +<H3>Description</H3> + +<P>The <CODE>SubscriptionPrivateAccess</CODE> directive specifies the access list for a +subscription's private values. The "default" access list is "@OWNER @SYSTEM". +"@ACL" maps to the printer's requesting-user-name-allowed or +requesting-user-name-denied values.</P> + +<P>The <CODE>SubscriptionPrivateAccess</CODE> directive must appear inside a <A +HREF="#Policy"><CODE>Policy</CODE></A> section.</P> + + +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="SubscriptionPrivateValues">SubscriptionPrivateValues</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +SubscriptionPrivateValues all +SubscriptionPrivateValues default +SubscriptionPrivateValues none +SubscriptionPrivateValues attribute-name-1 [ ... attribute-name-N ] +</PRE> + +<H3>Description</H3> + +<P>The <CODE>SubscriptionPrivateValues</CODE> directive specifies the list of +subscription values to make private. The "default" values are "notify-events", +"notify-pull-method", "notify-recipient-uri", "notify-subscriber-user-name", and +"notify-user-data".</P> + +<P>The <CODE>SubscriptionPrivateValues</CODE> directive must appear inside a <A +HREF="#Policy"><CODE>Policy</CODE></A> section.</P> + + <H2 CLASS="title"><A NAME="SystemGroup">SystemGroup</A></H2> <H3>Examples</H3> @@ -3095,5 +3181,18 @@ user whose ID is 0.</P> </BLOCKQUOTE> +<H2 CLASS="title"><SPAN CLASS="INFO">CUPS 1.5</SPAN><A NAME="WebInterface">WebInterface</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +WebInterface yes +WebInterface no +</PRE> + +<H3>Description</H3> + +<P>The <CODE>WebInterface</CODE> directive specifies whether the web interface is enabled. The default value is <CODE>@CUPS_WEBIF@</CODE>.</P> + </BODY> </HTML> diff --git a/doc/help/spec-banner.html b/doc/help/spec-banner.html index 7393a21e..2d22d9e8 100644 --- a/doc/help/spec-banner.html +++ b/doc/help/spec-banner.html @@ -8,7 +8,7 @@ </head> <body> <!-- - "$Id: spec-banner.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: spec-banner.html 9727 2011-04-28 21:20:12Z mike $" Banner file format specification for CUPS. diff --git a/doc/help/spec-browsing.html b/doc/help/spec-browsing.html index e2ab44c7..4583731d 100644 --- a/doc/help/spec-browsing.html +++ b/doc/help/spec-browsing.html @@ -8,7 +8,7 @@ </head> <body> <!-- - "$Id: spec-browsing.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: spec-browsing.html 9727 2011-04-28 21:20:12Z mike $" CUPS Browse Protocol specification for CUPS. diff --git a/doc/help/spec-command.html b/doc/help/spec-command.html index bf731ccb..af201cb5 100644 --- a/doc/help/spec-command.html +++ b/doc/help/spec-command.html @@ -8,7 +8,7 @@ </head> <body> <!-- - "$Id: spec-command.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: spec-command.html 9727 2011-04-28 21:20:12Z mike $" CUPS command file format specification for CUPS. diff --git a/doc/help/spec-ipp.html b/doc/help/spec-ipp.html index c8767279..98bc0574 100644 --- a/doc/help/spec-ipp.html +++ b/doc/help/spec-ipp.html @@ -8,7 +8,7 @@ </head> <body> <!-- - "$Id: spec-ipp.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: spec-ipp.html 9727 2011-04-28 21:20:12Z mike $" CUPS IPP specification for CUPS. diff --git a/doc/help/spec-postscript.html b/doc/help/spec-postscript.html index 3bff7fbd..3aa99c41 100644 --- a/doc/help/spec-postscript.html +++ b/doc/help/spec-postscript.html @@ -8,7 +8,7 @@ </head> <body> <!-- - "$Id: spec-postscript.html 9728 2011-04-28 21:21:24Z mike $" + "$Id: spec-postscript.html 9727 2011-04-28 21:20:12Z mike $" CUPS PostScript file specification for CUPS. diff --git a/doc/help/spec-ppd.html b/doc/help/spec-ppd.html index 1acd847d..f92725d8 100644 --- a/doc/help/spec-ppd.html +++ b/doc/help/spec-ppd.html @@ -2,17 +2,350 @@ <html> <!-- SECTION: Specifications --> <head> - <title>CUPS PPD Extensions</title> - <meta name='keywords' content='Programming, PostScript Printer Description'> - <link rel='stylesheet' type='text/css' href='../cups-printable.css'> + <title>CUPS PPD Extensions </title> + <meta name="keywords" content="Specifications"> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <meta name="creator" content="Mini-XML v2.7"> +<style type="text/css"><!-- +BODY { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +H1, H2, H3, H4, H5, H6, P, TD, TH { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +KBD { + font-family: monaco, courier, monospace; + font-weight: bold; +} + +PRE { + font-family: monaco, courier, monospace; +} + +PRE.command { + border: dotted thin #7f7f7f; + margin-left: 36pt; + padding: 10px; +} + +P.compact { + margin: 0; +} + +P.example { + font-style: italic; + margin-left: 36pt; +} + +PRE.example { + background: #eeeeee; + border: dotted thin #999999; + margin-left: 36pt; + padding: 10pt; +} + +PRE.command EM, PRE.example EM { + font-family: lucida grande, geneva, helvetica, arial, sans-serif; +} + +P.command { + font-family: monaco, courier, monospace; + margin-left: 36pt; +} + +P.formula { + font-style: italic; + margin-left: 36pt; +} + +BLOCKQUOTE { + background: #eeeeee; + border: solid thin #999999; + padding: 10pt; +} + +A IMG { + border: none; +} + +A:link:hover IMG { + background: #f0f0f0; + border-radius: 10px; + -moz-border-radius: 10px; +} + +A:link, A:visited { + font-weight: normal; + text-decoration: none; +} + +A:link:hover, A:visited:hover, A:active { + text-decoration: underline; +} + +SUB, SUP { + font-size: 50%; +} + +TR.data, TD.data, TR.data TD { + margin-top: 10pt; + padding: 5pt; + border-bottom: solid 1pt #999999; +} + +TR.data TH { + border-bottom: solid 1pt #999999; + padding-top: 10pt; + padding-left: 5pt; + text-align: left; +} + +DIV.table TABLE { + border: solid thin #999999; + border-collapse: collapse; + border-spacing: 0; + margin-left: auto; + margin-right: auto; +} + +DIV.table CAPTION { + caption-side: top; + font-size: 120%; + font-style: italic; + font-weight: bold; + margin-left: auto; + margin-right: auto; +} + +DIV.table TABLE TD { + border: solid thin #cccccc; + padding-top: 5pt; +} + +DIV.table TABLE TH { + background: #cccccc; + border: none; + border-bottom: solid thin #999999; +} + +DIV.figure TABLE { + margin-left: auto; + margin-right: auto; +} + +DIV.figure CAPTION { + caption-side: bottom; + font-size: 120%; + font-style: italic; + font-weight: bold; + margin-left: auto; + margin-right: auto; +} + +TH.label { + text-align: right; + vertical-align: top; +} + +TH.sublabel { + text-align: right; + font-weight: normal; +} + +HR { + border: solid thin; +} + +SPAN.info { + background: black; + border: thin solid black; + color: white; + font-size: 80%; + font-style: italic; + font-weight: bold; + white-space: nowrap; +} + +H2 SPAN.info, H3 SPAN.info, H4 SPAN.info { + float: right; + font-size: 100%; +} + +H1.title { +} + +H2.title, H3.title { + border-bottom: solid 2pt #000000; +} + +DIV.indent, TABLE.indent { + margin-top: 2em; + margin-left: auto; + margin-right: auto; + width: 90%; +} + +TABLE.indent { + border-collapse: collapse; +} + +TABLE.indent TD, TABLE.indent TH { + padding: 0; +} + +TABLE.list { + border-collapse: collapse; + margin-left: auto; + margin-right: auto; + width: 90%; +} + +TABLE.list TH { + background: white; + border-bottom: solid thin #cccccc; + color: #444444; + padding-top: 10pt; + padding-left: 5pt; + text-align: left; + vertical-align: bottom; + white-space: nowrap; +} + +TABLE.list TH A { + color: #4444cc; +} + +TABLE.list TD { + border-bottom: solid thin #eeeeee; + padding-top: 5pt; + padding-left: 5pt; +} + +TABLE.list TR:nth-child(even) { + background: #f8f8f8; +} + +TABLE.list TR:nth-child(odd) { + background: #f4f4f4; +} + +DT { + margin-left: 36pt; + margin-top: 12pt; +} + +DD { + margin-left: 54pt; +} + +DL.category DT { + font-weight: bold; +} + +P.summary { + margin-left: 36pt; + font-family: monaco, courier, monospace; +} + +DIV.summary TABLE { + border: solid thin #999999; + border-collapse: collapse; + border-spacing: 0; + margin: 10px; +} + +DIV.summary TABLE TD, DIV.summary TABLE TH { + border: solid thin #999999; + padding: 5px; + text-align: left; + vertical-align: top; +} + +DIV.summary TABLE THEAD TH { + background: #eeeeee; +} + +/* API documentation styles... */ +div.body h1 { + margin: 0; +} +div.body h2 { + margin-top: 1.5em; +} +div.body h3, div.body h4, div.body h5 { + margin-bottom: 0.5em; + margin-top: 1.5em; +} +.class, .enumeration, .function, .struct, .typedef, .union { + border-bottom: solid thin #999999; + margin-bottom: 0; + margin-top: 2em; +} +.description { + margin-top: 0.5em; +} +code, p.code, pre, ul.code li { + font-family: monaco, courier, monospace; + font-size: 90%; +} +ul.code, ul.contents, ul.subcontents { + list-style-type: none; + margin: 0; + padding-left: 0; +} +ul.code li { + margin: 0; +} +ul.contents > li { + margin-top: 1em; +} +ul.contents li ul.code, ul.contents li ul.subcontents { + padding-left: 2em; +} +div.body dl { + margin-left: 0; + margin-top: 0; +} +div.body dt { + font-style: italic; + margin-left: 0; + margin-top: 0; +} +div.body dd { + margin-bottom: 0.5em; +} + +/* This is just for the HTML files generated with the framedhelp target */ +div.contents { + background: #e8e8e8; + border: solid thin black; + padding: 10px; +} +div.contents h1 { + font-size: 110%; +} +div.contents h2 { + font-size: 100%; +} +div.contents ul.contents { + font-size: 80%; +} +div.contents ul.subcontents li { + margin-left: 1em; + text-indent: -1em; +} +--></style> </head> <body> +<div class='body'> <!-- - "$Id: spec-ppd.html 9406 2010-12-08 07:23:22Z mike $" + "$Id: spec-ppd.html 9813 2011-06-01 17:00:27Z mike $" - CUPS PPD extensions specification for CUPS. + PPD extension documentation for CUPS. - Copyright 2007-2010 by Apple Inc. + Copyright 2007-2011 by Apple Inc. Copyright 1997-2007 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -24,24 +357,89 @@ <H1 CLASS="title">CUPS PPD Extensions</H1> -<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2> - -<p>This specification describes the attributes and extensions -that CUPS adds to <a -href="http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_v4.3.pdf"> -Adobe TechNote #5003: PostScript Printer Description File Format -Specification Version 4.3</a>. PostScript Printer Description -("PPD") files describe the capabilities of each printer and are -used by CUPS to support printer-specific features and intelligent -filtering.</p> +<p>This specification describes the attributes and extensions that CUPS adds to <a href="http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_v4.3.pdf" target="_blank">Adobe TechNote #5003: PostScript Printer Description File Format Specification Version 4.3</a>. PostScript Printer Description ("PPD") files describe the capabilities of each printer and are used by CUPS to support printer-specific features and intelligent filtering.</p> +<div class='summary'><table summary='General Information'> +<tbody> +<tr> + <th>See Also</th> + <td>Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br> + Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br> + Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br> + Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br> + Programming: <a href='api-raster.html'>Raster API</a><br> + References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a></td> +</tr> +</tbody> +</table></div> +<h2 class="title">Contents</h2> +<ul class="contents"> +<li><a href="#SYNTAX">PPD File Syntax</a></li> +<li><a href="#AUTOCONFIG">Auto-Configuration</a><ul class="subcontents"> + <li><a href="#APAutoSetupTool">APAutoSetupTool</a></li> + <li><a href="#QUERYKEYWORD">?MainKeyword</a></li> + <li><a href="#OID">OIDMainKeyword</a></li> +</ul></li> +<li><a href="#PROFILES">Color Profiles</a><ul class="subcontents"> + <li><a href="#cupsColorProfile">cupsColorProfile</a></li> + <li><a href="#cupsICCProfile">cupsICCProfile</a></li> + <li><a href="#APCustom">Custom Color Matching Support</a></li> +</ul></li> +<li><a href="#CONSTRAINTS">Constraints</a><ul class="subcontents"> + <li><a href="#cupsUIConstraints">cupsUIConstraints</a></li> + <li><a href="#cupsUIResolver">cupsUIResolver</a></li> +</ul></li> +<li><a href="#I18N">Globalized PPD Support</a></li> +<li><a href="#OPTIONS">CUPS 1.3/Mac OS X 10.6Custom Options</a></li> +<li><a href="#RASTERPS">Writing PostScript Option Commands for Raster Drivers</a></li> +<li><a href="#MEDIA">Media Keywords</a><ul class="subcontents"> + <li><a href="#cupsMediaQualifier2">cupsMediaQualifier2</a></li> + <li><a href="#cupsMediaQualifier3">cupsMediaQualifier3</a></li> + <li><a href="#cupsMinSize">cupsMinSize</a></li> + <li><a href="#cupsMaxSize">cupsMaxSize</a></li> +</ul></li> +<li><a href="#ATTRIBUTES">General Attributes</a><ul class="subcontents"> + <li><a href="#cupsBackSide">cupsBackSide</a></li> + <li><a href="#cupsCommands">cupsCommands</a></li> + <li><a href="#cupsEvenDuplex">cupsEvenDuplex</a></li> + <li><a href="#cupsFax">cupsFax</a></li> + <li><a href="#cupsFilter">cupsFilter</a></li> + <li><a href="#cupsFilter2">cupsFilter2</a></li> + <li><a href="#cupsFlipDuplex">cupsFlipDuplex</a></li> + <li><a href="#cupsIPPFinishings">cupsIPPFinishings</a></li> + <li><a href="#cupsIPPReason">cupsIPPReason</a></li> + <li><a href="#cupsIPPSupplies">cupsIPPSupplies</a></li> + <li><a href="#cupsLanguages">cupsLanguages</a></li> + <li><a href="#cupsManualCopies">cupsManualCopies</a></li> + <li><a href="#cupsMarkerName">cupsMarkerName</a></li> + <li><a href="#cupsMarkerNotice">cupsMarkerNotice</a></li> + <li><a href="#cupsModelNumber">cupsModelNumber</a></li> + <li><a href="#cupsPJLCharset">cupsPJLCharset</a></li> + <li><a href="#cupsPJLDisplay">cupsPJLDisplay</a></li> + <li><a href="#cupsPortMonitor">cupsPortMonitor</a></li> + <li><a href="#cupsPreFilter">cupsPreFilter</a></li> + <li><a href="#cupsPrintQuality">cupsPrintQuality</a></li> + <li><a href="#cupsSingleFile">cupsSingleFile</a></li> + <li><a href="#cupsSNMPSupplies">cupsSNMPSupplies</a></li> + <li><a href="#cupsVersion">cupsVersion</a></li> +</ul></li> +<li><a href="#MACOSX">Mac OS X Attributes</a><ul class="subcontents"> + <li><a href="#APDialogExtension">APDialogExtension</a></li> + <li><a href="#APDuplexRequiresFlippedMargin">APDuplexRequiresFlippedMargin</a></li> + <li><a href="#APHelpBook">APHelpBook</a></li> + <li><a href="#APICADriver">APICADriver</a></li> + <li><a href="#APPrinterIconPath">APPrinterIconPath</a></li> + <li><a href="#APPrinterLowInkTool">APPrinterLowInkTool</a></li> + <li><a href="#APPrinterPreset">APPrinterPreset</a></li> + <li><a href="#APPrinterUtilityPath">APPrinterUtilityPath</a></li> + <li><a href="#APScannerOnly">APScannerOnly</a></li> + <li><a href="#APScanAppBundleID">APScanAppBundleID</a></li> +</ul></li> +<li><a href="#HISTORY">Change History</a></li> +</ul> <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2> -<p>The PPD format is text-based and uses lines of up to 255 -characters terminated by a carriage return, linefeed, or -combination of carriage return and line feed. The following ABNF -definition [RFC4234] defines the general format of lines in a PPD -file:</p> +<p>The PPD format is text-based and uses lines of up to 255 characters terminated by a carriage return, linefeed, or combination of carriage return and line feed. The following ABNF definition [<a href="http://tools.ietf.org/html/rfc5234" target="_blank">RFC5234</a>] defines the general format of lines in a PPD file:</p> <pre class='command'> PPD-FILE = HEADER +(DATA / COMMENT / LINE-END) @@ -69,20 +467,15 @@ LINE-END = CR / LF / CR LF <h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2> -<p>CUPS supports several methods of auto-configuration via PPD attributes. -<em>Currently these methods are only implemented on Mac OS X.</em></p> +<p>CUPS supports several methods of auto-configuration via PPD keywords.</p> <h3><span class='info'>Mac OS X 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3> <p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p> -<p>This attribute defines a program that sets the default option choices. It -is run when a printer is added from the printer browser instead of the -normal PostScript query and SNMP OID attribute lookups.</p> +<p>This Mac OS X keyword defines a program that sets the default option choices. It is run when a printer is added from the <var>Add Printer</var> window or the <var>Nearby Printers</var> list in the <var>Print</var> dialog.</p> -<p>The program is provided with two arguments: the printer's device URI and -the PPD file to be used for the printer. The program must write an updated -PPD file to stdout.</p> +<p>The program is provided with two arguments: the printer's device URI and the PPD file to be used for the printer. The program must write an updated PPD file to stdout.</p> <p>Examples:</p> @@ -91,20 +484,16 @@ PPD file to stdout.</p> *APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool" </pre> -<h3><span class='info'>Mac OS X 10.2</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3> +<h3><span class='info'>Mac OS X 10.2/CUPS 1.4</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3> <p class='summary'>*?<i>MainKeyword</i>: "<br> PostScript query code that writes a message using the = operator...<br> "<br> *End</p> -<p>The <tt>?<i>MainKeyword</i></tt> attribute defines PostScript code that -determines the currently selected/enabled option keyword (choice) for the -main keyword (option). It is typically used when communicating with USB, -serial, Appletalk, and AppSocket (port 9100) printers.</p> +<p>The <tt>?<i>MainKeyword</i></tt> keyword defines PostScript code that determines the currently selected/enabled option keyword (choice) for the main keyword (option). It is typically used when communicating with USB, serial, Appletalk, and AppSocket (port 9100) printers.</p> -<p>The PostScript code typically sends its response back using the <tt>=</tt> -operator.</p> +<p>The PostScript code typically sends its response back using the <tt>=</tt> operator.</p> <p>Example:</p> @@ -124,20 +513,14 @@ operator.</p> *CloseUI: OptionDuplex </pre> -<h3><span class='info'>Mac OS X 10.4</span><a name='OID'>OIDMainKeyword</a></h3> +<h3><span class='info'>Mac OS X 10.4/CUPS 1.5</span><a name='OID'>OIDMainKeyword</a></h3> <p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br> *OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br> ...<br> *OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p> -<p>The <tt>OID<i>MainKeyword</i></tt> attribute is used to define -SNMP OIDs that map to installable options. The first (query) line -defines the OID to lookup on the network device. The second and -subsequent attributes define a mapping from OID value to option -keyword. Since SNMP is an IP-based network protocol, this method -is typically only used to configure AppSocket, IPP, and LPD network -printers.</p> +<p>The <tt>OID<i>MainKeyword</i></tt> keyword is used to define SNMP OIDs that map to installable options. The first (query) line defines the OID to lookup on the network device. The second and subsequent keywords define a mapping from OID value to option keyword. Since SNMP is an IP-based network protocol, this method is typically only used to configure AppSocket, IPP, and LPD network printers.</p> <p>Examples:</p> @@ -153,32 +536,21 @@ printers.</p> <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2> -<p>CUPS supports three types of color profiles. The first type is -based on sRGB and is used by the standard CUPS raster filters and -GPL Ghostscript. The second type is based on ICC profiles and is -used by the Quartz-based filters on MacOS X. The final type is -based on well-known colorspaces such as sRGB and Adobe RGB.</p> +<p>CUPS supports three types of color profiles. The first type is based on sRGB and is used by the standard CUPS raster filters and GPL Ghostscript. The second type is based on ICC profiles and is used by the Quartz-based filters on MacOS X. The final type is based on well-known colorspaces such as sRGB and Adobe RGB.</p> <blockquote><b>Note:</b> -<p>At this time, none of the CUPS raster filters support ICC profiles. This -will be addressed as time and resources permit.</p> +<p>At this time, none of the CUPS raster filters support ICC profiles. This will be addressed as time and resources permit.</p> </blockquote> <h3><span class='info'>Deprecated</span><a name='cupsColorProfile'>cupsColorProfile</a></h3> -<p class='summary'>*cupsColorProfile Resolution/MediaType: "density -gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p> +<p class='summary'>*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p> -<p>This string attribute specifies an sRGB-based color profile -consisting of gamma and density controls and a 3x3 CMY color -transform matrix. <em>This attribute is not supported on Mac OS X.</em></p> +<p>This string keyword specifies an sRGB-based color profile consisting of gamma and density controls and a 3x3 CMY color transform matrix. <em>This keyword is not supported on Mac OS X.</em></p> -<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-" -to act as a wildcard. Otherwise they must match one of the -<tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in -the PPD file.</p> +<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-" to act as a wildcard. Otherwise they must match one of the <tt>Resolution</tt> or <tt>MediaType</tt> option keywords defined in the PPD file.</p> <p>The <i>density</i> and <i>gamma</i> values define gamma and density adjustment function such that:</p> @@ -187,9 +559,7 @@ density adjustment function such that:</p> f(x) = density * x <sup style='font-size: 100%'>gamma</sup> </pre> -<p>The <i>m00</i> through <i>m22</i> values define a 3x3 -transformation matrix for the CMY color values. The density -function is applied <i>after</i> the CMY transformation:</p> +<p>The <i>m00</i> through <i>m22</i> values define a 3x3 transformation matrix for the CMY color values. The density function is applied <i>after</i> the CMY transformation:</p> <pre class='command'> | m00 m01 m02 | @@ -200,57 +570,44 @@ function is applied <i>after</i> the CMY transformation:</p> <p>Examples:</p> <pre class='command'> -<em>*% Specify a profile for printing at 360dpi on all media types</em> +<em>*% Specify a profile for printing at 360dpi on all media types</em> *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" -<em>*% Specify a profile for printing at 720dpi on Glossy media</em> +<em>*% Specify a profile for printing at 720dpi on Glossy media</em> *cupsColorProfile 720dpi/Glossy: "1.0 2.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" -<em>*% Specify a default profile for printing at all other resolutions and media types</em> +<em>*% Specify a default profile for printing at all other resolutions and media types</em> *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" </pre> -<h3><span class='info'>Mac OS X 10.3/CUPS 1.2/Mac OS X 10.5</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> +<h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> -<p class='summary'>*cupsICCProfile -ColorModel.MediaType.Resolution/Description: "filename"</p> +<p class='summary'>*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"</p> -<p>This attribute specifies an ICC color profile that is -used to convert the document colors to the device -colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and -<tt>Resolution</tt> keywords specify a selector for color -profiles. If omitted, the color profile will match any option -keyword for the corresponding main keyword.</p> +<p>This keyword specifies an ICC color profile that is used to convert the document colors to the device colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and <tt>Resolution</tt> option keywords specify a selector for color profiles. If omitted, the color profile will match any option keyword for the corresponding main keyword.</p> -<p>The <tt>Description</tt> specifies human-readable text that -is associated with the color profile. The <tt>filename</tt> -portion specifies the ICC color profile to use; if the filename -is not absolute, it is loaded relative to the -<var>/usr/share/cups/profiles</var> directory.</p> +<p>The <tt>Description</tt> specifies human-readable text that is associated with the color profile. The <tt>filename</tt> portion specifies the ICC color profile to use; if the filename is not absolute, it is loaded relative to the <var>/usr/share/cups/profiles</var> directory.</p> <p>Examples:</p> <pre class='command'> -<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em> +<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em> *cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc" -<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em> +<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em> *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc" -<em>*% Specify a default profile for printing at all other resolutions and media types</em> +<em>*% Specify a default profile for printing at all other resolutions and media types</em> *cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc" </pre> <h4>Customizing the Profile Selection Keywords</h4> -<p>The <tt>MediaType</tt> and <tt>Resolution</tt> keywords can be -reassigned to different main keywords, allowing drivers to do -color profile selection based on different parameters. The -<tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> -attributes define the mapping from selector to main keyword:</p> +<p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and <tt>Resolution</tt> main keywords can be reassigned to different main keywords, allowing drivers to do color profile selection based on different parameters. The <tt>cupsICCQualifier1</tt>, <tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt> keywords define the mapping from selector to main keyword:</p> <pre class='command'> +*cupsICCQualifier1: MainKeyword1 *cupsICCQualifier2: MainKeyword2 *cupsICCQualifier3: MainKeyword3 </pre> @@ -258,6 +615,7 @@ attributes define the mapping from selector to main keyword:</p> <p>The default mapping is as follows:</p> <pre class='command'> +*cupsICCQualifier1: ColorModel *cupsICCQualifier2: MediaType *cupsICCQualifier3: Resolution </pre> @@ -269,19 +627,11 @@ attributes define the mapping from selector to main keyword:</p> *<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br> *<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p> -<p>These attributes tell the Mac OS X raster filters that the printer -driver provides its own custom color matching and that generic color -profiles should be used when generating 1-, 3-, and 4-component raster -data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt> -and <tt>APDefaultColorMatchingProfile</tt> attributes specify alternate -color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p> +<p>These keywords tell the Mac OS X raster filters that the printer driver provides its own custom color matching and that generic color profiles should be used when generating 1-, 3-, and 4-component raster data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt> and <tt>APDefaultColorMatchingProfile</tt> keywords specify alternate color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p> <blockquote><b>Note:</b> -<p>Prior to Mac OS X 10.6, the default RGB color space was Apple's "GenericRGB". -The new default in Mac OS X 10.6 and later is "sRGB". For more information, see -<a href="http://support.apple.com/kb/HT3712">"Mac OS X v10.6: About gamma -2.2"</a> on Apple's support site.</p> +<p>Prior to Mac OS X 10.6, the default RGB color space was Apple's "GenericRGB". The new default in Mac OS X 10.6 and later is "sRGB". For more information, see <a href="http://support.apple.com/kb/HT3712">"Mac OS X v10.6: About gamma 2.2"</a> on Apple's support site.</p> </blockquote> @@ -289,10 +639,7 @@ The new default in Mac OS X 10.6 and later is "sRGB". For more information, see <p class='summary'>*APCustomColorMatchingName name/text: ""</p> -<p>This attribute defines an alternate name for the color matching -provided by a driver in the <var>Color Matching</var> print panel. -The default is to use the name "Vendor Matching" or its localized -equivalent.</p> +<p>This keyword defines an alternate name for the color matching provided by a driver in the <var>Color Matching</var> print panel. The default is to use the name "Vendor Matching" or its localized equivalent.</p> <p>Examples:</p> @@ -306,18 +653,11 @@ equivalent.</p> <p class='summary'>*APCustomColorMatchingProfile: name</p> -<p>This attribute defines a supported RGB color profile that can be used -when doing custom color matching. Currently only <tt>sRGB</tt>, -<tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported. If not specified, RGB -data will use the GenericRGB colorspace.</p> +<p>This keyword defines a supported RGB color profile that can be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported. If not specified, RGB data will use the GenericRGB colorspace.</p> <blockquote><b>Note:</b> -<p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> attributes, -you are responsible for providing the necessary user interface controls to -select the profile in a <a href='#APDialogExtension'>print dialog pane</a>. -Add the named profile to the print settings using the key -<tt>kPMCustomColorMatchingProfileKey</tt>.</p> +<p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> keywords, you are responsible for providing the necessary user interface controls to select the profile in a <a href='#APDialogExtension'>print dialog pane</a>. Add the named profile to the print settings using the key <tt>kPMCustomColorMatchingProfileKey</tt>.</p> </blockquote> @@ -335,9 +675,7 @@ Add the named profile to the print settings using the key <p class='summary'>*APDefaultCustomColorMatchingProfile: name</p> -<p>This attribute defines the default RGB color profile that will be used -when doing custom color matching. Currently only <tt>sRGB</tt>, -<tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported.</p> +<p>This keyword defines the default RGB color profile that will be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported.</p> <p>Examples:</p> @@ -351,12 +689,7 @@ when doing custom color matching. Currently only <tt>sRGB</tt>, <p class='summary'>*APSupportsCustomColorMatching: boolean</p> -<p>This attribute specifies that the driver provides its own custom color -matching. When <tt>true</tt>, the default hand-off colorspace will be -GenericGray, GenericRGB, or GenericCMYK depending on the number of -components the driver requests. The <a -href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a> -attribute can be used to override the default 3-component (RGB) colorspace.</p> +<p>This keyword specifies that the driver provides its own custom color matching. When <tt>true</tt>, the default hand-off colorspace will be GenericGray, GenericRGB, or GenericCMYK depending on the number of components the driver requests. The <a href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a> keyword can be used to override the default 3-component (RGB) colorspace.</p> <p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p> @@ -370,11 +703,7 @@ attribute can be used to override the default 3-component (RGB) colorspace.</p> <h2 class='title'><a name='CONSTRAINTS'>Constraints</a></h2> -<p>Constraints are option choices that are not allowed by the driver or -device, for example printing 2-sided transparencies. All versions of CUPS -support constraints defined by the legacy Adobe <tt>UIConstraints</tt> and -<tt>NonUIConstraints</tt> attributes which support conflicts between any two -option choices, for example:</p> +<p>Constraints are option choices that are not allowed by the driver or device, for example printing 2-sided transparencies. All versions of CUPS support constraints defined by the legacy Adobe <tt>UIConstraints</tt> and <tt>NonUIConstraints</tt> keywords which support conflicts between any two option choices, for example:</p> <pre class='command'> *% Do not allow 2-sided printing on transparency media @@ -382,24 +711,13 @@ option choices, for example:</p> *UIConstraints: "*MediaType Transparency *Duplex" </pre> -<p>While nearly all constraints can be expressed using these attributes, there -are valid scenarios requiring constraints between more than two option choices. -In addition, resolution of constraints is problematic since users and software -have to guess how a particular constraint is best resolved.</p> +<p>While nearly all constraints can be expressed using these keywords, there are valid scenarios requiring constraints between more than two option choices. In addition, resolution of constraints is problematic since users and software have to guess how a particular constraint is best resolved.</p> -<p>CUPS 1.4 and higher define two new attributes for constraints, -<tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each -<tt>cupsUIConstraints</tt> attribute points to a <tt>cupsUIResolver</tt> -attribute which specifies alternate options that resolve the conflict condition. -The same <tt>cupsUIResolver</tt> can be used by multiple -<tt>cupsUIConstraints</tt>.</p> +<p>CUPS 1.4 and higher define two new keywords for constraints, <tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each <tt>cupsUIConstraints</tt> keyword points to a <tt>cupsUIResolver</tt> keyword which specifies alternate options that resolve the conflict condition. The same <tt>cupsUIResolver</tt> can be used by multiple <tt>cupsUIConstraints</tt>.</p> <blockquote><b>Note:</b> - <p>When developing PPD files that contain constraints, it is very important - to use the <a href="man-cupstestppd.html">cupstestppd(1)</a> program to - verify that your constraints are accurate and cannot result in unresolvable - option selections.</p> +<p>When developing PPD files that contain constraints, it is very important to use the <a href="man-cupstestppd.html">cupstestppd(1)</a> program to verify that your constraints are accurate and cannot result in unresolvable option selections.</p> </blockquote> @@ -411,18 +729,15 @@ The same <tt>cupsUIResolver</tt> can be used by multiple *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."<br> *cupsUIConstraints: "*InstallableKeyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p> -<p>Lists two or more options which conflict. The "resolver" string is a -(possibly unique) keyword which specifies which options to change when the -constraint exists. When no resolver is provided, CUPS first tries the default -choice followed by testing each option choice to resolve the conflict.</p> +<p>Lists two or more options which conflict. The "resolver" string is a (possibly unique) keyword which specifies which options to change when the constraint exists. When no resolver is provided, CUPS first tries the default choice followed by testing each option choice to resolve the conflict.</p> <p>Examples:</p> <pre class='command'> -<em>*% Specify that 2-sided printing cannot happen on transparencies</em> +<em>*% Specify that 2-sided printing cannot happen on transparencies</em> *cupsUIConstraints transparency: "*Duplex *MediaType Transparency" -<em>*% Specify that envelope printing cannot happen from the paper trays</em> +<em>*% Specify that envelope printing cannot happen from the paper trays</em> *cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1" *cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1" *cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2" @@ -431,7 +746,7 @@ choice followed by testing each option choice to resolve the conflict.</p> <em>*% Specify an installable option constraint for the envelope feeder</em> *cupsUIConstraints: "*InputSlot EnvFeeder *InstalledEnvFeeder" -<em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em> +<em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em> *cupsUIConstraints photo: "*OutputMode Photo *MediaType Plain *Resolution 1200dpi" *cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi" </pre> @@ -440,21 +755,12 @@ choice followed by testing each option choice to resolve the conflict.</p> <p class='summary'>*cupsUIResolver resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p> -<p>Specifies two or more options to mark/select to resolve a constraint. The -"resolver" string identifies a particular action to take for one or more -<a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action -can be used for multiple constraints. The option keyword pairs are treated as -an ordered list of option selections to try - only the first N selections will -be used, where N is the minimum number of selections required. Because -<a href="api-ppd.html#cupsResolveConflicts"><code>cupsResolveConflicts()</code></a> -will not change the most recent option selection passed to it, at least two -options from the constraints must be listed to avoid situations where conflicts -cannot be resolved.</p> +<p>Specifies two or more options to mark/select to resolve a constraint. The "resolver" string identifies a particular action to take for one or more <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action can be used for multiple constraints. The option keyword pairs are treated as an ordered list of option selections to try - only the first N selections will be used, where N is the minimum number of selections required. Because <a href="api-ppd.html#cupsResolveConflicts"><code>cupsResolveConflicts()</code></a> will not change the most recent option selection passed to it, at least two options from the constraints must be listed to avoid situations where conflicts cannot be resolved.</p> <p>Examples:</p> <pre class='command'> -<em>*% Specify the options to change for the 2-sided transparency constraint</em> +<em>*% Specify the options to change for the 2-sided transparency constraint</em> *cupsUIResolver transparency: "*Duplex None *MediaType Plain" <em>*% Specify the options to change for the envelope printing constraints. Notice @@ -462,15 +768,14 @@ cannot be resolved.</p> *% manual feed first, then we change the page size...</em> *cupsUIResolver envelope: "*InputSlot EnvFeeder *InputSlot ManualFeed *PageSize Letter" -<em>*% Specify the options to change for the photo printing constraints</em> +<em>*% Specify the options to change for the photo printing constraints</em> *cupsUIResolver photo: "*OutputMode Best *Resolution 600dpi" </pre> <h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2> -<p>CUPS 1.2 and higher adds support for PPD files containing multiple -languages by following the following additional rules:</p> +<p>CUPS 1.2 and higher adds support for PPD files containing multiple languages by following the following additional rules:</p> <ol> @@ -478,59 +783,36 @@ languages by following the following additional rules:</p> <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li> - <li>The <tt>cupsLanguages</tt> attribute MUST be provided and - list each of the supported locales in the PPD file</li> + <li>The <tt>cupsLanguages</tt> keyword MUST be provided and list each of the supported locales in the PPD file</li> - <li>Main and option keywords MUST NOT exceed 34 (instead of 40) - characters to allow room for the locale prefixes in translation - attributes</li> + <li>Main and option keywords MUST NOT exceed 34 (instead of 40) characters to allow room for the locale prefixes in translation keywords</li> <li>The main keyword "Translation" MUST NOT be used</li> - <li>Translation strings included with the main and option - keywords MUST NOT contain characters outside the ASCII - subset of ISOLatin1 and UTF-8; developers wishing to use - characters outside ASCII MUST provide a separate set of - English localization attributes for the affected keywords.</li> + <li>Translation strings included with the main and option keywords MUST NOT contain characters outside the ASCII subset of ISOLatin1 and UTF-8; developers wishing to use characters outside ASCII MUST provide a separate set of English localization keywords for the affected keywords.</li> - <li>Localizations are specified using a locale prefix of - the form "ll" or "ll_CC." where "ll" is the 2-letter ISO - language code and "CC" is the 2-letter ISO country - code<ul> + <li>Localizations are specified using a locale prefix of the form "ll" or "ll_CC." where "ll" is the 2-letter ISO language code and "CC" is the 2-letter ISO country code<ul> <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li> <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li> </ul></li> - <li>Locale-specific translation strings MUST be encoded - using UTF-8.</li> + <li>Locale-specific translation strings MUST be encoded using UTF-8.</li> - <li>Main keywords MUST be localized using one of the - following forms: - <p><tt>*ll.Translation MainKeyword/translation - text: ""</tt><br /> - <tt>*ll_CC.Translation MainKeyword/translation - text: ""</tt></p></li> + <li>Main keywords MUST be localized using one of the following forms: + <p><tt>*ll.Translation MainKeyword/translation text: ""</tt><br /> + <tt>*ll_CC.Translation MainKeyword/translation text: ""</tt></p></li> - <li>Option keywords MUST be localized using one of the - following forms: - <p><tt>*ll.MainKeyword OptionKeyword/translation - text: ""</tt><br /> - <tt>*ll_CC.MainKeyword OptionKeyword/translation - text: ""</tt></p></li> + <li>Option keywords MUST be localized using one of the following forms: + <p><tt>*ll.MainKeyword OptionKeyword/translation text: ""</tt><br> + <tt>*ll_CC.MainKeyword OptionKeyword/translation text: ""</tt></p></li> - <li>Localization attributes MAY appear anywhere after the - first line of the PPD file</li> + <li>Localization keywords MAY appear anywhere after the first line of the PPD file</li> </ol> <blockquote><b>Note:</b> -<p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt> -and limit the allowed base translation strings to ASCII to avoid -character coding issues that would otherwise occur. In addition, -requiring the base translation strings to be in English allows -for easier fallback translation when no localization is provided -in the PPD file for a given locale.</p> +<p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt> and limit the allowed base translation strings to ASCII to avoid character coding issues that would otherwise occur. In addition, requiring the base translation strings to be in English allows for easier fallback translation when no localization is provided in the PPD file for a given locale.</p> </blockquote> @@ -571,11 +853,9 @@ in the PPD file for a given locale.</p> </pre> -<h2 class='title'><a name='OPTIONS'>Custom Options</a></h2> +<h2 class='title'><a name='OPTIONS'><span class="info">CUPS 1.3/Mac OS X 10.6</span>Custom Options</a></h2> -<p>CUPS supports custom options using an extension of the -<tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt> -syntax:</p> +<p>CUPS supports custom options using an extension of the <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt> syntax:</p> <pre class='command'> *CustomFoo True: "command" @@ -585,72 +865,37 @@ syntax:</p> *ParamCustomFoo NameN/Text N: order type minimum maximum </pre> -<p>When the base option is part of the <tt>JCLSetup</tt> section, -the "command" string contains JCL commands with "\order" -placeholders for each numbered parameter. The CUPS API handles -any necessary value quoting for HP-PJL commands. For example, if -the JCL command string is "@PJL SET PASSCODE=\1" and the first -option value is "1234" then CUPS will output the string -"@PJL SET PASSCODE=1234".</p> +<p>When the base option is part of the <tt>JCLSetup</tt> section, the "command" string contains JCL commands with "\order" placeholders for each numbered parameter. The CUPS API handles any necessary value quoting for HP-PJL commands. For example, if the JCL command string is "@PJL SET PASSCODE=\1" and the first +option value is "1234" then CUPS will output the string "@PJL SET PASSCODE=1234".</p> -<p>For non-<tt>JCLSetup</tt> options, the "order" value is a -number from 1 to N and specifies the order of values as they are -placed on the stack before the command. For example, if the -PostScript command string is -"<</cupsReal1 2 1 roll>>setpagedevice" and the -option value is "2.0" then CUPS will output the string -"2.0 <</cupsReal1 2 1 roll>>setpagedevice".</p> +<p>For non-<tt>JCLSetup</tt> options, the "order" value is a number from 1 to N and specifies the order of values as they are placed on the stack before the command. For example, if the PostScript command string is "<</cupsReal1 2 1 roll>>setpagedevice" and the option value is "2.0" then CUPS will output the string "2.0 <</cupsReal1 2 1 roll>>setpagedevice".</p> <p>The "type" is one of the following keywords:</p> <ul> - <li><tt>curve</tt> - a real value from "minimum" to - "maximum" representing a gamma correction curve using the - function: f(x) = x <sup>value</sup></li> + <li><tt>curve</tt> - a real value from "minimum" to "maximum" representing a gamma correction curve using the function: f(x) = x <sup>value</sup></li> - <li><tt>int</tt> - an integer value from "minimum" to - "maximum"</li> + <li><tt>int</tt> - an integer value from "minimum" to "maximum"</li> - <li><tt>invcurve</tt> - a real value from "minimum" to - "maximum" representing a gamma correction curve using the - function: f(x) = x <sup>1 / value</sup></li> + <li><tt>invcurve</tt> - a real value from "minimum" to "maximum" representing a gamma correction curve using the function: f(x) = x <sup>1 / value</sup></li> - <li><tt>passcode</tt> - a string of numbers value with a - minimum of "minimum" numbers and a maximum of "maximum" - numbers ("minimum" and "maximum" are numbers and passcode - strings are not displayed in the user interface)</li> + <li><tt>passcode</tt> - a string of numbers value with a minimum of "minimum" numbers and a maximum of "maximum" numbers ("minimum" and "maximum" are numbers and passcode strings are not displayed in the user interface)</li> - <li><tt>password</tt> - a string value with a minimum of - "minimum" characters and a maximum of "maximum" - characters ("minimum" and "maximum" are numbers and password - strings are not displayed in the user interface)</li> + <li><tt>password</tt> - a string value with a minimum of "minimum" characters and a maximum of "maximum" characters ("minimum" and "maximum" are numbers and password strings are not displayed in the user interface)</li> - <li><tt>points</tt> - a measurement value in points from - "minimum" to "maximum"</li> + <li><tt>points</tt> - a measurement value in points from "minimum" to "maximum"</li> - <li><tt>real</tt> - a real value from "minimum" to - "maximum"</li> + <li><tt>real</tt> - a real value from "minimum" to "maximum"</li> - <li><tt>string</tt> - a string value with a minimum of - "minimum" characters and a maximum of "maximum" - characters ("minimum" and "maximum" are numbers)</li> + <li><tt>string</tt> - a string value with a minimum of "minimum" characters and a maximum of "maximum" characters ("minimum" and "maximum" are numbers)</li> </ul> -<blockquote><b>Note:</b> - -<p>Custom options are not directly supported by the Mac OS X Print Dialog -nor by the CUPS web interface at this time. Vendors that use custom -options on Mac OS X must provide their own user interface via the -<a href='#APDialogExtension'><tt>APDialogExtension</tt></a> attribute.</p> - -</blockquote> - <p>Examples:</p> <pre class='command'> -<em>*% Base JCL key code option</em> +<em>*% Base JCL key code option</em> *JCLOpenUI JCLPasscode/Key Code: PickOne *OrderDependency: 10 JCLSetup *JCLPasscode *DefaultJCLPasscode: None @@ -660,7 +905,7 @@ options on Mac OS X must provide their own user interface via the *JCLPasscode 3333: "@PJL SET PASSCODE = 3333<0A>" *JCLCloseUI: *JCLPasscode -<em>*% Custom JCL key code option</em> +<em>*% Custom JCL key code option</em> *CustomJCLPasscode True: "@PJL SET PASSCODE = \1<0A>" *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4 @@ -678,7 +923,7 @@ options on Mac OS X must provide their own user interface via the *ParamCustomWatermarkText Text: 1 string 0 32 -<em>*% Base PostScript gamma/density option</em> +<em>*% Base PostScript gamma/density option</em> *OpenUI GammaDensity/Gamma and Density: PickOne *OrderDependency: 10 AnySetup *GammaDensity *DefaultGammaDensity: Normal @@ -687,7 +932,7 @@ options on Mac OS X must provide their own user interface via the *GammaDensity Dark/Darker: "<</cupsReal1 1.1/cupsReal2 1.5>>setpagedevice" *CloseUI: *GammaDensity -<em>*% Custom PostScript gamma/density option</em> +<em>*% Custom PostScript gamma/density option</em> *CustomGammaDensity True: "<</cupsReal1 3 -1 roll/cupsReal2 5 -1>>setpagedevice" *ParamCustomGammaDensity Gamma: 1 curve 0.1 10 *ParamCustomGammaDensity Density: 2 real 0 2 @@ -696,7 +941,7 @@ options on Mac OS X must provide their own user interface via the <h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2> -<p>PPD files are used for both PostScript and non-PostScript printers. For CUPS raster drivers, you use a subset of the PostScript language to set page device attributes such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p> +<p>PPD files are used for both PostScript and non-PostScript printers. For CUPS raster drivers, you use a subset of the PostScript language to set page device keywords such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p> <pre class='command'> *PageSize A4: "<</PageSize[595 842]>>setpagedevice" @@ -1061,16 +1306,16 @@ PRE B { </table></div> -<h2 class='title'><a name='MEDIA'>Media Attributes</a></h2> +<h2 class='title'><a name='MEDIA'>Media Keywords</a></h2> -<p>The CUPS media attributes allow drivers to specify alternate custom page +<p>The CUPS media keywords allow drivers to specify alternate custom page size limits based on up to two options.</p> <h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMediaQualifier2'>cupsMediaQualifier2</a></h3> <p class='summary'>*cupsMediaQualifier2: MainKeyword</p> -<p>This attribute specifies the second option to use for overriding the +<p>This keyword specifies the second option to use for overriding the custom page size limits.</p> <p>Example:</p> @@ -1089,7 +1334,7 @@ custom page size limits.</p> <p class='summary'>*cupsMediaQualifier3: MainKeyword</p> -<p>This attribute specifies the third option to use for overriding the +<p>This keyword specifies the third option to use for overriding the custom page size limits.</p> <p>Example:</p> @@ -1110,9 +1355,9 @@ custom page size limits.</p> *cupsMinSize .Qualifier2.: "width length"<br> *cupsMinSize ..Qualifier3: "width length"</p> -<p>This attribute specifies alternate minimum custom page sizes in points. +<p>This keyword specifies alternate minimum custom page sizes in points. The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and -<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> attributes +<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords are used to identify options to use for matching.</p> <p>Example:</p> @@ -1133,9 +1378,9 @@ are used to identify options to use for matching.</p> *cupsMaxSize .Qualifier2.: "width length"<br> *cupsMaxSize ..Qualifier3: "width length"</p> -<p>This attribute specifies alternate maximum custom page sizes in points. +<p>This keyword specifies alternate maximum custom page sizes in points. The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and -<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> attributes +<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords are used to identify options to use for matching.</p> <p>Example:</p> @@ -1157,9 +1402,9 @@ are used to identify options to use for matching.</p> <p class='summary'>*cupsBackSide: keyword</p> -<p>This attribute requests special handling of the back side of pages +<p>This keyword requests special handling of the back side of pages when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a> -shows the supported keyword values for this attribute and their effect +shows the supported keyword values for this keyword and their effect on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt> is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver will receive print data starting at the bottom right corner of the page, with @@ -1169,7 +1414,7 @@ each line going right-to-left instead of left-to-right. The default value is <blockquote><b>Note:</b> <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt> -attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt> +keyword - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt> will be ignored.</p> </blockquote> @@ -1239,28 +1484,28 @@ will be ignored.</p> <p>Examples:</p> <pre class='command'> -<em>*% Flip the page image for the back side of duplexed output</em> +<em>*% Flip the page image for the back side of duplexed output</em> *cupsBackSide: Flipped -<em>*% Rotate the page image for the back side of duplexed output</em> +<em>*% Rotate the page image for the back side of duplexed output</em> *cupsBackSide: Rotated </pre> <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> -attribute.</p> +keyword.</p> <h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsCommands'>cupsCommands</a></h3> <p class='summary'>*cupsCommands: "name name2 ... nameN"</p> -<p>This string attribute specifies the commands that are supported by the +<p>This string keyword specifies the commands that are supported by the CUPS command file filter for this device. The command names are separated by whitespace.</p> <p>Example:</p> <pre class='command'> -<em>*% Specify the list of commands we support</em> +<em>*% Specify the list of commands we support</em> *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo" </pre> @@ -1269,14 +1514,14 @@ by whitespace.</p> <p class='summary'>*cupsEvenDuplex: boolean</p> -<p>This boolean attribute notifies the RIP filters that the +<p>This boolean keyword notifies the RIP filters that the destination printer requires an even number of pages when 2-sided printing is selected. The default value is <code>false</code>.</p> <p>Example:</p> <pre class='command'> -<em>*% Always send an even number of pages when duplexing</em> +<em>*% Always send an even number of pages when duplexing</em> *cupsEvenDuplex: true </pre> @@ -1284,7 +1529,7 @@ printing is selected. The default value is <code>false</code>.</p> <p class='summary'>*cupsFax: boolean</p> -<p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p> +<p>This boolean keyword specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p> <p>Examples:</p> @@ -1296,7 +1541,7 @@ printing is selected. The default value is <code>false</code>.</p> <p class='summary'>*cupsFilter: "source/type cost program"</p> -<p>This string attribute provides a conversion rule from the +<p>This string keyword provides a conversion rule from the given source type to the printer's native format using the filter "program". If a printer supports the source type directly, the special filter program "-" may be specified.</p> @@ -1304,23 +1549,48 @@ the special filter program "-" may be specified.</p> <p>Examples:</p> <pre class='command'> -<em>*% Standard raster printer driver filter</em> +<em>*% Standard raster printer driver filter</em> *cupsFilter: "application/vnd.cups-raster 100 rastertofoo" -<em>*% Plain text filter</em> +<em>*% Plain text filter</em> *cupsFilter: "text/plain 10 texttofoo" -<em>*% Pass-through filter for PostScript printers</em> +<em>*% Pass-through filter for PostScript printers</em> *cupsFilter: "application/vnd.cups-postscript 0 -" </pre> +<h3><span class='info'>CUPS 1.5</span><a name='cupsFilter2'>cupsFilter2</a></h3> + +<p class='summary'>*cupsFilter2: "source/type destination/type cost program"</p> + +<p>This string keyword provides a conversion rule from the given source type to the printer's native format using the filter "program". If a printer supports the source type directly, the special filter program "-" may be specified. The destination type is automatically created as needed and is passed to the filters and backend as the FINAL_CONTENT_TYPE value.</p> + +<blockquote><b>Note:</b> + +<p>The presence of a single <code>cupsFilter2</code> keyword in the PPD file will hide any <code>cupsFilter</code> keywords from the CUPS scheduler. When using <code>cupsFilter2</code> to provide filters specific for CUPS 1.5 and later, provide a <code>cupsFilter2</code> line for every filter and a <code>cupsFilter</code> line for each filter that is compatible with older versions of CUPS.</p> + +</blockquote> + +<p>Examples:</p> + +<pre class='command'> +<em>*% Standard raster printer driver filter</em> +*cupsFilter2: "application/vnd.cups-raster application/vnd.foo 100 rastertofoo" + +<em>*% Plain text filter</em> +*cupsFilter2: "text/plain application/vnd.foo 10 texttofoo" + +<em>*% Pass-through filter for PostScript printers</em> +*cupsFilter2: "application/vnd.cups-postscript application/postscript 0 -" +</pre> + <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3> <p class='summary'>*cupsFlipDuplex: boolean</p> <p>Due to implementation differences between Mac OS X and Ghostscript, -the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use -the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify +the <tt>cupsFlipDuplex</tt> keyword is deprecated. Instead, use +the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> keyword to specify the coordinate system (pixel layout) of the page data on the back side of duplex pages.</p> @@ -1334,7 +1604,7 @@ Ghostscript.</p> <p>Mac OS X drivers that previously used <tt>cupsFlipDuplex</tt> may wish to provide both the old and -new attributes for maximum compatibility, for example:</p> +new keywords for maximum compatibility, for example:</p> <pre class='command'> *cupsBackSide: Rotated @@ -1353,7 +1623,7 @@ Ghostscript can use:</p> <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p> -<p>This attribute defines a mapping from IPP <code>finishings</code> +<p>This keyword defines a mapping from IPP <code>finishings</code> values to PPD options and choices.</p> <p>Examples:</p> @@ -1369,7 +1639,7 @@ values to PPD options and choices.</p> <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p> -<p>This optional attribute maps custom +<p>This optional keyword maps custom <code>printer-state-reasons</code> keywords that are generated by the driver to human readable text. The optional URIs string contains zero or more URIs separated by a newline. Each URI can @@ -1379,11 +1649,7 @@ scheduler's <code>DocumentRoot</code> directory, a full HTTP URL valid URI which directs the user at additional information concerning the condition that is being reported.</p> -<p>Since the reason text is limited to 80 characters by the PPD specification, -longer text strings can be included by URI-encoding the text with the "text" -scheme, for example "text:some%20text". Multiple <code>text</code> URIs are -combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt> -into a single string that can be displayed to the user.</p> +<p>Since the reason text is limited to 80 characters by the PPD specification, longer text strings can be included by URI-encoding the text with the "text" scheme, for example "text:some%20text". Multiple <code>text</code> URIs are combined by the <tt>ppdLocalizeIPPReason</tt> into a single string that can be displayed to the user.</p> <p>Examples:</p> @@ -1409,18 +1675,31 @@ http://www.vendor.com/help" *End </pre> +<h3><span class='info'>CUPS 1.5</span><a name='cupsIPPSupplies'>cupsIPPSupplies</a></h3> + +<p class='summary'>*cupsIPPSupplies: boolean</p> + +<p>This keyword tells the IPP backend whether it should report the current marker-xxx supply attribute values. The default value is <code>True</code>. + +<p>Example:</p> + +<pre class='command'> +<em>*% Do not use IPP marker-xxx attributes to report supply levels</em> +*cupsIPPSupplies: False +</pre> + <h3><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3> <p class='summary'>*cupsLanguages: "locale list"</p> -<p>This attribute describes which language localizations are +<p>This keyword describes which language localizations are included in the PPD. The "locale list" string is a space-delimited list of locale names ("en", "en_US", "fr_CA", etc.)</p> <p>Example:</p> <pre class='command'> -<em>*% Specify Canadian, UK, and US English, and Candian and French French</em> +<em>*% Specify Canadian, UK, and US English, and Canadian and French French</em> *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR" </pre> @@ -1428,14 +1707,14 @@ list of locale names ("en", "en_US", "fr_CA", etc.)</p> <p class='summary'>*cupsManualCopies: boolean</p> -<p>This boolean attribute notifies the RIP filters that the +<p>This boolean keyword notifies the RIP filters that the destination printer does not support copy generation in hardware. The default value is <code>false</code>.</p> <p>Example:</p> <pre class='command'> -<em>*% Tell the RIP filters to generate the copies for us</em> +<em>*% Tell the RIP filters to generate the copies for us</em> *cupsManualCopies: true </pre> @@ -1443,7 +1722,7 @@ hardware. The default value is <code>false</code>.</p> <p class='summary'>*cupsMarkerName/Name Text: ""</p> -<p>This optional attribute maps <code>marker-names</code> strings that are +<p>This optional keyword maps <code>marker-names</code> strings that are generated by the driver to human readable text.</p> <p>Examples:</p> @@ -1457,7 +1736,7 @@ generated by the driver to human readable text.</p> <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p> -<p>This optional attribute provides disclaimer text for the supply level +<p>This optional keyword provides disclaimer text for the supply level information provided by the driver, typically something like "supply levels are approximate".</p> @@ -1471,14 +1750,14 @@ are approximate".</p> <p class='summary'>*cupsModelNumber: number</p> -<p>This integer attribute specifies a printer-specific model +<p>This integer keyword specifies a printer-specific model number. This number can be used by a filter program to adjust the output for a specific model of printer.</p> <p>Example:</p> <pre class='command'> -<em>*% Specify an integer for a driver-specific model number</em> +<em>*% Specify an integer for a driver-specific model number</em> *cupsModelNumber: 1234 </pre> @@ -1486,7 +1765,7 @@ the output for a specific model of printer.</p> <p class='summary'>*cupsPJLCharset: "ISO character set name"</p> -<p>This string attribute specifies the character set that is used +<p>This string keyword specifies the character set that is used for strings in PJL commands. If not specified, US-ASCII is assumed.</p> @@ -1501,7 +1780,7 @@ assumed.</p> <p class='summary'>*cupsPJLDisplay: "what"</p> -<p>This optional attribute specifies which command is used to display the +<p>This optional keyword specifies which command is used to display the job ID, name, and user on the printer's control panel. "What" is either "none" to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg" to use "@PJL RDYMSG DISPLAY". The default is "job".</p> @@ -1520,15 +1799,15 @@ to use "@PJL RDYMSG DISPLAY". The default is "job".</p> <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p> -<p>This string attribute specifies printer-specific "port +<p>This string keyword specifies printer-specific "port monitor" filters that may be used with the printer. The CUPS -scheduler also looks for the <tt>Protocols</tt> attribute to see +scheduler also looks for the <tt>Protocols</tt> keyword to see if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If so, the corresponding port monitor ("bcp" and "tbcp", respectively) is listed in the printer's -<tt>port-monitor-supported</tt> attribute.</p> +<tt>port-monitor-supported</tt> keyword.</p> -<p>The "urischeme" portion of the attribute specifies the URI scheme +<p>The "urischeme" portion of the keyword specifies the URI scheme that this port monitor should be used for. Typically this is used to pre-select a particular port monitor for each type of connection that is supported by the printer. The "port monitor" string can be "none" @@ -1544,7 +1823,7 @@ to disable the port monitor for the given URI scheme.</p> *cupsPortMonitor socket/AppSocket Printing: "tbcp" *cupsPortMonitor usb/USB Printing: "none" -<em>*% Specify a printer-specific port monitor for an Epson USB printer</em> +<em>*% Specify a printer-specific port monitor for an Epson USB printer</em> *cupsPortMonitor usb/USB Status Monitor: "epson-usb" </pre> @@ -1552,8 +1831,8 @@ to disable the port monitor for the given URI scheme.</p> <p class='summary'>*cupsPreFilter: "source/type cost program"</p> -<p>This string attribute provides a pre-filter rule. The pre-filter -program will be inserted in the conversion chain immediately +<p>This string keyword provides a pre-filter rule. The pre-filter +program will be inserted in the conversion chain immediately before the filter that accepts the given MIME type.</p> <p>Examples:</p> @@ -1571,7 +1850,7 @@ before the filter that accepts the given MIME type.</p> <p class='summary'>*cupsPrintQuality keyword/text: "code"</p> -<p>This UI keyword defines standard print qualities that directly map from the IPP "print-quality" job template attribute. Standard keyword values are "Draft", "Normal", and "High" which are mapped from the IPP "print-quality" values 3, 4, and 5 respectively. Each <code>cupsPrintQuality</code> option typically sets output mode and resolution parameters in the page device dictionary, eliminating the need for separate (and sometimes confusing) output mode and resolution options.</p> +<p>This UI keyword defines standard print qualities that directly map from the IPP "print-quality" job template keyword. Standard keyword values are "Draft", "Normal", and "High" which are mapped from the IPP "print-quality" values 3, 4, and 5 respectively. Each <code>cupsPrintQuality</code> option typically sets output mode and resolution parameters in the page device dictionary, eliminating the need for separate (and sometimes confusing) output mode and resolution options.</p> <blockquote><b>Note:</b> @@ -1591,11 +1870,27 @@ before the filter that accepts the given MIME type.</p> *CloseUI: *cupsPrintQuality </pre> +<h3><span class='info'>CUPS 1.5</span><a name='cupsSingleFile'>cupsSingleFile</a></h3> + +<p class='summary'>*cupsSingleFile: Boolean</p> + +<p>This boolean keyword tells the scheduler whether to print multiple files in a job together or singly. The default is "False" which uses a single instance of the backend for all files in the print job. Setting this keyword to "True" will result in separate instances of the backend for each file in the print job.</p> + +<p>Examples:</p> + +<pre class='command'> +<em>*% Send all print data to a single backend</em> +*cupsSingleFile: False + +<em>*% Send each file using a separate backend</em> +*cupsSingleFile: True +</pre> + <h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3> <p class='summary'>*cupsSNMPSupplies: boolean</p> -<p>This attribute tells the standard network backends whether they should query +<p>This keyword tells the standard network backends whether they should query the standard SNMP Printer MIB OIDs for supply levels. The default value is <code>True</code>. @@ -1610,14 +1905,14 @@ the standard SNMP Printer MIB OIDs for supply levels. The default value is <p class='summary'>*cupsVersion: major.minor</p> -<p>This required attribute describes which version of the CUPS +<p>This required keyword describes which version of the CUPS PPD file extensions was used. Currently it must be the string "1.0", "1.1", "1.2", or "1.3".</p> <p>Example:</p> <pre class='command'> -<em>*% Specify a CUPS 1.2 driver</em> +<em>*% Specify a CUPS 1.2 driver</em> *cupsVersion: "1.2" </pre> @@ -1628,8 +1923,8 @@ PPD file extensions was used. Currently it must be the string <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p> -<p>This attribute defines additional option panes that are displayed in the -print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE" +<p>This keyword defines additional option panes that are displayed in the +print dialog. Each keyword adds one or more option panes. See the "OutputBinsPDE" example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple Technical Q&A QA1352</a> for information on writing your own print dialog plug-ins.</p> @@ -1654,7 +1949,7 @@ in order to be usable with all applications.</p> <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p> -<p>This boolean attribute notifies the RIP filters that the +<p>This boolean keyword notifies the RIP filters that the destination printer requires the top and bottom margins of the <tt>ImageableArea</tt> to be swapped for the back page. The default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt> @@ -1725,20 +2020,20 @@ and the <tt>Tumble</tt> page attribute.</p> <em>*% Rotate the back side images</em> *cupsBackSide: Rotated -<em>*% Don't swap the top and bottom margins for the back side</em> +<em>*% Don't swap the top and bottom margins for the back side</em> *APDuplexRequiresFlippedMargin: false </pre> <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> -attribute.</p> +keyword.</p> <h3><a name='APHelpBook'>APHelpBook</a></h3> <p class='summary'>*APHelpBook: "bundle URL"</p> -<p>This string attribute specifies the Apple help book bundle to use when +<p>This string keyword specifies the Apple help book bundle to use when looking up IPP reason codes for this printer driver. The -<a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps +<a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword maps "help" URIs to this file.</p> <p>Example:</p> @@ -1751,7 +2046,7 @@ looking up IPP reason codes for this printer driver. The <p class='summary'>*APICADriver: boolean</p> -<p>This attribute specifies whether the device has a matching Image Capture +<p>This keyword specifies whether the device has a matching Image Capture Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p> <p>Examples:</p> @@ -1765,7 +2060,7 @@ Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p> <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p> -<p>This attribute defines the location of a printer icon file to use when +<p>This keyword defines the location of a printer icon file to use when displaying the printer. The file must be in the Apple icon format.</p> <p>Examples:</p> @@ -1779,7 +2074,7 @@ displaying the printer. The file must be in the Apple icon format.</p> <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p> -<p>This attribute defines an program that checks the ink/toner/marker levels +<p>This keyword defines an program that checks the ink/toner/marker levels on a printer, returning an XML document with those levels. See the "InkTool" example and <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple @@ -1796,7 +2091,7 @@ Technical Note TN2144</a> for more information.</p> <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p> -<p>This attribute defines presets for multiple options that show up +<p>This keyword defines presets for multiple options that show up in the print dialog of applications (such as iPhoto) that set the job style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or more pairs of PPD options and choices as well as providing key/value data for @@ -1866,7 +2161,7 @@ choice (*MainKeyword OptionKeyword) or a preset identifier and value <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p> -<p>This attribute defines a GUI application that can be used to do printer +<p>This keyword defines a GUI application that can be used to do printer maintenance functions such as cleaning the print head(s). See ... for more information.</p> @@ -1881,7 +2176,7 @@ information.</p> <p class='summary'>*APScannerOnly: boolean</p> -<p>This attribute specifies whether the device has scanning but no printing +<p>This keyword specifies whether the device has scanning but no printing capabilities. The default is <tt>False</tt>.</p> <p>Examples:</p> @@ -1895,7 +2190,7 @@ capabilities. The default is <tt>False</tt>.</p> <p class='summary'>*APScanAppBundleID: "bundle ID"</p> -<p>This attribute defines the application to use when scanning pages from +<p>This keyword defines the application to use when scanning pages from the device.</p> <p>Examples:</p> @@ -1908,6 +2203,15 @@ the device.</p> <h2 class='title'><a name='HISTORY'>Change History</a></h2> +<h3>Changes in CUPS 1.5</h3> + +<ul> + + <li>Changes all instances of PPD attributes to PPD keywords, to be consistent with the parent specification from Adobe.</li> + +</ul> + + <h3>Changes in CUPS 1.4.5</h3> <ul> @@ -1924,32 +2228,32 @@ the device.</p> <ul> <li>Added <a href='#APICADriver'><tt>APICADriver</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsCommands'><tt>cupsCommands</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsMarkerName'><tt>cupsMarkerName</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsMarkerNotice'><tt>cupsMarkerNotice</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsSNMPSupplies'><tt>cupsSNMPSupplies</tt></a> - attribute.</li> + keyword.</li> <li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a> - attributes.</li> + keywords.</li> <li>Added <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a>, <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a>, <a href='#cupsMinSize'><tt>cupsMinSize</tt></a>, and - <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> attributes.</li> + <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> keywords.</li> </ul> @@ -1958,11 +2262,11 @@ the device.</p> <ul> - <li>Added missing Mac OS X <tt>AP</tt> attributes.</li> + <li>Added missing Mac OS X <tt>AP</tt> keywords.</li> <li>Added section on auto-configuration including the <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt> - attributes.</li> + keywords.</li> <li>Minor reorganization.</li> @@ -1981,7 +2285,7 @@ the device.</p> <li>Added <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a>, <a href='#cupsIPPFinishings'><tt>cupsIPPFinishings</tt></a>, and - <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> attributes.</li> + <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> keywords.</li> <li>Added discussion of custom option code, sample <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li> @@ -2001,24 +2305,24 @@ the device.</p> <ul> - <li>Added globalization support attributes</li> + <li>Added globalization support keywords</li> <li>Added custom option values support</li> - <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> attribute</li> + <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> keyword</li> <li>Added <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> - attribute</li> + keyword</li> - <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> attribute</li> + <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> keyword</li> - <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute</li> + <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword</li> - <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> attribute</li> + <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> keyword</li> - <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> attribute</li> + <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> keyword</li> - <li>Removed <tt>cupsProtocol</tt> attribute</li> + <li>Removed <tt>cupsProtocol</tt> keyword</li> </ul> @@ -2026,11 +2330,11 @@ the device.</p> <ul> - <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> attribute</li> + <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> keyword</li> - <li>Added <tt>cupsProtocol</tt> attribute</li> + <li>Added <tt>cupsProtocol</tt> keyword</li> </ul> - +</div> </body> </html> diff --git a/doc/help/whatsnew.html b/doc/help/whatsnew.html index 9ffe6aed..856f30a9 100644 --- a/doc/help/whatsnew.html +++ b/doc/help/whatsnew.html @@ -1,204 +1,61 @@ <HTML> <!-- SECTION: Getting Started --> <HEAD> - <TITLE>What's New in CUPS 1.4</TITLE> + <TITLE>What's New in CUPS 1.5</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css"> </HEAD> <BODY> -<H1 CLASS="title">What's New in CUPS 1.4</H1> +<H1 CLASS="title">What's New in CUPS 1.5</H1> -<P>CUPS 1.4 adds over 67 changes and new features to CUPS 1.3.x. This page provides a high-level outline of these changes. If you have never used CUPS before, read the <A HREF="overview.html">"Overview of CUPS"</A> document instead.</P> +<P>CUPS 1.5 many changes and new features to CUPS 1.4.x. This page provides a high-level outline of these changes. If you have never used CUPS before, read the <A HREF="overview.html">"Overview of CUPS"</A> document instead.</P> <H2 CLASS="title"><A NAME="COMMANDS">Commands</A></H2> <OL START="1"> - <LI><EM>accept and reject;</EM> the accept and reject commands have been officially renamed to cupsaccept and cupsreject. The old names are still supported via symlinks.</LI> + <LI><EM>User defaults;</EM> Starting in CUPS 1.2, user defaults were stored in the ~/.cups directory, and the old ~/.cupsrc and ~/.lpoptions files were deprecated. Support for ~/.cupsrc and ~/.lpoptions have been removed in CUPS 1.5.</LI> - <LI><EM>cupsdisable and cupsenable;</EM> the cupsdisable command now supports a --hold option to stop printing after the current job and the cupsenable command now supports a --release option to release pending jobs for printing.</LI> - - <LI><EM>cupsfilter;</EM> the cupsfilter program now supports filtering of already-queued print job files and can also run printer-specific filters specified in the PPD file.</LI> - - <LI><EM>cupstestdsc;</EM> the cupstestdsc utility has been improved to better detect problems with PostScript print files.</LI> - - <LI><EM>cupstestppd;</EM> the cupstestppd utility has been improved to test new PPD keywords and better detect impossible contraints.</LI> - - <LI><EM>lpadmin;</EM> the lpadmin command now supports options to hold and release new jobs on a printer or all printers.</LI> - - <LI><EM>lpoptions;</EM> the lpoptions command now describes custom options and their parameters.</LI> - - <LI><EM>lppasswd;</EM> the lppasswd program is no longer installed setuid by default.</LI> - - <LI><EM>lpstat;</EM> the lpstat command now supports a -H option to show the current default server and no longer slows down when a printer is specified.</LI> + <LI><EM>IPP test tool;</EM> The <code>ipptool</code> IPP test tool is now a first-class user program.</LI> + <LI><EM>lpadmin;</EM> The <code>lpadmin</code> command now supports setting the cupsIPPSupplies and cupsSNMPSupplies keywords in PPDs and deleting options.</LI> </OL> - -<H2 CLASS="title"><A NAME="WEBIF">Web Interface</A></H2> - -<OL START="10"> - - <LI><EM>Look-n-feel;</EM> the web interface has been given a new look.</LI> - - <LI><EM>PHP support;</EM> the "php-cgi" program is used, when available, to process PHP pages in the CUPS web interface.</LI> - - <LI><EM>Printer configuration;</EM> improvements have been made to the add and modify printer pages.</LI> - - <LI><EM>Printer options;</EM> the Set Default Options page now provides a "query" button that queries the default and installed options from the printer.</LI> - - <LI><EM>Printer sharing;</EM> the "share printer" and "unshare printer" buttons are now only shown when printer sharing is enabled in the scheduler.</LI> - - <LI><EM>Security;</EM> the web interface has been updated to support authentication for printing of test pages and RSS subscription operations.</LI> - - <LI><EM>Server settings;</EM> the Administration page now provides access to common "advanced" server settings.</LI> - -</OL> - - -<H2 CLASS="title"><A NAME="NETWORKING">Networking</A></H2> - -<OL START="17"> - - <LI><EM>Bonjour (DNS-SD) printing support;</EM> a new mdns backend provides Bonjour-based printer discovery and the ipp, lpd, and socket backends now support Bonjour address resolution.</LI> - - <LI><EM>Bonjour (DNS-SD) perforance tuning;</EM> the scheduler now only uses a single file descriptor for printer sharing. It previously used one per printer.</LI> - - <LI><EM>Bonjour (DNS-SD) web interface registry;</EM> when remote access is enabled, the scheduler can register the web interface for easier access.</LI> - - <LI><EM>LPD client support;</EM> the cups-lpd mini-daemon now provides the document-name for print jobs and supports specification of a CUPS server.</LI> - - <LI><EM>PWG Port Monitor MIB;</EM> the snmp backend now supports the PWG Port Monitor MIB to better choose the device URI to use.</LI> - - <LI><EM>SNMP-based monitoring;</EM> the ipp, lpd, and socket backends now report supply levels and printer status using SNMP queries.</LI> - -</OL> - - -<H2 CLASS="title"><A NAME="IPP">IPP Support</A></H2> - -<OL START="23"> - - <LI><EM>IPP/2.x support;</EM> CUPS now conforms to the draft IPP/2.0 and IPP/2.1 specifications.</LI> - - <LI><EM>CUPS-Add-Modify-Printer operation;</EM> the scheduler now supports setting the printer-state-reasons attribute using this operation.</LI> - - <LI><EM>CUPS-Get-Document operation;</EM> the scheduler now supports a "get document" operation to download files from a print job.</LI> - - <LI><EM>Device location;</EM> the scheduler and backend discovery interface now support a device-location attribute.</LI> - - <LI><EM>Hold-New-Jobs and Release-Held-New-Jobs operations;</EM> the scheduler now supports the Hold-New-Jobs and Release-Held-New-Jobs operations.</LI> - -</OL> - - <H2 CLASS="title"><A NAME="SCHEDULER">Scheduler</A></H2> -<OL START="28"> +<OL START="4"> - <LI><EM>Access control;</EM> the scheduler now supports multiple addresses in Allow and Deny lines. It also now returns a HTTP 403 (forbidden) status when a user authenticates successfully but is not allowed to perform an operation.</LI> - - <LI><EM>Access logging;</EM> the scheduler now supports an AccessLogLevel directive to control what is logged in the access_log file.</LI> - - <LI><EM>Configuration files;</EM> the default cupsd.conf file now provides an "authenticated" policy that can be used to require a username and password to print or cancel a job.</LI> - - <LI><EM>Default LogLevel;</EM> the default LogLevel is now "warn" instead of "info".</LI> - - <LI><EM>Automatic debug logging;</EM> the scheduler now records up to the last N (default 200) debug messages for failed print jobs.</LI> - - <LI><EM>Default paper size;</EM> the scheduler now supports a DefaultPaperSize directive to override the default paper size defined by the locale or libpaper configuration.</LI> - - <LI><EM>Encryption support;</EM> the scheduler now supports a SSLOptions directive to optionally support Windows clients in "FIPS" mode. It also now loads both the server and CA certificates (if present) from the ServerCertificate file.</LI> - - <LI><EM>Error logging;</EM> the scheduler now logs unsuccessful operations as errors in the error_log file.</LI> - - <LI><EM>Error policies;</EM> the scheduler now supports a retry-current-job error policy that retries the current job immediately.</LI> - - <LI><EM>Fatal error handling;</EM> the scheduler now supports a FatalErrors directive to control which startup errors should be considered fatal.</LI> - - <LI><EM>Filter command-line;</EM> the scheduer now passes the job-originating-host-name attribute as a CUPS option to filters and backends.</LI> - - <LI><EM>Filter environment;</EM> the scheduler now includes CUPS_JOBTYPE, PRINTER_INFO, and PRINTER_LOCATION variables in the environment passed to filters and backends.</LI> - - <LI><EM>Job progress;</EM> the scheduler now supports a job-media-progress attribute to track the printing progress of each page.</LI> - - <LI><EM>MIME database;</EM> MIME types now support a priority attribute to override the default (alphabetical) rules of precedence.</LI> - - <LI><EM>Page logging;</EM> the scheduler now supports a <code>PageLogFormat</code> directive to control the format of the page_log file.</LI> - - <LI><EM>PAM support;</EM> the scheduler now sets more PAM attributes to better support third-party authentication schemes.</LI> - - <LI><EM>PDF job ticket support;</EM> the scheduler now supports cupsJobTicket comments at the beginning of PDF print jobs.</LI> - - <LI><EM>Performance tuning;</EM> the scheduler now coalesces configuration and state file changes to reduce the amount of disk activity and caches printer attributes to further reduce startup time.</LI> - - <LI><EM>Printcap support;</EM> the scheduler no longer clears the printcap file when shutting down, and can now create XML "plist" printcap files as well.</LI> - - <LI><EM>RSS subscriptions;</EM> the scheduler now starts the notifier for RSS subscriptions after creation so the feed is available immediately.</LI> - - <LI><EM>Sandbox support;</EM> the scheduler now runs child processes using restrictive policies on Mac OS X for improved security and job isolation.</LI> - - <LI><EM>Test option;</EM> the scheduler now supports a test mode via the "-t" option.</LI> - -</OL> - - -<H2 CLASS="title"><A NAME="DRIVERS">Printer Drivers</A></H2> - -<OL START="50"> - - <LI><EM>Device discovery;</EM> the cups-deviced helper now runs backends in parallel for faster discovery and streams the results of discovery as the backends provide them.</LI> - - <LI><EM>Driver development kit;</EM> the CUPS DDK is now a standard part of CUPS.</LI> - - <LI><EM>Driver information file support;</EM> the cups-driverd helper program now directly supports PPD compiler driver information files.</LI> - - <LI><EM>Dynamic PPD support;</EM> drivers can now set PPD keywords dynamically using <code>PPD:</code> messages.</LI> - - <LI><EM>Generic PostScript command filter;</EM> a new CUPS command file filter for PostScript printers provides auto-configuration, self-test page, and status and supply level reporting functions.</LI> - - <LI><EM>New printer drivers;</EM> new generic PostScript and PCL drivers provide improved support for laser printers, the CUPS DDK drivers offer support for many HP DesignJet printers, and new label drivers offer support for Seiko and Tharo label printers.</LI> - - <LI><EM>PJL support;</EM> the cupsPJLDisplay PPD attribute controls the PJL commands used to display the current user and job on the printer.</LI> - - <LI><EM>PPD compiler improvements;</EM> the PPD compiler now supports Mac OS X .strings files, OID query strings, conditional directives, long file names, and a test mode. It also fixes many other bugs from the CUPS DDK 1.2.3 release.</LI> - - <LI><EM>USB printer support;</EM> the usb backend now uses libusb when available to allow it to better work with third-party scanning and printing solutions.</LI> + <LI><EM>Filter security;</EM> Filters and backends must now have group write permissions disabled.</LI> </OL> <H2 CLASS="title"><A NAME="FILTERS">Print Filters</A></H2> -<OL START="59"> +<OL START="5"> - <LI><EM>Banner filter;</EM> the bundled banner ("job-sheets") pages are now generated using a new banner filter provides easier customization and better support for UTF-8 text.</LI> + <LI><EM>HP-GL/2 filter;</EM> The HP-GL/2 filter is no longer provided with CUPS.</LI> - <LI><EM>Image filters;</EM> the standard image filters now support image files larger than 2GB.</LI> + <LI><EM>PDF filter;</EM> The PDF filter now supports new Poppler and Ghostscript options.</LI> - <LI><EM>PDF filter;</EM> the pdftops filter has been replaced with a wrapper program that runs the Xpdf, poppler, or Ghostscript PDF to PostScript utilities.</LI> + <LI><EM>PWG Raster driver;</EM> Added a new PWG Raster printer driver filter.</LI> + + <LI><EM>SCSI backend;</EM> The SCSI backend is no longer provided with CUPS.</LI> </OL> <H2 CLASS="title"><A NAME="CUPSAPI">CUPS API</A></H2> -<OL START="62"> - - <LI><EM>Backend API;</EM> a new cupsBackendReport function is provided to report a device from a backend and handles any needed quoting of the make-and-model, info, device-id, and location strings.</LI> - - <LI><EM>Device discovery;</EM> the new <code>cupsGetDevices</code> function streams discovered devices to an application-provided callback function.</LI> +<OL START="9"> - <LI><EM>IPP API;</EM> the IPP read and write functions no longer use a large stack-based buffer when reading and writing IPP attributes.</LI> + <LI><EM>CUPS headers;</EM> Changes to the main CUPS header may require code changes to applications and toolkits. Users of PPD functions must now include the <cups/ppd.h> header file explicitly since the <cups/cups.h> header no longer does so.</LI> - <LI><EM>PPD support;</EM> several new functions are provided: cupsGetPPD3, cupsResolveConflicts, ppdInstallableConflict, ppdLocalizeAttr, ppdLocalizeMarkerName and ppdPageSizeLimits.</LI> + <LI><EM>HTTP support:</EM> Applications can now set a per-connection timeout interval and callback for HTTP operations as well as query and set SSL/TLS X.509 certificates.</LI> - <LI><EM>Side-Channel API;</EM> new cupsSideChannelSNMPGet and cupsSideChannelSNMPWalk functions allow printer drivers to do SNMP queries via the standard network backends.</LI> - - <LI><EM>Streaming API;</EM> a new streaming request API provides asynchronous job creation and request submission.</LI> + <LI><EM>Raster support;</EM> The CUPS raster functions now support the creation of PWG Raster files and streams, and a new callback-based context function allows reading and writing from objects other than file descriptors.</LI> </OL> - </BODY> </HTML> diff --git a/doc/images/raster-organization.svg b/doc/images/raster-organization.svg index 8f611f26..442032f2 100644 --- a/doc/images/raster-organization.svg +++ b/doc/images/raster-organization.svg @@ -187,192 +187,3 @@ </g> </g> </svg> -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="744.09448819" - height="1052.3622047" - id="svg2" - version="1.1" - inkscape:version="0.48.0 r9654" - sodipodi:docname="raster-organization.svg" - inkscape:export-filename="/Users/mike/c/cups-trunk/doc/images/raster-organization.png" - inkscape:export-xdpi="100.04211" - inkscape:export-ydpi="100.04211"> - <defs - id="defs4" /> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="0.80227655" - inkscape:cx="414.35236" - inkscape:cy="794.80623" - inkscape:document-units="px" - inkscape:current-layer="g4208" - showgrid="true" - inkscape:window-width="1089" - inkscape:window-height="815" - inkscape:window-x="308" - inkscape:window-y="0" - inkscape:window-maximized="0"> - <inkscape:grid - type="xygrid" - id="grid3979" /> - </sodipodi:namedview> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1"> - <rect - style="fill:none;stroke:#000000;stroke-width:0.98624134px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - id="rect2985" - width="359.01376" - height="39.01376" - x="180.49312" - y="52.855301" /> - <flowRoot - xml:space="preserve" - style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" - id="flowRoot4112" - transform="translate(70.681641,5.4232931)"><flowRegion - id="flowRegion4114"><use - x="0" - y="0" - xlink:href="#rect2985" - id="use4116" - width="744.09448" - height="1052.3622" /></flowRegion><flowPara - id="flowPara4118">Synchronization Word</flowPara></flowRoot> <g - id="g4196"> - <rect - style="fill:none;stroke:#000000;stroke-width:1.71552336px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - id="rect3981" - width="358.28448" - height="118.28448" - x="180.85776" - y="133.21994" /> - <rect - y="253.5766" - x="181.21442" - height="237.57117" - width="357.57117" - id="rect3983" - style="fill:none;stroke:#000000;stroke-width:2.42882872px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> - <flowRoot - xml:space="preserve" - style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" - id="flowRoot4120" - transform="translate(106.53711,125.42329)"><flowRegion - id="flowRegion4122"><use - x="0" - y="0" - xlink:href="#rect2985" - id="use4124" - width="744.09448" - height="1052.3622" /></flowRegion><flowPara - id="flowPara4126">Page Header 1</flowPara></flowRoot> <flowRoot - transform="translate(106.53711,295.42329)" - id="flowRoot4128" - style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" - xml:space="preserve"><flowRegion - id="flowRegion4130"><use - height="1052.3622" - width="744.09448" - id="use4132" - xlink:href="#rect2985" - y="0" - x="0" /></flowRegion><flowPara - id="flowPara4134">Page Bitmap 1</flowPara></flowRoot> </g> - <g - id="g4208" - transform="translate(4.1127203e-6,510)"> - <rect - y="133.21994" - x="180.85776" - height="118.28448" - width="358.28448" - id="rect4210" - style="fill:none;stroke:#000000;stroke-width:1.71552336px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> - <rect - style="fill:none;stroke:#000000;stroke-width:2.42882872px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" - id="rect4212" - width="357.57117" - height="237.57117" - x="181.21442" - y="253.5766" /> - <flowRoot - transform="translate(106.53711,125.42329)" - id="flowRoot4214" - style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" - xml:space="preserve"><flowRegion - id="flowRegion4216"><use - height="1052.3622" - width="744.09448" - id="use4218" - xlink:href="#rect2985" - y="0" - x="0" /></flowRegion><flowPara - id="flowPara4220">Page Header N</flowPara></flowRoot> <flowRoot - xml:space="preserve" - style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" - id="flowRoot4222" - transform="translate(106.53711,295.42329)"><flowRegion - id="flowRegion4224"><use - x="0" - y="0" - xlink:href="#rect2985" - id="use4226" - width="744.09448" - height="1052.3622" /></flowRegion><flowPara - id="flowPara4228">Page Bitmap N</flowPara></flowRoot> <path - style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:1,2;stroke-dashoffset:0" - d="m 180,92.362183 0,39.999997" - id="path4230" - inkscape:connector-curvature="0" - transform="translate(-4.1127203e-6,-510)" /> - <path - inkscape:connector-curvature="0" - id="path4232" - d="m 540,-417.63782 0,40" - style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1, 2;stroke-dashoffset:0" /> - <path - style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:1,2;stroke-dashoffset:0" - d="m 180,492.36218 0,60 -20,10 40,10 -20,10 0,60" - id="path4236" - inkscape:connector-curvature="0" - transform="translate(-4.1127203e-6,-510)" - sodipodi:nodetypes="cccccc" /> - <path - sodipodi:nodetypes="cccccc" - inkscape:connector-curvature="0" - id="path4238" - d="m 540,-17.637817 0,60 -20,10 40,10 -20,10 0,59.999997" - style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1, 2;stroke-dashoffset:0" /> - </g> - </g> -</svg> |
