1 /* Copyright (C) 2001-2019 Artifex Software, Inc.
2    All Rights Reserved.
3 
4    This software is provided AS-IS with no warranty, either express or
5    implied.
6 
7    This software is distributed under license and may not be copied,
8    modified or distributed except as expressly authorized under the terms
9    of the license contained in the file LICENSE in this distribution.
10 
11    Refer to licensing information at http://www.artifex.com or contact
12    Artifex Software, Inc.,  1305 Grant Avenue - Suite 200, Novato,
13    CA 94945, U.S.A., +1(415)492-9861, for further information.
14 */
15 
16 
17 /* Interface to idparam.c */
18 
19 #ifndef idparam_INCLUDED
20 #  define idparam_INCLUDED
21 
22 #include "stdpre.h"
23 #include "iref.h"
24 #include "gsmatrix.h"
25 #include "gsuid.h"
26 
27 /*
28  * Unless otherwise noted, all the following routines return 0 for
29  * a valid parameter, 1 for a defaulted parameter, or <0 on error.
30  *
31  * Note that all the dictionary parameter routines take a C string,
32  * not a t_name ref *.  Even though this is slower, it means that
33  * the GC doesn't have to worry about finding statically declared
34  * name refs, and we have that many fewer static variables.
35  *
36  * All these routines allow pdict == NULL, which they treat the same as
37  * pdict referring to an empty dictionary.  Routines with "null" in their
38  * name return 2 if the parameter is null, without setting *pvalue.
39  */
40 int dict_bool_param(const ref * pdict, const char *kstr,
41                     bool defaultval, bool * pvalue);
42 int dict_int_param(const ref * pdict, const char *kstr,
43                    int minval, int maxval, int defaultval, int *pvalue);
44 int dict_int_null_param(const ref * pdict, const char *kstr,
45                         int minval, int maxval, int defaultval,
46                         int *pvalue);
47 int dict_uint_param(const ref * pdict, const char *kstr,
48                     uint minval, uint maxval, uint defaultval,
49                     uint * pvalue);
50 int dict_float_param(const ref * pdict, const char *kstr,
51                      double defaultval, float *pvalue);
52 /*
53  * There are 3 variants of the procedures for getting array parameters.
54  * All return the element count if the parameter is present and of the
55  * correct size, 0 if the key is missing.
56  *	_xxx_check_param return over_error if the array size > len,
57  *	  (under_error < 0 ? under_error : the element count) if the array
58  *	  size < len.
59  *	_xxx_param return limitcheck if the array size > maxlen.
60  *	  Equivalent to _xxx_check_param(..., 0, limitcheck).
61  *	_xxxs return rangecheck if the array size != len.
62  *	  Equivalent to _xxx_check_param(..., rangecheck, rangecheck).
63  * All can return other error codes (e.g., typecheck).
64  */
65 int dict_int_array_check_param(const gs_memory_t *mem, const ref * pdict,
66    const char *kstr, uint len, int *ivec, int under_error, int over_error);
67 int dict_int_array_param(const gs_memory_t *mem, const ref * pdict,
68    const char *kstr, uint maxlen, int *ivec);
69 int dict_ints_param(const gs_memory_t *mem, const ref * pdict,
70    const char *kstr, uint len, int *ivec);
71 /*
72  * For _float_array_param, if the parameter is missing and defaultvec is
73  * not NULL, copy (max)len elements from defaultvec to fvec and return
74  * (max)len.
75  */
76 int dict_float_array_check_param(const gs_memory_t *mem,
77                                  const ref * pdict, const char *kstr,
78                                  uint len, float *fvec,
79                                  const float *defaultvec,
80                                  int under_error, int over_error);
81 int dict_float_array_param(const gs_memory_t *mem,
82                            const ref * pdict, const char *kstr,
83                            uint maxlen, float *fvec,
84                            const float *defaultvec);
85 int dict_floats_param(const gs_memory_t *mem,
86                       const ref * pdict, const char *kstr,
87                       uint len, float *fvec,
88                       const float *defaultvec);
89 /* Do dict_floats_param() and store [/key any] array in $error.errorinfo
90  * on failure. The key must be a permanently allocated C string.
91  */
92 int
93 dict_floats_param_errorinfo(i_ctx_t *i_ctx_p,
94                   const ref * pdict, const char *kstr,
95                   uint maxlen, float *fvec, const float *defaultvec);
96 
97 /*
98  * For dict_proc_param,
99  *      defaultval = false means substitute t__invalid;
100  *      defaultval = true means substitute an empty procedure.
101  * In either case, return 1.
102  */
103 int dict_proc_param(const ref * pdict, const char *kstr, ref * pproc,
104                     bool defaultval);
105 int dict_matrix_param(const gs_memory_t *mem,
106                       const ref * pdict, const char *kstr,
107                       gs_matrix * pmat);
108 int dict_uid_param(const ref * pdict, gs_uid * puid, int defaultval,
109                    gs_memory_t * mem, const i_ctx_t *i_ctx_p);
110 
111 /* Check that a UID in a dictionary is equal to an existing, valid UID. */
112 bool dict_check_uid_param(const ref * pdict, const gs_uid * puid);
113 
114 /* Create and store [/key any] array in $error.errorinfo.
115  * The key must be a permanently allocated C string.
116  */
117 int
118 gs_errorinfo_put_pair(i_ctx_t *i_ctx_p, const char *key, int len, const ref *any);
119 
120 /* Take a key's value from a given dictionary, create [/key any] array,
121  * and store it in $error.errorinfo.
122  * The key must be a permanently allocated C string.
123  */
124 void
125 gs_errorinfo_put_pair_from_dict(i_ctx_t *i_ctx_p, const ref *op, const char *key);
126 
127 #endif /* idparam_INCLUDED */
128