DRAFT - CUPS Software Programmers Manual


CUPS-SPM-1.0b1
Easy Software Products
Copyright 1997-1999, 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 - Constants B - Structures C - Functions
 

Preface

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

System Overview

The Common UNIX Printing System provides a portable printing layer for UNIX® 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 (IETF-IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD, RFC1179), Server Message Block (SMB), and AppSocket protocols are also supported with reduced functionality.

CUPS adds network printer browsing and PostScript Printer Description ("PPD")-based printing options to support real world applications under UNIX.

CUPS also includes a customized version of GNU GhostScript (currently based off GNU GhostScript 4.03) and an image file RIP that can be used to support non-PostScript printers.

 
Contents
Previous
Next

Document Overview

This software administrators manual is organized into the following sections:

  • 1 - Printing System Overview
  • 2 - The CUPS API
  • 3 - Writing Filters
  • 4 - Writing Printer Drivers
  • 5 - Writing Backends
  • A - Constants
  • B - Structures
  • C - Functions

 
Contents
Previous
Next

1 - Printing System Overview

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

 
Contents
Previous
Next

The Printing Problem

For years the printing problem has plagued UNIX®. Unlike Microsoft® Windows® or MacOS, UNIX has no standard interface or system in place for supporting printers. Among the solutions previously 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 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.

The Common UNIX Printing System, or 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.

 
Contents
Previous
Next

The Technology

CUPS is based upon an emerging Internet standard called the Internet Printing Protocol, or IPP. IPP has been embraced by dozens of printer and printer server manufacturers, and will be supported by the next Microsoft Windows operating system.

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 secure printing solution than older ones.

IPP is layered on top of the Hyper-Text Transport Protocol, or HTTP, which is the basis of web servers on the Internet. This allows the user to view documentation and status information on a printer or server using their web browser.

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

 
Contents
Previous
Next

Jobs

Each file 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.

 
Contents
Previous
Next

Classes

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

 
Contents
Previous
Next

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. Backend filters perform the most important task of all - they send the filtered print data to the printer.

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 Processors, or RIPs, that convert PostScript or image files into bitmaps that can be sent to a raster printer.

CUPS provides backends for printing over parallel and serial ports, and over the network via the JetDirect (AppSocket), Server Message Block, and Line Printer Daemon protocols.

 
Contents
Previous
Next

Printer Drivers

Printer drivers in CUPS consist of one of more filters specific to a printer. CUPS includes a sample printer driver for Hewlett-Packard LaserJet and DeskJet printers. While this driver does not generate optimal output for different printer models, it does demonstrate how you can write your own printer drivers and incorporate them into CUPS.

 
Contents
Previous
Next

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. If there is only one occurrence of a printer on a network, then that printer can be accessed using its name alone. If more than one printer exists with the same name, users must select the printer by specifying which server to use (e.g. "printer@host1" or "printer@host2".)

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 goes down!


 
Contents
Previous
Next

2 - The CUPS API

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

 
Contents
Previous
Next

The CUPS Library

Detecting the CUPS Library in Autoconf

 
Contents
Previous
Next

Basic Services

Include Files

Getting the Available Printers and Classes

Printing Files

Setting Printer Options

Cancelling Jobs

 
Contents
Previous
Next

HTTP Services

Include Files

Connecting to a Server

Setting Request Fields

Issuing a Request

Getting the Request Status

Sending Request Data

Reading Request Data

 
Contents
Previous
Next

IPP Services

Include Files

Creating an IPP Request

Adding Attributes

Sending an IPP Request

Reading an IPP Response

Finding Attributes

Looping Through Attributes

IPP Standard Operations

IPP Extension Operations

CUPS Extension Operations

 
Contents
Previous
Next

Language Services

Include Files

Getting the Default Language

Getting the Language Encoding

Getting a Language String

 
Contents
Previous
Next

MIME Services

Include Files

Loading a MIME Database

Finding a Specific MIME Type

Finding the MIME Type of a File

Filters

 
Contents
Previous
Next

PPD Services

Include Files

Loading a PPD File

Options and Groups

Finding an Option

Finding a Page Size

Marking Options

Checking for Conflicts

Sending Options


 
Contents
Previous
Next

3 - Writing Filters

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

 
Contents
Previous
Next

Overview

Security Considerations

Users and Groups

Temporary Files

Page Accounting

 
Contents
Previous
Next

Command-Line Arguments

Copy Generation

 
Contents
Previous
Next

Environment Variables

 
Contents
Previous
Next

Writing a HTML Filter


 
Contents
Previous
Next

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.

 
Contents
Previous
Next

Overview

Page Accounting

Color Management

 
Contents
Previous
Next

Raster Functions

cupsRasterOpen()

cupsRasterReadHeader()

cupsRasterReadPixels()

cupsRasterClose()

 
Contents
Previous
Next

Writing a HP-PCL Driver


 
Contents
Previous
Next

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.

 
Contents
Previous
Next

Overview

Security Considerations

Users and Groups

Temporary Files

Page Accounting

