Documentation

Introduction

The CUPS library provides a whole collection of interfaces needed to support the internal needs of the CUPS software as well as the needs of applications, filters, printer drivers, and backends.

Unlike the rest of CUPS, the CUPS API library is provided under the GNU Library General Public License. This means that you can use the CUPS API library in both proprietary and open-source programs.

General Usage

The <cups/cups.h> header file must be included to use the CUPS functions.

Programs using these functions must be linked to the CUPS library: libcups.a, libcups.so.2, libcups.2.dylib, libcups_s.a, or libcups2.lib depending on the platform. The following command compiles myprogram.c using GCC and the CUPS library:

gcc -o myprogram myprogram.c -lcups

Compatibility

Unless otherwise specified, the CUPS API functions require CUPS 1.1 or higher.

Contents

• Enumerations
• Functions
• Structures
• Types

Enumerations

• cups_ptype_e

cups_ptype_e

Description

Not a typedef'd enum so we can OR

Values

Functions

• cupsAddDest()
• cupsAddOption()
• cupsCancelJob()
• cupsEncryption()
• cupsFreeDests()
• cupsFreeJobs()
• cupsFreeOptions()
• cupsGetClasses()  DEPRECATED 
• cupsGetDefault()
• cupsGetDefault2()  CUPS 1.1.21 
• cupsGetDest()
• cupsGetDests()
• cupsGetDests2()  CUPS 1.1.21 
• cupsGetFd()  CUPS 1.1.20 
• cupsGetFile()  CUPS 1.1.20 
• cupsGetJobs()
• cupsGetJobs2()  CUPS 1.1.21 
• cupsGetOption()
• cupsGetPPD()
• cupsGetPPD2()  CUPS 1.1.21 
• cupsGetPassword()
• cupsGetPrinters()  DEPRECATED 
• cupsGetServerPPD()  CUPS 1.3 
• cupsLangDefault()
• cupsLangEncoding()
• cupsLangFlush()
• cupsLangFree()
• cupsLangGet()
• cupsLastError()
• cupsLastErrorString()  CUPS 1.2 
• cupsMarkOptions()
• cupsNotifySubject()  CUPS 1.2 
• cupsNotifyText()  CUPS 1.2 
• cupsParseOptions()
• cupsPrintFile()
• cupsPrintFile2()  CUPS 1.1.21 
• cupsPrintFiles()
• cupsPrintFiles2()  CUPS 1.1.21 
• cupsPutFd()  CUPS 1.1.20 
• cupsPutFile()  CUPS 1.1.20 
• cupsRemoveDest()  CUPS 1.3 
• cupsRemoveOption()  CUPS 1.2 
• cupsServer()
• cupsSetDefaultDest()  CUPS 1.3 
• cupsSetDests()
• cupsSetDests2()  CUPS 1.1.21 
• cupsSetEncryption()
• cupsSetPasswordCB()
• cupsSetServer()
• cupsSetUser()
• cupsTempFd()
• cupsTempFile()  DEPRECATED 
• cupsTempFile2()  CUPS 1.2 
• cupsUser()

cupsAddDest()

Description

Add a destination to the list of destinations.

This function cannot be used to add a new class or printer queue, it only adds a new container of saved options for the named destination or instance.

If the named destination already exists, the destination list is returned unchanged. Adding a new instance of a destination creates a copy of that destination's options.

Use the cupsSaveDests() function to save the updated list of destinations to the user's lpoptions file.

Syntax

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

Arguments

Returns

New number of destinations

cupsAddOption()

Description

Add an option to an option array.

Syntax

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

Arguments

Returns

Number of options

cupsCancelJob()

Description

Cancel a print job on the default server.

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

Syntax

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

Arguments

Returns

1 on success, 0 on failure

cupsEncryption()

Description

Get the default encryption settings.

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

Syntax

http_encryption_t
cupsEncryption(void);

Arguments

None.

Returns

Encryption settings

cupsFreeDests()

Description

Free the memory used by the list of destinations.

Syntax

void
cupsFreeDests( int num_dests, cups_dest_t * dests);

Arguments

Returns

Nothing.

cupsFreeJobs()

Description

Free memory used by job data.

Syntax

void
cupsFreeJobs( int num_jobs, cups_job_t * jobs);

Arguments

Returns

Nothing.

cupsFreeOptions()

Description

Free all memory used by options.

Syntax

void
cupsFreeOptions( int num_options, cups_option_t * options);

Arguments

Returns

Nothing.

 DEPRECATED cupsGetClasses()

Description

