Preface

This software programmers manual provides software programming information for the Common UNIX Printing System ("CUPS") Version 1.1.15.

Document Overview

This software programmers manual is organized into the following sections:

Notation Conventions

Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below:

Example     Description
 
lpstat
lpstat(1)
    The names of commands; the first mention of a command or function in a chapter is followed by a manual page section number.
 
/var
/usr/share/cups/data/testprint.ps
    File and directory names.
 
Request ID is Printer-123     Screen output.
 
lp -d printer filename ENTER     Literal user input; special keys like ENTER are in ALL CAPS.
 
12.3     Numbers in the text are written using the period (.) to indicate the decimal point.

Abbreviations

The following abbreviations are used throughout this manual:

Other References

2 - The CUPS API

This chapter describes the CUPS Application Programmers Interface ("API").

The CUPS API Library

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.

Programs that use the CUPS API library typically will include the <cups/cups.h> header file:

Use the -lcups compiler option when linking to the CUPS API library:

Additional options and libraries may be required depending on the operating system and the location of the CUPS API library.

Detecting the CUPS API Library in GNU Autoconf

GNU autoconf is a popular configuration tool used by many programs. Add the following lines to your configure.in file to check for the CUPS API library in your configuration script:

Printing Services

The CUPS API library provides some basic printing services for applications that need to print files.

Include Files

The include file used by all of these functions is <cups/cups.h>:

Printing a File

The CUPS API provides two functions for printing files. The first is cupsPrintFile which prints a single named file:

The name string is the name of the printer or class to print to. The filename string is the name of the file to print. The title string is the name of the print job, e.g. "Acme Word Document".

The return value is a unique ID number for the print job or 0 if there was an error.

Printing Multiple Files

The second printing function is cupsPrintFiles:

Instead of passing a filename string as with cupsPrintFile(), you pass a file count (num_files) and filename pointer array (files) for each file that you want to print.

As with cupsPrintFile(), the return value is a unique ID for the print job.

Cancelling Jobs

The cupsCancelJob() function cancels a queued print job:

The name string specifies the destination and is used to determine the server to send the request to. The jobid value is the integer returned from a previous cupsPrintFile() or cupsPrintFiles() call.

cupsCancelJob() returns 1 if the job was successfully cancelled and 0 if there was an error.

Getting the Available Printers and Classes

The cupsGetDests() function can be used to get a list of the available printers, classes, and instances that a user has defined:

Each destination is stored in a cups_dest_t structure which defines the printer or class name, the instance name (if any), if it is the default destination, and the default options the user has defined for the destination:

The destinations are sorted by name and instance for your convenience. Once you have the list of available destinations, you can lookup a specific destination using the cupsGetDest() function:

The name string is the printer or class name. You can pass a value of NULL to get the default destination.

The instance string is the user-defined instance name. Pass NULL to select the default instance, e.g. "name" instead of "name/instance".

Printing with Options

All of the previous printing examples have passed 0 and NULL for the last two arguments to the cupsPrintFile() and cupsPrintFiles() functions. These last two arguments are the number of options and a pointer to the option array:

The cups_option_t structure holds each option and its value. These are converted as needed and passed to the CUPS server when printing a file.

The simplest way of handling options is to use the num_options and options members of the cups_dest_t structure described earlier:

This effectively uses the options a user has previous selected without a lot of code.

Setting Printer Options

Options can also be set by your program using the cupsAddOption() function:

The name string is the name of the option, and the value string is the value for that option.

Each call to cupsAddOption() returns the new number of options. Since adding two options with the same name overwrites the first value with the second, do not assume that calling cupsAddOptions() 20 times will result in 20 options.

Call cupsFreeOptions once you are done using the options:

Getting Errors

If any of the CUPS API printing functions returns an error, the reason for that error can be found by calling cupsLastError() and cupsErrorString(). cupsLastError() returns the last IPP error code that was encountered. cupsErrorString() converts the error code to a localized message string suitable for presentation to the user:

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:

Similarly, a GUI interface could display the prompt string in a window with input fields for the username and password. The username should probably default to the value of cupsUser() to make things easier on the user.

PPD Services

CUPS includes functions to access and manipulate PostScript Printer Description ("PPD") files that are used with the printer drivers in CUPS.

