Introduction

The CUPS PPD API provides read-only access the data in PostScript Printer Description ("PPD") files. With it you can display printer options to users, mark option choices and check for conflicting choices, and output marked choices in PostScript output.

General Usage

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

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

gcc -o myprogram myprogram.c -lcups

Compatibility

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

Contents

• Enumerations
• Functions
• Structures
• Types
• Unions

Enumerations

• ppd_cptype_e  CUPS 1.2 
• ppd_cs_e
• ppd_section_e
• ppd_status_e
• ppd_ui_e

 CUPS 1.2 ppd_cptype_e

Description

Custom Parameter Type

Values

ppd_cs_e

Description

Colorspaces

Values

ppd_section_e

Description

Order dependency sections

Values

ppd_status_e

Description

Types and structures...

Values

ppd_ui_e

Description

UI Types

Values

Functions

• ppdClose()
• ppdCollect()
• ppdCollect2()  CUPS 1.2 
• ppdConflicts()
• ppdEmit()
• ppdEmitAfterOrder()  CUPS 1.2 
• ppdEmitFd()
• ppdEmitJCL()
• ppdEmitJCLEnd()  CUPS 1.2 
• ppdEmitString()  CUPS 1.2 
• ppdErrorString()  CUPS 1.1.19 
• ppdFindAttr()  CUPS 1.1.19 
• ppdFindChoice()
• ppdFindCustomOption()  CUPS 1.2 
• ppdFindCustomParam()  CUPS 1.2 
• ppdFindMarkedChoice()
• ppdFindNextAttr()  CUPS 1.1.19 
• ppdFindOption()
• ppdFirstCustomParam()  CUPS 1.2 
• ppdFirstOption()  CUPS 1.2 
• ppdIsMarked()
• ppdLastError()  CUPS 1.1.19 
• ppdLocalize()  CUPS 1.2 
• ppdMarkDefaults()
• ppdMarkOption()
• ppdNextCustomParam()  CUPS 1.2 
• ppdNextOption()  CUPS 1.2 
• ppdOpen()
• ppdOpen2()  CUPS 1.2 
• ppdOpenFd()
• ppdOpenFile()
• ppdPageLength()
• ppdPageSize()
• ppdPageWidth()
• ppdSetConformance()  CUPS 1.1.20 

ppdClose()

Description

Free all memory used by the PPD file.

Syntax

void
ppdClose(
    ppd_file_t * ppd);

Arguments

Returns

Nothing.

ppdCollect()

Description

Collect all marked options that reside in the specified section.

Syntax

int
ppdCollect(
    ppd_file_t * ppd,
    ppd_section_t section,
    ppd_choice_t *** choices);

Arguments

Returns

Number of options marked

 CUPS 1.2 ppdCollect2()

Description

Collect all marked options that reside in the specified section and minimum order.

Syntax

int
ppdCollect2(
    ppd_file_t * ppd,
    ppd_section_t section,
    float min_order,
    ppd_choice_t *** choices);

Arguments

Returns

Number of options marked

ppdConflicts()

Description

Check to see if there are any conflicts.

Syntax

int
ppdConflicts(
    ppd_file_t * ppd);

Arguments

Returns

Number of conflicts found

ppdEmit()

Description

Emit code for marked options to a file.

Syntax

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

Arguments

Returns

0 on success, -1 on failure

 CUPS 1.2 ppdEmitAfterOrder()

Description

Emit a subset of the code for marked options to a file. When "limit" is non-zero, this function only emits options whose OrderDependency value is greater than or equal to "min_order". When "limit" is zero, this function is identical to ppdEmit().

Syntax

int
ppdEmitAfterOrder(
    ppd_file_t * ppd,
    FILE * fp,
    ppd_section_t section,
    int limit,
    float min_order);

Arguments

Returns

0 on success, -1 on failure

ppdEmitFd()

Description

Emit code for marked options to a file.

Syntax

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

Arguments

Returns

0 on success, -1 on failure

ppdEmitJCL()

Description

Emit code for JCL options to a file.

Syntax

int
ppdEmitJCL(
    ppd_file_t * ppd,
    FILE * fp,
    int job_id,
    const char * user,
    const char * title);

Arguments

Returns

0 on success, -1 on failure

 CUPS 1.2 ppdEmitJCLEnd()

Description

Emit JCLEnd code to a file.

Syntax