Get a list of printer classes from the default server.

This function is deprecated - use cupsGetDests() instead.

Syntax

int
cupsGetClasses( char *** classes);

Arguments

Returns

Number of classes

cupsGetDefault()

Description

Get the default printer or class for the default server.

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

Syntax

const char *
cupsGetDefault(void);

Arguments

None.

Returns

Default printer or NULL

 CUPS 1.1.21 cupsGetDefault2()

Description

Get the default printer or class for the specified server.

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

Syntax

const char *
cupsGetDefault2( http_t * http);

Arguments

Returns

Default printer or NULL

cupsGetDest()

Description

Get the named destination from the list.

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

Syntax

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

Arguments

Returns

Destination pointer or NULL

cupsGetDests()

Description

Get the list of destinations from the default server.

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.

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

Syntax

int
cupsGetDests( cups_dest_t ** dests);

Arguments

Returns

Number of destinations

 CUPS 1.1.21 cupsGetDests2()

Description

Get the list of destinations from the specified server.

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.

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

Syntax

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

Arguments

Returns

Number of destinations

 CUPS 1.1.20 cupsGetFd()

Description

Get a file from the server.

This function returns HTTP_OK when the file is successfully retrieved.

Syntax

http_status_t
cupsGetFd( http_t * http, const char * resource, int fd);

Arguments

Returns

HTTP status

 CUPS 1.1.20 cupsGetFile()

Description

Get a file from the server.

This function returns HTTP_OK when the file is successfully retrieved.

Syntax

http_status_t
cupsGetFile( http_t * http, const char * resource, const char * filename);

Arguments

Returns

HTTP status

cupsGetJobs()

Description

Get the jobs from the default server.

Syntax

int
cupsGetJobs( cups_job_t ** jobs, const char * mydest, int myjobs, int completed);

Arguments

Returns

Number of jobs

 CUPS 1.1.21 cupsGetJobs2()

Description

Get the jobs from the specified server.

Syntax

int
cupsGetJobs2( http_t * http, cups_job_t ** jobs, const char * mydest, int myjobs, int completed);

Arguments

Returns

Number of jobs

cupsGetOption()

Description

Get an option value.

Syntax

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

Arguments

Returns

Option value or NULL

cupsGetPPD()

Description

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

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

Syntax

const char *
cupsGetPPD( const char * name);

Arguments

Returns

Filename for PPD file

 CUPS 1.1.21 cupsGetPPD2()

Description

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

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

Syntax

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

Arguments

Returns

Filename for PPD file

cupsGetPassword()

Description

Get a password from the user.

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

Syntax

const char *
cupsGetPassword( const char * prompt);

Arguments

Returns

Password

 DEPRECATED cupsGetPrinters()

Description

Get a list of printers from the default server.

This function is deprecated - use cupsGetDests() instead.

Syntax

int
cupsGetPrinters( char *** printers);

Arguments

Returns

Number of printers

 CUPS 1.3 cupsGetServerPPD()

Description

Get an available PPD file from the server.

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

Syntax

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

Arguments

Returns

Name of PPD file or NULL on error

cupsLangDefault()

Description

Return the default language.

Syntax

cups_lang_t *
cupsLangDefault(void);

Arguments

None.

Returns

Language data

cupsLangEncoding()

Description

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

Syntax

const char *
cupsLangEncoding( cups_lang_t * lang);

Arguments

Returns

Character encoding

cupsLangFlush()

Description

Flush all language data out of the cache.

Syntax

void
cupsLangFlush(void);

Arguments

None.

Returns

Nothing.

cupsLangFree()

Description

Free language data.

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

Syntax

void
cupsLangFree( cups_lang_t * lang);

Arguments

Returns

Nothing.

cupsLangGet()

Description

Get a language.

Syntax

cups_lang_t *
cupsLangGet( const char * language);

Arguments

Returns

Language data

cupsLastError()

Description

Return the last IPP status code.

Syntax

ipp_status_t
cupsLastError(void);

Arguments

None.

Returns

IPP status code from last request

 CUPS 1.2 cupsLastErrorString()

Description

Return the last IPP status-message.

Syntax

const char *
cupsLastErrorString(void);

Arguments

None.

Returns

status-message text from last request

cupsMarkOptions()

Description

Mark command-line options in a PPD file.

Syntax

int
cupsMarkOptions( ppd_file_t * ppd, int num_options, cups_option_t * options);

Arguments

Returns

1 if conflicting

 CUPS 1.2 cupsNotifySubject()

Description

Return the subject for the given notification message.

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

