Viewing file: api-ppd.html (62.13 KB) -rw-r--r-- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) |
PPD API
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
Description
Values
Name | Description |
PPD_CONFORM_RELAXED | Relax whitespace and control char
|
PPD_CONFORM_STRICT | Require strict conformance
|
Description
Custom Parameter Type
Values
Name | Description |
PPD_CUSTOM_CURVE | Curve value for f(x) = x^value
|
PPD_CUSTOM_INT | Integer number value
|
PPD_CUSTOM_INVCURVE | Curve value for f(x) = x^(1/value)
|
PPD_CUSTOM_PASSCODE | String of (hidden) numbers
|
PPD_CUSTOM_PASSWORD | String of (hidden) characters
|
PPD_CUSTOM_POINTS | Measurement value in points
|
PPD_CUSTOM_REAL | Real number value
|
PPD_CUSTOM_STRING | String of characters
|
Description
Colorspaces
Values
Name | Description |
PPD_CS_CMY | CMY colorspace
|
PPD_CS_CMYK | CMYK colorspace
|
PPD_CS_GRAY | Grayscale colorspace
|
PPD_CS_N | DeviceN colorspace
|
PPD_CS_RGB | RGB colorspace
|
PPD_CS_RGBK | RGBK (K = gray) colorspace
|
Description
Order dependency sections
Values
Name | Description |
PPD_ORDER_ANY | Option code can be anywhere in the file
|
PPD_ORDER_DOCUMENT | ... must be in the DocumentSetup section
|
PPD_ORDER_EXIT | ... must be sent prior to the document
|
PPD_ORDER_JCL | ... must be sent as a JCL command
|
PPD_ORDER_PAGE | ... must be in the PageSetup section
|
PPD_ORDER_PROLOG | ... must be in the Prolog section
|
Description
Types and structures...
Values
Name | Description |
PPD_ALLOC_ERROR | Memory allocation error
|
PPD_BAD_CUSTOM_PARAM | Bad custom parameter
|
PPD_BAD_OPEN_GROUP | Bad OpenGroup
|
PPD_BAD_OPEN_UI | Bad OpenUI/JCLOpenUI
|
PPD_BAD_ORDER_DEPENDENCY | Bad OrderDependency
|
PPD_BAD_UI_CONSTRAINTS | Bad UIConstraints
|
PPD_FILE_OPEN_ERROR | Unable to open PPD file
|
PPD_ILLEGAL_CHARACTER | Illegal control character
|
PPD_ILLEGAL_MAIN_KEYWORD | Illegal main keyword string
|
PPD_ILLEGAL_OPTION_KEYWORD | Illegal option keyword string
|
PPD_ILLEGAL_TRANSLATION | Illegal translation string
|
PPD_ILLEGAL_WHITESPACE | Illegal whitespace character
|
PPD_INTERNAL_ERROR | Internal error
|
PPD_LINE_TOO_LONG | Line longer than 255 chars
|
PPD_MISSING_ASTERISK | Missing asterisk in column 0
|
PPD_MISSING_PPDADOBE4 | Missing PPD-Adobe-4.x header
|
PPD_MISSING_VALUE | Missing value string
|
PPD_NESTED_OPEN_GROUP | OpenGroup without a CloseGroup first
|
PPD_NESTED_OPEN_UI | OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first
|
PPD_NULL_FILE | NULL PPD file pointer
|
PPD_OK | OK
|
Description
UI Types
Values
Name | Description |
PPD_UI_BOOLEAN | True or False option
|
PPD_UI_PICKMANY | Pick zero or more from a list
|
PPD_UI_PICKONE | Pick one from a list
|
Description
Free all memory used by the PPD file.
Syntax
void
ppdClose(
ppd_file_t * ppd);
Arguments
Name | Description |
ppd | PPD file record |
Returns
Nothing.
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
Name | Description |
ppd | PPD file data |
section | Section to collect |
choices | Pointers to choices |
Returns
Number of options marked
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
Name | Description |
ppd | PPD file data |
section | Section to collect |
min_order | Minimum OrderDependency value |
choices | Pointers to choices |
Returns
Number of options marked
Description
Check to see if there are any conflicts.
Syntax
int
ppdConflicts(
ppd_file_t * ppd);
Arguments
Name | Description |
ppd | PPD to check |
Returns
Number of conflicts found
Description
Emit code for marked options to a file.
Syntax
int
ppdEmit(
ppd_file_t * ppd,
FILE * fp,
ppd_section_t section);
Arguments
Name | Description |
ppd | PPD file record |
fp | File to write to |
section | Section to write |
Returns
0 on success, -1 on failure
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
Name | Description |
ppd | PPD file record |
fp | File to write to |
section | Section to write |
limit | Non-zero to use min_order |
min_order | Lowest OrderDependency |
Returns
0 on success, -1 on failure
Description
Emit code for marked options to a file.
Syntax
int
ppdEmitFd(
ppd_file_t * ppd,
int fd,
ppd_section_t section);
Arguments
Name | Description |
ppd | PPD file record |
fd | File to write to |
section | Section to write |
Returns
0 on success, -1 on failure
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
Name | Description |
ppd | PPD file record |
fp | File to write to |
job_id | Job ID |
user | Username |
title | Title |
Returns
0 on success, -1 on failure
Description
Emit JCLEnd code to a file.
Syntax
int
ppdEmitJCLEnd(
ppd_file_t * ppd,
FILE * fp);
Arguments
Name | Description |
ppd | PPD file record |
fp | File to write to |
Returns
0 on success, -1 on failure
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
Name | Description |
ppd | PPD file record |
section | Section to write |
min_order | Lowest OrderDependency |
Returns
String containing option code
Description
Returns the text assocated with a status.
Syntax
const char *
ppdErrorString(
ppd_status_t status);
Arguments
Name | Description |
status | PPD status |
Returns
Status string
Description
Find the first matching attribute...
Syntax
ppd_attr_t *
ppdFindAttr(
ppd_file_t * ppd,
const char * name,
const char * spec);
Arguments
Name | Description |
ppd | PPD file data |
name | Attribute name |
spec | Specifier string or NULL |
Returns
Attribute or NULL if not found
Description
Return a pointer to an option choice.
Syntax
ppd_choice_t *
ppdFindChoice(
ppd_option_t * o,
const char * choice);
Arguments
Name | Description |
o | Pointer to option |
choice | Name of choice |
Returns
Choice pointer or NULL
Description
Find a custom option.
Syntax
ppd_coption_t *
ppdFindCustomOption(
ppd_file_t * ppd,
const char * keyword);
Arguments
Name | Description |
ppd | PPD file |
keyword | Custom option name |
Returns
Custom option or NULL
Description
Find a parameter for a custom option.
Syntax
ppd_cparam_t *
ppdFindCustomParam(
ppd_coption_t * opt,
const char * name);
Arguments
Name | Description |
opt | Custom option |
name | Parameter name |
Returns
Custom parameter or NULL
Description
Return the marked choice for the specified option.
Syntax
ppd_choice_t *
ppdFindMarkedChoice(
ppd_file_t * ppd,
const char * option);
Arguments
Name | Description |
ppd | PPD file |
option | Keyword/option name |
Returns
Pointer to choice or NULL
Description
Find the next matching attribute...
Syntax
ppd_attr_t *
ppdFindNextAttr(
ppd_file_t * ppd,
const char * name,
const char * spec);
Arguments
Name | Description |
ppd | PPD file data |
name | Attribute name |
spec | Specifier string or NULL |
Returns
Attribute or NULL if not found
Description
Return a pointer to the specified option.
Syntax
ppd_option_t *
ppdFindOption(
ppd_file_t * ppd,
const char * option);
Arguments
Name | Description |
ppd | PPD file data |
option | Option/Keyword name |
Returns
Pointer to option or NULL
Description
Return the first parameter for a custom option.
Syntax
ppd_cparam_t *
ppdFirstCustomParam(
ppd_coption_t * opt);
Arguments
Name | Description |
opt | Custom option |
Returns
Custom parameter or NULL
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
Name | Description |
ppd | PPD file |
Returns
First option or NULL
Description
Check to see if an option is marked...
Syntax
int
ppdIsMarked(
ppd_file_t * ppd,
const char * option,
const char * choice);
Arguments
Name | Description |
ppd | PPD file data |
option | Option/Keyword name |
choice | Choice name |
Returns
Non-zero if option is marked
Description
Return the status from the last ppdOpen*().
Syntax
ppd_status_t
ppdLastError(
int * line);
Arguments
Name | Description |
line | Line number |
Returns
Status code
Description
Localize the PPD file to the current locale.
All groups, options, and choices are localized, as are ICC profile
descriptions, printer presets, and custom option parameters. Each
localized string uses the UTF-8 character encoding.
Syntax
int
ppdLocalize(
ppd_file_t * ppd);
Arguments
Name | Description |
ppd | PPD file |
Returns
0 on success, -1 on error
Description
Get the localized version of a cupsIPPReason
attribute.
This function uses the current locale to find the corresponding reason
text or URI from the attribute value. If "scheme" is NULL or "text",
the returned value contains human-readable (UTF-8) text from the translation
string or attribute value. Otherwise the corresponding URI is returned.
If no value of the requested scheme can be found, NULL is returned.
Syntax
const char *
ppdLocalizeIPPReason(
ppd_file_t * ppd,
const char * reason,
const char * scheme,
char * buffer,
size_t bufsize);
Arguments
Name | Description |
ppd | PPD file |
reason | IPP reason keyword to look up |
scheme | URI scheme or NULL for text |
buffer | Value buffer |
bufsize | Size of value buffer |
Returns
Value or NULL if not found
Description
Mark all default options in the PPD file.
Syntax
void
ppdMarkDefaults(
ppd_file_t * ppd);
Arguments
Name | Description |
ppd | PPD file record |
Returns
Nothing.
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
Name | Description |
ppd | PPD file record |
option | Keyword |
choice | Option name |
Returns
Number of conflicts
Description
Return the next parameter for a custom option.
Syntax
ppd_cparam_t *
ppdNextCustomParam(
ppd_coption_t * opt);
Arguments
Name | Description |
opt | Custom option |
Returns
Custom parameter or NULL
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
Name | Description |
ppd | PPD file |
Returns
Next option or NULL
Description
Read a PPD file into memory.
Syntax
ppd_file_t *
ppdOpen(
FILE * fp);
Arguments
Name | Description |
fp | File to read from |
Returns
PPD file record
Description
Read a PPD file into memory.
Syntax
ppd_file_t *
ppdOpen2(
cups_file_t * fp);
Arguments
Name | Description |
fp | File to read from |
Returns
PPD file record
Description
Read a PPD file into memory.
Syntax
ppd_file_t *
ppdOpenFd(
int fd);
Arguments
Name | Description |
fd | File to read from |
Returns
PPD file record
Description
Read a PPD file into memory.
Syntax
ppd_file_t *
ppdOpenFile(
const char * filename);
Arguments
Name | Description |
filename | File to read from |
Returns
PPD file record
Description
Get the page length for the given size.
Syntax
float
ppdPageLength(
ppd_file_t * ppd,
const char * name);
Arguments
Name | Description |
ppd | PPD file |
name | Size name |
Returns
Length of page in points or 0.0
Description
Get the page size record for the given size.
Syntax
ppd_size_t *
ppdPageSize(
ppd_file_t * ppd,
const char * name);
Arguments
Name | Description |
ppd | PPD file record |
name | Size name |
Returns
Size record for page or NULL
Description
Get the page width for the given size.
Syntax
float
ppdPageWidth(
ppd_file_t * ppd,
const char * name);
Arguments
Name | Description |
ppd | PPD file record |
name | Size name |
Returns
Width of page in points or 0.0
Description
Set the conformance level for PPD files.
Syntax
void
ppdSetConformance(
ppd_conform_t c);
Arguments
Name | Description |
c | Conformance level |
Returns
Nothing.
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
Name | Description |
name[PPD_MAX_NAME] | Name of attribute (cupsXYZ)
|
spec[PPD_MAX_NAME] | Specifier string, if any
|
text[PPD_MAX_TEXT] | Human-readable text, if any
|
value | Value string
|
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
Name | Description |
choice[PPD_MAX_NAME] | Computer-readable option name
|
code | Code to send for this option
|
marked | 0 if not selected, 1 otherwise
|
option | Pointer to parent option structure
|
text[PPD_MAX_TEXT] | Human-readable option name
|
Description
Custom Option
Definition
struct ppd_coption_s
{
char keyword[PPD_MAX_NAME];
int marked;
ppd_option_t * option;
cups_array_t * params;
};
Members
Name | Description |
keyword[PPD_MAX_NAME] | Name of option that is being extended...
|
marked | Extended option is marked
|
option | Option that is being extended...
|
params | Parameters
|
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
Name | Description |
current | Current value
|
maximum | Maximum value
|
name[PPD_MAX_NAME] | Parameter name
|
order | Order (0 to N)
|
text[PPD_MAX_TEXT] | Human-readable text
|
type | Parameter type
|
Description
Emulators
Definition
struct ppd_emul_s
{
char name[PPD_MAX_NAME];
char * start;
char * stop;
};
Members
Name | Description |
name[PPD_MAX_NAME] | Emulator name
|
start | Code to switch to this emulation
|
stop | Code to stop this emulation
|
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;
cups_array_t * marked;
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
Name | Description |
accurate_screens | 1 = supports accurate screens, 0 = not
|
attrs CUPS 1.1.19 | Attributes @private@
|
color_device | 1 = color device, 0 = grayscale
|
colorspace | Default colorspace
|
consts | UI/Non-UI constraints
|
contone_only | 1 = continuous tone only, 0 = not
|
coptions CUPS 1.2 | Custom options array @private@
|
cur_attr CUPS 1.1.19 | Current attribute @private@
|
custom_margins[4] | Margins around page
|
custom_max[2] | Maximum variable page size
|
custom_min[2] | Minimum variable page size
|
emulations | Emulations and the code to invoke them
|
filters | Filter strings...
|
flip_duplex DEPRECATED | 1 = Flip page for back sides
|
fonts | Pre-loaded fonts
|
groups | UI groups
|
jcl_begin | Start JCL commands
|
jcl_end | End JCL commands
|
jcl_ps | Enter PostScript interpreter
|
landscape | -90 or 90
|
lang_encoding | Language encoding
|
lang_version | Language version (English, Spanish, etc.)
|
language_level | Language level of device
|
manual_copies | 1 = Copies done manually, 0 = hardware
|
manufacturer | Manufacturer name
|
marked CUPS 1.3 | Marked choices @private@
|
model_number | Device-specific model number
|
modelname | Model name (general)
|
nickname | Nickname (specific)
|
num_attrs CUPS 1.1.19 | Number of attributes @private@
|
num_consts | Number of UI/Non-UI constraints
|
num_emulations | Number of emulations supported
|
num_filters | Number of filters
|
num_fonts | Number of pre-loaded fonts
|
num_groups | Number of UI groups
|
num_profiles | Number of sRGB color profiles
|
num_sizes | Number of page sizes
|
options CUPS 1.2 | Option lookup array @private@
|
patches | Patch commands to be sent to printer
|
pcfilename CUPS 1.1.19 | PCFileName string
|
product | Product name (from PS RIP/interpreter)
|
profiles | sRGB color profiles
|
protocols CUPS 1.1.19 | Protocols (BCP, TBCP) string
|
shortnickname | Short version of nickname
|
sizes | Page sizes
|
sorted_attrs CUPS 1.2 | Attribute lookup array @private@
|
throughput | Pages per minute
|
ttrasterizer | Truetype rasterizer
|
variable_sizes | 1 = supports variable sizes, 0 = doesn't
|
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
Name | Description |
PPD_MAX_NAME] | Human-readable group name
|
name[PPD_MAX_NAME] CUPS 1.1.18 | Group name
|
num_options | Number of options
|
num_subgroups | Number of sub-groups
|
options | Options
|
subgroups | Sub-groups (max depth = 1)
|
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
Name | Description |
choices | Option choices
|
conflicted | 0 if no conflicts exist, 1 otherwise
|
defchoice[PPD_MAX_NAME] | Default option choice
|
keyword[PPD_MAX_NAME] | Option keyword name ("PageSize", etc.)
|
num_choices | Number of option choices
|
order | Order number
|
section | Section for command
|
text[PPD_MAX_TEXT] | Human-readable text
|
ui | Type of UI option
|
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
Name | Description |
density | Ink density to use
|
gamma | Gamma correction to use
|
matrix[3][3] | Transform matrix
|
media_type[PPD_MAX_NAME] | Media type or "-"
|
resolution[PPD_MAX_NAME] | Resolution or "-"
|
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
Name | Description |
bottom | Bottom printable margin in points
|
left | Left printable margin in points
|
length | Length of media in points
|
marked | Page size selected?
|
name[PPD_MAX_NAME] | Media size option
|
right | Right printable margin in points
|
top | Top printable margin in points
|
width | Width of media in points
|
Description
PPD Attribute Structure
Definition
typedef struct ppd_attr_s ppd_attr_t;
Description
Option choices
Definition
typedef struct ppd_choice_s ppd_choice_t;
Description
Constraints
Definition
typedef struct ppd_const_t;
Description
Custom Option
Definition
typedef struct ppd_coption_s ppd_coption_t;
Description
Custom Parameter
Definition
typedef struct ppd_cparam_s ppd_cparam_t;
Description
Custom Parameter Limit
Definition
typedef union ppd_cplimit_u ppd_cplimit_t;
Description
Custom Parameter Type
Definition
typedef enum ppd_cptype_e ppd_cptype_t;
Description
Custom Parameter Value
Definition
typedef union ppd_cpvalue_u ppd_cpvalue_t;
Description
Emulators
Definition
typedef struct ppd_emul_s ppd_emul_t;
Description
PPD File
Definition
typedef struct ppd_file_s ppd_file_t;
Description
Groups
Definition
typedef struct ppd_group_s ppd_group_t;
Description
Options
Definition
typedef struct ppd_option_s ppd_option_t;
Description
sRGB Color Profiles
Definition
typedef struct ppd_profile_s ppd_profile_t;
Description
Order dependency sections
Definition
typedef enum ppd_section_e ppd_section_t;
Description
Page Sizes
Definition
typedef struct ppd_size_s ppd_size_t;
Description
UI Types
Definition
typedef enum ppd_ui_e ppd_ui_t;
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
Name | Description |
custom_curve | Gamma value
|
custom_int | Integer value
|
custom_invcurve | Gamma value
|
custom_passcode | Passcode length
|
custom_password | Password length
|
custom_points | Measurement value
|
custom_real | Real value
|
custom_string | String length
|
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
Name | Description |
custom_curve | Gamma value
|
custom_int | Integer value
|
custom_invcurve | Gamma value
|
custom_passcode | Passcode value
|
custom_password | Password value
|
custom_points | Measurement value
|
custom_real | Real value
|
custom_string | String value
|
|