Base API dealing with PPD information. More...

Data Structures
struct	caps_ppd_option
	Structure to keep the information read-in from an external PPD files. More...

struct	caps_ppd_device_info
	Some printer device product specific information to be used inside the PPD. More...

struct	caps_ppd_resolution
	Definition of one supported resolution in Dots Per Inch (DPI). More...

struct	caps_ppd_media_size
	Definition of the min/max printing medium the manual feed can handle. More...

struct	caps_ppd_media_margins
	Definition to calculate the printable area on all printing media. More...

struct	caps_ppd_custom_medium
	Definition of a custom medium. More...

struct	caps_ppd_selection_entry
	Definition of one 'option' entry a PPD selection provides. More...

struct	caps_ppd_selection
	Description of an OpenUI/CloseUI PPD selection. More...

struct	caps_ppd_base
	Basic description of common features a printing device/printing driver can provide. More...

Enumerations
enum	caps_ppd_paper_types { LIBCAPS_PT_SINGLE , LIBCAPS_PT_ENDLESS }

enum	caps_ppd_paper_leading_edges { LIBCAPS_PLE_UNDEFINED = 0 , LIBCAPS_PLE_SHORT = 1 , LIBCAPS_PLE_LONG = 2 , LIBCAPS_PLE_PLUS_90_DEGREE = 4 , LIBCAPS_PLE_MINUS_90_DEGREE = 8 }

enum	caps_ppd_color_formats { LIBCAPS_CT_MONOCHROME = 1 , LIBCAPS_CT_GRAY = 2 , LIBCAPS_CT_RGB = 4 , LIBCAPS_CT_CMYK = 8 }

enum	caps_ppd_common_features { LIBCAPS_GA_DUPLEX = 1 , LIBCAPS_GA_SINGLE_TRAY = 2 , LIBCAPS_GA_MANUAL_FEED = 4 , LIBCAPS_GA_CUSTOM_MEDIA = 8 , LIBCAPS_GA_CUTTER = 16 }

enum	caps_ppd_option_type { LIBCAPS_OT_PICKONE , LIBCAPS_OT_PICKMANY , LIBCAPS_OT_BOOLEAN }
	Definition of the three possible OpenUI/CloseUI types. More...

Functions
void	caps_libppd_init (void)

struct caps_ppd_options_table *	caps_ppd_options_table_create (void)

void	caps_ppd_options_table_clean_up (struct caps_ppd_options_table *pot)

int	caps_ppd_options_table_file_read (struct caps_ppd_options_table pot, const char ppd_file_name)

struct caps_ppd_option *	caps_ppd_option_get (const struct caps_ppd_options_table pot, const char keyword)

struct caps_ppd_option *	caps_ppd_option_with_name_get (const struct caps_ppd_options_table pot, const char keyword, const char *name)

void	caps_ppd_option_add (struct caps_ppd_options_table pot, const char keyword, const char name, const char description, const char *value)

struct caps_ppd_options_table *	caps_ppd_options_table_duplicate (const struct caps_ppd_options_table *src)

const struct caps_ppd_option *	caps_ppd_options_table_base_get (const struct caps_ppd_options_table *pot)

size_t	caps_ppd_options_table_element_count_get (const struct caps_ppd_options_table *pot)

void	caps_ppd_info_generate (struct caps_ppd_options_table db, FILE ppd_file, const struct caps_ppd_device_info prod_info, const struct caps_ppd_base cpb)

int	caps_ppd_paper_format_validate (const char *paper_name)

struct caps_rect	caps_ppd_paper_format_size_get (const char *paper_name)

const char *	caps_ppd_paper_format_name_get (const struct caps_rect *size)

const char *	caps_ppd_paper_default_format_get (void)

Detailed Description

Handle PPD file's content e.g. read it or create it on the fly

Reading the "PostScript Printer Description File Format Specification" each line in a PPD file conforms to:

 *KEYWORD[ [*]NAME[/DESCRIPTION]]:[ ]VALUE *

A few examples:

 *SomeOption: "some value"
 *OpenUI *SomeKeyword/SomeDescription: SomeAction
 *OrderDependency: 10 AnySetup *SomeKeyword
 *DefaultSomeKeyword: SomeOption
 *SomeKeyword SomeOption: "some code"
 *SomeKeyword SomeOption/SomeDescription: "some code"
 *CloseUI *SomeKeyword
 *?query SomeKeyword: "some query code"

Note: 'code' is meant as some PostScript code.

Attention: This library isn't a real PPD/PostScript interpreter when reading in a PPD file content!

Enumeration Type Documentation

◆ caps_ppd_paper_types

enum caps_ppd_paper_types

Define the provided/used printing media type