Each PPD file enumerates the available features provided by a printer, including conflict information for specific options (e.g. can't duplex output on envelopes.)

Include Files

Include the <cups/ppd.h> header file to use the PPD functions:

This header file is also included by the <cups/cups.h> header file.

Getting a PPD File for a Printer

The cupsGetPPD() function retrieves the PPD file for the named printer or class:

The name string is the name of the printer or class, including the remote server name as appropriate (e.g. "printer@server".)

The return value is a pointer to a filename in static storage; this value is overwritten with each call to cupsGetPPD(). If the printer or class does not exist, a NULL pointer will be returned.

Loading a PPD File

The ppdOpenFile() function "opens" a PPD file and loads it into memory:

The filename string is the name of the file to load, such as the value returned by the cupsGetPPD() function.

The return value is a pointer to a structure describing the contents of the PPD file or NULL if the PPD file could not be read.

Freeing PPD File Information

Once you are done using a PPD file, call the ppdClose() function to free all memory that has been used:

The PPD File Structure

Each PPD file contains a number of capability attributes, printer options, and conflict definitions. The page size options also include the physical margins for the printer and the minimum and maximum sizes for the printer. All of this information is stored in the ppd_file_t structure.

Capabilities

Each PPD file contains a number of informational attributes that describe the capabilities of the printer. These are provided in the ppd_file_t structure in the following members:

Member Type Description
accurate_screens int 1 = supports accurate screens
color_device int 1 = color device
colorspace ppd_cs_t Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N
contone_only int 1 = printer is continuous tone only
num_emulations
emulations
int
ppd_emul_t *
Emulations supported by the printer
flip_duplex int 1 = need to flip odd pages when duplexing
num_fonts
fonts
int
char **
The fonts available on the printer.
jcl_begin
jcl_ps
jcl_end
char * Job Control Language commands for PostScript output
landscape int Landscape orientation, -90 or 90 degrees
lang_encoding char * The character used for the option strings
lang_version char * The language used for the options strings (English, French, etc.)
language_level int PostScript language level, 1 to 3
manual_copies int 1 = Copies are done manually
model_number int Driver-specific model number.
patches char * Patch commands to send to the printer
manufacturer char * The Manufacturer attribute from the PPD file, if any
modelname char * The ModelName attribute from the PPD file
nickname char * The NickName attribute from the PPD file, if any
product char * The Product attribute from the PPD file, if any
shortnickname char * The ShortNickName attribute from the PPD file, if any
throughput int Number of pages per minute
ttrasterizer char * The TruType font rasterizer (Type42)
variable_sizes int 1 = supports variable sizes

Options and Groups

PPD files support multiple options, which are stored in ppd_option_t and ppd_choice_t structures by the PPD functions.

Each option in turn is associated with a group stored in the ppd_group_t structure. Groups can be specified in the PPD file; if an option is not associated with a group then it is put in a "General" or "Extra" group depending on the option.

Groups can also have sub-groups; CUPS currently limits the depth of sub-groups to 1 level to reduce programming complexity.

Conflicts

PPD files support specification of conflict conditions between different options. Conflicts are stored in ppd_conflict_t structures which specify the options that conflict with each other.

Page Sizes

PPD files specify all of the available pages sizes and the physical margins associated with them. These sizes are stored in ppd_size_t structures and are available in the num_sizes and sizes members of the ppd_file_t structure. You can lookup a particular page size with the ppdPageWidth(), ppdPageLength(), and ppdPageSize() functions:

The size string is the named page size option. The width and length are in points; there are 72 points per inch. The ppd_size_t structure contains the width, length, and margin information:

Custom Page Sizes

Besides the standard page sizes listed in a PPD file, some printers support variable or custom page sizes. If variables_sizes is non-zero, the custom_min, custom_max, and custom_margins members of the ppd_file_t structure define the limits of the variable sizes.

To get the resulting media size, use a page size string of Custom.widthxlength, where width and length are integer values in points:

Marking Options

Before marking any user-defined options, call the ppdMarkDefaults() function to mark the default options from the PPD file:

Then call the ppdMarkOption() function to mark individual options:

The name and value strings choose a particular option and choice, respectively. The return value is 0 if there are not conflicts created by the selection.

CUPS also provides a convenience function for marking all options in the cups_option_t structure:

The cupsMarkOptions() function also handles mapping the IPP job template attributes to PPD options. The return value is the number of conflicts present.

Checking for Conflicts

The ppdMarkOption() and cupsMarkOptions() functions return the number of conflicts with the currently marked options.

Call the ppdConflicts() function to get the number of conflicts after you have marked all of the options:

The return value is the number of conflicting options, or 0 if there are no conflicts.

3 - Writing Filters

This chapter describes how to write a file filter for CUPS.

Overview

File filters are programs that convert from one or more MIME types to another type. Filters use a common command-line and environment interface that allows them to be joined as needed to print files to any type of printer.

Security Considerations

Filters are normally run as a non-priviledged user, so the major security consideration is resource utilization - filters should not depend on unlimited amounts of memory and disk space.

Users and Groups

The default CUPS configuration runs filters as user "lp" and group "other".

Temporary Files

Temporary files should be created in the directory specified by the "TMPDIR" environment variable. The cupsTempFile() function can be used to safely choose temporary files in this directory.

Sending Messages to the User

The CUPS scheduler collects messages sent to the standard error file by the filter. These messages are relayed to the user based upon the scheduler LogLevel directive.

The type of message is determined by an initial prefix sent on each line:

If the line of text does not begin with any of the above prefixes, it is treated as a debug message. Text following the prefix is copied to the printer-state-message attribute for the printer, and also added to the error_log unless it is an informational or page accounting message.

Page Accounting

Page accounting messages are used to inform the server when one or more pages are printed. Each line has the form:

The page-number field is the current page number, starting at 1. The copy-count field specifies the number of copies of that page that was produced.

Page account messages are added to the page_log file and cause the job-sheets-completed attribute to be updated for the job.

Command-Line Arguments

Every filter accepts exactly 6 or 7 command-line arguments:

The filename argument is only provided to the first filter in the chain; all filters must be prepared to read the print file from the standard input if the filename argument is omitted.

Copy Generation

The copies argument specifies the number of copies to produce of the input file. In general, you should only generate copies if the filename argument is supplied. The only exception to this are filters that produce device-independent PostScript output (without any printer commands from the printer's PPD file), since the PostScript filter pstops is responsible for copy generation.

Environment Variables

Every filter receives a fixed set of environment variables that can be used by the filter:

Dissecting the HP-GL/2 Filter

The HP-GL/2 filter (hpgltops) provided with CUPS is a complex program that converts HP-GL/2 files into device-independent PostScript output. Since it produces device-independent PostScript output, it does not need to handle copy generation or writing printer options from the printer's PPD file.

Initializing the Filter

The first task of any filter is to ensure that the correct number of command-line arguments are present:

After this you open the print file or read from the standard input as needed:

Once the print file has been opened, options can be processed using the cupsParseOptions() and cupsGetOption() functions:

After the options have been processed, the filter writes PostScript code to the standard output based on the print file, closes the print file (as needed), and returns 0 to the scheduler.

PostScript Output

Filters that produce PostScript output must generate output conforming to the Adobe Document Structuring Conventions, 3.0. In general this means the beginning of each file must begin with:

The left, bottom, right, and top values are integers in points from the lower-lefthand corner of the page.

Pages must be surrounded by:

And the end of each file must contain:

These comments allow the PostScript filter to correctly perform page accounting, copy generation, N-up printing, and so forth.

4 - Writing Printer Drivers

This chapter discusses how to write a printer driver, which is a special filter program that converts CUPS raster data into the appropriate commands and data required for a printer.

Overview

Raster printers utilitize PPD files that specify one or more device-specific filters that handle converting print files for the printer. The simplest raster printer drivers provide a single filter that converts CUPS raster data to the printer's native format.

CUPS Raster Data

CUPS raster data (application/vnd.cups-raster) consists of a stream of raster page descriptions produced by one of the RIP filters, such as pstoraster or imagetoraster.

Each page of data begins with a page dictionary structure called cups_raster_header_t. This structure contains the colorspace, bits per color, media size, media type, hardware resolution, and so forth.

After the page dictionary comes the page data which is a full-resolution, uncompressed bitmap representing the page in the printer's output colorspace.

Page Accounting

Printer drivers must handle all page accounting. This means they must send "PAGE:" messages to the standard error file for each page (and in many cases, copy) sent to the printer.

Color Management

Printer drivers can implement their color management via the cupsColorProfile attributes in the PPD file or internally in the driver from a device-independent colorspace. In general, color management performed by the RIP filters is more efficient than that performed inside printer drivers.

For example, the pstoraster filter often only has to perform a color conversion once each time the color is used for multiple output pixels, while the raster filter must convert every pixel on the page.

Device and Bitmap Variables

Besides the standard PostScript page device dictionary variables defined in the Adobe PostScript Level 3 reference manual, the CUPS filters support additional variables that are passed in the page device dictionary header for the page and in some cases control the type of raster data that is generated:

Variable Type Description
cupsWidth read-only integer Width of bitmap in pixels
cupsHeight read-only integer Height of bitmap in pixels
cupsMediaType read-write integer Device-specific media type code
cupsBitsPerColor read-write integer Number of bits per color; 1, 2, 4, and 8 are currently supported
cupsBitsPerPixel read-only integer Number of bits per pixel; 1 to 32
cupsBytesPerLine read-only integer Number of bytes per line of raster graphics
cupsColorOrder read-write enum The order of color values in the bitmap:
  • CUPS_ORDER_CHUNKED - CMYK CMYK CMYK
  • CUPS_ORDER_BANDED - CCC MMM YYY KKK
  • CUPS_ORDER_PLANAR - CCC ... MMM ... YYY ... KKK ...
cupsColorSpace read-write enum The colorspace of the bitmap:
  • CUPS_CSPACE_W - White (luminance)
  • CUPS_CSPACE_RGB - Red, green, blue
  • CUPS_CSPACE_RGBA - Red, green, blue, alpha
  • CUPS_CSPACE_K - Black
  • CUPS_CSPACE_CMY - Cyan, magenta, yellow
  • CUPS_CSPACE_YMC - Yellow, magenta, cyan
  • CUPS_CSPACE_CMYK - Cyan, magenta, yellow, black
  • CUPS_CSPACE_YMCK - Yellow, magenta, cyan, black
  • CUPS_CSPACE_KCMY - Black, cyan, magenta, yellow
  • CUPS_CSPACE_KCMYcm - Black, cyan, magenta, yellow, light cyan, light magenta
  • CUPS_CSPACE_GMCK - Metallic yellow (gold), metallic magenta, metallic cyan, black
  • CUPS_CSPACE_GMCS - Metallic yellow (gold), metallic magenta, metallic cyan, metallic grey (silver)
  • CUPS_CSPACE_WHITE - White pigment (black as white pigment)
  • CUPS_CSPACE_GOLD - Gold foil (black as gold foil)
  • CUPS_CSPACE_SILVER - Silver foil (black as silver foil)
cupsCompression read-write integer Device-specific compression type code
cupsRowCount read-write integer Device-specific row count value
cupsRowFeed read-write integer Device-specific row feed value
cupsRowStep read-write integer Device-specific row step value

Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per color are transmitted to the raster driver in KCMY colorspace; the driver is responsible for producing the correct separation of normal and light cyan and magenta inks.

Dissecting the HP-PCL Driver

The HP-PCL driver provided with CUPS (rastertohp) converts bitmap data from the raster filters into HP-PCL commands for most PCL-compatible printers. The actual format of the raster data is controlled by the PPD file being used - deskjet.ppd or laserjet.ppd.

PPD Files

PPD files play an important part of all raster printer drivers. Options defined in the PPD file contain PostScript commands that control the raster data that is sent to the printer driver.

A typical CUPS printer driver will include ColorModel, InputSlot, PageSize, PageRegion, and Resolution options. Each option is shown using the standard PPD format:

The OpenUI keyword specifies the new option. The first name is the option with an asterisk (*) in front of it. The first name is usually followed by a slash (/) and a human-readable version of the option name.

Every option must have a default value, specified using the DefaultOption keyword.

Each option begins with the option name followed by the computer and human-readable values. The PostScript commands follow these inside double quotes. PostScript commands can be provided on a single line:

or broken down on separate lines using the End keyword to terminate them:

The choice of the two formats is usually esthetic. However, each line in a PPD file must not exceed 255 characters, so if your PostScript commands are long you may need to break them up on separate lines.

Reading Raster Data

As with any filter, your printer driver should handle raster data from a filename specified on the command-line or from the standard input. The cupsRasterOpen() function opens a raster stream for printing:

Once you have opened the raster stream you just need to read each page and print it:

After you have processed all pages, close the raster stream and return:

5 - Writing Backends

This chapter describes how to write a backend for CUPS. Backends communicate directly with printers and allow printer drivers and filters to send data using any type of connection transparently.

Overview

Backends are special filters that communicate with printers directly. They are treated slightly differently than filters, however, and have some unique requirements.

Security Considerations

Backends are run as the root user, so special care must be taken to avoid potential security violations. In particular, remember that a backend will be able to manipulate disk files, devices, and other resources that potentially could damage a system or printer.

Command-Line Arguments

Besides the standard filter arguments, backends are also run with no arguments to get a list of available devices. This discovery process is described later in this chapter.

Copy Generation

Like filters, backends should send multiple copies of the print file only if a filename is supplied on the command-line. Otherwise the backend should assume that the upstream filter has already added the necessary commands or data to produce the multiple copies.

Page Accounting

Backend filters generally do not do page accounting, however they should at a minimum produce a single page message for each copy that is produced when a filename is present on the command-line. This is because the user selected "raw" printing and no other accounting information is possible.

Exclusive Access

Backends that talk to local character or block devices should open the device file in exclusive mode (O_EXCL) to cooperate with other printers defined for the same device.

Retries

All backends must retry connections to the device. This includes backends that talk to local character or block devices, as the user may define more than one printer queue pointing at the same physical device.

To prevent excess CPU utilitization, the backend should go to sleep for an amount of time between retries; the CUPS-supplied backends retry once every 30 seconds.

Dissecting the Serial Port Backend

The serial port backend provides support for serial printers. Since it does everything a good backend needs to do, it provides an excellent example of what to do.

Supporting Device Discovery

As previously noted, backends are special filter programs that talk to printer devices. Another task a backend must perform is to list the available devices it supports. The backend lists the available devices when no additioanl arguments are supplied on the command-line (i.e. just the command name...)

The serial backend lists devices by looking at serial port files in the /dev directory, by consulting a hardware inventory (IRIX), and in some cases by trying to open the ports to see if they actually exist.

Once it finds a serial port it writes a single line for each port to the standard error file. Each line looks like this:

The first word "serial" is the device class; this identifies the class of device which can be used to categorize it in user interfaces. CUPS currently recognizes the following classes:

After the device class is the device URI, in this case "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by the user to select this port. For serial ports, the "baud=115200" specifies the maximum baud rate supported by the port - the actual value will vary based on the speed the user selects for the printer.

The last two strings are the model and description for the port. The "Unknown" string means that the printer model is unknown - some devices are able to provide a make and model such as "HP DeskJet" that allows users and software to choose an appropriate printer driver more easily. Both the model and description must be enclosed inside double quotes.

Opening the Serial Port

As noted previously, all backends should open device files in exclusive mode, and retry as needed until the port is available. The serial port does this using a do-while loop:

If the port is busy or in use by another process, the backend will go to sleep for 30 seconds and try again. If another error is detected a message is sent to the user and the backend aborts the print job until the problem can be corrected.

Writing Data to the Port

Network and character devices pose an interesting problem when writing data to the port - they may not be able to write all of the bytes in your buffer before returning. To work around this problem you must loop until all bytes have been written:

The check for the ENOTTY error is needed on some platforms to clear an error from a previous ioctl() call.

Finishing Up

Once you have sent the print file, return 0 if the file printed successfully or 1 if it did not. This will allow the scheduler to stop the print job if there is a device error, preserving the print job for later printing once the problem has been corrected.

A - Software License Agreement

B - Constants

This appendix lists all of the constants that are defined by the CUPS API.

CUPS Constants

Version Number

The CUPS_VERSION constant is a floating-point number representing the API version number. The current version number is 1.0100 which represents CUPS version 1.1.0.

Printer Capabilities

The CUPS_PRINTER constants represent capability bits for printers and classes:

Encodings

CUPS defines the following character set encoding constants:

HTTP Constants

Limits

The following constants define the limits for strings:

Status Codes

The following status codes can be returned by httpUpdate():

Fields

The following fields are indices for each of the standard HTTP fields in HTTP 1/1:

IPP Constants

Limits

The following constants define array limits for IPP data:

Tags

Resolution Units

The IPP_RES_PER_INCH and IPP_RES_PER_CM constants specify dots per inch and dots per centimeter, respectively.

Finishings

The finishing values specify special finishing operations to be performed on the job.

Orientations

The orientation values specify the orientation of the job.

Qualities

The quality values specify the desired quality of the print.

Job States

The job state values are used to represent the current job state.

Printer States

The printer state values are used to represent the current printer state.

Operations

The operation values represent the available IPP operations.

Status Codes

Status codes are returned by all IPP requests.

PPD Constants

PPD Format Version

The PPD_VERSION constant defines a floating point number representing the newest format version that is supported by CUPS, currently 4.3.

PPD User-Interface Types

Each printer option has a type associated with it:

PPD Sections

Some options must be output before others, or in different sections of the output document. The ppd_section_t enumeration defines which section the option must be output in:

PPD Colorspaces

Each printer has a default colorspace:

Raster Constants

Raster Sync Words

The CUPS_RASTER_SYNC and CUPS_RASTER_REVSYNC constants define the standard sync words at the beginning of each CUPS raster file.

Raster Stream Modes

The CUPS_RASTER_READ and CUPS_RASTER_WRITE constants are used with the cupsRasterOpen() function to specify a stream for reading or writing.

Raster Boolean Constants

The CUPS_FALSE and CUPS_TRUE constants represent boolean values in the page header.

Raster Jog Values

The cups_jog_t enumeration defines constants for the Jog page device dictionary variable:

Raster Orientation Values

The cups_orient_t enumeration defines constants for the Orientation page device dictionary variable:

Raster CutMedia Values

The cups_cut_t enumeration defines constants for the CutMedia page device dictionary variable:

Raster AdvanceMedia Values

The cups_advance_t enumeration defines constants for the AdvanceMedia page device dictionary variable:

Raster LeadingEdge Values

The cups_edge_t enumeration defines constants for the LeadingEdge page device dictionary variable:

Raster Color Order Values

The cups_order_t enumeration defines the possible color value orderings:

Raster Colorspace Values

The cups_cspace_t enumeration defines the possible colorspaces:

C - Structures

This appendix describes all of the structures that are defined by the CUPS API.

CUPS Structures

CUPS Destinations

The CUPS destination structure (cups_dest_t) contains information on a specific destination or instance:

Member Type Description
name char * The name of the printer or class.
instance char * The instance of the printer or class; NULL for the primary instance.
is_default int 1 if the destination is set as the default, 0 otherwise.
num_options int The number of options associated with this destination.
options cups_option_t * The options associated with this destination.

CUPS Jobs

The CUPS job structure (cups_job_t) contains information on a specific job:

Member Type Description
id int The job ID for this job.
dest char * The destination for this job (printer or class name).
title char * The job-name for this job (title).
user char * The job-originating-user-name for this job (username).
format char * The document-format for this job (MIME type string).
state ipp_jstate The current state of the job.
size int The size of this job in kilobytes.
priority int The priority of this job from 1 to 100 (50 is normal).
completed_time time_t The time the job was completed, or 0 if not yet completed.
creation_time time_t The time the job was queued.
processing_time time_t The time the job started printing.

CUPS Messages

The CUPS messages structure (cups_lang_t) contains the character set, locale name, and messages array:

Member Type Description
next cups_lang_t * Pointer to the next messages structure in memory.
used int The number of active users of this messages structure.
encoding cups_encoding_t The character encoding of the message strings.
language char [16] The language/locale name.
messages char *[] The array of message strings.

CUPS Options

The CUPS option structure (cups_option_t) contains the option name and string value:

Member Type Description
name char * The name of the option.
value char * The string value of the option.

Networking Structures

HTTP State

The HTTP state structure (http_t) contains the current state of a HTTP request or response:

Member Type Description
fd int The socket for the HTTP connection.
blocking int 1 if the HTTP functions should block, 0 if not.
error int The last OS error that occurred on the socket.
activity time_t The last time the HTTP connection was used.
state http_state_t The current HTTP request/response state.
status int The last HTTP status seen.
version http_version_t The HTTP protocol version in use.
keep_alive http_keep_alive_t Whether or not to use Keep-Alive
hostaddr struct sockaddr_in The IPv4 address of the HTTP server.
hostname char [] The hostname of the HTTP server.
fields char [][] The string values of all HTTP request/response fields.
data char * Current byte in data buffer.
data_encoding http_encoding_t The transfer encoding for the request/response.
data_remaining int The number of bytes remaining in the current request, response, or chunk.
used int The number of bytes that are used in the buffer.
buffer char [] The read/write buffer.
auth_type int The type of authentication in use.
md5_state md5_state_t The current MD5 digest state.
nonce char [] The nonce value for Digest authentication.
nonce_count int The nonce count value.
tls void * A pointer to private encryption data.
encryption http_encryption_t The current encryption mode.

IPP State

The IPP state structure (ipp_t) contains the current state of a IPP request or response:

Member Type Description

Raster Structures

Raster Page Header

The raster page header (cups_raster_header_t) consists of the PostScript page device dictionary for the page:

Member Type Description
MediaClass char[64] The media class name
MediaColor char[64] The media color name
MediaType char[64] The media type name
OutputType char[64] The output type name
AdvanceDistance unsigned The distance to advance the media in points
AdvanceMedia cups_adv_t When to advance the media
Collate cups_bool_t Whether or not to produce collated copies
CutMedia cups_cut_t When to cut the media
Duplex cups_bool_t Whether or not to print on both sides of the paper
HWResolution unsigned[2] The resolution of the page image in pixels per inch; the HWResolution[0] represents the horizontal resolution and HWResolution[1] represents the vertical resolution
ImagingBoundingBox unsigned[4] The bounding box for the page in points; the elements represent the left, bottom, right, and top coordinates of the imaged area (if 0 then the whole page is imaged)
InsertSheet cups_bool_t Whether or not to insert a sheet before this page
Jog cups_jog_t When to jog copies of the page
LeadingEdge cups_edge_t The leading edge of the page
Margins unsigned[2] The lower-lefthand margin of the page in points
ManualFeed cups_bool_t Whether or not to manually feed the page
MediaPosition unsigned The input slot number to use
MediaWeight unsigned The weight of the output media in grams/m2
MirrorPrint cups_bool_t Whether or not to mirror the print
NegativePrint cups_bool_t Whether or not to invert the print
NumCopies unsigned The number of copies to produce
Orientation cups_orient_t The orientation of the page image
OutputFaceUp cups_bool_t Whether or not to output the page face up
PageSize unsigned[2] The width and height of the page in points
Separations cups_bool_t Whether or not to output separations
TraySwitch cups_bool_t Whether or not to automatically switch trays for the requested media size/type
Tumble cups_bool_t Whether or not to rotate the back side of the page
cupsWidth unsigned The width of the page image in pixels
cupsHeight unsigned The height of the page image in pixels
cupsMediaType unsigned The device-specific media type code
cupsBitsPerColor unsigned The number of bits per color
cupsBitsPerPixel unsigned The number of bits per pixel
cupsBytesPerLine unsigned The number of bytes per line of image data
cupsColorOrder cups_order_t The order of color values
cupsColorSpace cups_cspace_t The type of color values
cupsCompression unsigned The device-specific compression code
cupsRowCount unsigned The device-specific row count
cupsRowFeed unsigned The device-specific row feed
cupsRowStep unsigned The device-specific row step

D - Functions

This appendix provides a reference for all of the CUPS API functions.

cupsAddOption()

Usage

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

Arguments

Argument Description
name The name of the option.
value The value of the option.
num_options Number of options currently in the array.
options Pointer to the options array.

Returns

The new number of options.

Description

cupsAddOption() adds an option to the specified array.

Example

#include <cups.h>

...

/* Declare the options array */
int           num_options;
cups_option_t *options;

/* Initialize the options array */
num_options = 0;
options     = (cups_option_t *)0;

/* Add options using cupsAddOption() */
num_options = cupsAddOption("media", "letter", num_options, &options);
num_options = cupsAddOption("resolution", "300dpi", num_options, &options);

See Also

cupsFreeOptions(), cupsGetOption(), cupsParseOptions()

cupsCancelJob()

Usage

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

Arguments

Argument Description
dest Printer or class name
job Job ID

Returns

1 on success, 0 on failure. On failure the error can be found by calling cupsLastError().

Description

cupsCancelJob() cancels the specifies job.

Example

#include <cups.h>

cupsCancelJob("LaserJet", 1);

See Also

cupsLastError(), cupsPrintFile()

cupsDoFileRequest()

Usage

ipp_t *
cupsDoFileRequest(http_t *http,
                  ipp_t *request,
                  const char *resource,
		  const char *filename);

Arguments

Argument Description
http HTTP connection to server.
request IPP request data.
resource HTTP resource name for POST.
filename File to send with POST request (NULL pointer if none.)

Returns

IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError().

Description

cupsDoFileRequest() does a HTTP POST request and provides the IPP request and optionally the contents of a file to the IPP server. It also handles resubmitting the request and performing password authentication as needed.

Example

#include <cups.h>

http_t      *http;
cups_lang_t *language;
ipp_t       *request;
ipp_t       *response;

...

/* Get the default language */
language = cupsLangDefault();

/* Create a new IPP request */
request  = ippNew();

request->request.op.operation_id = IPP_PRINT_FILE;
request->request.op.request_id   = 1;

/* Add required attributes */
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
             "attributes-charset", NULL, cupsLangEncoding(language));

ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
             "attributes-natural-language", NULL,
             language != NULL ? language->language : "C");

ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
             NULL, "ipp://hostname/resource");

ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
             NULL, cupsUser());

