The CUPS APIs provide...
The <cups/cups.h> header file must be included to use the CUPS functions.
Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library:
gcc -o myprogram myprogram.c -lcups
Unless otherwise specified, the CUPS API functions require CUPS 1.1 or higher.
Not a typedef'd enum so we can OR
| Name | Description |
|---|---|
| CUPS_PRINTER_AUTHENTICATED CUPS 1.2 | Printer requires authentication |
| CUPS_PRINTER_BIND | Can bind output |
| CUPS_PRINTER_BW | Can do B&W printing |
| CUPS_PRINTER_CLASS | Printer class |
| CUPS_PRINTER_COLLATE | Can collage copies |
| CUPS_PRINTER_COLOR | Can do color printing |
| CUPS_PRINTER_COPIES | Can do copies |
| CUPS_PRINTER_COVER | Can cover output |
| CUPS_PRINTER_DEFAULT | Default printer on network |
| CUPS_PRINTER_DELETE CUPS 1.2 | Delete printer |
| CUPS_PRINTER_DUPLEX | Can do duplexing |
| CUPS_PRINTER_FAX | Fax queue |
| CUPS_PRINTER_IMPLICIT | Implicit class |
| CUPS_PRINTER_LARGE | Can do D/E/A1/A0 |
| CUPS_PRINTER_LOCAL | Local printer or class |
| CUPS_PRINTER_MEDIUM | Can do Tabloid/B/C/A3/A2 |
| CUPS_PRINTER_NOT_SHARED CUPS 1.2 | Printer is not shared |
| CUPS_PRINTER_OPTIONS | ~(CLASS | REMOTE | IMPLICIT) |
| CUPS_PRINTER_PUNCH | Can punch output |
| CUPS_PRINTER_REJECTING | Printer is rejecting jobs |
| CUPS_PRINTER_REMOTE | Remote printer or class |
| CUPS_PRINTER_SMALL | Can do Letter/Legal/A4 |
| CUPS_PRINTER_SORT | Can sort output |
| CUPS_PRINTER_STAPLE | Can staple output |
| CUPS_PRINTER_VARIABLE | Can do variable sizes |
Add a destination to the list of destinations. Use the cupsSaveDests() function to save the updated list of destinations to the user's lpoptions file.
int
cupsAddDest(
const char * name,
const char * instance,
int num_dests,
cups_dest_t ** dests);
| Name | Description |
|---|---|
| name | Name of destination |
| instance | Instance of destination or NULL for none/primary |
| num_dests | Number of destinations |
| dests | Destinations |
New number of destinations
Add an option to an option array.
int
cupsAddOption(
const char * name,
const char * value,
int num_options,
cups_option_t ** options);
| Name | Description |
|---|---|
| name | Name of option |
| value | Value of option |
| num_options | Number of options |
| options | Pointer to options |
Number of options
Cancel a print job on the default server. Use the cupsLastError() and cupsLastErrorString() functions to get the cause of any failure.
int
cupsCancelJob(
const char * name,
int job);
| Name | Description |
|---|---|
| name | Name of printer or class |
| job | Job ID |
1 on success, 0 on failure
Authenticate a request. This function should be called in response to a HTTP_UNAUTHORIZED status, prior to resubmitting your request.
int
cupsDoAuthentication(
http_t * http,
const char * method,
const char * resource);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| method | Request method (GET, POST, PUT) |
| resource | Resource path |
0 on success, -1 on error
Do an IPP request. This function sends any IPP request to the specified server, retrying and authenticating as necessary.
ipp_t *
cupsDoFileRequest(
http_t * http,
ipp_t * request,
const char * resource,
const char * filename);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| request | IPP request |
| resource | HTTP resource for POST |
| filename | File to send or NULL for none |
Response data
Encode printer options into IPP attributes. This function adds operation, job, and then subscription attributes, in that order. Use the cupsEncodeOptions2() function to add attributes for a single group.
void
cupsEncodeOptions(
ipp_t * ipp,
int num_options,
cups_option_t * options);
| Name | Description |
|---|---|
| ipp | Request to add to |
| num_options | Number of options |
| options | Options |
Nothing.
Encode printer options into IPP attributes for a group. 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.
void
cupsEncodeOptions2(
ipp_t * ipp,
int num_options,
cups_option_t * options,
ipp_tag_t group_tag);
| Name | Description |
|---|---|
| ipp | Request to add to |
| num_options | Number of options |
| options | Options |
| group_tag | Group to encode |
Nothing.
Get the default encryption settings. The default encryption setting comes from the CUPS_ENCRYPTION environment variable, then the ~/.cupsrc file, and finally the /etc/cups/client.conf file. If not set, the default is HTTP_ENCRYPT_IF_REQUESTED.
http_encryption_t cupsEncryption(void);
None.
Encryption settings
Free the memory used by the list of destinations.
void
cupsFreeDests(
int num_dests,
cups_dest_t * dests);
| Name | Description |
|---|---|
| num_dests | Number of destinations |
| dests | Destinations |
Nothing.
Free memory used by job data.
void
cupsFreeJobs(
int num_jobs,
cups_job_t * jobs);
| Name | Description |
|---|---|
| num_jobs | Number of jobs |
| jobs | Jobs |
Nothing.
Free all memory used by options.
void
cupsFreeOptions(
int num_options,
cups_option_t * options);
| Name | Description |
|---|---|
| num_options | Number of options |
| options | Pointer to options |
Nothing.
Get a list of printer classes from the default server. This function is deprecated - use cupsGetDests() instead.
int
cupsGetClasses(
char *** classes);
| Name | Description |
|---|---|
| classes | Classes |
Number of classes
Get the default printer or class for the default server. 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.
const char * cupsGetDefault(void);
None.
Default printer or NULL
Get the default printer or class for the specified server. 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.
const char *
cupsGetDefault2(
http_t * http);
| Name | Description |
|---|---|
| http | HTTP connection |
Default printer or NULL
Get the named destination from the list. Use the cupsGetDests() or cupsGetDests2() functions to get a list of supported destinations for the current user.
cups_dest_t *
cupsGetDest(
const char * name,
const char * instance,
int num_dests,
cups_dest_t * dests);
| Name | Description |
|---|---|
| name | Name of destination |
| instance | Instance of destination |
| num_dests | Number of destinations |
| dests | Destinations |
Destination pointer or NULL
Get the list of destinations from the default server.
int
cupsGetDests(
cups_dest_t ** dests);
| Name | Description |
|---|---|
| dests | Destinations |
Number of destinations
Get the list of destinations from the specified server.
int
cupsGetDests2(
http_t * http,
cups_dest_t ** dests);
| Name | Description |
|---|---|
| http | HTTP connection |
| dests | Destinations |
Number of destinations
Get a file from the server. This function returns HTTP_OK when the file is successfully retrieved.
http_status_t
cupsGetFd(
http_t * http,
const char * resource,
int fd);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| resource | Resource name |
| fd | File descriptor |
Status
Get a file from the server. This function returns HTTP_OK when the file is successfully retrieved.
http_status_t
cupsGetFile(
http_t * http,
const char * resource,
const char * filename);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| resource | Resource name |
| filename | Filename |
Status
Get the jobs from the default server.
int
cupsGetJobs(
cups_job_t ** jobs,
const char * mydest,
int myjobs,
int completed);
| Name | Description |
|---|---|
| jobs | Job data |
| mydest | Only show jobs for dest? |
| myjobs | Only show my jobs? |
| completed | Only show completed jobs? |
Number of jobs
Get the jobs from the specified server.
int
cupsGetJobs2(
http_t * http,
cups_job_t ** jobs,
const char * mydest,
int myjobs,
int completed);
| Name | Description |
|---|---|
| http | HTTP connection |
| jobs | Job data |
| mydest | Only show jobs for dest? |
| myjobs | Only show my jobs? |
| completed | Only show completed jobs? |
Number of jobs
Get an option value.
const char *
cupsGetOption(
const char * name,
int num_options,
cups_option_t * options);
| Name | Description |
|---|---|
| name | Name of option |
| num_options | Number of options |
| options | Options |
Option value or NULL
Get the PPD file for a printer on the default server. For classes, cupsGetPPD() returns the PPD file for the first printer in the class.
const char *
cupsGetPPD(
const char * name);
| Name | Description |
|---|---|
| name | Printer name |
Filename for PPD file
Get the PPD file for a printer from the specified server. For classes, cupsGetPPD2() returns the PPD file for the first printer in the class.
const char *
cupsGetPPD2(
http_t * http,
const char * name);
| Name | Description |
|---|---|
| http | HTTP connection |
| name | Printer name |
Filename for PPD file
Get a password from the user. Returns NULL if the user does not provide a password.
const char *
cupsGetPassword(
const char * prompt);
| Name | Description |
|---|---|
| prompt | Prompt string |
Password
Get a list of printers from the default server. This function is deprecated - use cupsGetDests() instead.
int
cupsGetPrinters(
char *** printers);
| Name | Description |
|---|---|
| printers | Printers |
Number of printers
Return the default language.
cups_lang_t * cupsLangDefault(void);
None.
Language data
Return the character encoding (us-ascii, etc.) for the given language.
const char *
cupsLangEncoding(
cups_lang_t * lang);
| Name | Description |
|---|---|
| lang | Language data |
Character encoding
Flush all language data out of the cache.
void cupsLangFlush(void);
None.
Nothing.
Free language data. This does not actually free anything; use cupsLangFlush() for that.
void
cupsLangFree(
cups_lang_t * lang);
| Name | Description |
|---|---|
| lang | Language to free |
Nothing.
Get a language.
cups_lang_t *
cupsLangGet(
const char * language);
| Name | Description |
|---|---|
| language | Language or locale |
Language data
Return the last IPP status code.
ipp_status_t cupsLastError(void);
None.
IPP status code from last request
Return the last IPP status-message.
const char * cupsLastErrorString(void);
None.
status-message text from last request
Mark command-line options in a PPD file.
int
cupsMarkOptions(
ppd_file_t * ppd,
int num_options,
cups_option_t * options);
| Name | Description |
|---|---|
| ppd | PPD file |
| num_options | Number of options |
| options | Options |
1 if conflicting
Parse options from a command-line argument. This function converts space-delimited name/value pairs according to the PAPI text option ABNF specification. Collection values ("name={a=... b=... c=...}") are stored with the curley brackets intact - use cupsParseOptions() on the value to extract the collection attributes.
int
cupsParseOptions(
const char * arg,
int num_options,
cups_option_t ** options);
| Name | Description |
|---|---|
| arg | Argument to parse |
| num_options | Number of options |
| options | Options found |
Number of options found
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);
| Name | Description |
|---|---|
| name | Printer or class name |
| filename | File to print |
| title | Title of job |
| num_options | Number of options |
| options | Options |
Job ID
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);
| Name | Description |
|---|---|
| http | HTTP connection |
| name | Printer or class name |
| filename | File to print |
| title | Title of job |
| num_options | Number of options |
| options | Options |
Job ID
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);
| Name | Description |
|---|---|
| name | Printer or class name |
| num_files | Number of files |
| files | File(s) to print |
| title | Title of job |
| num_options | Number of options |
| options | Options |
Job ID
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);
| Name | Description |
|---|---|
| http | HTTP connection |
| name | Printer or class name |
| num_files | Number of files |
| files | File(s) to print |
| title | Title of job |
| num_options | Number of options |
| options | Options |
Job ID
Put a file on the server. This function returns HTTP_CREATED when the file is stored successfully.
http_status_t
cupsPutFd(
http_t * http,
const char * resource,
int fd);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| resource | Resource name |
| fd | File descriptor |
Status
Put a file on the server. This function returns HTTP_CREATED when the file is stored successfully.
http_status_t
cupsPutFile(
http_t * http,
const char * resource,
const char * filename);
| Name | Description |
|---|---|
| http | HTTP connection to server |
| resource | Resource name |
| filename | Filename |
Status
Return the hostname/address of the default server. The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname.
const char * cupsServer(void);
None.
Server name
Save the list of destinations for the default server. This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.lpoptions when run as a normal user.
void
cupsSetDests(
int num_dests,
cups_dest_t * dests);
| Name | Description |
|---|---|
| num_dests | Number of destinations |
| dests | Destinations |
Nothing.
Save the list of destinations for the specified server. This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.lpoptions when run as a normal user.
int
cupsSetDests2(
http_t * http,
int num_dests,
cups_dest_t * dests);
| Name | Description |
|---|---|
| http | HTTP connection |
| num_dests | Number of destinations |
| dests | Destinations |
0 on success, -1 on error
Set the encryption preference.
void
cupsSetEncryption(
http_encryption_t e);
| Name | Description |
|---|---|
| e | New encryption preference |
Nothing.
Set the password callback for CUPS. Pass NULL to restore the default (console) password callback.
void
cupsSetPasswordCB(
cups_password_cb_t cb);
| Name | Description |
|---|---|
| cb | Callback function |
Nothing.
Set the default server name. The "server" string can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to restore the default server name.
void
cupsSetServer(
const char * server);
| Name | Description |
|---|---|
| server | Server name |
Nothing.
Set the default user name. Pass NULL to restore the default user name.
void
cupsSetUser(
const char * user);
| Name | Description |
|---|---|
| user | User name |
Nothing.
Create a temporary file. The temporary filename is stored in the filename buffer.
int
cupsTempFd(
char * filename,
int len);
| Name | Description |
|---|---|
| filename | Pointer to buffer |
| len | Size of buffer |
New file descriptor
Generate a temporary filename. The temporary filename is stored in the filename buffer. This function is deprecated - use cupsTempFd() or cupsTempFile2() instead.
char *
cupsTempFile(
char * filename,
int len);
| Name | Description |
|---|---|
| filename | Pointer to buffer |
| len | Size of buffer |
Filename
Create a temporary CUPS file. The temporary filename is stored in the filename buffer.
cups_file_t *
cupsTempFile2(
char * filename,
int len);
| Name | Description |
|---|---|
| filename | Pointer to buffer |
| len | Size of buffer |
CUPS file or NULL on error
Return the current user's name.
const char * cupsUser(void);
None.
User name
Destination
struct cups_dest_s
{
char *name, * instance;
int is_default;
int num_options;
cups_option_t * options;
};
| Name | Description |
|---|---|
| instance | Local instance name or NULL |
| is_default | Is this printer the default? |
| num_options | Number of options |
| options | Options |
Job
struct cups_job_s
{
char *dest, *title, *user, * format;
int id;
int size, priority;
time_t completed_time, creation_time, processing_time;
ipp_jstate_t state;
};
| Name | Description |
|---|---|
| format | Document format |
| id | The job ID |
| priority | Priority (1-100) |
| processing_time | Time the job was processed |
| state | Job state |
Types and structures...
struct cups_option_s
{
char * name;
char * value;
};
| Name | Description |
|---|---|
| name | Name of option |
| value | Value of option |
Printer Options
typedef const * (*charcups_password_cb_t)(const char *);
Destination
typedef struct cups_dest_s cups_dest_t;
Job
typedef struct cups_job_s cups_job_t;
Types and structures...
typedef struct cups_option_s cups_option_t;
Printer Type/Capability Bits
typedef unsigned cups_ptype_t;