int
ppdEmitJCLEnd(
    ppd_file_t * ppd,
    FILE * fp);

Arguments

Returns

0 on success, -1 on failure

 CUPS 1.2 ppdEmitString()

Description

Get a string containing the code for marked options. When "min_order" is greater than zero, this function only includes options whose OrderDependency value is greater than or equal to "min_order". Otherwise, all options in the specified section are included in the returned string. The return string is allocated on the heap and should be freed using free() when you are done with it.

Syntax

char *
ppdEmitString(
    ppd_file_t * ppd,
    ppd_section_t section,
    float min_order);

Arguments

Returns

String containing option code

 CUPS 1.1.19 ppdErrorString()

Description

Returns the text assocated with a status.

Syntax

const char *
ppdErrorString(
    ppd_status_t status);

Arguments

Returns

Status string

 CUPS 1.1.19 ppdFindAttr()

Description

Find the first matching attribute...

Syntax

ppd_attr_t *
ppdFindAttr(
    ppd_file_t * ppd,
    const char * name,
    const char * spec);

Arguments

Returns

Attribute or NULL if not found

ppdFindChoice()

Description

Return a pointer to an option choice.

Syntax

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

Arguments

Returns

Choice pointer or NULL

 CUPS 1.2 ppdFindCustomOption()

Description

Find a custom option.

Syntax

ppd_coption_t *
ppdFindCustomOption(
    ppd_file_t * ppd,
    const char * keyword);

Arguments

Returns

Custom option or NULL

 CUPS 1.2 ppdFindCustomParam()

Description

Find a parameter for a custom option.

Syntax

ppd_cparam_t *
ppdFindCustomParam(
    ppd_coption_t * opt,
    const char * name);

Arguments

Returns

Custom parameter or NULL

ppdFindMarkedChoice()

Description

Return the marked choice for the specified option.

Syntax

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

Arguments

Returns

Pointer to choice or NULL

 CUPS 1.1.19 ppdFindNextAttr()

Description

Find the next matching attribute...

Syntax

ppd_attr_t *
ppdFindNextAttr(
    ppd_file_t * ppd,
    const char * name,
    const char * spec);

Arguments

Returns

Attribute or NULL if not found

ppdFindOption()

Description

Return a pointer to the specified option.

Syntax

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

Arguments

Returns

Pointer to option or NULL

 CUPS 1.2 ppdFirstCustomParam()

Description

Return the first parameter for a custom option.

Syntax

ppd_cparam_t *
ppdFirstCustomParam(
    ppd_coption_t * opt);

Arguments

Returns

Custom parameter or NULL

 CUPS 1.2 ppdFirstOption()

Description

Return the first option in the PPD file. Options are returned from all groups in sorted order.

Syntax

ppd_option_t *
ppdFirstOption(
    ppd_file_t * ppd);

Arguments

Returns

First option or NULL

ppdIsMarked()

Description

Check to see if an option is marked...

Syntax

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

Arguments

Returns

Non-zero if option is marked

 CUPS 1.1.19 ppdLastError()

Description

Return the status from the last ppdOpen*().

Syntax

ppd_status_t
ppdLastError(
    int * line);

Arguments

Returns

Status code

 CUPS 1.2 ppdLocalize()

Description

Localize the PPD file to the current locale.

Syntax

int
ppdLocalize(
    ppd_file_t * ppd);

Arguments

Returns

0 on success, -1 on error

ppdMarkDefaults()

Description

Mark all default options in the PPD file.

Syntax

void
ppdMarkDefaults(
    ppd_file_t * ppd);

Arguments

Returns

Nothing.

ppdMarkOption()

Description

Mark an option in a PPD file. Notes: -1 is returned if the given option would conflict with any currently selected option.

Syntax

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

Arguments

Returns

Number of conflicts

 CUPS 1.2 ppdNextCustomParam()

Description

Return the next parameter for a custom option.

Syntax

ppd_cparam_t *
ppdNextCustomParam(
    ppd_coption_t * opt);

Arguments

Returns

Custom parameter or NULL

 CUPS 1.2 ppdNextOption()

Description

Return the next option in the PPD file. Options are returned from all groups in sorted order.

Syntax

ppd_option_t *
ppdNextOption(
    ppd_file_t * ppd);

Arguments

Returns

Next option or NULL

ppdOpen()

Description

Read a PPD file into memory.

Syntax