/* Do the request... */
response = cupsDoFileRequest(http, request, "/resource", "filename.txt");

See Also

cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew()

cupsDoRequest()

Usage

ipp_t *
cupsDoRequest(http_t *http,
              ipp_t *request,
              const char *resource);

Arguments

Argument Description
http HTTP connection to server.
request IPP request data.
resource HTTP resource name for POST.

Returns

IPP response data or NULL if the request fails. On failure the error can be found by calling cupsLastError().

Description

cupsDoRequest() does a HTTP POST request and provides the IPP request to the IPP server. It also handles resubmitting the request and performing password authentication as needed.

Example

#include <cups.h>

http_t      *http;
cups_lang_t *language;
ipp_t       *request;
ipp_t       *response;

...

/* Get the default language */
language = cupsLangDefault();

/* Create a new IPP request */
request  = ippNew();

request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
request->request.op.request_id   = 1;

/* Add required attributes */
ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
             "attributes-charset", NULL, cupsLangEncoding(language));

ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
             "attributes-natural-language", NULL,
             language != NULL ? language->language : "C");

ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
             NULL, "ipp://hostname/resource");

/* Do the request... */
response = cupsDoRequest(http, request, "/resource");

See Also

cupsLangDefault(), cupsLangEncoding(), cupsUser(), httpConnect(), ippAddString(), ippNew()