Enumerator
LIBCAPS_PT_SINGLE	Individual type, e.g. single paper
LIBCAPS_PT_ENDLESS	Endless type, e.g. continuous form

◆ caps_ppd_paper_leading_edges

enum caps_ppd_paper_leading_edges

Printing media insertion direction and the printing coordinates

Short edge is leading (portrait) (LIBCAPS_PLE_SHORT): -> printing client processes in portrait mode

-------+
   P   |+-------------------+
   R   || PAPER             |
   I   ||                   | ^
   N   ||                   | |   <--- media moving direction
   T   ||                   | X
   E   ||                   | |
   R   |+-------------------+ |
-------+     <----------Y-----+

Long edge is leading (landscape) (LIBCAPS_PLE_LONG): -> printing client processes in landscape mode

-------+
       |+-----------+
       ||  PAPER    |
   P   ||           |
   R   ||           |
   I   ||           | ^
   N   ||           | |   <--- media moving direction
   T   ||           | |
   E   ||           | X
   R   ||           | |
       ||           | |
       |+-----------+ |
-------+  <------Y----+

Some coordinates will change if the printing media can be rotated when printing. In this case it depends on the landscape mode how the printing client must process its document.

Short edge is leading (LIBCAPS_PLE_SHORT): -> printing client processes in portrait mode

-------+
   P   |+-------------+
   R   || PAPER       | ^
   I   ||             | X
   N   |+-------------+ |   <--- media moving direction
   T   |   <-------Y----+
   E   |
   R   |
-------+

For this usecase various landscape variants are now possible:

Long edge is leading for a small printing media (LIBCAPS_PLE_LONG): -> printing client processes in landscape mode

-------+
   P   |+-------+
   R   || PAPER |
   I   ||       | ^
   N   ||       | |
   T   ||       | X   <--- media moving direction
   E   ||       | |
   R   |+-------+ |
-------+   <--Y---+

Long edge is leading for a small printing media (LIBCAPS_PLE_PLUS_90_DEGREE): -> printing client processes in portrait mode

-------+   <--X---+
   P   |+-------+ |
   R   || PAPER | |
   I   ||       | Y
   N   ||       | |
   T   ||       | V   <--- media moving direction
   E   ||       |
   R   |+-------+
-------+

Long edge is leading for a small printing media (LIBCAPS_PLE_MINUS_90_DEGREE): -> printing client processes in landscape mode

-------+
   P   |   +-------+
   R   |   | PAPER |
   I   | ^ |       |
   N   | | |       |   <--- media moving direction
   T   | Y |       |
   E   | | |       |
   R   | | +-------+
-------+ +---X--->

Note: Considering +90° or -90° makes no sense if the printing medium is blank. But it makes sense, if the printing medium is special (envelopes), has punch holes or is pre-marked already.

The LIBCAPS_PLE_PLUS_90_DEGREE and LIBCAPS_PLE_MINUS_90_DEGREE flags are used to create the PPD's LandscapeOrientation attribute. Since this attribute is globally only, all trays in a printing device share the same orientation. It's not possible to consider this orientation on a per tray base (which would be really useful!). So if you using more than one pre-marked printing media in different trays, all must be loaded in the same orientation.

The LIBCAPS_PLE_PLUS_90_DEGREE and LIBCAPS_PLE_MINUS_90_DEGREE flags are a run-time feature and should not be set in a static manner in the printing driver.

Todo:: Refer struct caps_rstr_page and the line directions.

Enumerator
LIBCAPS_PLE_UNDEFINED	Use the default settings LIBCAPS_PLE_SHORT instead
LIBCAPS_PLE_SHORT	Short edge is leading
LIBCAPS_PLE_LONG	Long edge is leading
LIBCAPS_PLE_PLUS_90_DEGREE	Portrait to landscape orientation, counterclock wise rotation
LIBCAPS_PLE_MINUS_90_DEGREE	Portrait to landscape orientation, clockwise rotation

◆ caps_ppd_color_formats

enum caps_ppd_color_formats

Colour formats the printer/printer driver supports

Defines the colour space(s) the printer driver can deal with. If more then one is given (to be ored) the PPD gets entries to let the user select one for a job. Thus, a user can print the same image in greyscale for testing purposes and in colour for the final print.

Note: If one of the RGB/CMYK formats are supported, the printing device gets marked as a colour printer; MONOCHROME on a monochrome printing device results into a regular print; MONOCHROME on a CMYK colour printing device results into a print where only the black ink is used; GRAY on a monochrome printing device results into a dithered print; GRAY on a CMYK colour printing device results into a really gray shaded print; RGB on a CMYK colour printing device results into a coloured print where the printing driver does the conversion to CMYK; CMYK on a CMYK colour printing device results into a coloured print and avoids the colour conversion in the printing driver