ppd_file_t *
ppdOpen(
    FILE * fp);

Arguments

Returns

PPD file record

 CUPS 1.2 ppdOpen2()

Description

Read a PPD file into memory.

Syntax

ppd_file_t *
ppdOpen2(
    cups_file_t * fp);

Arguments

Returns

PPD file record

ppdOpenFd()

Description

Read a PPD file into memory.

Syntax

ppd_file_t *
ppdOpenFd(
    int fd);

Arguments

Returns

PPD file record

ppdOpenFile()

Description

Read a PPD file into memory.

Syntax

ppd_file_t *
ppdOpenFile(
    const char * filename);

Arguments

Returns

PPD file record

ppdPageLength()

Description

Get the page length for the given size.

Syntax

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

Arguments

Returns

Length of page in points or 0.0

ppdPageSize()

Description

Get the page size record for the given size.

Syntax

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

Arguments

Returns

Size record for page or NULL

ppdPageWidth()

Description

Get the page width for the given size.

Syntax

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

Arguments

Returns

Width of page in points or 0.0

 CUPS 1.1.20 ppdSetConformance()

Description

Set the conformance level for PPD files.

Syntax

void
ppdSetConformance(
    ppd_conform_t c);

Arguments

Returns

Nothing.

Structures

• ppd_attr_s  CUPS 1.1.19 
• ppd_choice_s
• ppd_coption_s  CUPS 1.2 
• ppd_cparam_s  CUPS 1.2 
• ppd_emul_s
• ppd_file_s
• ppd_group_s
• ppd_option_s
• ppd_profile_s
• ppd_size_s

 CUPS 1.1.19 ppd_attr_s

Description

PPD Attribute Structure

Definition

struct ppd_attr_s
{
  char name[PPD_MAX_NAME];
  char spec[PPD_MAX_NAME];
  char text[PPD_MAX_TEXT];
  char * value;
};

Members

ppd_choice_s

Description

Option choices

Definition

struct ppd_choice_s
{
  char choice[PPD_MAX_NAME];
  char * code;
  char marked;
  ppd_option_t * option;
  char text[PPD_MAX_TEXT];
};

Members

 CUPS 1.2 ppd_coption_s

Description

Custom Option

Definition

struct ppd_coption_s
{
  char keyword[PPD_MAX_NAME];
  int marked;
  ppd_option_t * option;
  cups_array_t * params;
};

Members

 CUPS 1.2 ppd_cparam_s

Description

Custom Parameter

Definition

struct ppd_cparam_s
{
  ppd_cpvalue_t current;
  ppd_cplimit_t minimum, maximum;
  char name[PPD_MAX_NAME];
  int order;
  char text[PPD_MAX_TEXT];
  ppd_cptype_t type;
};

Members

ppd_emul_s

Description

Emulators

Definition

struct ppd_emul_s
{
  char name[PPD_MAX_NAME];
  char * start;
  char * stop;
};

Members

ppd_file_s

Description

PPD File

Definition

struct ppd_file_s
{
  int accurate_screens;
  ppd_attr_t ** attrs;
  int color_device;
  ppd_cs_t colorspace;
  ppd_const_t * consts;
  int contone_only;
  cups_array_t * coptions;
  int cur_attr;
  float custom_margins[4];
  float custom_max[2];
  float custom_min[2];
  ppd_emul_t * emulations;
  char ** filters;
  int flip_duplex;
  char ** fonts;
  ppd_group_t * groups;
  char * jcl_begin;
  char * jcl_end;
  char * jcl_ps;
  int landscape;
  char * lang_encoding;
  char * lang_version;
  int language_level;
  int manual_copies;
  char * manufacturer;
  int model_number;
  char * modelname;
  char * nickname;
  int num_attrs;
  int num_consts;
  int num_emulations;
  int num_filters;
  int num_fonts;
  int num_groups;
  int num_profiles;
  int num_sizes;
  cups_array_t * options;
  char * patches;
  char * pcfilename;
  char * product;
  ppd_profile_t * profiles;
  char * protocols;
  char * shortnickname;
  ppd_size_t * sizes;
  cups_array_t * sorted_attrs;
  int throughput;
  char * ttrasterizer;
  int variable_sizes;
};

Members

ppd_group_s

Description

Groups

Definition

