]> git.ipfire.org Git - thirdparty/cups.git/blob - cups/ppd.h
Update documentation and dependencies for 1.5b1.
[thirdparty/cups.git] / cups / ppd.h
1 /*
2 * "$Id$"
3 *
4 * PostScript Printer Description definitions for CUPS.
5 *
6 * Copyright 2007-2011 by Apple Inc.
7 * Copyright 1997-2007 by Easy Software Products, all rights reserved.
8 *
9 * These coded instructions, statements, and computer programs are the
10 * property of Apple Inc. and are protected by Federal copyright
11 * law. Distribution and use rights are outlined in the file "LICENSE.txt"
12 * which should have been included with this file. If this file is
13 * file is missing or damaged, see the license at "http://www.cups.org/".
14 *
15 * PostScript is a trademark of Adobe Systems, Inc.
16 *
17 * This code and any derivative of it may be used and distributed
18 * freely under the terms of the GNU General Public License when
19 * used with GNU Ghostscript or its derivatives. Use of the code
20 * (or any derivative of it) with software other than GNU
21 * GhostScript (or its derivatives) is governed by the CUPS license
22 * agreement.
23 *
24 * This file is subject to the Apple OS-Developed Software exception.
25 */
26
27 #ifndef _CUPS_PPD_H_
28 # define _CUPS_PPD_H_
29
30 /*
31 * Include necessary headers...
32 */
33
34 # include <stdio.h>
35 # include "cups.h"
36 # include "array.h"
37 # include "file.h"
38
39
40 /*
41 * C++ magic...
42 */
43
44 # ifdef __cplusplus
45 extern "C" {
46 # endif /* __cplusplus */
47
48
49 /*
50 * PPD version...
51 */
52
53 # define PPD_VERSION 4.3 /* Kept in sync with Adobe version number */
54
55
56 /*
57 * PPD size limits (defined in Adobe spec)
58 */
59
60 # define PPD_MAX_NAME 41 /* Maximum size of name + 1 for nul */
61 # define PPD_MAX_TEXT 81 /* Maximum size of text + 1 for nul */
62 # define PPD_MAX_LINE 256 /* Maximum size of line + 1 for nul */
63
64
65 /*
66 * Types and structures...
67 */
68
69 typedef enum ppd_ui_e /**** UI Types ****/
70 {
71 PPD_UI_BOOLEAN, /* True or False option */
72 PPD_UI_PICKONE, /* Pick one from a list */
73 PPD_UI_PICKMANY /* Pick zero or more from a list */
74 } ppd_ui_t;
75
76 typedef enum ppd_section_e /**** Order dependency sections ****/
77 {
78 PPD_ORDER_ANY, /* Option code can be anywhere in the file */
79 PPD_ORDER_DOCUMENT, /* ... must be in the DocumentSetup section */
80 PPD_ORDER_EXIT, /* ... must be sent prior to the document */
81 PPD_ORDER_JCL, /* ... must be sent as a JCL command */
82 PPD_ORDER_PAGE, /* ... must be in the PageSetup section */
83 PPD_ORDER_PROLOG /* ... must be in the Prolog section */
84 } ppd_section_t;
85
86 typedef enum ppd_cs_e /**** Colorspaces ****/
87 {
88 PPD_CS_CMYK = -4, /* CMYK colorspace */
89 PPD_CS_CMY, /* CMY colorspace */
90 PPD_CS_GRAY = 1, /* Grayscale colorspace */
91 PPD_CS_RGB = 3, /* RGB colorspace */
92 PPD_CS_RGBK, /* RGBK (K = gray) colorspace */
93 PPD_CS_N /* DeviceN colorspace */
94 } ppd_cs_t;
95
96 typedef enum ppd_status_e /**** Status Codes @since CUPS 1.1.19/Mac OS X 10.3@ ****/
97 {
98 PPD_OK = 0, /* OK */
99 PPD_FILE_OPEN_ERROR, /* Unable to open PPD file */
100 PPD_NULL_FILE, /* NULL PPD file pointer */
101 PPD_ALLOC_ERROR, /* Memory allocation error */
102 PPD_MISSING_PPDADOBE4, /* Missing PPD-Adobe-4.x header */
103 PPD_MISSING_VALUE, /* Missing value string */
104 PPD_INTERNAL_ERROR, /* Internal error */
105 PPD_BAD_OPEN_GROUP, /* Bad OpenGroup */
106 PPD_NESTED_OPEN_GROUP, /* OpenGroup without a CloseGroup first */
107 PPD_BAD_OPEN_UI, /* Bad OpenUI/JCLOpenUI */
108 PPD_NESTED_OPEN_UI, /* OpenUI/JCLOpenUI without a CloseUI/JCLCloseUI first */
109 PPD_BAD_ORDER_DEPENDENCY, /* Bad OrderDependency */
110 PPD_BAD_UI_CONSTRAINTS, /* Bad UIConstraints */
111 PPD_MISSING_ASTERISK, /* Missing asterisk in column 0 */
112 PPD_LINE_TOO_LONG, /* Line longer than 255 chars */
113 PPD_ILLEGAL_CHARACTER, /* Illegal control character */
114 PPD_ILLEGAL_MAIN_KEYWORD, /* Illegal main keyword string */
115 PPD_ILLEGAL_OPTION_KEYWORD, /* Illegal option keyword string */
116 PPD_ILLEGAL_TRANSLATION, /* Illegal translation string */
117 PPD_ILLEGAL_WHITESPACE, /* Illegal whitespace character */
118 PPD_BAD_CUSTOM_PARAM, /* Bad custom parameter */
119 PPD_MISSING_OPTION_KEYWORD, /* Missing option keyword */
120 PPD_BAD_VALUE, /* Bad value string */
121 PPD_MISSING_CLOSE_GROUP, /* Missing CloseGroup */
122 PPD_MAX_STATUS /* @private@ */
123 } ppd_status_t;
124
125 enum ppd_conform_e /**** Conformance Levels @since CUPS 1.1.19/Mac OS X 10.3@ ****/
126 {
127 PPD_CONFORM_RELAXED, /* Relax whitespace and control char */
128 PPD_CONFORM_STRICT /* Require strict conformance */
129 };
130
131 typedef enum ppd_conform_e ppd_conform_t;
132 /**** Conformance Levels @since CUPS 1.1.19/Mac OS X 10.3@ ****/
133
134 typedef struct ppd_attr_s /**** PPD Attribute Structure @since CUPS 1.1.19/Mac OS X 10.3@ ****/
135 {
136 char name[PPD_MAX_NAME]; /* Name of attribute (cupsXYZ) */
137 char spec[PPD_MAX_NAME]; /* Specifier string, if any */
138 char text[PPD_MAX_TEXT]; /* Human-readable text, if any */
139 char *value; /* Value string */
140 } ppd_attr_t;
141
142 typedef struct ppd_option_s ppd_option_t;
143 /**** Options ****/
144
145 typedef struct ppd_choice_s /**** Option choices ****/
146 {
147 char marked; /* 0 if not selected, 1 otherwise */
148 char choice[PPD_MAX_NAME]; /* Computer-readable option name */
149 char text[PPD_MAX_TEXT]; /* Human-readable option name */
150 char *code; /* Code to send for this option */
151 ppd_option_t *option; /* Pointer to parent option structure */
152 } ppd_choice_t;
153
154 struct ppd_option_s /**** Options ****/
155 {
156 char conflicted; /* 0 if no conflicts exist, 1 otherwise */
157 char keyword[PPD_MAX_NAME]; /* Option keyword name ("PageSize", etc.) */
158 char defchoice[PPD_MAX_NAME];/* Default option choice */
159 char text[PPD_MAX_TEXT]; /* Human-readable text */
160 ppd_ui_t ui; /* Type of UI option */
161 ppd_section_t section; /* Section for command */
162 float order; /* Order number */
163 int num_choices; /* Number of option choices */
164 ppd_choice_t *choices; /* Option choices */
165 };
166
167 typedef struct ppd_group_s /**** Groups ****/
168 {
169 /**** Group text strings are limited to 39 chars + nul in order to
170 **** preserve binary compatibility and allow applications to get
171 **** the group's keyword name.
172 ****/
173 char text[PPD_MAX_TEXT - PPD_MAX_NAME];
174 /* Human-readable group name */
175 char name[PPD_MAX_NAME]; /* Group name @since CUPS 1.1.18/Mac OS X 10.3@ */
176 int num_options; /* Number of options */
177 ppd_option_t *options; /* Options */
178 int num_subgroups; /* Number of sub-groups */
179 struct ppd_group_s *subgroups; /* Sub-groups (max depth = 1) */
180 } ppd_group_t;
181
182 typedef struct ppd_const_s /**** Constraints ****/
183 {
184 char option1[PPD_MAX_NAME]; /* First keyword */
185 char choice1[PPD_MAX_NAME]; /* First option/choice (blank for all) */
186 char option2[PPD_MAX_NAME]; /* Second keyword */
187 char choice2[PPD_MAX_NAME]; /* Second option/choice (blank for all) */
188 } ppd_const_t;
189
190 typedef struct ppd_size_s /**** Page Sizes ****/
191 {
192 int marked; /* Page size selected? */
193 char name[PPD_MAX_NAME]; /* Media size option */
194 float width; /* Width of media in points */
195 float length; /* Length of media in points */
196 float left; /* Left printable margin in points */
197 float bottom; /* Bottom printable margin in points */
198 float right; /* Right printable margin in points */
199 float top; /* Top printable margin in points */
200 } ppd_size_t;
201
202 typedef struct ppd_emul_s /**** Emulators ****/
203 {
204 char name[PPD_MAX_NAME]; /* Emulator name */
205 char *start; /* Code to switch to this emulation */
206 char *stop; /* Code to stop this emulation */
207 } ppd_emul_t;
208
209 typedef struct ppd_profile_s /**** sRGB Color Profiles ****/
210 {
211 char resolution[PPD_MAX_NAME];
212 /* Resolution or "-" */
213 char media_type[PPD_MAX_NAME];
214 /* Media type or "-" */
215 float density; /* Ink density to use */
216 float gamma; /* Gamma correction to use */
217 float matrix[3][3]; /* Transform matrix */
218 } ppd_profile_t;
219
220 /**** New in CUPS 1.2/Mac OS X 10.5 ****/
221 typedef enum ppd_cptype_e /**** Custom Parameter Type @since CUPS 1.2/Mac OS X 10.5@ ****/
222 {
223 PPD_CUSTOM_CURVE, /* Curve value for f(x) = x^value */
224 PPD_CUSTOM_INT, /* Integer number value */
225 PPD_CUSTOM_INVCURVE, /* Curve value for f(x) = x^(1/value) */
226 PPD_CUSTOM_PASSCODE, /* String of (hidden) numbers */
227 PPD_CUSTOM_PASSWORD, /* String of (hidden) characters */
228 PPD_CUSTOM_POINTS, /* Measurement value in points */
229 PPD_CUSTOM_REAL, /* Real number value */
230 PPD_CUSTOM_STRING /* String of characters */
231 } ppd_cptype_t;
232
233 typedef union ppd_cplimit_u /**** Custom Parameter Limit @since CUPS 1.2/Mac OS X 10.5@ ****/
234 {
235 float custom_curve; /* Gamma value */
236 int custom_int; /* Integer value */
237 float custom_invcurve; /* Gamma value */
238 int custom_passcode; /* Passcode length */
239 int custom_password; /* Password length */
240 float custom_points; /* Measurement value */
241 float custom_real; /* Real value */
242 int custom_string; /* String length */
243 } ppd_cplimit_t;
244
245 typedef union ppd_cpvalue_u /**** Custom Parameter Value @since CUPS 1.2/Mac OS X 10.5@ ****/
246 {
247 float custom_curve; /* Gamma value */
248 int custom_int; /* Integer value */
249 float custom_invcurve; /* Gamma value */
250 char *custom_passcode; /* Passcode value */
251 char *custom_password; /* Password value */
252 float custom_points; /* Measurement value */
253 float custom_real; /* Real value */
254 char *custom_string; /* String value */
255 } ppd_cpvalue_t;
256
257 typedef struct ppd_cparam_s /**** Custom Parameter @since CUPS 1.2/Mac OS X 10.5@ ****/
258 {
259 char name[PPD_MAX_NAME]; /* Parameter name */
260 char text[PPD_MAX_TEXT]; /* Human-readable text */
261 int order; /* Order (0 to N) */
262 ppd_cptype_t type; /* Parameter type */
263 ppd_cplimit_t minimum, /* Minimum value */
264 maximum; /* Maximum value */
265 ppd_cpvalue_t current; /* Current value */
266 } ppd_cparam_t;
267
268 typedef struct ppd_coption_s /**** Custom Option @since CUPS 1.2/Mac OS X 10.5@ ****/
269 {
270 char keyword[PPD_MAX_NAME]; /* Name of option that is being extended... */
271 ppd_option_t *option; /* Option that is being extended... */
272 int marked; /* Extended option is marked */
273 cups_array_t *params; /* Parameters */
274 } ppd_coption_t;
275
276 typedef struct _ppd_cache_s _ppd_cache_t;
277 /**** PPD cache and mapping data @since CUPS 1.5/Mac OS X 10.7@ @private@ ****/
278
279 typedef struct ppd_file_s /**** PPD File ****/
280 {
281 int language_level; /* Language level of device */
282 int color_device; /* 1 = color device, 0 = grayscale */
283 int variable_sizes; /* 1 = supports variable sizes, 0 = doesn't */
284 int accurate_screens; /* 1 = supports accurate screens, 0 = not */
285 int contone_only; /* 1 = continuous tone only, 0 = not */
286 int landscape; /* -90 or 90 */
287 int model_number; /* Device-specific model number */
288 int manual_copies; /* 1 = Copies done manually, 0 = hardware */
289 int throughput; /* Pages per minute */
290 ppd_cs_t colorspace; /* Default colorspace */
291 char *patches; /* Patch commands to be sent to printer */
292 int num_emulations; /* Number of emulations supported */
293 ppd_emul_t *emulations; /* Emulations and the code to invoke them */
294 char *jcl_begin; /* Start JCL commands */
295 char *jcl_ps; /* Enter PostScript interpreter */
296 char *jcl_end; /* End JCL commands */
297 char *lang_encoding; /* Language encoding */
298 char *lang_version; /* Language version (English, Spanish, etc.) */
299 char *modelname; /* Model name (general) */
300 char *ttrasterizer; /* Truetype rasterizer */
301 char *manufacturer; /* Manufacturer name */
302 char *product; /* Product name (from PS RIP/interpreter) */
303 char *nickname; /* Nickname (specific) */
304 char *shortnickname; /* Short version of nickname */
305 int num_groups; /* Number of UI groups */
306 ppd_group_t *groups; /* UI groups */
307 int num_sizes; /* Number of page sizes */
308 ppd_size_t *sizes; /* Page sizes */
309 float custom_min[2]; /* Minimum variable page size */
310 float custom_max[2]; /* Maximum variable page size */
311 float custom_margins[4]; /* Margins around page */
312 int num_consts; /* Number of UI/Non-UI constraints */
313 ppd_const_t *consts; /* UI/Non-UI constraints */
314 int num_fonts; /* Number of pre-loaded fonts */
315 char **fonts; /* Pre-loaded fonts */
316 int num_profiles; /* Number of sRGB color profiles @deprecated@ */
317 ppd_profile_t *profiles; /* sRGB color profiles @deprecated@ */
318 int num_filters; /* Number of filters */
319 char **filters; /* Filter strings... */
320
321 /**** New in CUPS 1.1 ****/
322 int flip_duplex; /* 1 = Flip page for back sides @deprecated@ */
323
324 /**** New in CUPS 1.1.19 ****/
325 char *protocols; /* Protocols (BCP, TBCP) string @since CUPS 1.1.19/Mac OS X 10.3@ */
326 char *pcfilename; /* PCFileName string @since CUPS 1.1.19/Mac OS X 10.3@ */
327 int num_attrs; /* Number of attributes @since CUPS 1.1.19/Mac OS X 10.3@ @private@ */
328 int cur_attr; /* Current attribute @since CUPS 1.1.19/Mac OS X 10.3@ @private@ */
329 ppd_attr_t **attrs; /* Attributes @since CUPS 1.1.19/Mac OS X 10.3@ @private@ */
330
331 /**** New in CUPS 1.2/Mac OS X 10.5 ****/
332 cups_array_t *sorted_attrs; /* Attribute lookup array @since CUPS 1.2/Mac OS X 10.5@ @private@ */
333 cups_array_t *options; /* Option lookup array @since CUPS 1.2/Mac OS X 10.5@ @private@ */
334 cups_array_t *coptions; /* Custom options array @since CUPS 1.2/Mac OS X 10.5@ @private@ */
335
336 /**** New in CUPS 1.3/Mac OS X 10.5 ****/
337 cups_array_t *marked; /* Marked choices @since CUPS 1.3/Mac OS X 10.5@ @private@ */
338
339 /**** New in CUPS 1.4/Mac OS X 10.6 ****/
340 cups_array_t *cups_uiconstraints; /* cupsUIConstraints @since CUPS 1.4/Mac OS X 10.6@ @private@ */
341
342 /**** New in CUPS 1.5 ****/
343 _ppd_cache_t *cache; /* PPD cache and mapping data @since CUPS 1.5/Mac OS X 10.7@ @private@ */
344 } ppd_file_t;
345
346
347 /*
348 * Prototypes...
349 */
350
351 extern int cupsMarkOptions(ppd_file_t *ppd, int num_options,
352 cups_option_t *options);
353 extern void ppdClose(ppd_file_t *ppd);
354 extern int ppdCollect(ppd_file_t *ppd, ppd_section_t section,
355 ppd_choice_t ***choices);
356 extern int ppdConflicts(ppd_file_t *ppd);
357 extern int ppdEmit(ppd_file_t *ppd, FILE *fp,
358 ppd_section_t section);
359 extern int ppdEmitFd(ppd_file_t *ppd, int fd,
360 ppd_section_t section);
361 extern int ppdEmitJCL(ppd_file_t *ppd, FILE *fp, int job_id,
362 const char *user, const char *title);
363 extern ppd_choice_t *ppdFindChoice(ppd_option_t *o, const char *option);
364 extern ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
365 extern ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
366 extern int ppdIsMarked(ppd_file_t *ppd, const char *keyword,
367 const char *option);
368 extern void ppdMarkDefaults(ppd_file_t *ppd);
369 extern int ppdMarkOption(ppd_file_t *ppd, const char *keyword,
370 const char *option);
371 extern ppd_file_t *ppdOpen(FILE *fp);
372 extern ppd_file_t *ppdOpenFd(int fd);
373 extern ppd_file_t *ppdOpenFile(const char *filename);
374 extern float ppdPageLength(ppd_file_t *ppd, const char *name);
375 extern ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
376 extern float ppdPageWidth(ppd_file_t *ppd, const char *name);
377
378 /**** New in CUPS 1.1.19 ****/
379 extern const char *ppdErrorString(ppd_status_t status) _CUPS_API_1_1_19;
380 extern ppd_attr_t *ppdFindAttr(ppd_file_t *ppd, const char *name,
381 const char *spec) _CUPS_API_1_1_19;
382 extern ppd_attr_t *ppdFindNextAttr(ppd_file_t *ppd, const char *name,
383 const char *spec) _CUPS_API_1_1_19;
384 extern ppd_status_t ppdLastError(int *line) _CUPS_API_1_1_19;
385
386 /**** New in CUPS 1.1.20 ****/
387 extern void ppdSetConformance(ppd_conform_t c) _CUPS_API_1_1_20;
388
389 /**** New in CUPS 1.2 ****/
390 extern int ppdCollect2(ppd_file_t *ppd, ppd_section_t section,
391 float min_order, ppd_choice_t ***choices) _CUPS_API_1_2;
392 extern int ppdEmitAfterOrder(ppd_file_t *ppd, FILE *fp,
393 ppd_section_t section, int limit,
394 float min_order) _CUPS_API_1_2;
395 extern int ppdEmitJCLEnd(ppd_file_t *ppd, FILE *fp) _CUPS_API_1_2;
396 extern char *ppdEmitString(ppd_file_t *ppd, ppd_section_t section,
397 float min_order) _CUPS_API_1_2;
398 extern ppd_coption_t *ppdFindCustomOption(ppd_file_t *ppd,
399 const char *keyword) _CUPS_API_1_2;
400 extern ppd_cparam_t *ppdFindCustomParam(ppd_coption_t *opt,
401 const char *name) _CUPS_API_1_2;
402 extern ppd_cparam_t *ppdFirstCustomParam(ppd_coption_t *opt) _CUPS_API_1_2;
403 extern ppd_option_t *ppdFirstOption(ppd_file_t *ppd) _CUPS_API_1_2;
404 extern ppd_cparam_t *ppdNextCustomParam(ppd_coption_t *opt) _CUPS_API_1_2;
405 extern ppd_option_t *ppdNextOption(ppd_file_t *ppd) _CUPS_API_1_2;
406 extern int ppdLocalize(ppd_file_t *ppd) _CUPS_API_1_2;
407 extern ppd_file_t *ppdOpen2(cups_file_t *fp) _CUPS_API_1_2;
408
409 /**** New in CUPS 1.3/Mac OS X 10.5 ****/
410 extern const char *ppdLocalizeIPPReason(ppd_file_t *ppd,
411 const char *reason,
412 const char *scheme,
413 char *buffer,
414 size_t bufsize) _CUPS_API_1_3;
415
416 /**** New in CUPS 1.4/Mac OS X 10.6 ****/
417 extern int cupsGetConflicts(ppd_file_t *ppd, const char *option,
418 const char *choice,
419 cups_option_t **options)
420 _CUPS_API_1_4;
421 extern int cupsResolveConflicts(ppd_file_t *ppd, const char *option,
422 const char *choice,
423 int *num_options,
424 cups_option_t **options)
425 _CUPS_API_1_4;
426 extern int ppdInstallableConflict(ppd_file_t *ppd,
427 const char *option,
428 const char *choice)
429 _CUPS_API_1_4;
430 extern ppd_attr_t *ppdLocalizeAttr(ppd_file_t *ppd, const char *keyword,
431 const char *spec) _CUPS_API_1_4;
432 extern const char *ppdLocalizeMarkerName(ppd_file_t *ppd,
433 const char *name) _CUPS_API_1_4;
434 extern int ppdPageSizeLimits(ppd_file_t *ppd,
435 ppd_size_t *minimum,
436 ppd_size_t *maximum) _CUPS_API_1_4;
437
438
439 /*
440 * C++ magic...
441 */
442
443 # ifdef __cplusplus
444 }
445 # endif /* __cplusplus */
446 #endif /* !_CUPS_PPD_H_ */
447
448 /*
449 * End of "$Id$".
450 */