LIBCAPS_CT_MONOCHROME:

-> *ColorDevice: False
-> *DefaultColorSpace: Grey
-> *ColorModel Mono/Monochrome: "…"

LIBCAPS_CT_GRAY:

-> *ColorDevice: False
-> *DefaultColorSpace: Gray
-> *ColorModel Gray/Grayscale: "…"

LIBCAPS_CT_RGB:

-> *ColorDevice: True
-> *DefaultColorSpace: RGB
-> *ColorModel RGB/Color: "…"

LIBCAPS_CT_CMYK:

-> *ColorDevice: True
-> *DefaultColorSpace: CMYK
-> *ColorModel CMYK/CMYK: "…"

From the PPD spec about the "*DefaultColorSpace" entry:

‍"This keyword indicates the default native color space of the device. The native color space is the color space that all colors are converted into before rendering."

For the "*DefaultColorSpace" the real value for colour printing devices depends on its default_color_format setting.

Note: This enum is used to define the colour capabilities of the printer as well. In this case LIBCAPS_CT_GRAY should never be used for a monochrome printer, because I do not know any monochrome printer which is able to print grey pixel nativly. Correct me please if I'm wrong!

Enumerator
LIBCAPS_CT_MONOCHROME	Black/white, e.g. monochrome
LIBCAPS_CT_GRAY	Gray scale
LIBCAPS_CT_RGB	RGB colours
LIBCAPS_CT_CMYK	CMYK colours

◆ caps_ppd_common_features

enum caps_ppd_common_features

Some common basic features a printing device can provide

Refer for details in caps_ppd_base::common_features.

Enumerator
LIBCAPS_GA_DUPLEX	Double sided printer
LIBCAPS_GA_SINGLE_TRAY	Printer has one paper input tray only
LIBCAPS_GA_MANUAL_FEED	Capable of feeding paper manually
LIBCAPS_GA_CUSTOM_MEDIA	Deals with its own media formats.
LIBCAPS_GA_CUTTER	Printer has a cutter

◆ caps_ppd_option_type

enum caps_ppd_option_type

Used by the dynamic PPD file generator to populate a 'PPD selection'

Enumerator
LIBCAPS_OT_PICKONE	The user can pick one of the available options
LIBCAPS_OT_PICKMANY	The user can pick more than one of the available options. Never seen yet, btw...
LIBCAPS_OT_BOOLEAN	Don't know what its good for

Function Documentation

◆ caps_libppd_init()

void caps_libppd_init ( void )

Initialize the library

Note: This function can be called multiple times.

◆ caps_ppd_options_table_create()

struct caps_ppd_options_table * caps_ppd_options_table_create ( void )

Create and init a table to handle PPD options

Returns: Pointer to a new PPD table

Postcondition: The table needs to be freed with caps_ppd_options_table_clean_up() if no longer used

Note: Does not return in case of memory failure

◆ caps_ppd_options_table_clean_up()

void caps_ppd_options_table_clean_up ( struct caps_ppd_options_table * pot )

Free up the memory used by the PPD option's table

Parameters

[in,out] pot The table to free (can be NULL, gets ignored then)

Postcondition: The pot pointer is invalid after the call.

◆ caps_ppd_options_table_file_read()

int caps_ppd_options_table_file_read	(	struct caps_ppd_options_table *	pot,
		const char *	ppd_file_name
	)

Read in a whole PPD file and create an option table of its content

Parameters

[in,out]	pot	The table to add the PPD content to
[in]	ppd_file_name	The path to the file to read

Return values

0	On success
negative	errno

Note: Does not return in case of memory failure

◆ caps_ppd_option_get()

struct caps_ppd_option * caps_ppd_option_get	(	const struct caps_ppd_options_table *	pot,
		const char *	keyword
	)

Get an option from the PPD table

Parameters

[in]	pot	The table to search in
[in]	keyword	Option's keyword

Return values

option	Valid pointer to the option if found
NULL	If the option wasn't found

The keyword must match exactly to be found.

◆ caps_ppd_option_with_name_get()

struct caps_ppd_option * caps_ppd_option_with_name_get	(	const struct caps_ppd_options_table *	pot,
		const char *	keyword,
		const char *	name
	)

Get a named option from the PPD table

Parameters

[in]	pot	The table to search in
[in]	keyword	option's keyword
[in]	name	option's name (can be NULL)

Return values

option	Valid pointer to the option if found
NULL	If the option wasn't found (`keyword` and/or `name`)

The keyword and the name (if given) must match exactly to be found.

◆ caps_ppd_option_add()

void caps_ppd_option_add	(	struct caps_ppd_options_table *	pot,
		const char *	keyword,
		const char *	name,
		const char *	description,
		const char *	value
	)

Add a new option entry into the PPD option table

