Line data Source code
1 : /*
2 : * SPDX-License-Identifier: MPL-2.0
3 : *
4 : * This Source Code Form is subject to the terms of the Mozilla Public
5 : * License, v. 2.0. If a copy of the MPL was not distributed with this
6 : * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 : *
8 : * Copyright 2024, 2025 MonetDB Foundation;
9 : * Copyright August 2008 - 2023 MonetDB B.V.;
10 : * Copyright 1997 - July 2008 CWI.
11 : */
12 :
13 : #ifndef _MSETTINGS_H
14 : #define _MSETTINGS_H 1
15 :
16 : #include "mapi.h"
17 : #include <stdbool.h>
18 :
19 : #define MP__BOOL_START (100)
20 : #define MP__LONG_START (200)
21 : #define MP__STRING_START (300)
22 : #define MP__MAX (400)
23 :
24 : #ifdef __cplusplus
25 : extern "C" {
26 : #endif
27 :
28 : /* avoid using "#ifdef WIN32" so that this file does not need our config.h */
29 : #if defined(_MSC_VER) || defined(__CYGWIN__) || defined(__MINGW32__)
30 : #ifndef LIBMAPI
31 : #define mapi_export extern __declspec(dllimport)
32 : #else
33 : #define mapi_export extern __declspec(dllexport)
34 : #endif
35 : #else
36 : #define mapi_export extern
37 : #endif
38 :
39 : /////////////////////////////////////////////////////////////////////
40 : // This enum identifies properties that can be set that affect how a
41 : // connection is made. In particular we have functies to parse strings
42 : // into a an enum value, and back.
43 :
44 : typedef enum mparm {
45 : MP_UNKNOWN,
46 : MP_IGNORE,
47 :
48 : // bool
49 : MP_TLS = MP__BOOL_START,
50 : MP_AUTOCOMMIT,
51 : MP_CLIENT_INFO,
52 : // Note: if you change anything about this enum whatsoever, make sure to
53 : // make the corresponding change to struct msettings in msettings.c as well.
54 :
55 : // long
56 : MP_PORT = MP__LONG_START,
57 : MP_TIMEZONE,
58 : MP_REPLYSIZE,
59 : MP_MAPTOLONGVARCHAR, // specific to ODBC
60 : MP_CONNECT_TIMEOUT,
61 : MP_REPLY_TIMEOUT,
62 : // Note: if you change anything about this enum whatsoever, make sure to
63 : // make the corresponding change to struct msettings in msettings.c as well.
64 :
65 : // string
66 : MP_SOCK = MP__STRING_START,
67 : MP_SOCKDIR,
68 : MP_CERT,
69 : MP_CLIENTKEY,
70 : MP_CLIENTCERT,
71 : MP_HOST,
72 : MP_DATABASE,
73 : MP_TABLESCHEMA,
74 : MP_TABLE,
75 : MP_CERTHASH,
76 : MP_USER,
77 : MP_PASSWORD,
78 : MP_LANGUAGE,
79 : MP_SCHEMA, // TODO implement this
80 : MP_BINARY,
81 : MP_LOGFILE,
82 : MP_CLIENT_APPLICATION,
83 : MP_CLIENT_REMARK,
84 : // Note: if you change anything about this enum whatsoever, make sure to
85 : // make the corresponding change to struct msettings in msettings.c as well.
86 :
87 : // !! Make sure to keep them all below MP__MAX !!
88 : } mparm;
89 :
90 : typedef enum mparm_class {
91 : MPCLASS_BOOL,
92 : MPCLASS_LONG,
93 : MPCLASS_STRING,
94 : } mparm_class;
95 :
96 : static inline mparm_class
97 1774898 : mparm_classify(mparm parm)
98 : {
99 1774898 : assert(parm > MP_IGNORE);
100 1774898 : if (parm < MP__LONG_START)
101 : return MPCLASS_BOOL;
102 1602190 : else if (parm >= MP__STRING_START)
103 : return MPCLASS_STRING;
104 : else
105 491176 : return MPCLASS_LONG;
106 : }
107 :
108 :
109 : /* returns NULL if not found, pointer to mparm if found */
110 : mapi_export mparm mparm_parse(const char *name);
111 : mapi_export const char *mparm_name(mparm parm);
112 : mapi_export mparm mparm_enumerate(int i);
113 : mapi_export bool mparm_is_core(mparm parm);
114 :
115 :
116 : /////////////////////////////////////////////////////////////////////
117 : // This type hold all properties that can be set that affect how a
118 : // connection is made. There are methods to create/destroy etc.,
119 : // getters and setters based on enum mparm above, and getters
120 : // and setters based on string values.
121 : // Also, msettings_validate, msettings_parse_url and a number
122 : // of helper functions.
123 :
124 : typedef struct msettings msettings;
125 :
126 : /* NULL means OK. non-NULL is error message. Valid until next call. Do not free. */
127 : typedef const char *msettings_error;
128 : mapi_export bool msettings_malloc_failed(msettings_error err);
129 :
130 : /* these return NULL if they cannot not allocate */
131 : typedef void *(*msettings_allocator)(void *state, void *old, size_t size);
132 : mapi_export msettings *msettings_create(void);
133 : mapi_export msettings *msettings_create_with(msettings_allocator alloc, void *alloc_state);
134 : mapi_export msettings *msettings_clone(const msettings *mp);
135 : mapi_export msettings *msettings_clone_with(msettings_allocator alloc, void *alloc_state, const msettings *mp);
136 : mapi_export msettings_allocator msettings_get_allocator(const msettings *mp, void **put_alloc_state_here);
137 : mapi_export void msettings_reset(msettings *mp);
138 : mapi_export const msettings *msettings_default;
139 :
140 : /* always returns NULL */
141 : mapi_export msettings *msettings_destroy(msettings *mp);
142 :
143 : mapi_export const char *msetting_parm_name(const msettings *mp, mparm parm);
144 : mapi_export void msettings_set_localizer(msettings *mp, const char* (*localizer)(const void *data, mparm parm), void *data);
145 :
146 : /* retrieve and set; call abort() on type error */
147 :
148 : mapi_export const char* msetting_string(const msettings *mp, mparm parm);
149 : mapi_export msettings_error msetting_set_string(msettings *mp, mparm parm, const char* value)
150 : __attribute__((__nonnull__(3)));
151 :
152 : mapi_export long msetting_long(const msettings *mp, mparm parm);
153 : mapi_export msettings_error msetting_set_long(msettings *mp, mparm parm, long value);
154 :
155 : mapi_export bool msetting_bool(const msettings *mp, mparm parm);
156 : mapi_export msettings_error msetting_set_bool(msettings *mp, mparm parm, bool value);
157 :
158 : /* Parse into the appropriate type */
159 : mapi_export msettings_error msetting_parse(msettings *mp, mparm parm, const char *text);
160 : /* Render setting as a string, requires a small scratch buffer (40 bytes is fine) for rendering integers.
161 : * Changing the msettings or the scratch buffer makes the returned pointer invalid. */
162 : mapi_export const char *msetting_as_string(const msettings *mp, mparm parm, char *scratch, size_t scratch_size);
163 :
164 : /* store named parameter */
165 : mapi_export msettings_error msetting_set_named(msettings *mp, bool allow_core, const char *key, const char *value);
166 :
167 : /* update the msettings from the URL. */
168 : mapi_export msettings_error msettings_parse_url(msettings *mp, const char *url);
169 :
170 : /* render the msettings as an URL. The result is always NUL terminated
171 : * even if it's truncated. Returns the number of characters that have been
172 : * written or would have been written if the buffer were large enough,
173 : * excluding the trailing NUL.
174 : */
175 : mapi_export size_t msettings_write_url(const msettings *mp, char *buffer, size_t);
176 :
177 : /* 1 = true, 0 = false, -1 = could not parse */
178 : mapi_export int msetting_parse_bool(const char *text);
179 :
180 : /* return an error message if the validity rules are not satisfied */
181 : mapi_export msettings_error msettings_validate(msettings *mp);
182 :
183 :
184 : /* virtual parameters */
185 : enum msetting_tls_verify {
186 : verify_none,
187 : verify_system,
188 : verify_cert,
189 : verify_hash,
190 : };
191 : mapi_export bool msettings_connect_scan(const msettings *mp);
192 : mapi_export const char *msettings_connect_unix(const msettings *mp);
193 : mapi_export const char *msettings_connect_tcp(const msettings *mp);
194 : mapi_export long msettings_connect_port(const msettings *mp);
195 : mapi_export const char *msettings_connect_certhash_digits(const msettings *mp);
196 : mapi_export long msettings_connect_binary(const msettings *mp);
197 : mapi_export enum msetting_tls_verify msettings_connect_tls_verify(const msettings *mp);
198 : mapi_export const char *msettings_connect_clientkey(const msettings *mp);
199 : mapi_export const char *msettings_connect_clientcert(const msettings *mp);
200 :
201 : /* automatically incremented each time the corresponding field is updated */
202 : long msettings_user_generation(const msettings *mp);
203 : long msettings_password_generation(const msettings *mp);
204 :
205 : /* convenience helpers*/
206 : bool msettings_lang_is_mal(const msettings *mp);
207 : bool msettings_lang_is_sql(const msettings *mp);
208 : bool msettings_lang_is_profiler(const msettings *mp);
209 :
210 : /////////////////////////////////////////////////////////////////////
211 : // Extend mapi.h
212 :
213 : // Mutable access settings of existing Mapi.
214 : // Do not make changes while connected.
215 : mapi_export msettings *mapi_get_settings(Mapi mid)
216 : __attribute__((__nonnull__(1)));
217 :
218 : // Create Mapi from settings.
219 : // Takes ownership of the settings except if malloc fails etc.
220 : // In that case NULL is returned and ownership of the settings remains with
221 : // the caller.
222 : mapi_export Mapi mapi_settings(msettings *settings)
223 : __attribute__((__nonnull__(1)));
224 :
225 :
226 : #ifdef __cplusplus
227 : }
228 : #endif
229 : #endif /* _MSETTINGS_H */
|
