From: mike Date: Mon, 5 Mar 2001 13:35:41 +0000 (+0000) Subject: Restore truncated files due to Andy's copyright update script... X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2a4fe6b6601b636adb9b8ca6fb83e2c252fa0133;p=thirdparty%2Fcups.git Restore truncated files due to Andy's copyright update script... git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@1608 7a7537e8-13f0-0310-91df-b6672ffda945 --- diff --git a/doc/documentation.html b/doc/documentation.html index e69de29bb2..39cc1f308b 100644 --- a/doc/documentation.html +++ b/doc/documentation.html @@ -0,0 +1,81 @@ + + + Documentation - Common UNIX Printing System + + + Easy Software Products Home Page + Do Administration Tasks + Manage Printer Classes Status + On-Line Help + Manage Jobs + Manage Printers + Download the Current CUPS Software + + + + +
+Common UNIX Printing System +
+ +

Documentation

+ +The following documentation for CUPS is available on this server: + + + +
+ +

The Common UNIX Printing System, CUPS, and the CUPS logo are the +trademark property of Easy Software +Products. CUPS is copyright 1997-2000 by Easy Software Products, +All Rights Reserved. + + + diff --git a/doc/index.html b/doc/index.html index e69de29bb2..1150e4cdf0 100644 --- a/doc/index.html +++ b/doc/index.html @@ -0,0 +1,36 @@ + + + Common UNIX Printing System + + + Easy Software Products Home Page + Do Administration Tasks + Manage Printer Classes Status + On-Line Help + Manage Jobs + Manage Printers + Download the Current CUPS Software + + + + +

+Common UNIX Printing System +
+ +

Do Administration Tasks

+

Manage Printer Classes

+

On-Line Help

+

Manage Jobs

+

Manage Printers

+

Download the Current CUPS Software

+ +
+ +

The Common UNIX Printing System, CUPS, and the CUPS logo are the +trademark property of Easy Software +Products. CUPS is copyright 1997-2000 by Easy Software Products, +All Rights Reserved. + + + diff --git a/doc/spm.html b/doc/spm.html index e69de29bb2..716ee1b63c 100644 --- a/doc/spm.html +++ b/doc/spm.html @@ -0,0 +1,7511 @@ + + + + CUPS Software Programmers Manual + + + + + + + +


+

CUPS Software Programmers Manual


+CUPS-SPM-1.1.7
+Easy Software Products
+Copyright 1997-2001, All Rights Reserved
+
+
+

Table of Contents

+

+

Preface + +1 - Printing System Overview + +2 - The CUPS API + +3 - Writing Filters + +4 - Writing Printer Drivers + +5 - Writing Backends + +A - Software License Agreement + +B - Constants + +C - Structures + +D - Functions + +
+

Preface

+

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

+

System Overview

+

CUPS provides a portable printing layer for UNIX®-based operating +systems. It has been developed by Easy +Software Products to promote a standard printing solution for all +UNIX vendors and users. CUPS provides the System V and Berkeley +command-line interfaces.

+

CUPS uses the Internet Printing Protocol ("IPP") as the basis for +managing print jobs and queues. The Line Printer Daemon ("LPD") Server +Message Block ("SMB"), and AppSocket (a.k.a. JetDirect) protocols are +also supported with reduced functionality. CUPS adds network printer +browsing and PostScript Printer Description ("PPD") based printing +options to support real-world printing under UNIX.

+

CUPS also includes a customized version of GNU Ghostscript +(currently based off GNU Ghostscript 5.50) and an image file RIP that +are used to support non-PostScript printers. Sample drivers for HP and +EPSON printers are included that use these filters.

+ + + +

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

+ +

1 - Printing System Overview

+

This chapter provides an overview of how the Common UNIX Printing +System works.

+

The Printing Problem

+

For years the printing problem has plagued UNIX. Unlike +Microsoft® Windows® or Mac OS, UNIX has no standard interface or system +in place for supporting printers. Among the solutions currently +available, the Berkeley and System V printing systems are the most +prevalent.

+

These printing systems support line printers (text only) or +PostScript printers (text and graphics), and with some coaxing they can +be made to support a full range of printers and file formats. However, +because each varient of the UNIX operating system uses a different +printing system than the next developing printer drivers for a wide +range of printers and operating systems is extremely difficult. That +combined with the limited volume of customers for each UNIX varient has +forced most printer vendors to give up supporting UNIX entirely.

+

CUPS is designed to eliminate the printing problem. One +common printing system can be used by all UNIX varients to support the +printing needs of users. Printer vendors can use its modular filter +interface to develop a single driver program that supports a wide range +of file formats with little or no effort. Since CUPS provides both the +System V and Berkeley printing commands, users (and applications) can +reap the benefits of this new technology with no changes.

+

The Technology

+

