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 wiith 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" | "1" if the destination is accepting new jobs, "0" if not. |
"printer-is-shared" | "1" if the destination is being shared with other computers, "0" if not. |
"printer-location" | The human-readable location of the destination such as "Lab 4". |
"printer-make-and-model" | The human-readable make and model of the destination such as "HP LaserJet 4000 Series". |
"printer-state" | "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped. |
"printer-state-change-time" | The UNIX time when the destination entered the current state. |
"printer-state-reasons" | Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning". |
"printer-type" | The cups_printer_t
value associated with the destination. |
Options 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_DEFAULT
PPD 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_DEFAULT
1 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_DEFAULT
1 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_DEFAULT
CUPS_JOBID_CURRENT
for the current job, or CUPS_JOBID_ALL
for all jobsIPP status
Canceled jobs remain in the job history while purged jobs are removed
from the job history.
Pass CUPS_JOBID_ALL
to cancel all jobs or CUPS_JOBID_CURRENT
to cancel the current job on the named destination.
Use the cupsLastError
and cupsLastErrorString
functions to get
the cause of any failure.
Create an empty job for streaming.
int cupsCreateJob (
http_t *http,
const char *name,
const char *title,
int num_options,
cups_option_t *options
);
CUPS_HTTP_DEFAULT
Job ID or 0 on error
Use this function when you want to stream print data using the
cupsStartDocument
, cupsWriteRequestData
, and
cupsFinishDocument
functions. If you have one or more files to
print, use the cupsPrintFile2
or cupsPrintFiles2
function
instead.
Get the default 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
.
Finish sending a document.
ipp_status_t cupsFinishDocument (
http_t *http,
const char *name
);
CUPS_HTTP_DEFAULT
Status of document submission
The document must have been started using cupsStartDocument
.
Free 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_DEFAULT
Default printer or NULL
This function returns the default printer or class as defined by
the LPDEST or PRINTER environment variables. If these environment
variables are not set, the server default destination is returned.
Applications should use the cupsGetDests
and cupsGetDest
functions to get the user-defined default printer, as this function does
not support the lpoptions-defined default printer.
Get the named destination from the list.
cups_dest_t *cupsGetDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
for the default destinationNULL
Destination pointer or NULL
Use the cupsGetDests
or cupsGetDests2
functions to get a
list of supported destinations for the current user.
Get the list of destinations from the default server.
int cupsGetDests (
cups_dest_t **dests
);
Number of destinations
Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
printer-state-reasons, and printer-type attributes as options. CUPS 1.4
adds the marker-change-time, marker-colors, marker-high-levels,
marker-levels, marker-low-levels, marker-message, marker-names,
marker-types, and printer-commands attributes as well.
Use the cupsFreeDests
function to free the destination list and
the cupsGetDest
function to find a particular destination.
Get the list of destinations from the specified server.
int cupsGetDests2 (
http_t *http,
cups_dest_t **dests
);
CUPS_HTTP_DEFAULT
Number of destinations
Starting with CUPS 1.2, the returned list of destinations include the
printer-info, printer-is-accepting-jobs, printer-is-shared,
printer-make-and-model, printer-state, printer-state-change-time,
printer-state-reasons, and printer-type attributes as options. CUPS 1.4
adds the marker-change-time, marker-colors, marker-high-levels,
marker-levels, marker-low-levels, marker-message, marker-names,
marker-types, and printer-commands attributes as well.
Use the cupsFreeDests
function to free the destination list and
the cupsGetDest
function to find a particular destination.
Get the jobs from the default server.
int cupsGetJobs (
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);
NULL
= all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL
, CUPS_WHICHJOBS_ACTIVE
, or CUPS_WHICHJOBS_COMPLETED
Number of jobs
A "whichjobs" value of CUPS_WHICHJOBS_ALL
returns all jobs regardless
of state, while CUPS_WHICHJOBS_ACTIVE
returns jobs that are
pending, processing, or held and CUPS_WHICHJOBS_COMPLETED
returns
jobs that are stopped, canceled, aborted, or completed.
Get the jobs from the specified server.
int cupsGetJobs2 (
http_t *http,
cups_job_t **jobs,
const char *name,
int myjobs,
int whichjobs
);
CUPS_HTTP_DEFAULT
NULL
= all destinations, otherwise show jobs for named destinationCUPS_WHICHJOBS_ALL
, CUPS_WHICHJOBS_ACTIVE
, or CUPS_WHICHJOBS_COMPLETED
Number of jobs
A "whichjobs" value of CUPS_WHICHJOBS_ALL
returns all jobs regardless
of state, while CUPS_WHICHJOBS_ACTIVE
returns jobs that are
pending, processing, or held and CUPS_WHICHJOBS_COMPLETED
returns
jobs that are stopped, canceled, aborted, or completed.
Get options for the named destination.
cups_dest_t *cupsGetNamedDest (
http_t *http,
const char *name,
const char *instance
);
CUPS_HTTP_DEFAULT
NULL
for the default destinationNULL
Destination or NULL
This function is optimized for retrieving a single destination and should
be used instead of cupsGetDests
and cupsGetDest
when you either
know the name of the destination or want to print to the default destination.
If NULL
is returned, the destination does not exist or there is no
default destination.
If "http" is CUPS_HTTP_DEFAULT
, the connection to the default print
server will be used.
If "name" is NULL
, the default printer for the current user will be
returned.
The returned destination must be freed using cupsFreeDests
with a
"num_dests" value of 1.
Get an option value.
const char *cupsGetOption (
const char *name,
int num_options,
cups_option_t *options
);
Option value or NULL
Get 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_DEFAULT
Filename 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_DEFAULT
HTTP 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.
Get a password from the user using the advanced callback.
const char *cupsGetPassword2 (
const char *prompt,
http_t *http,
const char *method,
const char *resource
);
CUPS_HTTP_DEFAULT
Password
Uses the current password callback function. Returns NULL
if the
user does not provide a password.
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_DEFAULT
Name 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 last IPP status code.
ipp_status_t cupsLastError (void);
IPP status code from last request
Return the last IPP status-message.
const char *cupsLastErrorString (void);
status-message text from last request
Return the subject for the given notification message.
char *cupsNotifySubject (
cups_lang_t *lang,
ipp_t *event
);
Subject string or NULL
The returned string must be freed by the caller using free
.
Return the text for the given notification message.
char *cupsNotifyText (
cups_lang_t *lang,
ipp_t *event
);
Message text or NULL
The returned string must be freed by the caller using free
.
Parse options from a command-line argument.
int cupsParseOptions (
const char *arg,
int num_options,
cups_option_t **options
);
Number of options found
This function converts space-delimited name/value pairs according
to the PAPI text option ABNF specification. Collection values
("name={a=... b=... c=...}") are stored with the curley brackets
intact - use cupsParseOptions
on the value to extract the
collection attributes.
Print a file to a printer or class on the default server.
int cupsPrintFile (
const char *name,
const char *filename,
const char *title,
int num_options,
cups_option_t *options
);
Job ID or 0 on error
Print a file to a printer or class on the specified server.
int cupsPrintFile2 (
http_t *http,
const char *name,
const char *filename,
const char *title,
int num_options,
cups_option_t *options
);
Job ID or 0 on error
Print one or more files to a printer or class on the default server.
int cupsPrintFiles (
const char *name,
int num_files,
const char **files,
const char *title,
int num_options,
cups_option_t *options
);
Job ID or 0 on error
Print one or more files to a printer or class on the specified server.
int cupsPrintFiles2 (
http_t *http,
const char *name,
int num_files,
const char **files,
const char *title,
int num_options,
cups_option_t *options
);
CUPS_HTTP_DEFAULT
Job ID or 0 on error
Remove a destination from the destination list.
int cupsRemoveDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t **dests
);
NULL
New number of destinations
Removing a destination/instance does not delete the class or printer
queue, merely the lpoptions for that destination/instance. Use the
cupsSetDests
or cupsSetDests2
functions to save the new
options for the user.
Remove an option from an option array.
int cupsRemoveOption (
const char *name,
int num_options,
cups_option_t **options
);
New number of options
Return the hostname/address of the default server.
const char *cupsServer (void);
Server name
The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname.
Set the default destination.
void cupsSetDefaultDest (
const char *name,
const char *instance,
int num_dests,
cups_dest_t *dests
);
NULL
Save the list of destinations for the default server.
void cupsSetDests (
int num_dests,
cups_dest_t *dests
);
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Save the list of destinations for the specified server.
int cupsSetDests2 (
http_t *http,
int num_dests,
cups_dest_t *dests
);
CUPS_HTTP_DEFAULT
0 on success, -1 on error
This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.
Set the encryption preference.
void cupsSetEncryption (
http_encryption_t e
);
Set the password callback for CUPS.
void cupsSetPasswordCB (
cups_password_cb_t cb
);
Pass NULL
to restore the default (console) password callback.
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.
Set the default server name.
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. Pass NULL
to
restore the default server name.
Set the default user name.
void cupsSetUser (
const char *user
);
Pass NULL
to restore the default user name.
Add a document to a job created with cupsCreateJob().
http_status_t cupsStartDocument (
http_t *http,
const char *name,
int job_id,
const char *docname,
const char *format,
int last_document
);
CUPS_HTTP_DEFAULT
cupsCreateJob
CUPS_FORMAT_foo
HTTP status of request
Use cupsWriteRequestData
to write data for the document and
cupsFinishDocument
to finish the document and get the submission status.
The MIME type constants CUPS_FORMAT_AUTO
, CUPS_FORMAT_PDF
,
CUPS_FORMAT_POSTSCRIPT
, CUPS_FORMAT_RAW
, and
CUPS_FORMAT_TEXT
are provided for the "format" argument, although
any supported MIME type string can be supplied.
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
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);
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;
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;
};
Printer type/capability bit constants