Home     Administration     Classes     Online Help     Jobs     Printers  
 

Search in CUPS API :

CUPS API

CUPS API

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

Contents

Overview

The CUPS API provides the convenience functions needed to support applications, filters, printer drivers, and backends that need to interface with the CUPS scheduler.

Clients and Servers

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

Printers and classes (collections of printers) are accessed through the cups_dest_t structure which includes the name (name), instance (instance - a way of selecting certain saved options/settings), and the options and attributes associated with that destination (num_options and options). Destinations are created using the cupsGetDests function and freed using the cupsFreeDests function. The cupsGetDest function finds a specific destination for printing:

#include <cups/cups.h>

cups_dest_t *dests;
int num_dests = cupsGetDests(&dests);
cups_dest_t *dest = cupsGetDest("name", NULL, num_dests, dests);

/* do something with dest */

cupsFreeDests(num_dests, dests);

Passing NULL to cupsGetDest for the destination name will return the default destination. Similarly, passing a NULL instance will return the default instance for that destination.

Table 1: Printer Attributes
Attribute Name Description
"auth-info-required" The type of authentication required for printing to this destination: "none", "username,password", "domain,username,password", or "negotiate" (Kerberos)
"printer-info" The human-readable description of the destination such as "My Laser Printer".
"printer-is-accepting-jobs" "true" if the destination is accepting new jobs, "false" if not.
"printer-is-shared" "true" if the destination is being shared with other computers, "false" if not.
"printer-location" The human-readable location of the destination such as "Lab 4".
"printer-make-and-model" The human-readable make and model of the destination such as "HP LaserJet 4000 Series".
"printer-state" "3" if the destination is idle, "4" if the destination is printing a job, and "5" if the destination is stopped.
"printer-state-change-time" The UNIX time when the destination entered the current state.
"printer-state-reasons" Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning".
"printer-type" The cups_printer_t value associated with the destination.

Options

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

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);

Error Handling

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());

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 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.

Functions

appleGetPaperSize

Get the default paper size.

char *appleGetPaperSize (
    char *name,
    int namesize
);

Parameters

name
Paper size name buffer
namesize
Size of buffer

Return Value

Default paper size

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

name
Destination name
instance
Instance name or NULL for none/primary
num_dests
Number of destinations
dests
Destinations

Return Value

New number of destinations

Discussion

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.

cupsAddOption

Add an option to an option array.

int cupsAddOption (
    const char *name,
    const char *value,
    int num_options,
    cups_option_t **options
);

Parameters

name
Name of option
value
Value of option
num_options
Number of options
options
Pointer to options

Return Value

Number of options

Discussion

New option arrays can be initialized simply by passing 0 for the "num_options" parameter.

 CUPS 1.2/Mac OS X 10.5 cupsAdminCreateWindowsPPD

Create the Windows PPD file for a printer.

char *cupsAdminCreateWindowsPPD (
    http_t *http,
    const char *dest,
    char *buffer,
    int bufsize
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
dest
Printer or class
buffer
Filename buffer
bufsize
Size of filename buffer

Return Value

PPD file or NULL

 CUPS 1.2/Mac OS X 10.5 cupsAdminExportSamba

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
);

Parameters

dest
Destination to export
ppd
PPD file
samba_server
Samba server
samba_user
Samba username
samba_password
Samba password
logfile
Log file, if any

Return Value

1 on success, 0 on failure

 CUPS 1.3/Mac OS X 10.5 cupsAdminGetServerSettings

Get settings from the server.