cupsFreeOptions()

Usage

void
cupsFreeOptions(int num_options,
                cups_option_t *options);

Arguments

Argument Description
num_options Number of options in array.
options Pointer to options array.

Description

cupsFreeOptions() frees all memory associated with the option array specified.

Example

#include <cups/cups.h>

int           num_options;
cups_option_t *options;

...

cupsFreeOptions(num_options, options);

See Also

cupsAddOption(), cupsGetOption(), cupsMarkOptions(), cupsParseOptions()

cupsGetClasses()

Usage

int
cupsGetClasses(char ***classes);

Arguments

Argument Description
classes Pointer to character pointer array.

Returns

The number of printer classes available.

Description

cupsGetClasses() gets a list of the available printer classes. The returned array should be freed using the free() when it is no longer needed.

Example

#include <cups/cups.h>

int  i;
int  num_classes;
char **classes;

...

num_classes = cupsGetClasses(&classes);

...

if (num_classes > 0)
{
  for (i = 0; i < num_classes; i ++)
    free(classes[i]);

  free(classes);
}

See Also

cupsGetDefault(), cupsGetPrinters()

cupsGetDefault()

Usage

const char *
cupsGetDefault(void);

Returns

A pointer to the default destination.

Description

cupsGetDefault() gets the default destination printer or class. The default destination is stored in a static string and will be overwritten (usually with the same value) after each call.

Example

#include <cups/cups.h>

printf("The default destination is %s\n", cupsGetDefault());

See Also

cupsGetClasses(), cupsGetPrinters()

cupsGetOption()

Usage

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

Arguments

Argument Description
name The name of the option.
num_options The number of options in the array.
options The options array.

Returns

A pointer to the option values or NULL if the option is not defined.

Description

cupsGetOption() returns the first occurrence of the named option. If the option is not included in the options array then a NULL pointer is returned.

#include <cups/cups.h>

int           num_options;
cups_option_t *options;
const char    *media;

...

media = cupsGetOption("media", num_options, options);

See Also

cupsAddOption(), cupsFreeOptions(), cupsMarkOptions(), cupsParseOptions()

cupsGetPassword()

Usage

const char *
cupsGetPassword(const char *prompt);

Arguments

Argument Description
prompt The prompt to display to the user.

Returns

A pointer to the password that was entered or NULL if no password was entered.

Description

cupsGetPassword() displays the prompt string and asks the user for a password. The password text is not echoed to the user.

Example

#include <cups/cups.h>

char *password;

...

password = cupsGetPassword("Please enter a password:");

See Also

cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser()

cupsGetPPD()

Usage

const char *
cupsGetPPD(const char *printer);

Arguments

Argument Description
printer The name of the printer.

Returns

The name of a temporary file containing the PPD file or NULL if the printer cannot be located or does not have a PPD file.

Description

cupsGetPPD() gets a copy of the PPD file for the named printer. The printer name can be of the form "printer" or "printer@hostname".

You should remove (unlink) the PPD file after you are done using it. The filename is stored in a static buffer and will be overwritten with each call to cupsGetPPD().

Example

#include <cups/cups.h>

char *ppd;

...

ppd = cupsGetPPD("printer@hostname");

...

unlink(ppd);

cupsGetPrinters()

Usage

int
cupsGetPrinters(char ***printers);

Arguments

Argument Description
printers Pointer to character pointer array.

Returns

The number of printer printers available.

Description

cupsGetPrinters() gets a list of the available printers. The returned array should be freed using the free() when it is no longer needed.

Example

#include <cups/cups.h>

int  i;
int  num_printers;
char **printers;

...

num_printers = cupsGetPrinters(&printers);

...

if (num_printers > 0)
{
  for (i = 0; i < num_printers; i ++)
    free(printers[i]);

  free(printers);
}

See Also

cupsGetClasses(), cupsGetDefault()

cupsLangDefault()

Usage

const char *
cupsLangDefault(void);

Returns

A pointer to the default language structure.

Description

cupsLangDefault() returns a language structure for the default language. The default language is defined by the LANG environment variable. If the specified language cannot be located then the POSIX (English) locale is used.

Call cupsLangFree() to free any memory associated with the language structure when you are done.

Example

#include <cups/language.h>

cups_lang_t *language;
...

language = cupsLangDefault();

...

cupsLangFree(language);

See Also

cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString()

cupsLangEncoding()

Usage

char *
cupsLangEncoding(cups_lang_t *language);

Arguments

Argument Description
language The language structure.

Returns

A pointer to the encoding string.

Description

cupsLangEncoding() returns the language encoding used for the specified language, e.g. "iso-8859-1", "utf-8", etc.

Example

#include <cups/language.h>

cups_lang_t *language;
char        *encoding;
...

language = cupsLangDefault();
encoding = cupsLangEncoding(language);
...

cupsLangFree(language);

See Also

cupsLangDefault(), cupsLangFlush(), cupsLangFree(), cupsLangGet(), cupsLangString()

cupsLangFlush()

Usage

void
cupsLangFlush(void);

Description

cupsLangFlush() frees all language structures that have been allocated.

Example

#include <cups/language.h>

...

cupsLangFlush();

See Also

cupsLangDefault(), cupsLangEncoding(), cupsLangFree(), cupsLangGet(), cupsLangString()

cupsLangFree()

Usage

void
cupsLangFree(cups_lang_t *language);

Arguments

Argument Description
language The language structure to free.

Description

cupsLangFree() frees the specified language structure.

Example

#include <cups/language.h>

cups_lang_t *language;
...

cupsLangFree(language);

See Also

cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangGet(), cupsLangString()

cupsLangGet()

Usage

cups_lang_t *
cupsLangGet(const char *name);

Arguments

Argument Description
name The name of the locale.

Returns

A pointer to a language structure.

Description

cupsLangGet() returns a language structure for the specified locale. If the locale is not defined then the POSIX (English) locale is substituted.

Example

#include <cups/language.h>

cups_lang_t *language;

...

language = cupsLangGet("fr");

...

cupsLangFree(language);

See Also

cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangString()

cupsLangString()

Usage