struct ppd_group_s
{
  char text[PPD_MAX_TEXT - PPD_MAX_NAME];
  char name[PPD_MAX_NAME];
  int num_options;
  int num_subgroups;
  ppd_option_t * options;
  struct ppd_group_s * subgroups;
};

Members

ppd_option_s

Description

Options

Definition

struct ppd_option_s
{
  ppd_choice_t * choices;
  char conflicted;
  char defchoice[PPD_MAX_NAME];
  char keyword[PPD_MAX_NAME];
  int num_choices;
  float order;
  ppd_section_t section;
  char text[PPD_MAX_TEXT];
  ppd_ui_t ui;
};

Members

ppd_profile_s

Description

sRGB Color Profiles

Definition

struct ppd_profile_s
{
  float density;
  float gamma;
  float matrix[3][3];
  char media_type[PPD_MAX_NAME];
  char resolution[PPD_MAX_NAME];
};

Members

ppd_size_s

Description

Page Sizes

Definition

struct ppd_size_s
{
  float bottom;
  float left;
  float length;
  int marked;
  char name[PPD_MAX_NAME];
  float right;
  float top;
  float width;
};

Members

Types

• ppd_attr_t  CUPS 1.1.19 
• ppd_choice_t
• ppd_const_t
• ppd_coption_t  CUPS 1.2 
• ppd_cparam_t  CUPS 1.2 
• ppd_cplimit_t  CUPS 1.2 
• ppd_cptype_t  CUPS 1.2 
• ppd_cpvalue_t  CUPS 1.2 
• ppd_emul_t
• ppd_file_t
• ppd_group_t
• ppd_option_t
• ppd_profile_t
• ppd_section_t
• ppd_size_t
• ppd_ui_t

 CUPS 1.1.19 ppd_attr_t

Description

PPD Attribute Structure

Definition

typedef struct ppd_attr_s ppd_attr_t;

ppd_choice_t

Description

Option choices

Definition

typedef struct ppd_choice_s ppd_choice_t;

ppd_const_t

Description

Constraints

Definition

typedef struct ppd_const_t;

 CUPS 1.2 ppd_coption_t

Description

Custom Option

Definition

typedef struct ppd_coption_s ppd_coption_t;

 CUPS 1.2 ppd_cparam_t

Description

Custom Parameter

Definition

typedef struct ppd_cparam_s ppd_cparam_t;

 CUPS 1.2 ppd_cplimit_t

Description

Custom Parameter Limit

Definition

typedef union ppd_cplimit_u ppd_cplimit_t;

 CUPS 1.2 ppd_cptype_t

Description

Custom Parameter Type

Definition

typedef enum ppd_cptype_e ppd_cptype_t;

 CUPS 1.2 ppd_cpvalue_t

Description

Custom Parameter Value

Definition

typedef union ppd_cpvalue_u ppd_cpvalue_t;

ppd_emul_t

Description

Emulators

Definition

typedef struct ppd_emul_s ppd_emul_t;

ppd_file_t

Description

PPD File

Definition

typedef struct ppd_file_s ppd_file_t;

ppd_group_t

Description

Groups

Definition

typedef struct ppd_group_s ppd_group_t;

ppd_option_t

Description

Options

Definition

typedef struct ppd_option_s ppd_option_t;

ppd_profile_t

Description

sRGB Color Profiles

Definition

typedef struct ppd_profile_s ppd_profile_t;

ppd_section_t

Description

Order dependency sections

Definition

typedef enum ppd_section_e ppd_section_t;

ppd_size_t

Description

Page Sizes

Definition

typedef struct ppd_size_s ppd_size_t;

ppd_ui_t

Description

UI Types

Definition

typedef enum ppd_ui_e ppd_ui_t;

Unions

• ppd_cplimit_u  CUPS 1.2 
• ppd_cpvalue_u  CUPS 1.2 

 CUPS 1.2 ppd_cplimit_u

Description

Custom Parameter Limit

Definition

union ppd_cplimit_u
{
  float custom_curve;
  int custom_int;
  float custom_invcurve;
  int custom_passcode;
  int custom_password;
  float custom_points;
  float custom_real;
  int custom_string;
};

Members

 CUPS 1.2 ppd_cpvalue_u

Description

Custom Parameter Value

Definition

union ppd_cpvalue_u
{
  float custom_curve;
  int custom_int;
  float custom_invcurve;
  char * custom_passcode;
  char * custom_password;
  float custom_points;
  float custom_real;
  char * custom_string;
};

Members