!C99Shell v. 2.0 [PHP 7 Update] [25.02.2019]!
Software: Apache/2.2.16 (Debian). PHP/5.3.3-7+squeeze19 uname -a: Linux mail.tri-specialutilitydistrict.com 2.6.32-5-amd64 #1 SMP Tue May 13 16:34:35 UTC 2014 x86_64 uid=33(www-data) gid=33(www-data) groups=33(www-data) Safe-mode: OFF (not secure) /usr/share/cups/doc-root/help/ drwxr-xr-x Free 130.01 GB of 142.11 GB (91.48%) Encoder Tools Proc. FTP brute Sec. SQL PHP-code Update Feedback Self remove Logout

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

Overview
Functions
Data Types
Structures
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.

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 wiith dest */

cupsFreeDests(num_dests, dests);

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

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 2³¹-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.

CUPS 1.2/Mac OS X 10.5 cupsAdminCreateWindowsPPD

Create the Windows PPD file for a printer.

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

Parameters

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

Return Value

PPD file or NULL

CUPS 1.2/Mac OS X 10.5 cupsAdminExportSamba

Export a printer to Samba.

int cupsAdminExportSamba (
    const char *dest,
    const char *ppd,
    const char *samba_server,
    const char *samba_user,
    const char *samba_password,
    FILE *logfile
);

Parameters

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

Return Value

1 on success, 0 on failure

CUPS 1.3/Mac OS X 10.5 cupsAdminGetServerSettings

Get settings from the server.

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

Parameters

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

Return Value

1 on success, 0 on failure

Discussion

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

CUPS 1.3/Mac OS X 10.5 cupsAdminSetServerSettings

Set settings on the server.

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

Parameters

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

Return Value

1 on success, 0 on failure

cupsCancelJob

Cancel a print job on the default server.

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

Parameters

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

Return Value

1 on success, 0 on failure

Discussion

Pass CUPS_JOBID_ALL to cancel all jobs or CUPS_JOBID_CURRENT to cancel the current job on the named destination.

Use the cupsLastError and cupsLastErrorString functions to get the cause of any failure.

CUPS 1.4/Mac OS X 10.6 cupsCancelJob2

Cancel or purge a print job.

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

Parameters

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

Return Value

IPP status

Discussion

Canceled jobs remain in the job history while purged jobs are removed from the job history.

Pass CUPS_JOBID_ALL to cancel all jobs or CUPS_JOBID_CURRENT to cancel the current job on the named destination.

Use the cupsLastError and cupsLastErrorString functions to get the cause of any failure.

CUPS 1.4/Mac OS X 10.6 cupsCreateJob

Create an empty job for streaming.

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

Parameters

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

Return Value

Job ID or 0 on error

Discussion

Use this function when you want to stream print data using the cupsStartDocument, cupsWriteRequestData, and cupsFinishDocument functions. If you have one or more files to print, use the cupsPrintFile2 or cupsPrintFiles2 function instead.

cupsEncryption

Get the current encryption settings.

http_encryption_t cupsEncryption (void);

Return Value

Encryption settings

Discussion

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

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

CUPS 1.4/Mac OS X 10.6 cupsFinishDocument

Finish sending a document.

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

Parameters

http: Connection to server or CUPS_HTTP_DEFAULT
name: Destination name

Return Value

Status of document submission

Discussion

The document must have been started using cupsStartDocument.

cupsFreeDests

Free the memory used by the list of destinations.

void cupsFreeDests (
int num_dests,
cups_dest_t *dests
);

Parameters

num_dests: Number of destinations
dests: Destinations

cupsFreeJobs

Free memory used by job data.

void cupsFreeJobs (
int num_jobs,
cups_job_t *jobs
);

Parameters

num_jobs: Number of jobs
jobs: Jobs

cupsFreeOptions

Free all memory used by options.

void cupsFreeOptions (
int num_options,
cups_option_t *options
);

Parameters

num_options: Number of options
options: Pointer to options

DEPRECATED cupsGetClasses

Get a list of printer classes from the default server.

int cupsGetClasses (
char ***classes
);

Parameters

classes: Classes

Return Value

Number of classes

Discussion

This function is deprecated - use cupsGetDests instead.

cupsGetDefault

Get the default printer or class for the default server.

const char *cupsGetDefault (void);

Return Value

Default printer or NULL

Discussion