Retries

 
Contents
Previous
Next

Command-Line Arguments

Copy Generation

 
Contents
Previous
Next

Environment Variables

 
Contents
Previous
Next

Writing a Serial Port Backend


 
Contents
Previous
Next

A - Constants

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

 
Contents
Previous
Next

CUPS Constants

 
Contents
Previous
Next

HTTP Constants

 
Contents
Previous
Next

IPP Constants

 
Contents
Previous
Next

Language Constants

 
Contents
Previous
Next

MIME Constants

 
Contents
Previous
Next

PPD Constants

 
Contents
Previous
Next

Raster Constants


 
Contents
Previous
Next

B - Structures

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

 
Contents
Previous
Next


 
Contents
Previous
Next

C - Functions

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

 
Contents
Previous
Next

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 

...

/* 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()
 
Contents
Previous
Next

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 

cupsCancelJob("LaserJet", 1);

See Also

cupsLastError(), cupsPrintFile()

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

int           num_options;
cups_option_t *options;

...

cupsFreeOptions(num_options, options);

See Also

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

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

See Also

cupsGetClasses(), cupsGetPrinters()

 
Contents
Previous
Next

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 

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

...

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

See Also

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

 
Contents
Previous
Next

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 

char *password;

...

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

See Also

cupsServer(), cupsUser()

 
Contents
Previous
Next

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 

char *ppd;

...

ppd = cupsGetPPD("printer@hostname");

...

unlink(ppd);
 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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_lang_t *language;
...

language = cupsLangDefault();

...

cupsLangFree(language);

See Also

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

 
Contents
Previous
Next

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_lang_t *language;
char        *encoding;
...

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

cupsLangFree(language);

See Also

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

 
Contents
Previous
Next

cupsLangFlush()

Usage

void
cupsLangFlush(void);

Description

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

Example

#include 

...

cupsLangFlush();

See Also

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

 
Contents
Previous
Next

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_lang_t *language;
...

cupsLangFree(language);

See Also

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

 
Contents
Previous
Next

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_lang_t *language;

...

language = cupsLangGet("fr");

...

cupsLangFree(language);

See Also

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

 
Contents
Previous
Next

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_lang_t *language;
char        *s;
...

language = cupsLangGet("fr");

s = cupsLangString(language, CUPS_MSG_YES);

...

cupsLangFree(language);

See Also

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

 
Contents
Previous
Next

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 

ipp_status_t status;

...

status = cupsLastError();

See Also

cupsCancelJob(), cupsPrintFile()

 
Contents
Previous
Next

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 

int           num_options;
cups_option_t *options;
ppd_file_t    *ppd;

...

cupsMarkOptions(ppd, num_options, options);

See Also

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

int           num_options;
cups_option_t *options;

...

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

See Also

cupsCancelJob(), cupsLastError()

 
Contents
Previous
Next

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_t *ras;

...

cupsRasterClose(ras);

See Also

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

 
Contents
Previous
Next

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_t *ras;

...

ras = cupsRasterOpen(0, CUPS_RASTER_READ);

See Also

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

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 

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

 
Contents
Previous
Next

cupsServer()

Usage

const char *
cupsServer(void);

Returns

A pointer to the default server name.

Description

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

The default server is determined from the following locations:

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

Example

#include 

const char *server;

server = cupsServer();

See Also

cupsGetPassword(), cupsUser()

 
Contents
Previous
Next

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 

char filename[256];

cupsTempFile(filename, sizeof(filename));
 
Contents
Previous
Next

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 

const char *user;

user = cupsUser();

See Also

cupsGetPassword(), cupsServer()

 
Contents
Previous
Next

httpBlocking()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpCheck()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpClearFields()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpClose()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpConnect()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpDecode64()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpDelete()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpEncode64()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpError()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpFlush()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGet()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGets()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGetDateString()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGetDateTime()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGetField()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpGetLength()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpHead()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpInitialize()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpOptions()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpPost()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpPrintf()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpPut()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpRead()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpReconnect()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpSeparate()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpSetField()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpTrace()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpUpdate()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

httpWrite()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddBoolean()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddBooleans()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddDate()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddInteger()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddIntegers()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddRange()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddRanges()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddResolution()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddResolutions()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddSeparator()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddString()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippAddStrings()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippDateToTime()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippDelete()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippFindAttribute()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippLength()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippNew()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippPort()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippRead()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippTimeToDate()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ippWrite()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeAddFilter()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeAddType()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeAddTypeRule()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeDelete()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeFileType()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeFilter()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeLoad()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeMerge()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeNew()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

mimeType()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdClose()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdConflicts()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

pddEmitFd()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdEmit()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdFindChoice()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdFindMarkedChoice()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdFindOption()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdIsMarked()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdMarkDefaults()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdMarkOption()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdOpenFd()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdOpenFile()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdOpen()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdPageLength()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdPageSize()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also

 
Contents
Previous
Next

ppdPageWidth()

Usage


Arguments

ArgumentDescription

Returns

Description

Example


See Also