CUPS is based upon an emerging Internet standard called the Internet +Printing Protocol. IPP has been embraced by dozens of printer and +printer server manufacturers and is supported by Microsoft Windows +2000.

+

IPP defines a standard protocol for printing as well as managing +print jobs and printer options like media size, resolution, and so +forth. Like all IP-based protocols, IPP can be used locally or over the +Internet to printers hundreds or thousands of miles away. Unlike other +protocols, however, IPP also supports access control, authentication, +and encryption, making it a much more capable and secure printing +solution than older ones.

+

IPP is layered on top of the Hyper-Text Transport Protocol ("HTTP") +which is the basis of web servers on the Internet. This allows users to +view documentation, check status information on a printer or server, +and manage their printers, classes, and jobs using their web browser.

+

CUPS provides a complete IPP/1.1 based printing system that provides +Basic, Digest, and local certificate authentication and user, domain, +or IP-based access control. TLS encryption will be available in future +versions of CUPS.

+

Jobs

+

Each file or set of files that is submitted for printing is called a +job. Jobs are identified by a unique number starting at 1 and are +assigned to a particular destination, usually a printer. Jobs can also +have options associated with them such as media size, number of copies, +and priority.

+

Classes

+

CUPS supports collections of printers known as classes. Jobs +sent to a class are forwarded to the first available printer in the +class.

+

Filters

+

Filters allow a user or application to print many types of files +without extra effort. Print jobs sent to a CUPS server are filtered +before sending them to a printer. Some filters convert job files to +different formats that the printer can understand. Others perform page +selection and ordering tasks.

+

CUPS provides filters for printing many types of image files, +HP-GL/2 files, PDF files, and text files. CUPS also supplies PostScript +and image file Raster Image Processor ("RIP") filters that convert +PostScript or image files into bitmaps that can be sent to a raster +printer.

+

Backends

+

Backends perform the most important task of all - they send the +filtered print data to the printer.

+

CUPS provides backends for printing over parallel, serial, and USB +ports, and over the network via the IPP, JetDirect (AppSocket), and +Line Printer Daemon ("LPD") protocols. Additional backends are +available in network service packages such as the SMB backend included +with the popular SAMBA software.

+

Backends are also used to determine the available devices. On +startup each backend is asked for a list of devices it supports, and +any information that is available. This allows the parallel backend to +tell CUPS that an EPSON Stylus Color 600 printer is attached to +parallel port 1, for example.

+

Printer Drivers

+

Printer drivers in CUPS consist of one of more filters specific to a +printer. CUPS includes sample printer drivers for Hewlett-Packard +LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color, +and Stylus Photo printers. While these drivers do not generate optimal +output for the different printer models, they do provide basic printing +and demonstrate how you can write your own printer drivers and +incorporate them into CUPS.

+

Networking

+

Printers and classes on the local system are automatically shared +with other systems on the network. This allows you to setup one system +to print to a printer and use this system as a printer server or spool +host for all of the others. Users may then select a local printer by +name or a remote printer using "name@server".

+

CUPS also provides implicit classes, which are collections of +printers and/or classes with the same name. This allows you to setup +multiple servers pointing to the same physical network printer, for +example, so that you aren't relying on a single system for printing. +Because this also works with printer classes, you can setup multiple +servers and printers and never worry about a single point of failure +unless all of the printers and servers go down!

+

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: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
MemberTypeDescription
accurate_screensint +1 = supports accurate screens
color_deviceint1 = +color device
colorspaceppd_cs_t +Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB, +PPD_CS_RGBK, PPD_CS_N
contone_onlyint1 = +printer is continuous tone only
num_emulations +

emulations		int +

ppd_emul_t *		Emulations supported by the +printer
flip_duplexint1 = +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
landscapeint +Landscape orientation, -90 or 90 degrees
lang_encodingchar * +The character used for the option strings
lang_versionchar * +The language used for the options strings (English, French, etc.)
language_levelint +PostScript language level, 1 to 3
manual_copiesint1 = +Copies are done manually
model_numberint +Driver-specific model number.
patcheschar *Patch +commands to send to the printer
manufacturerchar * +The Manufacturer attribute from the PPD file, if any
modelnamechar *The +ModelName attribute from the PPD file
nicknamechar *The +NickName attribute from the PPD file, if any
productchar *The +Product attribute from the PPD file, if any
shortnicknamechar * +The ShortNickName attribute from the PPD file, if any
throughputintNumber +of pages per minute
ttrasterizerchar * +The TruType font rasterizer (Type42)
variable_sizesint1 += 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: +

+ + + + + + + + + + + + + + +
VariableTypeDescription
cupsWidthread-only integerWidth of bitmap in +pixels
cupsHeightread-only integer Height of bitmap +in pixels
cupsMediaTyperead-write integer +Device-specific media type code
cupsBitsPerColorread-write integerNumber of +bits per color; 1, 2, 4, and 8 are currently supported
cupsBitsPerPixelread-only integer Number of +bits per pixel; 1 to 32
cupsBytesPerLineread-only integerNumber of +bytes per line of raster graphics
cupsColorOrderread-write enumThe 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 ...
    • +