char *
cupsLangString(cups_lang_t *language,
               int         message);

Arguments

Argument Description
language The language to query.
message The message number.

Returns

A pointer to the message string or NULL if the message is not defined.

Description

cupsLangString() returns a pointer to the specified message string in the specified language.

Example

#include <cups/language.h>

cups_lang_t *language;
char        *s;
...

language = cupsLangGet("fr");

s = cupsLangString(language, CUPS_MSG_YES);

...

cupsLangFree(language);

See Also

cupsLangDefault(), cupsLangEncoding(), cupsLangFlush(), cupsLangFree(), cupsLangGet()

cupsLastError()

Usage

ipp_status_t
cupsLastError(void);

Returns

An enumeration containing the last IPP error.

Description

cupsLastError() returns the last IPP error that occurred. If no error occurred then it will return IPP_OK or IPP_OK_CONFLICT.

Example

#include <cups/cups.h>

ipp_status_t status;

...

status = cupsLastError();

See Also

cupsCancelJob(), cupsPrintFile()

cupsMarkOptions()

Usage

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

Arguments

Argument Description
ppd The PPD file to mark.
num_options The number of options in the options array.
options A pointer to the options array.

Returns

The number of conflicts found.

Description

cupsMarkOptions() marks options in the PPD file. It also handles mapping of IPP option names and values to PPD option names.

Example

#include <cups/cups.h>

int           num_options;
cups_option_t *options;
ppd_file_t    *ppd;

...

cupsMarkOptions(ppd, num_options, options);

See Also

cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsParseOptions()

cupsParseOptions()

Usage

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

Arguments

Argument Description
arg The string containing one or more options.
num_options The number of options in the options array.
options A pointer to the options array pointer.

Returns

The new number of options in the array.

Description

cupsParseOptions() parses the specifies string for one or more options of the form "name=value", "name", or "noname". It can be called multiple times to combine the options from several strings.

Example

#include <cups/cups.h>

int           num_options;
cups_option_t *options;

...

num_options = 0;
options     = (cups_option_t *)0;
num_options = cupsParseOptions(argv[5], num_options, &options);

See Also

cupsAddOption(), cupsFreeOptions(), cupsGetOption(), cupsMarkOptions()

cupsPrintFile()

Usage

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

Arguments

Argument Description
printer The printer or class to print to.
filename The file to print.
title The job title.
num_options The number of options in the options array.
options A pointer to the options array.

Returns

The new job ID number or 0 on error.

Description

cupsPrintFile() sends a file to the specified printer or class for printing. If the job cannot be printed the error code can be found by calling cupsLastError().

Example

#include <cups/cups.h>

int           num_options;
cups_option_t *options;
int           jobid;

...

jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
                      num_options, options);

See Also

cupsCancelJob(), cupsLastError(), cupsPrintFiles()

cupsPrintFiles()

Usage

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

Arguments

Argument Description
printer The printer or class to print to.
num_files The number of files to print.
files The files to print.
title The job title.
num_options The number of options in the options array.
options A pointer to the options array.

Returns

The new job ID number or 0 on error.

Description

cupsPrintFiles() sends multiple files to the specified printer or class for printing. If the job cannot be printed the error code can be found by calling cupsLastError().

Example

#include <cups/cups.h>

int           num_files;
const char    *files[100];
int           num_options;
cups_option_t *options;
int           jobid;

...

jobid = cupsPrintFiles("printer@hostname", num_files, files,
                       "Job Title", num_options, options);

See Also

cupsCancelJob(), cupsLastError(), cupsPrintFile()

cupsRasterClose()

Usage

void
cupsRasterClose(cups_raster_t *ras);

Arguments

Argument Description
ras The raster stream to close.

Description

cupsRasterClose() closes the specified raster stream.

Example

#include <cups/raster.h>

cups_raster_t *ras;

...

cupsRasterClose(ras);

See Also

cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()

cupsRasterOpen()

Usage

cups_raster_t *
cupsRasterOpen(int fd,
               cups_mode_t mode);

Arguments

Argument Description
fd The file descriptor to use.
mode The mode to use; CUPS_RASTER_READ or CUPS_RASTER_WRITE.

Returns

A pointer to a raster stream or NULL if there was an error.

Description

cupsRasterOpen() opens a raster stream for reading or writing.

Example

#include <cups/raster.h>

cups_raster_t *ras;

...

ras = cupsRasterOpen(0, CUPS_RASTER_READ);

See Also

cupsRasterClose(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()

cupsRasterReadHeader()

Usage

unsigned
cupsRasterReadHeader(cups_raster_t *ras,
                     cups_page_header_t *header);

Arguments

Argument Description
ras The raster stream to read from.
header A pointer to a page header structure to read into.

Returns

1 on success, 0 on EOF or error.

Description

cupsRasterReadHeader() reads a page header from the specified raster stream.

Example

#include <cups/raster.h>

int                  line;
cups_raster_t        *ras;
cups_raster_header_t header;
unsigned char        pixels[8192];
...

while (cupsRasterReadHeader(ras, &header))
{
  ...

  for (line = 0; line < header.cupsHeight; line ++)
  {
    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);

    ...
  }
}

See Also

cupsRasterClose(), cupsRasterOpen(), cupsRasterReadPixels(), cupsRasterWriteHeader(), cupsRasterWritePixels()

cupsRasterReadPixels()

Usage

unsigned
cupsRasterReadPixels(cups_raster_t *ras,
                     unsigned char *pixels,
		     unsigned length);

Arguments

Argument Description
ras The raster stream to read from.
pixels The pointer to a pixel buffer.
length The number of bytes of pixel data to read.

Returns

The number of bytes read or 0 on EOF or error.

Description

cupsRasterReadPixels() reads pixel data from the specified raster stream.

Example

#include <cups/raster.h>

int                  line;
cups_raster_t        *ras;
cups_raster_header_t header;
unsigned char        pixels[8192];
...

while (cupsRasterReadHeader(ras, &header))
{
  ...

  for (line = 0; line < header.cupsHeight; line ++)
  {
    cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);

    ...
  }
}

See Also

cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterWriteHeader(), cupsRasterWritePixels()

cupsRasterWriteHeader()

Usage

unsigned
cupsRasterWriteHeader(cups_raster_t *ras,
                      cups_page_header_t *header);

Arguments

Argument Description
ras The raster stream to write to.
header A pointer to the page header to write.

Returns

1 on success, 0 on error.

Description

cupsRasterWriteHeader() writes the specified page header to a raster stream.

Example

#include <cups/raster.h>

int                  line;
cups_raster_t        *ras;
cups_raster_header_t header;
unsigned char        pixels[8192];
...

cupsRasterWriteHeader(ras, &header);

for (line = 0; line < header.cupsHeight; line ++)
{
  ...

  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
}

See Also

cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWritePixels()

cupsRasterWritePixels()

Usage

unsigned
cupsRasterWritePixels(cups_raster_t *ras,
                      unsigned char *pixels,
		      unsigned length);

Arguments

Argument Description
ras The raster stream to write to.
pixels The pixel data to write.
length The number of bytes to write.

Returns

The number of bytes written.

Description

cupsRasterWritePixels() writes the specified pixel data to a raster stream.

Example

#include <cups/raster.h>

int                  line;
cups_raster_t        *ras;
cups_raster_header_t header;
unsigned char        pixels[8192];
...

cupsRasterWriteHeader(ras, &header);

for (line = 0; line < header.cupsHeight; line ++)
{
  ...

  cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
}

See Also

cupsRasterClose(), cupsRasterOpen(), cupsRasterReadHeader(), cupsRasterReadPixels(), cupsRasterWriteHeader()

cupsServer()

Usage

const char *
cupsServer(void);

Returns

A pointer to the default server name.

Description

cupsServer() returns a pointer to the default server name. The server name is stored in a static location and will be overwritten with every call to cupsServer()

The default server is determined from the following locations:

  1. The CUPS_SERVER environment variable,
  2. The ServerName directive in the client.conf file,
  3. The default host, "localhost".

Example

#include <cups/cups.h>

const char *server;

server = cupsServer();

See Also

cupsGetPassword(), cupsSetPasswordCB(), cupsSetServer(), cupsSetUser(), cupsUser()

cupsSetPasswordCB()

Usage

void
cupsSetPasswordCB(const char *(*cb)(const char *prompt));

Arguments

Argument Description
cb The password callback function.

Description

cupsSetPasswordCB() sets the callback function to use when asking the user for a password. The callback function must accept a single character string pointer (the prompt string) and return NULL if the user did not enter a password string or a pointer to the password string otherwise.

Example

#include <cups/cups.h>

const char *
my_password_cb(const char *prompt)
{
  return (getpass(prompt));
}

...

char *password;

...

cupsSetPasswordCB(my_password_cb);
password = cupsGetPassword("Please enter a password:");

See Also

cupsServer(), cupsSetServer(), cupsSetUser(), cupsUser()

cupsSetServer()

Usage

void
cupsSetServer(const char *server);

Arguments

Argument Description
server The default server to use.

Description

cupsSetServer() sets the default server to use for the CUPS API. If the server argument is NULL, the default server is used.

Example

#include <cups/cups.h>

cupsSetServer("foo.bar.com");

See Also

cupsServer(), cupsSetPasswordCB(), cupsSetUser(), cupsUser()

cupsSetUser()

Usage

void
cupsSetUser(const char *user);

Arguments

Argument Description
user The user name string to use.

Description

cupsSetUser() sets the default user name for authentication. If the user argument is NULL then the current login user is used.

Example

#include <cups/cups.h>

...