This function returns the default printer or class as defined by the LPDEST or PRINTER environment variables. If these environment variables are not set, the server default destination is returned. Applications should use the cupsGetDests and cupsGetDest functions to get the user-defined default printer, as this function does not support the lpoptions-defined default printer.

CUPS 1.1.21/Mac OS X 10.4 cupsGetDefault2

Get the default printer or class for the specified server.

const char *cupsGetDefault2 (
http_t *http
);

Parameters

http: Connection to server or CUPS_HTTP_DEFAULT

Return Value

Default printer or NULL

Discussion

cupsGetDest

Get the named destination from the list.

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

Parameters

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

Return Value

Destination pointer or NULL

Discussion

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

cupsGetDests

Get the list of destinations from the default server.

int cupsGetDests (
cups_dest_t **dests
);

Parameters

dests: Destinations

Return Value

Number of destinations

Discussion

Starting with CUPS 1.2, the returned list of destinations include the printer-info, printer-is-accepting-jobs, printer-is-shared, printer-make-and-model, printer-state, printer-state-change-time, printer-state-reasons, and printer-type attributes as options. CUPS 1.4 adds the marker-change-time, marker-colors, marker-high-levels, marker-levels, marker-low-levels, marker-message, marker-names, marker-types, and printer-commands attributes as well.

Use the cupsFreeDests function to free the destination list and the cupsGetDest function to find a particular destination.

CUPS 1.1.21/Mac OS X 10.4 cupsGetDests2

Get the list of destinations from the specified server.

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

Parameters

http: Connection to server or CUPS_HTTP_DEFAULT
dests: Destinations

Return Value

Number of destinations

Discussion

cupsGetJobs

Get the jobs from the default server.

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

Parameters

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

Return Value

Number of jobs

Discussion

A "whichjobs" value of CUPS_WHICHJOBS_ALL returns all jobs regardless of state, while CUPS_WHICHJOBS_ACTIVE returns jobs that are pending, processing, or held and CUPS_WHICHJOBS_COMPLETED returns jobs that are stopped, canceled, aborted, or completed.

CUPS 1.1.21/Mac OS X 10.4 cupsGetJobs2

Get the jobs from the specified server.

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

Parameters

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

Return Value

Number of jobs

Discussion

CUPS 1.4/Mac OS X 10.6 cupsGetNamedDest

Get options for the named destination.

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

Parameters

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

Return Value

Destination or NULL

Discussion

This function is optimized for retrieving a single destination and should be used instead of cupsGetDests and cupsGetDest when you either know the name of the destination or want to print to the default destination. If NULL is returned, the destination does not exist or there is no default destination.

If "http" is CUPS_HTTP_DEFAULT, the connection to the default print server will be used.

If "name" is NULL, the default printer for the current user will be returned.

The returned destination must be freed using cupsFreeDests with a "num_dests" value of 1.

cupsGetOption

Get an option value.

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

Parameters

name: Name of option
num_options: Number of options
options: Options

Return Value

Option value or NULL

cupsGetPPD

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

const char *cupsGetPPD (
const char *name
);

Parameters

name: Destination name

Return Value

Filename for PPD file

Discussion

For classes, cupsGetPPD returns the PPD file for the first printer in the class.

The returned filename is stored in a static buffer and is overwritten with each call to cupsGetPPD or cupsGetPPD2. The caller "owns" the file that is created and must unlink the returned filename.

CUPS 1.1.21/Mac OS X 10.4 cupsGetPPD2

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

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

Parameters

http: Connection to server or CUPS_HTTP_DEFAULT
name: Destination name

Return Value

Filename for PPD file

Discussion

For classes, cupsGetPPD2 returns the PPD file for the first printer in the class.

The returned filename is stored in a static buffer and is overwritten with each call to cupsGetPPD or cupsGetPPD2. The caller "owns" the file that is created and must unlink the returned filename.

CUPS 1.4/Mac OS X 10.6 cupsGetPPD3

Get the PPD file for a printer on the specified server if it has changed.

http_status_t cupsGetPPD3 (
    http_t *http,
    const char *name,
    time_t *modtime,
    char *buffer,
    size_t bufsize
);

Parameters

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

Return Value

HTTP status

Discussion

The "modtime" parameter contains the modification time of any locally-cached content and is updated with the time from the PPD file on the server.

The "buffer" parameter contains the local PPD filename. If it contains the empty string, a new temporary file is created, otherwise the existing file will be overwritten as needed. The caller "owns" the file that is created and must unlink the returned filename.