+
cupsColorSpaceread-write enumThe 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)
    • +
+
cupsCompressionread-write integer +Device-specific compression type code
cupsRowCountread-write integerDevice-specific +row count value
cupsRowFeedread-write integerDevice-specific +row feed value
cupsRowStepread-write integerDevice-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

+

Common UNIX Printing System License +Agreement

+

Copyright 1997-2001 by Easy Software Products +

44141 AIRPORT VIEW DR STE 204 +

HOLLYWOOD, MARYLAND 20636-3111 USA +

+

Voice: +1.301.373.9600 +

Email: cups-info@cups.org +

WWW: http://www.cups.org

+

Introduction

+

The Common UNIX Printing SystemTM, ("CUPSTM"), +is provided under the GNU General Public License ("GPL") and GNU +Library General Public License ("LGPL"), Version 2. A copy of these +licenses follow this introduction.

+

The GNU LGPL applies to the CUPS API library, located in the "cups" +subdirectory of the CUPS source distribution and in the +"/usr/include/cups" directory and "libcups.a", "libcups.sl", or +"libcups.so" files in the binary distributions.

+

The GNU GPL applies to the remainder of the CUPS distribution, +including the "pstoraster" filter which is based upon GNU Ghostscript +5.50 and the "pdftops" filter which is based upon Xpdf 0.90.

+

For those not familiar with the GNU GPL, the license basically +allows you to:

+ +

What this license does not allow you to do is make changes or +add features to CUPS and then sell a binary distribution without source +code. You must provide source for any new drivers, changes, or +additions to the software, and all code must be provided under the GPL +or LGPL as appropriate.

+

The GNU LGPL relaxes the "link-to" restriction, allowing you to +develop applications that use the CUPS API library under other licenses +and/or conditions as appropriate for your application.

+

Trademarks

+

Easy Software Products has trademarked the Common UNIX Printing +System, CUPS, and CUPS logo. These names and logos may be used freely +in any direct port or binary distribution of CUPS. To use them in +derivative products, please contract Easy Software Products for written +permission. Our intention is to protect the value of these trademarks +and ensure that any derivative product meets the same high-quality +standards as the original.

+

Binary Distribution Rights

+

Easy Software Products also sells rights to the CUPS source code +under a binary distribution license for vendors that are unable to +release source code for their drivers, additions, and modifications to +CUPS under the GNU GPL and LGPL. For information please contact us at +the address shown above.

+

The Common UNIX Printing System provides a "pstoraster" filter that +utilizes the GNU GhostScript 5.50 core to convert PostScript files into +a stream of raster images. For binary distribution licensing of this +software, please contact:

Miles Jones +

Director of Marketing +

Artifex Software Inc. +

454 Las Gallinas Ave., Suite 108 +

San Rafael, CA 94903 USA +

Voice: +1.415.492.9861 +

Fax: +1.415.492.9862 +

EMail: info@arsoft.com
+

+

The "pdftops" filter is based on the Xpdf 0.90 software. For binary +distribution licensing of this software, please contact:

+ Derek B. Noonburg +

Email: derekn@foolabs.com +

WWW: +http://www.foolabs.com/xpdf/

+

Support

+

Easy Software Products sells software support for CUPS as well as a +commercial printing product based on CUPS called ESP Print Pro. You can +find out more at our web site:

+ + + + +

GNU GENERAL PUBLIC LICENSE

+

Version 2, June 1991

+
+Copyright 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+Everyone is permitted to copy and distribute verbatim
+copies of this license document, but changing it is not allowed.
+
+
+
+
+

Preamble

+

The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too.

+

When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things.

+

To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it.

+

For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights.

+

We protect your rights with two steps: (1) copyright the software, +and (2) offer you this license which gives you legal permission to +copy, distribute and/or modify the software.

+

Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, +we want its recipients to know that what they have is not the original, +so that any problems introduced by others will not reflect on the +original authors' reputations.

+

Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all.

+

The precise terms and conditions for copying, distribution and +modification follow.

+

GNU GENERAL PUBLIC LICENSE +

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +MODIFICATION

