| 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.
+ +The CUPS library provides a whole collection of interfaces -needed to support the internal needs of the CUPS software as well -as the needs of applications, filters, printer drivers, and -backends.
+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.
Unlike the rest of CUPS, the CUPS API library is provided -under the GNU Library General Public License. This means that you -can use the CUPS API library in both proprietary and open-source -programs.
+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:
The <cups/cups.h> header file must be included to -use the CUPS functions.
++#include <cups/cups.h> -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:
+cups_dest_t *dests; +int num_dests = cupsGetDests(&dests); +cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests); --gcc -o myprogram myprogram.c -lcups +/* do something with dest */ + +cupsFreeDests(num_dests, dests);-Compatibility
+Passing
-NULLto +cupsGetDestfor the destination name +will return the default destination. Similarly, passing aNULL+instance will return the default instance for that destination.Unless otherwise specified, the CUPS API functions require -CUPS 1.1 or higher.
-Contents
-
Not a typedef'd enum so we can OR
-| Name | Description |
|---|
| Attribute 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_COMMANDS CUPS 1.2 | Printer supports maintenance commands |
| 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); ++ +"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);-
| 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); + +You can create your own option arrays using the +
+ +cupsAddOptionfunction, 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);-Arguments
---
- - Name Description - name Name of option - value Value of option - num_options Number of options - options Pointer to options Returns
-Number of options
- -cupsCancelJob()
-Description
-Cancel a print job on the default server. - -Use the cupsLastError() and cupsLastErrorString() functions to get -the cause of any failure.
-Syntax
--int -cupsCancelJob( - const char * name, - int job); + +Use a
+ +forloop 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);-Arguments
---
- - Name Description - name Name of printer or class - job Job ID Returns
-1 on success, 0 on failure
- -cupsEncryption()
-Description
-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.
-Syntax
--http_encryption_t -cupsEncryption(void); + +Use the
+ +cupsFreeOptions+function to free the options array when you are done using it:+cupsFreeOptions(num_options, options);-Arguments
-None.
-Returns
-Encryption settings
- -cupsFreeDests()
-Description
-Free the memory used by the list of destinations.
-Syntax
--void -cupsFreeDests( - int num_dests, - cups_dest_t * dests); + +Print Jobs
+ +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);-Arguments
---
- - Name Description - num_dests Number of destinations - dests Destinations Returns
-Nothing.
- -cupsFreeJobs()
-Description
-Free memory used by job data.
-Syntax
--void -cupsFreeJobs( - int num_jobs, - cups_job_t * jobs); + +The
+ +cupsPrintFilesfunction +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);-Arguments
---
- - Name Description - num_jobs Number of jobs - jobs Jobs Returns
-Nothing.
- -cupsFreeOptions()
-Description
-Free all memory used by options.
-Syntax
--void -cupsFreeOptions( - int num_options, - cups_option_t * options); + +Finally, the
+ +cupsCreateJob+function creates a new job with no files in it. Files are added using the +cupsStartDocument, +cupsWriteRequestData, +andcupsFinishDocumentfunctions. +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); + } +}-Arguments
---
- - Name Description - num_options Number of options - options Pointer to options Returns
-Nothing.
- -DEPRECATED cupsGetClasses()
-Description
-Get a list of printer classes from the default server. - -This function is deprecated - use cupsGetDests() instead. - -
-Syntax
--int -cupsGetClasses( - char *** classes); + +Once you have created a job, you can monitor its status using the +
+ +cupsGetJobsfunction, which returns +an array ofcups_job_tstructures. +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 +cupsFreeJobsfunction. 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); +}-Arguments
---
- - Name Description - classes Classes Returns
-Number of classes
- -cupsGetDefault()
-Description
-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.
-Syntax
-+ +To cancel a job, use the +
+ +cupsCancelJobfunction with the +job ID:+#include <cups/cups.h> + +cups_dest_t *dest; +int job_id; + +cupsCancelJob(dest->name, job_id); ++ +Error Handling
+ +If any of the CUPS API printing functions returns an error, the reason for +that error can be found by calling the +
+ +cupsLastErrorand +cupsLastErrorStringfunctions. +cupsLastErrorreturns the last IPP +error code +(ipp_status_t) +that was encountered, while +cupsLastErrorStringreturns +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 +cupsLastErrorStringto show +the reason why the job could not be created:+#include <cups/cups.h> + +int job_id; + +if (job_id == 0) + puts(cupsLastErrorString()); ++ +Passwords and Authentication
+ +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
+ +cupsSetUserfunction 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 * -cupsGetDefault(void); +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);-Arguments
-None.
-Returns
-Default printer or NULL
- -CUPS 1.1.21 cupsGetDefault2()
-Description
-Get the default printer or class for the specified server. - -This function returns the default printer or class as defined by + +
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.Functions
+cupsAddDest
+Add a destination to the list of destinations.
++int cupsAddDest (
+
+ const char *name,
+ const char *instance,
+ int num_dests,
+ cups_dest_t **dests
+);Parameters
+
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 and no longer returns a list of printer
+classes - use cupsGetDests instead.
+
+
Get the default printer or class for the default server.
++const char *cupsGetDefault (void);
+Default printer or NULL
This function returns the default printer or class as defined by
the LPDEST or PRINTER environment variables. If these environment
variables are not set, the server default destination is returned.
-Applications should use the cupsGetDests() and cupsGetDest() functions
-to get the user-defined default printer, as this function does not
-support the lpoptions-defined default printer.
+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.
-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 +
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.
-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. - -Starting with CUPS 1.2, the returned list of destinations include the +
Get a media name, dimension, and margins for a +specific size.
+
+int cupsGetDestMediaByIndex (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ int n,
+ unsigned flags,
+ cups_size_t *size
+);
1 on success, 0 on failure
+The flags parameter determines which set of media are indexed. For
+example, passing CUPS_MEDIA_FLAGS_BORDERLESS will get the Nth
+borderless size supported by the printer.
+
+
Get media names, dimensions, and margins.
+
+int cupsGetDestMediaByName (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *media,
+ unsigned flags,
+ cups_size_t *size
+);
1 on match, 0 on failure
+The "media" string is a PWG media name. "Flags" provides some matching
+guidance (multiple flags can be combined):
+
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.
+
+The matching result (if any) is returned in the "cups_size_t" structure.
+
+Returns 1 when there is a match and 0 if there is not a match.
+
+
Get media names, dimensions, and margins.
+
+int cupsGetDestMediaBySize (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ int width,
+ int length,
+ unsigned flags,
+ cups_size_t *size
+);
1 on match, 0 on failure
+"Width" and "length" are the dimensions in hundredths of millimeters.
+"Flags" provides some matching guidance (multiple flags can be combined):
+
+CUPS_MEDIA_FLAGS_DEFAULT = find the closest size supported by the printer,
+CUPS_MEDIA_FLAGS_BORDERLESS = find a borderless size,
+CUPS_MEDIA_FLAGS_DUPLEX = find a size compatible with 2-sided printing,
+CUPS_MEDIA_FLAGS_EXACT = find an exact match for the size, and
+CUPS_MEDIA_FLAGS_READY = if the printer supports media sensing, find the
+size amongst the "ready" media.
+
+The matching result (if any) is returned in the "cups_size_t" structure.
+
+Returns 1 when there is a match and 0 if there is not a match.
+
+
Get the number of sizes supported by a +destination.
+
+int cupsGetDestMediaCount (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ unsigned flags
+);
Number of sizes
+The flags parameter determines the set of media sizes that are
+counted. For example, passing CUPS_MEDIA_FLAGS_BORDERLESS will return
+the number of borderless sizes.
+
+
Get the default size for a destination.
+
+int cupsGetDestMediaDefault (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ unsigned flags,
+ cups_size_t *size
+);
1 on success, 0 on failure
+The flags parameter determines which default size is returned. For
+example, passing CUPS_MEDIA_FLAGS_BORDERLESS will return the default
+borderless size, typically US Letter or A4, but sometimes 4x6 photo media.
+
+
Get a destination associated with a URI.
+
+cups_dest_t *cupsGetDestWithURI (
+ const char *name,
+ const char *uri
+);
NULLDestination or NULL
"name" is the desired name for the printer. If NULL, a name will be
+created using the URI.
+
+"uri" is the "ipp" or "ipps" URI for the printer.
+
+
Get the list of destinations from the default server.
+
+int cupsGetDests (
+ cups_dest_t **dests
+);
Number of destinations
+Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, -printer-state-reasons, and printer-type attributes as options.
--int -cupsGetDests( - cups_dest_t ** dests); --
| Name | Description |
|---|---|
| dests | Destinations |
Number of destinations
- -Get the list of destinations from the specified server.
-
-Starting with CUPS 1.2, the returned list of destinations include the
+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.
+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.
-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 |
HTTP 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 |
HTTP 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 | NULL = all destinations, * -otherwise show jobs for mydest |
| myjobs | 0 = all users, 1 = mine |
| completed | -1 = show all, 0 = active, * -1 = 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 | NULL = all destinations, * -otherwise show jobs for mydest |
| myjobs | 0 = all users, 1 = mine |
| completed | -1 = show all, 0 = active, * -1 = 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 +
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.
-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. - -Uses the current password callback function. 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.) +
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 and no longer returns a list of printers - 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); --
| 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 +
+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 media +size.
+
+const char *cupsLocalizeDestMedia (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ unsigned flags,
+ cups_size_t *size
+);
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +
+Get the localized string for a destination +option.
+
+const char *cupsLocalizeDestOption (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *option
+);
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +
+Get the localized string for a destination +option+value pair.
+
+const char *cupsLocalizeDestValue (
+ http_t *http,
+ cups_dest_t *dest,
+ cups_dinfo_t *dinfo,
+ const char *option,
+ const char *value
+);
Localized string
+The returned string is stored in the destination information and will become +invalid if the destination information is deleted. + +
+Return the subject for the given notification message.
+
+char *cupsNotifySubject (
+ cups_lang_t *lang,
+ ipp_t *event
+);
Subject string or NULL
The returned string must be freed by the caller using free.
+
+
Return the text for the given notification message.
+
+char *cupsNotifyText (
+ cups_lang_t *lang,
+ ipp_t *event
+);
Message text or NULL
The returned string must be freed by the caller using free.
+
+
Parse options from a command-line argument.
+
+int cupsParseOptions (
+ const char *arg,
+ int num_options,
+ cups_option_t **options
+);
Number of options found
+This function converts space-delimited name/value pairs according to the PAPI text option ABNF specification. Collection values ("name={a=... b=... c=...}") are stored with the curley brackets -intact - use cupsParseOptions() on the value to extract the collection -attributes.
--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
+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); --
| 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 |
HTTP 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 |
HTTP status
- -Remove an option from an option array. - -
--int -cupsRemoveOption( - const char * name, - int num_options, - cups_option_t ** options); --
| Name | Description |
|---|---|
| name | Option name |
| num_options | Current number of options |
| options | Options |
New number of options
- -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 +
+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.
--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 +
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.
--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. +
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.
-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
-{
- 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;
-};
-
-| Name | Description |
|---|---|
| completed_time | Time the job was completed |
| creation_time | Time the job was created |
| dest | Printer or class name |
| format | Document format |
| id | The job ID |
| priority | Priority (1-100) |
| processing_time | Time the job was processed |
| size | Size in kilobytes |
| state | Job state |
| title | Title/job name |
| user | User the submitted the job |
Printer Options
-
-struct cups_option_s
-{
- char * name;
- char * value;
-};
-
-| Name | Description |
|---|---|
| name | Name of option |
| value | Value of option |
Destination
--typedef struct cups_dest_s cups_dest_t; -- -
Job
--typedef struct cups_job_s cups_job_t; -- -
Printer Options
--typedef struct cups_option_s cups_option_t; -- -
Password callback
--typedef const char * (*cups_password_cb_t)(const char *); -- -
Printer Type/Capability Bits
-+cupsSetServer
+Set the default server name and port.
++void cupsSetServer (
+
+ const char *server
+);Parameters
+
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 and will no longer generate a temporary
+filename - 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
+