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

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.

 DEPRECATED 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

 DEPRECATED 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/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/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

cupsCancelDestJob

Include necessary headers...

ipp_status_t cupsCancelDestJob (
    http_t *http,
    cups_dest_t *dest,
    int job_id
);

Parameters

http
Connection to destination
dest
Destination
job_id
Job ID

Return Value

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.

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/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.6/OS X 10.8 cupsCheckDestSupported

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option
value
Value

Return Value

1 if supported, 0 otherwise

Discussion

Returns 1 if supported, 0 otherwise.

 CUPS 1.6/OS X 10.8 cupsCloseDestJob

Close a job and start printing.

ipp_status_t cupsCloseDestJob (
    http_t *http,
    cups_dest_t *dest,
    cups_dinfo_t *info,
    int job_id
);

Parameters

http
Connection to destination
dest
Destination
info
Destination information
job_id
Job ID

Return Value

IPP status code

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsConnectDest

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

Parameters

dest
Destination
flags
Connection flags
msec
Timeout in milliseconds
cancel
Pointer to "cancel" variable
resource
Resource buffer
resourcesize
Size of resource buffer
cb
Callback function
user_data
User data pointer

Return Value

Connection to server or NULL

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsConnectDestBlock

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

Parameters

dest
Destination
flags
Connection flags
msec
Timeout in milliseconds
cancel
Pointer to "cancel" variable
resource
Resource buffer
resourcesize
Size of resource buffer
block
Callback block

Return Value

Connection to server or NULL

Discussion

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.

cupsCopyDest

Callback block

int cupsCopyDest (
    cups_dest_t *dest,
    int num_dests,
    cups_dest_t **dests
);

Parameters

dest
num_dests
dests

Return Value

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

 CUPS 1.6/OS X 10.8 cupsCopyDestConflicts

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
num_options
Number of current options
options
Current options
new_option
New option
new_value
New value
num_conflicts
Number of conflicting options
conflicts
Conflicting options
num_resolved
Number of options to resolve
resolved
Resolved options

Return Value

1 if there is a conflict, 0 if none, -1 on error

Discussion

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

 CUPS 1.6/OS X 10.8 cupsCopyDestInfo

Get the supported values/capabilities for the destination.

cups_dinfo_t *cupsCopyDestInfo (
    http_t *http,
    cups_dest_t *dest
);

Parameters

http
Connection to destination
dest
Destination

Return Value

Destination information

Discussion

The caller is responsible for calling cupsFreeDestInfo on the return value. NULL is returned on error.

 CUPS 1.6/OS X 10.8 cupsCreateDestJob

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

Parameters

http
Connection to destination
dest
Destination
info
Destination information
job_id
Job ID or 0 on error
title
Job name
num_options
Number of job options
options
Job options

Return Value

IPP status code

Discussion

Returns IPP_STATUS_OK or IPP_STATUS_OK_SUBST on success, saving the job ID in the variable pointed to by "job_id".

 CUPS 1.4/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_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.

 CUPS 1.6/OS X 10.8 cupsEnumDests

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

Parameters

flags
Enumeration flags
msec
Timeout in milliseconds, -1 for indefinite
cancel
Pointer to "cancel" variable
type
Printer type bits
mask
Mask for printer type bits
cb
Callback function
user_data
User data

Return Value

1 on success, 0 on failure

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsEnumDestsBlock

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

Parameters

flags
Enumeration flags
timeout
Timeout in milliseconds, 0 for indefinite
cancel
Pointer to "cancel" variable
type
Printer type bits
mask
Mask for printer type bits
block
Block

Return Value

1 on success, 0 on failure

Discussion

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.

 CUPS 1.7 cupsFindDestDefault

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option/attribute name

Return Value

Default attribute or NULL for none

Discussion

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.

 CUPS 1.7 cupsFindDestReady

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option/attribute name

Return Value

Default attribute or NULL for none

Discussion

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.

 CUPS 1.7 cupsFindDestSupported

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option/attribute name

Return Value

Default attribute or NULL for none

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsFinishDestDocument

Finish the current document.

ipp_status_t cupsFinishDestDocument (
    http_t *http,
    cups_dest_t *dest,
    cups_dinfo_t *info
);

Parameters

http
Connection to destination
dest
Destination
info
Destination information

Return Value

Status of document submission

Discussion

Returns IPP_STATUS_OK or IPP_STATUS_OK_SUBST on success.

 CUPS 1.4/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.

cupsFreeDestInfo

Free destination information obtained using cupsCopyDestInfo.

void cupsFreeDestInfo (
    cups_dinfo_t *dinfo
);

Parameters

dinfo
Destination information

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

 CUPS 1.7 cupsGetDestMediaByIndex

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
n
Media size number (0-based)
flags
Media flags
size
Media size information

Return Value

1 on success, 0 on failure

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsGetDestMediaByName

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
media
Media name
flags
Media matching flags
size
Media size information

Return Value

1 on match, 0 on failure

Discussion

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.

 CUPS 1.6/OS X 10.8 cupsGetDestMediaBySize

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
width
Media width in hundredths of of millimeters
length
Media length in hundredths of of millimeters
flags
Media matching flags
size
Media size information

Return Value

1 on match, 0 on failure

Discussion

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

 CUPS 1.7 cupsGetDestMediaCount

Get the number of sizes supported by a destination.

int cupsGetDestMediaCount (
    http_t *http,
    cups_dest_t *dest,
    cups_dinfo_t *dinfo,
    unsigned flags
);

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
flags
Media flags

Return Value

Number of sizes

Discussion

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.

 CUPS 1.7 cupsGetDestMediaDefault

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
flags
Media flags
size
Media size information

Return Value

