From 5a738aeaea5c4dd9384a8601cc5c99be683b69ca Mon Sep 17 00:00:00 2001
From: msweet 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
+ The CUPS scheduler (cupsd) and many of the CUPS API
functions use the array API to efficiently manage large lists of
data. The <cups/array.h> header file must be
-included to use the cupsArray functions. Arrays are created using either the
+ 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 comparison function (type
+ The "user_data" pointer is passed to your comparison function. Pass
+ The The hash function (type
+ Once you have created the array, you add elements using the
+ Elements are removed using the
+ All of these functions require CUPS 1.2 or higher. Finally, you free the memory used by the array using the
+ 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: Each of these functions returns 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 (collections of printers) are accessed through
+the The <cups/cups.h> header file must be included to
-use the CUPS 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: Passing Options are stored in arrays of
+ You can create your own option arrays using the
+ Use a Use the 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 The Finally, the Once you have created a job, you can monitor its status using the
+ To cancel a job, use the
+ If any of the CUPS API printing functions returns an error, the reason for
+that error can be found by calling the
+ 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 The The following example shows a simple password callback that gets a
+username and password from the user: 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 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 Array API
+
+
+
+
+
+
+
+Header
+ cups/array.h
+
+
+Library
+ -lcups
+
+
+
+See Also
+ Programming: Introduction to CUPS Programming
+Introduction
+Overview
-cups_array_t
type is used when
+referring to a CUPS array.General Usage
+Managing Arrays
-cupsArrayNew
or
+cupsArrayNew2
functions. The
+first function creates a new array with the specified callback function
+and user data pointer:
+#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);
+
+
+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.NULL
if you do not need to associate the elements in your array
+with additional information.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);
+
+
+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.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
+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");
+
+
+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
+
+
+
+
+cupsArrayFind
cupsArrayFirst
cupsArrayIndex
cupsArrayLast
cupsArrayNext
cupsArrayPrev
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
+
+
+
+
+
+
+
+Header
+ cups/cups.h
+
+
+Library
+ -lcups
+
+
+
+See Also
+ Programming: 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 APIIntroduction
+Overview
-Printers and Classes
-General Usage
+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:
+#include <cups/cups.h>
-
-gcc -o myprogram myprogram.c -lcups
+/* do something wiith dest */
+
+cupsFreeDests(num_dests, dests);
-Compatibility
+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.
+
+
+
+
+Attribute Name
+ Description
+
+
+"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
+
+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);
+
+
+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);
+
+
+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);
+
+
+cupsFreeOptions
+function to free the options array when you are done using it:
+cupsFreeOptions(num_options, options);
+
+
+Print Jobs
+
+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);
+
+
+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);
+
+
+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);
+ }
+}
+
+
+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);
+}
+
+
+cupsCancelJob
function with the
+job ID:
+#include <cups/cups.h>
+
+cups_dest_t *dest;
+int job_id;
+
+cupsCancelJob(dest->name, job_id);
+
+
+Error Handling
+
+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
+
+cupsSetPasswordCB
+function is used to set a password callback in your program. Only one
+function can be used at any time.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.
+#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);
+
-cupsUser
+function.File and Directory APIs
+
+
+
+
+
+
+
+Headers
+ cups/file.h
+
+ cups/dir.h
+
+Library
+ -lcups
+
+
+
+See Also
+ Programming: Introduction to CUPS Programming
+
+ Programming: CUPS APIIntroduction
+Overview
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.
- -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 -- -
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 @@ + + +Header | +cups/backend.h + cups/sidechannel.h |
+
---|---|
Library | +-lcups | +
See Also | +Programming: Introduction to CUPS Programming + Programming: CUPS API + Programming: PPD API + Programming: Raster API |
+
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:
-
The <cups/backend.h> and -<cups/cups.h> header files must be included to -use the CUPS_BACKEND_ constants and -cupsBackChannel functions, respectively.
+The <cups/sidechannel.h> header file must be -included to use the CUPS_SC_ constants and cupsSideChannel 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:
+-gcc -o myprogram myprogram.c -lcups -+
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.
+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.
+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> +
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:
+-#include <cups/cups.h> +
The cupsSideChannel APIs allow your filters, drivers, port monitors, and backend to send and receive the following out-of-band commands:
+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.
+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:
+ +
marker-colors
, marker-levels
,
+ marker-names
, marker-types
,
+ printer-alert
, and printer-alert-description
+ printer attributes.Messages without one of these prefixes are treated as if they began with +the "DEBUG:" prefix string.
+ +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 +
-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; -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 atimeout
of 0.0, wait +indefinitely for commands using atimeout
of -1.0 (probably in a +separate thread for that purpose), or useselect
or +poll
on theCUPS_SC_FD
file descriptor (4) to handle +input and output on several file descriptors at the same time. Backends can pass +NULL
for thedata
anddatalen
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
+ +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/". --> -+ +
+ + + +Header +cups/cups.h ++ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ References: CUPS Implementation of IPPIntroduction
+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 constantCUPS_HTTP_DEFAULT
can be used with all of the +cups
functions to refer to the default CUPS server - the functions +create a per-threadhttp_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 theippDelete
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, thecupsDoRequest
+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 +withNULL
names indicate a separator between the attributes of +each object. For example, the following code will list the jobs returned from +our previousget_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
andCUPS_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 theippDelete
+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 previousCUPS_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
orHTTP_UNAUTHORIZED
. The latter status +is returned when the request requires authentication of some sort. The +cupsDoAuthentication
function +must be called when your seeHTTP_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
+ +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 @@ + + ++ +
+ + + +Headers +cups/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 Also +Programming: 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 APIOverview
+ +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
+ +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/". --> -+ +
+ + + +Header +cups/ppd.h ++ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ Reference: CUPS PPD SpecificationIntroduction
+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 orNULL
+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 passNULL
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. +Thecustom_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 appd_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 + + + ++ + +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 @@ -Array API
+ +++ +
+ + + +Header +cups/array.h ++ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +Contents
++ +
-- Overview
+- Functions
+
+- cupsArrayAdd
+- cupsArrayClear
+- cupsArrayCount
+- cupsArrayCurrent
+- cupsArrayDelete
+- cupsArrayDup
+- cupsArrayFind
+- cupsArrayFirst
+- cupsArrayGetIndex
+- cupsArrayGetInsert
+- cupsArrayIndex
+- cupsArrayInsert
+- cupsArrayLast
+- cupsArrayNew
+- cupsArrayNew2
+- cupsArrayNext
+- cupsArrayPrev
+- cupsArrayRemove
+- cupsArrayRestore
+- cupsArraySave
+- cupsArrayUserData
+- Data Types
+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 beNULL
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()
-- cupsArrayClear()
-- cupsArrayCount()
-- cupsArrayCurrent()
-- cupsArrayDelete()
-- cupsArrayDup()
-- cupsArrayFind()
-- cupsArrayFirst()
-- cupsArrayGetIndex() CUPS 1.3
-- cupsArrayGetInsert() CUPS 1.3
-- cupsArrayIndex()
-- cupsArrayInsert()
-- cupsArrayLast()
-- cupsArrayNew()
-- cupsArrayNew2() CUPS 1.3
-- cupsArrayNext()
-- cupsArrayPrev()
-- cupsArrayRemove()
-- cupsArrayRestore()
-- cupsArraySave()
-- cupsArrayUserData()
-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 simplefor
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
---
- - Name Description - a Array - e Element Returns
-1 on success, 0 on failure
- -cupsArrayClear()
-Description
-Clear the array. -
Syntax
--void
-
-cupsArrayClear( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Nothing.
- -cupsArrayCount()
-Description
-Get the number of elements in the array. -
Syntax
--int
-
-cupsArrayCount( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Number of elements
- -cupsArrayCurrent()
-Description
-Return the current element in the array. -
Syntax
--void *
-
-cupsArrayCurrent( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Element
- -cupsArrayDelete()
-Description
-Free all memory used by the array. -
Syntax
--void
-
-cupsArrayDelete( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Nothing.
- -cupsArrayDup()
-Description
-Duplicate the array. -
Syntax
--cups_array_t *
-
-cupsArrayDup( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Duplicate array
- -cupsArrayFind()
-Description
-Find an element in the array. -
Syntax
--void *
-
-cupsArrayFind( - cups_array_t * a, - void * e); -Arguments
---
- - Name Description - a Array - e Element Returns
-Element found or NULL
- -cupsArrayFirst()
-Description
-Get the first element in the array. -
Syntax
--void *
-
-cupsArrayFirst( - cups_array_t * a); -Arguments
---
- - Name Description - a Array 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
---
- - Name Description - a Array 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
---
- - Name Description - a Array 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
---
- - Name Description - a Array - n Index 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
---
- - Name Description - a Array - e Element Returns
-0 on failure, 1 on success
- -cupsArrayLast()
-Description
-Get the last element in the array. -
Syntax
--void *
-
-cupsArrayLast( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Last element or NULL
- -cupsArrayNew()
-Description
-Create a new array. -
Syntax
--cups_array_t *
-
-cupsArrayNew( - cups_array_func_t f, - void * d); -Arguments
---
- - Name Description - f Comparison function - d User 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
---
- - Name Description - f Comparison function - d User data - h Hash function - hsize Hash size Returns
-Array
- -cupsArrayNext()
-Description
-Get the next element in the array. -
Syntax
--void *
-
-cupsArrayNext( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Next element or NULL
- -cupsArrayPrev()
-Description
-Get the previous element in the array. -
Syntax
--void *
-
-cupsArrayPrev( - cups_array_t * a); -Arguments
---
- - Name Description - a Array Returns
-Previous element or NULL
- -cupsArrayRemove()
-Description
-Remove an element from the array. -
Syntax
--int
-
-cupsArrayRemove( - cups_array_t * a, - void * e); -Arguments
---
- - Name Description - a Array - e Element 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
---
- - Name Description - a Array 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
---
- - Name Description - a Array Returns
-1 on success, 0 on failure
- -cupsArrayUserData()
-Description
-Return the user data for an array. -
Syntax
--void *
-
-cupsArrayUserData( - cups_array_t * a); -Arguments
---
- - Name Description - a Array 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; -
+ +CUPS API - - - +CUPS API + + + ++ + +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 @@ -CUPS API
+ +++ +
+ + + +Header +cups/cups.h ++ +Library +-lcups ++ + +See Also +Programming: 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 APIContents
++ +
-- Overview
+- Functions
+
+- cupsAddDest
+- cupsAddOption
+- cupsCancelJob
+- cupsCancelJob2
+- cupsCreateJob
+- cupsEncryption
+- cupsFinishDocument
+- cupsFreeDests
+- cupsFreeJobs
+- cupsFreeOptions
+- cupsGetClasses
+- cupsGetDefault
+- cupsGetDefault2
+- cupsGetDest
+- cupsGetDests
+- cupsGetDests2
+- cupsGetFd
+- cupsGetFile
+- cupsGetJobs
+- cupsGetJobs2
+- cupsGetNamedDest
+- cupsGetOption
+- cupsGetPPD
+- cupsGetPPD2
+- cupsGetPPD3
+- cupsGetPassword
+- cupsGetPrinters
+- cupsGetServerPPD
+- cupsLangDefault
+- cupsLangEncoding
+- cupsLangFlush
+- cupsLangFree
+- cupsLangGet
+- cupsLastError
+- cupsLastErrorString
+- cupsNotifySubject
+- cupsNotifyText
+- cupsParseOptions
+- cupsPrintFile
+- cupsPrintFile2
+- cupsPrintFiles
+- cupsPrintFiles2
+- cupsPutFd
+- cupsPutFile
+- cupsRemoveDest
+- cupsRemoveOption
+- cupsServer
+- cupsSetDefaultDest
+- cupsSetDests
+- cupsSetDests2
+- cupsSetEncryption
+- cupsSetPasswordCB
+- cupsSetServer
+- cupsSetUser
+- cupsStartDocument
+- cupsTempFd
+- cupsTempFile
+- cupsTempFile2
+- cupsUser
+- Data Types
++
- cups_dest_t
+- cups_job_t
+- cups_option_t
+- cups_password_cb_t
+- cups_ptype_t
+- Structures
++
- cups_dest_s
+- cups_job_s
+- cups_option_s
+- Constants
++
- cups_ptype_e
+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 thecupsFreeDests
function. +ThecupsGetDest
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 aNULL
+instance will return the default instance for that destination.Unless otherwise specified, the CUPS API functions require -CUPS 1.1 or higher.
-Contents
--
- -- Enumerations
-- Functions
-- Structures
-- Types
-Enumerations
--
- -- cups_ptype_e
-cups_ptype_e
-Description
-Not a typedef'd enum so we can OR -
Values
-+ +-
+ Name Description - -+
Table 1: Printer Attributes + ++ + -Attribute Name +Description +- 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()
-- cupsAddOption()
-- cupsCancelJob()
-- cupsEncryption()
-- cupsFreeDests()
-- cupsFreeJobs()
-- cupsFreeOptions()
-- cupsGetClasses() DEPRECATED
-- cupsGetDefault()
-- cupsGetDefault2() CUPS 1.1.21
-- cupsGetDest()
-- cupsGetDests()
-- cupsGetDests2() CUPS 1.1.21
-- cupsGetFd() CUPS 1.1.20
-- cupsGetFile() CUPS 1.1.20
-- cupsGetJobs()
-- cupsGetJobs2() CUPS 1.1.21
-- cupsGetOption()
-- cupsGetPPD()
-- cupsGetPPD2() CUPS 1.1.21
-- cupsGetPPD3()
-- cupsGetPassword()
-- cupsGetPrinters() DEPRECATED
-- cupsGetServerPPD() CUPS 1.3
-- cupsLangDefault()
-- cupsLangEncoding()
-- cupsLangFlush()
-- cupsLangFree()
-- cupsLangGet()
-- cupsLastError()
-- cupsLastErrorString() CUPS 1.2
-- cupsMarkOptions()
-- cupsNotifySubject() CUPS 1.2
-- cupsNotifyText() CUPS 1.2
-- cupsParseOptions()
-- cupsPrintFile()
-- cupsPrintFile2() CUPS 1.1.21
-- cupsPrintFiles()
-- cupsPrintFiles2() CUPS 1.1.21
-- cupsPutFd() CUPS 1.1.20
-- cupsPutFile() CUPS 1.1.20
-- cupsRemoveDest() CUPS 1.3
-- cupsRemoveOption() CUPS 1.2
-- cupsServer()
-- cupsSetDefaultDest() CUPS 1.3
-- cupsSetDests()
-- cupsSetDests2() CUPS 1.1.21
-- cupsSetEncryption()
-- cupsSetPasswordCB()
-- cupsSetServer()
-- cupsSetUser()
-- cupsTempFd()
-- cupsTempFile() DEPRECATED
-- cupsTempFile2() CUPS 1.2
-- cupsUser()
-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. Thecups_dest_t
+num_options
andoptions
members contain the +default options for a particular destination, along with several informational +attributes about the destination as shown in Table 1. +ThecupsGetOption
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
, +andcupsFinishDocument
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 ofcups_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
---
- - Name Description - name Destination name - instance Instance name or NULL for none/primary - num_dests Number of destinations - dests Destinations 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
---
- - Name Description - name Name of option - value Value of option - num_options Number of options - options Pointer 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 thecupsSaveDests
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 orCUPS_JOBID_CURRENT
+to cancel the current job on the named destination.
+
+Use thecupsLastError
andcupsLastErrorString
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.
+
+PassCUPS_JOBID_ALL
to cancel all jobs orCUPS_JOBID_CURRENT
+to cancel the current job on the named destination.
+
+Use thecupsLastError
andcupsLastErrorString
functions to get the cause of any failure. -Syntax
--int
-
-cupsCancelJob( - const char * name, - int job); -Arguments
---
- - Name Description - name Name of printer or class - job Job 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
, andcupsFinishDocument
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
---
- - Name Description - num_dests Number of destinations - dests Destinations Returns
-Nothing.
- -cupsFreeJobs()
-Description
-Free memory used by job data. -
Syntax
--void
-
-cupsFreeJobs( - int num_jobs, - cups_job_t * jobs); -Arguments
---
- - Name Description - num_jobs Number of jobs - jobs Jobs Returns
-Nothing.
- -cupsFreeOptions()
-Description
-Free all memory used by options. -
Syntax
--void
-
-cupsFreeOptions( - int num_options, - cups_option_t * options); -Arguments
---
- - Name Description - num_options Number of options - options Pointer 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
---
- - Name Description - classes Classes 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
andcupsGetDest
+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
---
- - Name Description - http HTTP 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
---
- - Name Description - name Destination name or NULL for the default destination - instance Instance name or NULL - num_dests Number of destinations - dests Destinations 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
andcupsGetDest
+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
orcupsGetDests2
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
---
- - Name Description - dests Destinations 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 thecupsFreeDests
function to free the destination list and +thecupsGetDest
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
---
- - Name Description - http HTTP connection - dests Destinations 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
---
- - Name Description - http HTTP connection to server - resource Resource name - fd File 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
---
- - Name Description - http HTTP connection to server - resource Resource name - filename Filename 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
---
- - Name Description - jobs Job data - mydest NULL = all destinations, * -otherwise show jobs for mydest - myjobs 0 = 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
---
- - Name Description - http HTTP connection - jobs Job data - mydest NULL = all destinations, * -otherwise show jobs for mydest - myjobs 0 = 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
---
- - Name Description - name Name of option - num_options Number of options - options Options 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
---
- - Name Description - name Printer 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 thecupsFreeDests
function to free the destination list and +thecupsGetDest
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
---
- - Name Description - http HTTP connection - name Printer 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
, orCUPS_WHICHJOBS_COMPLETED
Return Value
+Number of jobs
+Discussion
+A "whichjobs" value of
+CUPS_WHICHJOBS_ALL
returns all jobs regardless +of state, whileCUPS_WHICHJOBS_ACTIVE
returns jobs that are +pending, processing, or held andCUPS_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
, orCUPS_WHICHJOBS_COMPLETED
Return Value
+Number of jobs
+Discussion
+A "whichjobs" value of
+CUPS_WHICHJOBS_ALL
returns all jobs regardless +of state, whileCUPS_WHICHJOBS_ACTIVE
returns jobs that are +pending, processing, or held andCUPS_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
andcupsGetDest
when you either +know the name of the destination or want to print to the default destination. +IfNULL
is returned, the destination does not exist or there is no +default destination.
+
+If "http" isCUPS_HTTP_DEFAULT
, the connection to the default print +server will be used.
+
+If "name" isNULL
, the default printer for the current user will be +returned.
+
+The returned destination must be freed usingcupsFreeDests
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
---
- - Name Description - http HTTP connection - name Printer name - modtime Modification time - buffer Filename buffer - bufsize Size 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
---
- - Name Description - prompt Prompt 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
---
- - Name Description - printers Printers 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 errorDiscussion
+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
---
- - Name Description - http HTTP connection - name Name 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
---
- - Name Description - lang Language 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
---
- - Name Description - lang Language to free Returns
-Nothing.
- -cupsLangGet()
-Description
-Get a language. -
Syntax
--cups_lang_t *
-
-cupsLangGet( - const char * language); -Arguments
---
- - Name Description - language Language 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
---
- - Name Description - ppd PPD file - num_options Number of options - options Options 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
---
- - Name Description - lang Language data - event Event 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
---
- - Name Description - lang Language data - event Event 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
, +orcupsGetServerPPD
. + +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
---
- - Name Description - arg Argument to parse - num_options Number of options - options Options 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
---
- - Name Description - name Printer or class name - filename File to print - title Title of job - num_options Number of options - options Options 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
---
- - Name Description - http HTTP connection - name Printer or class name - filename File to print - title Title of job - num_options Number of options - options Options 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
---
- - Name Description - 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 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
---
- - Name Description - http HTTP connection - 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 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
---
- - Name Description - http HTTP connection to server - resource Resource name - fd File 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
---
- - Name Description - http HTTP connection to server - resource Resource name - filename Filename 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
---
- - Name Description - name Destination name - instance Instance name or NULL - num_dests Number of destinations - dests Destinations 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
---
- - Name Description - name Option name - num_options Current number of options - options Options 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
---
- - Name Description - name Destination name - instance Instance name or NULL - num_dests Number of destinations - dests Destinations 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
---
- - Name Description - num_dests Number of destinations - dests Destinations 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
orcupsSetDests2
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 constantsCUPS_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
---
- - Name Description - http HTTP connection - num_dests Number of destinations - dests Destinations Returns
-0 on success, -1 on error
- -cupsSetEncryption()
-Description
-Set the encryption preference. -
Syntax
--void
-
-cupsSetEncryption( - http_encryption_t e); -Arguments
---
- - Name Description - e New 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
---
- - Name Description - cb Callback 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
---
- - Name Description - server Server 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
---
- - Name Description - user User 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
---
- - Name Description - filename Pointer to buffer - len Size 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
---
- - Name Description - filename Pointer to buffer - len Size 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
---
- - Name Description - filename Pointer to buffer - len Size 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
-- cups_job_s
-- cups_option_s
-cups_dest_s
-Description
-Destination -
Definition
--struct cups_dest_s
-
-{
- char *name, * instance;
- int is_default;
- int num_options;
- cups_option_t * options;
-};Members
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - name Name of option - - value Value of option - Types
--
- -- cups_dest_t
-- cups_job_t
-- cups_option_t
-- cups_password_cb_t
-- cups_ptype_t
-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
+File and Directory APIs - - - +File and Directory APIs + + + ++ + +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 @@ -File and Directory APIs
+ +++ +
+ + + +Headers +cups/file.h +
+ cups/dir.h+ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS APIContents
++ +
-- Overview
+- Functions
+
+- cupsDirClose
+- cupsDirOpen
+- cupsDirRead
+- cupsDirRewind
+- cupsFileClose
+- cupsFileCompression
+- cupsFileEOF
+- cupsFileFind
+- cupsFileFlush
+- cupsFileGetChar
+- cupsFileGetConf
+- cupsFileGetLine
+- cupsFileGets
+- cupsFileLock
+- cupsFileNumber
+- cupsFileOpen
+- cupsFileOpenFd
+- cupsFilePeekChar
+- cupsFilePrintf
+- cupsFilePutChar
+- cupsFilePuts
+- cupsFileRead
+- cupsFileRewind
+- cupsFileSeek
+- cupsFileStderr
+- cupsFileStdin
+- cupsFileStdout
+- cupsFileTell
+- cupsFileUnlock
+- cupsFileWrite
+- Data Types
++
- cups_dentry_t
+- cups_dir_t
+- cups_file_t
+- Structures
++
- cups_dentry_s
+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, thecupsFile
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 moreCUPS 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
orCUPS_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 foundDiscussion
+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. ANULL
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 errorCUPS 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 errorCUPS 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 openedDiscussion
+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 openedDiscussion
+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
-- Structures
-- Types
-Functions
--
- -- cupsDirClose()
-- cupsDirOpen()
-- cupsDirRead()
-- cupsDirRewind()
-- cupsFileClose()
-- cupsFileCompression()
-- cupsFileEOF()
-- cupsFileFind()
-- cupsFileFlush()
-- cupsFileGetChar()
-- cupsFileGetConf()
-- cupsFileGetLine()
-- cupsFileGets()
-- cupsFileLock()
-- cupsFileNumber()
-- cupsFileOpen()
-- cupsFileOpenFd()
-- cupsFilePeekChar()
-- cupsFilePrintf()
-- cupsFilePutChar()
-- cupsFilePuts()
-- cupsFileRead()
-- cupsFileRewind()
-- cupsFileSeek()
-- cupsFileStderr()
-- cupsFileStdin()
-- cupsFileStdout()
-- cupsFileTell()
-- cupsFileUnlock()
-- cupsFileWrite()
-cupsDirClose()
-Description
-Close a directory. -
Syntax
--void
-
-cupsDirClose( - cups_dir_t * dp); -Arguments
---
- - Name Description - dp Directory Returns
-Nothing.
- -cupsDirOpen()
-Description
-Open a directory. -
Syntax
--cups_dir_t *
-
-cupsDirOpen( - const char * directory); -Arguments
---
- - Name Description - directory Directory name Returns
-Directory
- -cupsDirRead()
-Description
-Read the next directory entry. -
Syntax
--cups_dentry_t *
-
-cupsDirRead( - cups_dir_t * dp); -Arguments
---
- - Name Description - dp Directory Returns
-Directory entry
- -cupsDirRewind()
-Description
-Rewind to the start of the directory. -
Syntax
--void
-
-cupsDirRewind( - cups_dir_t * dp); -Arguments
---
- - Name Description - dp Directory Returns
-Nothing.
- -cupsFileClose()
-Description
-Close a CUPS file. -
Syntax
--int
-
-cupsFileClose( - cups_file_t * fp); -Arguments
---
- - Name Description - fp CUPS file Returns
-0 on success, -1 on error
- -cupsFileCompression()
-Description
-Return whether a file is compressed. -
Syntax
--int
-
-cupsFileCompression( - cups_file_t * fp); -Arguments
---
- - Name Description - fp CUPS 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
---
- - Name Description - fp CUPS 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
---
- - Name Description - 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 Returns
-Full path to file or NULL
- -cupsFileFlush()
-Description
-Flush pending output. -
Syntax
--int
-
-cupsFileFlush( - cups_file_t * fp); -Arguments
---
- - Name Description - fp CUPS 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
---
- - Name Description - fp CUPS 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
---
- - Name Description - fp CUPS file - buf String buffer - buflen Size of string buffer - value Pointer to value - linenum Current 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
---
- - Name Description - fp File to read from - buf Buffer - buflen Size 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
---
- - Name Description - fp CUPS file - buf String buffer - buflen Size 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
---
- - Name Description - fp File to lock - block 1 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
---
- - Name Description - fp CUPS file Returns
-File descriptor
- -cupsFileOpen()
-Description
-Open a CUPS file. -
Syntax
--cups_file_t *
-
-cupsFileOpen( - const char * filename, - const char * mode); -Arguments
---
- - Name Description - filename Name of file - mode Open 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
---
- - Name Description - fd File descriptor - mode Open mode Returns
-CUPS file or NULL
- -cupsFilePeekChar()
-Description
-Peek at the next character from a file. -
Syntax
--int
-
-cupsFilePeekChar( - cups_file_t * fp); -Arguments
---
- - Name Description - fp CUPS file Returns
-Character or -1 on EOF
- -cupsFilePrintf()
-Description
-Write a formatted string. -
Syntax
--int
-
-cupsFilePrintf( - cups_file_t * fp, - const char * format, - ...); -Arguments
---
- - Name Description - fp CUPS file - format Printf-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
---
- - Name Description - fp CUPS file - c Character 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
---
- - Name Description - fp CUPS file - s String 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
---
- - Name Description - fp CUPS file - buf Buffer - bytes Number 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
---
- - Name Description - fp CUPS 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
---
- - Name Description - fp CUPS file - pos Position 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
---
- - Name Description - fp CUPS file Returns
-File position
- -cupsFileUnlock()
-Description
-Unlock access to a file. -
Syntax
--int
-
-cupsFileUnlock( - cups_file_t * fp); -Arguments
---
- - Name Description - fp File 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
---
- - Name Description - fp CUPS file - buf Buffer - bytes Number of bytes to write Returns
-Number of bytes written
- -Structures
--
- -- cups_dentry_s
-cups_dentry_s
-Description
-Directory entry type -
Definition
--struct cups_dentry_s
-
-{
- struct stat fileinfo;
- char filename[260];
-};Members
-- --
- - Name Description - fileinfo File information - - filename[260] File name - Types
--
- -- cups_dentry_t
-- cups_dir_t
-- cups_file_t
-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
+Filter and Backend APIs - - - +Filter and Backend Programming + + + +-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 @@ -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.
+++ +
+ + + +Header +cups/backend.h +
+ cups/sidechannel.h+ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ Programming: PPD API
+ Programming: Raster APIContents
++ +
+ -- Overview
+- Functions +
- Data Types
+- Constants
+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); - +
-char data; -int datalen; -cups_sc_bidi_t bidi; -cups_sc_status_t status; +- 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> +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
, andprinter-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 atimeout
of 0.0, wait +indefinitely for commands using atimeout
of -1.0 (probably in a +separate thread for that purpose), or useselect
or +poll
on theCUPS_SC_FD
file descriptor (4) to handle +input and output on several file descriptors at the same time. Backends can pass +NULL
for thedata
anddatalen
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
-Functions
--
- -- cupsBackChannelRead() CUPS 1.2
-- cupsBackChannelWrite() CUPS 1.2
-- cupsSideChannelDoRequest() CUPS 1.3
-- cupsSideChannelRead() CUPS 1.3
-- cupsSideChannelWrite() CUPS 1.3
-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
---
- - Name Description - buffer Buffer to read - bytes Bytes to read - timeout Timeout 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
---
- - Name Description - buffer Buffer to write - bytes Bytes to write - timeout Timeout 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
---
- - Name Description - 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 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
---
- - Name Description - 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 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
---
- - Name Description - command Command code - status Status code - data Data buffer pointer - datalen Number of bytes of data - timeout Timeout 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
+HTTP and IPP APIs - - - +HTTP and IPP APIs + + + ++ +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 @@ + + + + +HTTP and IPP APIs
+ +++ +
+ + + +Header +cups/cups.h ++ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ References: CUPS Implementation of IPPContents
++ +
+ -- Overview
+- Functions
+
+- cupsDoAuthentication
+- cupsDoFileRequest
+- cupsDoIORequest
+- cupsDoRequest
+- cupsEncodeOptions
+- cupsEncodeOptions2
+- cupsGetResponse
+- cupsReadResponseData
+- cupsSendRequest
+- cupsWriteRequestData
+- httpAddrAny
+- httpAddrEqual
+- httpAddrLength
+- httpAddrLocalhost
+- httpAddrLookup
+- httpAddrString
+- httpAssembleURI
+- httpAssembleURIf
+- httpBlocking
+- httpCheck
+- httpClearCookie
+- httpClearFields
+- httpClose
+- httpConnect
+- httpConnectEncrypt
+- httpDecode64
+- httpDecode64_2
+- httpDelete
+- httpEncode64
+- httpEncode64_2
+- httpEncryption
+- httpError
+- httpFlush
+- httpFlushWrite
+- httpGet
+- httpGetAuthString
+- httpGetBlocking
+- httpGetCookie
+- httpGetDateString
+- httpGetDateString2
+- httpGetDateTime
+- httpGetFd
+- httpGetField
+- httpGetHostByName
+- httpGetHostname
+- httpGetLength
+- httpGetLength2
+- httpGetStatus
+- httpGetSubField
+- httpGetSubField2
+- httpGets
+- httpHead
+- httpInitialize
+- httpMD5
+- httpMD5Final
+- httpMD5String
+- httpOptions
+- httpPost
+- httpPut
+- httpRead
+- httpRead2
+- httpReconnect
+- httpSeparate
+- httpSeparate2
+- httpSeparateURI
+- httpSetAuthString
+- httpSetCookie
+- httpSetExpect
+- httpSetField
+- httpSetLength
+- httpStatus
+- httpTrace
+- httpUpdate
+- httpWait
+- httpWrite
+- httpWrite2
+- ippAddBoolean
+- ippAddBooleans
+- ippAddCollection
+- ippAddCollections
+- ippAddDate
+- ippAddInteger
+- ippAddIntegers
+- ippAddOctetString
+- ippAddRange
+- ippAddRanges
+- ippAddResolution
+- ippAddResolutions
+- ippAddSeparator
+- ippAddString
+- ippAddStrings
+- ippDateToTime
+- ippDelete
+- ippDeleteAttribute
+- ippErrorString
+- ippErrorValue
+- ippFindAttribute
+- ippFindNextAttribute
+- ippLength
+- ippNew
+- ippNewRequest
+- ippOpString
+- ippOpValue
+- ippPort
+- ippRead
+- ippReadFile
+- ippReadIO
+- ippSetPort
+- ippTimeToDate
+- ippWrite
+- ippWriteFile
+- ippWriteIO
+- Data Types
++
- http_addrlist_t
+- http_auth_t
+- http_encoding_t
+- http_encryption_t
+- http_t
+- ipp_attribute_t
+- ipp_iocb_t
+- ipp_request_t
+- ipp_t
+- ipp_uchar_t
+- ipp_value_t
+- Structures
++
- http_addrlist_s
+- ipp_attribute_s
+- ipp_s
+- Unions
++
- ipp_request_u
+- ipp_value_u
+- Constants
++
- http_auth_e
+- http_encoding_e
+- http_encryption_e
+- http_field_e
+- http_keepalive_e
+- http_state_e
+- http_status_e
+- http_uri_coding_e
+- http_uri_status_e
+- http_version_e
+- ipp_finish_e
+- ipp_jstate_e
+- ipp_op_e
+- ipp_orient_e
+- ipp_pstate_e
+- ipp_quality_e
+- ipp_res_e
+- ipp_state_e
+- ipp_status_e
+- ipp_tag_e
+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 constantCUPS_HTTP_DEFAULT
can be used with all of the +cups
functions to refer to the default CUPS server - the functions +create a per-threadhttp_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 theippDelete
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, thecupsDoRequest
+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
-- Functions
-- Structures
-- Types
-- Unions
-Enumerations
--
- -- http_auth_e
-- http_encoding_e
-- http_encryption_e
-- http_field_e
-- http_keepalive_e
-- http_state_e
-- http_status_e
-- http_uri_coding_e
-- http_uri_status_e
-- http_version_e
-- ipp_finish_e
-- ipp_jstate_e
-- ipp_op_e
-- ipp_orient_e
-- ipp_pstate_e
-- ipp_quality_e
-- ipp_res_e
-- ipp_state_e
-- ipp_status_e
-- ipp_tag_e
-http_auth_e
-Description
-HTTP authentication types -
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - HTTP_KEEPALIVE_OFF No keep alive support - - HTTP_KEEPALIVE_ON Use keep alive - http_state_e
-Description
--
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - HTTP_0_9 HTTP/0.9 - - HTTP_1_0 HTTP/1.0 - - HTTP_1_1 HTTP/1.1 - ipp_finish_e
-Description
--
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - IPP_PRINTER_IDLE Printer is idle - - IPP_PRINTER_PROCESSING Printer is working - - IPP_PRINTER_STOPPED Printer is stopped - ipp_quality_e
-Description
--
Values
-- --
- - Name Description - IPP_QUALITY_DRAFT Draft quality - - IPP_QUALITY_HIGH High quality - - IPP_QUALITY_NORMAL Normal quality - ipp_res_e
-Description
-Types and structures... -
Values
-- --
- - Name Description - IPP_RES_PER_CM Pixels per centimeter - - IPP_RES_PER_INCH Pixels per inch - ipp_state_e
-Description
--
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
--
- -- cupsDoAuthentication() CUPS 1.1.20
-- cupsDoFileRequest()
-- cupsDoIORequest() CUPS 1.3
-- cupsDoRequest()
-- cupsEncodeOptions()
-- cupsEncodeOptions2() CUPS 1.2
-- httpAddrAny() CUPS 1.2
-- httpAddrEqual() CUPS 1.2
-- httpAddrLength() CUPS 1.2
-- httpAddrLocalhost() CUPS 1.2
-- httpAddrLookup() CUPS 1.2
-- httpAddrString() CUPS 1.2
-- httpAssembleURI() CUPS 1.2
-- httpAssembleURIf() CUPS 1.2
-- httpBlocking()
-- httpCheck()
-- httpClearCookie() CUPS 1.1.19
-- httpClearFields()
-- httpClose()
-- httpConnect()
-- httpConnectEncrypt()
-- httpDecode64() DEPRECATED
-- httpDecode64_2() CUPS 1.1.21
-- httpDelete()
-- httpEncode64() DEPRECATED
-- httpEncode64_2() CUPS 1.1.21
-- httpEncryption()
-- httpError()
-- httpFlush()
-- httpFlushWrite() CUPS 1.2
-- httpGet()
-- httpGetAuthString() CUPS 1.3
-- httpGetBlocking() CUPS 1.2
-- httpGetCookie() CUPS 1.1.19
-- httpGetDateString() DEPRECATED
-- httpGetDateString2() CUPS 1.2
-- httpGetDateTime()
-- httpGetFd() CUPS 1.2
-- httpGetField()
-- httpGetHostByName() DEPRECATED
-- httpGetHostname() CUPS 1.2
-- httpGetLength() DEPRECATED
-- httpGetLength2() CUPS 1.2
-- httpGetStatus() CUPS 1.2
-- httpGetSubField() DEPRECATED
-- httpGetSubField2() CUPS 1.2
-- httpGets()
-- httpHead()
-- httpInitialize()
-- httpMD5()
-- httpMD5Final()
-- httpMD5String()
-- httpOptions()
-- httpPost()
-- httpPut()
-- httpRead() DEPRECATED
-- httpRead2() CUPS 1.2
-- httpReconnect()
-- httpSeparate() DEPRECATED
-- httpSeparate2() CUPS 1.1.21
-- httpSeparateURI() CUPS 1.2
-- httpSetAuthString() CUPS 1.3
-- httpSetCookie() CUPS 1.1.19
-- httpSetExpect() CUPS 1.2
-- httpSetField()
-- httpSetLength() CUPS 1.2
-- httpStatus()
-- httpTrace()
-- httpUpdate()
-- httpWait() CUPS 1.1.19
-- httpWrite() DEPRECATED
-- httpWrite2() CUPS 1.2
-- ippAddBoolean()
-- ippAddBooleans()
-- ippAddCollection() CUPS 1.1.19
-- ippAddCollections() CUPS 1.1.19
-- ippAddDate()
-- ippAddInteger()
-- ippAddIntegers()
-- ippAddOctetString() CUPS 1.2
-- ippAddRange()
-- ippAddRanges()
-- ippAddResolution()
-- ippAddResolutions()
-- ippAddSeparator()
-- ippAddString()
-- ippAddStrings()
-- ippDateToTime()
-- ippDelete()
-- ippDeleteAttribute() CUPS 1.1.19
-- ippErrorString()
-- ippErrorValue() CUPS 1.2
-- ippFindAttribute()
-- ippFindNextAttribute()
-- ippLength()
-- ippNew()
-- ippNewRequest() CUPS 1.2
-- ippOpString() CUPS 1.2
-- ippOpValue() CUPS 1.2
-- ippPort()
-- ippRead()
-- ippReadFile() CUPS 1.1.19
-- ippReadIO() CUPS 1.2
-- ippSetPort()
-- ippTimeToDate()
-- ippWrite()
-- ippWriteFile() CUPS 1.1.19
-- ippWriteIO() CUPS 1.2
-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
---
- - Name Description - http HTTP connection to server - method Request method (GET, POST, PUT) - resource Resource 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 +withNULL
names indicate a separator between the attributes of +each object. For example, the following code will list the jobs returned from +our previousget_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
andCUPS_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 theippDelete
+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 previousCUPS_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
orHTTP_UNAUTHORIZED
. The latter status +is returned when the request requires authentication of some sort. The +cupsDoAuthentication
function +must be called when your seeHTTP_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
---
- - Name Description - http HTTP connection to server - request IPP request - resource HTTP resource for POST - filename File 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
---
- - Name Description - http HTTP connection to server - 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 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
---
- - Name Description - http HTTP connection to server - request IPP request - resource HTTP 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
---
- - Name Description - ipp Request to add to - num_options Number of options - options Options 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
---
- - Name Description - ipp Request to add to - num_options Number of options - options Options - group_tag Group to encode Returns
-Nothing.
- -CUPS 1.2 httpAddrAny()
-Description
-Check for the "any" address. - - -
Syntax
--int
-
-httpAddrAny( - const http_addr_t * addr); -Arguments
---
- - Name Description - addr Address 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
---
- - Name Description - addr1 First address - addr2 Second 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
---
- - Name Description - addr Address Returns
-Length in bytes
- -CUPS 1.2 httpAddrLocalhost()
-Description
-Check for the local loopback address. - - -
Syntax
--int
-
-httpAddrLocalhost( - const http_addr_t * addr); -Arguments
---
- - Name Description - addr Address 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
---
- - Name Description - addr Address to lookup - name Host name buffer - namelen Size 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
---
- - Name Description - addr Address to convert - s String buffer - slen Length 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
---
- - Name Description - 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 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
---
- - Name Description - 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 Returns
-URI status
- -httpBlocking()
-Description
-Set blocking/non-blocking behavior on a connection. -
Syntax
--void
-
-httpBlocking( - http_t * http, - int b); -Arguments
---
- - Name Description - http HTTP connection - b 1 = 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP connection Returns
-Nothing.
- -httpClearFields()
-Description
-Clear HTTP request fields. -
Syntax
--void
-
-httpClearFields( - http_t * http); -Arguments
---
- - Name Description - http HTTP connection Returns
-Nothing.
- -httpClose()
-Description
-Close an HTTP connection... -
Syntax
--void
-
-httpClose( - http_t * http); -Arguments
---
- - Name Description - http HTTP connection Returns
-Nothing.
- -httpConnect()
-Description
-Connect to a HTTP server. -
Syntax
--http_t *
-
-httpConnect( - const char * host, - int port); -Arguments
---
- - Name Description - host Host to connect to - port Port 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
---
- - Name Description - host Host to connect to - port Port number - encryption Type 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
---
- - Name Description - out String to write to - in String 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
---
- - Name Description - out String to write to - outlen Size of output string - in String 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - out String to write to - in String 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
---
- - Name Description - out String to write to - outlen Size of output string - in String to read from - inlen Size 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
---
- - Name Description - http HTTP connection - e New 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
---
- - Name Description - http HTTP connection Returns
-Error code (errno) value
- -httpFlush()
-Description
-Flush data from a HTTP connection. -
Syntax
--void
-
-httpFlush( - http_t * http); -Arguments
---
- - Name Description - http HTTP connection Returns
-Nothing.
- -CUPS 1.2 httpFlushWrite()
-Description
-Flush data in write buffer. - - -
Syntax
--int
-
-httpFlushWrite( - http_t * http); -Arguments
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP 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
---
- - Name Description - t UNIX 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
---
- - Name Description - t UNIX time - s String buffer - slen Size 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
---
- - Name Description - s Date/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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP connection - field Field 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
---
- - Name Description - name Hostname 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
---
- - Name Description - http HTTP connection or NULL - s String buffer for name - slen Size 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP connection - field Field index - name Name of sub-field - value Value 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
---
- - Name Description - http HTTP connection - field Field index - name Name of sub-field - value Value string - valuelen Size 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
---
- - Name Description - line Line to read into - length Max length of buffer - http HTTP connection Returns
-Line or NULL
- -httpHead()
-Description
-Send a HEAD request to the server. -
Syntax
--int
-
-httpHead( - http_t * http, - const char * uri); -Arguments
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - username User name - realm Realm name - passwd Password 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
---
- - Name Description - nonce Server nonce value - method METHOD (GET, POST, etc.) - resource Resource 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
---
- - Name Description - sum MD5 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - http HTTP connection - buffer Buffer for data - length Maximum 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
---
- - Name Description - http HTTP connection - buffer Buffer for data - length Maximum number of bytes Returns
-Number of bytes read
- -httpReconnect()
-Description
-Reconnect to a HTTP server. -
Syntax
--int
-
-httpReconnect( - http_t * http); -Arguments
---
- - Name Description - http HTTP 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
---
- - Name Description - 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] 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
---
- - Name Description - 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 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
---
- - Name Description - 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 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
---
- - Name Description - http HTTP connection - scheme Auth scheme (NULL to clear it) - data Auth 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
---
- - Name Description - http Connection - cookie Cookie 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
---
- - Name Description - http HTTP connection - expect HTTP 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
---
- - Name Description - http HTTP connection - field Field index - value Value Returns
-Nothing.
- -CUPS 1.2 httpSetLength()
-Description
-Set the content-length and content-encoding. - - -
Syntax
--void
-
-httpSetLength( - http_t * http, - size_t length); -Arguments
---
- - Name Description - http HTTP connection - length Length (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
---
- - Name Description - status HTTP 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
---
- - Name Description - http HTTP connection - uri URI 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
---
- - Name Description - http HTTP 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
---
- - Name Description - http HTTP connection - msec Milliseconds 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
---
- - Name Description - http HTTP connection - buffer Buffer for data - length Number 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
---
- - Name Description - http HTTP connection - buffer Buffer for data - length Number 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - value Value 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - num_values Number of values - values Values 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - value Value 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - num_values Number of values - values Values 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - value Value 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
---
- - Name Description - ipp IPP message - group IPP group - type Type of attribute - name Name of attribute - value Value 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
---
- - Name Description - ipp IPP message - group IPP group - type Type of attribute - name Name of attribute - num_values Number of values - values Values 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - data octetString data - datalen Length 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - lower Lower value - upper Upper 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - num_values Number of values - lower Lower values - upper Upper 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
---
- - Name Description - ipp IPP message - group IPP group - name Name of attribute - units Units for resolution - xres X resolution - yres Y 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
---
- - Name Description - 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 Returns
-New attribute
- -ippAddSeparator()
-Description
-Add a group separator to an IPP message. -
Syntax
--ipp_attribute_t *
-
-ippAddSeparator( - ipp_t * ipp); -Arguments
---
- - Name Description - ipp IPP 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
---
- - Name Description - ipp IPP message - group IPP group - type Type of attribute - name Name of attribute - charset Character set - value Value 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
---
- - Name Description - ipp IPP message - group IPP group - type Type of attribute - name Name of attribute - num_values Number of values - charset Character set - values Values 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
---
- - Name Description - date RFC 1903 date info Returns
-UNIX time value
- -ippDelete()
-Description
-Delete an IPP message. -
Syntax
--void
-
-ippDelete( - ipp_t * ipp); -Arguments
---
- - Name Description - ipp IPP 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
---
- - Name Description - ipp IPP message - attr Attribute to delete Returns
-Nothing.
- -ippErrorString()
-Description
-Return a name for the given status code. -
Syntax
--const char *
-
-ippErrorString( - ipp_status_t error); -Arguments
---
- - Name Description - error Error 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
---
- - Name Description - name Name 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
---
- - Name Description - ipp IPP message - name Name of attribute - type Type 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
---
- - Name Description - ipp IPP message - name Name of attribute - type Type of attribute Returns
-Matching attribute
- -ippLength()
-Description
-Compute the length of an IPP message. -
Syntax
--size_t
-
-ippLength( - ipp_t * ipp); -Arguments
---
- - Name Description - ipp IPP 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
---
- - Name Description - op Operation 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
---
- - Name Description - op Operation 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
---
- - Name Description - name Textual 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
---
- - Name Description - http HTTP connection - ipp IPP 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
---
- - Name Description - fd HTTP data - ipp IPP 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
---
- - Name Description - src Data source - cb Read callback function - blocking Use blocking IO? - parent Parent request, if any - ipp IPP data Returns
-Current state
- -ippSetPort()
-Description
-Set the default port number. -
Syntax
--void
-
-ippSetPort( - int p); -Arguments
---
- - Name Description - p Port 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
---
- - Name Description - t UNIX 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
---
- - Name Description - http HTTP connection - ipp IPP 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
---
- - Name Description - fd HTTP data - ipp IPP 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
---
- - Name Description - dst Destination - cb Write callback function - blocking Use blocking IO? - parent Parent IPP message - ipp IPP data Returns
-Current state
- -Structures
--
- -- http_addrlist_s CUPS 1.2
-- ipp_attribute_s
-- ipp_s
-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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
--
- -- http_addrlist_t CUPS 1.2
-- http_auth_t
-- http_encoding_t
-- http_encryption_t
-- http_t
-- ipp_attribute_t
-- ipp_iocb_t CUPS 1.2
-- ipp_request_t
-- ipp_t
-- ipp_uchar_t
-- ipp_value_t
-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
-- ipp_value_u
-ipp_request_u
-Description
-Request Header -
Definition
--union ipp_request_u
-
-{
-};Members
-- --
- - Name Description 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
-+ +-
- - Name Description - 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
+Introduction to CUPS Programming + + + + + ++ + ++ + 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 @@ -Introduction to CUPS Programming
+ +++ +
+ + + +Headers +cups/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 Also +Programming: 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 APIContents
+ + + +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.
+PPD API - - - +PPD API + + + ++ +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 @@ -PPD API
+ +++ +
+ + + +Header +cups/ppd.h ++ +Library +-lcups ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ Reference: CUPS PPD SpecificationContents
++ +
+ -- Overview
+- Functions
+
+- cupsMarkOptions
+- ppdClose
+- ppdCollect
+- ppdCollect2
+- ppdConflicts
+- ppdEmit
+- ppdEmitAfterOrder
+- ppdEmitFd
+- ppdEmitJCL
+- ppdEmitJCLEnd
+- ppdEmitString
+- ppdErrorString
+- ppdFindAttr
+- ppdFindChoice
+- ppdFindCustomOption
+- ppdFindCustomParam
+- ppdFindMarkedChoice
+- ppdFindNextAttr
+- ppdFindOption
+- ppdFirstCustomParam
+- ppdFirstOption
+- ppdIsMarked
+- ppdLastError
+- ppdLocalize
+- ppdLocalizeIPPReason
+- ppdLocalizeMarkerName
+- ppdMarkDefaults
+- ppdMarkOption
+- ppdNextCustomParam
+- ppdNextOption
+- ppdOpen
+- ppdOpen2
+- ppdOpenFd
+- ppdOpenFile
+- ppdPageLength
+- ppdPageSize
+- ppdPageWidth
+- ppdSetConformance
+- Data Types
++
- ppd_attr_t
+- ppd_choice_t
+- ppd_conform_t
+- ppd_const_t
+- ppd_coption_t
+- ppd_cparam_t
+- ppd_cplimit_t
+- ppd_cptype_t
+- ppd_cpvalue_t
+- ppd_emul_t
+- ppd_file_t
+- ppd_group_t
+- ppd_option_t
+- ppd_profile_t
+- ppd_section_t
+- ppd_size_t
+- ppd_ui_t
+- Structures
++
- ppd_attr_s
+- ppd_choice_s
+- ppd_const_s
+- ppd_coption_s
+- ppd_cparam_s
+- ppd_emul_s
+- ppd_file_s
+- ppd_group_s
+- ppd_option_s
+- ppd_profile_s
+- ppd_size_s
+- Unions
++
- ppd_cplimit_u
+- ppd_cpvalue_u
+- Constants
++
- ppd_conform_e
+- ppd_cptype_e
+- ppd_cs_e
+- ppd_section_e
+- ppd_status_e
+- ppd_ui_e
+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
-- Functions
-- Structures
-- Types
-- Unions
-Enumerations
--
- -- ppd_conform_e
-- ppd_cptype_e CUPS 1.2
-- ppd_cs_e
-- ppd_section_e
-- ppd_status_e
-- ppd_ui_e
-ppd_conform_e
-Description
--
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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()
-- ppdCollect()
-- ppdCollect2() CUPS 1.2
-- ppdConflicts()
-- ppdEmit()
-- ppdEmitAfterOrder() CUPS 1.2
-- ppdEmitFd()
-- ppdEmitJCL()
-- ppdEmitJCLEnd() CUPS 1.2
-- ppdEmitString() CUPS 1.2
-- ppdErrorString() CUPS 1.1.19
-- ppdFindAttr() CUPS 1.1.19
-- ppdFindChoice()
-- ppdFindCustomOption() CUPS 1.2
-- ppdFindCustomParam() CUPS 1.2
-- ppdFindMarkedChoice()
-- ppdFindNextAttr() CUPS 1.1.19
-- ppdFindOption()
-- ppdFirstCustomParam() CUPS 1.2
-- ppdFirstOption() CUPS 1.2
-- ppdIsMarked()
-- ppdLastError() CUPS 1.1.19
-- ppdLocalize() CUPS 1.2
-- ppdLocalizeIPPReason() CUPS 1.3
-- ppdMarkDefaults()
-- ppdMarkOption()
-- ppdNextCustomParam() CUPS 1.2
-- ppdNextOption() CUPS 1.2
-- ppdOpen()
-- ppdOpen2() CUPS 1.2
-- ppdOpenFd()
-- ppdOpenFile()
-- ppdPageLength()
-- ppdPageSize()
-- ppdPageWidth()
-- ppdSetConformance() CUPS 1.1.20
-ppdClose()
-Description
-Free all memory used by the PPD file. -
Syntax
--void
-
-ppdClose( - ppd_file_t * ppd); -Arguments
---
- - Name Description - ppd PPD 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
---
- - Name Description - ppd PPD file data - section Section to collect - choices Pointers 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
---
- - Name Description - ppd PPD file data - section Section to collect - min_order Minimum OrderDependency value - choices Pointers 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
---
- - Name Description - ppd PPD 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
---
- - Name Description - ppd PPD file record - fp File to write to - section Section 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
---
- - Name Description - ppd PPD file record - fp File to write to - section Section to write - limit Non-zero to use min_order - min_order Lowest 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
---
- - Name Description - ppd PPD file record - fd File to write to - section Section 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
---
- - Name Description - ppd PPD file record - fp File to write to - job_id Job ID - user Username - title Title 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
---
- - Name Description - ppd PPD file record - fp File 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 orNULL
+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 passNULL
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. +Thecustom_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 appd_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 codeDiscussion
+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
---
- - Name Description - ppd PPD file record - section Section to write - min_order Lowest 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
---
- - Name Description - status PPD 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
---
- - Name Description - ppd PPD file data - name Attribute name - spec Specifier 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
---
- - Name Description - o Pointer to option - choice Name 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
---
- - Name Description - ppd PPD file - keyword Custom 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
---
- - Name Description - opt Custom option - name Parameter 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
---
- - Name Description - ppd PPD file - option Keyword/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
---
- - Name Description - ppd PPD file data - name Attribute name - spec Specifier 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
---
- - Name Description - ppd PPD file data - option Option/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
---
- - Name Description - opt Custom 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
---
- - Name Description - ppd PPD 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
---
- - Name Description - ppd PPD file data - option Option/Keyword name - choice Choice 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
---
- - Name Description - line Line 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 foundppdFindChoice
+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 foundppdFindOption
+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
---
- - Name Description - ppd PPD 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
---
- - Name Description - 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 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
---
- - Name Description - ppd PPD 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
---
- - Name Description - ppd PPD file record - option Keyword - choice Option 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
---
- - Name Description - opt Custom 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
---
- - Name Description - ppd PPD file Returns
-Next option or NULL
- -ppdOpen()
-Description
-Read a PPD file into memory. -
Syntax
--ppd_file_t *
-
-ppdOpen( - FILE * fp); -Arguments
---
- - Name Description - fp File 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
---
- - Name Description - fp File to read from Returns
-PPD file record
- -ppdOpenFd()
-Description
-Read a PPD file into memory. -
Syntax
--ppd_file_t *
-
-ppdOpenFd( - int fd); -Arguments
---
- - Name Description - fd File to read from Returns
-PPD file record
- -ppdOpenFile()
-Description
-Read a PPD file into memory. -
Syntax
--ppd_file_t *
-
-ppdOpenFile( - const char * filename); -Arguments
---
- - Name Description - filename File 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
---
- - Name Description - ppd PPD file - name Size 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
---
- - Name Description - ppd PPD file record - name Size 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
---
- - Name Description - ppd PPD file record - name Size 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
---
- - Name Description - c Conformance level Returns
-Nothing.
- -Structures
--
- -- ppd_attr_s CUPS 1.1.19
-- ppd_choice_s
-- ppd_coption_s CUPS 1.2
-- ppd_cparam_s CUPS 1.2
-- ppd_emul_s
-- ppd_file_s
-- ppd_group_s
-- ppd_option_s
-- ppd_profile_s
-- ppd_size_s
-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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
--
- -- ppd_attr_t CUPS 1.1.19
-- ppd_choice_t
-- ppd_const_t
-- ppd_coption_t CUPS 1.2
-- ppd_cparam_t CUPS 1.2
-- ppd_cplimit_t CUPS 1.2
-- ppd_cptype_t CUPS 1.2
-- ppd_cpvalue_t CUPS 1.2
-- ppd_emul_t
-- ppd_file_t
-- ppd_group_t
-- ppd_option_t
-- ppd_profile_t
-- ppd_section_t
-- ppd_size_t
-- ppd_ui_t
-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
--
- -- ppd_cplimit_u CUPS 1.2
-- ppd_cpvalue_u CUPS 1.2
-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
-- --
- - Name Description - 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
-+string or attribute value. Otherwise the corresponding URI is returned.-
- - Name Description - 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 -
+
+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 foundDiscussion
+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
+Raster API - - - +Raster API + + + ++ + +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. -Raster API
+ +++ +
+ + + +Header +cups/raster.h ++ +Library +-lcupsimage ++ + +See Also +Programming: Introduction to CUPS Programming +
+ Programming: CUPS API
+ Programming: PPD API
+ References: CUPS PPD SpecificationContents
++ +
-- Overview
+- Functions +
- Data Types
+- Structures
+- Constants
++
- cups_adv_e
+- cups_bool_e
+- cups_cspace_e
+- cups_cut_e
+- cups_edge_e
+- cups_jog_e
+- cups_mode_e
+- cups_order_e
+- cups_orient_e
+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 thecupsRasterOpen
+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. Afor
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
-- Functions
-- Structures
-- Types
-Enumerations
--
- -- cups_adv_e
-- cups_bool_e
-- cups_cspace_e
-- cups_cut_e
-- cups_edge_e
-- cups_jog_e
-- cups_mode_e
-- cups_order_e
-- cups_orient_e
-cups_adv_e
-Description
-AdvanceMedia attribute values -
Values
-- --
- - Name Description - 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
-- --
- - Name Description - CUPS_FALSE Logical false - - CUPS_TRUE Logical true - cups_cspace_e
-Description
--
Values
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- --
- - Name Description - 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()
-- cupsRasterInterpretPPD() CUPS 1.2
-- cupsRasterOpen()
-- cupsRasterReadHeader()
-- cupsRasterReadHeader2() CUPS 1.2
-- cupsRasterReadPixels()
-- cupsRasterWriteHeader()
-- cupsRasterWriteHeader2() CUPS 1.2
-- cupsRasterWritePixels()
-cupsRasterClose()
-Description
-Close a raster stream. -
Syntax
--void
-
-cupsRasterClose( - cups_raster_t * r); -Arguments
---
- - Name Description - r Stream 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
andppdMarkOption
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 thecups_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
---
- - Name Description - h Page header - ppd PPD file - num_options Number of options - options Options - func Optional 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
---
- - Name Description - fd File descriptor - mode Mode 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
---
- - Name Description - r Raster stream - h Pointer 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
---
- - Name Description - r Raster stream - h Pointer 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
---
- - Name Description - r Raster stream - p Pointer to pixel buffer - len Number 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
---
- - Name Description - r Raster stream - h Raster 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
---
- - Name Description - r Raster stream - h Raster 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
---
- - Name Description - r Raster stream - p Bytes to write - len Number of bytes to write Returns
-Number of bytes written
- -Structures
--
- -- cups_page_header2_s CUPS 1.2
-- cups_page_header_s
-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
-- --
- - Name Description - 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
-- --
- - Name Description - 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
-- cups_page_header2_t CUPS 1.2
-- cups_page_header_t
-- cups_raster_t
-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
, andstopped
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
++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 lab999diff --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:
+ +
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 +
*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: "" ++
*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"
Header | +cups/raster.h | +
---|---|
Library | +-lcupsimage | +
See Also | +Programming: Introduction to CUPS Programming + Programming: CUPS API + Programming: PPD API + References: CUPS PPD Specification |
+
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.
-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. Afor
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.5