On success, HTTP_OK is returned for a new PPD file and HTTP_NOT_MODIFIED if the existing PPD file is up-to-date. Any other status is an error.

For classes, cupsGetPPD3 returns the PPD file for the first printer in the class.

cupsGetPassword

Get a password from the user.

const char *cupsGetPassword (
const char *prompt
);

Parameters

prompt: Prompt string

Return Value

Password

Discussion

Uses the current password callback function. Returns NULL if the user does not provide a password.

Note: The current password callback function is tracked separately for each thread in a program. Multi-threaded programs that override the setting via the cupsSetPasswordCB or cupsSetPasswordCB2 functions need to do so in each thread for the same function to be used.

CUPS 1.4/Mac OS X 10.6 cupsGetPassword2

Get a password from the user using the advanced password callback.

const char *cupsGetPassword2 (
    const char *prompt,
    http_t *http,
    const char *method,
    const char *resource
);

Parameters

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

Return Value

Password

Discussion

DEPRECATED cupsGetPrinters

Get a list of printers from the default server.

int cupsGetPrinters (
char ***printers
);

Parameters

printers: Printers

Return Value

Number of printers

Discussion

This function is deprecated - use cupsGetDests instead.

CUPS 1.3/Mac OS X 10.5 cupsGetServerPPD

Get an available PPD file from the server.

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

Parameters

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

Return Value

Name of PPD file or NULL on error

Discussion

This function returns the named PPD file from the server. The list of available PPDs is provided by the IPP CUPS_GET_PPDS operation.

You must remove (unlink) the PPD file when you are finished with it. The PPD filename is stored in a static location that will be overwritten on the next call to cupsGetPPD, cupsGetPPD2, or cupsGetServerPPD.

cupsLangDefault

Return the default language.

cups_lang_t *cupsLangDefault (void);

Return Value

Language data

cupsLangEncoding

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

const char *cupsLangEncoding (
cups_lang_t *lang
);

Parameters

lang: Language data

Return Value

Character encoding

cupsLangFlush

Flush all language data out of the cache.

void cupsLangFlush (void);

cupsLangFree

Free language data.

void cupsLangFree (
cups_lang_t *lang
);

Parameters

lang: Language to free

Discussion

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

cupsLangGet

Get a language.

cups_lang_t *cupsLangGet (
const char *language
);

Parameters

language: Language or locale

Return Value

Language data

cupsLastError

Return the last IPP status code.

ipp_status_t cupsLastError (void);

Return Value

IPP status code from last request

CUPS 1.2/Mac OS X 10.5 cupsLastErrorString

Return the last IPP status-message.

const char *cupsLastErrorString (void);

Return Value

status-message text from last request

CUPS 1.2/Mac OS X 10.5 cupsNotifySubject

Return the subject for the given notification message.

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

Parameters

lang: Language data
event: Event data

Return Value

Subject string or NULL

Discussion

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

CUPS 1.2/Mac OS X 10.5 cupsNotifyText

Return the text for the given notification message.

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

Parameters

lang: Language data
event: Event data

Return Value

Message text or NULL

Discussion

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

cupsParseOptions

Parse options from a command-line argument.

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

Parameters

arg: Argument to parse
num_options: Number of options
options: Options found

Return Value

Number of options found

Discussion

This function converts space-delimited name/value pairs according to the PAPI text option ABNF specification. Collection values ("name={a=... b=... c=...}") are stored with the curley brackets intact - use cupsParseOptions on the value to extract the collection attributes.

cupsPrintFile

Print a file to a printer or class on the default server.

int cupsPrintFile (
    const char *name,
    const char *filename,
    const char *title,
    int num_options,
    cups_option_t *options
);

Parameters

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

Return Value

Job ID or 0 on error

CUPS 1.1.21/Mac OS X 10.4 cupsPrintFile2

Print a file to a printer or class on the specified server.

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

Parameters

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

Return Value

Job ID or 0 on error

cupsPrintFiles

Print one or more files to a printer or class on the default server.

int cupsPrintFiles (
    const char *name,
    int num_files,
    const char **files,
    const char *title,
    int num_options,
    cups_option_t *options
);

Parameters

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

Return Value

Job ID or 0 on error

CUPS 1.1.21/Mac OS X 10.4 cupsPrintFiles2

Print one or more files to a printer or class on the specified server.

