hamsterdb Embedded Database  2.1.7
hamsterdb.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2005-2014 Christoph Rupp (chris@crupp.de).
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
107 #ifndef HAM_HAMSTERDB_H__
108 #define HAM_HAMSTERDB_H__
109 
110 #include <ham/types.h>
111 
112 #ifdef __cplusplus
113 extern "C" {
114 #endif
115 
122 #define HAM_API_REVISION 2
123 
130 struct ham_db_t;
131 typedef struct ham_db_t ham_db_t;
132 
139 struct ham_env_t;
140 typedef struct ham_env_t ham_env_t;
141 
151 struct ham_cursor_t;
152 typedef struct ham_cursor_t ham_cursor_t;
153 
177 typedef struct {
180 
182  void *data;
183 
186 
189 
192 
195 
198 
199 } ham_record_t;
200 
204 #define HAM_RECORD_USER_ALLOC 1
205 
232 typedef struct {
235 
237  void *data;
238 
241 
244 
245 } ham_key_t;
246 
250 #define HAM_KEY_USER_ALLOC 1
251 
269 typedef struct {
272 
275 
277 
278 
285 #define HAM_TYPE_BINARY 0
286 
287 #define HAM_TYPE_CUSTOM 1
288 
289 #define HAM_TYPE_UINT8 3
290 
291 #define HAM_TYPE_UINT16 5
292 
293 #define HAM_TYPE_UINT32 7
294 
295 #define HAM_TYPE_UINT64 9
296 
297 #define HAM_TYPE_REAL32 11
298 
299 #define HAM_TYPE_REAL64 12
300 
312 #define HAM_SUCCESS ( 0)
313 
314 #define HAM_INV_RECORD_SIZE ( -2)
315 
316 #define HAM_INV_KEY_SIZE ( -3)
317 /* deprecated */
318 #define HAM_INV_KEYSIZE HAM_INV_KEY_SIZE
319 
320 #define HAM_INV_PAGE_SIZE ( -4)
321 /* deprecated */
322 #define HAM_INV_PAGESIZE HAM_INV_PAGE_SIZE
323 
324 #define HAM_OUT_OF_MEMORY ( -6)
325 
326 #define HAM_INV_PARAMETER ( -8)
327 
328 #define HAM_INV_FILE_HEADER ( -9)
329 
330 #define HAM_INV_FILE_VERSION (-10)
331 
332 #define HAM_KEY_NOT_FOUND (-11)
333 
334 #define HAM_DUPLICATE_KEY (-12)
335 
336 #define HAM_INTEGRITY_VIOLATED (-13)
337 
338 #define HAM_INTERNAL_ERROR (-14)
339 
340 #define HAM_WRITE_PROTECTED (-15)
341 
342 #define HAM_BLOB_NOT_FOUND (-16)
343 
344 #define HAM_IO_ERROR (-18)
345 
346 #define HAM_NOT_IMPLEMENTED (-20)
347 
348 #define HAM_FILE_NOT_FOUND (-21)
349 
350 #define HAM_WOULD_BLOCK (-22)
351 
352 #define HAM_NOT_READY (-23)
353 
354 #define HAM_LIMITS_REACHED (-24)
355 
356 #define HAM_ALREADY_INITIALIZED (-27)
357 
358 #define HAM_NEED_RECOVERY (-28)
359 
360 #define HAM_CURSOR_STILL_OPEN (-29)
361 
362 #define HAM_FILTER_NOT_FOUND (-30)
363 
364 #define HAM_TXN_CONFLICT (-31)
365 /* internal use: key was erased in a Transaction */
366 #define HAM_KEY_ERASED_IN_TXN (-32)
367 
368 #define HAM_TXN_STILL_OPEN (-33)
369 
370 #define HAM_CURSOR_IS_NIL (-100)
371 
372 #define HAM_DATABASE_NOT_FOUND (-200)
373 
374 #define HAM_DATABASE_ALREADY_EXISTS (-201)
375 
376 #define HAM_DATABASE_ALREADY_OPEN (-202)
377 
378 #define HAM_ENVIRONMENT_ALREADY_OPEN (-203)
379 
380 #define HAM_LOG_INV_FILE_HEADER (-300)
381 
382 #define HAM_NETWORK_ERROR (-400)
383 
411 typedef void HAM_CALLCONV (*ham_errhandler_fun)(int level, const char *message);
412 
414 #define HAM_DEBUG_LEVEL_DEBUG 0
415 
417 #define HAM_DEBUG_LEVEL_NORMAL 1
418 
420 #define HAM_DEBUG_LEVEL_FATAL 3
421 
439 
447 HAM_EXPORT const char * HAM_CALLCONV
448 ham_strerror(ham_status_t status);
449 
458 ham_get_version(ham_u32_t *major, ham_u32_t *minor,
459  ham_u32_t *revision);
460 
469 ham_get_license(const char **licensee, const char **product);
470 
589 ham_env_create(ham_env_t **env, const char *filename,
590  ham_u32_t flags, ham_u32_t mode, const ham_parameter_t *param);
591 
676 ham_env_open(ham_env_t **env, const char *filename,
677  ham_u32_t flags, const ham_parameter_t *param);
678 
713 
828  ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
829 
868  ham_u16_t name, ham_u32_t flags, const ham_parameter_t *params);
869 
896  ham_u16_t newname, ham_u32_t flags);
897 
917 ham_env_erase_db(ham_env_t *env, ham_u16_t name, ham_u32_t flags);
918 
935 ham_env_flush(ham_env_t *env, ham_u32_t flags);
936 
937 /* internal use only - don't lock mutex */
938 #define HAM_DONT_LOCK 0xf0000000
939 
964  ham_u32_t *count);
965 
1004 ham_env_close(ham_env_t *env, ham_u32_t flags);
1005 
1022 struct ham_txn_t;
1023 typedef struct ham_txn_t ham_txn_t;
1024 
1054 ham_txn_begin(ham_txn_t **txn, ham_env_t *env, const char *name,
1055  void *reserved, ham_u32_t flags);
1056 
1058 #define HAM_TXN_READ_ONLY 1
1059 
1060 /* Internal flag for @ref ham_txn_begin */
1061 #define HAM_TXN_TEMPORARY 2
1062 
1068 HAM_EXPORT const char *
1070 
1090 ham_txn_commit(ham_txn_t *txn, ham_u32_t flags);
1091 
1111 ham_txn_abort(ham_txn_t *txn, ham_u32_t flags);
1112 
1125 #define HAM_ENABLE_FSYNC 0x00000001
1126 
1127 /* unused 0x00000002 */
1128 
1131 #define HAM_READ_ONLY 0x00000004
1132 
1133 /* unused 0x00000008 */
1134 
1135 /* unused 0x00000010 */
1136 
1137 /* reserved 0x00000020 */
1138 
1139 /* unused 0x00000040 */
1140 
1143 #define HAM_IN_MEMORY 0x00000080
1144 
1145 /* reserved: DB_USE_MMAP (not persistent) 0x00000100 */
1146 
1149 #define HAM_DISABLE_MMAP 0x00000200
1150 
1153 #define HAM_RECORD_NUMBER 0x00002000
1154 
1157 #define HAM_ENABLE_DUPLICATE_KEYS 0x00004000
1158 /* deprecated */
1159 #define HAM_ENABLE_DUPLICATES HAM_ENABLE_DUPLICATE_KEYS
1160 
1163 #define HAM_ENABLE_RECOVERY 0x00008000
1164 
1167 #define HAM_AUTO_RECOVERY 0x00010000
1168 
1171 #define HAM_ENABLE_TRANSACTIONS 0x00020000
1172 
1175 #define HAM_CACHE_UNLIMITED 0x00040000
1176 
1179 #define HAM_DISABLE_RECOVERY 0x00080000
1180 
1181 /* internal use only! (not persistent) */
1182 #define HAM_IS_REMOTE_INTERNAL 0x00200000
1183 
1184 /* internal use only! (not persistent) */
1185 #define HAM_DISABLE_RECLAIM_INTERNAL 0x00400000
1186 
1187 /* internal use only! (persistent) */
1188 #define HAM_FORCE_RECORDS_INLINE 0x00800000
1189 
1192 #define HAM_FLUSH_WHEN_COMMITTED 0x01000000
1193 
1205 
1215  const ham_u8_t *lhs, ham_u32_t lhs_length,
1216  const ham_u8_t *rhs, ham_u32_t rhs_length);
1217 
1239 
1366 ham_db_find(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
1367  ham_record_t *record, ham_u32_t flags);
1368 
1450 ham_db_insert(ham_db_t *db, ham_txn_t *txn, ham_key_t *key,
1451  ham_record_t *record, ham_u32_t flags);
1452 
1464 #define HAM_OVERWRITE 0x0001
1465 
1467 #define HAM_DUPLICATE 0x0002
1468 
1470 #define HAM_DUPLICATE_INSERT_BEFORE 0x0004
1471 
1473 #define HAM_DUPLICATE_INSERT_AFTER 0x0008
1474 
1476 #define HAM_DUPLICATE_INSERT_FIRST 0x0010
1477 
1479 #define HAM_DUPLICATE_INSERT_LAST 0x0020
1480 
1482 #define HAM_DIRECT_ACCESS 0x0040
1483 
1486 #define HAM_PARTIAL 0x0080
1487 
1500 #define HAM_HINT_APPEND 0x00080000
1501 
1514 #define HAM_HINT_PREPEND 0x00100000
1515 
1520 #define HAM_HINTS_MASK 0x001F0000
1521 
1546 ham_db_erase(ham_db_t *db, ham_txn_t *txn, ham_key_t *key, ham_u32_t flags);
1547 
1548 /* internal flag for ham_db_erase() - do not use */
1549 #define HAM_ERASE_ALL_DUPLICATES 1
1550 
1574  ham_u64_t *keycount);
1575 
1610 
1613 #define HAM_PARAM_CACHE_SIZE 0x00000100
1614 /* deprecated */
1615 #define HAM_PARAM_CACHESIZE HAM_PARAM_CACHE_SIZE
1616 
1618 #define HAM_PARAM_PAGE_SIZE 0x00000101
1619 /* deprecated */
1620 #define HAM_PARAM_PAGESIZE HAM_PARAM_PAGE_SIZE
1621 
1623 #define HAM_PARAM_KEY_SIZE 0x00000102
1624 /* deprecated */
1625 #define HAM_PARAM_KEYSIZE HAM_PARAM_KEY_SIZE
1626 
1629 #define HAM_PARAM_MAX_DATABASES 0x00000103
1630 
1632 #define HAM_PARAM_KEY_TYPE 0x00000104
1633 
1636 #define HAM_PARAM_LOG_DIRECTORY 0x00000105
1637 
1640 #define HAM_PARAM_ENCRYPTION_KEY 0x00000106
1641 
1644 #define HAM_PARAM_NETWORK_TIMEOUT_SEC 0x00000107
1645 
1647 #define HAM_PARAM_RECORD_SIZE 0x00000108
1648 
1650 #define HAM_RECORD_SIZE_UNLIMITED ((ham_u32_t)-1)
1651 
1653 #define HAM_KEY_SIZE_UNLIMITED ((ham_u16_t)-1)
1654 
1657 #define HAM_PARAM_FLAGS 0x00000200
1658 
1661 #define HAM_PARAM_FILEMODE 0x00000201
1662 
1670 #define HAM_PARAM_FILENAME 0x00000202
1671 
1676 #define HAM_PARAM_DATABASE_NAME 0x00000203
1677 
1683 #define HAM_PARAM_MAX_KEYS_PER_PAGE 0x00000204
1684 
1689 #define HAM_PARAM_JOURNAL_COMPRESSION 0x1000
1690 
1696 #define HAM_PARAM_RECORD_COMPRESSION 0x1001
1697 
1703 #define HAM_PARAM_KEY_COMPRESSION 0x1002
1704 
1706 #define HAM_COMPRESSOR_NONE 0
1707 
1709 #define HAM_COMPRESSOR_ZLIB 1
1710 
1715 #define HAM_COMPRESSOR_SNAPPY 2
1716 
1721 #define HAM_COMPRESSOR_LZF 3
1722 
1727 #define HAM_COMPRESSOR_LZO 4
1728 
1738 
1764 
1800 ham_db_close(ham_db_t *db, ham_u32_t flags);
1801 
1803 #define HAM_AUTO_CLEANUP 1
1804 
1806 #define HAM_DONT_CLEAR_LOG 2
1807 
1809 #define HAM_TXN_AUTO_ABORT 4
1810 
1812 #define HAM_TXN_AUTO_COMMIT 8
1813 
1852 ham_cursor_create(ham_cursor_t **cursor, ham_db_t *db, ham_txn_t *txn,
1853  ham_u32_t flags);
1854 
1875 
1992 ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key,
1993  ham_record_t *record, ham_u32_t flags);
1994 
1996 #define HAM_CURSOR_FIRST 0x0001
1997 
1999 #define HAM_CURSOR_LAST 0x0002
2000 
2002 #define HAM_CURSOR_NEXT 0x0004
2003 
2005 #define HAM_CURSOR_PREVIOUS 0x0008
2006 
2008 #define HAM_SKIP_DUPLICATES 0x0010
2009 
2011 #define HAM_ONLY_DUPLICATES 0x0020
2012 
2033  ham_u32_t flags);
2034 
2188 ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key,
2189  ham_record_t *record, ham_u32_t flags);
2190 
2199 #define HAM_FIND_EXACT_MATCH 0x4000
2200 
2207 #define HAM_FIND_LT_MATCH 0x1000
2208 
2215 #define HAM_FIND_GT_MATCH 0x2000
2216 
2226 #define HAM_FIND_LEQ_MATCH (HAM_FIND_LT_MATCH | HAM_FIND_EXACT_MATCH)
2227 
2237 #define HAM_FIND_GEQ_MATCH (HAM_FIND_GT_MATCH | HAM_FIND_EXACT_MATCH)
2238 
2254 #define HAM_FIND_NEAR_MATCH (HAM_FIND_LT_MATCH | HAM_FIND_GT_MATCH \
2255  | HAM_FIND_EXACT_MATCH)
2256 
2371  ham_record_t *record, ham_u32_t flags);
2372 
2395 ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
2396 
2416  ham_u32_t *count, ham_u32_t flags);
2417 
2432 
2449 
2454 #ifdef __cplusplus
2455 } // extern "C"
2456 #endif
2457 
2458 #endif /* HAM_HAMSTERDB_H__ */