+
    +
  1. This License applies to any program or other work which contains a +notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you".
    2. +

    Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the Program +(independent of having been made by running the Program). Whether that +is true depends on what the Program does.

    +
  2. You may copy and distribute verbatim copies of the Program's source +code as you receive it, in any medium, provided that you conspicuously +and appropriately publish on each copy an appropriate copyright notice +and disclaimer of warranty; keep intact all the notices that refer to +this License and to the absence of any warranty; and give any other +recipients of the Program a copy of this License along with the +Program.
    3. +

    You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee.

    +
  3. You may modify your copy or copies of the Program or any portion of +it, thus forming a work based on the Program, and copy and distribute +such modifications or work under the terms of Section 1 above, provided +that you also meet all of these conditions: +
      +
    1. You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change.
      2. +
    2. You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any part +thereof, to be licensed as a whole at no charge to all third parties +under the terms of this License.
      3. +
    3. if the modified program normally reads commands interactively when +run, you must cause it, when started running for such interactive use +in the most ordinary way, to print or display an announcement including +an appropriate copyright notice and a notice that there is no warranty +(or else, saying that you provide a warranty) and that users may +redistribute the program under these conditions, and telling the user +how to view a copy of this License. (Exception: if the Program itself +is interactive but does not normally print such an announcement, your +work based on the Program is not required to print an announcement.)
      4. +
    +
    4. +

    These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it.

    +

    Thus, it is not the intent of this section to claim rights or +contest your rights to work written entirely by you; rather, the intent +is to exercise the right to control the distribution of derivative or +collective works based on the Program.

    +

    In addition, mere aggregation of another work not based on the +Program with the Program (or with a work based on the Program) on a +volume of a storage or distribution medium does not bring the other +work under the scope of this License.

    +
  4. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: +
      +
    1. Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections 1 +and 2 above on a medium customarily used for software interchange; or,
      2. +
    2. Accompany it with a written offer, valid for at least three years, +to give any third party, for a charge no more than your cost of +physically performing source distribution, a complete machine-readable +copy of the corresponding source code, to be distributed under the +terms of Sections 1 and 2 above on a medium customarily used for +software interchange; or,
      3. +
    3. Accompany it with the information you received as to the offer to +distribute corresponding source code. (This alternative is allowed +only for noncommercial distribution and only if you received the +program in object code or executable form with such an offer, in accord +with Subsection b above.)
      4. +
    +
    5. +

    The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to control +compilation and installation of the executable. However, as a special +exception, the source code distributed need not include anything that +is normally distributed (in either source or binary form) with the +major components (compiler, kernel, and so on) of the operating system +on which the executable runs, unless that component itself accompanies +the executable.

    +

    If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent access +to copy the source code from the same place counts as distribution of +the source code, even though third parties are not compelled to copy +the source along with the object code.

    +
  5. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt otherwise +to copy, modify, sublicense or distribute the Program is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such parties +remain in full compliance.
    6. +
  6. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying the +Program or works based on it.
    7. +
  7. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License.
    8. +
  8. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program.
    9. +

    If any portion of this section is held invalid or unenforceable +under any particular circumstance, the balance of the section is +intended to apply and the section as a whole is intended to apply in +other circumstances.

    +

    It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice.

    +

    This section is intended to make thoroughly clear what is believed +to be a consequence of the rest of this License.

    +
  9. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License may +add an explicit geographical distribution limitation excluding those +countries, so that distribution is permitted only in or among countries +not thus excluded. In such case, this License incorporates the +limitation as if written in the body of this License.
    10. +
  10. The Free Software Foundation may publish revised and/or new +versions of the General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns.
    11. +

    Each version is given a distinguishing version number. If the +Program specifies a version number of this License which applies to it +and "any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Program does not specify a +version number of this License, you may choose any version ever +published by the Free Software Foundation.

    +
  11. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the +author to ask for permission. For software which is copyrighted by the +Free Software Foundation, write to the Free Software Foundation; we +sometimes make exceptions for this. Our decision will be guided by the +two goals of preserving the free status of all derivatives of our free +software and of promoting the sharing and reuse of software generally.
    12. +
+

NO WARRANTY

+
    +
  1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. + EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, +EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. + THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS +WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
    2. +
  2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES.
    3. +
+

END OF TERMS AND CONDITIONS

+ + + +

GNU LIBRARY GENERAL PUBLIC LICENSE

+

Version 2, June 1991

+
+Copyright (C) 1991 Free Software Foundation, Inc.
+59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the library GPL.  It is
+ numbered 2 because it goes with version 2 of the ordinary GPL.]
+
+

Preamble

+

The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users.

+

This license, the Library General Public License, applies to some +specially designated Free Software Foundation software, and to any +other libraries whose authors decide to use it. You can use it for +your libraries, too.

+

When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things.

+

To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the library, or if you modify it.

+

For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link a program with the library, you must provide +complete object files to the recipients so that they can relink them +with the library, after making changes to the library and recompiling +it. And you must show them these terms so they know their rights.

+

Our method of protecting your rights has two steps: (1) copyright +the library, and (2) offer you this license which gives you legal +permission to copy, distribute and/or modify the library.

+

