Michael R Sweet
Copyright 2007-2017 by Apple Inc.
The IPP Sample project provides APIs for IPP client and server applications in the "cups" library. Most library functions are accessed by including the <cups/cups.h> header, while the raster functions are found in the <cups/raster.h> header.
The library can be used from any C, C++, or Objective C program. The method of compiling against the library varies depending on the operating system and installation of the IPP Sample project.
The following simple program lists the available printers on the network:
#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); }
The CUPS API provides the convenience functions needed to support applications, filters, printer drivers, and backends that need to interface with the CUPS scheduler.
CUPS is based on the Internet Printing Protocol ("IPP"), which allows clients (applications) to communicate with a server (the scheduler) to get a list of printers, send print jobs, and so forth. You identify which server you want to communicate with using a pointer to the opaque structure http_t
. All of the examples in this document use the CUPS_HTTP_DEFAULT
constant, referring to the default connection to the scheduler. The HTTP and IPP APIs document provides more information on server connections.
Printers and classes (collections of printers) are accessed through the cups_dest_t
structure which includes the name (name
), instance (instance
- a way of selecting certain saved options/settings), 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> cups_dest_t *dests; int num_dests = cupsGetDests(&dests); cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests); /* do something with dest */ cupsFreeDests(num_dests, dests);
Passing NULL
to cupsGetDest
for the destination name will return the default destination. Similarly, passing a NULL
instance will return the default instance for that destination.
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" | "true" if the destination is accepting new jobs, "false" if not. |
"printer-is-shared" | "true" if the destination is being shared with other computers, "false" 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 are stored in arrays of cups_option_t
structures. Each option has a name (name
) and value (value
) associated with it. The cups_dest_t
num_options
and options
members contain the default options for a particular destination, along with several informational attributes about the destination as shown in Table 1. The cupsGetOption
function gets the value for the named option. For example, the following code lists the available destinations and their human-readable descriptions:
#include <cups/cups.h> cups_dest_t *dests; int num_dests = cupsGetDests(&dests); cups_dest_t *dest; int i; const char *value; for (i = num_dests, dest = dests; i > 0; i --, dest ++) if (dest->instance == NULL) { value = cupsGetOption("printer-info", dest->num_options, dest->options); printf("%s (%s)\n", dest->name, value ? value : "no description"); } cupsFreeDests(num_dests, dests);
You can create your own option arrays using the cupsAddOption
function, which adds a single named option to an array:
#include <cups/cups.h> int num_options = 0; cups_option_t *options = NULL; /* The returned num_options value is updated as needed */ num_options = cupsAddOption("first", "value", num_options, &options); /* This adds a second option value */ num_options = cupsAddOption("second", "value", num_options, &options); /* This replaces the first option we added */ num_options = cupsAddOption("first", "new value", num_options, &options);
Use a for
loop to copy the options from a destination:
#include <cups/cups.h> int i; int num_options = 0; cups_option_t *options = NULL; cups_dest_t *dest; for (i = 0; i < dest->num_options; i ++) num_options = cupsAddOption(dest->options[i].name, dest->options[i].value, num_options, &options);
Use the cupsFreeOptions
function to free the options array when you are done using it:
cupsFreeOptions(num_options, options);
Print jobs are identified by a locally-unique job ID number from 1 to 231-1 and have options and one or more files for printing to a single destination. The cupsPrintFile
function creates a new job with one file. The following code prints the CUPS test page file:
#include <cups/cups.h> cups_dest_t *dest; int num_options; cups_option_t *options; int job_id; /* Print a single file */ job_id = cupsPrintFile(dest->name, "/usr/share/cups/data/testprint.ps", "Test Print", num_options, options);
The cupsPrintFiles
function creates a job with multiple files. The files are provided in a char *
array:
#include <cups/cups.h> cups_dest_t *dest; int num_options; cups_option_t *options; int job_id; char *files[3] = { "file1.pdf", "file2.pdf", "file3.pdf" }; /* Print three files */ job_id = cupsPrintFiles(dest->name, 3, files, "Test Print", num_options, options);
Finally, the cupsCreateJob
function creates a new job with no files in it. Files are added using the cupsStartDocument
, cupsWriteRequestData
, and cupsFinishDocument
functions. The following example creates a job with 10 text files for printing:
#include <cups/cups.h> cups_dest_t *dest; int num_options; cups_option_t *options; int job_id; int i; char buffer[1024]; /* Create the job */ job_id = cupsCreateJob(CUPS_HTTP_DEFAULT, dest->name, "10 Text Files", num_options, options); /* If the job is created, add 10 files */ if (job_id > 0) { for (i = 1; i <= 10; i ++) { snprintf(buffer, sizeof(buffer), "file%d.txt", i); cupsStartDocument(CUPS_HTTP_DEFAULT, dest->name, job_id, buffer, CUPS_FORMAT_TEXT, i == 10); snprintf(buffer, sizeof(buffer), "File %d\n" "\n" "One fish,\n" "Two fish,\n "Red fish,\n "Blue fish\n", i); /* cupsWriteRequestData can be called as many times as needed */ cupsWriteRequestData(CUPS_HTTP_DEFAULT, buffer, strlen(buffer)); cupsFinishDocument(CUPS_HTTP_DEFAULT, dest->name); } }
Once you have created a job, you can monitor its status using the cupsGetJobs
function, which returns an array of cups_job_t
structures. Each contains the job ID (id
), destination name (dest
), title (title
), and other information associated with the job. The job array is freed using the cupsFreeJobs
function. The following example monitors a specific job ID, showing the current job state once every 5 seconds until the job is completed:
#include <cups/cups.h> cups_dest_t *dest; int job_id; int num_jobs; cups_job_t *jobs; int i; ipp_jstate_t job_state = IPP_JOB_PENDING; while (job_state < IPP_JOB_STOPPED) { /* Get my jobs (1) with any state (-1) */ num_jobs = cupsGetJobs(&jobs, dest->name, 1, -1); /* Loop to find my job */ job_state = IPP_JOB_COMPLETED; for (i = 0; i < num_jobs; i ++) if (jobs[i].id == job_id) { job_state = jobs[i].state; break; } /* Free the job array */ cupsFreeJobs(num_jobs, jobs); /* Show the current state */ switch (job_state) { case IPP_JOB_PENDING : printf("Job %d is pending.\n", job_id); break; case IPP_JOB_HELD : printf("Job %d is held.\n", job_id); break; case IPP_JOB_PROCESSING : printf("Job %d is processing.\n", job_id); break; case IPP_JOB_STOPPED : printf("Job %d is stopped.\n", job_id); break; case IPP_JOB_CANCELED : printf("Job %d is canceled.\n", job_id); break; case IPP_JOB_ABORTED : printf("Job %d is aborted.\n", job_id); break; case IPP_JOB_COMPLETED : printf("Job %d is completed.\n", job_id); break; } /* Sleep if the job is not finished */ if (job_state < IPP_JOB_STOPPED) sleep(5); }
To cancel a job, use the cupsCancelJob
function with the job ID:
#include <cups/cups.h> cups_dest_t *dest; int job_id; cupsCancelJob(dest->name, job_id);
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());
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.
The CUPS HTTP and IPP APIs provide low-level access to the HTTP and IPP protocols and CUPS scheduler. They are typically used by monitoring and administration programs to perform specific functions not supported by the high-level CUPS API functions.
The HTTP APIs use an opaque structure called http_t
to manage connections to a particular HTTP or IPP server. The httpConnectEncrypt
function is used to create an instance of this structure for a particular server. The constant CUPS_HTTP_DEFAULT
can be used with all of the cups
functions to refer to the default CUPS server - the functions create a per-thread http_t
as needed.
The IPP APIs use two opaque structures for requests (messages sent to the CUPS scheduler) and responses (messages sent back to your application from the scheduler). The ipp_t
type holds a complete request or response and is allocated using the ippNew
or ippNewRequest
functions and freed using the ippDelete
function.
The second opaque structure is called ipp_attribute_t
and holds a single IPP attribute which consists of a group tag (ippGetGroupTag
), a value type tag (ippGetValueTag
), the attribute name (ippGetName
), and 1 or more values (ippGetCount
, ippGetBoolean
, ippGetCollection
, ippGetDate
, ippGetInteger
, ippGetRange
, ippGetResolution
, and ippGetString
). Attributes are added to an ipp_t
pointer using one of the ippAdd
functions. For example, use ippAddString
to add the "printer-uri" and "requesting-user-name" string attributes to a request:
ipp_t *request = ippNewRequest(IPP_GET_JOBS); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://localhost/printers/"); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser());
Once you have created an IPP request, use the cups
functions to send the request to and read the response from the server. For example, the cupsDoRequest
function can be used for simple query operations that do not involve files:
#include <cups/cups.h> ipp_t *get_jobs(void) { ipp_t *request = ippNewRequest(IPP_GET_JOBS); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, "ipp://localhost/printers/"); 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 and returns an IPP response 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 = ippFirstAttribute(response); attr != NULL; attr = ippNextAttribute(response)) if (ippGetName(attr) == NULL) puts("--SEPARATOR--"); else puts(ippGetName(attr));
The for
loop approach is normally used when collecting attributes for multiple objects (jobs, printers, etc.) in a response. Attributes with NULL
names indicate a separator between the attributes of each object. For example, the following code will list the jobs returned from our previous get_jobs
example code:
ipp_t *response = get_jobs(); if (response != NULL) { ipp_attribute_t *attr; const char *attrname; int job_id = 0; const char *job_name = NULL; const char *job_originating_user_name = NULL; puts("Job ID Owner Title"); puts("------ ---------------- ---------------------------------"); for (attr = ippFirstAttribute(response); attr != NULL; attr = ippNextAttribute(response)) { /* Attributes without names are separators between jobs */ attrname = ippGetName(attr); if (attrname == NULL) { if (job_id > 0) { if (job_name == NULL) job_name = "(withheld)"; if (job_originating_user_name == NULL) job_originating_user_name = "(withheld)"; printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); } job_id = 0; job_name = NULL; job_originating_user_name = NULL; continue; } else if (!strcmp(attrname, "job-id") && ippGetValueTag(attr) == IPP_TAG_INTEGER) job_id = ippGetInteger(attr, 0); else if (!strcmp(attrname, "job-name") && ippGetValueTag(attr) == IPP_TAG_NAME) job_name = ippGetString(attr, 0, NULL); else if (!strcmp(attrname, "job-originating-user-name") && ippGetValueTag(attr) == IPP_TAG_NAME) job_originating_user_name = ippGetString(attr, 0, NULL); } if (job_id > 0) { if (job_name == NULL) job_name = "(withheld)"; if (job_originating_user_name == NULL) job_originating_user_name = "(withheld)"; printf("%5d %-16s %s\n", job_id, job_originating_user_name, job_name); } }
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);
The cupsDoFileRequest
and cupsDoIORequest
functions are used for requests involving files. The cupsDoFileRequest
function attaches the named file to a request and is typically used when sending a print file or changing a printer's PPD file:
const char *filename = "/usr/share/cups/data/testprint.ps"; const char *name = "Foo"; char uri[1024]; char resource[1024]; ipp_t *request = ippNewRequest(IPP_PRINT_JOB); ipp_t *response; /* Use httpAssembleURIf for the printer-uri string */ httpAssembleURIf(HTTP_URI_CODING_ALL, uri, sizeof(uri), "ipp", NULL, cupsServer(), ippPort(), "/printers/%s", name); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", NULL, uri); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", NULL, cupsUser()); ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name", NULL, "testprint.ps"); /* Use snprintf for the resource path */ snprintf(resource, sizeof(resource), "/printers/%s", name); response = cupsDoFileRequest(CUPS_HTTP_DEFAULT, request, resource, filename);
The cupsDoIORequest
function optionally attaches a file to the request and optionally saves a file in the response from the server. It is used when using a pipe for the request attachment or when using a request that returns a file, currently only CUPS_GET_DOCUMENT
and CUPS_GET_PPD
. For example, the following code will download the PPD file for the sample HP LaserJet printer driver:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); response = cupsDoIORequest(CUPS_HTTP_DEFAULT, request, "/", -1, tempfd);
The example passes -1
for the input file descriptor to specify that no file is to be attached to the request. The PPD file attached to the response is written to the temporary file descriptor we created using the cupsTempFd
function.
The cupsSendRequest
and cupsGetResponse
support asynchronous communications with the server. Unlike the other request functions, the IPP request is not automatically freed, so remember to free your request with the ippDelete
function.
File data is attached to the request using the cupsWriteRequestData
function, while file data returned from the server is read using the cupsReadResponseData
function. We can rewrite the previous CUPS_GET_PPD
example to use the asynchronous functions quite easily:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); if (cupsSendRequest(CUPS_HTTP_DEFAULT, request, "/") == HTTP_CONTINUE) { response = cupsGetResponse(CUPS_HTTP_DEFAULT, "/"); if (response != NULL) { ssize_t bytes; char buffer[8192]; while ((bytes = cupsReadResponseData(CUPS_HTTP_DEFAULT, buffer, sizeof(buffer))) > 0) write(tempfd, buffer, bytes); } } /* Free the request! */ ippDelete(request);
The cupsSendRequest
function returns the initial HTTP request status, typically either HTTP_CONTINUE
or HTTP_UNAUTHORIZED
. The latter status is returned when the request requires authentication of some sort. The cupsDoAuthentication
function must be called when your see HTTP_UNAUTHORIZED
and the request re-sent. We can add authentication support to our example code by using a do ... while
loop:
char tempfile[1024]; int tempfd; ipp_t *request = ippNewRequest(CUPS_GET_PPD); ipp_t *response; http_status_t status; ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "ppd-name", NULL, "laserjet.ppd"); tempfd = cupsTempFd(tempfile, sizeof(tempfile)); /* Loop for authentication */ do { status = 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);
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.
Two kinds of CUPS filters use the CUPS raster API - raster image processor (RIP) filters such as pstoraster
and cgpdftoraster
(macOS) that produce CUPS raster files and printer driver filters that convert CUPS raster files into a format usable by the printer. Printer driver filters are by far the most common.
CUPS raster files (application/vnd.cups-raster
) consists of a stream of raster page descriptions produced by one of the RIP filters such as pstoraster, imagetoraster, or cgpdftoraster. CUPS raster files are referred to using the cups_raster_t
type and are opened using the cupsRasterOpen
function. For example, to read raster data from the standard input, open file descriptor 0:
#include <cups/raster.h>> cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ);
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; while (cupsRasterReadHeader2(ras, &header)) { /* setup this page */ /* read raster data */ /* finish this page */ }
After the page dictionary comes the page data which is a full-resolution, possibly compressed bitmap representing the page in the printer's output colorspace. You read uncompressed raster data using the cupsRasterReadPixels
function. A for
loop is normally used to read the page one line at a time:
#include <cups/raster.h>> cups_raster_t *ras = cupsRasterOpen(0, CUPS_RASTER_READ); cups_page_header2_t header; int page = 0; int y; char *buffer; 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 on stdout */ } /* 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);
Add a destination to the list of destinations.
int cupsAddDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULL
for none/primaryNew number of destinations
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
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.
Add an option to an option array.
int cupsAddOption (
const char *name,
const char *value,
int num_options,
cups_option_t **options
);
Number of options
New option arrays can be initialized simply by passing 0 for the "num_options" parameter.
Include necessary headers...
ipp_status_t cupsCancelDestJob (
http_t *http,
cups_dest_t *dest,
int job_id
);
Cancel a job on a destination.
The "job_id" is the number returned by cupsCreateDestJob.
Returns IPP_STATUS_OK
on success and
IPP_STATUS_ERRPR_NOT_AUTHORIZED
or
IPP_STATUS_ERROR_FORBIDDEN
on failure.
Cancel a print job on the default server.
int cupsCancelJob (
const char *name,
int job_id
);
CUPS_JOBID_CURRENT
for the current job, or CUPS_JOBID_ALL
for all jobs1 on success, 0 on failure
Pass CUPS_JOBID_ALL
to cancel all jobs or CUPS_JOBID_CURRENT
to cancel the current job on the named destination.
Use the cupsLastError
and cupsLastErrorString
functions to get
the cause of any failure.
Cancel or purge a print job.
ipp_status_t cupsCancelJob2 (
http_t *http,
const char *name,
int job_id,
int purge
);
CUPS_HTTP_DEFAULT
CUPS_JOBID_CURRENT
for the current job, or CUPS_JOBID_ALL
for all jobsIPP status
Canceled jobs remain in the job history while purged jobs are removed
from the job history.
Pass CUPS_JOBID_ALL
to cancel all jobs or CUPS_JOBID_CURRENT
to cancel the current job on the named destination.
Use the cupsLastError
and cupsLastErrorString
functions to get
the cause of any failure.
Check that the option and value are supported by the destination.
int cupsCheckDestSupported (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option,
const char *value
);
1 if supported, 0 otherwise
Returns 1 if supported, 0 otherwise.
Close a job and start printing.
ipp_status_t cupsCloseDestJob (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info,
int job_id
);
IPP status code
Use when the last call to cupsStartDocument passed 0 for "last_document".
"job_id" is the job ID returned by cupsCreateDestJob. Returns IPP_STATUS_OK
on success.
Connect to the server for a destination.
http_t *cupsConnectDest (
cups_dest_t *dest,
unsigned flags,
int msec,
int *cancel,
char *resource,
size_t resourcesize,
cups_dest_cb_t cb,
void *user_data
);
Connection to server or NULL
Connect to the destination, returning a new http_t connection object and optionally the resource path to use for the destination. These calls will block until a connection is made, the timeout expires, the integer pointed to by "cancel" is non-zero, or the callback function (or block) returns 0, The caller is responsible for calling httpClose() on the returned object.
Connect to the server for a destination.
http_t *cupsConnectDestBlock (
cups_dest_t *dest,
unsigned flags,
int msec,
int *cancel,
char *resource,
size_t resourcesize,
cups_dest_block_t block
);
Connection to server or NULL
Connect to the destination, returning a new http_t connection object and optionally the resource path to use for the destination. These calls will block until a connection is made, the timeout expires, the integer pointed to by "cancel" is non-zero, or the callback function (or block) returns 0, The caller is responsible for calling httpClose() on the returned object.
Callback block
int cupsCopyDest (
cups_dest_t *dest,
int num_dests,
cups_dest_t **dests
);
Copy a destination.
Make a copy of the destination to an array of destinations (or just a single copy) - for use with the cupsEnumDests* functions. The caller is responsible for calling cupsFreeDests() on the returned object(s).
Get conflicts and resolutions for a new option/value pair.
int cupsCopyDestConflicts (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int num_options,
cups_option_t *options,
const char *new_option,
const char *new_value,
int *num_conflicts,
cups_option_t **conflicts,
int *num_resolved,
cups_option_t **resolved
);
1 if there is a conflict, 0 if none, -1 on error
"num_options" and "options" represent the currently selected options by the
user. "new_option" and "new_value" are the setting the user has just
changed.
Returns 1 if there is a conflict, 0 if there are no conflicts, and -1 if
there was an unrecoverable error such as a resolver loop.
If "num_conflicts" and "conflicts" are not NULL
, they are set to
contain the list of conflicting option/value pairs. Similarly, if
"num_resolved" and "resolved" are not NULL
they will be set to the
list of changes needed to resolve the conflict.
If cupsCopyDestConflicts returns 1 but "num_resolved" and "resolved" are set
to 0 and NULL
, respectively, then the conflict cannot be resolved.
Get the supported values/capabilities for the destination.
cups_dinfo_t *cupsCopyDestInfo (
http_t *http,
cups_dest_t *dest
);
Destination information
The caller is responsible for calling cupsFreeDestInfo
on the return
value. NULL
is returned on error.
Create a job on a destination.
ipp_status_t cupsCreateDestJob (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info,
int *job_id,
const char *title,
int num_options,
cups_option_t *options
);
IPP status code
Returns IPP_STATUS_OK
or IPP_STATUS_OK_SUBST
on success, saving the job ID
in the variable pointed to by "job_id".
Create an empty job for streaming.
int cupsCreateJob (
http_t *http,
const char *name,
const char *title,
int num_options,
cups_option_t *options
);
CUPS_HTTP_DEFAULT
Job ID or 0 on error
Use this function when you want to stream print data using the
cupsStartDocument
, cupsWriteRequestData
, and
cupsFinishDocument
functions. If you have one or more files to
print, use the cupsPrintFile2
or cupsPrintFiles2
function
instead.
Authenticate a request.
int cupsDoAuthentication (
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT
0 on success, -1 on error
This function should be called in response to a HTTP_STATUS_UNAUTHORIZED
status, prior to resubmitting your request.
Do an IPP request with a file.
ipp_t *cupsDoFileRequest (
http_t *http,
ipp_t *request,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULT
NULL
for noneResponse data
This function sends the IPP request and attached file to the specified
server, retrying and authenticating as necessary. The request is freed with
ippDelete
.
Do an IPP request with file descriptors.
ipp_t *cupsDoIORequest (
http_t *http,
ipp_t *request,
const char *resource,
int infile,
int outfile
);
CUPS_HTTP_DEFAULT
Response data
This function sends the IPP request with the optional input file "infile" to
the specified server, retrying and authenticating as necessary. The request
is freed with ippDelete
.
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.
Do an IPP request.
ipp_t *cupsDoRequest (
http_t *http,
ipp_t *request,
const char *resource
);
CUPS_HTTP_DEFAULT
Response data
This function sends the IPP request to the specified server, retrying
and authenticating as necessary. The request is freed with ippDelete
.
Encode printer options into IPP attributes.
void cupsEncodeOptions (
ipp_t *ipp,
int num_options,
cups_option_t *options
);
This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.
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
);
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.
Get the current encryption settings.
http_encryption_t cupsEncryption (void);
Encryption settings
The default encryption setting comes from the CUPS_ENCRYPTION
environment variable, then the ~/.cups/client.conf file, and finally the
/etc/cups/client.conf file. If not set, the default is
HTTP_ENCRYPTION_IF_REQUESTED
.
Note: The current encryption setting is tracked separately for each thread
in a program. Multi-threaded programs that override the setting via the
cupsSetEncryption
function need to do so in each thread for the same
setting to be used.
Enumerate available destinations with a callback function.
int cupsEnumDests (
unsigned flags,
int msec,
int *cancel,
cups_ptype_t type,
cups_ptype_t mask,
cups_dest_cb_t cb,
void *user_data
);
1 on success, 0 on failure
Destinations are enumerated from one or more sources. The callback function
receives the user_data
pointer, destination name, instance, number of
options, and options which can be used as input to the cupsAddDest
function. The function must return 1 to continue enumeration or 0 to stop.
Enumeration happens on the current thread and does not return until all
destinations have been enumerated or the callback function returns 0.
Enumerate available destinations with a block.
int cupsEnumDestsBlock (
unsigned flags,
int timeout,
int *cancel,
cups_ptype_t type,
cups_ptype_t mask,
cups_dest_block_t block
);
1 on success, 0 on failure
Destinations are enumerated from one or more sources. The block receives the
destination name, instance, number of options, and options which can be used
as input to the cupsAddDest
function. The block must return 1 to
continue enumeration or 0 to stop.
Enumeration happens on the current thread and does not return until all
destinations have been enumerated or the block returns 0.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestDefault (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestReady (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Find the default value(s) for the given option.
ipp_attribute_t *cupsFindDestSupported (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Default attribute or NULL
for none
The returned value is an IPP attribute. Use the ippGetBoolean
,
ippGetCollection
, ippGetCount
, ippGetDate
,
ippGetInteger
, ippGetOctetString
, ippGetRange
,
ippGetResolution
, ippGetString
, and ippGetValueTag
functions to inspect the default value(s) as needed.
Finish the current document.
ipp_status_t cupsFinishDestDocument (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info
);
Status of document submission
Returns IPP_STATUS_OK
or IPP_STATUS_OK_SUBST
on success.
Finish sending a document.
ipp_status_t cupsFinishDocument (
http_t *http,
const char *name
);
CUPS_HTTP_DEFAULT
Status of document submission
The document must have been started using cupsStartDocument
.
Free destination information obtained using
cupsCopyDestInfo
.
void cupsFreeDestInfo (
cups_dinfo_t *dinfo
);
Free the memory used by the list of destinations.
void cupsFreeDests (
int num_dests,
cups_dest_t *dests
);
Free memory used by job data.
void cupsFreeJobs (
int num_jobs,
cups_job_t *jobs
);
Free all memory used by options.
void cupsFreeOptions (
int num_options,
cups_option_t *options
);
Get a list of printer classes from the default server.
int cupsGetClasses (
char ***classes
);
Number of classes
This function is deprecated and no longer returns a list of printer
classes - use cupsGetDests
instead.
Get the default printer or class for the default server.
const char *cupsGetDefault (void);
Default printer or NULL
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.
Get the default printer or class for the specified server.
const char *cupsGetDefault2 (
http_t *http
);
CUPS_HTTP_DEFAULT
Default printer or NULL
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.
Get the named destination from the list.
cups_dest_t *cupsGetDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
for the default destinationNULL
Destination pointer or NULL
Use the cupsGetDests
or cupsGetDests2
functions to get a
list of supported destinations for the current user.
Get a media name, dimension, and margins for a specific size.
int cupsGetDestMediaByIndex (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int n,
unsigned flags,
cups_size_t *size
);
1 on success, 0 on failure
The flags
parameter determines which set of media are indexed. For
example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will get the Nth
borderless size supported by the printer.
Get media names, dimensions, and margins.
int cupsGetDestMediaByName (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *media,
unsigned flags,
cups_size_t *size
);
1 on match, 0 on failure
The "media" string is a PWG media name. "Flags" provides some matching
guidance (multiple flags can be combined):
CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
size amongst the "ready" media.
The matching result (if any) is returned in the "cups_size_t" structure.
Returns 1 when there is a match and 0 if there is not a match.
Get media names, dimensions, and margins.
int cupsGetDestMediaBySize (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
int width,
int length,
unsigned flags,
cups_size_t *size
);
1 on match, 0 on failure
"Width" and "length" are the dimensions in hundredths of millimeters.
"Flags" provides some matching guidance (multiple flags can be combined):
CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
size amongst the "ready" media.
The matching result (if any) is returned in the "cups_size_t" structure.
Returns 1 when there is a match and 0 if there is not a match.
Get the number of sizes supported by a destination.
int cupsGetDestMediaCount (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags
);
Number of sizes
The flags
parameter determines the set of media sizes that are
counted. For example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will return
the number of borderless sizes.
Get the default size for a destination.
int cupsGetDestMediaDefault (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags,
cups_size_t *size
);
1 on success, 0 on failure
The flags
parameter determines which default size is returned. For
example, passing CUPS_MEDIA_FLAGS_BORDERLESS
will return the default
borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
Get a destination associated with a URI.
cups_dest_t *cupsGetDestWithURI (
const char *name,
const char *uri
);
NULL
Destination or NULL
"name" is the desired name for the printer. If NULL
, a name will be
created using the URI.
"uri" is the "ipp" or "ipps" URI for the printer.
Get the list of destinations from the default server.
int cupsGetDests (
cups_dest_t **dests
);
Number of destinations
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. CUPS 1.4
adds the marker-change-time, marker-colors, marker-high-levels,
marker-levels, marker-low-levels, marker-message, marker-names,
marker-types, and printer-commands attributes as well.
Use the cupsFreeDests
function to free the destination list and
the cupsGetDest
function to find a particular destination.
Get the list of destinations from the specified server.
int cupsGetDests2 (
http_t *http,
cups_dest_t **dests
);
CUPS_HTTP_DEFAULT
Number of destinations
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. CUPS 1.4
adds the marker-change-time, marker-colors, marker-high-levels,
marker-levels, marker-low-levels, marker-message, marker-names,
marker-types, and printer-commands attributes as well.
Use the cupsFreeDests
function to free the destination list and
the cupsGetDest
function to find a particular destination.
Get a file from the server.
http_status_t cupsGetFd (
http_t *http,
const char *resource,
int fd
);
CUPS_HTTP_DEFAULT
HTTP status
This function returns HTTP_STATUS_OK
when the file is successfully retrieved.
Get a file from the server.
http_status_t cupsGetFile (
http_t *http,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULT
HTTP status
This function returns HTTP_STATUS_OK
when the file is successfully retrieved.
Get the jobs from the default server.
int cupsGetJobs (
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);
NULL
= all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL
, CUPS_WHICHJOBS_ACTIVE
, or CUPS_WHICHJOBS_COMPLETED
Number of jobs
A "whichjobs" value of CUPS_WHICHJOBS_ALL
returns all jobs regardless
of state, while CUPS_WHICHJOBS_ACTIVE
returns jobs that are
pending, processing, or held and CUPS_WHICHJOBS_COMPLETED
returns
jobs that are stopped, canceled, aborted, or completed.
Get the jobs from the specified server.
int cupsGetJobs2 (
http_t *http,
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);
CUPS_HTTP_DEFAULT
NULL
= all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL
, CUPS_WHICHJOBS_ACTIVE
, or CUPS_WHICHJOBS_COMPLETED
Number of jobs
A "whichjobs" value of CUPS_WHICHJOBS_ALL
returns all jobs regardless
of state, while CUPS_WHICHJOBS_ACTIVE
returns jobs that are
pending, processing, or held and CUPS_WHICHJOBS_COMPLETED
returns
jobs that are stopped, canceled, aborted, or completed.
Get options for the named destination.
cups_dest_t *cupsGetNamedDest (
http_t *http,
const char *name,
const char *instance
);
CUPS_HTTP_DEFAULT
NULL
for the default destinationNULL
Destination or NULL
This function is optimized for retrieving a single destination and should
be used instead of cupsGetDests
and cupsGetDest
when you either
know the name of the destination or want to print to the default destination.
If NULL
is returned, the destination does not exist or there is no
default destination.
If "http" is CUPS_HTTP_DEFAULT
, the connection to the default print
server will be used.
If "name" is NULL
, the default printer for the current user will be
returned.
The returned destination must be freed using cupsFreeDests
with a
"num_dests" value of 1.
Get an option value.
const char *cupsGetOption (
const char *name,
int num_options,
cups_option_t *options
);
Option value or NULL
Get a password from the user.
const char *cupsGetPassword (
const char *prompt
);
Password
Uses the current password callback function. Returns NULL
if the
user does not provide a password.
Note: The current password callback function is tracked separately for each
thread in a program. Multi-threaded programs that override the setting via
the cupsSetPasswordCB
or cupsSetPasswordCB2
functions need to
do so in each thread for the same function to be used.
Get a password from the user using the advanced password callback.
const char *cupsGetPassword2 (
const char *prompt,
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT
Password
Uses the current password callback function. Returns NULL
if the
user does not provide a password.
Note: The current password callback function is tracked separately for each
thread in a program. Multi-threaded programs that override the setting via
the cupsSetPasswordCB
or cupsSetPasswordCB2
functions need to
do so in each thread for the same function to be used.
Get a list of printers from the default server.
int cupsGetPrinters (
char ***printers
);
Number of printers
This function is deprecated and no longer returns a list of printers - use
cupsGetDests
instead.
Get a response to an IPP request.
ipp_t *cupsGetResponse (
http_t *http,
const char *resource
);
CUPS_HTTP_DEFAULT
Response or NULL
on HTTP error
Use this function to get the response for an IPP request sent using
cupsSendRequest
. For requests that return additional data, use
cupsReadResponseData
after getting a successful response,
otherwise call httpFlush
to complete the response processing.
Perform a hash function on the given data.
ssize_t cupsHashData (
const char *algorithm,
const void *data,
size_t datalen,
unsigned char *hash,
size_t hashsize
);
Size of hash or -1 on error
The "algorithm" argument can be any of the registered, non-deprecated IPP
hash algorithms for the "job-password-encryption" attribute, including
"sha" for SHA-1, "sha-256" for SHA2-256, etc.
The "hash" argument points to a buffer of "hashsize" bytes and should be at
least 64 bytes in length for all of the supported algorithms.
The returned hash is binary data.
Return the last IPP status code received on the current thread.
ipp_status_t cupsLastError (void);
IPP status code from last request
Return the last IPP status-message received on the current thread.
const char *cupsLastErrorString (void);
status-message text from last request
Get the localized string for a destination media size.
const char *cupsLocalizeDestMedia (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags,
cups_size_t *size
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Get the localized string for a destination option.
const char *cupsLocalizeDestOption (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Get the localized string for a destination option+value pair.
const char *cupsLocalizeDestValue (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
const char *option,
const char *value
);
Localized string
The returned string is stored in the destination information and will become invalid if the destination information is deleted.
Return the subject for the given notification message.
char *cupsNotifySubject (
cups_lang_t *lang,
ipp_t *event
);
Subject string or NULL
The returned string must be freed by the caller using free
.
Return the text for the given notification message.
char *cupsNotifyText (
cups_lang_t *lang,
ipp_t *event
);
Message text or NULL
The returned string must be freed by the caller using free
.
Parse options from a command-line argument.
int cupsParseOptions (
const char *arg,
int num_options,
cups_option_t **options
);
Number of options found
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.
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
);
Job ID or 0 on error
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
);
Job ID or 0 on error
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
);
Job ID or 0 on error
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
);
CUPS_HTTP_DEFAULT
Job ID or 0 on error
Put a file on the server.
http_status_t cupsPutFd (
http_t *http,
const char *resource,
int fd
);
CUPS_HTTP_DEFAULT
HTTP status
This function returns HTTP_STATUS_CREATED
when the file is stored
successfully.
Put a file on the server.
http_status_t cupsPutFile (
http_t *http,
const char *resource,
const char *filename
);
CUPS_HTTP_DEFAULT
HTTP status
This function returns HTTP_CREATED
when the file is stored
successfully.
Close a raster stream.
void cupsRasterClose (
cups_raster_t *r
);
The file descriptor associated with the raster stream must be closed separately as needed.
Return the last error from a raster function.
const char *cupsRasterErrorString (void);
Last error
If there are no recent errors, NULL is returned.
Initialize a page header for PWG Raster output.
int cupsRasterInitPWGHeader (
cups_page_header2_t *h,
pwg_media_t *media,
const char *type,
int xdpi,
int ydpi,
const char *sides,
const char *sheet_back
);
NULL
for none1 on success, 0 on failure
The "media" argument specifies the media to use.
The "type" argument specifies a "pwg-raster-document-type-supported" value
that controls the color space and bit depth of the raster data.
The "xres" and "yres" arguments specify the raster resolution in dots per
inch.
The "sheet_back" argument specifies a "pwg-raster-document-sheet-back" value
to apply for the back side of a page. Pass NULL
for the front side.
Open a raster stream using a file descriptor.
cups_raster_t *cupsRasterOpen (
int fd,
cups_mode_t mode
);
CUPS_RASTER_READ
,
CUPS_RASTER_WRITE
,
CUPS_RASTER_WRITE_COMPRESSED
,
or CUPS_RASTER_WRITE_PWG
New stream
This function associates a raster stream with the given file descriptor.
For most printer driver filters, "fd" will be 0 (stdin). For most raster
image processor (RIP) filters that generate raster data, "fd" will be 1
(stdout).
When writing raster data, the CUPS_RASTER_WRITE
,
CUPS_RASTER_WRITE_COMPRESS
, or CUPS_RASTER_WRITE_PWG
mode can
be used - compressed and PWG output is generally 25-50% smaller but adds a
100-300% execution time overhead.
Open a raster stream using a callback function.
cups_raster_t *cupsRasterOpenIO (
cups_raster_iocb_t iocb,
void *ctx,
cups_mode_t mode
);
CUPS_RASTER_READ
,
CUPS_RASTER_WRITE
,
CUPS_RASTER_WRITE_COMPRESSED
,
or CUPS_RASTER_WRITE_PWG
New stream
This function associates a raster stream with the given callback function and
context pointer.
When writing raster data, the CUPS_RASTER_WRITE
,
CUPS_RASTER_WRITE_COMPRESS
, or CUPS_RASTER_WRITE_PWG
mode can
be used - compressed and PWG output is generally 25-50% smaller but adds a
100-300% execution time overhead.
Read a raster page header and store it in a version 1 page header structure.
unsigned cupsRasterReadHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on failure/end-of-file
This function is deprecated. Use cupsRasterReadHeader2
instead.
Version 1 page headers were used in CUPS 1.0 and 1.1 and contain a subset
of the version 2 page header data. This function handles reading version 2
page headers and copying only the version 1 data into the provided buffer.
Read a raster page header and store it in a version 2 page header structure.
unsigned cupsRasterReadHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on failure/end-of-file
Read raster pixels.
unsigned cupsRasterReadPixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes read
For best performance, filters should read one or more whole lines. The "cupsBytesPerLine" value from the page header can be used to allocate the line buffer and as the number of bytes to read.
Write a raster page header from a version 1 page header structure.
unsigned cupsRasterWriteHeader (
cups_raster_t *r,
cups_page_header_t *h
);
1 on success, 0 on failure
This function is deprecated. Use cupsRasterWriteHeader2
instead.
Write a raster page header from a version 2 page header structure.
unsigned cupsRasterWriteHeader2 (
cups_raster_t *r,
cups_page_header2_t *h
);
1 on success, 0 on failure
The page header can be initialized using cupsRasterInterpretPPD
.
Write raster pixels.
unsigned cupsRasterWritePixels (
cups_raster_t *r,
unsigned char *p,
unsigned len
);
Number of bytes written
For best performance, filters should write one or more whole lines. The "cupsBytesPerLine" value from the page header can be used to allocate the line buffer and as the number of bytes to write.
Read additional data after the IPP response.
ssize_t cupsReadResponseData (
http_t *http,
char *buffer,
size_t length
);
CUPS_HTTP_DEFAULT
Bytes read, 0 on EOF, -1 on error
This function is used after cupsGetResponse
to read the PPD or document
files from CUPS_GET_PPD
and CUPS_GET_DOCUMENT
requests,
respectively.
Remove a destination from the destination list.
int cupsRemoveDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULL
New number of destinations
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.
Remove an option from an option array.
int cupsRemoveOption (
const char *name,
int num_options,
cups_option_t **options
);
New number of options
Send an IPP request.
http_status_t cupsSendRequest (
http_t *http,
ipp_t *request,
const char *resource,
size_t length
);
CUPS_HTTP_DEFAULT
CUPS_LENGTH_VARIABLE
Initial HTTP status
Use cupsWriteRequestData
to write any additional data (document, PPD
file, etc.) for the request, cupsGetResponse
to get the IPP response,
and cupsReadResponseData
to read any additional data following the
response. Only one request can be sent/queued at a time per http_t
connection.
Returns the initial HTTP status code, which will be HTTP_STATUS_CONTINUE
on a successful send of the request.
Note: Unlike cupsDoFileRequest
, cupsDoIORequest
, and
cupsDoRequest
, the request is NOT freed with ippDelete
.
Return the hostname/address of the current server.
const char *cupsServer (void);
Server name
The default server comes from the CUPS_SERVER environment variable, then the
~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not
set, the default is the local system - either "localhost" or a domain socket
path.
The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6
address, or a domain socket pathname.
Note: The current server is tracked separately for each thread in a program.
Multi-threaded programs that override the server via the
cupsSetServer
function need to do so in each thread for the same
server to be used.
Set the client certificate callback.
void cupsSetClientCertCB (
cups_client_cert_cb_t cb,
void *user_data
);
Pass NULL
to restore the default callback.
Note: The current certificate callback is tracked separately for each thread
in a program. Multi-threaded programs that override the callback need to do
so in each thread for the same callback to be used.
Set the default credentials to be used for SSL/TLS connections.
int cupsSetCredentials (
cups_array_t *credentials
);
Status of call (0 = success)
Note: The default credentials are tracked separately for each thread in a program. Multi-threaded programs that override the setting need to do so in each thread for the same setting to be used.
Set the default destination.
void cupsSetDefaultDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
Save the list of destinations for the default server.
void cupsSetDests (
int num_dests,
cups_dest_t *dests
);
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Save the list of destinations for the specified server.
int cupsSetDests2 (
http_t *http,
int num_dests,
cups_dest_t *dests
);
CUPS_HTTP_DEFAULT
0 on success, -1 on error
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Set the encryption preference.
void cupsSetEncryption (
http_encryption_t e
);
The default encryption setting comes from the CUPS_ENCRYPTION
environment variable, then the ~/.cups/client.conf file, and finally the
/etc/cups/client.conf file. If not set, the default is
HTTP_ENCRYPTION_IF_REQUESTED
.
Note: The current encryption setting is tracked separately for each thread
in a program. Multi-threaded programs that override the setting need to do
so in each thread for the same setting to be used.
Set the password callback for CUPS.
void cupsSetPasswordCB (
cups_password_cb_t cb
);
Pass NULL
to restore the default (console) password callback, which
reads the password from the console. Programs should call either this
function or cupsSetPasswordCB2
, as only one callback can be registered
by a program per thread.
Note: The current password callback is tracked separately for each thread
in a program. Multi-threaded programs that override the callback need to do
so in each thread for the same callback to be used.
Set the advanced password callback for CUPS.
void cupsSetPasswordCB2 (
cups_password_cb2_t cb,
void *user_data
);
Pass NULL
to restore the default (console) password callback, which
reads the password from the console. Programs should call either this
function or cupsSetPasswordCB2
, as only one callback can be registered
by a program per thread.
Note: The current password callback is tracked separately for each thread
in a program. Multi-threaded programs that override the callback need to do
so in each thread for the same callback to be used.
Set the default server name and port.
void cupsSetServer (
const char *server
);
The "server" string can be a fully-qualified hostname, a numeric
IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP
addresses can be optionally followed by a colon and port number to override
the default port 631, e.g. "hostname:8631". Pass NULL
to restore the
default server name and port.
Note: The current server is tracked separately for each thread in a program.
Multi-threaded programs that override the server need to do so in each
thread for the same server to be used.
Set the server certificate callback.
void cupsSetServerCertCB (
cups_server_cert_cb_t cb,
void *user_data
);
Pass NULL
to restore the default callback.
Note: The current credentials callback is tracked separately for each thread
in a program. Multi-threaded programs that override the callback need to do
so in each thread for the same callback to be used.
Set the default user name.
void cupsSetUser (
const char *user
);
Pass NULL
to restore the default user name.
Note: The current user name is tracked separately for each thread in a
program. Multi-threaded programs that override the user name need to do so
in each thread for the same user name to be used.
Set the default HTTP User-Agent string.
void cupsSetUserAgent (
const char *user_agent
);
NULL
Setting the string to NULL forces the default value containing the CUPS version, IPP version, and operating system version and architecture.
Start a new document.
http_status_t cupsStartDestDocument (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *info,
int job_id,
const char *docname,
const char *format,
int num_options,
cups_option_t *options,
int last_document
);
Status of document creation
"job_id" is the job ID returned by cupsCreateDestJob. "docname" is the name
of the document/file being printed, "format" is the MIME media type for the
document (see CUPS_FORMAT_xxx constants), and "num_options" and "options"
are the options do be applied to the document. "last_document" should be 1
if this is the last document to be submitted in the job. Returns
HTTP_CONTINUE
on success.
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
);
CUPS_HTTP_DEFAULT
cupsCreateJob
CUPS_FORMAT_foo
HTTP status of request
Use cupsWriteRequestData
to write data for the document and
cupsFinishDocument
to finish the document and get the submission status.
The MIME type constants CUPS_FORMAT_AUTO
, CUPS_FORMAT_PDF
,
CUPS_FORMAT_POSTSCRIPT
, CUPS_FORMAT_RAW
, and
CUPS_FORMAT_TEXT
are provided for the "format" argument, although
any supported MIME type string can be supplied.
Return the current user's name.
const char *cupsUser (void);
User name
Note: The current user name is tracked separately for each thread in a
program. Multi-threaded programs that override the user name with the
cupsSetUser
function need to do so in each thread for the same user
name to be used.
Return the default HTTP User-Agent string.
const char *cupsUserAgent (void);
User-Agent string
Write additional data after an IPP request.
http_status_t cupsWriteRequestData (
http_t *http,
const char *buffer,
size_t length
);
CUPS_HTTP_DEFAULT
HTTP_STATUS_CONTINUE
if OK or HTTP status on error
This function is used after cupsSendRequest
to provide a PPD and
after cupsStartDocument
to provide a document file.
Return a pointer to thread local storage.
_cups_raster_error_t *get_error_buffer (void);
Pointer to error buffer
Accept a new HTTP client connection from the specified listening socket.
http_t *httpAcceptConnection (
int fd,
int blocking
);
HTTP connection or NULL
Allocates and adds a single credential to an array.
int httpAddCredential (
cups_array_t *credentials,
const void *data,
size_t datalen
);
0 on success, -1 on error
Use cupsArrayNew(NULL, NULL)
to create a credentials array.
Check for the "any" address.
int httpAddrAny (
const http_addr_t *addr
);
1 if "any", 0 otherwise
Close a socket created by httpAddrConnect
or
httpAddrListen
.
int httpAddrClose (
http_addr_t *addr,
int fd
);
NULL
0 on success, -1 on failure
Pass NULL
for sockets created with httpAddrConnect
and the
listen address for sockets created with httpAddrListen
. This will
ensure that domain sockets are removed when closed.
Connect to any of the addresses in the list.
http_addrlist_t *httpAddrConnect (
http_addrlist_t *addrlist,
int *sock
);
Connected address or NULL on failure
Connect to any of the addresses in the list with a timeout and optional cancel.
http_addrlist_t *httpAddrConnect2 (
http_addrlist_t *addrlist,
int *sock,
int msec,
int *cancel
);
Connected address or NULL on failure
Copy an address list.
http_addrlist_t *httpAddrCopyList (
http_addrlist_t *src
);
New address list or NULL
on error
Compare two addresses.
int httpAddrEqual (
const http_addr_t *addr1,
const http_addr_t *addr2
);
1 if equal, 0 if not
Get the address family of an address.
int httpAddrFamily (
http_addr_t *addr
);
Address family
Free an address list.
void httpAddrFreeList (
http_addrlist_t *addrlist
);
Get a list of addresses for a hostname.
http_addrlist_t *httpAddrGetList (
const char *hostname,
int family,
const char *service
);
List of addresses or NULL
Return the length of the address in bytes.
int httpAddrLength (
const http_addr_t *addr
);
Length in bytes
Create a listening socket bound to the specified address and port.
int httpAddrListen (
http_addr_t *addr,
int port
);
Socket or -1 on error
Check for the local loopback address.
int httpAddrLocalhost (
const http_addr_t *addr
);
1 if local host, 0 otherwise
Lookup the hostname associated with the address.
char *httpAddrLookup (
const http_addr_t *addr,
char *name,
int namelen
);
Host name
Get the port number associated with an address.
int httpAddrPort (
http_addr_t *addr
);
Port number
Convert an address to a numeric string.
char *httpAddrString (
const http_addr_t *addr,
char *s,
int slen
);
Numeric address string
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
);
URI status
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.
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,
...
);
URI status
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.
Assemble a name-based UUID URN conforming to RFC 4122.
char *httpAssembleUUID (
const char *server,
int port,
const char *name,
int number,
char *buffer,
size_t bufsize
);
UUID string
This function creates a unique 128-bit identifying number using the server
name, port number, random data, and optionally an object name and/or object
number. The result is formatted as a UUID URN as defined in RFC 4122.
The buffer needs to be at least 46 bytes in size.
Set blocking/non-blocking behavior on a connection.
void httpBlocking (
http_t *http,
int b
);
Check to see if there is a pending response from the server.
int httpCheck (
http_t *http
);
0 = no data, 1 = data available
Clear the cookie value(s).
void httpClearCookie (
http_t *http
);
Clear HTTP request fields.
void httpClearFields (
http_t *http
);
Close an HTTP connection.
void httpClose (
http_t *http
);
Compare two sets of X.509 credentials.
int httpCompareCredentials (
cups_array_t *cred1,
cups_array_t *cred2
);
1 if they match, 0 if they do not
Connect to a HTTP server.
http_t *httpConnect (
const char *host,
int port
);
New HTTP connection
This function is deprecated - use httpConnect2
instead.
Connect to a HTTP server.
http_t *httpConnect2 (
const char *host,
int port,
http_addrlist_t *addrlist,
int family,
http_encryption_t encryption,
int blocking,
int msec,
int *cancel
);
AF_UNSPEC
for anyNew HTTP connection
Connect to a HTTP server using encryption.
http_t *httpConnectEncrypt (
const char *host,
int port,
http_encryption_t encryption
);
New HTTP connection
This function is now deprecated. Please use the httpConnect2
function
instead.
Local functions...
int httpCopyCredentials (
http_t *http,
cups_array_t **credentials
);
Stubs for when TLS is not supported/available
int httpCredentialsAreValidForName (
cups_array_t *credentials,
const char *common_name
);
time_t httpCredentialsGetExpiration (
cups_array_t *credentials
);
http_trust_t httpCredentialsGetTrust (
cups_array_t *credentials,
const char *common_name
);
size_t httpCredentialsString (
cups_array_t *credentials,
char *buffer,
size_t bufsize
);
Base64-decode a string.
char *httpDecode64 (
char *out,
const char *in
);
Decoded string
This function is deprecated. Use the httpDecode64_2() function instead which provides buffer length arguments.
Base64-decode a string.
char *httpDecode64_2 (
char *out,
int *outlen,
const char *in
);
Decoded string
Send a DELETE request to the server.
int httpDelete (
http_t *http,
const char *uri
);
Status of call (0 = success)
Base64-encode a string.
char *httpEncode64 (
char *out,
const char *in
);
Encoded string
This function is deprecated. Use the httpEncode64_2() function instead which provides buffer length arguments.
Base64-encode a string.
char *httpEncode64_2 (
char *out,
int outlen,
const char *in,
int inlen
);
Encoded string
Set the required encryption on the link.
int httpEncryption (
http_t *http,
http_encryption_t e
);
-1 on error, 0 on success
Get the last error on a connection.
int httpError (
http_t *http
);
Error code (errno) value
Return the HTTP field enumeration value for a field name.
http_field_t httpFieldValue (
const char *name
);
Field index
Flush data from a HTTP connection.
void httpFlush (
http_t *http
);
Flush data in write buffer.
int httpFlushWrite (
http_t *http
);
Bytes written or -1 on error
Free an array of credentials.
void httpFreeCredentials (
cups_array_t *credentials
);
Send a GET request to the server.
int httpGet (
http_t *http,
const char *uri
);
Status of call (0 = success)
Get the most recent activity for a connection.
time_t httpGetActivity (
http_t *http
);
Time of last read or write
The return value is the UNIX time of the last read or write.
Get the address of the connected peer of a connection.
http_addr_t *httpGetAddress (
http_t *http
);
Connected address or NULL
Returns NULL
if the socket is currently unconnected.
Get the current authorization string.
char *httpGetAuthString (
http_t *http
);
Authorization string
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.
Get the blocking/non-block state of a connection.
int httpGetBlocking (
http_t *http
);
1 if blocking, 0 if non-blocking
Get a common content encoding, if any, between the client and server.
const char *httpGetContentEncoding (
http_t *http
);
Content-Coding value or
NULL
for the identity
coding.
This function uses the value of the Accepts-Encoding HTTP header and must be called after receiving a response from the server or a request from the client. The value returned can be use in subsequent requests (for clients) or in the response (for servers) in order to compress the content stream.
Get any cookie data from the response.
const char *httpGetCookie (
http_t *http
);
Cookie data or NULL
Get a formatted date/time string from a time value.
const char *httpGetDateString (
time_t t
);
Date/time string
Get a formatted date/time string from a time value.
const char *httpGetDateString2 (
time_t t,
char *s,
int slen
);
Date/time string
Get a time value from a formatted date/time string.
time_t httpGetDateTime (
const char *s
);
UNIX time
Get the current encryption mode of a connection.
http_encryption_t httpGetEncryption (
http_t *http
);
Current encryption mode
This function returns the encryption mode for the connection. Use the
httpIsEncrypted
function to determine whether a TLS session has
been established.
Get the value of the Expect header, if any.
http_status_t httpGetExpect (
http_t *http
);
Expect: status, if any
Returns HTTP_STATUS_NONE
if there is no Expect header, otherwise
returns the expected HTTP status code, typically HTTP_STATUS_CONTINUE
.
Get the file descriptor associated with a connection.
int httpGetFd (
http_t *http
);
File descriptor or -1 if none
Get a field value from a request/response.
const char *httpGetField (
http_t *http,
http_field_t field
);
Field value
Lookup a hostname or IPv4 address, and return address records for the specified name.
struct hostent *httpGetHostByName (
const char *name
);
Host entry
Get the FQDN for the connection or local system.
const char *httpGetHostname (
http_t *http,
char *s,
int slen
);
FQDN for connection or system
When "http" points to a connected socket, return the hostname or address that was used in the call to httpConnect() or httpConnectEncrypt(), or the address of the client for the connection from httpAcceptConnection(). Otherwise, return the FQDN for the local system using both gethostname() and gethostbyname() to get the local hostname with domain.
Get the current Keep-Alive state of the connection.
http_keepalive_t httpGetKeepAlive (
http_t *http
);
Keep-Alive state
Get the amount of data remaining from the content-length or transfer-encoding fields.
int httpGetLength (
http_t *http
);
Content length
This function is deprecated and will not return lengths larger than 2^31 - 1; use httpGetLength2() instead.
Get the amount of data remaining from the content-length or transfer-encoding fields.
off_t httpGetLength2 (
http_t *http
);
Content length
This function returns the complete content length, even for content larger than 2^31 - 1.
Get the number of bytes that are buffered for writing.
size_t httpGetPending (
http_t *http
);
Number of bytes buffered
Get the number of bytes that can be read without blocking.
size_t httpGetReady (
http_t *http
);
Number of bytes available
Get the number of remaining bytes in the message body or current chunk.
size_t httpGetRemaining (
http_t *http
);
Remaining bytes
The httpIsChunked
function can be used to determine whether the
message body is chunked or fixed-length.
Get the current state of the HTTP request.
http_state_t httpGetState (
http_t *http
);
HTTP state
Get the status of the last HTTP request.
http_status_t httpGetStatus (
http_t *http
);
HTTP status
Get a sub-field value.
char *httpGetSubField (
http_t *http,
http_field_t field,
const char *name,
char *value
);
Value or NULL
Get a sub-field value.
char *httpGetSubField2 (
http_t *http,
http_field_t field,
const char *name,
char *value,
int valuelen
);
Value or NULL
Get the HTTP version at the other end.
http_version_t httpGetVersion (
http_t *http
);
Version number
Get a line of text from a HTTP connection.
char *httpGets (
char *line,
int length,
http_t *http
);
Line or NULL
Send a HEAD request to the server.
int httpHead (
http_t *http,
const char *uri
);
Status of call (0 = success)
Initialize the HTTP interface library and set the default HTTP proxy (if any).
void httpInitialize (void);
Report whether a message body is chunked.
int httpIsChunked (
http_t *http
);
1 if chunked, 0 if not
This function returns non-zero if the message body is composed of variable-length chunks.
Report whether a connection is encrypted.
int httpIsEncrypted (
http_t *http
);
1 if encrypted, 0 if not
This function returns non-zero if the connection is currently encrypted.
int httpLoadCredentials (
const char *path,
cups_array_t **credentials,
const char *common_name
);
Compute the MD5 sum of the username:group:password.
char *httpMD5 (
const char *username,
const char *realm,
const char *passwd,
char md5[33]
);
MD5 sum
Combine the MD5 sum of the username, group, and password with the server-supplied nonce value, method, and request-uri.
char *httpMD5Final (
const char *nonce,
const char *method,
const char *resource,
char md5[33]
);
New sum
Convert an MD5 sum to a character string.
char *httpMD5String (
const unsigned char *sum,
char md5[33]
);
MD5 sum in hex
Send an OPTIONS request to the server.
int httpOptions (
http_t *http,
const char *uri
);
Status of call (0 = success)
Peek at data from a HTTP connection.
ssize_t httpPeek (
http_t *http,
char *buffer,
size_t length
);
Number of bytes copied
This function copies available data from the given HTTP connection, reading
a buffer as needed. The data is still available for reading using
httpRead
or httpRead2
.
For non-blocking connections the usual timeouts apply.
Send a POST request to the server.
int httpPost (
http_t *http,
const char *uri
);
Status of call (0 = success)
Send a PUT request to the server.
int httpPut (
http_t *http,
const char *uri
);
Status of call (0 = success)
Read data from a HTTP connection.
int httpRead (
http_t *http,
char *buffer,
int length
);
Number of bytes read
This function is deprecated. Use the httpRead2() function which can read more than 2GB of data.
Read data from a HTTP connection.
ssize_t httpRead2 (
http_t *http,
char *buffer,
size_t length
);
Number of bytes read
Read a HTTP request from a connection.
http_state_t httpReadRequest (
http_t *http,
char *uri,
size_t urilen
);
New state of connection
Reconnect to a HTTP server.
int httpReconnect (
http_t *http
);
0 on success, non-zero on failure
This function is deprecated. Please use the httpReconnect2
function
instead.
Reconnect to a HTTP server with timeout and optional cancel.
int httpReconnect2 (
http_t *http,
int msec,
int *cancel
);
0 on success, non-zero on failure
Resolve the hostname of the HTTP connection address.
const char *httpResolveHostname (
http_t *http,
char *buffer,
size_t bufsize
);
Resolved hostname or NULL
int httpSaveCredentials (
const char *path,
cups_array_t *credentials,
const char *common_name
);
Separate a Universal Resource Identifier into its components.
void httpSeparate (
const char *uri,
char *scheme,
char *username,
char *host,
int *port,
char *resource
);
This function is deprecated; use the httpSeparateURI() function instead.
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
);
This function is deprecated; use the httpSeparateURI() function instead.
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
);
Result of separation
Set the current authorization string.
void httpSetAuthString (
http_t *http,
const char *scheme,
const char *data
);
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().
Set the cookie value(s).
void httpSetCookie (
http_t *http,
const char *cookie
);
Set the credentials associated with an encrypted connection.
int httpSetCredentials (
http_t *http,
cups_array_t *credentials
);
Status of call (0 = success)
Set the default value of an HTTP header.
void httpSetDefaultField (
http_t *http,
http_field_t field,
const char *value
);
Currently only HTTP_FIELD_ACCEPT_ENCODING
, HTTP_FIELD_SERVER
,
and HTTP_FIELD_USER_AGENT
can be set.
Set the Expect: header in a request.
void httpSetExpect (
http_t *http,
http_status_t expect
);
HTTP_STATUS_CONTINUE
)Currently only HTTP_STATUS_CONTINUE
is supported for the "expect"
argument.
Set the value of an HTTP header.
void httpSetField (
http_t *http,
http_field_t field,
const char *value
);
Set the current Keep-Alive state of a connection.
void httpSetKeepAlive (
http_t *http,
http_keepalive_t keep_alive
);
Set the content-length and content-encoding.
void httpSetLength (
http_t *http,
size_t length
);
Set read/write timeouts and an optional callback.
void httpSetTimeout (
http_t *http,
double timeout,
http_timeout_cb_t cb,
void *user_data
);
The optional timeout callback receives both the HTTP connection and a user data pointer and must return 1 to continue or 0 to error (time) out.
Shutdown one side of an HTTP connection.
void httpShutdown (
http_t *http
);
Return the string describing a HTTP state value.
const char *httpStateString (
http_state_t state
);
State string
Return a short string describing a HTTP status code.
const char *httpStatus (
http_status_t status
);
Localized status string
The returned string is localized to the current POSIX locale and is based on the status strings defined in RFC 2616.
Send an TRACE request to the server.
int httpTrace (
http_t *http,
const char *uri
);
Status of call (0 = success)
Return a string describing a URI status code.
const char *httpURIStatusString (
http_uri_status_t status
);
Localized status string
Update the current HTTP state for incoming data.
http_status_t httpUpdate (
http_t *http
);
HTTP status
Wait for data available on a connection.
int httpWait (
http_t *http,
int msec
);
1 if data is available, 0 otherwise
Write data to a HTTP connection.
int httpWrite (
http_t *http,
const char *buffer,
int length
);
Number of bytes written
This function is deprecated. Use the httpWrite2() function which can write more than 2GB of data.
Write data to a HTTP connection.
ssize_t httpWrite2 (
http_t *http,
const char *buffer,
size_t length
);
Number of bytes written
Write a HTTP response to a client connection.
int httpWriteResponse (
http_t *http,
http_status_t status
);
0 on success, -1 on error
Add a boolean attribute to an IPP message.
ipp_attribute_t *ippAddBoolean (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
char value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a collection value.
ipp_attribute_t *ippAddCollection (
ipp_t *ipp,
ipp_tag_t group,
const char *name,
ipp_t *value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a integer attribute to an IPP message.
ipp_attribute_t *ippAddInteger (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported values include enum (IPP_TAG_ENUM
) and integer
(IPP_TAG_INTEGER
).
Add an array of integer values.
ipp_attribute_t *ippAddIntegers (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const int *values
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported values include enum (IPP_TAG_ENUM
) and integer
(IPP_TAG_INTEGER
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add an out-of-band value to an IPP message.
ipp_attribute_t *ippAddOutOfBand (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported out-of-band values include unsupported-value
(IPP_TAG_UNSUPPORTED_VALUE
), default (IPP_TAG_DEFAULT
), unknown
(IPP_TAG_UNKNOWN
), no-value (IPP_TAG_NOVALUE
), not-settable
(IPP_TAG_NOTSETTABLE
), delete-attribute (IPP_TAG_DELETEATTR
), and
admin-define (IPP_TAG_ADMINDEFINE
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
The lower
parameter must be less than or equal to the upper
parameter.
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
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
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Add a group separator to an IPP message.
ipp_attribute_t *ippAddSeparator (
ipp_t *ipp
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Add a language-encoded string to an IPP message.
ipp_attribute_t *ippAddString (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *value
);
New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage and
textWithLanguage string values and must be NULL
for all other string values.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringf (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
...
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document
(IPP_TAG_DOCUMENT
), event notification
(IPP_TAG_EVENT_NOTIFICATION
), operation (IPP_TAG_OPERATION
),
printer (IPP_TAG_PRINTER
), subscription (IPP_TAG_SUBSCRIPTION
),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage
and textWithLanguage string values and must be NULL
for all other
string values.
The format
parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Add a formatted string to an IPP message.
ipp_attribute_t *ippAddStringfv (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
const char *language,
const char *format,
va_list ap
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document
(IPP_TAG_DOCUMENT
), event notification
(IPP_TAG_EVENT_NOTIFICATION
), operation (IPP_TAG_OPERATION
),
printer (IPP_TAG_PRINTER
), subscription (IPP_TAG_SUBSCRIPTION
),
or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage
and textWithLanguage string values and must be NULL
for all other
string values.
The format
parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments are passed in the
stdarg pointer ap
. The formatted string is truncated as needed to the
maximum length of the corresponding value type.
Add language-encoded strings to an IPP message.
ipp_attribute_t *ippAddStrings (
ipp_t *ipp,
ipp_tag_t group,
ipp_tag_t value_tag,
const char *name,
int num_values,
const char *language,
const char *const *values
);
NULL
for default)New attribute
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Supported string values include charset (IPP_TAG_CHARSET
), keyword
(IPP_TAG_KEYWORD
), language (IPP_TAG_LANGUAGE
), mimeMediaType
(IPP_TAG_MIMETYPE
), name (IPP_TAG_NAME
), nameWithLanguage
(IPP_TAG_NAMELANG), text (
code IPP_TAG_TEXT@), textWithLanguage
(IPP_TAG_TEXTLANG
), uri (IPP_TAG_URI
), and uriScheme
(IPP_TAG_URISCHEME
).
The language
parameter must be non-NULL
for nameWithLanguage and
textWithLanguage string values and must be NULL
for all other string values.
Convert the attribute's value to a string.
size_t ippAttributeString (
ipp_attribute_t *attr,
char *buffer,
size_t bufsize
);
Number of bytes less nul
Returns the number of bytes that would be written, not including the trailing nul. The buffer pointer can be NULL to get the required length, just like (v)snprintf.
Determine whether an attribute contains the specified value or is within the list of ranges.
int ippContainsInteger (
ipp_attribute_t *attr,
int value
);
1 on a match, 0 on no match
Returns non-zero when the attribute contains either a matching integer or enum value, or the value falls within one of the rangeOfInteger values for the attribute.
Determine whether an attribute contains the specified string value.
int ippContainsString (
ipp_attribute_t *attr,
const char *value
);
1 on a match, 0 on no match
Returns non-zero when the attribute contains a matching charset, keyword, language, mimeMediaType, name, text, URI, or URI scheme value.
Copy an attribute.
ipp_attribute_t *ippCopyAttribute (
ipp_t *dst,
ipp_attribute_t *srcattr,
int quickcopy
);
New attribute
The specified attribute, attr
, is copied to the destination IPP message.
When quickcopy
is non-zero, a "shallow" reference copy of the attribute is
created - this should only be done as long as the original source IPP message will
not be freed for the life of the destination.
Copy attributes from one IPP message to another.
int ippCopyAttributes (
ipp_t *dst,
ipp_t *src,
int quickcopy,
ipp_copycb_t cb,
void *context
);
NULL
for none1 on success, 0 on error
Zero or more attributes are copied from the source IPP message, src
, to the
destination IPP message, dst
. When quickcopy
is non-zero, a "shallow"
reference copy of the attribute is created - this should only be done as long as the
original source IPP message will not be freed for the life of the destination.
The cb
and context
parameters provide a generic way to "filter" the
attributes that are copied - the function must return 1 to copy the attribute or
0 to skip it. The function may also choose to do a partial copy of the source attribute
itself.
Create a CUPS array of attribute names from the given requested-attributes attribute.
cups_array_t *ippCreateRequestedArray (
ipp_t *request
);
CUPS array or NULL
if all
This function creates a (sorted) CUPS array of attribute names matching the
list of "requested-attribute" values supplied in an IPP request. All IANA-
registered values are supported in addition to the CUPS IPP extension
attributes.
The request
parameter specifies the request message that was read from
the client.
NULL
is returned if all attributes should be returned. Otherwise, the
result is a sorted array of attribute names, where cupsArrayFind(array,
"attribute-name")
will return a non-NULL pointer. The array must be freed
using the cupsArrayDelete
function.
Convert from RFC 1903 Date/Time format to UNIX time in seconds.
time_t ippDateToTime (
const ipp_uchar_t *date
);
UNIX time value
Delete an IPP message.
void ippDelete (
ipp_t *ipp
);
Delete a single attribute in an IPP message.
void ippDeleteAttribute (
ipp_t *ipp,
ipp_attribute_t *attr
);
Delete values in an attribute.
int ippDeleteValues (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int count
);
1 on success, 0 on failure
The element
parameter specifies the first value to delete, starting at
0. It must be less than the number of values returned by ippGetCount
.
The attr
parameter may be modified as a result of setting the value.
Deleting all values in an attribute deletes the attribute.
Return a string corresponding to the enum value.
const char *ippEnumString (
const char *attrname,
int enumvalue
);
Enum string
Return the value associated with a given enum string.
int ippEnumValue (
const char *attrname,
const char *enumstring
);
Enum value or -1 if unknown
Return a name for the given status code.
const char *ippErrorString (
ipp_status_t error
);
Text string
Return a status code for the given name.
ipp_status_t ippErrorValue (
const char *name
);
IPP status code
Find a named attribute in a request.
ipp_attribute_t *ippFindAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
Starting with CUPS 2.0, the attribute name can contain a hierarchical list of attribute and member names separated by slashes, for example "media-col/media-size".
Find the next named attribute in a request.
ipp_attribute_t *ippFindNextAttribute (
ipp_t *ipp,
const char *name,
ipp_tag_t type
);
Matching attribute
Starting with CUPS 2.0, the attribute name can contain a hierarchical list of attribute and member names separated by slashes, for example "media-col/media-size".
Return the first attribute in the message.
ipp_attribute_t *ippFirstAttribute (
ipp_t *ipp
);
First attribute or NULL
if none
Get a boolean value for an attribute.
int ippGetBoolean (
ipp_attribute_t *attr,
int element
);
Boolean value or 0 on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get a collection value for an attribute.
ipp_t *ippGetCollection (
ipp_attribute_t *attr,
int element
);
Collection value or NULL
on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the number of values in an attribute.
int ippGetCount (
ipp_attribute_t *attr
);
Number of values or 0 on error
Get a date value for an attribute.
const ipp_uchar_t *ippGetDate (
ipp_attribute_t *attr,
int element
);
Date value or NULL
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the group associated with an attribute.
ipp_tag_t ippGetGroupTag (
ipp_attribute_t *attr
);
Group tag or IPP_TAG_ZERO
on error
Get the integer/enum value for an attribute.
int ippGetInteger (
ipp_attribute_t *attr,
int element
);
Value or 0 on error
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the attribute name.
const char *ippGetName (
ipp_attribute_t *attr
);
Attribute name or NULL
for separators
Get an octetString value from an IPP attribute.
void *ippGetOctetString (
ipp_attribute_t *attr,
int element,
int *datalen
);
Pointer to octetString data
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the operation ID in an IPP message.
ipp_op_t ippGetOperation (
ipp_t *ipp
);
Operation ID or 0 on error
Get a rangeOfInteger value from an attribute.
int ippGetRange (
ipp_attribute_t *attr,
int element,
int *uppervalue
);
Lower value of range or 0
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the request ID from an IPP message.
int ippGetRequestId (
ipp_t *ipp
);
Request ID or 0 on error
Get a resolution value for an attribute.
int ippGetResolution (
ipp_attribute_t *attr,
int element,
int *yres,
ipp_res_t *units
);
Horizontal/cross feed resolution or 0
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the IPP message state.
ipp_state_t ippGetState (
ipp_t *ipp
);
IPP message state value
Get the status code from an IPP response or event message.
ipp_status_t ippGetStatusCode (
ipp_t *ipp
);
Status code in IPP message
Return the value...
const char *ippGetString (
ipp_attribute_t *attr,
int element,
const char **language
);
NULL
for don't care)Get the string and optionally the language code for an attribute.
The element
parameter specifies which value to get from 0 to
ippGetCount(attr)
- 1.
Get the value tag for an attribute.
ipp_tag_t ippGetValueTag (
ipp_attribute_t *attr
);
Value tag or IPP_TAG_ZERO
on error
Get the major and minor version number from an IPP message.
int ippGetVersion (
ipp_t *ipp,
int *minor
);
NULL
Major version number or 0 on error
Compute the length of an IPP message.
size_t ippLength (
ipp_t *ipp
);
Size of IPP message
Allocate a new IPP message.
ipp_t *ippNew (void);
New IPP message
Allocate a new IPP request message.
ipp_t *ippNewRequest (
ipp_op_t op
);
IPP request message
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.
Allocate a new IPP response message.
ipp_t *ippNewResponse (
ipp_t *request
);
IPP response message
The new response message is initialized with the same version-number, request-id, attributes-charset, and attributes-natural-language as the provided request message. If the attributes-charset or attributes-natural-language attributes are missing from the request, "utf-8" and a value derived from the current locale are substituted, respectively.
Return the next attribute in the message.
ipp_attribute_t *ippNextAttribute (
ipp_t *ipp
);
Next attribute or NULL
if none
Return a name for the given operation id.
const char *ippOpString (
ipp_op_t op
);
Name
Return an operation id for the given name.
ipp_op_t ippOpValue (
const char *name
);
Operation ID
Return the default IPP port number.
int ippPort (void);
Port number
Read data for an IPP message from a HTTP connection.
ipp_state_t ippRead (
http_t *http,
ipp_t *ipp
);
Current state
Read data for an IPP message from a file.
ipp_state_t ippReadFile (
int fd,
ipp_t *ipp
);
Current state
Read data for an IPP message.
ipp_state_t ippReadIO (
void *src,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Set a boolean value in an attribute.
int ippSetBoolean (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int boolvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a collection value in an attribute.
int ippSetCollection (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_t *colvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a date value in an attribute.
int ippSetDate (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const ipp_uchar_t *datevalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the group tag of an attribute.
int ippSetGroupTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t group_tag
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The group
parameter specifies the IPP attribute group tag: none
(IPP_TAG_ZERO
, for member attributes), document (IPP_TAG_DOCUMENT
),
event notification (IPP_TAG_EVENT_NOTIFICATION
), operation
(IPP_TAG_OPERATION
), printer (IPP_TAG_PRINTER
), subscription
(IPP_TAG_SUBSCRIPTION
), or unsupported (IPP_TAG_UNSUPPORTED_GROUP
).
Set an integer or enum value in an attribute.
int ippSetInteger (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int intvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the name of an attribute.
int ippSetName (
ipp_t *ipp,
ipp_attribute_t **attr,
const char *name
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
Set an octetString value in an IPP attribute.
int ippSetOctetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const void *data,
int datalen
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the operation ID in an IPP request message.
int ippSetOperation (
ipp_t *ipp,
ipp_op_t op
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Set the default port number.
void ippSetPort (
int p
);
Set a rangeOfInteger value in an attribute.
int ippSetRange (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
int lowervalue,
int uppervalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the request ID in an IPP message.
int ippSetRequestId (
ipp_t *ipp,
int request_id
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The request_id
parameter must be greater than 0.
Set a resolution value in an attribute.
int ippSetResolution (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
ipp_res_t unitsvalue,
int xresvalue,
int yresvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set the current state of the IPP message.
int ippSetState (
ipp_t *ipp,
ipp_state_t state
);
1 on success, 0 on failure
Set the status code in an IPP response or event message.
int ippSetStatusCode (
ipp_t *ipp,
ipp_status_t status
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
Set a string value in an attribute.
int ippSetString (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *strvalue
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
Set a formatted string value of an attribute.
int ippSetStringf (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
...
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
The format
parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Set a formatted string value of an attribute.
int ippSetStringfv (
ipp_t *ipp,
ipp_attribute_t **attr,
int element,
const char *format,
va_list ap
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
The element
parameter specifies which value to set from 0 to
ippGetCount(attr)
.
The format
parameter uses formatting characters compatible with the
printf family of standard functions. Additional arguments follow it as
needed. The formatted string is truncated as needed to the maximum length of
the corresponding value type.
Set the value tag of an attribute.
int ippSetValueTag (
ipp_t *ipp,
ipp_attribute_t **attr,
ipp_tag_t value_tag
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The attr
parameter may be modified as a result of setting the value.
Integer (IPP_TAG_INTEGER
) values can be promoted to rangeOfInteger
(IPP_TAG_RANGE
) values, the various string tags can be promoted to name
(IPP_TAG_NAME
) or nameWithLanguage (IPP_TAG_NAMELANG
) values, text
(IPP_TAG_TEXT
) values can be promoted to textWithLanguage
(IPP_TAG_TEXTLANG
) values, and all values can be demoted to the various
out-of-band value tags such as no-value (IPP_TAG_NOVALUE
). All other changes
will be rejected.
Promoting a string attribute to nameWithLanguage or textWithLanguage adds the language
code in the "attributes-natural-language" attribute or, if not present, the language
code for the current locale.
Set the version number in an IPP message.
int ippSetVersion (
ipp_t *ipp,
int major,
int minor
);
1 on success, 0 on failure
The ipp
parameter refers to an IPP message previously created using
the ippNew
, ippNewRequest
, or ippNewResponse
functions.
The valid version numbers are currently 1.0, 1.1, 2.0, 2.1, and 2.2.
Return the name corresponding to a state value.
const char *ippStateString (
ipp_state_t state
);
State name
Return the tag name corresponding to a tag value.
const char *ippTagString (
ipp_tag_t tag
);
Tag name
The returned names are defined in RFC 2911 and 3382.
Return the tag value corresponding to a tag name.
ipp_tag_t ippTagValue (
const char *name
);
Tag value
The tag names are defined in RFC 2911 and 3382.
Convert from UNIX time to RFC 1903 format.
const ipp_uchar_t *ippTimeToDate (
time_t t
);
RFC-1903 date/time data
Validate the contents of an attribute.
int ippValidateAttribute (
ipp_attribute_t *attr
);
1 if valid, 0 otherwise
This function validates the contents of an attribute based on the name and value tag. 1 is returned if the attribute is valid, 0 otherwise. On failure, cupsLastErrorString() is set to a human-readable message.
Validate all attributes in an IPP message.
int ippValidateAttributes (
ipp_t *ipp
);
1 if valid, 0 otherwise
This function validates the contents of the IPP message, including each
attribute. Like ippValidateAttribute
, cupsLastErrorString() is set
to a human-readable message on failure.
Write data for an IPP message to a HTTP connection.
ipp_state_t ippWrite (
http_t *http,
ipp_t *ipp
);
Current state
Write data for an IPP message to a file.
ipp_state_t ippWriteFile (
int fd,
ipp_t *ipp
);
Current state
Write data for an IPP message.
ipp_state_t ippWriteIO (
void *dst,
ipp_iocb_t cb,
int blocking,
ipp_t *parent,
ipp_t *ipp
);
Current state
Generate a PWG self-describing media size name.
int pwgFormatSizeName (
char *keyword,
size_t keysize,
const char *prefix,
const char *name,
int width,
int length,
const char *units
);
NULL
for automaticNULL
NULL
for automatic1 on success, 0 on failure
This function generates a PWG self-describing media size name of the form
"prefix_name_WIDTHxLENGTHunits". The prefix is typically "custom" or "roll"
for user-supplied sizes but can also be "disc", "iso", "jis", "jpn", "na",
"oe", "om", "prc", or "roc". A value of NULL
automatically chooses
"oe" or "om" depending on the units.
The size name may only contain lowercase letters, numbers, "-", and ".". If
NULL
is passed, the size name will contain the formatted dimensions.
The width and length are specified in hundredths of millimeters, equivalent
to 1/100000th of a meter or 1/2540th of an inch. The width, length, and
units used for the generated size name are calculated automatically if the
units string is NULL
, otherwise inches ("in") or millimeters ("mm")
are used.
Initialize a pwg_size_t structure using IPP Job Template attributes.
int pwgInitSize (
pwg_size_t *size,
ipp_t *job,
int *margins_set
);
1 if size was initialized, 0 otherwise
This function initializes a pwg_size_t structure from an IPP "media" or
"media-col" attribute in the specified IPP message. 0 is returned if neither
attribute is found in the message or the values are not valid.
The "margins_set" variable is initialized to 1 if any "media-xxx-margin"
member attribute was specified in the "media-col" Job Template attribute,
otherwise it is initialized to 0.
Find a PWG media size by ISO/IPP legacy name.
pwg_media_t *pwgMediaForLegacy (
const char *legacy
);
Matching size or NULL
The "name" argument specifies the legacy ISO media size name, for example "iso-a4" or "na-letter".
Find a PWG media size by Adobe PPD name.
pwg_media_t *pwgMediaForPPD (
const char *ppd
);
Matching size or NULL
The "ppd" argument specifies an Adobe page size name as defined in Table B.1
of the Adobe PostScript Printer Description File Format Specification Version
4.3.
If the name is non-standard, the returned PWG media size is stored in
thread-local storage and is overwritten by each call to the function in the
thread. Custom names can be of the form "Custom.WIDTHxLENGTH[units]" or
"WIDTHxLENGTH[units]".
Find a PWG media size by 5101.1 self-describing name.
pwg_media_t *pwgMediaForPWG (
const char *pwg
);
Matching size or NULL
The "pwg" argument specifies a self-describing media size name of the form
"prefix_name_WIDTHxLENGTHunits" as defined in PWG 5101.1.
If the name is non-standard, the returned PWG media size is stored in
thread-local storage and is overwritten by each call to the function in the
thread.
Get the PWG media size for the given dimensions.
pwg_media_t *pwgMediaForSize (
int width,
int length
);
PWG media name
The "width" and "length" are in hundredths of millimeters, equivalent to
1/100000th of a meter or 1/2540th of an inch.
If the dimensions are non-standard, the returned PWG media size is stored in
thread-local storage and is overwritten by each call to the function in the
thread.
AdvanceMedia attribute values
typedef enum cups_adv_e cups_adv_t;
Boolean type
typedef enum cups_bool_e cups_bool_t;
Client credentials callback
typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);
cupsColorSpace attribute values
typedef enum cups_cspace_e cups_cspace_t;
CutMedia attribute values
typedef enum cups_cut_e cups_cut_t;
Destination enumeration block
typedef int (*cups_dest_block_t(unsigned flags, cups_dest_t *dest);
Destination enumeration callback
typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, cups_dest_t *dest);
Destination
typedef struct cups_dest_s cups_dest_t;
Destination capability and status information
typedef struct _cups_dinfo_s cups_dinfo_t;
LeadingEdge attribute values
typedef enum cups_edge_e cups_edge_t;
cupsRasterInterpretPPD callback function
typedef int (*cups_interpret_cb_t)(cups_page_header2_t *header, int preferred_bits);
Job
typedef struct cups_job_s cups_job_t;
Jog attribute values
typedef enum cups_jog_e cups_jog_t;
cupsRasterOpen modes
typedef enum cups_mode_e cups_mode_t;
Printer Options
typedef struct cups_option_s cups_option_t;
cupsColorOrder attribute values
typedef enum cups_order_e cups_order_t;
Orientation attribute values
typedef enum cups_orient_e cups_orient_t;
Version 2 page header
typedef struct cups_page_header2_s cups_page_header2_t;
Version 1 page header
typedef struct cups_page_header_s cups_page_header_t;
New password callback
typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);
Password callback
typedef const char *(*cups_password_cb_t)(const char *prompt);
Printer type/capability bits
typedef unsigned cups_ptype_t;
cupsRasterOpenIO callback function
typedef ssize_t (*cups_raster_iocb_t)(void *ctx, unsigned char *buffer, size_t length);
Raster stream data
typedef struct _cups_raster_s cups_raster_t;
Server credentials callback
typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);
Media Size
typedef struct cups_size_s cups_size_t;
Local functions...
typedef struct gss_auth_identity gss_auth_identity_desc;
Socket address union, which makes using IPv6 and other address types easier and more portable.
typedef union _http_addr_u / http_addr_t;
Socket address list, which is used to enumerate all of the addresses that are associated with a hostname.
typedef struct http_addrlist_s / http_addrlist_t;
HTTP authentication types
typedef enum http_auth_e http_auth_t;
HTTP credential data
typedef struct http_credential_s http_credential_t;
HTTP transfer encoding values
typedef enum http_encoding_e http_encoding_t;
HTTP encryption values
typedef enum http_encryption_e http_encryption_t;
HTTP field names
typedef enum http_field_e http_field_t;
HTTP keep-alive values
typedef enum http_keepalive_e http_keepalive_t;
HTTP state values; states are server-oriented...
typedef enum http_state_e http_state_t;
HTTP connection type
typedef struct _http_s http_t;
HTTP timeout callback
typedef int (*http_timeout_cb_t)(http_t *http, void *user_data);
Level of trust for credentials
typedef enum http_trust_e http_trust_t;
URI en/decode flags
typedef enum http_uri_coding_e http_uri_coding_t;
URI separation status
typedef enum http_uri_status_e http_uri_status_t;
HTTP version numbers
typedef enum http_version_e http_version_t;
IPP attribute
typedef struct _ipp_attribute_s ipp_attribute_t;
The following structures are PRIVATE starting with CUPS 1.6/macOS 10.8. Please use the new accessor functions available in CUPS 1.6 and later, as these definitions will be moved to a private header file in a future release.
typedef int (*ipp_copycb_t)(void *context, ipp_t *dst, ipp_attribute_t *attr);
Document states
typedef enum ipp_dstate_e ipp_dstate_t;
Job collation types
typedef enum ipp_finishings_e ipp_finish_t;
IPP IO Callback Function
typedef ssize_t (*ipp_iocb_t)(void *context, ipp_uchar_t *buffer, size_t bytes);
Job collation types
typedef enum ipp_jcollate_e ipp_jcollate_t;
Orientation values
typedef enum ipp_orient_e ipp_orient_t;
Printer states
typedef enum ipp_pstate_e ipp_pstate_t;
Qualities
typedef enum ipp_quality_e ipp_quality_t;
Resolution units
typedef enum ipp_res_e ipp_res_t;
IPP states
typedef enum ipp_state_e ipp_state_t;
IPP request/response data
typedef struct _ipp_s ipp_t;
Unsigned 8-bit integer/character
typedef unsigned char ipp_uchar_t;
Map element - PPD to/from PWG
typedef struct pwg_map_s pwg_map_t;
Common media size data
typedef struct pwg_media_s pwg_media_t;
Size element - PPD to/from PWG
typedef struct pwg_size_s pwg_size_t;
Destination
struct cups_dest_s {
char *name, *instance;
int is_default;
int num_options;
cups_option_t *options;
};
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;
};
Printer Options
struct cups_option_s {
char *name;
char *value;
};
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;
};
cups_adv_t
)cups_cut_t
)cups_jog_t
)cups_edge_t
)cups_orient_t
)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;
};
cups_adv_t
)cups_cut_t
)cups_jog_t
)cups_edge_t
)cups_orient_t
)Media Size
struct cups_size_s {
char media[128];
int width, length, bottom, left, right, top;
};
Local functions...
struct gss_auth_identity {
gss_buffer_t *credentialsRef;
uint32_t flags;
char *password;
char *realm;
uint32_t type;
char *username;
};
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;
};
HTTP credential data
struct http_credential_s {
void *data;
size_t datalen;
};
User data (unused)
struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {
void) context;
void) timeout;
};
Map element - PPD to/from PWG
struct pwg_map_s {
char *pwg, *ppd;
};
Common media size data
struct pwg_media_s {
int width, length;
const char *pwg, *legacy, *ppd;
};
Size element - PPD to/from PWG
struct pwg_size_s {
pwg_map_t map;
int width, length, left, bottom, right, top;
};
AdvanceMedia attribute values
Boolean type
cupsColorSpace attribute values
CutMedia attribute values
LeadingEdge attribute values
Jog attribute values
cupsRasterOpen modes
cupsColorOrder attribute values
Orientation attribute values
Printer type/capability bit constants
HTTP authentication types
HTTP transfer encoding values
HTTP encryption values
HTTP field names
HTTP keep-alive values
HTTP state values; states are server-oriented...
HTTP status codes
Level of trust for credentials
URI en/decode flags
URI separation status
HTTP version numbers
Document states
Finishings
Job collation types
Job states
IPP operations
ippOpValue
Orientation values
Printer states
Qualities
Resolution units
IPP states
IPP status codes
ippErrorValue
Format tags for attributes
ippTagValue