int cupsAdminGetServerSettings (
    http_t *http,
    int *num_settings,
    cups_option_t **settings
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
num_settings
Number of settings
settings
Settings

Return Value

1 on success, 0 on failure

Discussion

The returned settings should be freed with cupsFreeOptions() when you are done with them.

 CUPS 1.3/Mac OS X 10.5 cupsAdminSetServerSettings

Set settings on the server.

int cupsAdminSetServerSettings (
    http_t *http,
    int num_settings,
    cups_option_t *settings
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
num_settings
Number of settings
settings
Settings

Return Value

1 on success, 0 on failure

cupsCancelJob

Cancel a print job on the default server.

int cupsCancelJob (
    const char *name,
    int job_id
);

Parameters

name
Name of printer or class
job_id
Job ID, CUPS_JOBID_CURRENT for the current job, or CUPS_JOBID_ALL for all jobs

Return Value

1 on success, 0 on failure

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsCancelJob2

Cancel or purge a print job.

ipp_status_t cupsCancelJob2 (
    http_t *http,
    const char *name,
    int job_id,
    int purge
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Name of printer or class
job_id
Job ID, CUPS_JOBID_CURRENT for the current job, or CUPS_JOBID_ALL for all jobs
purge
1 to purge, 0 to cancel

Return Value

IPP status

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsCreateJob

Create an empty job for streaming.

int cupsCreateJob (
    http_t *http,
    const char *name,
    const char *title,
    int num_options,
    cups_option_t *options
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name
title
Title of job
num_options
Number of options
options
Options

Return Value

Job ID or 0 on error

Discussion

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.

cupsEncryption

Get the current encryption settings.

http_encryption_t cupsEncryption (void);

Return Value

Encryption settings

Discussion

The default encryption setting comes from the CUPS_ENCRYPTION environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is HTTP_ENCRYPT_IF_REQUESTED.

Note: The current encryption setting is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the cupsSetEncryption function need to do so in each thread for the same setting to be used.

 CUPS 1.4/Mac OS X 10.6 cupsFinishDocument

Finish sending a document.

ipp_status_t cupsFinishDocument (
    http_t *http,
    const char *name
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name

Return Value

Status of document submission

Discussion

The document must have been started using cupsStartDocument.

cupsFreeDests

Free the memory used by the list of destinations.

void cupsFreeDests (
    int num_dests,
    cups_dest_t *dests
);

Parameters

num_dests
Number of destinations
dests
Destinations

cupsFreeJobs

Free memory used by job data.

void cupsFreeJobs (
    int num_jobs,
    cups_job_t *jobs
);

Parameters

num_jobs
Number of jobs
jobs
Jobs

cupsFreeOptions

Free all memory used by options.

void cupsFreeOptions (
    int num_options,
    cups_option_t *options
);

Parameters

num_options
Number of options
options
Pointer to options

 DEPRECATED cupsGetClasses

Get a list of printer classes from the default server.

int cupsGetClasses (
    char ***classes
);

Parameters

classes
Classes

Return Value

Number of classes

Discussion

This function is deprecated - use cupsGetDests instead.

cupsGetDefault

Get the default printer or class for the default server.

const char *cupsGetDefault (void);

Return Value

Default printer or NULL

Discussion

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.

 CUPS 1.1.21/Mac OS X 10.4 cupsGetDefault2

Get the default printer or class for the specified server.

const char *cupsGetDefault2 (
    http_t *http
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT

Return Value

Default printer or NULL

Discussion

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.

cupsGetDest

Get the named destination from the list.

cups_dest_t *cupsGetDest (
    const char *name,
    const char *instance,
    int num_dests,
    cups_dest_t *dests
);

Parameters

name
Destination name or NULL for the default destination
instance
Instance name or NULL
num_dests
Number of destinations
dests
Destinations

Return Value

Destination pointer or NULL

Discussion

Use the cupsGetDests or cupsGetDests2 functions to get a list of supported destinations for the current user.

cupsGetDests

Get the list of destinations from the default server.

int cupsGetDests (
    cups_dest_t **dests
);

Parameters

dests
Destinations

Return Value

Number of destinations

Discussion

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.

 CUPS 1.1.21/Mac OS X 10.4 cupsGetDests2

Get the list of destinations from the specified server.

int cupsGetDests2 (
    http_t *http,
    cups_dest_t **dests
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
dests
Destinations

Return Value

Number of destinations

Discussion

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.

cupsGetJobs

Get the jobs from the default server.

int cupsGetJobs (
    cups_job_t **jobs,
    const char *name,
    int myjobs,
    int whichjobs
);

Parameters

jobs
Job data
name
NULL = all destinations, otherwise show jobs for named destination
myjobs
0 = all users, 1 = mine
whichjobs
CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED

Return Value

Number of jobs

Discussion

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.

 CUPS 1.1.21/Mac OS X 10.4 cupsGetJobs2

Get the jobs from the specified server.

int cupsGetJobs2 (
    http_t *http,
    cups_job_t **jobs,
    const char *name,
    int myjobs,
    int whichjobs
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
jobs
Job data
name
NULL = all destinations, otherwise show jobs for named destination
myjobs
0 = all users, 1 = mine
whichjobs
CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED

Return Value

Number of jobs

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsGetNamedDest

Get options for the named destination.

cups_dest_t *cupsGetNamedDest (
    http_t *http,
    const char *name,
    const char *instance
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name or NULL for the default destination
instance
Instance name or NULL

Return Value

Destination or NULL

Discussion

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.

cupsGetOption

Get an option value.

const char *cupsGetOption (
    const char *name,
    int num_options,
    cups_option_t *options
);

Parameters

name
Name of option
num_options
Number of options
options
Options

Return Value

Option value or NULL

cupsGetPPD

Get the PPD file for a printer on the default server.

const char *cupsGetPPD (
    const char *name
);

Parameters

name
Destination name

Return Value

Filename for PPD file

Discussion

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.

 CUPS 1.1.21/Mac OS X 10.4 cupsGetPPD2

Get the PPD file for a printer from the specified server.

const char *cupsGetPPD2 (
    http_t *http,
    const char *name
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name

Return Value

Filename for PPD file

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsGetPPD3

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
);

Parameters

http
HTTP connection or CUPS_HTTP_DEFAULT
name
Destination name
modtime
Modification time
buffer
Filename buffer
bufsize
Size of filename buffer

Return Value

HTTP status

Discussion

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.

cupsGetPassword

Get a password from the user.

const char *cupsGetPassword (
    const char *prompt
);

Parameters

prompt
Prompt string

Return Value

Password

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsGetPassword2

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
);

Parameters

prompt
Prompt string
http
Connection to server or CUPS_HTTP_DEFAULT
method
Request method ("GET", "POST", "PUT")
resource
Resource path

Return Value

Password

Discussion

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.

 DEPRECATED cupsGetPrinters

Get a list of printers from the default server.

int cupsGetPrinters (
    char ***printers
);

Parameters

printers
Printers

Return Value

Number of printers

Discussion

This function is deprecated - use cupsGetDests instead.

 CUPS 1.3/Mac OS X 10.5 cupsGetServerPPD

Get an available PPD file from the server.

char *cupsGetServerPPD (
    http_t *http,
    const char *name
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Name of PPD file ("ppd-name")

Return Value

Name of PPD file or NULL on error

Discussion

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.

cupsLangDefault

Return the default language.

cups_lang_t *cupsLangDefault (void);

Return Value

Language data

cupsLangEncoding

Return the character encoding (us-ascii, etc.) for the given language.

const char *cupsLangEncoding (
    cups_lang_t *lang
);

Parameters

lang
Language data

Return Value

Character encoding

cupsLangFlush

Flush all language data out of the cache.

void cupsLangFlush (void);

cupsLangFree

Free language data.

void cupsLangFree (
    cups_lang_t *lang
);

Parameters

lang
Language to free

Discussion

This does not actually free anything; use cupsLangFlush for that.

cupsLangGet

Get a language.

cups_lang_t *cupsLangGet (
    const char *language
);

Parameters

language
Language or locale

Return Value

Language data

 CUPS 1.2/Mac OS X 10.5 cupsNotifySubject

Return the subject for the given notification message.

char *cupsNotifySubject (
    cups_lang_t *lang,
    ipp_t *event
);

Parameters

lang
Language data
event
Event data

Return Value

Subject string or NULL

Discussion

The returned string must be freed by the caller using free.

 CUPS 1.2/Mac OS X 10.5 cupsNotifyText

Return the text for the given notification message.

char *cupsNotifyText (
    cups_lang_t *lang,
    ipp_t *event
);

Parameters

lang
Language data
event
Event data

Return Value

Message text or NULL

Discussion

The returned string must be freed by the caller using free.

cupsParseOptions

Parse options from a command-line argument.

int cupsParseOptions (
    const char *arg,
    int num_options,
    cups_option_t **options
);

Parameters

arg
Argument to parse
num_options
Number of options
options
Options found

Return Value

Number of options found

Discussion

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.

cupsPrintFile

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
);

Parameters

name
Destination name
filename
File to print
title
Title of job
num_options
Number of options
options
Options

Return Value

Job ID or 0 on error

 CUPS 1.1.21/Mac OS X 10.4 cupsPrintFile2

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
);

Parameters

http
Connection to server
name
Destination name
filename
File to print
title
Title of job
num_options
Number of options
options
Options

Return Value

Job ID or 0 on error

cupsPrintFiles

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
);

Parameters

name
Destination name
num_files
Number of files
files
File(s) to print
title
Title of job
num_options
Number of options
options
Options

Return Value

Job ID or 0 on error

 CUPS 1.1.21/Mac OS X 10.4 cupsPrintFiles2

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
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name
num_files
Number of files
files
File(s) to print
title
Title of job
num_options
Number of options
options
Options

Return Value

Job ID or 0 on error

 CUPS 1.3/Mac OS X 10.5 cupsRemoveDest

Remove a destination from the destination list.

int cupsRemoveDest (
    const char *name,
    const char *instance,
    int num_dests,
    cups_dest_t **dests
);

Parameters

name
Destination name
instance
Instance name or NULL
num_dests
Number of destinations
dests
Destinations

Return Value

New number of destinations

Discussion

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.

 CUPS 1.2/Mac OS X 10.5 cupsRemoveOption

Remove an option from an option array.

int cupsRemoveOption (
    const char *name,
    int num_options,
    cups_option_t **options
);

Parameters

name
Option name
num_options
Current number of options
options
Options

Return Value

New number of options

cupsServer

Return the hostname/address of the current server.

const char *cupsServer (void);

Return Value

Server name

Discussion

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.

 CUPS 1.5/Mac OS X 10.7 cupsSetClientCertCB

Set the client certificate callback.

void cupsSetClientCertCB (
    cups_client_cert_cb_t cb,
    void *user_data
);

Parameters

cb
Callback function
user_data
User data pointer

Discussion

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.

 CUPS 1.5/Mac OS X 10.7 cupsSetCredentials

Set the default credentials to be used for SSL/TLS connections.

int cupsSetCredentials (
    cups_array_t *credentials
);

Parameters

credentials
Array of credentials

Return Value

Status of call (0 = success)

Discussion

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.

 CUPS 1.3/Mac OS X 10.5 cupsSetDefaultDest

Set the default destination.

void cupsSetDefaultDest (
    const char *name,
    const char *instance,
    int num_dests,
    cups_dest_t *dests
);

Parameters

name
Destination name
instance
Instance name or NULL
num_dests
Number of destinations
dests
Destinations

cupsSetDests

Save the list of destinations for the default server.

void cupsSetDests (
    int num_dests,
    cups_dest_t *dests
);

Parameters

num_dests
Number of destinations
dests
Destinations

Discussion

This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.

 CUPS 1.1.21/Mac OS X 10.4 cupsSetDests2

Save the list of destinations for the specified server.

int cupsSetDests2 (
    http_t *http,
    int num_dests,
    cups_dest_t *dests
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
num_dests
Number of destinations
dests
Destinations

Return Value

0 on success, -1 on error

Discussion

This function saves the destinations to /etc/cups/lpoptions when run as root and ~/.cups/lpoptions when run as a normal user.

cupsSetEncryption

Set the encryption preference.

void cupsSetEncryption (
    http_encryption_t e
);

Parameters

e
New encryption preference

Discussion

The default encryption setting comes from the CUPS_ENCRYPTION environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is HTTP_ENCRYPT_IF_REQUESTED.

Note: The current encryption setting is tracked separately for each thread in a program. Multi-threaded programs that override the setting need to do so in each thread for the same setting to be used.

cupsSetPasswordCB

Set the password callback for CUPS.

void cupsSetPasswordCB (
    cups_password_cb_t cb
);

Parameters

cb
Callback function

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsSetPasswordCB2

Set the advanced password callback for CUPS.

void cupsSetPasswordCB2 (
    cups_password_cb2_t cb,
    void *user_data
);

Parameters

cb
Callback function
user_data
User data pointer

Discussion

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.

cupsSetServer

Set the default server name and port.

void cupsSetServer (
    const char *server
);

Parameters

server
Server name

Discussion

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.

 CUPS 1.5/Mac OS X 10.7 cupsSetServerCertCB

Set the server certificate callback.

void cupsSetServerCertCB (
    cups_server_cert_cb_t cb,
    void *user_data
);

Parameters

cb
Callback function
user_data
User data pointer

Discussion

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.

cupsSetUser

Set the default user name.

void cupsSetUser (
    const char *user
);

Parameters

user
User name

Discussion

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.

 CUPS 1.4/Mac OS X 10.6 cupsStartDocument

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
);

Parameters

http
Connection to server or CUPS_HTTP_DEFAULT
name
Destination name
job_id
Job ID from cupsCreateJob
docname
Name of document
format
MIME type or CUPS_FORMAT_foo
last_document
1 for last document in job, 0 otherwise

Return Value

HTTP status of request

Discussion

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.

cupsTempFd

Creates a temporary file.

int cupsTempFd (
    char *filename,
    int len
);

Parameters

filename
Pointer to buffer
len
Size of buffer

Return Value

New file descriptor or -1 on error

Discussion

The temporary filename is returned in the filename buffer. The temporary file is opened for reading and writing.

 DEPRECATED cupsTempFile

Generates a temporary filename.

char *cupsTempFile (
    char *filename,
    int len
);

Parameters

filename
Pointer to buffer
len
Size of buffer

Return Value

Filename or NULL on error

Discussion

The temporary filename is returned in the filename buffer. This function is deprecated - use cupsTempFd or cupsTempFile2 instead.

 CUPS 1.2/Mac OS X 10.5 cupsTempFile2

Creates a temporary CUPS file.

cups_file_t *cupsTempFile2 (
    char *filename,
    int len
);

Parameters

filename
Pointer to buffer
len
Size of buffer

Return Value

CUPS file or NULL on error

Discussion

The temporary filename is returned in the filename buffer. The temporary file is opened for writing.

cupsUser

Return the current user's name.

const char *cupsUser (void);

Return Value

User name

Discussion

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.

Data Types

 CUPS 1.5/Mac OS X 10.7 cups_client_cert_cb_t

Client credentials callback

typedef int (*cups_client_cert_cb_t)(http_t *http, void *tls, cups_array_t *distinguished_names, void *user_data);

cups_dest_t

Destination

typedef struct cups_dest_s cups_dest_t;

 CUPS 1.4/Mac OS X 10.6 cups_device_cb_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);

cups_job_t

Job

typedef struct cups_job_s cups_job_t;

cups_option_t

Printer Options

typedef struct cups_option_s cups_option_t;

 CUPS 1.4/Mac OS X 10.6 cups_password_cb2_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);

cups_password_cb_t

Password callback

typedef const char *(*cups_password_cb_t)(const char *prompt);

cups_ptype_t

Printer type/capability bits

typedef unsigned cups_ptype_t;

 CUPS 1.5/Mac OS X 10.7 cups_server_cert_cb_t

Server credentials callback

typedef int (*cups_server_cert_cb_t)(http_t *http, void *tls, cups_array_t *certs, void *user_data);

Structures

cups_dest_s

Destination

struct cups_dest_s {
    char *name, *instance;
    int is_default;
    int num_options;
    cups_option_t *options;
};

Members

instance
Local instance name or NULL
is_default
Is this printer the default?
num_options
Number of options
options
Options

cups_job_s

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;
};

Members

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

cups_option_s

Printer Options

struct cups_option_s {
    char *name;
    char *value;
};

Members

name
Name of option
value
Value of option

Variables

CF_RETURNS_RETAINED

Get the Apple language identifier associated with a locale ID.

const char *locale) CF_RETURNS_RETAINED;

Constants

cups_ptype_e

Printer type/capability bit constants

Constants

CUPS_PRINTER_AUTHENTICATED  CUPS 1.2/Mac OS X 10.5 
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/Mac OS X 10.5 
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/Mac OS X 10.5 
Delete printer
CUPS_PRINTER_DISCOVERED  CUPS 1.3/Mac OS X 10.5 
Printer was automatically discovered and added
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_MFP  CUPS 1.4/Mac OS X 10.6 
Printer with scanning capabilities
CUPS_PRINTER_NOT_SHARED  CUPS 1.2/Mac OS X 10.5 
Printer is not shared
CUPS_PRINTER_PUNCH
Can punch output
CUPS_PRINTER_REJECTING
Printer is rejecting jobs
CUPS_PRINTER_REMOTE
Remote printer or class
CUPS_PRINTER_SCANNER  CUPS 1.4/Mac OS X 10.6 
Scanner-only device
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
 
CUPS and the CUPS logo are trademarks of Apple Inc. CUPS is copyright 2007-2012 Apple Inc. All rights reserved.