Also, for each distributor's protection, we want to make certain +that everyone understands that there is no warranty for this free +library. If the library is modified by someone else and passed on, we +want its recipients to know that what they have is not the original +version, so that any problems introduced by others will not reflect on +the original authors' reputations.

+

Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that companies distributing free +software will individually obtain patent licenses, thus in effect +transforming the program into proprietary software. To prevent this, +we have made it clear that any patent must be licensed for everyone's +free use or not licensed at all.

+

Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License, which was designed for utility +programs. This license, the GNU Library General Public License, +applies to certain designated libraries. This license is quite +different from the ordinary one; be sure to read it in full, and don't +assume that anything in it is the same as in the ordinary license.

+

The reason we have a separate public license for some libraries is +that they blur the distinction we usually make between modifying or +adding to a program and simply using it. Linking a program with a +library, without changing the library, is in some sense simply using +the library, and is analogous to running a utility program or +application program. However, in a textual and legal sense, the linked +executable is a combined work, a derivative of the original library, +and the ordinary General Public License treats it as such.

+

Because of this blurred distinction, using the ordinary General +Public License for libraries did not effectively promote software +sharing, because most developers did not use the libraries. We +concluded that weaker conditions might promote sharing better.

+

However, unrestricted linking of non-free programs would deprive the +users of those programs of all benefit from the free status of the +libraries themselves. This Library General Public License is intended +to permit developers of non-free programs to use free libraries, while +preserving your freedom as a user of such programs to change the free +libraries that are incorporated in them. (We have not seen how to +achieve this as regards changes in header files, but we have achieved +it as regards changes in the actual functions of the Library.) The +hope is that this will lead to faster development of free libraries.

+

The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, while the latter only +works together with the library.

+

Note that it is possible for a library to be covered by the ordinary +General Public License rather than by this special one.

+

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

+

0. This License Agreement applies to any software +library which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Library General Public License (also called "this License"). Each +licensee is addressed as "you".

+

A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables.

+

The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".)

+

"Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control +compilation and installation of the library.

+

Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does and +what the program that uses the Library does.

+

1. You may copy and distribute verbatim copies of +the Library's complete source code as you receive it, in any medium, +provided that you conspicuously and appropriately publish on each copy +an appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the Library.

+

You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee.

+

2. You may modify your copy or copies of the +Library or any portion of it, thus forming a work based on the Library, +and copy and distribute such modifications or work under the terms of +Section 1 above, provided that you also meet all of these conditions:

+
    +
  1. The modified work must itself be a software library.
    2. +

    +
  2. You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change.
    3. +

    +
  3. You must cause the whole of the work to be licensed at no charge +to all third parties under the terms of this License.
    4. +

    +
  4. If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses the +facility, other than as an argument passed when the facility is +invoked, then you must make a good faith effort to ensure that, in the +event an application does not supply such function or table, the +facility still operates, and performs whatever part of its purpose +remains meaningful.
    5. +

    (For example, a function in a library to compute square roots has a +purpose that is entirely well-defined independent of the application. + Therefore, Subsection 2d requires that any application-supplied +function or table used by this function must be optional: if the +application does not supply it, the square root function must still +compute square roots.)

    +
+

These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it.

+

Thus, it is not the intent of this section to claim rights or +contest your rights to work written entirely by you; rather, the intent +is to exercise the right to control the distribution of derivative or +collective works based on the Library.

+

In addition, mere aggregation of another work not based on the +Library with the Library (or with a work based on the Library) on a +volume of a storage or distribution medium does not bring the other +work under the scope of this License.

+

3. You may opt to apply the terms of the ordinary +GNU General Public License instead of this License to a given copy of +the Library. To do this, you must alter all the notices that refer to +this License, so that they refer to the ordinary GNU General Public +License, version 2, instead of to this License. (If a newer version +than version 2 of the ordinary GNU General Public License has appeared, +then you can specify that version instead if you wish.) Do not make +any other change in these notices.

+

Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy.

+

This option is useful when you wish to copy part of the code of the +Library into a program that is not a library.

+

4. You may copy and distribute the Library (or a +portion or derivative of it, under Section 2) in object code or +executable form under the terms of Sections 1 and 2 above provided that +you accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections 1 +and 2 above on a medium customarily used for software interchange.

+

If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to distribute +the source code, even though third parties are not compelled to copy +the source along with the object code.

+

5. A program that contains no derivative of any +portion of the Library, but is designed to work with the Library by +being compiled or linked with it, is called a "work that uses the +Library". Such a work, in isolation, is not a derivative work of the +Library, and therefore falls outside the scope of this License.

+

However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. Section +6 states terms for distribution of such executables.

+

When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law.

+

If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.)

+

Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, whether +or not they are linked directly with the Library itself.

+

6. As an exception to the Sections above, you may +also compile or link a "work that uses the Library" with the Library to +produce a work containing portions of the Library, and distribute that +work under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications.