Syntax

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

Arguments

Returns

Subject string or NULL

 CUPS 1.2 cupsNotifyText()

Description

Return the text for the given notification message.

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

Syntax

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

Arguments

Returns

Message text or NULL

cupsParseOptions()

Description

Parse options from a command-line argument.

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.

Syntax

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

Arguments

Returns

Number of options found

cupsPrintFile()

Description

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

Syntax

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

Arguments

Returns

Job ID

 CUPS 1.1.21 cupsPrintFile2()

Description

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

Syntax

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

Arguments

Returns

Job ID

cupsPrintFiles()

Description

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

Syntax

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

Arguments

Returns

Job ID

 CUPS 1.1.21 cupsPrintFiles2()

Description

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

Syntax

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

Arguments

Returns

Job ID

 CUPS 1.1.20 cupsPutFd()

Description

Put a file on the server.

This function returns HTTP_CREATED when the file is stored successfully.

Syntax

http_status_t
cupsPutFd( http_t * http, const char * resource, int fd);

Arguments

Returns

HTTP status

 CUPS 1.1.20 cupsPutFile()

Description

Put a file on the server.

This function returns HTTP_CREATED when the file is stored successfully.

Syntax

http_status_t
cupsPutFile( http_t * http, const char * resource, const char * filename);

Arguments

Returns

HTTP status

 CUPS 1.3 cupsRemoveDest()

Description

Remove a destination from the destination list.

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.

Syntax

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

Arguments

Returns

New number of destinations

 CUPS 1.2 cupsRemoveOption()

Description

Remove an option from an option array.

Syntax

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

Arguments

Returns

New number of options

cupsServer()

Description

Return the hostname/address of the default server.

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

Syntax

const char *
cupsServer(void);

Arguments

None.

Returns

Server name

 CUPS 1.3 cupsSetDefaultDest()

Description

Set the default destination.

Syntax

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

Arguments

Returns

Nothing.

cupsSetDests()

Description

Save the list of destinations for the default server.

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

Syntax

void
cupsSetDests( int num_dests, cups_dest_t * dests);

Arguments

Returns

Nothing.

 CUPS 1.1.21 cupsSetDests2()

Description

Save the list of destinations for the specified server.

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

Syntax

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

Arguments

Returns

0 on success, -1 on error

cupsSetEncryption()

Description

Set the encryption preference.

Syntax

void
cupsSetEncryption( http_encryption_t e);

Arguments

Returns

Nothing.

cupsSetPasswordCB()

Description

Set the password callback for CUPS.

Pass NULL to restore the default (console) password callback.

Syntax

void
cupsSetPasswordCB( cups_password_cb_t cb);

Arguments

Returns

Nothing.

cupsSetServer()

Description

Set the default server name.

The "server" string can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname. Pass NULL to restore the default server name.

Syntax

void
cupsSetServer( const char * server);

Arguments

Returns

Nothing.

cupsSetUser()

Description

Set the default user name.

Pass NULL to restore the default user name.

Syntax

void
cupsSetUser( const char * user);

Arguments

Returns

Nothing.

cupsTempFd()

Description

Creates a temporary file.

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

Syntax

int
cupsTempFd( char * filename, int len);

Arguments

Returns

New file descriptor or -1 on error

 DEPRECATED cupsTempFile()

Description

Generates a temporary filename.

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

Syntax

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

Arguments

Returns

Filename or NULL on error

 CUPS 1.2 cupsTempFile2()

Description

Creates a temporary CUPS file.

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

Syntax

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

Arguments

Returns

CUPS file or NULL on error

cupsUser()

Description

Return the current user's name.

Syntax

const char *
cupsUser(void);

Arguments

None.

Returns

User name

Structures

• cups_dest_s
• cups_job_s
• cups_option_s

cups_dest_s

Description

Destination

Definition

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

Members

cups_job_s

Description

Job

Definition

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

cups_option_s

Description

Printer Options

Definition

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

Members

Types

• cups_dest_t
• cups_job_t
• cups_option_t
• cups_password_cb_t
• cups_ptype_t

cups_dest_t

Description

Destination

Definition

typedef struct cups_dest_s cups_dest_t;

cups_job_t

Description

Job

Definition

typedef struct cups_job_s cups_job_t;

cups_option_t

Description

Printer Options

Definition

typedef struct cups_option_s cups_option_t;

cups_password_cb_t

Description

Password callback

Definition

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

cups_ptype_t

Description

Printer Type/Capability Bits

Definition

typedef unsigned cups_ptype_t;