Parameters

[in,out]	pot	The table to add the option to
[in]	keyword	Option's keyword
[in]	name	Option's name (can be NULL)
[in]	description	Option's description (can be NULL)
[in]	value	Option's value

Note: Stores a copy of all strings internally; Does not return in case of memory failure

◆ caps_ppd_options_table_duplicate()

struct caps_ppd_options_table * caps_ppd_options_table_duplicate ( const struct caps_ppd_options_table * src )

Create a copy of an existing PPD option table

Parameters

[in] src Source PPD option table

Returns: a copy of the src table

Since the entries contain pointer to external objects, this is a so called "deep copy".

Note: Does not return in case of memory failure

◆ caps_ppd_options_table_base_get()

const struct caps_ppd_option * caps_ppd_options_table_base_get ( const struct caps_ppd_options_table * pot )

Retrieve the option table array base

Parameters

[in] pot The PPD option table to get the array base from

Return values

table	Base address of the managed table
NULL	If the table is uninitialized and thus, empty.

Note: Whenever an option was added to the PPD option table the base pointer can be changed and must again be retrieved by this function

◆ caps_ppd_options_table_element_count_get()

size_t caps_ppd_options_table_element_count_get ( const struct caps_ppd_options_table * pot )

Retrieve the option table array size (e.g. element count)

Parameters

[in] pot The PPD option table to get the array element count from

Return values

number	Elements count
0	If the array is empty.

◆ caps_ppd_info_generate()

void caps_ppd_info_generate	(	struct caps_ppd_options_table *	db,
		FILE *	ppd_file,
		const struct caps_ppd_device_info *	prod_info,
		const struct caps_ppd_base *	cpb
	)

Create a "Postscript Printer Description" (aka. PPD) file on demand and an option table (a subset of the PPD file)

Parameters

[in,out]	db	The option table to fill (must already be allocated with caps_ppd_options_table_create())
[in,out]	ppd_file	FILE handle to fill with the PPD content
[in]	prod_info	Printer device product information. Can be NULL
[in]	cpb	Printing device capabilities description

If prod_info is NULL, some information like the product name or manufacturer is unknown and cannot be added to the generated PPD file. Maybe some printer management dialogues will then show some useless information.

Note: Does not return on failure (memory or I/O).

◆ caps_ppd_paper_format_validate()

int caps_ppd_paper_format_validate ( const char * paper_name )

Check if the given medium format name is a valid one (e.g. "known")

Parameters

[in] paper_name Name of the paper to check

Return values

0	If paper name is valid/known
-EINVAL	Format name is invalid

This is a wrapper around libpaper and for convinience.

◆ caps_ppd_paper_format_size_get()

struct caps_rect caps_ppd_paper_format_size_get ( const char * paper_name )

Get dimension information about a specific medium format name

Parameters

[in] paper_name Name of the paper (refer "paperconf -a" for valid names)

Returns: The size information for paper_name in portrait orientation

If the paper isn't known, the returned size will be 0.0 in both axis.

This is a wrapper around libpaper and for convinience.

◆ caps_ppd_paper_format_name_get()

const char * caps_ppd_paper_format_name_get ( const struct caps_rect * size )

Get the medium format name for a specific size

Parameters

[in] size The size information (in [pts])

Returns: The name of a well known format or 'custom'

Returns the best matching format name like a4 or letter for the specific size. This is a convenience function and a wrapper around libpaper and the returned name is more or less guessed.

If it returns "custom", nobody has a clue what kind of format it is. Be prepared!

◆ caps_ppd_paper_default_format_get()

const char * caps_ppd_paper_default_format_get ( void )

Get the default name of the systems medium format name

Returns: Pointer to a format name (refer "paperconf -a" for valid names)

This is a wrapper around libpaper and for convinience.

Note: This call isn't thread save, since it re-uses a single buffer on each call

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ caps_ppd_paper_types

◆ caps_ppd_paper_leading_edges

◆ caps_ppd_color_formats

◆ caps_ppd_common_features

◆ caps_ppd_option_type

Function Documentation

◆ caps_libppd_init()

◆ caps_ppd_options_table_create()

◆ caps_ppd_options_table_clean_up()

◆ caps_ppd_options_table_file_read()

◆ caps_ppd_option_get()

◆ caps_ppd_option_with_name_get()

◆ caps_ppd_option_add()

◆ caps_ppd_options_table_duplicate()

◆ caps_ppd_options_table_base_get()

◆ caps_ppd_options_table_element_count_get()

◆ caps_ppd_info_generate()

◆ caps_ppd_paper_format_validate()

◆ caps_ppd_paper_format_size_get()

◆ caps_ppd_paper_format_name_get()

◆ caps_ppd_paper_default_format_get()