# 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
  - Clients and Servers
  - Printers and Classes
  - Options
  - Print Jobs
  - Error Handling
  - Passwords and Authentication
- Functions
  - cupsAddDest
  - cupsAddOption
  - cupsAdminCreateWindowsPPD
  - cupsAdminExportSamba
  - cupsAdminGetServerSettings
  - cupsAdminSetServerSettings
  - cupsCancelDestJob
  - cupsCancelJob
  - cupsCancelJob2
  - cupsCheckDestSupported
  - cupsCloseDestJob
  - cupsConnectDest
  - cupsConnectDestBlock
  - cupsCopyDest
  - cupsCopyDestConflicts
  - cupsCopyDestInfo
  - cupsCreateDestJob
  - cupsCreateJob
  - cupsEncryption
  - cupsEnumDests
  - cupsEnumDestsBlock
  - cupsFindDestDefault
  - cupsFindDestReady
  - cupsFindDestSupported
  - cupsFinishDestDocument
  - cupsFinishDocument
  - cupsFreeDestInfo
  - cupsFreeDests
  - cupsFreeJobs
  - cupsFreeOptions
  - cupsGetClasses
  - cupsGetDefault
  - cupsGetDefault2
  - cupsGetDest
  - cupsGetDestMediaByIndex
  - cupsGetDestMediaByName
  - cupsGetDestMediaBySize
  - cupsGetDestMediaCount
  - cupsGetDestMediaDefault
  - cupsGetDestWithURI
  - cupsGetDests
  - cupsGetDests2
  - cupsGetJobs
  - cupsGetJobs2
  - cupsGetNamedDest
  - cupsGetOption
  - cupsGetPPD
  - cupsGetPPD2
  - cupsGetPPD3
  - cupsGetPassword
  - cupsGetPassword2
  - cupsGetPrinters
  - cupsGetServerPPD
  - cupsLangDefault
  - cupsLangEncoding
  - cupsLangFlush
  - cupsLangFree
  - cupsLangGet
  - cupsLocalizeDestMedia
  - cupsLocalizeDestOption
  - cupsLocalizeDestValue
  - cupsNotifySubject
  - cupsNotifyText
  - cupsParseOptions
  - cupsPrintFile
  - cupsPrintFile2
  - cupsPrintFiles
  - cupsPrintFiles2
  - cupsRemoveDest
  - cupsRemoveOption
  - cupsServer
  - cupsSetClientCertCB
  - cupsSetCredentials
  - cupsSetDefaultDest
  - cupsSetDests
  - cupsSetDests2
  - cupsSetEncryption
  - cupsSetPasswordCB
  - cupsSetPasswordCB2
  - cupsSetServer
  - cupsSetServerCertCB
  - cupsSetUser
  - cupsSetUserAgent
  - cupsStartDestDocument
  - cupsStartDocument
  - cupsTempFd
  - cupsTempFile
  - cupsTempFile2
  - cupsUser
  - cupsUserAgent
  - pwgFormatSizeName
  - pwgInitSize
  - pwgMediaForLegacy
  - pwgMediaForPPD
  - pwgMediaForPWG
  - pwgMediaForSize
- Data Types
  - cups_client_cert_cb_t
  - cups_dest_block_t
  - cups_dest_cb_t
  - cups_dest_t
  - cups_device_cb_t
  - cups_dinfo_t
  - cups_job_t
  - cups_option_t
  - cups_password_cb2_t
  - cups_password_cb_t
  - cups_ptype_t
  - cups_server_cert_cb_t
  - cups_size_t
  - pwg_map_t
  - pwg_media_t
  - pwg_size_t
- Structures
  - cups_dest_s
  - cups_job_s
  - cups_option_s
  - cups_size_s
  - pollfd
  - pwg_map_s
  - pwg_media_s
  - pwg_size_s
- Variables
  - CF_RETURNS_RETAINED
- Constants
  - cups_ptype_e

## 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/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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 and no longer returns a list of printer classes - 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/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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.

### CUPS 2.0/OS X 10.10 cupsGetDestWithURI

Get a destination associated with a URI.

cups_dest_t *cupsGetDestWithURI (
const char *name,
const char *uri
);

#### Parameters

name
  Desired printer name or `NULL`
uri
  URI for the printer

#### Return Value

Destination or `NULL`

#### Discussion

"name" is the desired name for the printer. If `NULL`, a name will be created using the URI.
"uri" is the "ipp" or "ipps" URI for the printer.

### 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 and no longer returns a list of printers - 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 2.0/OS X 10.10 cupsLocalizeDestMedia

Get the localized string for a destination media size.

const char *cupsLocalizeDestMedia (
http_t *http,
cups_dest_t *dest,
cups_dinfo_t *dinfo,
unsigned flags,
cups_size_t *size
);

#### Parameters

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

#### 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 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/OS X 10.9 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 and will no longer generate a temporary filename - 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/OS X 10.9 cupsUserAgent

Return the default HTTP User-Agent string.

const char *cupsUserAgent (void);

#### Return Value

User-Agent string

### CUPS 1.7/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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/OS X 10.9 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