+

You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things:

+
    +
  1. Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that uses +the Library", as object code and/or source code, so that the user can +modify the Library and then relink to produce a modified executable +containing the modified Library. (It is understood that the user who +changes the contents of definitions files in the Library will not +necessarily be able to recompile the application to use the modified +definitions.)
    2. +

    +
  2. Accompany the work with a written offer, valid for at least three +years, to give the same user the materials specified in Subsection 6a, +above, for a charge no more than the cost of performing this +distribution.
    3. +

    +
  3. If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place.
    4. +

    +
  4. Verify that the user has already received a copy of these + materials or that you have already sent this user a copy.
    5. +
+

For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the source code distributed need not include anything that is normally +distributed (in either source or binary form) with the major components +(compiler, kernel, and so on) of the operating system on which the +executable runs, unless that component itself accompanies the +executable.

+

It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute.

+

7. You may place library facilities that are a work +based on the Library side-by-side in a single library together with +other library facilities not covered by this License, and distribute +such a combined library, provided that the separate distribution of the +work based on the Library and of the other library facilities is +otherwise permitted, and provided that you do these two things:

+
    +
  1. Accompany the combined library with a copy of the same work based +on the Library, uncombined with any other library facilities. This +must be distributed under the terms of the Sections above.
    2. +

    +
  2. Give prominent notice with the combined library of the fact that +part of it is a work based on the Library, and explaining where to +find the accompanying uncombined form of the same work.
    3. +
+

8. You may not copy, modify, sublicense, link with, +or distribute the Library except as expressly provided under this +License. Any attempt otherwise to copy, modify, sublicense, link with, +or distribute the Library is void, and will automatically terminate +your rights under this License. However, parties who have received +copies, or rights, from you under this License will not have their +licenses terminated so long as such parties remain in full compliance.

+

9. You are not required to accept this License, +since you have not signed it. However, nothing else grants you +permission to modify or distribute the Library or its derivative works. + These actions are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Library (or any work based +on the Library), you indicate your acceptance of this License to do so, +and all its terms and conditions for copying, distributing or modifying +the Library or works based on it.

+

10. Each time you redistribute the Library (or any +work based on the Library), the recipient automatically receives a +license from the original licensor to copy, distribute, link with or +modify the Library subject to these terms and conditions. You may not +impose any further restrictions on the recipients' exercise of the +rights granted herein. You are not responsible for enforcing compliance +by third parties to this License.

+

11. If, as a consequence of a court judgment or +allegation of patent infringement or for any other reason (not limited +to patent issues), conditions are imposed on you (whether by court +order, agreement or otherwise) that contradict the conditions of this +License, they do not excuse you from the conditions of this License. + If you cannot distribute so as to satisfy simultaneously your +obligations under this License and any other pertinent obligations, +then as a consequence you may not distribute the Library at all. For +example, if a patent license would not permit royalty-free +redistribution of the Library by all those who receive copies directly +or indirectly through you, then the only way you could satisfy both it +and this License would be to refrain entirely from distribution of the +Library.

+

If any portion of this section is held invalid or unenforceable +under any particular circumstance, the balance of the section is +intended to apply, and the section as a whole is intended to apply in +other circumstances.

+

It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is implemented +by public license practices. Many people have made generous +contributions to the wide range of software distributed through that +system in reliance on consistent application of that system; it is up +to the author/donor to decide if he or she is willing to distribute +software through any other system and a licensee cannot impose that +choice.

+

This section is intended to make thoroughly clear what is believed +to be a consequence of the rest of this License.

+

12. If the distribution and/or use of the Library +is restricted in certain countries either by patents or by copyrighted +interfaces, the original copyright holder who places the Library under +this License may add an explicit geographical distribution limitation +excluding those countries, so that distribution is permitted only in or +among countries not thus excluded. In such case, this License +incorporates the limitation as if written in the body of this License.

+

13. The Free Software Foundation may publish +revised and/or new versions of the Library General Public License from +time to time. Such new versions will be similar in spirit to the +present version, but may differ in detail to address new problems or +concerns.

+

Each version is given a distinguishing version number. If the +Library specifies a version number of this License which applies to it +and "any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation.

+

14. If you wish to incorporate parts of the Library +into other free programs whose distribution conditions are incompatible +with these, write to the author to ask for permission. For software +which is copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally.

+

NO WARRANTY

+

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, +THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE +OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU +ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

+

16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW +OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY +WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE +LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL +OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES.

+

END OF TERMS AND CONDITIONS

+

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.

+

Raster Structures

+

Raster Page Header

+