cupsSetUser("root");

See Also

cupsServer(), cupsSetPasswordCB(), cupsSetServer(), cupsUser()

cupsTempFile()

Usage

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

Arguments

Argument Description
filename The character string to hold the temporary filename.
length The size of the filename string in bytes.

Returns

A pointer to filename.

Description

cupsTempFile() generates a temporary filename for the /var/tmp directory or the directory specified by the TMPDIR environment variable.

Example

#include <cups/cups.h>

char filename[256];

cupsTempFile(filename, sizeof(filename));

cupsUser()

Usage

const char *
cupsUser(void);

Returns

A pointer to the current username or NULL if the user ID is undefined.

Description

cupsUser() returns the name associated with the current user ID as reported by the getuid() system call.

Example

#include <cups/cups.h>

const char *user;

user = cupsUser();

See Also

cupsGetPassword(), cupsServer()

httpBlocking()

Usage

void httpBlocking(http_t *http, int blocking)

Arguments

Argument Description
http The HTTP connection
blocking 0 if the connection should be non-blocking, 1 if it should be blocking

Description

The httpBlocking() function sets the blocking mode for the HTTP connection. By default HTTP connections will block (stop) the client program until data is available or can be sent to the server.

Example

#include <cups/http.h>

http_t *http;

http = httpConnect("server", port);
httpBlocking(http, 0);

See Also

httpCheck(), httpConnect()

httpCheck()

Usage

int httpCheck(http_t *http);

Arguments

Argument Description
http The HTTP connection

Returns

0 if there is no data pending, 1 otherwise.

Description

The httpCheck() function checks to see if there is any data pending on an HTTP connection.

Example

#include <cups/http.h>

http_t *http;

if (httpCheck(http))
{
  ... do something ...
}

See Also

httpBlocking(), httpConnect(), httpGets(), httpRead()

httpClearFields()

Usage

void httpClearFields(http_t *http)

Arguments

Argument Description
http The HTTP connection

Description

The httpClearFields() function clears all HTTP request fields for the HTTP connection.

Example

#include <cups/http.h>

http_t *http;

httpClearFields(http);

See Also

httpConnect(), httpGetField(), httpSetField()

httpClose()

Usage

void httpClose(http_t *http);

Arguments

Argument Description
http The HTTP connection

Description

The httpClose() function closes an active HTTP connection.

Example

#include <cups/http.h>

http_t *http;

httpClose(http);

See Also

httpConnect()

httpConnect()

Usage

http_t *httpConnect(const char *hostname, int port);

Arguments

Argument Description
hostname The name or IP address of the server to connect to
port The port number to use

Returns

A pointer to a HTTP connection structure or NULL if the connection could not be made.

Description

The httpConnect() function opens a HTTP connection to the specified server and port.

Example

#include <cups/http.h>

http_t *http;

http = httpConnect(cupsServer(), ippPort());

See Also

httpClose(), httpGet(), httpGets(), httpPost(), httpRead(), httpWrite()

httpDecode64()

Usage

char *httpDecode64(char *out, const char *in);

Arguments

Argument Description
out The output string
in The input string

Returns

A pointer to the decoded string.

Description

The httpDecode64() function decodes a base-64 encoded string to the original string.

Example

#include <cups/http.h>

char encoded_string[255];
char original_string[255];

httpDecode64(original_string, encoded_string);

See Also

httpEncode64()

httpDelete()

Usage

int httpDelete(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to delete

Returns

0 on success, non-zero on failure.

Description

The httpDelete() function sends a HTTP DELETE request to the server.

Example

#include <cups/http.h>

http_t *http;

httpDelete(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpEncode64()

Usage

char *httpEncode64(char *out, const char *in);

Arguments

Argument Description
out The output string
in The input string

Returns

A pointer to the encoded string.

Description

The httpEncode64() function decodes a base-64 encoded string to the original string.

Example

#include <cups/http.h>

char encoded_string[255];
char original_string[255];

httpEncode64(encoded_string, original_string);

See Also

httpDecode64()

httpError()

Usage

int httpError(http_t *http);

Arguments

Argument Description
http The HTTP connection

Returns

The last error that occurred or 0 if no error has occurred.

Description

The httpError() function returns the last error that occurred on the HTTP connection.

Example

#include <cups/http.h>

http_t *http;

if (httpError(http))
{
  ... show an error message ...
}

See Also

httpConnect()

httpFlush()

Usage

void httpFlush(http_t *http);

Arguments

Argument Description
http The HTTP connection

Description

The httpFlush() function flushes any remaining data left from a GET or POST operation.

Example

#include <cups/http.h>

http_t *http;

httpFlush(http);

See Also

httpConnect(),

httpGet()

Usage

int httpGet(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to get

Returns

0 on success, non-zero on failure.

Description

The httpGet() function sends a HTTP GET request to the server.

Example

#include <cups/http.h>

http_t *http;

httpGet(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpGets()

Usage

char *httpGets(char *line, int length, http_t *http)

Arguments

Argument Description
line The string to fill with a line from the HTTP connection
length The maximum length of the string
http The HTTP connection

Returns

A pointer to the string or NULL if no line could be retrieved.

Description

The httpGets() function is used to read a request line from the HTTP connection. It is not normally used by a client program.

Example

#include <cups/http.h>

http_t *http;
char line[1024];

if (httpGets(line, sizeof(line), http))
{
  ... process the line ...
}

See Also

httpConnect(), httpUpdate()

httpGetDateString()

Usage

const char *httpGetDateString(time_t time)

Arguments

Argument Description
time The UNIX date/time value

Returns

A pointer to a static string containing the HTTP date/time string for the specified UNIX time value.

Description

The httpGetDateString() function generates a date/time string suitable for HTTP requests from a UNIX time value.

Example

#include <cups/http.h>

puts(httpGetDateString(time(NULL)));

See Also

httpGetDateTime()

httpGetDateTime()

Usage

time_t httpGetDateTime(const char *date)

Arguments

Argument Description
date The HTTP date/time string

Returns

A UNIX time value.

Description

The httpGetDateTime() function converts a HTTP date/time string to a UNIX time value.

Example

#include <cups/http.h>

printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));

See Also

httpGetDateString()

httpGetField()

Usage

const char *httpGetField(http_t *http, http_field_t field);

Arguments

Argument Description
http The HTTP connection
field The HTTP field

Returns

A pointer to the field value string.

Description

The httpGetField() function returns the current value for the specified HTTP field.

Example

#include <cups/http.h>

http_t *http;

httpGet(http, "/some/uri");
while (httpUpdate(http) == HTTP_CONTINUE);

puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));

See Also

httpConnect(), httpSetField()

httpHead()

Usage

