| Header | cups/cups.h |
|---|---|
| Library | -lcups |
| See Also | Programming: Introduction to CUPS Programming Programming: Array API Programming: File and Directory APIs Programming: Filter and Backend Programming Programming: HTTP and IPP APIs Programming: PPD API Programming: Raster API |
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.
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.
Create the Windows PPD file for a printer.
char *cupsAdminCreateWindowsPPD (
http_t *http,
const char *dest,
char *buffer,
int bufsize
);
CUPS_HTTP_DEFAULTPPD file or NULL
Export a printer to Samba.
int cupsAdminExportSamba (
const char *dest,
const char *ppd,
const char *samba_server,
const char *samba_user,
const char *samba_password,
FILE *logfile
);
1 on success, 0 on failure
Get settings from the server.
int cupsAdminGetServerSettings (
http_t *http,
int *num_settings,
cups_option_t **settings
);
CUPS_HTTP_DEFAULT1 on success, 0 on failure
The returned settings should be freed with cupsFreeOptions() when you are done with them.
Set settings on the server.
int cupsAdminSetServerSettings (
http_t *http,
int num_settings,
cups_option_t *settings
);
CUPS_HTTP_DEFAULT1 on success, 0 on failure
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_NOT_AUTHORIZED or IPP_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_DEFAULTCUPS_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_DEFAULTJob 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.
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_DEFAULTStatus 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 - 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_DEFAULTDefault 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 destinationNULLDestination 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 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_DEFAULTNumber 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 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_COMPLETEDNumber 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_DEFAULTNULL = all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETEDNumber 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_DEFAULTNULL for the default destinationNULLDestination 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 the PPD file for a printer on the default server.
const char *cupsGetPPD (
const char *name
);
Filename for PPD file
For classes, cupsGetPPD returns the PPD file for the first printer
in the class.
The returned filename is stored in a static buffer and is overwritten with
each call to cupsGetPPD or cupsGetPPD2. The caller "owns" the
file that is created and must unlink the returned filename.
Get the PPD file for a printer from the specified server.
const char *cupsGetPPD2 (
http_t *http,
const char *name
);
CUPS_HTTP_DEFAULTFilename for PPD file
For classes, cupsGetPPD2 returns the PPD file for the first printer
in the class.
The returned filename is stored in a static buffer and is overwritten with
each call to cupsGetPPD or cupsGetPPD2. The caller "owns" the
file that is created and must unlink the returned filename.
Get the PPD file for a printer on the specified server if it has changed.
http_status_t cupsGetPPD3 (
http_t *http,
const char *name,
time_t *modtime,
char *buffer,
size_t bufsize
);
CUPS_HTTP_DEFAULTHTTP status
The "modtime" parameter contains the modification time of any
locally-cached content and is updated with the time from the PPD file on
the server.
The "buffer" parameter contains the local PPD filename. If it contains
the empty string, a new temporary file is created, otherwise the existing
file will be overwritten as needed. The caller "owns" the file that is
created and must unlink the returned filename.
On success, HTTP_STATUS_OK is returned for a new PPD file and
HTTP_STATUS_NOT_MODIFIED if the existing PPD file is up-to-date. Any other
status is an error.
For classes, cupsGetPPD3 returns the PPD file for the first printer
in the class.
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_DEFAULTPassword
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 - use cupsGetDests instead.
Get an available PPD file from the server.
char *cupsGetServerPPD (
http_t *http,
const char *name
);
CUPS_HTTP_DEFAULTName of PPD file or NULL on error
This function returns the named PPD file from the server. The
list of available PPDs is provided by the IPP CUPS_GET_PPDS
operation.
You must remove (unlink) the PPD file when you are finished with
it. The PPD filename is stored in a static location that will be
overwritten on the next call to cupsGetPPD, cupsGetPPD2,
or cupsGetServerPPD.
Return the default language.
cups_lang_t *cupsLangDefault (void);
Language data
Return the character encoding (us-ascii, etc.) for the given language.
const char *cupsLangEncoding (
cups_lang_t *lang
);
Character encoding
Flush all language data out of the cache.
void cupsLangFlush (void);
Free language data.
void cupsLangFree (
cups_lang_t *lang
);
This does not actually free anything; use cupsLangFlush for that.
Get a language.
cups_lang_t *cupsLangGet (
const char *language
);
Language data
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_DEFAULTJob ID or 0 on error
Remove a destination from the destination list.
int cupsRemoveDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULLNew 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
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
);
NULLSave 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_DEFAULT0 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
);
NULLSetting 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_DEFAULTcupsCreateJobCUPS_FORMAT_fooHTTP 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.
Creates a temporary file.
int cupsTempFd (
char *filename,
int len
);
New file descriptor or -1 on error
The temporary filename is returned in the filename buffer. The temporary file is opened for reading and writing.
Generates a temporary filename.
char *cupsTempFile (
char *filename,
int len
);
Filename or NULL on error
The temporary filename is returned in the filename buffer.
This function is deprecated - use cupsTempFd or
cupsTempFile2 instead.
Creates a temporary CUPS file.
cups_file_t *cupsTempFile2 (
char *filename,
int len
);
CUPS file or NULL on error
The temporary filename is returned in the filename buffer. The temporary file is opened for writing.
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
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 automaticNULLNULL 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.
Client credentials callback
typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);
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;
Device callback
typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);
Destination capability and status information
typedef struct _cups_dinfo_s cups_dinfo_t;
Job
typedef struct cups_job_s cups_job_t;
Printer Options
typedef struct cups_option_s cups_option_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;
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;
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;
};
Media Size
struct cups_size_s {
char media[128];
int width, length, bottom, left, right, top;
};
User data (unused)
struct pollfd *pollfds, unsigned int num_pollfds, int timeout, void *context) {
_cups_dnssd_data_t *data;
else if(val 0) data - got_data;
void) timeout;
int val;
};
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;
};
Get the Apple language identifier associated with a locale ID.
const char *locale) CF_RETURNS_RETAINED;
Printer type/capability bit constants