The raster page header consists of the PostScript page device +dictionary for the page: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MemberTypeDescription
MediaClasschar[64]The media class name
MediaColorchar[64]The media color name
MediaTypechar[64]The media type name
OutputTypechar[64]The output type name
AdvanceDistanceunsignedThe distance to +advance the media in points
AdvanceMediacups_adv_tWhen to advance the +media
Collatecups_bool_tWhether or not to produce +collated copies
CutMediacups_cut_tWhen to cut the media
Duplexcups_bool_tWhether or not to print on +both sides of the paper
HWResolutionunsigned[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
ImagingBoundingBoxunsigned[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)
InsertSheetcups_bool_tWhether or not to +insert a sheet before this page
Jogcups_jog_tWhen to jog copies of the page
LeadingEdgecups_edge_tThe leading edge of the +page
Marginsunsigned[2]The lower-lefthand margin +of the page in points
ManualFeedcups_bool_tWhether or not to +manually feed the page
MediaPositionunsignedThe input slot number to +use
MediaWeightunsignedThe weight of the output +media in grams/m2
MirrorPrintcups_bool_tWhether or not to +mirror the print
NegativePrintcups_bool_tWhether or not to +invert the print
NumCopiesunsignedThe number of copies to +produce
Orientationcups_orient_tThe orientation of +the page image
OutputFaceUpcups_bool_tWhether or not to +output the page face up
PageSizeunsigned[2]The width and height of +the page in points
Separationscups_bool_tWhether or not to +output separations
TraySwitchcups_bool_tWhether or not to +automatically switch trays for the requested media size/type
Tumblecups_bool_tWhether or not to rotate the +back side of the page
cupsWidthunsignedThe width of the page image +in pixels
cupsHeightunsignedThe height of the page +image in pixels
cupsMediaTypeunsignedThe device-specific +media type code
cupsBitsPerColorunsignedThe number of bits +per color
cupsBitsPerPixelunsignedThe number of bits +per pixel
cupsBytesPerLineunsignedThe number of bytes +per line of image data
cupsColorOrdercups_order_tThe order of color +values
cupsColorSpacecups_cspace_tThe type of color +values
cupsCompressionunsignedThe device-specific +compression code
cupsRowCountunsignedThe device-specific row +count
cupsRowFeedunsignedThe device-specific row +feed
cupsRowStepunsignedThe 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

+
+ + + + + + + +
ArgumentDescription
nameThe name of the option.
valueThe value of the option.
num_optionsNumber of options currently in the array.
optionsPointer 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

+
+ + + + +
ArgumentDescription
destPrinter or class name
jobJob 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

+
+ + + + + + +
ArgumentDescription
httpHTTP connection to server.
requestIPP request data.
resourceHTTP resource name for POST.
filenameFile 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

+
+ + + + + +
ArgumentDescription
httpHTTP connection to server.
requestIPP request data.
resourceHTTP 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

+
+ + + + +
ArgumentDescription
num_optionsNumber of options in array.
optionsPointer 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

+
+ + + +
ArgumentDescription
classesPointer 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(
+
+...
+
+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

+
+ + + + + +
ArgumentDescription
nameThe name of the option.
num_optionsThe number of options in the array.
optionsThe 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

+
+ + + +
ArgumentDescription
promptThe 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

+
+ + + +
ArgumentDescription
printerThe 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

+
+ + + +
ArgumentDescription
printersPointer 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(
+
+...
+
+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

+
+ + + +
ArgumentDescription
languageThe 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

+
+ + + +
ArgumentDescription
languageThe 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

+
+ + + +
ArgumentDescription
nameThe 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

+
+ + + + +
ArgumentDescription
languageThe language to query.
messageThe 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

+
+ + + + + + +
ArgumentDescription
ppdThe PPD file to mark.
num_optionsThe number of options in the options array.
optionsA 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

+
+ + + + + + +
ArgumentDescription
argThe string containing one or more options.
num_optionsThe number of options in the options array.
optionsA 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

+
+ + + + + + + + +
ArgumentDescription
printerThe printer or class to print to.
filenameThe file to print.
titleThe job title.
num_optionsThe number of options in the options array.
optionsA 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

+
+ + + + + + + + + +
ArgumentDescription
printerThe printer or class to print to.
num_filesThe number of files to print.
filesThe files to print.
titleThe job title.
num_optionsThe number of options in the options array.
optionsA 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

+
+ + + +
ArgumentDescription
rasThe 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

+
+ + + + +
ArgumentDescription
fdThe file descriptor to use.
modeThe 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

+
+ + + + +
ArgumentDescription
rasThe raster stream to read from.
headerA 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

+
+ + + + + +
ArgumentDescription
rasThe raster stream to read from.
pixelsThe pointer to a pixel buffer.
lengthThe 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

+
+ + + + +
ArgumentDescription
rasThe raster stream to write to.
headerA 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

+
+ + + + + +
ArgumentDescription
rasThe raster stream to write to.
pixelsThe pixel data to write.
lengthThe 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. +
  2. The ServerName directive in the client.conf + file,
    3. +
  3. The default host, "localhost".
    4. +
+

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

+
+ + + +
ArgumentDescription
cbThe 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

+
+ + + +
ArgumentDescription
serverThe 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

+
+ + + +
ArgumentDescription
userThe 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

+
+ + + + +
ArgumentDescription
filenameThe character string to hold the temporary +filename.
lengthThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
blocking0 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + + +
ArgumentDescription
hostnameThe name or IP address of the server to +connect to
portThe 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

+
+ + + + +
ArgumentDescription
outThe output string
inThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + +
ArgumentDescription
outThe output string
inThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + + +
ArgumentDescription
lineThe string to fill with a line from the HTTP +connection
lengthThe maximum length of the string
httpThe 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

+
+ + + +
ArgumentDescription
timeThe 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

+
+ + + +
ArgumentDescription
dateThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
fieldThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
formatA 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + + + +
ArgumentDescription
httpThe HTTP connection
bufferThe buffer to read into
lengthThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + + + + + + +
ArgumentDescription
uriThe URI to separate
methodThe method (scheme) of the URI
usernameThe username (and password) portion of the +URI, if any
hostThe hostname portion of the URI, if any
portThe port number for the URI, either as specified +or as default for the method/scheme
resourceThe 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

+
+ + + + + +
ArgumentDescription
httpThe HTTP connection
fieldThe HTTP field
valueThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
uriThe 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

+
+ + + +
ArgumentDescription
httpThe 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

+
+ + + + + +
ArgumentDescription
httpThe HTTP connection
bufferThe buffer to read into
lengthThe 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

+
+ + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
valueThe 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

+
+ + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
num_valuesThe number of values
valuesThe 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

+
+ + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
valueThe 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

+
+ + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
tagThe type of integer value (IPP_TAG_INTEGER or +IPP_TAG_ENUM)
nameThe name of attribute
valueThe 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

+
+ + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
tagThe type of integer value (IPP_TAG_INTEGER or +IPP_TAG_ENUM)
nameThe name of attribute
num_valuesThe number of values
valuesThe 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

+
+ + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
lowThe lower value
highThe 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

+
+ + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
num_valuesThe number of range values
lowsThe lower values
highsThe 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

+
+ + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
xresThe horizontal resolution
yresThe vertical resolution
unitsThe 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

+
+ + + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
nameThe name of attribute
num_valuesThe number of resolution values
xresThe horizontal resolutions
yresThe vertical resolutions
unitsThe 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

+
+ + + +
ArgumentDescription
ippThe 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

+
+ + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
tagThe type of string value
nameThe name of attribute
charsetThe character set for the string
valueThe 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

+
+ + + + + + + + + +
ArgumentDescription
ippThe IPP request
groupThe IPP group
tagThe type of string value
nameThe name of attribute
num_valuesThe number of strings
charsetThe character set for the strings
valuesThe 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

+
+ + + +
ArgumentDescription
dateThe 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

+
+ + + +
ArgumentDescription
ippThe 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

+
+ + + + + +
ArgumentDescription
ippThe IPP request or response
nameThe name of the attribute
tagThe 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

+
+ + + +
ArgumentDescription
ippThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
ippThe 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

+
+ + + +
ArgumentDescription
portThe 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

+
+ + + +
ArgumentDescription
timeThe 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

+
+ + + + +
ArgumentDescription
httpThe HTTP connection
ippThe 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

+
+ + + +
ArgumentDescription
ppdThe 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

+
+ + + +
ArgumentDescription
ppdThe 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

+
+ + + + + +
ArgumentDescription
ppdThe PPD file
fileThe file to write to
sectionThe 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

+
+ + + + + +
ArgumentDescription
ppdThe PPD file
fdThe file descriptor to write to
sectionThe 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

+
+ + + + +
ArgumentDescription
optionA pointer to the option
choiceThe 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

+
+ + + + +
ArgumentDescription
ppdThe PPD file
keywordThe 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

+
+ + + + +
ArgumentDescription
ppdThe PPD file
keywordThe 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

+
+ + + + + +
ArgumentDescription
ppdThe PPD file
keywordThe name of the option
choiceThe 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

+
+ + + +
ArgumentDescription
ppdThe 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

+
+ + + + + +
ArgumentDescription
ppdThe PPD file
keywordThe name of the option
choiceThe 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

+
+ + + +
ArgumentDescription
fileThe 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

+
+ + + +
ArgumentDescription
fdThe 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

+
+ + + +
ArgumentDescription
filenameThe 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

+
+ + + + +
ArgumentDescription
ppdThe PPD file
nameThe 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

+
+ + + + +
ArgumentDescription
ppdThe PPD file
nameThe 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

+
+ + + + +
ArgumentDescription
ppdThe PPD file
nameThe 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() +