From 5a738aeaea5c4dd9384a8601cc5c99be683b69ca Mon Sep 17 00:00:00 2001 From: msweet Date: Thu, 31 Jan 2008 17:01:57 +0000 Subject: [PATCH] Merge changes from CUPS 1.4svn-r7282. git-svn-id: svn+ssh://src.apple.com/svn/cups/easysw/current@614 a1ca3aef-8c08-0410-bb20-df032aa958be --- CHANGES-1.3.txt | 9 + CHANGES.txt | 4 +- backend/backend-private.h | 8 +- berkeley/lprm.c | 176 +- cgi-bin/ipp-var.c | 8 +- cups/Makefile | 73 +- cups/adminutil.c | 12 - cups/api-array.header | 34 + cups/api-array.shtml | 170 +- cups/api-cups.header | 40 + cups/api-cups.shtml | 428 ++- cups/api-filedir.header | 36 + cups/api-filedir.shtml | 36 +- cups/api-filter.header | 39 + cups/api-filter.shtml | 323 +- cups/api-httpipp.header | 37 + cups/api-httpipp.shtml | 322 +- cups/api-overview.header | 49 + cups/api-overview.shtml | 95 + cups/api-ppd.header | 36 + cups/api-ppd.shtml | 196 +- cups/array.c | 54 +- cups/array.h | 2 +- cups/attr.c | 18 +- cups/auth.c | 45 +- cups/backend.h | 8 +- cups/cups.h | 24 +- cups/dest.c | 59 +- cups/dir.c | 38 +- cups/emit.c | 10 +- cups/encode.c | 303 +- cups/file.c | 141 +- cups/getputfile.c | 30 +- cups/ipp-private.h | 3 +- cups/ipp.c | 25 +- cups/ipp.h | 2 +- cups/language.c | 2 +- cups/libcups.exp | 1 + cups/localize.c | 62 +- cups/mark.c | 461 ++- cups/notify.c | 8 +- cups/options.c | 486 +-- cups/ppd.c | 6 +- cups/ppd.h | 18 +- cups/sidechannel.h | 26 +- cups/tempfile.c | 6 +- cups/test.ppd | 8 +- cups/testppd.c | 55 + cups/usersys.c | 26 +- cups/util.c | 181 +- doc/Makefile | 1 + doc/cups-printable.css | 108 +- doc/cups.css | 98 +- doc/help/api-array.html | 1284 ++++--- doc/help/api-cups.html | 3661 ++++++++++-------- doc/help/api-filedir.html | 1555 ++++---- doc/help/api-filter.html | 1039 +++-- doc/help/api-httpipp.html | 7413 ++++++++++++++++++------------------ doc/help/api-overview.html | 408 ++ doc/help/api-ppd.html | 3574 ++++++++--------- doc/help/api-raster.html | 1908 ++++++---- doc/help/policies.html | 20 +- doc/help/spec-ipp.html | 97 +- doc/help/spec-ppd.html | 18 +- filter/Makefile | 11 +- filter/api-raster.header | 37 + filter/api-raster.shtml | 111 +- filter/interpret.c | 15 +- filter/raster.h | 17 +- scheduler/client.c | 52 +- scheduler/ipp.c | 4 + scheduler/job.c | 28 + scheduler/printers.c | 115 + scheduler/printers.h | 3 + scheduler/process.c | 3 +- 75 files changed, 15223 insertions(+), 10596 deletions(-) create mode 100644 cups/api-array.header create mode 100644 cups/api-cups.header create mode 100644 cups/api-filedir.header create mode 100644 cups/api-filter.header create mode 100644 cups/api-httpipp.header create mode 100644 cups/api-overview.header create mode 100644 cups/api-overview.shtml create mode 100644 cups/api-ppd.header create mode 100644 doc/help/api-overview.html create mode 100644 filter/api-raster.header diff --git a/CHANGES-1.3.txt b/CHANGES-1.3.txt index dd43d52cd..3e05bf7dc 100644 --- a/CHANGES-1.3.txt +++ b/CHANGES-1.3.txt @@ -4,6 +4,15 @@ CHANGES-1.3.txt CHANGES IN CUPS V1.3.6 - Documentation updates (STR #2646, STR #2647, STR #2649) + - The scheduler did not support printer supply attributes + (STR #1307) + - The Kerberos credentials provided by some Windows KDCs + were still too large - now use a dynamic buffer to + support credentials up to 64k in size (STR #2695) + - Printing a test page from the web interface incorrectly + defaulted to the "guest" user (STR #2688) + - The cupsEncodeOptions2() function did not parse multiple- + value attribute values properly (STR #2690) - The scheduler incorrectly sent printer-stopped events for status updates from the print filters (STR #2680) - The IPP backend could crash when handling printer errors diff --git a/CHANGES.txt b/CHANGES.txt index c6f9a4b24..5d31aead4 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,8 +1,10 @@ -CHANGES.txt - 2008-01-23 +CHANGES.txt - 2008-01-30 ------------------------ CHANGES IN CUPS V1.4b1 + - Added a new ppdLocalizeMarkerName() function to get + the localized version of a marker-names value. - The scheduler now provides the printer-dns-sd-name attribute for printers shared via DNS-SD/Bonjour. - The pdftops filter now executes the Xpdf or poppler diff --git a/backend/backend-private.h b/backend/backend-private.h index cd6f78b38..cd5aaaf47 100644 --- a/backend/backend-private.h +++ b/backend/backend-private.h @@ -3,7 +3,7 @@ * * Backend support definitions for the Common UNIX Printing System (CUPS). * - * Copyright 2007 by Apple Inc. + * Copyright 2007-2008 by Apple Inc. * Copyright 1997-2007 by Easy Software Products, all rights reserved. * * These coded instructions, statements, and computer programs are the @@ -161,6 +161,12 @@ extern "C" { #define CUPS_TC_langPDF 54 #define CUPS_TC_langJPEG 61 +#define CUPS_TC_supplyThatIsConsumed 3 +#define CUPS_TC_receptacleThatIsFilled 4 + +#define CUPS_TC_process 3 +#define CUPS_TC_spot 4 + #define CUPS_TC_toner 3 #define CUPS_TC_wasteToner 4 #define CUPS_TC_ink 5 diff --git a/berkeley/lprm.c b/berkeley/lprm.c index d453af13c..d00372c55 100644 --- a/berkeley/lprm.c +++ b/berkeley/lprm.c @@ -37,19 +37,13 @@ int /* O - Exit status */ main(int argc, /* I - Number of command-line arguments */ char *argv[]) /* I - Command-line arguments */ { - http_t *http; /* HTTP connection to server */ int i; /* Looping var */ int job_id; /* Job ID */ - const char *dest; /* Destination printer */ + const char *name; /* Destination printer */ char *instance; /* Pointer to instance name */ - char uri[1024]; /* Printer or job URI */ - ipp_t *request; /* IPP request */ - ipp_t *response; /* IPP response */ - ipp_op_t op; /* Operation */ - int num_dests; /* Number of destinations */ - cups_dest_t *dests, /* Destinations */ + cups_dest_t *dest, /* Destination */ *defdest; /* Default destination */ - http_encryption_t encryption; /* Encryption? */ + int did_cancel; /* Did we cancel something? */ _cupsSetLocale(argv); @@ -58,26 +52,9 @@ main(int argc, /* I - Number of command-line arguments */ * Setup to cancel individual print jobs... */ - op = IPP_CANCEL_JOB; - job_id = 0; - dest = NULL; - response = NULL; - http = NULL; - encryption = cupsEncryption(); - - /* - * Open a connection to the server... - */ - - if ((http = httpConnectEncrypt(cupsServer(), ippPort(), encryption)) == NULL) - { - _cupsLangPuts(stderr, _("lprm: Unable to contact server!\n")); - return (1); - } - - num_dests = cupsGetDests2(http, &dests); - defdest = cupsGetDest(NULL, NULL, num_dests, dests); - dest = defdest ? defdest->name : NULL; + did_cancel = 0; + defdest = cupsGetNamedDest(CUPS_HTTP_DEFAULT, NULL, NULL); + name = defdest ? defdest->name : NULL; /* * Process command-line arguments... @@ -89,10 +66,7 @@ main(int argc, /* I - Number of command-line arguments */ { case 'E' : /* Encrypt */ #ifdef HAVE_SSL - encryption = HTTP_ENCRYPT_REQUIRED; - - httpEncryption(http, encryption); - cupsSetEncryption(encryption); + cupsSetEncryption(HTTP_ENCRYPT_REQUIRED); #else _cupsLangPrintf(stderr, _("%s: Sorry, no encryption support compiled in!\n"), @@ -102,25 +76,26 @@ main(int argc, /* I - Number of command-line arguments */ case 'P' : /* Cancel jobs on a printer */ if (argv[i][2]) - dest = argv[i] + 2; + name = argv[i] + 2; else { i ++; - dest = argv[i]; + name = argv[i]; } - if ((instance = strchr(dest, '/')) != NULL) + if ((instance = strchr(name, '/')) != NULL) *instance = '\0'; - if (cupsGetDest(dest, NULL, num_dests, dests) == NULL) + if ((dest = cupsGetNamedDest(CUPS_HTTP_DEFAULT, name, + NULL)) == NULL) { _cupsLangPrintf(stderr, _("%s: Error - unknown destination \"%s\"!\n"), - argv[0], dest); - cupsFreeDests(num_dests, dests); - httpClose(http); - return(1); + argv[0], name); + goto error; } + + cupsFreeDests(1, dest); break; case 'U' : /* Username */ @@ -135,7 +110,7 @@ main(int argc, /* I - Number of command-line arguments */ _("%s: Error - expected username after " "\'-U\' option!\n"), argv[0]); - return (1); + goto error; } cupsSetUser(argv[i]); @@ -155,34 +130,24 @@ main(int argc, /* I - Number of command-line arguments */ _("%s: Error - expected hostname after " "\'-h\' option!\n"), argv[0]); - return (1); + goto error; } else cupsSetServer(argv[i]); } - httpClose(http); - cupsFreeDests(num_dests, dests); + if (defdest) + cupsFreeDests(1, defdest); - if ((http = httpConnectEncrypt(cupsServer(), ippPort(), - encryption)) == NULL) - { - _cupsLangPuts(stderr, _("lprm: Unable to contact server!\n")); - return (1); - } - - num_dests = cupsGetDests2(http, &dests); - defdest = cupsGetDest(NULL, NULL, num_dests, dests); - dest = defdest ? defdest->name : NULL; + defdest = cupsGetNamedDest(CUPS_HTTP_DEFAULT, NULL, NULL); + name = defdest ? defdest->name : NULL; break; default : _cupsLangPrintf(stderr, _("%s: Error - unknown option \'%c\'!\n"), argv[0], argv[i][1]); - cupsFreeDests(num_dests, dests); - httpClose(http); - return (1); + goto error; } else { @@ -190,11 +155,17 @@ main(int argc, /* I - Number of command-line arguments */ * Cancel a job or printer... */ - if (isdigit(argv[i][0] & 255) && - cupsGetDest(argv[i], NULL, num_dests, dests) == NULL) + if ((dest = cupsGetNamedDest(CUPS_HTTP_DEFAULT, argv[i], NULL)) != NULL) + cupsFreeDests(1, dest); + + if (dest) { - dest = NULL; - op = IPP_CANCEL_JOB; + name = argv[i]; + job_id = 0; + } + else if (isdigit(argv[i][0] & 255)) + { + name = NULL; job_id = atoi(argv[i]); } else if (!strcmp(argv[i], "-")) @@ -203,64 +174,23 @@ main(int argc, /* I - Number of command-line arguments */ * Cancel all jobs */ - op = IPP_PURGE_JOBS; - } - else - { - dest = argv[i]; - job_id = 0; - } - - /* - * Build an IPP request, which requires the following - * attributes: - * - * attributes-charset - * attributes-natural-language - * printer-uri + job-id *or* job-uri - * [requesting-user-name] - */ - - request = ippNewRequest(op); - - if (dest) - { - httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, - "localhost", 0, "/printers/%s", dest); - ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, - "printer-uri", NULL, uri); - ippAddInteger(request, IPP_TAG_OPERATION, IPP_TAG_INTEGER, "job-id", - job_id); + job_id = -1; } else { - sprintf(uri, "ipp://localhost/jobs/%d", job_id); - ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "job-uri", NULL, - uri); + _cupsLangPrintf(stderr, + _("%s: Error - unknown destination \"%s\"!\n"), + argv[0], argv[i]); + goto error; } - ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, - "requesting-user-name", NULL, cupsUser()); - - /* - * Do the request and get back a response... - */ - - if (op == IPP_PURGE_JOBS) - response = cupsDoRequest(http, request, "/admin/"); - else - response = cupsDoRequest(http, request, "/jobs/"); - - ippDelete(response); - - if (cupsLastError() > IPP_OK_CONFLICT) + if (cupsCancelJob2(CUPS_HTTP_DEFAULT, name, job_id, 0) != IPP_OK) { _cupsLangPrintf(stderr, "%s: %s\n", argv[0], cupsLastErrorString()); - - cupsFreeDests(num_dests, dests); - httpClose(http); - return (1); + goto error; } + + did_cancel = 1; } /* @@ -268,19 +198,27 @@ main(int argc, /* I - Number of command-line arguments */ * (or default) printer... */ - if (response == NULL) - if (!cupsCancelJob(dest, 0)) + if (!did_cancel && cupsCancelJob2(CUPS_HTTP_DEFAULT, name, 0, 0) != IPP_OK) { _cupsLangPrintf(stderr, "%s: %s\n", argv[0], cupsLastErrorString()); - cupsFreeDests(num_dests, dests); - httpClose(http); - return (1); + goto error; } - cupsFreeDests(num_dests, dests); - httpClose(http); + if (defdest) + cupsFreeDests(1, defdest); return (0); + + /* + * If we get here there was an error, so clean up... + */ + + error: + + if (defdest) + cupsFreeDests(1, defdest); + + return (1); } diff --git a/cgi-bin/ipp-var.c b/cgi-bin/ipp-var.c index 8f8619127..c1703e101 100644 --- a/cgi-bin/ipp-var.c +++ b/cgi-bin/ipp-var.c @@ -525,8 +525,7 @@ cgiPrintTestPage(http_t *http, /* I - Connection to server */ * See who is logged in... */ - if ((user = getenv("REMOTE_USER")) == NULL) - user = "guest"; + user = getenv("REMOTE_USER"); /* * Locate the test page file... @@ -564,8 +563,9 @@ cgiPrintTestPage(http_t *http, /* I - Connection to server */ ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); - ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, - "requesting-user-name", NULL, user); + if (user) + ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, + "requesting-user-name", NULL, user); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "Test Page"); diff --git a/cups/Makefile b/cups/Makefile index e00a368e3..4ea63e200 100644 --- a/cups/Makefile +++ b/cups/Makefile @@ -444,29 +444,86 @@ testsnmp: testsnmp.o libcups.a apihelp: echo Generating CUPS API help files... + mxmldoc --section "Programming" \ + --title "Introduction to CUPS Programming" \ + --css ../doc/cups-printable.css \ + --header api-overview.header --intro api-overview.shtml \ + >../doc/help/api-overview.html mxmldoc --section "Programming" --title "Array API" \ - --intro api-array.shtml \ + --css ../doc/cups-printable.css \ + --header api-array.header --intro api-array.shtml \ array.h array.c >../doc/help/api-array.html mxmldoc --section "Programming" --title "CUPS API" \ - --intro api-cups.shtml \ + --css ../doc/cups-printable.css \ + --header api-cups.header --intro api-cups.shtml \ cups.h dest.c getputfile.c language.c notify.c \ options.c tempfile.c usersys.c \ util.c >../doc/help/api-cups.html mxmldoc --section "Programming" --title "File and Directory APIs" \ - --intro api-filedir.shtml \ + --css ../doc/cups-printable.css \ + --header api-filedir.header --intro api-filedir.shtml \ file.h file.c dir.h dir.c >../doc/help/api-filedir.html mxmldoc --section "Programming" --title "PPD API" \ - --intro api-ppd.shtml \ + --css ../doc/cups-printable.css \ + --header api-ppd.header --intro api-ppd.shtml \ ppd.h attr.c custom.c emit.c localize.c mark.c page.c \ ppd.c >../doc/help/api-ppd.html mxmldoc --section "Programming" --title "HTTP and IPP APIs" \ - --intro api-httpipp.shtml \ + --css ../doc/cups-printable.css \ + --header api-httpipp.header --intro api-httpipp.shtml \ http.h ipp.h auth.c encode.c http.c http-addr.c \ http-support.c ipp.c ipp-support.c md5passwd.c \ request.c >../doc/help/api-httpipp.html - mxmldoc --section "Programming" --title "Filter and Backend APIs" \ - --intro api-filter.shtml \ - backchannel.c sidechannel.c sidechannel.h >../doc/help/api-filter.html + mxmldoc --section "Programming" \ + --title "Filter and Backend Programming" \ + --css ../doc/cups-printable.css \ + --header api-filter.header --intro api-filter.shtml \ + backchannel.c backend.h sidechannel.c sidechannel.h \ + >../doc/help/api-filter.html + +framedhelp: + echo Generating CUPS API help files... + mxmldoc --framed api-overview \ + --section "Programming" \ + --title "Introduction to CUPS Programming" \ + --css ../doc/cups-printable.css \ + --header api-overview.header --intro api-overview.shtml + mxmldoc --framed api-array \ + --section "Programming" --title "Array API" \ + --css ../doc/cups-printable.css \ + --header api-array.header --intro api-array.shtml \ + array.h array.c + mxmldoc --framed api-cups \ + --section "Programming" --title "CUPS API" \ + --css ../doc/cups-printable.css \ + --header api-cups.header --intro api-cups.shtml \ + cups.h dest.c getputfile.c language.c notify.c \ + options.c tempfile.c usersys.c \ + util.c >../doc/help/api-cups.html + mxmldoc --framed api-filedir \ + --section "Programming" --title "File and Directory APIs" \ + --css ../doc/cups-printable.css \ + --header api-filedir.header --intro api-filedir.shtml \ + file.h file.c dir.h dir.c >../doc/help/api-filedir.html + mxmldoc --framed api-ppd \ + --section "Programming" --title "PPD API" \ + --css ../doc/cups-printable.css \ + --header api-ppd.header --intro api-ppd.shtml \ + ppd.h attr.c custom.c emit.c localize.c mark.c page.c \ + ppd.c >../doc/help/api-ppd.html + mxmldoc --framed api-httpipp \ + --section "Programming" --title "HTTP and IPP APIs" \ + --css ../doc/cups-printable.css \ + --header api-httpipp.header --intro api-httpipp.shtml \ + http.h ipp.h auth.c encode.c http.c http-addr.c \ + http-support.c ipp.c ipp-support.c md5passwd.c \ + request.c >../doc/help/api-httpipp.html + mxmldoc --framed api-filter \ + --section "Programming" \ + --title "Filter and Backend Programming" \ + --css ../doc/cups-printable.css \ + --header api-filter.header --intro api-filter.shtml \ + backchannel.c backend.h sidechannel.c sidechannel.h # diff --git a/cups/adminutil.c b/cups/adminutil.c index 3eda26dba..c75b0d904 100644 --- a/cups/adminutil.c +++ b/cups/adminutil.c @@ -1613,8 +1613,6 @@ _cupsAdminSetServerSettings( if (remote_admin) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); } else if (in_conf_location && remote_admin >= 0) { @@ -1632,8 +1630,6 @@ _cupsAdminSetServerSettings( if (remote_admin) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); } else if (in_root_location && (remote_admin >= 0 || share_printers >= 0)) { @@ -1654,8 +1650,6 @@ _cupsAdminSetServerSettings( if (remote_admin > 0 || share_printers > 0) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); } in_admin_location = 0; @@ -1876,8 +1870,6 @@ _cupsAdminSetServerSettings( if (remote_admin > 0 || share_printers > 0) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); cupsFilePuts(temp, "\n"); } @@ -1894,8 +1886,6 @@ _cupsAdminSetServerSettings( if (remote_admin) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); cupsFilePuts(temp, "\n"); } @@ -1915,8 +1905,6 @@ _cupsAdminSetServerSettings( if (remote_admin) cupsFilePrintf(temp, " Allow %s\n", remote_any > 0 ? "all" : "@LOCAL"); - else - cupsFilePuts(temp, " Allow localhost\n"); cupsFilePuts(temp, "\n"); } diff --git a/cups/api-array.header b/cups/api-array.header new file mode 100644 index 000000000..34b796f4c --- /dev/null +++ b/cups/api-array.header @@ -0,0 +1,34 @@ + + +

Array API

+ +
+ + + + + + + + + + + + + + + + +
Headercups/array.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming
diff --git a/cups/api-array.shtml b/cups/api-array.shtml index 355aa4822..92c540b09 100644 --- a/cups/api-array.shtml +++ b/cups/api-array.shtml @@ -3,7 +3,7 @@ Array API introduction for the Common UNIX Printing System (CUPS). - Copyright 2007 by Apple Inc. + Copyright 2007-2008 by Apple Inc. Copyright 1997-2006 by Easy Software Products, all rights reserved. These coded instructions, statements, and computer programs are the @@ -13,33 +13,165 @@ file is missing or damaged, see the license at "http://www.cups.org/". --> -

Introduction

+

Overview

-

The CUPS array API provides a high-performance generic array -container. The contents of the array container can be sorted and -the container itself is designed for optimal speed and memory -usage under a wide variety of conditions.

+

The CUPS array API provides a high-performance generic array container. +The contents of the array container can be sorted and the container itself is +designed for optimal speed and memory usage under a wide variety of conditions. +Sorted arrays use a binary search algorithm from the last found or inserted +element to quickly find matching elements in the array. Arrays created with the +optional hash function can often find elements with a single lookup. The +cups_array_t type is used when +referring to a CUPS array.

The CUPS scheduler (cupsd) and many of the CUPS API functions use the array API to efficiently manage large lists of data.

-

General Usage

+

Managing Arrays

-

The <cups/array.h> header file must be -included to use the cupsArray functions.

+

Arrays are created using either the +cupsArrayNew or +cupsArrayNew2 functions. The +first function creates a new array with the specified callback function +and user data pointer:

-

Programs using these functions must be linked to the CUPS -library: libcups.a, libcups.so.2, -libcups.2.dylib, libcups_s.a, or -libcups2.lib depending on the platform. The following -command compiles myprogram.c using GCC and the CUPS -library:

+
+#include <cups/array.h>
 
-
-gcc -o myprogram myprogram.c -lcups
+static int compare_func(void *first, void *second, void *user_data);
+
+void *user_data;
+cups_array_t *array = cupsArrayNew(compare_func, user_data);
+

+
+
The comparison function (type
+cups_arrayfunc_t) is called
+whenever an element is added to the array and can be NULL to
+create an unsorted array. The function returns -1 if the first element should
+come before the second, 0 if the first and second elements should have the same
+ordering, and 1 if the first element should come after the second.

+
+
The "user_data" pointer is passed to your comparison function. Pass
+NULL if you do not need to associate the elements in your array
+with additional information.

+
+
The cupsArrayNew2 function adds
+two more arguments to support hashed lookups, which can potentially provide
+instantaneous ("O(1)") lookups in your array:

+
+
+#include <cups/array.h>
+
+#define HASH_SIZE 512 /* Size of hash table */
+
+static int compare_func(void *first, void *second, void *user_data);
+static int hash_func(void *element, void *user_data);
+
+void *user_data;
+cups_array_t *array = cupsArrayNew2(compare_func, user_data, hash_func, HASH_SIZE);
+

+
+
The hash function (type
+cups_ahash_func_t) returns a
+number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
+element and is called whenever you look up an element in the array with
+cupsArrayFind. The hash size is
+only limited by available memory, but generally should not be larger than
+16384 to realize any performance improvement.

+
+
Once you have created the array, you add elements using the
+cupsArrayAdd
+cupsArrayInsert functions.
+The first function adds an element to the array, adding the new element
+after any elements that have the same order, while the second inserts the
+element before others with the same order. For unsorted arrays,
+cupsArrayAdd appends the elemnt to
+the end of the array while
+cupsArrayInsert inserts the
+element at the beginning of the array. For example, the following code
+creates a sorted array of character strings:

+
+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
 

 
-
Compatibility

+
Elements are removed using the
+cupsArrayRemove function, for
+example:

 
-
All of these functions require CUPS 1.2 or higher.

+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
+
+/* Remove "Red Fish" */
+cupsArrayRemove(array, "Red Fish");
+

+
+
Finally, you free the memory used by the array using the
+cupsArrayDelete function. All
+of the memory for the array and hash table (if any) is freed, however CUPS
+does not free the elements - if necessary, you must allocate and free the
+elements yourself.

+
+
Finding and Enumerating Elements

+
+
CUPS provides several functions to find and enumerate elements in an
+array. Each one sets or updates a "current index" into the array, such that
+future lookups will start where the last one left off:

+
+

+	
cupsArrayFind

+	
Returns the first matching element .

+	
cupsArrayFirst

+	
Returns the first element in the array.

+	
cupsArrayIndex

+	
Returns the Nth element in the array.

+	
cupsArrayLast

+	
Returns the last element in the array.

+	
cupsArrayNext

+	
Returns the next element in the array.

+	
cupsArrayPrev

+	
Returns the previous element in the array.

+

+
+
Each of these functions returns NULL when there is no
+corresponding element.  For example, a simple for loop using the
+cupsArrayFirst and
+cupsArrayNext functions will
+enumerate all of the strings in our previous example:
 
+
+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
+
+/* Show all of the strings in the array */
+char *s;
+for (s = (char *)cupsArrayFirst(array); s != NULL; s = (char *)cupsArrayNext(array))
+  puts(s);
+

diff --git a/cups/api-cups.header b/cups/api-cups.header
new file mode 100644
index 000000000..a706b55af
--- /dev/null
+++ b/cups/api-cups.header
@@ -0,0 +1,40 @@
+
+
+
CUPS API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/cups.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: Array API

+	Programming: File and Directory APIs

+	Programming: Filter and Backend Programming

+	Programming: HTTP and IPP APIs

+	Programming: PPD API

+	Programming: Raster API

diff --git a/cups/api-cups.shtml b/cups/api-cups.shtml
index 483feb30b..29982e58d 100644
--- a/cups/api-cups.shtml
+++ b/cups/api-cups.shtml
@@ -3,7 +3,7 @@
 
   CUPS API introduction for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -13,35 +13,415 @@
   file is missing or damaged, see the license at "http://www.cups.org/".
 -->
 
-
Introduction

+
Overview

 
-
The CUPS library provides a whole collection of interfaces
-needed to support the internal needs of the CUPS software as well
-as the needs of applications, filters, printer drivers, and
-backends.

+
The CUPS API provides the convenience functions needed to support
+applications, filters, printer drivers, and backends that need to interface
+with the CUPS scheduler.

 
-
Unlike the rest of CUPS, the CUPS API library is provided
-under the GNU Library General Public License. This means that you
-can use the CUPS API library in both proprietary and open-source
-programs.

+
Printers and Classes

 
-
General Usage

+
Printers and classes (collections of printers) are accessed through
+the cups_dest_t structure which
+includes the name (name), instance (instance -
+a way of selected certain saved options), and the options and attributes
+associated with that destination (num_options and
+options). Destinations are created using the
+cupsGetDests function and freed
+using the cupsFreeDests function.
+The cupsGetDest function finds a
+specific destination for printing:

 
-
The <cups/cups.h> header file must be included to
-use the CUPS functions.

+
+#include <cups/cups.h>
 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+cups_dest_t *dests;
+int num_dests = cupsGetDests(&dests);
+cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests);
 
-
-gcc -o myprogram myprogram.c -lcups
+/* do something wiith dest */
+
+cupsFreeDests(num_dests, dests);
 

 
-
Compatibility

+
Passing NULL to
+cupsGetDest for the destination name
+will return the default destination. Similarly, passing a NULL
+instance will return the default instance for that destination.

+
+

+
+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+	
+	
+
+
+
Table 1: Printer Attributes
Attribute NameDescription
"auth-info-required"The type of authentication required for printing to this
+	destination: "none", "username,password", "domain,username,password",
+	or "negotiate" (Kerberos)
"printer-info"The human-readable description of the destination such as "My
+	Laser Printer".
"printer-is-accepting-jobs""1" if the destination is accepting new jobs, "0" if not.
"printer-is-shared""1" if the destination is being shared with other computers, "0" if
+	not.
"printer-location"The human-readable location of the destination such as "Lab 4".
"printer-make-and-model"The human-readable make and model of the destination such as "HP
+	LaserJet 4000 Series".
"printer-state""3" if the destination is idle, "4" if the destination is printing
+	a job, and "5" if the destination is stopped.
"printer-state-change-time"The UNIX time when the destination entered the current state.
"printer-state-reasons"Additional comma-delimited state keywords for the destination
+	such as "media-tray-empty-error" and "toner-low-warning".
"printer-type"The cups_printer_t
+	value associated with the destination.

+
+
Options

+
+
Options are stored in arrays of
+cups_option_t structures. Each
+option has a name (name) and value (value)
+associated with it. The cups_dest_t
+num_options and options members contain the
+default options for a particular destination, along with several informational
+attributes about the destination as shown in Table 1.
+The cupsGetOption function gets
+the value for the named option. For example, the following code lists the
+available destinations and their human-readable descriptions:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dests;
+int num_dests = cupsGetDests(&dests);
+cups_dest_t *dest;
+int i;
+const char *value;
+
+for (i = num_dests, dest = dests; i > 0; i --, dest ++)
+  if (dest->instance == NULL)
+  {
+    value = cupsGetOption("printer-info", dest->num_options, dest->options);
+    printf("%s (%s)\n", dest->name, value ? value : "no description");
+  }
+
+cupsFreeDests(num_dests, dests);
+

+
+
You can create your own option arrays using the
+cupsAddOption function, which
+adds a single named option to an array:

+
+
+#include <cups/cups.h>
+
+int num_options = 0;
+cups_option_t *options = NULL;
+
+/* The returned num_options value is updated as needed */
+num_options = cupsAddOption("first", "value", num_options, &options);
+
+/* This adds a second option value */
+num_options = cupsAddOption("second", "value", num_options, &options);
+
+/* This replaces the first option we added */
+num_options = cupsAddOption("first", "new value", num_options, &options);
+

+
+
Use a for loop to copy the options from a destination:

+
+
+#include <cups/cups.h>
+
+int i;
+int num_options = 0;
+cups_option_t *options = NULL;
+cups_dest_t *dest;
+
+for (i = 0; i < dest->num_options; i ++)
+  num_options = cupsAddOption(dest->options[i].name, dest->options[i].value, num_options, &options);
+

+
+
Use the cupsFreeOptions
+function to free the options array when you are done using it:

+
+
+cupsFreeOptions(num_options, options);
+

+
+
Print Jobs

+
+
Print jobs are identified by a locally-unique job ID number from 1 to
+231-1 and have options and one or more files for printing to a
+single destination. The cupsPrintFile
+function creates a new job with one file. The following code prints the CUPS
+test page file:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+
+/* Print a single file */
+job_id = cupsPrintFile(dest->name, "/usr/share/cups/data/testprint.ps", "Test Print", num_options, options);
+

+
+
The cupsPrintFiles function
+creates a job with multiple files. The files are provided in a
+char * array:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
+
+/* Print three files */
+job_id = cupsPrintFiles(dest->name, 3, files, "Test Print", num_options, options);
+

+
+
Finally, the cupsCreateJob
+function creates a new job with no files in it. Files are added using the
+cupsStartDocument, 
+cupsWriteRequestData,
+and cupsFinishDocument functions.
+The following example creates a job with 10 text files for printing:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+int i;
+char buffer[1024];
+
+/* Create the job */
+job_id = cupsCreateJob(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", num_options, options);
+
+/* If the job is created, add 10 files */
+if (job_id > 0)
+{
+  for (i = 1; i <= 10; i ++)
+  {
+    snprintf(buffer, sizeof(buffer), "file%d.txt", i);
+
+    cupsStartDocument(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, CUPS_FORMAT_TEXT, i == 10);
+
+    snprintf(buffer, sizeof(buffer),
+             "File %d\n"
+             "\n"
+             "One fish,\n"
+             "Two fish,\n
+             "Red fish,\n
+             "Blue fish\n", i);
+
+    /* cupsWriteRequestData can be called as many times as needed */
+    cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
+
+    cupsFinishDocument(CUPS_HTTP_DEFAULT, dest->name);
+  }
+}
+

+
+
Once you have created a job, you can monitor its status using the
+cupsGetJobs function, which returns
+an array of cups_job_t structures.
+Each contains the job ID (id), destination name
+(dest), title (title), and other information
+associated with the job. The job array is freed using the
+cupsFreeJobs function. The following
+example monitors a specific job ID, showing the current job state once every
+5 seconds until the job is completed:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int job_id;
+int num_jobs;
+cups_job_t *jobs;
+int i;
+ipp_jstate_t job_state = IPP_JOB_PENDING;
+ 
+while (job_state < IPP_JOB_STOPPED)
+{
+  /* Get my jobs (1) with any state (-1) */
+  num_jobs = cupsGetJobs(&jobs, dest->name, 1, -1);
+
+  /* Loop to find my job */
+  job_state = IPP_JOB_COMPLETED;
+
+  for (i = 0; i < num_jobs; i ++)
+    if (jobs[i].id == job_id)
+    {
+      job_state = jobs[i].state;
+      break;
+    }
+
+  /* Free the job array */
+  cupsFreeJobs(num_jobs, jobs);
+
+  /* Show the current state */
+  switch (job_state)
+  {
+    case IPP_JOB_PENDING :
+        printf("Job %d is pending.\n", job_id);
+        break;
+    case IPP_JOB_HELD :
+        printf("Job %d is held.\n", job_id);
+        break;
+    case IPP_JOB_PROCESSING :
+        printf("Job %d is processing.\n", job_id);
+        break;
+    case IPP_JOB_STOPPED :
+        printf("Job %d is stopped.\n", job_id);
+        break;
+    case IPP_JOB_CANCELED :
+        printf("Job %d is canceled.\n", job_id);
+        break;
+    case IPP_JOB_ABORTED :
+        printf("Job %d is aborted.\n", job_id);
+        break;
+    case IPP_JOB_COMPLETED :
+        printf("Job %d is completed.\n", job_id);
+        break;
+  }
+
+  /* Sleep if the job is not finished */
+  if (job_state < IPP_JOB_STOPPED)
+    sleep(5);
+}
+

+
+
To cancel a job, use the
+cupsCancelJob function with the
+job ID:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int job_id;
+
+cupsCancelJob(dest->name, job_id);
+

+
+
Error Handling

+
+
If any of the CUPS API printing functions returns an error, the reason for
+that error can be found by calling the
+cupsLastError and
+cupsLastErrorString functions.
+cupsLastError returns the last IPP
+error code
+(ipp_status_t)
+that was encountered, while
+cupsLastErrorString returns
+a (localized) human-readable string that can be shown to the user. For example,
+if any of the job creation functions returns a job ID of 0, you can use
+cupsLastErrorString to show
+the reason why the job could not be created:

+
+
+#include <cups/cups.h>
+
+int job_id;
+
+if (job_id == 0)
+  puts(cupsLastErrorString());
+

+
+
Passwords and Authentication

+
+
CUPS supports authentication of any request, including submission of print
+jobs. The default mechanism for getting the username and password is to use the
+login user and a password from the console.

+
+
To support other types of applications, in particular Graphical User
+Interfaces ("GUIs"), the CUPS API provides functions to set the default
+username and to register a callback function that returns a password string.

+
+
The cupsSetPasswordCB
+function is used to set a password callback in your program. Only one
+function can be used at any time.

+
+
The cupsSetUser function sets the
+current username for authentication. This function can be called by your
+password callback function to change the current username as needed.

+
+
The following example shows a simple password callback that gets a
+username and password from the user:

+
+
+#include <cups/cups.h>
+
+const char *
+my_password_cb(const char *prompt)
+{
+  char	user[65];
+
+
+  puts(prompt);
+
+  /* Get a username from the user */
+  printf("Username: ");
+  if (fgets(user, sizeof(user), stdin) == NULL)
+    return (NULL);
+
+  /* Strip the newline from the string and set the user */
+  user[strlen(user) - 1] = '\0';
+
+  cupsSetUser(user);
+
+  /* Use getpass() to ask for the password... */
+  return (getpass("Password: "));
+}
+
+cupsSetPasswordCB(my_password_cb);
+

 
-
Unless otherwise specified, the CUPS API functions require
-CUPS 1.1 or higher.

+
Similarly, a GUI could display the prompt string in a window with input
+fields for the username and password. The username should default to the
+string returned by the cupsUser
+function.

diff --git a/cups/api-filedir.header b/cups/api-filedir.header
new file mode 100644
index 000000000..755311511
--- /dev/null
+++ b/cups/api-filedir.header
@@ -0,0 +1,36 @@
+
+
+
File and Directory APIs

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headerscups/file.h

+	cups/dir.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

diff --git a/cups/api-filedir.shtml b/cups/api-filedir.shtml
index b356e655c..2b19efa8a 100644
--- a/cups/api-filedir.shtml
+++ b/cups/api-filedir.shtml
@@ -3,7 +3,7 @@
 
   File and directory API introduction for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2005 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -13,45 +13,19 @@
   file is missing or damaged, see the license at "http://www.cups.org/".
 -->
 
-
Introduction

+
Overview

 
 
The CUPS file and directory APIs provide portable interfaces
 for manipulating files and listing files and directories. Unlike
-stdio FILE streams, the cupsFile functions
+stdio FILE streams, the cupsFile functions
 allow you to open more than 256 files at any given time. They
 also manage the platform-specific details of locking, large file
 support, line endings (CR, LF, or CR LF), and reading and writing
 files using Flate ("gzip") compression. Finally, you can also
 connect, read from, and write to network connections using the
-cupsFile functions.

+cupsFile functions.

 
-
The cupsDir functions manage the platform-specific
+
The cupsDir functions manage the platform-specific
 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.

-
-
The CUPS scheduler (cupsd), mailto notifier,
-and many of the CUPS API functions use these functions for
-everything except console (stdin, stdout, stderr) I/O.

-
-
General Usage

-
-
The <cups/dir.h> and
-<cups/file.h> header files must be included to
-use the cupsDir and cupsFile functions,
-respectively.

-
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

-
-
-gcc -o myprogram myprogram.c -lcups
-

-
-
Compatibility

-
-
All of these functions require CUPS 1.2 or higher.

diff --git a/cups/api-filter.header b/cups/api-filter.header
new file mode 100644
index 000000000..f7ae6a368
--- /dev/null
+++ b/cups/api-filter.header
@@ -0,0 +1,39 @@
+
+
+
Filter and Backend Programming

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/backend.h

+	cups/sidechannel.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Programming: PPD API

+	Programming: Raster API

diff --git a/cups/api-filter.shtml b/cups/api-filter.shtml
index 0eda305c7..4f72dfe71 100644
--- a/cups/api-filter.shtml
+++ b/cups/api-filter.shtml
@@ -1,9 +1,10 @@
 
 
-
Introduction

+
Overview

 
-
The CUPS filter and backend APIs define standard exit codes
-and provide access to the backchannel data stream. They are only
-used when writing backends, filters, and port monitors.

+
Filters, printer drivers, port monitors, and backends use a common interface
+for processing print jobs and communicating status information to the scheduler.
+Each filter is run with a standard set of command-line arguments:

 
-
General Usage

+

 
-
The <cups/backend.h> and
-<cups/cups.h> header files must be included to
-use the CUPS_BACKEND_ constants and
-cupsBackChannel functions, respectively.

+	
argv[1]

+	
The job ID

 
-
The <cups/sidechannel.h> header file must be
-included to use the CUPS_SC_ constants and cupsSideChannel functions.

+	
argv[2]

+	
The user printing the job

 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+	
argv[3]

+	
The job name/title

 
-
-gcc -o myprogram myprogram.c -lcups
-

+	
argv[4]

+	
The number of copies to print

 
+	
argv[5]

+	
The options that were provided when the job was submitted

 
-
Compatibility

+	
argv[6]

+	
The file to print (first filter only)

+

 
-
The cupsBackChannel functions require CUPS 1.2 or higher. The cupsSideChannel functions require CUPS 1.3 or higher.

+
The scheduler runs one or more of these programs to print any given job. The
+first filter reads from the print file and writes to the standard output, while
+the remaining filters read from the standard input and write to the standard
+output. The backend is the last filter in the chain and writes to the
+device.

 
+
Exit Codes

 
-
Using the cupsBackChannel APIs

+
Filters must exit with status 0 when they successfully generate print data
+or 1 when they encounter an error. Backends can return any of the
+cups_backend_t constants.

 
-
The cupsBackChannel APIs allow your filters, drivers, and port monitors to read data back from a printer and your backends to send data from a printer to the filters, drivers, and port monitors associated with the current job. Back-channel data is normally sent by the printer in response to a command sent from your program to the printer via stdout.

+
Environment Variables

 
-
The cupsBackChannelRead() function reads data from the printer via the backend. You provide a timeout in seconds along with a buffer pointer and the size of that buffer. It returns the number of bytes or -1 if there was an error. The following code example shows how to poll for back-channel data in your program:

+
The following environment variables are defined by the printing system:

 
-
-#include <cups/cups.h>
+

 
-char buffer[8192];
-ssize_t bytes;
+	
APPLE_LANGUAGES

+	
The Apple language identifier associated with the job
+	(Mac OS X only).

 
-/* Use a timeout of 0.0 seconds to poll for back-channel data */
-bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
-

+	
CHARSET

+	
The job character set, typically "utf-8".

 
-
If you are writing a backend, the cupsBackChannelWrite() function sends any back-channel data you have received from the printer to upstream filters in the print filter chain. We recommend using a timeout of 1.0 seconds:

+	
CLASS

+	
When a job is submitted to a printer class, contains the name of
+	the destination printer class. Otherwise this environment
+	variable will not be set.

 
-
-#include <cups/cups.h>
+	
CONTENT_TYPE

+	
The MIME type associated with the file (e.g.
+	application/postscript).

 
-char buffer[8192];
-ssize_t bytes;
-
-/* Use a timeout of 1.0 seconds to give filters a chance to read */
-cupsBackChannelWrite(buffer, bytes, 1.0);
-

+	
CUPS_CACHEDIR

+	
The directory where cache files can be stored.

 
+	
CUPS_DATADIR

+	
The directory where data files can be found.

 
-
Using the cupsSideChannel APIs

+	
CUPS_SERVERROOT

+	
The root directory of the server.

 
-
The cupsSideChannel APIs allow your filters, drivers, port monitors, and backend to send and receive the following out-of-band commands:

+	
DEVICE_URI

+	
The device-uri associated with the printer.

 
-
    
+	
    FINAL_CONTENT_TYPE
    
+	
    The MIME type associated with the printer (e.g.
+	application/vnd.cups-postscript).
    
 
-	
  • CUPS_SC_CMD_SOFT_RESET -  Do a soft reset
    • 
-	
  • CUPS_SC_CMD_DRAIN_OUTPUT -  Drain all pending output
    • 
-	
  • CUPS_SC_CMD_GET_BIDI -  Return bidirectional capabilities
    • 
-	
  • CUPS_SC_CMD_GET_DEVICE_ID -  Return the IEEE-1284 device ID
    • 
-	
  • CUPS_SC_CMD_GET_STATE - Return the device state
    • 
+	
    LANG
    
+	
    The language locale associated with the job.
    
 
-

+	
PPD

+	
The full pathname of the PostScript Printer Description (PPD)
+	file for this printer.

 
+	
PRINTER

+	
The name of the printer.

 
-
Sending Commands from a Filter, Driver, or Port Monitor

+	
RIP_CACHE

+	
The recommended amount of memory to use for Raster Image
+	Processors (RIPs).

 
-
The cupsSideChannelDoRequest() function is used by filters, drivers, and port monitors to send a command to the backend and read back a response:

-
-
-cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
-                                          char *data, int *datalen,
-                                          double timeout);
-

+
 
-
The CUPS_SC_CMD_SOFT_RESET and CUPS_SC_CMD_DRAIN_OUTPUT commands do not return any data values, while the others return one or more bytes. The timeout parameter allows your program to poll or wait for the command to complete - use a timeout of 30 seconds for CUPS_SC_CMD_SOFT_RESET and CUPS_SC_CMD_DRAIN_OUTPUT and a timeout of 1 second for all other commands.

+
Communicating with the Scheduler

 
-
CUPS_SC_CMD_GET_BIDI returns a single char value that tells you whether the backend supports bidirectional communications:

+
Filters and backends communicate wih the scheduler by writing messages
+to the standard error file. For example, the following code sets the current
+printer state message to "Printing page 5":

 
-
-#include <cups/sidechannel.h>
+
+int page = 5;
 
-char data;
-int datalen;
-cups_sc_bidi_t bidi;
-cups_sc_status_t status;
+fprintf(stderr, "INFO: Printing page %d\n", page);
+

 
-/* Tell cupsSideChannelDoRequest() how big our buffer is... */
-datalen = 1;
+
Each message is a single line of text starting with one of the following
+prefix strings:

+
+

+
+	
ALERT: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "alert" log level.

+
+	
ATTR: attribute=value [attribute=value]

+	
Sets the named printer or job attribute(s). Typically this is used
+	to set the marker-colors, marker-levels,
+	marker-names, marker-types,
+	printer-alert, and printer-alert-description
+	printer attributes.

+
+	
CRIT: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "critical" log
+	level.

+
+	
DEBUG: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "debug" log level.

+
+	
DEBUG2: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "debug2" log level.

+
+	
EMERG: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "emergency" log
+	level.

+
+	
ERROR: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "error" log level.

+
+	
INFO: message

+	
Sets the printer-state-message attribute. If the current log level
+	is set to "debug2", also adds the specified message to the current error
+	log file using the "info" log level.

+
+	
NOTICE: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "notice" log level.

+
+	
PAGE: page-number #-copies

+	
PAGE: total #-pages

+	
Adds an entry to the current page log file. The first form adds
+	#-copies to the job-media-sheets-completed attribute. The second
+	form sets the job-media-sheets-completed attribute to #-pages.

+
+	
STATE: printer-state-reason [printer-state-reason ...]

+	
STATE: + printer-state-reason [printer-state-reason ...]

+	
STATE: - printer-state-reason [printer-state-reason ...]

+	
Sets, adds, or removes printer-state-reason keywords to the
+	current queue. Typically this is used to indicate media, ink, and
+	toner conditions on a printer.

+
+	
WARNING: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "warning" log
+	level.

+
+

+
+
Messages without one of these prefixes are treated as if they began with
+the "DEBUG:" prefix string.

+
+
Communicating with the Backend

+
+
Filters can communicate with the backend via the
+cupsBackChannelRead and
+cupsSideChannelDoRequest
+functions. The 
+cupsBackChannelRead function
+reads data that has been sent back from the device and is typically used to
+obtain status and configuration information. For example, the following code
+polls the backend for back-channel data:

+
+
+#include <cups/cups.h>
 
-/* Get the bidirectional capabilities, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_BIDI, &data, &datalen, 1.0);
+char buffer[8192];
+ssize_t bytes;
 
-/* Use the returned value if OK was returned and the length is still 1 */
-if (status == CUPS_SC_STATUS_OK && datalen == 1)
-  bidi = (cups_sc_bidi_t)data;
-else
-  bidi = CUPS_SC_BIDI_NOT_SUPPORTED;
+/* Use a timeout of 0.0 seconds to poll for back-channel data */
+bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
 

 
-
CUPS_SC_CMD_GET_DEVICE_ID returns a string of characters containing the IEEE-1284 device ID for the connected printer:

+The
+cupsSideChannelDoRequest
+function allows you to get out-of-band status information and do synchronization
+with the device. For example, the following code gets the current IEEE-1284
+device ID string from the backend:

 
-
+
 #include <cups/sidechannel.h>
 
 char data[2049];
 int datalen;
-cups_sc_status_t status;
+cups_sc_status_t status;
 
 /* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
 datalen = sizeof(data) - 1;
 
 /* Get the IEEE-1284 device ID, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0);
+status = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0);
 
 /* Use the returned value if OK was returned and the length is non-zero */
 if (status == CUPS_SC_STATUS_OK && datalen > 0)
@@ -147,59 +236,53 @@ else
   data[0] = '\0';
 

 
-
CUPS_SC_CMD_GET_STATE returns a single char value that tells you the current device state:

-
-
-#include <cups/sidechannel.h>
+
Backends communicate with filters using the reciprocal functions
+cupsBackChannelWrite,
+cupsSideChannelRead, and
+cupsSideChannelWrite. We
+recommend writing back-channel data using a timeout of 1.0 seconds:

 
-char data;
-int datalen;
-cups_sc_state_t state;
-cups_sc_status_t status;
-
-/* Tell cupsSideChannelDoRequest() how big our buffer is... */
-datalen = 1;
-
-/* Get the bidirectional capabilities, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_STATE, &data, &datalen, 1.0);
-
-/* Use the returned value if OK was returned and the length is still 1 */
-if (status == CUPS_SC_STATUS_OK && datalen == 1)
-  state = (cups_sc_state_t)data;
-else
-  state = CUPS_SC_STATE_OFFLINE;
-

-
-
-
Handling Commands in your Backend

+
+#include <cups/cups.h>
 
-
The cupsSideChannelRead() function is used by backends to read a command from a filter, driver, or port monitor:

+char buffer[8192];
+ssize_t bytes;
 
-
-int cupsSideChannelRead(cups_sc_command_t &command,
-                        cups_sc_status_t  &status,
-                        char *data, int *datalen, double timeout);
+/* Use a timeout of 1.0 seconds to give filters a chance to read */
+cupsBackChannelWrite(buffer, bytes, 1.0);
 

 
-
Backends can either poll for commands using a timeout of 0.0, wait indefinitely for commands using a timeout of -1.0 (probably in a separate thread for that purpose), or use select() or poll() on the CUPS_SC_FD file descriptor (4) to handle input and output on several file descriptors at the same time. Backends can pass NULL for the data and datalen parameters, since none of the commands sent by upstream filters contain any data at this time.

-
-
Once a command is processed, the backend uses the cupsSideChannelWrite() function to send its response:

-
-
+
The cupsSideChannelRead
+function reads a side-channel command from a filter, driver, or port monitor.
+Backends can either poll for commands using a timeout of 0.0, wait
+indefinitely for commands using a timeout of -1.0 (probably in a
+separate thread for that purpose), or use select or
+poll on the CUPS_SC_FD file descriptor (4) to handle
+input and output on several file descriptors at the same time. Backends can pass
+NULL for the data and datalen parameters
+since none of the commands sent by upstream filters contain any data at this
+time.

+
+
Once a command is processed, the backend uses the
+cupsSideChannelWrite function
+to send its response. For example, the following code shows how to poll for a
+side-channel command and respond to it:

+
+
 #include <cups/sidechannel.h>
 
-cups_sc_command_t command;
-cups_sc_status_t status;
+cups_sc_command_t command;
+cups_sc_status_t status;
 
 /* Poll for a command... */
-if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
+if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
 {
   char data[2048];
   int datalen;
 
   switch (command)
   {
-    ... handle supported commands, file data/datalen/status with values as needed ...
+    /* handle supported commands, file data/datalen/status with values as needed */
 
     default :
         status  = CUPS_SC_STATUS_NOT_IMPLEMENTED;
@@ -208,6 +291,6 @@ if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
   }
 
   /* Send a response... */
-  cupsSideChannelWrite(command, status, data, datalen, 1.0);
+  cupsSideChannelWrite(command, status, data, datalen, 1.0);
 }
 

diff --git a/cups/api-httpipp.header b/cups/api-httpipp.header
new file mode 100644
index 000000000..03d5a8def
--- /dev/null
+++ b/cups/api-httpipp.header
@@ -0,0 +1,37 @@
+
+
+
HTTP and IPP APIs

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/cups.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	References: CUPS Implementation of IPP

diff --git a/cups/api-httpipp.shtml b/cups/api-httpipp.shtml
index 93e34f934..b755b7ded 100644
--- a/cups/api-httpipp.shtml
+++ b/cups/api-httpipp.shtml
@@ -3,7 +3,7 @@
 
   HTTP and IPP API introduction for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -13,31 +13,311 @@
   file is missing or damaged, see the license at "http://www.cups.org/".
 -->
 
-
Introduction

+
Overview

 
-
The CUPS HTTP and IPP APIs provide low-level access to the
-HTTP and IPP protocols and CUPS scheduler. They are typically
-used by monitoring and administration programs to perform
-specific functions not supported by the high-level CUPS API
-functions.

+
The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP
+protocols and CUPS scheduler. They are typically used by monitoring and
+administration programs to perform specific functions not supported by the
+high-level CUPS API functions.

 
-
General Usage

+
The HTTP APIs use an opaque structure called
+http_t to manage connections to
+a particular HTTP or IPP server. The
+httpConnectEncrypt function is
+used to create an instance of this structure for a particular server.
+The constant CUPS_HTTP_DEFAULT can be used with all of the
+cups functions to refer to the default CUPS server - the functions
+create a per-thread http_t as needed.

 
-
The <cups/cups.h> header file must be included to
-use the HTTP and IPP functions.

+
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 ipp_t structure holds a
+complete request or response and is allocated using the
+ippNew or
+ippNewRequest functions and
+freed using the ippDelete function.

 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+
The second structure is called
+ipp_attribute_t and holds a
+single IPP attribute which consists of a group tag (group_tag), a
+value type tag (value_tag), the attribute name (name),
+and 1 or more values (values[]). Attributes are added to an
+ipp_t structure using one of the
+ippAdd functions. For example, use
+ippAddString to add a
+"requesting-user-name" string attribute to a request:

 
-
-gcc -o myprogram myprogram.c -lcups
+
+ipp_t *request = ippNewRequest(IPP_GET_JOBS);
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+             NULL, cupsUser());
+

+
+
Once you have created an IPP request, use the cups
+functions to send the request to and read the response from the server.
+For example, the cupsDoRequest
+function can be used for simple query operations that do not involve files:

+
+
+#include <cups/cups.h>
+
+
+ipp_t *get_jobs(void)
+{
+  ipp_t *request = ippNewRequest(IPP_GET_JOBS);
+
+  ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+               NULL, cupsUser());
+
+  return (cupsDoRequest(CUPS_HTTP_DEFAULT, request, "/"));
+}
+

+
+
The cupsDoRequest 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
+ippFindAttribute and
+ippFindNextAttribute functions
+to find specific attributes, for example:

+
+
+ipp_t *response;
+ipp_attribute_t *attr;
+
+attr = ippFindAttribute(response, "printer-state", IPP_TAG_ENUM);
+

+
+
You can also walk the list of attributes with a simple for loop
+like this:

+
+
+ipp_t *response;
+ipp_attribute_t *attr;
+
+for (attr = response->attrs; attr != NULL; attr = attr->next)
+  if (attr->name == NULL)
+    puts("--SEPARATOR--");
+  else
+    puts(attr->name);
 

 
-
Compatibility

+
The for loop approach is normally used when collecting
+attributes for multiple objects (jobs, printers, etc.) in a response. Attributes
+with NULL names indicate a separator between the attributes of
+each object. For example, the following code will list the jobs returned from
+our previous get_jobs example code:

+
+
+ipp_t *response = get_jobs();
+
+if (response != NULL)
+{
+  ipp_attribute_t *attr;
+  int job_id = 0;
+  char *job_name = NULL;
+  char *job_originating_user_name = NULL;
+
+  puts("Job ID  Owner             Title");
+  puts("------  ----------------  ---------------------------------");
+
+  for (attr = response->attrs; attr != NULL; attr = attr->next)
+  {
+   /* Attributes without names are separators between jobs */
+    if (attr->name == NULL)
+    {
+      if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL)
+        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;
+  }
+
+  if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL)
+    printf("%5d  %-16s  %s\n", job_id, job_originating_user_name, job_name);
+}
+

+
+
Creating URI Strings

+
+
To ensure proper encoding, the
+httpAssembleURIf function must be
+used to format a "printer-uri" string for all printer-based requests:

+
+
+const char *name = "Foo";
+char uri[1024];
+ipp_t *request;
+
+httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
+                 ippPort(), "/printers/%s", name);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
+

+
+
Sending Requests with Files

+
+
The cupsDoFileRequest and
+cupsDoIORequest functions are
+used for requests involving files. The
+cupsDoFileRequest function
+attaches the named file to a request and is typically used when sending a print
+file or changing a printer's PPD file:

+
+
+const char *filename = "/usr/share/cups/data/testprint.ps";
+const char *name = "Foo";
+char uri[1024];
+char resource[1024];
+ipp_t *request = ippNewRequest(IPP_PRINT_JOB);
+ipp_t *response;
+
+/* Use httpAssembleURIf for the printer-uri string */
+httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
+                 ippPort(), "/printers/%s", name);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+             NULL, cupsUser());
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
+             NULL, "testprint.ps");
 
-
Unless otherwise specified, the HTTP and IPP API functions
-require CUPS 1.1 or higher.

+/* Use snprintf for the resource path */
+snprintf(resource, sizeof(resource), "/printers/%s", name);
+
+response = cupsDoFileRequest(CUPS_HTTP_DEFAULT, request, resource, filename);
+

+
+
The cupsDoIORequest function
+optionally attaches a file to the request and optionally saves a file in the
+response from the server. It is used when using a pipe for the request
+attachment or when using a request that returns a file, currently only
+CUPS_GET_DOCUMENT and CUPS_GET_PPD. For example,
+the following code will download the PPD file for the sample HP LaserJet
+printer driver:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+response = cupsDoIORequest(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd);
+

+
+
The example passes -1 for the input file descriptor to specify
+that no file is to be attached to the request. The PPD file attached to the
+response is written to the temporary file descriptor we created using the
+cupsTempFd function.

+
+
Asynchronous Request Processing

+
+
The cupsSendRequest and
+cupsGetResponse support
+asynchronous communications with the server. Unlike the other request
+functions, the IPP request is not automatically freed, so remember to
+free your request with the ippDelete
+function.

+
+
File data is attached to the request using the
+cupsWriteRequestData
+function, while file data returned from the server is read using the
+cupsReadResponseData
+function. We can rewrite the previous CUPS_GET_PPD example
+to use the asynchronous functions quite easily:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+if (cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE)
+{
+  response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/");
+
+  if (response != NULL)
+  {
+    ssize_t bytes;
+    char buffer[8192];
+
+    while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
+      write(tempfd, buffer, bytes);
+  }
+}
+
+/* Free the request! */
+ippDelete(request);
+

+
+
The cupsSendRequest function
+returns the initial HTTP request status, typically either
+HTTP_CONTINUE or HTTP_UNAUTHORIZED. The latter status
+is returned when the request requires authentication of some sort. The
+cupsDoAuthentication function
+must be called when your see HTTP_UNAUTHORIZED and the request
+re-sent. We can add authentication support to our example code by using a
+do ... while loop:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+http_status_t status;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+/* Loop for authentication */
+do
+{
+  status = a href='#cupsSendRequest'>cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/");
+
+  if (status == HTTP_UNAUTHORIZED)
+  {
+    /* Try to authenticate, break out of the loop if that fails */
+    if (cupsDoAuthentication(CUPS_HTTP_DEFAULT, "POST", "/"))
+      break;
+  }
+}
+while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED);
+
+if (status == HTTP_CONTINUE)
+{
+  response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/");
+
+  if (response != NULL)
+  {
+    ssize_t bytes;
+    char buffer[8192];
+
+    while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
+      write(tempfd, buffer, bytes);
+  }
+}
+
+/* Free the request! */
+ippDelete(request);
+

diff --git a/cups/api-overview.header b/cups/api-overview.header
new file mode 100644
index 000000000..51dbb2776
--- /dev/null
+++ b/cups/api-overview.header
@@ -0,0 +1,49 @@
+
+
+
Introduction to CUPS Programming

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headerscups/cups.h

+	cups/array.h

+	cups/backend.h

+	cups/dir.h

+	cups/file.h

+	cups/ppd.h

+	cups/raster.h

+	cups/sidechannel.h
Libraries-lcups

+	-lcupsimage
See AlsoProgramming: CUPS API

+	Programming: Array API

+	Programming: File and Directory APIs

+	Programming: Filter and Backend Programming

+	Programming: HTTP and IPP APIs

+	Programming: PPD API

+	Programming: Raster API

diff --git a/cups/api-overview.shtml b/cups/api-overview.shtml
new file mode 100644
index 000000000..dd1d6061d
--- /dev/null
+++ b/cups/api-overview.shtml
@@ -0,0 +1,95 @@
+
+
+
Overview

+
+
CUPS provides two libraries that interface with the different parts of the
+printing system. The "cups" library provides all of the common application and
+filter functions while the "cupsimage" library provides all of the imaging
+functions used in raster printer drivers. The "cups" library functions are
+accessed by including the <cups/cups.h> header, while
+"cupsimage" functions are found in the <cups/raster.h>
+header.

+
+
Compiling Programs

+
+
The CUPS libraries can be used from any C, C++, or Objective C program.
+The method of compiling against the libraries varies depending on the
+operating system and installation of CUPS. The following sections show how
+to compile a simple program (shown below) in two common environments.

+
+
The following simple program lists the available printers on the system:

+
+
+#include <stdio.h>
+#include <cups/cups.h>
+
+int main(void)
+{
+  int i;
+  cups_dest_t *dests, *dest;
+  int num_dests = cupsGetDests(&dests);
+
+  for (i = num_dests, dest = dests; i > 0; i --, dest ++)
+  {
+    if (dest->instance)
+      printf("%s/%s\n", dest->name, dest->instance);
+    else
+      puts(dest->name);
+  }
+
+  return (0);
+}
+

+
+
Compiling with Xcode

+
+
In Xcode, choose New Project... from the File menu,
+then select the Standard Tool project type under Command Line
+Utility. Click Next and choose a project directory. Click
+Next to create the project.

+
+
In the project window, double-click on the Targets group and
+control-click on the simple target to show the context menu. Choose
+Existing Framework... from the Add submenu. When the file
+chooser sheet appears, press the / key and enter "/usr/lib". Scroll
+down the file list and select the libcups.dylib file. Click the
+Add button in the file chooser and attributes sheets.

+
+
In the project window, double-click on the main.c source file.
+Replace the template source code with the listing above and save it. Click the
+Build and Go button to build the sample program and run it.

+
+
Compiling with GCC

+
+
From the command-line, create a file called sample.c using your
+favorite editor and then run the following command to compile it with GCC and
+run it:

+
+
+gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
+./simple
+

+
+
The cups-config command provides the compiler flags
+("cups-config --cflags") and libraries ("cups-config --libs") needed for the
+local system.

+
+
Where to Go Next

+
+
If you are developing a print filter, driver, or backend, see the
+Filter and Backend Programming
+guide. Raster printer driver developers should also read the
+Raster API reference.

diff --git a/cups/api-ppd.header b/cups/api-ppd.header
new file mode 100644
index 000000000..dfcb26a4c
--- /dev/null
+++ b/cups/api-ppd.header
@@ -0,0 +1,36 @@
+
+
+
PPD API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/ppd.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Reference: CUPS PPD Specification

diff --git a/cups/api-ppd.shtml b/cups/api-ppd.shtml
index 497e7ae6b..c1c2402d3 100644
--- a/cups/api-ppd.shtml
+++ b/cups/api-ppd.shtml
@@ -13,31 +13,187 @@
   file is missing or damaged, see the license at "http://www.cups.org/".
 -->
 
-
Introduction

+
Overview

 
-
The CUPS PPD API provides read-only access the data in
-PostScript Printer Description ("PPD") files. With it you can
-display printer options to users, mark option choices and check
-for conflicting choices, and output marked choices in PostScript
-output.

+
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 display printer options to users, mark option choices and check for
+conflicting choices, and output marked choices in PostScript output. The
+ppd_file_t structure contains all of
+the information in a PPD file.

 
-
General Usage

+
Loading a PPD File

 
-
The <cups/ppd.h> header file must be included
-to use the ppd functions.

+
The ppdOpenFile function "opens" a
+PPD file and loads it into memory. For example, the following code opens the
+current printer's PPD file in a CUPS filter:

 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+
+#include <cups/ppd.h>
 
-
-gcc -o myprogram myprogram.c -lcups
+ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
 

 
-
Compatibility

+
The return value is a pointer to a new
+ppd_file_t structure or NULL
+if the PPD file does not exist or cannot be loaded. The
+ppdClose function frees the memory used
+by the structure:

 
-
Unless otherwise specified, the PPD API functions require CUPS
-1.1 or higher.

+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdClose(ppd);
+

+
+
Options and Groups

+
+
PPD files support multiple options, which are stored in arrays of
+ppd_option_t and
+ppd_choice_t structures.

+
+
Each option in turn is associated with a group stored in a
+ppd_group_t structure. Groups can be
+specified in the PPD file; if an option is not associated with a group
+then it is put in an automatically-generated "General" group. Groups can also
+have sub-groups, however CUPS currently ignores sub-groups because of past
+abuses of this functionality.

+
+
Options are selected by marking them using one of three functions. The
+first is ppdMarkDefaults which
+selects all of the default options in the PPD file:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdMarkDefaults(ppd);
+

+
+
The second is ppdMarkOption
+which selects a single option choice in the PPD file. For example, the following
+code selects the manual feed media source:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdMarkOption(ppd, "InputSlot", "ManualFeed");
+

+
+
The last function is
+cupsMarkOptions which selects
+multiple option choices in the PPD file from an array of CUPS options, mapping
+IPP attributes like "media" and "sides" to their corresponding PPD options. You
+typically use this function in a print filter with
+cupsParseOptions and
+ppdMarkDefaults to select all of
+the option choices needed for the job, for example:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
+cups_option_t *options = NULL;
+int num_options = cupsParseOptions(argv[5], 0, &options);
+
+ppdMarkDefaults(ppd);
+cupsMarkOptions(ppd, num_options, options);
+

+
+
Constraints

+
+
PPD files support specification of conflict conditions, called
+constraints, between different options. Constraints are stored in an array of
+ppd_const_t structures which specify
+the options and choices that conflict with each other. The
+ppdConflicts function tells you
+how many of the selected options are incompatible.

+
+
Page Sizes

+
+
Page sizes are special options which have physical dimensions and margins
+associated with them. The size information is stored in
+ppd_size_t structures and is available
+by looking up the named size with the
+ppdPageSize function. The page size and
+margins are returned in units called points; there are 72 points per inch. If
+you pass NULL for the size, the currently selected size is
+returned:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+ppd_size_t *size = ppdPageSize(ppd, NULL);
+

+
+
Besides the standard page sizes listed in a PPD file, some printers
+support variable or custom page sizes. Custom page sizes are supported if the
+variables_sizes member of the
+ppd_file_t structure is non-zero.
+The custom_min, custom_max, and
+custom_margins members of the
+ppd_file_t structure define the limits
+of the printable area. To get the resulting media size, use a page size string
+of the form "Custom.widthxlength", where "width" and "length" are
+in points. Custom page size names can also be specified in inches
+("Custom.widthxheightin"), centimeters
+("Custom.widthxheightcm"), or millimeters
+("Custom.widthxheightmm"):

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+/* Get an 576x720 point custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.576x720");
+
+/* Get an 8x10 inch custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.8x10in");
+
+/* Get a 100x200 millimeter custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.100x200mm");
+
+/* Get a 12.7x34.5 centimeter custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.12.7x34.5cm");
+

+
+
Attributes

+
+
Every PPD file is composed of one or more attributes. Most of these
+attributes are used to define groups, options, choices, and page sizes,
+however several informations attributes are available which you may need
+to access in your program or filter. Attributes normally look like one of
+the following examples in a PPD file:

+
+
+*name: "value"
+*name spec: "value"
+*name spec/text: "value"
+

+
+
The ppdFindAttr and
+ppdFindNextAttr functions find the
+first and next instances, respectively, of the named attribute with the given
+"spec" string and return a ppd_attr_t
+structure. If you provide a NULL specifier string, all attributes with the
+given name will be returned. For example, the following code lists all of the
+Product attributes in a PPD file:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+ppd_attr_t *attr;
+
+for (attr = ppdFindAttr(ppd, "Product", NULL);
+     attr != NULL;
+     attr = ppdFindNextAttr(ppd, "Product", NULL))
+  puts(attr->value);
+

diff --git a/cups/array.c b/cups/array.c
index 5728d51e4..df1ae2e54 100644
--- a/cups/array.c
+++ b/cups/array.c
@@ -3,7 +3,7 @@
  *
  *   Sorted array routines for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -101,6 +101,8 @@ static int	cups_array_find(cups_array_t *a, void *e, int prev, int *rdiff);
  * When adding an element to a sorted array, non-unique elements are
  * appended at the end of the run.  For unsorted arrays, the element
  * is inserted at the end of the array.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 1 on success, 0 on failure */
@@ -129,6 +131,8 @@ cupsArrayAdd(cups_array_t *a,		/* I - Array */
 
 /*
  * 'cupsArrayClear()' - Clear the array.
+ *
+ * @since CUPS 1.2@
  */
 
 void
@@ -156,6 +160,8 @@ cupsArrayClear(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayCount()' - Get the number of elements in the array.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - Number of elements */
@@ -178,6 +184,8 @@ cupsArrayCount(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayCurrent()' - Return the current element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
 void *					/* O - Element */
@@ -203,6 +211,8 @@ cupsArrayCurrent(cups_array_t *a)	/* I - Array */
 
 /*
  * 'cupsArrayDelete()' - Free all memory used by the array.
+ *
+ * @since CUPS 1.2@
  */
 
 void
@@ -232,6 +242,8 @@ cupsArrayDelete(cups_array_t *a)	/* I - Array */
 
 /*
  * 'cupsArrayDup()' - Duplicate the array.
+ *
+ * @since CUPS 1.2@
  */
 
 cups_array_t *				/* O - Duplicate array */
@@ -296,9 +308,11 @@ cupsArrayDup(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayFind()' - Find an element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - Element found or NULL */
+void *					/* O - Element found or @code NULL@ */
 cupsArrayFind(cups_array_t *a,		/* I - Array */
               void         *e)		/* I - Element */
 {
@@ -389,9 +403,11 @@ cupsArrayFind(cups_array_t *a,		/* I - Array */
 
 /*
  * 'cupsArrayFirst()' - Get the first element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - First element or NULL */
+void *					/* O - First element or @code NULL@ */
 cupsArrayFirst(cups_array_t *a)		/* I - Array */
 {
  /*
@@ -445,9 +461,11 @@ cupsArrayGetInsert(cups_array_t *a)	/* I - Array */
 
 /*
  * 'cupsArrayIndex()' - Get the N-th element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - N-th element or NULL */
+void *					/* O - N-th element or @code NULL@ */
 cupsArrayIndex(cups_array_t *a,		/* I - Array */
                int          n)		/* I - Index into array, starting at 0 */
 {
@@ -466,6 +484,8 @@ cupsArrayIndex(cups_array_t *a,		/* I - Array */
  * When inserting an element in a sorted array, non-unique elements are
  * inserted at the beginning of the run.  For unsorted arrays, the element
  * is inserted at the beginning of the array.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on failure, 1 on success */
@@ -494,9 +514,11 @@ cupsArrayInsert(cups_array_t *a,	/* I - Array */
 
 /*
  * 'cupsArrayLast()' - Get the last element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - Last element or NULL */
+void *					/* O - Last element or @code NULL@ */
 cupsArrayLast(cups_array_t *a)		/* I - Array */
 {
  /*
@@ -518,6 +540,8 @@ cupsArrayLast(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayNew()' - Create a new array.
+ *
+ * @since CUPS 1.2@
  */
 
 cups_array_t *				/* O - Array */
@@ -579,9 +603,11 @@ cupsArrayNew2(cups_array_func_t  f,	/* I - Comparison function */
 
 /*
  * 'cupsArrayNext()' - Get the next element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - Next element or NULL */
+void *					/* O - Next element or @code NULL@ */
 cupsArrayNext(cups_array_t *a)		/* I - Array */
 {
  /*
@@ -604,9 +630,11 @@ cupsArrayNext(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayPrev()' - Get the previous element in the array.
+ *
+ * @since CUPS 1.2@
  */
 
-void *					/* O - Previous element or NULL */
+void *					/* O - Previous element or @code NULL@ */
 cupsArrayPrev(cups_array_t *a)		/* I - Array */
 {
  /*
@@ -629,6 +657,8 @@ cupsArrayPrev(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayRemove()' - Remove an element from the array.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 1 on success, 0 on failure */
@@ -689,6 +719,8 @@ cupsArrayRemove(cups_array_t *a,	/* I - Array */
 
 /*
  * 'cupsArrayRestore()' - Reset the current element to the last cupsArraySave.
+ *
+ * @since CUPS 1.2@
  */
 
 void *					/* O - New current element */
@@ -714,6 +746,8 @@ cupsArrayRestore(cups_array_t *a)	/* I - Array */
  * 'cupsArraySave()' - Mark the current element for a later cupsArrayRestore.
  *
  * The save/restore stack is guaranteed to be at least 32 elements deep.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 1 on success, 0 on failure */
@@ -734,6 +768,8 @@ cupsArraySave(cups_array_t *a)		/* I - Array */
 
 /*
  * 'cupsArrayUserData()' - Return the user data for an array.
+ *
+ * @since CUPS 1.2@
  */
 
 void *					/* O - User data */
@@ -748,6 +784,8 @@ cupsArrayUserData(cups_array_t *a)	/* I - Array */
 
 /*
  * 'cups_array_add()' - Insert or append an element to the array...
+ *
+ * @since CUPS 1.2@
  */
 
 static int				/* O - 1 on success, 0 on failure */
@@ -916,6 +954,8 @@ cups_array_add(cups_array_t *a,		/* I - Array */
 
 /*
  * 'cups_array_find()' - Find an element in the array...
+ *
+ * @since CUPS 1.2@
  */
 
 static int				/* O - Index of match */
diff --git a/cups/array.h b/cups/array.h
index 74785a4c6..ae5752195 100644
--- a/cups/array.h
+++ b/cups/array.h
@@ -3,7 +3,7 @@
  *
  *   Sorted array definitions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
diff --git a/cups/attr.c b/cups/attr.c
index d65b3ef45..83e6ba887 100644
--- a/cups/attr.c
+++ b/cups/attr.c
@@ -4,7 +4,7 @@
  *   PPD model-specific attribute routines for the Common UNIX Printing System
  *   (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -15,8 +15,8 @@
  *
  * Contents:
  *
- *   ppdFindAttr()     - Find the first matching attribute...
- *   ppdFindNextAttr() - Find the next matching attribute...
+ *   ppdFindAttr()     - Find the first matching attribute.
+ *   ppdFindNextAttr() - Find the next matching attribute.
  */
 
 /*
@@ -30,15 +30,15 @@
 
 
 /*
- * 'ppdFindAttr()' - Find the first matching attribute...
+ * 'ppdFindAttr()' - Find the first matching attribute.
  *
  * @since CUPS 1.1.19@
  */
 
-ppd_attr_t *				/* O - Attribute or NULL if not found */
+ppd_attr_t *				/* O - Attribute or @code NULL@ if not found */
 ppdFindAttr(ppd_file_t *ppd,		/* I - PPD file data */
             const char *name,		/* I - Attribute name */
-            const char *spec)		/* I - Specifier string or NULL */
+            const char *spec)		/* I - Specifier string or @code NULL@ */
 {
   ppd_attr_t	key,			/* Search key */
 		*attr;			/* Current attribute */
@@ -102,15 +102,15 @@ ppdFindAttr(ppd_file_t *ppd,		/* I - PPD file data */
 
 
 /*
- * 'ppdFindNextAttr()' - Find the next matching attribute...
+ * 'ppdFindNextAttr()' - Find the next matching attribute.
  *
  * @since CUPS 1.1.19@
  */
 
-ppd_attr_t *				/* O - Attribute or NULL if not found */
+ppd_attr_t *				/* O - Attribute or @code NULL@ if not found */
 ppdFindNextAttr(ppd_file_t *ppd,	/* I - PPD file data */
                 const char *name,	/* I - Attribute name */
-		const char *spec)	/* I - Specifier string or NULL */
+		const char *spec)	/* I - Specifier string or @code NULL@ */
 {
   ppd_attr_t	*attr;			/* Current attribute */
 
diff --git a/cups/auth.c b/cups/auth.c
index dd2d22c51..adc2436c9 100644
--- a/cups/auth.c
+++ b/cups/auth.c
@@ -76,7 +76,7 @@ static int	cups_local_auth(http_t *http);
 /*
  * 'cupsDoAuthentication()' - Authenticate a request.
  *
- * This function should be called in response to a HTTP_UNAUTHORIZED
+ * This function should be called in response to a @code HTTP_UNAUTHORIZED@
  * status, prior to resubmitting your request.
  *
  * @since CUPS 1.1.20@
@@ -84,15 +84,14 @@ static int	cups_local_auth(http_t *http);
 
 int					/* O - 0 on success, -1 on error */
 cupsDoAuthentication(http_t     *http,	/* I - HTTP connection to server */
-                     const char *method,/* I - Request method (GET, POST, PUT) */
+                     const char *method,/* I - Request method ("GET", "POST", "PUT") */
 		     const char *resource)
 					/* I - Resource path */
 {
   const char	*password;		/* Password string */
   char		prompt[1024],		/* Prompt for user */
 		realm[HTTP_MAX_VALUE],	/* realm="xyz" string */
-		nonce[HTTP_MAX_VALUE],	/* nonce="xyz" string */
-		encode[4096];		/* Encoded username:password */
+		nonce[HTTP_MAX_VALUE];	/* nonce="xyz" string */
   int		localauth;		/* Local authentication result */
   _cups_globals_t *cg;			/* Global data */
 
@@ -301,14 +300,40 @@ cupsDoAuthentication(http_t     *http,	/* I - HTTP connection to server */
     if (major_status == GSS_S_CONTINUE_NEEDED)
       DEBUG_gss_printf(major_status, minor_status, "Continuation needed!");
 
-    if (output_token.length)
+    if (output_token.length > 0 && output_token.length <= 65536)
     {
-      httpEncode64_2(encode, sizeof(encode), output_token.value,
+     /*
+      * Allocate the authorization string since Windows KDCs can have
+      * arbitrarily large credentials...
+      */
+
+      int authsize = 10 +				/* "Negotiate " */
+                     output_token.length * 4 / 3 + 1 +	/* Base64 */
+		     1;					/* nul */
+
+      httpSetAuthString(http, NULL, NULL);
+
+      if ((http->authstring = malloc(authsize)) == NULL)
+      {
+        http->authstring = http->_authstring;
+	authsize         = sizeof(http->_authstring);
+      }
+
+      strcpy(http->authstring, "Negotiate ");
+      httpEncode64_2(http->authstring + 10, authsize - 10, output_token.value,
 		     output_token.length);
-      httpSetAuthString(http, "Negotiate", encode);
  
       major_status = gss_release_buffer(&minor_status, &output_token);
     }
+    else
+    {
+      DEBUG_printf(("cupsDoAuthentication: Kerberos credentials too large - "
+                    "%d bytes!\n", output_token.length));
+
+      major_status = gss_release_buffer(&minor_status, &output_token);
+
+      return (-1);
+    }
 #endif /* HAVE_GSSAPI */
   }
   else if (strncmp(http->fields[HTTP_FIELD_WWW_AUTHENTICATE], "Digest", 6))
@@ -317,6 +342,9 @@ cupsDoAuthentication(http_t     *http,	/* I - HTTP connection to server */
     * Basic authentication...
     */
 
+    char	encode[256];		/* Base64 buffer */
+
+
     httpEncode64_2(encode, sizeof(encode), http->userpass,
                    (int)strlen(http->userpass));
     httpSetAuthString(http, "Basic", encode);
@@ -327,7 +355,8 @@ cupsDoAuthentication(http_t     *http,	/* I - HTTP connection to server */
     * Digest authentication...
     */
 
-    char digest[1024];			/* Digest auth data */
+    char	encode[33],		/* MD5 buffer */
+		digest[1024];		/* Digest auth data */
 
 
     httpGetSubField(http, HTTP_FIELD_WWW_AUTHENTICATE, "realm", realm);
diff --git a/cups/backend.h b/cups/backend.h
index 5057f086f..67d5e8115 100644
--- a/cups/backend.h
+++ b/cups/backend.h
@@ -3,7 +3,7 @@
  *
  *   Backend definitions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2005 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -30,7 +30,7 @@
  * Constants...
  */
 
-typedef enum cups_backend_e		/**** Backend exit codes ****/
+enum cups_backend_e			/**** Backend exit codes ****/
 {
   CUPS_BACKEND_OK = 0,			/* Job completed successfully */
   CUPS_BACKEND_FAILED = 1,		/* Job failed, use error-policy */
@@ -38,7 +38,9 @@ typedef enum cups_backend_e		/**** Backend exit codes ****/
   CUPS_BACKEND_HOLD = 3,		/* Job failed, hold job */
   CUPS_BACKEND_STOP = 4,		/* Job failed, stop queue */
   CUPS_BACKEND_CANCEL = 5		/* Job failed, cancel job */
-} cups_backend_t;
+};
+typedef enum cups_backend_e cups_backend_t;
+					/**** Backend exit codes ****/
 
 
 /*
diff --git a/cups/cups.h b/cups/cups.h
index 187071682..fd8cc3aa3 100644
--- a/cups/cups.h
+++ b/cups/cups.h
@@ -3,7 +3,7 @@
  *
  *   API definitions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -71,16 +71,21 @@ extern "C" {
 #  define CUPS_FORMAT_RAW	"application/vnd.cups-raw"
 #  define CUPS_FORMAT_TEXT	"text/plain"
 #  define CUPS_HTTP_DEFAULT	(http_t *)0
+#  define CUPS_JOBID_ALL	-1
+#  define CUPS_JOBID_CURRENT	0
 #  define CUPS_LENGTH_VARIABLE	(ssize_t)0
+#  define CUPS_WHICHJOBS_ALL	-1
+#  define CUPS_WHICHJOBS_ACTIVE	0
+#  define CUPS_WHICHJOBS_COMPLETED 1
 
 
 /*
  * Types and structures...
  */
 
-typedef unsigned cups_ptype_t;		/**** Printer Type/Capability Bits ****/
-enum cups_ptype_e			/* Not a typedef'd enum so we can OR */
-{
+typedef unsigned cups_ptype_t;		/**** Printer type/capability bits ****/
+enum cups_ptype_e			/**** Printer type/capability bit constants ****/
+{					/* Not a typedef'd enum so we can OR */
   CUPS_PRINTER_LOCAL = 0x0000,		/* Local printer or class */
   CUPS_PRINTER_CLASS = 0x0001,		/* Printer class */
   CUPS_PRINTER_REMOTE = 0x0002,		/* Remote printer or class */
@@ -107,7 +112,7 @@ enum cups_ptype_e			/* Not a typedef'd enum so we can OR */
   CUPS_PRINTER_AUTHENTICATED = 0x400000,/* Printer requires authentication @since CUPS 1.2@ */
   CUPS_PRINTER_COMMANDS = 0x800000,	/* Printer supports maintenance commands @since CUPS 1.2@ */
   CUPS_PRINTER_DISCOVERED = 0x1000000,	/* Printer was automatically discovered and added @since CUPS 1.3@ */
-  CUPS_PRINTER_OPTIONS = 0x6fffc	/* ~(CLASS | REMOTE | IMPLICIT | DEFAULT | FAX | REJECTING | DELETE | NOT_SHARED | AUTHENTICATED | COMMANDS | DISCOVERED) */
+  CUPS_PRINTER_OPTIONS = 0x6fffc	/* ~(CLASS | REMOTE | IMPLICIT | DEFAULT | FAX | REJECTING | DELETE | NOT_SHARED | AUTHENTICATED | COMMANDS | DISCOVERED) @private@ */
 };
 
 typedef const char *(*cups_password_cb_t)(const char *);
@@ -158,8 +163,8 @@ extern http_encryption_t cupsEncryption(void);
 extern void		cupsFreeJobs(int num_jobs, cups_job_t *jobs);
 extern int		cupsGetClasses(char ***classes) _CUPS_DEPRECATED;
 extern const char	*cupsGetDefault(void);
-extern int		cupsGetJobs(cups_job_t **jobs, const char *dest,
-			            int myjobs, int completed);
+extern int		cupsGetJobs(cups_job_t **jobs, const char *name,
+			            int myjobs, int whichjobs);
 extern const char	*cupsGetPPD(const char *name);
 extern int		cupsGetPrinters(char ***printers) _CUPS_DEPRECATED;
 extern ipp_status_t	cupsLastError(void);
@@ -215,7 +220,7 @@ extern const char	*cupsGetDefault2(http_t *http) _CUPS_API_1_1_21;
 extern int		cupsGetDests2(http_t *http, cups_dest_t **dests) _CUPS_API_1_1_21;
 extern int		cupsGetJobs2(http_t *http, cups_job_t **jobs,
 			             const char *name, int myjobs,
-				     int completed) _CUPS_API_1_1_21;
+				     int whichjobs) _CUPS_API_1_1_21;
 extern const char	*cupsGetPPD2(http_t *http, const char *name) _CUPS_API_1_1_21;
 extern int		cupsPrintFile2(http_t *http, const char *name,
 			               const char *filename,
@@ -257,7 +262,8 @@ extern void		cupsSetDefaultDest(const char *name,
 					   cups_dest_t *dests) _CUPS_API_1_3;
 
 /**** New in CUPS 1.4 ****/
-extern ipp_status_t	cupsCancelJob2(http_t *http, int job_id, int purge);
+extern ipp_status_t	cupsCancelJob2(http_t *http, const char *name,
+			               int job_id, int purge) _CUPS_API_1_4;
 extern int		cupsCreateJob(http_t *http, const char *name,
 				      const char *title, int num_options,
 				      cups_option_t *options) _CUPS_API_1_4;
diff --git a/cups/dest.c b/cups/dest.c
index 64b2ca431..6f61181d6 100644
--- a/cups/dest.c
+++ b/cups/dest.c
@@ -101,13 +101,13 @@ static int	cups_get_sdests(http_t *http, ipp_op_t op, const char *name,
  * returned unchanged.  Adding a new instance of a destination creates
  * a copy of that destination's options.
  *
- * Use the cupsSaveDests() function to save the updated list of
+ * Use the @link cupsSaveDests@ function to save the updated list of
  * destinations to the user's lpoptions file.
  */
 
 int					/* O  - New number of destinations */
 cupsAddDest(const char  *name,		/* I  - Destination name */
-            const char	*instance,	/* I  - Instance name or NULL for none/primary */
+            const char	*instance,	/* I  - Instance name or @code NULL@ for none/primary */
             int         num_dests,	/* I  - Number of destinations */
             cups_dest_t **dests)	/* IO - Destinations */
 {
@@ -218,13 +218,13 @@ cupsFreeDests(int         num_dests,	/* I - Number of destinations */
 /*
  * 'cupsGetDest()' - Get the named destination from the list.
  *
- * Use the cupsGetDests() or cupsGetDests2() functions to get a
+ * Use the @link cupsGetDests@ or @link cupsGetDests2@ functions to get a
  * list of supported destinations for the current user.
  */
 
-cups_dest_t *				/* O - Destination pointer or NULL */
-cupsGetDest(const char  *name,		/* I - Destination name or NULL for the default destination */
-            const char	*instance,	/* I - Instance name or NULL */
+cups_dest_t *				/* O - Destination pointer or @code NULL@ */
+cupsGetDest(const char  *name,		/* I - Destination name or @code NULL@ for the default destination */
+            const char	*instance,	/* I - Instance name or @code NULL@ */
             int         num_dests,	/* I - Number of destinations */
             cups_dest_t *dests)		/* I - Destinations */
 {
@@ -284,8 +284,8 @@ cupsGetDest(const char  *name,		/* I - Destination name or NULL for the default
  * printer-make-and-model, printer-state, printer-state-change-time,
  * printer-state-reasons, and printer-type attributes as options.
  *
- * Use the cupsFreeDests() function to free the destination list and
- * the cupsGetDest() function to find a particular destination.
+ * Use the @link cupsFreeDests@ function to free the destination list and
+ * the @link cupsGetDest@ function to find a particular destination.
  */
 
 int					/* O - Number of destinations */
@@ -303,14 +303,14 @@ cupsGetDests(cups_dest_t **dests)	/* O - Destinations */
  * printer-make-and-model, printer-state, printer-state-change-time,
  * printer-state-reasons, and printer-type attributes as options.
  *
- * Use the cupsFreeDests() function to free the destination list and
- * the cupsGetDest() function to find a particular destination.
+ * Use the @link cupsFreeDests@ function to free the destination list and
+ * the @link cupsGetDest@ function to find a particular destination.
  *
  * @since CUPS 1.1.21@
  */
 
 int					/* O - Number of destinations */
-cupsGetDests2(http_t      *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetDests2(http_t      *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
               cups_dest_t **dests)	/* O - Destinations */
 {
   int		i;			/* Looping var */
@@ -477,26 +477,27 @@ cupsGetDests2(http_t      *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
  * 'cupsGetNamedDest()' - Get options for the named destination.
  *
  * This function is optimized for retrieving a single destination and should
- * be used instead of cupsGetDests() and cupsGetDest() when you either know
- * the name of the destination or want to print to the default destination.
- * If NULL is returned, the destination does not exist or there is no default
- * destination.
+ * be used instead of @link cupsGetDests@ and @link cupsGetDest@ when you either
+ * know the name of the destination or want to print to the default destination.
+ * If @code NULL@ is returned, the destination does not exist or there is no
+ * default destination.
  *
- * If "http" is CUPS_HTTP_DEFAULT, the connection to the default print server
- * will be used.
+ * If "http" is @code CUPS_HTTP_DEFAULT@, the connection to the default print
+ * server will be used.
  *
- * If "name" is NULL, the default printer for the current user will be returned.
+ * If "name" is @code NULL@, the default printer for the current user will be
+ * returned.
  *
- * The returned destination must be freed using cupsFreeDests() with a
- * "num_dests" of 1.
+ * The returned destination must be freed using @link cupsFreeDests@ with a
+ * "num_dests" value of 1.
  *
  * @since CUPS 1.4@
  */
 
-cups_dest_t *				/* O - Destination or NULL */
-cupsGetNamedDest(http_t     *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
-                 const char *name,	/* I - Destination name or NULL */
-                 const char *instance)	/* I - Instance name or NULL */
+cups_dest_t *				/* O - Destination or @code NULL@ */
+cupsGetNamedDest(http_t     *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
+                 const char *name,	/* I - Destination name or @code NULL@ */
+                 const char *instance)	/* I - Instance name or @code NULL@ */
 {
   cups_dest_t	*dest;			/* Destination */
   char		filename[1024],		/* Path to lpoptions */
@@ -595,15 +596,15 @@ cupsGetNamedDest(http_t     *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT *
  *
  * Removing a destination/instance does not delete the class or printer
  * queue, merely the lpoptions for that destination/instance.  Use the
- * cupsSetDests() or cupsSetDests2() functions to save the new options
- * for the user.
+ * @link cupsSetDests@ or @link cupsSetDests2@ functions to save the new
+ * options for the user.
  *
  * @since CUPS 1.3@
  */
 
 int					/* O  - New number of destinations */
 cupsRemoveDest(const char  *name,	/* I  - Destination name */
-               const char  *instance,	/* I  - Instance name or NULL */
+               const char  *instance,	/* I  - Instance name or @code NULL@ */
 	       int         num_dests,	/* I  - Number of destinations */
 	       cups_dest_t **dests)	/* IO - Destinations */
 {
@@ -650,7 +651,7 @@ cupsRemoveDest(const char  *name,	/* I  - Destination name */
 void
 cupsSetDefaultDest(
     const char  *name,			/* I - Destination name */
-    const char  *instance,		/* I - Instance name or NULL */
+    const char  *instance,		/* I - Instance name or @code NULL@ */
     int         num_dests,		/* I - Number of destinations */
     cups_dest_t *dests)			/* I - Destinations */
 {
@@ -703,7 +704,7 @@ cupsSetDests(int         num_dests,	/* I - Number of destinations */
  */
 
 int					/* O - 0 on success, -1 on error */
-cupsSetDests2(http_t      *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsSetDests2(http_t      *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
               int         num_dests,	/* I - Number of destinations */
               cups_dest_t *dests)	/* I - Destinations */
 {
diff --git a/cups/dir.c b/cups/dir.c
index b3a689b70..1ef2046b7 100644
--- a/cups/dir.c
+++ b/cups/dir.c
@@ -5,7 +5,7 @@
  *
  *   This set of APIs abstracts enumeration of directory entries.
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2005 by Easy Software Products, all rights reserved.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -80,10 +80,12 @@ _cups_dir_time(FILETIME ft)		/* I - File time */
 
 /*
  * 'cupsDirClose()' - Close a directory.
+ *
+ * @since CUPS 1.2@
  */
 
 void
-cupsDirClose(cups_dir_t *dp)		/* I - Directory */
+cupsDirClose(cups_dir_t *dp)		/* I - Directory pointer */
 {
  /*
   * Range check input...
@@ -109,9 +111,11 @@ cupsDirClose(cups_dir_t *dp)		/* I - Directory */
 
 /*
  * 'cupsDirOpen()' - Open a directory.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_dir_t *				/* O - Directory */
+cups_dir_t *				/* O - Directory pointer or @code NULL@ if the directory could not be opened. */
 cupsDirOpen(const char *directory)	/* I - Directory name */
 {
   cups_dir_t	*dp;			/* Directory */
@@ -150,10 +154,12 @@ cupsDirOpen(const char *directory)	/* I - Directory name */
 
 /*
  * 'cupsDirRead()' - Read the next directory entry.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_dentry_t *			/* O - Directory entry */
-cupsDirRead(cups_dir_t *dp)		/* I - Directory */
+cups_dentry_t *				/* O - Directory entry or @code NULL@ if there are no more */
+cupsDirRead(cups_dir_t *dp)		/* I - Directory pointer */
 {
   WIN32_FIND_DATA	entry;		/* Directory entry data */
 
@@ -208,10 +214,12 @@ cupsDirRead(cups_dir_t *dp)		/* I - Directory */
 
 /*
  * 'cupsDirRewind()' - Rewind to the start of the directory.
+ *
+ * @since CUPS 1.2@
  */
 
 void
-cupsDirRewind(cups_dir_t *dp)		/* I - Directory */
+cupsDirRewind(cups_dir_t *dp)		/* I - Directory pointer */
 {
  /*
   * Range check input...
@@ -256,10 +264,12 @@ struct _cups_dir_s			/**** Directory data structure ****/
 
 /*
  * 'cupsDirClose()' - Close a directory.
+ *
+ * @since CUPS 1.2@
  */
 
 void
-cupsDirClose(cups_dir_t *dp)		/* I - Directory */
+cupsDirClose(cups_dir_t *dp)		/* I - Directory pointer */
 {
   DEBUG_printf(("cupsDirClose(dp=%p)\n", dp));
 
@@ -281,9 +291,11 @@ cupsDirClose(cups_dir_t *dp)		/* I - Directory */
 
 /*
  * 'cupsDirOpen()' - Open a directory.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_dir_t *				/* O - Directory */
+cups_dir_t *				/* O - Directory pointer or @code NULL@ if the directory could not be opened. */
 cupsDirOpen(const char *directory)	/* I - Directory name */
 {
   cups_dir_t	*dp;			/* Directory */
@@ -333,10 +345,12 @@ cupsDirOpen(const char *directory)	/* I - Directory name */
 
 /*
  * 'cupsDirRead()' - Read the next directory entry.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_dentry_t *				/* O - Directory entry */
-cupsDirRead(cups_dir_t *dp)		/* I - Directory */
+cups_dentry_t *				/* O - Directory entry or @code NULL@ when there are no more */
+cupsDirRead(cups_dir_t *dp)		/* I - Directory pointer */
 {
   struct dirent	*entry;			/* Pointer to entry */
   char		filename[1024];		/* Full filename */
@@ -428,10 +442,12 @@ cupsDirRead(cups_dir_t *dp)		/* I - Directory */
 
 /*
  * 'cupsDirRewind()' - Rewind to the start of the directory.
+ *
+ * @since CUPS 1.2@
  */
 
 void
-cupsDirRewind(cups_dir_t *dp)		/* I - Directory */
+cupsDirRewind(cups_dir_t *dp)		/* I - Directory pointer */
 {
   DEBUG_printf(("cupsDirRewind(dp=%p)\n", dp));
 
diff --git a/cups/emit.c b/cups/emit.c
index 5ac480f35..494b1d45e 100644
--- a/cups/emit.c
+++ b/cups/emit.c
@@ -68,6 +68,9 @@ static const char ppd_custom_code[] =
 /*
  * 'ppdCollect()' - Collect all marked options that reside in the specified
  *                  section.
+ *
+ * The choices array should be freed using @code free@ when you are
+ * finished with it.
  */
 
 int					/* O - Number of options marked */
@@ -83,6 +86,9 @@ ppdCollect(ppd_file_t    *ppd,		/* I - PPD file data */
  * 'ppdCollect2()' - Collect all marked options that reside in the
  *                   specified section and minimum order.
  *
+ * The choices array should be freed using @code free@ when you are
+ * finished with it.
+ *
  * @since CUPS 1.2@
  */
 
@@ -545,12 +551,12 @@ ppdEmitJCLEnd(ppd_file_t *ppd,		/* I - PPD file record */
  * returned string.
  *
  * The return string is allocated on the heap and should be freed using
- * free() when you are done with it.
+ * @code free@ when you are done with it.
  *
  * @since CUPS 1.2@
  */
 
-char *					/* O - String containing option code */
+char *					/* O - String containing option code or @code NULL@ if there is no option code */
 ppdEmitString(ppd_file_t    *ppd,	/* I - PPD file record */
               ppd_section_t section,	/* I - Section to write */
 	      float         min_order)	/* I - Lowest OrderDependency */
diff --git a/cups/encode.c b/cups/encode.c
index 9ac62b870..506b87f0f 100644
--- a/cups/encode.c
+++ b/cups/encode.c
@@ -43,98 +43,98 @@
 
 static const _ipp_option_t ipp_options[] =
 {
-  { "auth-info",		IPP_TAG_TEXT,		IPP_TAG_JOB },
-  { "auth-info-required",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
-  { "blackplot",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "blackplot-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "brightness",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "brightness-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "columns",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "columns-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "copies",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "copies-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "document-format",		IPP_TAG_MIMETYPE,	IPP_TAG_OPERATION },
-  { "document-format-default",	IPP_TAG_MIMETYPE,	IPP_TAG_PRINTER },
-  { "finishings",		IPP_TAG_ENUM,		IPP_TAG_JOB },
-  { "finishings-default",	IPP_TAG_ENUM,		IPP_TAG_PRINTER },
-  { "fitplot",			IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "fitplot-default",		IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "gamma",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "gamma-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "hue",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "hue-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "job-k-limit",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "job-page-limit",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "job-priority",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "job-quota-period",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "job-uuid",			IPP_TAG_URI,		IPP_TAG_JOB },
-  { "landscape",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "media",			IPP_TAG_KEYWORD,	IPP_TAG_JOB },
-  { "mirror",			IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "mirror-default",		IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "natural-scaling",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "natural-scaling-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "notify-charset",		IPP_TAG_CHARSET,	IPP_TAG_SUBSCRIPTION },
-  { "notify-events",		IPP_TAG_KEYWORD,	IPP_TAG_SUBSCRIPTION },
-  { "notify-events-default",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
-  { "notify-lease-duration",	IPP_TAG_INTEGER,	IPP_TAG_SUBSCRIPTION },
-  { "notify-lease-duration-default", IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "notify-natural-language",	IPP_TAG_LANGUAGE,	IPP_TAG_SUBSCRIPTION },
-  { "notify-pull-method",	IPP_TAG_KEYWORD,	IPP_TAG_SUBSCRIPTION },
-  { "notify-recipient-uri",	IPP_TAG_URI,		IPP_TAG_SUBSCRIPTION },
-  { "notify-time-interval",	IPP_TAG_INTEGER,	IPP_TAG_SUBSCRIPTION },
-  { "notify-user-data",		IPP_TAG_STRING,		IPP_TAG_SUBSCRIPTION },
-  { "number-up",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "number-up-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "orientation-requested",	IPP_TAG_ENUM,		IPP_TAG_JOB },
-  { "orientation-requested-default", IPP_TAG_ENUM,	IPP_TAG_PRINTER },
-  { "page-bottom",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "page-bottom-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "page-left",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "page-left-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "page-ranges",		IPP_TAG_RANGE,		IPP_TAG_JOB },
-  { "page-ranges-default",	IPP_TAG_RANGE,		IPP_TAG_PRINTER },
-  { "page-right",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "page-right-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "page-top",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "page-top-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "penwidth",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "penwidth-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "port-monitor",             IPP_TAG_NAME,           IPP_TAG_PRINTER },
-  { "ppi",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "ppi-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "prettyprint",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "prettyprint-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "print-quality",		IPP_TAG_ENUM,		IPP_TAG_JOB },
-  { "print-quality-default",	IPP_TAG_ENUM,		IPP_TAG_PRINTER },
-  { "printer-error-policy",	IPP_TAG_NAME,		IPP_TAG_PRINTER },
-  { "printer-info",		IPP_TAG_TEXT,		IPP_TAG_PRINTER },
-  { "printer-is-accepting-jobs",IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "printer-is-shared",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
-  { "printer-location",		IPP_TAG_TEXT,		IPP_TAG_PRINTER },
-  { "printer-make-and-model",	IPP_TAG_TEXT,		IPP_TAG_PRINTER },
-  { "printer-more-info",	IPP_TAG_URI,		IPP_TAG_PRINTER },
-  { "printer-op-policy",	IPP_TAG_NAME,		IPP_TAG_PRINTER },
-  { "printer-resolution",	IPP_TAG_RESOLUTION,	IPP_TAG_JOB },
-  { "printer-state",		IPP_TAG_ENUM,		IPP_TAG_PRINTER },
-  { "printer-state-change-time",IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "printer-state-reasons",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
-  { "printer-type",		IPP_TAG_ENUM,		IPP_TAG_PRINTER },
-  { "printer-uri",		IPP_TAG_URI,		IPP_TAG_OPERATION },
-  { "queued-job-count",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "raw",			IPP_TAG_MIMETYPE,	IPP_TAG_OPERATION },
-  { "requesting-user-name-allowed",	IPP_TAG_NAME,	IPP_TAG_PRINTER },
-  { "requesting-user-name-denied",	IPP_TAG_NAME,	IPP_TAG_PRINTER },
-  { "resolution",		IPP_TAG_RESOLUTION,	IPP_TAG_JOB },
-  { "resolution-default",	IPP_TAG_RESOLUTION,	IPP_TAG_PRINTER },
-  { "saturation",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "saturation-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "scaling",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
-  { "scaling-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
-  { "sides",			IPP_TAG_KEYWORD,	IPP_TAG_JOB },
-  { "sides-default",		IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
-  { "wrap",			IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
-  { "wrap-default",		IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER }
+  { 1, "auth-info",		IPP_TAG_TEXT,		IPP_TAG_JOB },
+  { 1, "auth-info-required",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
+  { 0, "blackplot",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 0, "blackplot-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "brightness",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "brightness-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "columns",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "columns-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "copies",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "copies-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "document-format",	IPP_TAG_MIMETYPE,	IPP_TAG_OPERATION },
+  { 0, "document-format-default", IPP_TAG_MIMETYPE,	IPP_TAG_PRINTER },
+  { 1, "finishings",		IPP_TAG_ENUM,		IPP_TAG_JOB },
+  { 1, "finishings-default",	IPP_TAG_ENUM,		IPP_TAG_PRINTER },
+  { 0, "fitplot",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 0, "fitplot-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "gamma",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "gamma-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "hue",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "hue-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "job-k-limit",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "job-page-limit",	IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "job-priority",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "job-quota-period",	IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "job-uuid",		IPP_TAG_URI,		IPP_TAG_JOB },
+  { 0, "landscape",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 1, "media",			IPP_TAG_KEYWORD,	IPP_TAG_JOB },
+  { 0, "mirror",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 0, "mirror-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "natural-scaling",	IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "natural-scaling-default", IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "notify-charset",	IPP_TAG_CHARSET,	IPP_TAG_SUBSCRIPTION },
+  { 1, "notify-events",		IPP_TAG_KEYWORD,	IPP_TAG_SUBSCRIPTION },
+  { 1, "notify-events-default",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
+  { 0, "notify-lease-duration",	IPP_TAG_INTEGER,	IPP_TAG_SUBSCRIPTION },
+  { 0, "notify-lease-duration-default", IPP_TAG_INTEGER, IPP_TAG_PRINTER },
+  { 0, "notify-natural-language", IPP_TAG_LANGUAGE,	IPP_TAG_SUBSCRIPTION },
+  { 0, "notify-pull-method",	IPP_TAG_KEYWORD,	IPP_TAG_SUBSCRIPTION },
+  { 0, "notify-recipient-uri",	IPP_TAG_URI,		IPP_TAG_SUBSCRIPTION },
+  { 0, "notify-time-interval",	IPP_TAG_INTEGER,	IPP_TAG_SUBSCRIPTION },
+  { 0, "notify-user-data",	IPP_TAG_STRING,		IPP_TAG_SUBSCRIPTION },
+  { 0, "number-up",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "number-up-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "orientation-requested",	IPP_TAG_ENUM,		IPP_TAG_JOB },
+  { 0, "orientation-requested-default", IPP_TAG_ENUM,	IPP_TAG_PRINTER },
+  { 0, "page-bottom",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "page-bottom-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "page-left",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "page-left-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 1, "page-ranges",		IPP_TAG_RANGE,		IPP_TAG_JOB },
+  { 1, "page-ranges-default",	IPP_TAG_RANGE,		IPP_TAG_PRINTER },
+  { 0, "page-right",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "page-right-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "page-top",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "page-top-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "penwidth",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "penwidth-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "port-monitor",		IPP_TAG_NAME,		IPP_TAG_PRINTER },
+  { 0, "ppi",			IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "ppi-default",		IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "prettyprint",		IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 0, "prettyprint-default",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "print-quality",		IPP_TAG_ENUM,		IPP_TAG_JOB },
+  { 0, "print-quality-default",	IPP_TAG_ENUM,		IPP_TAG_PRINTER },
+  { 0, "printer-error-policy",	IPP_TAG_NAME,		IPP_TAG_PRINTER },
+  { 0, "printer-info",		IPP_TAG_TEXT,		IPP_TAG_PRINTER },
+  { 0, "printer-is-accepting-jobs", IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "printer-is-shared",	IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER },
+  { 0, "printer-location",	IPP_TAG_TEXT,		IPP_TAG_PRINTER },
+  { 0, "printer-make-and-model", IPP_TAG_TEXT,		IPP_TAG_PRINTER },
+  { 0, "printer-more-info",	IPP_TAG_URI,		IPP_TAG_PRINTER },
+  { 0, "printer-op-policy",	IPP_TAG_NAME,		IPP_TAG_PRINTER },
+  { 0, "printer-resolution",	IPP_TAG_RESOLUTION,	IPP_TAG_JOB },
+  { 0, "printer-state",		IPP_TAG_ENUM,		IPP_TAG_PRINTER },
+  { 0, "printer-state-change-time", IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 1, "printer-state-reasons",	IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
+  { 0, "printer-type",		IPP_TAG_ENUM,		IPP_TAG_PRINTER },
+  { 0, "printer-uri",		IPP_TAG_URI,		IPP_TAG_OPERATION },
+  { 0, "queued-job-count",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "raw",			IPP_TAG_MIMETYPE,	IPP_TAG_OPERATION },
+  { 1, "requesting-user-name-allowed", IPP_TAG_NAME,	IPP_TAG_PRINTER },
+  { 1, "requesting-user-name-denied", IPP_TAG_NAME,	IPP_TAG_PRINTER },
+  { 0, "resolution",		IPP_TAG_RESOLUTION,	IPP_TAG_JOB },
+  { 0, "resolution-default",	IPP_TAG_RESOLUTION,	IPP_TAG_PRINTER },
+  { 0, "saturation",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "saturation-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "scaling",		IPP_TAG_INTEGER,	IPP_TAG_JOB },
+  { 0, "scaling-default",	IPP_TAG_INTEGER,	IPP_TAG_PRINTER },
+  { 0, "sides",			IPP_TAG_KEYWORD,	IPP_TAG_JOB },
+  { 0, "sides-default",		IPP_TAG_KEYWORD,	IPP_TAG_PRINTER },
+  { 0, "wrap",			IPP_TAG_BOOLEAN,	IPP_TAG_JOB },
+  { 0, "wrap-default",		IPP_TAG_BOOLEAN,	IPP_TAG_PRINTER }
 };
 
 
@@ -192,7 +192,8 @@ cupsEncodeOptions2(
   char		*s,			/* Pointer into option value */
 		*val,			/* Pointer to option value */
 		*copy,			/* Copy of option value */
-		*sep;			/* Option separator */
+		*sep,			/* Option separator */
+		quote;			/* Quote character */
   ipp_attribute_t *attr;		/* IPP attribute */
   ipp_tag_t	value_tag;		/* IPP value tag */
   cups_option_t	*option;		/* Current option */
@@ -284,41 +285,28 @@ cupsEncodeOptions2(
     * Count the number of values...
     */
 
-    for (count = 1, sep = option->value; *sep; sep ++)
+    if (match && match->multivalue)
     {
-      if (*sep == '\'')
+      for (count = 1, sep = option->value, quote = 0; *sep; sep ++)
       {
-       /*
-        * Skip quoted option value...
-	*/
-
-        sep ++;
-
-        while (*sep && *sep != '\'')
-	  sep ++;
-
-	if (!*sep)
-	  sep --;
-      }
-      else if (*sep == '\"')
-      {
-       /*
-        * Skip quoted option value...
-	*/
-
-        sep ++;
+	if (*sep == quote)
+	  quote = 0;
+	else if (!quote && (*sep == '\'' || *sep == '\"'))
+	{
+	 /*
+	  * Skip quoted option value...
+	  */
 
-        while (*sep && *sep != '\"')
+	  quote = *sep++;
+	}
+	else if (*sep == ',' && !quote)
+	  count ++;
+	else if (*sep == '\\' && sep[1])
 	  sep ++;
-
-	if (!*sep)
-	  sep --;
       }
-      else if (*sep == ',')
-        count ++;
-      else if (*sep == '\\' && sep[1])
-        sep ++;
     }
+    else
+      count = 1;
 
     DEBUG_printf(("cupsEncodeOptions2: option = \'%s\', count = %d\n",
                   option->name, count));
@@ -390,50 +378,47 @@ cupsEncodeOptions2(
     * Scan the value string for values...
     */
 
-    for (j = 0; j < count; val = sep, j ++)
+    for (j = 0, sep = val; j < count; val = sep, j ++)
     {
      /*
       * Find the end of this value and mark it if needed...
       */
 
-      for (sep = val; *sep; sep ++)
+      if (count > 1)
       {
-	if (*sep == '\'')
+	for (quote = 0; *sep; sep ++)
 	{
-	 /*
-	  * Skip quoted option value...
-	  */
-
-	  sep ++;
-
-	  while (*sep && *sep != '\'')
-	    sep ++;
+	  if (*sep == quote)
+	  {
+	   /*
+	    * Finish quoted value...
+	    */
 
-	  if (!*sep)
-	    sep --;
-	}
-	else if (*sep == '\"')
-	{
-	 /*
-	  * Skip quoted option value...
-	  */
+	    quote = 0;
+	  }
+	  else if (!quote && (*sep == '\'' || *sep == '\"'))
+	  {
+	   /*
+	    * Handle quoted option value...
+	    */
 
-	  sep ++;
+	    quote = *sep;
+	  }
+	  else if (*sep == ',' && count > 1)
+	    break;
+	  else if (*sep == '\\' && sep[1])
+	  {
+	   /*
+	    * Skip quoted character...
+	    */
 
-	  while (*sep && *sep != '\"')
 	    sep ++;
-
-	  if (!*sep)
-	    sep --;
+	  }
 	}
-	else if (*sep == ',')
-	  break;
-	else if (*sep == '\\' && sep[1])
-	  sep ++;
-      }
 
-      if (*sep == ',')
-	*sep++ = '\0';
+	if (*sep == ',')
+	  *sep++ = '\0';
+      }
 
      /*
       * Copy the option value(s) over as needed by the type...
@@ -447,7 +432,7 @@ cupsEncodeOptions2(
 	    * Integer/enumeration value...
 	    */
 
-            attr->values[j].integer = strtol(val, &s, 0);
+            attr->values[j].integer = strtol(val, &s, 10);
 
             DEBUG_printf(("cupsEncodeOptions2: Added integer option value %d...\n",
 	                  attr->values[j].integer));
@@ -489,12 +474,12 @@ cupsEncodeOptions2(
 	      s = val;
 	    }
 	    else
-	      attr->values[j].range.lower = strtol(val, &s, 0);
+	      attr->values[j].range.lower = strtol(val, &s, 10);
 
 	    if (*s == '-')
 	    {
 	      if (s[1])
-		attr->values[j].range.upper = strtol(s + 1, NULL, 0);
+		attr->values[j].range.upper = strtol(s + 1, NULL, 10);
 	      else
 		attr->values[j].range.upper = 2147483647;
             }
@@ -511,10 +496,10 @@ cupsEncodeOptions2(
 	    * Resolution...
 	    */
 
-	    attr->values[j].resolution.xres = strtol(val, &s, 0);
+	    attr->values[j].resolution.xres = strtol(val, &s, 10);
 
 	    if (*s == 'x')
-	      attr->values[j].resolution.yres = strtol(s + 1, &s, 0);
+	      attr->values[j].resolution.yres = strtol(s + 1, &s, 10);
 	    else
 	      attr->values[j].resolution.yres = attr->values[j].resolution.xres;
 
@@ -533,7 +518,7 @@ cupsEncodeOptions2(
 	    */
 
             attr->values[j].unknown.length = (int)strlen(val);
-	    attr->values[j].unknown.data   = _cupsStrAlloc(val);
+	    attr->values[j].unknown.data   = strdup(val);
 
             DEBUG_printf(("cupsEncodeOptions2: Added octet-string value \"%s\"...\n",
 	                  attr->values[j].unknown.data));
diff --git a/cups/file.c b/cups/file.c
index e7c7b0b15..9f92727a2 100644
--- a/cups/file.c
+++ b/cups/file.c
@@ -8,7 +8,7 @@
  *   our own file functions allows us to provide transparent support of
  *   gzip'd print files, PPD files, etc.
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products, all rights reserved.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -26,8 +26,8 @@
  *   cupsFileFlush()       - Flush pending output.
  *   cupsFileGetChar()     - Get a single character from a file.
  *   cupsFileGetConf()     - Get a line from a configuration file...
- *   cupsFileGetLine()     - Get a CR and/or LF-terminated line that may
- *                           contain binary data.
+ *   cupsFileGetLine()     - Get a CR and/or LF-terminated line that may contain
+ *                           binary data.
  *   cupsFileGets()        - Get a CR and/or LF-terminated line.
  *   cupsFileLock()        - Temporarily lock access to a file.
  *   cupsFileNumber()      - Return the file descriptor associated with a CUPS
@@ -39,7 +39,8 @@
  *   cupsFilePutChar()     - Write a character.
  *   cupsFilePuts()        - Write a string.
  *   cupsFileRead()        - Read from a file.
- *   cupsFileRewind()      - Rewind a file.
+ *   cupsFileRewind()      - Set the current file position to the beginning of
+ *                           the file.
  *   cupsFileSeek()        - Seek in a file.
  *   cupsFileStderr()      - Return a CUPS file associated with stderr.
  *   cupsFileStdin()       - Return a CUPS file associated with stdin.
@@ -134,6 +135,8 @@ static ssize_t	cups_write(cups_file_t *fp, const char *buf, size_t bytes);
 
 /*
  * 'cupsFileClose()' - Close a CUPS file.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on success, -1 on error */
@@ -261,9 +264,11 @@ cupsFileClose(cups_file_t *fp)		/* I - CUPS file */
 
 /*
  * 'cupsFileCompression()' - Return whether a file is compressed.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - CUPS_FILE_NONE or CUPS_FILE_GZIP */
+int					/* O - @code CUPS_FILE_NONE@ or @code CUPS_FILE_GZIP@ */
 cupsFileCompression(cups_file_t *fp)	/* I - CUPS file */
 {
   return (fp ? fp->compressed : CUPS_FILE_NONE);
@@ -272,9 +277,11 @@ cupsFileCompression(cups_file_t *fp)	/* I - CUPS file */
 
 /*
  * 'cupsFileEOF()' - Return the end-of-file status.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - 1 on EOF, 0 otherwise */
+int					/* O - 1 on end of file, 0 otherwise */
 cupsFileEOF(cups_file_t *fp)		/* I - CUPS file */
 {
   return (fp ? fp->eof : 1);
@@ -287,11 +294,13 @@ cupsFileEOF(cups_file_t *fp)		/* I - CUPS file */
  * This function allows the paths in the path string to be separated by
  * colons (UNIX standard) or semicolons (Windows standard) and stores the
  * result in the buffer supplied.  If the file cannot be found in any of
- * the supplied paths, NULL is returned. A NULL path only matches the
- * current directory.
+ * the supplied paths, @code NULL@ is returned. A @code NULL@ path only
+ * matches the current directory.
+ *
+ * @since CUPS 1.2@
  */
 
-const char *				/* O - Full path to file or NULL */
+const char *				/* O - Full path to file or @code NULL@ if not found */
 cupsFileFind(const char *filename,	/* I - File to find */
              const char *path,		/* I - Colon/semicolon-separated path */
              int        executable,	/* I - 1 = executable files, 0 = any file/dir */
@@ -386,6 +395,8 @@ cupsFileFind(const char *filename,	/* I - File to find */
 
 /*
  * 'cupsFileFlush()' - Flush pending output.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on success, -1 on error */
@@ -431,9 +442,11 @@ cupsFileFlush(cups_file_t *fp)		/* I - CUPS file */
 
 /*
  * 'cupsFileGetChar()' - Get a single character from a file.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - Character or -1 on EOF */
+int					/* O - Character or -1 on end of file */
 cupsFileGetChar(cups_file_t *fp)	/* I - CUPS file */
 {
  /*
@@ -469,9 +482,11 @@ cupsFileGetChar(cups_file_t *fp)	/* I - CUPS file */
 
 /*
  * 'cupsFileGetConf()' - Get a line from a configuration file...
+ *
+ * @since CUPS 1.2@
  */
 
-char *					/* O  - Line read or NULL on eof/error */
+char *					/* O  - Line read or @code NULL@ on end of file or error */
 cupsFileGetConf(cups_file_t *fp,	/* I  - CUPS file */
                 char        *buf,	/* O  - String buffer */
 		size_t      buflen,	/* I  - Size of string buffer */
@@ -603,13 +618,15 @@ cupsFileGetConf(cups_file_t *fp,	/* I  - CUPS file */
  * 'cupsFileGetLine()' - Get a CR and/or LF-terminated line that may
  *                       contain binary data.
  *
- * This function differs from cupsFileGets() in that the trailing CR and LF
- * are preserved, as is any binary data on the line. The buffer is nul-
- * terminated, however you should use the returned length to determine
+ * This function differs from @link cupsFileGets@ in that the trailing CR
+ * and LF are preserved, as is any binary data on the line. The buffer is
+ * nul-terminated, however you should use the returned length to determine
  * the number of bytes on the line.
+ *
+ * @since CUPS 1.2@
  */
 
-size_t					/* O - Number of bytes on line or 0 on EOF */
+size_t					/* O - Number of bytes on line or 0 on end of file */
 cupsFileGetLine(cups_file_t *fp,	/* I - File to read from */
                 char        *buf,	/* I - Buffer */
                 size_t      buflen)	/* I - Size of buffer */
@@ -671,9 +688,11 @@ cupsFileGetLine(cups_file_t *fp,	/* I - File to read from */
 
 /*
  * 'cupsFileGets()' - Get a CR and/or LF-terminated line.
+ *
+ * @since CUPS 1.2@
  */
 
-char *					/* O - Line read or NULL on eof/error */
+char *					/* O - Line read or @code NULL@ on end of file or error */
 cupsFileGets(cups_file_t *fp,		/* I - CUPS file */
              char        *buf,		/* O - String buffer */
 	     size_t      buflen)	/* I - Size of string buffer */
@@ -742,10 +761,12 @@ cupsFileGets(cups_file_t *fp,		/* I - CUPS file */
 
 /*
  * 'cupsFileLock()' - Temporarily lock access to a file.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on success, -1 on error */
-cupsFileLock(cups_file_t *fp,		/* I - File to lock */
+cupsFileLock(cups_file_t *fp,		/* I - CUPS file */
              int         block)		/* I - 1 to wait for the lock, 0 to fail right away */
 {
  /*
@@ -769,20 +790,39 @@ cupsFileLock(cups_file_t *fp,		/* I - File to lock */
 
 /*
  * 'cupsFileNumber()' - Return the file descriptor associated with a CUPS file.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - File descriptor */
 cupsFileNumber(cups_file_t *fp)		/* I - CUPS file */
 {
-  return (fp->fd);
+  if (fp)
+    return (fp->fd);
+  else
+    return (-1);
 }
 
 
 /*
  * 'cupsFileOpen()' - Open a CUPS file.
+ *
+ * The "mode" parameter can be "r" to read, "w" to write, overwriting any
+ * existing file, "a" to append to an existing file or create a new file,
+ * or "s" to open a socket connection.
+ *
+ * When opening for writing ("w") or appending ("a"), an optional number from
+ * 1 to 9 can be supplied which enables Flate compression of the file.
+ *
+ * When opening a socket connection, the filename is a string of the form
+ * "address:port" or "hostname:port". The socket will make an IPv4 or IPv6
+ * connection as needed, generally preferring IPv6 connections when there is
+ * a choice.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_file_t *				/* O - CUPS file or NULL */
+cups_file_t *				/* O - CUPS file or @code NULL@ if the file or socket cannot be opened */
 cupsFileOpen(const char *filename,	/* I - Name of file */
              const char *mode)		/* I - Open mode */
 {
@@ -877,9 +917,17 @@ cupsFileOpen(const char *filename,	/* I - Name of file */
 
 /*
  * 'cupsFileOpenFd()' - Open a CUPS file using a file descriptor.
+ *
+ * The "mode" parameter can be "r" to read, "a" or "w" to write, or "s"
+ * to treat the file descriptor as a bidirectional socket connection.
+ *
+ * When opening for writing ("w") or appending ("a"), an optional number from
+ * 1 to 9 can be supplied which enables Flate compression of the file.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_file_t *				/* O - CUPS file or NULL */
+cups_file_t *				/* O - CUPS file or @code NULL@ if the file could not be opened */
 cupsFileOpenFd(int        fd,		/* I - File descriptor */
 	       const char *mode)	/* I - Open mode */
 {
@@ -984,9 +1032,11 @@ cupsFileOpenFd(int        fd,		/* I - File descriptor */
 
 /*
  * 'cupsFilePeekChar()' - Peek at the next character from a file.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - Character or -1 on EOF */
+int					/* O - Character or -1 on end of file */
 cupsFilePeekChar(cups_file_t *fp)	/* I - CUPS file */
 {
  /*
@@ -1014,9 +1064,11 @@ cupsFilePeekChar(cups_file_t *fp)	/* I - CUPS file */
 
 /*
  * 'cupsFilePrintf()' - Write a formatted string.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - Number of bytes written or -1 */
+int					/* O - Number of bytes written or -1 on error */
 cupsFilePrintf(cups_file_t *fp,		/* I - CUPS file */
                const char  *format,	/* I - Printf-style format string */
 	       ...)			/* I - Additional args as necessary */
@@ -1067,6 +1119,8 @@ cupsFilePrintf(cups_file_t *fp,		/* I - CUPS file */
 
 /*
  * 'cupsFilePutChar()' - Write a character.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on success, -1 on error */
@@ -1115,9 +1169,13 @@ cupsFilePutChar(cups_file_t *fp,	/* I - CUPS file */
 
 /*
  * 'cupsFilePuts()' - Write a string.
+ *
+ * Like the @code fputs@ function, no newline is appended to the string.
+ *
+ * @since CUPS 1.2@
  */
 
-int					/* O - Number of bytes written or -1 */
+int					/* O - Number of bytes written or -1 on error */
 cupsFilePuts(cups_file_t *fp,		/* I - CUPS file */
              const char  *s)		/* I - String to write */
 {
@@ -1173,9 +1231,11 @@ cupsFilePuts(cups_file_t *fp,		/* I - CUPS file */
 
 /*
  * 'cupsFileRead()' - Read from a file.
+ *
+ * @since CUPS 1.2@
  */
 
-ssize_t					/* O - Number of bytes read or -1 */
+ssize_t					/* O - Number of bytes read or -1 on error */
 cupsFileRead(cups_file_t *fp,		/* I - CUPS file */
              char        *buf,		/* O - Buffer */
 	     size_t      bytes)		/* I - Number of bytes to read */
@@ -1242,10 +1302,13 @@ cupsFileRead(cups_file_t *fp,		/* I - CUPS file */
 
 
 /*
- * 'cupsFileRewind()' - Rewind a file.
+ * 'cupsFileRewind()' - Set the current file position to the beginning of the
+ *                      file.
+ *
+ * @since CUPS 1.2@
  */
 
-off_t					/* O - New file position or -1 */
+off_t					/* O - New file position or -1 on error */
 cupsFileRewind(cups_file_t *fp)		/* I - CUPS file */
 {
  /*
@@ -1299,9 +1362,11 @@ cupsFileRewind(cups_file_t *fp)		/* I - CUPS file */
 
 /*
  * 'cupsFileSeek()' - Seek in a file.
+ *
+ * @since CUPS 1.2@
  */
 
-off_t					/* O - New file position or -1 */
+off_t					/* O - New file position or -1 on error */
 cupsFileSeek(cups_file_t *fp,		/* I - CUPS file */
              off_t       pos)		/* I - Position in file */
 {
@@ -1454,9 +1519,11 @@ cupsFileSeek(cups_file_t *fp,		/* I - CUPS file */
 
 /*
  * 'cupsFileStderr()' - Return a CUPS file associated with stderr.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_file_t *
+cups_file_t *				/* O - CUPS file */
 cupsFileStderr(void)
 {
   _cups_globals_t *cg = _cupsGlobals();	/* Pointer to library globals... */
@@ -1488,9 +1555,11 @@ cupsFileStderr(void)
 
 /*
  * 'cupsFileStdin()' - Return a CUPS file associated with stdin.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_file_t *
+cups_file_t *				/* O - CUPS file */
 cupsFileStdin(void)
 {
   _cups_globals_t *cg = _cupsGlobals();	/* Pointer to library globals... */
@@ -1516,9 +1585,11 @@ cupsFileStdin(void)
 
 /*
  * 'cupsFileStdout()' - Return a CUPS file associated with stdout.
+ *
+ * @since CUPS 1.2@
  */
 
-cups_file_t *
+cups_file_t *				/* O - CUPS file */
 cupsFileStdout(void)
 {
   _cups_globals_t *cg = _cupsGlobals();	/* Pointer to library globals... */
@@ -1550,6 +1621,8 @@ cupsFileStdout(void)
 
 /*
  * 'cupsFileTell()' - Return the current file position.
+ *
+ * @since CUPS 1.2@
  */
 
 off_t					/* O - File position */
@@ -1561,10 +1634,12 @@ cupsFileTell(cups_file_t *fp)		/* I - CUPS file */
 
 /*
  * 'cupsFileUnlock()' - Unlock access to a file.
+ *
+ * @since CUPS 1.2@
  */
 
 int					/* O - 0 on success, -1 on error */
-cupsFileUnlock(cups_file_t *fp)		/* I - File to lock */
+cupsFileUnlock(cups_file_t *fp)		/* I - CUPS file */
 {
  /*
   * Range check...
@@ -1587,9 +1662,11 @@ cupsFileUnlock(cups_file_t *fp)		/* I - File to lock */
 
 /*
  * 'cupsFileWrite()' - Write to a file.
+ *
+ * @since CUPS 1.2@
  */
 
-ssize_t					/* O - Number of bytes written */
+ssize_t					/* O - Number of bytes written or -1 on error */
 cupsFileWrite(cups_file_t *fp,		/* I - CUPS file */
               const char  *buf,		/* I - Buffer */
 	      size_t      bytes)	/* I - Number of bytes to write */
diff --git a/cups/getputfile.c b/cups/getputfile.c
index b39a8339b..e144bd8e6 100644
--- a/cups/getputfile.c
+++ b/cups/getputfile.c
@@ -3,7 +3,7 @@
  *
  *   Get/put file functions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -45,13 +45,13 @@
 /*
  * 'cupsGetFd()' - Get a file from the server.
  *
- * This function returns HTTP_OK when the file is successfully retrieved.
+ * This function returns @code HTTP_OK@ when the file is successfully retrieved.
  *
  * @since CUPS 1.1.20@
  */
 
 http_status_t				/* O - HTTP status */
-cupsGetFd(http_t     *http,		/* I - HTTP connection to server */
+cupsGetFd(http_t     *http,		/* I - HTTP connection to server or @code CUPS_HTTP_DEFAULT@ */
 	  const char *resource,		/* I - Resource name */
 	  int        fd)		/* I - File descriptor */
 {
@@ -69,7 +69,7 @@ cupsGetFd(http_t     *http,		/* I - HTTP connection to server */
   DEBUG_printf(("cupsGetFd(http=%p, resource=\"%s\", fd=%d)\n", http,
                 resource, fd));
 
-  if (!http || !resource || fd < 0)
+  if (!resource || fd < 0)
   {
     if (http)
       http->error = EINVAL;
@@ -77,6 +77,9 @@ cupsGetFd(http_t     *http,		/* I - HTTP connection to server */
     return (HTTP_ERROR);
   }
 
+  if (!http)
+    http = _cupsConnect();
+
  /*
   * Then send GET requests to the HTTP server...
   */
@@ -182,13 +185,13 @@ cupsGetFd(http_t     *http,		/* I - HTTP connection to server */
 /*
  * 'cupsGetFile()' - Get a file from the server.
  *
- * This function returns HTTP_OK when the file is successfully retrieved.
+ * This function returns @code HTTP_OK@ when the file is successfully retrieved.
  *
  * @since CUPS 1.1.20@
  */
 
 http_status_t				/* O - HTTP status */
-cupsGetFile(http_t     *http,		/* I - HTTP connection to server */
+cupsGetFile(http_t     *http,		/* I - HTTP connection to server or @code CUPS_HTTP_DEFAULT@ */
 	    const char *resource,	/* I - Resource name */
 	    const char *filename)	/* I - Filename */
 {
@@ -249,13 +252,14 @@ cupsGetFile(http_t     *http,		/* I - HTTP connection to server */
 /*
  * 'cupsPutFd()' - Put a file on the server.
  *
- * This function returns HTTP_CREATED when the file is stored successfully.
+ * This function returns @code HTTP_CREATED@ when the file is stored
+ * successfully.
  *
  * @since CUPS 1.1.20@
  */
 
 http_status_t				/* O - HTTP status */
-cupsPutFd(http_t     *http,		/* I - HTTP connection to server */
+cupsPutFd(http_t     *http,		/* I - HTTP connection to server or @code CUPS_HTTP_DEFAULT@ */
           const char *resource,		/* I - Resource name */
 	  int        fd)		/* I - File descriptor */
 {
@@ -272,7 +276,7 @@ cupsPutFd(http_t     *http,		/* I - HTTP connection to server */
   DEBUG_printf(("cupsPutFd(http=%p, resource=\"%s\", fd=%d)\n", http,
                 resource, fd));
 
-  if (!http || !resource || fd < 0)
+  if (!resource || fd < 0)
   {
     if (http)
       http->error = EINVAL;
@@ -280,6 +284,9 @@ cupsPutFd(http_t     *http,		/* I - HTTP connection to server */
     return (HTTP_ERROR);
   }
 
+  if (!http)
+    http = _cupsConnect();
+
  /*
   * Then send PUT requests to the HTTP server...
   */
@@ -430,13 +437,14 @@ cupsPutFd(http_t     *http,		/* I - HTTP connection to server */
 /*
  * 'cupsPutFile()' - Put a file on the server.
  *
- * This function returns HTTP_CREATED when the file is stored successfully.
+ * This function returns @code HTTP_CREATED@ when the file is stored
+ * successfully.
  *
  * @since CUPS 1.1.20@
  */
 
 http_status_t				/* O - HTTP status */
-cupsPutFile(http_t     *http,		/* I - HTTP connection to server */
+cupsPutFile(http_t     *http,		/* I - HTTP connection to server or @code CUPS_HTTP_DEFAULT@ */
             const char *resource,	/* I - Resource name */
 	    const char *filename)	/* I - Filename */
 {
diff --git a/cups/ipp-private.h b/cups/ipp-private.h
index e38ca26e1..0083d2a38 100644
--- a/cups/ipp-private.h
+++ b/cups/ipp-private.h
@@ -3,7 +3,7 @@
  *
  *   Private IPP definitions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -40,6 +40,7 @@ extern "C" {
 
 typedef struct				/**** Attribute mapping data ****/
 {
+  int		multivalue;		/* Option has multiple values? */
   const char	*name;			/* Option/attribute name */
   ipp_tag_t	value_tag;		/* Value tag for this attribute */
   ipp_tag_t	group_tag;		/* Group tag for this attribute */
diff --git a/cups/ipp.c b/cups/ipp.c
index f212fd117..41f65c1d6 100644
--- a/cups/ipp.c
+++ b/cups/ipp.c
@@ -1187,17 +1187,15 @@ ippReadIO(void       *src,		/* I - Data source */
 
 	      attr->value_tag = tag;
 	    }
-	    else if (value_tag == IPP_TAG_STRING ||
-    		     (value_tag >= IPP_TAG_TEXTLANG &&
-		      value_tag <= IPP_TAG_MIMETYPE))
+	    else if (value_tag >= IPP_TAG_TEXTLANG &&
+		     value_tag <= IPP_TAG_MIMETYPE)
             {
 	     /*
 	      * String values can sometimes come across in different
 	      * forms; accept sets of differing values...
 	      */
 
-	      if (tag != IPP_TAG_STRING &&
-    		  (tag < IPP_TAG_TEXTLANG || tag > IPP_TAG_MIMETYPE))
+	      if (tag < IPP_TAG_TEXTLANG || tag > IPP_TAG_MIMETYPE)
 	        return (IPP_ERROR);
             }
 	    else if (value_tag != tag)
@@ -1334,6 +1332,7 @@ ippReadIO(void       *src,		/* I - Data source */
 
                 value->integer = n;
 	        break;
+
 	    case IPP_TAG_BOOLEAN :
 		if (n != 1)
 		{
@@ -1349,10 +1348,10 @@ ippReadIO(void       *src,		/* I - Data source */
 
                 value->boolean = buffer[0];
 	        break;
+
 	    case IPP_TAG_TEXT :
 	    case IPP_TAG_NAME :
 	    case IPP_TAG_KEYWORD :
-	    case IPP_TAG_STRING :
 	    case IPP_TAG_URI :
 	    case IPP_TAG_URISCHEME :
 	    case IPP_TAG_CHARSET :
@@ -1375,6 +1374,7 @@ ippReadIO(void       *src,		/* I - Data source */
 		DEBUG_printf(("ippReadIO: value = \'%s\'\n",
 		              value->string.text));
 	        break;
+
 	    case IPP_TAG_DATE :
 		if (n != 11)
 		{
@@ -1388,6 +1388,7 @@ ippReadIO(void       *src,		/* I - Data source */
 		  return (IPP_ERROR);
 		}
 	        break;
+
 	    case IPP_TAG_RESOLUTION :
 		if (n != 9)
 		{
@@ -1410,6 +1411,7 @@ ippReadIO(void       *src,		/* I - Data source */
                 value->resolution.units =
 		    (ipp_res_t)buffer[8];
 	        break;
+
 	    case IPP_TAG_RANGE :
 		if (n != 8)
 		{
@@ -1430,6 +1432,7 @@ ippReadIO(void       *src,		/* I - Data source */
 		    (((((buffer[4] << 8) | buffer[5]) << 8) | buffer[6]) << 8) |
 		    buffer[7];
 	        break;
+
 	    case IPP_TAG_TEXTLANG :
 	    case IPP_TAG_NAMELANG :
 	        if (n >= sizeof(buffer) || n < 4)
@@ -1955,7 +1958,6 @@ ippWriteIO(void       *dst,		/* I - Destination */
 	    case IPP_TAG_TEXT :
 	    case IPP_TAG_NAME :
 	    case IPP_TAG_KEYWORD :
-	    case IPP_TAG_STRING :
 	    case IPP_TAG_URI :
 	    case IPP_TAG_URISCHEME :
 	    case IPP_TAG_CHARSET :
@@ -2521,7 +2523,6 @@ _ippFreeAttr(ipp_attribute_t *attr)	/* I - Attribute to free */
     case IPP_TAG_TEXT :
     case IPP_TAG_NAME :
     case IPP_TAG_KEYWORD :
-    case IPP_TAG_STRING :
     case IPP_TAG_URI :
     case IPP_TAG_URISCHEME :
     case IPP_TAG_CHARSET :
@@ -2560,6 +2561,13 @@ _ippFreeAttr(ipp_attribute_t *attr)	/* I - Attribute to free */
           ippDelete(value->collection);
 	break;
 
+    case IPP_TAG_STRING :
+	for (i = 0, value = attr->values;
+	     i < attr->num_values;
+	     i ++, value ++)
+	  free(value->unknown.data);
+        break;
+
     default :
         if (!((int)attr->value_tag & IPP_TAG_COPY))
 	{
@@ -2648,7 +2656,6 @@ ipp_length(ipp_t *ipp,			/* I - IPP message or collection */
       case IPP_TAG_TEXT :
       case IPP_TAG_NAME :
       case IPP_TAG_KEYWORD :
-      case IPP_TAG_STRING :
       case IPP_TAG_URI :
       case IPP_TAG_URISCHEME :
       case IPP_TAG_CHARSET :
diff --git a/cups/ipp.h b/cups/ipp.h
index 29ef86afd..2a36fe35b 100644
--- a/cups/ipp.h
+++ b/cups/ipp.h
@@ -265,7 +265,7 @@ typedef enum ipp_status_e		/**** IPP status codes... ****/
   IPP_OK_TOO_MANY_EVENTS,		/* successful-ok-too-many-events */
   IPP_OK_BUT_CANCEL_SUBSCRIPTION,	/* successful-ok-but-cancel-subscription */
   IPP_OK_EVENTS_COMPLETE,		/* successful-ok-events-complete */
-  IPP_REDIRECTION_OTHER_SITE = 0x200,	/*  */
+  IPP_REDIRECTION_OTHER_SITE = 0x200,	/* redirection-other-site @private@ */
   CUPS_SEE_OTHER = 0x280,		/* cups-see-other */
   IPP_BAD_REQUEST = 0x0400,		/* client-error-bad-request */
   IPP_FORBIDDEN,			/* client-error-forbidden */
diff --git a/cups/language.c b/cups/language.c
index ea629c903..e08bde626 100644
--- a/cups/language.c
+++ b/cups/language.c
@@ -344,7 +344,7 @@ cupsLangFlush(void)
 /*
  * 'cupsLangFree()' - Free language data.
  *
- * This does not actually free anything; use cupsLangFlush() for that.
+ * This does not actually free anything; use @link cupsLangFlush@ for that.
  */
 
 void
diff --git a/cups/libcups.exp b/cups/libcups.exp
index a757eedcd..930c0d5d2 100644
--- a/cups/libcups.exp
+++ b/cups/libcups.exp
@@ -305,6 +305,7 @@ _ppdIsMarked
 _ppdLastError
 _ppdLocalize
 _ppdLocalizeIPPReason
+_ppdLocalizeMarkerName
 _ppdMarkDefaults
 _ppdMarkOption
 _ppdNextCustomParam
diff --git a/cups/localize.c b/cups/localize.c
index c03786ff3..9c91f6260 100644
--- a/cups/localize.c
+++ b/cups/localize.c
@@ -1,9 +1,9 @@
 /*
  * "$Id: localize.c 6882 2007-08-29 21:05:10Z mike $"
  *
- *   PPD custom option routines for the Common UNIX Printing System (CUPS).
+ *   PPD localization routines for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products, all rights reserved.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -25,11 +25,13 @@
  *
  * Contents:
  *
- *   ppdLocalize()          - Localize the PPD file to the current locale.
- *   ppdLocalizeIPPReason() - Get the localized version of a cupsIPPReason
- *                            attribute.
- *   ppd_ll_CC()            - Get the current locale names.
- *   ppd_localized_attr()   - Find a localized attribute.
+ *   ppdLocalize()           - Localize the PPD file to the current locale.
+ *   ppdLocalizeIPPReason()  - Get the localized version of a cupsIPPReason
+ *                             attribute.
+ *   ppdLocalizeMarkerName() - Get the localized version of a marker-names
+ *                             attribute value.
+ *   ppd_ll_CC()             - Get the current locale names.
+ *   ppd_localized_attr()    - Find a localized attribute.
  */
 
 /*
@@ -386,6 +388,52 @@ ppdLocalizeIPPReason(
 }
 
 
+/*
+ * 'ppdLocalizeMarkerName()' - Get the localized version of a marker-names
+ *                             attribute value.
+ *
+ * This function uses the current locale to find the corresponding name
+ * text from the attribute value. If no localized text for the requested
+ * name can be found, @code NULL@ is returned.
+ *
+ * @since CUPS 1.4@
+ */
+
+const char *				/* O - Value or @code NULL@ if not found */
+ppdLocalizeMarkerName(
+    ppd_file_t *ppd,			/* I - PPD file */
+    const char *name)			/* I - Marker name to look up */
+{
+  ppd_attr_t	*locattr;		/* Localized attribute */
+  char		ll_CC[6],		/* Language + country locale */
+		ll[3];			/* Language locale */
+
+
+ /*
+  * Range check input...
+  */
+
+  if (!ppd || !name)
+    return (NULL);
+
+ /*
+  * Get the default language...
+  */
+
+  ppd_ll_CC(ll_CC, sizeof(ll_CC), ll, sizeof(ll));
+
+ /*
+  * Find the localized attribute...
+  */
+
+  if ((locattr = ppd_localized_attr(ppd, "cupsMarkerName", name,
+                                    ll_CC, ll)) == NULL)
+    locattr = ppdFindAttr(ppd, "cupsMarkerName", name);
+
+  return (locattr ? locattr->text : NULL);
+}
+
+
 /*
  * 'ppd_ll_CC()' - Get the current locale names.
  */
diff --git a/cups/mark.c b/cups/mark.c
index 689aefb0f..0dbb0b8d1 100644
--- a/cups/mark.c
+++ b/cups/mark.c
@@ -1,9 +1,9 @@
 /*
- * "$Id: mark.c 6939 2007-09-10 21:18:02Z mike $"
+ * "$Id: mark.c 7278 2008-01-31 01:23:09Z mike $"
  *
  *   Option marking routines for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products, all rights reserved.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -18,16 +18,20 @@
  *
  * Contents:
  *
- *   ppdConflicts()        - Check to see if there are any conflicts.
+ *   cupsMarkOptions()     - Mark command-line options in a PPD file.
+ *   ppdConflicts()        - Check to see if there are any conflicts among the
+ *                           marked option choices.
  *   ppdFindChoice()       - Return a pointer to an option choice.
  *   ppdFindMarkedChoice() - Return the marked choice for the specified option.
  *   ppdFindOption()       - Return a pointer to the specified option.
- *   ppdFirstOption()      - Return the first option in the PPD file.
- *   ppdNextOption()       - Return the next option in the PPD file.
- *   ppdIsMarked()         - Check to see if an option is marked...
+ *   ppdIsMarked()         - Check to see if an option is marked.
  *   ppdMarkDefaults()     - Mark all default options in the PPD file.
  *   ppdMarkOption()       - Mark an option in a PPD file.
+ *   ppdFirstOption()      - Return the first option in the PPD file.
+ *   ppdNextOption()       - Return the next option in the PPD file.
+ *   debug_marked()        - Output the marked array to stdout...
  *   ppd_defaults()        - Set the defaults for this group and all sub-groups.
+ *   ppd_mark_choices()    - Mark one or more option choices from a string.
  */
 
 /*
@@ -43,11 +47,317 @@
  * Local functions...
  */
 
+#ifdef DEBUG
+static void	debug_marked(ppd_file_t *ppd, const char *title);
+#else
+#  define debug_marked(ppd,title)
+#endif /* DEBUG */
 static void	ppd_defaults(ppd_file_t *ppd, ppd_group_t *g);
+static int	ppd_mark_choices(ppd_file_t *ppd, const char *options);
 
 
 /*
- * 'ppdConflicts()' - Check to see if there are any conflicts.
+ * 'cupsMarkOptions()' - Mark command-line options in a PPD file.
+ *
+ * This function maps the IPP "finishings", "media", "mirror",
+ * "multiple-document-handling", "output-bin", "printer-resolution", and
+ * "sides" attributes to their corresponding PPD options and choices.
+ */
+
+int					/* O - 1 if conflicting */
+cupsMarkOptions(
+    ppd_file_t    *ppd,			/* I - PPD file */
+    int           num_options,		/* I - Number of options */
+    cups_option_t *options)		/* I - Options */
+{
+  int		i, j, k;		/* Looping vars */
+  int		conflict;		/* Option conflicts */
+  char		*val,			/* Pointer into value */
+		*ptr,			/* Pointer into string */
+		s[255];			/* Temporary string */
+  const char	*page_size;		/* PageSize option */
+  cups_option_t	*optptr;		/* Current option */
+  ppd_option_t	*option;		/* PPD option */
+  ppd_attr_t	*attr;			/* PPD attribute */
+  static const char * const duplex_options[] =
+		{			/* Duplex option names */
+		  "Duplex",		/* Adobe */
+		  "EFDuplex",		/* EFI */
+		  "EFDuplexing",	/* EFI */
+		  "KD03Duplex",		/* Kodak */
+		  "JCLDuplex"		/* Samsung */
+		};
+  static const char * const duplex_one[] =
+		{			/* one-sided names */
+		  "None",
+		  "False"
+		};
+  static const char * const duplex_two_long[] =
+		{			/* two-sided-long-edge names */
+		  "DuplexNoTumble",	/* Adobe */
+		  "LongEdge",		/* EFI */
+		  "Top"			/* EFI */
+		};
+  static const char * const duplex_two_short[] =
+		{			/* two-sided-long-edge names */
+		  "DuplexTumble",	/* Adobe */
+		  "ShortEdge",		/* EFI */
+		  "Bottom"		/* EFI */
+		};
+
+
+ /*
+  * Check arguments...
+  */
+
+  if (!ppd || num_options <= 0 || !options)
+    return (0);
+
+  debug_marked(ppd, "Before...");
+
+ /*
+  * Mark options...
+  */
+
+  conflict  = 0;
+
+  for (i = num_options, optptr = options; i > 0; i --, optptr ++)
+    if (!strcasecmp(optptr->name, "media"))
+    {
+     /*
+      * Loop through the option string, separating it at commas and
+      * marking each individual option as long as the corresponding
+      * PPD option (PageSize, InputSlot, etc.) is not also set.
+      *
+      * For PageSize, we also check for an empty option value since
+      * some versions of MacOS X use it to specify auto-selection
+      * of the media based solely on the size.
+      */
+
+      page_size = cupsGetOption("PageSize", num_options, options);
+
+      for (val = optptr->value; *val;)
+      {
+       /*
+        * Extract the sub-option from the string...
+	*/
+
+        for (ptr = s; *val && *val != ',' && (ptr - s) < (sizeof(s) - 1);)
+	  *ptr++ = *val++;
+	*ptr++ = '\0';
+
+	if (*val == ',')
+	  val ++;
+
+       /*
+        * Mark it...
+	*/
+
+        if (!page_size || !page_size[0])
+	  if (ppdMarkOption(ppd, "PageSize", s))
+            conflict = 1;
+
+        if (cupsGetOption("InputSlot", num_options, options) == NULL)
+	  if (ppdMarkOption(ppd, "InputSlot", s))
+            conflict = 1;
+
+        if (cupsGetOption("MediaType", num_options, options) == NULL)
+	  if (ppdMarkOption(ppd, "MediaType", s))
+            conflict = 1;
+
+        if (cupsGetOption("EFMediaType", num_options, options) == NULL)
+	  if (ppdMarkOption(ppd, "EFMediaType", s))		/* EFI */
+            conflict = 1;
+
+        if (cupsGetOption("EFMediaQualityMode", num_options, options) == NULL)
+	  if (ppdMarkOption(ppd, "EFMediaQualityMode", s))	/* EFI */
+            conflict = 1;
+
+	if (strcasecmp(s, "manual") == 0 &&
+	    cupsGetOption("ManualFeed", num_options, options) == NULL)
+          if (ppdMarkOption(ppd, "ManualFeed", "True"))
+	    conflict = 1;
+      }
+    }
+    else if (!strcasecmp(optptr->name, "sides"))
+    {
+      for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
+        if (cupsGetOption(duplex_options[j], num_options, options) != NULL)
+	  break;
+
+      if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
+      {
+       /*
+        * Don't override the PPD option with the IPP attribute...
+	*/
+
+        continue;
+      }
+
+      if (!strcasecmp(optptr->value, "one-sided"))
+      {
+       /*
+        * Mark the appropriate duplex option for one-sided output...
+	*/
+
+        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
+	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
+	    break;
+
+	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
+	{
+          for (k = 0; k < (int)(sizeof(duplex_one) / sizeof(duplex_one[0])); k ++)
+            if (ppdFindChoice(option, duplex_one[k]))
+	    {
+	      if (ppdMarkOption(ppd, duplex_options[j], duplex_one[k]))
+		conflict = 1;
+
+	      break;
+            }
+        }
+      }
+      else if (!strcasecmp(optptr->value, "two-sided-long-edge"))
+      {
+       /*
+        * Mark the appropriate duplex option for two-sided-long-edge output...
+	*/
+
+        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
+	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
+	    break;
+
+	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
+	{
+          for (k = 0; k < (int)(sizeof(duplex_two_long) / sizeof(duplex_two_long[0])); k ++)
+            if (ppdFindChoice(option, duplex_two_long[k]))
+	    {
+	      if (ppdMarkOption(ppd, duplex_options[j], duplex_two_long[k]))
+		conflict = 1;
+
+	      break;
+            }
+        }
+      }
+      else if (!strcasecmp(optptr->value, "two-sided-short-edge"))
+      {
+       /*
+        * Mark the appropriate duplex option for two-sided-short-edge output...
+	*/
+
+        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
+	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
+	    break;
+
+	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
+	{
+          for (k = 0; k < (int)(sizeof(duplex_two_short) / sizeof(duplex_two_short[0])); k ++)
+            if (ppdFindChoice(option, duplex_two_short[k]))
+	    {
+	      if (ppdMarkOption(ppd, duplex_options[j], duplex_two_short[k]))
+		conflict = 1;
+
+	      break;
+            }
+        }
+      }
+    }
+    else if (!strcasecmp(optptr->name, "resolution") ||
+             !strcasecmp(optptr->name, "printer-resolution"))
+    {
+      if (ppdMarkOption(ppd, "Resolution", optptr->value))
+        conflict = 1;
+      if (ppdMarkOption(ppd, "SetResolution", optptr->value))
+      	/* Calcomp, Linotype, QMS, Summagraphics, Tektronix, Varityper */
+        conflict = 1;
+      if (ppdMarkOption(ppd, "JCLResolution", optptr->value))	/* HP */
+        conflict = 1;
+      if (ppdMarkOption(ppd, "CNRes_PGP", optptr->value))	/* Canon */
+        conflict = 1;
+    }
+    else if (!strcasecmp(optptr->name, "output-bin"))
+    {
+      if (!cupsGetOption("OutputBin", num_options, options))
+        if (ppdMarkOption(ppd, "OutputBin", optptr->value))
+          conflict = 1;
+    }
+    else if (!strcasecmp(optptr->name, "multiple-document-handling"))
+    {
+      if (!cupsGetOption("Collate", num_options, options) &&
+          ppdFindOption(ppd, "Collate"))
+      {
+        if (strcasecmp(optptr->value, "separate-documents-uncollated-copies"))
+	{
+	  if (ppdMarkOption(ppd, "Collate", "True"))
+            conflict = 1;
+        }
+	else
+	{
+	  if (ppdMarkOption(ppd, "Collate", "False"))
+            conflict = 1;
+        }
+      }
+    }
+    else if (!strcasecmp(optptr->name, "finishings"))
+    {
+     /*
+      * Lookup cupsIPPFinishings attributes for each value...
+      */
+
+      for (ptr = optptr->value; *ptr;)
+      {
+       /*
+        * Get the next finishings number...
+	*/
+
+        if (!isdigit(*ptr & 255))
+	  break;
+
+        if ((j = strtol(ptr, &ptr, 10)) < 3)
+	  break;
+
+       /*
+        * Skip separator as needed...
+	*/
+
+        if (*ptr == ',')
+	  ptr ++;
+
+       /*
+        * Look it up in the PPD file...
+	*/
+
+	sprintf(s, "%d", j);
+
+        if ((attr = ppdFindAttr(ppd, "cupsIPPFinishings", s)) == NULL)
+	  continue;
+
+       /*
+        * Apply "*Option Choice" settings from the attribute value...
+	*/
+
+        if (ppd_mark_choices(ppd, attr->value))
+	  conflict = 1;
+      }
+    }
+    else if (!strcasecmp(optptr->name, "mirror"))
+    {
+      if (ppdMarkOption(ppd, "MirrorPrint", optptr->value))
+	conflict = 1;
+    }
+    else if (ppdMarkOption(ppd, optptr->name, optptr->value))
+      conflict = 1;
+
+  debug_marked(ppd, "After...");
+
+  return (conflict);
+}
+
+
+/*
+ * 'ppdConflicts()' - Check to see if there are any conflicts among the
+ *                    marked option choices.
+ *
+ * The returned value is the same as returned by @link ppdMarkOption@.
  */
 
 int					/* O - Number of conflicts found */
@@ -189,7 +499,7 @@ ppdConflicts(ppd_file_t *ppd)		/* I - PPD to check */
  * 'ppdFindChoice()' - Return a pointer to an option choice.
  */
 
-ppd_choice_t *				/* O - Choice pointer or NULL */
+ppd_choice_t *				/* O - Choice pointer or @code NULL@ */
 ppdFindChoice(ppd_option_t *o,		/* I - Pointer to option */
               const char   *choice)	/* I - Name of choice */
 {
@@ -212,7 +522,7 @@ ppdFindChoice(ppd_option_t *o,		/* I - Pointer to option */
  * 'ppdFindMarkedChoice()' - Return the marked choice for the specified option.
  */
 
-ppd_choice_t *				/* O - Pointer to choice or NULL */
+ppd_choice_t *				/* O - Pointer to choice or @code NULL@ */
 ppdFindMarkedChoice(ppd_file_t *ppd,	/* I - PPD file */
                     const char *option)	/* I - Keyword/option name */
 {
@@ -230,7 +540,7 @@ ppdFindMarkedChoice(ppd_file_t *ppd,	/* I - PPD file */
  * 'ppdFindOption()' - Return a pointer to the specified option.
  */
 
-ppd_option_t *				/* O - Pointer to option or NULL */
+ppd_option_t *				/* O - Pointer to option or @code NULL@ */
 ppdFindOption(ppd_file_t *ppd,		/* I - PPD file data */
               const char *option)	/* I - Option/Keyword name */
 {
@@ -278,7 +588,7 @@ ppdFindOption(ppd_file_t *ppd,		/* I - PPD file data */
 
 
 /*
- * 'ppdIsMarked()' - Check to see if an option is marked...
+ * 'ppdIsMarked()' - Check to see if an option is marked.
  */
 
 int					/* O - Non-zero if option is marked */
@@ -338,11 +648,6 @@ ppdMarkDefaults(ppd_file_t *ppd)	/* I - PPD file record */
 
 /*
  * 'ppdMarkOption()' - Mark an option in a PPD file.
- *
- * Notes:
- *
- *   -1 is returned if the given option would conflict with any currently
- *   selected option.
  */
 
 int					/* O - Number of conflicts */
@@ -668,12 +973,12 @@ ppdMarkOption(ppd_file_t *ppd,		/* I - PPD file record */
 /*
  * 'ppdFirstOption()' - Return the first option in the PPD file.
  *
- * Options are returned from all groups in sorted order.
+ * Options are returned from all groups in ascending alphanumeric order.
  *
  * @since CUPS 1.2@
  */
 
-ppd_option_t *				/* O - First option or NULL */
+ppd_option_t *				/* O - First option or @code NULL@ */
 ppdFirstOption(ppd_file_t *ppd)		/* I - PPD file */
 {
   if (!ppd)
@@ -686,12 +991,12 @@ ppdFirstOption(ppd_file_t *ppd)		/* I - PPD file */
 /*
  * 'ppdNextOption()' - Return the next option in the PPD file.
  *
- * Options are returned from all groups in sorted order.
+ * Options are returned from all groups in ascending alphanumeric order.
  *
  * @since CUPS 1.2@
  */
 
-ppd_option_t *				/* O - Next option or NULL */
+ppd_option_t *				/* O - Next option or @code NULL@ */
 ppdNextOption(ppd_file_t *ppd)		/* I - PPD file */
 {
   if (!ppd)
@@ -701,17 +1006,39 @@ ppdNextOption(ppd_file_t *ppd)		/* I - PPD file */
 }
 
 
+#ifdef DEBUG
+/*
+ * 'debug_marked()' - Output the marked array to stdout...
+ */
+
+static void
+debug_marked(ppd_file_t *ppd,		/* I - PPD file data */
+             const char *title)		/* I - Title for list */
+{
+  ppd_choice_t	*c;			/* Current choice */
+
+
+  printf("cupsMarkOptions: %s\n", title);
+
+  for (c = (ppd_choice_t *)cupsArrayFirst(ppd->marked);
+       c;
+       c = (ppd_choice_t *)cupsArrayNext(ppd->marked))
+    printf("cupsMarkOptions: %s=%s\n", c->option->keyword, c->choice);
+}
+#endif /* DEBUG */
+
+
 /*
  * 'ppd_defaults()' - Set the defaults for this group and all sub-groups.
  */
 
 static void
-ppd_defaults(ppd_file_t  *ppd,	/* I - PPD file */
-             ppd_group_t *g)	/* I - Group to default */
+ppd_defaults(ppd_file_t  *ppd,		/* I - PPD file */
+             ppd_group_t *g)		/* I - Group to default */
 {
-  int		i;		/* Looping var */
-  ppd_option_t	*o;		/* Current option */
-  ppd_group_t	*sg;		/* Current sub-group */
+  int		i;			/* Looping var */
+  ppd_option_t	*o;			/* Current option */
+  ppd_group_t	*sg;			/* Current sub-group */
 
 
   for (i = g->num_options, o = g->options; i > 0; i --, o ++)
@@ -724,5 +1051,87 @@ ppd_defaults(ppd_file_t  *ppd,	/* I - PPD file */
 
 
 /*
- * End of "$Id: mark.c 6939 2007-09-10 21:18:02Z mike $".
+ * 'ppd_mark_choices()' - Mark one or more option choices from a string.
+ */
+
+static int				/* O - 1 if there are conflicts, 0 otherwise */
+ppd_mark_choices(ppd_file_t *ppd,	/* I - PPD file */
+                 const char *options)	/* I - "*Option Choice ..." string */
+{
+  char	option[PPD_MAX_NAME],		/* Current option */
+	choice[PPD_MAX_NAME],		/* Current choice */
+	*ptr;				/* Pointer into option or choice */
+  int	conflict = 0;			/* Do we have a conflict? */
+
+
+  if (!options)
+    return (0);
+
+ /*
+  * Read all of the "*Option Choice" pairs from the string, marking PPD
+  * options as we go...
+  */
+
+  while (*options)
+  {
+   /*
+    * Skip leading whitespace...
+    */
+
+    while (isspace(*options & 255))
+      options ++;
+
+    if (*options != '*')
+      break;
+
+   /*
+    * Get the option name...
+    */
+
+    options ++;
+    ptr = option;
+    while (*options && !isspace(*options & 255) &&
+	       ptr < (option + sizeof(option) - 1))
+      *ptr++ = *options++;
+
+    if (ptr == option)
+      break;
+
+    *ptr = '\0';
+
+   /*
+    * Get the choice...
+    */
+
+    while (isspace(*options & 255))
+      options ++;
+
+    if (!*options)
+      break;
+
+    ptr = choice;
+    while (*options && !isspace(*options & 255) &&
+	       ptr < (choice + sizeof(choice) - 1))
+      *ptr++ = *options++;
+
+    *ptr = '\0';
+
+   /*
+    * Mark the option...
+    */
+
+    if (ppdMarkOption(ppd, option, choice))
+      conflict = 1;
+  }
+
+ /*
+  * Return whether we had any conflicts...
+  */
+
+  return (conflict);
+}
+
+
+/*
+ * End of "$Id: mark.c 7278 2008-01-31 01:23:09Z mike $".
  */
diff --git a/cups/notify.c b/cups/notify.c
index 02bb74560..32ff2c805 100644
--- a/cups/notify.c
+++ b/cups/notify.c
@@ -3,7 +3,7 @@
  *
  *   Notification routines for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 2005-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -36,7 +36,7 @@
  * @since CUPS 1.2@
  */
 
-char *					/* O - Subject string or NULL */
+char *					/* O - Subject string or @code NULL@ */
 cupsNotifySubject(cups_lang_t *lang,	/* I - Language data */
                   ipp_t       *event)	/* I - Event data */
 {
@@ -162,12 +162,12 @@ cupsNotifySubject(cups_lang_t *lang,	/* I - Language data */
 /*
  * 'cupsNotifyText()' - Return the text for the given notification message.
  *
- * The returned string must be freed by the caller using free().
+ * The returned string must be freed by the caller using @code free@.
  *
  * @since CUPS 1.2@
  */
 
-char *					/* O - Message text or NULL */
+char *					/* O - Message text or @code NULL@ */
 cupsNotifyText(cups_lang_t *lang,	/* I - Language data */
                ipp_t       *event)	/* I - Event data */
 {
diff --git a/cups/options.c b/cups/options.c
index f04138497..4ffb39f82 100644
--- a/cups/options.c
+++ b/cups/options.c
@@ -1,5 +1,5 @@
 /*
- * "$Id: options.c 6943 2007-09-10 23:00:33Z mike $"
+ * "$Id: options.c 7278 2008-01-31 01:23:09Z mike $"
  *
  *   Option routines for the Common UNIX Printing System (CUPS).
  *
@@ -16,14 +16,11 @@
  *
  * Contents:
  *
- *   cupsAddOption()     - Add an option to an option array.
- *   cupsFreeOptions()   - Free all memory used by options.
- *   cupsGetOption()     - Get an option value.
- *   cupsMarkOptions()   - Mark command-line options in a PPD file.
- *   cupsParseOptions()  - Parse options from a command-line argument.
- *   cupsRemoveOptions() - Remove an option from an option array.
- *   debug_marked()      - Output the marked array to stdout...
- *   ppd_mark_choices()  - Mark one or more option choices from a string.
+ *   cupsAddOption()    - Add an option to an option array.
+ *   cupsFreeOptions()  - Free all memory used by options.
+ *   cupsGetOption()    - Get an option value.
+ *   cupsParseOptions() - Parse options from a command-line argument.
+ *   cupsRemoveOption() - Remove an option from an option array.
  */
 
 /*
@@ -37,26 +34,17 @@
 #include "debug.h"
 
 
-/*
- * Local functions...
- */
-
-#ifdef DEBUG
-static void	debug_marked(ppd_file_t *ppd, const char *title);
-#else
-#  define debug_marked(ppd,title)
-#endif /* DEBUG */
-static int	ppd_mark_choices(ppd_file_t *ppd, const char *options);
-
-
 /*
  * 'cupsAddOption()' - Add an option to an option array.
+ *
+ * New option arrays can be initialized simply by passing 0 for the
+ * "num_options" parameter.
  */
 
-int					/* O - Number of options */
-cupsAddOption(const char    *name,	/* I - Name of option */
-              const char    *value,	/* I - Value of option */
-	      int           num_options,/* I - Number of options */
+int					/* O  - Number of options */
+cupsAddOption(const char    *name,	/* I  - Name of option */
+              const char    *value,	/* I  - Value of option */
+	      int           num_options,/* I  - Number of options */
               cups_option_t **options)	/* IO - Pointer to options */
 {
   int		i;			/* Looping var */
@@ -139,7 +127,7 @@ cupsFreeOptions(
  * 'cupsGetOption()' - Get an option value.
  */
 
-const char *				/* O - Option value or NULL */
+const char *				/* O - Option value or @code NULL@ */
 cupsGetOption(const char    *name,	/* I - Name of option */
               int           num_options,/* I - Number of options */
               cups_option_t *options)	/* I - Options */
@@ -158,307 +146,14 @@ cupsGetOption(const char    *name,	/* I - Name of option */
 }
 
 
-/*
- * 'cupsMarkOptions()' - Mark command-line options in a PPD file.
- */
-
-int					/* O - 1 if conflicting */
-cupsMarkOptions(
-    ppd_file_t    *ppd,			/* I - PPD file */
-    int           num_options,		/* I - Number of options */
-    cups_option_t *options)		/* I - Options */
-{
-  int		i, j, k;		/* Looping vars */
-  int		conflict;		/* Option conflicts */
-  char		*val,			/* Pointer into value */
-		*ptr,			/* Pointer into string */
-		s[255];			/* Temporary string */
-  const char	*page_size;		/* PageSize option */
-  cups_option_t	*optptr;		/* Current option */
-  ppd_option_t	*option;		/* PPD option */
-  ppd_attr_t	*attr;			/* PPD attribute */
-  static const char * const duplex_options[] =
-		{			/* Duplex option names */
-		  "Duplex",		/* Adobe */
-		  "EFDuplex",		/* EFI */
-		  "EFDuplexing",	/* EFI */
-		  "KD03Duplex",		/* Kodak */
-		  "JCLDuplex"		/* Samsung */
-		};
-  static const char * const duplex_one[] =
-		{			/* one-sided names */
-		  "None",
-		  "False"
-		};
-  static const char * const duplex_two_long[] =
-		{			/* two-sided-long-edge names */
-		  "DuplexNoTumble",	/* Adobe */
-		  "LongEdge",		/* EFI */
-		  "Top"			/* EFI */
-		};
-  static const char * const duplex_two_short[] =
-		{			/* two-sided-long-edge names */
-		  "DuplexTumble",	/* Adobe */
-		  "ShortEdge",		/* EFI */
-		  "Bottom"		/* EFI */
-		};
-
-
- /*
-  * Check arguments...
-  */
-
-  if (ppd == NULL || num_options <= 0 || options == NULL)
-    return (0);
-
-  debug_marked(ppd, "Before...");
-
- /*
-  * Mark options...
-  */
-
-  conflict  = 0;
-
-  for (i = num_options, optptr = options; i > 0; i --, optptr ++)
-    if (!strcasecmp(optptr->name, "media"))
-    {
-     /*
-      * Loop through the option string, separating it at commas and
-      * marking each individual option as long as the corresponding
-      * PPD option (PageSize, InputSlot, etc.) is not also set.
-      *
-      * For PageSize, we also check for an empty option value since
-      * some versions of MacOS X use it to specify auto-selection
-      * of the media based solely on the size.
-      */
-
-      page_size = cupsGetOption("PageSize", num_options, options);
-
-      for (val = optptr->value; *val;)
-      {
-       /*
-        * Extract the sub-option from the string...
-	*/
-
-        for (ptr = s; *val && *val != ',' && (ptr - s) < (sizeof(s) - 1);)
-	  *ptr++ = *val++;
-	*ptr++ = '\0';
-
-	if (*val == ',')
-	  val ++;
-
-       /*
-        * Mark it...
-	*/
-
-        if (!page_size || !page_size[0])
-	  if (ppdMarkOption(ppd, "PageSize", s))
-            conflict = 1;
-
-        if (cupsGetOption("InputSlot", num_options, options) == NULL)
-	  if (ppdMarkOption(ppd, "InputSlot", s))
-            conflict = 1;
-
-        if (cupsGetOption("MediaType", num_options, options) == NULL)
-	  if (ppdMarkOption(ppd, "MediaType", s))
-            conflict = 1;
-
-        if (cupsGetOption("EFMediaType", num_options, options) == NULL)
-	  if (ppdMarkOption(ppd, "EFMediaType", s))		/* EFI */
-            conflict = 1;
-
-        if (cupsGetOption("EFMediaQualityMode", num_options, options) == NULL)
-	  if (ppdMarkOption(ppd, "EFMediaQualityMode", s))	/* EFI */
-            conflict = 1;
-
-	if (strcasecmp(s, "manual") == 0 &&
-	    cupsGetOption("ManualFeed", num_options, options) == NULL)
-          if (ppdMarkOption(ppd, "ManualFeed", "True"))
-	    conflict = 1;
-      }
-    }
-    else if (!strcasecmp(optptr->name, "sides"))
-    {
-      for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
-        if (cupsGetOption(duplex_options[j], num_options, options) != NULL)
-	  break;
-
-      if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
-      {
-       /*
-        * Don't override the PPD option with the IPP attribute...
-	*/
-
-        continue;
-      }
-
-      if (!strcasecmp(optptr->value, "one-sided"))
-      {
-       /*
-        * Mark the appropriate duplex option for one-sided output...
-	*/
-
-        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
-	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
-	    break;
-
-	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
-	{
-          for (k = 0; k < (int)(sizeof(duplex_one) / sizeof(duplex_one[0])); k ++)
-            if (ppdFindChoice(option, duplex_one[k]))
-	    {
-	      if (ppdMarkOption(ppd, duplex_options[j], duplex_one[k]))
-		conflict = 1;
-
-	      break;
-            }
-        }
-      }
-      else if (!strcasecmp(optptr->value, "two-sided-long-edge"))
-      {
-       /*
-        * Mark the appropriate duplex option for two-sided-long-edge output...
-	*/
-
-        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
-	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
-	    break;
-
-	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
-	{
-          for (k = 0; k < (int)(sizeof(duplex_two_long) / sizeof(duplex_two_long[0])); k ++)
-            if (ppdFindChoice(option, duplex_two_long[k]))
-	    {
-	      if (ppdMarkOption(ppd, duplex_options[j], duplex_two_long[k]))
-		conflict = 1;
-
-	      break;
-            }
-        }
-      }
-      else if (!strcasecmp(optptr->value, "two-sided-short-edge"))
-      {
-       /*
-        * Mark the appropriate duplex option for two-sided-short-edge output...
-	*/
-
-        for (j = 0; j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])); j ++)
-	  if ((option = ppdFindOption(ppd, duplex_options[j])) != NULL)
-	    break;
-
-	if (j < (int)(sizeof(duplex_options) / sizeof(duplex_options[0])))
-	{
-          for (k = 0; k < (int)(sizeof(duplex_two_short) / sizeof(duplex_two_short[0])); k ++)
-            if (ppdFindChoice(option, duplex_two_short[k]))
-	    {
-	      if (ppdMarkOption(ppd, duplex_options[j], duplex_two_short[k]))
-		conflict = 1;
-
-	      break;
-            }
-        }
-      }
-    }
-    else if (!strcasecmp(optptr->name, "resolution") ||
-             !strcasecmp(optptr->name, "printer-resolution"))
-    {
-      if (ppdMarkOption(ppd, "Resolution", optptr->value))
-        conflict = 1;
-      if (ppdMarkOption(ppd, "SetResolution", optptr->value))
-      	/* Calcomp, Linotype, QMS, Summagraphics, Tektronix, Varityper */
-        conflict = 1;
-      if (ppdMarkOption(ppd, "JCLResolution", optptr->value))	/* HP */
-        conflict = 1;
-      if (ppdMarkOption(ppd, "CNRes_PGP", optptr->value))	/* Canon */
-        conflict = 1;
-    }
-    else if (!strcasecmp(optptr->name, "output-bin"))
-    {
-      if (!cupsGetOption("OutputBin", num_options, options))
-        if (ppdMarkOption(ppd, "OutputBin", optptr->value))
-          conflict = 1;
-    }
-    else if (!strcasecmp(optptr->name, "multiple-document-handling"))
-    {
-      if (!cupsGetOption("Collate", num_options, options) &&
-          ppdFindOption(ppd, "Collate"))
-      {
-        if (strcasecmp(optptr->value, "separate-documents-uncollated-copies"))
-	{
-	  if (ppdMarkOption(ppd, "Collate", "True"))
-            conflict = 1;
-        }
-	else
-	{
-	  if (ppdMarkOption(ppd, "Collate", "False"))
-            conflict = 1;
-        }
-      }
-    }
-    else if (!strcasecmp(optptr->name, "finishings"))
-    {
-     /*
-      * Lookup cupsIPPFinishings attributes for each value...
-      */
-
-      for (ptr = optptr->value; *ptr;)
-      {
-       /*
-        * Get the next finishings number...
-	*/
-
-        if (!isdigit(*ptr & 255))
-	  break;
-
-        if ((j = strtol(ptr, &ptr, 10)) < 3)
-	  break;
-
-       /*
-        * Skip separator as needed...
-	*/
-
-        if (*ptr == ',')
-	  ptr ++;
-
-       /*
-        * Look it up in the PPD file...
-	*/
-
-	sprintf(s, "%d", j);
-
-        if ((attr = ppdFindAttr(ppd, "cupsIPPFinishings", s)) == NULL)
-	  continue;
-
-       /*
-        * Apply "*Option Choice" settings from the attribute value...
-	*/
-
-        if (ppd_mark_choices(ppd, attr->value))
-	  conflict = 1;
-      }
-    }
-    else if (!strcasecmp(optptr->name, "mirror"))
-    {
-      if (ppdMarkOption(ppd, "MirrorPrint", optptr->value))
-	conflict = 1;
-    }
-    else if (ppdMarkOption(ppd, optptr->name, optptr->value))
-      conflict = 1;
-
-  debug_marked(ppd, "After...");
-
-  return (conflict);
-}
-
-
 /*
  * 'cupsParseOptions()' - Parse options from a command-line argument.
  *
  * This function converts space-delimited name/value pairs according
  * to the PAPI text option ABNF specification. Collection values
  * ("name={a=... b=... c=...}") are stored with the curley brackets
- * intact - use cupsParseOptions() on the value to extract the collection
- * attributes.
+ * intact - use @code cupsParseOptions@ on the value to extract the
+ * collection attributes.
  */
 
 int					/* O - Number of options found */
@@ -470,7 +165,8 @@ cupsParseOptions(
   char	*copyarg,			/* Copy of input string */
 	*ptr,				/* Pointer into string */
 	*name,				/* Pointer to name */
-	*value;				/* Pointer to value */
+	*value,				/* Pointer to value */
+	quote;				/* Quote character */
 
 
  /*
@@ -510,7 +206,7 @@ cupsParseOptions(
     */
 
     name = ptr;
-    while (!isspace(*ptr & 255) && *ptr != '=' && *ptr != '\0')
+    while (!isspace(*ptr & 255) && *ptr != '=' && *ptr)
       ptr ++;
 
    /*
@@ -530,10 +226,10 @@ cupsParseOptions(
     if (*ptr != '=')
     {
      /*
-      * Start of another option...
+      * Boolean option...
       */
 
-      if (strncasecmp(name, "no", 2) == 0)
+      if (!strncasecmp(name, "no", 2))
         num_options = cupsAddOption(name + 2, "false", num_options,
 	                            options);
       else
@@ -548,38 +244,18 @@ cupsParseOptions(
 
     *ptr++ = '\0';
 
-    if (*ptr == '\'')
+    if (*ptr == '\'' || *ptr == '\"')
     {
      /*
       * Quoted string constant...
       */
 
-      ptr ++;
-      value = ptr;
-
-      while (*ptr != '\'' && *ptr != '\0')
-      {
-        if (*ptr == '\\')
-	  _cups_strcpy(ptr, ptr + 1);
-
-        ptr ++;
-      }
-
-      if (*ptr != '\0')
-        *ptr++ = '\0';
-    }
-    else if (*ptr == '\"')
-    {
-     /*
-      * Double-quoted string constant...
-      */
-
-      ptr ++;
+      quote = *ptr++;
       value = ptr;
 
-      while (*ptr != '\"' && *ptr != '\0')
+      while (*ptr != quote && *ptr)
       {
-        if (*ptr == '\\')
+        if (*ptr == '\\' && ptr[1])
 	  _cups_strcpy(ptr, ptr + 1);
 
         ptr ++;
@@ -612,7 +288,7 @@ cupsParseOptions(
 	      break;
 	  }
         }
-        else if (*ptr == '\\')
+        else if (*ptr == '\\' && ptr[1])
 	  _cups_strcpy(ptr, ptr + 1);
 
       if (*ptr != '\0')
@@ -626,9 +302,9 @@ cupsParseOptions(
 
       value = ptr;
 
-      while (!isspace(*ptr & 255) && *ptr != '\0')
+      while (!isspace(*ptr & 255) && *ptr)
       {
-        if (*ptr == '\\')
+        if (*ptr == '\\' && ptr[1])
 	  _cups_strcpy(ptr, ptr + 1);
 
         ptr ++;
@@ -715,110 +391,6 @@ cupsRemoveOption(
 }
 
 
-#ifdef DEBUG
-/*
- * 'debug_marked()' - Output the marked array to stdout...
- */
-
-static void
-debug_marked(ppd_file_t *ppd,		/* I - PPD file data */
-             const char *title)		/* I - Title for list */
-{
-  ppd_choice_t	*c;			/* Current choice */
-
-
-  printf("cupsMarkOptions: %s\n", title);
-
-  for (c = (ppd_choice_t *)cupsArrayFirst(ppd->marked);
-       c;
-       c = (ppd_choice_t *)cupsArrayNext(ppd->marked))
-    printf("cupsMarkOptions: %s=%s\n", c->option->keyword, c->choice);
-}
-#endif /* DEBUG */
-
-
-/*
- * 'ppd_mark_choices()' - Mark one or more option choices from a string.
- */
-
-static int				/* O - 1 if there are conflicts, 0 otherwise */
-ppd_mark_choices(ppd_file_t *ppd,	/* I - PPD file */
-                 const char *options)	/* I - "*Option Choice ..." string */
-{
-  char	option[PPD_MAX_NAME],		/* Current option */
-	choice[PPD_MAX_NAME],		/* Current choice */
-	*ptr;				/* Pointer into option or choice */
-  int	conflict = 0;			/* Do we have a conflict? */
-
-
-  if (!options)
-    return (0);
-
- /*
-  * Read all of the "*Option Choice" pairs from the string, marking PPD
-  * options as we go...
-  */
-
-  while (*options)
-  {
-   /*
-    * Skip leading whitespace...
-    */
-
-    while (isspace(*options & 255))
-      options ++;
-
-    if (*options != '*')
-      break;
-
-   /*
-    * Get the option name...
-    */
-
-    options ++;
-    ptr = option;
-    while (*options && !isspace(*options & 255) &&
-	       ptr < (option + sizeof(option) - 1))
-      *ptr++ = *options++;
-
-    if (ptr == option)
-      break;
-
-    *ptr = '\0';
-
-   /*
-    * Get the choice...
-    */
-
-    while (isspace(*options & 255))
-      options ++;
-
-    if (!*options)
-      break;
-
-    ptr = choice;
-    while (*options && !isspace(*options & 255) &&
-	       ptr < (choice + sizeof(choice) - 1))
-      *ptr++ = *options++;
-
-    *ptr = '\0';
-
-   /*
-    * Mark the option...
-    */
-
-    if (ppdMarkOption(ppd, option, choice))
-      conflict = 1;
-  }
-
- /*
-  * Return whether we had any conflicts...
-  */
-
-  return (conflict);
-}
-
-
 /*
- * End of "$Id: options.c 6943 2007-09-10 23:00:33Z mike $".
+ * End of "$Id: options.c 7278 2008-01-31 01:23:09Z mike $".
  */
diff --git a/cups/ppd.c b/cups/ppd.c
index ea9eb86b7..a70a0cfeb 100644
--- a/cups/ppd.c
+++ b/cups/ppd.c
@@ -428,7 +428,7 @@ ppdOpen(FILE *fp)			/* I - File to read from */
  * @since CUPS 1.2@
  */
 
-ppd_file_t *				/* O - PPD file record */
+ppd_file_t *				/* O - PPD file record or @code NULL@ if the PPD file could not be opened. */
 ppdOpen2(cups_file_t *fp)		/* I - File to read from */
 {
   int			i, j, k;	/* Looping vars */
@@ -2020,7 +2020,7 @@ ppdOpen2(cups_file_t *fp)		/* I - File to read from */
  * 'ppdOpenFd()' - Read a PPD file into memory.
  */
 
-ppd_file_t *				/* O - PPD file record */
+ppd_file_t *				/* O - PPD file record or @code NULL@ if the PPD file could not be opened. */
 ppdOpenFd(int fd)			/* I - File to read from */
 {
   cups_file_t		*fp;		/* CUPS file pointer */
@@ -2070,7 +2070,7 @@ ppdOpenFd(int fd)			/* I - File to read from */
  * 'ppdOpenFile()' - Read a PPD file into memory.
  */
 
-ppd_file_t *				/* O - PPD file record */
+ppd_file_t *				/* O - PPD file record or @code NULL@ if the PPD file could not be opened. */
 ppdOpenFile(const char *filename)	/* I - File to read from */
 {
   cups_file_t		*fp;		/* File pointer */
diff --git a/cups/ppd.h b/cups/ppd.h
index f154c6ba3..c99981793 100644
--- a/cups/ppd.h
+++ b/cups/ppd.h
@@ -4,7 +4,7 @@
  *   PostScript Printer Description definitions for the Common UNIX Printing
  *   System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2007 by Easy Software Products, all rights reserved.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -118,11 +118,14 @@ typedef enum ppd_status_e		/**** Status Codes @since CUPS 1.1.19@ ****/
   PPD_BAD_CUSTOM_PARAM			/* Bad custom parameter */
 } ppd_status_t;
 
-typedef enum ppd_conform_e		/**** Conformance Levels @since CUPS 1.1.19@ ****/
+enum ppd_conform_e			/**** Conformance Levels @since CUPS 1.1.19@ ****/
 {
   PPD_CONFORM_RELAXED,			/* Relax whitespace and control char */
   PPD_CONFORM_STRICT			/* Require strict conformance */
-} ppd_conform_t;
+};
+
+typedef enum ppd_conform_e ppd_conform_t;
+					/**** Conformance Levels @since CUPS 1.1.19@ ****/
 
 typedef struct ppd_attr_s		/**** PPD Attribute Structure @since CUPS 1.1.19@ ****/
 {
@@ -172,7 +175,7 @@ typedef struct ppd_group_s		/**** Groups ****/
   struct ppd_group_s *subgroups;	/* Sub-groups (max depth = 1) */
 } ppd_group_t;
 
-typedef struct				/**** Constraints ****/
+typedef struct ppd_const_s		/**** Constraints ****/
 {
   char		option1[PPD_MAX_NAME];	/* First keyword */
   char		choice1[PPD_MAX_NAME];	/* First option/choice (blank for all) */
@@ -392,7 +395,12 @@ extern ppd_file_t	*ppdOpen2(cups_file_t *fp) _CUPS_API_1_2;
 extern const char	*ppdLocalizeIPPReason(ppd_file_t *ppd,
 			                      const char *reason,
 					      const char *scheme,
-					      char *buffer, size_t bufsize) _CUPS_API_1_3;
+					      char *buffer,
+					      size_t bufsize) _CUPS_API_1_3;
+
+/**** New in CUPS 1.4 ****/
+extern const char	*ppdLocalizeMarkerName(ppd_file_t *ppd,
+			                       const char *name) _CUPS_API_1_4;
 
 
 /*
diff --git a/cups/sidechannel.h b/cups/sidechannel.h
index bfe3cc0d6..e2eae6eb7 100644
--- a/cups/sidechannel.h
+++ b/cups/sidechannel.h
@@ -3,7 +3,7 @@
  *
  *   Side-channel API definitions for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -45,22 +45,26 @@ extern "C" {
  * Enumerations...
  */
 
-typedef enum				/**** Bidirectional capabilities ****/
+enum cups_sc_bidi_e			/**** Bidirectional capabilities ****/
 {
   CUPS_SC_BIDI_NOT_SUPPORTED = 0,	/* Bidirectional I/O is not supported */
   CUPS_SC_BIDI_SUPPORTED = 1		/* Bidirectional I/O is supported */
-} cups_sc_bidi_t;
+};
+typedef enum cups_sc_bidi_e cups_sc_bidi_t;
+					/**** Bidirectional capabilities ****/
 
-typedef enum				/**** Request command codes ****/
+enum cups_sc_command_e			/**** Request command codes ****/
 {
   CUPS_SC_CMD_SOFT_RESET = 1,		/* Do a soft reset */
   CUPS_SC_CMD_DRAIN_OUTPUT = 2,		/* Drain all pending output */
   CUPS_SC_CMD_GET_BIDI = 3,		/* Return bidirectional capabilities */
   CUPS_SC_CMD_GET_DEVICE_ID = 4,	/* Return the IEEE-1284 device ID */
   CUPS_SC_CMD_GET_STATE = 5		/* Return the device state */
-} cups_sc_command_t;
+};
+typedef enum cups_sc_command_e cups_sc_command_t;
+					/**** Request command codes ****/
 
-typedef enum				/**** Printer state bits ****/
+enum cups_sc_state_e			/**** Printer state bits ****/
 {
   CUPS_SC_STATE_OFFLINE = 0,		/* Device is off-line */
   CUPS_SC_STATE_ONLINE = 1,		/* Device is on-line */
@@ -70,9 +74,11 @@ typedef enum				/**** Printer state bits ****/
   CUPS_SC_STATE_MEDIA_EMPTY = 32,	/* Paper out condition */
   CUPS_SC_STATE_MARKER_LOW = 64,	/* Toner/ink low condition */
   CUPS_SC_STATE_MARKER_EMPTY = 128	/* Toner/ink out condition */
-} cups_sc_state_t;
+};
+typedef enum cups_sc_state_e cups_sc_state_t;
+					/**** Printer state bits ****/
 
-typedef enum				/**** Response status codes ****/
+enum cups_sc_status_e			/**** Response status codes ****/
 {
   CUPS_SC_STATUS_NONE,			/* No status */
   CUPS_SC_STATUS_OK,			/* Operation succeeded */
@@ -82,7 +88,9 @@ typedef enum				/**** Response status codes ****/
   CUPS_SC_STATUS_BAD_MESSAGE,		/* The command/response message was invalid */
   CUPS_SC_STATUS_TOO_BIG,		/* Response too big */
   CUPS_SC_STATUS_NOT_IMPLEMENTED	/* Command not implemented */
-} cups_sc_status_t;
+};
+typedef enum cups_sc_status_e cups_sc_status_t;
+					/**** Response status codes ****/
 
 
 /*
diff --git a/cups/tempfile.c b/cups/tempfile.c
index 5d5bd5206..30cbc0cae 100644
--- a/cups/tempfile.c
+++ b/cups/tempfile.c
@@ -3,7 +3,7 @@
  *
  *   Temp file utilities for the Common UNIX Printing System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -155,8 +155,8 @@ cupsTempFd(char *filename,		/* I - Pointer to buffer */
  * 'cupsTempFile()' - Generates a temporary filename.
  *
  * The temporary filename is returned in the filename buffer.
- * This function is deprecated - use cupsTempFd() or cupsTempFile2()
- * instead.
+ * This function is deprecated - use @link cupsTempFd@ or
+ * @link cupsTempFile2@ instead.
  *
  * @deprecated@
  */
diff --git a/cups/test.ppd b/cups/test.ppd
index 05d36c010..35682234a 100644
--- a/cups/test.ppd
+++ b/cups/test.ppd
@@ -139,7 +139,7 @@
 
 *CloseGroup: Extended
 
-*% IPP reasons (for ppdLocalizeIPPReason tests)
+*% IPP reasons for ppdLocalizeIPPReason tests
 *cupsIPPReason foo/Foo Reason: "http://foo/bar.html
 help:anchor='foo'%20bookID=Vendor%20Help
 /help/foo/bar.html"
@@ -163,6 +163,12 @@ help:anchor='foo'%20bookID=Vendor%20Help
 /help/zh/foo/bar.html"
 *End
 
+*% Marker names for ppdLocalizeMarkerName tests
+*cupsMarkerName cyan/Cyan Toner: ""
+*fr.cupsMarkerName cyan/La Toner Cyan: ""
+*zh_TW.cupsMarkerName cyan/Number 1 Cyan Toner: ""
+*zh.cupsMarkerName cyan/Number 2 Cyan Toner: ""
+
 *DefaultFont: Courier
 *Font AvantGarde-Book: Standard "(001.006S)" Standard ROM
 *Font AvantGarde-BookOblique: Standard "(001.006S)" Standard ROM
diff --git a/cups/testppd.c b/cups/testppd.c
index e88a12568..9efa851f5 100644
--- a/cups/testppd.c
+++ b/cups/testppd.c
@@ -99,6 +99,7 @@ main(int  argc,				/* I - Number of command-line arguments */
   int		conflicts;		/* Number of conflicts */
   char		*s;			/* String */
   char		buffer[8192];		/* String buffer */
+  const char	*text;			/* Localized text */
 
 
   status = 0;
@@ -235,6 +236,60 @@ main(int  argc,				/* I - Number of command-line arguments */
       status ++;
       printf("FAIL (\"%s\" instead of \"Number 1 Foo Reason\")\n", buffer);
     }
+
+   /*
+    * cupsMarkerName localization...
+    */
+
+    putenv("LANG=en");
+
+    fputs("ppdLocalizeMarkerName(bogus): ", stdout);
+
+    if ((text = ppdLocalizeMarkerName(ppd, "bogus")) != NULL)
+    {
+      status ++;
+      printf("FAIL (\"%s\" instead of NULL)\n", text);
+    }
+    else
+      puts("PASS");
+
+    fputs("ppdLocalizeMarkerName(cyan): ", stdout);
+
+    if ((text = ppdLocalizeMarkerName(ppd, "cyan")) != NULL &&
+        !strcmp(text, "Cyan Toner"))
+      puts("PASS");
+    else
+    {
+      status ++;
+      printf("FAIL (\"%s\" instead of \"Cyan Toner\")\n",
+             text ? text : "(null)");
+    }
+
+    putenv("LANG=fr");
+
+    fputs("ppdLocalizeMarkerName(fr cyan): ", stdout);
+    if ((text = ppdLocalizeMarkerName(ppd, "cyan")) != NULL &&
+        !strcmp(text, "La Toner Cyan"))
+      puts("PASS");
+    else
+    {
+      status ++;
+      printf("FAIL (\"%s\" instead of \"La Toner Cyan\")\n",
+             text ? text : "(null)");
+    }
+
+    putenv("LANG=zh_TW");
+
+    fputs("ppdLocalizeMarkerName(zh_TW cyan): ", stdout);
+    if ((text = ppdLocalizeMarkerName(ppd, "cyan")) != NULL &&
+        !strcmp(text, "Number 1 Cyan Toner"))
+      puts("PASS");
+    else
+    {
+      status ++;
+      printf("FAIL (\"%s\" instead of \"Number 1 Cyan Toner\")\n",
+             text ? text : "(null)");
+    }
   }
   else
   {
diff --git a/cups/usersys.c b/cups/usersys.c
index 64d71d22a..c8d2b2864 100644
--- a/cups/usersys.c
+++ b/cups/usersys.c
@@ -4,7 +4,7 @@
  *   User, system, and password routines for the Common UNIX Printing
  *   System (CUPS).
  *
- *   Copyright 2007 by Apple Inc.
+ *   Copyright 2007-2008 by Apple Inc.
  *   Copyright 1997-2006 by Easy Software Products.
  *
  *   These coded instructions, statements, and computer programs are the
@@ -56,7 +56,7 @@ static cups_file_t	*cups_open_client_conf(void);
  * The default encryption setting comes from the CUPS_ENCRYPTION
  * environment variable, then the ~/.cupsrc file, and finally the
  * /etc/cups/client.conf file. If not set, the default is
- * HTTP_ENCRYPT_IF_REQUESTED.
+ * @code HTTP_ENCRYPT_IF_REQUESTED@.
  */
 
 http_encryption_t			/* O - Encryption settings */
@@ -133,7 +133,7 @@ cupsEncryption(void)
 /*
  * 'cupsGetPassword()' - Get a password from the user.
  *
- * Uses the current password callback function. Returns NULL if the
+ * Uses the current password callback function. Returns @code NULL@ if the
  * user does not provide a password.
  */
 
@@ -151,7 +151,13 @@ cupsGetPassword(const char *prompt)	/* I - Prompt string */
 void
 cupsSetEncryption(http_encryption_t e)	/* I - New encryption preference */
 {
-  _cupsGlobals()->encryption = e;
+  _cups_globals_t *cg = _cupsGlobals();	/* Pointer to library globals */
+
+
+  cg->encryption = e;
+
+  if (cg->http)
+    httpEncryption(cg->http, e);
 }
 
 
@@ -266,7 +272,7 @@ cupsServer(void)
 /*
  * 'cupsSetPasswordCB()' - Set the password callback for CUPS.
  *
- * Pass NULL to restore the default (console) password callback.
+ * Pass @code NULL@ to restore the default (console) password callback.
  */
 
 void
@@ -286,7 +292,7 @@ cupsSetPasswordCB(cups_password_cb_t cb)/* I - Callback function */
  * 'cupsSetServer()' - Set the default server name.
  *
  * The "server" string can be a fully-qualified hostname, a numeric
- * IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
+ * IPv4 or IPv6 address, or a domain socket pathname. Pass @code NULL@ to
  * restore the default server name.
  */
 
@@ -319,13 +325,19 @@ cupsSetServer(const char *server)	/* I - Server name */
     cg->server[0]     = '\0';
     cg->servername[0] = '\0';
   }
+
+  if (cg->http)
+  {
+    httpClose(cg->http);
+    cg->http = NULL;
+  }
 }
 
 
 /*
  * 'cupsSetUser()' - Set the default user name.
  *
- * Pass NULL to restore the default user name.
+ * Pass @code NULL@ to restore the default user name.
  */
 
 void
diff --git a/cups/util.c b/cups/util.c
index 6dea98085..eade62f08 100644
--- a/cups/util.c
+++ b/cups/util.c
@@ -84,7 +84,10 @@ static int	cups_get_printer_uri(http_t *http, const char *name,
 /*
  * 'cupsCancelJob()' - Cancel a print job on the default server.
  *
- * Use the cupsLastError() and cupsLastErrorString() functions to get
+ * Pass @code CUPS_JOBID_ALL@ to cancel all jobs or @code CUPS_JOBID_CURRENT@
+ * to cancel the current job on the named destination.
+ *
+ * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get
  * the cause of any failure.
  */
 
@@ -92,7 +95,7 @@ int					/* O - 1 on success, 0 on failure */
 cupsCancelJob(const char *name,		/* I - Name of printer or class */
               int        job_id)	/* I - Job ID */
 {
-  return (cupsCancelJob2(CUPS_HTTP_DEFAULT, job_id, 0)
+  return (cupsCancelJob2(CUPS_HTTP_DEFAULT, name, job_id, 0)
               < IPP_REDIRECTION_OTHER_SITE);
 }
 
@@ -103,18 +106,22 @@ cupsCancelJob(const char *name,		/* I - Name of printer or class */
  * Canceled jobs remain in the job history while purged jobs are removed
  * from the job history.
  *
- * Use the cupsLastError() and cupsLastErrorString() functions to get
+ * Pass @code CUPS_JOBID_ALL@ to cancel all jobs or @code CUPS_JOBID_CURRENT@
+ * to cancel the current job on the named destination.
+ *
+ * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get
  * the cause of any failure.
  *
  * @since CUPS 1.4@
  */
 
 ipp_status_t				/* O - IPP status */
-cupsCancelJob2(http_t *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
-               int    job_id,		/* I - Job ID */
-	       int    purge)		/* I - 1 to purge, 0 to cancel */
+cupsCancelJob2(http_t     *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
+               const char *name,	/* I - Name of printer or class */
+               int        job_id,	/* I - Job ID or 0 for the current job, -1 for all jobs */
+	       int        purge)	/* I - 1 to purge, 0 to cancel */
 {
-  char		uri[HTTP_MAX_URI];	/* Job URI */
+  char		uri[HTTP_MAX_URI];	/* Job/printer URI */
   ipp_t		*request;		/* IPP request */
 
 
@@ -122,7 +129,7 @@ cupsCancelJob2(http_t *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
   * Range check input...
   */
 
-  if (job_id <= 0)
+  if (job_id < -1 || (!name && job_id == 0))
   {
     _cupsSetError(IPP_INTERNAL_ERROR, strerror(EINVAL));
     return (0);
@@ -137,25 +144,42 @@ cupsCancelJob2(http_t *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
       return (IPP_SERVICE_UNAVAILABLE);
 
  /*
-  * Build an IPP_CANCEL_JOB request, which requires the following
+  * Build an IPP_CANCEL_JOB or IPP_PURGE_JOBS request, which requires the following
   * attributes:
   *
   *    attributes-charset
   *    attributes-natural-language
-  *    job-uri
+  *    job-uri or printer-uri + job-id
   *    requesting-user-name
-  *    [purge-job]
+  *    [purge-job] or [purge-jobs]
   */
 
-  request = ippNewRequest(IPP_CANCEL_JOB);
+  request = ippNewRequest(job_id < 0 ? IPP_PURGE_JOBS : IPP_CANCEL_JOB);
 
-  snprintf(uri, sizeof(uri), "ipp://localhost/jobs/%d", job_id);
+  if (name)
+  {
+    httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL,
+                     "localhost", ippPort(), "/printers/%s", name);
+
+    ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL,
+                 uri);
+    ippAddInteger(request, IPP_TAG_OPERATION, IPP_TAG_INTEGER, "job-id",
+                  job_id);
+  }
+  else if (job_id > 0)
+  {
+    snprintf(uri, sizeof(uri), "ipp://localhost/jobs/%d", job_id);
+
+    ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "job-uri", NULL, uri);
+  }
 
-  ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "job-uri", NULL, uri);
   ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
                NULL, cupsUser());
-  if (purge)
+
+  if (purge && job_id >= 0)
     ippAddBoolean(request, IPP_TAG_OPERATION, "purge-job", 1);
+  else if (!purge && job_id < 0)
+    ippAddBoolean(request, IPP_TAG_OPERATION, "purge-jobs", 0);
 
  /*
   * Do the request...
@@ -170,15 +194,15 @@ cupsCancelJob2(http_t *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
 /*
  * 'cupsCreateJob()' - Create an empty job.
  *
- * Submit files for printing to the job using the cupsStartDocument(),
- * cupsWriteRequestData(), and cupsFinishDocument() functions.
+ * Submit files for printing to the job using the @link cupsStartDocument@,
+ * @link cupsWriteRequestData@, and @link cupsFinishDocument@ functions.
  *
  * @since CUPS 1.4@
  */
 
 int					/* O - Job ID or 0 on error */
 cupsCreateJob(
-    http_t        *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+    http_t        *http,		/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
     const char    *name,		/* I - Printer or class name */
     const char    *title,		/* I - Title of job */
     int           num_options,		/* I - Number of options */
@@ -251,11 +275,13 @@ cupsCreateJob(
 /*
  * 'cupsFinishDocument()' - Finish sending a document.
  *
+ * The document must have been started using @link cupsStartDocument@.
+ *
  * @since CUPS 1.4@
  */
 
 ipp_status_t				/* O - Status of document submission */
-cupsFinishDocument(http_t     *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsFinishDocument(http_t     *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
                    const char *name)	/* I - Printer or class name */
 {
   char	resource[1024];			/* Printer resource */
@@ -299,7 +325,7 @@ cupsFreeJobs(int        num_jobs,	/* I - Number of jobs */
 /*
  * 'cupsGetClasses()' - Get a list of printer classes from the default server.
  *
- * This function is deprecated - use cupsGetDests() instead.
+ * This function is deprecated - use @link cupsGetDests@ instead.
  *
  * @deprecated@
  */
@@ -394,12 +420,12 @@ cupsGetClasses(char ***classes)		/* O - Classes */
  * This function returns the default printer or class as defined by
  * the LPDEST or PRINTER environment variables. If these environment
  * variables are not set, the server default destination is returned.
- * Applications should use the cupsGetDests() and cupsGetDest() functions
- * to get the user-defined default printer, as this function does not
- * support the lpoptions-defined default printer.
+ * Applications should use the @link cupsGetDests@ and @link cupsGetDest@
+ * functions to get the user-defined default printer, as this function does
+ * not support the lpoptions-defined default printer.
  */
 
-const char *				/* O - Default printer or NULL */
+const char *				/* O - Default printer or @code NULL@ */
 cupsGetDefault(void)
 {
  /*
@@ -416,15 +442,15 @@ cupsGetDefault(void)
  * This function returns the default printer or class as defined by
  * the LPDEST or PRINTER environment variables. If these environment
  * variables are not set, the server default destination is returned.
- * Applications should use the cupsGetDests() and cupsGetDest() functions
- * to get the user-defined default printer, as this function does not
- * support the lpoptions-defined default printer.
+ * Applications should use the @link cupsGetDests@ and @link cupsGetDest@
+ * functions to get the user-defined default printer, as this function does
+ * not support the lpoptions-defined default printer.
  *
  * @since CUPS 1.1.21@
  */
 
-const char *				/* O - Default printer or NULL */
-cupsGetDefault2(http_t *http)		/* I - HTTP connection */
+const char *				/* O - Default printer or @code NULL@ */
+cupsGetDefault2(http_t *http)		/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
 {
   ipp_t		*request,		/* IPP Request */
 		*response;		/* IPP Response */
@@ -487,21 +513,24 @@ cupsGetDefault2(http_t *http)		/* I - HTTP connection */
 
 /*
  * 'cupsGetJobs()' - Get the jobs from the default server.
+ *
+ * A "whichjobs" value of @code CUPS_WHICHJOBS_ALL@ returns all jobs regardless
+ * of state, while @code CUPS_WHICHJOBS_ACTIVE@ returns jobs that are
+ * pending, processing, or held and @code CUPS_WHICHJOBS_COMPLETED@ returns
+ * jobs that are stopped, canceled, aborted, or completed.
  */
 
 int					/* O - Number of jobs */
 cupsGetJobs(cups_job_t **jobs,		/* O - Job data */
-            const char *mydest,		/* I - NULL = all destinations,       *
-	                                 *     otherwise show jobs for mydest */
+            const char *name,		/* I - @code NULL@ = all destinations, otherwise show jobs for mydest */
             int        myjobs,		/* I - 0 = all users, 1 = mine */
-	    int        completed)	/* I - -1 = show all, 0 = active, *
-	                                 *     1 = completed jobs         */
+	    int        whichjobs)	/* I - @code CUPS_WHICHJOBS_ALL@, @code CUPS_WHICHJOBS_ACTIVE@, or @code CUPS_WHICHJOBS_COMPLETED@ */
 {
  /*
   * Return the jobs...
   */
 
-  return (cupsGetJobs2(CUPS_HTTP_DEFAULT, jobs, mydest, myjobs, completed));
+  return (cupsGetJobs2(CUPS_HTTP_DEFAULT, jobs, name, myjobs, whichjobs));
 }
 
 
@@ -509,17 +538,20 @@ cupsGetJobs(cups_job_t **jobs,		/* O - Job data */
 /*
  * 'cupsGetJobs2()' - Get the jobs from the specified server.
  *
+ * A "whichjobs" value of @code CUPS_WHICHJOBS_ALL@ returns all jobs regardless
+ * of state, while @code CUPS_WHICHJOBS_ACTIVE@ returns jobs that are
+ * pending, processing, or held and @code CUPS_WHICHJOBS_COMPLETED@ returns
+ * jobs that are stopped, canceled, aborted, or completed.
+ *
  * @since CUPS 1.1.21@
  */
 
 int					/* O - Number of jobs */
-cupsGetJobs2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetJobs2(http_t     *http,		/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
              cups_job_t **jobs,		/* O - Job data */
-             const char *mydest,	/* I - NULL = all destinations,       *
-	                                 *     otherwise show jobs for mydest */
+             const char *name,		/* I - @code NULL@ = all destinations, otherwise show jobs for mydest */
              int        myjobs,		/* I - 0 = all users, 1 = mine */
-	     int        completed)	/* I - -1 = show all, 0 = active, *
-	                                 *     1 = completed jobs         */
+	     int        whichjobs)	/* I - @code CUPS_WHICHJOBS_ALL@, @code CUPS_WHICHJOBS_ACTIVE@, or @code CUPS_WHICHJOBS_COMPLETED@ */
 {
   int		n;			/* Number of jobs */
   ipp_t		*request,		/* IPP Request */
@@ -570,10 +602,10 @@ cupsGetJobs2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
   * Get the right URI...
   */
 
-  if (mydest)
+  if (name)
   {
     if (httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL,
-                         "localhost", 0, "/printers/%s", mydest) != HTTP_URI_OK)
+                         "localhost", 0, "/printers/%s", name) != HTTP_URI_OK)
     {
       _cupsSetError(IPP_INTERNAL_ERROR, NULL);
 
@@ -611,10 +643,10 @@ cupsGetJobs2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
   if (myjobs)
     ippAddBoolean(request, IPP_TAG_OPERATION, "my-jobs", 1);
 
-  if (completed > 0)
+  if (whichjobs == CUPS_WHICHJOBS_COMPLETED)
     ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
                  "which-jobs", NULL, "completed");
-  else if (completed < 0)
+  else if (whichjobs == CUPS_WHICHJOBS_ALL)
     ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_KEYWORD,
                  "which-jobs", NULL, "all");
 
@@ -776,7 +808,7 @@ cupsGetJobs2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
 /*
  * 'cupsGetPPD()' - Get the PPD file for a printer on the default server.
  *
- * For classes, cupsGetPPD() returns the PPD file for the first printer
+ * For classes, @code cupsGetPPD@ returns the PPD file for the first printer
  * in the class.
  */
 
@@ -804,14 +836,14 @@ cupsGetPPD(const char *name)		/* I - Printer name */
 /*
  * 'cupsGetPPD2()' - Get the PPD file for a printer from the specified server.
  *
- * For classes, cupsGetPPD2() returns the PPD file for the first printer
+ * For classes, @code cupsGetPPD2@ returns the PPD file for the first printer
  * in the class.
  *
  * @since CUPS 1.1.21@
  */
 
 const char *				/* O - Filename for PPD file */
-cupsGetPPD2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetPPD2(http_t     *http,		/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
             const char *name)		/* I - Printer name */
 {
   _cups_globals_t *cg = _cupsGlobals();	/* Pointer to library globals */
@@ -840,12 +872,16 @@ cupsGetPPD2(http_t     *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
  * the empty string, a new temporary file is created, otherwise the existing
  * file will be overwritten as needed.
  *
- * On success, HTTP_OK is returned for a new PPD file and HTTP_NOT_MODIFIED
- * if the existing PPD file is up-to-date.  Any other status is an error.
+ * On success, @code HTTP_OK@ is returned for a new PPD file and
+ * @code HTTP_NOT_MODIFIED@ if the existing PPD file is up-to-date.  Any other
+ * status is an error.
+ *
+ * For classes, @code cupsGetPPD3@ returns the PPD file for the first printer
+ * in the class.
  */
 
 http_status_t				/* O  - HTTP status */
-cupsGetPPD3(http_t     *http,		/* I  - HTTP connection or CUPS_HTTP_DEFAULT */
+cupsGetPPD3(http_t     *http,		/* I  - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
             const char *name,		/* I  - Printer name */
 	    time_t     *modtime,	/* IO - Modification time */
 	    char       *buffer,		/* I  - Filename buffer */
@@ -1026,7 +1062,7 @@ cupsGetPPD3(http_t     *http,		/* I  - HTTP connection or CUPS_HTTP_DEFAULT */
 /*
  * 'cupsGetPrinters()' - Get a list of printers from the default server.
  *
- * This function is deprecated - use cupsGetDests() instead.
+ * This function is deprecated - use @link cupsGetDests@ instead.
  *
  * @deprecated@
  */
@@ -1133,19 +1169,19 @@ cupsGetPrinters(char ***printers)	/* O - Printers */
  * 'cupsGetServerPPD()' - Get an available PPD file from the server.
  *
  * This function returns the named PPD file from the server.  The
- * list of available PPDs is provided by the IPP CUPS_GET_PPDS
+ * list of available PPDs is provided by the IPP @code CUPS_GET_PPDS@
  * operation.
  *
  * You must remove (unlink) the PPD file when you are finished with
  * it. The PPD filename is stored in a static location that will be
- * overwritten on the next call to cupsGetPPD(), cupsGetPPD2(), or
- * cupsGetServerPPD().
+ * overwritten on the next call to @link cupsGetPPD@, @link cupsGetPPD2@,
+ * or @link cupsGetServerPPD@.
  *
  * @since CUPS 1.3@
  */
 
-char *					/* O - Name of PPD file or NULL on error */
-cupsGetServerPPD(http_t     *http,	/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+char *					/* O - Name of PPD file or @code NULL@ on error */
+cupsGetServerPPD(http_t     *http,	/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
                  const char *name)	/* I - Name of PPD file ("ppd-name") */
 {
   int			fd;		/* PPD file descriptor */
@@ -1234,7 +1270,7 @@ cupsLastErrorString(void)
  * 'cupsPrintFile()' - Print a file to a printer or class on the default server.
  */
 
-int					/* O - Job ID */
+int					/* O - Job ID or 0 on error */
 cupsPrintFile(const char    *name,	/* I - Printer or class name */
               const char    *filename,	/* I - File to print */
 	      const char    *title,	/* I - Title of job */
@@ -1251,12 +1287,13 @@ cupsPrintFile(const char    *name,	/* I - Printer or class name */
 
 
 /*
- * 'cupsPrintFile2()' - Print a file to a printer or class on the specified server.
+ * 'cupsPrintFile2()' - Print a file to a printer or class on the specified
+ *                      server.
  *
  * @since CUPS 1.1.21@
  */
 
-int					/* O - Job ID */
+int					/* O - Job ID or 0 on error */
 cupsPrintFile2(
     http_t        *http,		/* I - HTTP connection */
     const char    *name,		/* I - Printer or class name */
@@ -1279,7 +1316,7 @@ cupsPrintFile2(
  *                      default server.
  */
 
-int					/* O - Job ID */
+int					/* O - Job ID or 0 on error */
 cupsPrintFiles(
     const char    *name,		/* I - Printer or class name */
     int           num_files,		/* I - Number of files */
@@ -1309,9 +1346,9 @@ cupsPrintFiles(
  * @since CUPS 1.1.21@
  */
 
-int					/* O - Job ID */
+int					/* O - Job ID or 0 on error */
 cupsPrintFiles2(
-    http_t        *http,		/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+    http_t        *http,		/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
     const char    *name,		/* I - Printer or class name */
     int           num_files,		/* I - Number of files */
     const char    **files,		/* I - File(s) to print */
@@ -1378,7 +1415,7 @@ cupsPrintFiles2(
       * Unable to open print file, cancel the job and return...
       */
 
-      cupsCancelJob2(http, job_id, 0);
+      cupsCancelJob2(http, name, job_id, 0);
       return (0);
     }
 
@@ -1397,7 +1434,7 @@ cupsPrintFiles2(
       * Unable to queue, cancel the job and return...
       */
 
-      cupsCancelJob2(http, job_id, 0);
+      cupsCancelJob2(http, name, job_id, 0);
       return (0);
     }
   }
@@ -1409,24 +1446,24 @@ cupsPrintFiles2(
 /*
  * 'cupsStartDocument()' - Add a document to a job created with cupsCreateJob().
  *
- * Use cupsWriteRequestData() to write data for the document and
- * cupsFinishDocument() to finish the document and get the submission status.
+ * Use @link cupsWriteRequestData@ to write data for the document and
+ * @link cupsFinishDocument@ to finish the document and get the submission status.
  *
- * The MIME type constants CUPS_FORMAT_AUTO, CUPS_FORMAT_PDF,
- * CUPS_FORMAT_POSTSCRIPT, CUPS_FORMAT_RAW, and CUPS_FORMAT_TEXT are provided
- * for the "format" argument, although any supported MIME type string can be
- * supplied.
+ * The MIME type constants @code CUPS_FORMAT_AUTO@, @code CUPS_FORMAT_PDF@,
+ * @code CUPS_FORMAT_POSTSCRIPT@, @code CUPS_FORMAT_RAW@, and
+ * @code CUPS_FORMAT_TEXT@ are provided for the "format" argument, although
+ * any supported MIME type string can be supplied.
  *
  * @since CUPS 1.4@
  */
 
 http_status_t				/* O - HTTP status of request */
 cupsStartDocument(
-    http_t     *http,			/* I - HTTP connection or CUPS_HTTP_DEFAULT */
+    http_t     *http,			/* I - HTTP connection or @code CUPS_HTTP_DEFAULT@ */
     const char *name,			/* I - Printer or class name */
-    int        job_id,			/* I - Job ID from cupsCreateJob() */
+    int        job_id,			/* I - Job ID from @link cupsCreateJob@ */
     const char *docname,		/* I - Name of document */
-    const char *format,			/* I - MIME type or CUPS_FORMAT_foo */
+    const char *format,			/* I - MIME type or @code CUPS_FORMAT_foo@ */
     int        last_document)		/* I - 1 for last document in job, 0 otherwise */
 {
   char		resource[1024],		/* Resource for destinatio */
diff --git a/doc/Makefile b/doc/Makefile
index 6e2260b3a..197344c15 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -54,6 +54,7 @@ HELPFILES	=	\
 			help/api-filedir.html \
 			help/api-filter.html \
 			help/api-httpipp.html \
+			help/api-overview.html \
 			help/api-ppd.html \
 			help/api-raster.html \
 			help/cgi.html \
diff --git a/doc/cups-printable.css b/doc/cups-printable.css
index 4b8bc87bd..12e7e7dbe 100644
--- a/doc/cups-printable.css
+++ b/doc/cups-printable.css
@@ -1,26 +1,37 @@
 BODY {
-  font-family: sans-serif;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
 }
 
 H1, H2, H3, H4, H5, H6, P, TD, TH {
-  font-family: sans-serif;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
 }
 
 KBD {
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
   font-weight: bold;
 }
 
 PRE {
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
 }
 
 PRE.command {
   margin-left: 36pt;
 }
 
+PRE.example {
+  background: #eeeeee;
+  border: dotted thin #999999;
+  margin-left: 36pt;
+  padding: 10px;
+}
+
+PRE.command EM, PRE.example EM {
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
 P.command {
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
   margin-left: 36pt;
 }
 
@@ -51,6 +62,7 @@ SUB, SUP {
 
 DIV.table TABLE {
   border: solid thin #999999;
+  border-collapse: collapse;
   border-spacing: 0;
   margin-left: auto;
   margin-right: auto;
@@ -134,10 +146,94 @@ DL.category DT {
 
 P.summary {
   margin-left: 36pt;
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
 }
 
 SPAN.message {
   font-style: italic;
   font-size: smaller;
 }
+
+DIV.summary TABLE {
+  border: solid thin #999999;
+  border-collapse: collapse;
+  border-spacing: 0;
+  margin: 10px;
+}
+
+DIV.summary TABLE TD, DIV.summary TABLE TH {
+  border: solid thin #999999;
+  padding: 5px;
+  text-align: left;
+  vertical-align: top;
+}
+
+DIV.summary TABLE THEAD TH {
+  background: #eeeeee;
+}
+
+/* API documentation styles... */
+div.body h1 {
+  margin: 0;
+}
+div.body h2 {
+  margin-top: 1.5em;
+}
+div.body h3, div.body h4, div.body h5 {
+  margin-bottom: 0.5em;
+  margin-top: 1.5em;
+}
+.class, .enumeration, .function, .struct, .typedef, .union {
+  border-bottom: solid thin #999999;
+  margin-bottom: 0;
+  margin-top: 2em;
+}
+.description {
+  margin-top: 0.5em;
+}
+code, p.code, pre, ul.code li {
+  font-family: monaco, courier, monospace;
+  font-size: 90%;
+}
+ul.code, ul.contents, ul.subcontents {
+  list-style-type: none;
+  margin: 0;
+  padding-left: 0;
+}
+ul.code li {
+  margin: 0;
+}
+ul.contents > li {
+  margin-top: 1em;
+}
+ul.contents li ul.code, ul.contents li ul.subcontents {
+  padding-left: 2em;
+}
+div.body dl {
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dt {
+  font-style: italic;
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dd {
+  margin-bottom: 0.5em;
+}
+
+/* This is just for the HTML files generated with the framedhelp target */
+div.contents {
+  background: #e8e8e8;
+  border: solid thin black;
+  padding: 10px;
+}
+div.contents h1 {
+  font-size: 110%;
+}
+div.contents h2 {
+  font-size: 100%;
+}
+div.contents ul.contents {
+  font-size: 80%;
+}
diff --git a/doc/cups.css b/doc/cups.css
index 6d356f6d0..935c42821 100644
--- a/doc/cups.css
+++ b/doc/cups.css
@@ -1,21 +1,21 @@
 BODY {
   background: #e8e8e8;
   color: #000000;
-  font-family: sans-serif;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
 }
 
 H1, H2, H3, H4, H5, H6, P, TD, TH {
-  font-family: sans-serif;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
 }
 
 KBD {
   color: #006600;
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
   font-weight: bold;
 }
 
 PRE {
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
 }
 
 PRE.command {
@@ -23,13 +23,21 @@ PRE.command {
   margin-left: 36pt;
 }
 
-PRE.command EM {
+PRE.example {
+  background: white;
+  border: dotted thin #999999;
+  margin-left: 36pt;
+  padding: 10px;
+}
+
+PRE.command EM, PRE.example EM {
   color: #3f0000;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
 }
 
 P.command {
   color: #7f0000;
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
   margin-left: 36pt;
 }
 
@@ -137,7 +145,7 @@ FORM {
 }
 
 INPUT[TYPE="TEXT"], TEXTAREA {
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
 }
 
 INPUT[TYPE="IMAGE"] {
@@ -164,6 +172,7 @@ TR.data TH {
 
 DIV.table TABLE {
   border: solid thin #999999;
+  border-collapse: collapse;
   border-spacing: 0;
   margin-left: auto;
   margin-right: auto;
@@ -179,12 +188,13 @@ DIV.table CAPTION {
 }
 
 DIV.table TABLE TD {
+  background: white;
   border: solid thin #bbbbbb;
   padding-top: 5pt;
 }
 
 DIV.table TABLE TH {
-  background: #bbbbbb;
+  background: #eeeeee;
   border: none;
   border-bottom: solid thin #999999;
 }
@@ -304,10 +314,80 @@ DL.category DT {
 
 P.summary {
   margin-left: 36pt;
-  font-family: monospace;
+  font-family: monaco, courier, monospace;
 }
 
 SPAN.message {
   font-style: italic;
   font-size: smaller;
 }
+
+DIV.summary TABLE {
+  border: solid thin #999999;
+  border-collapse: collapse;
+  border-spacing: 0;
+  margin: 10px;
+}
+
+DIV.summary TABLE TD, DIV.summary TABLE TH {
+  background: white;
+  border: solid thin #999999;
+  border-spacing: 0;
+  padding: 5px;
+  text-align: left;
+  vertical-align: top;
+}
+
+DIV.summary TABLE THEAD TH {
+  background: #eeeeee;
+}
+
+/* API documentation styles... */
+div.body h1 {
+  margin: 0;
+}
+div.body h2 {
+  margin-top: 1.5em;
+}
+div.body h3, div.body h4, div.body h5 {
+  margin-bottom: 0.5em;
+  margin-top: 1.5em;
+}
+.class, .enumeration, .function, .struct, .typedef, .union {
+  border-bottom: solid thin #999999;
+  margin-bottom: 0;
+  margin-top: 2em;
+}
+.description {
+  margin-top: 0.5em;
+}
+code, p.code, pre, ul.code li {
+  font-family: monaco, courier, monospace;
+  font-size: 90%;
+}
+ul.code, ul.contents, ul.subcontents {
+  list-style-type: none;
+  margin: 0;
+  padding-left: 0;
+}
+ul.code li {
+  margin: 0;
+}
+ul.contents > li {
+  margin-top: 1em;
+}
+ul.contents li ul.code, ul.contents li ul.subcontents {
+  padding-left: 2em;
+}
+div.body dl {
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dt {
+  font-style: italic;
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dd {
+  margin-bottom: 0.5em;
+}
diff --git a/doc/help/api-array.html b/doc/help/api-array.html
index aabafd45f..175f6fecd 100644
--- a/doc/help/api-array.html
+++ b/doc/help/api-array.html
@@ -2,25 +2,329 @@
 
 
 
-	Array API
-	
-	
-	
+Array API
+
+
+
 
 
+

+
+
+
Array API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/array.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+
Contents

+
 
 
-
Introduction

+
Overview

 
-
The CUPS array API provides a high-performance generic array
-container. The contents of the array container can be sorted and
-the container itself is designed for optimal speed and memory
-usage under a wide variety of conditions.

+
The CUPS array API provides a high-performance generic array container.
+The contents of the array container can be sorted and the container itself is
+designed for optimal speed and memory usage under a wide variety of conditions.
+Sorted arrays use a binary search algorithm from the last found or inserted
+element to quickly find matching elements in the array. Arrays created with the
+optional hash function can often find elements with a single lookup. The
+cups_array_t type is used when
+referring to a CUPS array.

 
 
The CUPS scheduler (cupsd) and many of the CUPS API
 functions use the array API to efficiently manage large lists of
 data.

 
-
General Usage

+
Managing Arrays

+
+
Arrays are created using either the
+cupsArrayNew or
+cupsArrayNew2 functions. The
+first function creates a new array with the specified callback function
+and user data pointer:

 
-
The <cups/array.h> header file must be
-included to use the cupsArray functions.

+
+#include <cups/array.h>
 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+static int compare_func(void *first, void *second, void *user_data);
 
-
-gcc -o myprogram myprogram.c -lcups
+void *user_data;
+cups_array_t *array = cupsArrayNew(compare_func, user_data);
 

 
-
Compatibility

+
The comparison function (type
+cups_arrayfunc_t) is called
+whenever an element is added to the array and can be NULL to
+create an unsorted array. The function returns -1 if the first element should
+come before the second, 0 if the first and second elements should have the same
+ordering, and 1 if the first element should come after the second.

 
-
All of these functions require CUPS 1.2 or higher.

-
Contents

-
-
-
Functions

-
-
-
cupsArrayAdd()

-
Description

-
Add an element to the array.
-
When adding an element to a sorted array, non-unique elements are
+
The "user_data" pointer is passed to your comparison function. Pass
+NULL if you do not need to associate the elements in your array
+with additional information.

+
+
The cupsArrayNew2 function adds
+two more arguments to support hashed lookups, which can potentially provide
+instantaneous ("O(1)") lookups in your array:

+
+
+#include <cups/array.h>
+
+#define HASH_SIZE 512 /* Size of hash table */
+
+static int compare_func(void *first, void *second, void *user_data);
+static int hash_func(void *element, void *user_data);
+
+void *user_data;
+cups_array_t *array = cupsArrayNew2(compare_func, user_data, hash_func, HASH_SIZE);
+

+
+
The hash function (type
+cups_ahash_func_t) returns a
+number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
+element and is called whenever you look up an element in the array with
+cupsArrayFind. The hash size is
+only limited by available memory, but generally should not be larger than
+16384 to realize any performance improvement.

+
+
Once you have created the array, you add elements using the
+cupsArrayAdd
+cupsArrayInsert functions.
+The first function adds an element to the array, adding the new element
+after any elements that have the same order, while the second inserts the
+element before others with the same order. For unsorted arrays,
+cupsArrayAdd appends the elemnt to
+the end of the array while
+cupsArrayInsert inserts the
+element at the beginning of the array. For example, the following code
+creates a sorted array of character strings:

+
+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
+

+
+
Elements are removed using the
+cupsArrayRemove function, for
+example:

+
+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
+
+/* Remove "Red Fish" */
+cupsArrayRemove(array, "Red Fish");
+

+
+
Finally, you free the memory used by the array using the
+cupsArrayDelete function. All
+of the memory for the array and hash table (if any) is freed, however CUPS
+does not free the elements - if necessary, you must allocate and free the
+elements yourself.

+
+
Finding and Enumerating Elements

+
+
CUPS provides several functions to find and enumerate elements in an
+array. Each one sets or updates a "current index" into the array, such that
+future lookups will start where the last one left off:

+
+

+	
cupsArrayFind

+	
Returns the first matching element .

+	
cupsArrayFirst

+	
Returns the first element in the array.

+	
cupsArrayIndex

+	
Returns the Nth element in the array.

+	
cupsArrayLast

+	
Returns the last element in the array.

+	
cupsArrayNext

+	
Returns the next element in the array.

+	
cupsArrayPrev

+	
Returns the previous element in the array.

+

+
+
Each of these functions returns NULL when there is no
+corresponding element.  For example, a simple for loop using the
+cupsArrayFirst and
+cupsArrayNext functions will
+enumerate all of the strings in our previous example:
 
+
+
+#include <cups/array.h>
+
+/* Use strcmp() to compare strings - it will ignore the user_data pointer */
+cups_array_t *array = cupsArrayNew((cups_array_func_t)strcmp, NULL);
+
+/* Add four strings to the array */
+cupsArrayAdd(array, "One Fish");
+cupsArrayAdd(array, "Two Fish");
+cupsArrayAdd(array, "Red Fish");
+cupsArrayAdd(array, "Blue Fish");
+
+/* Show all of the strings in the array */
+char *s;
+for (s = (char *)cupsArrayFirst(array); s != NULL; s = (char *)cupsArrayNext(array))
+  puts(s);
+

+
Functions

+
 CUPS 1.2 cupsArrayAdd

+
Add an element to the array.

+

+int cupsArrayAdd (

+    cups_array_t *a,

+    void *e

+);

+
Parameters

+

+
a

+
Array

+
e

+
Element

+

+
Return Value

+
1 on success, 0 on failure

+
Discussion

+
When adding an element to a sorted array, non-unique elements are
 appended at the end of the run.  For unsorted arrays, the element
 is inserted at the end of the array.
-
Syntax

-

-int

-cupsArrayAdd(
-    cups_array_t * a,
-    void * e);
-

-
Arguments

-

-
-
-
-
-
NameDescription
aArray
eElement

-
Returns

-
1 on success, 0 on failure

-
-
cupsArrayClear()

-
Description

-
Clear the array.
-
Syntax

-

-void

-cupsArrayClear(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Nothing.

-
-
cupsArrayCount()

-
Description

-
Get the number of elements in the array.
-
Syntax

-

-int

-cupsArrayCount(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Number of elements

-
-
cupsArrayCurrent()

-
Description

-
Return the current element in the array.
-
Syntax

-

-void *

-cupsArrayCurrent(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Element

-
-
cupsArrayDelete()

-
Description

-
Free all memory used by the array.
-
Syntax

-

-void

-cupsArrayDelete(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Nothing.

-
-
cupsArrayDup()

-
Description

-
Duplicate the array.
-
Syntax

-

-cups_array_t *

-cupsArrayDup(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Duplicate array

-
-
cupsArrayFind()

-
Description

-
Find an element in the array.
-
Syntax

-

-void *

-cupsArrayFind(
-    cups_array_t * a,
-    void * e);
-

-
Arguments

-

-
-
-
-
-
NameDescription
aArray
eElement

-
Returns

-
Element found or NULL

-
-
cupsArrayFirst()

-
Description

-
Get the first element in the array.
-
Syntax

-

-void *

-cupsArrayFirst(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
First element or NULL

-
-
 CUPS 1.3 cupsArrayGetIndex()

-
Description

-
Get the index of the current element.
-
-
-
Syntax

-

-int

-cupsArrayGetIndex(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Index of the current element

-
-
 CUPS 1.3 cupsArrayGetInsert()

-
Description

-
Get the index of the last inserted element.
-
-
-
Syntax

-

-int

-cupsArrayGetInsert(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Index of the last inserted element

-
-
cupsArrayIndex()

-
Description

-
Get the N-th element in the array.
-
Syntax

-

-void *

-cupsArrayIndex(
-    cups_array_t * a,
-    int n);
-

-
Arguments

-

-
-
-
-
-
NameDescription
aArray
nIndex into array, starting at 0

-
Returns

-
N-th element or NULL

-
-
cupsArrayInsert()

-
Description

-
Insert an element in the array.
-
When inserting an element in a sorted array, non-unique elements are
+
+

+
 CUPS 1.2 cupsArrayClear

+
Clear the array.

+

+void cupsArrayClear (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
 CUPS 1.2 cupsArrayCount

+
Get the number of elements in the array.

+

+int cupsArrayCount (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Number of elements

+
 CUPS 1.2 cupsArrayCurrent

+
Return the current element in the array.

+

+void *cupsArrayCurrent (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Element

+
 CUPS 1.2 cupsArrayDelete

+
Free all memory used by the array.

+

+void cupsArrayDelete (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
 CUPS 1.2 cupsArrayDup

+
Duplicate the array.

+

+cups_array_t *cupsArrayDup (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Duplicate array

+
 CUPS 1.2 cupsArrayFind

+
Find an element in the array.

+

+void *cupsArrayFind (

+    cups_array_t *a,

+    void *e

+);

+
Parameters

+

+
a

+
Array

+
e

+
Element

+

+
Return Value

+
Element found or NULL

+
 CUPS 1.2 cupsArrayFirst

+
Get the first element in the array.

+

+void *cupsArrayFirst (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
First element or NULL

+
 CUPS 1.3 cupsArrayGetIndex

+
Get the index of the current element.

+

+int cupsArrayGetIndex (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Index of the current element

+
 CUPS 1.3 cupsArrayGetInsert

+
Get the index of the last inserted element.

+

+int cupsArrayGetInsert (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Index of the last inserted element

+
 CUPS 1.2 cupsArrayIndex

+
Get the N-th element in the array.

+

+void *cupsArrayIndex (

+    cups_array_t *a,

+    int n

+);

+
Parameters

+

+
a

+
Array

+
n

+
Index into array, starting at 0

+

+
Return Value

+
N-th element or NULL

+
 CUPS 1.2 cupsArrayInsert

+
Insert an element in the array.

+

+int cupsArrayInsert (

+    cups_array_t *a,

+    void *e

+);

+
Parameters

+

+
a

+
Array

+
e

+
Element

+

+
Return Value

+
0 on failure, 1 on success

+
Discussion

+
When inserting an element in a sorted array, non-unique elements are
 inserted at the beginning of the run.  For unsorted arrays, the element
 is inserted at the beginning of the array.
-
Syntax

-

-int

-cupsArrayInsert(
-    cups_array_t * a,
-    void * e);
-

-
Arguments

-

-
-
-
-
-
NameDescription
aArray
eElement

-
Returns

-
0 on failure, 1 on success

-
-
cupsArrayLast()

-
Description

-
Get the last element in the array.
-
Syntax

-

-void *

-cupsArrayLast(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Last element or NULL

-
-
cupsArrayNew()

-
Description

-
Create a new array.
-
Syntax

-

-cups_array_t *

-cupsArrayNew(
-    cups_array_func_t f,
-    void * d);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fComparison function
dUser data

-
Returns

-
Array

-
-
 CUPS 1.3 cupsArrayNew2()

-
Description

-
Create a new array with hash.
-
-
-
Syntax

-

-cups_array_t *

-cupsArrayNew2(
-    cups_array_func_t f,
-    void * d,
-    cups_ahash_func_t h,
-    int hsize);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
fComparison function
dUser data
hHash function
hsizeHash size

-
Returns

-
Array

-
-
cupsArrayNext()

-
Description

-
Get the next element in the array.
-
Syntax

-

-void *

-cupsArrayNext(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Next element or NULL

-
-
cupsArrayPrev()

-
Description

-
Get the previous element in the array.
-
Syntax

-

-void *

-cupsArrayPrev(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
Previous element or NULL

-
-
cupsArrayRemove()

-
Description

-
Remove an element from the array.
-
Syntax

-

-int

-cupsArrayRemove(
-    cups_array_t * a,
-    void * e);
-

-
Arguments

-

-
-
-
-
-
NameDescription
aArray
eElement

-
Returns

-
1 on success, 0 on failure

-
-
cupsArrayRestore()

-
Description

-
Reset the current element to the last cupsArraySave.
-
Syntax

-

-void *

-cupsArrayRestore(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
New current element

-
-
cupsArraySave()

-
Description

-
Mark the current element for a later cupsArrayRestore.
-
The save/restore stack is guaranteed to be at least 32 elements deep.
-
Syntax

-

-int

-cupsArraySave(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
1 on success, 0 on failure

-
-
cupsArrayUserData()

-
Description

-
Return the user data for an array.
-
Syntax

-

-void *

-cupsArrayUserData(
-    cups_array_t * a);
-

-
Arguments

-

-
-
-
-
NameDescription
aArray

-
Returns

-
User data

-
-
Types

-
-
-
cups_ahash_func_t

-
Description

-
Array hash function
-
Definition

-

+
+

+
 CUPS 1.2 cupsArrayLast

+
Get the last element in the array.

+

+void *cupsArrayLast (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Last element or NULL

+
 CUPS 1.2 cupsArrayNew

+
Create a new array.

+

+cups_array_t *cupsArrayNew (

+    cups_array_func_t f,

+    void *d

+);

+
Parameters

+

+
f

+
Comparison function

+
d

+
User data

+

+
Return Value

+
Array

+
 CUPS 1.3 cupsArrayNew2

+
Create a new array with hash.

+

+cups_array_t *cupsArrayNew2 (

+    cups_array_func_t f,

+    void *d,

+    cups_ahash_func_t h,

+    int hsize

+);

+
Parameters

+

+
f

+
Comparison function

+
d

+
User data

+
h

+
Hash function

+
hsize

+
Hash size

+

+
Return Value

+
Array

+
 CUPS 1.2 cupsArrayNext

+
Get the next element in the array.

+

+void *cupsArrayNext (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Next element or NULL

+
 CUPS 1.2 cupsArrayPrev

+
Get the previous element in the array.

+

+void *cupsArrayPrev (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
Previous element or NULL

+
 CUPS 1.2 cupsArrayRemove

+
Remove an element from the array.

+

+int cupsArrayRemove (

+    cups_array_t *a,

+    void *e

+);

+
Parameters

+

+
a

+
Array

+
e

+
Element

+

+
Return Value

+
1 on success, 0 on failure

+
 CUPS 1.2 cupsArrayRestore

+
Reset the current element to the last cupsArraySave.

+

+void *cupsArrayRestore (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
New current element

+
 CUPS 1.2 cupsArraySave

+
Mark the current element for a later cupsArrayRestore.

+

+int cupsArraySave (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
1 on success, 0 on failure

+
Discussion

+
The save/restore stack is guaranteed to be at least 32 elements deep.
+
+

+
 CUPS 1.2 cupsArrayUserData

+
Return the user data for an array.

+

+void *cupsArrayUserData (

+    cups_array_t *a

+);

+
Parameters

+

+
a

+
Array

+

+
Return Value

+
User data

+
Data Types

+
cups_ahash_func_t

+
Array hash function

+

 typedef int (*cups_ahash_func_t)(void *element, void *data);
-

-
-
cups_array_func_t

-
Description

-
Array comparison function
-
Definition

-

+

+
cups_array_func_t

+
Array comparison function

+

 typedef int (*cups_array_func_t)(void *first, void *second, void *data);
-

-
-
cups_array_t

-
Description

-
CUPS array type
-
Definition

-

+

+
cups_array_t

+
CUPS array type

+

 typedef struct _cups_array_s cups_array_t;
-

+

+

 
 
diff --git a/doc/help/api-cups.html b/doc/help/api-cups.html
index c95ce89ed..e2ff9ad28 100644
--- a/doc/help/api-cups.html
+++ b/doc/help/api-cups.html
@@ -2,25 +2,391 @@
 
 
 
-	CUPS API
-	
-	
-	
+CUPS API
+
+
+
 
 
+

+
+
+
CUPS API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/cups.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: Array API

+	Programming: File and Directory APIs

+	Programming: Filter and Backend Programming

+	Programming: HTTP and IPP APIs

+	Programming: PPD API

+	Programming: Raster API

+
Contents

+
 
 
-
Introduction

+
Overview

+
+
The CUPS API provides the convenience functions needed to support
+applications, filters, printer drivers, and backends that need to interface
+with the CUPS scheduler.

 
-
The CUPS library provides a whole collection of interfaces
-needed to support the internal needs of the CUPS software as well
-as the needs of applications, filters, printer drivers, and
-backends.

+
Printers and Classes

 
-
Unlike the rest of CUPS, the CUPS API library is provided
-under the GNU Library General Public License. This means that you
-can use the CUPS API library in both proprietary and open-source
-programs.

+
Printers and classes (collections of printers) are accessed through
+the cups_dest_t structure which
+includes the name (name), instance (instance -
+a way of selected certain saved options), and the options and attributes
+associated with that destination (num_options and
+options). Destinations are created using the
+cupsGetDests function and freed
+using the cupsFreeDests function.
+The cupsGetDest function finds a
+specific destination for printing:

 
-
General Usage

+
+#include <cups/cups.h>
 
-
The <cups/cups.h> header file must be included to
-use the CUPS functions.

+cups_dest_t *dests;
+int num_dests = cupsGetDests(&dests);
+cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests);
 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+/* do something wiith dest */
 
-
-gcc -o myprogram myprogram.c -lcups
+cupsFreeDests(num_dests, dests);
 

 
-
Compatibility

+
Passing NULL to
+cupsGetDest for the destination name
+will return the default destination. Similarly, passing a NULL
+instance will return the default instance for that destination.

 
-
Unless otherwise specified, the CUPS API functions require
-CUPS 1.1 or higher.

-
Contents

-
-
-
Enumerations

-
-
-
cups_ptype_e

-
Description

-
Not a typedef'd enum so we can OR
-
Values

-

-
+
NameDescription

+
+
+
+	
+	
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Table 1: Printer Attributes
Attribute NameDescription

 
CUPS_PRINTER_AUTHENTICATED  CUPS 1.2 Printer requires authentication 
-
CUPS_PRINTER_BIND Can bind output
-
CUPS_PRINTER_BW Can do B&W printing
-
CUPS_PRINTER_CLASS Printer class
-
CUPS_PRINTER_COLLATE Can collage copies
-
CUPS_PRINTER_COLOR Can do color printing
-
CUPS_PRINTER_COMMANDS  CUPS 1.2 Printer supports maintenance commands 
-
CUPS_PRINTER_COPIES Can do copies
-
CUPS_PRINTER_COVER Can cover output
-
CUPS_PRINTER_DEFAULT Default printer on network
-
CUPS_PRINTER_DELETE  CUPS 1.2 Delete printer 
-
CUPS_PRINTER_DISCOVERED  CUPS 1.3 Printer was automatically discovered and added 
-
CUPS_PRINTER_DUPLEX Can do duplexing
-
CUPS_PRINTER_FAX Fax queue
-
CUPS_PRINTER_IMPLICIT Implicit class
-
CUPS_PRINTER_LARGE Can do D/E/A1/A0
-
CUPS_PRINTER_LOCAL Local printer or class
-
CUPS_PRINTER_MEDIUM Can do Tabloid/B/C/A3/A2
-
CUPS_PRINTER_NOT_SHARED  CUPS 1.2 Printer is not shared 
-
CUPS_PRINTER_OPTIONS ~(CLASS | REMOTE | IMPLICIT | DEFAULT | FAX | REJECTING | DELETE | NOT_SHARED | AUTHENTICATED | COMMANDS | DISCOVERED)
-
CUPS_PRINTER_PUNCH Can punch output
-
CUPS_PRINTER_REJECTING Printer is rejecting jobs
-
CUPS_PRINTER_REMOTE Remote printer or class
-
CUPS_PRINTER_SMALL Can do Letter/Legal/A4
-
CUPS_PRINTER_SORT Can sort output
-
CUPS_PRINTER_STAPLE Can staple output
-
CUPS_PRINTER_VARIABLE Can do variable sizes
-

-
-
Functions

-
-
-
cupsAddDest()

-
Description

-
Add a destination to the list of destinations.
-
This function cannot be used to add a new class or printer queue,
+
+	"auth-info-required"
+	The type of authentication required for printing to this
+	destination: "none", "username,password", "domain,username,password",
+	or "negotiate" (Kerberos)
+
+
+	"printer-info"
+	The human-readable description of the destination such as "My
+	Laser Printer".
+
+
+	"printer-is-accepting-jobs"
+	"1" if the destination is accepting new jobs, "0" if not.
+
+
+	"printer-is-shared"
+	"1" if the destination is being shared with other computers, "0" if
+	not.
+
+
+	"printer-location"
+	The human-readable location of the destination such as "Lab 4".
+
+
+	"printer-make-and-model"
+	The human-readable make and model of the destination such as "HP
+	LaserJet 4000 Series".
+
+
+	"printer-state"
+	"3" if the destination is idle, "4" if the destination is printing
+	a job, and "5" if the destination is stopped.
+
+
+	"printer-state-change-time"
+	The UNIX time when the destination entered the current state.
+
+
+	"printer-state-reasons"
+	Additional comma-delimited state keywords for the destination
+	such as "media-tray-empty-error" and "toner-low-warning".
+
+
+	"printer-type"
+	The cups_printer_t
+	value associated with the destination.
+
+
+

+
+
Options

+
+
Options are stored in arrays of
+cups_option_t structures. Each
+option has a name (name) and value (value)
+associated with it. The cups_dest_t
+num_options and options members contain the
+default options for a particular destination, along with several informational
+attributes about the destination as shown in Table 1.
+The cupsGetOption function gets
+the value for the named option. For example, the following code lists the
+available destinations and their human-readable descriptions:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dests;
+int num_dests = cupsGetDests(&dests);
+cups_dest_t *dest;
+int i;
+const char *value;
+
+for (i = num_dests, dest = dests; i > 0; i --, dest ++)
+  if (dest->instance == NULL)
+  {
+    value = cupsGetOption("printer-info", dest->num_options, dest->options);
+    printf("%s (%s)\n", dest->name, value ? value : "no description");
+  }
+
+cupsFreeDests(num_dests, dests);
+

+
+
You can create your own option arrays using the
+cupsAddOption function, which
+adds a single named option to an array:

+
+
+#include <cups/cups.h>
+
+int num_options = 0;
+cups_option_t *options = NULL;
+
+/* The returned num_options value is updated as needed */
+num_options = cupsAddOption("first", "value", num_options, &options);
+
+/* This adds a second option value */
+num_options = cupsAddOption("second", "value", num_options, &options);
+
+/* This replaces the first option we added */
+num_options = cupsAddOption("first", "new value", num_options, &options);
+

+
+
Use a for loop to copy the options from a destination:

+
+
+#include <cups/cups.h>
+
+int i;
+int num_options = 0;
+cups_option_t *options = NULL;
+cups_dest_t *dest;
+
+for (i = 0; i < dest->num_options; i ++)
+  num_options = cupsAddOption(dest->options[i].name, dest->options[i].value, num_options, &options);
+

+
+
Use the cupsFreeOptions
+function to free the options array when you are done using it:

+
+
+cupsFreeOptions(num_options, options);
+

+
+
Print Jobs

+
+
Print jobs are identified by a locally-unique job ID number from 1 to
+231-1 and have options and one or more files for printing to a
+single destination. The cupsPrintFile
+function creates a new job with one file. The following code prints the CUPS
+test page file:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+
+/* Print a single file */
+job_id = cupsPrintFile(dest->name, "/usr/share/cups/data/testprint.ps", "Test Print", num_options, options);
+

+
+
The cupsPrintFiles function
+creates a job with multiple files. The files are provided in a
+char * array:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" };
+
+/* Print three files */
+job_id = cupsPrintFiles(dest->name, 3, files, "Test Print", num_options, options);
+

+
+
Finally, the cupsCreateJob
+function creates a new job with no files in it. Files are added using the
+cupsStartDocument, 
+cupsWriteRequestData,
+and cupsFinishDocument functions.
+The following example creates a job with 10 text files for printing:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int num_options;
+cups_option_t *options;
+int job_id;
+int i;
+char buffer[1024];
+
+/* Create the job */
+job_id = cupsCreateJob(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", num_options, options);
+
+/* If the job is created, add 10 files */
+if (job_id > 0)
+{
+  for (i = 1; i <= 10; i ++)
+  {
+    snprintf(buffer, sizeof(buffer), "file%d.txt", i);
+
+    cupsStartDocument(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, CUPS_FORMAT_TEXT, i == 10);
+
+    snprintf(buffer, sizeof(buffer),
+             "File %d\n"
+             "\n"
+             "One fish,\n"
+             "Two fish,\n
+             "Red fish,\n
+             "Blue fish\n", i);
+
+    /* cupsWriteRequestData can be called as many times as needed */
+    cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, strlen(buffer));
+
+    cupsFinishDocument(CUPS_HTTP_DEFAULT, dest->name);
+  }
+}
+

+
+
Once you have created a job, you can monitor its status using the
+cupsGetJobs function, which returns
+an array of cups_job_t structures.
+Each contains the job ID (id), destination name
+(dest), title (title), and other information
+associated with the job. The job array is freed using the
+cupsFreeJobs function. The following
+example monitors a specific job ID, showing the current job state once every
+5 seconds until the job is completed:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int job_id;
+int num_jobs;
+cups_job_t *jobs;
+int i;
+ipp_jstate_t job_state = IPP_JOB_PENDING;
+ 
+while (job_state < IPP_JOB_STOPPED)
+{
+  /* Get my jobs (1) with any state (-1) */
+  num_jobs = cupsGetJobs(&jobs, dest->name, 1, -1);
+
+  /* Loop to find my job */
+  job_state = IPP_JOB_COMPLETED;
+
+  for (i = 0; i < num_jobs; i ++)
+    if (jobs[i].id == job_id)
+    {
+      job_state = jobs[i].state;
+      break;
+    }
+
+  /* Free the job array */
+  cupsFreeJobs(num_jobs, jobs);
+
+  /* Show the current state */
+  switch (job_state)
+  {
+    case IPP_JOB_PENDING :
+        printf("Job %d is pending.\n", job_id);
+        break;
+    case IPP_JOB_HELD :
+        printf("Job %d is held.\n", job_id);
+        break;
+    case IPP_JOB_PROCESSING :
+        printf("Job %d is processing.\n", job_id);
+        break;
+    case IPP_JOB_STOPPED :
+        printf("Job %d is stopped.\n", job_id);
+        break;
+    case IPP_JOB_CANCELED :
+        printf("Job %d is canceled.\n", job_id);
+        break;
+    case IPP_JOB_ABORTED :
+        printf("Job %d is aborted.\n", job_id);
+        break;
+    case IPP_JOB_COMPLETED :
+        printf("Job %d is completed.\n", job_id);
+        break;
+  }
+
+  /* Sleep if the job is not finished */
+  if (job_state < IPP_JOB_STOPPED)
+    sleep(5);
+}
+

+
+
To cancel a job, use the
+cupsCancelJob function with the
+job ID:

+
+
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int job_id;
+
+cupsCancelJob(dest->name, job_id);
+

+
+
Error Handling

+
+
If any of the CUPS API printing functions returns an error, the reason for
+that error can be found by calling the
+cupsLastError and
+cupsLastErrorString functions.
+cupsLastError returns the last IPP
+error code
+(ipp_status_t)
+that was encountered, while
+cupsLastErrorString returns
+a (localized) human-readable string that can be shown to the user. For example,
+if any of the job creation functions returns a job ID of 0, you can use
+cupsLastErrorString to show
+the reason why the job could not be created:

+
+
+#include <cups/cups.h>
+
+int job_id;
+
+if (job_id == 0)
+  puts(cupsLastErrorString());
+

+
+
Passwords and Authentication

+
+
CUPS supports authentication of any request, including submission of print
+jobs. The default mechanism for getting the username and password is to use the
+login user and a password from the console.

+
+
To support other types of applications, in particular Graphical User
+Interfaces ("GUIs"), the CUPS API provides functions to set the default
+username and to register a callback function that returns a password string.

+
+
The cupsSetPasswordCB
+function is used to set a password callback in your program. Only one
+function can be used at any time.

+
+
The cupsSetUser function sets the
+current username for authentication. This function can be called by your
+password callback function to change the current username as needed.

+
+
The following example shows a simple password callback that gets a
+username and password from the user:

+
+
+#include <cups/cups.h>
+
+const char *
+my_password_cb(const char *prompt)
+{
+  char	user[65];
+
+
+  puts(prompt);
+
+  /* Get a username from the user */
+  printf("Username: ");
+  if (fgets(user, sizeof(user), stdin) == NULL)
+    return (NULL);
+
+  /* Strip the newline from the string and set the user */
+  user[strlen(user) - 1] = '\0';
+
+  cupsSetUser(user);
+
+  /* Use getpass() to ask for the password... */
+  return (getpass("Password: "));
+}
+
+cupsSetPasswordCB(my_password_cb);
+

+
+
Similarly, a GUI could display the prompt string in a window with input
+fields for the username and password. The username should default to the
+string returned by the cupsUser
+function.

+
Functions

+
cupsAddDest

+
Add a destination to the list of destinations.

+

+int cupsAddDest (

+    const char *name,

+    const char *instance,

+    int num_dests,

+    cups_dest_t **dests

+);

+
Parameters

+

+
name

+
Destination name

+
instance

+
Instance name or NULL for none/primary

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
Return Value

+
New number of destinations

+
Discussion

+
This function cannot be used to add a new class or printer queue,
 it only adds a new container of saved options for the named
-destination or instance.
-
If the named destination already exists, the destination list is
+destination or instance.

+

+If the named destination already exists, the destination list is
 returned unchanged.  Adding a new instance of a destination creates
-a copy of that destination's options.
-
Use the cupsSaveDests() function to save the updated list of
-destinations to the user's lpoptions file.
-
Syntax

-

-int

-cupsAddDest(
-    const char * name,
-    const char * instance,
-    int num_dests,
-    cups_dest_t ** dests);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nameDestination name
instanceInstance name or NULL for none/primary
num_destsNumber of destinations
destsDestinations

-
Returns

-
New number of destinations

-
-
cupsAddOption()

-
Description

-
Add an option to an option array.
-
Syntax

-

-int

-cupsAddOption(
-    const char * name,
-    const char * value,
-    int num_options,
-    cups_option_t ** options);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nameName of option
valueValue of option
num_optionsNumber of options
optionsPointer to options

-
Returns

-
Number of options

-
-
cupsCancelJob()

-
Description

-
Cancel a print job on the default server.
-
Use the cupsLastError() and cupsLastErrorString() functions to get
+a copy of that destination's options.

+

+Use the cupsSaveDests function to save the updated list of
+destinations to the user's lpoptions file.

+
cupsAddOption

+
Add an option to an option array.

+

+int cupsAddOption (

+    const char *name,

+    const char *value,

+    int num_options,

+    cups_option_t **options

+);

+
Parameters

+

+
name

+
Name of option

+
value

+
Value of option

+
num_options

+
Number of options

+
options

+
Pointer to options

+

+
Return Value

+
Number of options

+
Discussion

+
New option arrays can be initialized simply by passing 0 for the
+"num_options" parameter.

+
cupsCancelJob

+
Cancel a print job on the default server.

+

+int cupsCancelJob (

+    const char *name,

+    int job_id

+);

+
Parameters

+

+
name

+
Name of printer or class

+
job_id

+
Job ID

+

+
Return Value

+
1 on success, 0 on failure

+
Discussion

+
Pass CUPS_JOBID_ALL to cancel all jobs or CUPS_JOBID_CURRENT
+to cancel the current job on the named destination.

+

+Use the cupsLastError and cupsLastErrorString functions to get
+the cause of any failure.

+
 CUPS 1.4 cupsCancelJob2

+
Cancel or purge a print job.

+

+ipp_status_t cupsCancelJob2 (

+    http_t *http,

+    const char *name,

+    int job_id,

+    int purge

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Name of printer or class

+
job_id

+
Job ID or 0 for the current job, -1 for all jobs

+
purge

+
1 to purge, 0 to cancel

+

+
Return Value

+
IPP status

+
Discussion

+
Canceled jobs remain in the job history while purged jobs are removed
+from the job history.

+

+Pass CUPS_JOBID_ALL to cancel all jobs or CUPS_JOBID_CURRENT
+to cancel the current job on the named destination.

+

+Use the cupsLastError and cupsLastErrorString functions to get
 the cause of any failure.
-
Syntax

-

-int

-cupsCancelJob(
-    const char * name,
-    int job);
-

-
Arguments

-

-
-
-
-
-
NameDescription
nameName of printer or class
jobJob ID

-
Returns

-
1 on success, 0 on failure

-
-
cupsEncryption()

-
Description

-
Get the default encryption settings.
-
The default encryption setting comes from the CUPS_ENCRYPTION
+
+

+
 CUPS 1.4 cupsCreateJob

+
Create an empty job.

+

+int cupsCreateJob (

+    http_t *http,

+    const char *name,

+    const char *title,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer or class name

+
title

+
Title of job

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Job ID or 0 on error

+
Discussion

+
Submit files for printing to the job using the cupsStartDocument,
+cupsWriteRequestData, and cupsFinishDocument functions.
+
+

+
cupsEncryption

+
Get the default encryption settings.

+

+http_encryption_t cupsEncryption (void);

+
Return Value

+
Encryption settings

+
Discussion

+
The default encryption setting comes from the CUPS_ENCRYPTION
 environment variable, then the ~/.cupsrc file, and finally the
 /etc/cups/client.conf file. If not set, the default is
-HTTP_ENCRYPT_IF_REQUESTED.
-
Syntax

-

-http_encryption_t

-cupsEncryption(void);
-

-
Arguments

-
None.

-
Returns

-
Encryption settings

-
-
cupsFreeDests()

-
Description

-
Free the memory used by the list of destinations.
-
Syntax

-

-void

-cupsFreeDests(
-    int num_dests,
-    cups_dest_t * dests);
-

-
Arguments

-

-
-
-
-
-
NameDescription
num_destsNumber of destinations
destsDestinations

-
Returns

-
Nothing.

-
-
cupsFreeJobs()

-
Description

-
Free memory used by job data.
-
Syntax

-

-void

-cupsFreeJobs(
-    int num_jobs,
-    cups_job_t * jobs);
-

-
Arguments

-

-
-
-
-
-
NameDescription
num_jobsNumber of jobs
jobsJobs

-
Returns

-
Nothing.

-
-
cupsFreeOptions()

-
Description

-
Free all memory used by options.
-
Syntax

-

-void

-cupsFreeOptions(
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
NameDescription
num_optionsNumber of options
optionsPointer to options

-
Returns

-
Nothing.

-
-
 DEPRECATED cupsGetClasses()

-
Description

-
Get a list of printer classes from the default server.
-
This function is deprecated - use cupsGetDests() instead.
-
-
-
Syntax

-

-int

-cupsGetClasses(
-    char *** classes);
-

-
Arguments

-

-
-
-
-
NameDescription
classesClasses

-
Returns

-
Number of classes

-
-
cupsGetDefault()

-
Description

-
Get the default printer or class for the default server.
-
This function returns the default printer or class as defined by
+HTTP_ENCRYPT_IF_REQUESTED.

+
 CUPS 1.4 cupsFinishDocument

+
Finish sending a document.

+

+ipp_status_t cupsFinishDocument (

+    http_t *http,

+    const char *name

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer or class name

+

+
Return Value

+
Status of document submission

+
Discussion

+
The document must have been started using cupsStartDocument.
+
+

+
cupsFreeDests

+
Free the memory used by the list of destinations.

+

+void cupsFreeDests (

+    int num_dests,

+    cups_dest_t *dests

+);

+
Parameters

+

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
cupsFreeJobs

+
Free memory used by job data.

+

+void cupsFreeJobs (

+    int num_jobs,

+    cups_job_t *jobs

+);

+
Parameters

+

+
num_jobs

+
Number of jobs

+
jobs

+
Jobs

+

+
cupsFreeOptions

+
Free all memory used by options.

+

+void cupsFreeOptions (

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
num_options

+
Number of options

+
options

+
Pointer to options

+

+
 DEPRECATED cupsGetClasses

+
Get a list of printer classes from the default server.

+

+int cupsGetClasses (

+    char ***classes

+);

+
Parameters

+

+
classes

+
Classes

+

+
Return Value

+
Number of classes

+
Discussion

+
This function is deprecated - use cupsGetDests instead.
+
+

+
cupsGetDefault

+
Get the default printer or class for the default server.

+

+const char *cupsGetDefault (void);

+
Return Value

+
Default printer or NULL

+
Discussion

+
This function returns the default printer or class as defined by
 the LPDEST or PRINTER environment variables. If these environment
 variables are not set, the server default destination is returned.
-Applications should use the cupsGetDests() and cupsGetDest() functions
-to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.
-
Syntax

-

-const char *

-cupsGetDefault(void);
-

-
Arguments

-
None.

-
Returns

-
Default printer or NULL

-
-
 CUPS 1.1.21 cupsGetDefault2()

-
Description

-
Get the default printer or class for the specified server.
-
This function returns the default printer or class as defined by
+Applications should use the cupsGetDests and cupsGetDest
+functions to get the user-defined default printer, as this function does
+not support the lpoptions-defined default printer.

+
 CUPS 1.1.21 cupsGetDefault2

+
Get the default printer or class for the specified server.

+

+const char *cupsGetDefault2 (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+

+
Return Value

+
Default printer or NULL

+
Discussion

+
This function returns the default printer or class as defined by
 the LPDEST or PRINTER environment variables. If these environment
 variables are not set, the server default destination is returned.
-Applications should use the cupsGetDests() and cupsGetDest() functions
-to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.
-
-
-
Syntax

-

-const char *

-cupsGetDefault2(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Default printer or NULL

-
-
cupsGetDest()

-
Description

-
Get the named destination from the list.
-
Use the cupsGetDests() or cupsGetDests2() functions to get a
-list of supported destinations for the current user.
-
Syntax

-

-cups_dest_t *

-cupsGetDest(
-    const char * name,
-    const char * instance,
-    int num_dests,
-    cups_dest_t * dests);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nameDestination name or NULL for the default destination
instanceInstance name or NULL
num_destsNumber of destinations
destsDestinations

-
Returns

-
Destination pointer or NULL

-
-
cupsGetDests()

-
Description

-
Get the list of destinations from the default server.
-
Starting with CUPS 1.2, the returned list of destinations include the
+Applications should use the cupsGetDests and cupsGetDest
+functions to get the user-defined default printer, as this function does
+not support the lpoptions-defined default printer.
+
+

+
cupsGetDest

+
Get the named destination from the list.

+

+cups_dest_t *cupsGetDest (

+    const char *name,

+    const char *instance,

+    int num_dests,

+    cups_dest_t *dests

+);

+
Parameters

+

+
name

+
Destination name or NULL for the default destination

+
instance

+
Instance name or NULL

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
Return Value

+
Destination pointer or NULL

+
Discussion

+
Use the cupsGetDests or cupsGetDests2 functions to get a
+list of supported destinations for the current user.

+
cupsGetDests

+
Get the list of destinations from the default server.

+

+int cupsGetDests (

+    cups_dest_t **dests

+);

+
Parameters

+

+
dests

+
Destinations

+

+
Return Value

+
Number of destinations

+
Discussion

+
Starting with CUPS 1.2, the returned list of destinations include the
 printer-info, printer-is-accepting-jobs, printer-is-shared,
 printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.
-
Use the cupsFreeDests() function to free the destination list and
-the cupsGetDest() function to find a particular destination.
-
Syntax

-

-int

-cupsGetDests(
-    cups_dest_t ** dests);
-

-
Arguments

-

-
-
-
-
NameDescription
destsDestinations

-
Returns

-
Number of destinations

-
-
 CUPS 1.1.21 cupsGetDests2()

-
Description

-
Get the list of destinations from the specified server.
-
Starting with CUPS 1.2, the returned list of destinations include the
+printer-state-reasons, and printer-type attributes as options.

+

+Use the cupsFreeDests function to free the destination list and
+the cupsGetDest function to find a particular destination.

+
 CUPS 1.1.21 cupsGetDests2

+
Get the list of destinations from the specified server.

+

+int cupsGetDests2 (

+    http_t *http,

+    cups_dest_t **dests

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
dests

+
Destinations

+

+
Return Value

+
Number of destinations

+
Discussion

+
Starting with CUPS 1.2, the returned list of destinations include the
 printer-info, printer-is-accepting-jobs, printer-is-shared,
 printer-make-and-model, printer-state, printer-state-change-time,
-printer-state-reasons, and printer-type attributes as options.
-
Use the cupsFreeDests() function to free the destination list and
-the cupsGetDest() function to find a particular destination.
-
-
-
Syntax

-

-int

-cupsGetDests2(
-    http_t * http,
-    cups_dest_t ** dests);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
destsDestinations

-
Returns

-
Number of destinations

-
-
 CUPS 1.1.20 cupsGetFd()

-
Description

-
Get a file from the server.
-
This function returns HTTP_OK when the file is successfully retrieved.
-
-
-
Syntax

-

-http_status_t

-cupsGetFd(
-    http_t * http,
-    const char * resource,
-    int fd);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
resourceResource name
fdFile descriptor

-
Returns

-
HTTP status

-
-
 CUPS 1.1.20 cupsGetFile()

-
Description

-
Get a file from the server.
-
This function returns HTTP_OK when the file is successfully retrieved.
-
-
-
Syntax

-

-http_status_t

-cupsGetFile(
-    http_t * http,
-    const char * resource,
-    const char * filename);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
resourceResource name
filenameFilename

-
Returns

-
HTTP status

-
-
cupsGetJobs()

-
Description

-
Get the jobs from the default server.
-
Syntax

-

-int

-cupsGetJobs(
-    cups_job_t ** jobs,
-    const char * mydest,
-    int myjobs,
-    int completed);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
jobsJob data
mydestNULL = all destinations,       *
-otherwise show jobs for mydest
myjobs0 = all users, 1 = mine
completed-1 = show all, 0 = active, *
-1 = completed jobs

-
Returns

-
Number of jobs

-
-
 CUPS 1.1.21 cupsGetJobs2()

-
Description

-
Get the jobs from the specified server.
-
-
-
Syntax

-

-int

-cupsGetJobs2(
-    http_t * http,
-    cups_job_t ** jobs,
-    const char * mydest,
-    int myjobs,
-    int completed);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection
jobsJob data
mydestNULL = all destinations,       *
-otherwise show jobs for mydest
myjobs0 = all users, 1 = mine
completed-1 = show all, 0 = active, *
-1 = completed jobs

-
Returns

-
Number of jobs

-
-
cupsGetOption()

-
Description

-
Get an option value.
-
Syntax

-

-const char *

-cupsGetOption(
-    const char * name,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
nameName of option
num_optionsNumber of options
optionsOptions

-
Returns

-
Option value or NULL

-
-
cupsGetPPD()

-
Description

-
Get the PPD file for a printer on the default server.
-
For classes, cupsGetPPD() returns the PPD file for the first printer
-in the class.
-
Syntax

-

-const char *

-cupsGetPPD(
-    const char * name);
-

-
Arguments

-

-
-
-
-
NameDescription
namePrinter name

-
Returns

-
Filename for PPD file

-
-
 CUPS 1.1.21 cupsGetPPD2()

-
Description

-
Get the PPD file for a printer from the specified server.
-
For classes, cupsGetPPD2() returns the PPD file for the first printer
-in the class.
+printer-state-reasons, and printer-type attributes as options.

+

+Use the cupsFreeDests function to free the destination list and
+the cupsGetDest function to find a particular destination.
 
+

+
 CUPS 1.1.20 cupsGetFd

+
Get a file from the server.

+

+http_status_t cupsGetFd (

+    http_t *http,

+    const char *resource,

+    int fd

+);

+
Parameters

+

+
http

+
HTTP connection to server or CUPS_HTTP_DEFAULT

+
resource

+
Resource name

+
fd

+
File descriptor

+

+
Return Value

+
HTTP status

+
Discussion

+
This function returns HTTP_OK when the file is successfully retrieved.
 
-
Syntax

-

-const char *

-cupsGetPPD2(
-    http_t * http,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
namePrinter name

-
Returns

-
Filename for PPD file

-
-
cupsGetPPD3()

-
Description

-
Get the PPD file for a printer on the specified
-server if it has changed.
-
The "modtime" parameter contains the modification time of any
+

+
 CUPS 1.1.20 cupsGetFile

+
Get a file from the server.

+

+http_status_t cupsGetFile (

+    http_t *http,

+    const char *resource,

+    const char *filename

+);

+
Parameters

+

+
http

+
HTTP connection to server or CUPS_HTTP_DEFAULT

+
resource

+
Resource name

+
filename

+
Filename

+

+
Return Value

+
HTTP status

+
Discussion

+
This function returns HTTP_OK when the file is successfully retrieved.
+
+

+
cupsGetJobs

+
Get the jobs from the default server.

+

+int cupsGetJobs (

+    cups_job_t **jobs,

+    const char *name,

+    int myjobs,

+    int whichjobs

+);

+
Parameters

+

+
jobs

+
Job data

+
name

+
NULL = all destinations, otherwise show jobs for mydest

+
myjobs

+
0 = all users, 1 = mine

+
whichjobs

+
CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED

+

+
Return Value

+
Number of jobs

+
Discussion

+
A "whichjobs" value of CUPS_WHICHJOBS_ALL returns all jobs regardless
+of state, while CUPS_WHICHJOBS_ACTIVE returns jobs that are
+pending, processing, or held and CUPS_WHICHJOBS_COMPLETED returns
+jobs that are stopped, canceled, aborted, or completed.

+
 CUPS 1.1.21 cupsGetJobs2

+
Get the jobs from the specified server.

+

+int cupsGetJobs2 (

+    http_t *http,

+    cups_job_t **jobs,

+    const char *name,

+    int myjobs,

+    int whichjobs

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
jobs

+
Job data

+
name

+
NULL = all destinations, otherwise show jobs for mydest

+
myjobs

+
0 = all users, 1 = mine

+
whichjobs

+
CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED

+

+
Return Value

+
Number of jobs

+
Discussion

+
A "whichjobs" value of CUPS_WHICHJOBS_ALL returns all jobs regardless
+of state, while CUPS_WHICHJOBS_ACTIVE returns jobs that are
+pending, processing, or held and CUPS_WHICHJOBS_COMPLETED returns
+jobs that are stopped, canceled, aborted, or completed.
+
+

+
 CUPS 1.4 cupsGetNamedDest

+
Get options for the named destination.

+

+cups_dest_t *cupsGetNamedDest (

+    http_t *http,

+    const char *name,

+    const char *instance

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Destination name or NULL

+
instance

+
Instance name or NULL

+

+
Return Value

+
Destination or NULL

+
Discussion

+
This function is optimized for retrieving a single destination and should
+be used instead of cupsGetDests and cupsGetDest when you either
+know the name of the destination or want to print to the default destination.
+If NULL is returned, the destination does not exist or there is no
+default destination.

+

+If "http" is CUPS_HTTP_DEFAULT, the connection to the default print
+server will be used.

+

+If "name" is NULL, the default printer for the current user will be
+returned.

+

+The returned destination must be freed using cupsFreeDests with a
+"num_dests" value of 1.
+
+

+
cupsGetOption

+
Get an option value.

+

+const char *cupsGetOption (

+    const char *name,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
name

+
Name of option

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Option value or NULL

+
cupsGetPPD

+
Get the PPD file for a printer on the default server.

+

+const char *cupsGetPPD (

+    const char *name

+);

+
Parameters

+

+
name

+
Printer name

+

+
Return Value

+
Filename for PPD file

+
Discussion

+
For classes, cupsGetPPD returns the PPD file for the first printer
+in the class.

+
 CUPS 1.1.21 cupsGetPPD2

+
Get the PPD file for a printer from the specified server.

+

+const char *cupsGetPPD2 (

+    http_t *http,

+    const char *name

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer name

+

+
Return Value

+
Filename for PPD file

+
Discussion

+
For classes, cupsGetPPD2 returns the PPD file for the first printer
+in the class.
+
+

+
cupsGetPPD3

+
Get the PPD file for a printer on the specified
+server if it has changed.

+

+http_status_t cupsGetPPD3 (

+    http_t *http,

+    const char *name,

+    time_t *modtime,

+    char *buffer,

+    size_t bufsize

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer name

+
modtime

+
Modification time

+
buffer

+
Filename buffer

+
bufsize

+
Size of filename buffer

+

+
Return Value

+
HTTP status

+
Discussion

+
The "modtime" parameter contains the modification time of any
 locally-cached content and is updated with the time from the PPD file on
-the server.
-
The "buffer" parameter contains the local PPD filename.  If it contains
+the server.

+

+The "buffer" parameter contains the local PPD filename.  If it contains
 the empty string, a new temporary file is created, otherwise the existing
-file will be overwritten as needed.
-
On success, HTTP_OK is returned for a new PPD file and HTTP_NOT_MODIFIED
-if the existing PPD file is up-to-date.  Any other status is an error.
-
Syntax

-

-http_status_t

-cupsGetPPD3(
-    http_t * http,
-    const char * name,
-    time_t * modtime,
-    char * buffer,
-    size_t bufsize);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection
namePrinter name
modtimeModification time
bufferFilename buffer
bufsizeSize of filename buffer

-
Returns

-
HTTP status

-
-
cupsGetPassword()

-
Description

-
Get a password from the user.
-
Uses the current password callback function. Returns NULL if the
-user does not provide a password.
-
Syntax

-

-const char *

-cupsGetPassword(
-    const char * prompt);
-

-
Arguments

-

-
-
-
-
NameDescription
promptPrompt string

-
Returns

-
Password

-
-
 DEPRECATED cupsGetPrinters()

-
Description

-
Get a list of printers from the default server.
-
This function is deprecated - use cupsGetDests() instead.
-
-
-
Syntax

-

-int

-cupsGetPrinters(
-    char *** printers);
-

-
Arguments

-

-
-
-
-
NameDescription
printersPrinters

-
Returns

-
Number of printers

-
-
 CUPS 1.3 cupsGetServerPPD()

-
Description

-
Get an available PPD file from the server.
-
This function returns the named PPD file from the server.  The
-list of available PPDs is provided by the IPP CUPS_GET_PPDS
-operation.
-
You must remove (unlink) the PPD file when you are finished with
+file will be overwritten as needed.

+

+On success, HTTP_OK is returned for a new PPD file and
+HTTP_NOT_MODIFIED if the existing PPD file is up-to-date.  Any other
+status is an error.

+

+For classes, cupsGetPPD3 returns the PPD file for the first printer
+in the class.

+
cupsGetPassword

+
Get a password from the user.

+

+const char *cupsGetPassword (

+    const char *prompt

+);

+
Parameters

+

+
prompt

+
Prompt string

+

+
Return Value

+
Password

+
Discussion

+
Uses the current password callback function. Returns NULL if the
+user does not provide a password.

+
 DEPRECATED cupsGetPrinters

+
Get a list of printers from the default server.

+

+int cupsGetPrinters (

+    char ***printers

+);

+
Parameters

+

+
printers

+
Printers

+

+
Return Value

+
Number of printers

+
Discussion

+
This function is deprecated - use cupsGetDests instead.
+
+

+
 CUPS 1.3 cupsGetServerPPD

+
Get an available PPD file from the server.

+

+char *cupsGetServerPPD (

+    http_t *http,

+    const char *name

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Name of PPD file ("ppd-name")

+

+
Return Value

+
Name of PPD file or NULL on error

+
Discussion

+
This function returns the named PPD file from the server.  The
+list of available PPDs is provided by the IPP CUPS_GET_PPDS
+operation.

+

+You must remove (unlink) the PPD file when you are finished with
 it. The PPD filename is stored in a static location that will be
-overwritten on the next call to cupsGetPPD(), cupsGetPPD2(), or
-cupsGetServerPPD().
-
-
-
Syntax

-

-char *

-cupsGetServerPPD(
-    http_t * http,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
nameName of PPD file ("ppd-name")

-
Returns

-
Name of PPD file or NULL on error

-
-
cupsLangDefault()

-
Description

-
Return the default language.
-
Syntax

-

-cups_lang_t *

-cupsLangDefault(void);
-

-
Arguments

-
None.

-
Returns

-
Language data

-
-
cupsLangEncoding()

-
Description

-
Return the character encoding (us-ascii, etc.)
-for the given language.
-
Syntax

-

-const char *

-cupsLangEncoding(
-    cups_lang_t * lang);
-

-
Arguments

-

-
-
-
-
NameDescription
langLanguage data

-
Returns

-
Character encoding

-
-
cupsLangFlush()

-
Description

-
Flush all language data out of the cache.
-
Syntax

-

-void

-cupsLangFlush(void);
-

-
Arguments

-
None.

-
Returns

-
Nothing.

-
-
cupsLangFree()

-
Description

-
Free language data.
-
This does not actually free anything; use cupsLangFlush() for that.
-
Syntax

-

-void

-cupsLangFree(
-    cups_lang_t * lang);
-

-
Arguments

-

-
-
-
-
NameDescription
langLanguage to free

-
Returns

-
Nothing.

-
-
cupsLangGet()

-
Description

-
Get a language.
-
Syntax

-

-cups_lang_t *

-cupsLangGet(
-    const char * language);
-

-
Arguments

-

-
-
-
-
NameDescription
languageLanguage or locale

-
Returns

-
Language data

-
-
cupsLastError()

-
Description

-
Return the last IPP status code.
-
Syntax

-

-ipp_status_t

-cupsLastError(void);
-

-
Arguments

-
None.

-
Returns

-
IPP status code from last request

-
-
 CUPS 1.2 cupsLastErrorString()

-
Description

-
Return the last IPP status-message.
-
-
-
Syntax

-

-const char *

-cupsLastErrorString(void);
-

-
Arguments

-
None.

-
Returns

-
status-message text from last request

-
-
cupsMarkOptions()

-
Description

-
Mark command-line options in a PPD file.
-
Syntax

-

-int

-cupsMarkOptions(
-    ppd_file_t * ppd,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file
num_optionsNumber of options
optionsOptions

-
Returns

-
1 if conflicting

-
-
 CUPS 1.2 cupsNotifySubject()

-
Description

-
Return the subject for the given notification message.
-
The returned string must be freed by the caller using free().
-
-
-
Syntax

-

-char *

-cupsNotifySubject(
-    cups_lang_t * lang,
-    ipp_t * event);
-

-
Arguments

-

-
-
-
-
-
NameDescription
langLanguage data
eventEvent data

-
Returns

-
Subject string or NULL

-
-
 CUPS 1.2 cupsNotifyText()

-
Description

-
Return the text for the given notification message.
-
The returned string must be freed by the caller using free().
-
-
-
Syntax

-

-char *

-cupsNotifyText(
-    cups_lang_t * lang,
-    ipp_t * event);
-

-
Arguments

-

-
-
-
-
-
NameDescription
langLanguage data
eventEvent data

-
Returns

-
Message text or NULL

-
-
cupsParseOptions()

-
Description

-
Parse options from a command-line argument.
-
This function converts space-delimited name/value pairs according
+overwritten on the next call to cupsGetPPD, cupsGetPPD2,
+or cupsGetServerPPD.
+
+

+
cupsLangDefault

+
Return the default language.

+

+cups_lang_t *cupsLangDefault (void);

+
Return Value

+
Language data

+
cupsLangEncoding

+
Return the character encoding (us-ascii, etc.)
+for the given language.

+

+const char *cupsLangEncoding (

+    cups_lang_t *lang

+);

+
Parameters

+

+
lang

+
Language data

+

+
Return Value

+
Character encoding

+
cupsLangFlush

+
Flush all language data out of the cache.

+

+void cupsLangFlush (void);

+
cupsLangFree

+
Free language data.

+

+void cupsLangFree (

+    cups_lang_t *lang

+);

+
Parameters

+

+
lang

+
Language to free

+

+
Discussion

+
This does not actually free anything; use cupsLangFlush for that.

+
cupsLangGet

+
Get a language.

+

+cups_lang_t *cupsLangGet (

+    const char *language

+);

+
Parameters

+

+
language

+
Language or locale

+

+
Return Value

+
Language data

+
cupsLastError

+
Return the last IPP status code.

+

+ipp_status_t cupsLastError (void);

+
Return Value

+
IPP status code from last request

+
 CUPS 1.2 cupsLastErrorString

+
Return the last IPP status-message.

+

+const char *cupsLastErrorString (void);

+
Return Value

+
status-message text from last request

+
 CUPS 1.2 cupsNotifySubject

+
Return the subject for the given notification message.

+

+char *cupsNotifySubject (

+    cups_lang_t *lang,

+    ipp_t *event

+);

+
Parameters

+

+
lang

+
Language data

+
event

+
Event data

+

+
Return Value

+
Subject string or NULL

+
Discussion

+
The returned string must be freed by the caller using free().
+
+

+
 CUPS 1.2 cupsNotifyText

+
Return the text for the given notification message.

+

+char *cupsNotifyText (

+    cups_lang_t *lang,

+    ipp_t *event

+);

+
Parameters

+

+
lang

+
Language data

+
event

+
Event data

+

+
Return Value

+
Message text or NULL

+
Discussion

+
The returned string must be freed by the caller using free.
+
+

+
cupsParseOptions

+
Parse options from a command-line argument.

+

+int cupsParseOptions (

+    const char *arg,

+    int num_options,

+    cups_option_t **options

+);

+
Parameters

+

+
arg

+
Argument to parse

+
num_options

+
Number of options

+
options

+
Options found

+

+
Return Value

+
Number of options found

+
Discussion

+
This function converts space-delimited name/value pairs according
 to the PAPI text option ABNF specification. Collection values
 ("name={a=... b=... c=...}") are stored with the curley brackets
-intact - use cupsParseOptions() on the value to extract the collection
-attributes.
-
Syntax

-

-int

-cupsParseOptions(
-    const char * arg,
-    int num_options,
-    cups_option_t ** options);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
argArgument to parse
num_optionsNumber of options
optionsOptions found

-
Returns

-
Number of options found

-
-
cupsPrintFile()

-
Description

-
Print a file to a printer or class on the default server.
-
Syntax

-

-int

-cupsPrintFile(
-    const char * name,
-    const char * filename,
-    const char * title,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
namePrinter or class name
filenameFile to print
titleTitle of job
num_optionsNumber of options
optionsOptions

-
Returns

-
Job ID

-
-
 CUPS 1.1.21 cupsPrintFile2()

-
Description

-
Print a file to a printer or class on the specified server.
-
-
-
Syntax

-

-int

-cupsPrintFile2(
-    http_t * http,
-    const char * name,
-    const char * filename,
-    const char * title,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection
namePrinter or class name
filenameFile to print
titleTitle of job
num_optionsNumber of options
optionsOptions

-
Returns

-
Job ID

-
-
cupsPrintFiles()

-
Description

-
Print one or more files to a printer or class on the
-default server.
-
Syntax

-

-int

-cupsPrintFiles(
-    const char * name,
-    int num_files,
-    const char ** files,
-    const char * title,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
namePrinter or class name
num_filesNumber of files
filesFile(s) to print
titleTitle of job
num_optionsNumber of options
optionsOptions

-
Returns

-
Job ID

-
-
 CUPS 1.1.21 cupsPrintFiles2()

-
Description

-
Print one or more files to a printer or class on the
-specified server.
-
-
-
Syntax

-

-int

-cupsPrintFiles2(
-    http_t * http,
-    const char * name,
-    int num_files,
-    const char ** files,
-    const char * title,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection
namePrinter or class name
num_filesNumber of files
filesFile(s) to print
titleTitle of job
num_optionsNumber of options
optionsOptions

-
Returns

-
Job ID

-
-
 CUPS 1.1.20 cupsPutFd()

-
Description

-
Put a file on the server.
-
This function returns HTTP_CREATED when the file is stored successfully.
-
-
-
Syntax

-

-http_status_t

-cupsPutFd(
-    http_t * http,
-    const char * resource,
-    int fd);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
resourceResource name
fdFile descriptor

-
Returns

-
HTTP status

-
-
 CUPS 1.1.20 cupsPutFile()

-
Description

-
Put a file on the server.
-
This function returns HTTP_CREATED when the file is stored successfully.
-
-
-
Syntax

-

-http_status_t

-cupsPutFile(
-    http_t * http,
-    const char * resource,
-    const char * filename);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
resourceResource name
filenameFilename

-
Returns

-
HTTP status

-
-
 CUPS 1.3 cupsRemoveDest()

-
Description

-
Remove a destination from the destination list.
-
Removing a destination/instance does not delete the class or printer
+intact - use cupsParseOptions on the value to extract the
+collection attributes.

+
cupsPrintFile

+
Print a file to a printer or class on the default server.

+

+int cupsPrintFile (

+    const char *name,

+    const char *filename,

+    const char *title,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
name

+
Printer or class name

+
filename

+
File to print

+
title

+
Title of job

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Job ID or 0 on error

+
 CUPS 1.1.21 cupsPrintFile2

+
Print a file to a printer or class on the specified
+server.

+

+int cupsPrintFile2 (

+    http_t *http,

+    const char *name,

+    const char *filename,

+    const char *title,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
http

+
HTTP connection

+
name

+
Printer or class name

+
filename

+
File to print

+
title

+
Title of job

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Job ID or 0 on error

+
cupsPrintFiles

+
Print one or more files to a printer or class on the
+default server.

+

+int cupsPrintFiles (

+    const char *name,

+    int num_files,

+    const char **files,

+    const char *title,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
name

+
Printer or class name

+
num_files

+
Number of files

+
files

+
File(s) to print

+
title

+
Title of job

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Job ID or 0 on error

+
 CUPS 1.1.21 cupsPrintFiles2

+
Print one or more files to a printer or class on the
+specified server.

+

+int cupsPrintFiles2 (

+    http_t *http,

+    const char *name,

+    int num_files,

+    const char **files,

+    const char *title,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer or class name

+
num_files

+
Number of files

+
files

+
File(s) to print

+
title

+
Title of job

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
Job ID or 0 on error

+
 CUPS 1.1.20 cupsPutFd

+
Put a file on the server.

+

+http_status_t cupsPutFd (

+    http_t *http,

+    const char *resource,

+    int fd

+);

+
Parameters

+

+
http

+
HTTP connection to server or CUPS_HTTP_DEFAULT

+
resource

+
Resource name

+
fd

+
File descriptor

+

+
Return Value

+
HTTP status

+
Discussion

+
This function returns HTTP_CREATED when the file is stored
+successfully.
+
+

+
 CUPS 1.1.20 cupsPutFile

+
Put a file on the server.

+

+http_status_t cupsPutFile (

+    http_t *http,

+    const char *resource,

+    const char *filename

+);

+
Parameters

+

+
http

+
HTTP connection to server or CUPS_HTTP_DEFAULT

+
resource

+
Resource name

+
filename

+
Filename

+

+
Return Value

+
HTTP status

+
Discussion

+
This function returns HTTP_CREATED when the file is stored
+successfully.
+
+

+
 CUPS 1.3 cupsRemoveDest

+
Remove a destination from the destination list.

+

+int cupsRemoveDest (

+    const char *name,

+    const char *instance,

+    int num_dests,

+    cups_dest_t **dests

+);

+
Parameters

+

+
name

+
Destination name

+
instance

+
Instance name or NULL

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
Return Value

+
New number of destinations

+
Discussion

+
Removing a destination/instance does not delete the class or printer
 queue, merely the lpoptions for that destination/instance.  Use the
-cupsSetDests() or cupsSetDests2() functions to save the new options
-for the user.
-
-
-
Syntax

-

-int

-cupsRemoveDest(
-    const char * name,
-    const char * instance,
-    int num_dests,
-    cups_dest_t ** dests);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nameDestination name
instanceInstance name or NULL
num_destsNumber of destinations
destsDestinations

-
Returns

-
New number of destinations

-
-
 CUPS 1.2 cupsRemoveOption()

-
Description

-
Remove an option from an option array.
-
-
-
Syntax

-

-int

-cupsRemoveOption(
-    const char * name,
-    int num_options,
-    cups_option_t ** options);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
nameOption name
num_optionsCurrent number of options
optionsOptions

-
Returns

-
New number of options

-
-
cupsServer()

-
Description

-
Return the hostname/address of the default server.
-
The returned value can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname.
-
Syntax

-

-const char *

-cupsServer(void);
-

-
Arguments

-
None.

-
Returns

-
Server name

-
-
 CUPS 1.3 cupsSetDefaultDest()

-
Description

-
Set the default destination.
-
-
-
Syntax

-

-void

-cupsSetDefaultDest(
-    const char * name,
-    const char * instance,
-    int num_dests,
-    cups_dest_t * dests);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nameDestination name
instanceInstance name or NULL
num_destsNumber of destinations
destsDestinations

-
Returns

-
Nothing.

-
-
cupsSetDests()

-
Description

-
Save the list of destinations for the default server.
-
This function saves the destinations to /etc/cups/lpoptions when run
-as root and ~/.cups/lpoptions when run as a normal user.
-
Syntax

-

-void

-cupsSetDests(
-    int num_dests,
-    cups_dest_t * dests);
-

-
Arguments

-

-
-
-
-
-
NameDescription
num_destsNumber of destinations
destsDestinations

-
Returns

-
Nothing.

-
-
 CUPS 1.1.21 cupsSetDests2()

-
Description

-
Save the list of destinations for the specified server.
-
This function saves the destinations to /etc/cups/lpoptions when run
+cupsSetDests or cupsSetDests2 functions to save the new
+options for the user.
+
+

+
 CUPS 1.2 cupsRemoveOption

+
Remove an option from an option array.

+

+int cupsRemoveOption (

+    const char *name,

+    int num_options,

+    cups_option_t **options

+);

+
Parameters

+

+
name

+
Option name

+
num_options

+
Current number of options

+
options

+
Options

+

+
Return Value

+
New number of options

+
cupsServer

+
Return the hostname/address of the default server.

+

+const char *cupsServer (void);

+
Return Value

+
Server name

+
Discussion

+
The returned value can be a fully-qualified hostname, a numeric
+IPv4 or IPv6 address, or a domain socket pathname.

+
 CUPS 1.3 cupsSetDefaultDest

+
Set the default destination.

+

+void cupsSetDefaultDest (

+    const char *name,

+    const char *instance,

+    int num_dests,

+    cups_dest_t *dests

+);

+
Parameters

+

+
name

+
Destination name

+
instance

+
Instance name or NULL

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
cupsSetDests

+
Save the list of destinations for the default server.

+

+void cupsSetDests (

+    int num_dests,

+    cups_dest_t *dests

+);

+
Parameters

+

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
Discussion

+
This function saves the destinations to /etc/cups/lpoptions when run
+as root and ~/.cups/lpoptions when run as a normal user.

+
 CUPS 1.1.21 cupsSetDests2

+
Save the list of destinations for the specified server.

+

+int cupsSetDests2 (

+    http_t *http,

+    int num_dests,

+    cups_dest_t *dests

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
num_dests

+
Number of destinations

+
dests

+
Destinations

+

+
Return Value

+
0 on success, -1 on error

+
Discussion

+
This function saves the destinations to /etc/cups/lpoptions when run
 as root and ~/.cups/lpoptions when run as a normal user.
 
+

+
cupsSetEncryption

+
Set the encryption preference.

+

+void cupsSetEncryption (

+    http_encryption_t e

+);

+
Parameters

+

+
e

+
New encryption preference

+

+
cupsSetPasswordCB

+
Set the password callback for CUPS.

+

+void cupsSetPasswordCB (

+    cups_password_cb_t cb

+);

+
Parameters

+

+
cb

+
Callback function

+

+
Discussion

+
Pass NULL to restore the default (console) password callback.

+
cupsSetServer

+
Set the default server name.

+

+void cupsSetServer (

+    const char *server

+);

+
Parameters

+

+
server

+
Server name

+

+
Discussion

+
The "server" string can be a fully-qualified hostname, a numeric
+IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
+restore the default server name.

+
cupsSetUser

+
Set the default user name.

+

+void cupsSetUser (

+    const char *user

+);

+
Parameters

+

+
user

+
User name

+

+
Discussion

+
Pass NULL to restore the default user name.

+
 CUPS 1.4 cupsStartDocument

+
Add a document to a job created with cupsCreateJob().

+

+http_status_t cupsStartDocument (

+    http_t *http,

+    const char *name,

+    int job_id,

+    const char *docname,

+    const char *format,

+    int last_document

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
name

+
Printer or class name

+
job_id

+
Job ID from cupsCreateJob

+
docname

+
Name of document

+
format

+
MIME type or CUPS_FORMAT_foo

+
last_document

+
1 for last document in job, 0 otherwise

+

+
Return Value

+
HTTP status of request

+
Discussion

+
Use cupsWriteRequestData to write data for the document and
+cupsFinishDocument to finish the document and get the submission status.

+

+The MIME type constants CUPS_FORMAT_AUTO, CUPS_FORMAT_PDF,
+CUPS_FORMAT_POSTSCRIPT, CUPS_FORMAT_RAW, and
+CUPS_FORMAT_TEXT are provided for the "format" argument, although
+any supported MIME type string can be supplied.
 
-
Syntax

-

-int

-cupsSetDests2(
-    http_t * http,
-    int num_dests,
-    cups_dest_t * dests);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
num_destsNumber of destinations
destsDestinations

-
Returns

-
0 on success, -1 on error

-
-
cupsSetEncryption()

-
Description

-
Set the encryption preference.
-
Syntax

-

-void

-cupsSetEncryption(
-    http_encryption_t e);
-

-
Arguments

-

-
-
-
-
NameDescription
eNew encryption preference

-
Returns

-
Nothing.

-
-
cupsSetPasswordCB()

-
Description

-
Set the password callback for CUPS.
-
Pass NULL to restore the default (console) password callback.
-
Syntax

-

-void

-cupsSetPasswordCB(
-    cups_password_cb_t cb);
-

-
Arguments

-

-
-
-
-
NameDescription
cbCallback function

-
Returns

-
Nothing.

-
-
cupsSetServer()

-
Description

-
Set the default server name.
-
The "server" string can be a fully-qualified hostname, a numeric
-IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to
-restore the default server name.
-
Syntax

-

-void

-cupsSetServer(
-    const char * server);
-

-
Arguments

-

-
-
-
-
NameDescription
serverServer name

-
Returns

-
Nothing.

-
-
cupsSetUser()

-
Description

-
Set the default user name.
-
Pass NULL to restore the default user name.
-
Syntax

-

-void

-cupsSetUser(
-    const char * user);
-

-
Arguments

-

-
-
-
-
NameDescription
userUser name

-
Returns

-
Nothing.

-
-
cupsTempFd()

-
Description

-
Creates a temporary file.
-
The temporary filename is returned in the filename buffer.
-The temporary file is opened for reading and writing.
-
Syntax

-

-int

-cupsTempFd(
-    char * filename,
-    int len);
-

-
Arguments

-

-
-
-
-
-
NameDescription
filenamePointer to buffer
lenSize of buffer

-
Returns

-
New file descriptor or -1 on error

-
-
 DEPRECATED cupsTempFile()

-
Description

-
Generates a temporary filename.
-
The temporary filename is returned in the filename buffer.
-This function is deprecated - use cupsTempFd() or cupsTempFile2()
-instead.
-
-
-
Syntax

-

-char *

-cupsTempFile(
-    char * filename,
-    int len);
-

-
Arguments

-

-
-
-
-
-
NameDescription
filenamePointer to buffer
lenSize of buffer

-
Returns

-
Filename or NULL on error

-
-
 CUPS 1.2 cupsTempFile2()

-
Description

-
Creates a temporary CUPS file.
-
The temporary filename is returned in the filename buffer.
-The temporary file is opened for writing.
+

+
cupsTempFd

+
Creates a temporary file.

+

+int cupsTempFd (

+    char *filename,

+    int len

+);

+
Parameters

+

+
filename

+
Pointer to buffer

+
len

+
Size of buffer

+

+
Return Value

+
New file descriptor or -1 on error

+
Discussion

+
The temporary filename is returned in the filename buffer.
+The temporary file is opened for reading and writing.

+
 DEPRECATED cupsTempFile

+
Generates a temporary filename.

+

+char *cupsTempFile (

+    char *filename,

+    int len

+);

+
Parameters

+

+
filename

+
Pointer to buffer

+
len

+
Size of buffer

+

+
Return Value

+
Filename or NULL on error

+
Discussion

+
The temporary filename is returned in the filename buffer.
+This function is deprecated - use cupsTempFd or
+cupsTempFile2 instead.
 
+

+
 CUPS 1.2 cupsTempFile2

+
Creates a temporary CUPS file.

+

+cups_file_t *cupsTempFile2 (

+    char *filename,

+    int len

+);

+
Parameters

+

+
filename

+
Pointer to buffer

+
len

+
Size of buffer

+

+
Return Value

+
CUPS file or NULL on error

+
Discussion

+
The temporary filename is returned in the filename buffer.
+The temporary file is opened for writing.
 
-
Syntax

-

-cups_file_t *

-cupsTempFile2(
-    char * filename,
-    int len);
-

-
Arguments

-

-
-
-
-
-
NameDescription
filenamePointer to buffer
lenSize of buffer

-
Returns

-
CUPS file or NULL on error

-
-
cupsUser()

-
Description

-
Return the current user's name.
-
Syntax

-

-const char *

-cupsUser(void);
-

-
Arguments

-
None.

-
Returns

-
User name

-
-
Structures

-
-
-
cups_dest_s

-
Description

-
Destination
-
Definition

-

-struct cups_dest_s

-{

-  char *name, * instance;

-  int is_default;

-  int num_options;

-  cups_option_t * options;

-};

-
Members

-

-
-
-
-
-
-
-
NameDescription
instance Local instance name or NULL
-
is_default Is this printer the default?
-
num_options Number of options
-
options Options
-

-
-
cups_job_s

-
Description

-
Job
-
Definition

-

-struct cups_job_s

-{

-  time_t completed_time;

-  time_t creation_time;

-  char * dest;

-  char * format;

-  int id;

-  int priority;

-  time_t processing_time;

-  int size;

-  ipp_jstate_t state;

-  char * title;

-  char * user;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
completed_time Time the job was completed
-
creation_time Time the job was created
-
dest Printer or class name
-
format Document format
-
id The job ID
-
priority Priority (1-100)
-
processing_time Time the job was processed
-
size Size in kilobytes
-
state Job state
-
title Title/job name
-
user User the submitted the job
-

-
-
cups_option_s

-
Description

-
Printer Options
-
Definition

-

-struct cups_option_s

-{

-  char * name;

-  char * value;

-};

-
Members

-

-
-
-
-
-
NameDescription
name Name of option
-
value Value of option
-

-
-
Types

-
-
-
cups_dest_t

-
Description

-
Destination
-
Definition

-

-typedef struct cups_dest_s cups_dest_t;
-

-
-
cups_job_t

-
Description

-
Job
-
Definition

-

-typedef struct cups_job_s cups_job_t;
-

-
-
cups_option_t

-
Description

-
Printer Options
-
Definition

-

-typedef struct cups_option_s cups_option_t;
-

-
-
cups_password_cb_t

-
Description

-
Password callback
-
Definition

-

-typedef const char * (*cups_password_cb_t)(const char *);
-

-
-
cups_ptype_t

-
Description

-
Printer Type/Capability Bits
-
Definition

-

+

+
cupsUser

+
Return the current user's name.

+

+const char *cupsUser (void);

+
Return Value

+
User name

+
Data Types

+
cups_dest_t

+
Destination

+

+typedef struct cups_dest_s cups_dest_t;
+

+
cups_job_t

+
Job

+

+typedef struct cups_job_s cups_job_t;
+

+
cups_option_t

+
Printer Options

+

+typedef struct cups_option_s cups_option_t;
+

+
cups_password_cb_t

+
Password callback

+

+typedef const char *(*cups_password_cb_t)(const char *);
+

+
cups_ptype_t

+
Printer type/capability bits

+

 typedef unsigned cups_ptype_t;
-

+

+
Structures

+
cups_dest_s

+
Destination

+
struct cups_dest_s {

+    char *name, *instance;

+    int is_default;

+    int num_options;

+    cups_option_t *options;

+};

+
Members

+

+
instance 

+
Local instance name or NULL

+
is_default 

+
Is this printer the default?

+
num_options 

+
Number of options

+
options 

+
Options

+

+
cups_job_s

+
Job

+
struct cups_job_s {

+    time_t completed_time;

+    time_t creation_time;

+    char *dest;

+    char *format;

+    int id;

+    int priority;

+    time_t processing_time;

+    int size;

+    ipp_jstate_t state;

+    char *title;

+    char *user;

+};

+
Members

+

+
completed_time 

+
Time the job was completed

+
creation_time 

+
Time the job was created

+
dest 

+
Printer or class name

+
format 

+
Document format

+
id 

+
The job ID

+
priority 

+
Priority (1-100)

+
processing_time 

+
Time the job was processed

+
size 

+
Size in kilobytes

+
state 

+
Job state

+
title 

+
Title/job name

+
user 

+
User the submitted the job

+

+
cups_option_s

+
Printer Options

+
struct cups_option_s {

+    char *name;

+    char *value;

+};

+
Members

+

+
name 

+
Name of option

+
value 

+
Value of option

+

+
Constants

+
cups_ptype_e

+
Printer type/capability bit constants

+
Constants

+

+
CUPS_PRINTER_AUTHENTICATED  CUPS 1.2 

+
Printer requires authentication 

+
CUPS_PRINTER_BIND 

+
Can bind output

+
CUPS_PRINTER_BW 

+
Can do B&W printing

+
CUPS_PRINTER_CLASS 

+
Printer class

+
CUPS_PRINTER_COLLATE 

+
Can collage copies

+
CUPS_PRINTER_COLOR 

+
Can do color printing

+
CUPS_PRINTER_COMMANDS  CUPS 1.2 

+
Printer supports maintenance commands 

+
CUPS_PRINTER_COPIES 

+
Can do copies

+
CUPS_PRINTER_COVER 

+
Can cover output

+
CUPS_PRINTER_DEFAULT 

+
Default printer on network

+
CUPS_PRINTER_DELETE  CUPS 1.2 

+
Delete printer 

+
CUPS_PRINTER_DISCOVERED  CUPS 1.3 

+
Printer was automatically discovered and added 

+
CUPS_PRINTER_DUPLEX 

+
Can do duplexing

+
CUPS_PRINTER_FAX 

+
Fax queue

+
CUPS_PRINTER_IMPLICIT 

+
Implicit class

+
CUPS_PRINTER_LARGE 

+
Can do D/E/A1/A0

+
CUPS_PRINTER_LOCAL 

+
Local printer or class

+
CUPS_PRINTER_MEDIUM 

+
Can do Tabloid/B/C/A3/A2

+
CUPS_PRINTER_NOT_SHARED  CUPS 1.2 

+
Printer is not shared 

+
CUPS_PRINTER_PUNCH 

+
Can punch output

+
CUPS_PRINTER_REJECTING 

+
Printer is rejecting jobs

+
CUPS_PRINTER_REMOTE 

+
Remote printer or class

+
CUPS_PRINTER_SMALL 

+
Can do Letter/Legal/A4

+
CUPS_PRINTER_SORT 

+
Can sort output

+
CUPS_PRINTER_STAPLE 

+
Can staple output

+
CUPS_PRINTER_VARIABLE 

+
Can do variable sizes

+

+
 
 
diff --git a/doc/help/api-filedir.html b/doc/help/api-filedir.html
index b4c6c43ad..8c35624ce 100644
--- a/doc/help/api-filedir.html
+++ b/doc/help/api-filedir.html
@@ -2,25 +2,342 @@
 
 
 
-	File and Directory APIs
-	
-	
-	
+File and Directory APIs
+
+
+
 
 
+

+
+
+
File and Directory APIs

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headerscups/file.h

+	cups/dir.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+
Contents

+
 
 
-
Introduction

+
Overview

 
 
The CUPS file and directory APIs provide portable interfaces
 for manipulating files and listing files and directories. Unlike
-stdio FILE streams, the cupsFile functions
+stdio FILE streams, the cupsFile functions
 allow you to open more than 256 files at any given time. They
 also manage the platform-specific details of locking, large file
 support, line endings (CR, LF, or CR LF), and reading and writing
 files using Flate ("gzip") compression. Finally, you can also
 connect, read from, and write to network connections using the
-cupsFile functions.

+cupsFile functions.

 
-
The cupsDir functions manage the platform-specific
+
The cupsDir functions manage the platform-specific
 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.

+
Functions

+
 CUPS 1.2 cupsDirClose

+
Close a directory.

+

+void cupsDirClose (

+    cups_dir_t *dp

+);

+
Parameters

+

+
dp

+
Directory pointer

+

+
 CUPS 1.2 cupsDirOpen

+
Open a directory.

+

+cups_dir_t *cupsDirOpen (

+    const char *directory

+);

+
Parameters

+

+
directory

+
Directory name

+

+
Return Value

+
Directory pointer or NULL if the directory could not be opened.

+
 CUPS 1.2 cupsDirRead

+
Read the next directory entry.

+

+cups_dentry_t *cupsDirRead (

+    cups_dir_t *dp

+);

+
Parameters

+

+
dp

+
Directory pointer

+

+
Return Value

+
Directory entry or NULL when there are no more

+
 CUPS 1.2 cupsDirRewind

+
Rewind to the start of the directory.

+

+void cupsDirRewind (

+    cups_dir_t *dp

+);

+
Parameters

+

+
dp

+
Directory pointer

+

+
 CUPS 1.2 cupsFileClose

+
Close a CUPS file.

+

+int cupsFileClose (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
0 on success, -1 on error

+
 CUPS 1.2 cupsFileCompression

+
Return whether a file is compressed.

+

+int cupsFileCompression (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
CUPS_FILE_NONE or CUPS_FILE_GZIP

+
 CUPS 1.2 cupsFileEOF

+
Return the end-of-file status.

+

+int cupsFileEOF (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
1 on end of file, 0 otherwise

+
 CUPS 1.2 cupsFileFind

+
Find a file using the specified path.

+

+const char *cupsFileFind (

+    const char *filename,

+    const char *path,

+    int executable,

+    char *buffer,

+    int bufsize

+);

+
Parameters

+

+
filename

+
File to find

+
path

+
Colon/semicolon-separated path

+
executable

+
1 = executable files, 0 = any file/dir

+
buffer

+
Filename buffer

+
bufsize

+
Size of filename buffer

+

+
Return Value

+
Full path to file or NULL if not found

+
Discussion

+
This function allows the paths in the path string to be separated by
+colons (UNIX standard) or semicolons (Windows standard) and stores the
+result in the buffer supplied.  If the file cannot be found in any of
+the supplied paths, NULL is returned. A NULL path only
+matches the current directory.
 
-
The CUPS scheduler (cupsd), mailto notifier,
-and many of the CUPS API functions use these functions for
-everything except console (stdin, stdout, stderr) I/O.

-
-
General Usage

-
-
The <cups/dir.h> and
-<cups/file.h> header files must be included to
-use the cupsDir and cupsFile functions,
-respectively.

+

+
 CUPS 1.2 cupsFileFlush

+
Flush pending output.

+

+int cupsFileFlush (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
0 on success, -1 on error

+
 CUPS 1.2 cupsFileGetChar

+
Get a single character from a file.

+

+int cupsFileGetChar (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
Character or -1 on end of file

+
 CUPS 1.2 cupsFileGetConf

+
Get a line from a configuration file...

+

+char *cupsFileGetConf (

+    cups_file_t *fp,

+    char *buf,

+    size_t buflen,

+    char **value,

+    int *linenum

+);

+
Parameters

+

+
fp

+
CUPS file

+
buf

+
String buffer

+
buflen

+
Size of string buffer

+
value

+
Pointer to value

+
linenum

+
Current line number

+

+
Return Value

+
Line read or NULL on end of file or error

+
 CUPS 1.2 cupsFileGetLine

+
Get a CR and/or LF-terminated line that may
+contain binary data.

+

+size_t cupsFileGetLine (

+    cups_file_t *fp,

+    char *buf,

+    size_t buflen

+);

+
Parameters

+

+
fp

+
File to read from

+
buf

+
Buffer

+
buflen

+
Size of buffer

+

+
Return Value

+
Number of bytes on line or 0 on end of file

+
Discussion

+
This function differs from cupsFileGets in that the trailing CR
+and LF are preserved, as is any binary data on the line. The buffer is
+nul-terminated, however you should use the returned length to determine
+the number of bytes on the line.
 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+

+
 CUPS 1.2 cupsFileGets

+
Get a CR and/or LF-terminated line.

+

+char *cupsFileGets (

+    cups_file_t *fp,

+    char *buf,

+    size_t buflen

+);

+
Parameters

+

+
fp

+
CUPS file

+
buf

+
String buffer

+
buflen

+
Size of string buffer

+

+
Return Value

+
Line read or NULL on end of file or error

+
 CUPS 1.2 cupsFileLock

+
Temporarily lock access to a file.

+

+int cupsFileLock (

+    cups_file_t *fp,

+    int block

+);

+
Parameters

+

+
fp

+
CUPS file

+
block

+
1 to wait for the lock, 0 to fail right away

+

+
Return Value

+
0 on success, -1 on error

+
 CUPS 1.2 cupsFileNumber

+
Return the file descriptor associated with a CUPS file.

+

+int cupsFileNumber (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
File descriptor

+
 CUPS 1.2 cupsFileOpen

+
Open a CUPS file.

+

+cups_file_t *cupsFileOpen (

+    const char *filename,

+    const char *mode

+);

+
Parameters

+

+
filename

+
Name of file

+
mode

+
Open mode

+

+
Return Value

+
CUPS file or NULL if the file or socket cannot be opened

+
Discussion

+
The "mode" parameter can be "r" to read, "w" to write, overwriting any
+existing file, "a" to append to an existing file or create a new file,
+or "s" to open a socket connection.

+

+When opening for writing ("w") or appending ("a"), an optional number from
+1 to 9 can be supplied which enables Flate compression of the file.

+

+When opening a socket connection, the filename is a string of the form
+"address:port" or "hostname:port". The socket will make an IPv4 or IPv6
+connection as needed, generally preferring IPv6 connections when there is
+a choice.
 
-
-gcc -o myprogram myprogram.c -lcups
-

+

+
 CUPS 1.2 cupsFileOpenFd

+
Open a CUPS file using a file descriptor.

+

+cups_file_t *cupsFileOpenFd (

+    int fd,

+    const char *mode

+);

+
Parameters

+

+
fd

+
File descriptor

+
mode

+
Open mode

+

+
Return Value

+
CUPS file or NULL if the file could not be opened

+
Discussion

+
The "mode" parameter can be "r" to read, "a" or "w" to write, or "s"
+to treat the file descriptor as a bidirectional socket connection.

+

+When opening for writing ("w") or appending ("a"), an optional number from
+1 to 9 can be supplied which enables Flate compression of the file.
 
-
Compatibility

+

+
 CUPS 1.2 cupsFilePeekChar

+
Peek at the next character from a file.

+

+int cupsFilePeekChar (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
Character or -1 on end of file

+
 CUPS 1.2 cupsFilePrintf

+
Write a formatted string.

+

+int cupsFilePrintf (

+    cups_file_t *fp,

+    const char *format,

+    ...

+);

+
Parameters

+

+
fp

+
CUPS file

+
format

+
Printf-style format string

+
...

+
Additional args as necessary

+

+
Return Value

+
Number of bytes written or -1 on error

+
 CUPS 1.2 cupsFilePutChar

+
Write a character.

+

+int cupsFilePutChar (

+    cups_file_t *fp,

+    int c

+);

+
Parameters

+

+
fp

+
CUPS file

+
c

+
Character to write

+

+
Return Value

+
0 on success, -1 on error

+
 CUPS 1.2 cupsFilePuts

+
Write a string.

+

+int cupsFilePuts (

+    cups_file_t *fp,

+    const char *s

+);

+
Parameters

+

+
fp

+
CUPS file

+
s

+
String to write

+

+
Return Value

+
Number of bytes written or -1 on error

+
Discussion

+
Like the fputs function, no newline is appended to the string.
 
-
All of these functions require CUPS 1.2 or higher.

-
Contents

-
-
-
Functions

-
-
-
cupsDirClose()

-
Description

-
Close a directory.
-
Syntax

-

-void

-cupsDirClose(
-    cups_dir_t * dp);
-

-
Arguments

-

-
-
-
-
NameDescription
dpDirectory

-
Returns

-
Nothing.

-
-
cupsDirOpen()

-
Description

-
Open a directory.
-
Syntax

-

-cups_dir_t *

-cupsDirOpen(
-    const char * directory);
-

-
Arguments

-

-
-
-
-
NameDescription
directoryDirectory name

-
Returns

-
Directory

-
-
cupsDirRead()

-
Description

-
Read the next directory entry.
-
Syntax

-

-cups_dentry_t *

-cupsDirRead(
-    cups_dir_t * dp);
-

-
Arguments

-

-
-
-
-
NameDescription
dpDirectory

-
Returns

-
Directory entry

-
-
cupsDirRewind()

-
Description

-
Rewind to the start of the directory.
-
Syntax

-

-void

-cupsDirRewind(
-    cups_dir_t * dp);
-

-
Arguments

-

-
-
-
-
NameDescription
dpDirectory

-
Returns

-
Nothing.

-
-
cupsFileClose()

-
Description

-
Close a CUPS file.
-
Syntax

-

-int

-cupsFileClose(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
0 on success, -1 on error

-
-
cupsFileCompression()

-
Description

-
Return whether a file is compressed.
-
Syntax

-

-int

-cupsFileCompression(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
CUPS_FILE_NONE or CUPS_FILE_GZIP

-
-
cupsFileEOF()

-
Description

-
Return the end-of-file status.
-
Syntax

-

-int

-cupsFileEOF(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
1 on EOF, 0 otherwise

-
-
cupsFileFind()

-
Description

-
Find a file using the specified path.
-
This function allows the paths in the path string to be separated by
-colons (UNIX standard) or semicolons (Windows standard) and stores the
-result in the buffer supplied.  If the file cannot be found in any of
-the supplied paths, NULL is returned. A NULL path only matches the
-current directory.
-
Syntax

-

-const char *

-cupsFileFind(
-    const char * filename,
-    const char * path,
-    int executable,
-    char * buffer,
-    int bufsize);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
filenameFile to find
pathColon/semicolon-separated path
executable1 = executable files, 0 = any file/dir
bufferFilename buffer
bufsizeSize of filename buffer

-
Returns

-
Full path to file or NULL

-
-
cupsFileFlush()

-
Description

-
Flush pending output.
-
Syntax

-

-int

-cupsFileFlush(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
0 on success, -1 on error

-
-
cupsFileGetChar()

-
Description

-
Get a single character from a file.
-
Syntax

-

-int

-cupsFileGetChar(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
Character or -1 on EOF

-
-
cupsFileGetConf()

-
Description

-
Get a line from a configuration file...
-
Syntax

-

-char *

-cupsFileGetConf(
-    cups_file_t * fp,
-    char * buf,
-    size_t buflen,
-    char ** value,
-    int * linenum);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
fpCUPS file
bufString buffer
buflenSize of string buffer
valuePointer to value
linenumCurrent line number

-
Returns

-
Line read or NULL on eof/error

-
-
cupsFileGetLine()

-
Description

-
Get a CR and/or LF-terminated line that may
-contain binary data.
-
This function differs from cupsFileGets() in that the trailing CR and LF
-are preserved, as is any binary data on the line. The buffer is nul-
-terminated, however you should use the returned length to determine
-the number of bytes on the line.
-
Syntax

-

-size_t

-cupsFileGetLine(
-    cups_file_t * fp,
-    char * buf,
-    size_t buflen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
fpFile to read from
bufBuffer
buflenSize of buffer

-
Returns

-
Number of bytes on line or 0 on EOF

-
-
cupsFileGets()

-
Description

-
Get a CR and/or LF-terminated line.
-
Syntax

-

-char *

-cupsFileGets(
-    cups_file_t * fp,
-    char * buf,
-    size_t buflen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
fpCUPS file
bufString buffer
buflenSize of string buffer

-
Returns

-
Line read or NULL on eof/error

-
-
cupsFileLock()

-
Description

-
Temporarily lock access to a file.
-
Syntax

-

-int

-cupsFileLock(
-    cups_file_t * fp,
-    int block);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fpFile to lock
block1 to wait for the lock, 0 to fail right away

-
Returns

-
0 on success, -1 on error

-
-
cupsFileNumber()

-
Description

-
Return the file descriptor associated with a CUPS file.
-
Syntax

-

-int

-cupsFileNumber(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
File descriptor

-
-
cupsFileOpen()

-
Description

-
Open a CUPS file.
-
Syntax

-

-cups_file_t *

-cupsFileOpen(
-    const char * filename,
-    const char * mode);
-

-
Arguments

-

-
-
-
-
-
NameDescription
filenameName of file
modeOpen mode

-
Returns

-
CUPS file or NULL

-
-
cupsFileOpenFd()

-
Description

-
Open a CUPS file using a file descriptor.
-
Syntax

-

-cups_file_t *

-cupsFileOpenFd(
-    int fd,
-    const char * mode);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fdFile descriptor
modeOpen mode

-
Returns

-
CUPS file or NULL

-
-
cupsFilePeekChar()

-
Description

-
Peek at the next character from a file.
-
Syntax

-

-int

-cupsFilePeekChar(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
Character or -1 on EOF

-
-
cupsFilePrintf()

-
Description

-
Write a formatted string.
-
Syntax

-

-int

-cupsFilePrintf(
-    cups_file_t * fp,
-    const char * format,
-    ...);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
fpCUPS file
formatPrintf-style format string
...Additional args as necessary

-
Returns

-
Number of bytes written or -1

-
-
cupsFilePutChar()

-
Description

-
Write a character.
-
Syntax

-

-int

-cupsFilePutChar(
-    cups_file_t * fp,
-    int c);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fpCUPS file
cCharacter to write

-
Returns

-
0 on success, -1 on error

-
-
cupsFilePuts()

-
Description

-
Write a string.
-
Syntax

-

-int

-cupsFilePuts(
-    cups_file_t * fp,
-    const char * s);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fpCUPS file
sString to write

-
Returns

-
Number of bytes written or -1

-
-
cupsFileRead()

-
Description

-
Read from a file.
-
Syntax

-

-ssize_t

-cupsFileRead(
-    cups_file_t * fp,
-    char * buf,
-    size_t bytes);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
fpCUPS file
bufBuffer
bytesNumber of bytes to read

-
Returns

-
Number of bytes read or -1

-
-
cupsFileRewind()

-
Description

-
Rewind a file.
-
Syntax

-

-off_t

-cupsFileRewind(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
New file position or -1

-
-
cupsFileSeek()

-
Description

-
Seek in a file.
-
Syntax

-

-off_t

-cupsFileSeek(
-    cups_file_t * fp,
-    off_t pos);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fpCUPS file
posPosition in file

-
Returns

-
New file position or -1

-
-
cupsFileStderr()

-
Description

-
Just reposition the current pointer, since we have the right
-range...
-
Syntax

-

-cups_file_t *

-cupsFileStderr(void);
-

-
Arguments

-
None.

-
Returns

-
Return a CUPS file associated with stderr.

-
-
cupsFileStdin()

-
Description

-
Open file descriptor 2...
-
Syntax

-

-cups_file_t *

-cupsFileStdin(void);
-

-
Arguments

-
None.

-
Returns

-
Return a CUPS file associated with stdin.

-
-
cupsFileStdout()

-
Description

-
Open file descriptor 0...
-
Syntax

-

-cups_file_t *

-cupsFileStdout(void);
-

-
Arguments

-
None.

-
Returns

-
Return a CUPS file associated with stdout.

-
-
cupsFileTell()

-
Description

-
Return the current file position.
-
Syntax

-

-off_t

-cupsFileTell(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpCUPS file

-
Returns

-
File position

-
-
cupsFileUnlock()

-
Description

-
Unlock access to a file.
-
Syntax

-

-int

-cupsFileUnlock(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpFile to lock

-
Returns

-
0 on success, -1 on error

-
-
cupsFileWrite()

-
Description

-
Write to a file.
-
Syntax

-

-ssize_t

-cupsFileWrite(
-    cups_file_t * fp,
-    const char * buf,
-    size_t bytes);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
fpCUPS file
bufBuffer
bytesNumber of bytes to write

-
Returns

-
Number of bytes written

-
-
Structures

-
-
-
cups_dentry_s

-
Description

-
Directory entry type
-
Definition

-

-struct cups_dentry_s

-{

-  struct stat fileinfo;

-  char filename[260];

-};

-
Members

-

-
-
-
-
-
NameDescription
fileinfo File information
-
filename[260] File name
-

-
-
Types

-
-
-
cups_dentry_t

-
Description

-
Directory entry type
-
Definition

-

-typedef struct cups_dentry_s cups_dentry_t;
-

-
-
cups_dir_t

-
Description

-
Directory type
-
Definition

-

+

+
 CUPS 1.2 cupsFileRead

+
Read from a file.

+

+ssize_t cupsFileRead (

+    cups_file_t *fp,

+    char *buf,

+    size_t bytes

+);

+
Parameters

+

+
fp

+
CUPS file

+
buf

+
Buffer

+
bytes

+
Number of bytes to read

+

+
Return Value

+
Number of bytes read or -1 on error

+
 CUPS 1.2 cupsFileRewind

+
Set the current file position to the beginning of the
+file.

+

+off_t cupsFileRewind (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
New file position or -1 on error

+
 CUPS 1.2 cupsFileSeek

+
Seek in a file.

+

+off_t cupsFileSeek (

+    cups_file_t *fp,

+    off_t pos

+);

+
Parameters

+

+
fp

+
CUPS file

+
pos

+
Position in file

+

+
Return Value

+
New file position or -1 on error

+
 CUPS 1.2 cupsFileStderr

+
Return a CUPS file associated with stderr.

+

+cups_file_t *cupsFileStderr (void);

+
Return Value

+
CUPS file

+
 CUPS 1.2 cupsFileStdin

+
Return a CUPS file associated with stdin.

+

+cups_file_t *cupsFileStdin (void);

+
Return Value

+
CUPS file

+
 CUPS 1.2 cupsFileStdout

+
Return a CUPS file associated with stdout.

+

+cups_file_t *cupsFileStdout (void);

+
Return Value

+
CUPS file

+
 CUPS 1.2 cupsFileTell

+
Return the current file position.

+

+off_t cupsFileTell (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
File position

+
 CUPS 1.2 cupsFileUnlock

+
Unlock access to a file.

+

+int cupsFileUnlock (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
CUPS file

+

+
Return Value

+
0 on success, -1 on error

+
 CUPS 1.2 cupsFileWrite

+
Write to a file.

+

+ssize_t cupsFileWrite (

+    cups_file_t *fp,

+    const char *buf,

+    size_t bytes

+);

+
Parameters

+

+
fp

+
CUPS file

+
buf

+
Buffer

+
bytes

+
Number of bytes to write

+

+
Return Value

+
Number of bytes written or -1 on error

+
Data Types

+
cups_dentry_t

+
Directory entry type

+

+typedef struct cups_dentry_s cups_dentry_t;
+

+
cups_dir_t

+
Directory type

+

 typedef struct _cups_dir_s cups_dir_t;
-

-
-
cups_file_t

-
Description

-
CUPS file type
-
Definition

-

+

+
cups_file_t

+
CUPS file type

+

 typedef struct _cups_file_s cups_file_t;
-

+

+
Structures

+
cups_dentry_s

+
Directory entry type

+
struct cups_dentry_s {

+    struct stat fileinfo;

+    char filename[260];

+};

+
Members

+

+
fileinfo 

+
File information

+
filename[260] 

+
File name

+

+

 
 
diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html
index 492f1b2d4..62ae4ac3a 100644
--- a/doc/help/api-filter.html
+++ b/doc/help/api-filter.html
@@ -2,26 +2,260 @@
 
 
 
-	Filter and Backend APIs
-	
-	
-	
+Filter and Backend Programming
+
+
+
 
 
+

 
 
-
Introduction

+
Filter and Backend Programming

 
-
The CUPS filter and backend APIs define standard exit codes
-and provide access to the backchannel data stream. They are only
-used when writing backends, filters, and port monitors.

+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/backend.h

+	cups/sidechannel.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Programming: PPD API

+	Programming: Raster API

+
Contents

+
+
 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+
Overview

 
-
-gcc -o myprogram myprogram.c -lcups
-

+
Filters, printer drivers, port monitors, and backends use a common interface
+for processing print jobs and communicating status information to the scheduler.
+Each filter is run with a standard set of command-line arguments:

 
+

 
-
Compatibility

+	
argv[1]

+	
The job ID

 
-
The cupsBackChannel functions require CUPS 1.2 or higher. The cupsSideChannel functions require CUPS 1.3 or higher.

+	
argv[2]

+	
The user printing the job

 
+	
argv[3]

+	
The job name/title

 
-
Using the cupsBackChannel APIs

+	
argv[4]

+	
The number of copies to print

 
-
The cupsBackChannel APIs allow your filters, drivers, and port monitors to read data back from a printer and your backends to send data from a printer to the filters, drivers, and port monitors associated with the current job. Back-channel data is normally sent by the printer in response to a command sent from your program to the printer via stdout.

+	
argv[5]

+	
The options that were provided when the job was submitted

 
-
The cupsBackChannelRead() function reads data from the printer via the backend. You provide a timeout in seconds along with a buffer pointer and the size of that buffer. It returns the number of bytes or -1 if there was an error. The following code example shows how to poll for back-channel data in your program:

+	
argv[6]

+	
The file to print (first filter only)

+

 
-
-#include <cups/cups.h>
+
The scheduler runs one or more of these programs to print any given job. The
+first filter reads from the print file and writes to the standard output, while
+the remaining filters read from the standard input and write to the standard
+output. The backend is the last filter in the chain and writes to the
+device.

 
-char buffer[8192];
-ssize_t bytes;
+
Exit Codes

 
-/* Use a timeout of 0.0 seconds to poll for back-channel data */
-bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
-

+
Filters must exit with status 0 when they successfully generate print data
+or 1 when they encounter an error. Backends can return any of the
+cups_backend_t constants.

 
-
If you are writing a backend, the cupsBackChannelWrite() function sends any back-channel data you have received from the printer to upstream filters in the print filter chain. We recommend using a timeout of 1.0 seconds:

+
Environment Variables

 
-
-#include <cups/cups.h>
+
The following environment variables are defined by the printing system:

 
-char buffer[8192];
-ssize_t bytes;
+

 
-/* Use a timeout of 1.0 seconds to give filters a chance to read */
-cupsBackChannelWrite(buffer, bytes, 1.0);
-

+	
APPLE_LANGUAGES

+	
The Apple language identifier associated with the job
+	(Mac OS X only).

 
+	
CHARSET

+	
The job character set, typically "utf-8".

 
-
Using the cupsSideChannel APIs

+	
CLASS

+	
When a job is submitted to a printer class, contains the name of
+	the destination printer class. Otherwise this environment
+	variable will not be set.

 
-
The cupsSideChannel APIs allow your filters, drivers, port monitors, and backend to send and receive the following out-of-band commands:

+	
CONTENT_TYPE

+	
The MIME type associated with the file (e.g.
+	application/postscript).

 
-
    
+	
    CUPS_CACHEDIR
    
+	
    The directory where cache files can be stored.
    
 
-	
  • CUPS_SC_CMD_SOFT_RESET -  Do a soft reset
    • 
-	
  • CUPS_SC_CMD_DRAIN_OUTPUT -  Drain all pending output
    • 
-	
  • CUPS_SC_CMD_GET_BIDI -  Return bidirectional capabilities
    • 
-	
  • CUPS_SC_CMD_GET_DEVICE_ID -  Return the IEEE-1284 device ID
    • 
-	
  • CUPS_SC_CMD_GET_STATE - Return the device state
    • 
+	
    CUPS_DATADIR
    
+	
    The directory where data files can be found.
    
 
-

+	
CUPS_SERVERROOT

+	
The root directory of the server.

 
+	
DEVICE_URI

+	
The device-uri associated with the printer.

 
-
Sending Commands from a Filter, Driver, or Port Monitor

+	
FINAL_CONTENT_TYPE

+	
The MIME type associated with the printer (e.g.
+	application/vnd.cups-postscript).

 
-
The cupsSideChannelDoRequest() function is used by filters, drivers, and port monitors to send a command to the backend and read back a response:

+	
LANG

+	
The language locale associated with the job.

 
-
-cups_sc_status_t cupsSideChannelDoRequest(cups_sc_command_t command,
-                                          char *data, int *datalen,
-                                          double timeout);
-

+	
PPD

+	
The full pathname of the PostScript Printer Description (PPD)
+	file for this printer.

 
-
The CUPS_SC_CMD_SOFT_RESET and CUPS_SC_CMD_DRAIN_OUTPUT commands do not return any data values, while the others return one or more bytes. The timeout parameter allows your program to poll or wait for the command to complete - use a timeout of 30 seconds for CUPS_SC_CMD_SOFT_RESET and CUPS_SC_CMD_DRAIN_OUTPUT and a timeout of 1 second for all other commands.

+	
PRINTER

+	
The name of the printer.

 
-
CUPS_SC_CMD_GET_BIDI returns a single char value that tells you whether the backend supports bidirectional communications:

+	
RIP_CACHE

+	
The recommended amount of memory to use for Raster Image
+	Processors (RIPs).

 
-
-#include <cups/sidechannel.h>
+
 
-char data;
-int datalen;
-cups_sc_bidi_t bidi;
-cups_sc_status_t status;
+
Communicating with the Scheduler

 
-/* Tell cupsSideChannelDoRequest() how big our buffer is... */
-datalen = 1;
+
Filters and backends communicate wih the scheduler by writing messages
+to the standard error file. For example, the following code sets the current
+printer state message to "Printing page 5":

 
-/* Get the bidirectional capabilities, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_BIDI, &data, &datalen, 1.0);
+
+int page = 5;
 
-/* Use the returned value if OK was returned and the length is still 1 */
-if (status == CUPS_SC_STATUS_OK && datalen == 1)
-  bidi = (cups_sc_bidi_t)data;
-else
-  bidi = CUPS_SC_BIDI_NOT_SUPPORTED;
+fprintf(stderr, "INFO: Printing page %d\n", page);
 

 
-
CUPS_SC_CMD_GET_DEVICE_ID returns a string of characters containing the IEEE-1284 device ID for the connected printer:

+
Each message is a single line of text starting with one of the following
+prefix strings:

+
+

+
+	
ALERT: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "alert" log level.

+
+	
ATTR: attribute=value [attribute=value]

+	
Sets the named printer or job attribute(s). Typically this is used
+	to set the marker-colors, marker-levels,
+	marker-names, marker-types,
+	printer-alert, and printer-alert-description
+	printer attributes.

+
+	
CRIT: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "critical" log
+	level.

+
+	
DEBUG: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "debug" log level.

+
+	
DEBUG2: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "debug2" log level.

+
+	
EMERG: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "emergency" log
+	level.

+
+	
ERROR: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "error" log level.

+
+	
INFO: message

+	
Sets the printer-state-message attribute. If the current log level
+	is set to "debug2", also adds the specified message to the current error
+	log file using the "info" log level.

+
+	
NOTICE: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "notice" log level.

+
+	
PAGE: page-number #-copies

+	
PAGE: total #-pages

+	
Adds an entry to the current page log file. The first form adds
+	#-copies to the job-media-sheets-completed attribute. The second
+	form sets the job-media-sheets-completed attribute to #-pages.

+
+	
STATE: printer-state-reason [printer-state-reason ...]

+	
STATE: + printer-state-reason [printer-state-reason ...]

+	
STATE: - printer-state-reason [printer-state-reason ...]

+	
Sets, adds, or removes printer-state-reason keywords to the
+	current queue. Typically this is used to indicate media, ink, and
+	toner conditions on a printer.

+
+	
WARNING: message

+	
Sets the printer-state-message attribute and adds the specified
+	message to the current error log file using the "warning" log
+	level.

+
+

+
+
Messages without one of these prefixes are treated as if they began with
+the "DEBUG:" prefix string.

+
+
Communicating with the Backend

+
+
Filters can communicate with the backend via the
+cupsBackChannelRead and
+cupsSideChannelDoRequest
+functions. The 
+cupsBackChannelRead function
+reads data that has been sent back from the device and is typically used to
+obtain status and configuration information. For example, the following code
+polls the backend for back-channel data:

+
+
+#include <cups/cups.h>
+
+char buffer[8192];
+ssize_t bytes;
+
+/* Use a timeout of 0.0 seconds to poll for back-channel data */
+bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
+

 
-
+The
+cupsSideChannelDoRequest
+function allows you to get out-of-band status information and do synchronization
+with the device. For example, the following code gets the current IEEE-1284
+device ID string from the backend:

+
+
 #include <cups/sidechannel.h>
 
 char data[2049];
 int datalen;
-cups_sc_status_t status;
+cups_sc_status_t status;
 
 /* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
 datalen = sizeof(data) - 1;
 
 /* Get the IEEE-1284 device ID, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0);
+status = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_DEVICE_ID, data, &datalen, 1.0);
 
 /* Use the returned value if OK was returned and the length is non-zero */
 if (status == CUPS_SC_STATUS_OK && datalen > 0)
@@ -164,59 +557,53 @@ else
   data[0] = '\0';
 

 
-
CUPS_SC_CMD_GET_STATE returns a single char value that tells you the current device state:

-
-
-#include <cups/sidechannel.h>
-
-char data;
-int datalen;
-cups_sc_state_t state;
-cups_sc_status_t status;
-
-/* Tell cupsSideChannelDoRequest() how big our buffer is... */
-datalen = 1;
-
-/* Get the bidirectional capabilities, waiting for up to 1 second */
-status  = cupsSideChannelDoRequest(CUPS_SC_CMD_GET_STATE, &data, &datalen, 1.0);
-
-/* Use the returned value if OK was returned and the length is still 1 */
-if (status == CUPS_SC_STATUS_OK && datalen == 1)
-  state = (cups_sc_state_t)data;
-else
-  state = CUPS_SC_STATE_OFFLINE;
-

-
+
Backends communicate with filters using the reciprocal functions
+cupsBackChannelWrite,
+cupsSideChannelRead, and
+cupsSideChannelWrite. We
+recommend writing back-channel data using a timeout of 1.0 seconds:

 
-
Handling Commands in your Backend

+
+#include <cups/cups.h>
 
-
The cupsSideChannelRead() function is used by backends to read a command from a filter, driver, or port monitor:

+char buffer[8192];
+ssize_t bytes;
 
-
-int cupsSideChannelRead(cups_sc_command_t &command,
-                        cups_sc_status_t  &status,
-                        char *data, int *datalen, double timeout);
+/* Use a timeout of 1.0 seconds to give filters a chance to read */
+cupsBackChannelWrite(buffer, bytes, 1.0);
 

 
-
Backends can either poll for commands using a timeout of 0.0, wait indefinitely for commands using a timeout of -1.0 (probably in a separate thread for that purpose), or use select() or poll() on the CUPS_SC_FD file descriptor (4) to handle input and output on several file descriptors at the same time. Backends can pass NULL for the data and datalen parameters, since none of the commands sent by upstream filters contain any data at this time.

-
-
Once a command is processed, the backend uses the cupsSideChannelWrite() function to send its response:

-
-
+
The cupsSideChannelRead
+function reads a side-channel command from a filter, driver, or port monitor.
+Backends can either poll for commands using a timeout of 0.0, wait
+indefinitely for commands using a timeout of -1.0 (probably in a
+separate thread for that purpose), or use select or
+poll on the CUPS_SC_FD file descriptor (4) to handle
+input and output on several file descriptors at the same time. Backends can pass
+NULL for the data and datalen parameters
+since none of the commands sent by upstream filters contain any data at this
+time.

+
+
Once a command is processed, the backend uses the
+cupsSideChannelWrite function
+to send its response. For example, the following code shows how to poll for a
+side-channel command and respond to it:

+
+
 #include <cups/sidechannel.h>
 
-cups_sc_command_t command;
-cups_sc_status_t status;
+cups_sc_command_t command;
+cups_sc_status_t status;
 
 /* Poll for a command... */
-if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
+if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
 {
   char data[2048];
   int datalen;
 
   switch (command)
   {
-    ... handle supported commands, file data/datalen/status with values as needed ...
+    /* handle supported commands, file data/datalen/status with values as needed */
 
     default :
         status  = CUPS_SC_STATUS_NOT_IMPLEMENTED;
@@ -225,176 +612,272 @@ if (!cupsSideChannelRead(&command, &status, NULL, NULL, 0.0))
   }
 
   /* Send a response... */
-  cupsSideChannelWrite(command, status, data, datalen, 1.0);
+  cupsSideChannelWrite(command, status, data, datalen, 1.0);
 }
 

-
Contents

-
-
-
Functions

-
-
-
 CUPS 1.2 cupsBackChannelRead()

-
Description

-
Read data from the backchannel.
-
Reads up to "bytes" bytes from the backchannel. The "timeout"
+
Functions

+
 CUPS 1.2 cupsBackChannelRead

+
Read data from the backchannel.

+

+ssize_t cupsBackChannelRead (

+    char *buffer,

+    size_t bytes,

+    double timeout

+);

+
Parameters

+

+
buffer

+
Buffer to read

+
bytes

+
Bytes to read

+
timeout

+
Timeout in seconds

+

+
Return Value

+
Bytes read or -1 on error

+
Discussion

+
Reads up to "bytes" bytes from the backchannel. The "timeout"
 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.
 
-
-
Syntax

-

-ssize_t

-cupsBackChannelRead(
-    char * buffer,
-    size_t bytes,
-    double timeout);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
bufferBuffer to read
bytesBytes to read
timeoutTimeout in seconds

-
Returns

-
Bytes read or -1 on error

-
-
 CUPS 1.2 cupsBackChannelWrite()

-
Description

-
Write data to the backchannel.
-
Writes "bytes" bytes to the backchannel. The "timeout" parameter
+

+
 CUPS 1.2 cupsBackChannelWrite

+
Write data to the backchannel.

+

+ssize_t cupsBackChannelWrite (

+    const char *buffer,

+    size_t bytes,

+    double timeout

+);

+
Parameters

+

+
buffer

+
Buffer to write

+
bytes

+
Bytes to write

+
timeout

+
Timeout in seconds

+

+
Return Value

+
Bytes written or -1 on error

+
Discussion

+
Writes "bytes" bytes to the backchannel. The "timeout" parameter
 controls how many seconds to wait for the data to be written - use
 0.0 to return immediately if the data cannot be written, -1.0 to wait
 indefinitely.
 
-
-
Syntax

-

-ssize_t

-cupsBackChannelWrite(
-    const char * buffer,
-    size_t bytes,
-    double timeout);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
bufferBuffer to write
bytesBytes to write
timeoutTimeout in seconds

-
Returns

-
Bytes written or -1 on error

-
-
 CUPS 1.3 cupsSideChannelDoRequest()

-
Description

-
Send a side-channel command to a backend and wait for a response.
-
This function is normally only called by filters, drivers, or port
+

+
 CUPS 1.3 cupsSideChannelDoRequest

+
Send a side-channel command to a backend and wait for a response.

+

+cups_sc_status_t cupsSideChannelDoRequest (

+    cups_sc_command_t command,

+    char *data,

+    int *datalen,

+    double timeout

+);

+
Parameters

+

+
command

+
Command to send

+
data

+
Response data buffer pointer

+
datalen

+
Size of data buffer on entry, number of bytes in buffer on return

+
timeout

+
Timeout in seconds

+

+
Return Value

+
Status of command

+
Discussion

+
This function is normally only called by filters, drivers, or port
 monitors in order to communicate with the backend used by the current
 printer.  Programs must be prepared to handle timeout or "not
 implemented" status codes, which indicate that the backend or device
-do not support the specified side-channel command.
-
The "datalen" parameter must be initialized to the size of the buffer
+do not support the specified side-channel command.

+

+The "datalen" parameter must be initialized to the size of the buffer
 pointed to by the "data" parameter.  cupsSideChannelDoRequest() will
 update the value to contain the number of data bytes in the buffer.
 
-
-
Syntax

-

-cups_sc_status_t

-cupsSideChannelDoRequest(
-    cups_sc_command_t command,
-    char * data,
-    int * datalen,
-    double timeout);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
commandCommand to send
dataResponse data buffer pointer
datalenSize of data buffer on entry, number of bytes in buffer on return
timeoutTimeout in seconds

-
Returns

-
Status of command

-
-
 CUPS 1.3 cupsSideChannelRead()

-
Description

-
Read a side-channel message.
-
This function is normally only called by backend programs to read
+

+
 CUPS 1.3 cupsSideChannelRead

+
Read a side-channel message.

+

+int cupsSideChannelRead (

+    cups_sc_command_t *command,

+    cups_sc_status_t *status,

+    char *data,

+    int *datalen,

+    double timeout

+);

+
Parameters

+

+
command

+
Command code

+
status

+
Status code

+
data

+
Data buffer pointer

+
datalen

+
Size of data buffer on entry, number of bytes in buffer on return

+
timeout

+
Timeout in seconds

+

+
Return Value

+
0 on success, -1 on error

+
Discussion

+
This function is normally only called by backend programs to read
 commands from a filter, driver, or port monitor program.  The
 caller must be prepared to handle incomplete or invalid messages
-and return the corresponding status codes.
-
The "datalen" parameter must be initialized to the size of the buffer
+and return the corresponding status codes.

+

+The "datalen" parameter must be initialized to the size of the buffer
 pointed to by the "data" parameter.  cupsSideChannelDoRequest() will
 update the value to contain the number of data bytes in the buffer.
 
-
-
Syntax

-

-int

-cupsSideChannelRead(
-    cups_sc_command_t * command,
-    cups_sc_status_t * status,
-    char * data,
-    int * datalen,
-    double timeout);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
commandCommand code
statusStatus code
dataData buffer pointer
datalenSize of data buffer on entry, number of bytes in buffer on return
timeoutTimeout in seconds

-
Returns

-
0 on success, -1 on error

-
-
 CUPS 1.3 cupsSideChannelWrite()

-
Description

-
Write a side-channel message.
-
This function is normally only called by backend programs to send
+

+
 CUPS 1.3 cupsSideChannelWrite

+
Write a side-channel message.

+

+int cupsSideChannelWrite (

+    cups_sc_command_t command,

+    cups_sc_status_t status,

+    const char *data,

+    int datalen,

+    double timeout

+);

+
Parameters

+

+
command

+
Command code

+
status

+
Status code

+
data

+
Data buffer pointer

+
datalen

+
Number of bytes of data

+
timeout

+
Timeout in seconds

+

+
Return Value

+
0 on success, -1 on error

+
Discussion

+
This function is normally only called by backend programs to send
 responses to a filter, driver, or port monitor program.
 
-
-
Syntax

-

-int

-cupsSideChannelWrite(
-    cups_sc_command_t command,
-    cups_sc_status_t status,
-    const char * data,
-    int datalen,
-    double timeout);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
commandCommand code
statusStatus code
dataData buffer pointer
datalenNumber of bytes of data
timeoutTimeout in seconds

-
Returns

-
0 on success, -1 on error

+

+
Data Types

+
cups_backend_t

+
Backend exit codes

+

+typedef enum cups_backend_e cups_backend_t;
+

+
cups_sc_bidi_t

+
Bidirectional capabilities

+

+typedef enum cups_sc_bidi_e cups_sc_bidi_t;
+

+
cups_sc_command_t

+
Request command codes

+

+typedef enum cups_sc_command_e cups_sc_command_t;
+

+
cups_sc_state_t

+
Printer state bits

+

+typedef enum cups_sc_state_e cups_sc_state_t;
+

+
cups_sc_status_t

+
Response status codes

+

+typedef enum cups_sc_status_e cups_sc_status_t;
+

+
Constants

+
cups_backend_e

+
Backend exit codes

+
Constants

+

+
CUPS_BACKEND_AUTH_REQUIRED 

+
Job failed, authentication required

+
CUPS_BACKEND_CANCEL 

+
Job failed, cancel job

+
CUPS_BACKEND_FAILED 

+
Job failed, use error-policy

+
CUPS_BACKEND_HOLD 

+
Job failed, hold job

+
CUPS_BACKEND_OK 

+
Job completed successfully

+
CUPS_BACKEND_STOP 

+
Job failed, stop queue

+

+
cups_sc_bidi_e

+
Bidirectional capabilities

+
Constants

+

+
CUPS_SC_BIDI_NOT_SUPPORTED 

+
Bidirectional I/O is not supported

+
CUPS_SC_BIDI_SUPPORTED 

+
Bidirectional I/O is supported

+

+
cups_sc_command_e

+
Request command codes

+
Constants

+

+
CUPS_SC_CMD_DRAIN_OUTPUT 

+
Drain all pending output

+
CUPS_SC_CMD_GET_BIDI 

+
Return bidirectional capabilities

+
CUPS_SC_CMD_GET_DEVICE_ID 

+
Return the IEEE-1284 device ID

+
CUPS_SC_CMD_GET_STATE 

+
Return the device state

+
CUPS_SC_CMD_SOFT_RESET 

+
Do a soft reset

+

+
cups_sc_state_e

+
Printer state bits

+
Constants

+

+
CUPS_SC_STATE_BUSY 

+
Device is busy

+
CUPS_SC_STATE_ERROR 

+
Other error condition

+
CUPS_SC_STATE_MARKER_EMPTY 

+
Toner/ink out condition

+
CUPS_SC_STATE_MARKER_LOW 

+
Toner/ink low condition

+
CUPS_SC_STATE_MEDIA_EMPTY 

+
Paper out condition

+
CUPS_SC_STATE_MEDIA_LOW 

+
Paper low condition

+
CUPS_SC_STATE_OFFLINE 

+
Device is off-line

+
CUPS_SC_STATE_ONLINE 

+
Device is on-line

+

+
cups_sc_status_e

+
Response status codes

+
Constants

+

+
CUPS_SC_STATUS_BAD_MESSAGE 

+
The command/response message was invalid

+
CUPS_SC_STATUS_IO_ERROR 

+
An I/O error occurred

+
CUPS_SC_STATUS_NONE 

+
No status

+
CUPS_SC_STATUS_NOT_IMPLEMENTED 

+
Command not implemented

+
CUPS_SC_STATUS_NO_RESPONSE 

+
The device did not respond

+
CUPS_SC_STATUS_OK 

+
Operation succeeded

+
CUPS_SC_STATUS_TIMEOUT 

+
The backend did not respond

+
CUPS_SC_STATUS_TOO_BIG 

+
Response too big

+

+

 
 
diff --git a/doc/help/api-httpipp.html b/doc/help/api-httpipp.html
index 3f4e2eee8..e8c09e286 100644
--- a/doc/help/api-httpipp.html
+++ b/doc/help/api-httpipp.html
@@ -2,25 +2,481 @@
 
 
 
-	HTTP and IPP APIs
-	
-	
-	
+HTTP and IPP APIs
+
+
+
 
 
+

 
+
+
HTTP and IPP APIs

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/cups.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	References: CUPS Implementation of IPP

+
Contents

+
+
 
-
Introduction

+
Overview

+
+
The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP
+protocols and CUPS scheduler. They are typically used by monitoring and
+administration programs to perform specific functions not supported by the
+high-level CUPS API functions.

+
+
The HTTP APIs use an opaque structure called
+http_t to manage connections to
+a particular HTTP or IPP server. The
+httpConnectEncrypt function is
+used to create an instance of this structure for a particular server.
+The constant CUPS_HTTP_DEFAULT can be used with all of the
+cups functions to refer to the default CUPS server - the functions
+create a per-thread http_t as needed.

+
+
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 ipp_t structure holds a
+complete request or response and is allocated using the
+ippNew or
+ippNewRequest functions and
+freed using the ippDelete function.

+
+
The second structure is called
+ipp_attribute_t and holds a
+single IPP attribute which consists of a group tag (group_tag), a
+value type tag (value_tag), the attribute name (name),
+and 1 or more values (values[]). Attributes are added to an
+ipp_t structure using one of the
+ippAdd functions. For example, use
+ippAddString to add a
+"requesting-user-name" string attribute to a request:

+
+
+ipp_t *request = ippNewRequest(IPP_GET_JOBS);
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+             NULL, cupsUser());
+

 
-
The CUPS HTTP and IPP APIs provide low-level access to the
-HTTP and IPP protocols and CUPS scheduler. They are typically
-used by monitoring and administration programs to perform
-specific functions not supported by the high-level CUPS API
-functions.

+
Once you have created an IPP request, use the cups
+functions to send the request to and read the response from the server.
+For example, the cupsDoRequest
+function can be used for simple query operations that do not involve files:

 
-
General Usage

+
+#include <cups/cups.h>
 
-
The <cups/cups.h> header file must be included to
-use the HTTP and IPP functions.

 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+ipp_t *get_jobs(void)
+{
+  ipp_t *request = ippNewRequest(IPP_GET_JOBS);
 
-
-gcc -o myprogram myprogram.c -lcups
+  ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+               NULL, cupsUser());
+
+  return (cupsDoRequest(CUPS_HTTP_DEFAULT, request, "/"));
+}
 

 
-
Compatibility

-
-
Unless otherwise specified, the HTTP and IPP API functions
-require CUPS 1.1 or higher.

-
Contents

-
-
-
Enumerations

-
-
-
http_auth_e

-
Description

-
HTTP authentication types
-
Values

-

-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_AUTH_BASIC Basic authentication in use
-
HTTP_AUTH_MD5 Digest authentication in use
-
HTTP_AUTH_MD5_INT Digest authentication in use for body
-
HTTP_AUTH_MD5_SESS MD5-session authentication in use
-
HTTP_AUTH_MD5_SESS_INT MD5-session authentication in use for body
-
HTTP_AUTH_NEGOTIATE  CUPS 1.3 GSSAPI authentication in use 
-
HTTP_AUTH_NONE No authentication in use
-

-
-
http_encoding_e

-
Description

-
HTTP transfer encoding values
-
Values

-

-
-
-
-
-
-
NameDescription
HTTP_ENCODE_CHUNKED Data is chunked
-
HTTP_ENCODE_FIELDS Sending HTTP fields
-
HTTP_ENCODE_LENGTH Data is sent with Content-Length
-

-
-
http_encryption_e

-
Description

-
HTTP encryption values
-
Values

-

-
-
-
-
-
-
-
NameDescription
HTTP_ENCRYPT_ALWAYS Always encrypt (SSL)
-
HTTP_ENCRYPT_IF_REQUESTED Encrypt if requested (TLS upgrade)
-
HTTP_ENCRYPT_NEVER Never encrypt
-
HTTP_ENCRYPT_REQUIRED Encryption is required (TLS upgrade)
-

-
-
http_field_e

-
Description

-
HTTP field names
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_FIELD_ACCEPT_LANGUAGE Accept-Language field
-
HTTP_FIELD_ACCEPT_RANGES Accept-Ranges field
-
HTTP_FIELD_AUTHORIZATION Authorization field
-
HTTP_FIELD_CONNECTION Connection field
-
HTTP_FIELD_CONTENT_ENCODING Content-Encoding field
-
HTTP_FIELD_CONTENT_LANGUAGE Content-Language field
-
HTTP_FIELD_CONTENT_LENGTH Content-Length field
-
HTTP_FIELD_CONTENT_LOCATION Content-Location field
-
HTTP_FIELD_CONTENT_MD5 Content-MD5 field
-
HTTP_FIELD_CONTENT_RANGE Content-Range field
-
HTTP_FIELD_CONTENT_TYPE Content-Type field
-
HTTP_FIELD_CONTENT_VERSION Content-Version field
-
HTTP_FIELD_DATE Date field
-
HTTP_FIELD_HOST Host field
-
HTTP_FIELD_IF_MODIFIED_SINCE If-Modified-Since field
-
HTTP_FIELD_IF_UNMODIFIED_SINCE If-Unmodified-Since field
-
HTTP_FIELD_KEEP_ALIVE Keep-Alive field
-
HTTP_FIELD_LAST_MODIFIED Last-Modified field
-
HTTP_FIELD_LINK Link field
-
HTTP_FIELD_LOCATION Location field
-
HTTP_FIELD_MAX Maximum field index
-
HTTP_FIELD_RANGE Range field
-
HTTP_FIELD_REFERER Referer field
-
HTTP_FIELD_RETRY_AFTER Retry-After field
-
HTTP_FIELD_TRANSFER_ENCODING Transfer-Encoding field
-
HTTP_FIELD_UNKNOWN Unknown field
-
HTTP_FIELD_UPGRADE Upgrade field
-
HTTP_FIELD_USER_AGENT User-Agent field
-
HTTP_FIELD_WWW_AUTHENTICATE WWW-Authenticate field
-

-
-
http_keepalive_e

-
Description

-
Types and structures...
-
Values

-

-
-
-
-
-
NameDescription
HTTP_KEEPALIVE_OFF No keep alive support
-
HTTP_KEEPALIVE_ON Use keep alive
-

-
-
http_state_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_CLOSE CLOSE command, waiting for blank line
-
HTTP_DELETE DELETE command, waiting for blank line
-
HTTP_GET GET command, waiting for blank line
-
HTTP_GET_SEND GET command, sending data
-
HTTP_HEAD HEAD command, waiting for blank line
-
HTTP_OPTIONS OPTIONS command, waiting for blank line
-
HTTP_POST POST command, waiting for blank line
-
HTTP_POST_RECV POST command, receiving data
-
HTTP_POST_SEND POST command, sending data
-
HTTP_PUT PUT command, waiting for blank line
-
HTTP_PUT_RECV PUT command, receiving data
-
HTTP_STATUS Command complete, sending status
-
HTTP_TRACE TRACE command, waiting for blank line
-
HTTP_WAITING Waiting for command
-

-
-
http_status_e

-
Description

-
HTTP status codes
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_ACCEPTED DELETE command was successful
-
HTTP_BAD_GATEWAY Bad gateway
-
HTTP_BAD_REQUEST Bad request
-
HTTP_CONFLICT Request is self-conflicting
-
HTTP_CONTINUE Everything OK, keep going...
-
HTTP_CREATED PUT command was successful
-
HTTP_ERROR An error response from httpXxxx()
-
HTTP_EXPECTATION_FAILED The expectation given in an Expect header field was not met
-
HTTP_FORBIDDEN Forbidden to access this URI
-
HTTP_GATEWAY_TIMEOUT Gateway connection timed out
-
HTTP_GONE Server has gone away
-
HTTP_LENGTH_REQUIRED A content length or encoding is required
-
HTTP_METHOD_NOT_ALLOWED Method is not allowed
-
HTTP_MOVED_PERMANENTLY Document has moved permanently
-
HTTP_MOVED_TEMPORARILY Document has moved temporarily
-
HTTP_MULTIPLE_CHOICES Multiple files match request
-
HTTP_NOT_ACCEPTABLE Not Acceptable
-
HTTP_NOT_AUTHORITATIVE Information isn't authoritative
-
HTTP_NOT_FOUND URI was not found
-
HTTP_NOT_IMPLEMENTED Feature not implemented
-
HTTP_NOT_MODIFIED File not modified
-
HTTP_NOT_SUPPORTED HTTP version not supported
-
HTTP_NO_CONTENT Successful command, no new data
-
HTTP_OK OPTIONS/GET/HEAD/POST/TRACE command was successful
-
HTTP_PARTIAL_CONTENT Only a partial file was recieved/sent
-
HTTP_PAYMENT_REQUIRED Payment required
-
HTTP_PRECONDITION Precondition failed
-
HTTP_PROXY_AUTHENTICATION Proxy Authentication is Required
-
HTTP_REQUESTED_RANGE The requested range is not satisfiable
-
HTTP_REQUEST_TIMEOUT Request timed out
-
HTTP_REQUEST_TOO_LARGE Request entity too large
-
HTTP_RESET_CONTENT Content was reset/recreated
-
HTTP_SEE_OTHER See this other link...
-
HTTP_SERVER_ERROR Internal server error
-
HTTP_SERVICE_UNAVAILABLE Service is unavailable
-
HTTP_SWITCHING_PROTOCOLS HTTP upgrade to TLS/SSL
-
HTTP_UNAUTHORIZED Unauthorized to access host
-
HTTP_UNSUPPORTED_MEDIATYPE The requested media type is unsupported
-
HTTP_UPGRADE_REQUIRED Upgrade to SSL/TLS required
-
HTTP_URI_TOO_LONG URI too long
-
HTTP_USE_PROXY Must use a proxy to access this URI
-

-
-
http_uri_coding_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_URI_CODING_ALL En/decode everything
-
HTTP_URI_CODING_HOSTNAME En/decode the hostname portion
-
HTTP_URI_CODING_MOST En/decode all but the query
-
HTTP_URI_CODING_NONE Don't en/decode anything
-
HTTP_URI_CODING_QUERY En/decode the query portion
-
HTTP_URI_CODING_RESOURCE En/decode the resource portion
-
HTTP_URI_CODING_USERNAME En/decode the username portion
-

-
-
http_uri_status_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
HTTP_URI_BAD_ARGUMENTS Bad arguments to function (error)
-
HTTP_URI_BAD_HOSTNAME Bad hostname in URI (error)
-
HTTP_URI_BAD_PORT Bad port number in URI (error)
-
HTTP_URI_BAD_RESOURCE Bad resource in URI (error)
-
HTTP_URI_BAD_SCHEME Bad scheme in URI (error)
-
HTTP_URI_BAD_URI Bad/empty URI (error)
-
HTTP_URI_BAD_USERNAME Bad username in URI (error)
-
HTTP_URI_MISSING_RESOURCE Missing resource in URI (warning)
-
HTTP_URI_MISSING_SCHEME Missing scheme in URI (warning)
-
HTTP_URI_OK URI decoded OK
-
HTTP_URI_OVERFLOW URI buffer for httpAssembleURI is too small
-
HTTP_URI_UNKNOWN_SCHEME Unknown scheme in URI (warning)
-

-
-
http_version_e

-
Description

-

-
Values

-

-
-
-
-
-
-
NameDescription
HTTP_0_9 HTTP/0.9
-
HTTP_1_0 HTTP/1.0
-
HTTP_1_1 HTTP/1.1
-

-
-
ipp_finish_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
IPP_FINISHINGS_BALE Bale (any type)
-
IPP_FINISHINGS_BIND Bind
-
IPP_FINISHINGS_BIND_BOTTOM Bind on bottom
-
IPP_FINISHINGS_BIND_LEFT Bind on left
-
IPP_FINISHINGS_BIND_RIGHT Bind on right
-
IPP_FINISHINGS_BIND_TOP Bind on top
-
IPP_FINISHINGS_BOOKLET_MAKER Fold to make booklet
-
IPP_FINISHINGS_COVER Add cover
-
IPP_FINISHINGS_EDGE_STITCH Stitch along any side
-
IPP_FINISHINGS_EDGE_STITCH_BOTTOM Stitch along bottom edge
-
IPP_FINISHINGS_EDGE_STITCH_LEFT Stitch along left side
-
IPP_FINISHINGS_EDGE_STITCH_RIGHT Stitch along right side
-
IPP_FINISHINGS_EDGE_STITCH_TOP Stitch along top edge
-
IPP_FINISHINGS_FOLD Fold (any type)
-
IPP_FINISHINGS_JOB_OFFSET Offset for binding (any type)
-
IPP_FINISHINGS_NONE No finishing
-
IPP_FINISHINGS_PUNCH Punch (any location/count)
-
IPP_FINISHINGS_SADDLE_STITCH Staple interior
-
IPP_FINISHINGS_STAPLE Staple (any location)
-
IPP_FINISHINGS_STAPLE_BOTTOM_LEFT Staple bottom left corner
-
IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT Staple bottom right corner
-
IPP_FINISHINGS_STAPLE_DUAL_BOTTOM Two staples on bottom
-
IPP_FINISHINGS_STAPLE_DUAL_LEFT Two staples on left
-
IPP_FINISHINGS_STAPLE_DUAL_RIGHT Two staples on right
-
IPP_FINISHINGS_STAPLE_DUAL_TOP Two staples on top
-
IPP_FINISHINGS_STAPLE_TOP_LEFT Staple top left corner
-
IPP_FINISHINGS_STAPLE_TOP_RIGHT Staple top right corner
-
IPP_FINISHINGS_TRIM Trim (any type)
-

-
-
ipp_jstate_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
NameDescription
IPP_JOB_ABORTED Job has aborted due to error
-
IPP_JOB_CANCELED Job has been canceled
-
IPP_JOB_COMPLETED Job has completed successfully
-
IPP_JOB_HELD Job is held for printing
-
IPP_JOB_PENDING Job is waiting to be printed
-
IPP_JOB_PROCESSING Job is currently printing
-
IPP_JOB_STOPPED Job has been stopped
-

-
-
ipp_op_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
CUPS_ACCEPT_JOBS Accept new jobs on a printer
-
CUPS_ADD_MODIFY_CLASS Add or modify a class
-
CUPS_ADD_MODIFY_PRINTER Add or modify a printer
-
CUPS_AUTHENTICATE_JOB  CUPS 1.2 Authenticate a job 
-
CUPS_DELETE_CLASS Delete a class
-
CUPS_DELETE_PRINTER Delete a printer
-
CUPS_GET_CLASSES  DEPRECATED Get a list of classes 
-
CUPS_GET_DEFAULT Get the default printer
-
CUPS_GET_DEVICES Get a list of supported devices
-
CUPS_GET_DOCUMENT  CUPS 1.4 Get a document file 
-
CUPS_GET_PPD  CUPS 1.3 Get a PPD file 
-
CUPS_GET_PPDS Get a list of supported drivers
-
CUPS_GET_PRINTERS Get a list of printers and/or classes
-
CUPS_MOVE_JOB Move a job to a different printer
-
CUPS_REJECT_JOBS Reject new jobs on a printer
-
CUPS_SET_DEFAULT Set the default printer
-
IPP_ACTIVATE_PRINTER Start a printer @private@
-
IPP_CANCEL_CURRENT_JOB Cancel the current job @private@
-
IPP_CANCEL_JOB Cancel a job
-
IPP_CANCEL_SUBSCRIPTION  CUPS 1.2 Cancel a subscription 
-
IPP_CREATE_JOB Create an empty print job
-
IPP_CREATE_JOB_SUBSCRIPTION  CUPS 1.2 Create a job subscription 
-
IPP_CREATE_PRINTER_SUBSCRIPTION  CUPS 1.2 Create a printer subscription 
-
IPP_DEACTIVATE_PRINTER Stop a printer @private@
-
IPP_DISABLE_PRINTER Stop a printer
-
IPP_ENABLE_PRINTER Start a printer
-
IPP_GET_JOBS Get a list of jobs
-
IPP_GET_JOB_ATTRIBUTES Get job attributes
-
IPP_GET_NOTIFICATIONS  CUPS 1.2 Get notification events 
-
IPP_GET_PRINTER_ATTRIBUTES Get printer attributes
-
IPP_GET_PRINTER_SUPPORTED_VALUES Get supported attribute values
-
IPP_GET_PRINT_SUPPORT_FILES Get printer support files @private@
-
IPP_GET_SUBSCRIPTIONS  CUPS 1.2 Get list of subscriptions 
-
IPP_GET_SUBSCRIPTION_ATTRIBUTES  CUPS 1.2 Get subscription attributes 
-
IPP_HOLD_JOB Hold a job for printing
-
IPP_HOLD_NEW_JOBS Hold new jobs @private@
-
IPP_PAUSE_PRINTER Stop a printer
-
IPP_PAUSE_PRINTER_AFTER_CURRENT_JOB Stop printer after the current job @private@
-
IPP_PRINT_JOB Print a single file
-
IPP_PRINT_URI Print a single URL @private@
-
IPP_PRIVATE Reserved @private@
-
IPP_PROMOTE_JOB Promote a job to print sooner @private@
-
IPP_PURGE_JOBS Cancel all jobs
-
IPP_RELEASE_HELD_NEW_JOBS Release new jobs @private@
-
IPP_RELEASE_JOB Release a job for printing
-
IPP_RENEW_SUBSCRIPTION  CUPS 1.2 Renew a printer subscription 
-
IPP_REPROCESS_JOB Reprint a job @private@
-
IPP_RESTART_JOB Reprint a job
-
IPP_RESTART_PRINTER Restart a printer @private@
-
IPP_RESUME_JOB Resume the current job @private@
-
IPP_RESUME_PRINTER Start a printer
-
IPP_SCHEDULE_JOB_AFTER Schedule a job to print after another @private@
-
IPP_SEND_DOCUMENT Add a file to a job
-
IPP_SEND_NOTIFICATIONS Send notification events @private@
-
IPP_SEND_URI Add a URL to a job @private@
-
IPP_SET_JOB_ATTRIBUTES Set job attributes
-
IPP_SET_PRINTER_ATTRIBUTES Set printer attributes @private@
-
IPP_SHUTDOWN_PRINTER Turn a printer off @private@
-
IPP_STARTUP_PRINTER Turn a printer on @private@
-
IPP_SUSPEND_CURRENT_JOB Suspend the current job @private@
-
IPP_VALIDATE_JOB Validate job options
-

-
-
ipp_orient_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
NameDescription
IPP_LANDSCAPE 90 degrees counter-clockwise
-
IPP_PORTRAIT No rotation
-
IPP_REVERSE_LANDSCAPE 90 degrees clockwise
-
IPP_REVERSE_PORTRAIT 180 degrees
-

-
-
ipp_pstate_e

-
Description

-

-
Values

-

-
-
-
-
-
-
NameDescription
IPP_PRINTER_IDLE Printer is idle
-
IPP_PRINTER_PROCESSING Printer is working
-
IPP_PRINTER_STOPPED Printer is stopped
-

-
-
ipp_quality_e

-
Description

-

-
Values

-

-
-
-
-
-
-
NameDescription
IPP_QUALITY_DRAFT Draft quality
-
IPP_QUALITY_HIGH High quality
-
IPP_QUALITY_NORMAL Normal quality
-

-
-
ipp_res_e

-
Description

-
Types and structures...
-
Values

-

-
-
-
-
-
NameDescription
IPP_RES_PER_CM Pixels per centimeter
-
IPP_RES_PER_INCH Pixels per inch
-

-
-
ipp_state_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
NameDescription
IPP_ATTRIBUTE One or more attributes need to be sent/received
-
IPP_DATA IPP request data needs to be sent/received
-
IPP_ERROR An error occurred
-
IPP_HEADER The request header needs to be sent/received
-
IPP_IDLE Nothing is happening/request completed
-

-
-
ipp_status_e

-
Description

-
IPP status codes...
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
CUPS_SEE_OTHER cups-see-other
-
IPP_ATTRIBUTES client-error-attributes-or-values-not-supported
-
IPP_ATTRIBUTES_NOT_SETTABLE client-error-attributes-not-settable
-
IPP_BAD_REQUEST client-error-bad-request
-
IPP_CHARSET client-error-charset-not-supported
-
IPP_COMPRESSION_ERROR client-error-compression-error
-
IPP_COMPRESSION_NOT_SUPPORTED client-error-compression-not-supported
-
IPP_CONFLICT client-error-conflicting-attributes
-
IPP_DEVICE_ERROR server-error-device-error
-
IPP_DOCUMENT_ACCESS_ERROR client-error-document-access-error
-
IPP_DOCUMENT_FORMAT client-error-document-format-not-supported
-
IPP_DOCUMENT_FORMAT_ERROR client-error-document-format-error
-
IPP_ERROR_JOB_CANCELED server-error-job-canceled
-
IPP_FORBIDDEN client-error-forbidden
-
IPP_GONE client-error-gone
-
IPP_IGNORED_ALL_NOTIFICATIONS client-error-ignored-all-notifications
-
IPP_IGNORED_ALL_SUBSCRIPTIONS client-error-ignored-all-subscriptions
-
IPP_INTERNAL_ERROR server-error-internal-error
-
IPP_MULTIPLE_JOBS_NOT_SUPPORTED server-error-multiple-document-jobs-not-supported
-
IPP_NOT_ACCEPTING server-error-not-accepting-jobs
-
IPP_NOT_AUTHENTICATED client-error-not-authenticated
-
IPP_NOT_AUTHORIZED client-error-not-authorized
-
IPP_NOT_FOUND client-error-not-found
-
IPP_NOT_POSSIBLE client-error-not-possible
-
IPP_OK successful-ok
-
IPP_OK_BUT_CANCEL_SUBSCRIPTION successful-ok-but-cancel-subscription
-
IPP_OK_CONFLICT successful-ok-conflicting-attributes
-
IPP_OK_EVENTS_COMPLETE successful-ok-events-complete
-
IPP_OK_IGNORED_NOTIFICATIONS successful-ok-ignored-notifications
-
IPP_OK_IGNORED_SUBSCRIPTIONS successful-ok-ignored-subscriptions
-
IPP_OK_SUBST successful-ok-ignored-or-substituted-attributes
-
IPP_OK_TOO_MANY_EVENTS successful-ok-too-many-events
-
IPP_OPERATION_NOT_SUPPORTED server-error-operation-not-supported
-
IPP_PRINTER_BUSY server-error-busy
-
IPP_PRINTER_IS_DEACTIVATED server-error-printer-is-deactivated
-
IPP_PRINT_SUPPORT_FILE_NOT_FOUND client-error-print-support-file-not-found
-
IPP_REDIRECTION_OTHER_SITE 
-
IPP_REQUEST_ENTITY client-error-request-entity-too-large
-
IPP_REQUEST_VALUE client-error-request-value-too-long
-
IPP_SERVICE_UNAVAILABLE server-error-service-unavailable
-
IPP_TEMPORARY_ERROR server-error-temporary-error
-
IPP_TIMEOUT client-error-timeout
-
IPP_TOO_MANY_SUBSCRIPTIONS client-error-too-many-subscriptions
-
IPP_URI_SCHEME client-error-uri-scheme-not-supported
-
IPP_VERSION_NOT_SUPPORTED server-error-version-not-supported
-

-
-
ipp_tag_e

-
Description

-
Format tags for attributes...
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
IPP_TAG_ADMINDEFINE Admin-defined value
-
IPP_TAG_BEGIN_COLLECTION Beginning of collection value
-
IPP_TAG_BOOLEAN Boolean value
-
IPP_TAG_CHARSET Character set value
-
IPP_TAG_COPY Bitflag for copied attribute values
-
IPP_TAG_DATE Date/time value
-
IPP_TAG_DEFAULT Default value
-
IPP_TAG_DELETEATTR Delete-attribute value
-
IPP_TAG_END End-of-attributes
-
IPP_TAG_END_COLLECTION End of collection value
-
IPP_TAG_ENUM Enumeration value
-
IPP_TAG_EVENT_NOTIFICATION Event group
-
IPP_TAG_INTEGER Integer value
-
IPP_TAG_JOB Job group
-
IPP_TAG_KEYWORD Keyword value
-
IPP_TAG_LANGUAGE Language value
-
IPP_TAG_MASK Mask for copied attribute values
-
IPP_TAG_MEMBERNAME Collection member name value
-
IPP_TAG_MIMETYPE MIME media type value
-
IPP_TAG_NAME Name value
-
IPP_TAG_NAMELANG Name-with-language value
-
IPP_TAG_NOTSETTABLE Not-settable value
-
IPP_TAG_NOVALUE No-value value
-
IPP_TAG_OPERATION Operation group
-
IPP_TAG_PRINTER Printer group
-
IPP_TAG_RANGE Range value
-
IPP_TAG_RESOLUTION Resolution value
-
IPP_TAG_STRING Octet string value
-
IPP_TAG_SUBSCRIPTION Subscription group
-
IPP_TAG_TEXT Text value
-
IPP_TAG_TEXTLANG Text-with-language value
-
IPP_TAG_UNKNOWN Unknown value
-
IPP_TAG_UNSUPPORTED_GROUP Unsupported attributes group
-
IPP_TAG_UNSUPPORTED_VALUE Unsupported value
-
IPP_TAG_URI URI value
-
IPP_TAG_URISCHEME URI scheme value
-
IPP_TAG_ZERO Zero tag - used for separators
-

-
-
Functions

-
-
-
 CUPS 1.1.20 cupsDoAuthentication()

-
Description

-
Authenticate a request.
-
This function should be called in response to a HTTP_UNAUTHORIZED
-status, prior to resubmitting your request.
+
The cupsDoRequest 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
+ippFindAttribute and
+ippFindNextAttribute functions
+to find specific attributes, for example:

 
+
+ipp_t *response;
+ipp_attribute_t *attr;
 
-
Syntax

-

-int

-cupsDoAuthentication(
-    http_t * http,
-    const char * method,
-    const char * resource);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
methodRequest method (GET, POST, PUT)
resourceResource path

-
Returns

-
0 on success, -1 on error

-
-
cupsDoFileRequest()

-
Description

-
Do an IPP request with a file.
-
This function sends the IPP request to the specified server, retrying
+attr = ippFindAttribute(response, "printer-state", IPP_TAG_ENUM);
+

+
+
You can also walk the list of attributes with a simple for loop
+like this:

+
+
+ipp_t *response;
+ipp_attribute_t *attr;
+
+for (attr = response->attrs; attr != NULL; attr = attr->next)
+  if (attr->name == NULL)
+    puts("--SEPARATOR--");
+  else
+    puts(attr->name);
+

+
+
The for loop approach is normally used when collecting
+attributes for multiple objects (jobs, printers, etc.) in a response. Attributes
+with NULL names indicate a separator between the attributes of
+each object. For example, the following code will list the jobs returned from
+our previous get_jobs example code:

+
+
+ipp_t *response = get_jobs();
+
+if (response != NULL)
+{
+  ipp_attribute_t *attr;
+  int job_id = 0;
+  char *job_name = NULL;
+  char *job_originating_user_name = NULL;
+
+  puts("Job ID  Owner             Title");
+  puts("------  ----------------  ---------------------------------");
+
+  for (attr = response->attrs; attr != NULL; attr = attr->next)
+  {
+   /* Attributes without names are separators between jobs */
+    if (attr->name == NULL)
+    {
+      if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL)
+        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;
+  }
+
+  if (job_id > 0 && job_name != NULL && job_originating_user_name != NULL)
+    printf("%5d  %-16s  %s\n", job_id, job_originating_user_name, job_name);
+}
+

+
+
Creating URI Strings

+
+
To ensure proper encoding, the
+httpAssembleURIf function must be
+used to format a "printer-uri" string for all printer-based requests:

+
+
+const char *name = "Foo";
+char uri[1024];
+ipp_t *request;
+
+httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
+                 ippPort(), "/printers/%s", name);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
+

+
+
Sending Requests with Files

+
+
The cupsDoFileRequest and
+cupsDoIORequest functions are
+used for requests involving files. The
+cupsDoFileRequest function
+attaches the named file to a request and is typically used when sending a print
+file or changing a printer's PPD file:

+
+
+const char *filename = "/usr/share/cups/data/testprint.ps";
+const char *name = "Foo";
+char uri[1024];
+char resource[1024];
+ipp_t *request = ippNewRequest(IPP_PRINT_JOB);
+ipp_t *response;
+
+/* Use httpAssembleURIf for the printer-uri string */
+httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(),
+                 ippPort(), "/printers/%s", name);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri);
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
+             NULL, cupsUser());
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
+             NULL, "testprint.ps");
+
+/* Use snprintf for the resource path */
+snprintf(resource, sizeof(resource), "/printers/%s", name);
+
+response = cupsDoFileRequest(CUPS_HTTP_DEFAULT, request, resource, filename);
+

+
+
The cupsDoIORequest function
+optionally attaches a file to the request and optionally saves a file in the
+response from the server. It is used when using a pipe for the request
+attachment or when using a request that returns a file, currently only
+CUPS_GET_DOCUMENT and CUPS_GET_PPD. For example,
+the following code will download the PPD file for the sample HP LaserJet
+printer driver:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+response = cupsDoIORequest(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd);
+

+
+
The example passes -1 for the input file descriptor to specify
+that no file is to be attached to the request. The PPD file attached to the
+response is written to the temporary file descriptor we created using the
+cupsTempFd function.

+
+
Asynchronous Request Processing

+
+
The cupsSendRequest and
+cupsGetResponse support
+asynchronous communications with the server. Unlike the other request
+functions, the IPP request is not automatically freed, so remember to
+free your request with the ippDelete
+function.

+
+
File data is attached to the request using the
+cupsWriteRequestData
+function, while file data returned from the server is read using the
+cupsReadResponseData
+function. We can rewrite the previous CUPS_GET_PPD example
+to use the asynchronous functions quite easily:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+if (cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE)
+{
+  response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/");
+
+  if (response != NULL)
+  {
+    ssize_t bytes;
+    char buffer[8192];
+
+    while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
+      write(tempfd, buffer, bytes);
+  }
+}
+
+/* Free the request! */
+ippDelete(request);
+

+
+
The cupsSendRequest function
+returns the initial HTTP request status, typically either
+HTTP_CONTINUE or HTTP_UNAUTHORIZED. The latter status
+is returned when the request requires authentication of some sort. The
+cupsDoAuthentication function
+must be called when your see HTTP_UNAUTHORIZED and the request
+re-sent. We can add authentication support to our example code by using a
+do ... while loop:

+
+
+char tempfile[1024];
+int tempfd;
+ipp_t *request = ippNewRequest(CUPS_GET_PPD);
+ipp_t *response;
+http_status_t status;
+
+ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name",
+             NULL, "laserjet.ppd");
+
+tempfd = cupsTempFd(tempfile, sizeof(tempfile));
+
+/* Loop for authentication */
+do
+{
+  status = a href='#cupsSendRequest'>cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/");
+
+  if (status == HTTP_UNAUTHORIZED)
+  {
+    /* Try to authenticate, break out of the loop if that fails */
+    if (cupsDoAuthentication(CUPS_HTTP_DEFAULT, "POST", "/"))
+      break;
+  }
+}
+while (status != HTTP_CONTINUE && status != HTTP_UNAUTHORIZED);
+
+if (status == HTTP_CONTINUE)
+{
+  response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/");
+
+  if (response != NULL)
+  {
+    ssize_t bytes;
+    char buffer[8192];
+
+    while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0)
+      write(tempfd, buffer, bytes);
+  }
+}
+
+/* Free the request! */
+ippDelete(request);
+

+
Functions

+
 CUPS 1.1.20 cupsDoAuthentication

+
Authenticate a request.

+

+int cupsDoAuthentication (

+    http_t *http,

+    const char *method,

+    const char *resource

+);

+
Parameters

+

+
http

+
HTTP connection to server

+
method

+
Request method ("GET", "POST", "PUT")

+
resource

+
Resource path

+

+
Return Value

+
0 on success, -1 on error

+
Discussion

+
This function should be called in response to a HTTP_UNAUTHORIZED
+status, prior to resubmitting your request.
+
+

+
cupsDoFileRequest

+
Do an IPP request with a file.

+

+ipp_t *cupsDoFileRequest (

+    http_t *http,

+    ipp_t *request,

+    const char *resource,

+    const char *filename

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
request

+
IPP request

+
resource

+
HTTP resource for POST

+
filename

+
File to send or NULL for none

+

+
Return Value

+
Response data

+
Discussion

+
This function sends the IPP request to the specified server, retrying
 and authenticating as necessary.  The request is freed with ippDelete()
-after receiving a valid IPP response.
-
Syntax

-

-ipp_t *

-cupsDoFileRequest(
-    http_t * http,
-    ipp_t * request,
-    const char * resource,
-    const char * filename);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
httpHTTP connection to server
requestIPP request
resourceHTTP resource for POST
filenameFile to send or NULL for none

-
Returns

-
Response data

-
-
 CUPS 1.3 cupsDoIORequest()

-
Description

-
Do an IPP request with file descriptors.
-
This function sends the IPP request to the specified server, retrying
+after receiving a valid IPP response.

+
 CUPS 1.3 cupsDoIORequest

+
Do an IPP request with file descriptors.

+

+ipp_t *cupsDoIORequest (

+    http_t *http,

+    ipp_t *request,

+    const char *resource,

+    int infile,

+    int outfile

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
request

+
IPP request

+
resource

+
HTTP resource for POST

+
infile

+
File to read from or -1 for none

+
outfile

+
File to write to or -1 for none

+

+
Return Value

+
Response data

+
Discussion

+
This function sends the IPP request to the specified server, retrying
 and authenticating as necessary.  The request is freed with ippDelete()
-after receiving a valid IPP response.
-
If "infile" is a valid file descriptor, cupsDoIORequest() copies
-all of the data from the file after the IPP request message.
-
If "outfile" is a valid file descriptor, cupsDoIORequest() copies
+after receiving a valid IPP response.

+

+If "infile" is a valid file descriptor, cupsDoIORequest() copies
+all of the data from the file after the IPP request message.

+

+If "outfile" is a valid file descriptor, cupsDoIORequest() copies
 all of the data after the IPP response message to the file.
 
-
-
Syntax

-

-ipp_t *

-cupsDoIORequest(
-    http_t * http,
-    ipp_t * request,
-    const char * resource,
-    int infile,
-    int outfile);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection to server
requestIPP request
resourceHTTP resource for POST
infileFile to read from or -1 for none
outfileFile to write to or -1 for none

-
Returns

-
Response data

-
-
cupsDoRequest()

-
Description

-
Do an IPP request.
-
This function sends the IPP request to the specified server, retrying
+

+
cupsDoRequest

+
Do an IPP request.

+

+ipp_t *cupsDoRequest (

+    http_t *http,

+    ipp_t *request,

+    const char *resource

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
request

+
IPP request

+
resource

+
HTTP resource for POST

+

+
Return Value

+
Response data

+
Discussion

+
This function sends the IPP request to the specified server, retrying
 and authenticating as necessary.  The request is freed with ippDelete()
-after receiving a valid IPP response.
-
Syntax

-

-ipp_t *

-cupsDoRequest(
-    http_t * http,
-    ipp_t * request,
-    const char * resource);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection to server
requestIPP request
resourceHTTP resource for POST

-
Returns

-
Response data

-
-
cupsEncodeOptions()

-
Description

-
Encode printer options into IPP attributes.
-
This function adds operation, job, and then subscription attributes,
+after receiving a valid IPP response.

+
cupsEncodeOptions

+
Encode printer options into IPP attributes.

+

+void cupsEncodeOptions (

+    ipp_t *ipp,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
ipp

+
Request to add to

+
num_options

+
Number of options

+
options

+
Options

+

+
Discussion

+
This function adds operation, job, and then subscription attributes,
 in that order. Use the cupsEncodeOptions2() function to add attributes
-for a single group.
-
Syntax

-

-void

-cupsEncodeOptions(
-    ipp_t * ipp,
-    int num_options,
-    cups_option_t * options);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ippRequest to add to
num_optionsNumber of options
optionsOptions

-
Returns

-
Nothing.

-
-
 CUPS 1.2 cupsEncodeOptions2()

-
Description

-
Encode printer options into IPP attributes for a group.
-
This function only adds attributes for a single group. Call this
+for a single group.

+
 CUPS 1.2 cupsEncodeOptions2

+
Encode printer options into IPP attributes for a group.

+

+void cupsEncodeOptions2 (

+    ipp_t *ipp,

+    int num_options,

+    cups_option_t *options,

+    ipp_tag_t group_tag

+);

+
Parameters

+

+
ipp

+
Request to add to

+
num_options

+
Number of options

+
options

+
Options

+
group_tag

+
Group to encode

+

+
Discussion

+
This function only adds attributes for a single group. Call this
 function multiple times for each group, or use cupsEncodeOptions()
 to add the standard groups.
 
-
-
Syntax

-

-void

-cupsEncodeOptions2(
-    ipp_t * ipp,
-    int num_options,
-    cups_option_t * options,
-    ipp_tag_t group_tag);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
ippRequest to add to
num_optionsNumber of options
optionsOptions
group_tagGroup to encode

-
Returns

-
Nothing.

-
-
 CUPS 1.2 httpAddrAny()

-
Description

-
Check for the "any" address.
-
-
-
Syntax

-

-int

-httpAddrAny(
-    const http_addr_t * addr);
-

-
Arguments

-

-
-
-
-
NameDescription
addrAddress to check

-
Returns

-
1 if "any", 0 otherwise

-
-
 CUPS 1.2 httpAddrEqual()

-
Description

-
Compare two addresses.
-
-
-
Syntax

-

-int

-httpAddrEqual(
-    const http_addr_t * addr1,
-    const http_addr_t * addr2);
-

-
Arguments

-

-
-
-
-
-
NameDescription
addr1First address
addr2Second address

-
Returns

-
1 if equal, 0 if not

-
-
 CUPS 1.2 httpAddrLength()

-
Description

-
Return the length of the address in bytes.
-
-
-
Syntax

-

-int

-httpAddrLength(
-    const http_addr_t * addr);
-

-
Arguments

-

-
-
-
-
NameDescription
addrAddress

-
Returns

-
Length in bytes

-
-
 CUPS 1.2 httpAddrLocalhost()

-
Description

-
Check for the local loopback address.
-
-
-
Syntax

-

-int

-httpAddrLocalhost(
-    const http_addr_t * addr);
-

-
Arguments

-

-
-
-
-
NameDescription
addrAddress to check

-
Returns

-
1 if local host, 0 otherwise

-
-
 CUPS 1.2 httpAddrLookup()

-
Description

-
Lookup the hostname associated with the address.
-
-
-
Syntax

-

-char *

-httpAddrLookup(
-    const http_addr_t * addr,
-    char * name,
-    int namelen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
addrAddress to lookup
nameHost name buffer
namelenSize of name buffer

-
Returns

-
Host name

-
-
 CUPS 1.2 httpAddrString()

-
Description

-
Convert an address to a numeric string.
-
-
-
Syntax

-

-char *

-httpAddrString(
-    const http_addr_t * addr,
-    char * s,
-    int slen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
addrAddress to convert
sString buffer
slenLength of string

-
Returns

-
Numeric address string

-
-
 CUPS 1.2 httpAssembleURI()

-
Description

-
Assemble a uniform resource identifier from its
-components.
-
This function escapes reserved characters in the URI depending on the
+

+
 CUPS 1.4 cupsGetResponse

+
Get a response to an IPP request.

+

+ipp_t *cupsGetResponse (

+    http_t *http,

+    const char *resource

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
resource

+
HTTP resource for POST

+

+
Return Value

+
Response or NULL on HTTP error

+
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.
+
+

+
 CUPS 1.4 cupsReadResponseData

+
Read additional data after the IPP response.

+

+ssize_t cupsReadResponseData (

+    http_t *http,

+    char *buffer,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
buffer

+
Buffer to use

+
length

+
Number of bytes to read

+

+
Return Value

+
Bytes read, 0 on EOF, -1 on error

+
Discussion

+
This function is used after cupsGetResponse() to read the PPD or document
+files for CUPS_GET_PPD and CUPS_GET_DOCUMENT requests, respectively.
+
+

+
 CUPS 1.4 cupsSendRequest

+
Send an IPP request.

+

+http_status_t cupsSendRequest (

+    http_t *http,

+    ipp_t *request,

+    const char *resource,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
request

+
IPP request

+
resource

+
Resource path

+
length

+
Length of data to follow or CUPS_LENGTH_VARIABLE

+

+
Return Value

+
Initial HTTP status

+
Discussion

+
Use httpWrite() to write any additional data (document, PPD file, etc.)
+for the request, cupsGetResponse() to get the IPP response, and httpRead()
+to read any additional data following the response. Only one request can be 
+sent/queued at a time.

+

+Unlike cupsDoFileRequest(), cupsDoIORequest(), and cupsDoRequest(), the
+request is not freed.
+
+

+
 CUPS 1.4 cupsWriteRequestData

+
Write additional data after an IPP request.

+

+http_status_t cupsWriteRequestData (

+    http_t *http,

+    const char *buffer,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection or CUPS_HTTP_DEFAULT

+
buffer

+
Bytes to write

+
length

+
Number of bytes to write

+

+
Return Value

+
HTTP_CONTINUE if OK or HTTP status on error

+
Discussion

+
This function is used after cupsSendRequest() or cupsStartDocument()
+to provide a PPD or document file as needed.
+
+

+
 CUPS 1.2 httpAddrAny

+
Check for the "any" address.

+

+int httpAddrAny (

+    const http_addr_t *addr

+);

+
Parameters

+

+
addr

+
Address to check

+

+
Return Value

+
1 if "any", 0 otherwise

+
 CUPS 1.2 httpAddrEqual

+
Compare two addresses.

+

+int httpAddrEqual (

+    const http_addr_t *addr1,

+    const http_addr_t *addr2

+);

+
Parameters

+

+
addr1

+
First address

+
addr2

+
Second address

+

+
Return Value

+
1 if equal, 0 if not

+
 CUPS 1.2 httpAddrLength

+
Return the length of the address in bytes.

+

+int httpAddrLength (

+    const http_addr_t *addr

+);

+
Parameters

+

+
addr

+
Address

+

+
Return Value

+
Length in bytes

+
 CUPS 1.2 httpAddrLocalhost

+
Check for the local loopback address.

+

+int httpAddrLocalhost (

+    const http_addr_t *addr

+);

+
Parameters

+

+
addr

+
Address to check

+

+
Return Value

+
1 if local host, 0 otherwise

+
 CUPS 1.2 httpAddrLookup

+
Lookup the hostname associated with the address.

+

+char *httpAddrLookup (

+    const http_addr_t *addr,

+    char *name,

+    int namelen

+);

+
Parameters

+

+
addr

+
Address to lookup

+
name

+
Host name buffer

+
namelen

+
Size of name buffer

+

+
Return Value

+
Host name

+
 CUPS 1.2 httpAddrString

+
Convert an address to a numeric string.

+

+char *httpAddrString (

+    const http_addr_t *addr,

+    char *s,

+    int slen

+);

+
Parameters

+

+
addr

+
Address to convert

+
s

+
String buffer

+
slen

+
Length of string

+

+
Return Value

+
Numeric address string

+
 CUPS 1.2 httpAssembleURI

+
Assemble a uniform resource identifier from its
+components.

+

+http_uri_status_t httpAssembleURI (

+    http_uri_coding_t encoding,

+    char *uri,

+    int urilen,

+    const char *scheme,

+    const char *username,

+    const char *host,

+    int port,

+    const char *resource

+);

+
Parameters

+

+
encoding

+
Encoding flags

+
uri

+
URI buffer

+
urilen

+
Size of URI buffer

+
scheme

+
Scheme name

+
username

+
Username

+
host

+
Hostname or address

+
port

+
Port number

+
resource

+
Resource

+

+
Return Value

+
URI status

+
Discussion

+
This function escapes reserved characters in the URI depending on the
 value of the "encoding" argument.  You should use this function in
 place of traditional string functions whenever you need to create a
 URI string.
 
-
-
Syntax

-

-http_uri_status_t

-httpAssembleURI(
-    http_uri_coding_t encoding,
-    char * uri,
-    int urilen,
-    const char * scheme,
-    const char * username,
-    const char * host,
-    int port,
-    const char * resource);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
-
NameDescription
encodingEncoding flags
uriURI buffer
urilenSize of URI buffer
schemeScheme name
usernameUsername
hostHostname or address
portPort number
resourceResource

-
Returns

-
URI status

-
-
 CUPS 1.2 httpAssembleURIf()

-
Description

-
Assemble a uniform resource identifier from its
-components with a formatted resource.
-
This function creates a formatted version of the resource string
+

+
 CUPS 1.2 httpAssembleURIf

+
Assemble a uniform resource identifier from its
+components with a formatted resource.

+

+http_uri_status_t httpAssembleURIf (

+    http_uri_coding_t encoding,

+    char *uri,

+    int urilen,

+    const char *scheme,

+    const char *username,

+    const char *host,

+    int port,

+    const char *resourcef,

+    ...

+);

+
Parameters

+

+
encoding

+
Encoding flags

+
uri

+
URI buffer

+
urilen

+
Size of URI buffer

+
scheme

+
Scheme name

+
username

+
Username

+
host

+
Hostname or address

+
port

+
Port number

+
resourcef

+
Printf-style resource

+
...

+
Additional arguments as needed

+

+
Return Value

+
URI status

+
Discussion

+
This function creates a formatted version of the resource string
 argument "resourcef" and escapes reserved characters in the URI
 depending on the value of the "encoding" argument.  You should use
 this function in place of traditional string functions whenever
 you need to create a URI string.
 
-
-
Syntax

-

-http_uri_status_t

-httpAssembleURIf(
-    http_uri_coding_t encoding,
-    char * uri,
-    int urilen,
-    const char * scheme,
-    const char * username,
-    const char * host,
-    int port,
-    const char * resourcef,
-    ...);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
encodingEncoding flags
uriURI buffer
urilenSize of URI buffer
schemeScheme name
usernameUsername
hostHostname or address
portPort number
resourcefPrintf-style resource
...Additional arguments as needed

-
Returns

-
URI status

-
-
httpBlocking()

-
Description

-
Set blocking/non-blocking behavior on a connection.
-
Syntax

-

-void

-httpBlocking(
-    http_t * http,
-    int b);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
b1 = blocking, 0 = non-blocking

-
Returns

-
Nothing.

-
-
httpCheck()

-
Description

-
Check to see if there is a pending response from the server.
-
Syntax

-

-int

-httpCheck(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
0 = no data, 1 = data available

-
-
 CUPS 1.1.19 httpClearCookie()

-
Description

-
Clear the cookie value(s).
-
-
-
Syntax

-

-void

-httpClearCookie(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Nothing.

-
-
httpClearFields()

-
Description

-
Clear HTTP request fields.
-
Syntax

-

-void

-httpClearFields(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Nothing.

-
-
httpClose()

-
Description

-
Close an HTTP connection...
-
Syntax

-

-void

-httpClose(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Nothing.

-
-
httpConnect()

-
Description

-
Connect to a HTTP server.
-
Syntax

-

-http_t *

-httpConnect(
-    const char * host,
-    int port);
-

-
Arguments

-

-
-
-
-
-
NameDescription
hostHost to connect to
portPort number

-
Returns

-
New HTTP connection

-
-
httpConnectEncrypt()

-
Description

-
Connect to a HTTP server using encryption.
-
Syntax

-

-http_t *

-httpConnectEncrypt(
-    const char * host,
-    int port,
-    http_encryption_t encryption);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
hostHost to connect to
portPort number
encryptionType of encryption to use

-
Returns

-
New HTTP connection

-
-
 DEPRECATED httpDecode64()

-
Description

-
Base64-decode a string.
-
This function is deprecated. Use the httpDecode64_2() function instead
+

+
httpBlocking

+
Set blocking/non-blocking behavior on a connection.

+

+void httpBlocking (

+    http_t *http,

+    int b

+);

+
Parameters

+

+
http

+
HTTP connection

+
b

+
1 = blocking, 0 = non-blocking

+

+
httpCheck

+
Check to see if there is a pending response from the server.

+

+int httpCheck (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
0 = no data, 1 = data available

+
 CUPS 1.1.19 httpClearCookie

+
Clear the cookie value(s).

+

+void httpClearCookie (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
httpClearFields

+
Clear HTTP request fields.

+

+void httpClearFields (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
httpClose

+
Close an HTTP connection...

+

+void httpClose (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
httpConnect

+
Connect to a HTTP server.

+

+http_t *httpConnect (

+    const char *host,

+    int port

+);

+
Parameters

+

+
host

+
Host to connect to

+
port

+
Port number

+

+
Return Value

+
New HTTP connection

+
httpConnectEncrypt

+
Connect to a HTTP server using encryption.

+

+http_t *httpConnectEncrypt (

+    const char *host,

+    int port,

+    http_encryption_t encryption

+);

+
Parameters

+

+
host

+
Host to connect to

+
port

+
Port number

+
encryption

+
Type of encryption to use

+

+
Return Value

+
New HTTP connection

+
 DEPRECATED httpDecode64

+
Base64-decode a string.

+

+char *httpDecode64 (

+    char *out,

+    const char *in

+);

+
Parameters

+

+
out

+
String to write to

+
in

+
String to read from

+

+
Return Value

+
Decoded string

+
Discussion

+
This function is deprecated. Use the httpDecode64_2() function instead
 which provides buffer length arguments.
 
-
-
Syntax

-

-char *

-httpDecode64(
-    char * out,
-    const char * in);
-

-
Arguments

-

-
-
-
-
-
NameDescription
outString to write to
inString to read from

-
Returns

-
Decoded string

-
-
 CUPS 1.1.21 httpDecode64_2()

-
Description

-
Base64-decode a string.
-
-
-
Syntax

-

-char *

-httpDecode64_2(
-    char * out,
-    int * outlen,
-    const char * in);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
outString to write to
outlenSize of output string
inString to read from

-
Returns

-
Decoded string

-
-
httpDelete()

-
Description

-
Send a DELETE request to the server.
-
Syntax

-

-int

-httpDelete(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI to delete

-
Returns

-
Status of call (0 = success)

-
-
 DEPRECATED httpEncode64()

-
Description

-
Base64-encode a string.
-
This function is deprecated. Use the httpEncode64_2() function instead
+

+
 CUPS 1.1.21 httpDecode64_2

+
Base64-decode a string.

+

+char *httpDecode64_2 (

+    char *out,

+    int *outlen,

+    const char *in

+);

+
Parameters

+

+
out

+
String to write to

+
outlen

+
Size of output string

+
in

+
String to read from

+

+
Return Value

+
Decoded string

+
httpDelete

+
Send a DELETE request to the server.

+

+int httpDelete (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI to delete

+

+
Return Value

+
Status of call (0 = success)

+
 DEPRECATED httpEncode64

+
Base64-encode a string.

+

+char *httpEncode64 (

+    char *out,

+    const char *in

+);

+
Parameters

+

+
out

+
String to write to

+
in

+
String to read from

+

+
Return Value

+
Encoded string

+
Discussion

+
This function is deprecated. Use the httpEncode64_2() function instead
 which provides buffer length arguments.
 
-
-
Syntax

-

-char *

-httpEncode64(
-    char * out,
-    const char * in);
-

-
Arguments

-

-
-
-
-
-
NameDescription
outString to write to
inString to read from

-
Returns

-
Encoded string

-
-
 CUPS 1.1.21 httpEncode64_2()

-
Description

-
Base64-encode a string.
-
-
-
Syntax

-

-char *

-httpEncode64_2(
-    char * out,
-    int outlen,
-    const char * in,
-    int inlen);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
outString to write to
outlenSize of output string
inString to read from
inlenSize of input string

-
Returns

-
Encoded string

-
-
httpEncryption()

-
Description

-
Set the required encryption on the link.
-
Syntax

-

-int

-httpEncryption(
-    http_t * http,
-    http_encryption_t e);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
eNew encryption preference

-
Returns

-
-1 on error, 0 on success

-
-
httpError()

-
Description

-
Get the last error on a connection.
-
Syntax

-

-int

-httpError(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Error code (errno) value

-
-
httpFlush()

-
Description

-
Flush data from a HTTP connection.
-
Syntax

-

-void

-httpFlush(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Nothing.

-
-
 CUPS 1.2 httpFlushWrite()

-
Description

-
Flush data in write buffer.
-
-
-
Syntax

-

-int

-httpFlushWrite(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Bytes written or -1 on error

-
-
httpGet()

-
Description

-
Send a GET request to the server.
-
Syntax

-

-int

-httpGet(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI to get

-
Returns

-
Status of call (0 = success)

-
-
 CUPS 1.3 httpGetAuthString()

-
Description

-
Get the current authorization string.
-
The authorization string is set by cupsDoAuthentication() and
+

+
 CUPS 1.1.21 httpEncode64_2

+
Base64-encode a string.

+

+char *httpEncode64_2 (

+    char *out,

+    int outlen,

+    const char *in,

+    int inlen

+);

+
Parameters

+

+
out

+
String to write to

+
outlen

+
Size of output string

+
in

+
String to read from

+
inlen

+
Size of input string

+

+
Return Value

+
Encoded string

+
httpEncryption

+
Set the required encryption on the link.

+

+int httpEncryption (

+    http_t *http,

+    http_encryption_t e

+);

+
Parameters

+

+
http

+
HTTP connection

+
e

+
New encryption preference

+

+
Return Value

+
-1 on error, 0 on success

+
httpError

+
Get the last error on a connection.

+

+int httpError (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
Error code (errno) value

+
httpFlush

+
Flush data from a HTTP connection.

+

+void httpFlush (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
 CUPS 1.2 httpFlushWrite

+
Flush data in write buffer.

+

+int httpFlushWrite (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
Bytes written or -1 on error

+
httpGet

+
Send a GET request to the server.

+

+int httpGet (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI to get

+

+
Return Value

+
Status of call (0 = success)

+
 CUPS 1.3 httpGetAuthString

+
Get the current authorization string.

+

+char *httpGetAuthString (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
Authorization string

+
Discussion

+
The authorization string is set by cupsDoAuthentication() and
 httpSetAuthString().  Use httpGetAuthString() to retrieve the
 string to use with httpSetField() for the HTTP_FIELD_AUTHORIZATION
 value.
 
-
-
Syntax

-

-char *

-httpGetAuthString(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Authorization string

-
-
 CUPS 1.2 httpGetBlocking()

-
Description

-
Get the blocking/non-block state of a connection.
-
-
-
Syntax

-

-int

-httpGetBlocking(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
1 if blocking, 0 if non-blocking

-
-
 CUPS 1.1.19 httpGetCookie()

-
Description

-
Get any cookie data from the response.
-
-
-
Syntax

-

-const char *

-httpGetCookie(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connecion

-
Returns

-
Cookie data or NULL

-
-
 DEPRECATED httpGetDateString()

-
Description

-
Get a formatted date/time string from a time value.
-
-
-
Syntax

-

-const char *

-httpGetDateString(
-    time_t t);
-

-
Arguments

-

-
-
-
-
NameDescription
tUNIX time

-
Returns

-
Date/time string

-
-
 CUPS 1.2 httpGetDateString2()

-
Description

-
Get a formatted date/time string from a time value.
-
-
-
Syntax

-

-const char *

-httpGetDateString2(
-    time_t t,
-    char * s,
-    int slen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
tUNIX time
sString buffer
slenSize of string buffer

-
Returns

-
Date/time string

-
-
httpGetDateTime()

-
Description

-
Get a time value from a formatted date/time string.
-
Syntax

-

-time_t

-httpGetDateTime(
-    const char * s);
-

-
Arguments

-

-
-
-
-
NameDescription
sDate/time string

-
Returns

-
UNIX time

-
-
 CUPS 1.2 httpGetFd()

-
Description

-
Get the file descriptor associated with a connection.
-
-
-
Syntax

-

-int

-httpGetFd(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
File descriptor or -1 if none

-
-
httpGetField()

-
Description

-
Get a field value from a request/response.
-
Syntax

-

-const char *

-httpGetField(
-    http_t * http,
-    http_field_t field);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
fieldField to get

-
Returns

-
Field value

-
-
 DEPRECATED httpGetHostByName()

-
Description

-
Lookup a hostname or IPv4 address, and return
-address records for the specified name.
-
-
-
Syntax

-

-struct hostent *

-httpGetHostByName(
-    const char * name);
-

-
Arguments

-

-
-
-
-
NameDescription
nameHostname or IP address

-
Returns

-
Host entry

-
-
 CUPS 1.2 httpGetHostname()

-
Description

-
Get the FQDN for the connection or local system.
-
When "http" points to a connected socket, return the hostname or
+

+
 CUPS 1.2 httpGetBlocking

+
Get the blocking/non-block state of a connection.

+

+int httpGetBlocking (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
1 if blocking, 0 if non-blocking

+
 CUPS 1.1.19 httpGetCookie

+
Get any cookie data from the response.

+

+const char *httpGetCookie (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connecion

+

+
Return Value

+
Cookie data or NULL

+
 DEPRECATED httpGetDateString

+
Get a formatted date/time string from a time value.

+

+const char *httpGetDateString (

+    time_t t

+);

+
Parameters

+

+
t

+
UNIX time

+

+
Return Value

+
Date/time string

+
 CUPS 1.2 httpGetDateString2

+
Get a formatted date/time string from a time value.

+

+const char *httpGetDateString2 (

+    time_t t,

+    char *s,

+    int slen

+);

+
Parameters

+

+
t

+
UNIX time

+
s

+
String buffer

+
slen

+
Size of string buffer

+

+
Return Value

+
Date/time string

+
httpGetDateTime

+
Get a time value from a formatted date/time string.

+

+time_t httpGetDateTime (

+    const char *s

+);

+
Parameters

+

+
s

+
Date/time string

+

+
Return Value

+
UNIX time

+
 CUPS 1.2 httpGetFd

+
Get the file descriptor associated with a connection.

+

+int httpGetFd (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
File descriptor or -1 if none

+
httpGetField

+
Get a field value from a request/response.

+

+const char *httpGetField (

+    http_t *http,

+    http_field_t field

+);

+
Parameters

+

+
http

+
HTTP connection

+
field

+
Field to get

+

+
Return Value

+
Field value

+
 DEPRECATED httpGetHostByName

+
Lookup a hostname or IPv4 address, and return
+address records for the specified name.

+

+struct hostent *httpGetHostByName (

+    const char *name

+);

+
Parameters

+

+
name

+
Hostname or IP address

+

+
Return Value

+
Host entry

+
 CUPS 1.2 httpGetHostname

+
Get the FQDN for the connection or local system.

+

+const char *httpGetHostname (

+    http_t *http,

+    char *s,

+    int slen

+);

+
Parameters

+

+
http

+
HTTP connection or NULL

+
s

+
String buffer for name

+
slen

+
Size of buffer

+

+
Return Value

+
FQDN for connection or system

+
Discussion

+
When "http" points to a connected socket, return the hostname or
 address that was used in the call to httpConnect() or httpConnectEncrypt().
 Otherwise, return the FQDN for the local system using both gethostname()
 and gethostbyname() to get the local hostname with domain.
 
-
-
Syntax

-

-const char *

-httpGetHostname(
-    http_t * http,
-    char * s,
-    int slen);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection or NULL
sString buffer for name
slenSize of buffer

-
Returns

-
FQDN for connection or system

-
-
 DEPRECATED httpGetLength()

-
Description

-
Get the amount of data remaining from the
-content-length or transfer-encoding fields.
-
This function is deprecated and will not return lengths larger than
+

+
 DEPRECATED httpGetLength

+
Get the amount of data remaining from the
+content-length or transfer-encoding fields.

+

+int httpGetLength (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
Content length

+
Discussion

+
This function is deprecated and will not return lengths larger than
 2^31 - 1; use httpGetLength2() instead.
 
-
-
Syntax

-

-int

-httpGetLength(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Content length

-
-
 CUPS 1.2 httpGetLength2()

-
Description

-
Get the amount of data remaining from the
-content-length or transfer-encoding fields.
-
This function returns the complete content length, even for
+

+
 CUPS 1.2 httpGetLength2

+
Get the amount of data remaining from the
+content-length or transfer-encoding fields.

+

+off_t httpGetLength2 (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
Content length

+
Discussion

+
This function returns the complete content length, even for
 content larger than 2^31 - 1.
 
-
-
Syntax

-

-off_t

-httpGetLength2(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
Content length

-
-
 CUPS 1.2 httpGetStatus()

-
Description

-
Get the status of the last HTTP request.
-
-
-
Syntax

-

-http_status_t

-httpGetStatus(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
HTTP status

-
-
 DEPRECATED httpGetSubField()

-
Description

-
Get a sub-field value.
-
-
-
Syntax

-

-char *

-httpGetSubField(
-    http_t * http,
-    http_field_t field,
-    const char * name,
-    char * value);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
httpHTTP connection
fieldField index
nameName of sub-field
valueValue string

-
Returns

-
Value or NULL

-
-
 CUPS 1.2 httpGetSubField2()

-
Description

-
Get a sub-field value.
-
-
-
Syntax

-

-char *

-httpGetSubField2(
-    http_t * http,
-    http_field_t field,
-    const char * name,
-    char * value,
-    int valuelen);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
httpHTTP connection
fieldField index
nameName of sub-field
valueValue string
valuelenSize of value buffer

-
Returns

-
Value or NULL

-
-
httpGets()

-
Description

-
Get a line of text from a HTTP connection.
-
Syntax

-

-char *

-httpGets(
-    char * line,
-    int length,
-    http_t * http);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
lineLine to read into
lengthMax length of buffer
httpHTTP connection

-
Returns

-
Line or NULL

-
-
httpHead()

-
Description

-
Send a HEAD request to the server.
-
Syntax

-

-int

-httpHead(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI for head

-
Returns

-
Status of call (0 = success)

-
-
httpInitialize()

-
Description

-
Initialize the HTTP interface library and set the
-default HTTP proxy (if any).
-
Syntax

-

-void

-httpInitialize(void);
-

-
Arguments

-
None.

-
Returns

-
Nothing.

-
-
httpMD5()

-
Description

-
Compute the MD5 sum of the username:group:password.
-
Syntax

-

-char *

-httpMD5(
-    const char * username,
-    const char * realm,
-    const char * passwd,
-    char md5[33]);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
usernameUser name
realmRealm name
passwdPassword string
md5[33]MD5 string

-
Returns

-
MD5 sum

-
-
httpMD5Final()

-
Description

-
Combine the MD5 sum of the username, group, and password
+

+
 CUPS 1.2 httpGetStatus

+
Get the status of the last HTTP request.

+

+http_status_t httpGetStatus (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
HTTP status

+
 DEPRECATED httpGetSubField

+
Get a sub-field value.

+

+char *httpGetSubField (

+    http_t *http,

+    http_field_t field,

+    const char *name,

+    char *value

+);

+
Parameters

+

+
http

+
HTTP connection

+
field

+
Field index

+
name

+
Name of sub-field

+
value

+
Value string

+

+
Return Value

+
Value or NULL

+
 CUPS 1.2 httpGetSubField2

+
Get a sub-field value.

+

+char *httpGetSubField2 (

+    http_t *http,

+    http_field_t field,

+    const char *name,

+    char *value,

+    int valuelen

+);

+
Parameters

+

+
http

+
HTTP connection

+
field

+
Field index

+
name

+
Name of sub-field

+
value

+
Value string

+
valuelen

+
Size of value buffer

+

+
Return Value

+
Value or NULL

+
httpGets

+
Get a line of text from a HTTP connection.

+

+char *httpGets (

+    char *line,

+    int length,

+    http_t *http

+);

+
Parameters

+

+
line

+
Line to read into

+
length

+
Max length of buffer

+
http

+
HTTP connection

+

+
Return Value

+
Line or NULL

+
httpHead

+
Send a HEAD request to the server.

+

+int httpHead (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI for head

+

+
Return Value

+
Status of call (0 = success)

+
httpInitialize

+
Initialize the HTTP interface library and set the
+default HTTP proxy (if any).

+

+void httpInitialize (void);

+
httpMD5

+
Compute the MD5 sum of the username:group:password.

+

+char *httpMD5 (

+    const char *username,

+    const char *realm,

+    const char *passwd,

+    char md5[33]

+);

+
Parameters

+

+
username

+
User name

+
realm

+
Realm name

+
passwd

+
Password string

+
md5[33]

+
MD5 string

+

+
Return Value

+
MD5 sum

+
httpMD5Final

+
Combine the MD5 sum of the username, group, and password
 with the server-supplied nonce value, method, and
-request-uri.
-
Syntax

-

-char *

-httpMD5Final(
-    const char * nonce,
-    const char * method,
-    const char * resource,
-    char md5[33]);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
nonceServer nonce value
methodMETHOD (GET, POST, etc.)
resourceResource path
md5[33]MD5 sum

-
Returns

-
New sum

-
-
httpMD5String()

-
Description

-
Convert an MD5 sum to a character string.
-
Syntax

-

-char *

-httpMD5String(
-    const unsigned char * sum,
-    char md5[33]);
-

-
Arguments

-

-
-
-
-
-
NameDescription
sumMD5 sum data
md5[33]MD5 sum in hex

-
Returns

-
MD5 sum in hex

-
-
httpOptions()

-
Description

-
Send an OPTIONS request to the server.
-
Syntax

-

-int

-httpOptions(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI for options

-
Returns

-
Status of call (0 = success)

-
-
httpPost()

-
Description

-
Send a POST request to the server.
-
Syntax

-

-int

-httpPost(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI for post

-
Returns

-
Status of call (0 = success)

-
-
httpPut()

-
Description

-
Send a PUT request to the server.
-
Syntax

-

-int

-httpPut(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI to put

-
Returns

-
Status of call (0 = success)

-
-
 DEPRECATED httpRead()

-
Description

-
Read data from a HTTP connection.
-
This function is deprecated. Use the httpRead2() function which can
+request-uri.

+

+char *httpMD5Final (

+    const char *nonce,

+    const char *method,

+    const char *resource,

+    char md5[33]

+);

+
Parameters

+

+
nonce

+
Server nonce value

+
method

+
METHOD (GET, POST, etc.)

+
resource

+
Resource path

+
md5[33]

+
MD5 sum

+

+
Return Value

+
New sum

+
httpMD5String

+
Convert an MD5 sum to a character string.

+

+char *httpMD5String (

+    const unsigned char *sum,

+    char md5[33]

+);

+
Parameters

+

+
sum

+
MD5 sum data

+
md5[33]

+
MD5 sum in hex

+

+
Return Value

+
MD5 sum in hex

+
httpOptions

+
Send an OPTIONS request to the server.

+

+int httpOptions (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI for options

+

+
Return Value

+
Status of call (0 = success)

+
httpPost

+
Send a POST request to the server.

+

+int httpPost (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI for post

+

+
Return Value

+
Status of call (0 = success)

+
httpPut

+
Send a PUT request to the server.

+

+int httpPut (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI to put

+

+
Return Value

+
Status of call (0 = success)

+
 DEPRECATED httpRead

+
Read data from a HTTP connection.

+

+int httpRead (

+    http_t *http,

+    char *buffer,

+    int length

+);

+
Parameters

+

+
http

+
HTTP connection

+
buffer

+
Buffer for data

+
length

+
Maximum number of bytes

+

+
Return Value

+
Number of bytes read

+
Discussion

+
This function is deprecated. Use the httpRead2() function which can
 read more than 2GB of data.
 
-
-
Syntax

-

-int

-httpRead(
-    http_t * http,
-    char * buffer,
-    int length);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
bufferBuffer for data
lengthMaximum number of bytes

-
Returns

-
Number of bytes read

-
-
 CUPS 1.2 httpRead2()

-
Description

-
Read data from a HTTP connection.
-
-
-
Syntax

-

-ssize_t

-httpRead2(
-    http_t * http,
-    char * buffer,
-    size_t length);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
bufferBuffer for data
lengthMaximum number of bytes

-
Returns

-
Number of bytes read

-
-
httpReconnect()

-
Description

-
Reconnect to a HTTP server.
-
Syntax

-

-int

-httpReconnect(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
0 on success, non-zero on failure

-
-
 DEPRECATED httpSeparate()

-
Description

-
Separate a Universal Resource Identifier into its
-components.
-
This function is deprecated; use the httpSeparateURI() function instead.
-
-
-
Syntax

-

-void

-httpSeparate(
-    const char * uri,
-    char * scheme,
-    char * username,
-    char * host,
-    int * port,
-    char * resource);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
uriUniversal Resource Identifier
schemeScheme [32] (http, https, etc.)
usernameUsername [1024]
hostHostname [1024]
portPort number to use
resourceResource/filename [1024]

-
Returns

-
Nothing.

-
-
 CUPS 1.1.21 httpSeparate2()

-
Description

-
Separate a Universal Resource Identifier into its
-components.
-
This function is deprecated; use the httpSeparateURI() function instead.
-
-
-
-
Syntax

-

-void

-httpSeparate2(
-    const char * uri,
-    char * scheme,
-    int schemelen,
-    char * username,
-    int usernamelen,
-    char * host,
-    int hostlen,
-    int * port,
-    char * resource,
-    int resourcelen);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
uriUniversal Resource Identifier
schemeScheme (http, https, etc.)
schemelenSize of scheme buffer
usernameUsername
usernamelenSize of username buffer
hostHostname
hostlenSize of hostname buffer
portPort number to use
resourceResource/filename
resourcelenSize of resource buffer

-
Returns

-
Nothing.

-
-
 CUPS 1.2 httpSeparateURI()

-
Description

-
Separate a Universal Resource Identifier into its
-components.
-
-
-
Syntax

-

-http_uri_status_t

-httpSeparateURI(
-    http_uri_coding_t decoding,
-    const char * uri,
-    char * scheme,
-    int schemelen,
-    char * username,
-    int usernamelen,
-    char * host,
-    int hostlen,
-    int * port,
-    char * resource,
-    int resourcelen);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
decodingDecoding flags
uriUniversal Resource Identifier
schemeScheme (http, https, etc.)
schemelenSize of scheme buffer
usernameUsername
usernamelenSize of username buffer
hostHostname
hostlenSize of hostname buffer
portPort number to use
resourceResource/filename
resourcelenSize of resource buffer

-
Returns

-
Result of separation

-
-
 CUPS 1.3 httpSetAuthString()

-
Description

-
Set the current authorization string.
-
This function just stores a copy of the current authorization string in
+

+
 CUPS 1.2 httpRead2

+
Read data from a HTTP connection.

+

+ssize_t httpRead2 (

+    http_t *http,

+    char *buffer,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection

+
buffer

+
Buffer for data

+
length

+
Maximum number of bytes

+

+
Return Value

+
Number of bytes read

+
httpReconnect

+
Reconnect to a HTTP server.

+

+int httpReconnect (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
0 on success, non-zero on failure

+
 DEPRECATED httpSeparate

+
Separate a Universal Resource Identifier into its
+components.

+

+void httpSeparate (

+    const char *uri,

+    char *scheme,

+    char *username,

+    char *host,

+    int *port,

+    char *resource

+);

+
Parameters

+

+
uri

+
Universal Resource Identifier

+
scheme

+
Scheme [32] (http, https, etc.)

+
username

+
Username [1024]

+
host

+
Hostname [1024]

+
port

+
Port number to use

+
resource

+
Resource/filename [1024]

+

+
Discussion

+
This function is deprecated; use the httpSeparateURI() function instead.
+
+

+
 CUPS 1.1.21 httpSeparate2

+
Separate a Universal Resource Identifier into its
+components.

+

+void httpSeparate2 (

+    const char *uri,

+    char *scheme,

+    int schemelen,

+    char *username,

+    int usernamelen,

+    char *host,

+    int hostlen,

+    int *port,

+    char *resource,

+    int resourcelen

+);

+
Parameters

+

+
uri

+
Universal Resource Identifier

+
scheme

+
Scheme (http, https, etc.)

+
schemelen

+
Size of scheme buffer

+
username

+
Username

+
usernamelen

+
Size of username buffer

+
host

+
Hostname

+
hostlen

+
Size of hostname buffer

+
port

+
Port number to use

+
resource

+
Resource/filename

+
resourcelen

+
Size of resource buffer

+

+
Discussion

+
This function is deprecated; use the httpSeparateURI() function instead.
+
+
+

+
 CUPS 1.2 httpSeparateURI

+
Separate a Universal Resource Identifier into its
+components.

+

+http_uri_status_t httpSeparateURI (

+    http_uri_coding_t decoding,

+    const char *uri,

+    char *scheme,

+    int schemelen,

+    char *username,

+    int usernamelen,

+    char *host,

+    int hostlen,

+    int *port,

+    char *resource,

+    int resourcelen

+);

+
Parameters

+

+
decoding

+
Decoding flags

+
uri

+
Universal Resource Identifier

+
scheme

+
Scheme (http, https, etc.)

+
schemelen

+
Size of scheme buffer

+
username

+
Username

+
usernamelen

+
Size of username buffer

+
host

+
Hostname

+
hostlen

+
Size of hostname buffer

+
port

+
Port number to use

+
resource

+
Resource/filename

+
resourcelen

+
Size of resource buffer

+

+
Return Value

+
Result of separation

+
 CUPS 1.3 httpSetAuthString

+
Set the current authorization string.

+

+void httpSetAuthString (

+    http_t *http,

+    const char *scheme,

+    const char *data

+);

+
Parameters

+

+
http

+
HTTP connection

+
scheme

+
Auth scheme (NULL to clear it)

+
data

+
Auth data (NULL for none)

+

+
Discussion

+
This function just stores a copy of the current authorization string in
 the HTTP connection object.  You must still call httpSetField() to set
 HTTP_FIELD_AUTHORIZATION prior to issuing a HTTP request using httpGet(),
 httpHead(), httpOptions(), httpPost, or httpPut().
 
-
-
Syntax

-

-void

-httpSetAuthString(
-    http_t * http,
-    const char * scheme,
-    const char * data);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
schemeAuth scheme (NULL to clear it)
dataAuth data (NULL for none)

-
Returns

-
Nothing.

-
-
 CUPS 1.1.19 httpSetCookie()

-
Description

-
Set the cookie value(s)...
-
-
-
Syntax

-

-void

-httpSetCookie(
-    http_t * http,
-    const char * cookie);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpConnection
cookieCookie string

-
Returns

-
Nothing.

-
-
 CUPS 1.2 httpSetExpect()

-
Description

-
Set the Expect: header in a request.
-
Currently only HTTP_CONTINUE is supported for the "expect" argument.
-
-
-
Syntax

-

-void

-httpSetExpect(
-    http_t * http,
-    http_status_t expect);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
expectHTTP status to expect (HTTP_CONTINUE)

-
Returns

-
Nothing.

-
-
httpSetField()

-
Description

-
Set the value of an HTTP header.
-
Syntax

-

-void

-httpSetField(
-    http_t * http,
-    http_field_t field,
-    const char * value);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
fieldField index
valueValue

-
Returns

-
Nothing.

-
-
 CUPS 1.2 httpSetLength()

-
Description

-
Set the content-length and content-encoding.
-
-
-
Syntax

-

-void

-httpSetLength(
-    http_t * http,
-    size_t length);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
lengthLength (0 for chunked)

-
Returns

-
Nothing.

-
-
httpStatus()

-
Description

-
Return a short string describing a HTTP status code.
-
Syntax

-

-const char *

-httpStatus(
-    http_status_t status);
-

-
Arguments

-

-
-
-
-
NameDescription
statusHTTP status code

-
Returns

-
String or NULL

-
-
httpTrace()

-
Description

-
Send an TRACE request to the server.
-
Syntax

-

-int

-httpTrace(
-    http_t * http,
-    const char * uri);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
uriURI for trace

-
Returns

-
Status of call (0 = success)

-
-
httpUpdate()

-
Description

-
Update the current HTTP state for incoming data.
-
Syntax

-

-http_status_t

-httpUpdate(
-    http_t * http);
-

-
Arguments

-

-
-
-
-
NameDescription
httpHTTP connection

-
Returns

-
HTTP status

-
-
 CUPS 1.1.19 httpWait()

-
Description

-
Wait for data available on a connection.
-
-
-
Syntax

-

-int

-httpWait(
-    http_t * http,
-    int msec);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
msecMilliseconds to wait

-
Returns

-
1 if data is available, 0 otherwise

-
-
 DEPRECATED httpWrite()

-
Description

-
Write data to a HTTP connection.
-
This function is deprecated. Use the httpWrite2() function which can
+

+
 CUPS 1.1.19 httpSetCookie

+
Set the cookie value(s)...

+

+void httpSetCookie (

+    http_t *http,

+    const char *cookie

+);

+
Parameters

+

+
http

+
Connection

+
cookie

+
Cookie string

+

+
 CUPS 1.2 httpSetExpect

+
Set the Expect: header in a request.

+

+void httpSetExpect (

+    http_t *http,

+    http_status_t expect

+);

+
Parameters

+

+
http

+
HTTP connection

+
expect

+
HTTP status to expect (HTTP_CONTINUE)

+

+
Discussion

+
Currently only HTTP_CONTINUE is supported for the "expect" argument.
+
+

+
httpSetField

+
Set the value of an HTTP header.

+

+void httpSetField (

+    http_t *http,

+    http_field_t field,

+    const char *value

+);

+
Parameters

+

+
http

+
HTTP connection

+
field

+
Field index

+
value

+
Value

+

+
 CUPS 1.2 httpSetLength

+
Set the content-length and content-encoding.

+

+void httpSetLength (

+    http_t *http,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection

+
length

+
Length (0 for chunked)

+

+
httpStatus

+
Return a short string describing a HTTP status code.

+

+const char *httpStatus (

+    http_status_t status

+);

+
Parameters

+

+
status

+
HTTP status code

+

+
Return Value

+
String or NULL

+
httpTrace

+
Send an TRACE request to the server.

+

+int httpTrace (

+    http_t *http,

+    const char *uri

+);

+
Parameters

+

+
http

+
HTTP connection

+
uri

+
URI for trace

+

+
Return Value

+
Status of call (0 = success)

+
httpUpdate

+
Update the current HTTP state for incoming data.

+

+http_status_t httpUpdate (

+    http_t *http

+);

+
Parameters

+

+
http

+
HTTP connection

+

+
Return Value

+
HTTP status

+
 CUPS 1.1.19 httpWait

+
Wait for data available on a connection.

+

+int httpWait (

+    http_t *http,

+    int msec

+);

+
Parameters

+

+
http

+
HTTP connection

+
msec

+
Milliseconds to wait

+

+
Return Value

+
1 if data is available, 0 otherwise

+
 DEPRECATED httpWrite

+
Write data to a HTTP connection.

+

+int httpWrite (

+    http_t *http,

+    const char *buffer,

+    int length

+);

+
Parameters

+

+
http

+
HTTP connection

+
buffer

+
Buffer for data

+
length

+
Number of bytes to write

+

+
Return Value

+
Number of bytes written

+
Discussion

+
This function is deprecated. Use the httpWrite2() function which can
 write more than 2GB of data.
 
-
-
Syntax

-

-int

-httpWrite(
-    http_t * http,
-    const char * buffer,
-    int length);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
bufferBuffer for data
lengthNumber of bytes to write

-
Returns

-
Number of bytes written

-
-
 CUPS 1.2 httpWrite2()

-
Description

-
Write data to a HTTP connection.
-
-
-
Syntax

-

-ssize_t

-httpWrite2(
-    http_t * http,
-    const char * buffer,
-    size_t length);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
httpHTTP connection
bufferBuffer for data
lengthNumber of bytes to write

-
Returns

-
Number of bytes written

-
-
ippAddBoolean()

-
Description

-
Add a boolean attribute to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddBoolean(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    char value);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
valueValue of attribute

-
Returns

-
New attribute

-
-
ippAddBooleans()

-
Description

-
Add an array of boolean values.
-
Syntax

-

-ipp_attribute_t *

-ippAddBooleans(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    int num_values,
-    const char * values);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
num_valuesNumber of values
valuesValues

-
Returns

-
New attribute

-
-
 CUPS 1.1.19 ippAddCollection()

-
Description

-
Add a collection value.
-
-
-
Syntax

-

-ipp_attribute_t *

-ippAddCollection(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    ipp_t * value);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
valueValue

-
Returns

-
New attribute

-
-
 CUPS 1.1.19 ippAddCollections()

-
Description

-
Add an array of collection values.
-
-
-
Syntax

-

-ipp_attribute_t *

-ippAddCollections(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    int num_values,
-    const ipp_t ** values);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
num_valuesNumber of values
valuesValues

-
Returns

-
New attribute

-
-
ippAddDate()

-
Description

-
Add a date attribute to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddDate(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    const ipp_uchar_t * value);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
valueValue

-
Returns

-
New attribute

-
-
ippAddInteger()

-
Description

-
Add a integer attribute to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddInteger(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    ipp_tag_t type,
-    const char * name,
-    int value);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
typeType of attribute
nameName of attribute
valueValue of attribute

-
Returns

-
New attribute

-
-
ippAddIntegers()

-
Description

-
Add an array of integer values.
-
Syntax

-

-ipp_attribute_t *

-ippAddIntegers(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    ipp_tag_t type,
-    const char * name,
-    int num_values,
-    const int * values);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
typeType of attribute
nameName of attribute
num_valuesNumber of values
valuesValues

-
Returns

-
New attribute

-
-
 CUPS 1.2 ippAddOctetString()

-
Description

-
Add an octetString value to an IPP message.
-
-
-
Syntax

-

-ipp_attribute_t *

-ippAddOctetString(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    const void * data,
-    int datalen);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
dataoctetString data
datalenLength of data in bytes

-
Returns

-
New attribute

-
-
ippAddRange()

-
Description

-
Add a range of values to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddRange(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    int lower,
-    int upper);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
lowerLower value
upperUpper value

-
Returns

-
New attribute

-
-
ippAddRanges()

-
Description

-
Add ranges of values to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddRanges(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    int num_values,
-    const int * lower,
-    const int * upper);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
num_valuesNumber of values
lowerLower values
upperUpper values

-
Returns

-
New attribute

-
-
ippAddResolution()

-
Description

-
Add a resolution value to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddResolution(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    ipp_res_t units,
-    int xres,
-    int yres);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
unitsUnits for resolution
xresX resolution
yresY resolution

-
Returns

-
New attribute

-
-
ippAddResolutions()

-
Description

-
Add resolution values to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddResolutions(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    const char * name,
-    int num_values,
-    ipp_res_t units,
-    const int * xres,
-    const int * yres);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
nameName of attribute
num_valuesNumber of values
unitsUnits for resolution
xresX resolutions
yresY resolutions

-
Returns

-
New attribute

-
-
ippAddSeparator()

-
Description

-
Add a group separator to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddSeparator(
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
NameDescription
ippIPP message

-
Returns

-
New attribute

-
-
ippAddString()

-
Description

-
Add a language-encoded string to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddString(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    ipp_tag_t type,
-    const char * name,
-    const char * charset,
-    const char * value);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
typeType of attribute
nameName of attribute
charsetCharacter set
valueValue

-
Returns

-
New attribute

-
-
ippAddStrings()

-
Description

-
Add language-encoded strings to an IPP message.
-
Syntax

-

-ipp_attribute_t *

-ippAddStrings(
-    ipp_t * ipp,
-    ipp_tag_t group,
-    ipp_tag_t type,
-    const char * name,
-    int num_values,
-    const char * charset,
-    const char *const * values);
-

-
Arguments

-

-
-
-
-
-
-
-
-
-
-
NameDescription
ippIPP message
groupIPP group
typeType of attribute
nameName of attribute
num_valuesNumber of values
charsetCharacter set
valuesValues

-
Returns

-
New attribute

-
-
ippDateToTime()

-
Description

-
Convert from RFC 1903 Date/Time format to UNIX time
-in seconds.
-
Syntax

-

-time_t

-ippDateToTime(
-    const ipp_uchar_t * date);
-

-
Arguments

-

-
-
-
-
NameDescription
dateRFC 1903 date info

-
Returns

-
UNIX time value

-
-
ippDelete()

-
Description

-
Delete an IPP message.
-
Syntax

-

-void

-ippDelete(
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
NameDescription
ippIPP message

-
Returns

-
Nothing.

-
-
 CUPS 1.1.19 ippDeleteAttribute()

-
Description

-
Delete a single attribute in an IPP message.
-
-
-
Syntax

-

-void

-ippDeleteAttribute(
-    ipp_t * ipp,
-    ipp_attribute_t * attr);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ippIPP message
attrAttribute to delete

-
Returns

-
Nothing.

-
-
ippErrorString()

-
Description

-
Return a name for the given status code.
-
Syntax

-

-const char *

-ippErrorString(
-    ipp_status_t error);
-

-
Arguments

-

-
-
-
-
NameDescription
errorError status

-
Returns

-
Text string

-
-
 CUPS 1.2 ippErrorValue()

-
Description

-
Return a status code for the given name.
-
-
-
Syntax

-

-ipp_status_t

-ippErrorValue(
-    const char * name);
-

-
Arguments

-

-
-
-
-
NameDescription
nameName

-
Returns

-
IPP status code

-
-
ippFindAttribute()

-
Description

-
Find a named attribute in a request...
-
Syntax

-

-ipp_attribute_t *

-ippFindAttribute(
-    ipp_t * ipp,
-    const char * name,
-    ipp_tag_t type);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ippIPP message
nameName of attribute
typeType of attribute

-
Returns

-
Matching attribute

-
-
ippFindNextAttribute()

-
Description

-
Find the next named attribute in a request...
-
Syntax

-

-ipp_attribute_t *

-ippFindNextAttribute(
-    ipp_t * ipp,
-    const char * name,
-    ipp_tag_t type);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ippIPP message
nameName of attribute
typeType of attribute

-
Returns

-
Matching attribute

-
-
ippLength()

-
Description

-
Compute the length of an IPP message.
-
Syntax

-

-size_t

-ippLength(
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
NameDescription
ippIPP message

-
Returns

-
Size of IPP message

-
-
ippNew()

-
Description

-
Allocate a new IPP message.
-
Syntax

-

-ipp_t *

-ippNew(void);
-

-
Arguments

-
None.

-
Returns

-
New IPP message

-
-
 CUPS 1.2 ippNewRequest()

-
Description

-
Allocate a new IPP request message.
-
The new request message is initialized with the attributes-charset and
+

+
 CUPS 1.2 httpWrite2

+
Write data to a HTTP connection.

+

+ssize_t httpWrite2 (

+    http_t *http,

+    const char *buffer,

+    size_t length

+);

+
Parameters

+

+
http

+
HTTP connection

+
buffer

+
Buffer for data

+
length

+
Number of bytes to write

+

+
Return Value

+
Number of bytes written

+
ippAddBoolean

+
Add a boolean attribute to an IPP message.

+

+ipp_attribute_t *ippAddBoolean (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    char value

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
value

+
Value of attribute

+

+
Return Value

+
New attribute

+
ippAddBooleans

+
Add an array of boolean values.

+

+ipp_attribute_t *ippAddBooleans (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    int num_values,

+    const char *values

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
num_values

+
Number of values

+
values

+
Values

+

+
Return Value

+
New attribute

+
 CUPS 1.1.19 ippAddCollection

+
Add a collection value.

+

+ipp_attribute_t *ippAddCollection (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    ipp_t *value

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
value

+
Value

+

+
Return Value

+
New attribute

+
 CUPS 1.1.19 ippAddCollections

+
Add an array of collection values.

+

+ipp_attribute_t *ippAddCollections (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    int num_values,

+    const ipp_t **values

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
num_values

+
Number of values

+
values

+
Values

+

+
Return Value

+
New attribute

+
ippAddDate

+
Add a date attribute to an IPP message.

+

+ipp_attribute_t *ippAddDate (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    const ipp_uchar_t *value

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
value

+
Value

+

+
Return Value

+
New attribute

+
ippAddInteger

+
Add a integer attribute to an IPP message.

+

+ipp_attribute_t *ippAddInteger (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    ipp_tag_t type,

+    const char *name,

+    int value

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
type

+
Type of attribute

+
name

+
Name of attribute

+
value

+
Value of attribute

+

+
Return Value

+
New attribute

+
ippAddIntegers

+
Add an array of integer values.

+

+ipp_attribute_t *ippAddIntegers (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    ipp_tag_t type,

+    const char *name,

+    int num_values,

+    const int *values

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
type

+
Type of attribute

+
name

+
Name of attribute

+
num_values

+
Number of values

+
values

+
Values

+

+
Return Value

+
New attribute

+
 CUPS 1.2 ippAddOctetString

+
Add an octetString value to an IPP message.

+

+ipp_attribute_t *ippAddOctetString (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    const void *data,

+    int datalen

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
data

+
octetString data

+
datalen

+
Length of data in bytes

+

+
Return Value

+
New attribute

+
ippAddRange

+
Add a range of values to an IPP message.

+

+ipp_attribute_t *ippAddRange (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    int lower,

+    int upper

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
lower

+
Lower value

+
upper

+
Upper value

+

+
Return Value

+
New attribute

+
ippAddRanges

+
Add ranges of values to an IPP message.

+

+ipp_attribute_t *ippAddRanges (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    int num_values,

+    const int *lower,

+    const int *upper

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
num_values

+
Number of values

+
lower

+
Lower values

+
upper

+
Upper values

+

+
Return Value

+
New attribute

+
ippAddResolution

+
Add a resolution value to an IPP message.

+

+ipp_attribute_t *ippAddResolution (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    ipp_res_t units,

+    int xres,

+    int yres

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
units

+
Units for resolution

+
xres

+
X resolution

+
yres

+
Y resolution

+

+
Return Value

+
New attribute

+
ippAddResolutions

+
Add resolution values to an IPP message.

+

+ipp_attribute_t *ippAddResolutions (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    const char *name,

+    int num_values,

+    ipp_res_t units,

+    const int *xres,

+    const int *yres

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
name

+
Name of attribute

+
num_values

+
Number of values

+
units

+
Units for resolution

+
xres

+
X resolutions

+
yres

+
Y resolutions

+

+
Return Value

+
New attribute

+
ippAddSeparator

+
Add a group separator to an IPP message.

+

+ipp_attribute_t *ippAddSeparator (

+    ipp_t *ipp

+);

+
Parameters

+

+
ipp

+
IPP message

+

+
Return Value

+
New attribute

+
ippAddString

+
Add a language-encoded string to an IPP message.

+

+ipp_attribute_t *ippAddString (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    ipp_tag_t type,

+    const char *name,

+    const char *charset,

+    const char *value

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
type

+
Type of attribute

+
name

+
Name of attribute

+
charset

+
Character set

+
value

+
Value

+

+
Return Value

+
New attribute

+
ippAddStrings

+
Add language-encoded strings to an IPP message.

+

+ipp_attribute_t *ippAddStrings (

+    ipp_t *ipp,

+    ipp_tag_t group,

+    ipp_tag_t type,

+    const char *name,

+    int num_values,

+    const char *charset,

+    const char *const *values

+);

+
Parameters

+

+
ipp

+
IPP message

+
group

+
IPP group

+
type

+
Type of attribute

+
name

+
Name of attribute

+
num_values

+
Number of values

+
charset

+
Character set

+
values

+
Values

+

+
Return Value

+
New attribute

+
ippDateToTime

+
Convert from RFC 1903 Date/Time format to UNIX time
+in seconds.

+

+time_t ippDateToTime (

+    const ipp_uchar_t *date

+);

+
Parameters

+

+
date

+
RFC 1903 date info

+

+
Return Value

+
UNIX time value

+
ippDelete

+
Delete an IPP message.

+

+void ippDelete (

+    ipp_t *ipp

+);

+
Parameters

+

+
ipp

+
IPP message

+

+
 CUPS 1.1.19 ippDeleteAttribute

+
Delete a single attribute in an IPP message.

+

+void ippDeleteAttribute (

+    ipp_t *ipp,

+    ipp_attribute_t *attr

+);

+
Parameters

+

+
ipp

+
IPP message

+
attr

+
Attribute to delete

+

+
ippErrorString

+
Return a name for the given status code.

+

+const char *ippErrorString (

+    ipp_status_t error

+);

+
Parameters

+

+
error

+
Error status

+

+
Return Value

+
Text string

+
 CUPS 1.2 ippErrorValue

+
Return a status code for the given name.

+

+ipp_status_t ippErrorValue (

+    const char *name

+);

+
Parameters

+

+
name

+
Name

+

+
Return Value

+
IPP status code

+
ippFindAttribute

+
Find a named attribute in a request...

+

+ipp_attribute_t *ippFindAttribute (

+    ipp_t *ipp,

+    const char *name,

+    ipp_tag_t type

+);

+
Parameters

+

+
ipp

+
IPP message

+
name

+
Name of attribute

+
type

+
Type of attribute

+

+
Return Value

+
Matching attribute

+
ippFindNextAttribute

+
Find the next named attribute in a request...

+

+ipp_attribute_t *ippFindNextAttribute (

+    ipp_t *ipp,

+    const char *name,

+    ipp_tag_t type

+);

+
Parameters

+

+
ipp

+
IPP message

+
name

+
Name of attribute

+
type

+
Type of attribute

+

+
Return Value

+
Matching attribute

+
ippLength

+
Compute the length of an IPP message.

+

+size_t ippLength (

+    ipp_t *ipp

+);

+
Parameters

+

+
ipp

+
IPP message

+

+
Return Value

+
Size of IPP message

+
ippNew

+
Allocate a new IPP message.

+

+ipp_t *ippNew (void);

+
Return Value

+
New IPP message

+
 CUPS 1.2 ippNewRequest

+
Allocate a new IPP request message.

+

+ipp_t *ippNewRequest (

+    ipp_op_t op

+);

+
Parameters

+

+
op

+
Operation code

+

+
Return Value

+
IPP request message

+
Discussion

+
The new request message is initialized with the attributes-charset and
 attributes-natural-language attributes added. The
 attributes-natural-language value is derived from the current locale.
 
-
-
Syntax

-

-ipp_t *

-ippNewRequest(
-    ipp_op_t op);
-

-
Arguments

-

-
-
-
-
NameDescription
opOperation code

-
Returns

-
IPP request message

-
-
 CUPS 1.2 ippOpString()

-
Description

-
Return a name for the given operation id.
-
-
-
Syntax

-

-const char *

-ippOpString(
-    ipp_op_t op);
-

-
Arguments

-

-
-
-
-
NameDescription
opOperation ID

-
Returns

-
Name

-
-
 CUPS 1.2 ippOpValue()

-
Description

-
Return an operation id for the given name.
-
-
-
Syntax

-

-ipp_op_t

-ippOpValue(
-    const char * name);
-

-
Arguments

-

-
-
-
-
NameDescription
nameTextual name

-
Returns

-
Operation ID

-
-
ippPort()

-
Description

-
Return the default IPP port number.
-
Syntax

-

-int

-ippPort(void);
-

-
Arguments

-
None.

-
Returns

-
Port number

-
-
ippRead()

-
Description

-
Read data for an IPP message from a HTTP connection.
-
Syntax

-

-ipp_state_t

-ippRead(
-    http_t * http,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
ippIPP data

-
Returns

-
Current state

-
-
 CUPS 1.1.19 ippReadFile()

-
Description

-
Read data for an IPP message from a file.
-
-
-
Syntax

-

-ipp_state_t

-ippReadFile(
-    int fd,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fdHTTP data
ippIPP data

-
Returns

-
Current state

-
-
 CUPS 1.2 ippReadIO()

-
Description

-
Read data for an IPP message.
-
-
-
Syntax

-

-ipp_state_t

-ippReadIO(
-    void * src,
-    ipp_iocb_t cb,
-    int blocking,
-    ipp_t * parent,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
srcData source
cbRead callback function
blockingUse blocking IO?
parentParent request, if any
ippIPP data

-
Returns

-
Current state

-
-
ippSetPort()

-
Description

-
Set the default port number.
-
Syntax

-

-void

-ippSetPort(
-    int p);
-

-
Arguments

-

-
-
-
-
NameDescription
pPort number to use

-
Returns

-
Nothing.

-
-
ippTimeToDate()

-
Description

-
Convert from UNIX time to RFC 1903 format.
-
Syntax

-

-const ipp_uchar_t *

-ippTimeToDate(
-    time_t t);
-

-
Arguments

-

-
-
-
-
NameDescription
tUNIX time value

-
Returns

-
RFC-1903 date/time data

-
-
ippWrite()

-
Description

-
Write data for an IPP message to a HTTP connection.
-
Syntax

-

-ipp_state_t

-ippWrite(
-    http_t * http,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
NameDescription
httpHTTP connection
ippIPP data

-
Returns

-
Current state

-
-
 CUPS 1.1.19 ippWriteFile()

-
Description

-
Write data for an IPP message to a file.
-
-
-
Syntax

-

-ipp_state_t

-ippWriteFile(
-    int fd,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fdHTTP data
ippIPP data

-
Returns

-
Current state

-
-
 CUPS 1.2 ippWriteIO()

-
Description

-
Write data for an IPP message.
-
-
-
Syntax

-

-ipp_state_t

-ippWriteIO(
-    void * dst,
-    ipp_iocb_t cb,
-    int blocking,
-    ipp_t * parent,
-    ipp_t * ipp);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
dstDestination
cbWrite callback function
blockingUse blocking IO?
parentParent IPP message
ippIPP data

-
Returns

-
Current state

-
-
Structures

-
-
-
 CUPS 1.2 http_addrlist_s

-
Description

-
Socket address list, which is
-used to enumerate all of the
-addresses that are associated
-with a hostname. 
-
Definition

-

-struct http_addrlist_s

-{

-  http_addr_t addr;

-  struct http_addrlist_s * next;

-};

-
Members

-

-
-
-
-
-
NameDescription
addr Address
-
next Pointer to next address in list
-

-
-
ipp_attribute_s

-
Description

-
Attribute
-
Definition

-

-struct ipp_attribute_s

-{

-  char * name;

-  struct ipp_attribute_s * next;

-  int num_values;

-  ipp_tag_t group_tag, value_tag;

-  ipp_value_t values[1];

-};

-
Members

-

-
-
-
-
-
-
-
-
NameDescription
name Name of attribute
-
next Next attribute in list
-
num_values Number of values
-
value_tag What type of value is it?
-
values[1] Values
-

-
-
ipp_s

-
Description

-
IPP Request/Response/Notification
-
Definition

-

-struct ipp_s

-{

-  ipp_attribute_t * attrs;

-  ipp_attribute_t * current;

-  ipp_tag_t curtag;

-  ipp_attribute_t * last;

-  ipp_attribute_t * prev;

-  ipp_request_t request;

-  ipp_state_t state;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
NameDescription
attrs Attributes
-
current Current attribute (for read/write)
-
curtag Current attribute group tag
-
last Last attribute in list
-
prev Previous attribute (for read)
-
request Request header
-
state State of request
-

-
-
Types

-
-
-
 CUPS 1.2 http_addrlist_t

-
Description

-
Socket address list, which is
+

+
 CUPS 1.2 ippOpString

+
Return a name for the given operation id.

+

+const char *ippOpString (

+    ipp_op_t op

+);

+
Parameters

+

+
op

+
Operation ID

+

+
Return Value

+
Name

+
 CUPS 1.2 ippOpValue

+
Return an operation id for the given name.

+

+ipp_op_t ippOpValue (

+    const char *name

+);

+
Parameters

+

+
name

+
Textual name

+

+
Return Value

+
Operation ID

+
ippPort

+
Return the default IPP port number.

+

+int ippPort (void);

+
Return Value

+
Port number

+
ippRead

+
Read data for an IPP message from a HTTP connection.

+

+ipp_state_t ippRead (

+    http_t *http,

+    ipp_t *ipp

+);

+
Parameters

+

+
http

+
HTTP connection

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
 CUPS 1.1.19 ippReadFile

+
Read data for an IPP message from a file.

+

+ipp_state_t ippReadFile (

+    int fd,

+    ipp_t *ipp

+);

+
Parameters

+

+
fd

+
HTTP data

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
 CUPS 1.2 ippReadIO

+
Read data for an IPP message.

+

+ipp_state_t ippReadIO (

+    void *src,

+    ipp_iocb_t cb,

+    int blocking,

+    ipp_t *parent,

+    ipp_t *ipp

+);

+
Parameters

+

+
src

+
Data source

+
cb

+
Read callback function

+
blocking

+
Use blocking IO?

+
parent

+
Parent request, if any

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
ippSetPort

+
Set the default port number.

+

+void ippSetPort (

+    int p

+);

+
Parameters

+

+
p

+
Port number to use

+

+
ippTimeToDate

+
Convert from UNIX time to RFC 1903 format.

+

+const ipp_uchar_t *ippTimeToDate (

+    time_t t

+);

+
Parameters

+

+
t

+
UNIX time value

+

+
Return Value

+
RFC-1903 date/time data

+
ippWrite

+
Write data for an IPP message to a HTTP connection.

+

+ipp_state_t ippWrite (

+    http_t *http,

+    ipp_t *ipp

+);

+
Parameters

+

+
http

+
HTTP connection

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
 CUPS 1.1.19 ippWriteFile

+
Write data for an IPP message to a file.

+

+ipp_state_t ippWriteFile (

+    int fd,

+    ipp_t *ipp

+);

+
Parameters

+

+
fd

+
HTTP data

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
 CUPS 1.2 ippWriteIO

+
Write data for an IPP message.

+

+ipp_state_t ippWriteIO (

+    void *dst,

+    ipp_iocb_t cb,

+    int blocking,

+    ipp_t *parent,

+    ipp_t *ipp

+);

+
Parameters

+

+
dst

+
Destination

+
cb

+
Write callback function

+
blocking

+
Use blocking IO?

+
parent

+
Parent IPP message

+
ipp

+
IPP data

+

+
Return Value

+
Current state

+
Data Types

+
 CUPS 1.2 http_addrlist_t

+
Socket address list, which is
 used to enumerate all of the
 addresses that are associated
-with a hostname. 
-
Definition

-

-typedef struct http_addrlist_s / http_addrlist_t;
-

-
-
http_auth_t

-
Description

-
HTTP authentication types
-
Definition

-

-typedef enum http_auth_e http_auth_t;
-

-
-
http_encoding_t

-
Description

-
HTTP transfer encoding values
-
Definition

-

-typedef enum http_encoding_e http_encoding_t;
-

-
-
http_encryption_t

-
Description

-
HTTP encryption values
-
Definition

-

-typedef enum http_encryption_e http_encryption_t;
-

-
-
http_t

-
Description

-
HTTP connection type
-
Definition

-

+with a hostname. 

+

+typedef struct http_addrlist_s / http_addrlist_t;
+

+
http_auth_t

+
HTTP authentication types

+

+typedef enum http_auth_e http_auth_t;
+

+
http_encoding_t

+
HTTP transfer encoding values

+

+typedef enum http_encoding_e http_encoding_t;
+

+
http_encryption_t

+
HTTP encryption values

+

+typedef enum http_encryption_e http_encryption_t;
+

+
http_t

+
HTTP connection type

+

 typedef struct _http_s http_t;
-

-
-
ipp_attribute_t

-
Description

-
Attribute
-
Definition

-

-typedef struct ipp_attribute_s ipp_attribute_t;
-

-
-
 CUPS 1.2 ipp_iocb_t

-
Description

-
IPP IO Callback Function 
-
Definition

-

-typedef ssize_t (*ipp_iocb_t)(void *, ipp_uchar_t *, size_t);
-

-
-
ipp_request_t

-
Description

-
Request Header
-
Definition

-

-typedef union ipp_request_u ipp_request_t;
-

-
-
ipp_t

-
Description

-
Attribute Value
-
Definition

-

-typedef struct ipp_s ipp_t;
-

-
-
ipp_uchar_t

-
Description

-
IPP status codes...
-
Definition

-

+

+
ipp_attribute_t

+
Attribute

+

+typedef struct ipp_attribute_s ipp_attribute_t;
+

+
 CUPS 1.2 ipp_iocb_t

+
IPP IO Callback Function 

+

+typedef ssize_t (*ipp_iocb_t)(void *, ipp_uchar_t *, size_t);
+

+
ipp_request_t

+
Request Header

+

+typedef union ipp_request_u ipp_request_t;
+

+
ipp_t

+
Attribute Value

+

+typedef struct ipp_s ipp_t;
+

+
ipp_uchar_t

+
IPP status codes...

+

 typedef typedef unsigned char ipp_uchar_t;
-

-
-
ipp_value_t

-
Description

-
New in CUPS 1.1.19
-
Definition

-

-typedef union ipp_value_u ipp_value_t;
-

-
-
Unions

-
-
-
ipp_request_u

-
Description

-
Request Header
-
Definition

-

-union ipp_request_u

-{

-};

-
Members

-

-
-
-
NameDescription

-
-
ipp_value_u

-
Description

-
New in CUPS 1.1.19
-
Definition

-

-union ipp_value_u

-{

-  char boolean;

-  ipp_t * collection;

-  ipp_uchar_t date[11];

-  int integer;

-};

-
Members

-

-
-
-
-
-
-
-
NameDescription
boolean Boolean value
-
collection Collection value
-
date[11] Date/time value
-
integer Integer/enumerated value
-

+

+
ipp_value_t

+
New in CUPS 1.1.19

+

+typedef union ipp_value_u ipp_value_t;
+

+
Structures

+
 CUPS 1.2 http_addrlist_s

+
Socket address list, which is
+used to enumerate all of the
+addresses that are associated
+with a hostname. 

+
struct http_addrlist_s {

+    http_addr_t addr;

+    struct http_addrlist_s *next;

+};

+
Members

+

+
addr 

+
Address

+
next 

+
Pointer to next address in list

+

+
ipp_attribute_s

+
Attribute

+
struct ipp_attribute_s {

+    char *name;

+    struct ipp_attribute_s *next;

+    int num_values;

+    ipp_tag_t group_tag, value_tag;

+    ipp_value_t values[1];

+};

+
Members

+

+
name 

+
Name of attribute

+
next 

+
Next attribute in list

+
num_values 

+
Number of values

+
value_tag 

+
What type of value is it?

+
values[1] 

+
Values

+

+
ipp_s

+
IPP Request/Response/Notification

+
struct ipp_s {

+    ipp_attribute_t *attrs;

+    ipp_attribute_t *current;

+    ipp_tag_t curtag;

+    ipp_attribute_t *last;

+    ipp_attribute_t *prev;

+    ipp_request_t request;

+    ipp_state_t state;

+};

+
Members

+

+
attrs 

+
Attributes

+
current 

+
Current attribute (for read/write)

+
curtag 

+
Current attribute group tag

+
last 

+
Last attribute in list

+
prev 

+
Previous attribute (for read)

+
request 

+
Request header

+
state 

+
State of request

+

+
Unions

+
ipp_request_u

+
Request Header

+
union ipp_request_u {

+};

+
Members

+

+

+
ipp_value_u

+
New in CUPS 1.1.19

+
union ipp_value_u {

+    char boolean;

+    ipp_t *collection;

+    ipp_uchar_t date[11];

+    int integer;

+};

+
Members

+

+
boolean 

+
Boolean value

+
collection 

+
Collection value

+
date[11] 

+
Date/time value

+
integer 

+
Integer/enumerated value

+

+
Constants

+
http_auth_e

+
HTTP authentication types

+
Constants

+

+
HTTP_AUTH_BASIC 

+
Basic authentication in use

+
HTTP_AUTH_MD5 

+
Digest authentication in use

+
HTTP_AUTH_MD5_INT 

+
Digest authentication in use for body

+
HTTP_AUTH_MD5_SESS 

+
MD5-session authentication in use

+
HTTP_AUTH_MD5_SESS_INT 

+
MD5-session authentication in use for body

+
HTTP_AUTH_NEGOTIATE  CUPS 1.3 

+
GSSAPI authentication in use 

+
HTTP_AUTH_NONE 

+
No authentication in use

+

+
http_encoding_e

+
HTTP transfer encoding values

+
Constants

+

+
HTTP_ENCODE_CHUNKED 

+
Data is chunked

+
HTTP_ENCODE_FIELDS 

+
Sending HTTP fields

+
HTTP_ENCODE_LENGTH 

+
Data is sent with Content-Length

+

+
http_encryption_e

+
HTTP encryption values

+
Constants

+

+
HTTP_ENCRYPT_ALWAYS 

+
Always encrypt (SSL)

+
HTTP_ENCRYPT_IF_REQUESTED 

+
Encrypt if requested (TLS upgrade)

+
HTTP_ENCRYPT_NEVER 

+
Never encrypt

+
HTTP_ENCRYPT_REQUIRED 

+
Encryption is required (TLS upgrade)

+

+
http_field_e

+
HTTP field names

+
Constants

+

+
HTTP_FIELD_ACCEPT_LANGUAGE 

+
Accept-Language field

+
HTTP_FIELD_ACCEPT_RANGES 

+
Accept-Ranges field

+
HTTP_FIELD_AUTHORIZATION 

+
Authorization field

+
HTTP_FIELD_CONNECTION 

+
Connection field

+
HTTP_FIELD_CONTENT_ENCODING 

+
Content-Encoding field

+
HTTP_FIELD_CONTENT_LANGUAGE 

+
Content-Language field

+
HTTP_FIELD_CONTENT_LENGTH 

+
Content-Length field

+
HTTP_FIELD_CONTENT_LOCATION 

+
Content-Location field

+
HTTP_FIELD_CONTENT_MD5 

+
Content-MD5 field

+
HTTP_FIELD_CONTENT_RANGE 

+
Content-Range field

+
HTTP_FIELD_CONTENT_TYPE 

+
Content-Type field

+
HTTP_FIELD_CONTENT_VERSION 

+
Content-Version field

+
HTTP_FIELD_DATE 

+
Date field

+
HTTP_FIELD_HOST 

+
Host field

+
HTTP_FIELD_IF_MODIFIED_SINCE 

+
If-Modified-Since field

+
HTTP_FIELD_IF_UNMODIFIED_SINCE 

+
If-Unmodified-Since field

+
HTTP_FIELD_KEEP_ALIVE 

+
Keep-Alive field

+
HTTP_FIELD_LAST_MODIFIED 

+
Last-Modified field

+
HTTP_FIELD_LINK 

+
Link field

+
HTTP_FIELD_LOCATION 

+
Location field

+
HTTP_FIELD_MAX 

+
Maximum field index

+
HTTP_FIELD_RANGE 

+
Range field

+
HTTP_FIELD_REFERER 

+
Referer field

+
HTTP_FIELD_RETRY_AFTER 

+
Retry-After field

+
HTTP_FIELD_TRANSFER_ENCODING 

+
Transfer-Encoding field

+
HTTP_FIELD_UNKNOWN 

+
Unknown field

+
HTTP_FIELD_UPGRADE 

+
Upgrade field

+
HTTP_FIELD_USER_AGENT 

+
User-Agent field

+
HTTP_FIELD_WWW_AUTHENTICATE 

+
WWW-Authenticate field

+

+
http_keepalive_e

+
Types and structures...

+
Constants

+

+
HTTP_KEEPALIVE_OFF 

+
No keep alive support

+
HTTP_KEEPALIVE_ON 

+
Use keep alive

+

+
http_state_e

+

+
Constants

+

+
HTTP_CLOSE 

+
CLOSE command, waiting for blank line

+
HTTP_DELETE 

+
DELETE command, waiting for blank line

+
HTTP_GET 

+
GET command, waiting for blank line

+
HTTP_GET_SEND 

+
GET command, sending data

+
HTTP_HEAD 

+
HEAD command, waiting for blank line

+
HTTP_OPTIONS 

+
OPTIONS command, waiting for blank line

+
HTTP_POST 

+
POST command, waiting for blank line

+
HTTP_POST_RECV 

+
POST command, receiving data

+
HTTP_POST_SEND 

+
POST command, sending data

+
HTTP_PUT 

+
PUT command, waiting for blank line

+
HTTP_PUT_RECV 

+
PUT command, receiving data

+
HTTP_STATUS 

+
Command complete, sending status

+
HTTP_TRACE 

+
TRACE command, waiting for blank line

+
HTTP_WAITING 

+
Waiting for command

+

+
http_status_e

+
HTTP status codes

+
Constants

+

+
HTTP_ACCEPTED 

+
DELETE command was successful

+
HTTP_BAD_GATEWAY 

+
Bad gateway

+
HTTP_BAD_REQUEST 

+
Bad request

+
HTTP_CONFLICT 

+
Request is self-conflicting

+
HTTP_CONTINUE 

+
Everything OK, keep going...

+
HTTP_CREATED 

+
PUT command was successful

+
HTTP_ERROR 

+
An error response from httpXxxx()

+
HTTP_EXPECTATION_FAILED 

+
The expectation given in an Expect header field was not met

+
HTTP_FORBIDDEN 

+
Forbidden to access this URI

+
HTTP_GATEWAY_TIMEOUT 

+
Gateway connection timed out

+
HTTP_GONE 

+
Server has gone away

+
HTTP_LENGTH_REQUIRED 

+
A content length or encoding is required

+
HTTP_METHOD_NOT_ALLOWED 

+
Method is not allowed

+
HTTP_MOVED_PERMANENTLY 

+
Document has moved permanently

+
HTTP_MOVED_TEMPORARILY 

+
Document has moved temporarily

+
HTTP_MULTIPLE_CHOICES 

+
Multiple files match request

+
HTTP_NOT_ACCEPTABLE 

+
Not Acceptable

+
HTTP_NOT_AUTHORITATIVE 

+
Information isn't authoritative

+
HTTP_NOT_FOUND 

+
URI was not found

+
HTTP_NOT_IMPLEMENTED 

+
Feature not implemented

+
HTTP_NOT_MODIFIED 

+
File not modified

+
HTTP_NOT_SUPPORTED 

+
HTTP version not supported

+
HTTP_NO_CONTENT 

+
Successful command, no new data

+
HTTP_OK 

+
OPTIONS/GET/HEAD/POST/TRACE command was successful

+
HTTP_PARTIAL_CONTENT 

+
Only a partial file was recieved/sent

+
HTTP_PAYMENT_REQUIRED 

+
Payment required

+
HTTP_PRECONDITION 

+
Precondition failed

+
HTTP_PROXY_AUTHENTICATION 

+
Proxy Authentication is Required

+
HTTP_REQUESTED_RANGE 

+
The requested range is not satisfiable

+
HTTP_REQUEST_TIMEOUT 

+
Request timed out

+
HTTP_REQUEST_TOO_LARGE 

+
Request entity too large

+
HTTP_RESET_CONTENT 

+
Content was reset/recreated

+
HTTP_SEE_OTHER 

+
See this other link...

+
HTTP_SERVER_ERROR 

+
Internal server error

+
HTTP_SERVICE_UNAVAILABLE 

+
Service is unavailable

+
HTTP_SWITCHING_PROTOCOLS 

+
HTTP upgrade to TLS/SSL

+
HTTP_UNAUTHORIZED 

+
Unauthorized to access host

+
HTTP_UNSUPPORTED_MEDIATYPE 

+
The requested media type is unsupported

+
HTTP_UPGRADE_REQUIRED 

+
Upgrade to SSL/TLS required

+
HTTP_URI_TOO_LONG 

+
URI too long

+
HTTP_USE_PROXY 

+
Must use a proxy to access this URI

+

+
http_uri_coding_e

+

+
Constants

+

+
HTTP_URI_CODING_ALL 

+
En/decode everything

+
HTTP_URI_CODING_HOSTNAME 

+
En/decode the hostname portion

+
HTTP_URI_CODING_MOST 

+
En/decode all but the query

+
HTTP_URI_CODING_NONE 

+
Don't en/decode anything

+
HTTP_URI_CODING_QUERY 

+
En/decode the query portion

+
HTTP_URI_CODING_RESOURCE 

+
En/decode the resource portion

+
HTTP_URI_CODING_USERNAME 

+
En/decode the username portion

+

+
http_uri_status_e

+

+
Constants

+

+
HTTP_URI_BAD_ARGUMENTS 

+
Bad arguments to function (error)

+
HTTP_URI_BAD_HOSTNAME 

+
Bad hostname in URI (error)

+
HTTP_URI_BAD_PORT 

+
Bad port number in URI (error)

+
HTTP_URI_BAD_RESOURCE 

+
Bad resource in URI (error)

+
HTTP_URI_BAD_SCHEME 

+
Bad scheme in URI (error)

+
HTTP_URI_BAD_URI 

+
Bad/empty URI (error)

+
HTTP_URI_BAD_USERNAME 

+
Bad username in URI (error)

+
HTTP_URI_MISSING_RESOURCE 

+
Missing resource in URI (warning)

+
HTTP_URI_MISSING_SCHEME 

+
Missing scheme in URI (warning)

+
HTTP_URI_OK 

+
URI decoded OK

+
HTTP_URI_OVERFLOW 

+
URI buffer for httpAssembleURI is too small

+
HTTP_URI_UNKNOWN_SCHEME 

+
Unknown scheme in URI (warning)

+

+
http_version_e

+

+
Constants

+

+
HTTP_0_9 

+
HTTP/0.9

+
HTTP_1_0 

+
HTTP/1.0

+
HTTP_1_1 

+
HTTP/1.1

+

+
ipp_finish_e

+

+
Constants

+

+
IPP_FINISHINGS_BALE 

+
Bale (any type)

+
IPP_FINISHINGS_BIND 

+
Bind

+
IPP_FINISHINGS_BIND_BOTTOM 

+
Bind on bottom

+
IPP_FINISHINGS_BIND_LEFT 

+
Bind on left

+
IPP_FINISHINGS_BIND_RIGHT 

+
Bind on right

+
IPP_FINISHINGS_BIND_TOP 

+
Bind on top

+
IPP_FINISHINGS_BOOKLET_MAKER 

+
Fold to make booklet

+
IPP_FINISHINGS_COVER 

+
Add cover

+
IPP_FINISHINGS_EDGE_STITCH 

+
Stitch along any side

+
IPP_FINISHINGS_EDGE_STITCH_BOTTOM 

+
Stitch along bottom edge

+
IPP_FINISHINGS_EDGE_STITCH_LEFT 

+
Stitch along left side

+
IPP_FINISHINGS_EDGE_STITCH_RIGHT 

+
Stitch along right side

+
IPP_FINISHINGS_EDGE_STITCH_TOP 

+
Stitch along top edge

+
IPP_FINISHINGS_FOLD 

+
Fold (any type)

+
IPP_FINISHINGS_JOB_OFFSET 

+
Offset for binding (any type)

+
IPP_FINISHINGS_NONE 

+
No finishing

+
IPP_FINISHINGS_PUNCH 

+
Punch (any location/count)

+
IPP_FINISHINGS_SADDLE_STITCH 

+
Staple interior

+
IPP_FINISHINGS_STAPLE 

+
Staple (any location)

+
IPP_FINISHINGS_STAPLE_BOTTOM_LEFT 

+
Staple bottom left corner

+
IPP_FINISHINGS_STAPLE_BOTTOM_RIGHT 

+
Staple bottom right corner

+
IPP_FINISHINGS_STAPLE_DUAL_BOTTOM 

+
Two staples on bottom

+
IPP_FINISHINGS_STAPLE_DUAL_LEFT 

+
Two staples on left

+
IPP_FINISHINGS_STAPLE_DUAL_RIGHT 

+
Two staples on right

+
IPP_FINISHINGS_STAPLE_DUAL_TOP 

+
Two staples on top

+
IPP_FINISHINGS_STAPLE_TOP_LEFT 

+
Staple top left corner

+
IPP_FINISHINGS_STAPLE_TOP_RIGHT 

+
Staple top right corner

+
IPP_FINISHINGS_TRIM 

+
Trim (any type)

+

+
ipp_jstate_e

+

+
Constants

+

+
IPP_JOB_ABORTED 

+
Job has aborted due to error

+
IPP_JOB_CANCELED 

+
Job has been canceled

+
IPP_JOB_COMPLETED 

+
Job has completed successfully

+
IPP_JOB_HELD 

+
Job is held for printing

+
IPP_JOB_PENDING 

+
Job is waiting to be printed

+
IPP_JOB_PROCESSING 

+
Job is currently printing

+
IPP_JOB_STOPPED 

+
Job has been stopped

+

+
ipp_op_e

+

+
Constants

+

+
CUPS_ACCEPT_JOBS 

+
Accept new jobs on a printer

+
CUPS_ADD_MODIFY_CLASS 

+
Add or modify a class

+
CUPS_ADD_MODIFY_PRINTER 

+
Add or modify a printer

+
CUPS_AUTHENTICATE_JOB  CUPS 1.2 

+
Authenticate a job 

+
CUPS_DELETE_CLASS 

+
Delete a class

+
CUPS_DELETE_PRINTER 

+
Delete a printer

+
CUPS_GET_CLASSES  DEPRECATED 

+
Get a list of classes 

+
CUPS_GET_DEFAULT 

+
Get the default printer

+
CUPS_GET_DEVICES 

+
Get a list of supported devices

+
CUPS_GET_DOCUMENT  CUPS 1.4 

+
Get a document file 

+
CUPS_GET_PPD  CUPS 1.3 

+
Get a PPD file 

+
CUPS_GET_PPDS 

+
Get a list of supported drivers

+
CUPS_GET_PRINTERS 

+
Get a list of printers and/or classes

+
CUPS_MOVE_JOB 

+
Move a job to a different printer

+
CUPS_REJECT_JOBS 

+
Reject new jobs on a printer

+
CUPS_SET_DEFAULT 

+
Set the default printer

+
IPP_CANCEL_JOB 

+
Cancel a job

+
IPP_CANCEL_SUBSCRIPTION  CUPS 1.2 

+
Cancel a subscription 

+
IPP_CREATE_JOB 

+
Create an empty print job

+
IPP_CREATE_JOB_SUBSCRIPTION  CUPS 1.2 

+
Create a job subscription 

+
IPP_CREATE_PRINTER_SUBSCRIPTION  CUPS 1.2 

+
Create a printer subscription 

+
IPP_DISABLE_PRINTER 

+
Stop a printer

+
IPP_ENABLE_PRINTER 

+
Start a printer

+
IPP_GET_JOBS 

+
Get a list of jobs

+
IPP_GET_JOB_ATTRIBUTES 

+
Get job attributes

+
IPP_GET_NOTIFICATIONS  CUPS 1.2 

+
Get notification events 

+
IPP_GET_PRINTER_ATTRIBUTES 

+
Get printer attributes

+
IPP_GET_PRINTER_SUPPORTED_VALUES 

+
Get supported attribute values

+
IPP_GET_SUBSCRIPTIONS  CUPS 1.2 

+
Get list of subscriptions 

+
IPP_GET_SUBSCRIPTION_ATTRIBUTES  CUPS 1.2 

+
Get subscription attributes 

+
IPP_HOLD_JOB 

+
Hold a job for printing

+
IPP_PAUSE_PRINTER 

+
Stop a printer

+
IPP_PRINT_JOB 

+
Print a single file

+
IPP_PURGE_JOBS 

+
Cancel all jobs

+
IPP_RELEASE_JOB 

+
Release a job for printing

+
IPP_RENEW_SUBSCRIPTION  CUPS 1.2 

+
Renew a printer subscription 

+
IPP_RESTART_JOB 

+
Reprint a job

+
IPP_RESUME_PRINTER 

+
Start a printer

+
IPP_SEND_DOCUMENT 

+
Add a file to a job

+
IPP_SET_JOB_ATTRIBUTES 

+
Set job attributes

+
IPP_VALIDATE_JOB 

+
Validate job options

+

+
ipp_orient_e

+

+
Constants

+

+
IPP_LANDSCAPE 

+
90 degrees counter-clockwise

+
IPP_PORTRAIT 

+
No rotation

+
IPP_REVERSE_LANDSCAPE 

+
90 degrees clockwise

+
IPP_REVERSE_PORTRAIT 

+
180 degrees

+

+
ipp_pstate_e

+

+
Constants

+

+
IPP_PRINTER_IDLE 

+
Printer is idle

+
IPP_PRINTER_PROCESSING 

+
Printer is working

+
IPP_PRINTER_STOPPED 

+
Printer is stopped

+

+
ipp_quality_e

+

+
Constants

+

+
IPP_QUALITY_DRAFT 

+
Draft quality

+
IPP_QUALITY_HIGH 

+
High quality

+
IPP_QUALITY_NORMAL 

+
Normal quality

+

+
ipp_res_e

+
Types and structures...

+
Constants

+

+
IPP_RES_PER_CM 

+
Pixels per centimeter

+
IPP_RES_PER_INCH 

+
Pixels per inch

+

+
ipp_state_e

+

+
Constants

+

+
IPP_ATTRIBUTE 

+
One or more attributes need to be sent/received

+
IPP_DATA 

+
IPP request data needs to be sent/received

+
IPP_ERROR 

+
An error occurred

+
IPP_HEADER 

+
The request header needs to be sent/received

+
IPP_IDLE 

+
Nothing is happening/request completed

+

+
ipp_status_e

+
IPP status codes...

+
Constants

+

+
CUPS_SEE_OTHER 

+
cups-see-other

+
IPP_ATTRIBUTES 

+
client-error-attributes-or-values-not-supported

+
IPP_ATTRIBUTES_NOT_SETTABLE 

+
client-error-attributes-not-settable

+
IPP_BAD_REQUEST 

+
client-error-bad-request

+
IPP_CHARSET 

+
client-error-charset-not-supported

+
IPP_COMPRESSION_ERROR 

+
client-error-compression-error

+
IPP_COMPRESSION_NOT_SUPPORTED 

+
client-error-compression-not-supported

+
IPP_CONFLICT 

+
client-error-conflicting-attributes

+
IPP_DEVICE_ERROR 

+
server-error-device-error

+
IPP_DOCUMENT_ACCESS_ERROR 

+
client-error-document-access-error

+
IPP_DOCUMENT_FORMAT 

+
client-error-document-format-not-supported

+
IPP_DOCUMENT_FORMAT_ERROR 

+
client-error-document-format-error

+
IPP_ERROR_JOB_CANCELED 

+
server-error-job-canceled

+
IPP_FORBIDDEN 

+
client-error-forbidden

+
IPP_GONE 

+
client-error-gone

+
IPP_IGNORED_ALL_NOTIFICATIONS 

+
client-error-ignored-all-notifications

+
IPP_IGNORED_ALL_SUBSCRIPTIONS 

+
client-error-ignored-all-subscriptions

+
IPP_INTERNAL_ERROR 

+
server-error-internal-error

+
IPP_MULTIPLE_JOBS_NOT_SUPPORTED 

+
server-error-multiple-document-jobs-not-supported

+
IPP_NOT_ACCEPTING 

+
server-error-not-accepting-jobs

+
IPP_NOT_AUTHENTICATED 

+
client-error-not-authenticated

+
IPP_NOT_AUTHORIZED 

+
client-error-not-authorized

+
IPP_NOT_FOUND 

+
client-error-not-found

+
IPP_NOT_POSSIBLE 

+
client-error-not-possible

+
IPP_OK 

+
successful-ok

+
IPP_OK_BUT_CANCEL_SUBSCRIPTION 

+
successful-ok-but-cancel-subscription

+
IPP_OK_CONFLICT 

+
successful-ok-conflicting-attributes

+
IPP_OK_EVENTS_COMPLETE 

+
successful-ok-events-complete

+
IPP_OK_IGNORED_NOTIFICATIONS 

+
successful-ok-ignored-notifications

+
IPP_OK_IGNORED_SUBSCRIPTIONS 

+
successful-ok-ignored-subscriptions

+
IPP_OK_SUBST 

+
successful-ok-ignored-or-substituted-attributes

+
IPP_OK_TOO_MANY_EVENTS 

+
successful-ok-too-many-events

+
IPP_OPERATION_NOT_SUPPORTED 

+
server-error-operation-not-supported

+
IPP_PRINTER_BUSY 

+
server-error-busy

+
IPP_PRINTER_IS_DEACTIVATED 

+
server-error-printer-is-deactivated

+
IPP_PRINT_SUPPORT_FILE_NOT_FOUND 

+
client-error-print-support-file-not-found

+
IPP_REQUEST_ENTITY 

+
client-error-request-entity-too-large

+
IPP_REQUEST_VALUE 

+
client-error-request-value-too-long

+
IPP_SERVICE_UNAVAILABLE 

+
server-error-service-unavailable

+
IPP_TEMPORARY_ERROR 

+
server-error-temporary-error

+
IPP_TIMEOUT 

+
client-error-timeout

+
IPP_TOO_MANY_SUBSCRIPTIONS 

+
client-error-too-many-subscriptions

+
IPP_URI_SCHEME 

+
client-error-uri-scheme-not-supported

+
IPP_VERSION_NOT_SUPPORTED 

+
server-error-version-not-supported

+

+
ipp_tag_e

+
Format tags for attributes...

+
Constants

+

+
IPP_TAG_ADMINDEFINE 

+
Admin-defined value

+
IPP_TAG_BEGIN_COLLECTION 

+
Beginning of collection value

+
IPP_TAG_BOOLEAN 

+
Boolean value

+
IPP_TAG_CHARSET 

+
Character set value

+
IPP_TAG_COPY 

+
Bitflag for copied attribute values

+
IPP_TAG_DATE 

+
Date/time value

+
IPP_TAG_DEFAULT 

+
Default value

+
IPP_TAG_DELETEATTR 

+
Delete-attribute value

+
IPP_TAG_END 

+
End-of-attributes

+
IPP_TAG_END_COLLECTION 

+
End of collection value

+
IPP_TAG_ENUM 

+
Enumeration value

+
IPP_TAG_EVENT_NOTIFICATION 

+
Event group

+
IPP_TAG_INTEGER 

+
Integer value

+
IPP_TAG_JOB 

+
Job group

+
IPP_TAG_KEYWORD 

+
Keyword value

+
IPP_TAG_LANGUAGE 

+
Language value

+
IPP_TAG_MASK 

+
Mask for copied attribute values

+
IPP_TAG_MEMBERNAME 

+
Collection member name value

+
IPP_TAG_MIMETYPE 

+
MIME media type value

+
IPP_TAG_NAME 

+
Name value

+
IPP_TAG_NAMELANG 

+
Name-with-language value

+
IPP_TAG_NOTSETTABLE 

+
Not-settable value

+
IPP_TAG_NOVALUE 

+
No-value value

+
IPP_TAG_OPERATION 

+
Operation group

+
IPP_TAG_PRINTER 

+
Printer group

+
IPP_TAG_RANGE 

+
Range value

+
IPP_TAG_RESOLUTION 

+
Resolution value

+
IPP_TAG_STRING 

+
Octet string value

+
IPP_TAG_SUBSCRIPTION 

+
Subscription group

+
IPP_TAG_TEXT 

+
Text value

+
IPP_TAG_TEXTLANG 

+
Text-with-language value

+
IPP_TAG_UNKNOWN 

+
Unknown value

+
IPP_TAG_UNSUPPORTED_GROUP 

+
Unsupported attributes group

+
IPP_TAG_UNSUPPORTED_VALUE 

+
Unsupported value

+
IPP_TAG_URI 

+
URI value

+
IPP_TAG_URISCHEME 

+
URI scheme value

+
IPP_TAG_ZERO 

+
Zero tag - used for separators

+

+

 
 
diff --git a/doc/help/api-overview.html b/doc/help/api-overview.html
new file mode 100644
index 000000000..151f3c90b
--- /dev/null
+++ b/doc/help/api-overview.html
@@ -0,0 +1,408 @@
+
+
+
+
+Introduction to CUPS Programming
+
+
+
+
+
+

+
+
+
Introduction to CUPS Programming

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headerscups/cups.h

+	cups/array.h

+	cups/backend.h

+	cups/dir.h

+	cups/file.h

+	cups/ppd.h

+	cups/raster.h

+	cups/sidechannel.h
Libraries-lcups

+	-lcupsimage
See AlsoProgramming: CUPS API

+	Programming: Array API

+	Programming: File and Directory APIs

+	Programming: Filter and Backend Programming

+	Programming: HTTP and IPP APIs

+	Programming: PPD API

+	Programming: Raster API

+
Contents

+
+
+
+
Overview

+
+
CUPS provides two libraries that interface with the different parts of the
+printing system. The "cups" library provides all of the common application and
+filter functions while the "cupsimage" library provides all of the imaging
+functions used in raster printer drivers. The "cups" library functions are
+accessed by including the <cups/cups.h> header, while
+"cupsimage" functions are found in the <cups/raster.h>
+header.

+
+
Compiling Programs

+
+
The CUPS libraries can be used from any C, C++, or Objective C program.
+The method of compiling against the libraries varies depending on the
+operating system and installation of CUPS. The following sections show how
+to compile a simple program (shown below) in two common environments.

+
+
The following simple program lists the available printers on the system:

+
+
+#include <stdio.h>
+#include <cups/cups.h>
+
+int main(void)
+{
+  int i;
+  cups_dest_t *dests, *dest;
+  int num_dests = cupsGetDests(&dests);
+
+  for (i = num_dests, dest = dests; i > 0; i --, dest ++)
+  {
+    if (dest->instance)
+      printf("%s/%s\n", dest->name, dest->instance);
+    else
+      puts(dest->name);
+  }
+
+  return (0);
+}
+

+
+
Compiling with Xcode

+
+
In Xcode, choose New Project... from the File menu,
+then select the Standard Tool project type under Command Line
+Utility. Click Next and choose a project directory. Click
+Next to create the project.

+
+
In the project window, double-click on the Targets group and
+control-click on the simple target to show the context menu. Choose
+Existing Framework... from the Add submenu. When the file
+chooser sheet appears, press the / key and enter "/usr/lib". Scroll
+down the file list and select the libcups.dylib file. Click the
+Add button in the file chooser and attributes sheets.

+
+
In the project window, double-click on the main.c source file.
+Replace the template source code with the listing above and save it. Click the
+Build and Go button to build the sample program and run it.

+
+
Compiling with GCC

+
+
From the command-line, create a file called sample.c using your
+favorite editor and then run the following command to compile it with GCC and
+run it:

+
+
+gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`
+./simple
+

+
+
The cups-config command provides the compiler flags
+("cups-config --cflags") and libraries ("cups-config --libs") needed for the
+local system.

+
+
Where to Go Next

+
+
If you are developing a print filter, driver, or backend, see the
+Filter and Backend Programming
+guide. Raster printer driver developers should also read the
+Raster API reference.

+

+
+
diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html
index 2fe00be67..d8aa110a7 100644
--- a/doc/help/api-ppd.html
+++ b/doc/help/api-ppd.html
@@ -2,21 +2,391 @@
 
 
 
-	PPD API
-	
-	
-	
+PPD API
+
+
+
 
 
+

 
+
+
PPD API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/ppd.h
Library-lcups
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Reference: CUPS PPD Specification

+
Contents

+
+
 
-
Introduction

+
Overview

 
-
The CUPS PPD API provides read-only access the data in
-PostScript Printer Description ("PPD") files. With it you can
-display printer options to users, mark option choices and check
-for conflicting choices, and output marked choices in PostScript
-output.

+
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 display printer options to users, mark option choices and check for
+conflicting choices, and output marked choices in PostScript output. The
+ppd_file_t structure contains all of
+the information in a PPD file.

 
-
General Usage

+
Loading a PPD File

 
-
The <cups/ppd.h> header file must be included
-to use the ppd functions.

+
The ppdOpenFile function "opens" a
+PPD file and loads it into memory. For example, the following code opens the
+current printer's PPD file in a CUPS filter:

 
-
Programs using these functions must be linked to the CUPS
-library: libcups.a, libcups.so.2,
-libcups.2.dylib, libcups_s.a, or
-libcups2.lib depending on the platform. The following
-command compiles myprogram.c using GCC and the CUPS
-library:

+
+#include <cups/ppd.h>
 
-
-gcc -o myprogram myprogram.c -lcups
+ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
 

 
-
Compatibility

-
-
Unless otherwise specified, the PPD API functions require CUPS
-1.1 or higher.

-
Contents

-
-
-
Enumerations

-
-
-
ppd_conform_e

-
Description

-

-
Values

-

-
-
-
-
-
NameDescription
PPD_CONFORM_RELAXED Relax whitespace and control char
-
PPD_CONFORM_STRICT Require strict conformance
-

-
-
 CUPS 1.2 ppd_cptype_e

-
Description

-
Custom Parameter Type 
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
NameDescription
PPD_CUSTOM_CURVE Curve value for f(x) = x^value
-
PPD_CUSTOM_INT Integer number value
-
PPD_CUSTOM_INVCURVE Curve value for f(x) = x^(1/value)
-
PPD_CUSTOM_PASSCODE String of (hidden) numbers
-
PPD_CUSTOM_PASSWORD String of (hidden) characters
-
PPD_CUSTOM_POINTS Measurement value in points
-
PPD_CUSTOM_REAL Real number value
-
PPD_CUSTOM_STRING String of characters
-

-
-
ppd_cs_e

-
Description

-
Colorspaces
-
Values

-

-
-
-
-
-
-
-
-
-
NameDescription
PPD_CS_CMY CMY colorspace
-
PPD_CS_CMYK CMYK colorspace
-
PPD_CS_GRAY Grayscale colorspace
-
PPD_CS_N DeviceN colorspace
-
PPD_CS_RGB RGB colorspace
-
PPD_CS_RGBK RGBK (K = gray) colorspace
-

-
-
ppd_section_e

-
Description

-
Order dependency sections
-
Values

-

-
-
-
-
-
-
-
-
-
NameDescription
PPD_ORDER_ANY Option code can be anywhere in the file
-
PPD_ORDER_DOCUMENT ... must be in the DocumentSetup section
-
PPD_ORDER_EXIT ... must be sent prior to the document
-
PPD_ORDER_JCL ... must be sent as a JCL command
-
PPD_ORDER_PAGE ... must be in the PageSetup section
-
PPD_ORDER_PROLOG ... must be in the Prolog section
-

-
-
ppd_status_e

-
Description

-
Types and structures...
-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
PPD_ALLOC_ERROR Memory allocation error
-
PPD_BAD_CUSTOM_PARAM Bad custom parameter
-
PPD_BAD_OPEN_GROUP Bad OpenGroup
-
PPD_BAD_OPEN_UI Bad OpenUI/JCLOpenUI
-
PPD_BAD_ORDER_DEPENDENCY Bad OrderDependency
-
PPD_BAD_UI_CONSTRAINTS Bad UIConstraints
-
PPD_FILE_OPEN_ERROR Unable to open PPD file
-
PPD_ILLEGAL_CHARACTER Illegal control character
-
PPD_ILLEGAL_MAIN_KEYWORD Illegal main keyword string
-
PPD_ILLEGAL_OPTION_KEYWORD Illegal option keyword string
-
PPD_ILLEGAL_TRANSLATION Illegal translation string
-
PPD_ILLEGAL_WHITESPACE Illegal whitespace character
-
PPD_INTERNAL_ERROR Internal error
-
PPD_LINE_TOO_LONG Line longer than 255 chars
-
PPD_MISSING_ASTERISK Missing asterisk in column 0
-
PPD_MISSING_PPDADOBE4 Missing PPD-Adobe-4.x header
-
PPD_MISSING_VALUE Missing value string
-
PPD_NESTED_OPEN_GROUP OpenGroup without a CloseGroup first
-
PPD_NESTED_OPEN_UI OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first
-
PPD_NULL_FILE NULL PPD file pointer
-
PPD_OK OK
-

-
-
ppd_ui_e

-
Description

-
UI Types
-
Values

-

-
-
-
-
-
-
NameDescription
PPD_UI_BOOLEAN True or False option
-
PPD_UI_PICKMANY Pick zero or more from a list
-
PPD_UI_PICKONE Pick one from a list
-

-
-
Functions

-
-
-
ppdClose()

-
Description

-
Free all memory used by the PPD file.
-
Syntax

-

-void

-ppdClose(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD file record

-
Returns

-
Nothing.

-
-
ppdCollect()

-
Description

-
Collect all marked options that reside in the specified
-section.
-
Syntax

-

-int

-ppdCollect(
-    ppd_file_t * ppd,
-    ppd_section_t section,
-    ppd_choice_t *** choices);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file data
sectionSection to collect
choicesPointers to choices

-
Returns

-
Number of options marked

-
-
 CUPS 1.2 ppdCollect2()

-
Description

-
Collect all marked options that reside in the
-specified section and minimum order.
-
-
-
Syntax

-

-int

-ppdCollect2(
-    ppd_file_t * ppd,
-    ppd_section_t section,
-    float min_order,
-    ppd_choice_t *** choices);
-

-
Arguments

-

-
-
-
-
-
-
-
NameDescription
ppdPPD file data
sectionSection to collect
min_orderMinimum OrderDependency value
choicesPointers to choices

-
Returns

-
Number of options marked

-
-
ppdConflicts()

-
Description

-
Check to see if there are any conflicts.
-
Syntax

-

-int

-ppdConflicts(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD to check

-
Returns

-
Number of conflicts found

-
-
ppdEmit()

-
Description

-
Emit code for marked options to a file.
-
Syntax

-

-int

-ppdEmit(
-    ppd_file_t * ppd,
-    FILE * fp,
-    ppd_section_t section);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file record
fpFile to write to
sectionSection to write

-
Returns

-
0 on success, -1 on failure

-
-
 CUPS 1.2 ppdEmitAfterOrder()

-
Description

-
Emit a subset of the code for marked options to a file.
-
When "limit" is non-zero, this function only emits options whose
-OrderDependency value is greater than or equal to "min_order".
-
When "limit" is zero, this function is identical to ppdEmit().
-
-
-
Syntax

-

-int

-ppdEmitAfterOrder(
-    ppd_file_t * ppd,
-    FILE * fp,
-    ppd_section_t section,
-    int limit,
-    float min_order);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ppdPPD file record
fpFile to write to
sectionSection to write
limitNon-zero to use min_order
min_orderLowest OrderDependency

-
Returns

-
0 on success, -1 on failure

-
-
ppdEmitFd()

-
Description

-
Emit code for marked options to a file.
-
Syntax

-

-int

-ppdEmitFd(
-    ppd_file_t * ppd,
-    int fd,
-    ppd_section_t section);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file record
fdFile to write to
sectionSection to write

-
Returns

-
0 on success, -1 on failure

-
-
ppdEmitJCL()

-
Description

-
Emit code for JCL options to a file.
-
Syntax

-

-int

-ppdEmitJCL(
-    ppd_file_t * ppd,
-    FILE * fp,
-    int job_id,
-    const char * user,
-    const char * title);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ppdPPD file record
fpFile to write to
job_idJob ID
userUsername
titleTitle

-
Returns

-
0 on success, -1 on failure

-
-
 CUPS 1.2 ppdEmitJCLEnd()

-
Description

-
Emit JCLEnd code to a file.
-
-
-
Syntax

-

-int

-ppdEmitJCLEnd(
-    ppd_file_t * ppd,
-    FILE * fp);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file record
fpFile to write to

-
Returns

-
0 on success, -1 on failure

-
-
 CUPS 1.2 ppdEmitString()

-
Description

-
Get a string containing the code for marked options.
-
When "min_order" is greater than zero, this function only includes options
+
The return value is a pointer to a new
+ppd_file_t structure or NULL
+if the PPD file does not exist or cannot be loaded. The
+ppdClose function frees the memory used
+by the structure:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdClose(ppd);
+

+
+
Options and Groups

+
+
PPD files support multiple options, which are stored in arrays of
+ppd_option_t and
+ppd_choice_t structures.

+
+
Each option in turn is associated with a group stored in a
+ppd_group_t structure. Groups can be
+specified in the PPD file; if an option is not associated with a group
+then it is put in an automatically-generated "General" group. Groups can also
+have sub-groups, however CUPS currently ignores sub-groups because of past
+abuses of this functionality.

+
+
Options are selected by marking them using one of three functions. The
+first is ppdMarkDefaults which
+selects all of the default options in the PPD file:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdMarkDefaults(ppd);
+

+
+
The second is ppdMarkOption
+which selects a single option choice in the PPD file. For example, the following
+code selects the manual feed media source:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+ppdMarkOption(ppd, "InputSlot", "ManualFeed");
+

+
+
The last function is
+cupsMarkOptions which selects
+multiple option choices in the PPD file from an array of CUPS options, mapping
+IPP attributes like "media" and "sides" to their corresponding PPD options. You
+typically use this function in a print filter with
+cupsParseOptions and
+ppdMarkDefaults to select all of
+the option choices needed for the job, for example:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd = ppdOpenFile(getenv("PPD"));
+cups_option_t *options = NULL;
+int num_options = cupsParseOptions(argv[5], 0, &options);
+
+ppdMarkDefaults(ppd);
+cupsMarkOptions(ppd, num_options, options);
+

+
+
Constraints

+
+
PPD files support specification of conflict conditions, called
+constraints, between different options. Constraints are stored in an array of
+ppd_const_t structures which specify
+the options and choices that conflict with each other. The
+ppdConflicts function tells you
+how many of the selected options are incompatible.

+
+
Page Sizes

+
+
Page sizes are special options which have physical dimensions and margins
+associated with them. The size information is stored in
+ppd_size_t structures and is available
+by looking up the named size with the
+ppdPageSize function. The page size and
+margins are returned in units called points; there are 72 points per inch. If
+you pass NULL for the size, the currently selected size is
+returned:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+ppd_size_t *size = ppdPageSize(ppd, NULL);
+

+
+
Besides the standard page sizes listed in a PPD file, some printers
+support variable or custom page sizes. Custom page sizes are supported if the
+variables_sizes member of the
+ppd_file_t structure is non-zero.
+The custom_min, custom_max, and
+custom_margins members of the
+ppd_file_t structure define the limits
+of the printable area. To get the resulting media size, use a page size string
+of the form "Custom.widthxlength", where "width" and "length" are
+in points. Custom page size names can also be specified in inches
+("Custom.widthxheightin"), centimeters
+("Custom.widthxheightcm"), or millimeters
+("Custom.widthxheightmm"):

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+
+/* Get an 576x720 point custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.576x720");
+
+/* Get an 8x10 inch custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.8x10in");
+
+/* Get a 100x200 millimeter custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.100x200mm");
+
+/* Get a 12.7x34.5 centimeter custom page size */
+ppd_size_t *size = ppdPageSize(ppd, "Custom.12.7x34.5cm");
+

+
+
Attributes

+
+
Every PPD file is composed of one or more attributes. Most of these
+attributes are used to define groups, options, choices, and page sizes,
+however several informations attributes are available which you may need
+to access in your program or filter. Attributes normally look like one of
+the following examples in a PPD file:

+
+
+*name: "value"
+*name spec: "value"
+*name spec/text: "value"
+

+
+
The ppdFindAttr and
+ppdFindNextAttr functions find the
+first and next instances, respectively, of the named attribute with the given
+"spec" string and return a ppd_attr_t
+structure. If you provide a NULL specifier string, all attributes with the
+given name will be returned. For example, the following code lists all of the
+Product attributes in a PPD file:

+
+
+#include <cups/ppd.h>
+
+ppd_file_t *ppd;
+ppd_attr_t *attr;
+
+for (attr = ppdFindAttr(ppd, "Product", NULL);
+     attr != NULL;
+     attr = ppdFindNextAttr(ppd, "Product", NULL))
+  puts(attr->value);
+

+
Functions

+
cupsMarkOptions

+
Mark command-line options in a PPD file.

+

+int cupsMarkOptions (

+    ppd_file_t *ppd,

+    int num_options,

+    cups_option_t *options

+);

+
Parameters

+

+
ppd

+
PPD file

+
num_options

+
Number of options

+
options

+
Options

+

+
Return Value

+
1 if conflicting

+
Discussion

+
This function maps the IPP "finishings", "media", "mirror",
+"multiple-document-handling", "output-bin", "printer-resolution", and
+"sides" attributes to their corresponding PPD options and choices.

+
ppdClose

+
Free all memory used by the PPD file.

+

+void ppdClose (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD file record

+

+
ppdCollect

+
Collect all marked options that reside in the specified
+section.

+

+int ppdCollect (

+    ppd_file_t *ppd,

+    ppd_section_t section,

+    ppd_choice_t ***choices

+);

+
Parameters

+

+
ppd

+
PPD file data

+
section

+
Section to collect

+
choices

+
Pointers to choices

+

+
Return Value

+
Number of options marked

+
Discussion

+
The choices array should be freed using free when you are
+finished with it.

+
 CUPS 1.2 ppdCollect2

+
Collect all marked options that reside in the
+specified section and minimum order.

+

+int ppdCollect2 (

+    ppd_file_t *ppd,

+    ppd_section_t section,

+    float min_order,

+    ppd_choice_t ***choices

+);

+
Parameters

+

+
ppd

+
PPD file data

+
section

+
Section to collect

+
min_order

+
Minimum OrderDependency value

+
choices

+
Pointers to choices

+

+
Return Value

+
Number of options marked

+
Discussion

+
The choices array should be freed using free when you are
+finished with it.
+
+

+
ppdConflicts

+
Check to see if there are any conflicts among the
+marked option choices.

+

+int ppdConflicts (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD to check

+

+
Return Value

+
Number of conflicts found

+
Discussion

+
The returned value is the same as returned by ppdMarkOption.

+
ppdEmit

+
Emit code for marked options to a file.

+

+int ppdEmit (

+    ppd_file_t *ppd,

+    FILE *fp,

+    ppd_section_t section

+);

+
Parameters

+

+
ppd

+
PPD file record

+
fp

+
File to write to

+
section

+
Section to write

+

+
Return Value

+
0 on success, -1 on failure

+
 CUPS 1.2 ppdEmitAfterOrder

+
Emit a subset of the code for marked options to a file.

+

+int ppdEmitAfterOrder (

+    ppd_file_t *ppd,

+    FILE *fp,

+    ppd_section_t section,

+    int limit,

+    float min_order

+);

+
Parameters

+

+
ppd

+
PPD file record

+
fp

+
File to write to

+
section

+
Section to write

+
limit

+
Non-zero to use min_order

+
min_order

+
Lowest OrderDependency

+

+
Return Value

+
0 on success, -1 on failure

+
Discussion

+
When "limit" is non-zero, this function only emits options whose
+OrderDependency value is greater than or equal to "min_order".

+

+When "limit" is zero, this function is identical to ppdEmit().
+
+

+
ppdEmitFd

+
Emit code for marked options to a file.

+

+int ppdEmitFd (

+    ppd_file_t *ppd,

+    int fd,

+    ppd_section_t section

+);

+
Parameters

+

+
ppd

+
PPD file record

+
fd

+
File to write to

+
section

+
Section to write

+

+
Return Value

+
0 on success, -1 on failure

+
ppdEmitJCL

+
Emit code for JCL options to a file.

+

+int ppdEmitJCL (

+    ppd_file_t *ppd,

+    FILE *fp,

+    int job_id,

+    const char *user,

+    const char *title

+);

+
Parameters

+

+
ppd

+
PPD file record

+
fp

+
File to write to

+
job_id

+
Job ID

+
user

+
Username

+
title

+
Title

+

+
Return Value

+
0 on success, -1 on failure

+
 CUPS 1.2 ppdEmitJCLEnd

+
Emit JCLEnd code to a file.

+

+int ppdEmitJCLEnd (

+    ppd_file_t *ppd,

+    FILE *fp

+);

+
Parameters

+

+
ppd

+
PPD file record

+
fp

+
File to write to

+

+
Return Value

+
0 on success, -1 on failure

+
 CUPS 1.2 ppdEmitString

+
Get a string containing the code for marked options.

+

+char *ppdEmitString (

+    ppd_file_t *ppd,

+    ppd_section_t section,

+    float min_order

+);

+
Parameters

+

+
ppd

+
PPD file record

+
section

+
Section to write

+
min_order

+
Lowest OrderDependency

+

+
Return Value

+
String containing option code or NULL if there is no option code

+
Discussion

+
When "min_order" is greater than zero, this function only includes options
 whose OrderDependency value is greater than or equal to "min_order".
 Otherwise, all options in the specified section are included in the
-returned string.
-
The return string is allocated on the heap and should be freed using
-free() when you are done with it.
-
-
-
Syntax

-

-char *

-ppdEmitString(
-    ppd_file_t * ppd,
-    ppd_section_t section,
-    float min_order);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file record
sectionSection to write
min_orderLowest OrderDependency

-
Returns

-
String containing option code

-
-
 CUPS 1.1.19 ppdErrorString()

-
Description

-
Returns the text assocated with a status.
-
-
-
Syntax

-

-const char *

-ppdErrorString(
-    ppd_status_t status);
-

-
Arguments

-

-
-
-
-
NameDescription
statusPPD status

-
Returns

-
Status string

-
-
 CUPS 1.1.19 ppdFindAttr()

-
Description

-
Find the first matching attribute...
-
-
-
Syntax

-

-ppd_attr_t *

-ppdFindAttr(
-    ppd_file_t * ppd,
-    const char * name,
-    const char * spec);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file data
nameAttribute name
specSpecifier string or NULL

-
Returns

-
Attribute or NULL if not found

-
-
ppdFindChoice()

-
Description

-
Return a pointer to an option choice.
-
Syntax

-

-ppd_choice_t *

-ppdFindChoice(
-    ppd_option_t * o,
-    const char * choice);
-

-
Arguments

-

-
-
-
-
-
NameDescription
oPointer to option
choiceName of choice

-
Returns

-
Choice pointer or NULL

-
-
 CUPS 1.2 ppdFindCustomOption()

-
Description

-
Find a custom option.
-
-
-
Syntax

-

-ppd_coption_t *

-ppdFindCustomOption(
-    ppd_file_t * ppd,
-    const char * keyword);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file
keywordCustom option name

-
Returns

-
Custom option or NULL

-
-
 CUPS 1.2 ppdFindCustomParam()

-
Description

-
Find a parameter for a custom option.
-
-
-
Syntax

-

-ppd_cparam_t *

-ppdFindCustomParam(
-    ppd_coption_t * opt,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
optCustom option
nameParameter name

-
Returns

-
Custom parameter or NULL

-
-
ppdFindMarkedChoice()

-
Description

-
Return the marked choice for the specified option.
-
Syntax

-

-ppd_choice_t *

-ppdFindMarkedChoice(
-    ppd_file_t * ppd,
-    const char * option);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file
optionKeyword/option name

-
Returns

-
Pointer to choice or NULL

-
-
 CUPS 1.1.19 ppdFindNextAttr()

-
Description

-
Find the next matching attribute...
-
-
-
Syntax

-

-ppd_attr_t *

-ppdFindNextAttr(
-    ppd_file_t * ppd,
-    const char * name,
-    const char * spec);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file data
nameAttribute name
specSpecifier string or NULL

-
Returns

-
Attribute or NULL if not found

-
-
ppdFindOption()

-
Description

-
Return a pointer to the specified option.
-
Syntax

-

-ppd_option_t *

-ppdFindOption(
-    ppd_file_t * ppd,
-    const char * option);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file data
optionOption/Keyword name

-
Returns

-
Pointer to option or NULL

-
-
 CUPS 1.2 ppdFirstCustomParam()

-
Description

-
Return the first parameter for a custom option.
-
-
-
Syntax

-

-ppd_cparam_t *

-ppdFirstCustomParam(
-    ppd_coption_t * opt);
-

-
Arguments

-

-
-
-
-
NameDescription
optCustom option

-
Returns

-
Custom parameter or NULL

-
-
 CUPS 1.2 ppdFirstOption()

-
Description

-
Return the first option in the PPD file.
-
Options are returned from all groups in sorted order.
-
-
-
Syntax

-

-ppd_option_t *

-ppdFirstOption(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD file

-
Returns

-
First option or NULL

-
-
ppdIsMarked()

-
Description

-
Check to see if an option is marked...
-
Syntax

-

-int

-ppdIsMarked(
-    ppd_file_t * ppd,
-    const char * option,
-    const char * choice);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file data
optionOption/Keyword name
choiceChoice name

-
Returns

-
Non-zero if option is marked

-
-
 CUPS 1.1.19 ppdLastError()

-
Description

-
Return the status from the last ppdOpen*().
-
-
-
Syntax

-

-ppd_status_t

-ppdLastError(
-    int * line);
-

-
Arguments

-

-
-
-
-
NameDescription
lineLine number

-
Returns

-
Status code

-
-
 CUPS 1.2 ppdLocalize()

-
Description

-
Localize the PPD file to the current locale.
-
All groups, options, and choices are localized, as are ICC profile
+returned string.

+

+The return string is allocated on the heap and should be freed using
+free when you are done with it.
+
+

+
 CUPS 1.1.19 ppdErrorString

+
Returns the text assocated with a status.

+

+const char *ppdErrorString (

+    ppd_status_t status

+);

+
Parameters

+

+
status

+
PPD status

+

+
Return Value

+
Status string

+
 CUPS 1.1.19 ppdFindAttr

+
Find the first matching attribute.

+

+ppd_attr_t *ppdFindAttr (

+    ppd_file_t *ppd,

+    const char *name,

+    const char *spec

+);

+
Parameters

+

+
ppd

+
PPD file data

+
name

+
Attribute name

+
spec

+
Specifier string or NULL

+

+
Return Value

+
Attribute or NULL if not found

+
ppdFindChoice

+
Return a pointer to an option choice.

+

+ppd_choice_t *ppdFindChoice (

+    ppd_option_t *o,

+    const char *choice

+);

+
Parameters

+

+
o

+
Pointer to option

+
choice

+
Name of choice

+

+
Return Value

+
Choice pointer or NULL

+
 CUPS 1.2 ppdFindCustomOption

+
Find a custom option.

+

+ppd_coption_t *ppdFindCustomOption (

+    ppd_file_t *ppd,

+    const char *keyword

+);

+
Parameters

+

+
ppd

+
PPD file

+
keyword

+
Custom option name

+

+
Return Value

+
Custom option or NULL

+
 CUPS 1.2 ppdFindCustomParam

+
Find a parameter for a custom option.

+

+ppd_cparam_t *ppdFindCustomParam (

+    ppd_coption_t *opt,

+    const char *name

+);

+
Parameters

+

+
opt

+
Custom option

+
name

+
Parameter name

+

+
Return Value

+
Custom parameter or NULL

+
ppdFindMarkedChoice

+
Return the marked choice for the specified option.

+

+ppd_choice_t *ppdFindMarkedChoice (

+    ppd_file_t *ppd,

+    const char *option

+);

+
Parameters

+

+
ppd

+
PPD file

+
option

+
Keyword/option name

+

+
Return Value

+
Pointer to choice or NULL

+
 CUPS 1.1.19 ppdFindNextAttr

+
Find the next matching attribute.

+

+ppd_attr_t *ppdFindNextAttr (

+    ppd_file_t *ppd,

+    const char *name,

+    const char *spec

+);

+
Parameters

+

+
ppd

+
PPD file data

+
name

+
Attribute name

+
spec

+
Specifier string or NULL

+

+
Return Value

+
Attribute or NULL if not found

+
ppdFindOption

+
Return a pointer to the specified option.

+

+ppd_option_t *ppdFindOption (

+    ppd_file_t *ppd,

+    const char *option

+);

+
Parameters

+

+
ppd

+
PPD file data

+
option

+
Option/Keyword name

+

+
Return Value

+
Pointer to option or NULL

+
 CUPS 1.2 ppdFirstCustomParam

+
Return the first parameter for a custom option.

+

+ppd_cparam_t *ppdFirstCustomParam (

+    ppd_coption_t *opt

+);

+
Parameters

+

+
opt

+
Custom option

+

+
Return Value

+
Custom parameter or NULL

+
 CUPS 1.2 ppdFirstOption

+
Return the first option in the PPD file.

+

+ppd_option_t *ppdFirstOption (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD file

+

+
Return Value

+
First option or NULL

+
Discussion

+
Options are returned from all groups in ascending alphanumeric order.
+
+

+
ppdIsMarked

+
Check to see if an option is marked.

+

+int ppdIsMarked (

+    ppd_file_t *ppd,

+    const char *option,

+    const char *choice

+);

+
Parameters

+

+
ppd

+
PPD file data

+
option

+
Option/Keyword name

+
choice

+
Choice name

+

+
Return Value

+
Non-zero if option is marked

+
 CUPS 1.1.19 ppdLastError

+
Return the status from the last ppdOpen*().

+

+ppd_status_t ppdLastError (

+    int *line

+);

+
Parameters

+

+
line

+
Line number

+

+
Return Value

+
Status code

+
 CUPS 1.2 ppdLocalize

+
Localize the PPD file to the current locale.

+

+int ppdLocalize (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD file

+

+
Return Value

+
0 on success, -1 on error

+
Discussion

+
All groups, options, and choices are localized, as are ICC profile
 descriptions, printer presets, and custom option parameters.  Each
 localized string uses the UTF-8 character encoding.
 
-
-
Syntax

-

-int

-ppdLocalize(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD file

-
Returns

-
0 on success, -1 on error

-
-
 CUPS 1.3 ppdLocalizeIPPReason()

-
Description

-
Get the localized version of a cupsIPPReason
-attribute.
-
This function uses the current locale to find the corresponding reason
+

+
 CUPS 1.3 ppdLocalizeIPPReason

+
Get the localized version of a cupsIPPReason
+attribute.

+

+const char *ppdLocalizeIPPReason (

+    ppd_file_t *ppd,

+    const char *reason,

+    const char *scheme,

+    char *buffer,

+    size_t bufsize

+);

+
Parameters

+

+
ppd

+
PPD file

+
reason

+
IPP reason keyword to look up

+
scheme

+
URI scheme or NULL for text

+
buffer

+
Value buffer

+
bufsize

+
Size of value buffer

+

+
Return Value

+
Value or NULL if not found

+
Discussion

+
This function uses the current locale to find the corresponding reason
 text or URI from the attribute value. If "scheme" is NULL or "text",
 the returned value contains human-readable (UTF-8) text from the translation
-string or attribute value. Otherwise the corresponding URI is returned.
-
If no value of the requested scheme can be found, NULL is returned.
-
-
-
Syntax

-

-const char *

-ppdLocalizeIPPReason(
-    ppd_file_t * ppd,
-    const char * reason,
-    const char * scheme,
-    char * buffer,
-    size_t bufsize);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
ppdPPD file
reasonIPP reason keyword to look up
schemeURI scheme or NULL for text
bufferValue buffer
bufsizeSize of value buffer

-
Returns

-
Value or NULL if not found

-
-
ppdMarkDefaults()

-
Description

-
Mark all default options in the PPD file.
-
Syntax

-

-void

-ppdMarkDefaults(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD file record

-
Returns

-
Nothing.

-
-
ppdMarkOption()

-
Description

-
Mark an option in a PPD file.
-
Notes:
-
-1 is returned if the given option would conflict with any currently
-selected option.
-
Syntax

-

-int

-ppdMarkOption(
-    ppd_file_t * ppd,
-    const char * option,
-    const char * choice);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
ppdPPD file record
optionKeyword
choiceOption name

-
Returns

-
Number of conflicts

-
-
 CUPS 1.2 ppdNextCustomParam()

-
Description

-
Return the next parameter for a custom option.
-
-
-
Syntax

-

-ppd_cparam_t *

-ppdNextCustomParam(
-    ppd_coption_t * opt);
-

-
Arguments

-

-
-
-
-
NameDescription
optCustom option

-
Returns

-
Custom parameter or NULL

-
-
 CUPS 1.2 ppdNextOption()

-
Description

-
Return the next option in the PPD file.
-
Options are returned from all groups in sorted order.
-
-
-
Syntax

-

-ppd_option_t *

-ppdNextOption(
-    ppd_file_t * ppd);
-

-
Arguments

-

-
-
-
-
NameDescription
ppdPPD file

-
Returns

-
Next option or NULL

-
-
ppdOpen()

-
Description

-
Read a PPD file into memory.
-
Syntax

-

-ppd_file_t *

-ppdOpen(
-    FILE * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpFile to read from

-
Returns

-
PPD file record

-
-
 CUPS 1.2 ppdOpen2()

-
Description

-
Read a PPD file into memory.
-
-
-
Syntax

-

-ppd_file_t *

-ppdOpen2(
-    cups_file_t * fp);
-

-
Arguments

-

-
-
-
-
NameDescription
fpFile to read from

-
Returns

-
PPD file record

-
-
ppdOpenFd()

-
Description

-
Read a PPD file into memory.
-
Syntax

-

-ppd_file_t *

-ppdOpenFd(
-    int fd);
-

-
Arguments

-

-
-
-
-
NameDescription
fdFile to read from

-
Returns

-
PPD file record

-
-
ppdOpenFile()

-
Description

-
Read a PPD file into memory.
-
Syntax

-

-ppd_file_t *

-ppdOpenFile(
-    const char * filename);
-

-
Arguments

-

-
-
-
-
NameDescription
filenameFile to read from

-
Returns

-
PPD file record

-
-
ppdPageLength()

-
Description

-
Get the page length for the given size.
-
Syntax

-

-float

-ppdPageLength(
-    ppd_file_t * ppd,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file
nameSize name

-
Returns

-
Length of page in points or 0.0

-
-
ppdPageSize()

-
Description

-
Get the page size record for the given size.
-
Syntax

-

-ppd_size_t *

-ppdPageSize(
-    ppd_file_t * ppd,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file record
nameSize name

-
Returns

-
Size record for page or NULL

-
-
ppdPageWidth()

-
Description

-
Get the page width for the given size.
-
Syntax

-

-float

-ppdPageWidth(
-    ppd_file_t * ppd,
-    const char * name);
-

-
Arguments

-

-
-
-
-
-
NameDescription
ppdPPD file record
nameSize name

-
Returns

-
Width of page in points or 0.0

-
-
 CUPS 1.1.20 ppdSetConformance()

-
Description

-
Set the conformance level for PPD files.
-
-
-
Syntax

-

-void

-ppdSetConformance(
-    ppd_conform_t c);
-

-
Arguments

-

-
-
-
-
NameDescription
cConformance level

-
Returns

-
Nothing.

-
-
Structures

-
-
-
 CUPS 1.1.19 ppd_attr_s

-
Description

-
PPD Attribute Structure 
-
Definition

-

-struct ppd_attr_s

-{

-  char name[PPD_MAX_NAME];

-  char spec[PPD_MAX_NAME];

-  char text[PPD_MAX_TEXT];

-  char * value;

-};

-
Members

-

-
-
-
-
-
-
-
NameDescription
name[PPD_MAX_NAME] Name of attribute (cupsXYZ)
-
spec[PPD_MAX_NAME] Specifier string, if any
-
text[PPD_MAX_TEXT] Human-readable text, if any
-
value Value string
-

-
-
ppd_choice_s

-
Description

-
Option choices
-
Definition

-

-struct ppd_choice_s

-{

-  char choice[PPD_MAX_NAME];

-  char * code;

-  char marked;

-  ppd_option_t * option;

-  char text[PPD_MAX_TEXT];

-};

-
Members

-

-
-
-
-
-
-
-
-
NameDescription
choice[PPD_MAX_NAME] Computer-readable option name
-
code Code to send for this option
-
marked 0 if not selected, 1 otherwise
-
option Pointer to parent option structure
-
text[PPD_MAX_TEXT] Human-readable option name
-

-
-
 CUPS 1.2 ppd_coption_s

-
Description

-
Custom Option 
-
Definition

-

-struct ppd_coption_s

-{

-  char keyword[PPD_MAX_NAME];

-  int marked;

-  ppd_option_t * option;

-  cups_array_t * params;

-};

-
Members

-

-
-
-
-
-
-
-
NameDescription
keyword[PPD_MAX_NAME] Name of option that is being extended...
-
marked Extended option is marked
-
option Option that is being extended...
-
params Parameters
-

-
-
 CUPS 1.2 ppd_cparam_s

-
Description

-
Custom Parameter 
-
Definition

-

-struct ppd_cparam_s

-{

-  ppd_cpvalue_t current;

-  ppd_cplimit_t minimum, maximum;

-  char name[PPD_MAX_NAME];

-  int order;

-  char text[PPD_MAX_TEXT];

-  ppd_cptype_t type;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
NameDescription
current Current value
-
maximum Maximum value
-
name[PPD_MAX_NAME] Parameter name
-
order Order (0 to N)
-
text[PPD_MAX_TEXT] Human-readable text
-
type Parameter type
-

-
-
ppd_emul_s

-
Description

-
Emulators
-
Definition

-

-struct ppd_emul_s

-{

-  char name[PPD_MAX_NAME];

-  char * start;

-  char * stop;

-};

-
Members

-

-
-
-
-
-
-
NameDescription
name[PPD_MAX_NAME] Emulator name
-
start Code to switch to this emulation
-
stop Code to stop this emulation
-

-
-
ppd_file_s

-
Description

-
PPD File
-
Definition

-

-struct ppd_file_s

-{

-  int accurate_screens;

-  ppd_attr_t ** attrs;

-  int color_device;

-  ppd_cs_t colorspace;

-  ppd_const_t * consts;

-  int contone_only;

-  cups_array_t * coptions;

-  int cur_attr;

-  float custom_margins[4];

-  float custom_max[2];

-  float custom_min[2];

-  ppd_emul_t * emulations;

-  char ** filters;

-  int flip_duplex;

-  char ** fonts;

-  ppd_group_t * groups;

-  char * jcl_begin;

-  char * jcl_end;

-  char * jcl_ps;

-  int landscape;

-  char * lang_encoding;

-  char * lang_version;

-  int language_level;

-  int manual_copies;

-  char * manufacturer;

-  cups_array_t * marked;

-  int model_number;

-  char * modelname;

-  char * nickname;

-  int num_attrs;

-  int num_consts;

-  int num_emulations;

-  int num_filters;

-  int num_fonts;

-  int num_groups;

-  int num_profiles;

-  int num_sizes;

-  cups_array_t * options;

-  char * patches;

-  char * pcfilename;

-  char * product;

-  ppd_profile_t * profiles;

-  char * protocols;

-  char * shortnickname;

-  ppd_size_t * sizes;

-  cups_array_t * sorted_attrs;

-  int throughput;

-  char * ttrasterizer;

-  int variable_sizes;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
accurate_screens 1 = supports accurate screens, 0 = not
-
attrs  CUPS 1.1.19 Attributes  @private@
-
color_device 1 = color device, 0 = grayscale
-
colorspace Default colorspace
-
consts UI/Non-UI constraints
-
contone_only 1 = continuous tone only, 0 = not
-
coptions  CUPS 1.2 Custom options array  @private@
-
cur_attr  CUPS 1.1.19 Current attribute  @private@
-
custom_margins[4] Margins around page
-
custom_max[2] Maximum variable page size
-
custom_min[2] Minimum variable page size
-
emulations Emulations and the code to invoke them
-
filters Filter strings...
-
flip_duplex  DEPRECATED 1 = Flip page for back sides 
-
fonts Pre-loaded fonts
-
groups UI groups
-
jcl_begin Start JCL commands
-
jcl_end End JCL commands
-
jcl_ps Enter PostScript interpreter
-
landscape -90 or 90
-
lang_encoding Language encoding
-
lang_version Language version (English, Spanish, etc.)
-
language_level Language level of device
-
manual_copies 1 = Copies done manually, 0 = hardware
-
manufacturer Manufacturer name
-
marked  CUPS 1.3 Marked choices  @private@
-
model_number Device-specific model number
-
modelname Model name (general)
-
nickname Nickname (specific)
-
num_attrs  CUPS 1.1.19 Number of attributes  @private@
-
num_consts Number of UI/Non-UI constraints
-
num_emulations Number of emulations supported
-
num_filters Number of filters
-
num_fonts Number of pre-loaded fonts
-
num_groups Number of UI groups
-
num_profiles Number of sRGB color profiles
-
num_sizes Number of page sizes
-
options  CUPS 1.2 Option lookup array  @private@
-
patches Patch commands to be sent to printer
-
pcfilename  CUPS 1.1.19 PCFileName string 
-
product Product name (from PS RIP/interpreter)
-
profiles sRGB color profiles
-
protocols  CUPS 1.1.19 Protocols (BCP, TBCP) string 
-
shortnickname Short version of nickname
-
sizes Page sizes
-
sorted_attrs  CUPS 1.2 Attribute lookup array  @private@
-
throughput Pages per minute
-
ttrasterizer Truetype rasterizer
-
variable_sizes 1 = supports variable sizes, 0 = doesn't
-

-
-
ppd_group_s

-
Description

-
Groups
-
Definition

-

-struct ppd_group_s

-{

-  char text[PPD_MAX_TEXT - PPD_MAX_NAME];

-  char name[PPD_MAX_NAME];

-  int num_options;

-  int num_subgroups;

-  ppd_option_t * options;

-  struct ppd_group_s * subgroups;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
NameDescription
PPD_MAX_NAME] Human-readable group name
-
name[PPD_MAX_NAME]  CUPS 1.1.18 Group name 
-
num_options Number of options
-
num_subgroups Number of sub-groups
-
options Options
-
subgroups Sub-groups (max depth = 1)
-

-
-
ppd_option_s

-
Description

-
Options
-
Definition

-

-struct ppd_option_s

-{

-  ppd_choice_t * choices;

-  char conflicted;

-  char defchoice[PPD_MAX_NAME];

-  char keyword[PPD_MAX_NAME];

-  int num_choices;

-  float order;

-  ppd_section_t section;

-  char text[PPD_MAX_TEXT];

-  ppd_ui_t ui;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
choices Option choices
-
conflicted 0 if no conflicts exist, 1 otherwise
-
defchoice[PPD_MAX_NAME] Default option choice
-
keyword[PPD_MAX_NAME] Option keyword name ("PageSize", etc.)
-
num_choices Number of option choices
-
order Order number
-
section Section for command
-
text[PPD_MAX_TEXT] Human-readable text
-
ui Type of UI option
-

-
-
ppd_profile_s

-
Description

-
sRGB Color Profiles
-
Definition

-

-struct ppd_profile_s

-{

-  float density;

-  float gamma;

-  float matrix[3][3];

-  char media_type[PPD_MAX_NAME];

-  char resolution[PPD_MAX_NAME];

-};

-
Members

-

-
-
-
-
-
-
-
-
NameDescription
density Ink density to use
-
gamma Gamma correction to use
-
matrix[3][3] Transform matrix
-
media_type[PPD_MAX_NAME] Media type or "-"
-
resolution[PPD_MAX_NAME] Resolution or "-"
-

-
-
ppd_size_s

-
Description

-
Page Sizes
-
Definition

-

-struct ppd_size_s

-{

-  float bottom;

-  float left;

-  float length;

-  int marked;

-  char name[PPD_MAX_NAME];

-  float right;

-  float top;

-  float width;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
NameDescription
bottom Bottom printable margin in points
-
left Left printable margin in points
-
length Length of media in points
-
marked Page size selected?
-
name[PPD_MAX_NAME] Media size option
-
right Right printable margin in points
-
top Top printable margin in points
-
width Width of media in points
-

-
-
Types

-
-
-
 CUPS 1.1.19 ppd_attr_t

-
Description

-
PPD Attribute Structure 
-
Definition

-

-typedef struct ppd_attr_s ppd_attr_t;
-

-
-
ppd_choice_t

-
Description

-
Option choices
-
Definition

-

-typedef struct ppd_choice_s ppd_choice_t;
-

-
-
ppd_const_t

-
Description

-
Constraints
-
Definition

-

-typedef struct ppd_const_t;
-

-
-
 CUPS 1.2 ppd_coption_t

-
Description

-
Custom Option 
-
Definition

-

-typedef struct ppd_coption_s ppd_coption_t;
-

-
-
 CUPS 1.2 ppd_cparam_t

-
Description

-
Custom Parameter 
-
Definition

-

-typedef struct ppd_cparam_s ppd_cparam_t;
-

-
-
 CUPS 1.2 ppd_cplimit_t

-
Description

-
Custom Parameter Limit 
-
Definition

-

-typedef union ppd_cplimit_u ppd_cplimit_t;
-

-
-
 CUPS 1.2 ppd_cptype_t

-
Description

-
Custom Parameter Type 
-
Definition

-

-typedef enum ppd_cptype_e ppd_cptype_t;
-

-
-
 CUPS 1.2 ppd_cpvalue_t

-
Description

-
Custom Parameter Value 
-
Definition

-

-typedef union ppd_cpvalue_u ppd_cpvalue_t;
-

-
-
ppd_emul_t

-
Description

-
Emulators
-
Definition

-

-typedef struct ppd_emul_s ppd_emul_t;
-

-
-
ppd_file_t

-
Description

-
PPD File
-
Definition

-

-typedef struct ppd_file_s ppd_file_t;
-

-
-
ppd_group_t

-
Description

-
Groups
-
Definition

-

-typedef struct ppd_group_s ppd_group_t;
-

-
-
ppd_option_t

-
Description

-
Options
-
Definition

-

-typedef struct ppd_option_s ppd_option_t;
-

-
-
ppd_profile_t

-
Description

-
sRGB Color Profiles
-
Definition

-

-typedef struct ppd_profile_s ppd_profile_t;
-

-
-
ppd_section_t

-
Description

-
Order dependency sections
-
Definition

-

-typedef enum ppd_section_e ppd_section_t;
-

-
-
ppd_size_t

-
Description

-
Page Sizes
-
Definition

-

-typedef struct ppd_size_s ppd_size_t;
-

-
-
ppd_ui_t

-
Description

-
UI Types
-
Definition

-

-typedef enum ppd_ui_e ppd_ui_t;
-

-
-
Unions

-
-
-
 CUPS 1.2 ppd_cplimit_u

-
Description

-
Custom Parameter Limit 
-
Definition

-

-union ppd_cplimit_u

-{

-  float custom_curve;

-  int custom_int;

-  float custom_invcurve;

-  int custom_passcode;

-  int custom_password;

-  float custom_points;

-  float custom_real;

-  int custom_string;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
NameDescription
custom_curve Gamma value
-
custom_int Integer value
-
custom_invcurve Gamma value
-
custom_passcode Passcode length
-
custom_password Password length
-
custom_points Measurement value
-
custom_real Real value
-
custom_string String length
-

-
-
 CUPS 1.2 ppd_cpvalue_u

-
Description

-
Custom Parameter Value 
-
Definition

-

-union ppd_cpvalue_u

-{

-  float custom_curve;

-  int custom_int;

-  float custom_invcurve;

-  char * custom_passcode;

-  char * custom_password;

-  float custom_points;

-  float custom_real;

-  char * custom_string;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
NameDescription
custom_curve Gamma value
-
custom_int Integer value
-
custom_invcurve Gamma value
-
custom_passcode Passcode value
-
custom_password Password value
-
custom_points Measurement value
-
custom_real Real value
-
custom_string String value
-

+string or attribute value. Otherwise the corresponding URI is returned.

+

+If no value of the requested scheme can be found, NULL is returned.
+
+

+
 CUPS 1.4 ppdLocalizeMarkerName

+
Get the localized version of a marker-names
+attribute value.

+

+const char *ppdLocalizeMarkerName (

+    ppd_file_t *ppd,

+    const char *name

+);

+
Parameters

+

+
ppd

+
PPD file

+
name

+
Marker name to look up

+

+
Return Value

+
Value or NULL if not found

+
Discussion

+
This function uses the current locale to find the corresponding name
+text from the attribute value. If no localized text for the requested
+name can be found, NULL is returned.
+
+

+
ppdMarkDefaults

+
Mark all default options in the PPD file.

+

+void ppdMarkDefaults (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD file record

+

+
ppdMarkOption

+
Mark an option in a PPD file.

+

+int ppdMarkOption (

+    ppd_file_t *ppd,

+    const char *option,

+    const char *choice

+);

+
Parameters

+

+
ppd

+
PPD file record

+
option

+
Keyword

+
choice

+
Option name

+

+
Return Value

+
Number of conflicts

+
 CUPS 1.2 ppdNextCustomParam

+
Return the next parameter for a custom option.

+

+ppd_cparam_t *ppdNextCustomParam (

+    ppd_coption_t *opt

+);

+
Parameters

+

+
opt

+
Custom option

+

+
Return Value

+
Custom parameter or NULL

+
 CUPS 1.2 ppdNextOption

+
Return the next option in the PPD file.

+

+ppd_option_t *ppdNextOption (

+    ppd_file_t *ppd

+);

+
Parameters

+

+
ppd

+
PPD file

+

+
Return Value

+
Next option or NULL

+
Discussion

+
Options are returned from all groups in ascending alphanumeric order.
+
+

+
ppdOpen

+
Read a PPD file into memory.

+

+ppd_file_t *ppdOpen (

+    FILE *fp

+);

+
Parameters

+

+
fp

+
File to read from

+

+
Return Value

+
PPD file record

+
 CUPS 1.2 ppdOpen2

+
Read a PPD file into memory.

+

+ppd_file_t *ppdOpen2 (

+    cups_file_t *fp

+);

+
Parameters

+

+
fp

+
File to read from

+

+
Return Value

+
PPD file record or NULL if the PPD file could not be opened.

+
ppdOpenFd

+
Read a PPD file into memory.

+

+ppd_file_t *ppdOpenFd (

+    int fd

+);

+
Parameters

+

+
fd

+
File to read from

+

+
Return Value

+
PPD file record or NULL if the PPD file could not be opened.

+
ppdOpenFile

+
Read a PPD file into memory.

+

+ppd_file_t *ppdOpenFile (

+    const char *filename

+);

+
Parameters

+

+
filename

+
File to read from

+

+
Return Value

+
PPD file record or NULL if the PPD file could not be opened.

+
ppdPageLength

+
Get the page length for the given size.

+

+float ppdPageLength (

+    ppd_file_t *ppd,

+    const char *name

+);

+
Parameters

+

+
ppd

+
PPD file

+
name

+
Size name

+

+
Return Value

+
Length of page in points or 0.0

+
ppdPageSize

+
Get the page size record for the given size.

+

+ppd_size_t *ppdPageSize (

+    ppd_file_t *ppd,

+    const char *name

+);

+
Parameters

+

+
ppd

+
PPD file record

+
name

+
Size name

+

+
Return Value

+
Size record for page or NULL

+
ppdPageWidth

+
Get the page width for the given size.

+

+float ppdPageWidth (

+    ppd_file_t *ppd,

+    const char *name

+);

+
Parameters

+

+
ppd

+
PPD file record

+
name

+
Size name

+

+
Return Value

+
Width of page in points or 0.0

+
 CUPS 1.1.20 ppdSetConformance

+
Set the conformance level for PPD files.

+

+void ppdSetConformance (

+    ppd_conform_t c

+);

+
Parameters

+

+
c

+
Conformance level

+

+
Data Types

+
 CUPS 1.1.19 ppd_attr_t

+
PPD Attribute Structure 

+

+typedef struct ppd_attr_s ppd_attr_t;
+

+
ppd_choice_t

+
Option choices

+

+typedef struct ppd_choice_s ppd_choice_t;
+

+
 CUPS 1.1.19 ppd_conform_t

+
Conformance Levels 

+

+typedef enum ppd_conform_e ppd_conform_t;
+

+
ppd_const_t

+
Constraints

+

+typedef struct ppd_const_s ppd_const_t;
+

+
 CUPS 1.2 ppd_coption_t

+
Custom Option 

+

+typedef struct ppd_coption_s ppd_coption_t;
+

+
 CUPS 1.2 ppd_cparam_t

+
Custom Parameter 

+

+typedef struct ppd_cparam_s ppd_cparam_t;
+

+
 CUPS 1.2 ppd_cplimit_t

+
Custom Parameter Limit 

+

+typedef union ppd_cplimit_u ppd_cplimit_t;
+

+
 CUPS 1.2 ppd_cptype_t

+
Custom Parameter Type 

+

+typedef enum ppd_cptype_e ppd_cptype_t;
+

+
 CUPS 1.2 ppd_cpvalue_t

+
Custom Parameter Value 

+

+typedef union ppd_cpvalue_u ppd_cpvalue_t;
+

+
ppd_emul_t

+
Emulators

+

+typedef struct ppd_emul_s ppd_emul_t;
+

+
ppd_file_t

+
PPD File

+

+typedef struct ppd_file_s ppd_file_t;
+

+
ppd_group_t

+
Groups

+

+typedef struct ppd_group_s ppd_group_t;
+

+
ppd_option_t

+
Options

+

+typedef struct ppd_option_s ppd_option_t;
+

+
ppd_profile_t

+
sRGB Color Profiles

+

+typedef struct ppd_profile_s ppd_profile_t;
+

+
ppd_section_t

+
Order dependency sections

+

+typedef enum ppd_section_e ppd_section_t;
+

+
ppd_size_t

+
Page Sizes

+

+typedef struct ppd_size_s ppd_size_t;
+

+
ppd_ui_t

+
UI Types

+

+typedef enum ppd_ui_e ppd_ui_t;
+

+
Structures

+
 CUPS 1.1.19 ppd_attr_s

+
PPD Attribute Structure 

+
struct ppd_attr_s {

+    char name[PPD_MAX_NAME];

+    char spec[PPD_MAX_NAME];

+    char text[PPD_MAX_TEXT];

+    char *value;

+};

+
Members

+

+
name[PPD_MAX_NAME] 

+
Name of attribute (cupsXYZ)

+
spec[PPD_MAX_NAME] 

+
Specifier string, if any

+
text[PPD_MAX_TEXT] 

+
Human-readable text, if any

+
value 

+
Value string

+

+
ppd_choice_s

+
Option choices

+
struct ppd_choice_s {

+    char choice[PPD_MAX_NAME];

+    char *code;

+    char marked;

+    ppd_option_t *option;

+    char text[PPD_MAX_TEXT];

+};

+
Members

+

+
choice[PPD_MAX_NAME] 

+
Computer-readable option name

+
code 

+
Code to send for this option

+
marked 

+
0 if not selected, 1 otherwise

+
option 

+
Pointer to parent option structure

+
text[PPD_MAX_TEXT] 

+
Human-readable option name

+

+
ppd_const_s

+
Constraints

+
struct ppd_const_s {

+    char choice1[PPD_MAX_NAME];

+    char choice2[PPD_MAX_NAME];

+    char option1[PPD_MAX_NAME];

+    char option2[PPD_MAX_NAME];

+};

+
Members

+

+
choice1[PPD_MAX_NAME] 

+
First option/choice (blank for all)

+
choice2[PPD_MAX_NAME] 

+
Second option/choice (blank for all)

+
option1[PPD_MAX_NAME] 

+
First keyword

+
option2[PPD_MAX_NAME] 

+
Second keyword

+

+
 CUPS 1.2 ppd_coption_s

+
Custom Option 

+
struct ppd_coption_s {

+    char keyword[PPD_MAX_NAME];

+    int marked;

+    ppd_option_t *option;

+    cups_array_t *params;

+};

+
Members

+

+
keyword[PPD_MAX_NAME] 

+
Name of option that is being extended...

+
marked 

+
Extended option is marked

+
option 

+
Option that is being extended...

+
params 

+
Parameters

+

+
 CUPS 1.2 ppd_cparam_s

+
Custom Parameter 

+
struct ppd_cparam_s {

+    ppd_cpvalue_t current;

+    ppd_cplimit_t minimum, maximum;

+    char name[PPD_MAX_NAME];

+    int order;

+    char text[PPD_MAX_TEXT];

+    ppd_cptype_t type;

+};

+
Members

+

+
current 

+
Current value

+
maximum 

+
Maximum value

+
name[PPD_MAX_NAME] 

+
Parameter name

+
order 

+
Order (0 to N)

+
text[PPD_MAX_TEXT] 

+
Human-readable text

+
type 

+
Parameter type

+

+
ppd_emul_s

+
Emulators

+
struct ppd_emul_s {

+    char name[PPD_MAX_NAME];

+    char *start;

+    char *stop;

+};

+
Members

+

+
name[PPD_MAX_NAME] 

+
Emulator name

+
start 

+
Code to switch to this emulation

+
stop 

+
Code to stop this emulation

+

+
ppd_file_s

+
PPD File

+
struct ppd_file_s {

+    int accurate_screens;

+    int color_device;

+    ppd_cs_t colorspace;

+    ppd_const_t *consts;

+    int contone_only;

+    float custom_margins[4];

+    float custom_max[2];

+    float custom_min[2];

+    ppd_emul_t *emulations;

+    char **filters;

+    int flip_duplex;

+    char **fonts;

+    ppd_group_t *groups;

+    char *jcl_begin;

+    char *jcl_end;

+    char *jcl_ps;

+    int landscape;

+    char *lang_encoding;

+    char *lang_version;

+    int language_level;

+    int manual_copies;

+    char *manufacturer;

+    int model_number;

+    char *modelname;

+    char *nickname;

+    int num_consts;

+    int num_emulations;

+    int num_filters;

+    int num_fonts;

+    int num_groups;

+    int num_profiles;

+    int num_sizes;

+    char *patches;

+    char *pcfilename;

+    char *product;

+    ppd_profile_t *profiles;

+    char *protocols;

+    char *shortnickname;

+    ppd_size_t *sizes;

+    int throughput;

+    char *ttrasterizer;

+    int variable_sizes;

+};

+
Members

+

+
accurate_screens 

+
1 = supports accurate screens, 0 = not

+
color_device 

+
1 = color device, 0 = grayscale

+
colorspace 

+
Default colorspace

+
consts 

+
UI/Non-UI constraints

+
contone_only 

+
1 = continuous tone only, 0 = not

+
custom_margins[4] 

+
Margins around page

+
custom_max[2] 

+
Maximum variable page size

+
custom_min[2] 

+
Minimum variable page size

+
emulations 

+
Emulations and the code to invoke them

+
filters 

+
Filter strings...

+
flip_duplex  DEPRECATED 

+
1 = Flip page for back sides 

+
fonts 

+
Pre-loaded fonts

+
groups 

+
UI groups

+
jcl_begin 

+
Start JCL commands

+
jcl_end 

+
End JCL commands

+
jcl_ps 

+
Enter PostScript interpreter

+
landscape 

+
-90 or 90

+
lang_encoding 

+
Language encoding

+
lang_version 

+
Language version (English, Spanish, etc.)

+
language_level 

+
Language level of device

+
manual_copies 

+
1 = Copies done manually, 0 = hardware

+
manufacturer 

+
Manufacturer name

+
model_number 

+
Device-specific model number

+
modelname 

+
Model name (general)

+
nickname 

+
Nickname (specific)

+
num_consts 

+
Number of UI/Non-UI constraints

+
num_emulations 

+
Number of emulations supported

+
num_filters 

+
Number of filters

+
num_fonts 

+
Number of pre-loaded fonts

+
num_groups 

+
Number of UI groups

+
num_profiles 

+
Number of sRGB color profiles

+
num_sizes 

+
Number of page sizes

+
patches 

+
Patch commands to be sent to printer

+
pcfilename  CUPS 1.1.19 

+
PCFileName string 

+
product 

+
Product name (from PS RIP/interpreter)

+
profiles 

+
sRGB color profiles

+
protocols  CUPS 1.1.19 

+
Protocols (BCP, TBCP) string 

+
shortnickname 

+
Short version of nickname

+
sizes 

+
Page sizes

+
throughput 

+
Pages per minute

+
ttrasterizer 

+
Truetype rasterizer

+
variable_sizes 

+
1 = supports variable sizes, 0 = doesn't

+

+
ppd_group_s

+
Groups

+
struct ppd_group_s {

+    char text[PPD_MAX_TEXT - PPD_MAX_NAME];

+    char name[PPD_MAX_NAME];

+    int num_options;

+    int num_subgroups;

+    ppd_option_t *options;

+    struct ppd_group_s *subgroups;

+};

+
Members

+

+
PPD_MAX_NAME] 

+
Human-readable group name

+
name[PPD_MAX_NAME]  CUPS 1.1.18 

+
Group name 

+
num_options 

+
Number of options

+
num_subgroups 

+
Number of sub-groups

+
options 

+
Options

+
subgroups 

+
Sub-groups (max depth = 1)

+

+
ppd_option_s

+
Options

+
struct ppd_option_s {

+    ppd_choice_t *choices;

+    char conflicted;

+    char defchoice[PPD_MAX_NAME];

+    char keyword[PPD_MAX_NAME];

+    int num_choices;

+    float order;

+    ppd_section_t section;

+    char text[PPD_MAX_TEXT];

+    ppd_ui_t ui;

+};

+
Members

+

+
choices 

+
Option choices

+
conflicted 

+
0 if no conflicts exist, 1 otherwise

+
defchoice[PPD_MAX_NAME] 

+
Default option choice

+
keyword[PPD_MAX_NAME] 

+
Option keyword name ("PageSize", etc.)

+
num_choices 

+
Number of option choices

+
order 

+
Order number

+
section 

+
Section for command

+
text[PPD_MAX_TEXT] 

+
Human-readable text

+
ui 

+
Type of UI option

+

+
ppd_profile_s

+
sRGB Color Profiles

+
struct ppd_profile_s {

+    float density;

+    float gamma;

+    float matrix[3][3];

+    char media_type[PPD_MAX_NAME];

+    char resolution[PPD_MAX_NAME];

+};

+
Members

+

+
density 

+
Ink density to use

+
gamma 

+
Gamma correction to use

+
matrix[3][3] 

+
Transform matrix

+
media_type[PPD_MAX_NAME] 

+
Media type or "-"

+
resolution[PPD_MAX_NAME] 

+
Resolution or "-"

+

+
ppd_size_s

+
Page Sizes

+
struct ppd_size_s {

+    float bottom;

+    float left;

+    float length;

+    int marked;

+    char name[PPD_MAX_NAME];

+    float right;

+    float top;

+    float width;

+};

+
Members

+

+
bottom 

+
Bottom printable margin in points

+
left 

+
Left printable margin in points

+
length 

+
Length of media in points

+
marked 

+
Page size selected?

+
name[PPD_MAX_NAME] 

+
Media size option

+
right 

+
Right printable margin in points

+
top 

+
Top printable margin in points

+
width 

+
Width of media in points

+

+
Unions

+
 CUPS 1.2 ppd_cplimit_u

+
Custom Parameter Limit 

+
union ppd_cplimit_u {

+    float custom_curve;

+    int custom_int;

+    float custom_invcurve;

+    int custom_passcode;

+    int custom_password;

+    float custom_points;

+    float custom_real;

+    int custom_string;

+};

+
Members

+

+
custom_curve 

+
Gamma value

+
custom_int 

+
Integer value

+
custom_invcurve 

+
Gamma value

+
custom_passcode 

+
Passcode length

+
custom_password 

+
Password length

+
custom_points 

+
Measurement value

+
custom_real 

+
Real value

+
custom_string 

+
String length

+

+
 CUPS 1.2 ppd_cpvalue_u

+
Custom Parameter Value 

+
union ppd_cpvalue_u {

+    float custom_curve;

+    int custom_int;

+    float custom_invcurve;

+    char *custom_passcode;

+    char *custom_password;

+    float custom_points;

+    float custom_real;

+    char *custom_string;

+};

+
Members

+

+
custom_curve 

+
Gamma value

+
custom_int 

+
Integer value

+
custom_invcurve 

+
Gamma value

+
custom_passcode 

+
Passcode value

+
custom_password 

+
Password value

+
custom_points 

+
Measurement value

+
custom_real 

+
Real value

+
custom_string 

+
String value

+

+
Constants

+
ppd_conform_e

+

+
Constants

+

+
PPD_CONFORM_RELAXED 

+
Relax whitespace and control char

+
PPD_CONFORM_STRICT 

+
Require strict conformance

+

+
 CUPS 1.2 ppd_cptype_e

+
Custom Parameter Type 

+
Constants

+

+
PPD_CUSTOM_CURVE 

+
Curve value for f(x) = x^value

+
PPD_CUSTOM_INT 

+
Integer number value

+
PPD_CUSTOM_INVCURVE 

+
Curve value for f(x) = x^(1/value)

+
PPD_CUSTOM_PASSCODE 

+
String of (hidden) numbers

+
PPD_CUSTOM_PASSWORD 

+
String of (hidden) characters

+
PPD_CUSTOM_POINTS 

+
Measurement value in points

+
PPD_CUSTOM_REAL 

+
Real number value

+
PPD_CUSTOM_STRING 

+
String of characters

+

+
ppd_cs_e

+
Colorspaces

+
Constants

+

+
PPD_CS_CMY 

+
CMY colorspace

+
PPD_CS_CMYK 

+
CMYK colorspace

+
PPD_CS_GRAY 

+
Grayscale colorspace

+
PPD_CS_N 

+
DeviceN colorspace

+
PPD_CS_RGB 

+
RGB colorspace

+
PPD_CS_RGBK 

+
RGBK (K = gray) colorspace

+

+
ppd_section_e

+
Order dependency sections

+
Constants

+

+
PPD_ORDER_ANY 

+
Option code can be anywhere in the file

+
PPD_ORDER_DOCUMENT 

+
... must be in the DocumentSetup section

+
PPD_ORDER_EXIT 

+
... must be sent prior to the document

+
PPD_ORDER_JCL 

+
... must be sent as a JCL command

+
PPD_ORDER_PAGE 

+
... must be in the PageSetup section

+
PPD_ORDER_PROLOG 

+
... must be in the Prolog section

+

+
ppd_status_e

+
Types and structures...

+
Constants

+

+
PPD_ALLOC_ERROR 

+
Memory allocation error

+
PPD_BAD_CUSTOM_PARAM 

+
Bad custom parameter

+
PPD_BAD_OPEN_GROUP 

+
Bad OpenGroup

+
PPD_BAD_OPEN_UI 

+
Bad OpenUI/JCLOpenUI

+
PPD_BAD_ORDER_DEPENDENCY 

+
Bad OrderDependency

+
PPD_BAD_UI_CONSTRAINTS 

+
Bad UIConstraints

+
PPD_FILE_OPEN_ERROR 

+
Unable to open PPD file

+
PPD_ILLEGAL_CHARACTER 

+
Illegal control character

+
PPD_ILLEGAL_MAIN_KEYWORD 

+
Illegal main keyword string

+
PPD_ILLEGAL_OPTION_KEYWORD 

+
Illegal option keyword string

+
PPD_ILLEGAL_TRANSLATION 

+
Illegal translation string

+
PPD_ILLEGAL_WHITESPACE 

+
Illegal whitespace character

+
PPD_INTERNAL_ERROR 

+
Internal error

+
PPD_LINE_TOO_LONG 

+
Line longer than 255 chars

+
PPD_MISSING_ASTERISK 

+
Missing asterisk in column 0

+
PPD_MISSING_PPDADOBE4 

+
Missing PPD-Adobe-4.x header

+
PPD_MISSING_VALUE 

+
Missing value string

+
PPD_NESTED_OPEN_GROUP 

+
OpenGroup without a CloseGroup first

+
PPD_NESTED_OPEN_UI 

+
OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first

+
PPD_NULL_FILE 

+
NULL PPD file pointer

+
PPD_OK 

+
OK

+

+
ppd_ui_e

+
UI Types

+
Constants

+

+
PPD_UI_BOOLEAN 

+
True or False option

+
PPD_UI_PICKMANY 

+
Pick zero or more from a list

+
PPD_UI_PICKONE 

+
Pick one from a list

+

+

 
 
diff --git a/doc/help/api-raster.html b/doc/help/api-raster.html
index 4ffde1100..f9010c933 100644
--- a/doc/help/api-raster.html
+++ b/doc/help/api-raster.html
@@ -2,869 +2,1099 @@
 
 
 
-	Raster API
-	
-	
-	
+Raster API
+
+
+
 
 
+

+
+
+
Raster API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/raster.h
Library-lcupsimage
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Programming: PPD API

+	References: CUPS PPD Specification

+
Contents

+
 
 
-
Introduction

+
Overview

+
+
The CUPS raster API provides a standard interface for reading and writing
+CUPS raster streams which are used for printing to raster printers. Because the
+raster format is updated from time to time, it is important to use this API to
+avoid incompatibilities with newer versions of CUPS.

+
+
CUPS raster files (application/vnd.cups-raster) consists of
+a stream of raster page descriptions produced by one of the RIP filters such as
+pstoraster, imagetoraster, or
+cgpdftoraster. CUPS raster files are referred to using the
+cups_raster_t type and are
+opened using the cupsRasterOpen
+function. For example, to read raster data from the standard input, open
+file descriptor 0:

+
+
+#include <cups/raster.h>>
+
+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+

 
-
The CUPS raster API provides a standard interface for reading
-and writing CUPS raster streams which are used for printing to
-raster printers. Because the raster format is updated from time
-to time, it is important to use this API to avoid
-incompatibilities with newer versions of CUPS.

+
Each page of data begins with a page dictionary structure called
+cups_page_header2_t. This
+structure contains the colorspace, bits per color, media size, media type,
+hardware resolution, and so forth used for the page. You read the page header
+using the
+cupsRasterReadHeader2
+function:

 
-
General Usage

+
+#include <cups/raster.h>>
 
-
The <cups/raster.h> header file must be
-included to use the cupsRaster functions.

+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+cups_page_header2_t header;
 
-
Programs using these functions must be linked to the CUPS
-imaging library: libcupsimage.a,
-libcupsimage.so.2, libcupsimage.2.dylib,
-libcupsimage_s.a, or libcupsimage2.lib
-depending on the platform. The following command compiles
-myprogram.c using GCC and the CUPS imaging
-library:

+while (cupsRasterReadHeader2(ras, &header))
+{
+  /* setup this page */
 
-
-gcc -o myprogram myprogram.c -lcupsimage
+  /* read raster data */
+
+  /* finish this page */
+}
 

 
-
Compatibility

+
After the page dictionary comes the page data which is a full-resolution,
+possibly compressed bitmap representing the page in the printer's output
+colorspace. You read uncompressed raster data using the
+cupsRasterReadPixels
+function. A for loop is normally used to read the page one line
+at a time:

 
-
Unless otherwise specified, the raster API functions require
-CUPS 1.1 or higher.

+
+#include <cups/raster.h>>
 
-
Licensing

+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+cups_page_header2_t header;
+int page = 0;
+int y;
+char *buffer;
 
-
The CUPS raster API is provided under the terms of the GNU
-Library General Public License, with exceptions for MacOS X-based
-programs. Please see the CUPS license agreement for more
-information.

-
Contents

-
-
-
Enumerations

-
-
-
cups_adv_e

-
Description

-
AdvanceMedia attribute values
-
Values

-

-
-
-
-
-
-
-
-
NameDescription
CUPS_ADVANCE_FILE Advance the roll after this file
-
CUPS_ADVANCE_JOB Advance the roll after this job
-
CUPS_ADVANCE_NONE Never advance the roll
-
CUPS_ADVANCE_PAGE Advance the roll after this page
-
CUPS_ADVANCE_SET Advance the roll after this set
-

-
-
cups_bool_e

-
Description

-
Types...
-
Values

-

-
-
-
-
-
NameDescription
CUPS_FALSE Logical false
-
CUPS_TRUE Logical true
-

-
-
cups_cspace_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
CUPS_CSPACE_CIELab  CUPS 1.1.19 CIE Lab 
-
CUPS_CSPACE_CIEXYZ  CUPS 1.1.19 CIE XYZ 
-
CUPS_CSPACE_CMY Cyan, magenta, yellow
-
CUPS_CSPACE_CMYK Cyan, magenta, yellow, black
-
CUPS_CSPACE_GMCK Gold, magenta, yellow, black
-
CUPS_CSPACE_GMCS Gold, magenta, yellow, silver
-
CUPS_CSPACE_GOLD Gold foil
-
CUPS_CSPACE_ICC1  CUPS 1.1.19 ICC-based, 1 color 
-
CUPS_CSPACE_ICC2  CUPS 1.1.19 ICC-based, 2 colors 
-
CUPS_CSPACE_ICC3  CUPS 1.1.19 ICC-based, 3 colors 
-
CUPS_CSPACE_ICC4  CUPS 1.1.19 ICC-based, 4 colors 
-
CUPS_CSPACE_ICC5  CUPS 1.1.19 ICC-based, 5 colors 
-
CUPS_CSPACE_ICC6  CUPS 1.1.19 ICC-based, 6 colors 
-
CUPS_CSPACE_ICC7  CUPS 1.1.19 ICC-based, 7 colors 
-
CUPS_CSPACE_ICC8  CUPS 1.1.19 ICC-based, 8 colors 
-
CUPS_CSPACE_ICC9  CUPS 1.1.19 ICC-based, 9 colors 
-
CUPS_CSPACE_ICCA  CUPS 1.1.19 ICC-based, 10 colors 
-
CUPS_CSPACE_ICCB  CUPS 1.1.19 ICC-based, 11 colors 
-
CUPS_CSPACE_ICCC  CUPS 1.1.19 ICC-based, 12 colors 
-
CUPS_CSPACE_ICCD  CUPS 1.1.19 ICC-based, 13 colors 
-
CUPS_CSPACE_ICCE  CUPS 1.1.19 ICC-based, 14 colors 
-
CUPS_CSPACE_ICCF  CUPS 1.1.19 ICC-based, 15 colors 
-
CUPS_CSPACE_K Black
-
CUPS_CSPACE_KCMY Black, cyan, magenta, yellow
-
CUPS_CSPACE_KCMYcm Black, cyan, magenta, yellow, *
-light-cyan, light-magenta
-
CUPS_CSPACE_RGB Red, green, blue
-
CUPS_CSPACE_RGBA Red, green, blue, alpha
-
CUPS_CSPACE_RGBW  CUPS 1.2 Red, green, blue, white 
-
CUPS_CSPACE_SILVER Silver foil
-
CUPS_CSPACE_W Luminance
-
CUPS_CSPACE_WHITE White ink (as black)
-
CUPS_CSPACE_YMC Yellow, magenta, cyan
-
CUPS_CSPACE_YMCK Yellow, magenta, cyan, black
-

-
-
cups_cut_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
-
NameDescription
CUPS_CUT_FILE Cut the roll after this file
-
CUPS_CUT_JOB Cut the roll after this job
-
CUPS_CUT_NONE Never cut the roll
-
CUPS_CUT_PAGE Cut the roll after this page
-
CUPS_CUT_SET Cut the roll after this set
-

-
-
cups_edge_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
NameDescription
CUPS_EDGE_BOTTOM Leading edge is the bottom of the page
-
CUPS_EDGE_LEFT Leading edge is the left of the page
-
CUPS_EDGE_RIGHT Leading edge is the right of the page
-
CUPS_EDGE_TOP Leading edge is the top of the page
-

-
-
cups_jog_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
NameDescription
CUPS_JOG_FILE Move pages after this file
-
CUPS_JOG_JOB Move pages after this job
-
CUPS_JOG_NONE Never move pages
-
CUPS_JOG_SET Move pages after this set
-

-
-
cups_mode_e

-
Description

-

-
Values

-

-
-
-
-
-
-
NameDescription
CUPS_RASTER_READ Open stream for reading
-
CUPS_RASTER_WRITE Open stream for writing
-
CUPS_RASTER_WRITE_COMPRESSED  CUPS 1.3 Open stream for compressed writing 
-

-
-
cups_order_e

-
Description

-

-
Values

-

-
-
-
-
-
-
NameDescription
CUPS_ORDER_BANDED CCC MMM YYY KKK ...
-
CUPS_ORDER_CHUNKED CMYK CMYK CMYK ...
-
CUPS_ORDER_PLANAR CCC ... MMM ... YYY ... KKK ...
-

-
-
cups_orient_e

-
Description

-

-
Values

-

-
-
-
-
-
-
-
NameDescription
CUPS_ORIENT_0 Don't rotate the page
-
CUPS_ORIENT_180 Turn the page upside down
-
CUPS_ORIENT_270 Rotate the page clockwise
-
CUPS_ORIENT_90 Rotate the page counter-clockwise
-

-
-
Functions

-
-
-
cupsRasterClose()

-
Description

-
Close a raster stream.
-
Syntax

-

-void

-cupsRasterClose(
-    cups_raster_t * r);
-

-
Arguments

-

-
-
-
-
NameDescription
rStream to close

-
Returns

-
Nothing.

-
-
 CUPS 1.2 cupsRasterInterpretPPD()

-
Description

-
Interpret PPD commands to create a page header.
-
This function does not mark the options in the PPD using the "num_options"
-and "options" arguments.  Instead, mark the options prior to calling
-cupsRasterInterpretPPD() - this allows you to do per-page options
-without manipulating the options array.
-
The "func" argument specifies an optional callback function that is
+while (cupsRasterReadHeader2(ras, &header))
+{
+  /* setup this page */
+  page ++;
+  fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
+
+  /* allocate memory for 1 line */
+  buffer = malloc(header.cupsBytesPerLine);
+
+  /* read raster data */
+  for (y = 0; y < header.cupsHeight; y ++)
+  {
+    if (cupsRasterReadPixels(ras, buffer, header.cupsBytesPerLine) == 0)
+      break;
+
+    /* write raster data to printer */
+  }
+
+  /* finish this page */
+}
+

+
+
When you are done reading the raster data, call the
+cupsRasterClose function to free
+the memory used to read the raster file:

+
+
+cups_raster_t *ras;
+
+cupsRasterClose(ras);
+

+
Functions

+
cupsRasterClose

+
Close a raster stream.

+

+void cupsRasterClose (

+    cups_raster_t *r

+);

+
Parameters

+

+
r

+
Stream to close

+

+
 CUPS 1.2 cupsRasterInterpretPPD

+
Interpret PPD commands to create a page header.

+

+int cupsRasterInterpretPPD (

+    cups_page_header2_t *h,

+    ppd_file_t *ppd,

+    int num_options,

+    cups_option_t *options,

+    cups_interpret_cb_t func

+);

+
Parameters

+

+
h

+
Page header

+
ppd

+
PPD file

+
num_options

+
Number of options

+
options

+
Options

+
func

+
Optional page header callback

+

+
Return Value

+
0 on success, -1 on failure

+
Discussion

+
This function does not mark the options in the PPD using the "num_options"
+and "options" arguments.  Instead, mark the options with
+cupsMarkOptions and ppdMarkOption prior to calling
+cupsRasterInterpretPPD - this allows you to do per-page options
+without manipulating the options array.

+

+The "func" argument specifies an optional callback function that is
 called prior to the computation of the final raster data.  The function
-can make changes to the cups_page_header2_t data as needed to use a
+can make changes to the cups_page_header2_t data as needed to use a
 supported raster format and then returns 0 on success and -1 if the
 requested attributes cannot be supported.
-
cupsRasterInterpretPPD() supports a subset of the PostScript language.
-Currently only the [, ], <<, >>, {, }, cleartomark, copy, dup, index,
-pop, roll, setpagedevice, and stopped operators are supported.
-
-
-
Syntax

-

-int

-cupsRasterInterpretPPD(
-    cups_page_header2_t * h,
-    ppd_file_t * ppd,
-    int num_options,
-    cups_option_t * options,
-    cups_interpret_cb_t func);
-

-
Arguments

-

-
-
-
-
-
-
-
-
NameDescription
hPage header
ppdPPD file
num_optionsNumber of options
optionsOptions
funcOptional page header callback

-
Returns

-
0 on success, -1 on failure

-
-
cupsRasterOpen()

-
Description

-
Open a raster stream.
-
Syntax

-

-cups_raster_t *

-cupsRasterOpen(
-    int fd,
-    cups_mode_t mode);
-

-
Arguments

-

-
-
-
-
-
NameDescription
fdFile descriptor
modeMode

-
Returns

-
New stream

-
-
cupsRasterReadHeader()

-
Description

-
Read a raster page header and store it in a
-V1 page header structure.
-
Syntax

-

-unsigned

-cupsRasterReadHeader(
-    cups_raster_t * r,
-    cups_page_header_t * h);
-

-
Arguments

-

-
-
-
-
-
NameDescription
rRaster stream
hPointer to header data

-
Returns

-
1 on success, 0 on fail

-
-
 CUPS 1.2 cupsRasterReadHeader2()

-
Description

-
Read a raster page header and store it in a
-V2 page header structure.
-
-
-
Syntax

-

-unsigned

-cupsRasterReadHeader2(
-    cups_raster_t * r,
-    cups_page_header2_t * h);
-

-
Arguments

-

-
-
-
-
-
NameDescription
rRaster stream
hPointer to header data

-
Returns

-
1 on success, 0 on fail

-
-
cupsRasterReadPixels()

-
Description

-
Read raster pixels.
-
Syntax

-

-unsigned

-cupsRasterReadPixels(
-    cups_raster_t * r,
-    unsigned char * p,
-    unsigned len);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
rRaster stream
pPointer to pixel buffer
lenNumber of bytes to read

-
Returns

-
Number of bytes read

-
-
cupsRasterWriteHeader()

-
Description

-
Write a raster page header from a V1 page
-header structure.
-
Syntax

-

-unsigned

-cupsRasterWriteHeader(
-    cups_raster_t * r,
-    cups_page_header_t * h);
-

-
Arguments

-

-
-
-
-
-
NameDescription
rRaster stream
hRaster page header

-
Returns

-
1 on success, 0 on failure

-
-
 CUPS 1.2 cupsRasterWriteHeader2()

-
Description

-
Write a raster page header from a V2 page
-header structure.
-
-
-
Syntax

-

-unsigned

-cupsRasterWriteHeader2(
-    cups_raster_t * r,
-    cups_page_header2_t * h);
-

-
Arguments

-

-
-
-
-
-
NameDescription
rRaster stream
hRaster page header

-
Returns

-
1 on success, 0 on failure

-
-
cupsRasterWritePixels()

-
Description

-
Write raster pixels.
-
Syntax

-

-unsigned

-cupsRasterWritePixels(
-    cups_raster_t * r,
-    unsigned char * p,
-    unsigned len);
-

-
Arguments

-

-
-
-
-
-
-
NameDescription
rRaster stream
pBytes to write
lenNumber of bytes to write

-
Returns

-
Number of bytes written

-
-
Structures

-
-
-
 CUPS 1.2 cups_page_header2_s

-
Description

-
Version 2 Page Header 
-
Definition

-

-struct cups_page_header2_s

-{

-  unsigned AdvanceDistance;

-  cups_adv_t AdvanceMedia;

-  cups_bool_t Collate;

-  cups_cut_t CutMedia;

-  cups_bool_t Duplex;

-  unsigned HWResolution[2];

-  unsigned ImagingBoundingBox[4];

-  cups_bool_t InsertSheet;

-  cups_jog_t Jog;

-  cups_edge_t LeadingEdge;

-  cups_bool_t ManualFeed;

-  unsigned Margins[2];

-  char MediaClass[64];

-  char MediaColor[64];

-  unsigned MediaPosition;

-  char MediaType[64];

-  unsigned MediaWeight;

-  cups_bool_t MirrorPrint;

-  cups_bool_t NegativePrint;

-  unsigned NumCopies;

-  cups_orient_t Orientation;

-  cups_bool_t OutputFaceUp;

-  char OutputType[64];

-  unsigned PageSize[2];

-  cups_bool_t Separations;

-  cups_bool_t TraySwitch;

-  cups_bool_t Tumble;

-  unsigned cupsBitsPerColor;

-  unsigned cupsBitsPerPixel;

-  float cupsBorderlessScalingFactor;

-  unsigned cupsBytesPerLine;

-  cups_order_t cupsColorOrder;

-  cups_cspace_t cupsColorSpace;

-  unsigned cupsCompression;

-  unsigned cupsHeight;

-  float cupsImagingBBox[4];

-  unsigned cupsInteger[16];

-  char cupsMarkerType[64];

-  unsigned cupsMediaType;

-  unsigned cupsNumColors;

-  char cupsPageSizeName[64];

-  float cupsPageSize[2];

-  float cupsReal[16];

-  char cupsRenderingIntent[64];

-  unsigned cupsRowCount;

-  unsigned cupsRowFeed;

-  unsigned cupsRowStep;

-  char cupsString[16][64];

-  unsigned cupsWidth;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
AdvanceDistance AdvanceDistance value in points
-
AdvanceMedia AdvanceMedia value (see above)
-
Collate Collated copies value
-
CutMedia CutMedia value (see above)
-
Duplex Duplexed (double-sided) value
-
HWResolution[2] Resolution in dots-per-inch
-
ImagingBoundingBox[4] Pixel region that is painted (points)
-
InsertSheet InsertSheet value
-
Jog Jog value (see above)
-
LeadingEdge LeadingEdge value (see above)
-
ManualFeed ManualFeed value
-
Margins[2] Lower-lefthand margins in points
-
MediaClass[64] MediaClass string
-
MediaColor[64] MediaColor string
-
MediaPosition MediaPosition value
-
MediaType[64] MediaType string
-
MediaWeight MediaWeight value in grams/m^2
-
MirrorPrint MirrorPrint value
-
NegativePrint NegativePrint value
-
NumCopies Number of copies to produce
-
Orientation Orientation value (see above)
-
OutputFaceUp OutputFaceUp value
-
OutputType[64] OutputType string
-
PageSize[2] Width and length of page in points
-
Separations Separations value
-
TraySwitch TraySwitch value
-
Tumble Tumble value
-
cupsBitsPerColor Number of bits for each color
-
cupsBitsPerPixel Number of bits for each pixel
-
cupsBorderlessScalingFactor  CUPS 1.2 Scaling that was applied to page data 
-
cupsBytesPerLine Number of bytes per line
-
cupsColorOrder Order of colors
-
cupsColorSpace True colorspace
-
cupsCompression Device compression to use
-
cupsHeight Height of page image in pixels
-
cupsImagingBBox[4]  CUPS 1.2 Floating point ImagingBoundingBox *
-(scaling factor not applied) 
-
cupsInteger[16]  CUPS 1.2 User-defined integer values 
-
cupsMarkerType[64]  CUPS 1.2 Ink/toner type 
-
cupsMediaType Media type code
-
cupsNumColors  CUPS 1.2 Number of colors 
-
cupsPageSizeName[64]  CUPS 1.2 PageSize name 
-
cupsPageSize[2]  CUPS 1.2 Floating point PageSize (scaling *
-factor not applied) 
-
cupsReal[16]  CUPS 1.2 User-defined floating-point values 
-
cupsRenderingIntent[64]  CUPS 1.2 Color rendering intent 
-
cupsRowCount Rows per band
-
cupsRowFeed Feed between bands
-
cupsRowStep Spacing between lines
-
cupsString[16][64]  CUPS 1.2 User-defined string values 
-
cupsWidth Width of page image in pixels
-

-
-
cups_page_header_s

-
Description

-
Version 1 Page Header
-
Definition

-

-struct cups_page_header_s

-{

-  unsigned AdvanceDistance;

-  cups_adv_t AdvanceMedia;

-  cups_bool_t Collate;

-  cups_cut_t CutMedia;

-  cups_bool_t Duplex;

-  unsigned HWResolution[2];

-  unsigned ImagingBoundingBox[4];

-  cups_bool_t InsertSheet;

-  cups_jog_t Jog;

-  cups_edge_t LeadingEdge;

-  cups_bool_t ManualFeed;

-  unsigned Margins[2];

-  char MediaClass[64];

-  char MediaColor[64];

-  unsigned MediaPosition;

-  char MediaType[64];

-  unsigned MediaWeight;

-  cups_bool_t MirrorPrint;

-  cups_bool_t NegativePrint;

-  unsigned NumCopies;

-  cups_orient_t Orientation;

-  cups_bool_t OutputFaceUp;

-  char OutputType[64];

-  unsigned PageSize[2];

-  cups_bool_t Separations;

-  cups_bool_t TraySwitch;

-  cups_bool_t Tumble;

-  unsigned cupsBitsPerColor;

-  unsigned cupsBitsPerPixel;

-  unsigned cupsBytesPerLine;

-  cups_order_t cupsColorOrder;

-  cups_cspace_t cupsColorSpace;

-  unsigned cupsCompression;

-  unsigned cupsHeight;

-  unsigned cupsMediaType;

-  unsigned cupsRowCount;

-  unsigned cupsRowFeed;

-  unsigned cupsRowStep;

-  unsigned cupsWidth;

-};

-
Members

-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
NameDescription
AdvanceDistance AdvanceDistance value in points
-
AdvanceMedia AdvanceMedia value (see above)
-
Collate Collated copies value
-
CutMedia CutMedia value (see above)
-
Duplex Duplexed (double-sided) value
-
HWResolution[2] Resolution in dots-per-inch
-
ImagingBoundingBox[4] Pixel region that is painted (points)
-
InsertSheet InsertSheet value
-
Jog Jog value (see above)
-
LeadingEdge LeadingEdge value (see above)
-
ManualFeed ManualFeed value
-
Margins[2] Lower-lefthand margins in points
-
MediaClass[64] MediaClass string
-
MediaColor[64] MediaColor string
-
MediaPosition MediaPosition value
-
MediaType[64] MediaType string
-
MediaWeight MediaWeight value in grams/m^2
-
MirrorPrint MirrorPrint value
-
NegativePrint NegativePrint value
-
NumCopies Number of copies to produce
-
Orientation Orientation value (see above)
-
OutputFaceUp OutputFaceUp value
-
OutputType[64] OutputType string
-
PageSize[2] Width and length of page in points
-
Separations Separations value
-
TraySwitch TraySwitch value
-
Tumble Tumble value
-
cupsBitsPerColor Number of bits for each color
-
cupsBitsPerPixel Number of bits for each pixel
-
cupsBytesPerLine Number of bytes per line
-
cupsColorOrder Order of colors
-
cupsColorSpace True colorspace
-
cupsCompression Device compression to use
-
cupsHeight Height of page image in pixels
-
cupsMediaType Media type code
-
cupsRowCount Rows per band
-
cupsRowFeed Feed between bands
-
cupsRowStep Spacing between lines
-
cupsWidth Width of page image in pixels
-

-
-
Types

-
-
-
cups_interpret_cb_t

-
Description

-
Prototypes...
-
Definition

-

-typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
-

-
-
 CUPS 1.2 cups_page_header2_t

-
Description

-
Version 2 Page Header 
-
Definition

-

-typedef struct cups_page_header2_s cups_page_header2_t;
-

-
-
cups_page_header_t

-
Description

-
Version 1 Page Header
-
Definition

-

-typedef struct cups_page_header_s cups_page_header_t;
-

-
-
cups_raster_t

-
Description

-
Raster stream data
-
Definition

-

+
+cupsRasterInterpretPPD supports a subset of the PostScript language.
+Currently only the [, ], <<, >>, {,
+}, cleartomark, copy, dup, index,
+pop, roll, setpagedevice, and stopped operators
+are supported.
+
+

+
cupsRasterOpen

+
Open a raster stream.

+

+cups_raster_t *cupsRasterOpen (

+    int fd,

+    cups_mode_t mode

+);

+
Parameters

+

+
fd

+
File descriptor

+
mode

+
Mode

+

+
Return Value

+
New stream

+
cupsRasterReadHeader

+
Read a raster page header and store it in a
+V1 page header structure.

+

+unsigned cupsRasterReadHeader (

+    cups_raster_t *r,

+    cups_page_header_t *h

+);

+
Parameters

+

+
r

+
Raster stream

+
h

+
Pointer to header data

+

+
Return Value

+
1 on success, 0 on fail

+
 CUPS 1.2 cupsRasterReadHeader2

+
Read a raster page header and store it in a
+V2 page header structure.

+

+unsigned cupsRasterReadHeader2 (

+    cups_raster_t *r,

+    cups_page_header2_t *h

+);

+
Parameters

+

+
r

+
Raster stream

+
h

+
Pointer to header data

+

+
Return Value

+
1 on success, 0 on fail

+
cupsRasterReadPixels

+
Read raster pixels.

+

+unsigned cupsRasterReadPixels (

+    cups_raster_t *r,

+    unsigned char *p,

+    unsigned len

+);

+
Parameters

+

+
r

+
Raster stream

+
p

+
Pointer to pixel buffer

+
len

+
Number of bytes to read

+

+
Return Value

+
Number of bytes read

+
cupsRasterWriteHeader

+
Write a raster page header from a V1 page
+header structure.

+

+unsigned cupsRasterWriteHeader (

+    cups_raster_t *r,

+    cups_page_header_t *h

+);

+
Parameters

+

+
r

+
Raster stream

+
h

+
Raster page header

+

+
Return Value

+
1 on success, 0 on failure

+
 CUPS 1.2 cupsRasterWriteHeader2

+
Write a raster page header from a V2 page
+header structure.

+

+unsigned cupsRasterWriteHeader2 (

+    cups_raster_t *r,

+    cups_page_header2_t *h

+);

+
Parameters

+

+
r

+
Raster stream

+
h

+
Raster page header

+

+
Return Value

+
1 on success, 0 on failure

+
cupsRasterWritePixels

+
Write raster pixels.

+

+unsigned cupsRasterWritePixels (

+    cups_raster_t *r,

+    unsigned char *p,

+    unsigned len

+);

+
Parameters

+

+
r

+
Raster stream

+
p

+
Bytes to write

+
len

+
Number of bytes to write

+

+
Return Value

+
Number of bytes written

+
Data Types

+
cups_interpret_cb_t

+
cupsRasterInterpretPPD callback function

+

+typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
+

+
cups_mode_t

+
cupsRasterOpen modes

+

+typedef enum cups_mode_e cups_mode_t;
+

+
 CUPS 1.2 cups_page_header2_t

+
Version 2 page header 

+

+typedef struct cups_page_header2_s cups_page_header2_t;
+

+
cups_page_header_t

+
Version 1 page header

+

+typedef struct cups_page_header_s cups_page_header_t;
+

+
cups_raster_t

+
Raster stream data

+

 typedef struct _cups_raster_s cups_raster_t;
-

+

+
Structures

+
 CUPS 1.2 cups_page_header2_s

+
Version 2 page header 

+
struct cups_page_header2_s {

+    unsigned AdvanceDistance;

+    cups_adv_t AdvanceMedia;

+    cups_bool_t Collate;

+    cups_cut_t CutMedia;

+    cups_bool_t Duplex;

+    unsigned HWResolution[2];

+    unsigned ImagingBoundingBox[4];

+    cups_bool_t InsertSheet;

+    cups_jog_t Jog;

+    cups_edge_t LeadingEdge;

+    cups_bool_t ManualFeed;

+    unsigned Margins[2];

+    char MediaClass[64];

+    char MediaColor[64];

+    unsigned MediaPosition;

+    char MediaType[64];

+    unsigned MediaWeight;

+    cups_bool_t MirrorPrint;

+    cups_bool_t NegativePrint;

+    unsigned NumCopies;

+    cups_orient_t Orientation;

+    cups_bool_t OutputFaceUp;

+    char OutputType[64];

+    unsigned PageSize[2];

+    cups_bool_t Separations;

+    cups_bool_t TraySwitch;

+    cups_bool_t Tumble;

+    unsigned cupsBitsPerColor;

+    unsigned cupsBitsPerPixel;

+    float cupsBorderlessScalingFactor;

+    unsigned cupsBytesPerLine;

+    cups_order_t cupsColorOrder;

+    cups_cspace_t cupsColorSpace;

+    unsigned cupsCompression;

+    unsigned cupsHeight;

+    float cupsImagingBBox[4];

+    unsigned cupsInteger[16];

+    char cupsMarkerType[64];

+    unsigned cupsMediaType;

+    unsigned cupsNumColors;

+    char cupsPageSizeName[64];

+    float cupsPageSize[2];

+    float cupsReal[16];

+    char cupsRenderingIntent[64];

+    unsigned cupsRowCount;

+    unsigned cupsRowFeed;

+    unsigned cupsRowStep;

+    char cupsString[16][64];

+    unsigned cupsWidth;

+};

+
Members

+

+
AdvanceDistance 

+
AdvanceDistance value in points

+
AdvanceMedia 

+
AdvanceMedia value (see above)

+
Collate 

+
Collated copies value

+
CutMedia 

+
CutMedia value (see above)

+
Duplex 

+
Duplexed (double-sided) value

+
HWResolution[2] 

+
Resolution in dots-per-inch

+
ImagingBoundingBox[4] 

+
Pixel region that is painted (points)

+
InsertSheet 

+
InsertSheet value

+
Jog 

+
Jog value (see above)

+
LeadingEdge 

+
LeadingEdge value (see above)

+
ManualFeed 

+
ManualFeed value

+
Margins[2] 

+
Lower-lefthand margins in points

+
MediaClass[64] 

+
MediaClass string

+
MediaColor[64] 

+
MediaColor string

+
MediaPosition 

+
MediaPosition value

+
MediaType[64] 

+
MediaType string

+
MediaWeight 

+
MediaWeight value in grams/m^2

+
MirrorPrint 

+
MirrorPrint value

+
NegativePrint 

+
NegativePrint value

+
NumCopies 

+
Number of copies to produce

+
Orientation 

+
Orientation value (see above)

+
OutputFaceUp 

+
OutputFaceUp value

+
OutputType[64] 

+
OutputType string

+
PageSize[2] 

+
Width and length of page in points

+
Separations 

+
Separations value

+
TraySwitch 

+
TraySwitch value

+
Tumble 

+
Tumble value

+
cupsBitsPerColor 

+
Number of bits for each color

+
cupsBitsPerPixel 

+
Number of bits for each pixel

+
cupsBorderlessScalingFactor  CUPS 1.2 

+
Scaling that was applied to page data 

+
cupsBytesPerLine 

+
Number of bytes per line

+
cupsColorOrder 

+
Order of colors

+
cupsColorSpace 

+
True colorspace

+
cupsCompression 

+
Device compression to use

+
cupsHeight 

+
Height of page image in pixels

+
cupsImagingBBox[4]  CUPS 1.2 

+
Floating point ImagingBoundingBox *
+(scaling factor not applied) 

+
cupsInteger[16]  CUPS 1.2 

+
User-defined integer values 

+
cupsMarkerType[64]  CUPS 1.2 

+
Ink/toner type 

+
cupsMediaType 

+
Media type code

+
cupsNumColors  CUPS 1.2 

+
Number of colors 

+
cupsPageSizeName[64]  CUPS 1.2 

+
PageSize name 

+
cupsPageSize[2]  CUPS 1.2 

+
Floating point PageSize (scaling *
+factor not applied) 

+
cupsReal[16]  CUPS 1.2 

+
User-defined floating-point values 

+
cupsRenderingIntent[64]  CUPS 1.2 

+
Color rendering intent 

+
cupsRowCount 

+
Rows per band

+
cupsRowFeed 

+
Feed between bands

+
cupsRowStep 

+
Spacing between lines

+
cupsString[16][64]  CUPS 1.2 

+
User-defined string values 

+
cupsWidth 

+
Width of page image in pixels

+

+
cups_page_header_s

+
Version 1 page header

+
struct cups_page_header_s {

+    unsigned AdvanceDistance;

+    cups_adv_t AdvanceMedia;

+    cups_bool_t Collate;

+    cups_cut_t CutMedia;

+    cups_bool_t Duplex;

+    unsigned HWResolution[2];

+    unsigned ImagingBoundingBox[4];

+    cups_bool_t InsertSheet;

+    cups_jog_t Jog;

+    cups_edge_t LeadingEdge;

+    cups_bool_t ManualFeed;

+    unsigned Margins[2];

+    char MediaClass[64];

+    char MediaColor[64];

+    unsigned MediaPosition;

+    char MediaType[64];

+    unsigned MediaWeight;

+    cups_bool_t MirrorPrint;

+    cups_bool_t NegativePrint;

+    unsigned NumCopies;

+    cups_orient_t Orientation;

+    cups_bool_t OutputFaceUp;

+    char OutputType[64];

+    unsigned PageSize[2];

+    cups_bool_t Separations;

+    cups_bool_t TraySwitch;

+    cups_bool_t Tumble;

+    unsigned cupsBitsPerColor;

+    unsigned cupsBitsPerPixel;

+    unsigned cupsBytesPerLine;

+    cups_order_t cupsColorOrder;

+    cups_cspace_t cupsColorSpace;

+    unsigned cupsCompression;

+    unsigned cupsHeight;

+    unsigned cupsMediaType;

+    unsigned cupsRowCount;

+    unsigned cupsRowFeed;

+    unsigned cupsRowStep;

+    unsigned cupsWidth;

+};

+
Members

+

+
AdvanceDistance 

+
AdvanceDistance value in points

+
AdvanceMedia 

+
AdvanceMedia value (see above)

+
Collate 

+
Collated copies value

+
CutMedia 

+
CutMedia value (see above)

+
Duplex 

+
Duplexed (double-sided) value

+
HWResolution[2] 

+
Resolution in dots-per-inch

+
ImagingBoundingBox[4] 

+
Pixel region that is painted (points)

+
InsertSheet 

+
InsertSheet value

+
Jog 

+
Jog value (see above)

+
LeadingEdge 

+
LeadingEdge value (see above)

+
ManualFeed 

+
ManualFeed value

+
Margins[2] 

+
Lower-lefthand margins in points

+
MediaClass[64] 

+
MediaClass string

+
MediaColor[64] 

+
MediaColor string

+
MediaPosition 

+
MediaPosition value

+
MediaType[64] 

+
MediaType string

+
MediaWeight 

+
MediaWeight value in grams/m^2

+
MirrorPrint 

+
MirrorPrint value

+
NegativePrint 

+
NegativePrint value

+
NumCopies 

+
Number of copies to produce

+
Orientation 

+
Orientation value (see above)

+
OutputFaceUp 

+
OutputFaceUp value

+
OutputType[64] 

+
OutputType string

+
PageSize[2] 

+
Width and length of page in points

+
Separations 

+
Separations value

+
TraySwitch 

+
TraySwitch value

+
Tumble 

+
Tumble value

+
cupsBitsPerColor 

+
Number of bits for each color

+
cupsBitsPerPixel 

+
Number of bits for each pixel

+
cupsBytesPerLine 

+
Number of bytes per line

+
cupsColorOrder 

+
Order of colors

+
cupsColorSpace 

+
True colorspace

+
cupsCompression 

+
Device compression to use

+
cupsHeight 

+
Height of page image in pixels

+
cupsMediaType 

+
Media type code

+
cupsRowCount 

+
Rows per band

+
cupsRowFeed 

+
Feed between bands

+
cupsRowStep 

+
Spacing between lines

+
cupsWidth 

+
Width of page image in pixels

+

+
Constants

+
cups_adv_e

+
AdvanceMedia attribute values

+
Constants

+

+
CUPS_ADVANCE_FILE 

+
Advance the roll after this file

+
CUPS_ADVANCE_JOB 

+
Advance the roll after this job

+
CUPS_ADVANCE_NONE 

+
Never advance the roll

+
CUPS_ADVANCE_PAGE 

+
Advance the roll after this page

+
CUPS_ADVANCE_SET 

+
Advance the roll after this set

+

+
cups_bool_e

+
Types...

+
Constants

+

+
CUPS_FALSE 

+
Logical false

+
CUPS_TRUE 

+
Logical true

+

+
cups_cspace_e

+

+
Constants

+

+
CUPS_CSPACE_CIELab  CUPS 1.1.19 

+
CIE Lab 

+
CUPS_CSPACE_CIEXYZ  CUPS 1.1.19 

+
CIE XYZ 

+
CUPS_CSPACE_CMY 

+
Cyan, magenta, yellow

+
CUPS_CSPACE_CMYK 

+
Cyan, magenta, yellow, black

+
CUPS_CSPACE_GMCK 

+
Gold, magenta, yellow, black

+
CUPS_CSPACE_GMCS 

+
Gold, magenta, yellow, silver

+
CUPS_CSPACE_GOLD 

+
Gold foil

+
CUPS_CSPACE_ICC1  CUPS 1.1.19 

+
ICC-based, 1 color 

+
CUPS_CSPACE_ICC2  CUPS 1.1.19 

+
ICC-based, 2 colors 

+
CUPS_CSPACE_ICC3  CUPS 1.1.19 

+
ICC-based, 3 colors 

+
CUPS_CSPACE_ICC4  CUPS 1.1.19 

+
ICC-based, 4 colors 

+
CUPS_CSPACE_ICC5  CUPS 1.1.19 

+
ICC-based, 5 colors 

+
CUPS_CSPACE_ICC6  CUPS 1.1.19 

+
ICC-based, 6 colors 

+
CUPS_CSPACE_ICC7  CUPS 1.1.19 

+
ICC-based, 7 colors 

+
CUPS_CSPACE_ICC8  CUPS 1.1.19 

+
ICC-based, 8 colors 

+
CUPS_CSPACE_ICC9  CUPS 1.1.19 

+
ICC-based, 9 colors 

+
CUPS_CSPACE_ICCA  CUPS 1.1.19 

+
ICC-based, 10 colors 

+
CUPS_CSPACE_ICCB  CUPS 1.1.19 

+
ICC-based, 11 colors 

+
CUPS_CSPACE_ICCC  CUPS 1.1.19 

+
ICC-based, 12 colors 

+
CUPS_CSPACE_ICCD  CUPS 1.1.19 

+
ICC-based, 13 colors 

+
CUPS_CSPACE_ICCE  CUPS 1.1.19 

+
ICC-based, 14 colors 

+
CUPS_CSPACE_ICCF  CUPS 1.1.19 

+
ICC-based, 15 colors 

+
CUPS_CSPACE_K 

+
Black

+
CUPS_CSPACE_KCMY 

+
Black, cyan, magenta, yellow

+
CUPS_CSPACE_KCMYcm 

+
Black, cyan, magenta, yellow, *
+light-cyan, light-magenta

+
CUPS_CSPACE_RGB 

+
Red, green, blue

+
CUPS_CSPACE_RGBA 

+
Red, green, blue, alpha

+
CUPS_CSPACE_RGBW  CUPS 1.2 

+
Red, green, blue, white 

+
CUPS_CSPACE_SILVER 

+
Silver foil

+
CUPS_CSPACE_W 

+
Luminance

+
CUPS_CSPACE_WHITE 

+
White ink (as black)

+
CUPS_CSPACE_YMC 

+
Yellow, magenta, cyan

+
CUPS_CSPACE_YMCK 

+
Yellow, magenta, cyan, black

+

+
cups_cut_e

+

+
Constants

+

+
CUPS_CUT_FILE 

+
Cut the roll after this file

+
CUPS_CUT_JOB 

+
Cut the roll after this job

+
CUPS_CUT_NONE 

+
Never cut the roll

+
CUPS_CUT_PAGE 

+
Cut the roll after this page

+
CUPS_CUT_SET 

+
Cut the roll after this set

+

+
cups_edge_e

+

+
Constants

+

+
CUPS_EDGE_BOTTOM 

+
Leading edge is the bottom of the page

+
CUPS_EDGE_LEFT 

+
Leading edge is the left of the page

+
CUPS_EDGE_RIGHT 

+
Leading edge is the right of the page

+
CUPS_EDGE_TOP 

+
Leading edge is the top of the page

+

+
cups_jog_e

+

+
Constants

+

+
CUPS_JOG_FILE 

+
Move pages after this file

+
CUPS_JOG_JOB 

+
Move pages after this job

+
CUPS_JOG_NONE 

+
Never move pages

+
CUPS_JOG_SET 

+
Move pages after this set

+

+
cups_mode_e

+

+
Constants

+

+
CUPS_RASTER_READ 

+
Open stream for reading

+
CUPS_RASTER_WRITE 

+
Open stream for writing

+
CUPS_RASTER_WRITE_COMPRESSED  CUPS 1.3 

+
Open stream for compressed writing 

+

+
cups_order_e

+
cupsColorOrder attribute values

+
Constants

+

+
CUPS_ORDER_BANDED 

+
CCC MMM YYY KKK ...

+
CUPS_ORDER_CHUNKED 

+
CMYK CMYK CMYK ...

+
CUPS_ORDER_PLANAR 

+
CCC ... MMM ... YYY ... KKK ...

+

+
cups_orient_e

+

+
Constants

+

+
CUPS_ORIENT_0 

+
Don't rotate the page

+
CUPS_ORIENT_180 

+
Turn the page upside down

+
CUPS_ORIENT_270 

+
Rotate the page clockwise

+
CUPS_ORIENT_90 

+
Rotate the page counter-clockwise

+

+

 
 
diff --git a/doc/help/policies.html b/doc/help/policies.html
index 732c91960..37ab489ef 100644
--- a/doc/help/policies.html
+++ b/doc/help/policies.html
@@ -49,7 +49,7 @@ the cupsd.conf file from the console, make sure to restart the cupsd process before
 trying to use the new policy.

 
-
+
 Listing 1: Default Operation Policy
 
  1    <Policy default>
@@ -106,14 +106,14 @@ trying to use the new policy.

 
The policy definition starts with an opening Policy
 directive:

 
-
+
  1    <Policy default>
 

 
 
The first Limit subsection defines the rules for IPP
 job operations:

 
-
+
  3      <Limit Send-Document Send-URI Hold-Job Release-Job
       Restart-Job Purge-Jobs Set-Job-Attributes
       Create-Job-Subscription Renew-Subscription
@@ -146,7 +146,7 @@ request. The administrative operations starting on line 9,
 however, do use the AuthType directive, and so
 administrative operations need to be authenticated:

 
-
+
  9      <Limit CUPS-Add-Printer CUPS-Delete-Printer CUPS-Add-Class
       CUPS-Delete-Class CUPS-Set-Default>
 10        AuthType Default
@@ -180,7 +180,7 @@ more easily edit their policy without disturbing the rest. Like
 the rest of the job operations, we want the job's owner
 ("@OWNER") or an administrator ("@SYSTEM") to do it:

 
-
+
 16      <Limit Cancel-Job CUPS-Authenticate-Job>
 17        Require user @OWNER @SYSTEM
 18        Order deny,allow
@@ -193,7 +193,7 @@ this subsection for any operation you don't list specifically in
 the policy. In this case, all other operations are allowed
 without a username or authentication:

 
-
+
 21      <Limit All>
 22        Order deny,allow
 23      </Limit>
@@ -521,7 +521,7 @@ change you'll make is to give the policy a new name. Policy names
 can use the same characters as a printer name, specifically all
 printable characters except space, slash (/), and pound (#):

 
-
+
 <Policy mypolicy>
 

 
@@ -530,7 +530,7 @@ policy. For example, if you want to allow any user to cancel any
 other users' jobs, you can change the Cancel-Job limits
 to:

 
-
+
 <Limit Cancel-Job>
   Order deny,allow
 </Limit>
@@ -613,7 +613,7 @@ the lab technicians, who are members of a special UNIX group for
 that lab called "lab999", to do job, printer, and subscription
 management operations.

 
-
+
 Listing 2: Operation Policy for a Lab
 
  1    <Policy lab999>
@@ -664,7 +664,7 @@ directive in the cupsd.conf file. For example, add the
 following line to the cupsd.conf file to use the
 "lab999" policy from the previous section:

 
-
+
 DefaultPolicy lab999
 

 
diff --git a/doc/help/spec-ipp.html b/doc/help/spec-ipp.html
index 704e967ba..0d768c9fb 100644
--- a/doc/help/spec-ipp.html
+++ b/doc/help/spec-ipp.html
@@ -11,7 +11,7 @@
 
   CUPS IPP specification for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2007 by Easy Software Products.
 
   These coded instructions, statements, and computer programs are the
@@ -2459,6 +2459,101 @@ the system.
 
The job-sheets-supported attribute specifies the available banner files.
 There will always be at least one banner file available called "none".
 
+
marker-change-time (integer)

+
+
The marker-change-time attribute specifies the printer-up-time value when
+the last change to the marker-colors, marker-levels, marker-names, or
+marker-types attributes was made.

+
+
marker-colors (1setof name(MAX))

+
+
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".

+
+
marker-levels (1setof integer(-1:100))

+
+
The marker-levels attribute specifies the current supply levels for the
+printer. It is only available when the driver provides supply levels. A
+value of -1 indicates the level is unknown, while values from 0 to 100
+indicate the corresponding percentage.

+
+
marker-names (1setof name(MAX))

+
+
The marker-names attribute specifies the name(s) for each supply in the
+printer. It is only available when the driver provides supply levels.

+
+
marker-types (1setof type3 keyword)

+
+
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
+following (RFC 3805) types are currently supported:

+
+
    
+
+	
  • toner
    • 
+
+	
  • wasteToner
    • 
+
+	
  • ink
    • 
+
+	
  • inkCartridge
    • 
+
+	
  • inkRibbon
    • 
+
+	
  • wasteInk
    • 
+
+	
  • opc
    • 
+
+	
  • developer
    • 
+
+	
  • fuserOil
    • 
+
+	
  • solidWax
    • 
+
+	
  • ribbonWax
    • 
+
+	
  • wasteWax
    • 
+
+	
  • fuser
    • 
+
+	
  • coronaWire
    • 
+
+	
  • fuserOilWick
    • 
+
+	
  • cleanerUnit
    • 
+
+	
  • fuserCleaningPad
    • 
+
+	
  • transferUnit
    • 
+
+	
  • tonerCartridge
    • 
+
+	
  • fuserOiler
    • 
+
+	
  • water
    • 
+
+	
  • wasteWater
    • 
+
+	
  • bindingSupply
    • 
+
+	
  • bandingSupply
    • 
+
+	
  • stichingWire
    • 
+
+	
  • shrinkWrap
    • 
+
+	
  • paperWrap
    • 
+
+	
  • staples
    • 
+
+	
  • inserts
    • 
+
+	
  • covers
    • 
+
+

+
 
port-monitor" (name(127))

 
 
The port-monitor attribute specifies the port monitor to use when printing
diff --git a/doc/help/spec-ppd.html b/doc/help/spec-ppd.html
index 0285f4697..63238e557 100644
--- a/doc/help/spec-ppd.html
+++ b/doc/help/spec-ppd.html
@@ -12,7 +12,7 @@
 
   CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2007 by Easy Software Products.
 
   These coded instructions, statements, and computer programs are the
@@ -1192,6 +1192,20 @@ http://www.vendor.com/help"
 *End
 

 
+
CUPS 1.4cupsMarkerName

+
+
*cupsMarkerName/Name Text: ""

+
+
This optional attribute maps marker-names strings that are
+generated by the driver to human readable text.

+
+
Examples:

+
+
+*% Map cyanToner to "Cyan Toner"
+*cupsMarkerName cyanToner/Cyan Toner: ""
+

+
 
CUPS 1.2cupsLanguages

 
 
*cupsLanguages: "locale list"

@@ -1204,7 +1218,7 @@ list of locale names ("en", "en_US", "fr_CA", etc.)

 
 
 *% Specify Canadian, UK, and US English, and Candian and French French 
-*cupsLanguages: "en_CA en_UK en_US fr_CA fr_CA"
+*cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
 

 
 
cupsManualCopies

diff --git a/filter/Makefile b/filter/Makefile
index f0691fc72..5f6a4aca5 100644
--- a/filter/Makefile
+++ b/filter/Makefile
@@ -168,9 +168,18 @@ uninstall64bit:
 apihelp:
 	echo Generating CUPS API help files...
 	mxmldoc --section "Programming" --title "Raster API" \
-		--intro api-raster.shtml \
+		--css ../doc/cups-printable.css \
+		--header api-raster.header --intro api-raster.shtml \
 		raster.h interpret.c raster.c >../doc/help/api-raster.html
 
+framedhelp:
+	echo Generating CUPS API help files...
+	mxmldoc --section "Programming" --title "Raster API" \
+		--framed ../cups/api-raster \
+		--css ../doc/cups-printable.css \
+		--header api-raster.header --intro api-raster.shtml \
+		raster.h interpret.c raster.c
+
 
 #
 # formtops
diff --git a/filter/api-raster.header b/filter/api-raster.header
new file mode 100644
index 000000000..8c6aaa0cc
--- /dev/null
+++ b/filter/api-raster.header
@@ -0,0 +1,37 @@
+
+
+
Raster API

+
+

+
+
+	
+	
+
+
+
+
+	
+	
+
+
+	
+	
+
+
+
Headercups/raster.h
Library-lcupsimage
See AlsoProgramming: Introduction to CUPS Programming

+	Programming: CUPS API

+	Programming: PPD API

+	References: CUPS PPD Specification

diff --git a/filter/api-raster.shtml b/filter/api-raster.shtml
index 327592655..b5529d230 100644
--- a/filter/api-raster.shtml
+++ b/filter/api-raster.shtml
@@ -3,7 +3,7 @@
 
   Raster API introduction for the Common UNIX Printing System (CUPS).
 
-  Copyright 2007 by Apple Inc.
+  Copyright 2007-2008 by Apple Inc.
   Copyright 1997-2006 by Easy Software Products, all rights reserved.
 
   These coded instructions, statements, and computer programs are the
@@ -13,39 +13,96 @@
   file is missing or damaged, see the license at "http://www.cups.org/".
 -->
 
-
Introduction

+
Overview

 
-
The CUPS raster API provides a standard interface for reading
-and writing CUPS raster streams which are used for printing to
-raster printers. Because the raster format is updated from time
-to time, it is important to use this API to avoid
-incompatibilities with newer versions of CUPS.

+
The CUPS raster API provides a standard interface for reading and writing
+CUPS raster streams which are used for printing to raster printers. Because the
+raster format is updated from time to time, it is important to use this API to
+avoid incompatibilities with newer versions of CUPS.

 
-
General Usage

+
CUPS raster files (application/vnd.cups-raster) consists of
+a stream of raster page descriptions produced by one of the RIP filters such as
+pstoraster, imagetoraster, or
+cgpdftoraster. CUPS raster files are referred to using the
+cups_raster_t type and are
+opened using the cupsRasterOpen
+function. For example, to read raster data from the standard input, open
+file descriptor 0:

 
-
The <cups/raster.h> header file must be
-included to use the cupsRaster functions.

+
+#include <cups/raster.h>>
 
-
Programs using these functions must be linked to the CUPS
-imaging library: libcupsimage.a,
-libcupsimage.so.2, libcupsimage.2.dylib,
-libcupsimage_s.a, or libcupsimage2.lib
-depending on the platform. The following command compiles
-myprogram.c using GCC and the CUPS imaging
-library:

+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+

+
+
Each page of data begins with a page dictionary structure called
+cups_page_header2_t. This
+structure contains the colorspace, bits per color, media size, media type,
+hardware resolution, and so forth used for the page. You read the page header
+using the
+cupsRasterReadHeader2
+function:

+
+
+#include <cups/raster.h>>
+
+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+cups_page_header2_t header;
 
-
-gcc -o myprogram myprogram.c -lcupsimage
+while (cupsRasterReadHeader2(ras, &header))
+{
+  /* setup this page */
+
+  /* read raster data */
+
+  /* finish this page */
+}
 

 
-
Compatibility

+
After the page dictionary comes the page data which is a full-resolution,
+possibly compressed bitmap representing the page in the printer's output
+colorspace. You read uncompressed raster data using the
+cupsRasterReadPixels
+function. A for loop is normally used to read the page one line
+at a time:

+
+
+#include <cups/raster.h>>
+
+cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
+cups_page_header2_t header;
+int page = 0;
+int y;
+char *buffer;
 
-
Unless otherwise specified, the raster API functions require
-CUPS 1.1 or higher.

+while (cupsRasterReadHeader2(ras, &header))
+{
+  /* setup this page */
+  page ++;
+  fprintf(stderr, "PAGE: %d %d\n", page, header.NumCopies);
 
-
Licensing

+  /* allocate memory for 1 line */
+  buffer = malloc(header.cupsBytesPerLine);
 
-
The CUPS raster API is provided under the terms of the GNU
-Library General Public License, with exceptions for MacOS X-based
-programs. Please see the CUPS license agreement for more
-information.

+  /* read raster data */
+  for (y = 0; y < header.cupsHeight; y ++)
+  {
+    if (cupsRasterReadPixels(ras, buffer, header.cupsBytesPerLine) == 0)
+      break;
+
+    /* write raster data to printer */
+  }
+
+  /* finish this page */
+}
+

+
+
When you are done reading the raster data, call the
+cupsRasterClose function to free
+the memory used to read the raster file:

+
+
+cups_raster_t *ras;
+
+cupsRasterClose(ras);
+

diff --git a/filter/interpret.c b/filter/interpret.c
index e0db81e63..a4687bd28 100644
--- a/filter/interpret.c
+++ b/filter/interpret.c
@@ -123,19 +123,22 @@ static void		DEBUG_stack(_cups_ps_stack_t *st);
  * 'cupsRasterInterpretPPD()' - Interpret PPD commands to create a page header.
  *
  * This function does not mark the options in the PPD using the "num_options"
- * and "options" arguments.  Instead, mark the options prior to calling
- * cupsRasterInterpretPPD() - this allows you to do per-page options
+ * and "options" arguments.  Instead, mark the options with
+ * @code cupsMarkOptions@ and @code ppdMarkOption@ prior to calling
+ * @code cupsRasterInterpretPPD@ - this allows you to do per-page options
  * without manipulating the options array.
  *
  * The "func" argument specifies an optional callback function that is
  * called prior to the computation of the final raster data.  The function
- * can make changes to the cups_page_header2_t data as needed to use a
+ * can make changes to the @link cups_page_header2_t@ data as needed to use a
  * supported raster format and then returns 0 on success and -1 if the
  * requested attributes cannot be supported.
  *
- * cupsRasterInterpretPPD() supports a subset of the PostScript language.
- * Currently only the [, ], <<, >>, {, }, cleartomark, copy, dup, index,
- * pop, roll, setpagedevice, and stopped operators are supported.
+ * @code cupsRasterInterpretPPD@ supports a subset of the PostScript language.
+ * Currently only the @code [@, @code ]@, @code <<@, @code >>@, @code {@,
+ * @code }@, @code cleartomark@, @code copy@, @code dup@, @code index@,
+ * @code pop@, @code roll@, @code setpagedevice@, and @code stopped@ operators
+ * are supported.
  *
  * @since CUPS 1.2@
  */
diff --git a/filter/raster.h b/filter/raster.h
index 4092dfa0d..2155ea516 100644
--- a/filter/raster.h
+++ b/filter/raster.h
@@ -147,12 +147,14 @@ typedef enum cups_jog_e			/**** Jog attribute values ****/
   CUPS_JOG_SET = 3			/* Move pages after this set */
 } cups_jog_t;
 
-typedef enum cups_mode_e		/**** Raster modes ****/
+enum cups_mode_e			/**** cupsRasterOpen modes ****/
 {
   CUPS_RASTER_READ = 0,			/* Open stream for reading */
   CUPS_RASTER_WRITE = 1,		/* Open stream for writing */
   CUPS_RASTER_WRITE_COMPRESSED = 2	/* Open stream for compressed writing @since CUPS 1.3@ */
-} cups_mode_t;
+};
+
+typedef enum cups_mode_e cups_mode_t;	/**** cupsRasterOpen modes ****/
 
 typedef enum cups_order_e		/**** cupsColorOrder attribute values ****/
 {
@@ -179,7 +181,7 @@ typedef enum cups_orient_e		/**** Orientation attribute values ****/
  * (from CUPS 1.2 and higher) page header, for binary compatibility.
  */
 
-typedef struct cups_page_header_s	/**** Version 1 Page Header ****/
+typedef struct cups_page_header_s	/**** Version 1 page header ****/
 {
   /**** Standard Page Device Dictionary String Values ****/
   char		MediaClass[64];		/* MediaClass string */
@@ -228,7 +230,7 @@ typedef struct cups_page_header_s	/**** Version 1 Page Header ****/
 } cups_page_header_t;
 
 /**** New in CUPS 1.2 ****/
-typedef struct cups_page_header2_s	/**** Version 2 Page Header @since CUPS 1.2@ ****/
+typedef struct cups_page_header2_s	/**** Version 2 page header @since CUPS 1.2@ ****/
 {
   /**** Standard Page Device Dictionary String Values ****/
   char		MediaClass[64];		/* MediaClass string */
@@ -295,6 +297,13 @@ typedef struct _cups_raster_s cups_raster_t;
 					/**** Raster stream data ****/
 
 typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
+					/**** cupsRasterInterpretPPD callback function
+					 *
+					 * This function is called by
+					 * @link cupsRasterInterpretPPD@ to
+					 * validate (and update, as needed)
+					 * the page header attributes.
+					 ****/
 
 
 /*
diff --git a/scheduler/client.c b/scheduler/client.c
index 98e1b7cf0..706c31541 100644
--- a/scheduler/client.c
+++ b/scheduler/client.c
@@ -2369,7 +2369,11 @@ cupsdSendHeader(
     char           *type,		/* I - MIME type of document */
     int            auth_type)		/* I - Type of authentication */
 {
-  char	auth_str[1024];			/* Authorization string */
+  char		auth_str[1024];		/* Authorization string */
+#ifdef HAVE_GSSAPI
+  static char	*gss_buf = NULL;	/* Kerberos auth data buffer */
+  static int	gss_bufsize = 0;	/* Size of Kerberos auth data buffer */
+#endif /* HAVE_GSSAPI */
 
 
  /*
@@ -2478,23 +2482,57 @@ cupsdSendHeader(
   * non-401 replies...
   */
 
-  if (con->gss_output_token.length > 0)
+  if (con->gss_output_token.length > 0 && con->gss_output_token.length <= 65536)
   {
-    char	buf[2048];		/* Output token buffer */
     OM_uint32	minor_status;		/* Minor status code */
+    int		bufsize;		/* Size of output token buffer */
+
+
+    bufsize = con->gss_output_token.length * 4 / 3 + 2;
+
+    if (bufsize > gss_bufsize)
+    {
+      char	*buf;			/* New buffer */
+
 
+      bufsize = (bufsize + 1023) & 1023;/* Round up */
 
-    httpEncode64_2(buf, sizeof(buf),
-    	           con->gss_output_token.value,
+      if (gss_buf)
+        buf = realloc(gss_buf, bufsize);
+      else
+        buf = malloc(bufsize);
+
+      if (!buf)
+      {
+	cupsdLogMessage(CUPSD_LOG_ERROR,
+			"Unable to allocate %d bytes for Kerberos credentials!",
+			bufsize);
+	return (0);
+      }
+
+      gss_buf     = buf;
+      gss_bufsize = bufsize;
+    }
+
+    httpEncode64_2(gss_buf, gss_bufsize,
+		   con->gss_output_token.value,
 		   con->gss_output_token.length);
     gss_release_buffer(&minor_status, &con->gss_output_token);
 
     cupsdLogMessage(CUPSD_LOG_DEBUG,
-                    "cupsdSendHeader: WWW-Authenticate: Negotiate %s", buf);
+		    "cupsdSendHeader: WWW-Authenticate: Negotiate %s", gss_buf);
 
-    if (httpPrintf(HTTP(con), "WWW-Authenticate: Negotiate %s\r\n", buf) < 0)
+    if (httpPrintf(HTTP(con), "WWW-Authenticate: Negotiate %s\r\n",
+                   gss_buf) < 0)
       return (0);
   }
+  else if (con->gss_output_token.length > 65536)
+  {
+    cupsdLogMessage(CUPSD_LOG_ERROR,
+                    "Kerberos credentials larger than 64k (%d)!",
+		    con->gss_output_token.length);
+    return (0);
+  }
 #endif /* HAVE_GSSAPI */
 
   if (con->language && strcmp(con->language->language, "C"))
diff --git a/scheduler/ipp.c b/scheduler/ipp.c
index df8f7e933..39ba5919b 100644
--- a/scheduler/ipp.c
+++ b/scheduler/ipp.c
@@ -4668,6 +4668,10 @@ copy_printer_attrs(
 		 printer->recoverable);
 #endif /* __APPLE__ */
 
+  if (!ra || cupsArrayFind(ra, "marker-change-time"))
+    ippAddInteger(con->response, IPP_TAG_PRINTER, IPP_TAG_INTEGER,
+                  "marker-change-time", printer->marker_time);
+
   if (printer->alert && (!ra || cupsArrayFind(ra, "printer-alert")))
     ippAddString(con->response, IPP_TAG_PRINTER, IPP_TAG_STRING,
                  "printer-alert", NULL, printer->alert);
diff --git a/scheduler/job.c b/scheduler/job.c
index 19f48a50c..004ee5148 100644
--- a/scheduler/job.c
+++ b/scheduler/job.c
@@ -3673,6 +3673,34 @@ update_job(cupsd_job_t *job)		/* I - Job to check */
 	event |= CUPSD_EVENT_PRINTER_STATE;
       }
 
+      if ((attr = cupsGetOption("marker-colors", num_attrs, attrs)) != NULL)
+      {
+        cupsdSetPrinterAttr(job->printer, "marker-colors", (char *)attr);
+	job->printer->marker_time = time(NULL);
+	event |= CUPSD_EVENT_PRINTER_STATE;
+      }
+
+      if ((attr = cupsGetOption("marker-levels", num_attrs, attrs)) != NULL)
+      {
+        cupsdSetPrinterAttr(job->printer, "marker-levels", (char *)attr);
+	job->printer->marker_time = time(NULL);
+	event |= CUPSD_EVENT_PRINTER_STATE;
+      }
+
+      if ((attr = cupsGetOption("marker-names", num_attrs, attrs)) != NULL)
+      {
+        cupsdSetPrinterAttr(job->printer, "marker-names", (char *)attr);
+	job->printer->marker_time = time(NULL);
+	event |= CUPSD_EVENT_PRINTER_STATE;
+      }
+
+      if ((attr = cupsGetOption("marker-types", num_attrs, attrs)) != NULL)
+      {
+        cupsdSetPrinterAttr(job->printer, "marker-types", (char *)attr);
+	job->printer->marker_time = time(NULL);
+	event |= CUPSD_EVENT_PRINTER_STATE;
+      }
+
       cupsFreeOptions(num_attrs, attrs);
     }
 #ifdef __APPLE__
diff --git a/scheduler/printers.c b/scheduler/printers.c
index 6eab48a84..6dc8bd971 100644
--- a/scheduler/printers.c
+++ b/scheduler/printers.c
@@ -27,6 +27,7 @@
  *   cupsdSaveAllPrinters()      - Save all printer definitions to the
  *                                 printers.conf file.
  *   cupsdSetAuthInfoRequired()  - Set the required authentication info.
+ *   cupsdSetPrinterAttr()       - Set a printer attribute.
  *   cupsdSetPrinterAttrs()      - Set printer attributes based upon the PPD
  *                                 file.
  *   cupsdSetPrinterReasons()    - Set/update the reasons strings.
@@ -1650,6 +1651,120 @@ cupsdSetAuthInfoRequired(
 }
 
 
+/*
+ * 'cupsdSetPrinterAttr()' - Set a printer attribute.
+ */
+
+void
+cupsdSetPrinterAttr(
+    cupsd_printer_t *p,			/* I - Printer */
+    const char      *name,		/* I - Attribute name */
+    char            *value)		/* I - Attribute value string */
+{
+  ipp_attribute_t	*attr;		/* Attribute */
+  int			i,		/* Looping var */
+			count;		/* Number of values */
+  char			*ptr;		/* Pointer into value */
+  ipp_tag_t		value_tag;	/* Value tag for this attribute */
+
+
+ /*
+  * Count the number of values...
+  */
+
+  for (count = 1, ptr = value;
+       (ptr = strchr(ptr, ',')) != NULL;
+       ptr ++, count ++);
+
+ /*
+  * Then add or update the attribute as needed...
+  */
+
+  if (!strcmp(name, "marker-levels"))
+  {
+   /*
+    * Integer values...
+    */
+
+    if ((attr = ippFindAttribute(p->attrs, name, IPP_TAG_INTEGER)) != NULL &&
+        attr->num_values < count)
+    {
+      ippDeleteAttribute(p->attrs, attr);
+      attr = NULL;
+    }
+
+    if (attr)
+      attr->num_values = count;
+    else
+      attr = ippAddIntegers(p->attrs, IPP_TAG_PRINTER, IPP_TAG_INTEGER, name,
+                            count, NULL);
+
+    if (!attr)
+    {
+      cupsdLogMessage(CUPSD_LOG_ERROR,
+                      "Unable to allocate memory for printer attribute "
+		      "(%d values)", count);
+      return;
+    }
+
+    for (i = 0; i < count; i ++)
+    {
+      if ((ptr = strchr(value, ',')) != NULL)
+        *ptr++ = '\0';
+
+      attr->values[i].integer = strtol(value, NULL, 10);
+
+      if (ptr)
+        value = ptr;
+    }
+  }
+  else
+  {
+   /*
+    * Name or keyword values...
+    */
+
+    if (!strcmp(name, "marker-types"))
+      value_tag = IPP_TAG_KEYWORD;
+    else
+      value_tag = IPP_TAG_NAME;
+
+    if ((attr = ippFindAttribute(p->attrs, name, value_tag)) != NULL &&
+        attr->num_values < count)
+    {
+      ippDeleteAttribute(p->attrs, attr);
+      attr = NULL;
+    }
+
+    if (attr)
+      attr->num_values = count;
+    else
+      attr = ippAddStrings(p->attrs, IPP_TAG_PRINTER, value_tag, name,
+                           count, NULL, NULL);
+
+    if (!attr)
+    {
+      cupsdLogMessage(CUPSD_LOG_ERROR,
+                      "Unable to allocate memory for printer attribute "
+		      "(%d values)", count);
+      return;
+    }
+
+    for (i = 0; i < count; i ++)
+    {
+      if ((ptr = strchr(value, ',')) != NULL)
+        *ptr++ = '\0';
+
+      _cupsStrFree(attr->values[i].string.text);
+      attr->values[i].string.text = _cupsStrAlloc(value);
+
+      if (ptr)
+        value = ptr;
+    }
+  }
+}
+
+
 /*
  * 'cupsdSetPrinterAttrs()' - Set printer attributes based upon the PPD file.
  */
diff --git a/scheduler/printers.h b/scheduler/printers.h
index 7a19b973e..a7fecdad5 100644
--- a/scheduler/printers.h
+++ b/scheduler/printers.h
@@ -86,6 +86,7 @@ typedef struct cupsd_printer_s
   const char	*auth_info_required[4];	/* Required authentication fields */
   char		*alert,			/* PSX printer-alert value */
 		*alert_description;	/* PSX printer-alert-description value */
+  time_t	marker_time;		/* Last time marker attributes were updated */
 
 #ifdef __APPLE__
   char		*recoverable;		/* com.apple.print.recoverable-message */
@@ -150,6 +151,8 @@ extern void		cupsdSaveAllPrinters(void);
 extern int		cupsdSetAuthInfoRequired(cupsd_printer_t *p,
 			                         const char *values,
 						 ipp_attribute_t *attr);
+extern void		cupsdSetPrinterAttr(cupsd_printer_t *p,
+			                    const char *name, char *value);
 extern void		cupsdSetPrinterAttrs(cupsd_printer_t *p);
 extern void		cupsdSetPrinterReasons(cupsd_printer_t *p,
 			                       const char *s);
diff --git a/scheduler/process.c b/scheduler/process.c
index a22548e8f..d37b07915 100644
--- a/scheduler/process.c
+++ b/scheduler/process.c
@@ -106,7 +106,8 @@ cupsdCreateProfile(int job_id)		/* I - Job ID or 0 for none */
 		 "#\"^/Library\" #\"^/System\" #\"^/Users\"))\n", root);
   cupsFilePrintf(fp,
                  "(allow file-write* file-read-data file-read-metadata\n"
-                 "  (regex #\"^%s$\" #\"^%s/\" #\"^%s$\" #\"^%s/\"))\n",
+                 "  (regex #\"^%s$\" #\"^%s/\" #\"^%s$\" #\"^%s/\" "
+		 "#\"^/Library/Caches/\"))\n",
 		 temp, temp, cache, cache);
   if (job_id)
     cupsFilePrintf(fp,
-- 
2.39.2