int httpHead(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to head

Returns

0 on success, non-zero on failure.

Description

The httpHead() function sends a HTTP HEAD request to the server.

Example

#include <cups/http.h>

http_t *http;

httpHead(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpInitialize()

Usage

void httpInitialize(void);

Description

The httpInitialize() function initializes the networking code as needed by the underlying platform. It is called automatically by the httpConnect() function.

Example

#include <cups/http.h>

httpInitialize();

See Also

httpConnect()

httpOptions()

Usage

int httpOptions(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to check for options

Returns

0 on success, non-zero on failure.

Description

The httpOptions() function sends a HTTP OPTIONS request to the server.

Example

#include <cups/http.h>

http_t *http;

httpOptions(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpPost()

Usage

int httpPost(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to post to

Returns

0 on success, non-zero on failure.

Description

The httpPost() function sends a HTTP POST request to the server.

Example

#include <cups/http.h>

http_t *http;

httpPost(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpPrintf()

Usage

int httpPrintf(http_t *http, const char *format, ...);

Arguments

Argument Description
http The HTTP connection
format A printf-style format string

Returns

The number of bytes written.

Description

The httpPrintf() function sends a formatted string to the HTTP connection. It is normally only used by the CUPS API and scheduler.

Example

#include <cups/http.h>

http_t *http;

httpPrintf(http, "GET / HTTP/1.1 \r\n");

See Also

httpConnect()

httpPut()

Usage

int httpPut(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to put

Returns

0 on success, non-zero on failure.

Description

The httpPut() function sends a HTTP PUT request to the server.

Example

#include <cups/http.h>

http_t *http;

httpDelete(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpRead()

Usage

int httpRead(http_t *http, char *buffer, int length);

Arguments

Argument Description
http The HTTP connection
buffer The buffer to read into
length The number of bytes to read

Returns

The number of bytes read or -1 on error.

Description

The httpRead() function reads data from the HTTP connection, possibly the result of a GET or POST request.

Example

#include <cups/http.h>

http_t *http;
char buffer[1024];
int  bytes;

httpGet(http, "/");
while (httpUpdate(http) != HTTP_CONTINUE);
while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
{
  buffer[bytes] = '\0';
  fputs(buffer, stdout);
}

See Also

httpConnect(), httpWrite()

httpReconnect()

Usage

int httpReconnect(http_t *http);

Arguments

Argument Description
http The HTTP connection

Returns

0 on success, non-zero on failure.

Description

The httpReconnect() function reconnects to the HTTP server. This is usually done automatically if the HTTP functions detect that the server connection has terminated.

Example

#include <cups/http.h>

http_t *http;

httpReconnect(http);

See Also

httpConnect()

httpSeparate()

Usage

void httpSeparate(const char *uri, char *method,
                  char *username, char *host, int *port,
                  char *resource);

Arguments

Argument Description
uri The URI to separate
method The method (scheme) of the URI
username The username (and password) portion of the URI, if any
host The hostname portion of the URI, if any
port The port number for the URI, either as specified or as default for the method/scheme
resource The resource string, usually a filename on the server

Description

The httpSeparate() function separates the specified URI into its component parts. The method, username, hostname, and resource strings should be at least HTTP_MAX_URI characters long to avoid potential buffer overflow problems.

Example

char uri[HTTP_MAX_URI];
char method[HTTP_MAX_URI];
char username[HTTP_MAX_URI];
char host[HTTP_MAX_URI];
char resource[HTTP_MAX_URI];
int port;

httpSeparate(uri, method, username, host, &port, resource);

See Also

httpConnect()

httpSetField()

Usage

void httpSetField(http_t *http, http_field_t field, const char *value);

Arguments

Argument Description
http The HTTP connection
field The HTTP field
value The string value for the field

Description

The httpSetField() function sets the current value for the specified HTTP field.

Example

#include <cups/http.h>

http_t *http;

httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
httpGet(http, "/some/uri");
while (httpUpdate(http) == HTTP_CONTINUE);

See Also

httpConnect(), httpGetField()

httpTrace()

Usage

int httpTrace(http_t *http, const char *uri);

Arguments

Argument Description
http The HTTP connection
uri The URI to trace

Returns

0 on success, non-zero on failure.

Description

The httpTrace() function sends a HTTP TRACE request to the server.

Example

#include <cups/http.h>

http_t *http;

httpTrace(http, "/some/uri");

See Also

httpConnect(), httpSetField(), httpUpdate()

httpUpdate()

Usage

http_status_t httpUpdate(http_t *http);

Arguments

Argument Description
http The HTTP connection

Returns

The HTTP status of the current request.

Description

The httpUpdate() function updates the current request status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE request to finalize the HTTP request and retrieve the request status.

Since proxies and the current blocking mode can cause the request to take longer, programs should continue calling httpUpdate() until the return status is not the constant value HTTP_CONTINUE.

Example

#include <cups/http.h>

http_t *http;
http_status_t status;

httpGet(http, "/some/uri");
while ((status = httpUpdate(http)) == HTTP_CONTINUE);
printf("Request status is %d\n", status);

See Also

httpConnect(), httpDelete(), httpGet(), httpHead(), httpOptions(), httpPost(), httpPut(), httpTrace()

httpWrite()

Usage

int httpWrite(http_t *http, char *buffer, int length);

Arguments

Argument Description
http The HTTP connection
buffer The buffer to read into
length The number of bytes to read

Returns

The number of bytes read or -1 on error.

Description

The httpWrite() function reads data from the HTTP connection, possibly the result of a GET or POST request.

Example

#include <cups/http.h>

http_t *http;
FILE *fp;
char buffer[1024];
int  bytes;

httpPost(http, "/");

while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
  httpWrite(http, buffer, bytes);

while (httpUpdate(http) != HTTP_CONTINUE);

while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
{
  buffer[bytes] = '\0';
  fputs(buffer, stdout);
}

See Also

httpConnect(), httpRead()

ippAddBoolean()

Usage

ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
                               const char *name, char value);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
value The boolean value

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddBoolean() function adds a single boolean attribute value to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);

See Also

ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddBooleans()

Usage

ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
                                const char *name, int num_values,
                                const char *values);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
num_values The number of values
values The boolean values

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddBooleans() function adds one or more boolean attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values false values is created.

Example

#include <cups/ipp.h>

ipp_t *ipp;
char values[10];

ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);

See Also

ippAddBoolean(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddDate()

Usage

ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group,
                            const char *name, ipp_uchar_t *value);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
value The date value

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddDate() function adds a single date-time attribute value to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute", 
           ippTimeToDate(time(NULL));

See Also

ippAddBoolean(), ippAddBooleans(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings(), ippTimeToDate()

ippAddInteger()

Usage

ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
                               ipp_tag_t tag, const char *name,
                               int value);

Arguments

Argument Description
ipp The IPP request
group The IPP group
tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)
name The name of attribute
value The integer value

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddInteger() function adds a single integer attribute value to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddIntegers()

Usage

ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
                                ipp_tag_t tag, const char *name,
                                int num_values, const int *values);

Arguments

Argument Description
ipp The IPP request
group The IPP group
tag The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)
name The name of attribute
num_values The number of values
values The integer values

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddIntegers() function adds one or more integer attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0 values is created.

Example

#include <cups/ipp.h>

ipp_t *ipp;
int values[100];

ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddRange()

Usage

ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group,
                             const char *name, int low,
                             int high);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
low The lower value
high The higher value

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddRange() function adds a single range attribute value to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddRanges()

Usage

ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
                              const char *name, int num_values,
                              const int *lows, const int *highs);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
num_values The number of range values
lows The lower values
highs The higher values

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddRanges() function adds one or more range attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 ranges is created.

Example

#include <cups/ipp.h>

ipp_t *ipp;
int lows[2];
int highs[2];

ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddResolution()

Usage

ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
                                  const char *name, int xres,
                                  int yres, ipp_res_t units);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
xres The horizontal resolution
yres The vertical resolution
units The resolution units

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddResolution() function adds a single resolution attribute value to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
              720, 720, IPP_RES_PER_INCH);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolutions(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddResolutions()

Usage

ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
                                   const char *name, int num_values,
                                   const int *xres, const int *yres,
                                   const ipp_res_t *units);

Arguments

Argument Description
ipp The IPP request
group The IPP group
name The name of attribute
num_values The number of resolution values
xres The horizontal resolutions
yres The vertical resolutions
units The resolution units

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddResolutions() function adds one or more resolution attribute values to the specified IPP request. If the values pointer is NULL then an array of num_values 0,0 resolutions is created.

Example

#include <cups/ipp.h>

ipp_t *ipp;
int xres[5];
int yres[5];
ipp_res_t units[5];

ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
              5, xres, yres, units);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddSeparator(), ippAddString(), ippAddStrings()

ippAddSeparator()

Usage

ipp_attribute_t *ippAddSeparator(ipp_t *ipp);

Arguments

Argument Description
ipp The IPP request

Returns

A pointer to the new separator or NULL if the separator could not be created.

Description

The ippAddSeparator() function adds a group separator to the specified IPP request.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddSeparator(ipp);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddString(), ippAddStrings()

ippAddString()

Usage

ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group,
                              ipp_tag_t tag, const char *name,
                              const char *charset, const char *value);

Arguments

Argument Description
ipp The IPP request
group The IPP group
tag The type of string value
name The name of attribute
charset The character set for the string
value The string value

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddString() function adds a single string attribute value to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the string to identify the string encoding used. Otherwise the charset value is ignored.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
             NULL, "abc123");

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddStrings()

ippAddStrings()

Usage

ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
                               ipp_tag_t tag, const char *name,
                               int num_values, const char *charset,
                               const char **values);

Arguments

Argument Description
ipp The IPP request
group The IPP group
tag The type of string value
name The name of attribute
num_values The number of strings
charset The character set for the strings
values The string values

Returns

A pointer to the new attribute or NULL if the attribute could not be created.

Description

The ippAddStrings() function adds one or more string attribute values to the specified IPP request. For IPP_TAG_NAMELANG and IPP_TAG_TEXTLANG strings, the charset value is provided with the strings to identify the string encoding used. Otherwise the charset value is ignored. If the values pointer is NULL then an array of num_values NULL strings is created.

Example

#include <cups/ipp.h>

ipp_t *ipp;
char *values[2] = { "one", "two" };

ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
              2, NULL, values);

See Also

ippAddBoolean(), ippAddBooleans(), ippAddDate(), ippAddInteger(), ippAddIntegers(), ippAddRange(), ippAddRanges(), ippAddResolution(), ippAddResolutions(), ippAddSeparator(), ippAddString()

ippDateToTime()

Usage

time_t ippDateToTime(const ipp_uchar_t date[11]);

Arguments

Argument Description
date The IPP date-time value

Returns

A UNIX time value.

Description

The ippDateToTime() function converts an IPP date-time value to a UNIX time value.

Example

#include <cups/ipp.h>

ipp_uchar_t date[11];

printf("UNIX time is %d\n", ippDateToTime(date));

See Also

ippTimeToDate()

ippDelete()

Usage

void ippDelete(ipp_t *ipp);

Arguments

Argument Description
ipp The IPP request or response

Description

The ippDelete() function deletes all memory used by an IPP request or response.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ippDelete(ipp);

See Also

ippNew()

ippFindAttribute()

Usage

ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);

Arguments

Argument Description
ipp The IPP request or response
name The name of the attribute
tag The required value tag for the attribute or IPP_TAG_ZERO for any type of value.

Returns

A pointer to the first occurrence of the requested attribute, or NULL if it was not found.

Description

ippFindAttribute() finds the first occurrence of the named attribute. The tag parameter restricts the search to a specific value type - use IPP_TAG_ZERO to find any value with the name.

The value tags IPP_TAG_NAME and IPP_TAG_TEXT match the name/text values with or without the language code.

Example

ipp_attribute_t *attr;

attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);

See Also

cupsDoFileRequest(), cupsDoRequest(), ippDelete(), ippNew()

ippLength()

Usage

int ippLength(ipp_t *ipp);

Arguments

Argument Description
ipp The IPP request or response

Returns

The total encoded length of the IPP request or response in bytes.

Description

ippLength() returns the length of the IPP request or response in bytes.

Example

printf("The length of the response is %d bytes.\n", ippLength(response));

See Also

ippDelete(), ippNew()

ippNew()

Usage

ipp_t *ippNew(void);