1 on success, 0 on failure

Discussion

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.

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

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/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/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.6/OS X 10.8 cupsLocalizeDestOption

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option to localize

Return Value

Localized string

Discussion

The returned string is stored in the destination information and will become invalid if the destination information is deleted.

 CUPS 1.6/OS X 10.8 cupsLocalizeDestValue

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

Parameters

http
Connection to destination
dest
Destination
dinfo
Destination information
option
Option to localize
value
Value to localize

Return Value

Localized string

Discussion

The returned string is stored in the destination information and will become invalid if the destination information is deleted.

 CUPS 1.2/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/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/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/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/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/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/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/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/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/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_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.

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

Set the default HTTP User-Agent string.

void cupsSetUserAgent (
    const char *user_agent
);

Parameters

user_agent
User-Agent string or NULL

Discussion

Setting the string to NULL forces the default value containing the CUPS version, IPP version, and operating system version and architecture.

 CUPS 1.6/OS X 10.8 cupsStartDestDocument

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

Parameters

http
Connection to destination
dest
Destination
info
Destination information
job_id
Job ID
docname
Document name
format
Document format
num_options
Number of document options
options
Document options
last_document
1 if this is the last document

Return Value

Status of document creation

Discussion

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

 CUPS 1.4/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/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.

 CUPS 1.7 cupsUserAgent

Return the default HTTP User-Agent string.

const char *cupsUserAgent (void);

Return Value

User-Agent string

 CUPS 1.7 pwgFormatSizeName

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

Parameters

keyword
Keyword buffer
keysize
Size of keyword buffer
prefix
Prefix for PWG size or NULL for automatic
name
Size name or NULL
width
Width of page in 2540ths
length
Length of page in 2540ths
units
Units - "in", "mm", or NULL for automatic

Return Value

1 on success, 0 on failure

Discussion

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.

 CUPS 1.7 pwgInitSize

Initialize a pwg_size_t structure using IPP Job Template attributes.

int pwgInitSize (
    pwg_size_t *size,
    ipp_t *job,
    int *margins_set
);

Parameters

size
Size to initialize
job
Job template attributes
margins_set
1 if margins were set, 0 otherwise

Return Value

1 if size was initialized, 0 otherwise

Discussion

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.

 CUPS 1.7 pwgMediaForLegacy

Find a PWG media size by ISO/IPP legacy name.

pwg_media_t *pwgMediaForLegacy (
    const char *legacy
);

Parameters

legacy
Legacy size name

Return Value

Matching size or NULL

Discussion

The "name" argument specifies the legacy ISO media size name, for example "iso-a4" or "na-letter".

 CUPS 1.7 pwgMediaForPPD

Find a PWG media size by Adobe PPD name.

pwg_media_t *pwgMediaForPPD (
    const char *ppd
);

Parameters

ppd
PPD size name

Return Value

Matching size or NULL

Discussion

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

 CUPS 1.7 pwgMediaForPWG

Find a PWG media size by 5101.1 self-describing name.

pwg_media_t *pwgMediaForPWG (
    const char *pwg
);

Parameters

pwg
PWG size name

Return Value

Matching size or NULL

Discussion

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.

 CUPS 1.7 pwgMediaForSize

Get the PWG media size for the given dimensions.

pwg_media_t *pwgMediaForSize (
    int width,
    int length
);

Parameters

width
Width in hundredths of millimeters
length
Length in hundredths of millimeters

Return Value

PWG media name

Discussion

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.

Data Types

 CUPS 1.5/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 1.6/OS X 10.8 cups_dest_block_t

Destination enumeration block

typedef int (*cups_dest_block_t(unsigned flags, cups_dest_t *dest);

 CUPS 1.6/OS X 10.8 cups_dest_cb_t

Destination enumeration callback

typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, cups_dest_t *dest);

cups_dest_t

Destination

typedef struct cups_dest_s cups_dest_t;

 CUPS 1.4/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 1.6/OS X 10.8 cups_dinfo_t

Destination capability and status information

typedef struct _cups_dinfo_s cups_dinfo_t;

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

 CUPS 1.6/OS X 10.8 cups_size_t

Media Size

typedef struct cups_size_s cups_size_t;

pwg_map_t

Map element - PPD to/from PWG

typedef struct pwg_map_s pwg_map_t;

pwg_media_t

Common media size data

typedef struct pwg_media_s pwg_media_t;

pwg_size_t

Size element - PPD to/from PWG

typedef struct pwg_size_s pwg_size_t;

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

 CUPS 1.6/OS X 10.8 cups_size_s

Media Size

struct cups_size_s {
    char media[128];
    int width, length, bottom, left, right, top;
};

Members

media[128]
Media name to use
top
Top margin in hundredths of millimeters

pollfd

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

Members

data
Enumeration data
got_data
timeout
val
Return value

pwg_map_s

Map element - PPD to/from PWG

struct pwg_map_s {
    char *pwg, *ppd;
};

Members

ppd
PPD option keyword

pwg_media_s

Common media size data

struct pwg_media_s {
    int width, length;
    const char *pwg, *legacy, *ppd;
};

Members

length
Length in 2540ths
ppd
Standard Adobe PPD name

pwg_size_s

Size element - PPD to/from PWG

struct pwg_size_s {
    pwg_map_t map;
    int width, length, left, bottom, right, top;
};

Members

map
Map element
top
Top margin in 2540ths

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/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/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/OS X 10.5 
Delete printer
CUPS_PRINTER_DUPLEX
Can do duplexing
CUPS_PRINTER_FAX
Fax queue
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/OS X 10.6 
Printer with scanning capabilities
CUPS_PRINTER_NOT_SHARED  CUPS 1.2/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/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