summaryrefslogtreecommitdiff
path: root/support/dktools/dk3dbi.h
blob: 5ba48975b8d5f9a948986cfd88a41bc75e30db06 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
/*
Copyright (C) 2011-2020, Dirk Krause
SPDX-License-Identifier: BSD-3-Clause
*/

/*
	WARNING: This file was generated by the dkct program (see
	http://dktools.sourceforge.net/ for details).
	Changes you make here will be lost if dkct is run again!
	You should modify the original source and run dkct on it.
	Original source: dk3dbi.ctr
*/

/**	@file dk3dbi.h Header file for the dk3dbi module.
*/

#ifndef DK3DBI_H_INCLUDED
/** Avoid multiple inclusions. */
#define DK3DBI_H_INCLUDED 1


#line 10 "dk3dbi.ctr"

#ifdef __cplusplus
extern "C" {
#endif

/**	Check whether a database type is supported.
	@param	tp	Database type, see @ref databasetypes.
	@return	1 on success (type supported), 0 on error (not supported).
*/
int
dk3dbi_type_supported(int tp);

/**	Open a database.
	@param	fn	Database file name.
	@param	tp	Database type, see @ref databasetypes.
	@param	acc	Access type, see @ref databaseaccess.
	@param	pec	Pointer to error code variable, may be NULL.
	@param	app	Application structure for diagnostics, may be NULL.
	@return	Pointer to opened database on success, NULL on error.
*/
dk3_dbi_t *
dk3dbi_open_app(dkChar const *fn, int tp, int acc, int *pec, dk3_app_t *app);

/**	Open a database.
	@param	fn	Database file name.
	@param	tp	Database type, see @ref databasetypes.
	@param	acc	Access type, see @ref databaseaccess.
	@param	pec	Pointer to error code variable, may be NULL.
	@return	Pointer to opened database on success, NULL on error.
*/
dk3_dbi_t *
dk3dbi_open(dkChar const *fn, int tp, int acc, int *pec);

/**	Open a database, discard all existing contents.
	@param	fn	Database file name.
	@param	tp	Database type, see @ref databasetypes.
	@param	acc	Access type, see @ref databaseaccess.
	@param	pec	Pointer to error code variable, may be NULL.
	@param	app	Application structure for diagnostics, may be NULL.
	@return	Pointer to opened database on success, NULL on error.
*/
dk3_dbi_t *
dk3dbi_open_truncate_app(
  dkChar const *fn,
  int tp,
  int acc,
  int *pec,
  dk3_app_t *app
);

/**	Open a database, discard all existing contents.
	@param	fn	Database file name.
	@param	tp	Database type, see @ref databasetypes.
	@param	acc	Access type, see @ref databaseaccess.
	@param	pec	Pointer to error code variable, may be NULL.
	@return	Pointer to opened database on success, NULL on error.
*/
dk3_dbi_t *
dk3dbi_open_truncate(dkChar const *fn, int tp, int acc, int *pec);

/**	Set an entry in the database.
	@param	dbp	Database.
	@param	key	Key data.
	@param	val	Value data.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_set(dk3_dbi_t *dbp, dk3_datum_t *key, dk3_datum_t *val);

/**	Get an entry from the database.
	@param	dbp	Database.
	@param	key	Key data.
	@param	val	Value data, set up for a result buffer.
	On input it contains the buffer size, on successful
	return it contains the number of bytes.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_get(dk3_dbi_t *dbp, dk3_datum_t *key, dk3_datum_t *val);

/**	Delete an entry from the database.
	@param	dbp	Database.
	@param	key	Key data.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_delete(dk3_dbi_t *dbp, dk3_datum_t *key);

/**	Save 8-bit character string to database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	val	Value string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_set_c8_string(
  dk3_dbi_t	*dbp,
  char const	*key,
  char const	*val
);

/**	Retrieve 8-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	vb	Value buffer.
	@param	vbsz	Value buffer size in bytes.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_get_c8_string(
  dk3_dbi_t	*dbp,
  char const	*key,
  char		*vb,
  size_t	 vbsz
);

/**	Delete 8-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_delete_c8_string(
  dk3_dbi_t	*dbp,
  char const	*key
);

/**	Save 16-bit character string to database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	val	Value string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_set_c16_string(
  dk3_dbi_t		*dbp,
  dk3_c16_t const	*key,
  dk3_c16_t const	*val
);

/**	Retrieve 16-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	vb	Value buffer.
	@param	vbsz	Value buffer size (number of 16-bit characters).
	@return	1 on success, 0 on error.
*/
int
dk3dbi_get_c16_string(
  dk3_dbi_t		*dbp,
  dk3_c16_t const	*key,
  dk3_c16_t		*vb,
  size_t		 vbsz
);

/**	Delete 16-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_delete_c16_string(
  dk3_dbi_t		*dbp,
  dk3_c16_t const	*key
);

/**	Save 32-bit character string to database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	val	Value string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_set_c32_string(
  dk3_dbi_t		*dbp,
  dk3_c32_t const	*key,
  dk3_c32_t const	*val
);

/**	Retrieve 32-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	vb	Value buffer.
	@param	vbsz	Value buffer size (number of 32-bit characters).
	@return	1 on success, 0 on error.
*/
int
dk3dbi_get_c32_string(
  dk3_dbi_t		*dbp,
  dk3_c32_t const	*key,
  dk3_c32_t		*vb,
  size_t		 vbsz
);

/**	Delete 32-bit character string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_delete_c32_string(
  dk3_dbi_t		*dbp,
  dk3_c32_t const	*key
);

/**	Save a dkChar string to the database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	val	Value string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_set_string(
  dk3_dbi_t	*dbp,
  dkChar const	*key,
  dkChar const	*val
);

/**	Retrieve dkChar string from the database.
	@param	dbp	Database.
	@param	key	Key string.
	@param	vb	Value buffer.
	@param	vbsz	Size of value buffer (Number of dkChar).
	@return	1 on success, 0 on error.
*/
int
dk3dbi_get_string(
  dk3_dbi_t	*dbp,
  dkChar const	*key,
  dkChar	*vb,
  size_t	 vbsz
);

/**	Delete dkChar string from database.
	@param	dbp	Database.
	@param	key	Key string.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_delete_string(
  dk3_dbi_t	*dbp,
  dkChar const	*key
);

/**	Synchronize to disk.
	@param	dbp	Database.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_sync(dk3_dbi_t *dbp);

/**	Traverse database.
	@param	dbp	Database.
	@param	obj	Object to modify while traversing the database.
	@param	fct	Callback function to use for each key/value pair.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_traverse(dk3_dbi_t *dbp, void *obj, dk3_db_traverse_fct_t *fct);

/**	Get last error code occured.
	@param	dbp	Database.
	@param	res	Flag: Reset error code.
	@return	Error code for last error.
*/
int
dk3dbi_get_error(dk3_dbi_t *dbp, int res);

/**	Close database.
	@param	dbp	Database to close.
	@return	1 on success (sync ok), 0 on error.
*/
int
dk3dbi_close(dk3_dbi_t *dbp);

/**	Delete database file(s).
	@param	fn	Database file name.
	@param	tp	Database type.
	@param	app	Application structure for diagnostics, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_dbfile_delete_app(dkChar const *fn, int tp, dk3_app_t *app);

/**	Truncate database (remove all contents).
	@param	fn	Database file name.
	@param	tp	Database type.
	@param	app	Application structure for diagnostics, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_dbfile_truncate_app(dkChar const *fn, int tp, dk3_app_t *app);

/**	Delete database file(s).
	@param	fn	Database file name.
	@param	tp	Database type.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_dbfile_delete(dkChar const *fn, int tp);

/**	Truncate database (remove all contents).
	@param	fn	Database file name.
	@param	tp	Database type.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_dbfile_truncate(dkChar const *fn, int tp);

/**	Split a given name into database type and real file name.
	The given name may be either a file name with tp set to a
	database type or
	"mem::file", "bdb::file", or "ndbm::file" to specify a file name
	and database type with tp set to DK3_DB_TYPE_UNKNOWN.
	@param	myfn	Pointer to a pointer to receive real file name.
	@param	mytp	Pointer to type output variable.
	@param	fn	File name or type::filename.
	@param	tp	Type as specified.
	@param	pec	Pointer to error code variable.
	@param	app	Application structure for diagnostics, may be NULL.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_find_type_and_name(
  dkChar const	**myfn,
  int		 *mytp,
  dkChar const	 *fn,
  int		  tp,
  int		 *pec,
  dk3_app_t	 *app
);


#if !DK3_ON_WINDOWS
#if DK3_CHAR_SIZE == 1
#if DK3_HAVE_CHOWN && DK3_HAVE_CHMOD
/**	Change user name and permissions for a database.
	This function is intended for daemons on *x systems where the daemon
	is started by user root but gives up privileges before starting
	processing.
	@param	db	Database to change.
	@param	uid	New user ID.
	@param	gid	New group ID.
	@param	mode	Unix/Linux permissions.
	@return	1 on success, 0 on error.
*/
int
dk3dbi_change_user_and_permissions(
  dk3_dbi_t		*db,
  uid_t			 uid,
  gid_t			 gid,
  mode_t		 mode
);
#endif
#endif
#endif

#ifdef __cplusplus
}
#endif


#endif