int cupsPrintFiles2 (
    http_t *http,
    const char *name,
    int num_files,
    const char **files,
    const char *title,
    int num_options,
    cups_option_t *options
);

Parameters

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

Return Value

Job ID or 0 on error

CUPS 1.3/Mac OS X 10.5 cupsRemoveDest

Remove a destination from the destination list.

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

Parameters

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

Return Value

New number of destinations

Discussion

Removing a destination/instance does not delete the class or printer queue, merely the lpoptions for that destination/instance. Use the cupsSetDests or cupsSetDests2 functions to save the new options for the user.

CUPS 1.2/Mac OS X 10.5 cupsRemoveOption

Remove an option from an option array.

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

Parameters

name: Option name
num_options: Current number of options
options: Options

Return Value

New number of options

cupsServer

Return the hostname/address of the current server.

const char *cupsServer (void);

Return Value

Server name

Discussion

The default server comes from the CUPS_SERVER environment variable, then the ~/.cups/client.conf file, and finally the /etc/cups/client.conf file. If not set, the default is the local system - either "localhost" or a domain socket path.

The returned value can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname.

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

CUPS 1.3/Mac OS X 10.5 cupsSetDefaultDest

Set the default destination.

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

Parameters

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

cupsSetDests

Save the list of destinations for the default server.

void cupsSetDests (
int num_dests,
cups_dest_t *dests
);

Parameters

num_dests: Number of destinations
dests: Destinations

Discussion

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

CUPS 1.1.21/Mac OS X 10.4 cupsSetDests2

Save the list of destinations for the specified server.

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

Parameters

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

Return Value

0 on success, -1 on error

Discussion

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

cupsSetEncryption

Set the encryption preference.

void cupsSetEncryption (
http_encryption_t e
);

Parameters

e: New encryption preference

Discussion

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

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

cupsSetPasswordCB

Set the password callback for CUPS.

void cupsSetPasswordCB (
cups_password_cb_t cb
);

Parameters

cb: Callback function

Discussion

Pass NULL to restore the default (console) password callback, which reads the password from the console. Programs should call either this function or cupsSetPasswordCB2, as only one callback can be registered by a program per thread.

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

CUPS 1.4/Mac OS X 10.6 cupsSetPasswordCB2

Set the advanced password callback for CUPS.

void cupsSetPasswordCB2 (
cups_password_cb2_t cb,
void *user_data
);

Parameters

cb: Callback function
user_data: User data pointer

Discussion

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.

cupsSetUser

Set the default user name.

void cupsSetUser (
const char *user
);

Parameters

user: User name

Discussion

Pass NULL to restore the default user name.

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

CUPS 1.4/Mac OS X 10.6 cupsStartDocument

Add a document to a job created with cupsCreateJob().

http_status_t cupsStartDocument (
    http_t *http,
    const char *name,
    int job_id,
    const char *docname,
    const char *format,
    int last_document
);

Parameters

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

Return Value

HTTP status of request

Discussion

Use cupsWriteRequestData to write data for the document and cupsFinishDocument to finish the document and get the submission status.

The MIME type constants CUPS_FORMAT_AUTO, CUPS_FORMAT_PDF, CUPS_FORMAT_POSTSCRIPT, CUPS_FORMAT_RAW, and CUPS_FORMAT_TEXT are provided for the "format" argument, although any supported MIME type string can be supplied.

cupsTempFd

Creates a temporary file.

int cupsTempFd (
char *filename,
int len
);

Parameters

filename: Pointer to buffer
len: Size of buffer

Return Value

New file descriptor or -1 on error

Discussion

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

DEPRECATED cupsTempFile

Generates a temporary filename.

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

Parameters

filename: Pointer to buffer
len: Size of buffer

Return Value

Filename or NULL on error

Discussion

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

CUPS 1.2/Mac OS X 10.5 cupsTempFile2

Creates a temporary CUPS file.

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

Parameters

filename: Pointer to buffer
len: Size of buffer

Return Value

CUPS file or NULL on error

Discussion

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

cupsUser

Return the current user's name.

const char *cupsUser (void);

Return Value

User name

Discussion

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

Data Types

cups_dest_t

Destination

typedef struct cups_dest_s cups_dest_t;

CUPS 1.4/Mac OS X 10.6 cups_device_cb_t

Device callback

typedef void (*cups_device_cb_t)(const char *device_class, const char *device_id, const char *device_info, const char *device_make_and_model, const char *device_uri, const char *device_location, void *user_data);

