pstoraster/gsparam.h

   1 /* Copyright (C) 1993, 1995 Aladdin Enterprises.  All rights reserved.
   2
   3   This file is part of GNU Ghostscript.
   4
   5   GNU Ghostscript is distributed in the hope that it will be useful, but
   6   WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility to
   7   anyone for the consequences of using it or for whether it serves any
   8   particular purpose or works at all, unless he says so in writing.  Refer to
   9   the GNU General Public License for full details.
  10
  11   Everyone is granted permission to copy, modify and redistribute GNU
  12   Ghostscript, but only under the conditions described in the GNU General
  13   Public License.  A copy of this license is supposed to have been given to
  14   you along with GNU Ghostscript so you can know your rights and
  15   responsibilities.  It should be in a file named COPYING.  Among other
  16   things, the copyright notice and this notice must be preserved on all
  17   copies.
  18
  19   Aladdin Enterprises is not affiliated with the Free Software Foundation or
  20   the GNU Project.  GNU Ghostscript, as distributed by Aladdin Enterprises,
  21   does not depend on any other GNU software.
  22 */
  23
  24 /* gsparam.h */
  25 /* Client interface to parameter dictionaries */
  26
  27 #ifndef gsparam_INCLUDED
  28 #  define gsparam_INCLUDED
  29
  30 /*
  31  * Several interfaces use parameter dictionaries to communicate sets of
  32  * (key, value) pairs from a client to an object with complex state.
  33  * (Several of these correspond directly to similar interfaces in the
  34  * PostScript language.) This file defines the API for parameter dictionaries.
  35  */
  36
  37 #ifndef gs_param_list_DEFINED
  38 #  define gs_param_list_DEFINED
  39 typedef struct gs_param_list_s gs_param_list;
  40 #endif
  41 typedef const char *gs_param_name;
  42
  43 /*
  44  * Define a structure for representing a variable-size value
  45  * (string/name, integer array, or floating point array).
  46  * The size is the number of elements, not the size in bytes.
  47  * A value is persistent if it is defined as static const,
  48  * or if it is allocated in garbage-collectable space and never freed.
  49  */
  50
  51 #define _param_array_struct(sname,etype)\
  52   struct sname { const etype *data; uint size; bool persistent; }
  53 typedef _param_array_struct(gs_param_string_s, byte) gs_param_string;
  54 typedef _param_array_struct(gs_param_int_array_s, int) gs_param_int_array;
  55 typedef _param_array_struct(gs_param_float_array_s, float) gs_param_float_array;
  56 typedef _param_array_struct(gs_param_string_array_s, gs_param_string) gs_param_string_array;
  57
  58 #define param_string_from_string(ps, str)\
  59   (ps).data = (const byte *)(str), (ps).size = strlen((const char *)(ps).data),\
  60   (ps).persistent = true
  61
  62 /* Define the type for dictionary and mixed-type-array values. */
  63 typedef struct gs_param_collection_s {
  64         gs_param_list *list;
  65         uint size;
  66 } gs_param_collection;
  67 typedef gs_param_collection gs_param_dict;
  68 typedef gs_param_collection gs_param_array;
  69
  70 /* Define the 'policies' for handling out-of-range parameter values. */
  71 /* This is not an enum, because some parameters may recognize other values. */
  72 #define gs_param_policy_signal_error 0
  73 #define gs_param_policy_ignore 1
  74 #define gs_param_policy_consult_user 2
  75
  76 /*
  77  * Define the object procedures.  Note that the same interface is used
  78  * both for getting and for setting parameter values.  (This is a bit
  79  * of a hack, and we might change it someday.)  The procedures return
  80  * as follows:
  81  *      - 'reading' procedures ('put' operations from the client's viewpoint)
  82  * return 1 for a missing parameter, 0 for a valid parameter, <0 on error.
  83  *      - 'writing' procedures ('get' operations from the client's viewpoint)
  84  * return 0 or 1 if successful, <0 on error.
  85  */
  86
  87 /*
  88  * Transmitting variable-size objects requires some extra care.
  89  *      - When writing an array, string, name, or dictionary, the
  90  * implementation (not the client) sets all the fields of the value.
  91  *      - When reading an array, string, or name, the client must set
  92  * all the fields of the value.
  93  *      - When reading a dictionary, the client must set the size field
  94  * before calling begin_write_dict; the implementation of begin_write_dict
  95  * allocates the list.
  96  */
  97
  98 /*
  99  * Setting parameters must use a "two-phase commit" policy.  Specifically,
 100  * any put_params procedure must observe the following discipline:
 101
 102         1. For each parameter known to the device, ask the parameter list if
 103 there is a new value, and if so, make all necessary validity checks.  If any
 104 check fails, call param_signal_error for that parameter, but continue to
 105 check further parameters.  Normally, this step should not alter the state of
 106 the device; however, if the device allows changing any parameters that are
 107 read-only by default (for example, BitsPerPixel or ProcessColorModel), or if
 108 it replaces the default put_params behavior for any parameter (for example,
 109 if it handles MediaSize or Resolution itself to forestall the normal closing
 110 of the device when these are set), step 1 of put_params must change the
 111 parameters in the device state, and step 2 must undo the changes if
 112 returning an error.
 113
 114         2. Call the "superclass" put_params routine.  For printer devices,
 115 this is gdev_prn_put_params; for other devices, it is gx_default_put_params.
 116 Note that this must be done even if errors were detected in step 1.  If this
 117 routine returns an error code, or if step 1 detected an error, undo any
 118 changes that step 1 made in the device state, and return the error code.
 119
 120         3. Install the new parameter values in the device.  If necessary,
 121 close the device first; a higher-level routine (gs_putdeviceparams) will
 122 reopen the device if necessary.
 123
 124  */
 125
 126 typedef struct gs_param_list_procs_s {
 127
 128         /* Transmit a null value. */
 129         /* Note that this is the only 'transmit' operation */
 130         /* that does not actually pass any data. */
 131
 132 #define param_proc_xmit_null(proc)\
 133   int proc(P2(gs_param_list *, gs_param_name))
 134         param_proc_xmit_null((*xmit_null));
 135 #define param_read_null(plist, pkey)\
 136   (*(plist)->procs->xmit_null)(plist, pkey)
 137 #define param_write_null(plist, pkey)\
 138   (*(plist)->procs->xmit_null)(plist, pkey)
 139
 140         /* Transmit a Boolean value. */
 141
 142 #define param_proc_xmit_bool(proc)\
 143   int proc(P3(gs_param_list *, gs_param_name, bool *))
 144         param_proc_xmit_bool((*xmit_bool));
 145 #define param_read_bool(plist, pkey, pvalue)\
 146   (*(plist)->procs->xmit_bool)(plist, pkey, pvalue)
 147 #define param_write_bool(plist, pkey, pvalue)\
 148   (*(plist)->procs->xmit_bool)(plist, pkey, pvalue)
 149
 150         /* Transmit an integer value. */
 151
 152 #define param_proc_xmit_int(proc)\
 153   int proc(P3(gs_param_list *, gs_param_name, int *))
 154         param_proc_xmit_int((*xmit_int));
 155 #define param_read_int(plist, pkey, pvalue)\
 156   (*(plist)->procs->xmit_int)(plist, pkey, pvalue)
 157 #define param_write_int(plist, pkey, pvalue)\
 158   (*(plist)->procs->xmit_int)(plist, pkey, pvalue)
 159
 160         /* Transmit a long value. */
 161
 162 #define param_proc_xmit_long(proc)\
 163   int proc(P3(gs_param_list *, gs_param_name, long *))
 164         param_proc_xmit_long((*xmit_long));
 165 #define param_read_long(plist, pkey, pvalue)\
 166   (*(plist)->procs->xmit_long)(plist, pkey, pvalue)
 167 #define param_write_long(plist, pkey, pvalue)\
 168   (*(plist)->procs->xmit_long)(plist, pkey, pvalue)
 169
 170         /* Transmit a float value. */
 171
 172 #define param_proc_xmit_float(proc)\
 173   int proc(P3(gs_param_list *, gs_param_name, float *))
 174         param_proc_xmit_float((*xmit_float));
 175 #define param_read_float(plist, pkey, pvalue)\
 176   (*(plist)->procs->xmit_float)(plist, pkey, pvalue)
 177 #define param_write_float(plist, pkey, pvalue)\
 178   (*(plist)->procs->xmit_float)(plist, pkey, pvalue)
 179
 180         /* Transmit a string value. */
 181
 182 #define param_proc_xmit_string(proc)\
 183   int proc(P3(gs_param_list *, gs_param_name, gs_param_string *))
 184         param_proc_xmit_string((*xmit_string));
 185 #define param_read_string(plist, pkey, pvalue)\
 186   (*(plist)->procs->xmit_string)(plist, pkey, pvalue)
 187 #define param_write_string(plist, pkey, pvalue)\
 188   (*(plist)->procs->xmit_string)(plist, pkey, pvalue)
 189
 190         /* Transmit a name value. */
 191
 192 #define param_proc_xmit_name(proc)\
 193   int proc(P3(gs_param_list *, gs_param_name, gs_param_string *))
 194         param_proc_xmit_name((*xmit_name));
 195 #define param_read_name(plist, pkey, pvalue)\
 196   (*(plist)->procs->xmit_name)(plist, pkey, pvalue)
 197 #define param_write_name(plist, pkey, pvalue)\
 198   (*(plist)->procs->xmit_name)(plist, pkey, pvalue)
 199
 200         /* Transmit an integer array value. */
 201
 202 #define param_proc_xmit_int_array(proc)\
 203   int proc(P3(gs_param_list *, gs_param_name, gs_param_int_array *))
 204         param_proc_xmit_int_array((*xmit_int_array));
 205 #define param_read_int_array(plist, pkey, pvalue)\
 206   (*(plist)->procs->xmit_int_array)(plist, pkey, pvalue)
 207 #define param_write_int_array(plist, pkey, pvalue)\
 208   (*(plist)->procs->xmit_int_array)(plist, pkey, pvalue)
 209
 210         /* Transmit a float array value. */
 211
 212 #define param_proc_xmit_float_array(proc)\
 213   int proc(P3(gs_param_list *, gs_param_name, gs_param_float_array *))
 214         param_proc_xmit_float_array((*xmit_float_array));
 215 #define param_read_float_array(plist, pkey, pvalue)\
 216   (*(plist)->procs->xmit_float_array)(plist, pkey, pvalue)
 217 #define param_write_float_array(plist, pkey, pvalue)\
 218   (*(plist)->procs->xmit_float_array)(plist, pkey, pvalue)
 219
 220         /* Transmit a string array value. */
 221
 222 #define param_proc_xmit_string_array(proc)\
 223   int proc(P3(gs_param_list *, gs_param_name, gs_param_string_array *))
 224         param_proc_xmit_string_array((*xmit_string_array));
 225 #define param_read_string_array(plist, pkey, pvalue)\
 226   (*(plist)->procs->xmit_string_array)(plist, pkey, pvalue)
 227 #define param_write_string_array(plist, pkey, pvalue)\
 228   (*(plist)->procs->xmit_string_array)(plist, pkey, pvalue)
 229
 230         /* Transmit a name array value. */
 231
 232 #define param_proc_xmit_name_array(proc)\
 233   int proc(P3(gs_param_list *, gs_param_name, gs_param_string_array *))
 234         param_proc_xmit_name_array((*xmit_name_array));
 235 #define param_read_name_array(plist, pkey, pvalue)\
 236   (*(plist)->procs->xmit_name_array)(plist, pkey, pvalue)
 237 #define param_write_name_array(plist, pkey, pvalue)\
 238   (*(plist)->procs->xmit_name_array)(plist, pkey, pvalue)
 239
 240         /* Start transmitting a dictionary value. */
 241         /* If int_keys is true, the keys are actually integers */
 242         /* (although still presented as strings). */
 243
 244 #define param_proc_begin_xmit_dict(proc)\
 245   int proc(P4(gs_param_list *, gs_param_name, gs_param_dict *, bool))
 246         param_proc_begin_xmit_dict((*begin_xmit_dict));
 247 #define param_begin_read_dict(plist, pkey, pvalue, int_keys)\
 248   (*(plist)->procs->begin_xmit_dict)(plist, pkey, pvalue, int_keys)
 249 #define param_begin_write_dict(plist, pkey, pvalue, int_keys)\
 250   (*(plist)->procs->begin_xmit_dict)(plist, pkey, pvalue, int_keys)
 251
 252         /* Finish transmitting a dictionary value. */
 253
 254 #define param_proc_end_xmit_dict(proc)\
 255   int proc(P3(gs_param_list *, gs_param_name, gs_param_dict *))
 256         param_proc_end_xmit_dict((*end_xmit_dict));
 257 #define param_end_read_dict(plist, pkey, pvalue)\
 258   (*(plist)->procs->end_xmit_dict)(plist, pkey, pvalue)
 259 #define param_end_write_dict(plist, pkey, pvalue)\
 260   (*(plist)->procs->end_xmit_dict)(plist, pkey, pvalue)
 261
 262         /* Determine whether a given key has been requested. */
 263         /* (Only used when writing.) */
 264
 265 #define param_proc_requested(proc)\
 266   bool proc(P2(const gs_param_list *, gs_param_name))
 267         param_proc_requested((*requested));
 268 #define param_requested(plist, pkey)\
 269   (*(plist)->procs->requested)(plist, pkey)
 270
 271         /* Get the 'policy' associated with an out-of-range parameter value. */
 272         /* (Only used when reading.) */
 273
 274 #define param_proc_get_policy(proc)\
 275   int proc(P2(gs_param_list *, gs_param_name))
 276         param_proc_get_policy((*get_policy));
 277 #define param_get_policy(plist, pkey)\
 278   (*(plist)->procs->get_policy)(plist, pkey)
 279
 280         /*
 281          * Signal an error.  (Only used when reading.)
 282          * The procedure may return a different error code,
 283          * or may return 0 indicating that the error is to be ignored.
 284          */
 285
 286 #define param_proc_signal_error(proc)\
 287   int proc(P3(gs_param_list *, gs_param_name, int))
 288         param_proc_signal_error((*signal_error));
 289 #define param_signal_error(plist, pkey, code)\
 290   (*(plist)->procs->signal_error)(plist, pkey, code)
 291 #define param_return_error(plist, pkey, code)\
 292   return_error(param_signal_error(plist, pkey, code))
 293
 294         /*
 295          * "Commit" a set of changes.  (Only used when reading.)
 296          * This is called at the end of the first phase.
 297          */
 298
 299 #define param_proc_commit(proc)\
 300   int proc(P1(gs_param_list *))
 301         param_proc_commit((*commit));
 302 #define param_commit(plist)\
 303   (*(plist)->procs->commit)(plist)
 304
 305 } gs_param_list_procs;
 306
 307 /* Define an abstract parameter dictionary.  Implementations are */
 308 /* concrete subclasses. */
 309 #define gs_param_list_common\
 310         const gs_param_list_procs _ds *procs
 311 struct gs_param_list_s {
 312         gs_param_list_common;
 313 };
 314
 315 /*
 316  * Define a default implementation, intended to be usable easily
 317  * from C code.  The intended usage pattern is:
 318         gs_c_param_list list;
 319         [... other code here ...]
 320         gs_c_param_list_write(&list, mem);
 321         [As many as needed:]
 322                 code = param_write_XXX(&list, "ParamName", &param_value);
 323                 [Check code for <0]
 324         gs_c_param_list_read(&list);
 325         code = gs_putdeviceparams(dev, &list);
 326         gs_c_param_list_release(&list);
 327         [Check code for <0]
 328         if ( code == 1 )
 329         { code = (*dev_proc(dev, open_device))(dev);
 330           [Check code for <0]
 331         }
 332  */
 333
 334 typedef struct gs_c_param_s gs_c_param;         /* opaque here */
 335 typedef struct gs_c_param_list_s {
 336         gs_param_list_common;
 337         gs_memory_t *memory;
 338         gs_c_param *head;
 339         uint count;
 340 } gs_c_param_list;
 341 #define private_st_c_param_list()       /* in gsparam.c */\
 342   gs_private_st_ptrs1(st_c_param_list, gs_c_param_list, "c_param_list",\
 343     c_param_list_enum_ptrs, c_param_list_reloc_ptrs, head)
 344 /* Clients normally allocate the gs_c_param_list on the stack. */
 345 void gs_c_param_list_write(P2(gs_c_param_list *, gs_memory_t *));
 346 void gs_c_param_list_read(P1(gs_c_param_list *));       /* switch to reading */
 347 void gs_c_param_list_release(P1(gs_c_param_list *));
 348
 349 #endif                                  /* gsparam_INCLUDED */