Returns

A pointer to a new IPP request or response.

Description

The ippNew() function creates a new IPP request or response.

Example

#include <cups/ipp.h>

ipp_t *ipp;

ipp = ippNew();

See Also

ippDelete()

ippPort()

Usage

int ippPort(void);

Returns

The default TCP/IP port number for IPP requests.

Description

The ippPort() function returns the default IPP port number for requests.

Example

#include <cups/http.h>
#include <cups/ipp.h>

http_t *http;

http = httpConnect(cupsServer(), ippPort());

See Also

cupsServer(), ippSetPort()

ippRead()

Usage

ipp_state_t ippRead(http_t *http, ipp_t *ipp);

Arguments

Argument Description
http The HTTP connection
ipp The IPP request or response

Returns

The current read state.

Description

The ippRead() function reads IPP attributes from the specified HTTP connection. Programs should continue calling ippRead() until IPP_ERROR or IPP_DATA is returned.

Example

#include <cups/http.h>
#include <cups/ipp.h>

http_t *http;
ipp_t *ipp;
ipp_state_t status;

ipp = ippNew();

while ((status = ippRead(http, ipp)) != IPP_ERROR)
  if (status == IPP_DATA)
    break;

if (status == IPP_DATA)
{
  ... read additional non-IPP data using httpRead() ...
}

See Also

ippWrite()

ippSetPort()

Usage

void
ippSetPort(int port);

Arguments

Argument Description
port The port number to use

Description

The ippSetPort() function sets the default IPP port number for requests.

Example

#include <cups/http.h>
#include <cups/ipp.h>

...

ippSetPort(8631);

See Also

ippPort()

ippTimeToDate()

Usage

ipp_uchar_t *ippTimeToDate(time_t time);

Arguments

Argument Description
time The UNIX time value

Returns

A static pointer to an IPP date-time value.

Description

The ippTimeToDate() function converts a UNIX time to an IPP date-time value.

Example

#include <cups/ipp.h>

ipp_uchar_t *date;

date = ippTimeToDate(time(NULL));

See Also

ippDateToTime()

ippWrite()

Usage

ipp_state_t ippWrite(http_t *http, ipp_t *ipp);

Arguments

Argument Description
http The HTTP connection
ipp The IPP request or response

Returns

The current write state.

Description

The ippWrite() function writes IPP attributes to the specified HTTP connection. Programs should continue calling ippWrite() until IPP_ERROR or IPP_DATA is returned.

Example

#include <cups/http.h>
#include <cups/ipp.h>

http_t *http;
ipp_t *ipp;
ipp_state_t status;

ipp = ippNew();
... add attributes ...

while ((status = ippWrite(http, ipp)) != IPP_ERROR)
  if (status == IPP_DATA)
    break;

if (status == IPP_DATA)
{
  ... read additional non-IPP data using httpWrite() ...
}

See Also

ippRead()

ppdClose()

Usage

void ppdClose(ppd_file_t *ppd);

Arguments

Argument Description
ppd The PPD file

Description

The ppdClose() function frees all memory associated with the PPD file.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppdClose(ppd);

See Also

ppdOpen(), ppdOpenFd(), ppdOpenFile()

ppdConflicts()

Usage

int ppdConflicts(ppd_file_t *ppd);

Arguments

Argument Description
ppd The PPD file

Returns

The number of option conflicts in the file.

Description

The ppdConflicts() function returns the number of conflicts with the currently selected options.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

printf("%d conflicts\n", ppdConflicts(ppd));

See Also

cupsMarkOptions(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption()

ppdEmit()

Usage

int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);

Arguments

Argument Description
ppd The PPD file
file The file to write to
section The option section to write

Returns

0 on success, -1 on error.

Description

The ppdEmit() function sends printer-specific option commands to the specified file.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppdEmit(ppd, stdout, PPD_ORDER_PAGE);

See Also

ppdEmitFd()

ppdEmitFd()

Usage

int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);

Arguments

Argument Description
ppd The PPD file
fd The file descriptor to write to
section The option section to write

Returns

0 on success, -1 on error.

Description

The ppdEmitFd() function sends printer-specific option commands to the specified file descriptor.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);

See Also

ppdEmit()

ppdFindChoice()

Usage

ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);

Arguments

Argument Description
option A pointer to the option
choice The name of the choice

Returns

A pointer to the choice data or NULL if the choice does not exist.

Description

The ppdFindChoice() function returns a pointer to the choice data for the specified option.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
ppd_option_t *option;
ppd_choice_t *choice;

option = ppdFindOption(ppd, "PageSize");
choice = ppdFindChoice(option, "Letter");

See Also

ppdFindMarkedChoice(), ppdFindOption()

ppdFindMarkedChoice()

Usage

ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);

Arguments

Argument Description
ppd The PPD file
keyword The name of the option

Returns

A pointer to the choice data or NULL if the choice does not exist or is not marked.

Description

The ppdFindMarkedChoice() function returns a pointer to the marked choice data for the specified option.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
ppd_choice_t *choice;

choice = ppdFindMarkedChoice(ppd, "PageSize");

See Also

ppdFindChoice(), ppdFindOption()

ppdFindOption()

Usage

ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);

Arguments

Argument Description
ppd The PPD file
keyword The name of the option

Returns

A pointer to the option data or NULL if the option does not exist.

Description

The ppdFindOption() function returns a pointer to the option data for the specified option.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
ppd_option_t *option;

option = ppdFindOption(ppd, "PageSize");

See Also

ppdFindChoice(), ppdFindMarkedChoice()

ppdIsMarked()

Usage

int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);

Arguments

Argument Description
ppd The PPD file
keyword The name of the option
choice The name of the option choice

Returns

1 if the choice is marked, 0 otherwise.

Description

The ppdIsMarked() function returns whether or not the specified option choice is marked.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

printf("Letter size %s selected.\n",
       ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");

See Also

cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption()

ppdMarkDefaults()

Usage

void ppdMarkDefaults(ppd_file_t *ppd);

Arguments

Argument Description
ppd The PPD file

Description

The ppdMarkDefaults() function marks all of the default choices in the PPD file.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppdMarkDefaults(ppd);

See Also

cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption()

ppdMarkOption()

Usage

int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);

Arguments

Argument Description
ppd The PPD file
keyword The name of the option
choice The name of the choice

Returns

The number of conflicts in the PPD file.

Description

The ppdMarkOption() function marks the specified option choice.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppdMarkOption(ppd, "PageSize", "Letter");

See Also

cupsMarkOptions(), ppdConflicts(), ppdIsMarked(), ppdMarkDefaults(), ppdMarkOption()

ppdOpen()

Usage

ppd_file_t *ppdOpen(FILE *file);

Arguments

Argument Description
file The file to read from

Returns

A pointer to a PPD file structure or NULL if the PPD file could not be read.

Description

The ppdOpen() function reads a PPD file from the specified file into memory.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
FILE *file;

file = fopen("filename.ppd", "rb");
ppd = ppdOpen(file);
fclose(file);

See Also

ppdClose(), ppdOpenFd(), ppdOpenFile()

ppdOpenFd()

Usage

ppd_file_t *ppdOpenFd(int fd);

Arguments

Argument Description
fd The file descriptor to read from

Returns

A pointer to a PPD file structure or NULL if the PPD file could not be read.

Description

The ppdOpenFd() function reads a PPD file from the specified file descriptor into memory.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
int        fd;

fd = open("filename.ppd", O_RDONLY);
ppd = ppdOpenFd(fd);
close(fd);

See Also

ppdClose(), ppdOpen(), ppdOpenFile()

ppdOpenFile()

Usage

ppd_file_t *ppdOpenFile(const char *filename);

Arguments

Argument Description
filename The name of the file to read from

Returns

A pointer to a PPD file structure or NULL if the PPD file could not be read.

Description

The ppdOpenFile() function reads a PPD file from the named file into memory.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

ppd = ppdOpenFile("filename.ppd");

See Also

ppdClose(), ppdOpen(), ppdOpenFd()

ppdPageLength()

Usage

float ppdPageLength(ppd_file_t *ppd, const char *name);

Arguments

Argument Description
ppd The PPD file
name The name of the page size

Returns

The length of the specified page size in points or 0 if the page size does not exist.

Description

The ppdPageLength() function returns the page length of the specified page size.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));

See Also

ppdPageLength(), ppdPageSize(), ppdPageWidth()

ppdPageSize()

Usage

ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);

Arguments

Argument Description
ppd The PPD file
name The name of the page size

Returns

A pointer to the page size record of the specified page size in points or NULL if the page size does not exist.

Description

The ppdPageSize() function returns the page size record for the specified page size.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;
ppd_size_t *size;

size = ppdPageSize(ppd, "Letter");
if (size != NULL)
{
  printf(" Width = %.0f\n", size->width);
  printf("Length = %.0f\n", size->length);
  printf("  Left = %.0f\n", size->left);
  printf(" Right = %.0f\n", size->right);
  printf("Bottom = %.0f\n", size->bottom);
  printf("   Top = %.0f\n", size->top);
}

See Also

ppdPageLength(), ppdPageWidth()

ppdPageWidth()

Usage

float ppdPageWidth(ppd_file_t *ppd, const char *name);

Arguments

Argument Description
ppd The PPD file
name The name of the page size

Returns

The width of the specified page size in points or 0 if the page size does not exist.

Description

The ppdPageWidth() function returns the page width of the specified page size.

Example

#include <cups/ppd.h>

ppd_file_t *ppd;

printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));

See Also

ppdPageLength(), ppdPageSize()