cups_job_t

Job

typedef struct cups_job_s cups_job_t;

cups_option_t

Printer Options

typedef struct cups_option_s cups_option_t;

CUPS 1.4/Mac OS X 10.6 cups_password_cb2_t

New password callback

typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, const char *resource, void *user_data);

cups_password_cb_t

Password callback

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

cups_ptype_t

Printer type/capability bits

typedef unsigned cups_ptype_t;

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

Constants

cups_ptype_e

Printer type/capability bit constants

Constants

CUPS_PRINTER_AUTHENTICATED CUPS 1.2/Mac OS X 10.5: Printer requires authentication
CUPS_PRINTER_BIND: Can bind output
CUPS_PRINTER_BW: Can do B&W printing
CUPS_PRINTER_CLASS: Printer class
CUPS_PRINTER_COLLATE: Can collage copies
CUPS_PRINTER_COLOR: Can do color printing
CUPS_PRINTER_COMMANDS CUPS 1.2/Mac OS X 10.5: Printer supports maintenance commands
CUPS_PRINTER_COPIES: Can do copies
CUPS_PRINTER_COVER: Can cover output
CUPS_PRINTER_DEFAULT: Default printer on network
CUPS_PRINTER_DELETE CUPS 1.2/Mac OS X 10.5: Delete printer
CUPS_PRINTER_DISCOVERED CUPS 1.3/Mac OS X 10.5: Printer was automatically discovered and added
CUPS_PRINTER_DUPLEX: Can do duplexing
CUPS_PRINTER_FAX: Fax queue
CUPS_PRINTER_IMPLICIT: Implicit class
CUPS_PRINTER_LARGE: Can do D/E/A1/A0
CUPS_PRINTER_LOCAL: Local printer or class
CUPS_PRINTER_MEDIUM: Can do Tabloid/B/C/A3/A2
CUPS_PRINTER_MFP CUPS 1.4/Mac OS X 10.6: Printer with scanning capabilities
CUPS_PRINTER_NOT_SHARED CUPS 1.2/Mac OS X 10.5: Printer is not shared
CUPS_PRINTER_PUNCH: Can punch output
CUPS_PRINTER_REJECTING: Printer is rejecting jobs
CUPS_PRINTER_REMOTE: Remote printer or class
CUPS_PRINTER_SCANNER CUPS 1.4/Mac OS X 10.6: Scanner-only device
CUPS_PRINTER_SMALL: Can do Letter/Legal/A4
CUPS_PRINTER_SORT: Can sort output
CUPS_PRINTER_STAPLE: Can staple output
CUPS_PRINTER_VARIABLE: Can do variable sizes

:: Command execute ::
Enter:	Select:

CUPS API

Contents

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

CUPS 1.2/Mac OS X 10.5 cupsAdminCreateWindowsPPD

Parameters

Return Value

CUPS 1.2/Mac OS X 10.5 cupsAdminExportSamba

Parameters

Return Value

CUPS 1.3/Mac OS X 10.5 cupsAdminGetServerSettings

Parameters

Return Value

Discussion

CUPS 1.3/Mac OS X 10.5 cupsAdminSetServerSettings

Parameters

Return Value

Parameters

Return Value

Discussion

CUPS 1.4/Mac OS X 10.6 cupsCancelJob2

Parameters

Return Value

Discussion

CUPS 1.4/Mac OS X 10.6 cupsCreateJob

Parameters

Return Value

Discussion

Return Value

Discussion

CUPS 1.4/Mac OS X 10.6 cupsFinishDocument

Parameters

Return Value

Discussion

Parameters

Parameters

Parameters

DEPRECATED cupsGetClasses

Parameters

Return Value

Discussion

Return Value

Discussion

CUPS 1.1.21/Mac OS X 10.4 cupsGetDefault2

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

CUPS 1.1.21/Mac OS X 10.4 cupsGetDests2

Parameters

Return Value

Discussion

Parameters

Return Value

Discussion

CUPS 1.1.21/Mac OS X 10.4 cupsGetJobs2

Parameters

Return Value

Discussion

CUPS 1.4/Mac OS X 10.6 cupsGetNamedDest

Parameters

Return Value

Discussion

Parameters

Return Value

Parameters

Return Value

Discussion

CUPS 1.1.21/Mac OS X 10.4 cupsGetPPD2

Parameters

Return Value