diff options
| author | Didier Raboud <odyx@debian.org> | 2012-10-25 21:07:57 +0200 |
|---|---|---|
| committer | Didier Raboud <odyx@debian.org> | 2012-10-25 21:07:57 +0200 |
| commit | 81ab83f382660bc7980ae954725c4ebf28764b03 (patch) | |
| tree | 523268f698a63a8fd44f3491d94d140266b2403b /doc/help | |
| parent | a75966e33dbc3e3e096338fd332f515cb313b58a (diff) | |
| download | cups-81ab83f382660bc7980ae954725c4ebf28764b03.tar.gz | |
Imported Upstream version 1.6.0upstream/1.6.0
Diffstat (limited to 'doc/help')
31 files changed, 3569 insertions, 2242 deletions
diff --git a/doc/help/api-array.html b/doc/help/api-array.html index 7f22251b..7211fd8a 100644 --- a/doc/help/api-array.html +++ b/doc/help/api-array.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-array.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-array.html 10424 2012-04-23 17:26:57Z mike $" Array API header for CUPS. @@ -413,7 +413,7 @@ div.contents ul.subcontents li { </ul></li> </ul> <!-- - "$Id: api-array.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-array.html 10424 2012-04-23 17:26:57Z mike $" Array API introduction for CUPS. @@ -609,7 +609,7 @@ for (s = (char *)<a href='#cupsArrayFirst'>cupsArrayFirst</a>(array); s != NULL; puts(s); </pre> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayAdd">cupsArrayAdd</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayAdd">cupsArrayAdd</a></h3> <p class="description">Add an element to the array.</p> <p class="code"> int cupsArrayAdd (<br> @@ -631,7 +631,7 @@ appended at the end of the run of identical elements. For unsorted arrays, the element is appended to the end of the array. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayClear">cupsArrayClear</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayClear">cupsArrayClear</a></h3> <p class="description">Clear the array.</p> <p class="code"> void cupsArrayClear (<br> @@ -648,7 +648,7 @@ The caller is responsible for freeing the memory used by the elements themselves. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayCount">cupsArrayCount</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayCount">cupsArrayCount</a></h3> <p class="description">Get the number of elements in the array.</p> <p class="code"> int cupsArrayCount (<br> @@ -661,7 +661,7 @@ int cupsArrayCount (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of elements</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayCurrent">cupsArrayCurrent</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayCurrent">cupsArrayCurrent</a></h3> <p class="description">Return the current element in the array.</p> <p class="code"> void *cupsArrayCurrent (<br> @@ -679,7 +679,7 @@ void *cupsArrayCurrent (<br> <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayDelete">cupsArrayDelete</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayDelete">cupsArrayDelete</a></h3> <p class="description">Free all memory used by the array.</p> <p class="code"> void cupsArrayDelete (<br> @@ -695,7 +695,7 @@ void cupsArrayDelete (<br> elements themselves. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayDup">cupsArrayDup</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayDup">cupsArrayDup</a></h3> <p class="description">Duplicate the array.</p> <p class="code"> <a href="#cups_array_t">cups_array_t</a> *cupsArrayDup (<br> @@ -708,7 +708,7 @@ elements themselves. </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Duplicate array</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayFind">cupsArrayFind</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayFind">cupsArrayFind</a></h3> <p class="description">Find an element in the array.</p> <p class="code"> void *cupsArrayFind (<br> @@ -724,7 +724,7 @@ void *cupsArrayFind (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Element found or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayFirst">cupsArrayFirst</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayFirst">cupsArrayFirst</a></h3> <p class="description">Get the first element in the array.</p> <p class="code"> void *cupsArrayFirst (<br> @@ -737,7 +737,7 @@ void *cupsArrayFirst (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">First element or <code>NULL</code> if the array is empty</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3> <p class="description">Get the index of the current element.</p> <p class="code"> int cupsArrayGetIndex (<br> @@ -755,7 +755,7 @@ int cupsArrayGetIndex (<br> <a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3> <p class="description">Get the index of the last inserted element.</p> <p class="code"> int cupsArrayGetInsert (<br> @@ -768,7 +768,7 @@ int cupsArrayGetInsert (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Index of the last inserted element, starting at 0</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayIndex">cupsArrayIndex</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayIndex">cupsArrayIndex</a></h3> <p class="description">Get the N-th element in the array.</p> <p class="code"> void *cupsArrayIndex (<br> @@ -784,7 +784,7 @@ void *cupsArrayIndex (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">N-th element or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayInsert">cupsArrayInsert</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayInsert">cupsArrayInsert</a></h3> <p class="description">Insert an element in the array.</p> <p class="code"> int cupsArrayInsert (<br> @@ -806,7 +806,7 @@ inserted at the beginning of the run of identical elements. For unsorted arrays, the element is inserted at the beginning of the array. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayLast">cupsArrayLast</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayLast">cupsArrayLast</a></h3> <p class="description">Get the last element in the array.</p> <p class="code"> void *cupsArrayLast (<br> @@ -819,7 +819,7 @@ void *cupsArrayLast (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Last element or <code>NULL</code> if the array is empty</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayNew">cupsArrayNew</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayNew">cupsArrayNew</a></h3> <p class="description">Create a new array.</p> <p class="code"> <a href="#cups_array_t">cups_array_t</a> *cupsArrayNew (<br> @@ -842,7 +842,7 @@ data pointer argument can safely be omitted when not required so functions like <code>strcmp</code> can be used for sorted string arrays. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsArrayNew2">cupsArrayNew2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsArrayNew2">cupsArrayNew2</a></h3> <p class="description">Create a new array with hash.</p> <p class="code"> <a href="#cups_array_t">cups_array_t</a> *cupsArrayNew2 (<br> @@ -874,7 +874,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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> @@ -918,7 +918,7 @@ The free function ("cf") is used to automatically free/release element 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> +<h3 class="function"><span class="info"> CUPS 1.2/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"> void *cupsArrayNext (<br> @@ -939,7 +939,7 @@ The next element is undefined until you call <a href="#cupsArrayFind"><code>cups to set the current element. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayPrev">cupsArrayPrev</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayPrev">cupsArrayPrev</a></h3> <p class="description">Get the previous element in the array.</p> <p class="code"> void *cupsArrayPrev (<br> @@ -960,7 +960,7 @@ The previous element is undefined until you call <a href="#cupsArrayFind"><code> to set the current element. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayRemove">cupsArrayRemove</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayRemove">cupsArrayRemove</a></h3> <p class="description">Remove an element from the array.</p> <p class="code"> int cupsArrayRemove (<br> @@ -984,7 +984,7 @@ The caller is responsible for freeing the memory used by the removed element. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayRestore">cupsArrayRestore</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayRestore">cupsArrayRestore</a></h3> <p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p> <p class="code"> void *cupsArrayRestore (<br> @@ -997,7 +997,7 @@ void *cupsArrayRestore (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New current element</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArraySave">cupsArraySave</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArraySave">cupsArraySave</a></h3> <p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p> <p class="code"> int cupsArraySave (<br> @@ -1018,7 +1018,7 @@ to set the current element.<br> The save/restore stack is guaranteed to be at least 32 elements deep. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsArrayUserData">cupsArrayUserData</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsArrayUserData">cupsArrayUserData</a></h3> <p class="description">Return the user data for an array.</p> <p class="code"> void *cupsArrayUserData (<br> diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html index 2dd40830..2d6c7882 100644 --- a/doc/help/api-cups.html +++ b/doc/help/api-cups.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-cups.html 10507 2012-05-23 22:39:50Z mike $" CUPS API header for CUPS. @@ -400,8 +400,13 @@ div.contents ul.subcontents 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="#cupsConnectDest" title="Connect to the server for a destination.">cupsConnectDest</a></li> + <li><a href="#cupsConnectDestBlock" title="Connect to the server for a destination.">cupsConnectDestBlock</a></li> + <li><a href="#cupsCopyDest" title="Callback block">cupsCopyDest</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="#cupsEnumDests" title="Enumerate available destinations with a callback function.">cupsEnumDests</a></li> + <li><a href="#cupsEnumDestsBlock" title="Enumerate available destinations with a block.">cupsEnumDestsBlock</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> @@ -463,31 +468,45 @@ connections.">cupsSetCredentials</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_client_cert_cb_t" title="Client credentials callback +">cups_client_cert_cb_t</a></li> + <li><a href="#cups_dest_block_t" title="Destination enumeration block +">cups_dest_block_t</a></li> + <li><a href="#cups_dest_cb_t" title="Destination enumeration callback +">cups_dest_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_device_cb_t" title="Device callback +">cups_device_cb_t</a></li> + <li><a href="#cups_dinfo_t" title="Destination capability and status +information ">cups_dinfo_t</a></li> <li><a href="#cups_job_t" title="Job">cups_job_t</a></li> <li><a href="#cups_option_t" title="Printer Options">cups_option_t</a></li> - <li><a href="#cups_password_cb2_t" title="New password callback ">cups_password_cb2_t</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> + <li><a href="#cups_server_cert_cb_t" title="Server credentials callback +">cups_server_cert_cb_t</a></li> + <li><a href="#cups_size_t" title="Media Size ">cups_size_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> + <li><a href="#cups_size_s" title="Media Size ">cups_size_s</a></li> + <li><a href="#pollfd" title="User data (unused)">pollfd</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> + <li><a href="#cups_ptype_e" title="Printer type/capability bit +constants">cups_ptype_e</a></li> </ul></li> </ul> <!-- - "$Id: api-cups.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-cups.html 10507 2012-05-23 22:39:50Z mike $" API introduction for CUPS. @@ -1004,7 +1023,7 @@ int cupsAddOption (<br> <h4 class="discussion">Discussion</h4> <p class="discussion">New option arrays can be initialized simply by passing 0 for the "num_options" parameter.</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsAdminCreateWindowsPPD">cupsAdminCreateWindowsPPD</a></h3> <p class="description">Create the Windows PPD file for a printer.</p> <p class="code"> char *cupsAdminCreateWindowsPPD (<br> @@ -1026,7 +1045,7 @@ char *cupsAdminCreateWindowsPPD (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">PPD file or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsAdminExportSamba">cupsAdminExportSamba</a></h3> <p class="description">Export a printer to Samba.</p> <p class="code"> int cupsAdminExportSamba (<br> @@ -1054,7 +1073,7 @@ int cupsAdminExportSamba (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 on success, 0 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsAdminGetServerSettings">cupsAdminGetServerSettings</a></h3> <p class="description">Get settings from the server.</p> <p class="code"> int cupsAdminGetServerSettings (<br> @@ -1078,7 +1097,7 @@ int cupsAdminGetServerSettings (<br> you are done with them. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsAdminSetServerSettings">cupsAdminSetServerSettings</a></h3> <p class="description">Set settings on the server.</p> <p class="code"> int cupsAdminSetServerSettings (<br> @@ -1119,7 +1138,7 @@ to cancel the current job on the named destination.<br> <br> Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cupsLastErrorString"><code>cupsLastErrorString</code></a> functions to get the cause of any failure.</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsCancelJob2">cupsCancelJob2</a></h3> <p class="description">Cancel or purge a print job.</p> <p class="code"> ipp_status_t cupsCancelJob2 (<br> @@ -1152,7 +1171,109 @@ Use the <a href="#cupsLastError"><code>cupsLastError</code></a> and <a href="#cu the cause of any failure. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDest">cupsConnectDest</a></h3> +<p class="description">Connect to the server for a destination.</p> +<p class="code"> +http_t *cupsConnectDest (<br> + <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> + unsigned flags,<br> + int msec,<br> + int *cancel,<br> + char *resource,<br> + size_t resourcesize,<br> + <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> +<dd class="description">Destination</dd> +<dt>flags</dt> +<dd class="description">Connection flags</dd> +<dt>msec</dt> +<dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> +<dd class="description">Pointer to "cancel" variable</dd> +<dt>resource</dt> +<dd class="description">Resource buffer</dd> +<dt>resourcesize</dt> +<dd class="description">Size of resource buffer</dd> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data pointer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Connection to server or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Connect to the destination, returning a new http_t connection object and +optionally the resource path to use for the destination. These calls will +block until a connection is made, the timeout expires, the integer pointed +to by "cancel" is non-zero, or the callback function (or block) returns 0, +The caller is responsible for calling httpClose() on the returned object. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsConnectDestBlock">cupsConnectDestBlock</a></h3> +<p class="description">Connect to the server for a destination.</p> +<p class="code"> +http_t *cupsConnectDestBlock (<br> + <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> + unsigned flags,<br> + int msec,<br> + int *cancel,<br> + char *resource,<br> + size_t resourcesize,<br> + <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> +<dd class="description">Destination</dd> +<dt>flags</dt> +<dd class="description">Connection flags</dd> +<dt>msec</dt> +<dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> +<dd class="description">Pointer to "cancel" variable</dd> +<dt>resource</dt> +<dd class="description">Resource buffer</dd> +<dt>resourcesize</dt> +<dd class="description">Size of resource buffer</dd> +<dt>block</dt> +<dd class="description">Callback block</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Connection to server or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Connect to the destination, returning a new http_t connection object and +optionally the resource path to use for the destination. These calls will +block until a connection is made, the timeout expires, the integer pointed +to by "cancel" is non-zero, or the callback function (or block) returns 0, +The caller is responsible for calling httpClose() on the returned object. + +</p> +<h3 class="function"><a name="cupsCopyDest">cupsCopyDest</a></h3> +<p class="description">Callback block</p> +<p class="code"> +int cupsCopyDest (<br> + <a href="#cups_dest_t">cups_dest_t</a> *dest,<br> + int num_dests,<br> + <a href="#cups_dest_t">cups_dest_t</a> **dests<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dest</dt> +<dt>num_dests</dt> +<dt>dests</dt> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Copy a destination.</p> +<p class="discussion">Make a copy of the destination to an array of destinations (or just a single +copy) - for use with the cupsEnumDests* functions. The caller is responsible +for calling cupsFreeDests() on the returned object(s). + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsCreateJob">cupsCreateJob</a></h3> <p class="description">Create an empty job for streaming.</p> <p class="code"> int cupsCreateJob (<br> @@ -1201,7 +1322,87 @@ Note: The current encryption setting is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the <a href="#cupsSetEncryption"><code>cupsSetEncryption</code></a> function need to do so in each thread for the same setting to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsEnumDests">cupsEnumDests</a></h3> +<p class="description">Enumerate available destinations with a callback function.</p> +<p class="code"> +int cupsEnumDests (<br> + unsigned flags,<br> + int msec,<br> + int *cancel,<br> + <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> + <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> + <a href="#cups_dest_cb_t">cups_dest_cb_t</a> cb,<br> + void *user_data<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>flags</dt> +<dd class="description">Enumeration flags</dd> +<dt>msec</dt> +<dd class="description">Timeout in milliseconds, +-1 for indefinite</dd> +<dt>cancel</dt> +<dd class="description">Pointer to "cancel" variable</dd> +<dt>type</dt> +<dd class="description">Printer type bits</dd> +<dt>mask</dt> +<dd class="description">Mask for printer type bits</dd> +<dt>cb</dt> +<dd class="description">Callback function</dd> +<dt>user_data</dt> +<dd class="description">User data</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Destinations are enumerated from one or more sources. The callback function +receives the <code>user_data</code> pointer, destination name, instance, number of +options, and options which can be used as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> +function. The function must return 1 to continue enumeration or 0 to stop.<br> +<br> +Enumeration happens on the current thread and does not return until all +destinations have been enumerated or the callback function returns 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cupsEnumDestsBlock">cupsEnumDestsBlock</a></h3> +<p class="description">Enumerate available destinations with a block.</p> +<p class="code"> +int cupsEnumDestsBlock (<br> + unsigned flags,<br> + int timeout,<br> + int *cancel,<br> + <a href="#cups_ptype_t">cups_ptype_t</a> type,<br> + <a href="#cups_ptype_t">cups_ptype_t</a> mask,<br> + <a href="#cups_dest_block_t">cups_dest_block_t</a> block<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>flags</dt> +<dd class="description">Enumeration flags</dd> +<dt>timeout</dt> +<dd class="description">Timeout in milliseconds, 0 for indefinite</dd> +<dt>cancel</dt> +<dd class="description">Pointer to "cancel" variable</dd> +<dt>type</dt> +<dd class="description">Printer type bits</dd> +<dt>mask</dt> +<dd class="description">Mask for printer type bits</dd> +<dt>block</dt> +<dd class="description">Block</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Destinations are enumerated from one or more sources. The block receives the +destination name, instance, number of options, and options which can be used +as input to the <a href="#cupsAddDest"><code>cupsAddDest</code></a> function. The block must return 1 to +continue enumeration or 0 to stop.<br> +<br> +Enumeration happens on the current thread and does not return until all +destinations have been enumerated or the block returns 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsFinishDocument">cupsFinishDocument</a></h3> <p class="description">Finish sending a document.</p> <p class="code"> ipp_status_t cupsFinishDocument (<br> @@ -1293,7 +1494,7 @@ variables are not set, the server default destination is returned. Applications should use the <a href="#cupsGetDests"><code>cupsGetDests</code></a> and <a href="#cupsGetDest"><code>cupsGetDest</code></a> functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetDefault2">cupsGetDefault2</a></h3> <p class="description">Get the default printer or class for the specified server.</p> <p class="code"> const char *cupsGetDefault2 (<br> @@ -1364,7 +1565,7 @@ marker-types, and printer-commands attributes as well.<br> <br> Use the <a href="#cupsFreeDests"><code>cupsFreeDests</code></a> function to free the destination list and the <a href="#cupsGetDest"><code>cupsGetDest</code></a> function to find a particular destination.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetDests2">cupsGetDests2</a></h3> <p class="description">Get the list of destinations from the specified server.</p> <p class="code"> int cupsGetDests2 (<br> @@ -1420,7 +1621,7 @@ int cupsGetJobs (<br> of state, while <code>CUPS_WHICHJOBS_ACTIVE</code> returns jobs that are pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns jobs that are stopped, canceled, aborted, or completed.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetJobs2">cupsGetJobs2</a></h3> <p class="description">Get the jobs from the specified server.</p> <p class="code"> int cupsGetJobs2 (<br> @@ -1452,7 +1653,7 @@ pending, processing, or held and <code>CUPS_WHICHJOBS_COMPLETED</code> returns jobs that are stopped, canceled, aborted, or completed. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetNamedDest">cupsGetNamedDest</a></h3> <p class="description">Get options for the named destination.</p> <p class="code"> <a href="#cups_dest_t">cups_dest_t</a> *cupsGetNamedDest (<br> @@ -1527,7 +1728,7 @@ in the class.<br> The returned filename is stored in a static buffer and is overwritten with each call to <code>cupsGetPPD</code> or <a href="#cupsGetPPD2"><code>cupsGetPPD2</code></a>. The caller "owns" the file that is created and must <code>unlink</code> the returned filename.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsGetPPD2">cupsGetPPD2</a></h3> <p class="description">Get the PPD file for a printer from the specified server.</p> <p class="code"> const char *cupsGetPPD2 (<br> @@ -1552,7 +1753,7 @@ each call to <a href="#cupsGetPPD"><code>cupsGetPPD</code></a> or <code>cupsGetP file that is created and must <code>unlink</code> the returned filename. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetPPD3">cupsGetPPD3</a></h3> <p class="description">Get the PPD file for a printer on the specified server if it has changed.</p> <p class="code"> @@ -1617,7 +1818,7 @@ Note: The current password callback function is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the <a href="#cupsSetPasswordCB"><code>cupsSetPasswordCB</code></a> or <a href="#cupsSetPasswordCB2"><code>cupsSetPasswordCB2</code></a> functions need to do so in each thread for the same function to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetPassword2">cupsGetPassword2</a></h3> <p class="description">Get a password from the user using the advanced password callback.</p> <p class="code"> @@ -1667,7 +1868,7 @@ int cupsGetPrinters (<br> <p class="discussion">This function is deprecated - use <a href="#cupsGetDests"><code>cupsGetDests</code></a> instead. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsGetServerPPD">cupsGetServerPPD</a></h3> <p class="description">Get an available PPD file from the server.</p> <p class="code"> char *cupsGetServerPPD (<br> @@ -1744,7 +1945,7 @@ cups_lang_t *cupsLangGet (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Language data</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifySubject">cupsNotifySubject</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/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"> char *cupsNotifySubject (<br> @@ -1764,7 +1965,7 @@ char *cupsNotifySubject (<br> <p class="discussion">The returned string must be freed by the caller using <code>free</code>. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsNotifyText">cupsNotifyText</a></h3> <p class="description">Return the text for the given notification message.</p> <p class="code"> char *cupsNotifyText (<br> @@ -1834,7 +2035,7 @@ int cupsPrintFile (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsPrintFile2">cupsPrintFile2</a></h3> <p class="description">Print a file to a printer or class on the specified server.</p> <p class="code"> @@ -1892,7 +2093,7 @@ int cupsPrintFiles (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsPrintFiles2">cupsPrintFiles2</a></h3> <p class="description">Print one or more files to a printer or class on the specified server.</p> <p class="code"> @@ -1924,7 +2125,7 @@ int cupsPrintFiles2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Job ID or 0 on error</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsRemoveDest">cupsRemoveDest</a></h3> <p class="description">Remove a destination from the destination list.</p> <p class="code"> int cupsRemoveDest (<br> @@ -1953,7 +2154,7 @@ queue, merely the lpoptions for that destination/instance. Use the options for the user. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsRemoveOption">cupsRemoveOption</a></h3> <p class="description">Remove an option from an option array.</p> <p class="code"> int cupsRemoveOption (<br> @@ -1991,7 +2192,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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> @@ -2013,7 +2214,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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"> @@ -2033,7 +2234,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSetDefaultDest">cupsSetDefaultDest</a></h3> <p class="description">Set the default destination.</p> <p class="code"> void cupsSetDefaultDest (<br> @@ -2070,7 +2271,7 @@ void cupsSetDests (<br> <h4 class="discussion">Discussion</h4> <p class="discussion">This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.</p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="cupsSetDests2">cupsSetDests2</a></h3> <p class="description">Save the list of destinations for the specified server.</p> <p class="code"> int cupsSetDests2 (<br> @@ -2134,7 +2335,7 @@ by a program per thread.<br> Note: The current password 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.4/Mac OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSetPasswordCB2">cupsSetPasswordCB2</a></h3> <p class="description">Set the advanced password callback for CUPS.</p> <p class="code"> void cupsSetPasswordCB2 (<br> @@ -2180,7 +2381,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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> @@ -2219,7 +2420,7 @@ void cupsSetUser (<br> Note: The current user name is tracked separately for each thread in a program. Multi-threaded programs that override the user name need to do so in each thread for the same user name to be used.</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsStartDocument">cupsStartDocument</a></h3> <p class="description">Add a document to a job created with cupsCreateJob().</p> <p class="code"> http_status_t cupsStartDocument (<br> @@ -2298,7 +2499,7 @@ This function is deprecated - use <a href="#cupsTempFd"><code>cupsTempFd</code>< <a href="#cupsTempFile2"><code>cupsTempFile2</code></a> instead. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsTempFile2">cupsTempFile2</a></h3> <p class="description">Creates a temporary CUPS file.</p> <p class="code"> cups_file_t *cupsTempFile2 (<br> @@ -2331,21 +2532,41 @@ 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> +<h3 class="typedef"><span class="info"> CUPS 1.5/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"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_block_t">cups_dest_block_t</a></h3> +<p class="description">Destination enumeration block +</p> +<p class="code"> +typedef int (*cups_dest_block_t(unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); +</p> +<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dest_cb_t">cups_dest_cb_t</a></h3> +<p class="description">Destination enumeration callback +</p> +<p class="code"> +typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, <a href="#cups_dest_t">cups_dest_t</a> *dest); +</p> <h3 class="typedef"><a name="cups_dest_t">cups_dest_t</a></h3> <p class="description">Destination</p> <p class="code"> typedef struct <a href="#cups_dest_s">cups_dest_s</a> cups_dest_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3> -<p class="description">Device callback </p> +<h3 class="typedef"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cups_device_cb_t">cups_device_cb_t</a></h3> +<p class="description">Device callback +</p> <p class="code"> typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data); </p> +<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_dinfo_t">cups_dinfo_t</a></h3> +<p class="description">Destination capability and status +information </p> +<p class="code"> +typedef struct _cups_dinfo_s cups_dinfo_t; +</p> <h3 class="typedef"><a name="cups_job_t">cups_job_t</a></h3> <p class="description">Job</p> <p class="code"> @@ -2356,8 +2577,9 @@ typedef struct <a href="#cups_job_s">cups_job_s</a> cups_job_t; <p class="code"> typedef struct <a href="#cups_option_s">cups_option_s</a> cups_option_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3> -<p class="description">New password callback </p> +<h3 class="typedef"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cups_password_cb2_t">cups_password_cb2_t</a></h3> +<p class="description">New password callback +</p> <p class="code"> typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data); </p> @@ -2371,11 +2593,17 @@ 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> +<h3 class="typedef"><span class="info"> CUPS 1.5/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> +<h3 class="typedef"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_t">cups_size_t</a></h3> +<p class="description">Media Size </p> +<p class="code"> +typedef struct <a href="#cups_size_s">cups_size_s</a> cups_size_t; +</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> @@ -2449,6 +2677,37 @@ typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *cert <dt>value </dt> <dd class="description">Value of option</dd> </dl> +<h3 class="struct"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="cups_size_s">cups_size_s</a></h3> +<p class="description">Media Size </p> +<p class="code">struct cups_size_s {<br> + char media[128];<br> + int width, length, bottom, left, right, top;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>media[128] </dt> +<dd class="description">Media name to use</dd> +<dt>top </dt> +<dd class="description">Top margin in hundredths of +millimeters</dd> +</dl> +<h3 class="struct"><a name="pollfd">pollfd</a></h3> +<p class="description">User data (unused)</p> +<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br> + _cups_dnssd_data_t *data;<br> + else if(val 0) data - got_data;<br> + void) timeout;<br> + int val;<br> +};</p> +<h4 class="members">Members</h4> +<dl> +<dt>data </dt> +<dd class="description">Enumeration data</dd> +<dt>got_data </dt> +<dt>timeout </dt> +<dt>val </dt> +<dd class="description">Return value</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 @@ -2456,11 +2715,13 @@ 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> +<p class="description">Printer type/capability bit +constants</p> <h4 class="constants">Constants</h4> <dl> -<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> -<dd class="description">Printer requires authentication </dd> +<dt>CUPS_PRINTER_AUTHENTICATED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> +<dd class="description">Printer requires authentication +</dd> <dt>CUPS_PRINTER_BIND </dt> <dd class="description">Can bind output</dd> <dt>CUPS_PRINTER_BW </dt> @@ -2471,42 +2732,43 @@ locale ID.</p> <dd class="description">Can collage copies</dd> <dt>CUPS_PRINTER_COLOR </dt> <dd class="description">Can do color printing</dd> -<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> -<dd class="description">Printer supports maintenance commands </dd> +<dt>CUPS_PRINTER_COMMANDS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> +<dd class="description">Printer supports maintenance commands +</dd> <dt>CUPS_PRINTER_COPIES </dt> <dd class="description">Can do copies</dd> <dt>CUPS_PRINTER_COVER </dt> <dd class="description">Can cover output</dd> <dt>CUPS_PRINTER_DEFAULT </dt> <dd class="description">Default printer on network</dd> -<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> -<dd class="description">Delete printer </dd> -<dt>CUPS_PRINTER_DISCOVERED <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> -<dd class="description">Printer was automatically discovered and added </dd> +<dt>CUPS_PRINTER_DELETE <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> +<dd class="description">Delete printer +</dd> <dt>CUPS_PRINTER_DUPLEX </dt> <dd class="description">Can do duplexing</dd> <dt>CUPS_PRINTER_FAX </dt> <dd class="description">Fax queue</dd> -<dt>CUPS_PRINTER_IMPLICIT </dt> -<dd class="description">Implicit class</dd> <dt>CUPS_PRINTER_LARGE </dt> <dd class="description">Can do D/E/A1/A0</dd> <dt>CUPS_PRINTER_LOCAL </dt> <dd class="description">Local printer or class</dd> <dt>CUPS_PRINTER_MEDIUM </dt> <dd class="description">Can do Tabloid/B/C/A3/A2</dd> -<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> -<dd class="description">Printer with scanning capabilities </dd> -<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> -<dd class="description">Printer is not shared </dd> +<dt>CUPS_PRINTER_MFP <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> +<dd class="description">Printer with scanning capabilities +</dd> +<dt>CUPS_PRINTER_NOT_SHARED <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> +<dd class="description">Printer is not shared +</dd> <dt>CUPS_PRINTER_PUNCH </dt> <dd class="description">Can punch output</dd> <dt>CUPS_PRINTER_REJECTING </dt> <dd class="description">Printer is rejecting jobs</dd> <dt>CUPS_PRINTER_REMOTE </dt> <dd class="description">Remote printer or class</dd> -<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> -<dd class="description">Scanner-only device </dd> +<dt>CUPS_PRINTER_SCANNER <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> +<dd class="description">Scanner-only device +</dd> <dt>CUPS_PRINTER_SMALL </dt> <dd class="description">Can do Letter/Legal/A4</dd> <dt>CUPS_PRINTER_SORT </dt> diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html index 430494a7..8d31c7f4 100644 --- a/doc/help/api-filedir.html +++ b/doc/help/api-filedir.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-filedir.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-filedir.html 10424 2012-04-23 17:26:57Z mike $" File and Directory API header for CUPS. @@ -424,7 +424,7 @@ file.">cupsFileRewind</a></li> </ul></li> </ul> <!-- - "$Id: api-filedir.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-filedir.html 10424 2012-04-23 17:26:57Z mike $" File and directory API introduction for CUPS. @@ -455,7 +455,7 @@ details of directory access/listing and provide a convenient way to get both a list of files and the information (permissions, size, timestamp, etc.) for each of those files.</p> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirClose">cupsDirClose</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsDirClose">cupsDirClose</a></h3> <p class="description">Close a directory.</p> <p class="code"> void cupsDirClose (<br> @@ -466,7 +466,7 @@ void cupsDirClose (<br> <dt>dp</dt> <dd class="description">Directory pointer</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirOpen">cupsDirOpen</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsDirOpen">cupsDirOpen</a></h3> <p class="description">Open a directory.</p> <p class="code"> <a href="#cups_dir_t">cups_dir_t</a> *cupsDirOpen (<br> @@ -479,7 +479,7 @@ void cupsDirClose (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Directory pointer or <code>NULL</code> if the directory could not be opened.</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirRead">cupsDirRead</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsDirRead">cupsDirRead</a></h3> <p class="description">Read the next directory entry.</p> <p class="code"> <a href="#cups_dentry_t">cups_dentry_t</a> *cupsDirRead (<br> @@ -492,7 +492,7 @@ void cupsDirClose (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Directory entry or <code>NULL</code> when there are no more</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsDirRewind">cupsDirRewind</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsDirRewind">cupsDirRewind</a></h3> <p class="description">Rewind to the start of the directory.</p> <p class="code"> void cupsDirRewind (<br> @@ -503,7 +503,7 @@ void cupsDirRewind (<br> <dt>dp</dt> <dd class="description">Directory pointer</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileClose">cupsFileClose</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileClose">cupsFileClose</a></h3> <p class="description">Close a CUPS file.</p> <p class="code"> int cupsFileClose (<br> @@ -516,7 +516,7 @@ int cupsFileClose (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileCompression">cupsFileCompression</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileCompression">cupsFileCompression</a></h3> <p class="description">Return whether a file is compressed.</p> <p class="code"> int cupsFileCompression (<br> @@ -529,7 +529,7 @@ int cupsFileCompression (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description"><code>CUPS_FILE_NONE</code> or <code>CUPS_FILE_GZIP</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileEOF">cupsFileEOF</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileEOF">cupsFileEOF</a></h3> <p class="description">Return the end-of-file status.</p> <p class="code"> int cupsFileEOF (<br> @@ -542,7 +542,7 @@ int cupsFileEOF (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 on end of file, 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileFind">cupsFileFind</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileFind">cupsFileFind</a></h3> <p class="description">Find a file using the specified path.</p> <p class="code"> const char *cupsFileFind (<br> @@ -575,7 +575,7 @@ the supplied paths, <code>NULL</code> is returned. A <code>NULL</code> path only matches the current directory. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileFlush">cupsFileFlush</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileFlush">cupsFileFlush</a></h3> <p class="description">Flush pending output.</p> <p class="code"> int cupsFileFlush (<br> @@ -588,7 +588,7 @@ int cupsFileFlush (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetChar">cupsFileGetChar</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileGetChar">cupsFileGetChar</a></h3> <p class="description">Get a single character from a file.</p> <p class="code"> int cupsFileGetChar (<br> @@ -601,7 +601,7 @@ int cupsFileGetChar (<br> </dl> <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> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileGetConf">cupsFileGetConf</a></h3> <p class="description">Get a line from a configuration file.</p> <p class="code"> char *cupsFileGetConf (<br> @@ -626,7 +626,7 @@ char *cupsFileGetConf (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Line read or <code>NULL</code> on end of file or error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGetLine">cupsFileGetLine</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileGetLine">cupsFileGetLine</a></h3> <p class="description">Get a CR and/or LF-terminated line that may contain binary data.</p> <p class="code"> @@ -653,7 +653,7 @@ nul-terminated, however you should use the returned length to determine the number of bytes on the line. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileGets">cupsFileGets</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileGets">cupsFileGets</a></h3> <p class="description">Get a CR and/or LF-terminated line.</p> <p class="code"> char *cupsFileGets (<br> @@ -672,7 +672,7 @@ char *cupsFileGets (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Line read or <code>NULL</code> on end of file or error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileLock">cupsFileLock</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileLock">cupsFileLock</a></h3> <p class="description">Temporarily lock access to a file.</p> <p class="code"> int cupsFileLock (<br> @@ -688,7 +688,7 @@ int cupsFileLock (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileNumber">cupsFileNumber</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileNumber">cupsFileNumber</a></h3> <p class="description">Return the file descriptor associated with a CUPS file.</p> <p class="code"> int cupsFileNumber (<br> @@ -701,7 +701,7 @@ int cupsFileNumber (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">File descriptor</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileOpen">cupsFileOpen</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileOpen">cupsFileOpen</a></h3> <p class="description">Open a CUPS file.</p> <p class="code"> <a href="#cups_file_t">cups_file_t</a> *cupsFileOpen (<br> @@ -732,7 +732,7 @@ connection as needed, generally preferring IPv6 connections when there is a choice. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileOpenFd">cupsFileOpenFd</a></h3> <p class="description">Open a CUPS file using a file descriptor.</p> <p class="code"> <a href="#cups_file_t">cups_file_t</a> *cupsFileOpenFd (<br> @@ -757,7 +757,7 @@ supplied which enables Flate compression of the file. Compression is not supported for the "a" (append) mode. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFilePeekChar">cupsFilePeekChar</a></h3> <p class="description">Peek at the next character from a file.</p> <p class="code"> int cupsFilePeekChar (<br> @@ -770,7 +770,7 @@ int cupsFilePeekChar (<br> </dl> <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="cupsFilePrintf">cupsFilePrintf</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFilePrintf">cupsFilePrintf</a></h3> <p class="description">Write a formatted string.</p> <p class="code"> int cupsFilePrintf (<br> @@ -789,7 +789,7 @@ int cupsFilePrintf (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of bytes written or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePutChar">cupsFilePutChar</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFilePutChar">cupsFilePutChar</a></h3> <p class="description">Write a character.</p> <p class="code"> int cupsFilePutChar (<br> @@ -805,7 +805,7 @@ int cupsFilePutChar (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsFilePutConf">cupsFilePutConf</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsFilePutConf">cupsFilePutConf</a></h3> <p class="description">Write a configuration line.</p> <p class="code"> ssize_t cupsFilePutConf (<br> @@ -828,7 +828,7 @@ ssize_t cupsFilePutConf (<br> <p class="discussion">This function handles any comment escaping of the value. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFilePuts">cupsFilePuts</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFilePuts">cupsFilePuts</a></h3> <p class="description">Write a string.</p> <p class="code"> int cupsFilePuts (<br> @@ -848,7 +848,7 @@ int cupsFilePuts (<br> <p class="discussion">Like the <code>fputs</code> function, no newline is appended to the string. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileRead">cupsFileRead</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileRead">cupsFileRead</a></h3> <p class="description">Read from a file.</p> <p class="code"> ssize_t cupsFileRead (<br> @@ -867,7 +867,7 @@ ssize_t cupsFileRead (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of bytes read or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileRewind">cupsFileRewind</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileRewind">cupsFileRewind</a></h3> <p class="description">Set the current file position to the beginning of the file.</p> <p class="code"> @@ -881,7 +881,7 @@ off_t cupsFileRewind (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New file position or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileSeek">cupsFileSeek</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileSeek">cupsFileSeek</a></h3> <p class="description">Seek in a file.</p> <p class="code"> off_t cupsFileSeek (<br> @@ -897,25 +897,25 @@ off_t cupsFileSeek (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New file position or -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStderr">cupsFileStderr</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileStderr">cupsFileStderr</a></h3> <p class="description">Return a CUPS file associated with stderr.</p> <p class="code"> <a href="#cups_file_t">cups_file_t</a> *cupsFileStderr (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStdin">cupsFileStdin</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileStdin">cupsFileStdin</a></h3> <p class="description">Return a CUPS file associated with stdin.</p> <p class="code"> <a href="#cups_file_t">cups_file_t</a> *cupsFileStdin (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileStdout">cupsFileStdout</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileStdout">cupsFileStdout</a></h3> <p class="description">Return a CUPS file associated with stdout.</p> <p class="code"> <a href="#cups_file_t">cups_file_t</a> *cupsFileStdout (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">CUPS file</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileTell">cupsFileTell</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileTell">cupsFileTell</a></h3> <p class="description">Return the current file position.</p> <p class="code"> off_t cupsFileTell (<br> @@ -928,7 +928,7 @@ off_t cupsFileTell (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">File position</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileUnlock">cupsFileUnlock</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileUnlock">cupsFileUnlock</a></h3> <p class="description">Unlock access to a file.</p> <p class="code"> int cupsFileUnlock (<br> @@ -941,7 +941,7 @@ int cupsFileUnlock (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on error</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsFileWrite">cupsFileWrite</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsFileWrite">cupsFileWrite</a></h3> <p class="description">Write to a file.</p> <p class="code"> ssize_t cupsFileWrite (<br> diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 3a9d1288..9433c655 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-filter.html 9799 2011-05-20 18:09:22Z mike $" + "$Id: api-filter.html 10424 2012-04-23 17:26:57Z mike $" Filter and backend programming header for CUPS. @@ -426,11 +426,11 @@ div.contents ul.subcontents li { </ul></li> </ul> <!-- - "$Id: api-filter.html 9799 2011-05-20 18:09:22Z mike $" + "$Id: api-filter.html 10424 2012-04-23 17:26:57Z mike $" Filter and backend programming introduction for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -508,7 +508,7 @@ directory to write to.</p> <p>In addition, some operating systems provide additional security mechanisms 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> +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> @@ -580,7 +580,7 @@ when running print filters and backends:</p> <dt>APPLE_LANGUAGE</dt> <dd>The Apple language identifier associated with the job - (Mac OS X only).</dd> + (OS X only).</dd> <dt>CHARSET</dt> <dd>The job character set, typically "utf-8".</dd> @@ -901,7 +901,7 @@ 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 +on 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> @@ -1191,7 +1191,7 @@ void *my_data; <a href="#cupsSideChannelSNMPWalk">cupsSNMPSideChannelWalk</a>(".1.3.6.1.2.1.43", 5.0, my_callback, my_data); </pre> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackChannelRead">cupsBackChannelRead</a></h3> <p class="description">Read data from the backchannel.</p> <p class="code"> ssize_t cupsBackChannelRead (<br> @@ -1216,7 +1216,7 @@ parameter controls how many seconds to wait for the data - use 0.0 to return immediately if there is no data, -1.0 to wait for data indefinitely. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3> <p class="description">Write data to the backchannel.</p> <p class="code"> ssize_t cupsBackChannelWrite (<br> @@ -1242,7 +1242,7 @@ controls how many seconds to wait for the data to be written - use indefinitely. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsBackendDeviceURI">cupsBackendDeviceURI</a></h3> <p class="description">Get the device URI for a backend.</p> <p class="code"> const char *cupsBackendDeviceURI (<br> @@ -1262,7 +1262,7 @@ variable or the device URI passed in argv[0], whichever is found first. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsBackendReport">cupsBackendReport</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsBackendReport">cupsBackendReport</a></h3> <p class="description">Write a device line from a backend.</p> <p class="code"> void cupsBackendReport (<br> @@ -1294,7 +1294,7 @@ It handles quoting of special characters in the device-make-and-model, device-info, device-id, and device-location strings. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelDoRequest">cupsSideChannelDoRequest</a></h3> <p class="description">Send a side-channel command to a backend and wait for a response.</p> <p class="code"> <a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelDoRequest (<br> @@ -1328,7 +1328,7 @@ pointed to by the "data" parameter. cupsSideChannelDoRequest() will update the value to contain the number of data bytes in the buffer. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSideChannelRead">cupsSideChannelRead</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelRead">cupsSideChannelRead</a></h3> <p class="description">Read a side-channel message.</p> <p class="code"> int cupsSideChannelRead (<br> @@ -1364,7 +1364,7 @@ pointed to by the "data" parameter. cupsSideChannelDoRequest() will update the value to contain the number of data bytes in the buffer. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSideChannelSNMPGet">cupsSideChannelSNMPGet</a></h3> <p class="description">Query a SNMP OID's value.</p> <p class="code"> <a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPGet (<br> @@ -1405,7 +1405,7 @@ support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when the printer does not respond to the SNMP query. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSideChannelSNMPWalk">cupsSideChannelSNMPWalk</a></h3> <p class="description">Query multiple SNMP OID values.</p> <p class="code"> <a href="#cups_sc_status_t">cups_sc_status_t</a> cupsSideChannelSNMPWalk (<br> @@ -1451,7 +1451,7 @@ support SNMP queries. <code>CUPS_SC_STATUS_NO_RESPONSE</code> is returned when the printer does not respond to the first SNMP query. </p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsSideChannelWrite">cupsSideChannelWrite</a></h3> <p class="description">Write a side-channel message.</p> <p class="code"> int cupsSideChannelWrite (<br> @@ -1556,15 +1556,15 @@ 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> +<dt>CUPS_SC_CMD_GET_CONNECTED <span class="info"> CUPS 1.5/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> <dd class="description">Return the device state</dd> -<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> +<dt>CUPS_SC_CMD_SNMP_GET <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> <dd class="description">Query an SNMP OID </dd> -<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> +<dt>CUPS_SC_CMD_SNMP_GET_NEXT <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> <dd class="description">Query the next SNMP OID </dd> <dt>CUPS_SC_CMD_SOFT_RESET </dt> <dd class="description">Do a soft reset</dd> diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html index 38a3e3fc..a49f6d94 100644 --- a/doc/help/api-httpipp.html +++ b/doc/help/api-httpipp.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-httpipp.html 9801 2011-05-21 04:02:41Z mike $" + "$Id: api-httpipp.html 10424 2012-04-23 17:26:57Z mike $" HTTP and IPP API header for CUPS. @@ -448,9 +448,11 @@ address records for the specified name.">httpGetHostByName</a></li> content-length or transfer-encoding fields.">httpGetLength</a></li> <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="#httpGetState" title="Get the current state of the HTTP request.">httpGetState</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="#httpGetVersion" title="Get the HTTP version at the other end.">httpGetVersion</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 @@ -466,6 +468,8 @@ request-uri.">httpMD5Final</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="#httpReconnect2" title="Reconnect to a HTTP server with timeout and optional +cancel.">httpReconnect2</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 @@ -494,6 +498,7 @@ connection.">httpSetCredentials</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="#ippAddOutOfBand" title="Add an out-of-band value to an IPP message.">ippAddOutOfBand</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> @@ -501,24 +506,63 @@ connection.">httpSetCredentials</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="#ippAttributeString" title="Convert the attribute's value to a string.">ippAttributeString</a></li> + <li><a href="#ippCopyAttribute" title="Copy an attribute.">ippCopyAttribute</a></li> + <li><a href="#ippCopyAttributes" title="Copy attributes from one IPP message to another.">ippCopyAttributes</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="#ippDeleteValues" title="Delete values in an attribute.">ippDeleteValues</a></li> + <li><a href="#ippEnumString" title="Return a string corresponding to the enum value.">ippEnumString</a></li> + <li><a href="#ippEnumValue" title="Return the value associated with a given enum string.">ippEnumValue</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="#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="#ippFirstAttribute" title="Return the first attribute in the message.">ippFirstAttribute</a></li> + <li><a href="#ippGetBoolean" title="Get a boolean value for an attribute.">ippGetBoolean</a></li> + <li><a href="#ippGetCollection" title="Get a collection value for an attribute.">ippGetCollection</a></li> + <li><a href="#ippGetCount" title="Get the number of values in an attribute.">ippGetCount</a></li> + <li><a href="#ippGetDate" title="Get a date value for an attribute.">ippGetDate</a></li> + <li><a href="#ippGetGroupTag" title="Get the group associated with an attribute.">ippGetGroupTag</a></li> + <li><a href="#ippGetInteger" title="Get the integer/enum value for an attribute.">ippGetInteger</a></li> + <li><a href="#ippGetName" title="Get the attribute name.">ippGetName</a></li> + <li><a href="#ippGetOperation" title="Get the operation ID in an IPP message.">ippGetOperation</a></li> + <li><a href="#ippGetRange" title="Get a rangeOfInteger value from an attribute.">ippGetRange</a></li> + <li><a href="#ippGetRequestId" title="Get the request ID from an IPP message.">ippGetRequestId</a></li> + <li><a href="#ippGetResolution" title="Get a resolution value for an attribute.">ippGetResolution</a></li> + <li><a href="#ippGetState" title="Get the IPP message state.">ippGetState</a></li> + <li><a href="#ippGetStatusCode" title="Get the status code from an IPP response or event message.">ippGetStatusCode</a></li> + <li><a href="#ippGetString" title="Return the value...">ippGetString</a></li> + <li><a href="#ippGetValueTag" title="Get the value tag for an attribute.">ippGetValueTag</a></li> + <li><a href="#ippGetVersion" title="Get the major and minor version number from an IPP message.">ippGetVersion</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="#ippNextAttribute" title="Return the next attribute in the message.">ippNextAttribute</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="#ippSetBoolean" title="Set a boolean value in an attribute.">ippSetBoolean</a></li> + <li><a href="#ippSetCollection" title="Set a collection value in an attribute.">ippSetCollection</a></li> + <li><a href="#ippSetDate" title="Set a date value in an attribute.">ippSetDate</a></li> + <li><a href="#ippSetGroupTag" title="Set the group tag of an attribute.">ippSetGroupTag</a></li> + <li><a href="#ippSetInteger" title="Set an integer or enum value in an attribute.">ippSetInteger</a></li> + <li><a href="#ippSetName" title="Set the name of an attribute.">ippSetName</a></li> + <li><a href="#ippSetOperation" title="Set the operation ID in an IPP request message.">ippSetOperation</a></li> <li><a href="#ippSetPort" title="Set the default port number.">ippSetPort</a></li> + <li><a href="#ippSetRange" title="Set a rangeOfInteger value in an attribute.">ippSetRange</a></li> + <li><a href="#ippSetRequestId" title="Set the request ID in an IPP message.">ippSetRequestId</a></li> + <li><a href="#ippSetResolution" title="Set a resolution value in an attribute.">ippSetResolution</a></li> + <li><a href="#ippSetState" title="Set the current state of the IPP message.">ippSetState</a></li> + <li><a href="#ippSetStatusCode" title="Set the status code in an IPP response or event message.">ippSetStatusCode</a></li> + <li><a href="#ippSetString" title="Set a string value in an attribute.">ippSetString</a></li> + <li><a href="#ippSetValueTag" title="Set the value tag of an attribute.">ippSetValueTag</a></li> + <li><a href="#ippSetVersion" title="Set the version number in an IPP message.">ippSetVersion</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> @@ -550,21 +594,21 @@ are server-oriented...">http_state_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> - <li><a href="#ipp_attribute_t" title="Attribute">ipp_attribute_t</a></li> + <li><a href="#ipp_attribute_t" title="IPP attribute">ipp_attribute_t</a></li> + <li><a href="#ipp_copycb_t" title="The following structures are PRIVATE starting with CUPS 1.6/OS X 10.8. +Please use the new accessor functions available in CUPS 1.6 and later, as +these definitions will be moved to a private header file in a future release.">ipp_copycb_t</a></li> + <li><a href="#ipp_dstate_t" title="Document states">ipp_dstate_t</a></li> <li><a href="#ipp_finish_t" title="Finishings">ipp_finish_t</a></li> <li><a href="#ipp_iocb_t" title="IPP IO Callback Function ">ipp_iocb_t</a></li> - <li><a href="#ipp_jstate_t" title="Job states">ipp_jstate_t</a></li> - <li><a href="#ipp_op_t" title="IPP operations">ipp_op_t</a></li> + <li><a href="#ipp_jcollate_t" title="Job collation types">ipp_jcollate_t</a></li> <li><a href="#ipp_orient_t" title="Orientation values">ipp_orient_t</a></li> <li><a href="#ipp_pstate_t" title="Printer states">ipp_pstate_t</a></li> <li><a href="#ipp_quality_t" title="Qualities">ipp_quality_t</a></li> - <li><a href="#ipp_request_t" title="Request Header">ipp_request_t</a></li> <li><a href="#ipp_res_t" title="Resolution units">ipp_res_t</a></li> <li><a href="#ipp_state_t" title="IPP states">ipp_state_t</a></li> - <li><a href="#ipp_t" title="Attribute Value">ipp_t</a></li> - <li><a href="#ipp_uchar_t" title="IPP status codes">ipp_uchar_t</a></li> - <li><a href="#ipp_tag_t" title="Format tags for attributes">ipp_tag_t</a></li> - <li><a href="#ipp_value_t" title="Attribute Value">ipp_value_t</a></li> + <li><a href="#ipp_t" title="IPP request/response data">ipp_t</a></li> + <li><a href="#ipp_uchar_t" title="Unsigned 8-bit integer/character">ipp_uchar_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> @@ -573,12 +617,7 @@ 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> -<li><a href="#UNIONS">Unions</a><ul class="code"> - <li><a href="#ipp_request_u" title="Request Header">ipp_request_u</a></li> - <li><a href="#ipp_value_u" title="Attribute Value">ipp_value_u</a></li> + <li><a href="#pollfd" title="User data (unused)">pollfd</a></li> </ul></li> <li><a href="#ENUMERATIONS">Constants</a><ul class="code"> <li><a href="#http_auth_e" title="HTTP authentication types">http_auth_e</a></li> @@ -592,7 +631,9 @@ are server-oriented...">http_state_e</a></li> <li><a href="#http_uri_coding_e" title="URI en/decode flags">http_uri_coding_e</a></li> <li><a href="#http_uri_status_e" title="URI separation status ">http_uri_status_e</a></li> <li><a href="#http_version_e" title="HTTP version numbers">http_version_e</a></li> + <li><a href="#ipp_dstate_e" title="Document states">ipp_dstate_e</a></li> <li><a href="#ipp_finish_e" title="Finishings">ipp_finish_e</a></li> + <li><a href="#ipp_jcollate_e" title="Job collation types">ipp_jcollate_e</a></li> <li><a href="#ipp_jstate_e" title="Job states">ipp_jstate_e</a></li> <li><a href="#ipp_op_e" title="IPP operations">ipp_op_e</a></li> <li><a href="#ipp_orient_e" title="Orientation values">ipp_orient_e</a></li> @@ -605,11 +646,11 @@ are server-oriented...">http_state_e</a></li> </ul></li> </ul> <!-- - "$Id: api-httpipp.html 9801 2011-05-21 04:02:41Z mike $" + "$Id: api-httpipp.html 10424 2012-04-23 17:26:57Z mike $" HTTP and IPP API introduction for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -635,35 +676,20 @@ The constant <code>CUPS_HTTP_DEFAULT</code> can be used with all of the <code>cups</code> functions to refer to the default CUPS server - the functions create a per-thread <a href='#http_t'><code>http_t</code></a> as needed.</p> -<p>The IPP APIs use two structures for requests (messages sent to the CUPS -scheduler) and responses (messages sent back to your application from the -scheduler). The <a href='#ipp_t'><code>ipp_t</code></a> structure holds a -complete request or response and is allocated using the -<a href='#ippNew'><code>ippNew</code></a> or -<a href='#ippNewRequest'><code>ippNewRequest</code></a> functions and -freed using the <a href='#ippDelete'><code>ippDelete</code></a> function.</p> - -<p>The second structure is called -<a href='#ipp_attribute_t'><code>ipp_attribute_t</code></a> and holds a -single IPP attribute which consists of a group tag (<code>group_tag</code>), a -value type tag (<code>value_tag</code>), the attribute name (<code>name</code>), -and 1 or more values (<code>values[]</code>). Attributes are added to an -<a href='#ipp_t'><code>ipp_t</code></a> structure using one of the -<code>ippAdd</code> functions. For example, use -<a href='#ippAddString'><code>ippAddString</code></a> to add a -"requesting-user-name" string attribute to a request:</p> +<p>The IPP APIs use two opaque structures for requests (messages sent to the CUPS scheduler) and responses (messages sent back to your application from the scheduler). The <a href='#ipp_t'><code>ipp_t</code></a> type holds a complete request or response and is allocated using the <a href='#ippNew'><code>ippNew</code></a> or <a href='#ippNewRequest'><code>ippNewRequest</code></a> functions and freed using the <a href='#ippDelete'><code>ippDelete</code></a> function.</p> + +<p>The second opaque structure is called <a href='#ipp_attribute_t'><code>ipp_attribute_t</code></a> and holds a single IPP attribute which consists of a group tag (<a href='#ippGetGroupTag'><code>ippGetGroupTag</code></a>), a value type tag (<a href='#ippGetValueTag'><code>ippGetValueTag</code></a>), the attribute name (<a href='#ippGetName'><code>ippGetName</code></a>), and 1 or more values (<a href='#ippGetCount'><code>ippGetCount</code></a>, <a href='#ippGetBoolean'><code>ippGetBoolean</code></a>, <a href='#ippGetCollection'><code>ippGetCollection</code></a>, <a href='#ippGetDate'><code>ippGetDate</code></a>, <a href='#ippGetInteger'><code>ippGetInteger</code></a>, <a href='#ippGetRange'><code>ippGetRange</code></a>, <a href='#ippGetResolution'><code>ippGetResolution</code></a>, and <a href='#ippGetString'><code>ippGetString</code></a>). Attributes are added to an <a href='#ipp_t'><code>ipp_t</code></a> pointer using one of the <code>ippAdd</code> functions. For example, use <a href='#ippAddString'><code>ippAddString</code></a> to add the "printer-uri" and "requesting-user-name" string attributes to a request:</p> <pre class='example'> <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); +<a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", + NULL, "ipp://localhost/printers/"); <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser()); </pre> -<p>Once you have created an IPP request, use the <code>cups</code> -functions to send the request to and read the response from the server. -For example, the <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> -function can be used for simple query operations that do not involve files:</p> +<p>Once you have created an IPP request, use the <code>cups</code> functions to send the request to and read the response from the server. For example, the <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function can be used for simple query operations that do not involve files:</p> <pre class='example'> #include <cups/cups.h> @@ -673,6 +699,8 @@ function can be used for simple query operations that do not involve files:</p> { <a href='#ipp_t'>ipp_t</a> *request = <a href='#ippNewRequest'>ippNewRequest</a>(IPP_GET_JOBS); + <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", + NULL, "ipp://localhost/printers/"); <a href='#ippAddString'>ippAddString</a>(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser()); @@ -680,13 +708,7 @@ function can be used for simple query operations that do not involve files:</p> } </pre> -<p>The <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function frees -the request structure and returns an IPP response structure or NULL pointer if -the request could not be sent to the server. Once you have a response from -the server, you can either use the -<a href='#ippFindAttribute'><code>ippFindAttribute</code></a> and -<a href='#ippFindNextAttribute'><code>ippFindNextAttribute</code></a> functions -to find specific attributes, for example:</p> +<p>The <a href='#cupsDoRequest'><code>cupsDoRequest</code></a> function frees the request and returns an IPP response or <code>NULL</code> pointer if the request could not be sent to the server. Once you have a response from the server, you can either use the <a href='#ippFindAttribute'><code>ippFindAttribute</code></a> and <a href='#ippFindNextAttribute'><code>ippFindNextAttribute</code></a> functions to find specific attributes, for example:</p> <pre class='example'> <a href='#ipp_t'>ipp_t</a> *response; @@ -695,25 +717,20 @@ to find specific attributes, for example:</p> attr = <a href='#ippFindAttribute'>ippFindAttribute</a>(response, "printer-state", IPP_TAG_ENUM); </pre> -<p>You can also walk the list of attributes with a simple <code>for</code> loop -like this:</p> +<p>You can also walk the list of attributes with a simple <code>for</code> loop like this:</p> <pre class='example'> <a href='#ipp_t'>ipp_t</a> *response; <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; -for (attr = response->attrs; attr != NULL; attr = attr->next) - if (attr->name == NULL) +for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) + if (ippGetName(attr) == NULL) puts("--SEPARATOR--"); else - puts(attr->name); + puts(ippGetName(attr)); </pre> -<p>The <code>for</code> loop approach is normally used when collecting -attributes for multiple objects (jobs, printers, etc.) in a response. Attributes -with <code>NULL</code> names indicate a separator between the attributes of -each object. For example, the following code will list the jobs returned from -our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> +<p>The <code>for</code> loop approach is normally used when collecting attributes for multiple objects (jobs, printers, etc.) in a response. Attributes with <code>NULL</code> names indicate a separator between the attributes of each object. For example, the following code will list the jobs returned from our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> <pre class='example'> <a href='#ipp_t'>ipp_t</a> *response = <a href='#get_jobs'>get_jobs</a>(); @@ -721,37 +738,55 @@ our previous <a href='#get_jobs'><code>get_jobs</code></a> example code:</p> if (response != NULL) { <a href='#ipp_attribute_t'>ipp_attribute_t</a> *attr; + const char *attrname; int job_id = 0; - char *job_name = NULL; - char *job_originating_user_name = NULL; + const char *job_name = NULL; + const char *job_originating_user_name = NULL; puts("Job ID Owner Title"); puts("------ ---------------- ---------------------------------"); - for (attr = response->attrs; attr != NULL; attr = attr->next) + for (attr = <a href='#ippFirstAttribute'>ippFirstAttribute</a>(response); attr != NULL; attr = <a href='#ippNextAttribute'>ippNextAttribute</a>(response)) { /* Attributes without names are separators between jobs */ - if (attr->name == NULL) + attrname = ippGetName(attr); + if (attrname == NULL) { - if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) + if (job_id > 0) + { + if (job_name == NULL) + job_name = "(withheld)"; + + if (job_originating_user_name == NULL) + job_originating_user_name = "(withheld)"; + printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); + } job_id = 0; job_name = NULL; job_originating_user_name = NULL; continue; } - else if (!strcmp(attr->name, "job-id") && attr->value_tag == IPP_TAG_INTEGER) - job_id = attr->values[0].integer; - else if (!strcmp(attr->name, "job-name") && attr->value_tag == IPP_TAG_NAME) - job_name = attr->values[0].string.text; - else if (!strcmp(attr->name, "job-originating-user-name") && - attr->value_tag == IPP_TAG_NAME) - job_originating_user_name = attr->values[0].string.text; + else if (!strcmp(attrname, "job-id") && ippGetValueTag(attr) == IPP_TAG_INTEGER) + job_id = ippGetInteger(attr, 0); + else if (!strcmp(attrname, "job-name") && ippGetValueTag(attr) == IPP_TAG_NAME) + job_name = ippGetString(attr, 0, NULL); + else if (!strcmp(attrname, "job-originating-user-name") && + ippGetValueTag(attr) == IPP_TAG_NAME) + job_originating_user_name = ippGetString(attr, 0, NULL); } - if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL) + if (job_id > 0) + { + if (job_name == NULL) + job_name = "(withheld)"; + + if (job_originating_user_name == NULL) + job_originating_user_name = "(withheld)"; + printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); + } } </pre> @@ -928,7 +963,7 @@ if (status == HTTP_CONTINUE) <a href='#ippDelete'>ippDelete</a>(request); </pre> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="cupsDoAuthentication">cupsDoAuthentication</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="cupsDoAuthentication">cupsDoAuthentication</a></h3> <p class="description">Authenticate a request.</p> <p class="code"> int cupsDoAuthentication (<br> @@ -978,7 +1013,7 @@ status, prior to resubmitting your request. <p class="discussion">This function sends the IPP request to the specified server, retrying and authenticating as necessary. The request is freed with <a href="#ippDelete"><code>ippDelete</code></a> after receiving a valid IPP response.</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="cupsDoIORequest">cupsDoIORequest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="cupsDoIORequest">cupsDoIORequest</a></h3> <p class="description">Do an IPP request with file descriptors.</p> <p class="code"> <a href="#ipp_t">ipp_t</a> *cupsDoIORequest (<br> @@ -1059,14 +1094,14 @@ void cupsEncodeOptions (<br> <p class="discussion">This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsEncodeOptions2">cupsEncodeOptions2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsEncodeOptions2">cupsEncodeOptions2</a></h3> <p class="description">Encode printer options into IPP attributes for a group.</p> <p class="code"> void cupsEncodeOptions2 (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> int num_options,<br> cups_option_t *options,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group_tag<br> + ipp_tag_t group_tag<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -1085,7 +1120,7 @@ function multiple times for each group, or use cupsEncodeOptions() to add the standard groups. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetDevices">cupsGetDevices</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetDevices">cupsGetDevices</a></h3> <p class="description">Get available printer devices.</p> <p class="code"> ipp_status_t cupsGetDevices (<br> @@ -1121,7 +1156,7 @@ parameters provide comma-delimited lists of backends to include or omit from the request respectively. </p> -<h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="cupsGetFd">cupsGetFd</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="cupsGetFd">cupsGetFd</a></h3> <p class="description">Get a file from the server.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsGetFd (<br> @@ -1144,7 +1179,7 @@ the request respectively. <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved. </p> -<h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="cupsGetFile">cupsGetFile</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="cupsGetFile">cupsGetFile</a></h3> <p class="description">Get a file from the server.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsGetFile (<br> @@ -1167,7 +1202,7 @@ the request respectively. <p class="discussion">This function returns <code>HTTP_OK</code> when the file is successfully retrieved. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetResponse">cupsGetResponse</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetResponse">cupsGetResponse</a></h3> <p class="description">Get a response to an IPP request.</p> <p class="code"> <a href="#ipp_t">ipp_t</a> *cupsGetResponse (<br> @@ -1186,7 +1221,8 @@ the request respectively. <h4 class="discussion">Discussion</h4> <p class="discussion">Use this function to get the response for an IPP request sent using cupsSendDocument() or cupsSendRequest(). For requests that return -additional data, use httpRead() after getting a successful response. +additional data, use httpRead() after getting a successful response, +otherwise call httpFlush() to complete the response processing. </p> <h3 class="function"><a name="cupsLastError">cupsLastError</a></h3> @@ -1195,13 +1231,13 @@ additional data, use httpRead() after getting a successful response. 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> +<h3 class="function"><span class="info"> CUPS 1.2/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> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="cupsPutFd">cupsPutFd</a></h3> <p class="description">Put a file on the server.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsPutFd (<br> @@ -1225,7 +1261,7 @@ const char *cupsLastErrorString (void);</p> successfully. </p> -<h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="cupsPutFile">cupsPutFile</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="cupsPutFile">cupsPutFile</a></h3> <p class="description">Put a file on the server.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsPutFile (<br> @@ -1249,7 +1285,7 @@ successfully. successfully. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsReadResponseData">cupsReadResponseData</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsReadResponseData">cupsReadResponseData</a></h3> <p class="description">Read additional data after the IPP response.</p> <p class="code"> ssize_t cupsReadResponseData (<br> @@ -1273,7 +1309,7 @@ ssize_t cupsReadResponseData (<br> files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsSendRequest">cupsSendRequest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsSendRequest">cupsSendRequest</a></h3> <p class="description">Send an IPP request.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsSendRequest (<br> @@ -1305,7 +1341,7 @@ Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the request is not freed. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsWriteRequestData">cupsWriteRequestData</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsWriteRequestData">cupsWriteRequestData</a></h3> <p class="description">Write additional data after an IPP request.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> cupsWriteRequestData (<br> @@ -1329,7 +1365,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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> @@ -1352,7 +1388,7 @@ int httpAddCredential (<br> <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> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrAny">httpAddrAny</a></h3> <p class="description">Check for the "any" address.</p> <p class="code"> int httpAddrAny (<br> @@ -1365,7 +1401,7 @@ int httpAddrAny (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if "any", 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrEqual">httpAddrEqual</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrEqual">httpAddrEqual</a></h3> <p class="description">Compare two addresses.</p> <p class="code"> int httpAddrEqual (<br> @@ -1381,7 +1417,7 @@ int httpAddrEqual (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if equal, 0 if not</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrLength">httpAddrLength</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrLength">httpAddrLength</a></h3> <p class="description">Return the length of the address in bytes.</p> <p class="code"> int httpAddrLength (<br> @@ -1394,7 +1430,7 @@ int httpAddrLength (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Length in bytes</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrLocalhost">httpAddrLocalhost</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrLocalhost">httpAddrLocalhost</a></h3> <p class="description">Check for the local loopback address.</p> <p class="code"> int httpAddrLocalhost (<br> @@ -1407,7 +1443,7 @@ int httpAddrLocalhost (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if local host, 0 otherwise</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrLookup">httpAddrLookup</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrLookup">httpAddrLookup</a></h3> <p class="description">Lookup the hostname associated with the address.</p> <p class="code"> char *httpAddrLookup (<br> @@ -1426,7 +1462,7 @@ char *httpAddrLookup (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Host name</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAddrString">httpAddrString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAddrString">httpAddrString</a></h3> <p class="description">Convert an address to a numeric string.</p> <p class="code"> char *httpAddrString (<br> @@ -1445,7 +1481,7 @@ char *httpAddrString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Numeric address string</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAssembleURI">httpAssembleURI</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAssembleURI">httpAssembleURI</a></h3> <p class="description">Assemble a uniform resource identifier from its components.</p> <p class="code"> @@ -1487,7 +1523,7 @@ place of traditional string functions whenever you need to create a URI string. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpAssembleURIf">httpAssembleURIf</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpAssembleURIf">httpAssembleURIf</a></h3> <p class="description">Assemble a uniform resource identifier from its components with a formatted resource.</p> <p class="code"> @@ -1560,7 +1596,7 @@ int httpCheck (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 = no data, 1 = data available</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="httpClearCookie">httpClearCookie</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="httpClearCookie">httpClearCookie</a></h3> <p class="description">Clear the cookie value(s).</p> <p class="code"> void httpClearCookie (<br> @@ -1632,7 +1668,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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"> @@ -1670,7 +1706,7 @@ char *httpDecode64 (<br> which provides buffer length arguments. </p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="httpDecode64_2">httpDecode64_2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="httpDecode64_2">httpDecode64_2</a></h3> <p class="description">Base64-decode a string.</p> <p class="code"> char *httpDecode64_2 (<br> @@ -1726,7 +1762,7 @@ char *httpEncode64 (<br> which provides buffer length arguments. </p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="httpEncode64_2">httpEncode64_2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="httpEncode64_2">httpEncode64_2</a></h3> <p class="description">Base64-encode a string.</p> <p class="code"> char *httpEncode64_2 (<br> @@ -1788,7 +1824,7 @@ void httpFlush (<br> <dt>http</dt> <dd class="description">Connection to server</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpFlushWrite">httpFlushWrite</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpFlushWrite">httpFlushWrite</a></h3> <p class="description">Flush data in write buffer.</p> <p class="code"> int httpFlushWrite (<br> @@ -1828,7 +1864,7 @@ int httpGet (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status of call (0 = success)</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="httpGetAuthString">httpGetAuthString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="httpGetAuthString">httpGetAuthString</a></h3> <p class="description">Get the current authorization string.</p> <p class="code"> char *httpGetAuthString (<br> @@ -1848,7 +1884,7 @@ string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION value. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetBlocking">httpGetBlocking</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetBlocking">httpGetBlocking</a></h3> <p class="description">Get the blocking/non-block state of a connection.</p> <p class="code"> int httpGetBlocking (<br> @@ -1861,7 +1897,7 @@ int httpGetBlocking (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">1 if blocking, 0 if non-blocking</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="httpGetCookie">httpGetCookie</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="httpGetCookie">httpGetCookie</a></h3> <p class="description">Get any cookie data from the response.</p> <p class="code"> const char *httpGetCookie (<br> @@ -1887,7 +1923,7 @@ const char *httpGetDateString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Date/time string</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetDateString2">httpGetDateString2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetDateString2">httpGetDateString2</a></h3> <p class="description">Get a formatted date/time string from a time value.</p> <p class="code"> const char *httpGetDateString2 (<br> @@ -1919,7 +1955,7 @@ time_t httpGetDateTime (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">UNIX time</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetFd">httpGetFd</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetFd">httpGetFd</a></h3> <p class="description">Get the file descriptor associated with a connection.</p> <p class="code"> int httpGetFd (<br> @@ -1962,7 +1998,7 @@ struct hostent *httpGetHostByName (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Host entry</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetHostname">httpGetHostname</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetHostname">httpGetHostname</a></h3> <p class="description">Get the FQDN for the connection or local system.</p> <p class="code"> const char *httpGetHostname (<br> @@ -2007,7 +2043,7 @@ int httpGetLength (<br> 2^31 - 1; use httpGetLength2() instead. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetLength2">httpGetLength2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetLength2">httpGetLength2</a></h3> <p class="description">Get the amount of data remaining from the content-length or transfer-encoding fields.</p> <p class="code"> @@ -2026,7 +2062,20 @@ off_t httpGetLength2 (<br> content larger than 2^31 - 1. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetStatus">httpGetStatus</a></h3> +<h3 class="function"><a name="httpGetState">httpGetState</a></h3> +<p class="description">Get the current state of the HTTP request.</p> +<p class="code"> +<a href="#http_state_t">http_state_t</a> httpGetState (<br> + <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">HTTP state</p> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetStatus">httpGetStatus</a></h3> <p class="description">Get the status of the last HTTP request.</p> <p class="code"> <a href="#http_status_t">http_status_t</a> httpGetStatus (<br> @@ -2061,7 +2110,7 @@ char *httpGetSubField (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Value or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpGetSubField2">httpGetSubField2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpGetSubField2">httpGetSubField2</a></h3> <p class="description">Get a sub-field value.</p> <p class="code"> char *httpGetSubField2 (<br> @@ -2086,6 +2135,19 @@ char *httpGetSubField2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Value or NULL</p> +<h3 class="function"><a name="httpGetVersion">httpGetVersion</a></h3> +<p class="description">Get the HTTP version at the other end.</p> +<p class="code"> +<a href="#http_version_t">http_version_t</a> httpGetVersion (<br> + <a href="#http_t">http_t</a> *http<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Version number</p> <h3 class="function"><a name="httpGets">httpGets</a></h3> <p class="description">Get a line of text from a HTTP connection.</p> <p class="code"> @@ -2260,7 +2322,7 @@ int httpRead (<br> read more than 2GB of data. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpRead2">httpRead2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpRead2">httpRead2</a></h3> <p class="description">Read data from a HTTP connection.</p> <p class="code"> ssize_t httpRead2 (<br> @@ -2292,6 +2354,26 @@ int httpReconnect (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, non-zero on failure</p> +<h3 class="function"><a name="httpReconnect2">httpReconnect2</a></h3> +<p class="description">Reconnect to a HTTP server with timeout and optional +cancel.</p> +<p class="code"> +int httpReconnect2 (<br> + <a href="#http_t">http_t</a> *http,<br> + int msec,<br> + int *cancel<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>http</dt> +<dd class="description">Connection to server</dd> +<dt>msec</dt> +<dd class="description">Timeout in milliseconds</dd> +<dt>cancel</dt> +<dd class="description">Pointer to "cancel" variable</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">0 on success, non-zero on failure</p> <h3 class="function"><span class="info"> DEPRECATED </span><a name="httpSeparate">httpSeparate</a></h3> <p class="description">Separate a Universal Resource Identifier into its components.</p> @@ -2323,7 +2405,7 @@ void httpSeparate (<br> <p class="discussion">This function is deprecated; use the httpSeparateURI() function instead. </p> -<h3 class="function"><span class="info"> CUPS 1.1.21/Mac OS X 10.4 </span><a name="httpSeparate2">httpSeparate2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.21/OS X 10.4 </span><a name="httpSeparate2">httpSeparate2</a></h3> <p class="description">Separate a Universal Resource Identifier into its components.</p> <p class="code"> @@ -2367,7 +2449,7 @@ void httpSeparate2 (<br> </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpSeparateURI">httpSeparateURI</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpSeparateURI">httpSeparateURI</a></h3> <p class="description">Separate a Universal Resource Identifier into its components.</p> <p class="code"> @@ -2411,7 +2493,7 @@ components.</p> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Result of separation</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="httpSetAuthString">httpSetAuthString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="httpSetAuthString">httpSetAuthString</a></h3> <p class="description">Set the current authorization string.</p> <p class="code"> void httpSetAuthString (<br> @@ -2435,7 +2517,7 @@ HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(), httpHead(), httpOptions(), httpPost, or httpPut(). </p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="httpSetCookie">httpSetCookie</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="httpSetCookie">httpSetCookie</a></h3> <p class="description">Set the cookie value(s).</p> <p class="code"> void httpSetCookie (<br> @@ -2449,7 +2531,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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"> @@ -2466,7 +2548,7 @@ int httpSetCredentials (<br> </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> +<h3 class="function"><span class="info"> CUPS 1.2/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"> void httpSetExpect (<br> @@ -2501,7 +2583,7 @@ void httpSetField (<br> <dt>value</dt> <dd class="description">Value</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpSetLength">httpSetLength</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpSetLength">httpSetLength</a></h3> <p class="description">Set the content-length and content-encoding.</p> <p class="code"> void httpSetLength (<br> @@ -2515,7 +2597,7 @@ 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> +<h3 class="function"><span class="info"> CUPS 1.5/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> @@ -2586,7 +2668,7 @@ int httpTrace (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">HTTP status</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="httpWait">httpWait</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="httpWait">httpWait</a></h3> <p class="description">Wait for data available on a connection.</p> <p class="code"> int httpWait (<br> @@ -2626,7 +2708,7 @@ int httpWrite (<br> write more than 2GB of data. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="httpWrite2">httpWrite2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="httpWrite2">httpWrite2</a></h3> <p class="description">Write data to a HTTP connection.</p> <p class="code"> ssize_t httpWrite2 (<br> @@ -2650,7 +2732,7 @@ ssize_t httpWrite2 (<br> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> char value<br> );</p> @@ -2667,12 +2749,21 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> <h3 class="function"><a name="ippAddBooleans">ippAddBooleans</a></h3> <p class="description">Add an array of boolean values.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> int num_values,<br> const char *values<br> @@ -2692,12 +2783,21 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ippAddCollection">ippAddCollection</a></h3> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ippAddCollection">ippAddCollection</a></h3> <p class="description">Add a collection value.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> <a href="#ipp_t">ipp_t</a> *value<br> );</p> @@ -2714,12 +2814,23 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ippAddCollections">ippAddCollections</a></h3> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ippAddCollections">ippAddCollections</a></h3> <p class="description">Add an array of collection values.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> int num_values,<br> const <a href="#ipp_t">ipp_t</a> **values<br> @@ -2739,12 +2850,23 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> <h3 class="function"><a name="ippAddDate">ippAddDate</a></h3> <p class="description">Add a date attribute to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> const <a href="#ipp_uchar_t">ipp_uchar_t</a> *value<br> );</p> @@ -2761,13 +2883,22 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> <h3 class="function"><a name="ippAddInteger">ippAddInteger</a></h3> <p class="description">Add a integer attribute to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type,<br> + ipp_tag_t group,<br> + ipp_tag_t value_tag,<br> const char *name,<br> int value<br> );</p> @@ -2777,7 +2908,7 @@ ssize_t httpWrite2 (<br> <dd class="description">IPP message</dd> <dt>group</dt> <dd class="description">IPP group</dd> -<dt>type</dt> +<dt>value_tag</dt> <dd class="description">Type of attribute</dd> <dt>name</dt> <dd class="description">Name of attribute</dd> @@ -2786,13 +2917,25 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer +(<code>IPP_TAG_INTEGER</code>).</p> <h3 class="function"><a name="ippAddIntegers">ippAddIntegers</a></h3> <p class="description">Add an array of integer values.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type,<br> + ipp_tag_t group,<br> + ipp_tag_t value_tag,<br> const char *name,<br> int num_values,<br> const int *values<br> @@ -2803,7 +2946,7 @@ ssize_t httpWrite2 (<br> <dd class="description">IPP message</dd> <dt>group</dt> <dd class="description">IPP group</dd> -<dt>type</dt> +<dt>value_tag</dt> <dd class="description">Type of attribute</dd> <dt>name</dt> <dd class="description">Name of attribute</dd> @@ -2814,12 +2957,24 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippAddOctetString">ippAddOctetString</a></h3> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported values include enum (<code>IPP_TAG_ENUM</code>) and integer +(<code>IPP_TAG_INTEGER</code>).</p> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippAddOctetString">ippAddOctetString</a></h3> <p class="description">Add an octetString value to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> const void *data,<br> int datalen<br> @@ -2839,12 +2994,62 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippAddOutOfBand">ippAddOutOfBand</a></h3> +<p class="description">Add an out-of-band value to an IPP message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOutOfBand (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + ipp_tag_t group,<br> + ipp_tag_t value_tag,<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>group</dt> +<dd class="description">IPP group</dd> +<dt>value_tag</dt> +<dd class="description">Type of attribute</dd> +<dt>name</dt> +<dd class="description">Name of attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported out-of-band values include unsupported-value +(<code>IPP_TAG_UNSUPPORTED_VALUE</code>), default (<code>IPP_TAG_DEFAULT</code>), unknown +(<code>IPP_TAG_UNKNOWN</code>), no-value (<code>IPP_TAG_NOVALUE</code>), not-settable +(<code>IPP_TAG_NOTSETTABLE</code>), delete-attribute (<code>IPP_TAG_DELETEATTR</code>), and +admin-define (<code>IPP_TAG_ADMINDEFINE</code>). + +</p> <h3 class="function"><a name="ippAddRange">ippAddRange</a></h3> <p class="description">Add a range of values to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> int lower,<br> int upper<br> @@ -2864,12 +3069,23 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +The <code>lower</code> parameter must be less than or equal to the <code>upper</code> parameter.</p> <h3 class="function"><a name="ippAddRanges">ippAddRanges</a></h3> <p class="description">Add ranges of values to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> int num_values,<br> const int *lower,<br> @@ -2892,12 +3108,21 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> <h3 class="function"><a name="ippAddResolution">ippAddResolution</a></h3> <p class="description">Add a resolution value to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> <a href="#ipp_res_t">ipp_res_t</a> units,<br> int xres,<br> @@ -2920,12 +3145,21 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> <h3 class="function"><a name="ippAddResolutions">ippAddResolutions</a></h3> <p class="description">Add resolution values to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> + ipp_tag_t group,<br> const char *name,<br> int num_values,<br> <a href="#ipp_res_t">ipp_res_t</a> units,<br> @@ -2951,6 +3185,15 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).</p> <h3 class="function"><a name="ippAddSeparator">ippAddSeparator</a></h3> <p class="description">Add a group separator to an IPP message.</p> <p class="code"> @@ -2964,15 +3207,18 @@ ssize_t httpWrite2 (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.</p> <h3 class="function"><a name="ippAddString">ippAddString</a></h3> <p class="description">Add a language-encoded string to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type,<br> + ipp_tag_t group,<br> + ipp_tag_t value_tag,<br> const char *name,<br> - const char *charset,<br> + const char *language,<br> const char *value<br> );</p> <h4 class="parameters">Parameters</h4> @@ -2981,27 +3227,46 @@ ssize_t httpWrite2 (<br> <dd class="description">IPP message</dd> <dt>group</dt> <dd class="description">IPP group</dd> -<dt>type</dt> +<dt>value_tag</dt> <dd class="description">Type of attribute</dd> <dt>name</dt> <dd class="description">Name of attribute</dd> -<dt>charset</dt> -<dd class="description">Character set</dd> +<dt>language</dt> +<dd class="description">Language code</dd> <dt>value</dt> <dd class="description">Value</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and +textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> <h3 class="function"><a name="ippAddStrings">ippAddStrings</a></h3> <p class="description">Add language-encoded strings to an IPP message.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type,<br> + ipp_tag_t group,<br> + ipp_tag_t value_tag,<br> const char *name,<br> int num_values,<br> - const char *charset,<br> + const char *language,<br> const char *const *values<br> );</p> <h4 class="parameters">Parameters</h4> @@ -3010,19 +3275,126 @@ ssize_t httpWrite2 (<br> <dd class="description">IPP message</dd> <dt>group</dt> <dd class="description">IPP group</dd> -<dt>type</dt> +<dt>value_tag</dt> <dd class="description">Type of attribute</dd> <dt>name</dt> <dd class="description">Name of attribute</dd> <dt>num_values</dt> <dd class="description">Number of values</dd> -<dt>charset</dt> -<dd class="description">Character set</dd> +<dt>language</dt> +<dd class="description">Language code (<code>NULL</code> for default)</dd> <dt>values</dt> <dd class="description">Values</dd> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>).<br> +<br> +Supported string values include charset (<code>IPP_TAG_CHARSET</code>), keyword +(<code>IPP_TAG_KEYWORD</code>), language (<code>IPP_TAG_LANGUAGE</code>), mimeMediaType +(<code>IPP_TAG_MIMETYPE</code>), name (<code>IPP_TAG_NAME</code>), nameWithLanguage +(<code>IPP_TAG_NAMELANG), text (</code>code IPP_TAG_TEXT@), textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>), uri (<code>IPP_TAG_URI</code>), and uriScheme +(<code>IPP_TAG_URISCHEME</code>).<br> +<br> +The <code>language</code> parameter must be non-<code>NULL</code> for nameWithLanguage and +textWithLanguage string values and must be <code>NULL</code> for all other string values.</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippAttributeString">ippAttributeString</a></h3> +<p class="description">Convert the attribute's value to a string.</p> +<p class="code"> +size_t ippAttributeString (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + char *buffer,<br> + size_t bufsize<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">Attribute</dd> +<dt>buffer</dt> +<dd class="description">String buffer or NULL</dd> +<dt>bufsize</dt> +<dd class="description">Size of string buffer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of bytes less nul</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Returns the number of bytes that would be written, not including the +trailing nul. The buffer pointer can be NULL to get the required length, +just like (v)snprintf. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippCopyAttribute">ippCopyAttribute</a></h3> +<p class="description">Copy an attribute.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippCopyAttribute (<br> + <a href="#ipp_t">ipp_t</a> *dst,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *srcattr,<br> + int quickcopy<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dst</dt> +<dd class="description">Destination IPP message</dd> +<dt>srcattr</dt> +<dd class="description">Attribute to copy</dd> +<dt>quickcopy</dt> +<dd class="description">1 for a referenced copy, 0 for normal</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">New attribute</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The specified attribute, <code>attr</code>, is copied to the destination IPP message. +When <code>quickcopy</code> is non-zero, a "shallow" reference copy of the attribute is +created - this should only be done as long as the original source IPP message will +not be freed for the life of the destination. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippCopyAttributes">ippCopyAttributes</a></h3> +<p class="description">Copy attributes from one IPP message to another.</p> +<p class="code"> +int ippCopyAttributes (<br> + <a href="#ipp_t">ipp_t</a> *dst,<br> + <a href="#ipp_t">ipp_t</a> *src,<br> + int quickcopy,<br> + <a href="#ipp_copycb_t">ipp_copycb_t</a> cb,<br> + void *context<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>dst</dt> +<dd class="description">Destination IPP message</dd> +<dt>src</dt> +<dd class="description">Source IPP message</dd> +<dt>quickcopy</dt> +<dd class="description">1 for a referenced copy, 0 for normal</dd> +<dt>cb</dt> +<dd class="description">Copy callback or <code>NULL</code> for none</dd> +<dt>context</dt> +<dd class="description">Context pointer</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">Zero or more attributes are copied from the source IPP message, @code@ src, to the +destination IPP message, <code>dst</code>. When <code>quickcopy</code> is non-zero, a "shallow" +reference copy of the attribute is created - this should only be done as long as the +original source IPP message will not be freed for the life of the destination.<br> +<br> +The <code>cb</code> and <code>context</code> parameters provide a generic way to "filter" the +attributes that are copied - the function must return 1 to copy the attribute or +0 to skip it. The function may also choose to do a partial copy of the source attribute +itself. + +</p> <h3 class="function"><a name="ippDateToTime">ippDateToTime</a></h3> <p class="description">Convert from RFC 1903 Date/Time format to UNIX time in seconds.</p> @@ -3048,7 +3420,7 @@ void ippDelete (<br> <dt>ipp</dt> <dd class="description">IPP message</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ippDeleteAttribute">ippDeleteAttribute</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ippDeleteAttribute">ippDeleteAttribute</a></h3> <p class="description">Delete a single attribute in an IPP message.</p> <p class="code"> void ippDeleteAttribute (<br> @@ -3062,6 +3434,69 @@ void ippDeleteAttribute (<br> <dt>attr</dt> <dd class="description">Attribute to delete</dd> </dl> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippDeleteValues">ippDeleteValues</a></h3> +<p class="description">Delete values in an attribute.</p> +<p class="code"> +int ippDeleteValues (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + int count<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">Attribute</dd> +<dt>element</dt> +<dd class="description">Index of first value to delete (0-based)</dd> +<dt>count</dt> +<dd class="description">Number of values to delete</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies the first value to delete, starting at +0. It must be less than the number of values returned by <a href="#ippGetCount"><code>ippGetCount</code></a>.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +Deleting all values in an attribute deletes the attribute. + +</p> +<h3 class="function"><a name="ippEnumString">ippEnumString</a></h3> +<p class="description">Return a string corresponding to the enum value.</p> +<p class="code"> +const char *ippEnumString (<br> + const char *attrname,<br> + int enumvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attrname</dt> +<dd class="description">Attribute name</dd> +<dt>enumvalue</dt> +<dd class="description">Enum value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Enum string</p> +<h3 class="function"><a name="ippEnumValue">ippEnumValue</a></h3> +<p class="description">Return the value associated with a given enum string.</p> +<p class="code"> +int ippEnumValue (<br> + const char *attrname,<br> + const char *enumstring<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attrname</dt> +<dd class="description">Attribute name</dd> +<dt>enumstring</dt> +<dd class="description">Enum string</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Enum value or -1 if unknown</p> <h3 class="function"><a name="ippErrorString">ippErrorString</a></h3> <p class="description">Return a name for the given status code.</p> <p class="code"> @@ -3075,7 +3510,7 @@ const char *ippErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Text string</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippErrorValue">ippErrorValue</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippErrorValue">ippErrorValue</a></h3> <p class="description">Return a status code for the given name.</p> <p class="code"> ipp_status_t ippErrorValue (<br> @@ -3089,12 +3524,12 @@ ipp_status_t ippErrorValue (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">IPP status code</p> <h3 class="function"><a name="ippFindAttribute">ippFindAttribute</a></h3> -<p class="description">Find a named attribute in a request...</p> +<p class="description">Find a named attribute in a request.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> const char *name,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type<br> + ipp_tag_t type<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -3108,12 +3543,12 @@ ipp_status_t ippErrorValue (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">Matching attribute</p> <h3 class="function"><a name="ippFindNextAttribute">ippFindNextAttribute</a></h3> -<p class="description">Find the next named attribute in a request...</p> +<p class="description">Find the next named attribute in a request.</p> <p class="code"> <a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute (<br> <a href="#ipp_t">ipp_t</a> *ipp,<br> const char *name,<br> - <a href="#ipp_tag_t">ipp_tag_t</a> type<br> + ipp_tag_t type<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -3126,6 +3561,297 @@ ipp_status_t ippErrorValue (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Matching attribute</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippFirstAttribute">ippFirstAttribute</a></h3> +<p class="description">Return the first attribute in the message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFirstAttribute (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">First attribute or <code>NULL</code> if none</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetBoolean">ippGetBoolean</a></h3> +<p class="description">Get a boolean value for an attribute.</p> +<p class="code"> +int ippGetBoolean (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Boolean value or -1 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetCollection">ippGetCollection</a></h3> +<p class="description">Get a collection value for an attribute.</p> +<p class="code"> +<a href="#ipp_t">ipp_t</a> *ippGetCollection (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Collection value or <code>NULL</code> on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetCount">ippGetCount</a></h3> +<p class="description">Get the number of values in an attribute.</p> +<p class="code"> +int ippGetCount (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Number of values or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetDate">ippGetDate</a></h3> +<p class="description">Get a date value for an attribute.</p> +<p class="code"> +const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippGetDate (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Date value or <code>NULL</code></p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetGroupTag">ippGetGroupTag</a></h3> +<p class="description">Get the group associated with an attribute.</p> +<p class="code"> +ipp_tag_t ippGetGroupTag (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Group tag or <code>IPP_TAG_ZERO</code> on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetInteger">ippGetInteger</a></h3> +<p class="description">Get the integer/enum value for an attribute.</p> +<p class="code"> +int ippGetInteger (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Value or -1 on error</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetName">ippGetName</a></h3> +<p class="description">Get the attribute name.</p> +<p class="code"> +const char *ippGetName (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Attribute name or <code>NULL</code> for separators</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetOperation">ippGetOperation</a></h3> +<p class="description">Get the operation ID in an IPP message.</p> +<p class="code"> +ipp_op_t ippGetOperation (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP request message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Operation ID or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetRange">ippGetRange</a></h3> +<p class="description">Get a rangeOfInteger value from an attribute.</p> +<p class="code"> +int ippGetRange (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element,<br> + int *uppervalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>uppervalue</dt> +<dd class="description">Upper value of range</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Lower value of range or -1</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetRequestId">ippGetRequestId</a></h3> +<p class="description">Get the request ID from an IPP message.</p> +<p class="code"> +int ippGetRequestId (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Request ID or -1 on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetResolution">ippGetResolution</a></h3> +<p class="description">Get a resolution value for an attribute.</p> +<p class="code"> +int ippGetResolution (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element,<br> + int *yres,<br> + <a href="#ipp_res_t">ipp_res_t</a> *units<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>yres</dt> +<dd class="description">Vertical/feed resolution</dd> +<dt>units</dt> +<dd class="description">Units for resolution</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Horizontal/cross feed resolution or -1</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetState">ippGetState</a></h3> +<p class="description">Get the IPP message state.</p> +<p class="code"> +<a href="#ipp_state_t">ipp_state_t</a> ippGetState (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">IPP message state value</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetStatusCode">ippGetStatusCode</a></h3> +<p class="description">Get the status code from an IPP response or event message.</p> +<p class="code"> +ipp_status_t ippGetStatusCode (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP response or event message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Status code in IPP message</p> +<h3 class="function"><a name="ippGetString">ippGetString</a></h3> +<p class="description">Return the value...</p> +<p class="code"> +const char *ippGetString (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr,<br> + int element,<br> + const char **language<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>language</dt> +<dd class="description">Language code (<code>NULL</code> for don't care)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Get the string and optionally the language code for an attribute.</p> +<p class="discussion">The <code>element</code> parameter specifies which value to get from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a> - 1. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetValueTag">ippGetValueTag</a></h3> +<p class="description">Get the value tag for an attribute.</p> +<p class="code"> +ipp_tag_t ippGetValueTag (<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Value tag or <code>IPP_TAG_ZERO</code> on error</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippGetVersion">ippGetVersion</a></h3> +<p class="description">Get the major and minor version number from an IPP message.</p> +<p class="code"> +int ippGetVersion (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + int *minor<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>minor</dt> +<dd class="description">Minor version number or <code>NULL</code></dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Major version number or -1 on error</p> <h3 class="function"><a name="ippLength">ippLength</a></h3> <p class="description">Compute the length of an IPP message.</p> <p class="code"> @@ -3145,11 +3871,11 @@ size_t ippLength (<br> <a href="#ipp_t">ipp_t</a> *ippNew (void);</p> <h4 class="returnvalue">Return Value</h4> <p class="description">New IPP message</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippNewRequest">ippNewRequest</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippNewRequest">ippNewRequest</a></h3> <p class="description">Allocate a new IPP request message.</p> <p class="code"> <a href="#ipp_t">ipp_t</a> *ippNewRequest (<br> - <a href="#ipp_op_t">ipp_op_t</a> op<br> + ipp_op_t op<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -3164,11 +3890,24 @@ attributes-natural-language attributes added. The attributes-natural-language value is derived from the current locale. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippOpString">ippOpString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippNextAttribute">ippNextAttribute</a></h3> +<p class="description">Return the next attribute in the message.</p> +<p class="code"> +<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippNextAttribute (<br> + <a href="#ipp_t">ipp_t</a> *ipp<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">Next attribute or <code>NULL</code> if none</p> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippOpString">ippOpString</a></h3> <p class="description">Return a name for the given operation id.</p> <p class="code"> const char *ippOpString (<br> - <a href="#ipp_op_t">ipp_op_t</a> op<br> + ipp_op_t op<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -3177,10 +3916,10 @@ const char *ippOpString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Name</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippOpValue">ippOpValue</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippOpValue">ippOpValue</a></h3> <p class="description">Return an operation id for the given name.</p> <p class="code"> -<a href="#ipp_op_t">ipp_op_t</a> ippOpValue (<br> +ipp_op_t ippOpValue (<br> const char *name<br> );</p> <h4 class="parameters">Parameters</h4> @@ -3212,7 +3951,7 @@ int ippPort (void);</p> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ippReadFile">ippReadFile</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ippReadFile">ippReadFile</a></h3> <p class="description">Read data for an IPP message from a file.</p> <p class="code"> <a href="#ipp_state_t">ipp_state_t</a> ippReadFile (<br> @@ -3228,7 +3967,7 @@ int ippPort (void);</p> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippReadIO">ippReadIO</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippReadIO">ippReadIO</a></h3> <p class="description">Read data for an IPP message.</p> <p class="code"> <a href="#ipp_state_t">ipp_state_t</a> ippReadIO (<br> @@ -3253,6 +3992,213 @@ int ippPort (void);</p> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetBoolean">ippSetBoolean</a></h3> +<p class="description">Set a boolean value in an attribute.</p> +<p class="code"> +int ippSetBoolean (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + int boolvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>boolvalue</dt> +<dd class="description">Boolean value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetCollection">ippSetCollection</a></h3> +<p class="description">Set a collection value in an attribute.</p> +<p class="code"> +int ippSetCollection (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + <a href="#ipp_t">ipp_t</a> *colvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>colvalue</dt> +<dd class="description">Collection value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetDate">ippSetDate</a></h3> +<p class="description">Set a date value in an attribute.</p> +<p class="code"> +int ippSetDate (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + const <a href="#ipp_uchar_t">ipp_uchar_t</a> *datevalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>datevalue</dt> +<dd class="description">Date value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetGroupTag">ippSetGroupTag</a></h3> +<p class="description">Set the group tag of an attribute.</p> +<p class="code"> +int ippSetGroupTag (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + ipp_tag_t group_tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">Attribute</dd> +<dt>group_tag</dt> +<dd class="description">Group tag</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>group</code> parameter specifies the IPP attribute group tag: none +(<code>IPP_TAG_ZERO</code>, for member attributes), document (<code>IPP_TAG_DOCUMENT</code>), +event notification (<code>IPP_TAG_EVENT_NOTIFICATION</code>), operation +(<code>IPP_TAG_OPERATION</code>), printer (<code>IPP_TAG_PRINTER</code>), subscription +(<code>IPP_TAG_SUBSCRIPTION</code>), or unsupported (<code>IPP_TAG_UNSUPPORTED_GROUP</code>). + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetInteger">ippSetInteger</a></h3> +<p class="description">Set an integer or enum value in an attribute.</p> +<p class="code"> +int ippSetInteger (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + int intvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>intvalue</dt> +<dd class="description">Integer/enum value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetName">ippSetName</a></h3> +<p class="description">Set the name of an attribute.</p> +<p class="code"> +int ippSetName (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + const char *name<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>name</dt> +<dd class="description">Attribute name</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetOperation">ippSetOperation</a></h3> +<p class="description">Set the operation ID in an IPP request message.</p> +<p class="code"> +int ippSetOperation (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + ipp_op_t op<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP request message</dd> +<dt>op</dt> +<dd class="description">Operation ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions. + +</p> <h3 class="function"><a name="ippSetPort">ippSetPort</a></h3> <p class="description">Set the default port number.</p> <p class="code"> @@ -3264,11 +4210,240 @@ void ippSetPort (<br> <dt>p</dt> <dd class="description">Port number to use</dd> </dl> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="ippTagString">ippTagString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetRange">ippSetRange</a></h3> +<p class="description">Set a rangeOfInteger value in an attribute.</p> +<p class="code"> +int ippSetRange (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + int lowervalue,<br> + int uppervalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>lowervalue</dt> +<dd class="description">Lower bound for range</dd> +<dt>uppervalue</dt> +<dd class="description">Upper bound for range</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetRequestId">ippSetRequestId</a></h3> +<p class="description">Set the request ID in an IPP message.</p> +<p class="code"> +int ippSetRequestId (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + int request_id<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>request_id</dt> +<dd class="description">Request ID</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>request_id</code> parameter must be greater than 0. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetResolution">ippSetResolution</a></h3> +<p class="description">Set a resolution value in an attribute.</p> +<p class="code"> +int ippSetResolution (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + <a href="#ipp_res_t">ipp_res_t</a> unitsvalue,<br> + int xresvalue,<br> + int yresvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>unitsvalue</dt> +<dd class="description">Resolution units</dd> +<dt>xresvalue</dt> +<dd class="description">Horizontal/cross feed resolution</dd> +<dt>yresvalue</dt> +<dd class="description">Vertical/feed resolution</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetState">ippSetState</a></h3> +<p class="description">Set the current state of the IPP message.</p> +<p class="code"> +int ippSetState (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_state_t">ipp_state_t</a> state<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>state</dt> +<dd class="description">IPP state value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetStatusCode">ippSetStatusCode</a></h3> +<p class="description">Set the status code in an IPP response or event message.</p> +<p class="code"> +int ippSetStatusCode (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + ipp_status_t status<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP response or event message</dd> +<dt>status</dt> +<dd class="description">Status code</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetString">ippSetString</a></h3> +<p class="description">Set a string value in an attribute.</p> +<p class="code"> +int ippSetString (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + int element,<br> + const char *strvalue<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>element</dt> +<dd class="description">Value number (0-based)</dd> +<dt>strvalue</dt> +<dd class="description">String value</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +The <code>element</code> parameter specifies which value to set from 0 to +<a href="#ippGetCount(attr)"><code>ippGetCount(attr)</code></a>. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetValueTag">ippSetValueTag</a></h3> +<p class="description">Set the value tag of an attribute.</p> +<p class="code"> +int ippSetValueTag (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + <a href="#ipp_attribute_t">ipp_attribute_t</a> **attr,<br> + ipp_tag_t value_tag<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>attr</dt> +<dd class="description">IPP attribute</dd> +<dt>value_tag</dt> +<dd class="description">Value tag</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to the IPP message containing the attribute that was +previously created using the <a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The <code>attr</code> parameter may be modified as a result of setting the value.<br> +<br> +Integer (<code>IPP_TAG_INTEGER</code>) values can be promoted to rangeOfInteger +(<code>IPP_TAG_RANGE</code>) values, the various string tags can be promoted to name +(<code>IPP_TAG_NAME</code>) or nameWithLanguage (<code>IPP_TAG_NAMELANG</code>) values, text +(<code>IPP_TAG_TEXT</code>) values can be promoted to textWithLanguage +(<code>IPP_TAG_TEXTLANG</code>) values, and all values can be demoted to the various +out-of-band value tags such as no-value (<code>IPP_TAG_NOVALUE</code>). All other changes +will be rejected.<br> +<br> +Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language +code in the "attributes-natural-language" attribute or, if not present, the language +code for the current locale. + +</p> +<h3 class="function"><span class="info"> CUPS 1.6/OS X 10.8 </span><a name="ippSetVersion">ippSetVersion</a></h3> +<p class="description">Set the version number in an IPP message.</p> +<p class="code"> +int ippSetVersion (<br> + <a href="#ipp_t">ipp_t</a> *ipp,<br> + int major,<br> + int minor<br> +);</p> +<h4 class="parameters">Parameters</h4> +<dl> +<dt>ipp</dt> +<dd class="description">IPP message</dd> +<dt>major</dt> +<dd class="description">Major version number (major.minor)</dd> +<dt>minor</dt> +<dd class="description">Minor version number (major.minor)</dd> +</dl> +<h4 class="returnvalue">Return Value</h4> +<p class="description">1 on success, 0 on failure</p> +<h4 class="discussion">Discussion</h4> +<p class="discussion">The <code>ipp</code> parameter refers to an IPP message previously created using the +<a href="#ippNew"><code>ippNew</code></a> or <a href="#ippNewRequest"><code>ippNewRequest</code></a> functions.<br> +<br> +The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2. + +</p> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="ippTagString">ippTagString</a></h3> <p class="description">Return the tag name corresponding to a tag value.</p> <p class="code"> const char *ippTagString (<br> - <a href="#ipp_tag_t">ipp_tag_t</a> tag<br> + ipp_tag_t tag<br> );</p> <h4 class="parameters">Parameters</h4> <dl> @@ -3281,10 +4456,10 @@ const char *ippTagString (<br> <p class="discussion">The returned names are defined in RFC 2911 and 3382. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="ippTagValue">ippTagValue</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="ippTagValue">ippTagValue</a></h3> <p class="description">Return the tag value corresponding to a tag name.</p> <p class="code"> -<a href="#ipp_tag_t">ipp_tag_t</a> ippTagValue (<br> +ipp_tag_t ippTagValue (<br> const char *name<br> );</p> <h4 class="parameters">Parameters</h4> @@ -3327,7 +4502,7 @@ const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ippWriteFile">ippWriteFile</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ippWriteFile">ippWriteFile</a></h3> <p class="description">Write data for an IPP message to a file.</p> <p class="code"> <a href="#ipp_state_t">ipp_state_t</a> ippWriteFile (<br> @@ -3343,7 +4518,7 @@ const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Current state</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ippWriteIO">ippWriteIO</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ippWriteIO">ippWriteIO</a></h3> <p class="description">Write data for an IPP message.</p> <p class="code"> <a href="#ipp_state_t">ipp_state_t</a> ippWriteIO (<br> @@ -3374,7 +4549,7 @@ const <a href="#ipp_uchar_t">ipp_uchar_t</a> *ippTimeToDate (<br> <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> +<h3 class="typedef"><span class="info"> CUPS 1.2/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 address types easier and @@ -3382,7 +4557,7 @@ more portable. </p> <p class="code"> typedef union _http_addr_u / http_addr_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="http_addrlist_t">http_addrlist_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="http_addrlist_t">http_addrlist_t</a></h3> <p class="description">Socket address list, which is used to enumerate all of the addresses that are associated @@ -3395,7 +4570,7 @@ 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> +<h3 class="typedef"><span class="info"> CUPS 1.5/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; @@ -3436,7 +4611,7 @@ 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> +<h3 class="typedef"><span class="info"> CUPS 1.5/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); @@ -3457,29 +4632,36 @@ typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_ typedef enum <a href="#http_version_e">http_version_e</a> http_version_t; </p> <h3 class="typedef"><a name="ipp_attribute_t">ipp_attribute_t</a></h3> -<p class="description">Attribute</p> +<p class="description">IPP attribute</p> +<p class="code"> +typedef struct _ipp_attribute_s ipp_attribute_t; +</p> +<h3 class="typedef"><a name="ipp_copycb_t">ipp_copycb_t</a></h3> +<p class="description">The following structures are PRIVATE starting with CUPS 1.6/OS X 10.8. +Please use the new accessor functions available in CUPS 1.6 and later, as +these definitions will be moved to a private header file in a future release.</p> <p class="code"> -typedef struct <a href="#ipp_attribute_s">ipp_attribute_s</a> ipp_attribute_t; +typedef int (*ipp_copycb_t)(void *context, <a href="#ipp_t">ipp_t</a> *dst, <a href="#ipp_attribute_t">ipp_attribute_t</a> *attr); +</p> +<h3 class="typedef"><a name="ipp_dstate_t">ipp_dstate_t</a></h3> +<p class="description">Document states</p> +<p class="code"> +typedef enum <a href="#ipp_dstate_e">ipp_dstate_e</a> ipp_dstate_t; </p> <h3 class="typedef"><a name="ipp_finish_t">ipp_finish_t</a></h3> <p class="description">Finishings</p> <p class="code"> typedef enum <a href="#ipp_finish_e">ipp_finish_e</a> ipp_finish_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ipp_iocb_t">ipp_iocb_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ipp_iocb_t">ipp_iocb_t</a></h3> <p class="description">IPP IO Callback Function </p> <p class="code"> -typedef ssize_t (*ipp_iocb_t)(void *, <a href="#ipp_uchar_t">ipp_uchar_t</a> *, size_t); +typedef ssize_t (*ipp_iocb_t)(void *context, <a href="#ipp_uchar_t">ipp_uchar_t</a> *buffer, size_t bytes); </p> -<h3 class="typedef"><a name="ipp_jstate_t">ipp_jstate_t</a></h3> -<p class="description">Job states</p> +<h3 class="typedef"><a name="ipp_jcollate_t">ipp_jcollate_t</a></h3> +<p class="description">Job collation types</p> <p class="code"> -typedef enum <a href="#ipp_jstate_e">ipp_jstate_e</a> ipp_jstate_t; -</p> -<h3 class="typedef"><a name="ipp_op_t">ipp_op_t</a></h3> -<p class="description">IPP operations</p> -<p class="code"> -typedef enum <a href="#ipp_op_e">ipp_op_e</a> ipp_op_t; +typedef enum <a href="#ipp_jcollate_e">ipp_jcollate_e</a> ipp_jcollate_t; </p> <h3 class="typedef"><a name="ipp_orient_t">ipp_orient_t</a></h3> <p class="description">Orientation values</p> @@ -3496,11 +4678,6 @@ typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t; <p class="code"> typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t; </p> -<h3 class="typedef"><a name="ipp_request_t">ipp_request_t</a></h3> -<p class="description">Request Header</p> -<p class="code"> -typedef union <a href="#ipp_request_u">ipp_request_u</a> ipp_request_t; -</p> <h3 class="typedef"><a name="ipp_res_t">ipp_res_t</a></h3> <p class="description">Resolution units</p> <p class="code"> @@ -3512,24 +4689,14 @@ typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t; typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t; </p> <h3 class="typedef"><a name="ipp_t">ipp_t</a></h3> -<p class="description">Attribute Value</p> +<p class="description">IPP request/response data</p> <p class="code"> -typedef struct <a href="#ipp_s">ipp_s</a> ipp_t; +typedef struct _ipp_s ipp_t; </p> <h3 class="typedef"><a name="ipp_uchar_t">ipp_uchar_t</a></h3> -<p class="description">IPP status codes</p> +<p class="description">Unsigned 8-bit integer/character</p> <p class="code"> -typedef typedef unsigned char ipp_uchar_t; -</p> -<h3 class="typedef"><a name="ipp_tag_t">ipp_tag_t</a></h3> -<p class="description">Format tags for attributes</p> -<p class="code"> -typedef enum <a href="#ipp_tag_e">ipp_tag_e</a> ipp_tag_t; -</p> -<h3 class="typedef"><a name="ipp_value_t">ipp_value_t</a></h3> -<p class="description">Attribute Value</p> -<p class="code"> -typedef union <a href="#ipp_value_u">ipp_value_u</a> ipp_value_t; +typedef unsigned char ipp_uchar_t; </p> <h2 class="title"><a name="STRUCTURES">Structures</a></h2> <h3 class="struct"><a name="gss_auth_identity">gss_auth_identity</a></h3> @@ -3551,7 +4718,7 @@ typedef union <a href="#ipp_value_u">ipp_value_u</a> ipp_value_t; <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> +<h3 class="struct"><span class="info"> CUPS 1.2/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 addresses that are associated @@ -3567,7 +4734,7 @@ 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> +<h3 class="struct"><span class="info"> CUPS 1.5/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> @@ -3580,85 +4747,16 @@ with a hostname. </p> <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> - char *name;<br> - struct <a href="#ipp_attribute_s">ipp_attribute_s</a> *next;<br> - int num_values;<br> - <a href="#ipp_tag_t">ipp_tag_t</a> group_tag, value_tag;<br> - <a href="#ipp_value_t">ipp_value_t</a> values[1];<br> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>name </dt> -<dd class="description">Name of attribute</dd> -<dt>next </dt> -<dd class="description">Next attribute in list</dd> -<dt>num_values </dt> -<dd class="description">Number of values</dd> -<dt>value_tag </dt> -<dd class="description">What type of value is it?</dd> -<dt>values[1] </dt> -<dd class="description">Values</dd> -</dl> -<h3 class="struct"><a name="ipp_s">ipp_s</a></h3> -<p class="description">IPP Request/Response/Notification</p> -<p class="code">struct ipp_s {<br> - <a href="#ipp_attribute_t">ipp_attribute_t</a> *attrs;<br> - <a href="#ipp_attribute_t">ipp_attribute_t</a> *current;<br> - <a href="#ipp_tag_t">ipp_tag_t</a> curtag;<br> - <a href="#ipp_attribute_t">ipp_attribute_t</a> *last;<br> - <a href="#ipp_attribute_t">ipp_attribute_t</a> *prev;<br> - <a href="#ipp_request_t">ipp_request_t</a> request;<br> - <a href="#ipp_state_t">ipp_state_t</a> state;<br> - int use;<br> -};</p> -<h4 class="members">Members</h4> -<dl> -<dt>attrs </dt> -<dd class="description">Attributes</dd> -<dt>current </dt> -<dd class="description">Current attribute (for read/write)</dd> -<dt>curtag </dt> -<dd class="description">Current attribute group tag</dd> -<dt>last </dt> -<dd class="description">Last attribute in list</dd> -<dt>prev <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> -<dd class="description">Previous attribute (for read) </dd> -<dt>request </dt> -<dd class="description">Request header</dd> -<dt>state </dt> -<dd class="description">State of request</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> -<p class="description">Request Header</p> -<p class="code">union ipp_request_u {<br> -};</p> -<h4 class="members">Members</h4> -<dl> -</dl> -<h3 class="union"><a name="ipp_value_u">ipp_value_u</a></h3> -<p class="description">Attribute Value</p> -<p class="code">union ipp_value_u {<br> - char boolean;<br> - <a href="#ipp_t">ipp_t</a> *collection;<br> - <a href="#ipp_uchar_t">ipp_uchar_t</a> date[11];<br> - int integer;<br> +<h3 class="struct"><a name="pollfd">pollfd</a></h3> +<p class="description">User data (unused)</p> +<p class="code">struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {<br> + void) context;<br> + void) timeout;<br> };</p> <h4 class="members">Members</h4> <dl> -<dt>boolean </dt> -<dd class="description">Boolean value</dd> -<dt>collection <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> -<dd class="description">Collection value </dd> -<dt>date[11] </dt> -<dd class="description">Date/time value</dd> -<dt>integer </dt> -<dd class="description">Integer/enumerated value</dd> +<dt>context </dt> +<dt>timeout </dt> </dl> <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> <h3 class="enumeration"><a name="http_auth_e">http_auth_e</a></h3> @@ -3675,7 +4773,7 @@ with a hostname. </p> <dd class="description">MD5-session authentication in use</dd> <dt>HTTP_AUTH_MD5_SESS_INT </dt> <dd class="description">MD5-session authentication in use for body</dd> -<dt>HTTP_AUTH_NEGOTIATE <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> +<dt>HTTP_AUTH_NEGOTIATE <span class="info"> CUPS 1.3/OS X 10.5 </span></dt> <dd class="description">GSSAPI authentication in use </dd> <dt>HTTP_AUTH_NONE </dt> <dd class="description">No authentication in use</dd> @@ -3868,7 +4966,7 @@ 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> +<dt>HTTP_PKI_ERROR <span class="info"> CUPS 1.5/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> @@ -3960,6 +5058,16 @@ are server-oriented...</p> <dt>HTTP_1_1 </dt> <dd class="description">HTTP/1.1</dd> </dl> +<h3 class="enumeration"><a name="ipp_dstate_e">ipp_dstate_e</a></h3> +<p class="description">Document states</p> +<h4 class="constants">Constants</h4> +<dl> +<dt>IPP_DOCUMENT_ABORTED </dt> +<dt>IPP_DOCUMENT_CANCELED </dt> +<dt>IPP_DOCUMENT_COMPLETED </dt> +<dt>IPP_DOCUMENT_PENDING </dt> +<dt>IPP_DOCUMENT_PROCESSING </dt> +</dl> <h3 class="enumeration"><a name="ipp_finish_e">ipp_finish_e</a></h3> <p class="description">Finishings</p> <h4 class="constants">Constants</h4> @@ -4020,6 +5128,22 @@ are server-oriented...</p> <dd class="description">Staple top right corner</dd> <dt>IPP_FINISHINGS_TRIM </dt> <dd class="description">Trim (any type)</dd> +<dt>IPP_FINISHINGS_TRIM_AFTER_COPIES </dt> +<dd class="description">Trim output after each copy</dd> +<dt>IPP_FINISHINGS_TRIM_AFTER_DOCUMENTS </dt> +<dd class="description">Trim output after each document</dd> +<dt>IPP_FINISHINGS_TRIM_AFTER_JOB </dt> +<dd class="description">Trim output after job</dd> +<dt>IPP_FINISHINGS_TRIM_AFTER_PAGES </dt> +<dd class="description">Trim output after each page</dd> +</dl> +<h3 class="enumeration"><a name="ipp_jcollate_e">ipp_jcollate_e</a></h3> +<p class="description">Job collation types</p> +<h4 class="constants">Constants</h4> +<dl> +<dt>IPP_JOB_COLLATED_DOCUMENTS </dt> +<dt>IPP_JOB_UNCOLLATED_DOCUMENTS </dt> +<dt>IPP_JOB_UNCOLLATED_SHEETS </dt> </dl> <h3 class="enumeration"><a name="ipp_jstate_e">ipp_jstate_e</a></h3> <p class="description">Job states</p> @@ -4050,7 +5174,7 @@ are server-oriented...</p> <dd class="description">Add or modify a class</dd> <dt>CUPS_ADD_MODIFY_PRINTER </dt> <dd class="description">Add or modify a printer</dd> -<dt>CUPS_AUTHENTICATE_JOB <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>CUPS_AUTHENTICATE_JOB <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Authenticate a job </dd> <dt>CUPS_DELETE_CLASS </dt> <dd class="description">Delete a class</dd> @@ -4062,9 +5186,9 @@ are server-oriented...</p> <dd class="description">Get the default printer</dd> <dt>CUPS_GET_DEVICES </dt> <dd class="description">Get a list of supported devices</dd> -<dt>CUPS_GET_DOCUMENT <span class="info"> CUPS 1.4/Mac OS X 10.6 </span></dt> +<dt>CUPS_GET_DOCUMENT <span class="info"> CUPS 1.4/OS X 10.6 </span></dt> <dd class="description">Get a document file </dd> -<dt>CUPS_GET_PPD <span class="info"> CUPS 1.3/Mac OS X 10.5 </span></dt> +<dt>CUPS_GET_PPD <span class="info"> CUPS 1.3/OS X 10.5 </span></dt> <dd class="description">Get a PPD file </dd> <dt>CUPS_GET_PPDS </dt> <dd class="description">Get a list of supported drivers</dd> @@ -4082,15 +5206,15 @@ are server-oriented...</p> <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> +<dt>IPP_CANCEL_SUBSCRIPTION <span class="info"> CUPS 1.2/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> +<dt>IPP_CREATE_JOB_SUBSCRIPTION <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Create a job subscription </dd> -<dt>IPP_CREATE_PRINTER_SUBSCRIPTION <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>IPP_CREATE_PRINTER_SUBSCRIPTION <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Create a printer subscription </dd> <dt>IPP_DISABLE_PRINTER </dt> <dd class="description">Stop a printer</dd> @@ -4100,18 +5224,22 @@ are server-oriented...</p> <dd class="description">Get a list of jobs</dd> <dt>IPP_GET_JOB_ATTRIBUTES </dt> <dd class="description">Get job attributes</dd> -<dt>IPP_GET_NOTIFICATIONS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>IPP_GET_NOTIFICATIONS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Get notification events </dd> <dt>IPP_GET_PRINTER_ATTRIBUTES </dt> <dd class="description">Get printer attributes</dd> <dt>IPP_GET_PRINTER_SUPPORTED_VALUES </dt> <dd class="description">Get supported attribute values</dd> -<dt>IPP_GET_SUBSCRIPTIONS <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>IPP_GET_SUBSCRIPTIONS <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Get list of subscriptions </dd> -<dt>IPP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>IPP_GET_SUBSCRIPTION_ATTRIBUTES <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Get subscription attributes </dd> <dt>IPP_HOLD_JOB </dt> <dd class="description">Hold a job for printing</dd> +<dt>IPP_IDENTIFY_PRINTER </dt> +<dd class="description">Identify-Printer (proposed IPP JPS3)</dd> +<dt>IPP_OP_CUPS_INVALID </dt> +<dd class="description">Invalid operation name for <a href="#ippOpValue"><code>ippOpValue</code></a></dd> <dt>IPP_PAUSE_PRINTER </dt> <dd class="description">Stop a printer</dd> <dt>IPP_PRINT_JOB </dt> @@ -4120,7 +5248,7 @@ are server-oriented...</p> <dd class="description">Cancel all jobs</dd> <dt>IPP_RELEASE_JOB </dt> <dd class="description">Release a job for printing</dd> -<dt>IPP_RENEW_SUBSCRIPTION <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>IPP_RENEW_SUBSCRIPTION <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Renew a printer subscription </dd> <dt>IPP_RESTART_JOB </dt> <dd class="description">Reprint a job</dd> @@ -4132,6 +5260,8 @@ are server-oriented...</p> <dd class="description">Add a file to a job</dd> <dt>IPP_SET_JOB_ATTRIBUTES </dt> <dd class="description">Set job attributes</dd> +<dt>IPP_VALIDATE_DOCUMENT </dt> +<dd class="description">Validate-Document (proposed IPP JPS3)</dd> <dt>IPP_VALIDATE_JOB </dt> <dd class="description">Validate job options</dd> </dl> @@ -4204,7 +5334,7 @@ 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> +<dt>IPP_AUTHENTICATION_CANCELED <span class="info"> CUPS 1.5/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> @@ -4224,14 +5354,20 @@ are server-oriented...</p> <dd class="description">client-error-document-format-not-supported</dd> <dt>IPP_DOCUMENT_FORMAT_ERROR </dt> <dd class="description">client-error-document-format-error</dd> +<dt>IPP_DOCUMENT_PASSWORD_ERROR </dt> +<dd class="description">client-error-document-password-error</dd> +<dt>IPP_DOCUMENT_PERMISSION_ERROR </dt> +<dd class="description">client-error-document-permission-error</dd> +<dt>IPP_DOCUMENT_SECURITY_ERROR </dt> +<dd class="description">client-error-document-security-error</dd> +<dt>IPP_DOCUMENT_UNPRINTABLE_ERROR </dt> +<dd class="description">client-error-document-unprintable-error</dd> <dt>IPP_ERROR_JOB_CANCELED </dt> <dd class="description">server-error-job-canceled</dd> <dt>IPP_FORBIDDEN </dt> <dd class="description">client-error-forbidden</dd> <dt>IPP_GONE </dt> <dd class="description">client-error-gone</dd> -<dt>IPP_IGNORED_ALL_NOTIFICATIONS </dt> -<dd class="description">client-error-ignored-all-notifications</dd> <dt>IPP_IGNORED_ALL_SUBSCRIPTIONS </dt> <dd class="description">client-error-ignored-all-subscriptions</dd> <dt>IPP_INTERNAL_ERROR </dt> @@ -4250,14 +5386,10 @@ are server-oriented...</p> <dd class="description">client-error-not-possible</dd> <dt>IPP_OK </dt> <dd class="description">successful-ok</dd> -<dt>IPP_OK_BUT_CANCEL_SUBSCRIPTION </dt> -<dd class="description">successful-ok-but-cancel-subscription</dd> <dt>IPP_OK_CONFLICT </dt> <dd class="description">successful-ok-conflicting-attributes</dd> <dt>IPP_OK_EVENTS_COMPLETE </dt> <dd class="description">successful-ok-events-complete</dd> -<dt>IPP_OK_IGNORED_NOTIFICATIONS </dt> -<dd class="description">successful-ok-ignored-notifications</dd> <dt>IPP_OK_IGNORED_SUBSCRIPTIONS </dt> <dd class="description">successful-ok-ignored-subscriptions</dd> <dt>IPP_OK_SUBST </dt> @@ -4266,24 +5398,28 @@ 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> +<dt>IPP_PKI_ERROR <span class="info"> CUPS 1.5/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> <dd class="description">server-error-printer-is-deactivated</dd> -<dt>IPP_PRINT_SUPPORT_FILE_NOT_FOUND </dt> -<dd class="description">client-error-print-support-file-not-found</dd> <dt>IPP_REQUEST_ENTITY </dt> <dd class="description">client-error-request-entity-too-large</dd> <dt>IPP_REQUEST_VALUE </dt> <dd class="description">client-error-request-value-too-long</dd> <dt>IPP_SERVICE_UNAVAILABLE </dt> <dd class="description">server-error-service-unavailable</dd> +<dt>IPP_STATUS_CUPS_INVALID </dt> +<dd class="description">Invalid status name for <a href="#ippErrorValue"><code>ippErrorValue</code></a></dd> <dt>IPP_TEMPORARY_ERROR </dt> <dd class="description">server-error-temporary-error</dd> <dt>IPP_TIMEOUT </dt> <dd class="description">client-error-timeout</dd> +<dt>IPP_TOO_MANY_DOCUMENTS </dt> +<dd class="description">server-error-too-many-documents</dd> +<dt>IPP_TOO_MANY_JOBS </dt> +<dd class="description">server-error-too-many-jobs</dd> <dt>IPP_TOO_MANY_SUBSCRIPTIONS </dt> <dd class="description">client-error-too-many-subscriptions</dd> <dt>IPP_UPGRADE_REQUIRED </dt> @@ -4305,14 +5441,16 @@ are server-oriented...</p> <dd class="description">Boolean value</dd> <dt>IPP_TAG_CHARSET </dt> <dd class="description">Character set value</dd> -<dt>IPP_TAG_COPY </dt> -<dd class="description">Bitflag for copied attribute values</dd> +<dt>IPP_TAG_CUPS_INVALID </dt> +<dd class="description">Invalid tag name for <a href="#ippTagValue"><code>ippTagValue</code></a></dd> <dt>IPP_TAG_DATE </dt> <dd class="description">Date/time value</dd> <dt>IPP_TAG_DEFAULT </dt> <dd class="description">Default value</dd> <dt>IPP_TAG_DELETEATTR </dt> <dd class="description">Delete-attribute value</dd> +<dt>IPP_TAG_DOCUMENT </dt> +<dd class="description">Document group</dd> <dt>IPP_TAG_END </dt> <dd class="description">End-of-attributes</dd> <dt>IPP_TAG_END_COLLECTION </dt> @@ -4321,6 +5459,8 @@ are server-oriented...</p> <dd class="description">Enumeration value</dd> <dt>IPP_TAG_EVENT_NOTIFICATION </dt> <dd class="description">Event group</dd> +<dt>IPP_TAG_EXTENSION </dt> +<dd class="description">Extension point for 32-bit tags</dd> <dt>IPP_TAG_INTEGER </dt> <dd class="description">Integer value</dd> <dt>IPP_TAG_JOB </dt> @@ -4329,8 +5469,6 @@ are server-oriented...</p> <dd class="description">Keyword value</dd> <dt>IPP_TAG_LANGUAGE </dt> <dd class="description">Language value</dd> -<dt>IPP_TAG_MASK </dt> -<dd class="description">Mask for copied attribute values</dd> <dt>IPP_TAG_MEMBERNAME </dt> <dd class="description">Collection member name value</dd> <dt>IPP_TAG_MIMETYPE </dt> diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html index ae32165d..1be3ed13 100644 --- a/doc/help/api-ppd.html +++ b/doc/help/api-ppd.html @@ -2,7 +2,7 @@ <html> <!-- SECTION: Programming --> <head> - <title>PPD API </title> + <title>PPD API (DEPRECATED) </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"> @@ -341,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-ppd.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-ppd.html 10441 2012-04-30 20:59:09Z mike $" PPD API header for CUPS. - Copyright 2008-2011 by Apple Inc. + Copyright 2008-2012 by Apple Inc. These coded instructions, statements, and computer programs are the property of Apple Inc. and are protected by Federal copyright @@ -354,7 +354,9 @@ div.contents ul.subcontents li { file is missing or damaged, see the license at "http://www.cups.org/". --> -<h1 class='title'>PPD API</h1> +<h1 class='title'>PPD API (DEPRECATED)</h1> + +<blockquote>The PPD API is deprecated starting in CUPS 1.6/OS X 10.8. Please use the new Job Ticket APIs in the <a href="api-cups.html">CUPS API</a> documentation. These functions will be removed in a future release of CUPS.</blockquote> <div class='summary'><table summary='General Information'> <thead> @@ -432,7 +434,7 @@ conflicts.">ppdMarkOption</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="#ppdPageSize" title="Get the page size record for the named 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> @@ -484,11 +486,11 @@ conflicts.">ppdMarkOption</a></li> </ul></li> </ul> <!-- - "$Id: api-ppd.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-ppd.html 10441 2012-04-30 20:59:09Z mike $" PPD API introduction for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -500,6 +502,8 @@ conflicts.">ppdMarkOption</a></li> <h2 class='title'><a name='OVERVIEW'>Overview</a></h2> +<blockquote>The PPD API is deprecated starting in CUPS 1.6/OS X 10.8. Please use the new Job Ticket APIs in the <a href="api-cups.html">CUPS API</a> documentation. These functions will be removed in a future release of CUPS.</blockquote> + <p>The CUPS PPD API provides read-only access the data in PostScript Printer Description ("PPD") files which are used for all printers with a driver. With it you can obtain the data necessary to display printer options to users, mark @@ -701,7 +705,7 @@ for (attr = <a href="#ppdFindAttr">ppdFindAttr</a>(ppd, "Product", NULL); puts(attr->value); </pre> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="cupsGetConflicts">cupsGetConflicts</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsGetConflicts">cupsGetConflicts</a></h3> <p class="description">Get a list of conflicting options in a marked PPD.</p> <p class="code"> int cupsGetConflicts (<br> @@ -758,7 +762,7 @@ int cupsMarkOptions (<br> "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> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="cupsResolveConflicts">cupsResolveConflicts</a></h3> <p class="description">Resolve conflicts in a marked PPD.</p> <p class="code"> int cupsResolveConflicts (<br> @@ -850,7 +854,7 @@ int ppdCollect (<br> <h4 class="discussion">Discussion</h4> <p class="discussion">The choices array should be freed using <code>free</code> when you are finished with it.</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdCollect2">ppdCollect2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdCollect2">ppdCollect2</a></h3> <p class="description">Collect all marked options that reside in the specified section and minimum order.</p> <p class="code"> @@ -913,7 +917,7 @@ int ppdEmit (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdEmitAfterOrder">ppdEmitAfterOrder</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdEmitAfterOrder">ppdEmitAfterOrder</a></h3> <p class="description">Emit a subset of the code for marked options to a file.</p> <p class="code"> int ppdEmitAfterOrder (<br> @@ -989,7 +993,7 @@ int ppdEmitJCL (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdEmitJCLEnd">ppdEmitJCLEnd</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdEmitJCLEnd">ppdEmitJCLEnd</a></h3> <p class="description">Emit JCLEnd code to a file.</p> <p class="code"> int ppdEmitJCLEnd (<br> @@ -1005,7 +1009,7 @@ int ppdEmitJCLEnd (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">0 on success, -1 on failure</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdEmitString">ppdEmitString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdEmitString">ppdEmitString</a></h3> <p class="description">Get a string containing the code for marked options.</p> <p class="code"> char *ppdEmitString (<br> @@ -1034,7 +1038,7 @@ The return string is allocated on the heap and should be freed using <code>free</code> when you are done with it. </p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppdErrorString">ppdErrorString</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppdErrorString">ppdErrorString</a></h3> <p class="description">Returns the text assocated with a status.</p> <p class="code"> const char *ppdErrorString (<br> @@ -1047,7 +1051,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status string</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppdFindAttr">ppdFindAttr</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppdFindAttr">ppdFindAttr</a></h3> <p class="description">Find the first matching attribute.</p> <p class="code"> <a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindAttr (<br> @@ -1082,7 +1086,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Choice pointer or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdFindCustomOption">ppdFindCustomOption</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdFindCustomOption">ppdFindCustomOption</a></h3> <p class="description">Find a custom option.</p> <p class="code"> <a href="#ppd_coption_t">ppd_coption_t</a> *ppdFindCustomOption (<br> @@ -1098,7 +1102,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Custom option or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdFindCustomParam">ppdFindCustomParam</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdFindCustomParam">ppdFindCustomParam</a></h3> <p class="description">Find a parameter for a custom option.</p> <p class="code"> <a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFindCustomParam (<br> @@ -1130,7 +1134,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Pointer to choice or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppdFindNextAttr">ppdFindNextAttr</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppdFindNextAttr">ppdFindNextAttr</a></h3> <p class="description">Find the next matching attribute.</p> <p class="code"> <a href="#ppd_attr_t">ppd_attr_t</a> *ppdFindNextAttr (<br> @@ -1165,7 +1169,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Pointer to option or <code>NULL</code></p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdFirstCustomParam">ppdFirstCustomParam</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdFirstCustomParam">ppdFirstCustomParam</a></h3> <p class="description">Return the first parameter for a custom option.</p> <p class="code"> <a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdFirstCustomParam (<br> @@ -1178,7 +1182,7 @@ const char *ppdErrorString (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Custom parameter or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdFirstOption">ppdFirstOption</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdFirstOption">ppdFirstOption</a></h3> <p class="description">Return the first option in the PPD file.</p> <p class="code"> <a href="#ppd_option_t">ppd_option_t</a> *ppdFirstOption (<br> @@ -1195,7 +1199,7 @@ const char *ppdErrorString (<br> <p class="discussion">Options are returned from all groups in ascending alphanumeric order. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="ppdInstallableConflict">ppdInstallableConflict</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="ppdInstallableConflict">ppdInstallableConflict</a></h3> <p class="description">Test whether an option choice conflicts with an installable option.</p> <p class="code"> @@ -1239,7 +1243,7 @@ int ppdIsMarked (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Non-zero if option is marked</p> -<h3 class="function"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppdLastError">ppdLastError</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppdLastError">ppdLastError</a></h3> <p class="description">Return the status from the last ppdOpen*().</p> <p class="code"> <a href="#ppd_status_t">ppd_status_t</a> ppdLastError (<br> @@ -1252,7 +1256,7 @@ int ppdIsMarked (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Status code</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdLocalize">ppdLocalize</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdLocalize">ppdLocalize</a></h3> <p class="description">Localize the PPD file to the current locale.</p> <p class="code"> int ppdLocalize (<br> @@ -1294,7 +1298,7 @@ localized string uses the UTF-8 character encoding. <p class="discussion">This function uses the current locale to find the localized attribute for the given main and option keywords. If no localized version of the attribute exists for the current locale, the unlocalized version is returned.</p> -<h3 class="function"><span class="info"> CUPS 1.3/Mac OS X 10.5 </span><a name="ppdLocalizeIPPReason">ppdLocalizeIPPReason</a></h3> +<h3 class="function"><span class="info"> CUPS 1.3/OS X 10.5 </span><a name="ppdLocalizeIPPReason">ppdLocalizeIPPReason</a></h3> <p class="description">Get the localized version of a cupsIPPReason attribute.</p> <p class="code"> @@ -1329,7 +1333,7 @@ string or attribute value. Otherwise the corresponding URI is returned.<br> If no value of the requested scheme can be found, NULL is returned. </p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="ppdLocalizeMarkerName">ppdLocalizeMarkerName</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="ppdLocalizeMarkerName">ppdLocalizeMarkerName</a></h3> <p class="description">Get the localized version of a marker-names attribute value.</p> <p class="code"> @@ -1383,7 +1387,7 @@ int ppdMarkOption (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Number of conflicts</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdNextCustomParam">ppdNextCustomParam</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdNextCustomParam">ppdNextCustomParam</a></h3> <p class="description">Return the next parameter for a custom option.</p> <p class="code"> <a href="#ppd_cparam_t">ppd_cparam_t</a> *ppdNextCustomParam (<br> @@ -1396,7 +1400,7 @@ int ppdMarkOption (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Custom parameter or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdNextOption">ppdNextOption</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdNextOption">ppdNextOption</a></h3> <p class="description">Return the next option in the PPD file.</p> <p class="code"> <a href="#ppd_option_t">ppd_option_t</a> *ppdNextOption (<br> @@ -1426,7 +1430,7 @@ int ppdMarkOption (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">PPD file record</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppdOpen2">ppdOpen2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppdOpen2">ppdOpen2</a></h3> <p class="description">Read a PPD file into memory.</p> <p class="code"> <a href="#ppd_file_t">ppd_file_t</a> *ppdOpen2 (<br> @@ -1482,7 +1486,7 @@ float ppdPageLength (<br> <h4 class="returnvalue">Return Value</h4> <p class="description">Length of page in points or 0.0</p> <h3 class="function"><a name="ppdPageSize">ppdPageSize</a></h3> -<p class="description">Get the page size record for the given size.</p> +<p class="description">Get the page size record for the named size.</p> <p class="code"> <a href="#ppd_size_t">ppd_size_t</a> *ppdPageSize (<br> <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br> @@ -1497,7 +1501,7 @@ float ppdPageLength (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Size record for page or NULL</p> -<h3 class="function"><span class="info"> CUPS 1.4/Mac OS X 10.6 </span><a name="ppdPageSizeLimits">ppdPageSizeLimits</a></h3> +<h3 class="function"><span class="info"> CUPS 1.4/OS X 10.6 </span><a name="ppdPageSizeLimits">ppdPageSizeLimits</a></h3> <p class="description">Return the custom page size limits.</p> <p class="code"> int ppdPageSizeLimits (<br> @@ -1540,7 +1544,7 @@ float ppdPageWidth (<br> </dl> <h4 class="returnvalue">Return Value</h4> <p class="description">Width of page in points or 0.0</p> -<h3 class="function"><span class="info"> CUPS 1.1.20/Mac OS X 10.4 </span><a name="ppdSetConformance">ppdSetConformance</a></h3> +<h3 class="function"><span class="info"> CUPS 1.1.20/OS X 10.4 </span><a name="ppdSetConformance">ppdSetConformance</a></h3> <p class="description">Set the conformance level for PPD files.</p> <p class="code"> void ppdSetConformance (<br> @@ -1552,7 +1556,7 @@ void ppdSetConformance (<br> <dd class="description">Conformance level</dd> </dl> <h2 class="title"><a name="TYPES">Data Types</a></h2> -<h3 class="typedef"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_attr_t">ppd_attr_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_attr_t">ppd_attr_t</a></h3> <p class="description">PPD Attribute Structure </p> <p class="code"> typedef struct <a href="#ppd_attr_s">ppd_attr_s</a> ppd_attr_t; @@ -1562,7 +1566,7 @@ typedef struct <a href="#ppd_attr_s">ppd_attr_s</a> ppd_attr_t; <p class="code"> typedef struct <a href="#ppd_choice_s">ppd_choice_s</a> ppd_choice_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_conform_t">ppd_conform_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_conform_t">ppd_conform_t</a></h3> <p class="description">Conformance Levels </p> <p class="code"> typedef enum <a href="#ppd_conform_e">ppd_conform_e</a> ppd_conform_t; @@ -1572,27 +1576,27 @@ typedef enum <a href="#ppd_conform_e">ppd_conform_e</a> ppd_conform_t; <p class="code"> typedef struct <a href="#ppd_const_s">ppd_const_s</a> ppd_const_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_coption_t">ppd_coption_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_coption_t">ppd_coption_t</a></h3> <p class="description">Custom Option </p> <p class="code"> typedef struct <a href="#ppd_coption_s">ppd_coption_s</a> ppd_coption_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cparam_t">ppd_cparam_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cparam_t">ppd_cparam_t</a></h3> <p class="description">Custom Parameter </p> <p class="code"> typedef struct <a href="#ppd_cparam_s">ppd_cparam_s</a> ppd_cparam_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cplimit_t">ppd_cplimit_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cplimit_t">ppd_cplimit_t</a></h3> <p class="description">Custom Parameter Limit </p> <p class="code"> typedef union <a href="#ppd_cplimit_u">ppd_cplimit_u</a> ppd_cplimit_t; </p> -<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> +<h3 class="typedef"><span class="info"> CUPS 1.2/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 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> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cpvalue_t">ppd_cpvalue_t</a></h3> <p class="description">Custom Parameter Value </p> <p class="code"> typedef union <a href="#ppd_cpvalue_u">ppd_cpvalue_u</a> ppd_cpvalue_t; @@ -1637,7 +1641,7 @@ typedef enum <a href="#ppd_section_e">ppd_section_e</a> ppd_section_t; <p class="code"> typedef struct <a href="#ppd_size_s">ppd_size_s</a> ppd_size_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_status_t">ppd_status_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_status_t">ppd_status_t</a></h3> <p class="description">Status Codes </p> <p class="code"> typedef enum <a href="#ppd_status_e">ppd_status_e</a> ppd_status_t; @@ -1648,7 +1652,7 @@ typedef enum <a href="#ppd_status_e">ppd_status_e</a> ppd_status_t; typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; </p> <h2 class="title"><a name="STRUCTURES">Structures</a></h2> -<h3 class="struct"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_attr_s">ppd_attr_s</a></h3> +<h3 class="struct"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_attr_s">ppd_attr_s</a></h3> <p class="description">PPD Attribute Structure </p> <p class="code">struct ppd_attr_s {<br> char name[PPD_MAX_NAME];<br> @@ -1708,7 +1712,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dt>option2[PPD_MAX_NAME] </dt> <dd class="description">Second keyword</dd> </dl> -<h3 class="struct"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_coption_s">ppd_coption_s</a></h3> +<h3 class="struct"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_coption_s">ppd_coption_s</a></h3> <p class="description">Custom Option </p> <p class="code">struct ppd_coption_s {<br> char keyword[PPD_MAX_NAME];<br> @@ -1727,7 +1731,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dt>params </dt> <dd class="description">Parameters</dd> </dl> -<h3 class="struct"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cparam_s">ppd_cparam_s</a></h3> +<h3 class="struct"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cparam_s">ppd_cparam_s</a></h3> <p class="description">Custom Parameter </p> <p class="code">struct ppd_cparam_s {<br> <a href="#ppd_cpvalue_t">ppd_cpvalue_t</a> current;<br> @@ -1882,13 +1886,13 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dd class="description">Number of page sizes</dd> <dt>patches </dt> <dd class="description">Patch commands to be sent to printer</dd> -<dt>pcfilename <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>pcfilename <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">PCFileName string </dd> <dt>product </dt> <dd class="description">Product name (from PS RIP/interpreter)</dd> <dt>profiles <span class="info"> DEPRECATED </span></dt> <dd class="description">sRGB color profiles </dd> -<dt>protocols <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>protocols <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">Protocols (BCP, TBCP) string </dd> <dt>shortnickname </dt> <dd class="description">Short version of nickname</dd> @@ -1915,7 +1919,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dl> <dt>PPD_MAX_NAME] </dt> <dd class="description">Human-readable group name</dd> -<dt>name[PPD_MAX_NAME] <span class="info"> CUPS 1.1.18/Mac OS X 10.3 </span></dt> +<dt>name[PPD_MAX_NAME] <span class="info"> CUPS 1.1.18/OS X 10.3 </span></dt> <dd class="description">Group name </dd> <dt>num_options </dt> <dd class="description">Number of options</dd> @@ -2014,7 +2018,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dd class="description">Width of media in points</dd> </dl> <h2 class="title"><a name="UNIONS">Unions</a></h2> -<h3 class="union"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cplimit_u">ppd_cplimit_u</a></h3> +<h3 class="union"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cplimit_u">ppd_cplimit_u</a></h3> <p class="description">Custom Parameter Limit </p> <p class="code">union ppd_cplimit_u {<br> float custom_curve;<br> @@ -2045,7 +2049,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dt>custom_string </dt> <dd class="description">String length</dd> </dl> -<h3 class="union"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="ppd_cpvalue_u">ppd_cpvalue_u</a></h3> +<h3 class="union"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="ppd_cpvalue_u">ppd_cpvalue_u</a></h3> <p class="description">Custom Parameter Value </p> <p class="code">union ppd_cpvalue_u {<br> float custom_curve;<br> @@ -2077,7 +2081,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dd class="description">String value</dd> </dl> <h2 class="title"><a name="ENUMERATIONS">Constants</a></h2> -<h3 class="enumeration"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_conform_e">ppd_conform_e</a></h3> +<h3 class="enumeration"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_conform_e">ppd_conform_e</a></h3> <p class="description">Conformance Levels </p> <h4 class="constants">Constants</h4> <dl> @@ -2120,7 +2124,7 @@ typedef enum <a href="#ppd_ui_e">ppd_ui_e</a> ppd_ui_t; <dt>PPD_ORDER_PROLOG </dt> <dd class="description">... must be in the Prolog section</dd> </dl> -<h3 class="enumeration"><span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span><a name="ppd_status_e">ppd_status_e</a></h3> +<h3 class="enumeration"><span class="info"> CUPS 1.1.19/OS X 10.3 </span><a name="ppd_status_e">ppd_status_e</a></h3> <p class="description">Status Codes </p> <h4 class="constants">Constants</h4> <dl> diff --git a/doc/help/api-ppdc.html b/doc/help/api-ppdc.html index cb15f61e..25ccef40 100644 --- a/doc/help/api-ppdc.html +++ b/doc/help/api-ppdc.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-ppdc.html 9740 2011-05-04 06:26:22Z mike $" + "$Id: api-ppdc.html 10356 2012-03-16 16:03:10Z mike $" PPD Compiler API header for CUPS. @@ -414,7 +414,7 @@ div.contents ul.subcontents li { </ul></li> </ul> <!-- - "$Id: api-ppdc.html 9740 2011-05-04 06:26:22Z mike $" + "$Id: api-ppdc.html 10356 2012-03-16 16:03:10Z mike $" PPD Compiler API introduction for CUPS. @@ -1016,12 +1016,15 @@ void ~ppdcDriver (void);</p> <p class="description">// File</p> <p class="code">class ppdcFile {<br> public:<br> + bool close_on_delete;<br> const char *filename;<br> cups_file_t *fp;<br> int line;<br> };</p> <h4 class="members">Members</h4> <dl> +<dt>close_on_delete </dt> +<dd class="description">Close file on delete?</dd> <dt>filename </dt> <dd class="description">Filename</dd> <dt>fp </dt> diff --git a/doc/help/api-raster.html b/doc/help/api-raster.html index f193d07e..4a77da3c 100644 --- a/doc/help/api-raster.html +++ b/doc/help/api-raster.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: api-raster.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-raster.html 10424 2012-04-23 17:26:57Z mike $" Raster API documentation for CUPS. @@ -434,11 +434,11 @@ page header structure.">cupsRasterWriteHeader2</a></li> </ul></li> </ul> <!-- - "$Id: api-raster.html 9772 2011-05-12 05:46:30Z mike $" + "$Id: api-raster.html 10424 2012-04-23 17:26:57Z mike $" Raster API introduction for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -457,7 +457,7 @@ avoid incompatibilities with newer versions of CUPS.</p> <p>Two kinds of CUPS filters use the CUPS raster API - raster image processor (RIP) filters such as <code>pstoraster</code> and <code>cgpdftoraster</code> -(Mac OS X) that produce CUPS raster files and printer driver filters that +(OS X) that produce CUPS raster files and printer driver filters that convert CUPS raster files into a format usable by the printer. Printer driver filters are by far the most common.</p> @@ -577,7 +577,7 @@ the memory used to read the raster file:</p> <ul class="code"> - <li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a version 1 page header structure.">cupsRasterReadHeader</a> <span class="info">Deprecated in CUPS 1.2/Mac OS X 10.5</span></li> + <li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a version 1 page header structure.">cupsRasterReadHeader</a> <span class="info">Deprecated in CUPS 1.2/OS X 10.5</span></li> <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> @@ -588,10 +588,10 @@ the memory used to read the raster file:</p> <ul class="code"> <li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li> - <li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page header structure.">cupsRasterWriteHeader</a> <span class="info">Deprecated in CUPS 1.2/Mac OS X 10.5</span></li> + <li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page header structure.">cupsRasterWriteHeader</a> <span class="info">Deprecated in CUPS 1.2/OS X 10.5</span></li> <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> - + </ul> <h2 class="title"><a name="FUNCTIONS">Functions</a></h2> <h3 class="function"><a name="cupsRasterClose">cupsRasterClose</a></h3> @@ -608,7 +608,7 @@ void cupsRasterClose (<br> <h4 class="discussion">Discussion</h4> <p class="discussion">The file descriptor associated with the raster stream must be closed separately as needed.</p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterInterpretPPD">cupsRasterInterpretPPD</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsRasterInterpretPPD">cupsRasterInterpretPPD</a></h3> <p class="description">Interpret PPD commands to create a page header.</p> <p class="code"> int cupsRasterInterpretPPD (<br> @@ -743,7 +743,7 @@ of the version 2 page header data. This function handles reading version 2 page headers and copying only the version 1 data into the provided buffer. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterReadHeader2">cupsRasterReadHeader2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsRasterReadHeader2">cupsRasterReadHeader2</a></h3> <p class="description">Read a raster page header and store it in a version 2 page header structure.</p> <p class="code"> @@ -804,7 +804,7 @@ unsigned cupsRasterWriteHeader (<br> <p class="discussion">This function is deprecated. Use <a href="#cupsRasterWriteHeader2"><code>cupsRasterWriteHeader2</code></a> instead. </p> -<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></h3> +<h3 class="function"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></h3> <p class="description">Write a raster page header from a version 2 page header structure.</p> <p class="code"> @@ -899,7 +899,7 @@ typedef enum <a href="#cups_order_e">cups_order_e</a> cups_order_t; <p class="code"> typedef enum <a href="#cups_orient_e">cups_orient_e</a> cups_orient_t; </p> -<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cups_page_header2_t">cups_page_header2_t</a></h3> +<h3 class="typedef"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cups_page_header2_t">cups_page_header2_t</a></h3> <p class="description">Version 2 page header </p> <p class="code"> typedef struct <a href="#cups_page_header2_s">cups_page_header2_s</a> cups_page_header2_t; @@ -920,7 +920,7 @@ typedef ssize_t (*cups_raster_iocb_t)(void *ctx, unsigned char *buffer, size_t l typedef struct _cups_raster_s cups_raster_t; </p> <h2 class="title"><a name="STRUCTURES">Structures</a></h2> -<h3 class="struct"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cups_page_header2_s">cups_page_header2_s</a></h3> +<h3 class="struct"><span class="info"> CUPS 1.2/OS X 10.5 </span><a name="cups_page_header2_s">cups_page_header2_s</a></h3> <p class="description">Version 2 page header </p> <p class="code">struct cups_page_header2_s {<br> unsigned AdvanceDistance;<br> @@ -1033,7 +1033,7 @@ typedef struct _cups_raster_s cups_raster_t; <dd class="description">Number of bits for each color</dd> <dt>cupsBitsPerPixel </dt> <dd class="description">Number of bits for each pixel</dd> -<dt>cupsBorderlessScalingFactor <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsBorderlessScalingFactor <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Scaling that was applied to page data </dd> <dt>cupsBytesPerLine </dt> <dd class="description">Number of bytes per line</dd> @@ -1045,26 +1045,26 @@ typedef struct _cups_raster_s cups_raster_t; <dd class="description">Device compression to use</dd> <dt>cupsHeight </dt> <dd class="description">Height of page image in pixels</dd> -<dt>cupsImagingBBox[4] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsImagingBBox[4] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Floating point ImagingBoundingBox (scaling factor not applied, left, bottom, right, top) </dd> -<dt>cupsInteger[16] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsInteger[16] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">User-defined integer values </dd> -<dt>cupsMarkerType[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsMarkerType[64] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Ink/toner type </dd> <dt>cupsMediaType </dt> <dd class="description">Media type code</dd> -<dt>cupsNumColors <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsNumColors <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Number of color compoents </dd> -<dt>cupsPageSizeName[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsPageSizeName[64] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">PageSize name </dd> -<dt>cupsPageSize[2] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsPageSize[2] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Floating point PageSize (scaling * factor not applied) </dd> -<dt>cupsReal[16] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsReal[16] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">User-defined floating-point values </dd> -<dt>cupsRenderingIntent[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsRenderingIntent[64] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Color rendering intent </dd> <dt>cupsRowCount </dt> <dd class="description">Rows per band</dd> @@ -1072,7 +1072,7 @@ factor not applied) </dd> <dd class="description">Feed between bands</dd> <dt>cupsRowStep </dt> <dd class="description">Spacing between lines</dd> -<dt>cupsString[16][64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>cupsString[16][64] <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">User-defined string values </dd> <dt>cupsWidth </dt> <dd class="description">Width of page image in pixels</dd> @@ -1232,9 +1232,9 @@ factor not applied) </dd> <dl> <dt>CUPS_CSPACE_ADOBERGB <span class="info"> CUPS 1.4.5 </span></dt> <dd class="description">Red, green, blue (Adobe RGB) </dd> -<dt>CUPS_CSPACE_CIELab <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_CIELab <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">CIE Lab </dd> -<dt>CUPS_CSPACE_CIEXYZ <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_CIEXYZ <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">CIE XYZ </dd> <dt>CUPS_CSPACE_CMY </dt> <dd class="description">Cyan, magenta, yellow (DeviceCMY)</dd> @@ -1276,35 +1276,35 @@ factor not applied) </dd> <dd class="description">Gold, magenta, yellow, silver </dd> <dt>CUPS_CSPACE_GOLD <span class="info"> DEPRECATED </span></dt> <dd class="description">Gold foil </dd> -<dt>CUPS_CSPACE_ICC1 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC1 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 1 color </dd> -<dt>CUPS_CSPACE_ICC2 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC2 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 2 colors </dd> -<dt>CUPS_CSPACE_ICC3 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC3 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 3 colors </dd> -<dt>CUPS_CSPACE_ICC4 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC4 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 4 colors </dd> -<dt>CUPS_CSPACE_ICC5 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC5 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 5 colors </dd> -<dt>CUPS_CSPACE_ICC6 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC6 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 6 colors </dd> -<dt>CUPS_CSPACE_ICC7 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC7 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 7 colors </dd> -<dt>CUPS_CSPACE_ICC8 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC8 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 8 colors </dd> -<dt>CUPS_CSPACE_ICC9 <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICC9 <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 9 colors </dd> -<dt>CUPS_CSPACE_ICCA <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCA <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 10 colors </dd> -<dt>CUPS_CSPACE_ICCB <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCB <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 11 colors </dd> -<dt>CUPS_CSPACE_ICCC <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCC <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 12 colors </dd> -<dt>CUPS_CSPACE_ICCD <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCD <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 13 colors </dd> -<dt>CUPS_CSPACE_ICCE <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCE <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 14 colors </dd> -<dt>CUPS_CSPACE_ICCF <span class="info"> CUPS 1.1.19/Mac OS X 10.3 </span></dt> +<dt>CUPS_CSPACE_ICCF <span class="info"> CUPS 1.1.19/OS X 10.3 </span></dt> <dd class="description">ICC-based, 15 colors </dd> <dt>CUPS_CSPACE_K </dt> <dd class="description">Black (DeviceK)</dd> @@ -1316,7 +1316,7 @@ factor not applied) </dd> <dd class="description">Red, green, blue (DeviceRGB, sRGB by default)</dd> <dt>CUPS_CSPACE_RGBA </dt> <dd class="description">Red, green, blue, alpha (DeviceRGB, sRGB by default)</dd> -<dt>CUPS_CSPACE_RGBW <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt> +<dt>CUPS_CSPACE_RGBW <span class="info"> CUPS 1.2/OS X 10.5 </span></dt> <dd class="description">Red, green, blue, white (DeviceRGB, sRGB by default) </dd> <dt>CUPS_CSPACE_SILVER <span class="info"> DEPRECATED </span></dt> <dd class="description">Silver foil </dd> @@ -1382,9 +1382,9 @@ factor not applied) </dd> <dd class="description">Open stream for reading</dd> <dt>CUPS_RASTER_WRITE </dt> <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> +<dt>CUPS_RASTER_WRITE_COMPRESSED <span class="info"> CUPS 1.3/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> +<dt>CUPS_RASTER_WRITE_PWG <span class="info"> CUPS 1.5/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> diff --git a/doc/help/kerberos.html b/doc/help/kerberos.html index cb8b88c2..30fb5336 100644 --- a/doc/help/kerberos.html +++ b/doc/help/kerberos.html @@ -46,7 +46,7 @@ DNS server(s).</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> + on OS X Frequently Asked Questions</A></LI> </UL> diff --git a/doc/help/license.html b/doc/help/license.html index 2b7c2460..9bbc729e 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-2011 by Apple Inc.<BR> +<P ALIGN="CENTER">Copyright 2007-2012 by Apple Inc.<BR> 1 Infinite Loop<BR> Cupertino, CA 95014 USA<BR> <BR> @@ -91,11 +91,10 @@ the following special exceptions:</P> <LI>An Apple Operating System means any operating system software developed and/or - marketed by Apple Computer, Inc., including but - not limited to all existing releases and - versions of Apple's Darwin, Mac OS X, and Mac OS - X Server products and all follow-on releases and - future versions thereof.</LI> + marketed by Apple Inc., including but not limited + to all existing releases and versions of Apple's + Darwin, OS X, and OS X Server products and all + follow-on releases and future versions thereof.</LI> <LI>This exception is only available for Apple OS-Developed Software and does not apply to diff --git a/doc/help/man-ipptool.html b/doc/help/man-ipptool.html new file mode 100644 index 00000000..1b523c53 --- /dev/null +++ b/doc/help/man-ipptool.html @@ -0,0 +1,157 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- SECTION: Man Pages --> +<head> + <link rel="stylesheet" type="text/css" href="../cups-printable.css"> + <title>ipptool(1)</title> +</head> +<body> +<h1 class="title">ipptool(1)</h1> +<h2 class="title"><a name="NAME">Name</a></h2> +ipptool - perform internet printing protocol requests +<h2 class="title"><a name="SYNOPSIS">Synopsis</a></h2> +<b>ipptool +</b>[ -4 ] [ -6 ] [ -C ] [ -E ] [ -I ] [ -L ] [ -S ] [ -T +<i>seconds +</i>] [ -V +<i>version +</i>] [ -X ] [ -c ] [ -d +<i>name=value +</i>] [ -f +<i>filename +</i>] [ -i +<i>seconds +</i>] [ -n +<i>repeat-count +</i>] [ -q ] [ -t ] [ -v ] +<i>URI +</i><i>filename +</i>[ +<i>... filenameN +</i>] +<h2 class="title"><a name="DESCRIPTION">Description</a></h2> +<i>ipptool</i> sends IPP requests to the specified URI and tests and/or displays the results. Each named file defines one or more requests, including the expected response status, attributes, and values. Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. The file format is described in <a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>. +<h2 class="title"><a name="OPTIONS">Options</a></h2> +The following options are recognized by <i>ipptool</i>: +<dl> +<dt>-4 +</dt> +<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv4. +</dd> +<dt>-6 +</dt> +<dd>Specifies that <i>ipptool</i> must connect to the printer or server using IPv6. +</dd> +<dt>-C +</dt> +<dd>Specifies that requests should be sent using the HTTP/1.1 "Transfer-Encoding: chunked" header, which is required for conformance by all versions of IPP. The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files. +</dd> +<dt>-E +</dt> +<dd>Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header. +</dd> +<dt>-I +</dt> +<dd>Specifies that <i>ipptool</i> will continue past errors. +</dd> +<dt>-L +</dt> +<dd>Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP. The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files. +</dd> +<dt>-S +</dt> +<dd>Forces (dedicated) SSL encryption when connecting to the server. +</dd> +<dt>-T seconds +</dt> +<dd>Specifies a timeout for IPP requests in seconds. +</dd> +<dt>-V version +</dt> +<dd>Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used. +</dd> +<dt>-X +</dt> +<dd>Specifies that XML (Apple plist) output is desired instead of the plain text report. This option is incompatible with the <i>-i</i> (interval) and <i>-n</i> (repeat-count) options. +</dd> +<dt>-c +</dt> +<dd>Specifies that CSV (comma-separated values) output is desired instead of the plain text output. +</dd> +<dt>-d name=value +</dt> +<dd>Defines the named variable. +</dd> +<dt>-f filename +</dt> +<dd>Defines the default request filename for tests. +</dd> +<dt>-i seconds +</dt> +<dd>Specifies that the (last) file should be repeated at the specified interval. This option is incompatible with the <i>-X</i> (XML plist output) option. +</dd> +<dt>-l +</dt> +<dd>Specifies that plain text output is desired. +</dd> +<dt>-n repeat-count +</dt> +<dd>Specifies that the (last) file should be repeated the specified number of times. This option is incompatible with the <i>-X</i> (XML plist output) option. +</dd> +<dt>-t +</dt> +<dd>Specifies that CUPS test report output is desired instead of the plain text output. +</dd> +<dt>-v +</dt> +<dd>Specifies that all request and response attributes should be output in CUPS test mode (<i>-t</i>). This is the default for XML output. +</dd> +</dl> +<h2 class="title"><a name="COMPATIBILITY">Compatibility</a></h2> +The <i>ipptool</i> program is unique to CUPS. +<h2 class="title"><a name="EXAMPLES">Examples</a></h2> +Get a list of completed jobs for "myprinter": +<pre> + ipptool ipp://localhost/printers/myprinter get-completed-jobs.test +</pre> +<p>Send email notifications to "user@example.com" when "myprinter" changes: +<pre> + ipptool -d recipient=mailto:user@example.com + ipp://localhost/printers/myprinter create-printer-subscription.test +</pre> +<h2 class="title"><a name="STANDARD_FILES">Standard Files</a></h2> +The following standard files are available: +<pre> + color.jpg + create-printer-subscription.test + document-a4.pdf + document-a4.ps + document-letter.pdf + document-letter.ps + get-completed-jobs.test + get-jobs.test + get-printer-attributes.test + gray.jpg + ipp-1.1.test + ipp-2.0.test + ipp-2.1.test + ipp-2.2.test + onepage-a4.pdf + onepage-a4.ps + onepage-letter.pdf + onepage-letter.ps + print-job.test + testfile.jpg + testfile.pdf + testfile.ps + testfile.txt +</pre> +<h2 class="title"><a name="SEE_ALSO">See Also</a></h2> +<a href='man-ipptoolfile.html?TOPIC=Man+Pages'>ipptoolfile(5)</a>, +<br> +<a href='http://localhost:631/help'>http://localhost:631/help</a> +<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> +Copyright 2007-2012 by Apple Inc. + +</body> +</html> diff --git a/doc/help/man-ipptoolfile.html b/doc/help/man-ipptoolfile.html new file mode 100644 index 00000000..645fd4a1 --- /dev/null +++ b/doc/help/man-ipptoolfile.html @@ -0,0 +1,668 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- SECTION: Man Pages --> +<head> + <link rel="stylesheet" type="text/css" href="../cups-printable.css"> + <title>ipptoolfile(5)</title> +</head> +<body> +<h1 class="title">ipptoolfile(5)</h1> +<h2 class="title"><a name="NAME">Name</a></h2> +ipptoolfile - ipptool file format + +<h2 class="title"><a name="DESCRIPTION">Description</a></h2> +The <a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a> program accepts free-form plain text files that describe one or more IPP requests. Comments start with the "#" character and continue to the end of the line. Each request is enclosed by curley braces, for example: +<pre> + + # This is a comment + { + # The name of the test + NAME "Print PostScript Job" + + # The request to send + OPERATION Print-Job + GROUP operation-attributes-tag + ATTR charset attributes-charset utf-8 + ATTR language attributes-natural-language en + ATTR uri printer-uri $uri + ATTR name requesting-user-name $user + FILE testfile.ps + + # The response to expect + STATUS successful-ok + EXPECT attributes-charset OF-TYPE charset + EXPECT attributes-natural-language OF-TYPE naturalLanguage + EXPECT job-id OF-TYPE integer + EXPECT job-uri OF-TYPE uri + } + { + # The name of the test + NAME "Get Attributes of PostScript Job" + + # The request to send + OPERATION Get-Job-Attributes + GROUP operation-attributes-tag + ATTR charset attributes-charset utf-8 + ATTR language attributes-natural-language en + ATTR uri printer-uri $uri + ATTR integer job-id $job-id + ATTR name requesting-user-name $user + + # The response to expect + STATUS successful-ok + EXPECT attributes-charset OF-TYPE charset + EXPECT attributes-natural-language OF-TYPE naturalLanguage + EXPECT job-id OF-TYPE integer + EXPECT job-uri OF-TYPE uri + EXPECT job-state OF-TYPE enum + EXPECT job-originating-user-name OF-TYPE name WITH-VALUE "$user" + } +</pre> + +<h2 class="title"><a name="TOP-LEVEL_DIRECTIVES">Top-level Directives</a></h2> +The following directives can be used outside of a test: +<dl> +<dt>{ test } +</dt> +<dd>Defines a test. +</dd> +<dt>DEFINE variable-name value +</dt> +<dd>Defines the named variable to the given value. This is equivalent to specifying +"-d variable-name=value" on the <i>ipptool</i> command-line. +</dd> +<dt>DEFINE-DEFAULT variable-name value +</dt> +<dd>Defines the named variable to the given value if it does not already have a +value. +</dd> +<dt>IGNORE-ERRORS yes +</dt> +<dd></dd> +<dt>IGNORE-ERRORS no +</dt> +<dd>Specifies whether, by default, <i>ipptool</i> will ignore errors and continue with +subsequent tests. +</dd> +<dt>INCLUDE "filename" +</dt> +<dd></dd> +<dt>INCLUDE <filename> +</dt> +<dd>Includes another test file. The first form includes a file relative to the +current test file, while the second form includes a file from the <i>ipptool</i> +include directory. +</dd> +<dt>INCLUDE-IF-DEFINED name "filename" +</dt> +<dd></dd> +<dt>INCLUDE-IF-DEFINED name <filename> +</dt> +<dd>Includes another test file if the named variable is defined. The first form +includes a file relative to the current test file, while the second form +includes a file from the <i>ipptool</i> include directory. +</dd> +<dt>INCLUDE-IF-NOT-DEFINED name "filename" +</dt> +<dd></dd> +<dt>INCLUDE-IF-NOT-DEFINED name <filename> +</dt> +<dd>Includes another test file if the named variable is not defined. The first form +includes a file relative to the current test file, while the second form +includes a file from the <i>ipptool</i> include directory. +</dd> +<dt>SKIP-IF-DEFINED variable-name +</dt> +<dd></dd> +<dt>SKIP-IF-NOT-DEFINED variable-name +</dt> +<dd>Specifies that the remainder of the test file should be skipped when the +variable is or is not defined. +</dd> +<dt>TRANSFER auto +</dt> +<dd>Specifies that tests will, by default, use "Transfer-Encoding: chunked" for +requests with attached files and "Content-Length:" for requests without attached +files. +</dd> +<dt>TRANSFER chunked +</dt> +<dd>Specifies that tests will, by default, use the HTTP/1.1 "Transfer-Encoding: +chunked" header. This is the default and is equivalent to specifying "-c" on the +<i>ipptool</i> command-line. Support for chunked requests is required for +conformance with all versions of IPP. +</dd> +<dt>TRANSFER length +</dt> +<dd>Specifies that tests will, by default, use the HTTP/1.0 "Content-Length:" +header. This is equivalent to specifying "-l" on the <i>ipptool</i> command-line. +Support for content length requests is required for conformance with all +versions of IPP. +</dd> +<dt>VERSION 1.0 +</dt> +<dd></dd> +<dt>VERSION 1.1 +</dt> +<dd></dd> +<dt>VERSION 2.0 +</dt> +<dd></dd> +<dt>VERSION 2.1 +</dt> +<dd></dd> +<dt>VERSION 2.2 +</dt> +<dd>Specifies the default IPP version number to use for the tests that follow. + +</dd> +</dl> +<h2 class="title"><a name="TEST_DIRECTIVES">Test Directives</a></h2> +The following directives are understood in a test: +<dl> +<dt>ATTR tag attribute-name value(s) +</dt> +<dd>Adds an attribute to the test request. Values are separated by the comma (",") +character - escape commas using the "" character. +</dd> +<dt>ATTR collection attribute-name { MEMBER tag member-name value(s) ... } [ ... { ... } ] +</dt> +<dd>Adds a collection attribute to the test request. Member attributes follow the +same syntax as regular attributes and can themselves be nested collections. +Multiple collection values can be supplied as needed. +</dd> +<dt>DELAY seconds +</dt> +<dd>Specifies a delay before this test will be run. +</dd> +<dt>DISPLAY attribute-name +</dt> +<dd>Specifies that value of the named attribute should be output as part of the +test report. +</dd> +<dt>EXPECT attribute-name [ predicate(s) ] +</dt> +<dd></dd> +<dt>EXPECT ?attribute-name predicate(s) +</dt> +<dd></dd> +<dt>EXPECT !attribute-name +</dt> +<dd>Specifies that the response must/may/must not include the named attribute. +Additional requirements can be added as predicates - see the "EXPECT PREDICATES" +section for more information on predicates. +</dd> +<dt>FILE filename +</dt> +<dd>Specifies a file to include at the end of the request. This is typically used +when sending a test print file. +</dd> +<dt>GROUP tag +</dt> +<dd>Specifies the group tag for subsequent attributes in the request. +</dd> +<dt>IGNORE-ERRORS yes +</dt> +<dd></dd> +<dt>IGNORE-ERRORS no +</dt> +<dd>Specifies whether <i>ipptool</i> will ignore errors and continue with subsequent +tests. +</dd> +<dt>NAME "literal string" +</dt> +<dd>Specifies the human-readable name of the test. +</dd> +<dt>OPERATION operation-code +</dt> +<dd>Specifies the operation to be performed. +</dd> +<dt>REQUEST-ID number +</dt> +<dd></dd> +<dt>REQUEST-ID random +</dt> +<dd>Specifies the request-id value to use in the request, either an integer or the +word "random" to use a randomly generated value (the default). +</dd> +<dt>RESOURCE path +</dt> +<dd>Specifies an alternate resource path that is used for the HTTP POST request. +The default is the resource from the URI provided to the <i>ipptool</i> program. +</dd> +<dt>SKIP-IF-DEFINED variable-name +</dt> +<dd></dd> +<dt>SKIP-IF-NOT-DEFINED variable-name +</dt> +<dd>Specifies that the current test should be skipped when the variable is or is not +defined. +</dd> +<dt>SKIP-PREVIOUS-ERROR yes +</dt> +<dd></dd> +<dt>SKIP-PREVIOUS-ERROR no +</dt> +<dd>Specifies whether <i>ipptool</i> will skip the current test if the previous test +resulted in an error/failure. +</dd> +<dt>STATUS status-code [ predicate ] +</dt> +<dd>Specifies an expected response status-code value. Additional requirements can be +added as predicates - see the "STATUS PREDICATES" section for more information +on predicates. +</dd> +<dt>TRANSFER auto +</dt> +<dd>Specifies that this test will use "Transfer-Encoding: chunked" if it has an +attached file or "Content-Length:" otherwise. +</dd> +<dt>TRANSFER chunked +</dt> +<dd>Specifies that this test will use the HTTP/1.1 "Transfer-Encoding: chunked" +header. +</dd> +<dt>TRANSFER length +</dt> +<dd>Specifies that this test will use the HTTP/1.0 "Content-Length:" header. +</dd> +<dt>VERSION 1.0 +</dt> +<dd></dd> +<dt>VERSION 1.1 +</dt> +<dd></dd> +<dt>VERSION 2.0 +</dt> +<dd></dd> +<dt>VERSION 2.1 +</dt> +<dd></dd> +<dt>VERSION 2.2 +</dt> +<dd>Specifies the IPP version number to use for this test. + +</dd> +</dl> +<h2 class="title"><a name="EXPECT_PREDICATES">Expect Predicates</a></h2> +The following predicates are understood following the EXPECT test directive: +<dl> +<dt>COUNT number +</dt> +<dd>Requires the EXPECT attribute to have the specified number of values. +</dd> +<dt>DEFINE-MATCH variable-name +</dt> +<dd>Defines the variable to "1" when the EXPECT condition matches. A side-effect of +this predicate is that this EXPECT will never fail a test. +</dd> +<dt>DEFINE-NO-MATCH variable-name +</dt> +<dd>Defines the variable to "1" when the EXPECT condition does not match. A side- +effect of this predicate is that this EXPECT will never fail a test. +</dd> +<dt>DEFINE-VALUE variable-name +</dt> +<dd>Defines the variable to the value of the attribute when the EXPECT condition +matches. A side-effect of this predicate is that this EXPECT will never fail a test. +</dd> +<dt>IF-DEFINED variable-name +</dt> +<dd>Makes the EXPECT conditions apply only if the specified variable is defined. +</dd> +<dt>IF-NOT-DEFINED variable-name +</dt> +<dd>Makes the EXPECT conditions apply only if the specified variable is not +defined. +</dd> +<dt>IN-GROUP tag +</dt> +<dd>Requires the EXPECT attribute to be in the specified group tag. +</dd> +<dt>OF-TYPE tag[,tag,...] +</dt> +<dd>Requires the EXPECT attribute to use the specified value tag(s). +</dd> +<dt>REPEAT-LIMIT number +</dt> +<dd></dd> +<dd>Specifies the maximum number of times to repeat. The default value is 1000. +</dd> +<dt>REPEAT-MATCH +</dt> +<dd></dd> +<dt>REPEAT-NO-MATCH +</dt> +<dd>Specifies that the current test should be repeated when the EXPECT condition +matches or does not match. +</dd> +<dt>SAME-COUNT-AS attribute-name +</dt> +<dd>Requires the EXPECT attribute to have the same number of values as the specified +parallel attribute. +</dd> +<dt>WITH-ALL-VALUES "literal string" +</dt> +<dd>Requires that all values of the EXPECT attribute match the literal string. Comparisons are case-sensitive. +</dd> +<dt>WITH-ALL-VALUES <number +</dt> +<dd></dd> +<dt>WITH-ALL-VALUES =number +</dt> +<dd></dd> +<dt>WITH-ALL-VALUES >number +</dt> +<dd></dd> +<dt>WITH-ALL-VALUES number[,number,...] +</dt> +<dd>Requires that all values of the EXPECT attribute match the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range. +</dd> +<dt>WITH-ALL-VALUES "false" +</dt> +<dd></dd> +<dt>WITH-ALL-VALUES "true" +</dt> +<dd>Requires that all values of the EXPECT attribute match the boolean value given. +</dd> +<dt>WITH-ALL-VALUES "/regular expression/" +</dt> +<dd>Requires that all values of the EXPECT attribute match the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive. +</dd> +<dt>WITH-VALUE "literal string" +</dt> +<dd>Requires that at least one value of the EXPECT attribute matches the literal string. Comparisons are case-sensitive. +</dd> +<dt>WITH-VALUE <number +</dt> +<dd></dd> +<dt>WITH-VALUE =number +</dt> +<dd></dd> +<dt>WITH-VALUE >number +</dt> +<dd></dd> +<dt>WITH-VALUE number[,number,...] +</dt> +<dd>Requires that at least one value of the EXPECT attribute matches the number(s) or numeric comparison. When comparing rangeOfInteger values, the "<" and ">" operators only check the upper bound of the range. +</dd> +<dt>WITH-VALUE "false" +</dt> +<dd></dd> +<dt>WITH-VALUE "true" +</dt> +<dd>Requires that at least one value of the EXPECT attribute matches the boolean value given. +</dd> +<dt>WITH-VALUE "/regular expression/" +</dt> +<dd>Requires that at least one value of the EXPECT attribute matches the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive. + +</dd> +</dl> +<h2 class="title"><a name="STATUS_PREDICATES">Status Predicates</a></h2> +The following predicates are understood following the STATUS test directive: +<dl> +<dt>IF-DEFINED variable-name +</dt> +<dd>Makes the STATUS apply only if the specified variable is defined. +</dd> +<dt>IF-NOT-DEFINED variable-name +</dt> +<dd>Makes the STATUS apply only if the specified variable is not defined. +</dd> +<dt>REPEAT-LIMIT number +</dt> +<dd></dd> +<dd>Specifies the maximum number of times to repeat. The default value is 1000. +</dd> +<dt>REPEAT-MATCH +</dt> +<dd></dd> +<dt>REPEAT-NO-MATCH +</dt> +<dd>Specifies that the current test should be repeated when the response status-code +matches or does not match the value specified by the STATUS directive. + +</dd> +</dl> +<h2 class="title"><a name="OPERATION_CODES">Operation Codes</a></h2> +Operation codes correspond to the hexadecimal numbers (0xHHHH) and names from +RFC 2911 and other IPP extension specifications. Here is a complete list: +<pre> + Activate-Printer + CUPS-Accept-Jobs + CUPS-Add-Modify-Class + CUPS-Add-Modify-Printer + CUPS-Authenticate-Job + CUPS-Delete-Class + CUPS-Delete-Printer + CUPS-Get-Classes + CUPS-Get-Default + CUPS-Get-Devices + CUPS-Get-Document + CUPS-Get-PPD + CUPS-Get-PPDs + CUPS-Get-Printers + CUPS-Move-Job + CUPS-Reject-Jobs + CUPS-Set-Default + Cancel-Current-Job + Cancel-Job + Cancel-Jobs + Cancel-My-Jobs + Cancel-Subscription + Close-Job + Create-Job + Create-Job-Subscription + Create-Printer-Subscription + Deactivate-Printer + Disable-Printer + Enable-Printer + Get-Job-Attributes + Get-Jobs + Get-Notifications + Get-Printer-Attributes + Get-Printer-Support-Files + Get-Printer-Supported-Values + Get-Subscription-Attributes + Get-Subscriptions + Hold-Job + Hold-New-Jobs + Identify-Printer + Pause-Printer + Pause-Printer-After-Current-Job + Print-Job + Print-URI + Promote-Job + Purge-Jobs + Release-Held-New-Jobs + Release-Job + Renew-Subscription + Reprocess-Job + Restart-Job + Restart-Printer + Resubmit-Job + Resume-Job + Resume-Printer + Schedule-Job-After + Send-Document + Send-Notifications + Send-URI + Set-Job-Attributes + Set-Printer-Attributes + Shutdown-Printer + Startup-Printer + Suspend-Current-Job + Validate-Document + Validate-Job +</pre> + +<h2 class="title"><a name="STATUS_CODES">Status Codes</a></h2> +Status codes correspond to the hexadecimal numbers (0xHHHH) and names from RFC +2911 and other IPP extension specifications. Here is a complete list: +<pre> + client-error-attributes-not-settable + client-error-attributes-or-values-not-supported + client-error-bad-request + client-error-charset-not-supported + client-error-compression-error + client-error-compression-not-supported + client-error-conflicting-attributes + client-error-document-access-error + client-error-document-format-error + client-error-document-format-not-supported + client-error-document-password-error + client-error-document-permission-error + client-error-document-security-error + client-error-document-unprintable-error + client-error-forbidden + client-error-gone + client-error-ignored-all-notifications + client-error-ignored-all-subscriptions + client-error-not-authenticated + client-error-not-authorized + client-error-not-found + client-error-not-possible + client-error-print-support-file-not-found + client-error-request-entity-too-large + client-error-request-value-too-long + client-error-timeout + client-error-too-many-subscriptions + client-error-uri-scheme-not-supported + cups-see-other + redirection-other-site + server-error-busy + server-error-device-error + server-error-internal-error + server-error-job-canceled + server-error-multiple-document-jobs-not-supported + server-error-not-accepting-jobs + server-error-operation-not-supported + server-error-printer-is-deactivated + server-error-service-unavailable + server-error-temporary-error + server-error-version-not-supported + successful-ok + successful-ok-but-cancel-subscription + successful-ok-conflicting-attributes + successful-ok-events-complete + successful-ok-ignored-notifications + successful-ok-ignored-or-substituted-attributes + successful-ok-ignored-subscriptions + successful-ok-too-many-events +</pre> + +<h2 class="title"><a name="TAGS">Tags</a></h2> +Value and group tags correspond to the names from RFC 2911 and other IPP +extension specifications. Here are the group tags: +<pre> + event-notification-attributes-tag + job-attributes-tag + operation-attributes-tag + printer-attributes-tag + subscription-attributes-tag + unsupported-attributes-tag +</pre> +<p>Here are the value tags: +<pre> + admin-define + boolean + charset + collection + dateTime + default + delete-attribute + enum + integer + keyword + mimeMediaType + nameWithLanguage + nameWithoutLanguage + naturalLanguage + no-value + not-settable + octetString + rangeOfInteger + resolution + textWithLanguage + textWithoutLanguage + unknown + unsupported + uri + uriScheme +</pre> + +<h2 class="title"><a name="VARIABLES">Variables</a></h2> +The <i>ipptool</i> program maintains a list of variables that can be used in any +literal string or attribute value by specifying "$variable-name". Aside from +variables defined using the "-d" option or "DEFINE" directive, the following +pre-defined variables are available: +<dl> +<dt>$$ +</dt> +<dd>Inserts a single "$" character. +</dd> +<dt>$ENV[name] +</dt> +<dd>Inserts the value of the named environment variable, or an empty string if the +environment variable is not defined. +</dd> +<dt>$filename +</dt> +<dd>Inserts the filename provided to <i>ipptool</i> with the "-f" option. +</dd> +<dt>$hostname +</dt> +<dd>Inserts the hostname from the URI provided to <i>ipptool</i>. +</dd> +<dt>$job-id +</dt> +<dd>Inserts the last job-id value returned in a test response or 0 if no job-id has +been seen. +</dd> +<dt>$job-uri +</dt> +<dd>Inserts the last job-uri value returned in a test response or an empty string if +no job-uri has been seen. +</dd> +<dt>$scheme +</dt> +<dd>Inserts the scheme from the URI provided to <i>ipptool</i>. +</dd> +<dt>$notify-subscription-id +</dt> +<dd>Inserts the last notify-subscription-id value returnd in a test response or 0 if +no notify-subscription-id has been seen. +</dd> +<dt>$port +</dt> +<dd>Inserts the port number from the URI provided to <i>ipptool</i>. +</dd> +<dt>$resource +</dt> +<dd>Inserts the resource path from the URI provided to <i>ipptool</i>. +</dd> +<dt>$uri +</dt> +<dd>Inserts the URI provided to <i>ipptool</i>. +</dd> +<dt>$user +</dt> +<dd>Inserts the current user's login name. +</dd> +<dt>$username +</dt> +<dd>Inserts the username from the URI provided to <i>ipptool</i>, if any. + +</dd> +</dl> +<h2 class="title"><a name="SEE_ALSO">See Also</a></h2> +<a href='man-ipptool.html?TOPIC=Man+Pages'>ipptool(1)</a>, +<br> +<a href='http://localhost:631/help'>http://localhost:631/help</a> + +<h2 class="title"><a name="COPYRIGHT">Copyright</a></h2> +Copyright 2007-2012 by Apple Inc. + +</body> +</html> diff --git a/doc/help/network.html b/doc/help/network.html index d02d4f40..6743651f 100644 --- a/doc/help/network.html +++ b/doc/help/network.html @@ -397,21 +397,19 @@ lpd://<i>username@ip-address-or-hostname</i>/<i>queue</i>?<i>option=value&option <H2 CLASS="title"><A NAME="SNMP">Troubleshooting SNMP Discovery Problems</A></H2> -<P>Whenever you view the administration web page or a list of supported device URIs, the <tt>snmp</tt> backend will probe the local network(s) using Simple Network Management Protocol (SNMP) broadcasts. Printers that respond to these broadcasts are then interrogated for the make and model and supported protocols, yielding a device URI that can be used to add the printer.</P> +<P>Whenever you view the administration web page or a list of supported device URIs, the <tt>snmp</tt> backend can probe the local network(s) using Simple Network Management Protocol (SNMP) v1 broadcasts. Printers that respond to these broadcasts are then interrogated for the make, model, and supported protocols, yielding a device URI that can be used to add the printer.</P> -<P>That said, the SNMP requests sometimes expose problems in vendor SNMP or IPP implementations. If you are experiencing long delays in loading the CUPS web interface administration page, or if you don't see your printer listed, the following instructions will help you to diagnose those problems and/or provide important feedback to the CUPS developers so that we can correct problems and improve the SNMP backend in future releases.</P> +<P>That said, the SNMP requests sometimes expose problems in vendor implementations. If you are experiencing long delays in loading the CUPS web interface administration page, or if you don't see your printer listed, the following instructions will help you to diagnose those problems and/or provide important feedback to the CUPS developers so that we can correct problems and improve the SNMP backend in future releases.</P> <H3>Quick Fixes</H3> -<P>If you don't use "public" as your community name, create a text file called <VAR>/etc/cups/snmp.conf</VAR> and put the following line in it:</P> +<P>If you don't use "public" as your community name, edit or create (as needed) a text file called <VAR>/etc/cups/snmp.conf</VAR> and put the following line in it:</P> <PRE CLASS="command"> Community <I>your community name</I> </PRE> -<P>If you have more than one community name, list them all on separate lines.</P> - -<P>If you don't support SNMP v1 on your network, you are currently "out of luck". That said, we will be adding v2, v2c, and v3 support in future CUPS releases once we have a handle on the actual requirements people have for such things. Please file or update an <A HREF="http://www.cups.org/str.php">SNMP enhancement request</A> with <em>specific</em> requirements you have - what you need supported, why you need it supported, and how you would like to see the functionality provided/exposed - so that we can do it "right" the first time.</P> +<P>The SNMP backend will not be able to find any printers on your network if SNMP v1 or broadcasting are not supported on your network.</P> <H3>Basic Debugging</H3> diff --git a/doc/help/options.html b/doc/help/options.html index 0cfa7413..546f2ec1 100644 --- a/doc/help/options.html +++ b/doc/help/options.html @@ -95,8 +95,8 @@ printing.</P> printer options using the <CODE>-o</CODE> option:</P> <PRE CLASS="command"> -lp -o landscape -o scaling=75 -o media=A4 filename.jpg -lpr -o landscape -o scaling=75 -o media=A4 filename.jpg +lp -o landscape -o fit-to-page -o media=A4 filename.jpg +lpr -o landscape -o fit-to-page -o media=A4 filename.jpg </PRE> <P>The available printer options vary depending on the printer. @@ -662,117 +662,5 @@ lpr -o nowrap filename </PRE> -<H2 CLASS="title"><SPAN CLASS="info">Not Supported on Mac OS X</SPAN><A NAME="IMAGEOPTIONS">Image Options</A></H2> - -<P>CUPS supports several options that are only used when printing -image files. These options have absolutely no effect on PostScript, PDF, -HP-GL/2, or text files.</P> - -<H3><A NAME="position">Positioning Images</A></H3> - -<P>The <CODE>-o position=name</CODE> option specifies the position of the -image on the page: - -<UL> - - <LI><CODE>center</CODE> - Center the image on the page (default) - - <LI><CODE>top</CODE> - Print the image centered at the top of the page - - <LI><CODE>left</CODE> - Print the image centered on the left of page - - <LI><CODE>right</CODE> - Print the image centered on the right of the page - - <LI><CODE>top-left</CODE> - Print the image at the top left corner of - the page - - <LI><CODE>top-right</CODE> - Print the image at the top right corner of - the page - - <LI><CODE>bottom</CODE> - Print the image centered at the bottom of - the page - - <LI><CODE>bottom-left</CODE> - Print the image at the bottom left - corner of the page - - <LI><CODE>bottom-right</CODE> - Print the image at the bottom right - corner of the page - -</UL> - -<H3><A NAME="scaling">Scaling Images</A></H3> - -<P>The <CODE>-o scaling=percent</CODE>, <CODE>-o -ppi=value</CODE>, and <CODE>-o natural-scaling=percent</CODE> -options change the size of a printed image: - -<PRE CLASS="command"> -lp -o scaling=<EM>percent</EM> filename -lp -o ppi=<EM>value</EM> filename -lpr -o natural-scaling=<EM>percent</EM> filename -</PRE> - -<P>The <CODE>scaling=percent</CODE> value is a number from 1 to 800 -specifying the size in relation to the page (<EM>not</EM> the image.) A -scaling of 100 percent will fill the page as completely as the image -aspect ratio allows. A scaling of 200 percent will print on up to 4 -pages. - -<P>The <CODE>ppi=value</CODE> value is a number from 1 to 1200 specifying the -resolution of the image in pixels per inch. An image that is 3000x2400 -pixels will print 10x8 inches at 300 pixels per inch, for example. If -the specified resolution makes the image larger than the page, multiple -pages will be printed to satisfy the request. - -<P>The <CODE>natural-scaling=percent</CODE> value is a number -from 1 to 800 specifying the size in relation to the natural -image size. A scaling of 100 percent will print the image at its -natural size, while a scaling of 50 percent will print the image -at half its natural size. If the specified scaling makes the -image larger than the page, multiple pages will be printed to -satisfy the request. - - -<H2 CLASS="title"><A NAME="HPGL2OPTIONS">HP-GL/2 Options</A></H2> - -<P>CUPS supports several options that are only used when printing -HP-GL/2 files. These options have absolutely no effect on PostScript, PDF, -image, or text files.</P> - -<H3><A NAME="blackplot">Printing in Black</A></H3> - -<P>The <CODE>-o blackplot</CODE> option specifies that all pens should -plot in black:</P> - -<PRE CLASS="command"> -lp -o blackplot filename -lpr -o blackplot filename -</PRE> - -<P>The default is to use the colors defined in the plot file or the -standard pen colors defined in the HP-GL/2 reference manual from -Hewlett Packard. - -<H3><A NAME="penwidth">Setting the Default Pen Width</A></H3> - -<P>The <CODE>-o penwidth=value</CODE> option specifies the default pen -width for HP-GL/2 files:</P> - -<PRE CLASS="command"> -lp -o penwidth=<EM>value</EM> filename -lpr -o penwidth=<EM>value</EM> filename -</PRE> - -<P>The pen width <CODE>value</CODE> specifies the pen width in micrometers. -The default value of 1000 produces lines that are 1 millimeter in width. -Specifying a pen width of 0 produces lines that are exactly 1 pixel wide.</P> - -<BLOCKQUOTE><B>Note:</B> - -<P>This option is ignored when the pen widths are set in the plot -file. - -</BLOCKQUOTE> - </BODY> </HTML> diff --git a/doc/help/overview.html b/doc/help/overview.html index 59a2ac06..4a4b173b 100644 --- a/doc/help/overview.html +++ b/doc/help/overview.html @@ -26,7 +26,7 @@ out on its own.</P> <P>The first time you print to a printer, CUPS creates a <em>queue</em> to keep track of the current status of the printer (everything OK, out of paper, etc.) and any pages you have printed. Most of the time the queue points to a printer -connected directly to your computer via a USB or parallel port, however it can +connected directly to your computer via a USB port, however it can also point to a printer on your network, a printer on the Internet, or multiple printers depending on the configuration. Regardless of <em>where</em> the queue points, it will look like any other printer to you and your applications.</P> diff --git a/doc/help/policies.html b/doc/help/policies.html index 14a5b4b8..18f4c80e 100644 --- a/doc/help/policies.html +++ b/doc/help/policies.html @@ -36,7 +36,7 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th 4 Require user @OWNER @SYSTEM 5 Order deny,allow 6 </Limit> - 7 + 7 8 # All administration operations require an administrator to authenticate... 9 <Limit CUPS-Add-Printer CUPS-Delete-Printer CUPS-Add-Class @@ -45,7 +45,7 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th 11 Require user @SYSTEM 12 Order deny,allow 13 </Limit> -14 +14 15 # All printer operations require a printer operator to authenticate... 16 <Limit Pause-Printer Resume-Printer @@ -59,14 +59,14 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th 18 Require user <em>varies by OS</em> 19 Order deny,allow 20 </Limit> -21 +21 22 # Only the owner or an administrator can cancel or authenticate a job... 23 <Limit Cancel-Job CUPS-Authenticate-Job> 24 Require user @OWNER @SYSTEM 25 Order deny,allow 26 </Limit> -27 +27 28 <Limit All> 29 Order deny,allow 30 </Limit> @@ -106,7 +106,7 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th 11 Require user @SYSTEM 12 Order deny,allow 13 </Limit> -14 +14 15 # All printer operations require a printer operator to authenticate... 16 <Limit Pause-Printer Resume-Printer @@ -380,12 +380,12 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th <TD>Prints a job after others.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Get-Default</TT></TD> + <TD NOWRAP><TT>CUPS-Get-Default</TT> *</TD> <TD>Yes</TD> <TD>Gets the server/network default printer or class.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Get-Printers</TT></TD> + <TD NOWRAP><TT>CUPS-Get-Printers</TT> *</TD> <TD>Yes</TD> <TD>Gets a list of printers and/or classes.</TD> </TR> @@ -395,12 +395,12 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th <TD>Adds or modifies a printer.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Delete-Printer</TT></TD> + <TD NOWRAP><TT>CUPS-Delete-Printer</TT> *</TD> <TD>Yes</TD> <TD>Removes a printer.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Get-Classes</TT></TD> + <TD NOWRAP><TT>CUPS-Get-Classes</TT> *</TD> <TD>Yes</TD> <TD>Gets a list of classes.</TD> </TR> @@ -410,7 +410,7 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th <TD>Adds or modifies a class.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Delete-Class</TT></TD> + <TD NOWRAP><TT>CUPS-Delete-Class</TT> *</TD> <TD>Yes</TD> <TD>Removes a class.</TD> </TR> @@ -427,17 +427,17 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th attribute to false.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Set-Default</TT></TD> + <TD NOWRAP><TT>CUPS-Set-Default</TT> *</TD> <TD>Yes</TD> <TD>Sets the server/network default printer or class.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Get-Devices</TT></TD> + <TD NOWRAP><TT>CUPS-Get-Devices</TT> *</TD> <TD>Yes</TD> <TD>Gets a list of printer devices.</TD> </TR> <TR> - <TD NOWRAP><TT>CUPS-Get-PPDs</TT></TD> + <TD NOWRAP><TT>CUPS-Get-PPDs</TT> *</TD> <TD>Yes</TD> <TD>Gets a list of printer drivers or manufacturers.</TD> </TR> @@ -459,6 +459,7 @@ HREF="ref-cupsd-conf.html#LimitIPP"><TT>Limit</TT></A> subsections which list th </TBODY> </TABLE></DIV> +<P>* = These operations only apply to the default policy.</P> <H2 CLASS="title"><A NAME="CREATING">Creating Your Own Policies</A></H2> @@ -556,7 +557,7 @@ Allow from @LOCAL</PRE></TD> 5 Order allow,deny 6 Allow from 10.0.2.0/24 7 </Limit> - 8 + 8 9 # All administration operations require a lab technician or an administrator to authenticate... 10 <Limit Pause-Printer Resume-Printer diff --git a/doc/help/postscript-driver.html b/doc/help/postscript-driver.html index 501043c7..4f35374d 100644 --- a/doc/help/postscript-driver.html +++ b/doc/help/postscript-driver.html @@ -341,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: postscript-driver.html 9740 2011-05-04 06:26:22Z mike $" + "$Id: postscript-driver.html 10424 2012-04-23 17:26:57Z mike $" PostScript printer driver documentation for CUPS. - Copyright 2007-2010 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2007 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -357,7 +357,7 @@ div.contents ul.subcontents li { <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> +<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 OS X features</a>.</p> <div class='summary'><table summary='General Information'> <tbody> @@ -380,7 +380,7 @@ div.contents ul.subcontents 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> +<li><a href="#MACOSX">Adding OS X Features</a></li> </ul> <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2> @@ -453,7 +453,7 @@ div.contents ul.subcontents li { dup [612 792] (Letter) put dup [612 1008] (Legal) put dup [595 842] (A4) put - {exch aload pop 4 index sub abs 5 le exch + {exch aload pop 4 index sub abs 5 le exch 5 index sub abs 5 le and {exch pop exit} {pop} ifelse } bind forall = flush pop pop @@ -550,7 +550,7 @@ div.contents ul.subcontents li { dup [612 792] (Letter) put dup [612 1008] (Legal) put dup [595 842] (A4) put - {exch aload pop 4 index sub abs 5 le exch + {exch aload pop 4 index sub abs 5 le exch 5 index sub abs 5 le and {exch pop exit} {pop} ifelse } bind forall = flush pop pop @@ -648,9 +648,9 @@ information file.</P> <p>The options used for profile selection can be customized using the <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> attributes.</p> -<h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2> +<h2 class='title'><a name='MACOSX'>Adding OS X Features</a></h2> -<p>Mac OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p> +<p>OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p> <pre class='example'> <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDialogExtension "" /Library/Printers/Vendor/filename.plugin diff --git a/doc/help/ppd-compiler.html b/doc/help/ppd-compiler.html index db891f17..576c9187 100644 --- a/doc/help/ppd-compiler.html +++ b/doc/help/ppd-compiler.html @@ -341,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: ppd-compiler.html 9740 2011-05-04 06:26:22Z mike $" + "$Id: ppd-compiler.html 10424 2012-04-23 17:26:57Z mike $" PPD compiler documentation for CUPS. - Copyright 2007-2010 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2007 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -361,6 +361,12 @@ div.contents ul.subcontents li { (PPD) file compiler. The PPD compiler generates PPD files from simple text files that describe the features and capabilities of one or more printers.</P> +<BLOCKQUOTE><B>Note:</B> + +<P>The PPD compiler and related tools are deprecated and will be removed in a future release of CUPS.</P> + +</BLOCKQUOTE> + <div class='summary'><table summary='General Information'> <tbody> <tr> @@ -598,7 +604,7 @@ follows:</P> <LI>Bits per color. In the example file, we define 8 bits per color, for a continuous-tone grayscale output. All versions of CUPS support 1 and - 8 bits per color. CUPS 1.2 and higher (Mac OS X 10.5 and higher) also + 8 bits per color. CUPS 1.2 and higher (OS X 10.5 and higher) also supports 16 bits per color.</LI> <LI>Rows per band. In the example file, we define 0 rows per band to diff --git a/doc/help/raster-driver.html b/doc/help/raster-driver.html index 2ec3f4e5..259ea184 100644 --- a/doc/help/raster-driver.html +++ b/doc/help/raster-driver.html @@ -341,11 +341,11 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: raster-driver.html 9740 2011-05-04 06:26:22Z mike $" + "$Id: raster-driver.html 10424 2012-04-23 17:26:57Z mike $" Raster printer driver documentation for CUPS. - Copyright 2007-2010 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2007 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -357,7 +357,7 @@ div.contents ul.subcontents li { <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> +<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 OS X features</a>.</p> <div class='summary'><table summary='General Information'> <tbody> @@ -378,7 +378,7 @@ div.contents ul.subcontents 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> +<li><a href="#MACOSX">Adding OS X Features</a></li> </ul> <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2> @@ -554,9 +554,9 @@ div.contents ul.subcontents li { <p>The options used for profile selection can be customized using the <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> attributes.</p> -<h3><span class='info'>Since Mac OS X 10.5</span>Custom Color Matching Support</h3> +<h3><span class='info'>Since OS X 10.5</span>Custom Color Matching Support</h3> -<p>Mac OS X printer drivers that are based on an existing standard RGB colorspace can tell the system to use the corresponding colorspace instead of an arbitrary ICC color profile when doing color management. The <a href='#APCustom'><tt>APSupportsCustomColorMatching</tt></a> and <tt>APDefaultCustomColorMatchingProfile</tt> attributes can be used to enable this mode:</p> +<p>OS X printer drivers that are based on an existing standard RGB colorspace can tell the system to use the corresponding colorspace instead of an arbitrary ICC color profile when doing color management. The <a href='#APCustom'><tt>APSupportsCustomColorMatching</tt></a> and <tt>APDefaultCustomColorMatchingProfile</tt> attributes can be used to enable this mode:</p> <pre class='example'> <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APSupportsCustomColorMatching "" true @@ -564,9 +564,9 @@ div.contents ul.subcontents li { </pre> -<h2 class='title'><a name='MACOSX'>Adding Mac OS X Features</a></h2> +<h2 class='title'><a name='MACOSX'>Adding OS X Features</a></h2> -<p>Mac OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p> +<p>OS X printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p> <pre class='example'> <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDialogExtension "" /Library/Printers/Vendor/filename.plugin diff --git a/doc/help/ref-classes-conf.html b/doc/help/ref-classes-conf.html index 40bc3d5e..4171bb26 100644 --- a/doc/help/ref-classes-conf.html +++ b/doc/help/ref-classes-conf.html @@ -171,7 +171,7 @@ HREF="#AllowUser"><CODE>AllowUser</CODE></A></P> <H3>Description</H3> -<P>The <CODE>Info</CODE> directive defines the string for the +<P>The <CODE>Info</CODE> directive defines the string for the <VAR>printer-info</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -260,7 +260,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>KLimit</CODE> directive defines the value of the +<P>The <CODE>KLimit</CODE> directive defines the value of the <VAR>job-k-limit</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -287,7 +287,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>Location</CODE> directive defines the string for the +<P>The <CODE>Location</CODE> directive defines the string for the <VAR>printer-location</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -372,7 +372,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>PageLimit</CODE> directive defines the value of the +<P>The <CODE>PageLimit</CODE> directive defines the value of the <VAR>job-page-limit</VAR> attribute. It can be set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -511,7 +511,7 @@ section.</P> <PRE CLASS="command"> <Class name> ... - StateMessage Ready to print. + StateMessage Class is lonely. </Class> </PRE> @@ -528,7 +528,6 @@ StateMessage Network host host_name is busy; will retry in 30 seconds... StateMessage Class busy; will retry in 10 seconds... StateMessage Class is busy; retrying print job... StateMessage Print file accepted - job ID id_number. -StateMessage Ready to print. StateMessage Waiting for job to complete </PRE> diff --git a/doc/help/ref-client-conf.html b/doc/help/ref-client-conf.html index 0229b004..f17d5407 100644 --- a/doc/help/ref-client-conf.html +++ b/doc/help/ref-client-conf.html @@ -34,6 +34,20 @@ encryption settings for the client.</P> <P>The default setting is <VAR>IfRequested</VAR>.</P> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="GSSServiceName">GSSServiceName</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +GSSServiceName http +GSSServiceName ipp +</PRE> + +<H3>Description</H3> + +<P>The <CODE>GSSServiceName</CODE> directive sets the Kerberos service name to use. The default is <CODE>http</CODE> for compatibility with Microsoft Windows.</P> + + <H2 CLASS="title"><A NAME="ServerName">ServerName</A></H2> <H3>Examples</H3> @@ -52,5 +66,25 @@ ServerName foo.bar.com:8631 <P>The default is to use the local server ("<VAR>localhost</VAR>") or domain socket, if so configured.</P> +<BLOCKQUOTE><B>Note:</B> +<P>Only one <CODE>ServerName</CODE> directive may appear. If multiple names are +present, only the last one is used. This directive is not supported on OS X 10.7 or later.</P> +</BLOCKQUOTE> + + +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="User">User</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +User joe +User bob +</PRE> + +<H3>Description</H3> + +<P>The <CODE>User</CODE> directive sets the user name to use. The default is the username associated with the current login.</P> + + </BODY> </HTML> diff --git a/doc/help/ref-cupsd-conf.html.in b/doc/help/ref-cupsd-conf.html.in index ce0ec8f6..8454cf78 100644 --- a/doc/help/ref-cupsd-conf.html.in +++ b/doc/help/ref-cupsd-conf.html.in @@ -42,6 +42,12 @@ sudo launchctl load /System/Library/LaunchDaemons/org.cups.cupsd.plist <P>You can also edit this file from the CUPS web interface, which automatically handles restarting the scheduler.</P> +<BLOCKQUOTE><B>Note:</B> + +<P>The specification of time units ("w" for weeks, "h" for hours, etc.) in the various time interval directives is new in CUPS 1.6/OS X 10.8. Prior releases of CUPS only supported time intervals in seconds.</P> + +</BLOCKQUOTE> + <H2 CLASS="title"><A NAME="AccessLog">AccessLog</A></H2> @@ -335,243 +341,14 @@ quotas. This option has no effect if quotas are not enabled. The default setting is <CODE>No</CODE>.</P> -<H2 CLASS="title"><A NAME="BrowseAddress">BrowseAddress</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseAddress 255.255.255.255:631 -BrowseAddress 192.0.2.255:631 -BrowseAddress host.example.com:631 -BrowseAddress @LOCAL -BrowseAddress @IF(name) -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseAddress</CODE> directive specifies an address -to send browsing information to. Multiple -<CODE>BrowseAddress</CODE> directives can be specified to send -browsing information to different networks or systems.</P> - -<P>The <CODE>@LOCAL</CODE> name will broadcast printer -information to all local interfaces. The <CODE>@IF(name)</CODE> -name will broadcast to the named interface.</P> - -<P>There is no default browse address.</P> - -<BLOCKQUOTE><B>Note:</B> - -<P>If you are using HP-UX 10.20 and a subnet that is not 24, -16, or 8 bits, printer browsing (and in fact all broadcast -reception) will not work. This problem appears to be fixed in -HP-UX 11.0.</P> - -</BLOCKQUOTE> - - -<H2 CLASS="title"><A NAME="BrowseAllow">BrowseAllow</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseAllow from all -BrowseAllow from none -BrowseAllow from 192.0.2 -BrowseAllow from 192.0.2.0/24 -BrowseAllow from 192.0.2.0/255.255.255.0 -BrowseAllow from *.example.com -BrowseAllow from @LOCAL -BrowseAllow from @IF(name) -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseAllow</CODE> directive specifies a system or -network to accept browse packets from. The default is to accept -browse packets from all hosts.</P> - -<P>Host and domain name matching require that you enable the <A -HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> -directive.</P> - -<P>IP address matching supports exact matches, partial addresses that match -networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, or network -addresses using the specified netmask or bit count. The <CODE>/mm</CODE> -notation specifies a CIDR netmask, a shown in <A HREF="TABLE1">Table 1</A>.</P> - -<P>The <CODE>@LOCAL</CODE> name will allow browse data from all -local interfaces. The <CODE>@IF(name)</CODE> name will allow -browse data from the named interface. In both cases, CUPS only -allows data from the network that the interface(s) are configured -for - data arriving on the interface from a foreign network will -<em>not</em> be allowed.</P> - - -<H2 CLASS="title"><A NAME="BrowseDeny">BrowseDeny</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseDeny from all -BrowseDeny from none -BrowseDeny from 192.0.2 -BrowseDeny from 192.0.2.0/24 -BrowseDeny from 192.0.2.0/255.255.255.0 -BrowseDeny from *.example.com -BrowseDeny from @LOCAL -BrowseDeny from @IF(name) -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseDeny</CODE> directive specifies a system or -network to reject browse packets from. The default is to not deny -browse packets from any hosts.</P> - -<P>Host and domain name matching require that you enable the <A -HREF="#HostNameLookups"><CODE>HostNameLookups</CODE></A> -directive.</P> - -<P>IP address matching supports exact matches, partial addresses that match -networks using netmasks of 255.0.0.0, 255.255.0.0, and 255.255.255.0, or network -addresses using the specified netmask or bit count. The <CODE>/mm</CODE> -notation specifies a CIDR netmask, a shown in <A HREF="TABLE1">Table 1</A>.</P> - -<P>The <CODE>@LOCAL</CODE> name will block browse data from all -local interfaces. The <CODE>@IF(name)</CODE> name will block -browse data from the named interface. In both cases, CUPS only -blocks data from the network that the interface(s) are configured -for - data arriving on the interface from a foreign network will -<em>not</em> be blocked.</P> - - -<H2 CLASS="title"><A NAME="BrowseInterval">BrowseInterval</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseInterval 0 -BrowseInterval 30 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseInterval</CODE> directive specifies the -maximum amount of time between browsing updates. Specifying a -value of 0 seconds disables outgoing browse updates but allows a -server to receive printer information from other hosts.</P> - -<P>The <CODE>BrowseInterval</CODE> value should always be less -than the <A HREF="#BrowseTimeout"><CODE>BrowseTimeout</CODE></A> -value. Otherwise printers and classes will disappear from client -systems between updates.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPBindDN">BrowseLDAPBindDN</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLDAPBindDN foo -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLDAPBindDN</CODE> directive specifies the LDAP -domain name to use when listening for printer registrations. The -default is undefined.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="BrowseLDAPCACertFile">BrowseLDAPCACertFile</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLDAPCACertFile /etc/cups/ssl/certs -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLDAPCACertFile</CODE> directive specifies the SSL certificate -authority file to use for LDAP + SSL. The default is undefined.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPDN">BrowseLDAPDN</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLDAPDN bar -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLDAPDN</CODE> directive specifies the LDAP -domain name to use when registering local shared printers. The -default is undefined.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPPassword">BrowseLDAPPassword</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLDAPPassword foo123 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLDAPPassword</CODE> directive specifies the -access password to use when connecting to the LDAP server. The -default is undefined.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLDAPServer">BrowseLDAPServer</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLDAPServer localhost -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLDAPServer</CODE> directive specifies the name -of the LDAP server to connect to. The default is undefined.</P> - - -<H2 CLASS="title"><A NAME="BrowseLocalOptions">BrowseLocalOptions</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseLocalOptions compression=yes -BrowseLocalOptions encryption=required -BrowseLocalOptions compression=yes&encryption=required -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseLocalOptions</CODE> directive specifies -additional IPP backend options to advertise with local shared -printers. The default is to not include any options.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseLocalProtocols">BrowseLocalProtocols</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="BrowseLocalProtocols">BrowseLocalProtocols</A></H2> <H3>Examples</H3> <PRE CLASS="command"> BrowseLocalProtocols all BrowseLocalProtocols none -BrowseLocalProtocols cups BrowseLocalProtocols dnssd -BrowseLocalProtocols ldap -BrowseLocalProtocols lpd -BrowseLocalProtocols slp -BrowseLocalProtocols smb -BrowseLocalProtocols cups dnssd </PRE> <H3>Description</H3> @@ -582,230 +359,6 @@ network. Multiple protocols can be specified by separating them with spaces. The default is "<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>".</P> -<H2 CLASS="title"><A NAME="BrowseOrder">BrowseOrder</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseOrder allow,deny -BrowseOrder deny,allow -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseOrder</CODE> directive specifies the order of -allow/deny processing. The default order is -<CODE>deny,allow</CODE>:</P> - -<UL> - - <LI><CODE>allow,deny</CODE> - Deny browse packets by - default, then check <CODE>BrowseAllow</CODE> lines - followed by <CODE>BrowseDeny</CODE> lines.</LI> - - <LI><CODE>deny,allow</CODE> - Allow browse packets by - default, then check <CODE>BrowseDeny</CODE> lines - followed by <CODE>BrowseAllow</CODE> lines.</LI> - -</UL> - - -<H2 CLASS="title"><A NAME="BrowsePoll">BrowsePoll</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowsePoll 192.0.2.2:631 -BrowsePoll host.example.com:631 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowsePoll</CODE> directive polls a server for -available printers once every <A -HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> seconds. -Multiple <CODE>BrowsePoll</CODE> directives can be specified to -poll multiple servers.</P> - -<P>If <CODE>BrowseInterval</CODE> is set to 0 then the server is -polled once every 30 seconds.</P> - - -<H2 CLASS="title"><A NAME="BrowsePort">BrowsePort</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowsePort 631 -BrowsePort 9999 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowsePort</CODE> directive specifies the UDP port number -used for browse packets. The default port number is 631.</P> - -<BLOCKQUOTE><B>Note:</B> - -<P>You must set the <CODE>BrowsePort</CODE> to the same value -on all of the systems that you want to see. - -</BLOCKQUOTE> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="BrowseProtocols">BrowseProtocols</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseProtocols all -BrowseProtocols none -BrowseProtocols cups -BrowseProtocols dnssd -BrowseProtocols ldap -BrowseProtocols lpd -BrowseProtocols slp -BrowseProtocols smb -BrowseProtocols cups dnssd -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseProtocols</CODE> directive specifies the -protocols to use when showing and advertising shared printers on -the local network. Multiple protocols can be specified by -separating them with spaces. The default protocol is -"<CODE>@CUPS_BROWSE_LOCAL_PROTOCOLS@</CODE>" for -<A HREF="#BrowseLocalProtocols"><CODE>BrowseLocalProtocols</CODE></A> and -"<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>" for -<A HREF="#BrowseRemoteProtocols"><CODE>BrowseRemoteProtocols</CODE></A>.</P> - -<BLOCKQUOTE><B>Note:</B> - -<P>When using the <CODE>SLP</CODE> protocol, you must have at least -one Directory Agent (DA) server on your network. Otherwise the -CUPS scheduler (<CODE>cupsd</CODE>) will not respond to client -requests for several seconds while polling the network.</P> - -</BLOCKQUOTE> - - -<H2 CLASS="title"><A NAME="BrowseRelay">BrowseRelay</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseRelay 193.0.2.1 192.0.2.255 -BrowseRelay 193.0.2.0/255.255.255.0 192.0.2.255 -BrowseRelay 193.0.2.0/24 192.0.2.255 -BrowseRelay *.example.com 192.0.2.255 -BrowseRelay host.example.com 192.0.2.255 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseRelay</CODE> directive specifies source and -destination addresses for relaying browsing information from one -host or network to another. Multiple <CODE>BrowseRelay</CODE> -directives can be specified as needed.</P> - -<P><CODE>BrowseRelay</CODE> is typically used on systems that -bridge multiple subnets using one or more network interfaces. It -can also be used to relay printer information from polled servers -with the line:</P> - -<PRE CLASS="command"> -BrowseRelay 127.0.0.1 192.0.2.255 -</PRE> - -<P>This effectively provides access to printers on a WAN for all -clients on the LAN. Use multiple <CODE>BrowseRelay</CODE> lines to -relay information to multiple subnets.</P> - - -<H2 CLASS="title"><A NAME="BrowseRemoteOptions">BrowseRemoteOptions</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseRemoteOptions compression=yes -BrowseRemoteOptions encryption=required -BrowseRemoteOptions ?compression=yes&encryption=required -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseRemoteOptions</CODE> directive specifies -additional IPP backend options to include with remote shared -printers. If the options string begins with a question mark (?), -the options replace any options specified by the remote server. -The default is to not include any options.</P> - - -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="BrowseRemoteProtocols">BrowseRemoteProtocols</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseRemoteProtocols all -BrowseRemoteProtocols none -BrowseRemoteProtocols cups -BrowseRemoteProtocols ldap -BrowseRemoteProtocols slp -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseRemoteProtocols</CODE> directive specifies the -protocols to use when finding remote shared printers on the -network. Multiple protocols can be specified by separating them -with spaces. The default is "<CODE>@CUPS_BROWSE_REMOTE_PROTOCOLS@</CODE>".</P> - - -<H2 CLASS="title"><A NAME="BrowseShortNames">BrowseShortNames</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseShortNames Yes -BrowseShortNames No -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseShortNames</CODE> directive specifies whether -or not short names are used for remote printers when possible. -Short names are just the remote printer name, without the server -("printer"). If more than one remote printer is detected with the -same name, the printers will have long names ("printer@server1", -"printer@server2".)</P> - -<P>The default value for this option is <CODE>@CUPS_BROWSE_SHORT_NAMES@</CODE>.</P> - - -<H2 CLASS="title"><A NAME="BrowseTimeout">BrowseTimeout</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -BrowseTimeout 300 -BrowseTimeout 60 -</PRE> - -<H3>Description</H3> - -<P>The <CODE>BrowseTimeout</CODE> directive sets the timeout for -printer or class information that is received in browse packets. -Once a printer or class times out it is removed from the list of -available destinations.</P> - -<P>The <CODE>BrowseTimeout</CODE> value should always be greater -than the <A -HREF="#BrowseInterval"><CODE>BrowseInterval</CODE></A> value. -Otherwise printers and classes will disappear from client systems -between updates.</P> - - <H2 CLASS="title"><A NAME="BrowseWebIF">BrowseWebIF</A></H2> <H3>Examples</H3> @@ -834,24 +387,9 @@ Browsing Off <H3>Description</H3> <P>The <CODE>Browsing</CODE> directive controls whether or not -network printer browsing is enabled. The default setting is +printer sharing is enabled. The default setting is <CODE>@CUPS_BROWSING@</CODE>.</P> -<P>This directive does not enable sharing of local printers by -itself; you must also use the <A -HREF="#BrowseAddress"><CODE>BrowseAddress</CODE></A> or <A -HREF="#BrowseProtocols"><CODE>BrowseProtocols</CODE></A> -directives to advertise local printers to other systems.</P> - -<BLOCKQUOTE><B>Note:</B> - -<P>If you are using HP-UX 10.20 and a subnet that is not 24, -16, or 8 bits, printer browsing (and in fact all broadcast -reception) will not work. This problem appears to be fixed in -HP-UX 11.0.</P> - -</BLOCKQUOTE> - <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Classification">Classification</A></H2> @@ -932,7 +470,7 @@ DataDir /usr/share/cups for data files.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultAuthType">DefaultAuthType</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultAuthType">DefaultAuthType</A></H2> <H3>Examples</H3> @@ -950,7 +488,7 @@ of authentication to use for IPP operations that require a username. The default is <CODE>Basic</CODE>.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultEncryption">DefaultEncryption</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultEncryption">DefaultEncryption</A></H2> <H3>Examples</H3> @@ -988,7 +526,7 @@ language localization file exists for it. The default language is "en" for English.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="DefaultPaperSize">DefaultPaperSize</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="DefaultPaperSize">DefaultPaperSize</A></H2> <H3>Examples</H3> @@ -1008,7 +546,7 @@ of <CODE>None</CODE> tells the scheduler to not set the default paper size.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultPolicy">DefaultPolicy</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultPolicy">DefaultPolicy</A></H2> <H3>Examples</H3> @@ -1027,7 +565,7 @@ policy to use for IPP operation. The default is and other job operations.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="DefaultShared">DefaultShared</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="DefaultShared">DefaultShared</A></H2> <H3>Examples</H3> @@ -1095,22 +633,24 @@ HREF="#Location"><CODE>Location</CODE></A> or <A HREF="#Limit"><CODE>Limit</CODE></A> section.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="DirtyCleanInterval">DirtyCleanInterval</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="DirtyCleanInterval">DirtyCleanInterval</A></H2> <H3>Examples</H3> <PRE CLASS="command"> +DirtyCleanInterval 1w +DirtyCleanInterval 1d +DirtyCleanInterval 1h +DirtyCleanInterval 1m DirtyCleanInterval 30 DirtyCleanInterval 0 </PRE> <H3>Description</H3> -<P>The <CODE>DirtyCleanInterval</CODE> directive specifies the number of -seconds to wait before updating configuration and state files for printers, -classes, subscriptions, and jobs. The default is 30 seconds. A value of 0 -causes the update to occur as soon as possible, typically within a few -milliseconds.</P> +<P>The <CODE>DirtyCleanInterval</CODE> directive specifies the amount of time to wait before updating configuration and state files for printers, classes, subscriptions, and jobs in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). A value of <CODE>0</CODE> causes the update to occur as soon as possible, typically within a few milliseconds.</P> + +<P>The default value is <CODE>30</CODE> (30 seconds).</P> <H2 CLASS="title"><A NAME="DocumentRoot">DocumentRoot</A></H2> @@ -1186,7 +726,7 @@ default error log file is <VAR>@CUPS_LOGDIR@/error_log</VAR>.</P> information to the system log instead of a plain file.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3/Mac OS X 10.5</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.3/OS X 10.5</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2> <H3>Examples</H3> @@ -1225,7 +765,7 @@ printer.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="FatalErrors">FatalErrors</A></H2> <H3>Examples</H3> @@ -1386,23 +926,18 @@ system-specific but is usually <CODE>lp</CODE> or <CODE>nobody</CODE>.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="HideImplicitMembers">HideImplicitMembers</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="GSSServiceName">GSSServiceName</A></H2> <H3>Examples</H3> <PRE CLASS="command"> -HideImplicitMembers Yes -HideImplicitMembers No +GSSServiceName http +GSSServiceName ipp </PRE> <H3>Description</H3> -<P>The <CODE>HideImplicitMembers</CODE> directive controls -whether the individual printers in an implicit class are hidden -from the user. The default is <CODE>Yes</CODE>.</P> - -<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A> -must be enabled for this directive to have any effect.</P> +<P>The <CODE>GSSServiceName</CODE> directive sets the Kerberos service name to use. The default is <CODE>@CUPS_DEFAULT_GSSSERVICE_NAME@</CODE> for compatibility with Microsoft Windows.</P> <H2 CLASS="title"><A NAME="HostNameLookups">HostNameLookups</A></H2> @@ -1431,45 +966,6 @@ performance problems with hostname lookups. Set this option to required.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.10</SPAN><A NAME="ImplicitAnyClasses">ImplicitAnyClasses</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -ImplicitAnyClasses On -ImplicitAnyClasses Off -</PRE> - -<H3>Description</H3> - -<P>The <CODE>ImplicitAnyClasses</CODE> directive controls -whether implicit classes for local and remote printers are -created with the name <CODE>AnyPrinter</CODE>. The default -setting is <CODE>Off</CODE>.</P> - -<P><A HREF="#ImplicitClasses"><CODE>ImplicitClasses</CODE></A> -must be enabled for this directive to have any effect.</P> - - -<H2 CLASS="title"><A NAME="ImplicitClasses">ImplicitClasses</A></H2> - -<H3>Examples</H3> - -<PRE CLASS="command"> -ImplicitClasses On -ImplicitClasses Off -</PRE> - -<H3>Description</H3> - -<P>The <CODE>ImplicitClasses</CODE> directive controls whether -implicit classes are created based upon the available network -printers and classes. The default setting is -<CODE>@CUPS_IMPLICIT_CLASSES@</CODE> but is automatically turned -<CODE>Off</CODE> if <A HREF="#Browsing"><CODE>Browsing</CODE></A> is turned -<CODE>Off</CODE>.</P> - - <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.9</SPAN><A NAME="Include">Include</A></H2> <H3>Examples</H3> @@ -1523,47 +1019,51 @@ JobPrivateValues attribute-name-1 [ ... attribute-name-N ] <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> +"job-originating-host-name", "job-originating-user-name", and "phone".</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> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="JobRetryInterval">JobRetryInterval</A></H2> <H3>Examples</H3> <PRE CLASS="command"> +JobRetryInterval 1w +JobRetryInterval 1d +JobRetryInterval 1h +JobRetryInterval 1m JobRetryInterval 30 -JobRetryInterval 120 </PRE> <H3>Description</H3> -<P>The <CODE>JobRetryInterval</CODE> directive specifies the -number of seconds to wait before retrying a job. This is -typically used for fax queues but can also be used with normal -print queues whose error policy is <CODE>retry-job</CODE>. The -default is 30 seconds.</P> +<P>The <CODE>JobRetryInterval</CODE> directive specifies the amount of time to wait before retrying a job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). This is typically used for fax queues but can also be used with normal print queues whose error policy is <CODE>retry-job</CODE> or <CODE>retry-current-job</CODE>.</P> +<P>The default is <CODE>30</CODE> (30 seconds).</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="JobKillDelay">JobKillDelay</A></H2> + +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="JobKillDelay">JobKillDelay</A></H2> <H3>Examples</H3> <PRE CLASS="command"> +JobKillDelay 1w +JobKillDelay 1d +JobKillDelay 1h +JobKillDelay 1m JobKillDelay 30 -JobKillDelay 120 </PRE> <H3>Description</H3> -<P>The <CODE>JobKillDelay</CODE> directive specifies the number of seconds to -wait before killing the filters and backend associated with a canceled or held -job. The default is 30 seconds.</P> +<P>The <CODE>JobKillDelay</CODE> directive specifies the amount of time to wait before killing the filters and backend associated with a canceled or held job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<P>The default is <CODE>30</CODE> (30 seconds).</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="JobRetryLimit">JobRetryLimit</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="JobRetryLimit">JobRetryLimit</A></H2> <H3>Examples</H3> @@ -1607,15 +1107,18 @@ field of each request.</P> <H3>Examples</H3> <PRE CLASS="command"> -KeepAliveTimeout 60 +KeepAliveTimeout 1w +KeepAliveTimeout 1d +KeepAliveTimeout 1h +KeepAliveTimeout 1m KeepAliveTimeout 30 </PRE> <H3>Description</H3> -<P>The <CODE>KeepAliveTimeout</CODE> directive controls how long -a persistent HTTP connection will remain open after the last -request. The default is 30 seconds.</P> +<P>The <CODE>KeepAliveTimeout</CODE> directive controls how long a persistent HTTP connection will remain open after the last request in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<P>The default is <CODE>30</CODE> (30 seconds).</P> <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Limit">Limit (Location)</A></H2> @@ -1647,7 +1150,7 @@ The request type names are case-sensitive for compatibility with Apache.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="LimitIPP">Limit (Policy)</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="LimitIPP">Limit (Policy)</A></H2> <H3>Examples</H3> @@ -2187,6 +1690,23 @@ copies to 100.</P> </BLOCKQUOTE> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="MaxHoldTime">MaxHoldTime</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +MaxHoldTime 10800 +MaxHoldTime 3h +MaxHoldTime 180m +MaxHoldTime 0 +</PRE> + +<H3>Description</H3> + +<P>The <CODE>MaxHoldTime</CODE> directive controls the maximum number of seconds allowed for a job to remain in the "indefinite" hold state. The job is canceled automatically if it remains held indefinitely longer than the specified time interval in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<p>The default setting is <CODE>0</CODE> which disables this functionality.</P> + <H2 CLASS="title"><A NAME="MaxJobs">MaxJobs</A></H2> @@ -2254,6 +1774,26 @@ active jobs is completed, stopped, aborted, or canceled.</P> default setting is 0.</P> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.6/OS X 10.8</SPAN><A NAME="MaxJobTime">MaxJobTime</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +MaxJobTime 10800 +MaxJobTime 3h +MaxJobTime 180m +MaxJobTime 0 +</PRE> + +<H3>Description</H3> + +<P>The <CODE>MaxJobTime</CODE> directive controls the maximum number of +seconds allowed for a job to complete printing before it is considered "stuck". +The job is canceled automatically if it takes longer than the specified time to complete in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<p>Setting the maximum time to <CODE>0</CODE> disables this functionality. The default setting is <CODE>3h</CODE> (3 hours).</P> + + <H2 CLASS="title"><A NAME="MaxLogSize">MaxLogSize</A></H2> <H3>Examples</H3> @@ -2298,20 +1838,23 @@ HREF="#LimitRequestBody"><CODE>LimitRequestBody</CODE></A> directive instead.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/Mac OS X 10.6</SPAN><A NAME="MultipleOperationTimeout">MultipleOperationTimeout</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.4/OS X 10.6</SPAN><A NAME="MultipleOperationTimeout">MultipleOperationTimeout</A></H2> <H3>Examples</H3> <PRE CLASS="command"> -MultipleOperationTimeout 60 +MultipleOperationTimeout 1w +MultipleOperationTimeout 1d +MultipleOperationTimeout 1h +MultipleOperationTimeout 5m MultipleOperationTimeout 300 -MultipleOperationTimeout 86400 </PRE> <H3>Description</H3> -<P>The <CODE>MultipleOperationTimeout</CODE> directive sets the maximum amount -of time between files in a multi-file print job. The default is 300 seconds.</P> +<P>The <CODE>MultipleOperationTimeout</CODE> directive sets the maximum amount of time between files in a multi-file print job in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<P>The default is <CODE>5m</CODE> (five minutes).</P> <H2 CLASS="title"><A NAME="Order">Order</A></H2> @@ -2417,7 +1960,7 @@ recognized:</P> <P>The default is "%p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides}".</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="PassEnv">PassEnv</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="PassEnv">PassEnv</A></H2> <H3>Examples</H3> @@ -2436,7 +1979,7 @@ scheduler only passes the <CODE>DYLD_LIBRARY_PATH</CODE>, environment variables to child processes.</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="Policy">Policy</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="Policy">Policy</A></H2> <H3>Examples</H3> @@ -2504,20 +2047,24 @@ the IPv4 and IPv6 wildcard address.</P> <PRE CLASS="command"> PreserveJobHistory On PreserveJobHistory Off +PreserveJobHistory 1w +PreserveJobHistory 7d +PreserveJobHistory 168h +PreserveJobHistory 10080m +PreserveJobHistory 604800 </PRE> <H3>Description</H3> -<P>The <CODE>PreserveJobHistory</CODE> directive controls whether -the history of completed, canceled, or aborted print jobs is -stored on disk.</P> +<P>The <CODE>PreserveJobHistory</CODE> directive controls whether the history of completed, canceled, or aborted print jobs is retained by the scheduler. A value of <CODE>On</CODE> preserves job information until the administrator purges it with the <CODE>cancel</CODE> command. A value of <CODE>Off</CODE> removes the job information as soon as each job is completed, canceled, or aborted. Numeric values preserve job information for the specified number of seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> -<P>A value of <CODE>On</CODE> (the default) preserves job -information until the administrator purges it with the -<CODE>cancel</CODE> command.</P> +<P>The default value is <CODE>On</CODE>.</P> -<P>A value of <CODE>Off</CODE> removes the job information as -soon as each job is completed, canceled, or aborted.</P> +<BLOCKQUOTE><B>Note:</B> + +<P>The <A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>, <A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>, and <A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A> directives can cause job history to be discarded to make room for new jobs.</P> + +</BLOCKQUOTE> <H2 CLASS="title"><A NAME="PreserveJobFiles">PreserveJobFiles</A></H2> @@ -2527,21 +2074,26 @@ soon as each job is completed, canceled, or aborted.</P> <PRE CLASS="command"> PreserveJobFiles On PreserveJobFiles Off +PreserveJobFiles 1w +PreserveJobFiles 7d +PreserveJobFiles 168h +PreserveJobFiles 10080m +PreserveJobFiles 604800 </PRE> <H3>Description</H3> -<P>The <CODE>PreserveJobFiles</CODE> directive controls whether -the document files of completed, canceled, or aborted print jobs -are stored on disk.</P> +<P>The <CODE>PreserveJobFiles</CODE> directive controls whether the document files of completed, canceled, or aborted print jobs are retained. Jobs can be restarted (and reprinted) as desired until they are purged.</P> + +<P>A value of <CODE>On</CODE> preserves job files until the administrator purges them with the <CODE>cancel</CODE> command. A value of <CODE>Off</CODE> removes the job files as soon as each job is completed, canceled, or aborted. Numeric values preserve job files for the specified number of seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<P>The default value is <CODE>1d</CODE> (one day).</P> + +<BLOCKQUOTE><B>Note:</B> -<P>A value of <CODE>On</CODE> preserves job files until the -administrator purges them with the <CODE>cancel</CODE> command. -Jobs can be restarted (and reprinted) as desired until they are -purged.</P> +<P>The <A HREF="#MaxJobs"><CODE>MaxJobs</CODE></A>, <A HREF="#MaxJobsPerPrinter"><CODE>MaxJobsPerPrinter</CODE></A>, <A HREF="#MaxJobsPerUser"><CODE>MaxJobsPerUser</CODE></A>, and <A HREF="#PreserveJobHistory"><CODE>PreserveJobHistory</CODE></A> directives can cause job files to be discarded sooner than specified.</P> -<P>A value of <CODE>Off</CODE> (the default) removes the job -files as soon as each job is completed, canceled, or aborted.</P> +</BLOCKQUOTE> <H2 CLASS="title"><A NAME="Printcap">Printcap</A></H2> @@ -2583,7 +2135,7 @@ PrintcapFormat plist <H3>Description</H3> <P>The <CODE>PrintcapFormat</CODE> directive controls the output format of the -printcap file. The default is to generate the plist format on Mac OS X, the +printcap file. The default is to generate the plist format on OS X, the Solaris format on Solaris, and the BSD format on other operating systems.</P> @@ -2717,17 +2269,18 @@ megabytes.</P> <PRE CLASS="command"> RootCertDuration 0 +RootCertDuration 1w +RootCertDuration 1d +RootCertDuration 1h +RootCertDuration 5m RootCertDuration 300 </PRE> <H3>Description</H3> -<P>The <CODE>RootCertDuration</CODE> directive specifies the -number of seconds the <EM>root certificate</EM> remains valid. -The scheduler will generate a new certificate as needed when the -number of seconds has expired. If set to 0, the root certificate -is generated only once on startup or on a restart. The default is -300 seconds.</P> +<P>The <CODE>RootCertDuration</CODE> directive specifies the amount of time the <EM>root certificate</EM> remains valid in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix). The scheduler will generate a new certificate as needed when the given time interval has expired. If set to 0, the root certificate is generated only once on startup or on a restart.</P> + +<P>The default is <CODE>5m</CODE> (five minutes).</P> <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.1.7</SPAN><A NAME="Satisfy">Satisfy</A></H2> @@ -2963,7 +2516,7 @@ the text that is returned. The default is </TABLE></DIV> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="SetEnv">SetEnv</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="SetEnv">SetEnv</A></H2> <H3>Examples</H3> @@ -3032,6 +2585,23 @@ 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.6</SPAN><A NAME="StrictConformance">StrictConformance</A></H2> + +<H3>Examples</H3> + +<PRE CLASS="command"> +StrictConformance No +StrictConformance Yes +</PRE> + +<H3>Description</H3> + +<P>The <CODE>StrictConformance</CODE> directive specifies whether the scheduler +requires strict IPP conformance for client requests, for example to not allow +document attributes in a Create-Job request. The default is +<code>No</code>.</P> + + <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.5</SPAN><A NAME="SubscriptionPrivateAccess">SubscriptionPrivateAccess</A></H2> <H3>Examples</H3> @@ -3127,18 +2697,22 @@ an appropriate temporary directory called <H3>Examples</H3> <PRE CLASS="command"> +Timeout 1w +Timeout 1d +Timeout 1h +Timeout 5m Timeout 300 -Timeout 90 </PRE> <H3>Description</H3> <P>The <CODE>Timeout</CODE> directive controls the amount of time -to wait before an active HTTP or IPP request times out. The -default timeout is 300 seconds.</P> +to wait before an active HTTP or IPP request times out in seconds (no suffix), minutes ("m" suffix), hours ("h" suffix), days ("d" suffix), or weeks ("w" suffix).</P> + +<P>The default timeout is <CODE>5m</CODE> (five minutes).</P> -<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/Mac OS X 10.5</SPAN><A NAME="UseNetworkDefault">UseNetworkDefault</A></H2> +<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2/OS X 10.5</SPAN><A NAME="UseNetworkDefault">UseNetworkDefault</A></H2> <H3>Examples</H3> diff --git a/doc/help/ref-ppdcfile.html b/doc/help/ref-ppdcfile.html index c3967f1c..1c77a735 100644 --- a/doc/help/ref-ppdcfile.html +++ b/doc/help/ref-ppdcfile.html @@ -148,7 +148,7 @@ and the underscore. The value can be any valid expression.</p> ... #else ... -#endif +#endif </pre> <h3>Description</h3> @@ -181,7 +181,7 @@ corresponding <a href="#_if"><code>#if</code></a> directive.</p> ... #else ... -#endif +#endif </pre> <h3>Description</h3> @@ -215,7 +215,7 @@ expressions are non-zero.</p> ... #else ... -#endif +#endif </pre> <h3>Description</h3> @@ -302,7 +302,7 @@ defining the standard raster fonts in the ... #else ... -#endif +#endif </pre> <h3>Description</h3> @@ -405,7 +405,7 @@ suffixes:</p> </ul> -<p>Points are assumed if no units are specified. +<p>Points are assumed if no units are specified. <h3>See Also</h3> @@ -434,7 +434,7 @@ suffixes:</p> <p>The <code>#po</code> directive defines a message catalog to use for the given POSIX language abbreviation. Multiple <code>#po</code> directives can be specified to list multiple catalogs. The filename can be an absolute path or -relative to the driver information file. GNU gettext and Mac OS X .strings +relative to the driver information file. GNU gettext and OS X .strings files are supported.</p> @@ -1111,7 +1111,7 @@ Adobe PPD file specification.</p> either the word <code>ROM</code> or <code>Disk</code>.</p> <p>Device fonts differ from fonts defined using the <a -href='#_font'><code>#font</code></a> directive in that they are +href='#_font'><code>#font</code></a> directive in that they are automatically associated with the current driver. Fonts defined using <code>#font</code> may be imported into the current driver using the <code>Font *</code> form of this directive.</p> @@ -1597,7 +1597,7 @@ Option <i>"name/text" type section order</i> <pre> Option Punch Boolean AnySetup 10 -Option "fooFinish/Finishing Option" PickOne DocumentSetup 10 +Option "fooFinish/Finishing Option" PickOne DocumentSetup 10 </pre> <h3>Description</h3> @@ -1798,7 +1798,7 @@ SimpleColorProfile 720dpi/Glossy 100 90 120 1.5 -5 5 10 <h3>Description</h3> <p>The <code>SimpleColorProfile</code> directive creates a -matrix-based <a href="#ColorProfile"><code>ColorProfile</code></a>. +matrix-based <a href="#ColorProfile"><code>ColorProfile</code></a>. The resolution and mediatype arguments specify the <code>Resolution</code> and <code>MediaType</code> choices which use the profile; the hyphen (<code>-</code>) is used to specify that any @@ -2414,8 +2414,8 @@ supported keywords for each type.</p> <BR> - <BR><A NAME="REF_COLOR_APPLE">*</A> = This colorspace is not supported on Mac OS X prior to 10.4. - <BR><A NAME="REF_COLOR_APPLE2">**</A> = This colorspace is not supported on Mac OS X.</LI> + <BR><A NAME="REF_COLOR_APPLE">*</A> = This colorspace is not supported on OS X prior to 10.4. + <BR><A NAME="REF_COLOR_APPLE2">**</A> = This colorspace is not supported on OS X.</LI> </UL> @@ -2441,7 +2441,7 @@ supported keywords for each type.</p> <BR><A NAME="REF_COLOR_APPLE2">*</A> = This color order is not supported by the current Apple RIP filters and should not be used when developing printer drivers for - Mac OS X.</LI> + OS X.</LI> </UL> diff --git a/doc/help/ref-printers-conf.html b/doc/help/ref-printers-conf.html index 9568fc7c..bb44c4c6 100644 --- a/doc/help/ref-printers-conf.html +++ b/doc/help/ref-printers-conf.html @@ -151,7 +151,7 @@ HREF="#AllowUser"><CODE>AllowUser</CODE></A></P> <H3>Description</H3> -<P>The <CODE>DeviceURI</CODE> directive defines the value of the +<P>The <CODE>DeviceURI</CODE> directive defines the value of the <VAR>device-uri-attribute</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -248,7 +248,7 @@ in the printer's PPD file.</P> <H3>Description</H3> -<P>The <CODE>Info</CODE> directive defines the string for the +<P>The <CODE>Info</CODE> directive defines the string for the <VAR>printer-info</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -337,7 +337,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>KLimit</CODE> directive defines the value of the +<P>The <CODE>KLimit</CODE> directive defines the value of the <VAR>job-k-limit</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -364,7 +364,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>Location</CODE> directive defines the string for the +<P>The <CODE>Location</CODE> directive defines the string for the <VAR>printer-location</VAR> attribute. It is normally set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -449,7 +449,7 @@ section.</P> <H3>Description</H3> -<P>The <CODE>PageLimit</CODE> directive defines the value of the +<P>The <CODE>PageLimit</CODE> directive defines the value of the <VAR>job-page-limit</VAR> attribute. It can be set using the <CODE>lpadmin(8)</CODE> command:</P> @@ -665,7 +665,7 @@ section.</P> <PRE CLASS="command"> <Printer name> ... - StateMessage Ready to print. + StateMessage Printer is lonely. </Printer> </PRE> @@ -682,7 +682,6 @@ StateMessage Network host host_name is busy; will retry in 30 seconds... StateMessage Printer busy; will retry in 10 seconds... StateMessage Printer is busy; retrying print job... StateMessage Print file accepted - job ID id_number. -StateMessage Ready to print. StateMessage Waiting for job to complete </PRE> diff --git a/doc/help/ref-snmp-conf.html b/doc/help/ref-snmp-conf.html index db4aacee..4cab237e 100644 --- a/doc/help/ref-snmp-conf.html +++ b/doc/help/ref-snmp-conf.html @@ -55,9 +55,8 @@ Community BigCorp <H3>Description</H3> <P>The <CODE>Community</CODE> directive specifies a community -name to use when discovering printers. Multiple -<CODE>Community</CODE> lines can be provided to scan different -SNMP communities.</P> +name to use when discovering printers and reporting status and supply +levels for network printers.</P> <P>The default community is "public".</P> diff --git a/doc/help/sharing.html b/doc/help/sharing.html index 00ccb6fe..e13cfed4 100644 --- a/doc/help/sharing.html +++ b/doc/help/sharing.html @@ -12,123 +12,46 @@ <h2><a name="BASICS">The Basics</h2> -<p>A "server" is any machine that communicates directly to a printer. A "client" -is any machine that sends print jobs to a server for final printing. Clients can -also be servers if they communicate directly with any printers of their own.</p> +<p>A "server" is any machine that communicates directly to a printer. A "client" is any machine that sends print jobs to a server for final printing. Clients can also be servers if they communicate directly with any printers of their own.</p> -<p>By default, CUPS uses the Internet Printing Protocol (IPP) to send jobs from -a client to a server. When printing to legacy print servers you may also use the -Line Printer Daemon (LPD) when printing to older UNIX-based servers or Server -Message Block (SMB) when printing to Windows<sup>®</sup> servers.</p> +<p>By default, CUPS uses the Internet Printing Protocol (IPP) to send jobs from a client to a server. When printing to legacy print servers you may also use the Line Printer Daemon (LPD) protocol when printing to older UNIX-based servers or Server Message Block (SMB) when printing to Windows<sup>®</sup> servers.</p> -<p>Clients can automatically discover and access shared printers via CUPS -browsing, IPP, Service Location Protocol (SLP), and Lightweight Directory Access -Protocol (LDAP). DNS Service Discovery (DNS-SD a.k.a. Bonjour<sup>®</sup>) -and SMB browsing can also be used to manually discover and access shared -printers.</p> +<p>Clients can automatically discover and access shared printers via DNS Service Discovery (DNS-SD a.k.a. Bonjour<sup>®</sup>). SMB browsing can also be used to manually discover and access shared printers when <a href="http://www.samba.org/">Samba</a> is installed.</p> <h2><a name="SERVER_CONFIG">Configuring the Server</a></h2> -<p>You must enable printer sharing on the server before clients can print -through it. The simplest way to do this is to use the -<a href="man-cupsctl.html">cupsctl(8)</a> command on the server:</p> +<p>You must enable printer sharing on the server before clients can print through it. The simplest way to do this is to use the <a href="man-cupsctl.html">cupsctl(8)</a> command on the server:</p> <pre class="command"> cupsctl --share-printers </pre> -<p>By default, the above command will allow printing from other clients on the -same subnet as your server. To allow printing from any subnet, use the following -command instead:</p> +<p>By default, the above command will allow printing from other clients on the same subnet as your server. To allow printing from any subnet, use the following command instead:</p> <pre class="command"> cupsctl --share-printers --remote-any </pre> -<p>Next, you need to choose which protocols to use for printer sharing. The -default is CUPS browsing and DNS-SD on Mac OS X and CUPS browsing alone on -other platforms. To set the sharing protocols, run the <b>cupsctl</b> command -to set the -<a href="ref-cupsd-conf.html#BrowseLocalProtocols">BrowseLocalProtocols</a> -value. For example, run the following command to allow shared printing via -CUPS, DNS-SD, LPD, and SMB:</p> +<p>Next, tag each printer that you want to share using the <a href="man-lpadmin.html">lpadmin(8)</a> command on the server, for example:</p> <pre class="command"> -cupsctl 'BrowseLocalProtocols="cups dnssd lpd smb"' +lpadmin -p printer -o printer-is-shared=true </pre> - -<h2><a name="AUTO_CUPS">Automatic Configuration using CUPS Browsing</a></h2> - -<p>CUPS browsing works by periodically broadcasting information about printers -that are being shared to client systems on the same subnet. Each client -maintains its own list of shared printers, and when more than one server shares -the same printer (or the same kind of printer) the client uses all of the -servers and printers to provide high-availability and failsafe printing.</p> - -<p>To configure printers on the same subnet, <em>do nothing</em>. Each client -should see the available printers within 30 seconds automatically. The printer -and class lists are updated automatically as printers and servers are added or -removed.</p> - -<blockquote><b>Note:</b> - -<p>Due to user interface changes in Mac OS X 10.5, CUPS shared printers will not -automatically appear in the print dialog. Instead, you must first run the -following command to enable CUPS browsing on your system:</p> - -<pre class="command"> -cupsctl BrowseRemoteProtocols=cups -</pre> - -<p>Then choose each of the CUPS shared printers you want to see in the print -dialog by adding them, either from the <var>Add Printer...</var> item in the -print dialog or from the <var>Print & Fax</var> preference pane in the -<var>System Preferences</var> window.</p> - -</blockquote> - -<h3><a name="BROWSE_POLL">Seeing Printers on Other Subnets</a></h3> - -<p>You can automatically access printers on other subnets by adding -<a href="ref-cupsd-conf.html#BrowsePoll"><code>BrowsePoll</code></a> lines -to the <var>cupsd.conf</var> file on your local system. For a single -server you can use the <b>cupsctl</b> command:</p> +<p>You can require authentication for shared printing by setting the policy on each printer, for example:</p> <pre class="command"> -cupsctl BrowsePoll=server:port -</pre> - -<p>For multiple servers, use the CUPS web interface (http://localhost:631/admin) -to edit the configuration file instead. Enter one <code>BrowsePoll</code> line -per server at the bottom of the file, as follows:</p> - -<pre class="example"> -BrowsePoll server1:port -BrowsePoll server2:port -BrowsePoll server3:port -</pre> - -<p>If you have more than one client on your subnet that wants to see the -printers on those servers, add a -<a href="ref-cupsd-conf.html#BrowseRelay"><code>BrowseRely</code></a> line -to the <var>cupsd.conf</var> file on your local system using the <b>cupsctl</b> -command:</p> - -<pre class="command"> -cupsctl 'BrowseRelay="127.0.0.1 @LOCAL"' -</pre> - -<p>or CUPS web interface (again, at the bottom of the file):</p> - -<pre class="example"> -BrowseRelay 127.0.0.1 @LOCAL +lpadmin -p printer -o printer-op-policy=authenticated </pre> <h2><a name="AUTO_IPP">Automatic Configuration using IPP</a></h2> +<blockquote><b>Note:</b> +<p>This method of configuration does not work on OS X 10.7 or later because sandboxed applications do not always have direct network access.</p> +</blockquote> + <p>CUPS can be configured to run without a local spooler and send all jobs to a single server. However, if that server goes down then all printing will be disabled. Use this configuration only as absolutely necessary.</p> @@ -167,6 +90,10 @@ port. The environment variable overrides both the user and system <h2><a name="MANUAL">Manual Configuration of Print Queues</a></h2> +<blockquote><b>Note:</b> +<p>This method of configuration does not work on OS X 10.7 or later because sandboxed applications do not always have direct network access.</p> +</blockquote> + <p>The most tedious method of configuring client machines is to configure each remote queue by hand using the <a href="man-lpadmin.html">lpadmin(8)</a> command:</p> diff --git a/doc/help/spec-cmp.html b/doc/help/spec-cmp.html index 47f56d31..2c66e320 100644 --- a/doc/help/spec-cmp.html +++ b/doc/help/spec-cmp.html @@ -11,87 +11,66 @@ <P>This developer guide documents the guidelines and processes we use when developing and maintaining CUPS and related software. Our goal is to provide reliable and efficient software and documentation that addresses the needs of our users.</P> +<H2 CLASS="title"><A NAME="OVERVIEW">Overview</A></H2> + +<P>CUPS is developed by Apple Inc. and distributed as open source software under a combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow linking to OpenSSL (which has a GPL-incompatible license) and for developers on Apple's operating systems to develop CUPS-based software until alternate license terms. Significant contributions to CUPS must be licensed to Apple using the <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">Apple Contributor Agreement</A>.</P> + +<P>Apple releases updates to the CUPS software approximately every three months. Each release has a version number consisting of the major version (currently 1), minor version (currently 6), and patch version (starting at 0) separated by the period, for example "1.6.0". Releases where only the patch version number changes will contain only bug fixes to the previous release, for example "1.6.1" includes bug fixes for the "1.6.0" release. New features require the major or minor version numbers to change, for example "1.6.0" release contains new features compared to the "1.5.3" release. Multiple beta and "candidate" releases generally precede each new feature release, for example "1.5b1", "1.5b2", and "1.5rc1" preceded the "1.5.0" release. Finally, we also post regular Subversion snapshot releases, for example "1.6svn-r10486", which represent a snapshot of the development for the next feature release.</P> + +<P>CUPS interfaces, including the C APIs and command-line arguments, environment variables, configuration files, and output format, are stable across patch versions and are generally backwards-compatible with interfaces used in prior major and minor versions. However, program interfaces such as those used by the scheduler to run filter, port monitor, and backend processes for job processing should only be considered stable from the point of view of a filter, port monitor, or backend. Software that simulates the scheduler in order to run those programs outside of CUPS must necessarily be updated when the corresponding interface is changed in a subsequent CUPS release, otherwise undefined behavior can occur.</P> + +<P>CUPS C APIs starting with an underscore (_) are considered to be private to CUPS and are not subject to the normal guarantees of stability between CUPS releases and must <em>never</em> be used in non-CUPS source code. Similarly, configuration and state files written by CUPS are considered private if a corresponding man page is not provided with the CUPS release. <em>Never</em> rely on undocumented files or formats when developing software for CUPS. <em>Always</em> use a published C API to access data stored in a file to avoid compatibility problems in the future.</P> + + <H2 CLASS="title"><A NAME="COMMUNICATION">Communication</A></H2> <H3><A NAME="CONTACT">How to Contact the Developers</A></H3> -<P>The <A HREF="http://www.cups.org/newsgroups.php">CUPS -Forums</A> are the primary means of asking questions and -informally discussing issues and feature requests with the CUPS -developers. Table 1 shows the available forums and their -focus:</P> +<P>The <A HREF="http://lists.cups.org/">CUPS Mailing Lists</A> are the primary means of asking questions and informally discussing issues and feature requests with the CUPS developers and other experienced CUPS users and developers. Table 1 shows the available mailing lists and their focus:</P> <DIV CLASS="table"><TABLE SUMMARY="CUPS Forums"> -<CAPTION>Table 1: CUPS Forums</CAPTION> +<CAPTION>Table 1: CUPS Mailing Lists</CAPTION> <TR> - <TH>Forum</TH> + <TH>List</TH> <TH>Focus/Purpose</TH> </TR> <TR> - <TD>cups.bugs</TD> - <TD>Discussion of bugs and issues in the CUPS - software</TD> -</TR> -<TR> - <TD>cups.commit</TD> - <TD>Report of all commits to the Subversion repository - (read-only)</TD> + <TD>cups</TD> + <TD>General discussion and usage questions for the CUPS software</TD> </TR> <TR> - <TD>cups.ddk</TD> - <TD>Usage and development questions for the CUPS Driver - Development Kit</TD> + <TD>cups-bugs</TD> + <TD>Discussion of bugs and issues in the CUPS software</TD> </TR> <TR> - <TD>cups.development</TD> - <TD>Development questions and discussion of new features - in the CUPS software</TD> + <TD>cups-commit</TD> + <TD>Report of all commits to the Subversion repository (read-only)</TD> </TR> <TR> - <TD>cups.general</TD> - <TD>Usage questions for the CUPS software</TD> + <TD>cups-dev</TD> + <TD>Development questions and discussion of new features in the CUPS software</TD> </TR> </TABLE></DIV> + <H3><A NAME="SUBMIT">How to Submit a Bug Report or Feature Request</A></H3> -<P>The CUPS "<A HREF="http://www.cups.org/str.php">Bugs & -Features</A>" page provides access to the CUPS <em>software -trouble report</em> database and is the formal way to submit a -bug report or feature request to the CUPS developers. Please -note, however, that we <em>do not</em> provide answers to usage -questions or resolve problems in third-party software on this -page - use the CUPS Forums for that instead.</P> - -<P>Unlike discussions that occur on the CUPS Forums, formal bug -reports and feature requests must be acted on by the CUPS -developers. This does not mean that every bug report is resolved -or every feature request is implemented, but we do respond and -keep track of them all for posterity.</P> - -<BLOCKQUOTE>Please use the search feature of the Bugs & -Features page before submitting a new bug report or feature -request. If you see an existing report that matches your issue, -please post a message to that report ("I have this issue as -well", "I would also like to see", etc.) rather than submitting a -new report. This helps speed the resolution of your issue by -reducing the CUPS developers' work load.</BLOCKQUOTE> +<P>The CUPS "<A HREF="http://www.cups.org/str.php">Bugs & Features</A>" page provides access to the CUPS <em>Software Trouble Report</em> (STR) database and is the formal way to submit a bug report or feature request to the CUPS developers. Please note, however, that we <em>do not</em> provide answers to usage questions or resolve problems in third-party software on this page - use the <A HREF="#CONTACT">CUPS Mailing Lists</A> for that instead.</P> + +<P>Unlike discussions that occur on the CUPS Mailing Lists, formal bug reports and feature requests must be acted on by the CUPS developers. This does not mean that every bug report is resolved or every feature request is implemented, but we do respond and keep track of them all for posterity.</P> + +<BLOCKQUOTE>Please use the search feature of the Bugs & Features page before submitting a new bug report or feature request. If you see an existing report that matches your issue, please post a message to that report ("I have this issue as well", "I would also like to see", etc.) rather than submitting a new report. This helps speed the resolution of your issue by reducing the CUPS developers' work load and identifying popular issues.</BLOCKQUOTE> + <H3><A NAME="PATCH">How to Prepare a Patch</A></H3> -<P>When submitting a bug report or feature request, you can -include patch files that resolve the bug or implement the feature -to speed the inclusion of that bug fix or feature in a new CUPS -release. For changes to existing files, we prefer a unified diff -against the current Subversion <VAR>trunk</VAR> branch, which can -be generated easily using the following Subversion command:</P> +<P>When submitting a bug report or feature request, you can include patch files that resolve the bug or implement the feature to speed the inclusion of that bug fix or feature in a new CUPS release. For changes to existing files, we prefer a unified diff against the current Subversion <VAR>trunk</VAR> branch, which can be generated easily using the following Subversion command:</P> <PRE CLASS="command"> svn diff >filename.patch </PRE> -<P>If you produce a patch using a released source archive, use -one of the following commands instead:</P> +<P>If you produce a patch using a released source archive, use one of the following commands instead:</P> <PRE CLASS="command"> diff -u oldfilename filename >filename.patch @@ -99,36 +78,22 @@ diff -u oldfilename filename >filename.patch diff -urN olddirectory directory >filename.patch </PRE> -<P>New files and files with significant changes can be submitted -in their entirety, however that may delay the adoption of your -changes.</P> +<P>New files and files with significant changes can be submitted in their entirety, however that may delay the adoption of your changes.</P> + +<BLOCKQUOTE><B>Note:</B> -<BLOCKQUOTE>Patches and files must conform to the standards outlined in the -"<A HREF="#CODING">Coding Guidelines</A>" and "<A HREF="#MAKEFILES">Makefile -Guidelines</A>" sections in this document. In addition, since Apple Inc. -provides CUPS under multiple licenses, we require that you assign the copyright -for your changes and files to us for inclusion in CUPS.</BLOCKQUOTE> +<P>Patches and files must conform to the standards outlined in the "<A HREF="#CODING">Coding Guidelines</A>" and "<A HREF="#MAKEFILES">Makefile Guidelines</A>" sections in this document. In addition, since Apple Inc. provides CUPS under multiple licenses, we require that you <A HREF="http://www.cups.org/AppleContributorAgreement_2011-03-10.pdf">license</A> significant changes and files to us for inclusion in CUPS. The CUPS developers will inform you if licensing is required.</P></BLOCKQUOTE> <H2 CLASS="title"><A NAME="PRACTICES">Software Development Practices</A></H2> <H3><A NAME="VERSIONS">Version Numbering</A></H3> -<P>CUPS uses a three-part version number separated by periods to -represent the major, minor, and patch release numbers. Major -release numbers indicate large design changes or -backwards-incompatible changes to the CUPS API or CUPS Imaging -API. Minor release numbers indicate new features and other -smaller changes which are backwards-compatible with previous CUPS -releases. Patch numbers indicate bug fixes to the previous -release.</P> - -<BLOCKQUOTE>When we talk about compatibility, we are talking -about binary compatibility for public APIs and output format -compatibility for program interfaces. Changes to configuration -file formats or the default behavior of programs are not -generally considered incompatible as the upgrade process can -normally address such changes gracefully.</BLOCKQUOTE> +<P>CUPS uses a three-part version number separated by periods to represent the major, minor, and patch release numbers. Major release numbers indicate large design changes or backwards-incompatible changes to the CUPS API or CUPS Imaging API. Minor release numbers indicate new features and other smaller changes which are backwards-compatible with previous CUPS releases. Patch numbers indicate bug fixes to the previous feature release.</P> + +<BLOCKQUOTE><B>Note:</B> + +<P>When we talk about compatibility, we are talking about binary compatibility for public APIs and output format compatibility for program interfaces. Changes to configuration file formats or the default behavior of programs are not generally considered incompatible as the upgrade process can normally address such changes gracefully.</P></BLOCKQUOTE> <P>Production releases use the plain version numbers:</P> @@ -149,59 +114,44 @@ MAJOR.MINOR.PATCH 2.0.0 </PRE> -<P>The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is -called a feature release. Feature releases are the only releases that may -contain new features. Subsequent production releases in a MAJOR.MINOR series may -only contain bug fixes.</P> +<P>The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called a feature release. Feature releases are the only releases that may contain new features. Subsequent production releases in a MAJOR.MINOR series may only contain bug fixes.</P> + +<BLOCKQUOTE><B>Note:</B> -<BLOCKQUOTE>We did not hold to this limitation in the CUPS 1.1 series for a -variety of reasons. Starting with CUPS 1.2, the "no new features in a patch -release" policy has been strictly enforced. The policy has also resulted in -fewer new features (and interactions!) to validate/test in the subsequence -feature releases.</BLOCKQUOTE> +<P>We did not hold to this limitation in the CUPS 1.1 series for a variety of reasons. Starting with CUPS 1.2, the "no new features in a patch release" policy has been strictly enforced. The policy has also resulted in fewer new features (and interactions!) to validate/test in the subsequence feature releases.</P></BLOCKQUOTE> -<P>Beta-test releases are identified by appending the letter B to the major and -minor version numbers followed by the beta release number:</P> +<P>Beta-test releases are identified by appending the letter B to the major and minor version numbers followed by the beta release number:</P> <PRE CLASS="command"> MAJOR.MINORbNUMBER 1.2b1 </PRE> -<P>Release candidates are identified by appending the letters RC to the major -and minor version numbers followed by the release candidate number:</P> +<P>Release candidates are identified by appending the letters RC to the major and minor version numbers followed by the release candidate number:</P> <PRE CLASS="command"> MAJOR.MINORrcNUMBER 1.2rc1 </PRE> -<P>Developer snapshots are identified by appending the letters SVN-R to the -major and minor version numbers followed by the revision number:</P> +<P>Developer snapshots are identified by appending the letters SVN-R to the major and minor version numbers followed by the revision number:</P> <PRE CLASS="command"> MAJOR.MINORsvn-rREV 1.2svn-r1234 </PRE> -<P>Beta-test releases, release candidates, and developer snapshots are only -created for new minor releases. Once a production release has been made -(MAJOR.MINOR.0), subsequent patch releases are issues without preliminary beta -or release testing.</P> +<P>Beta-test releases, release candidates, and developer snapshots are only created for new minor releases. Once a production release has been made (MAJOR.MINOR.0), subsequent patch releases are issued without preliminary beta or release testing.</P> <H3>Version Control (Subversion)</H3> -<P>The CUPS source files are managed by the Subversion ("SVN") -software, available at:</P> +<P>The CUPS source files are managed by the Subversion ("SVN") software, available at:</P> <PRE CLASS="command"> -<A HREF="http://subversion.tigris.org/" TARGET="_blank">subversion.tigris.org</A> +<A HREF="http://subversion.apache.org/" TARGET="_blank">subversion.apache.org</A> </PRE> -<P>Source files are "checked in" with each change so that -modifications can be tracked, and each checkin must reference any -applicable STRs. The following format <em>must</em> be used for -commit log messages:</P> +<P>Source files are "checked in" with each change so that modifications can be tracked, and each checkin must reference any applicable STRs. The following format <em>must</em> be used for commit log messages:</P> <PRE CLASS="command"> Summary of the change on one line followed by bug number (STR #NNNN) @@ -209,10 +159,7 @@ Summary of the change on one line followed by bug number (STR #NNNN) Detailed list of changes. </PRE> -<P>Primary development occurs on the <var>trunk</var> branch, -with changes merged back to release branches as needed. Table 2 -shows the URLs developers use for the various CUPS sub-projects -and branches:</P> +<P>Primary development occurs on the <var>trunk</var> branch, with changes merged back to release branches as needed. Table 2 shows the URLs developers use for the various CUPS sub-projects and branches:</P> <DIV CLASS="table"><TABLE SUMMARY="CUPS Subversion URLs"> <CAPTION>Table 2: CUPS Subversion URLs</CAPTION> @@ -221,113 +168,55 @@ and branches:</P> <TH>Purpose</TH> </TR> <TR> - <TD><A HREF="http://svn.easysw.com/public/cups/trunk/">https://svn.easysw.com/public/cups/trunk/</A></TD> + <TD><A HREF="http://svn.cups.org/public/cups/trunk/">https://svn.cups.org/public/cups/trunk/</A></TD> <TD>Primary CUPS development branch</TD> </TR> <TR> - <TD><A HREF="http://svn.easysw.com/public/cups/branches/">https://svn.easysw.com/public/cups/branches/</A></TD> + <TD><A HREF="http://svn.cups.org/public/cups/branches/">https://svn.cups.org/public/cups/branches/</A></TD> <TD>CUPS maintenance branches (merge-only)</TD> </TR> <TR> - <TD><A HREF="http://svn.easysw.com/public/cups/tags/">https://svn.easysw.com/public/cups/tags/</A></TD> + <TD><A HREF="http://svn.cups.org/public/cups/tags/">https://svn.cups.org/public/cups/tags/</A></TD> <TD>CUPS release tags (read-only)</TD> </TR> -<TR> - <TD><A HREF="http://svn.easysw.com/public/windows/trunk/">https://svn.easysw.com/public/windows/trunk/</A></TD> - <TD>Primary CUPS Windows Driver development branch</TD> -</TR> -<TR> - <TD><A HREF="http://svn.easysw.com/public/windows/branches/">https://svn.easysw.com/public/windows/branches/</A></TD> - <TD>CUPS Windows Driver maintenance branches (merge-only)</TD> -</TR> -<TR> - <TD><A HREF="http://svn.easysw.com/public/windows/tags/">https://svn.easysw.com/public/windows/tags/</A></TD> - <TD>CUPS Windows Driver release tags (read-only)</TD> -</TR> </TABLE></DIV> -<P>The branch for a MAJOR.MINOR release are created when the -first production release (MAJOR.MINOR.0) is made using the name -"branch-MAJOR.MINOR". Release tags are created for every beta, -candidate, and production release using the name -"release-MAJOR.MINOR.PATCHbNUMBER", -"release-MAJOR.MINOR.PATCHrcNUMBER", or -"release-MAJOR.MINOR.PATCH", respectively. No release tags are -created for developer snapshots.</P> +<P>The branch for a MAJOR.MINOR release are created when the first production release (MAJOR.MINOR.0) is made using the name "branch-MAJOR.MINOR". Release tags are created for every beta, candidate, and production release using the name "release-MAJOR.MINORbNUMBER", "release-MAJOR.MINORrcNUMBER", or "release-MAJOR.MINOR.PATCH", respectively. No release tags are created for developer snapshots.</P> <H3>Files and Directories</H3> -<P>File and directory names may not exceed 16 characters in -length to ensure compatibility with older UNIX filesystems. In -addition, to avoid problems with case-insensitive filesystems, -you may not use names which differ only by case, for example -"ReadMe" and "README" are not allowed in the same directory.</P> +<P>File and directory names may not exceed 16 characters in length to ensure compatibility with older UNIX filesystems. In addition, to avoid problems with case-insensitive filesystems, you may not use names which differ only by case, for example "ReadMe" and "README" are not allowed in the same directory.</P> -<P>Source files must be documented and formatted as described in -"<A HREF="#CODING">Coding Requirements</A>". Make files must -follow the guidelines in "<A HREF="#MAKEFILE">Makefile -Guidelines</A>".</P> +<P>Source files must be documented and formatted as described in "<A HREF="#CODING">Coding Requirements</A>". Makefiles must follow the guidelines in "<A HREF="#MAKEFILE">Makefile Guidelines</A>".</P> <H3>Build System</H3> -<P>The CUPS build system uses <A -HREF="http://www.gnu.org/software/autoconf/">GNU autoconf</A> to -tailor the library to the local operating system. Project files -for major IDEs are also provided for Microsoft -Windows<SUP>®</SUP>. To improve portability, makefiles must -not make use of the unique features offered by <A -HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A -HREF="#MAKEFILES">Makefile Guidelines</A> section for a -description of the allowed make features and makefile -guidelines.</P> - -<P>Additional GNU build programs such as <A -HREF="http://www.gnu.org/software/automake">GNU automake</A> and -<A HREF="http://www.gnu.org/software/libtool">GNU libtool</A> -must not be used. GNU automake produces non-portable makefiles -which depend on GNU-specific extensions, and GNU libtool is not -portable or reliable enough for CUPS.</P> +<P>The CUPS build system uses <A HREF="http://www.gnu.org/software/autoconf/">GNU autoconf</A> to tailor the library to the local operating system. Project files for the current release of Visual C++ are also provided for Microsoft Windows<SUP>®</SUP>. To improve portability, makefiles must not make use of features unique to <A HREF="http://www.gnu.org/software/make/">GNU make</A>. See the <A HREF="#MAKEFILES">Makefile Guidelines</A> section for a description of the allowed make features and makefile guidelines.</P> + +<P>Additional GNU build programs such as <A HREF="http://www.gnu.org/software/automake">GNU automake</A> and <A HREF="http://www.gnu.org/software/libtool">GNU libtool</A> must not be used. GNU automake produces non-portable makefiles which depend on GNU-specific extensions, and GNU libtool is not portable or reliable enough for CUPS.</P> <H3><A NAME="PACKAGING">Packaging</A></H3> -<P>Source packages are created using the -<VAR>tools/makesrcdist</VAR> script in the Subversion repository. -The script optionally uses a version number argument:</P> +<P>Source packages are created using the <VAR>tools/makesrcdist</VAR> script in the Subversion repository. The script optionally uses a version number argument:</P> <PRE CLASS="command"> tools/makesrcdist tools/makesrcdist <I>version</I> </PRE> -<P>When run with no arguments, the script creates a snapshot of -the current working copy and names it using the highest revision -number in the WC, for example -"/tmp/cups-1.3svn-r1234-source.tar.bz2" and -"/tmp/cups-1.3svn-r1234-source.tar.gz". When run with two -arguments, the script creates a release tag in the repository and -exports that tag, creating the files -"/tmp/cups-<I>version</I>-source.tar.bz2" and -"/tmp/cups-<I>version</I>-source.tar.gz".</P> - -<P>Binary packages are not generally distributed by the CUPS -team, however the <VAR>packaging/cups.spec</VAR> and -<VAR>packaging/cups.list</VAR> files may be used to create binary -packages on Linux, Mac OS X, and UNIX. The -<VAR>packaging/cups.spec</VAR> file produces a binary package -using the <CODE>rpmbuild(8)</CODE> software:</P> +<P>When run with no arguments, the script creates a snapshot of the current working copy and names it using the highest revision number in the WC, for example "/tmp/cups-1.3svn-r1234-source.tar.bz2" and "/tmp/cups-1.3svn-r1234-source.tar.gz". When run with two arguments, the script creates a release tag in the repository and exports that tag, creating the files +"/tmp/cups-<I>version</I>-source.tar.bz2" and "/tmp/cups-<I>version</I>-source.tar.gz".</P> + +<P>Binary packages are not generally distributed by the CUPS team, however the <VAR>packaging/cups.spec</VAR> and <VAR>packaging/cups.list</VAR> files may be used to create binary packages on Linux, OS X, and UNIX. The <VAR>packaging/cups.spec</VAR> file produces a binary package using the <CODE>rpmbuild(8)</CODE> software:</P> <PRE CLASS="command"> rpmbuild -ta cups-<I>version</I>-source.tar.gz </PRE> -<P>The <VAR>cups.list</VAR> file is generated by the -<VAR>configure</VAR> script and produces binary packages for many -platforms using the <A HREF="http://www.easysw.com/epm/" -TARGET="_blank">EPM</A> software. Table 3 shows the targets that -are available for each type of binary package:</P> +<P>The <VAR>cups.list</VAR> file is generated by the <VAR>configure</VAR> script and produces binary packages for many platforms using the <A HREF="http://www.epmhome.org/" TARGET="_blank">EPM</A> software. Table 3 shows the targets that are available for each type of binary package:</P> <DIV CLASS="table"><TABLE SUMMARY="Binary Package Targets"> <CAPTION>Table 3: Binary Package Targets</CAPTION> @@ -360,10 +249,6 @@ are available for each type of binary package:</P> <TD>IRIX inst/tardist</TD> </TR> <TR> - <TD>osx</TD> - <TD>Mac OS X Install</TD> -</TR> -<TR> <TD>pkg</TD> <TD>Solaris pkgadd</TD> </TR> @@ -389,10 +274,7 @@ are available for each type of binary package:</P> </TR> </TABLE></DIV> -<P>Finally, the <VAR>tools/testrpm</VAR> and -<VAR>tools/testosx</VAR> scripts can be used to create binary -packages from the current working copy for testing on Linux and -Mac OS X, respectively:</P> +<P>Finally, the <VAR>tools/testrpm</VAR> and <VAR>tools/testosx</VAR> scripts can be used to create binary packages from the current working copy for testing on Linux and OS X, respectively:</P> <PRE CLASS="command"> tools/testrpm @@ -405,26 +287,18 @@ open cups.pkg <H3><A NAME="TESTING">Testing</A></H3> -<P>Software testing is conducted according to the <A -HREF="spec-stp.html">CUPS Software Test Plan</A>. This testing is -automated via the top-level makefile <VAR>test</VAR> target:</P> +<P>Software testing is conducted according to the <A HREF="spec-stp.html">CUPS Software Test Plan</A>. This testing is automated via the top-level makefile <VAR>test</VAR> target:</P> <PRE CLASS="command"> make test </PRE> -<P>The test environment allows for both short-term automated -testing and long-term testing and development without the -automated test script.</P> +<P>The test environment allows for both short-term automated testing and long-term testing and development without the automated test script.</P> <H2 CLASS="title"><A NAME="STR">Trouble Report Processing</A></H2> -<P>A Software Trouble Report ("STR") must be submitted every time -a user or vendor experiences a problem with the CUPS software. -Trouble reports are maintained on the <A -HREF="http://www.cups.org/str.php" TARGET="_blank">Bugs & -Features</A> page with one of the following states:</P> +<P>A Software Trouble Report ("STR") must be submitted every time a user or vendor experiences a problem with the CUPS software. Trouble reports are maintained on the <A HREF="http://www.cups.org/str.php" TARGET="_blank">Bugs & Features</A> page with one of the following states:</P> <OL> @@ -442,36 +316,25 @@ Features</A> page with one of the following states:</P> <P>Trouble reports are processed using the following steps.</P> -<OL> +<H3>1. Classification</H3> -<LI>Classification - -<P>When a trouble report is received it must be classified at one -of the following priority levels:</P> +<P>When a trouble report is received it must be classified at one of the following priority levels:</P> <OL> - <LI>Request for enhancement, e.g. asking for a - feature + <LI>Request for enhancement, e.g. asking for a feature - <LI>Low, e.g. a documentation error or undocumented - side-effect + <LI>Low, e.g. a documentation error or undocumented side-effect - <LI>Moderate, e.g. unable to print a file or unable to - compile the software + <LI>Moderate, e.g. unable to print a file or unable to compile the software - <LI>High, e.g. unable to print to a printer or key - functionality not working + <LI>High, e.g. unable to print to a printer or key functionality not working <LI>Critical, e.g. unable to print at all </OL> -<P>Level 4 and 5 trouble reports must be resolved in the next -software release. Level 2 and 3 trouble reports are scheduled for -resolution in a specific release at the discretion of the release -coordinator. Level 1 trouble reports are scheduled for resolution -in a future feature release.</P> +<P>Level 4 and 5 trouble reports must be resolved in the next software release. Level 2 and 3 trouble reports are scheduled for resolution in a specific release at the discretion of the release coordinator. Level 1 trouble reports are scheduled for resolution in a future feature release.</P> <P>The scope of the problem is also determined as:</P> @@ -485,43 +348,24 @@ in a future feature release.</P> </OL> -<LI>Identification - -<P>Once the level and scope of the trouble report is determined -the software sub-system(s) involved with the problem are -determined. This may involve additional communication with the -user or vendor to isolate the problem to a specific cause.</P> +<H3>2. Identification</H3> -<P>When the sub-system(s) involved have been identified, an -engineer will then determine the change(s) needed and estimate -the time required for the change(s).</P> +<P>Once the level and scope of the trouble report is determined the software sub-system(s) involved with the problem are determined. This may involve additional communication with the user or vendor to isolate the problem to a specific cause.</P> -<LI>Correction +<P>When the sub-system(s) involved have been identified, an engineer will then determine the change(s) needed and estimate the time required for the change(s).</P> -<P>Corrections are scheduled based upon the severity and -complexity of the problem. Once all changes have been made, -documented, and tested successfully a new software release -snapshot is generated. Additional tests are added as necessary -for proper testing of the changes.</P> +<H3>3. Correction</H3> -<LI>Notification +<P>Corrections are scheduled based upon the severity and complexity of the problem. Once all changes have been made, documented, and tested successfully a new software release snapshot is generated. Additional tests are added as necessary for proper testing of the changes.</P> -<P>The user or vendor is notified when the fix is available or if -the problem was caused by user error.</P> +<H3>4. Notification</H3> -</OL> +<P>The user or vendor is notified when the fix is available or if the problem was caused by user error.</P> <H2 CLASS="title"><A NAME="RELEASES">Release Management</A></H2> -<P>When testing has been completed successfully, a new source -package is created using the <VAR>tools/makesrcdist</VAR> script. -Three types of releases, beta, candidate, and production, are -created and released to the public using the basic schedule in -Table 4. At least one beta and one release candidate must be -created prior to a production release, and there must be at least -two weeks between the last beta and first candidate and last -candidate and first production release.</P> +<P>When testing has been completed successfully, a new source package is created using the <VAR>tools/makesrcdist</VAR> script. Three types of releases - beta, candidate, and production - are created and released to the public using the basic schedule in Table 4. At least one beta and one release candidate must be created prior to a production release, and there must be at least two weeks between the last beta and first candidate and last candidate and first production release.</P> <DIV CLASS="table"><TABLE SUMMARY="CUPS Basic Release Schedule"> <CAPTION>Table: CUPS Basic Release Schedule</CAPTION> @@ -560,25 +404,18 @@ candidate and first production release.</P> <H2 CLASS="title"><A NAME="CODING">Coding Guidelines</A></H2> -<P>These coding guidelines provide detailed information on source -file formatting and documentation content and must be applied to -all C and C++ source files provided with CUPS. Source code for -other languages should conform to these guidelines as allowed by -the language.</P> +<P>These coding guidelines provide detailed information on source file formatting and documentation content and must be applied to all C and C++ source files provided with CUPS. Source code for other languages should conform to these guidelines as allowed by the language.</P> + <H3>Source Files</H3> -<P>All source files names shall be 16 characters or less in -length to ensure compatibility with older UNIX filesystems. -Source files containing functions shall have an extension of ".c" -for ANSI C and ".cxx" for C++ source files. All other "include" -files shall have an extension of ".h".</P> +<P>All source files names must be 16 characters or less in length to ensure compatibility with older UNIX filesystems. Source files containing functions have an extension of ".c" for ANSI C and ".cxx" for C++ source files. All other "include" files have an extension of ".h". Tabs are set to 8 characters.</P> -<P>The top of each source file shall contain a header giving the -name of the file, the purpose or nature of the source file, the -copyright and licensing notice, and the functions contained in -the file. The file name and revision information is provided by -the Subversion "$Id$" tag:</P> +<BLOCKQUOTE><B>Note:</B> + +<P>The ".cxx" extension is used because it is the only common C++ extension between Linux, OS X, UNIX, and Windows.</P></BLOCKQUOTE> + +<P>The top of each source file contains a header giving the name of the file, the purpose or nature of the source file, the copyright and licensing notice, and the functions contained in the file. The file name and revision information is provided by the Subversion "$Id$" tag:</P> <PRE CLASS="command"> /* @@ -586,7 +423,7 @@ the Subversion "$Id$" tag:</P> * * Description of file contents. * - * Copyright 2010 by Apple Inc. + * Copyright 2012 by Apple Inc. * * These coded instructions, statements, and computer programs are the * property of Apple Inc. and are protected by Federal copyright @@ -602,19 +439,13 @@ the Subversion "$Id$" tag:</P> */ </PRE> -<P>For source files that are subject to the Apple OS-Developed -Software exception, the following additional comment should -appear after the contact information:</P> +<P>For source files that are subject to the Apple OS-Developed Software exception, the following additional comment appears after the contact information:</P> <PRE CLASS="command"> * This file is subject to the Apple OS-Developed Software exception. </PRE> -<P>The bottom of each source file shall contain a trailer giving -the name of the file using the Subversion "$Id$" tag. The -primary purpose of this is to mark the end of a source file; if -the trailer is missing it is possible that code has been lost -near the end of the file:</P> +<P>The bottom of each source file contains a trailer giving the name of the file using the Subversion "$Id$" tag. The primary purpose of this is to mark the end of a source file; if the trailer is missing it is possible that code has been lost near the end of the file:</P> <PRE CLASS="command"> /* @@ -622,22 +453,92 @@ near the end of the file:</P> */ </PRE> + +<H3>Comments</H3> + +<P>All source code utilizes block comments within functions to describe the operations being performed by a group of statements; avoid putting a comment per line unless absolutely necessary, and then consider refactoring the code so that it is not necessary. C source files use the block comment format ("/* comment */") since many vendor C compilers still do not support C99/C++ comments ("// comment"):</P> + +<PRE CLASS="command"> + /* + * Clear the state array before we begin... + */ + + for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) + array[i] = CUPS_STATE_IDLE; + + /* + * Wait for state changes on another thread... + */ + + do + { + for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) + if (array[i] != CUPS_STATE_IDLE) + break; + + if (i == (sizeof(array) / sizeof(array[0]))) + sleep(1); + } while (i == (sizeof(array) / sizeof(array[0]))); +</PRE> + +<H3>Indentation</H3> + +<P>All code blocks enclosed by brackets begin with the opening brace on a new line. The code then follows starting on a new line after the brace and is indented 2 spaces. The closing brace is then placed on a new line following the code at the original indentation:</P> + +<PRE CLASS="command"> +{ + int i; /* Looping var */ + + + /* + * Process foobar values from 0 to 999... + */ + + for (i = 0; i < 1000; i ++) + { + do_this(i); + do_that(i); + } +} +</PRE> + +<P>Single-line statements following "do", "else", "for", "if", and "while" are indented 2 spaces as well. Blocks of code in a "switch" block are indented 4 spaces after each "case" and "default" case:</P> + +<PRE CLASS="command"> +switch (array[i]) +{ + case CUPS_STATE_IDLE : + do_this(i); + do_that(i); + break; + default : + do_nothing(i); + break; +} +</PRE> + + +<H3>Spacing</H3> + +<P>A space follows each reserved word such as "if", "while", etc. Spaces are not inserted between a function name and the arguments in parenthesis.</P> + + +<H3>Return Values</H3> + +<P>Parenthesis surround values returned from a function:</P> + +<PRE CLASS="command"> +return (CUPS_STATE_IDLE); +</PRE> + + <H3>Functions</H3> -<P>Functions with a global scope shall have a lowercase prefix -followed by capitalized words ("cupsDoThis", "cupsDoThat", -"cupsDoSomethingElse", etc.) Private global functions shall begin -with a leading underscore ("_cupsDoThis", "_cupsDoThat", -etc.)</P> +<P>Functions with a global scope have a lowercase prefix followed by capitalized words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private global functions begin with a leading underscore, e.g., "_cupsDoThis", "_cupsDoThat", etc.</P> -<P>Functions with a local scope shall be declared "static" and be -lowercase with underscores between words ("do_this", "do_that", -"do_something_else", etc.)</P> +<P>Functions with a local scope are declared "static" with lowercase names and underscores between words, e.g., "do_this", "do_that", "do_something_else", etc.</P> -<P>Each function shall begin with a comment header describing -what the function does, the possible input limits (if any), and -the possible output values (if any), and any special information -needed:</P> +<P>Each function begins with a comment header describing what the function does, the possible input limits (if any), and the possible output values (if any), and any special information needed:</P> <PRE CLASS="command"> /* @@ -654,100 +555,68 @@ do_this(float x) /* I - Power value (0.0 <= x <= 1. } </PRE> -<P>Return/output values are indicated using an "O" prefix, input -values are indicated using the "I" prefix, and values that are -both input and output use the "IO" prefix for the corresponding -in-line comment.</P> +<P>Return/output values are indicated using an "O" prefix, input values are indicated using the "I" prefix, and values that are both input and output use the "IO" prefix for the corresponding in-line comment.</P> -<P>The Mini-XML documentation generator also understands the following -special text in the function description comment:</P> +<P>The Mini-XML documentation generator also understands the following special text in the function description comment:</P> <UL> - <LI><CODE>@deprecated@</CODE> - Marks the function as - deprecated (not recommended for new development and - scheduled for removal)</LI> + <LI><CODE>@deprecated@</CODE> - Marks the function as deprecated (not recommended for new development and scheduled for removal)</LI> - <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the - function as new in the specified version of CUPS.</LI> + <LI><CODE>@since CUPS <I>version</I>@</CODE> - Marks the function as new in the specified version of CUPS.</LI> - <LI><CODE>@private@</CODE> - Marks the function as private.</LI> + <LI><CODE>@private@</CODE> - Marks the function as private (same as starting the function name with an underscore)</LI> </UL> + <H3>Variables</H3> -<P>Variables with a global scope shall be capitalized -("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The -only exception to this rule shall be the CUPS interface library -global variables which must begin with the prefix "cups" -("cupsThisVariable", "cupsThatVariable", etc.) Global variables -shall be replaced by function arguments whenever possible.</P> +<P>Variables with a global scope are capitalized, e.g., "ThisVariable", "ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either part of the per-thread global values managed by the "_cupsGlobals()" function or are suitably protected for concurrent access. Global variables should be replaced by function arguments whenever possible.</P> -<P>Variables with a local scope shall be lowercase with -underscores between words ("this_variable", "that_variable", -etc.) Any local variables shared by functions within a source -file shall be declared "static".</P> +<P>Variables with a local scope are lowercase with underscores between words, e.g., "this_variable", "that_variable", etc. Any "local global" variables shared by functions within a source file are declared "static". As for global variables, local static variables are suitably protected for concurrent access.</P> -<P>Each variable shall be declared on a separate line and shall -be immediately followed by a comment block describing the -variable:</P> +<P>Each variable is declared on a separate line and is immediately followed by a comment block describing the variable:</P> <PRE CLASS="command"> -int this_variable; /* The current state of this */ -int that_variable; /* The current state of that */ +int ThisVariable; /* The current state of this */ +static int that_variable; /* The current state of that */ </PRE> + <H3>Types</H3> -<P>All type names shall be lowercase with underscores between -words and "_t" appended to the end of the name -("cups_this_type_t", "cups_that_type_t", etc.) Type names must -start with a prefix, typically "cups" or the name of the program, -to avoid conflicts with system types. Private type names must -start with an underscore ("_cups_this_t", "_cups_that_t", -etc.)</P> +<P>All type names are lowercase with underscores between words and "_t" appended to the end of the name, e.g., "cups_this_type_t", "cups_that_type_t", etc. Type names start with a prefix, typically "cups" or the name of the program, to avoid conflicts with system types. Private type names start with an underscore, e.g., "_cups_this_t", "_cups_that_t", etc.</P> -<P>Each type shall have a comment block immediately after the -typedef:</P> +<P>Each type has a comment block immediately after the typedef:</P> <PRE CLASS="command"> -typedef int cups_this_type_t; /* This type is for CUPS foobar options. */ +typedef int cups_this_type_t; /* This type is for CUPS foobar options. */ </PRE> + <H3>Structures</H3> -<P>All structure names shall be lowercase with underscores -between words and "_s" appended to the end of the name -("cups_this_s", "cups_that_s", etc.) Structure names must start -with a prefix, typically "cups" or the name of the program, to -avoid conflicts with system types. Private structure names must -start with an underscore ("_cups_this_s", "_cups_that_s", -etc.)</P> +<P>All structure names are lowercase with underscores between words and "_s" appended to the end of the name, e.g., "cups_this_s", "cups_that_s", etc. Structure names start with a prefix, typically "cups" or the name of the program, to avoid conflicts with system types. Private structure names start with an underscore, e.g., "_cups_this_s", "_cups_that_s", etc.</P> -<P>Each structure shall have a comment block immediately after -the struct and each member shall be documented in accordance with -the variable naming policy above:</P> +<P>Each structure has a comment block immediately after the struct and each member is documented similar to the variable naming policy above:</P> <PRE CLASS="command"> -struct cups_this_struct_s /* This structure is for CUPS foobar options. */ +struct cups_this_struct_s /* This structure is for CUPS foobar options. */ { - int this_member; /* Current state for this */ - int that_member; /* Current state for that */ + int this_member; /* Current state for this */ + int that_member; /* Current state for that */ }; </PRE> + <H3>Constants</H3> -<P>All constant names shall be uppercase with underscored between -words ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.) -Constants must begin with an uppercase prefix, typically "CUPS" -or the program name.</P> +<P>All constant names are uppercase with underscores between words, e.g., "CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc. Constants begin with an uppercase prefix, typically "CUPS" or the program name. Private constants start with an underscore, e.g., "_CUPS_THIS_CONSTANT", "_CUPS_THAT_CONSTANT", etc.</P> -<P>Typed enumerations shall be used whenever possible to allow -for type checking by the compiler.</P> +<P>Typed enumerations should be used whenever possible to allow for type checking by the compiler.</P> -<P>Comment blocks shall immediately follow each constant:</P> +<P>Comment blocks immediately follow each constant:</P> <PRE CLASS="command"> enum @@ -757,124 +626,20 @@ enum }; </PRE> -<H3>Code</H3> - -<P>All source code shall utilize block comments within functions -to describe the operations being performed by a group of -statements; avoid putting a comment per line unless absolutely -necessary, and then consider refactoring the code so that it is -not necessary:</P> - -<PRE CLASS="command"> -/* - * Clear the state array before we begin... - */ - -for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) - array[i] = STATE_IDLE; - -/* - * Wait for state changes... - */ - -do -{ - for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) - if (array[i] != STATE_IDLE) - break; - - if (i == (sizeof(array) / sizeof(array[0]))) - sleep(1); -} while (i == (sizeof(array) / sizeof(array[0]))); -</PRE> - -<H3>Indentation</H3> - -<P>All code blocks enclosed by brackets shall begin with the -opening brace on a new line. The code then follows starting on a -new line after the brace and is indented 2 spaces. The closing -brace is then placed on a new line following the code at the -original indentation:</P> - -<PRE CLASS="command"> -{ - int i; /* Looping var */ - - /* - * Process foobar values from 0 to 999... - */ - - for (i = 0; i < 1000; i ++) - { - do_this(i); - do_that(i); - } -} -</PRE> - -<P>Single-line statements following "do", "else", "for", "if", -and "while" shall be indented 2 spaces as well. Blocks of code -in a "switch" block shall be indented 4 spaces after each "case" -and "default" case:</P> - -<PRE CLASS="command"> -switch (array[i]) -{ - case STATE_IDLE : - do_this(i); - do_that(i); - break; - default : - do_nothing(i); - break; -} -</PRE> - -<H3>Spacing</H3> - -<P>A space shall follow each reserved word ("if", "while", etc.) -Spaces shall not be inserted between a function name and the -arguments in parenthesis.</P> - -<H3>Return Values</H3> - -<P>Parenthesis shall surround values returned from a function -using "return":</P> - -<PRE CLASS="command"> -return (CUPS_STATE_IDLE); -</PRE> - -<H3>Loops</H3> - -<P>Whenever convenient loops should count downward to zero to -improve program performance:</P> - -<PRE CLASS="command"> -for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --) - array[i] = CUPS_STATE_IDLE; -</PRE> <H2 CLASS="title"><A NAME="MAKEFILES">Makefile Guidelines</A></H2> -<P>The following is a guide to the makefile-based build system -used by CUPS. These standards have been developed over the years -to allow CUPS to be built on as many systems and environments as -possible.</P> +<P>The following is a guide to the makefile-based build system used by CUPS. These standards have been developed over the years to allow CUPS to be built on as many systems and environments as possible.</P> + <H3>General Organization</H3> -<P>The CUPS source code is organized functionally into a -top-level makefile, include file, and subdirectories each with -their own makefile and dependencies files. The ".in" files are -template files for the <CODE>autoconf</CODE> software and are -used to generate a static version of the corresponding file.</P> +<P>The CUPS source code is organized functionally into a top-level makefile, include file, and subdirectories each with their own makefile and dependencies files. The ".in" files are template files for the <CODE>autoconf</CODE> software and are used to generate a static version of the corresponding file.</P> + <H3>Makefile Documentation</H3> -<P>Each make file must start with the standard CUPS header -containing the Subversion "$Id$" keyword, description of the -file, and CUPS copyright and license notice:</P> +<P>Each makefile starts with the standard CUPS header containing the Subversion "$Id$" keyword, description of the file, and CUPS copyright and license notice:</P> <PRE CLASS="command"> # @@ -882,7 +647,7 @@ file, and CUPS copyright and license notice:</P> # # Makefile for ... # -# Copyright 2007 by Apple Inc. +# Copyright 2012 by Apple Inc. # # These coded instructions, statements, and computer programs are the # property of Apple Inc. and are protected by Federal copyright @@ -892,7 +657,7 @@ file, and CUPS copyright and license notice:</P> # </PRE> -<P>The end of each makefile must have a comment saying:</P> +<P>The end of each makefile has a comment saying:</P> <PRE CLASS="command"> # @@ -900,28 +665,21 @@ file, and CUPS copyright and license notice:</P> # </PRE> -<P>The purpose of the trailer is to indicate the end of the -makefile so that truncations are immediately obvious.</P> +<P>The purpose of the trailer is to indicate the end of the makefile so that truncations are immediately obvious.</P> + <H3>Portable Makefile Construction</H3> -<P>CUPS uses a common subset of make program syntax to ensure -that the software can be compiled "out of the box" on as many -systems as possible. The following is a list of assumptions we -follow when constructing makefiles:</P> +<P>CUPS uses a common subset of make program syntax to ensure that the software can be compiled "out of the box" on as many systems as possible. The following is a list of assumptions we follow when constructing makefiles:</P> <UL> - <LI><b>Targets</b>; we assume that the make program - supports the notion of simple targets of the form - "name:" that perform tab-indented commands that follow - the target, e.g.: + <LI><b>Targets</b>; we assume that the make program supports the notion of simple targets of the form "name:" that perform tab-indented commands that follow the target, e.g.: <PRE CLASS="command"> target: → target commands</PRE></LI> - <LI><b>Dependencies</b>; we assume that the make program - supports recursive dependencies on targets, e.g.: + <LI><b>Dependencies</b>; we assume that the make program supports recursive dependencies on targets, e.g.: <PRE CLASS="command"> target: foo bar → target commands @@ -935,28 +693,21 @@ bar: bla: → bla commands</PRE></LI> - <LI><b>Variable Definition</b>; we assume that the make program - supports variable definition on the command-line or in the makefile - using the following form: + <LI><b>Variable Definition</b>; we assume that the make program supports variable definition on the command-line or in the makefile using the following form: <PRE CLASS="command"> name=value</PRE> - <LI><b>Variable Substitution</b>; we assume that the make program - supports variable substitution using the following forms: + <LI><b>Variable Substitution</b>; we assume that the make program supports variable substitution using the following forms: <UL> <LI><CODE>$(name)</CODE>; substitutes the value of "name",</LI> - <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name" - with the filename extensions ".old" changed to ".new",</LI> - <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the - command-line options passed to the program - without the leading hyphen (-),</LI> + <LI><CODE>($name:.old=.new)</CODE>; substitutes the value of "name" with the filename extension ".old" changed to ".new",</LI> + <LI><CODE>$(MAKEFLAGS)</CODE>; substitutes the command-line options passed to the program without the leading hyphen (-),</LI> <LI><CODE>$$</CODE>; substitutes a single <CODE>$</CODE> character,</LI> <LI><CODE>$<</CODE>; substitutes the current source file or dependency, and</LI> <LI><CODE>$@</CODE>; substitutes the current target name.</LI> </UL></LI> - <LI><b>Suffixes</b>; we assume that the make program - supports filename suffixes with assumed dependencies, e.g.: + <LI><b>Suffixes</b>; we assume that the make program supports filename suffixes with assumed dependencies, e.g.: <PRE CLASS="command"> .SUFFIXES: .c .o .c.o: @@ -968,64 +719,67 @@ name=value</PRE> include ../Makedefs include Dependencies</PRE></LI> - <LI><b>Comments</b>; we assume that comments begin with - a <CODE>#</CODE> character and proceed to the end of the - current line.</LI> + <LI><b>Comments</b>; we assume that comments begin with a <CODE>#</CODE> character and proceed to the end of the current line.</LI> - <LI><b>Line Length</b>; we assume that there is no - practical limit to the length of lines.</LI> + <LI><b>Line Length</b>; we assume that there is no practical limit to the length of lines.</LI> - <LI><b>Continuation of long lines</b>; we assume that - the <CODE>\</CODE> character may be placed at the end of a - line to concatenate two or more lines in a - makefile to form a single long line.</LI> + <LI><b>Continuation of long lines</b>; we assume that the <CODE>\</CODE> character may be placed at the end of a line to concatenate two or more lines in a makefile to form a single long line.</LI> - <LI><b>Shell</b>; we assume a POSIX-compatible shell is - present on the build system.</LI> + <LI><b>Shell</b>; we assume a POSIX-compatible shell is present on the build system.</LI> </UL> + <H3>Standard Variables</H3> -<P>The following variables are defined in the "Makedefs" file -generated by the <CODE>autoconf</CODE> software:</P> +<P>The following variables are defined in the "Makedefs" file generated by the <CODE>autoconf</CODE> software:</P> <UL> - <LI><CODE>AR</CODE>; the library archiver command,</LI> + <LI><CODE>ALL_CFLAGS</CODE>; the combined C compiler options,</LI> - <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI> - - <LI><CODE>BUILDROOT</CODE>; optional installation prefix,</LI> + <LI><CODE>ALL_CXXFLAGS</CODE>; the combined C++ compiler options,</LI> - <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI> + <LI><CODE>AMANDIR</CODE>; the administrative man page installation directory (section 8/1m depending on the platform),</LI> - <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI> + <LI><CODE>AR</CODE>; the library archiver command,</LI> - <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI> + <LI><CODE>ARFLAGS</CODE>; options for the library archiver command,</LI> - <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI> + <LI><CODE>AWK</CODE>; the local awk command,</LI> - <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI> + <LI><CODE>BINDIR</CODE>; the binary installation directory,</LI> - <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI> + <LI><CODE>BUILDROOT</CODE>; optional installation prefix (defaults to DSTROOT),</LI> <LI><CODE>CC</CODE>; the C compiler command,</LI> <LI><CODE>CFLAGS</CODE>; options for the C compiler command,</LI> + <LI><CODE>CHMOD</CODE>; the chmod command,</LI> + <LI><CODE>CXX</CODE>; the C++ compiler command,</LI> <LI><CODE>CXXFLAGS</CODE>; options for the C++ compiler command,</LI> - <LI><CODE>DSOCOMMAND</CODE>; the shared library building command,</LI> + <LI><CODE>DATADIR</CODE>; the data file installation directory,</LI> + + <LI><CODE>DSO</CODE>; the C shared library building command,</LI> + + <LI><CODE>DSOXX</CODE>; the C++ shared library building command,</LI> <LI><CODE>DSOFLAGS</CODE>; options for the shared library building command,</LI> + <LI><CODE>INCLUDEDIR</CODE>; the public header file installation directory,</LI> + <LI><CODE>INSTALL</CODE>; the <CODE>install</CODE> command,</LI> <LI><CODE>INSTALL_BIN</CODE>; the program installation command,</LI> + <LI><CODE>INSTALL_COMPDATA</CODE>; the compressed data file installation command,</LI> + + <LI><CODE>INSTALL_CONFIG</CODE>; the configuration file installation command,</LI> + <LI><CODE>INSTALL_DATA</CODE>; the data file installation command,</LI> <LI><CODE>INSTALL_DIR</CODE>; the directory installation command,</LI> @@ -1036,77 +790,82 @@ generated by the <CODE>autoconf</CODE> software:</P> <LI><CODE>INSTALL_SCRIPT</CODE>; the shell script installation command,</LI> + <LI><CODE>LD</CODE>; the linker command,</LI> + <LI><CODE>LDFLAGS</CODE>; options for the linker,</LI> + <LI><CODE>LIBDIR</CODE>; the library installation directory,</LI> + <LI><CODE>LIBS</CODE>; libraries for all programs,</LI> <LI><CODE>LN</CODE>; the <CODE>ln</CODE> command,</LI> - <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI> + <LI><CODE>MAN1EXT</CODE>; extension for man pages in section 1,</LI> - <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI> + <LI><CODE>MAN3EXT</CODE>; extension for man pages in section 3,</LI> - <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI> + <LI><CODE>MAN5EXT</CODE>; extension for man pages in section 5,</LI> - <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI> + <LI><CODE>MAN7EXT</CODE>; extension for man pages in section 7,</LI> - <LI><CODE>bindir</CODE>; the binary installation directory,</LI> + <LI><CODE>MAN8DIR</CODE>; subdirectory for man pages in section 8,</LI> + + <LI><CODE>MAN8EXT</CODE>; extension for man pages in section 8,</LI> - <LI><CODE>datadir</CODE>; the data file installation directory,</LI> + <LI><CODE>MANDIR</CODE>; the man page installation directory,</LI> - <LI><CODE>exec_prefix</CODE>; the installation prefix for executable files,</LI> + <LI><CODE>OPTIM</CODE>; common compiler optimization options,</LI> + + <LI><CODE>PRIVATEINCLUDE</CODE>; the private header file installation directory,</LI> - <LI><CODE>libdir</CODE>; the library installation directory,</LI> + <LI><CODE>RM</CODE>; the <CODE>rm</CODE> command,</LI> - <LI><CODE>mandir</CODE>; the man page installation directory,</LI> + <LI><CODE>SHELL</CODE>; the <CODE>sh</CODE> (POSIX shell) command,</LI> - <LI><CODE>prefix</CODE>; the installation prefix for non-executable files, and</LI> + <LI><CODE>STRIP</CODE>; the <CODE>strip</CODE> command,</LI> <LI><CODE>srcdir</CODE>; the source directory.</LI> </UL> + <H3>Standard Targets</H3> -<P>The following standard targets must be defined in each -makefile:</P> +<P>The following standard targets are defined in each makefile:</P> <UL> - <LI><CODE>all</CODE>; creates all target programs, - libraries, and documentation files,</LI> + <LI><CODE>all</CODE>; creates all target programs, libraries, and documentation files,</LI> + + <LI><CODE>clean</CODE>; removes all target programs libraries, documentation files, and object files,</LI> + + <LI><CODE>depend</CODE>; generates automatic dependencies for any C or C++ source files (also see <A HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI> + + <LI><CODE>distclean</CODE>; removes autoconf-generated files in addition to those removed by the "clean" target,</LI> + + <LI><CODE>install</CODE>; installs all distribution files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI> - <LI><CODE>clean</CODE>; removes all target programs, - libraries, documentation files, and object files,</LI> + <LI><CODE>install-data</CODE>; installs all data files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI> - <LI><CODE>depend</CODE>; generates automatic dependencies - for any C or C++ source files (also see <A - HREF="#DEPEND_TARGET">"Dependencies"</A>),</LI> + <LI><CODE>install-exec</CODE>; installs all executable files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI> - <LI><CODE>distclean</CODE>; removes autoconf-generated files - in addition to those removed by the "clean" target,</LI> + <LI><CODE>install-headers</CODE>; installs all include files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI> - <LI><CODE>install</CODE>; installs all distribution files in - their corresponding locations (also see <A - HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), </LI> + <LI><CODE>install-libs</CODE>; installs all library files in their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>),</LI> - <LI><CODE>uninstall</CODE>; removes all distribution files from - their corresponding locations (also see <A - HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI> + <LI><CODE>uninstall</CODE>; removes all distribution files from their corresponding locations (also see <A HREF="#INSTALL_TARGET">"Install/Uninstall Support"</A>), and</LI> </UL> <H3>Object Files</H3> -<P>Object files (the result of compiling a C or C++ source file) -have the extension ".o".</P> +<P>Object files (the result of compiling a C or C++ source file) have the extension ".o".</P> + <H3>Programs</H3> -<P>Program files are the result of linking object files and -libraries together to form an executable file. A typical -program target looks like:</P> +<P>Program files are the result of linking object files and libraries together to form an executable file. A typical program target looks like:</P> <PRE CLASS="command"> program: $(OBJS) @@ -1114,10 +873,10 @@ program: $(OBJS) → $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) </PRE> + <H3>Static Libraries</H3> -<P>Static libraries have a prefix of "lib" and the extension -".a". A typical static library target looks like:</P> +<P>Static libraries have a prefix of "lib" and the extension ".a". A typical static library target looks like:</P> <PRE CLASS="command"> libname.a: $(OBJECTS) @@ -1127,12 +886,10 @@ libname.a: $(OBJECTS) → $(RANLIB) $@ </PRE> + <H3>Shared Libraries</H3> -<P>Shared libraries have a prefix of "lib" and the extension -".dylib", ".sl", ".so", or "_s.a" depending on the operating -system. A typical shared library is composed of several targets -that look like:</P> +<P>Shared libraries have a prefix of "lib" and the extension ".dylib", ".sl", ".so", or "_s.a" depending on the operating system. A typical shared library is composed of several targets that look like:</P> <PRE CLASS="command"> libname.so: $(OBJECTS) @@ -1173,46 +930,29 @@ libname_s.a: $(OBJECTS) <H3>Dependencies</H3> -<P>Static dependencies are expressed in each makefile following the -target, for example:</P> +<P>Static dependencies are expressed in each makefile following the target, for example:</P> <PRE CLASS="command"> foo: bar </PRE> -<P>Static dependencies shall only be used when it is not -possible to automatically generate them. Automatic dependencies -are stored in a file named "Dependencies" and included at the -end of the makefile. The following "depend" target rule shall be -used to create the automatic dependencies: +<P>Static dependencies are only used when it is not possible to automatically generate them. Automatic dependencies are stored in a file named "Dependencies" and included at the end of the makefile. The following "depend" target rule is used to create the automatic dependencies: <PRE CLASS="command"> depend: -→ $(MAKEDEPEND) -Y -I.. -f Dependencies $(OBJS:.o=.c) +→ $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies </PRE> -<P>We only regenerate the automatic dependencies on a Linux -system and express any non-Linux dependencies statically in the -makefile.</P> +<P>We regenerate the automatic dependencies on an OS X system and express any non-OS X dependencies statically in the makefile.</P> + <H3><A NAME="TARGET_INSTALL">Install/Uninstall Support</A></H3> -<P>All makefiles must contain install and uninstall rules which -install or remove the corresponding software. These rules must -use the <CODE>$(BUILDROOT)</CODE> variable as a prefix to any -installation directory so that CUPS can be installed in a -temporary location for packaging by programs like -<CODE>rpmbuild</CODE>.</P> - -<P>The <CODE>$(INSTALL_BIN)</CODE>, <CODE>$(INSTALL_DATA)</CODE>, -<CODE>$(INSTALL_DIR)</CODE>, <CODE>$(INSTALL_LIB)</CODE>, -<CODE>$(INSTALL_MAN)</CODE>, and <CODE>$(INSTALL_SCRIPT)</CODE> -variables must be used when installing files so that the proper -ownership and permissions are set on the installed files.</P> - -<P>The <CODE>$(RANLIB)</CODE> command must be run on any static -libraries after installation since the symbol table is -invalidated when the library is copied on some platforms.</P> +<P>All makefiles contains install and uninstall rules which install or remove the corresponding software. These rules must use the <CODE>$(BUILDROOT)</CODE> variable as a prefix to any installation directory so that CUPS can be installed in a temporary location for packaging by programs like <CODE>rpmbuild</CODE>.</P> + +<P>The <CODE>$(INSTALL_BIN)</CODE>, <CODE>$(INSTALL_COMPDATA)</CODE>, <CODE>$(INSTALL_CONFIG)</CODE>, <CODE>$(INSTALL_DATA)</CODE>, <CODE>$(INSTALL_DIR)</CODE>, <CODE>$(INSTALL_LIB)</CODE>, <CODE>$(INSTALL_MAN)</CODE>, and <CODE>$(INSTALL_SCRIPT)</CODE> variables must be used when installing files so that the proper ownership and permissions are set on the installed files.</P> + +<P>The <CODE>$(RANLIB)</CODE> command must be run on any static libraries after installation since the symbol table is invalidated when the library is copied on some platforms.</P> </BODY> </HTML> diff --git a/doc/help/spec-ipp.html b/doc/help/spec-ipp.html index 98bc0574..27b8fca2 100644 --- a/doc/help/spec-ipp.html +++ b/doc/help/spec-ipp.html @@ -8,11 +8,11 @@ </head> <body> <!-- - "$Id: spec-ipp.html 9727 2011-04-28 21:20:12Z mike $" + "$Id: spec-ipp.html 10424 2012-04-23 17:26:57Z mike $" CUPS IPP specification for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 1997-2007 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -365,7 +365,7 @@ Print-Job request: <dl> - <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute. @@ -472,7 +472,7 @@ Create-Job request: <dl> - <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute. @@ -577,7 +577,7 @@ Cancel-Job request: <dd>The client MUST supply a URI for the specified printer and a job ID number, or the job URI. - <dt><span class="info">CUPS 1.4/Mac OS X 10.6</span>"purge-job" (boolean): + <dt><span class="info">CUPS 1.4/OS X 10.6</span>"purge-job" (boolean): <dd>The client OPTIONALLY supplies this attribute. When true, all job files (history and document) are purged. The default @@ -632,18 +632,18 @@ Purge-Jobs request: <dd>The client MUST supply a URI for the specified printer or "ipp://.../printers" for all printers and classes. - <dt><span class="info">CUPS 1.2/Mac OS X 10.5</span>"requesting-user-name" (name(MAX)): + <dt><span class="info">CUPS 1.2/OS X 10.5</span>"requesting-user-name" (name(MAX)): <dd>The client OPTIONALLY supplies this attribute to specify whose jobs jobs are purged or canceled. - <dt><span class="info">CUPS 1.2/Mac OS X 10.5</span>"my-jobs" (boolean): + <dt><span class="info">CUPS 1.2/OS X 10.5</span>"my-jobs" (boolean): <dd>The client OPTIONALLY supplies this attribute to specify that only the jobs owned by the requesting user are purged or canceled. The default is false. - <dt><span class="info">CUPS 1.2/Mac OS X 10.5</span>"purge-jobs" (boolean): + <dt><span class="info">CUPS 1.2/OS X 10.5</span>"purge-jobs" (boolean): <dd>The client OPTIONALLY supplies this attribute to specify whether the jobs are purged (true) or just canceled (false). @@ -754,7 +754,7 @@ Response: </dl> -<h3 class='title'><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a +<h3 class='title'><span class='info'>CUPS 1.2/OS X 10.5</span><a name='CREATE_PRINTER_SUBSCRIPTION'>Create-Printer-Subscription</a></h3> <p>The Create-Printer-Subscription operation (0x0016) creates a @@ -926,7 +926,7 @@ CUPS-Get-Printers request: attributes as described in section 3.1.4.1 of the IPP Model and Semantics document. - <dt>"first-printer-name" (name(127)):<span class='info'>CUPS 1.2/Mac OS X 10.5</span> + <dt>"first-printer-name" (name(127)):<span class='info'>CUPS 1.2/OS X 10.5</span> <dd>The client OPTIONALLY supplies this attribute to select the first printer that is returned. @@ -960,7 +960,7 @@ CUPS-Get-Printers request: responds as if this attribute had been supplied with a value of 'all'. - <dt>"requested-user-name" (name(127)) : <span class='info'>CUPS 1.2/Mac OS X 10.5</span> + <dt>"requested-user-name" (name(127)) : <span class='info'>CUPS 1.2/OS X 10.5</span> <dd>The client OPTIONALLY supplies a user name that is used to filter the returned printers. @@ -1027,7 +1027,7 @@ CUPS-Add-Modify-Printer request: <dl> - <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue. @@ -1190,7 +1190,7 @@ CUPS-Get-Classes request: attributes as described in section 3.1.4.1 of the IPP Model and Semantics document. - <dt>"first-printer-name" (name(127)):<span class='info'>CUPS 1.2/Mac OS X 10.5</span> + <dt>"first-printer-name" (name(127)):<span class='info'>CUPS 1.2/OS X 10.5</span> <dd>The client OPTIONALLY supplies this attribute to select the first printer that is returned. @@ -1220,7 +1220,7 @@ CUPS-Get-Classes request: interested. If the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'. - <dt>"requested-user-name" (name(127)) : <span class='info'>CUPS 1.2/Mac OS X 10.5</span> + <dt>"requested-user-name" (name(127)) : <span class='info'>CUPS 1.2/OS X 10.5</span> <dd>The client OPTIONALLY supplies a user name that is used to filter the returned printers. @@ -1287,7 +1287,7 @@ CUPS-Add-Modify-Class request: <dl> - <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"auth-info-required" (1setOf type2 keyword):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies one or more authentication keywords that are required to communicate with the printer/remote queue. @@ -1586,14 +1586,14 @@ CUPS-Get-Devices request: <dd>The client OPTIONALLY supplies a device class keyword to select which devices are returned. - <dt>"exclude-schemes" (1setOf name) :<span class='info'>CUPS 1.4/Mac OS X 10.6</span> + <dt>"exclude-schemes" (1setOf name) :<span class='info'>CUPS 1.4/OS X 10.6</span> <dd>The client OPTIONALLY supplies a set of scheme names that the requestor does not want to discover. If the client omits this attribute, the server responds with devices of all schemes specified by the "include-schemes" attribute. - <dt>"include-schemes" (1setOf name) :<span class='info'>CUPS 1.4/Mac OS X 10.6</span> + <dt>"include-schemes" (1setOf name) :<span class='info'>CUPS 1.4/OS X 10.6</span> <dd>The client OPTIONALLY supplies a set of scheme names that the requestor wants to discover. If the client omits this attribute, @@ -1612,7 +1612,7 @@ CUPS-Get-Devices request: the client omits this attribute, the server responds as if this attribute had been supplied with a value of 'all'. - <dt>"timeout" (integer (1:MAX)) :<span class='info'>CUPS 1.4/Mac OS X 10.6</span> + <dt>"timeout" (integer (1:MAX)) :<span class='info'>CUPS 1.4/OS X 10.6</span> <dd>The client OPTIONALLY supplies this attribute to limit the duration of the lookup. The default timeout is 15 seconds. @@ -1669,14 +1669,14 @@ CUPS-Get-PPDs request: attributes as described in section 3.1.4.1 of the IPP Model and Semantics document. - <dt>"exclude-schemes" (1setOf name) :<span class='info'>CUPS 1.4/Mac OS X 10.6</span> + <dt>"exclude-schemes" (1setOf name) :<span class='info'>CUPS 1.4/OS X 10.6</span> <dd>The client OPTIONALLY supplies a set of scheme names that the requestor does not want to list. If the client omits this attribute, the server responds with PPDs of all schemes specified by the "include-schemes" attribute. - <dt>"include-schemes" (1setOf name) :<span class='info'>CUPS 1.4/Mac OS X 10.6</span> + <dt>"include-schemes" (1setOf name) :<span class='info'>CUPS 1.4/OS X 10.6</span> <dd>The client OPTIONALLY supplies a set of scheme names that the requestor wants to list. If the client omits this attribute, the server @@ -1691,27 +1691,27 @@ CUPS-Get-PPDs request: <dd>The client OPTIONALLY supplies a printer manufacturer to select which PPDs are returned. - <dt>"ppd-make-and-model" (text(127)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-make-and-model" (text(127)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a make and model to select which PPDs are returned. - <dt>"ppd-model-number" (integer):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-model-number" (integer):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a model number to select which PPDs are returned. - <dt>"ppd-natural-language" (naturalLanguage):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-natural-language" (naturalLanguage):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a language to select which PPDs are returned. - <dt>"ppd-product" (text(127)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-product" (text(127)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a PostScript product string to select which PPDs are returned. - <dt>"ppd-psversion" (text(127)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-psversion" (text(127)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a PostScript version string to select which PPDs are returned. - <dt>"ppd-type" (type1 keyword):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"ppd-type" (type1 keyword):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a driver type to select which PPDs are returned. @@ -1813,7 +1813,7 @@ CUPS-Move-Job Response: </dl> -<h3 class='title'><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job Operation</a></h3> +<h3 class='title'><span class='info'>CUPS 1.2/OS X 10.5</span><a name='CUPS_AUTHENTICATE_JOB'>CUPS-Authenticate-Job Operation</a></h3> <p>The CUPS-Authenticate-Job operation (0x400E) authenticates a print job for printing, releasing the job if it is held. Typically this is used when printing @@ -1848,11 +1848,11 @@ CUPS-Authenticate-Job request: <dl> - <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"auth-info" (1setOf text(MAX)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies one or more authentication values as specified by the "auth-info-required" attribute. - <dt>"job-hold-until" (keyword | name(MAX)):<span class='info'>CUPS 1.3/Mac OS X 10.5</span> + <dt>"job-hold-until" (keyword | name(MAX)):<span class='info'>CUPS 1.3/OS X 10.5</span> <dd>The client OPTIONALLY supplies a new job-hold-until value for the job. If specified and not the "no-hold" value, the job is held instead @@ -1891,7 +1891,7 @@ CUPS-Authenticate-Job Response: </dl> -<h3 class='title'><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='CUPS_GET_PPD'>CUPS-Get-PPD Operation</a></h3> +<h3 class='title'><span class='info'>CUPS 1.3/OS X 10.5</span><a name='CUPS_GET_PPD'>CUPS-Get-PPD Operation</a></h3> <p>The CUPS-Get-PPD operation (0x400F) gets a PPD file from the server. The PPD file can be specified using a <tt>ppd-name</tt> @@ -1961,7 +1961,7 @@ CUPS-Get-PPD Response: <p>If the status code is <tt>successful-ok</tt>, the PPD file follows the end of the IPP response.</p> -<h3 class='title'><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='CUPS_GET_DOCUMENT'>CUPS-Get-Document Operation</a></h3> +<h3 class='title'><span class='info'>CUPS 1.4/OS X 10.6</span><a name='CUPS_GET_DOCUMENT'>CUPS-Get-Document Operation</a></h3> <p>The CUPS-Get-Document operation (0x4027) gets a document file from a job on the server. The document file is specified using the @@ -2078,7 +2078,7 @@ one of the following: </ul> -<h4><a name="device-id">device-id (text(127))</a><span class="info">CUPS 1.2/Mac OS X 10.5</span></h4> +<h4><a name="device-id">device-id (text(127))</a><span class="info">CUPS 1.2/OS X 10.5</span></h4> <p>The device-id attribute specifies the IEEE-1284 device ID string for the device.</p> @@ -2088,7 +2088,7 @@ string for the device.</p> <p>The device-info attribute specifies a human-readable string describing the device, e.g. "Parallel Port #1". -<h4><a name="device-location">device-location (text(127))</a><span class="info">CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="device-location">device-location (text(127))</a><span class="info">CUPS 1.4/OS X 10.6</span></h4> <p>The device-location attribute specifies the physical location of the printer. @@ -2148,89 +2148,22 @@ of the device-class attribute: <h3 class='title'><a name='JOB_TEMPLATE_ATTRIBUTES'>Job Template Attributes</a></h3> -<h4><a name="auth-info">auth-info (1setOf text(MAX))</a><span class="info">CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="auth-info">auth-info (1setOf text(MAX))</a><span class="info">CUPS 1.3/OS X 10.5</span></h4> <p>The auth-info attribute specifies the authentication information to use when printing to a remote device. The order and content of each text value is specifed by the <a href="#auth-info-required">auth-info-required</a> printer attribute. -<h4><a name="blackplot">blackplot (boolean)</a></h4> - -<p>The blackplot attribute specifies whether HP-GL/2 plot files should be -rendered entirely in black ink (blackplot=true) or using the colors and shades -specified in the file (blackplot=false). The default value is false. - -<h4><a name="brightness">brightness (integer(0:200))</a><span class="info">Deprecated</span></h4> - -<p>The brightness attribute specifies the overall brightness of the printed -output in percent. A brightness of 100 is normal, while 200 is twice as -bright and 50 is half as bright. The default value is 100. - -<p>Brightness is applied to the Cyan, Magenta, Yellow, and Black values using -the function "f(x) = brightness / 100 * x". - -<blockquote><b>Note:</b> - -<p>This attribute is deprecated and will be removed from a future CUPS -release.</p> - -</blockquote> - -<h4><a name="columns">columns (integer(1:4))</a> <span class='info'>Deprecated</span></h4> - -<p>The columns attribute specifies the number of columns to generate when -printing text files. The default value is 1. - <h4><a name="cpi">cpi (type2 enum)</a></h4> <p>The cpi attribute specifies the number of characters per inch when printing text files. Only the values 10, 12, and 17 are currently supported. The default value is 10. -<h4><a name="document-count">document-count (integer(1:MAX))</a></h4> - -<p>The document-count attribute specifies the number of documents that -are present in the job. - -<h4><a name="fit-to-page">fit-to-page (boolean)</a><span class="info">CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="fit-to-page">fit-to-page (boolean)</a><span class="info">CUPS 1.4/OS X 10.6</span></h4> <p>The fit-to-page attribute specifies whether to scale documents to fit on the selected media (fit-to-page=true) or use the physical size specified in the document (fit-to-page=false). The default value is false. -<h4><a name="fitplot">fitplot (boolean)</a><span class="info">Deprecated</span></h4> - -<p>The fitplot attribute specifies whether to scale HP-GL/2 plot files to -fit on the selected media (fitplot=true) or use the physical scale specified -in the plot file (fitplot=false). The default value is false. - -<h4><a name="gamma">gamma (integer(1:10000))</a><span class="info">Deprecated</span></h4> - -<p>The gamma attribute specifies the luminance correction for the output. -A value of 1000 specifies no correction, while values of 2000 and 500 will -generate lighter and darker output, respectively. The default value is -1000. - -<p>Gamma is applied to the Red, Green, and Blue values (or luminance for -grayscale output) using the function "f(x) = x<sup>(1000/gamma)</sup>". - -<blockquote><b>Note:</b> - -<p>This attribute is deprecated and will be removed from a future CUPS -release.</p> - -</blockquote> - -<h4><a name="hue">hue (integer(-180:180))</a><span class="info">Deprecated</span></h4> - -<p>The hue attribute specifies a color hue rotation when printing image -files. The default value is 0. - -<blockquote><b>Note:</b> - -<p>This attribute is deprecated and will be removed from a future CUPS -release.</p> - -</blockquote> - <h4><a name="job-billing">job-billing (text(MAX))</a><span class='info'>CUPS 1.1</span></h4> <p>The job-billing attribute provides a text value to associate with a job @@ -2245,17 +2178,17 @@ Universal Coordinated Time (UTC) and <i>not</i> in the local time zone. If the specified time is less than the current time, the job is held until the next day. -<h4><a name="job-media-progress">job-media-progress (integer(0:100))</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="job-media-progress">job-media-progress (integer(0:100))</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The job-media-progress attribute specifies the percentage of completion of the current page. It is only valid when the job-state attribute has the "processing" value (5).</p> -<h4><a name="job-printer-state-message">job-printer-state-message (text(MAX))</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="job-printer-state-message">job-printer-state-message (text(MAX))</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The job-printer-state-message attribute provides the last known value of the printer-state-message attribute for the printer that processed (or is processing) the job.</p> -<h4><a name="job-printer-state-reasons">job-printer-state-reasons (1setOf type2 keyword)</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="job-printer-state-reasons">job-printer-state-reasons (1setOf type2 keyword)</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The job-printer-state-reasons attribute provides the last known value of the printer-state-reasons attribute for the printer that processed (or is processing) the job.</p> @@ -2293,16 +2226,8 @@ The default value is 6. their X axis, which is useful for printing transfer images on special media. The default value is false. -<h4><a name="natural-scaling">natural-scaling (integer(1:1000))</a><span class='info'>CUPS 1.1.9</span></h4> -<p>The natural-scaling attribute specifies the scaling of image files with -respect to the natural image size. A value of 100 specifies that the image -file should exactly the natural size, while 50 is half the natural size -and 200 is twice the natural size. The default value is 100. +<h4><a name="number-up-layout">number-up-layout (type2 keyword)</a><span class='info'>Deprecated/Introduced in CUPS 1.1.15</span></h4> -<p>The ppi option can be used to override the natural resolution of the -image, which controls the natural size. - -<h4><a name="number-up-layout">number-up-layout (type2 keyword)</a><span class='info'>CUPS 1.1.15</span></h4> <p>The number-up-layout attribute specifies the order each input page is placed on each output page. The following keywords are presently defined: @@ -2327,6 +2252,12 @@ presently defined: </ul> +<blockquote><b>Note:</b> + +<p>This attribute is deprecated in favor of the PWG presentation-direction-number-up attribute and will be removed in a future release.</p> + +</blockquote> + <h4><a name="page-border">page-border (type2 keyword)</a><span class='info'>CUPS 1.1.15</span></h4> <p>The page-border attribute specifies whether a border is draw around each page. The following keywords are presently @@ -2346,23 +2277,23 @@ defined: </ul> -<h4><a name="page-bottom">page-bottom (integer(0:MAX))</a></h4> +<h4><a name="page-bottom">page-bottom (integer(0:MAX))</a><span class="info">Deprecated</span></h4> <p>The page-bottom attribute specifies the bottom margin in points (72 points equals 1 inch). The default value is the device physical margin. -<h4><a name="page-label">page-label (text(MAX))</a><span class='info'>CUPS 1.1.7</span></h4> +<h4><a name="page-label">page-label (text(MAX))</a><span class='info'>Deprecated</span></h4> <p>The page-label attribute provides a text value to place in the header and footer on each page. If a classification level is set on the server, then this classification is printed before the page label. -<h4><a name="page-left">page-left (integer(0:MAX))</a></h4> +<h4><a name="page-left">page-left (integer(0:MAX))</a><span class="info">Deprecated</span></h4> <p>The page-left attribute specifies the left margin in points (72 points equals 1 inch). The default value is the device physical margin. -<h4><a name="page-right">page-right (integer(0:MAX))</a></h4> +<h4><a name="page-right">page-right (integer(0:MAX))</a><span class="info">Deprecated</span></h4> <p>The page-right attribute specifies the right margin in points (72 points equals 1 inch). The default value is the device physical margin. @@ -2373,84 +2304,18 @@ equals 1 inch). The default value is the device physical margin. supported keywords are "all", "even", and "odd". The default value is "all". -<h4><a name="page-top">page-top (integer(0:MAX))</a></h4> +<h4><a name="page-top">page-top (integer(0:MAX))</a><span class="info">Deprecated</span></h4> <p>The page-top attribute specifies the top margin in points (72 points equals 1 inch). The default value is the device physical margin. -<h4><a name="penwidth">penwidth (integer(0:MAX))</a></h4> - -<p>The penwidth attribute specifies the default pen width in micrometers -when printing HP-GL/2 plot files. The default value is 1000 (1 millimeter). - -<h4><a name="position">position (type2 keyword)</a></h4> - -<p>The position attribute specifies the location of image files on the -media. The following keyword values are recognized: - -<ul> - - <li><CODE>center</CODE> - Center the image on the page (default) - - <li><CODE>top</CODE> - Print the image centered at the top of the page - - <li><CODE>left</CODE> - Print the image centered on the left of page - - <li><CODE>right</CODE> - Print the image centered on the right of the page - - <li><CODE>top-left</CODE> - Print the image at the top left corner of - the page - - <li><CODE>top-right</CODE> - Print the image at the top right corner of - the page - - <li><CODE>bottom</CODE> - Print the image centered at the bottom of - the page - - <li><CODE>bottom-left</CODE> - Print the image at the bottom left - corner of the page - - <li><CODE>bottom-right</CODE> - Print the image at the bottom right - corner of the page - -</ul> - -<h4><a name="ppi">ppi (integer(1:MAX))</a></h4> - -<p>The ppi attribute specifies the resolution of an image file in pixels -per inch. The default value is the resolution included with the file or -128 if no resolution information is available. - -<h4><a name="prettyprint">prettyprint (boolean)</a></h4> +<h4><a name="prettyprint">prettyprint (boolean)</a><span class="info">Deprecated</span></h4> <p>The prettyprint attribute specifies whether text files should be printed with a shaded header and keyword highlighting (prettyprint=true) or without additional formatting (prettyprint=false). The default value is false. -<h4><a name="saturation">saturation (integer(0:200))</a><span class="info">Deprecated</span></h4> - -<p>The saturation attribute specifies the color saturation when -printing image files. A saturation of 100 is normal, while values of 50 -and 200 will be half and twice as colorful, respectively. The default -value is 100. - -<blockquote><b>Note:</b> - -<p>This attribute is deprecated and will be removed from a future CUPS -release.</p> - -</blockquote> - -<h4><a name="scaling">scaling (integer(1:1000))</a></h4> - -<p>The scaling attribute specifies the scaling of image files with -respect to the selected media. A value of 100 specifies that the image -file should fit 100% of the page, or as much as possible given the -image dimensions. The default value is unspecified. - -<p>The scaling attribute overrides the ppi attribute if specified. - -<h4><a name="wrap">wrap (boolean)</a></h4> +<h4><a name="wrap">wrap (boolean)</a><span class="info">Deprecated</span></h4> <p>The wrap attribute specifies whether long lines should be wrapped (wrap=true) or not (wrap=false) when printing text files. The default @@ -2477,7 +2342,7 @@ name of the PPD file (the NickName attribute in the PPD file). If the make and model is not specified in the PPD file then the ModelName or ShortNickName attributes are used instead. -<h4><a name="ppd-model-number">ppd-model-number (integer)</a><span class="info">CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="ppd-model-number">ppd-model-number (integer)</a><span class="info">CUPS 1.3/OS X 10.5</span></h4> <p>The ppd-model-number attribute provides the <tt>cupsModelNumber</tt> value from the PPD file. @@ -2495,11 +2360,11 @@ language is unknown or undefined then "en" (English) is assumed. <p>The ppd-product attribute specifies the Product attribute values in the PPD file. -<h4><a name="ppd-psversion">ppd-psversion (1setOf text(127))</a><span class="info">CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="ppd-psversion">ppd-psversion (1setOf text(127))</a><span class="info">CUPS 1.3/OS X 10.5</span></h4> <p>The ppd-product attribute specifies the PSVersion attribute values in the PPD file. -<h4><a name="ppd-type">ppd-type (type1 keyword)</a><span class="info">CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="ppd-type">ppd-type (type1 keyword)</a><span class="info">CUPS 1.3/OS X 10.5</span></h4> <p>The ppd-type attribute specifies the type of driver described by the PPD file:</p> @@ -2520,7 +2385,7 @@ language is unknown or undefined then "en" (English) is assumed. <h3 class='title'><a name='PRINTER_ATTRIBUTES'>Printer Attributes</a></h3> -<h4><a name="auth-info-required">auth-info-required (1setOf type2 keyword)</a><span class="info">CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="auth-info-required">auth-info-required (1setOf type2 keyword)</a><span class="info">CUPS 1.3/OS X 10.5</span></h4> <p>The auth-info-required attribute specifies the authentication information that is required for printing a job. The following keywords are recognized:</p> @@ -2560,26 +2425,26 @@ the system. <p>The job-sheets-supported attribute specifies the available banner files. There will always be at least one banner file available called "none". -<h4><a name="marker-change-time">marker-change-time (integer)</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="marker-change-time">marker-change-time (integer)</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The marker-change-time attribute specifies the printer-up-time value when the last change to the marker-colors, marker-levels, marker-message, marker-names, or marker-types attributes was made.</p> -<h4><a name="marker-colors">marker-colors (1setof name(MAX))</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="marker-colors">marker-colors (1setof name(MAX))</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The marker-colors attribute specifies the color(s) for each supply in the printer. It is only available when the driver provides supply levels. The color is either "none" or one or more hex-encoded sRGB colors of the form "#RRGGBB".</p> -<h4><a name="marker-high-levels">marker-high-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="marker-high-levels">marker-high-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The marker-high-levels attribute specifies the supply levels that indicate a near-full condition. A value of 100 should be used for supplies that are consumed/emptied, e.g. ink cartridges.</p> -<h4><a name="marker-levels">marker-levels (1setof integer(-3:100))</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="marker-levels">marker-levels (1setof integer(-3:100))</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The marker-levels attribute specifies the current supply levels for the printer. It is only available when the driver provides supply levels. A @@ -2587,24 +2452,24 @@ 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.</p> -<h4><a name="marker-low-levels">marker-low-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="marker-low-levels">marker-low-levels (1setof integer(0:100))</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The marker-low-levels attribute specifies the supply levels that indicate a near-empty condition. A value of 0 should be used for supplies that are filled, e.g. waste ink tanks.</p> -<h4><a name="marker-message">marker-message (text(MAX))</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="marker-message">marker-message (text(MAX))</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The marker-message attribute provides a human-readable status message for the current supply levels, e.g. "12 pages of ink remaining." It is only available when the driver provides supply levels.</p> -<h4><a name="marker-names">marker-names (1setof name(MAX))</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="marker-names">marker-names (1setof name(MAX))</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The marker-names attribute specifies the name(s) for each supply in the printer. It is only available when the driver provides supply levels.</p> -<h4><a name="marker-types">marker-types (1setof type3 keyword)</a><span class='info'>CUPS 1.3/Mac OS X 10.5</span></h4> +<h4><a name="marker-types">marker-types (1setof type3 keyword)</a><span class='info'>CUPS 1.3/OS X 10.5</span></h4> <p>The marker-types attribute specifies the type(s) of each supply in the printer. It is only available when the driver provides supply levels. The @@ -2683,13 +2548,13 @@ to this printer. The default port monitor is "none". <p>The port-monitor-supported attribute specifies the available port monitors. -<h4><a name="printer-commands">printer-commands (1setOf Type3 keyword)</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="printer-commands">printer-commands (1setOf Type3 keyword)</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The printer-commands attribute specifies the commands that are supported by the CUPS command file filter. The keyword "none" indicates that no commands are supported.</p> -<h4><a name="printer-dns-sd-name">printer-dns-sd-name (name(MAX) | noValue)</a><span class='info'>CUPS 1.4/Mac OS X 10.6</span></h4> +<h4><a name="printer-dns-sd-name">printer-dns-sd-name (name(MAX) | noValue)</a><span class='info'>CUPS 1.4/OS X 10.6</span></h4> <p>The printer-dns-sd-name attribute specifies the registered DNS-SD service name for the printer. If the printer is not being shared using this protocol, @@ -2709,10 +2574,10 @@ and the following CUPS-specific keywords:</p> permissions. CUPS will not execute programs with world write permissions or setuid programs. When run as root (the default), CUPS also does not execute programs that are not owned by root. - <span class='info'>CUPS 1.4/Mac OS X 10.6</span></li> + <span class='info'>CUPS 1.4/OS X 10.6</span></li> <li><tt>cups-missing-filter-warning</tt> - a filter or backend is not - installed. <span class='info'>CUPS 1.4/Mac OS X 10.6</span></li> + installed. <span class='info'>CUPS 1.4/OS X 10.6</span></li> </ul> diff --git a/doc/help/spec-postscript.html b/doc/help/spec-postscript.html index 3aa99c41..8a84273c 100644 --- a/doc/help/spec-postscript.html +++ b/doc/help/spec-postscript.html @@ -8,11 +8,11 @@ </head> <body> <!-- - "$Id: spec-postscript.html 9727 2011-04-28 21:20:12Z mike $" + "$Id: spec-postscript.html 10424 2012-04-23 17:26:57Z mike $" CUPS PostScript file specification for CUPS. - Copyright 2007-2011 by Apple Inc. + Copyright 2007-2012 by Apple Inc. Copyright 2006 by Easy Software Products. These coded instructions, statements, and computer programs are the @@ -39,7 +39,7 @@ output will work reliably.</p> de-facto standard print job file format/language for UNIX-based applications, it is slowly being phased out in favor of Adobe's Portable Document Format ("PDF") which offers many advantages -over PostScript. Mac OS X uses PDF as the primary print job file +over PostScript. OS X uses PDF as the primary print job file format and Linux is making the transition. Both PostScript and PDF are complex formats, and we highly recommend using high-level toolkits whenever possible to create your print jobs.</blockquote> diff --git a/doc/help/spec-ppd.html b/doc/help/spec-ppd.html index f92725d8..21433684 100644 --- a/doc/help/spec-ppd.html +++ b/doc/help/spec-ppd.html @@ -341,7 +341,7 @@ div.contents ul.subcontents li { <body> <div class='body'> <!-- - "$Id: spec-ppd.html 9813 2011-06-01 17:00:27Z mike $" + "$Id: spec-ppd.html 10441 2012-04-30 20:59:09Z mike $" PPD extension documentation for CUPS. @@ -390,13 +390,14 @@ div.contents ul.subcontents 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="#OPTIONS">CUPS 1.3/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> + <li><a href="#cupsPageSizeCategory">cupsPageSizeCategory</a></li> </ul></li> <li><a href="#ATTRIBUTES">General Attributes</a><ul class="subcontents"> <li><a href="#cupsBackSide">cupsBackSide</a></li> @@ -413,6 +414,7 @@ div.contents ul.subcontents 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="#cupsMaxCopies">cupsMaxCopies</a></li> <li><a href="#cupsModelNumber">cupsModelNumber</a></li> <li><a href="#cupsPJLCharset">cupsPJLCharset</a></li> <li><a href="#cupsPJLDisplay">cupsPJLDisplay</a></li> @@ -422,8 +424,9 @@ div.contents ul.subcontents li { <li><a href="#cupsSingleFile">cupsSingleFile</a></li> <li><a href="#cupsSNMPSupplies">cupsSNMPSupplies</a></li> <li><a href="#cupsVersion">cupsVersion</a></li> + <li><a href="#JCLToPDFInterpreter">JCLToPDFInterpreter</a></li> </ul></li> -<li><a href="#MACOSX">Mac OS X Attributes</a><ul class="subcontents"> +<li><a href="#MACOSX">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> @@ -469,11 +472,11 @@ LINE-END = CR / LF / CR LF <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> +<h3><span class='info'>OS X 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3> <p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</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>This 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> @@ -484,7 +487,7 @@ LINE-END = CR / LF / CR LF *APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool" </pre> -<h3><span class='info'>Mac OS X 10.2/CUPS 1.4</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3> +<h3><span class='info'>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> @@ -513,7 +516,7 @@ LINE-END = CR / LF / CR LF *CloseUI: OptionDuplex </pre> -<h3><span class='info'>Mac OS X 10.4/CUPS 1.5</span><a name='OID'>OIDMainKeyword</a></h3> +<h3><span class='info'>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> @@ -548,7 +551,7 @@ LINE-END = CR / LF / CR LF <p class='summary'>*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</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>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 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> option keywords defined in the PPD file.</p> @@ -581,7 +584,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> </pre> -<h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> +<h3><span class='info'>OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> <p class='summary'>*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"</p> @@ -620,22 +623,22 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> *cupsICCQualifier3: Resolution </pre> -<h3><span class='info'>Mac OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3> +<h3><span class='info'>OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3> <p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br> *<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br> *<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br> *<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</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> +<p>These keywords tell the 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 OS X 10.6, the default RGB color space was Apple's "GenericRGB". The new default in OS X 10.6 and later is "sRGB". For more information, see <a href="http://support.apple.com/kb/HT3712">"OS X v10.6: About gamma 2.2"</a> on Apple's support site.</p> </blockquote> -<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4> +<h4><span class='info'>OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4> <p class='summary'>*APCustomColorMatchingName name/text: ""</p> @@ -649,7 +652,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> *fr.APCustomColorMatchingName name/La AcmeColor(tm): "" </pre> -<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4> +<h4><span class='info'>OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4> <p class='summary'>*APCustomColorMatchingProfile: name</p> @@ -671,7 +674,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> *APCustomColorMatchingProfile: AdobeRGB </pre> -<h4><span class='info'>Mac OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4> +<h4><span class='info'>OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4> <p class='summary'>*APDefaultCustomColorMatchingProfile: name</p> @@ -685,7 +688,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> *APDefaultCustomColorMatchingProfile: sRGB </pre> -<h4><span class='info'>Mac OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4> +<h4><span class='info'>OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4> <p class='summary'>*APSupportsCustomColorMatching: boolean</p> @@ -721,7 +724,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> </blockquote> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3> <p class='summary'>*cupsUIConstraints resolver: "*Keyword1 *Keyword2 ..."<br> *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 ..."<br> @@ -751,7 +754,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> *cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsUIResolver'>cupsUIResolver</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsUIResolver'>cupsUIResolver</a></h3> <p class='summary'>*cupsUIResolver resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p> @@ -853,7 +856,7 @@ f(x) = density * x <sup style='font-size: 100%'>gamma</sup> </pre> -<h2 class='title'><a name='OPTIONS'><span class="info">CUPS 1.3/Mac OS X 10.6</span>Custom Options</a></h2> +<h2 class='title'><a name='OPTIONS'><span class="info">CUPS 1.3/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> @@ -1311,7 +1314,7 @@ PRE B { <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> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMediaQualifier2'>cupsMediaQualifier2</a></h3> <p class='summary'>*cupsMediaQualifier2: MainKeyword</p> @@ -1330,7 +1333,7 @@ custom page size limits.</p> *cupsMinSize ..Photo: "300 300" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMediaQualifier3'>cupsMediaQualifier3</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMediaQualifier3'>cupsMediaQualifier3</a></h3> <p class='summary'>*cupsMediaQualifier3: MainKeyword</p> @@ -1349,7 +1352,7 @@ custom page size limits.</p> *cupsMinSize ..Photo: "300 300" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMinSize'>cupsMinSize</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMinSize'>cupsMinSize</a></h3> <p class='summary'>*cupsMinSize .Qualifier2.Qualifier3: "width length"<br> *cupsMinSize .Qualifier2.: "width length"<br> @@ -1372,7 +1375,7 @@ are used to identify options to use for matching.</p> *cupsMinSize ..Photo: "300 300" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMaxSize'>cupsMaxSize</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMaxSize'>cupsMaxSize</a></h3> <p class='summary'>*cupsMaxSize .Qualifier2.Qualifier3: "width length"<br> *cupsMaxSize .Qualifier2.: "width length"<br> @@ -1396,9 +1399,24 @@ are used to identify options to use for matching.</p> </pre> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsPageSizeCategory'>cupsPageSizeCategory</a></h3> + +<p class="summary">*cupsPageSizeCategory name/text: "name name2 ... nameN"</p> + +<p>This keyword lists related paper size names that should be grouped together in the Print or Page Setup dialogs. The "name" portion of the keyword specifies the root/default size for the grouping. On OS X the grouped paper sizes are shown in a submenu of the main paper size. When omitted, sizes with the same dimensions are automatically grouped together, for example "Letter" and "Letter.Borderless".</p> + +<p>Example:</p> + +<pre class="command"> +<em>*% Specify grouping of borderless/non-borderless sizes</em> +*cupsPageSizeCategory Letter/US Letter: "Letter Letter.Borderless" +*cupsPageSizeCategory A4/A4: "A4 A4.Borderless" +</pre> + + <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsBackSide'>cupsBackSide</a></h3> +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsBackSide'>cupsBackSide</a></h3> <p class='summary'>*cupsBackSide: keyword</p> @@ -1474,7 +1492,7 @@ will be ignored.</p> </table> </div> -<p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p> +<p><em>* - Not supported in OS X 10.5.x and earlier</em></p> <div class='figure'><table summary='Back side images'> <caption>Figure 1: Back side images</caption> @@ -1494,7 +1512,7 @@ will be ignored.</p> <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> keyword.</p> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsCommands'>cupsCommands</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsCommands'>cupsCommands</a></h3> <p class='summary'>*cupsCommands: "name name2 ... nameN"</p> @@ -1510,7 +1528,7 @@ by whitespace.</p> </pre> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3> +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3> <p class='summary'>*cupsEvenDuplex: boolean</p> @@ -1588,21 +1606,21 @@ the special filter program "-" may be specified.</p> <p class='summary'>*cupsFlipDuplex: boolean</p> -<p>Due to implementation differences between Mac OS X and Ghostscript, +<p>Due to implementation differences between OS X and Ghostscript, 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> <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value -of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with +of <code>Rotated</code> on OS X and <code>Flipped</code> with Ghostscript.</p> <p>The default value is <code>false</code>.</p> <blockquote><b>Note:</b> -<p>Mac OS X drivers that previously used +<p>OS X drivers that previously used <tt>cupsFlipDuplex</tt> may wish to provide both the old and new keywords for maximum compatibility, for example:</p> @@ -1619,7 +1637,7 @@ Ghostscript can use:</p> *cupsFlipDuplex: true </pre></blockquote> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3> +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3> <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p> @@ -1635,7 +1653,7 @@ values to PPD options and choices.</p> *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape" </pre> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsIPPReason'>cupsIPPReason</a></h3> +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsIPPReason'>cupsIPPReason</a></h3> <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p> @@ -1688,7 +1706,7 @@ http://www.vendor.com/help" *cupsIPPSupplies: False </pre> -<h3><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3> +<h3><span class='info'>CUPS 1.2/OS X 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3> <p class='summary'>*cupsLanguages: "locale list"</p> @@ -1718,7 +1736,7 @@ hardware. The default value is <code>false</code>.</p> *cupsManualCopies: true </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMarkerName'>cupsMarkerName</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMarkerName'>cupsMarkerName</a></h3> <p class='summary'>*cupsMarkerName/Name Text: ""</p> @@ -1732,7 +1750,7 @@ generated by the driver to human readable text.</p> *cupsMarkerName cyanToner/Cyan Toner: "" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3> <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p> @@ -1746,6 +1764,19 @@ are approximate".</p> *cupsMarkerNotice: "Supply levels are approximate." </pre> +<h3><span class='info'>CUPS 1.6/OS X 10.8</span><a name='cupsMaxCopies'>cupsMaxCopies</a></h3> + +<p class='summary'>*cupsMaxCopies: integer</p> + +<p>This integer keyword notifies the filters that the destination printer supports up to N copies in hardware. The default value is <code>9999</code>.</p> + +<p>Example:</p> + +<pre class='command'> +<em>*% Tell the RIP filters we can do up to 99 copies</em> +*cupsMaxCopies: 99 +</pre> + <h3><a name='cupsModelNumber'>cupsModelNumber</a></h3> <p class='summary'>*cupsModelNumber: number</p> @@ -1761,7 +1792,8 @@ the output for a specific model of printer.</p> *cupsModelNumber: 1234 </pre> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3> + +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3> <p class='summary'>*cupsPJLCharset: "ISO character set name"</p> @@ -1776,7 +1808,7 @@ assumed.</p> *cupsPJLCharset: "UTF-8" </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3> <p class='summary'>*cupsPJLDisplay: "what"</p> @@ -1795,7 +1827,7 @@ to use "@PJL RDYMSG DISPLAY". The default is "job".</p> *cupsPJLDisplay: "none" </pre> -<h3><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3> +<h3><span class='info'>CUPS 1.2/OS X 10.5</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3> <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p> @@ -1827,7 +1859,7 @@ to disable the port monitor for the given URI scheme.</p> *cupsPortMonitor usb/USB Status Monitor: "epson-usb" </pre> -<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsPreFilter'>cupsPreFilter</a></h3> +<h3><span class='info'>CUPS 1.3/OS X 10.5</span><a name='cupsPreFilter'>cupsPreFilter</a></h3> <p class='summary'>*cupsPreFilter: "source/type cost program"</p> @@ -1886,7 +1918,7 @@ before the filter that accepts the given MIME type.</p> *cupsSingleFile: True </pre> -<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3> +<h3><span class='info'>CUPS 1.4/OS X 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3> <p class='summary'>*cupsSNMPSupplies: boolean</p> @@ -1907,7 +1939,7 @@ the standard SNMP Printer MIB OIDs for supply levels. The default value is <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> +"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", or "1.6".</p> <p>Example:</p> @@ -1917,9 +1949,23 @@ PPD file extensions was used. Currently it must be the string </pre> -<h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2> +<h3><span class="info">CUPS 1.6/OS X 10.8</span><a name="JCLToPDFInterpreter">JCLToPDFInterpreter</a></h3> + +<p class="summary">*JCLToPDFInterpreter: "JCL"</p> + +<p>This keyword provfides the JCL command to insert a PDF job file into a printer-ready data stream. The JCL command is added after the <tt>JCLBegin</tt> value and any commands for JCL options in the PPD file.</p> + +<p>Example:</p> + +<pre class='command'> +<em>*% PJL command to start the PDF interpreter</em> +*JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF<0A>" +</pre> + + +<h2 class='title'><a name='MACOSX'>OS X Attributes</a></h2> -<h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3> +<h3><span class='info'>OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3> <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p> @@ -1931,7 +1977,7 @@ plug-ins.</p> <blockquote><b>Note:</b> -<p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat" +<p>Starting with OS X 10.5, each plug-in must be compiled "4-way fat" (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled in order to be usable with all applications.</p> @@ -1945,7 +1991,7 @@ in order to be usable with all applications.</p> *APDialogExtension: "/Library/Printers/vendor/options.plugin" </pre> -<h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3> +<h3><span class='info'>OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3> <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p> @@ -2042,7 +2088,7 @@ looking up IPP reason codes for this printer driver. The *APHelpBook: "file:///Library/Printers/vendor/Help.bundle" </pre> -<h3><span class='info'>Mac OS X 10.6</span><a name='APICADriver'>APICADriver</a></h3> +<h3><span class='info'>OS X 10.6</span><a name='APICADriver'>APICADriver</a></h3> <p class='summary'>*APICADriver: boolean</p> @@ -2056,7 +2102,7 @@ Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p> *APScanAppBundleID: "com.apple.ImageCaptureApp" </pre> -<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3> +<h3><span class='info'>OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3> <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p> @@ -2070,7 +2116,7 @@ displaying the printer. The file must be in the Apple icon format.</p> *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns" </pre> -<h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3> +<h3><span class='info'>OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3> <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p> @@ -2087,7 +2133,7 @@ Technical Note TN2144</a> for more information.</p> *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool" </pre> -<h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3> +<h3><span class='info'>OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3> <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p> @@ -2157,7 +2203,7 @@ choice (*MainKeyword OptionKeyword) or a preset identifier and value *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: "" </pre> -<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3> +<h3><span class='info'>OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3> <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p> @@ -2172,7 +2218,7 @@ information.</p> *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app" </pre> -<h3><span class='info'>Mac OS X 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3> +<h3><span class='info'>OS X 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3> <p class='summary'>*APScannerOnly: boolean</p> @@ -2186,7 +2232,7 @@ capabilities. The default is <tt>False</tt>.</p> *APScannerOnly: True </pre> -<h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3> +<h3><span class='info'>OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3> <p class='summary'>*APScanAppBundleID: "bundle ID"</p> @@ -2203,6 +2249,21 @@ the device.</p> <h2 class='title'><a name='HISTORY'>Change History</a></h2> +<h3>Changes in CUPS 1.6</h3> + +<ul> + + <li>Added <a href="#cupsPageSizeCategory"><tt>cupsPageSizeCategory</tt></a> keyword (originally defined in CUPS 1.4).</li> + + <li>Added <a href="#cupsMaxCopies"><tt>cupsMaxCopies</tt></a> keyword.</li> + + <li>Documented <a href="#JCLToPDFInterpreter"><tt>JCLToPDFInterpreter</tt></a> keyword.</li> + + <li>Updated <a href="#cupsVersion"><tt>cupsVersion</tt></a> keyword documentation to list all current releases of CUPS.</li> + +</ul> + + <h3>Changes in CUPS 1.5</h3> <ul> @@ -2262,7 +2323,7 @@ the device.</p> <ul> - <li>Added missing Mac OS X <tt>AP</tt> keywords.</li> + <li>Added missing 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> diff --git a/doc/help/whatsnew.html b/doc/help/whatsnew.html index 856f30a9..1d77c67e 100644 --- a/doc/help/whatsnew.html +++ b/doc/help/whatsnew.html @@ -1,59 +1,64 @@ <HTML> <!-- SECTION: Getting Started --> <HEAD> - <TITLE>What's New in CUPS 1.5</TITLE> + <TITLE>What's New in CUPS 1.6</TITLE> <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css"> </HEAD> <BODY> -<H1 CLASS="title">What's New in CUPS 1.5</H1> +<H1 CLASS="title">What's New in CUPS 1.6</H1> -<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> +<P>CUPS 1.6 provides many changes and new features to CUPS 1.5.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> +<H2 CLASS="title"><A NAME="COMMANDS">General</A></H2> <OL START="1"> - <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>Bonjour Support;</EM> Bonjour printer sharing and discovery is now also supported using Avahi.</LI> - <LI><EM>IPP test tool;</EM> The <code>ipptool</code> IPP test tool is now a first-class user program.</LI> + <LI><EM>Color Management;</EM> ICC profiles referenced by PPD files are now registered on systems with D-BUS and colord installed.</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> + <LI><EM>Default Username;</EM> CUPS now supports the <CODE>CUPS_USER</CODE> environment variable and <CODE>User</CODE> directive in the <VAR>client.conf</VAR> file to override the default username.</LI> -<H2 CLASS="title"><A NAME="SCHEDULER">Scheduler</A></H2> + <LI><EM>Open Printing Filters;</EM> The parallel and serial backends, php_cups scripting module, and bannertops, commandtoescpx, commandtopclx, imagetops, imagetoraster, pdftops, rastertoescpx, rastertopclx, and texttops filters are now provided as part of a separate cups-filters project hosted by the Linux Foundation.</LI> -<OL START="4"> + <LI><EM>Passwords;</EM> Passwords up to 127 characters are now supported.</LI> - <LI><EM>Filter security;</EM> Filters and backends must now have group write permissions disabled.</LI> + <LI><EM>Printer Options;</EM> The "brightness", "columns", "fitplot", "gamma", "hue", "natural-scaling", "penwidth", "position", "ppi", "saturation", and "scaling" options are not longer supported by CUPS directly, while the "page-bottom", "page-left", "page-right", "page-top", "prettyprint", and "wrap" options have been deprecated.</LI> </OL> -<H2 CLASS="title"><A NAME="FILTERS">Print Filters</A></H2> +<H2 CLASS="title"><A NAME="SCHEDULER">Scheduler</A></H2> + +<OL START="7"> + + <LI><EM>Authentication;</EM> The scheduler now supports a <CODE>DefaultAuthType</CODE> value of <CODE>auto</CODE> which automatically chooses between Basic (username/password) and Negotiate (Kerberos) authentication.</LI> -<OL START="5"> + <LI><EM>IPP Conformance;</EM> The scheduler now correctly reports the "number-of-documents" attribute for jobs and fully conforms to the latest IPP/2.1 test suite.</LI> - <LI><EM>HP-GL/2 filter;</EM> The HP-GL/2 filter is no longer provided with CUPS.</LI> + <LI><EM>Permissions;</EM> Filters and backends may no longer have group write permissions enabled.</LI> - <LI><EM>PDF filter;</EM> The PDF filter now supports new Poppler and Ghostscript options.</LI> + <LI><EM>PPD Files;</EM> PPD files can now be packaged and installed as compressed tar files to reduce the amount of disk space required. Dynamic PPD updates are now also consolidated so that a printer's PPD file is updated once at the end of a job.</LI> - <LI><EM>PWG Raster driver;</EM> Added a new PWG Raster printer driver filter.</LI> + <LI><EM>Sharing Protocols;</EM> The scheduler no longer supports the CUPS, LDAP, or SLP protocols for printer sharing.</LI> - <LI><EM>SCSI backend;</EM> The SCSI backend is no longer provided with CUPS.</LI> + <LI><EM>Time-Based Job Limits;</EM> New <CODE>MaxHoldTime</CODE> and <CODE>MaxJobTime</CODE> directives, combined with support for time values in the <CODE>PreserveJobFiles</CODE> and <CODE>PreserveJobHistory</CODE> directives, allow administrators to define time-based job limits and behaviors.</LI> </OL> <H2 CLASS="title"><A NAME="CUPSAPI">CUPS API</A></H2> -<OL START="9"> +<OL START="13"> + + <LI><EM>Destination-Based Printing;</EM> Inspired by IPP Everywhere, new dynamic destination-based APIs allow applications to discover, query, and use both shared and network printers directly and display localized user interfaces with full conflict resolution without static configuration files. These APIs provide equivalent functionality offered by PPD-based printer drivers without the disadvantages of static configuration files.</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>IPP;</EM> IPP requests now default to protocol version 2.0, and the <CODE>ipp_t</CODE> and <CODE>ipp_value_t</CODE> structures are now private by default. New software should be developed using the corresponding accessor functions instead of directly accessing these structures.</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>PPD;</EM> The PPD functions are now officially deprecated in favor of the new destination-based printing APIs.</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> + <LI><EM>SNMP Support;</EM> The <CODE>cupsSideChannelSNMPGet</CODE> and <CODE>cupsSideChannelSNMPWalk</CODE> functions now support OIDs and values up to 64k in length.</LI> </OL> |