| 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.
Get the default paper size.
char *appleGetPaperSize (
char *name,
int namesize
);
Default paper size
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
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.
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).
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_ENCRYPT_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.
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 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 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_OK is returned for a new PPD file and
HTTP_NOT_MODIFIED if the existing PPD file is up-to-date. Any other
status is an error.
For classes, cupsGetPPD3 returns the PPD file for the first printer
in the class.
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
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_ENCRYPT_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.
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.
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;
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;
};
Get the Apple language identifier associated with a locale ID.
const char *locale) CF_RETURNS_RETAINED;
Printer type/capability bit constants