ObjectBox C and C++ API  0.12.0
ObjectBox C API

Classes

struct  OBX_bytes
 Bytes struct is an input/output wrapper typically used for a single object data (represented as FlatBuffers). More...
 
struct  OBX_bytes_array
 Bytes array struct is an input/output wrapper for multiple FlatBuffers object data representation. More...
 
struct  OBX_id_array
 ID array struct is an input/output wrapper for an array of object IDs. More...
 
struct  OBX_string_array
 String array struct is an input/output wrapper for an array of character strings. More...
 
struct  OBX_int64_array
 Int64 array struct is an input/output wrapper for an array of int64 numbers. More...
 
struct  OBX_int32_array
 Int32 array struct is an input/output wrapper for an array of int32 numbers. More...
 
struct  OBX_int16_array
 Int16 array struct is an input/output wrapper for an array of int16 numbers. More...
 
struct  OBX_int8_array
 Int8 array struct is an input/output wrapper for an array of int8 numbers. More...
 
struct  OBX_double_array
 Double array struct is an input/output wrapper for an array of double precision floating point numbers. More...
 
struct  OBX_float_array
 Float array struct is an input/output wrapper for an array of single precision floating point numbers. More...
 
struct  OBX_sync_change
 
struct  OBX_sync_change_array
 

Macros

#define OBX_VERSION_MAJOR   0
 When using ObjectBox as a dynamic library, you should verify that a compatible version was linked using obx_version() or obx_version_is_at_least(). More...
 
#define OBX_VERSION_MINOR   12
 
#define OBX_VERSION_PATCH   0
 
#define OBX_ID_NEW   0xFFFFFFFFFFFFFFFF
 To be used for putting objects with prepared ID slots, e.g. obx_cursor_put_object(). More...
 
#define OBX_SUCCESS   0
 Value returned when no error occurred (0) More...
 
#define OBX_NOT_FOUND   404
 Returned by, e.g., get operations if nothing was found for a specific ID. This is NOT an error condition, and thus no "last error" info (code/text) is set. More...
 
#define OBX_NO_SUCCESS   1001
 Indicates that a function had "no success", which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set. More...
 
#define OBX_TIMEOUT   1002
 Indicates that a function reached a time out, which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set. More...
 
#define OBX_ERROR_ILLEGAL_STATE   10001
 
#define OBX_ERROR_ILLEGAL_ARGUMENT   10002
 
#define OBX_ERROR_ALLOCATION   10003
 
#define OBX_ERROR_NUMERIC_OVERFLOW   10004
 
#define OBX_ERROR_NO_ERROR_INFO   10097
 
#define OBX_ERROR_GENERAL   10098
 
#define OBX_ERROR_UNKNOWN   10099
 
#define OBX_ERROR_DB_FULL   10101
 
#define OBX_ERROR_MAX_READERS_EXCEEDED   10102
 
#define OBX_ERROR_STORE_MUST_SHUTDOWN   10103
 
#define OBX_ERROR_STORAGE_GENERAL   10199
 
#define OBX_ERROR_UNIQUE_VIOLATED   10201
 
#define OBX_ERROR_NON_UNIQUE_RESULT   10202
 
#define OBX_ERROR_PROPERTY_TYPE_MISMATCH   10203
 
#define OBX_ERROR_ID_ALREADY_EXISTS   10210
 
#define OBX_ERROR_ID_NOT_FOUND   10211
 
#define OBX_ERROR_TIME_SERIES   10212
 
#define OBX_ERROR_CONSTRAINT_VIOLATED   10299
 
#define OBX_ERROR_STD_ILLEGAL_ARGUMENT   10301
 
#define OBX_ERROR_STD_OUT_OF_RANGE   10302
 
#define OBX_ERROR_STD_LENGTH   10303
 
#define OBX_ERROR_STD_BAD_ALLOC   10304
 
#define OBX_ERROR_STD_RANGE   10305
 
#define OBX_ERROR_STD_OVERFLOW   10306
 
#define OBX_ERROR_STD_OTHER   10399
 
#define OBX_ERROR_SCHEMA   10501
 
#define OBX_ERROR_FILE_CORRUPT   10502
 DB file has errors, e.g. illegal values or structural inconsistencies were detected. More...
 
#define OBX_ERROR_FILE_PAGES_CORRUPT   10503
 DB file has errors related to pages, e.g. bad page refs outside of the file. More...
 
#define OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND   10504
 A requested schema object (e.g., an entity or a property) was not found in the schema. More...
 
#define OBX_ERROR_TIME_SERIES_NOT_AVAILABLE   10601
 Feature specific errors. More...
 
#define OBX_ERROR_SYNC_NOT_AVAILABLE   10602
 

Typedefs

typedef uint32_t obx_schema_id
 Schema entity & property identifiers. More...
 
typedef uint64_t obx_uid
 Universal identifier used in schema for entities & properties. More...
 
typedef uint64_t obx_id
 ID of a single Object stored in the database. More...
 
typedef int obx_err
 Error/success code returned by an obx_* function; see defines OBX_SUCCESS, OBX_NOT_FOUND, and OBX_ERROR_*. More...
 
typedef bool obx_data_visitor(void *user_data, const void *data, size_t size)
 The callback for reading data one-by-one. More...
 
typedef struct OBX_model OBX_model
 
typedef struct OBX_store OBX_store
 
typedef struct OBX_store_options OBX_store_options
 
typedef struct OBX_bytes OBX_bytes
 Bytes struct is an input/output wrapper typically used for a single object data (represented as FlatBuffers). More...
 
typedef struct OBX_bytes_array OBX_bytes_array
 Bytes array struct is an input/output wrapper for multiple FlatBuffers object data representation. More...
 
typedef struct OBX_id_array OBX_id_array
 ID array struct is an input/output wrapper for an array of object IDs. More...
 
typedef struct OBX_string_array OBX_string_array
 String array struct is an input/output wrapper for an array of character strings. More...
 
typedef struct OBX_int64_array OBX_int64_array
 Int64 array struct is an input/output wrapper for an array of int64 numbers. More...
 
typedef struct OBX_int32_array OBX_int32_array
 Int32 array struct is an input/output wrapper for an array of int32 numbers. More...
 
typedef struct OBX_int16_array OBX_int16_array
 Int16 array struct is an input/output wrapper for an array of int16 numbers. More...
 
typedef struct OBX_int8_array OBX_int8_array
 Int8 array struct is an input/output wrapper for an array of int8 numbers. More...
 
typedef struct OBX_double_array OBX_double_array
 Double array struct is an input/output wrapper for an array of double precision floating point numbers. More...
 
typedef struct OBX_float_array OBX_float_array
 Float array struct is an input/output wrapper for an array of single precision floating point numbers. More...
 
typedef struct OBX_txn OBX_txn
 
typedef struct OBX_cursor OBX_cursor
 
typedef struct OBX_box OBX_box
 
typedef struct OBX_async OBX_async
 
typedef struct OBX_query_builder OBX_query_builder
 
typedef int obx_qb_cond
 Query Builder condition identifier. More...
 
typedef struct OBX_query OBX_query
 
typedef struct OBX_query_prop OBX_query_prop
 
typedef struct OBX_observer OBX_observer
 
typedef void obx_observer(void *user_data, const obx_schema_id *type_ids, size_t type_ids_count)
 Callback for obx_observe() More...
 
typedef void obx_observer_single_type(void *user_data)
 Callback for obx_observe_single_type() More...
 
typedef struct OBX_sync OBX_sync
 
typedef struct OBX_sync_change OBX_sync_change
 
typedef struct OBX_sync_change_array OBX_sync_change_array
 
typedef void OBX_sync_listener_connect(void *arg)
 Called when connection is established. More...
 
typedef void OBX_sync_listener_disconnect(void *arg)
 Called when connection is closed/lost. More...
 
typedef void OBX_sync_listener_login(void *arg)
 Called on successful login. More...
 
typedef void OBX_sync_listener_login_failure(void *arg, OBXSyncCode code)
 Called on a login failure. More...
 
typedef void OBX_sync_listener_complete(void *arg)
 Called when synchronization is complete. More...
 
typedef void OBX_sync_listener_change(void *arg, const OBX_sync_change_array *changes)
 Called with fine grained sync changes (IDs of put and removed entities) More...
 

Enumerations

enum  OBXFeature {
  OBXFeature_ResultArray = 1, OBXFeature_TimeSeries = 2, OBXFeature_Sync = 3, OBXFeature_DebugLog = 4,
  OBXFeature_ObjectBrowser = 5
}
 
enum  OBXPropertyType {
  OBXPropertyType_Bool = 1, OBXPropertyType_Byte = 2, OBXPropertyType_Short = 3, OBXPropertyType_Char = 4,
  OBXPropertyType_Int = 5, OBXPropertyType_Long = 6, OBXPropertyType_Float = 7, OBXPropertyType_Double = 8,
  OBXPropertyType_String = 9, OBXPropertyType_Date = 10, OBXPropertyType_Relation = 11, OBXPropertyType_DateNano = 12,
  OBXPropertyType_ByteVector = 23, OBXPropertyType_StringVector = 30
}
 
enum  OBXEntityFlags { OBXEntityFlags_SYNC_ENABLED = 2, OBXEntityFlags_SHARED_GLOBAL_IDS = 4 }
 Bit-flags defining the behavior of entities. Note: Numbers indicate the bit position. More...
 
enum  OBXPropertyFlags {
  OBXPropertyFlags_ID = 1, OBXPropertyFlags_NON_PRIMITIVE_TYPE = 2, OBXPropertyFlags_NOT_NULL = 4, OBXPropertyFlags_INDEXED = 8,
  OBXPropertyFlags_RESERVED = 16, OBXPropertyFlags_UNIQUE = 32, OBXPropertyFlags_ID_MONOTONIC_SEQUENCE = 64, OBXPropertyFlags_ID_SELF_ASSIGNABLE = 128,
  OBXPropertyFlags_INDEX_PARTIAL_SKIP_NULL = 256, OBXPropertyFlags_INDEX_PARTIAL_SKIP_ZERO = 512, OBXPropertyFlags_VIRTUAL = 1024, OBXPropertyFlags_INDEX_HASH = 2048,
  OBXPropertyFlags_INDEX_HASH64 = 4096, OBXPropertyFlags_UNSIGNED = 8192, OBXPropertyFlags_ID_COMPANION = 16384
}
 Bit-flags defining the behavior of properties. Note: Numbers indicate the bit position. More...
 
enum  OBXDebugFlags {
  OBXDebugFlags_LOG_TRANSACTIONS_READ = 1, OBXDebugFlags_LOG_TRANSACTIONS_WRITE = 2, OBXDebugFlags_LOG_QUERIES = 4, OBXDebugFlags_LOG_QUERY_PARAMETERS = 8,
  OBXDebugFlags_LOG_ASYNC_QUEUE = 16
}
 
enum  OBXPutPaddingMode { OBXPutPaddingMode_PaddingAutomatic = 1, OBXPutPaddingMode_PaddingAllowedByBuffer = 2, OBXPutPaddingMode_PaddingByCaller = 3 }
 Defines a padding mode for putting data bytes. Depending on how that data is created, this mode may optimize data handling by avoiding copying memory. Internal background: data buffers used by put operations are required to have a size divisible by 4 for an efficient data layout. More...
 
enum  OBXPutMode { OBXPutMode_PUT = 1, OBXPutMode_INSERT = 2, OBXPutMode_UPDATE = 3 }
 
enum  OBXOrderFlags {
  OBXOrderFlags_DESCENDING = 1, OBXOrderFlags_CASE_SENSITIVE = 2, OBXOrderFlags_UNSIGNED = 4, OBXOrderFlags_NULLS_LAST = 8,
  OBXOrderFlags_NULLS_ZERO = 16
}
 Not really an enum, but binary flags to use across languages. More...
 
enum  OBXSyncCredentialsType { OBXSyncCredentialsType_NONE = 0, OBXSyncCredentialsType_SHARED_SECRET = 1, OBXSyncCredentialsType_GOOGLE_AUTH = 2 }
 
enum  OBXRequestUpdatesMode { OBXRequestUpdatesMode_MANUAL = 0, OBXRequestUpdatesMode_AUTO = 1, OBXRequestUpdatesMode_AUTO_NO_PUSHES = 2 }
 
enum  OBXSyncState {
  OBXSyncState_CREATED = 1, OBXSyncState_STARTED = 2, OBXSyncState_CONNECTED = 3, OBXSyncState_LOGGED_IN = 4,
  OBXSyncState_DISCONNECTED = 5, OBXSyncState_STOPPED = 6, OBXSyncState_DEAD = 7
}
 
enum  OBXSyncCode {
  OBXSyncCode_OK = 20, OBXSyncCode_REQ_REJECTED = 40, OBXSyncCode_CREDENTIALS_REJECTED = 43, OBXSyncCode_UNKNOWN = 50,
  OBXSyncCode_AUTH_UNREACHABLE = 53, OBXSyncCode_BAD_VERSION = 55, OBXSyncCode_CLIENT_ID_TAKEN = 61, OBXSyncCode_TX_VIOLATED_UNIQUE = 71
}
 

Functions

void obx_version (int *major, int *minor, int *patch)
 Return the version of the library as ints. Pointers may be null. More...
 
bool obx_version_is_at_least (int major, int minor, int patch)
 Check if the version of the library is equal to or higher than the given version ints. More...
 
const char * obx_version_string (void)
 Return the version of the library to be printed. The format may change in any future release; only use for information purposes. More...
 
const char * obx_version_core_string (void)
 Return the version of the ObjectBox core to be printed. The format may change in any future release; only use for information purposes. More...
 
bool obx_has_feature (OBXFeature feature)
 Checks whether the given feature is available in the currently loaded library. More...
 
bool obx_supports_bytes_array (void)
 Check whether functions returning OBX_bytes_array are fully supported (depends on build, invariant during runtime) More...
 
bool obx_supports_time_series (void)
 Check whether time series functions are available in the version of this library. More...
 
obx_err obx_remove_db_files (char const *directory)
 Delete the store files from the given directory. More...
 
bool obx_last_error_pop (obx_err *out_error, const char **out_message)
 Return the error status on the current thread and clear the error state. The buffer returned in out_message is valid only until the next call into ObjectBox. More...
 
obx_err obx_last_error_code (void)
 The last error raised by an ObjectBox API call on the current thread, or OBX_SUCCESS if no error occurred yet. Note that API calls do not clear this error code (also true for this method). Thus, if you receive an error from this, it's usually a good idea to call obx_last_error_clear() to clear the error state (or use obx_last_error_pop()) for future API calls. More...
 
const char * obx_last_error_message (void)
 The error message string attached to the error returned by obx_last_error_code(). Like obx_last_error_code(), this is bound to the current thread, and this call does not clear the error state. The buffer returned is valid only until the next call into ObjectBox. More...
 
obx_err obx_last_error_secondary (void)
 The underlying error for the error returned by obx_last_error_code(). Where obx_last_error_code() may be a generic error like OBX_ERROR_STORAGE_GENERAL, this will give a further underlying and possibly platform-specific error code. More...
 
void obx_last_error_clear (void)
 Clear the error state on the current thread; e.g. obx_last_error_code() will now return OBX_SUCCESS. Note that clearing the error state does not happen automatically; API calls set the error state when they produce an error, but do not clear it on success. See also: obx_last_error_pop() to retrieve the error state and clear it. More...
 
bool obx_last_error_set (obx_err code, obx_err secondary, const char *message)
 Set the last error code and test - reserved for internal use from generated code. More...
 
OBX_modelobx_model (void)
 Create an (empty) data meta model which is to be consumed by obx_opt_model(). More...
 
obx_err obx_model_free (OBX_model *model)
 Only call when not calling obx_store_open() (which will free it internally) More...
 
obx_err obx_model_error_code (OBX_model *model)
 To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred. More...
 
const char * obx_model_error_message (OBX_model *model)
 To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred. More...
 
obx_err obx_model_entity (OBX_model *model, const char *name, obx_schema_id entity_id, obx_uid entity_uid)
 Starts the definition of a new entity type for the meta data model. After this, call obx_model_property() to add properties to the entity type. More...
 
obx_err obx_model_entity_flags (OBX_model *model, OBXEntityFlags flags)
 Refine the definition of the entity declared by the most recent obx_model_entity() call, specifying flags. More...
 
obx_err obx_model_property (OBX_model *model, const char *name, OBXPropertyType type, obx_schema_id property_id, obx_uid property_uid)
 Starts the definition of a new property for the entity type of the last obx_model_entity() call. More...
 
obx_err obx_model_property_flags (OBX_model *model, OBXPropertyFlags flags)
 Refine the definition of the property declared by the most recent obx_model_property() call, specifying flags. More...
 
obx_err obx_model_property_relation (OBX_model *model, const char *target_entity, obx_schema_id index_id, obx_uid index_uid)
 Refine the definition of the property declared by the most recent obx_model_property() call, declaring it a relation. More...
 
obx_err obx_model_property_index_id (OBX_model *model, obx_schema_id index_id, obx_uid index_uid)
 Refine the definition of the property declared by the most recent obx_model_property() call, adding an index. More...
 
obx_err obx_model_relation (OBX_model *model, obx_schema_id relation_id, obx_uid relation_uid, obx_schema_id target_id, obx_uid target_uid)
 Add a standalone relation between the active entity and the target entity to the model. More...
 
void obx_model_last_entity_id (OBX_model *, obx_schema_id entity_id, obx_uid entity_uid)
 Set the highest ever known entity id in the model. Should always be equal to or higher than the last entity id of the previous version of the model. More...
 
void obx_model_last_index_id (OBX_model *model, obx_schema_id index_id, obx_uid index_uid)
 Set the highest ever known index id in the model. Should always be equal to or higher than the last index id of the previous version of the model. More...
 
void obx_model_last_relation_id (OBX_model *model, obx_schema_id relation_id, obx_uid relation_uid)
 Set the highest every known relation id in the model. Should always be equal to or higher than the last relation id of the previous version of the model. More...
 
obx_err obx_model_entity_last_property_id (OBX_model *model, obx_schema_id property_id, obx_uid property_uid)
 Set the highest ever known property id in the entity. Should always be equal to or higher than the last property id of the previous version of the entity. More...
 
OBX_store_optionsobx_opt ()
 Create a default set of store options. More...
 
obx_err obx_opt_directory (OBX_store_options *opt, const char *dir)
 Set the store directory on the options. The default is "objectbox". More...
 
void obx_opt_max_db_size_in_kb (OBX_store_options *opt, size_t size_in_kb)
 Set the maximum db size on the options. The default is 1Gb. More...
 
void obx_opt_file_mode (OBX_store_options *opt, unsigned int file_mode)
 Set the file mode on the options. The default is 0644 (unix-style) More...
 
void obx_opt_max_readers (OBX_store_options *opt, unsigned int max_readers)
 Set the maximum number of readers on the options. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. Note: The internal default is currently around 120. So when hitting this limit, try values around 200-500. More...
 
obx_err obx_opt_model (OBX_store_options *opt, OBX_model *model)
 Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs. More...
 
obx_err obx_opt_model_bytes (OBX_store_options *opt, const void *bytes, size_t size)
 Set the model on the options copying the given bytes. The default is no model. More...
 
obx_err obx_opt_model_bytes_direct (OBX_store_options *opt, const void *bytes, size_t size)
 Like obx_opt_model_bytes BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created. More...
 
void obx_opt_validate_on_open (OBX_store_options *opt, size_t page_limit, bool leaf_level)
 When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync). More...
 
void obx_opt_put_padding_mode (OBX_store_options *opt, OBXPutPaddingMode mode)
 Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description. More...
 
void obx_opt_read_schema (OBX_store_options *opt, bool value)
 Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true. More...
 
void obx_opt_use_previous_commit (OBX_store_options *opt, bool value)
 Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false. More...
 
void obx_opt_read_only (OBX_store_options *opt, bool value)
 Open store in read-only mode: no schema update, no write transactions. Defaults to false. More...
 
void obx_opt_debug_flags (OBX_store_options *opt, OBXDebugFlags flags)
 Configure debug logging. Defaults to NONE. More...
 
void obx_opt_async_max_queue_length (OBX_store_options *opt, size_t value)
 Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too. More...
 
void obx_opt_async_throttle_at_queue_length (OBX_store_options *opt, size_t value)
 Producers (AsyncTx submitter) is throttled when the queue size hits this. More...
 
void obx_opt_async_throttle_micros (OBX_store_options *opt, uint32_t value)
 Sleeping time for throttled producers on each submission. More...
 
void obx_opt_async_max_in_tx_duration (OBX_store_options *opt, uint32_t micros)
 Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...
 
void obx_opt_async_max_in_tx_operations (OBX_store_options *opt, uint32_t value)
 Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...
 
void obx_opt_async_pre_txn_delay (OBX_store_options *opt, uint32_t delay_micros)
 Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...
 
void obx_opt_async_pre_txn_delay4 (OBX_store_options *opt, uint32_t delay_micros, uint32_t delay2_micros, size_t min_queue_length_for_delay2)
 Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...
 
void obx_opt_async_post_txn_delay (OBX_store_options *opt, uint32_t delay_micros)
 Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...
 
void obx_opt_async_post_txn_delay4 (OBX_store_options *opt, uint32_t delay_micros, uint32_t delay2_micros, size_t min_queue_length_for_delay2)
 Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...
 
void obx_opt_async_minor_refill_threshold (OBX_store_options *opt, size_t queue_length)
 Numbers of operations below this value are considered "minor refills". More...
 
void obx_opt_async_minor_refill_max_count (OBX_store_options *opt, uint32_t value)
 If non-zero, this allows "minor refills" with small batches that came in (off by default). More...
 
void obx_opt_async_max_tx_pool_size (OBX_store_options *opt, size_t value)
 Default value: 10000, set to 0 to deactivate pooling. More...
 
void obx_opt_async_object_bytes_max_cache_size (OBX_store_options *opt, uint64_t value)
 Total cache size; default: ~ 0.5 MB. More...
 
void obx_opt_async_object_bytes_max_size_to_cache (OBX_store_options *opt, uint64_t value)
 Maximal size for an object to be cached (only cache smaller ones) More...
 
void obx_opt_free (OBX_store_options *opt)
 Free the options. Note: Only free unused options, obx_store_open() frees the options internally. More...
 
OBX_storeobx_store_open (OBX_store_options *opt)
 Note: the given options are always freed by this function, including when an error occurs. More...
 
OBX_storeobx_store_wrap (void *core_store)
 For stores created outside of this C API, e.g. via C++ or Java, this is how you can use it via C too. Like this, it is OK to use the same store instance (same database) from multiple languages in parallel. Note: the store's life time will still be managed outside of the C API; thus ensure that store is not closed while calling any C function on it. Once you are done with the C specific OBX_store, call obx_store_close() to free any C related resources. This, however, will not close the "core store". More...
 
obx_schema_id obx_store_entity_id (OBX_store *store, const char *entity_name)
 Look for an entity with the given name in the model and return its Entity ID. More...
 
obx_schema_id obx_store_entity_property_id (OBX_store *store, obx_schema_id entity_id, const char *property_name)
 Return the property id from the property name or 0 if the name is not found. More...
 
bool obx_store_await_async_completion (OBX_store *store)
 Await for all (including future) async submissions to be completed (the async queue becomes idle for a moment). More...
 
bool obx_store_await_async_submitted (OBX_store *store)
 Await for previously submitted async operations to be completed (the async queue does not have to become idle). More...
 
obx_err obx_store_debug_flags (OBX_store *store, OBXDebugFlags flags)
 Configure debug logging. More...
 
bool obx_store_opened_with_previous_commit (OBX_store *store)
 
obx_err obx_store_close (OBX_store *store)
 
OBX_txnobx_txn_write (OBX_store *store)
 Create a write transaction (read and write). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. More...
 
OBX_txnobx_txn_read (OBX_store *store)
 Create a read transaction (read only). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. More...
 
obx_err obx_txn_success (OBX_txn *txn)
 "Finish" this write transaction successfully and close it, performing a commit if this is the top level transaction and all inner transactions (if any) were also successful (obx_txn_success() was called on them). Because this also closes the given transaction, the given OBX_txn pointer must not be used afterwards. More...
 
obx_err obx_txn_close (OBX_txn *txn)
 Close (free) the transaction (read or write); the given OBX_txn pointer must not be used afterwards. While this is the only way to release read transactions, this call is also an alternative to call obx_txn_success() on write transactions. In combination with obx_txn_mark_success(), this potentially commits or aborts a write transaction on the DB: 1) If it's an outermost TX and all (inner) TXs were marked successful, this commits the transaction. 2) If this transaction was not marked successful, this aborts the transaction (even if it's an inner TX). If an error is returned (e.g., a commit failed because DB is full), you can assume that the transaction was closed. More...
 
obx_err obx_txn_abort (OBX_txn *txn)
 Abort the underlying transaction immediately and thus frees DB resources. Only obx_txn_close() is allowed to be called on the transaction after calling this. More...
 
obx_err obx_txn_mark_success (OBX_txn *txn, bool wasSuccessful)
 Mark the given write transaction as successful or failed. You can call this method multiple times with different values before calling obx_txn_close() on the transaction. More...
 
OBX_cursorobx_cursor (OBX_txn *txn, obx_schema_id entity_id)
 
obx_err obx_cursor_close (OBX_cursor *cursor)
 
obx_id obx_cursor_id_for_put (OBX_cursor *cursor, obx_id id_or_zero)
 Call this when putting an object to generate/prepare an ID for it. More...
 
obx_err obx_cursor_put (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
 Puts the given object data using the given ID. A "put" in ObjectBox follows "insert or update" semantics; New objects (no pre-existing object for given ID) are inserted while existing objects are replaced/updated. More...
 
obx_err obx_cursor_put4 (OBX_cursor *cursor, obx_id id, const void *data, size_t size, OBXPutMode mode)
 Like put obx_cursor_put(), but takes an additional parameter (4th parameter) for choosing a put mode. More...
 
obx_err obx_cursor_put_new (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
 An optimized version of obx_cursor_put() if you can ensure that the given ID is not used yet. Typically used right after getting a new ID via obx_cursor_id_for_put(). WARNING: using this incorrectly (an object with the given ID already exists) may result in inconsistent data (e.g. indexes do not get updated). More...
 
obx_err obx_cursor_insert (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
 Convenience for obx_cursor_put4() with OBXPutMode_INSERT. More...
 
obx_err obx_cursor_update (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
 Convenience for obx_cursor_put4() with OBXPutMode_UPDATE. More...
 
obx_id obx_cursor_put_object (OBX_cursor *cursor, void *data, size_t size)
 FB ID slot must be present; new entities must prepare the slot using the special value OBX_ID_NEW. Alternatively, you may also pass 0 to indicate a new entity if you are aware that FlatBuffers builders typically skip zero values by default. Thus, you have to "force" writing the zero in FlatBuffers. More...
 
obx_id obx_cursor_put_object4 (OBX_cursor *cursor, void *data, size_t size, OBXPutMode mode)
 
obx_err obx_cursor_get (OBX_cursor *cursor, obx_id id, const void **data, size_t *size)
 
OBX_bytes_arrayobx_cursor_get_all (OBX_cursor *cursor)
 Get all objects as bytes. For larger quantities, it's recommended to iterate using obx_cursor_first and obx_cursor_next. However, if the calling overhead is high (e.g., for language bindings), this method helps. More...
 
obx_err obx_cursor_first (OBX_cursor *cursor, const void **data, size_t *size)
 
obx_err obx_cursor_next (OBX_cursor *cursor, const void **data, size_t *size)
 
obx_err obx_cursor_seek (OBX_cursor *cursor, obx_id id)
 
obx_err obx_cursor_current (OBX_cursor *cursor, const void **data, size_t *size)
 
obx_err obx_cursor_remove (OBX_cursor *cursor, obx_id id)
 
obx_err obx_cursor_remove_all (OBX_cursor *cursor)
 
obx_err obx_cursor_count (OBX_cursor *cursor, uint64_t *count)
 Count the number of available objects. More...
 
obx_err obx_cursor_count_max (OBX_cursor *cursor, uint64_t max_count, uint64_t *out_count)
 Count the number of available objects up to the specified maximum. More...
 
obx_err obx_cursor_is_empty (OBX_cursor *cursor, bool *out_is_empty)
 Return true if there is no object available (false if at least one object is available) More...
 
OBX_bytes_arrayobx_cursor_backlinks (OBX_cursor *cursor, obx_schema_id entity_id, obx_schema_id property_id, obx_id id)
 
OBX_id_arrayobx_cursor_backlink_ids (OBX_cursor *cursor, obx_schema_id entity_id, obx_schema_id property_id, obx_id id)
 
obx_err obx_cursor_rel_put (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
 
obx_err obx_cursor_rel_remove (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
 
OBX_id_arrayobx_cursor_rel_ids (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id)
 
obx_err obx_cursor_ts_min_max (OBX_cursor *cursor, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
 Time series: get the limits (min/max time values) over all objects. More...
 
obx_err obx_cursor_ts_min_max_range (OBX_cursor *cursor, int64_t range_begin, int64_t range_end, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
 Time series: get the limits (min/max time values) over objects within the given time range. More...
 
OBX_boxobx_box (OBX_store *store, obx_schema_id entity_id)
 Get access to the box for the given entity. A box may be used across threads. Boxes are shared instances and managed by the store so there's no need to close/free them manually. More...
 
OBX_storeobx_box_store (OBX_box *box)
 Get access to the store this box belongs to - utility for when you only have access to the box variable but need some store method, such as starting a transaction. This doesn't produce a new instance of OBX_store, just gives you back the same pointer you've created this box with. In other words, don't close the returned store separately. More...
 
obx_err obx_box_contains (OBX_box *box, obx_id id, bool *out_contains)
 Check whether a given object exists in the box. More...
 
obx_err obx_box_contains_many (OBX_box *box, const OBX_id_array *ids, bool *out_contains)
 Check whether this box contains objects with all of the IDs given. More...
 
obx_err obx_box_get (OBX_box *box, obx_id id, const void **data, size_t *size)
 Fetch a single object from the box; must be called inside a (reentrant) transaction. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime: More...
 
OBX_bytes_arrayobx_box_get_many (OBX_box *box, const OBX_id_array *ids)
 Fetch multiple objects for the given IDs from the box; must be called inside a (reentrant) transaction. More...
 
OBX_bytes_arrayobx_box_get_all (OBX_box *box)
 Fetch all objects from the box; must be called inside a (reentrant) transaction. NOTE: don't call this in 32 bit mode! Use obx_box_visit_all() instead. More...
 
obx_err obx_box_visit_many (OBX_box *box, const OBX_id_array *ids, obx_data_visitor *visitor, void *user_data)
 Read given objects from the database in a single transaction. Call the visitor() on each object, passing user_data, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. If an object is not found, the visitor() is still called, passing NULL as data and a 0 as size. More...
 
obx_err obx_box_visit_all (OBX_box *box, obx_data_visitor *visitor, void *user_data)
 Read all objects in a single transaction. Calls the visitor() on each object, passing visitor_arg, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. More...
 
obx_id obx_box_id_for_put (OBX_box *box, obx_id id_or_zero)
 Prepares an ID for insertion: pass in 0 (zero) to reserve a new ID or an existing ID to check/prepare it. More...
 
obx_err obx_box_ids_for_put (OBX_box *box, uint64_t count, obx_id *out_first_id)
 Reserve the given number of (new) IDs for insertion; a bulk version of obx_box_id_for_put(). More...
 
obx_err obx_box_put (OBX_box *box, obx_id id, const void *data, size_t size)
 Put the given object using the given ID synchronously; note that the ID also must match the one present in data. More...
 
obx_err obx_box_insert (OBX_box *box, obx_id id, const void *data, size_t size)
 Convenience for obx_box_put5() with OBXPutMode_INSERT. More...
 
obx_err obx_box_update (OBX_box *box, obx_id id, const void *data, size_t size)
 Convenience for obx_cursor_put4() with OBXPutMode_UPDATE. More...
 
obx_err obx_box_put5 (OBX_box *box, obx_id id, const void *data, size_t size, OBXPutMode mode)
 Put the given object using the given ID synchronously; note that the ID also must match the one present in data. More...
 
obx_id obx_box_put_object (OBX_box *box, void *data, size_t size)
 FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW. More...
 
obx_id obx_box_put_object4 (OBX_box *box, void *data, size_t size, OBXPutMode mode)
 FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW. More...
 
obx_err obx_box_put_many (OBX_box *box, const OBX_bytes_array *objects, const obx_id *ids, OBXPutMode mode)
 Put all given objects in the database in a single transaction. If any of the individual objects failed to put, none are put and an error is returned, equivalent to calling obx_box_put_many5() with fail_on_id_failure=true. More...
 
obx_err obx_box_put_many5 (OBX_box *box, const OBX_bytes_array *objects, const obx_id *ids, OBXPutMode mode, bool fail_on_id_failure)
 Like obx_box_put_many(), but with an additional flag indicating how to treat ID failures with OBXPutMode_INSERT and OBXPutMode_UPDATE. More...
 
obx_err obx_box_remove (OBX_box *box, obx_id id)
 Remove a single object will return OBX_NOT_FOUND if an object with the given ID doesn't exist. More...
 
obx_err obx_box_remove_many (OBX_box *box, const OBX_id_array *ids, uint64_t *out_count)
 Remove all given objects from the database in a single transaction. Note that this method will not fail if the object is not found (e.g. already removed). In case you need to strictly check whether all of the objects exist before removing them, execute obx_box_contains_ids() and obx_box_remove_ids() inside a single write transaction. More...
 
obx_err obx_box_remove_all (OBX_box *box, uint64_t *out_count)
 Remove all objects and set the out_count the the number of removed objects. More...
 
obx_err obx_box_is_empty (OBX_box *box, bool *out_is_empty)
 Check whether there are any objects for this entity and updates the out_is_empty accordingly. More...
 
obx_err obx_box_count (OBX_box *box, uint64_t limit, uint64_t *out_count)
 Count the number of objects in the box, up to the given maximum. You can pass limit=0 to count all objects without any limitation. More...
 
OBX_id_arrayobx_box_get_backlink_ids (OBX_box *box, obx_schema_id property_id, obx_id id)
 Fetch IDs of all objects that link back to the given object (ID) using the given relation property (ID). Note: This method refers to "property based relations" unlike the "stand-alone relations" (see obx_box_rel_*). More...
 
obx_err obx_box_rel_put (OBX_box *box, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
 Insert a standalone relation entry between two objects. More...
 
obx_err obx_box_rel_remove (OBX_box *box, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
 Remove a standalone relation entry between two objects. See obx_box_rel_put() for parameters documentation. More...
 
OBX_id_arrayobx_box_rel_get_ids (OBX_box *box, obx_schema_id relation_id, obx_id id)
 Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation. More...
 
OBX_id_arrayobx_box_rel_get_backlink_ids (OBX_box *box, obx_schema_id relation_id, obx_id id)
 Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation. More...
 
obx_err obx_box_ts_min_max (OBX_box *box, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
 Time series: get the limits (min/max time values) over all objects. More...
 
obx_err obx_box_ts_min_max_range (OBX_box *box, int64_t range_begin, int64_t range_end, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
 Time series: get the limits (min/max time values) over objects within the given time range. More...
 
OBX_asyncobx_async (OBX_box *box)
 Note: DO NOT close this OBX_async; its lifetime is tied to the OBX_box instance. More...
 
obx_err obx_async_put (OBX_async *async, obx_id id, const void *data, size_t size)
 Put asynchronously with standard put semantics (insert or update). More...
 
obx_err obx_async_put5 (OBX_async *async, obx_id id, const void *data, size_t size, OBXPutMode mode)
 Put asynchronously using the given mode. More...
 
obx_err obx_async_insert (OBX_async *async, obx_id id, const void *data, size_t size)
 Put asynchronously with inserts semantics (won't put if object already exists). More...
 
obx_err obx_async_update (OBX_async *async, obx_id id, const void *data, size_t size)
 Put asynchronously with update semantics (won't put if object is not yet present). More...
 
obx_id obx_async_put_object (OBX_async *async, void *data, size_t size)
 Reserve an ID, which is returned immediately for future reference, and put asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be put successfully in the DB. More...
 
obx_id obx_async_insert_object (OBX_async *async, void *data, size_t size)
 Reserve an ID, which is returned immediately for future reference, and insert asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be inserted successfully in the DB. More...
 
obx_err obx_async_remove (OBX_async *async, obx_id id)
 Remove asynchronously. More...
 
OBX_asyncobx_async_create (OBX_box *box, uint64_t enqueue_timeout_millis)
 Create a custom OBX_async instance that has to be closed using obx_async_close(). Note: for standard tasks, prefer obx_box_async() giving you a shared instance that does not have to be closed. More...
 
obx_err obx_async_close (OBX_async *async)
 Close a custom OBX_async instance created with obx_async_create(). More...
 
OBX_query_builderobx_query_builder (OBX_store *store, obx_schema_id entity_id)
 Create a query builder which is used to collect conditions using the obx_qb_* functions. Once all conditions are applied, use obx_query() to build a OBX_query that is used to actually retrieve data. Use obx_qb_close() to close (free) the query builder. More...
 
obx_err obx_qb_close (OBX_query_builder *builder)
 Close the query builder; note that OBX_query objects outlive their builder and thus are not affected by this call. More...
 
obx_err obx_qb_error_code (OBX_query_builder *builder)
 To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred. More...
 
const char * obx_qb_error_message (OBX_query_builder *builder)
 To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred. More...
 
obx_qb_cond obx_qb_null (OBX_query_builder *builder, obx_schema_id property_id)
 Add null check to the query. More...
 
obx_qb_cond obx_qb_not_null (OBX_query_builder *builder, obx_schema_id property_id)
 Add not-null check to the query. More...
 
obx_qb_cond obx_qb_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_not_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_contains_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_starts_with_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_ends_with_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_greater_than_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_greater_or_equal_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_less_than_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_less_or_equal_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 
obx_qb_cond obx_qb_in_strings (OBX_query_builder *builder, obx_schema_id property_id, const char *const values[], size_t count, bool case_sensitive)
 Note that all string values are copied and thus do not need to be maintained by the calling code. More...
 
obx_qb_cond obx_qb_any_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
 For OBXPropertyType_StringVector - matches if at least one vector item equals the given value. More...
 
obx_qb_cond obx_qb_equals_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_not_equals_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_greater_than_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_greater_or_equal_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_less_than_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_less_or_equal_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
 
obx_qb_cond obx_qb_between_2ints (OBX_query_builder *builder, obx_schema_id property_id, int64_t value_a, int64_t value_b)
 
obx_qb_cond obx_qb_in_int64s (OBX_query_builder *builder, obx_schema_id property_id, const int64_t values[], size_t count)
 Note that all values are copied and thus do not need to be maintained by the calling code. More...
 
obx_qb_cond obx_qb_not_in_int64s (OBX_query_builder *builder, obx_schema_id property_id, const int64_t values[], size_t count)
 Note that all values are copied and thus do not need to be maintained by the calling code. More...
 
obx_qb_cond obx_qb_in_int32s (OBX_query_builder *builder, obx_schema_id property_id, const int32_t values[], size_t count)
 Note that all values are copied and thus do not need to be maintained by the calling code. More...
 
obx_qb_cond obx_qb_not_in_int32s (OBX_query_builder *builder, obx_schema_id property_id, const int32_t values[], size_t count)
 Note that all values are copied and thus do not need to be maintained by the calling code. More...
 
obx_qb_cond obx_qb_greater_than_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
 
obx_qb_cond obx_qb_greater_or_equal_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
 
obx_qb_cond obx_qb_less_than_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
 
obx_qb_cond obx_qb_less_or_equal_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
 
obx_qb_cond obx_qb_between_2doubles (OBX_query_builder *builder, obx_schema_id property_id, double value_a, double value_b)
 
obx_qb_cond obx_qb_equals_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
 
obx_qb_cond obx_qb_greater_than_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
 
obx_qb_cond obx_qb_greater_or_equal_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
 
obx_qb_cond obx_qb_less_than_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
 
obx_qb_cond obx_qb_less_or_equal_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
 
obx_qb_cond obx_qb_all (OBX_query_builder *builder, const obx_qb_cond conditions[], size_t count)
 Combine conditions[] to a new condition using operator AND (all). More...
 
obx_qb_cond obx_qb_any (OBX_query_builder *builder, const obx_qb_cond conditions[], size_t count)
 Combine conditions[] to a new condition using operator OR (any). More...
 
obx_err obx_qb_param_alias (OBX_query_builder *builder, const char *alias)
 
obx_err obx_qb_order (OBX_query_builder *builder, obx_schema_id property_id, OBXOrderFlags flags)
 Configures an order of results in the query. More...
 
OBX_query_builderobx_qb_link_property (OBX_query_builder *builder, obx_schema_id property_id)
 Create a link based on a property-relation (many-to-one) More...
 
OBX_query_builderobx_qb_backlink_property (OBX_query_builder *builder, obx_schema_id source_entity_id, obx_schema_id source_property_id)
 Create a backlink based on a property-relation used in reverse (one-to-many) More...
 
OBX_query_builderobx_qb_link_standalone (OBX_query_builder *builder, obx_schema_id relation_id)
 Create a link based on a standalone relation (many-to-many) More...
 
OBX_query_builderobx_qb_backlink_standalone (OBX_query_builder *builder, obx_schema_id relation_id)
 Create a backlink based on a standalone relation (many-to-many, reverse direction) More...
 
OBX_query_builderobx_qb_link_time (OBX_query_builder *builder, obx_schema_id linked_entity_id, obx_schema_id begin_property_id, obx_schema_id end_property_id)
 Link the (time series) entity type to another entity space using a time point or range defined in the given linked entity type and properties. Note: time series functionality must be available to use this. More...
 
OBX_queryobx_query (OBX_query_builder *builder)
 
obx_err obx_query_close (OBX_query *query)
 Close the query and free resources. More...
 
OBX_queryobx_query_clone (OBX_query *query)
 Create a clone of the given query such that it can be run on a separate thread. More...
 
obx_err obx_query_offset (OBX_query *query, uint64_t offset)
 Configure an offset for this query - all methods that support offset will return/process objects starting at this offset. Example use case: use together with limit to get a slice of the whole result, e.g. for "result paging". Call with offset=0 to reset to the default behavior, i.e. starting from the first element. More...
 
obx_err obx_query_offset_limit (OBX_query *query, uint64_t offset, uint64_t limit)
 Configure an offset and a limit for this query - all methods that support an offset/limit will return/process objects starting at this offset and up to the given limit. Example use case: get a slice of the whole result, e.g. for "result paging". Call with offset/limit=0 to reset to the default behavior, i.e. starting from the first element without limit. More...
 
obx_err obx_query_limit (OBX_query *query, uint64_t limit)
 Configure a limit for this query - all methods that support limit will return/process only the given number of objects. Example use case: use together with offset to get a slice of the whole result, e.g. for "result paging". Call with limit=0 to reset to the default behavior - zero limit means no limit applied. More...
 
OBX_bytes_arrayobx_query_find (OBX_query *query)
 Find entities matching the query. NOTE: the returned data is only valid as long the transaction is active! More...
 
obx_err obx_query_visit (OBX_query *query, obx_data_visitor *visitor, void *user_data)
 Walk over matching objects using the given data visitor. More...
 
OBX_id_arrayobx_query_find_ids (OBX_query *query)
 Return the IDs of all matching objects. More...
 
obx_err obx_query_count (OBX_query *query, uint64_t *out_count)
 Return the number of matching objects. More...
 
obx_err obx_query_remove (OBX_query *query, uint64_t *out_count)
 Remove all matching objects from the database & return the number of deleted objects. More...
 
const char * obx_query_describe (OBX_query *query)
 The returned char* is valid until another call to describe() is made on the query or until the query is freed. More...
 
const char * obx_query_describe_params (OBX_query *query)
 The returned char* is valid until another call to describe_params() is made on the query or until the query is freed. More...
 
obx_err obx_query_cursor_visit (OBX_query *query, OBX_cursor *cursor, obx_data_visitor *visitor, void *user_data)
 
OBX_bytes_arrayobx_query_cursor_find (OBX_query *query, OBX_cursor *cursor)
 Find entities matching the query; NOTE: the returned data is only valid as long the transaction is active! More...
 
OBX_id_arrayobx_query_cursor_find_ids (OBX_query *query, OBX_cursor *cursor)
 
obx_err obx_query_cursor_count (OBX_query *query, OBX_cursor *cursor, uint64_t *out_count)
 
obx_err obx_query_cursor_remove (OBX_query *query, OBX_cursor *cursor, uint64_t *out_count)
 Remove (delete!) all matching objects. More...
 
obx_err obx_query_param_string (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const char *value)
 
obx_err obx_query_param_strings (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const char *const values[], size_t count)
 
obx_err obx_query_param_int (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, int64_t value)
 
obx_err obx_query_param_2ints (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, int64_t value_a, int64_t value_b)
 
obx_err obx_query_param_int64s (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const int64_t values[], size_t count)
 
obx_err obx_query_param_int32s (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const int32_t values[], size_t count)
 
obx_err obx_query_param_double (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, double value)
 
obx_err obx_query_param_2doubles (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, double value_a, double value_b)
 
obx_err obx_query_param_bytes (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const void *value, size_t size)
 
size_t obx_query_param_get_type_size (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id)
 Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints). More...
 
obx_err obx_query_param_alias_string (OBX_query *query, const char *alias, const char *value)
 
obx_err obx_query_param_alias_strings (OBX_query *query, const char *alias, const char *const values[], size_t count)
 
obx_err obx_query_param_alias_int (OBX_query *query, const char *alias, int64_t value)
 
obx_err obx_query_param_alias_2ints (OBX_query *query, const char *alias, int64_t value_a, int64_t value_b)
 
obx_err obx_query_param_alias_int64s (OBX_query *query, const char *alias, const int64_t values[], size_t count)
 
obx_err obx_query_param_alias_int32s (OBX_query *query, const char *alias, const int32_t values[], size_t count)
 
obx_err obx_query_param_alias_double (OBX_query *query, const char *alias, double value)
 
obx_err obx_query_param_alias_2doubles (OBX_query *query, const char *alias, double value_a, double value_b)
 
obx_err obx_query_param_alias_bytes (OBX_query *query, const char *alias, const void *value, size_t size)
 
size_t obx_query_param_alias_get_type_size (OBX_query *query, const char *alias)
 Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints). More...
 
OBX_query_propobx_query_prop (OBX_query *query, obx_schema_id property_id)
 Create a "property query" with results referring to single property (not complete objects). Also provides aggregates like for example obx_query_prop_avg(). More...
 
obx_err obx_query_prop_close (OBX_query_prop *query)
 Close the property query and release resources. More...
 
obx_err obx_query_prop_distinct (OBX_query_prop *query, bool distinct)
 Configure the property query to work only on distinct values. More...
 
obx_err obx_query_prop_distinct_case (OBX_query_prop *query, bool distinct, bool case_sensitive)
 Configure the property query to work only on distinct values. This version is reserved for string properties and defines the case sensitivity for distinctness. More...
 
obx_err obx_query_prop_count (OBX_query_prop *query, uint64_t *out_count)
 Count the number of non-NULL values of the given property across all objects matching the query. More...
 
obx_err obx_query_prop_avg (OBX_query_prop *query, double *out_average, int64_t *out_count)
 Calculate an average value for the given numeric property across all objects matching the query. More...
 
obx_err obx_query_prop_avg_int (OBX_query_prop *query, int64_t *out_average, int64_t *out_count)
 Calculate an average value for the given numeric property across all objects matching the query. More...
 
obx_err obx_query_prop_min (OBX_query_prop *query, double *out_minimum, int64_t *out_count)
 Find the minimum value of the given floating-point property across all objects matching the query. More...
 
obx_err obx_query_prop_max (OBX_query_prop *query, double *out_maximum, int64_t *out_count)
 Find the maximum value of the given floating-point property across all objects matching the query. More...
 
obx_err obx_query_prop_sum (OBX_query_prop *query, double *out_sum, int64_t *out_count)
 Calculate the sum of the given floating-point property across all objects matching the query. More...
 
obx_err obx_query_prop_min_int (OBX_query_prop *query, int64_t *out_minimum, int64_t *out_count)
 Find the minimum value of the given property across all objects matching the query. More...
 
obx_err obx_query_prop_max_int (OBX_query_prop *query, int64_t *out_maximum, int64_t *out_count)
 Find the maximum value of the given property across all objects matching the query. More...
 
obx_err obx_query_prop_sum_int (OBX_query_prop *query, int64_t *out_sum, int64_t *out_count)
 Calculate the sum of the given property across all objects matching the query. More...
 
OBX_string_arrayobx_query_prop_find_strings (OBX_query_prop *query, const char *value_if_null)
 Return an array of strings stored as the given property across all objects matching the query. More...
 
OBX_int64_arrayobx_query_prop_find_int64s (OBX_query_prop *query, const int64_t *value_if_null)
 Return an array of ints stored as the given property across all objects matching the query. More...
 
OBX_int32_arrayobx_query_prop_find_int32s (OBX_query_prop *query, const int32_t *value_if_null)
 Return an array of ints stored as the given property across all objects matching the query. More...
 
OBX_int16_arrayobx_query_prop_find_int16s (OBX_query_prop *query, const int16_t *value_if_null)
 Return an array of ints stored as the given property across all objects matching the query. More...
 
OBX_int8_arrayobx_query_prop_find_int8s (OBX_query_prop *query, const int8_t *value_if_null)
 Return an array of ints stored as the given property across all objects matching the query. More...
 
OBX_double_arrayobx_query_prop_find_doubles (OBX_query_prop *query, const double *value_if_null)
 Return an array of doubles stored as the given property across all objects matching the query. More...
 
OBX_float_arrayobx_query_prop_find_floats (OBX_query_prop *query, const float *value_if_null)
 Return an array of int stored as the given property across all objects matching the query. More...
 
OBX_observerobx_observe (OBX_store *store, obx_observer *callback, void *user_data)
 Create an observer (callback) to be notified about all data changes (for all object types). The callback is invoked right after a successful commit. More...
 
OBX_observerobx_observe_single_type (OBX_store *store, obx_schema_id type_id, obx_observer_single_type *callback, void *user_data)
 Create an observer (callback) to be notified about data changes for a given object type. The callback is invoked right after a successful commit. More...
 
obx_err obx_observer_close (OBX_observer *observer)
 Free the memory used by the given observer and unsubscribe it from its box or query. More...
 
void obx_bytes_free (OBX_bytes *bytes)
 
OBX_bytes_arrayobx_bytes_array (size_t count)
 Allocate a bytes array struct of the given size, ready for the data to be pushed. More...
 
obx_err obx_bytes_array_set (OBX_bytes_array *array, size_t index, const void *data, size_t size)
 Set the given data as the index in the bytes array. The data is not copied, just referenced through the pointer. More...
 
void obx_bytes_array_free (OBX_bytes_array *array)
 Free the bytes array struct. More...
 
OBX_id_arrayobx_id_array (const obx_id *ids, size_t count)
 Create an ID array struct, copying the given IDs as the contents. More...
 
void obx_id_array_free (OBX_id_array *array)
 Free the array struct. More...
 
void obx_string_array_free (OBX_string_array *array)
 Free the array struct. More...
 
void obx_int64_array_free (OBX_int64_array *array)
 Free the array struct. More...
 
void obx_int32_array_free (OBX_int32_array *array)
 Free the array struct. More...
 
void obx_int16_array_free (OBX_int16_array *array)
 Free the array struct. More...
 
void obx_int8_array_free (OBX_int8_array *array)
 Free the array struct. More...
 
void obx_double_array_free (OBX_double_array *array)
 Free the array struct. More...
 
void obx_float_array_free (OBX_float_array *array)
 Free the array struct. More...
 
void obx_posix_sem_prefix_set (const char *prefix)
 Only for Apple platforms: set the prefix to use for mutexes based on POSIX semaphores. You must supply the application group identifier for sand-boxed macOS apps here; see also: https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24. More...
 
bool obx_sync_available ()
 Before calling any of the other sync APIs, ensure that those are actually available. If the application is linked a non-sync ObjectBox library, this allows you to fail gracefully. More...
 
OBX_syncobx_sync (OBX_store *store, const char *server_uri)
 Creates a sync client associated with the given store and sync server URI. This does not initiate any connection attempts yet: call obx_sync_start() to do so. Before obx_sync_start(), you must configure credentials via obx_sync_credentials. By default a sync client automatically receives updates from the server once login succeeded. To configure this differently, call obx_sync_request_updates_mode() with the wanted mode. More...
 
obx_err obx_sync_close (OBX_sync *sync)
 Stops and closes (deletes) the sync client freeing its resources. More...
 
obx_err obx_sync_credentials (OBX_sync *sync, OBXSyncCredentialsType type, const void *data, size_t size)
 Sets credentials to authenticate the client with the server. See OBXSyncCredentialsType for available options. The accepted OBXSyncCredentials type depends on your sync-server configuration. More...
 
obx_err obx_sync_max_messages_in_flight (OBX_sync *sync, int value)
 Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server. More...
 
obx_err obx_sync_request_updates_mode (OBX_sync *sync, OBXRequestUpdatesMode mode)
 Switches operation mode that's initialized after successful login Must be called before obx_sync_start (returns OBX_ERROR_ILLEGAL_STATE if it was already started) More...
 
obx_err obx_sync_start (OBX_sync *sync)
 Once the sync client is configured, you can "start" it to initiate synchronization. This method triggers communication in the background and will return immediately. If the synchronization destination is reachable, this background thread will connect to the server, log in (authenticate) and, depending on "update request mode", start syncing data. If the device, network or server is currently offline, connection attempts will be retried later using increasing backoff intervals. More...
 
obx_err obx_sync_stop (OBX_sync *sync)
 Stops this sync client and thus stopping the synchronization. Does nothing if it is already stopped. More...
 
OBXSyncState obx_sync_state (OBX_sync *sync)
 Gets the current state of the sync client (0 on error, e.g. given sync was NULL) More...
 
obx_err obx_sync_wait_for_logged_in_state (OBX_sync *sync, uint64_t timeout_millis)
 Waits for the sync client to get into the given state or until the given timeout is reached. For an asynchronous alternative, please check the listeners. More...
 
obx_err obx_sync_updates_request (OBX_sync *sync, bool subscribe_for_pushes)
 Request updates from the server since we last synced our database. More...
 
obx_err obx_sync_updates_cancel (OBX_sync *sync)
 Cancel updates from the server (once received, the server stops sending updates). The counterpart to obx_sync_updates_request(). This should only be called in "logged in" state and there are no delivery guarantees given. More...
 
obx_err obx_sync_outgoing_message_count (OBX_sync *sync, uint64_t limit, uint64_t *out_count)
 Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server. More...
 
obx_err obx_sync_full (OBX_sync *sync)
 Experimental. This API is likely to be replaced/removed in a future version. Quickly bring our database up-to-date in a single transaction, without transmitting all the history. Good for initial sync of new clients. More...
 
void obx_sync_listener_connect (OBX_sync *sync, OBX_sync_listener_connect *listener, void *listener_arg)
 Set or overwrite a previously set 'connect' listener. More...
 
void obx_sync_listener_disconnect (OBX_sync *sync, OBX_sync_listener_disconnect *listener, void *listener_arg)
 Set or overwrite a previously set 'disconnect' listener. More...
 
void obx_sync_listener_login (OBX_sync *sync, OBX_sync_listener_login *listener, void *listener_arg)
 Set or overwrite a previously set 'login' listener. More...
 
void obx_sync_listener_login_failure (OBX_sync *sync, OBX_sync_listener_login_failure *listener, void *listener_arg)
 Set or overwrite a previously set 'login failure' listener. More...
 
void obx_sync_listener_complete (OBX_sync *sync, OBX_sync_listener_complete *listener, void *listener_arg)
 Set or overwrite a previously set 'complete' listener - notifies when the latest sync has finished. More...
 
void obx_sync_listener_change (OBX_sync *sync, OBX_sync_listener_change *listener, void *listener_arg)
 Set or overwrite a previously set 'change' listener - provides information about incoming changes. More...
 

Detailed Description

Macro Definition Documentation

◆ OBX_ERROR_ALLOCATION

#define OBX_ERROR_ALLOCATION   10003

◆ OBX_ERROR_CONSTRAINT_VIOLATED

#define OBX_ERROR_CONSTRAINT_VIOLATED   10299

◆ OBX_ERROR_DB_FULL

#define OBX_ERROR_DB_FULL   10101

◆ OBX_ERROR_FILE_CORRUPT

#define OBX_ERROR_FILE_CORRUPT   10502

DB file has errors, e.g. illegal values or structural inconsistencies were detected.

◆ OBX_ERROR_FILE_PAGES_CORRUPT

#define OBX_ERROR_FILE_PAGES_CORRUPT   10503

DB file has errors related to pages, e.g. bad page refs outside of the file.

◆ OBX_ERROR_GENERAL

#define OBX_ERROR_GENERAL   10098

◆ OBX_ERROR_ID_ALREADY_EXISTS

#define OBX_ERROR_ID_ALREADY_EXISTS   10210

◆ OBX_ERROR_ID_NOT_FOUND

#define OBX_ERROR_ID_NOT_FOUND   10211

◆ OBX_ERROR_ILLEGAL_ARGUMENT

#define OBX_ERROR_ILLEGAL_ARGUMENT   10002

◆ OBX_ERROR_ILLEGAL_STATE

#define OBX_ERROR_ILLEGAL_STATE   10001

◆ OBX_ERROR_MAX_READERS_EXCEEDED

#define OBX_ERROR_MAX_READERS_EXCEEDED   10102

◆ OBX_ERROR_NO_ERROR_INFO

#define OBX_ERROR_NO_ERROR_INFO   10097

◆ OBX_ERROR_NON_UNIQUE_RESULT

#define OBX_ERROR_NON_UNIQUE_RESULT   10202

◆ OBX_ERROR_NUMERIC_OVERFLOW

#define OBX_ERROR_NUMERIC_OVERFLOW   10004

◆ OBX_ERROR_PROPERTY_TYPE_MISMATCH

#define OBX_ERROR_PROPERTY_TYPE_MISMATCH   10203

◆ OBX_ERROR_SCHEMA

#define OBX_ERROR_SCHEMA   10501

◆ OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND

#define OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND   10504

A requested schema object (e.g., an entity or a property) was not found in the schema.

◆ OBX_ERROR_STD_BAD_ALLOC

#define OBX_ERROR_STD_BAD_ALLOC   10304

◆ OBX_ERROR_STD_ILLEGAL_ARGUMENT

#define OBX_ERROR_STD_ILLEGAL_ARGUMENT   10301

◆ OBX_ERROR_STD_LENGTH

#define OBX_ERROR_STD_LENGTH   10303

◆ OBX_ERROR_STD_OTHER

#define OBX_ERROR_STD_OTHER   10399

◆ OBX_ERROR_STD_OUT_OF_RANGE

#define OBX_ERROR_STD_OUT_OF_RANGE   10302

◆ OBX_ERROR_STD_OVERFLOW

#define OBX_ERROR_STD_OVERFLOW   10306

◆ OBX_ERROR_STD_RANGE

#define OBX_ERROR_STD_RANGE   10305

◆ OBX_ERROR_STORAGE_GENERAL

#define OBX_ERROR_STORAGE_GENERAL   10199

◆ OBX_ERROR_STORE_MUST_SHUTDOWN

#define OBX_ERROR_STORE_MUST_SHUTDOWN   10103

◆ OBX_ERROR_SYNC_NOT_AVAILABLE

#define OBX_ERROR_SYNC_NOT_AVAILABLE   10602

◆ OBX_ERROR_TIME_SERIES

#define OBX_ERROR_TIME_SERIES   10212

◆ OBX_ERROR_TIME_SERIES_NOT_AVAILABLE

#define OBX_ERROR_TIME_SERIES_NOT_AVAILABLE   10601

Feature specific errors.

◆ OBX_ERROR_UNIQUE_VIOLATED

#define OBX_ERROR_UNIQUE_VIOLATED   10201

◆ OBX_ERROR_UNKNOWN

#define OBX_ERROR_UNKNOWN   10099

◆ OBX_ID_NEW

#define OBX_ID_NEW   0xFFFFFFFFFFFFFFFF

To be used for putting objects with prepared ID slots, e.g. obx_cursor_put_object().

◆ OBX_NO_SUCCESS

#define OBX_NO_SUCCESS   1001

Indicates that a function had "no success", which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_NOT_FOUND

#define OBX_NOT_FOUND   404

Returned by, e.g., get operations if nothing was found for a specific ID. This is NOT an error condition, and thus no "last error" info (code/text) is set.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_SUCCESS

#define OBX_SUCCESS   0

Value returned when no error occurred (0)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_TIMEOUT

#define OBX_TIMEOUT   1002

Indicates that a function reached a time out, which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set.

◆ OBX_VERSION_MAJOR

#define OBX_VERSION_MAJOR   0

When using ObjectBox as a dynamic library, you should verify that a compatible version was linked using obx_version() or obx_version_is_at_least().

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_VERSION_MINOR

#define OBX_VERSION_MINOR   12

◆ OBX_VERSION_PATCH

#define OBX_VERSION_PATCH   0

Typedef Documentation

◆ OBX_async

typedef struct OBX_async OBX_async

◆ OBX_box

typedef struct OBX_box OBX_box

◆ OBX_bytes

typedef struct OBX_bytes OBX_bytes

Bytes struct is an input/output wrapper typically used for a single object data (represented as FlatBuffers).

◆ OBX_bytes_array

Bytes array struct is an input/output wrapper for multiple FlatBuffers object data representation.

◆ OBX_cursor

typedef struct OBX_cursor OBX_cursor

◆ obx_data_visitor

typedef bool obx_data_visitor(void *user_data, const void *data, size_t size)

The callback for reading data one-by-one.

Parameters
user_datais a pass-through argument passed to the called API
datais the read data buffer
sizespecifies the length of the read data
Returns
true to keep going, false to cancel.

◆ OBX_double_array

Double array struct is an input/output wrapper for an array of double precision floating point numbers.

◆ obx_err

typedef int obx_err

Error/success code returned by an obx_* function; see defines OBX_SUCCESS, OBX_NOT_FOUND, and OBX_ERROR_*.

◆ OBX_float_array

Float array struct is an input/output wrapper for an array of single precision floating point numbers.

◆ obx_id

typedef uint64_t obx_id

ID of a single Object stored in the database.

◆ OBX_id_array

typedef struct OBX_id_array OBX_id_array

ID array struct is an input/output wrapper for an array of object IDs.

◆ OBX_int16_array

Int16 array struct is an input/output wrapper for an array of int16 numbers.

◆ OBX_int32_array

Int32 array struct is an input/output wrapper for an array of int32 numbers.

◆ OBX_int64_array

Int64 array struct is an input/output wrapper for an array of int64 numbers.

◆ OBX_int8_array

Int8 array struct is an input/output wrapper for an array of int8 numbers.

◆ OBX_model

typedef struct OBX_model OBX_model

◆ OBX_observer

typedef struct OBX_observer OBX_observer

◆ obx_observer

typedef void obx_observer(void *user_data, const obx_schema_id *type_ids, size_t type_ids_count)

Callback for obx_observe()

Parameters
user_datauser data given to obx_observe()
type_idsarray of object type IDs that had changes
type_ids_countnumber of IDs of type_ids

◆ obx_observer_single_type

typedef void obx_observer_single_type(void *user_data)

◆ obx_qb_cond

typedef int obx_qb_cond

Query Builder condition identifier.

  • returned by condition creating functions,
  • used to combine conditions with any/all, thus building more complex conditions

◆ OBX_query

typedef struct OBX_query OBX_query

◆ OBX_query_builder

◆ OBX_query_prop

◆ obx_schema_id

typedef uint32_t obx_schema_id

Schema entity & property identifiers.

◆ OBX_store

typedef struct OBX_store OBX_store

◆ OBX_store_options

◆ OBX_string_array

String array struct is an input/output wrapper for an array of character strings.

◆ OBX_sync

typedef struct OBX_sync OBX_sync

◆ OBX_sync_change

◆ OBX_sync_change_array

◆ OBX_sync_listener_change

typedef void OBX_sync_listener_change(void *arg, const OBX_sync_change_array *changes)

Called with fine grained sync changes (IDs of put and removed entities)

Parameters
argis a pass-through argument passed to the called API
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_sync_listener_complete

typedef void OBX_sync_listener_complete(void *arg)

Called when synchronization is complete.

Parameters
argis a pass-through argument passed to the called API
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_sync_listener_connect

typedef void OBX_sync_listener_connect(void *arg)

Called when connection is established.

Parameters
argis a pass-through argument passed to the called API
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_sync_listener_disconnect

typedef void OBX_sync_listener_disconnect(void *arg)

Called when connection is closed/lost.

Parameters
argis a pass-through argument passed to the called API
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_sync_listener_login

typedef void OBX_sync_listener_login(void *arg)

Called on successful login.

Parameters
argis a pass-through argument passed to the called API
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_sync_listener_login_failure

typedef void OBX_sync_listener_login_failure(void *arg, OBXSyncCode code)

Called on a login failure.

Parameters
argis a pass-through argument passed to the called API
codeerror code indicating why the login failed
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBX_txn

typedef struct OBX_txn OBX_txn

◆ obx_uid

typedef uint64_t obx_uid

Universal identifier used in schema for entities & properties.

Enumeration Type Documentation

◆ OBXDebugFlags

Enumerator
OBXDebugFlags_LOG_TRANSACTIONS_READ 
OBXDebugFlags_LOG_TRANSACTIONS_WRITE 
OBXDebugFlags_LOG_QUERIES 
OBXDebugFlags_LOG_QUERY_PARAMETERS 
OBXDebugFlags_LOG_ASYNC_QUEUE 

◆ OBXEntityFlags

Bit-flags defining the behavior of entities. Note: Numbers indicate the bit position.

Enumerator
OBXEntityFlags_SYNC_ENABLED 

Enable "data synchronization" for this entity type: objects will be synced with other stores over the network. It's possible to have local-only (non-synced) types and synced types in the same store (schema/data model).

OBXEntityFlags_SHARED_GLOBAL_IDS 

Makes object IDs for a synced types (SYNC_ENABLED is set) global. By default (not using this flag), the 64 bit object IDs have a local scope and are not unique globally. This flag tells ObjectBox to treat object IDs globally and thus no ID mapping (local <-> global) is performed. Often this is used with assignable IDs (ID_SELF_ASSIGNABLE property flag is set) and some special ID scheme. Note: typically you won't do this with automatically assigned IDs, set by the local ObjectBox store. Two devices would likely overwrite each other's object during sync as object IDs are prone to collide. It might be OK if you can somehow ensure that only a single device will create new IDs.

◆ OBXFeature

enum OBXFeature
Enumerator
OBXFeature_ResultArray 

Functions that are returning multiple results (e.g. multiple objects) can be only used if this is available. This is only available for 64-bit OSes and is the opposite of "chunked mode", which forces to consume results in chunks (e.g. one by one). Since chunked mode consumes a bit less RAM, ResultArray style functions are typically only preferable if there's an additional overhead per call, e.g. caused by a higher level language abstraction like CGo.

OBXFeature_TimeSeries 

TimeSeries support (date/date-nano companion ID and other time-series functionality).

OBXFeature_Sync 

Sync client availability. Visit https://objectbox.io/sync for more details.

OBXFeature_DebugLog 

Check whether debug log can be enabled during runtime.

OBXFeature_ObjectBrowser 

HTTP server with a database browser.

◆ OBXOrderFlags

Not really an enum, but binary flags to use across languages.

Enumerator
OBXOrderFlags_DESCENDING 

Reverse the order from ascending (default) to descending.

OBXOrderFlags_CASE_SENSITIVE 

Sort upper case letters (e.g. "Z") before lower case letters (e.g. "a"). If not specified, the default is case insensitive for ASCII characters.

OBXOrderFlags_UNSIGNED 

For scalars only: change the comparison to unsigned (default is signed).

OBXOrderFlags_NULLS_LAST 

null values will be put last. If not specified, by default null values will be put first.

OBXOrderFlags_NULLS_ZERO 

null values should be treated equal to zero (scalars only).

◆ OBXPropertyFlags

Bit-flags defining the behavior of properties. Note: Numbers indicate the bit position.

Enumerator
OBXPropertyFlags_ID 

64 bit long property (internally unsigned) representing the ID of the entity. May be combined with: NON_PRIMITIVE_TYPE, ID_MONOTONIC_SEQUENCE, ID_SELF_ASSIGNABLE.

OBXPropertyFlags_NON_PRIMITIVE_TYPE 

On languages like Java, a non-primitive type is used (aka wrapper types, allowing null)

OBXPropertyFlags_NOT_NULL 

Unused yet.

OBXPropertyFlags_INDEXED 
OBXPropertyFlags_RESERVED 

Unused yet.

OBXPropertyFlags_UNIQUE 

Unique index.

OBXPropertyFlags_ID_MONOTONIC_SEQUENCE 

Unused yet: Use a persisted sequence to enforce ID to rise monotonic (no ID reuse)

OBXPropertyFlags_ID_SELF_ASSIGNABLE 

Allow IDs to be assigned by the developer.

OBXPropertyFlags_INDEX_PARTIAL_SKIP_NULL 

Unused yet.

OBXPropertyFlags_INDEX_PARTIAL_SKIP_ZERO 

Used by References for 1) back-references and 2) to clear references to deleted objects (required for ID reuse)

OBXPropertyFlags_VIRTUAL 

Virtual properties may not have a dedicated field in their entity class, e.g. target IDs of to-one relations.

OBXPropertyFlags_INDEX_HASH 

Index uses a 32 bit hash instead of the value 32 bits is shorter on disk, runs well on 32 bit systems, and should be OK even with a few collisions.

OBXPropertyFlags_INDEX_HASH64 

Index uses a 64 bit hash instead of the value recommended mostly for 64 bit machines with values longer >200 bytes; small values are faster with a 32 bit hash.

OBXPropertyFlags_UNSIGNED 

The actual type of the variable is unsigned (used in combination with numeric OBXPropertyType_*). While our default are signed ints, queries & indexes need do know signing info. Note: Don't combine with ID (IDs are always unsigned internally).

OBXPropertyFlags_ID_COMPANION 

By defining an ID companion property, a special ID encoding scheme is activated involving this property.

For Time Series IDs, a companion property of type Date or DateNano represents the exact timestamp.

◆ OBXPropertyType

Enumerator
OBXPropertyType_Bool 

1 byte

OBXPropertyType_Byte 

1 byte

OBXPropertyType_Short 

2 bytes

OBXPropertyType_Char 

1 byte

OBXPropertyType_Int 

4 bytes

OBXPropertyType_Long 

8 bytes

OBXPropertyType_Float 

4 bytes

OBXPropertyType_Double 

8 bytes

OBXPropertyType_String 
OBXPropertyType_Date 

Unix timestamp (milliseconds since 1970) in 8 bytes.

OBXPropertyType_Relation 
OBXPropertyType_DateNano 

Unix timestamp (nanoseconds since 1970) in 8 bytes.

OBXPropertyType_ByteVector 
OBXPropertyType_StringVector 
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ OBXPutMode

enum OBXPutMode
Enumerator
OBXPutMode_PUT 

Standard put ("insert or update")

OBXPutMode_INSERT 

Put succeeds only if the entity does not exist yet.

OBXPutMode_UPDATE 

Put succeeds only if the entity already exist.

◆ OBXPutPaddingMode

Defines a padding mode for putting data bytes. Depending on how that data is created, this mode may optimize data handling by avoiding copying memory. Internal background: data buffers used by put operations are required to have a size divisible by 4 for an efficient data layout.

Enumerator
OBXPutPaddingMode_PaddingAutomatic 

Adds a padding when needed (may require a memory copy): this is the safe option and also the default. The extra memory copy may impact performance, however this is usually not noticeable.

OBXPutPaddingMode_PaddingAllowedByBuffer 

Indicates that data buffers are safe to be extended for padding (adding up to 3 bytes to size is OK). Typically, it depends on the used FlatBuffers builder; e.g. the official C++ seems to ensure it, but flatcc (3rd party implementation for plain C) may not.

OBXPutPaddingMode_PaddingByCaller 

The caller ensures that all data bytes are already padded. ObjectBox will verify the buffer size and returns an error if it's not divisible by 4.

◆ OBXRequestUpdatesMode

Enumerator
OBXRequestUpdatesMode_MANUAL 

no updates by default, obx_sync_updates_request() must be called manually

OBXRequestUpdatesMode_AUTO 

same as calling obx_sync_updates_request(sync, TRUE) default mode unless overridden by obx_sync_request_updates_mode

OBXRequestUpdatesMode_AUTO_NO_PUSHES 

same as calling obx_sync_updates_request(sync, FALSE)

◆ OBXSyncCode

Enumerator
OBXSyncCode_OK 
OBXSyncCode_REQ_REJECTED 
OBXSyncCode_CREDENTIALS_REJECTED 
OBXSyncCode_UNKNOWN 
OBXSyncCode_AUTH_UNREACHABLE 
OBXSyncCode_BAD_VERSION 
OBXSyncCode_CLIENT_ID_TAKEN 
OBXSyncCode_TX_VIOLATED_UNIQUE 

◆ OBXSyncCredentialsType

Enumerator
OBXSyncCredentialsType_NONE 
OBXSyncCredentialsType_SHARED_SECRET 
OBXSyncCredentialsType_GOOGLE_AUTH 

◆ OBXSyncState

Enumerator
OBXSyncState_CREATED 
OBXSyncState_STARTED 
OBXSyncState_CONNECTED 
OBXSyncState_LOGGED_IN 
OBXSyncState_DISCONNECTED 
OBXSyncState_STOPPED 
OBXSyncState_DEAD 

Function Documentation

◆ obx_async()

OBX_async* obx_async ( OBX_box box)

Note: DO NOT close this OBX_async; its lifetime is tied to the OBX_box instance.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_async_close()

obx_err obx_async_close ( OBX_async async)

Close a custom OBX_async instance created with obx_async_create().

Returns
OBX_ERROR_ILLEGAL_ARGUMENT if you pass the shared instance from obx_box_async()
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_async_create()

OBX_async* obx_async_create ( OBX_box box,
uint64_t  enqueue_timeout_millis 
)

Create a custom OBX_async instance that has to be closed using obx_async_close(). Note: for standard tasks, prefer obx_box_async() giving you a shared instance that does not have to be closed.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_async_insert()

obx_err obx_async_insert ( OBX_async async,
obx_id  id,
const void *  data,
size_t  size 
)

Put asynchronously with inserts semantics (won't put if object already exists).

◆ obx_async_insert_object()

obx_id obx_async_insert_object ( OBX_async async,
void *  data,
size_t  size 
)

Reserve an ID, which is returned immediately for future reference, and insert asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be inserted successfully in the DB.

Parameters
datathe given bytes are mutated to update the contained ID data.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_async_put()

obx_err obx_async_put ( OBX_async async,
obx_id  id,
const void *  data,
size_t  size 
)

Put asynchronously with standard put semantics (insert or update).

◆ obx_async_put5()

obx_err obx_async_put5 ( OBX_async async,
obx_id  id,
const void *  data,
size_t  size,
OBXPutMode  mode 
)

Put asynchronously using the given mode.

◆ obx_async_put_object()

obx_id obx_async_put_object ( OBX_async async,
void *  data,
size_t  size 
)

Reserve an ID, which is returned immediately for future reference, and put asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be put successfully in the DB.

Parameters
datathe given bytes are mutated to update the contained ID data.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_async_remove()

obx_err obx_async_remove ( OBX_async async,
obx_id  id 
)

◆ obx_async_update()

obx_err obx_async_update ( OBX_async async,
obx_id  id,
const void *  data,
size_t  size 
)

Put asynchronously with update semantics (won't put if object is not yet present).

◆ obx_box()

OBX_box* obx_box ( OBX_store store,
obx_schema_id  entity_id 
)

Get access to the box for the given entity. A box may be used across threads. Boxes are shared instances and managed by the store so there's no need to close/free them manually.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_contains()

obx_err obx_box_contains ( OBX_box box,
obx_id  id,
bool *  out_contains 
)

Check whether a given object exists in the box.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_contains_many()

obx_err obx_box_contains_many ( OBX_box box,
const OBX_id_array ids,
bool *  out_contains 
)

Check whether this box contains objects with all of the IDs given.

Parameters
out_containsis set to true if all of the IDs are present, otherwise false
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_count()

obx_err obx_box_count ( OBX_box box,
uint64_t  limit,
uint64_t *  out_count 
)

Count the number of objects in the box, up to the given maximum. You can pass limit=0 to count all objects without any limitation.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_get()

obx_err obx_box_get ( OBX_box box,
obx_id  id,
const void **  data,
size_t *  size 
)

Fetch a single object from the box; must be called inside a (reentrant) transaction. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime:

Attention
The exposed data is only valid as long as the (top) transaction is still active and no write
operation (e.g. put/remove) was executed. Accessing data after this is undefined behavior.
Returns
OBX_ERROR_ILLEGAL_STATE if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

◆ obx_box_get_all()

OBX_bytes_array* obx_box_get_all ( OBX_box box)

Fetch all objects from the box; must be called inside a (reentrant) transaction. NOTE: don't call this in 32 bit mode! Use obx_box_visit_all() instead.

Attention
See obx_box_get() for important notes on the limited lifetime of the exposed data.
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

◆ obx_box_get_backlink_ids()

OBX_id_array* obx_box_get_backlink_ids ( OBX_box box,
obx_schema_id  property_id,
obx_id  id 
)

Fetch IDs of all objects that link back to the given object (ID) using the given relation property (ID). Note: This method refers to "property based relations" unlike the "stand-alone relations" (see obx_box_rel_*).

Parameters
property_idthe relation property, which must belong to the entity type represented by this box
idobject ID; the object's type is the target of the relation property (typically from another Box)
Returns
resulting IDs representing objects in this Box, or NULL in case of an error
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_get_many()

OBX_bytes_array* obx_box_get_many ( OBX_box box,
const OBX_id_array ids 
)

Fetch multiple objects for the given IDs from the box; must be called inside a (reentrant) transaction.

Attention
See obx_box_get() for important notes on the limited lifetime of the exposed data.
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

◆ obx_box_id_for_put()

obx_id obx_box_id_for_put ( OBX_box box,
obx_id  id_or_zero 
)

Prepares an ID for insertion: pass in 0 (zero) to reserve a new ID or an existing ID to check/prepare it.

Parameters
id_or_zeroThe ID of the entity. If you pass 0, this will generate a new one. @seealso obx_cursor_id_for_put()

◆ obx_box_ids_for_put()

obx_err obx_box_ids_for_put ( OBX_box box,
uint64_t  count,
obx_id out_first_id 
)

Reserve the given number of (new) IDs for insertion; a bulk version of obx_box_id_for_put().

Parameters
countnumber of IDs to reserve, max 10000
out_first_idthe first ID of the sequence as
Returns
an error in case the required number of IDs could not be reserved.

◆ obx_box_insert()

obx_err obx_box_insert ( OBX_box box,
obx_id  id,
const void *  data,
size_t  size 
)

Convenience for obx_box_put5() with OBXPutMode_INSERT.

Parameters
idnon-zero
Returns
OBX_ERROR_ID_ALREADY_EXISTS if an insert fails because of a colliding ID

◆ obx_box_is_empty()

obx_err obx_box_is_empty ( OBX_box box,
bool *  out_is_empty 
)

Check whether there are any objects for this entity and updates the out_is_empty accordingly.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_put()

obx_err obx_box_put ( OBX_box box,
obx_id  id,
const void *  data,
size_t  size 
)

Put the given object using the given ID synchronously; note that the ID also must match the one present in data.

Parameters
idAn ID usually reserved via obx_box_id_for_put().
See also
obx_box_put5() to additionally provide a put mode
obx_box_put_object() for a variant not requiring reserving IDs

◆ obx_box_put5()

obx_err obx_box_put5 ( OBX_box box,
obx_id  id,
const void *  data,
size_t  size,
OBXPutMode  mode 
)

Put the given object using the given ID synchronously; note that the ID also must match the one present in data.

Parameters
idAn ID usually reserved via obx_box_id_for_put().
See also
obx_box_put() for standard put mode
obx_box_put_object() for a variant not requiring reserving IDs

◆ obx_box_put_many()

obx_err obx_box_put_many ( OBX_box box,
const OBX_bytes_array objects,
const obx_id ids,
OBXPutMode  mode 
)

Put all given objects in the database in a single transaction. If any of the individual objects failed to put, none are put and an error is returned, equivalent to calling obx_box_put_many5() with fail_on_id_failure=true.

Parameters
idsPreviously allocated IDs for the given given objects (e.g. using obx_box_ids_for_put)

◆ obx_box_put_many5()

obx_err obx_box_put_many5 ( OBX_box box,
const OBX_bytes_array objects,
const obx_id ids,
OBXPutMode  mode,
bool  fail_on_id_failure 
)

Like obx_box_put_many(), but with an additional flag indicating how to treat ID failures with OBXPutMode_INSERT and OBXPutMode_UPDATE.

Parameters
fail_on_id_failureif set to true, an ID failure (OBX_ERROR_ID_ALREADY_EXISTS and OBX_ERROR_ID_NOT_FOUND) will fail the transaction, and none of the objects are put/inserted/updated. Note 1: If this function is run inside a managed TX (created by obx_txn_write()) with fail_on_id_failure=true and a failure occurs, the whole outer TX is also aborted. Note 2: ID failure errors are returned even if fail_on_id_failure=false and the TX wasn't aborted.

◆ obx_box_put_object()

obx_id obx_box_put_object ( OBX_box box,
void *  data,
size_t  size 
)

FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW.

Parameters
datawritable data buffer, which may be updated for the ID
Returns
0 on error

◆ obx_box_put_object4()

obx_id obx_box_put_object4 ( OBX_box box,
void *  data,
size_t  size,
OBXPutMode  mode 
)

FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW.

Parameters
datawritable data buffer, which may be updated for the ID
Returns
0 on error, e.g. the entity was not put according to OBXPutMode
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_rel_get_backlink_ids()

OBX_id_array* obx_box_rel_get_backlink_ids ( OBX_box box,
obx_schema_id  relation_id,
obx_id  id 
)

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation.

Parameters
relation_idID of a standalone relation, whose source type matches this Box
idobject ID of the relation target type (typically from another Box)
Returns
resulting IDs representing objects in this Box, or NULL in case of an error
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_rel_get_ids()

OBX_id_array* obx_box_rel_get_ids ( OBX_box box,
obx_schema_id  relation_id,
obx_id  id 
)

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation.

Parameters
relation_idID of a standalone relation, whose target type matches this Box
idobject ID of the relation source type (typically from another Box)
Returns
resulting IDs representing objects in this Box, or NULL in case of an error
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_rel_put()

obx_err obx_box_rel_put ( OBX_box box,
obx_schema_id  relation_id,
obx_id  source_id,
obx_id  target_id 
)

Insert a standalone relation entry between two objects.

Parameters
relation_idmust be a standalone relation ID with source entity belonging to this box
source_ididentifies an object from this box
target_ididentifies an object from the target box (as per the relation definition)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_rel_remove()

obx_err obx_box_rel_remove ( OBX_box box,
obx_schema_id  relation_id,
obx_id  source_id,
obx_id  target_id 
)

Remove a standalone relation entry between two objects. See obx_box_rel_put() for parameters documentation.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_remove()

obx_err obx_box_remove ( OBX_box box,
obx_id  id 
)

Remove a single object will return OBX_NOT_FOUND if an object with the given ID doesn't exist.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_remove_all()

obx_err obx_box_remove_all ( OBX_box box,
uint64_t *  out_count 
)

Remove all objects and set the out_count the the number of removed objects.

Parameters
out_countPointer to retrieve the number of removed objects; optional: may be NULL.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_remove_many()

obx_err obx_box_remove_many ( OBX_box box,
const OBX_id_array ids,
uint64_t *  out_count 
)

Remove all given objects from the database in a single transaction. Note that this method will not fail if the object is not found (e.g. already removed). In case you need to strictly check whether all of the objects exist before removing them, execute obx_box_contains_ids() and obx_box_remove_ids() inside a single write transaction.

Parameters
out_countPointer to retrieve the number of removed objects; optional: may be NULL.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_store()

OBX_store* obx_box_store ( OBX_box box)

Get access to the store this box belongs to - utility for when you only have access to the box variable but need some store method, such as starting a transaction. This doesn't produce a new instance of OBX_store, just gives you back the same pointer you've created this box with. In other words, don't close the returned store separately.

◆ obx_box_ts_min_max()

obx_err obx_box_ts_min_max ( OBX_box box,
obx_id out_min_id,
int64_t *  out_min_value,
obx_id out_max_id,
int64_t *  out_max_value 
)

Time series: get the limits (min/max time values) over all objects.

Parameters
out_min_idpointer to receive an output (may be NULL)
out_min_valuepointer to receive an output (may be NULL)
out_max_idpointer to receive an output (may be NULL)
out_max_valuepointer to receive an output (may be NULL)
Returns
OBX_NOT_FOUND if no objects are stored
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_ts_min_max_range()

obx_err obx_box_ts_min_max_range ( OBX_box box,
int64_t  range_begin,
int64_t  range_end,
obx_id out_min_id,
int64_t *  out_min_value,
obx_id out_max_id,
int64_t *  out_max_value 
)

Time series: get the limits (min/max time values) over objects within the given time range.

Parameters
out_min_idpointer to receive an output (may be NULL)
out_min_valuepointer to receive an output (may be NULL)
out_max_idpointer to receive an output (may be NULL)
out_max_valuepointer to receive an output (may be NULL)
Returns
OBX_NOT_FOUND if no objects are stored in the given range
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_box_update()

obx_err obx_box_update ( OBX_box box,
obx_id  id,
const void *  data,
size_t  size 
)

Convenience for obx_cursor_put4() with OBXPutMode_UPDATE.

Parameters
idnon-zero
Returns
OBX_ERROR_ID_NOT_FOUND if an update fails because the given ID does not represent any object

◆ obx_box_visit_all()

obx_err obx_box_visit_all ( OBX_box box,
obx_data_visitor visitor,
void *  user_data 
)

Read all objects in a single transaction. Calls the visitor() on each object, passing visitor_arg, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel.

◆ obx_box_visit_many()

obx_err obx_box_visit_many ( OBX_box box,
const OBX_id_array ids,
obx_data_visitor visitor,
void *  user_data 
)

Read given objects from the database in a single transaction. Call the visitor() on each object, passing user_data, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. If an object is not found, the visitor() is still called, passing NULL as data and a 0 as size.

◆ obx_bytes_array()

OBX_bytes_array* obx_bytes_array ( size_t  count)

Allocate a bytes array struct of the given size, ready for the data to be pushed.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_bytes_array_free()

void obx_bytes_array_free ( OBX_bytes_array array)

Free the bytes array struct.

◆ obx_bytes_array_set()

obx_err obx_bytes_array_set ( OBX_bytes_array array,
size_t  index,
const void *  data,
size_t  size 
)

Set the given data as the index in the bytes array. The data is not copied, just referenced through the pointer.

◆ obx_bytes_free()

void obx_bytes_free ( OBX_bytes bytes)

◆ obx_cursor()

OBX_cursor* obx_cursor ( OBX_txn txn,
obx_schema_id  entity_id 
)
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_cursor_backlink_ids()

OBX_id_array* obx_cursor_backlink_ids ( OBX_cursor cursor,
obx_schema_id  entity_id,
obx_schema_id  property_id,
obx_id  id 
)
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_cursor_backlinks()

OBX_bytes_array* obx_cursor_backlinks ( OBX_cursor cursor,
obx_schema_id  entity_id,
obx_schema_id  property_id,
obx_id  id 
)
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_cursor_close()

obx_err obx_cursor_close ( OBX_cursor cursor)
Parameters
cursormay be NULL
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_cursor_count()

obx_err obx_cursor_count ( OBX_cursor cursor,
uint64_t *  count 
)

Count the number of available objects.

◆ obx_cursor_count_max()

obx_err obx_cursor_count_max ( OBX_cursor cursor,
uint64_t  max_count,
uint64_t *  out_count 
)

Count the number of available objects up to the specified maximum.

◆ obx_cursor_current()

obx_err obx_cursor_current ( OBX_cursor cursor,
const void **  data,
size_t *  size 
)

◆ obx_cursor_first()

obx_err obx_cursor_first ( OBX_cursor cursor,
const void **  data,
size_t *  size 
)

◆ obx_cursor_get()

obx_err obx_cursor_get ( OBX_cursor cursor,
obx_id  id,
const void **  data,
size_t *  size 
)

◆ obx_cursor_get_all()

OBX_bytes_array* obx_cursor_get_all ( OBX_cursor cursor)

Get all objects as bytes. For larger quantities, it's recommended to iterate using obx_cursor_first and obx_cursor_next. However, if the calling overhead is high (e.g., for language bindings), this method helps.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_cursor_id_for_put()

obx_id obx_cursor_id_for_put ( OBX_cursor cursor,
obx_id  id_or_zero 
)

Call this when putting an object to generate/prepare an ID for it.

Parameters
id_or_zeroThe ID of the entity. If you pass 0, this will generate a new one. @seealso obx_box_id_for_put()

◆ obx_cursor_insert()

obx_err obx_cursor_insert ( OBX_cursor cursor,
obx_id  id,
const void *  data,
size_t  size 
)

Convenience for obx_cursor_put4() with OBXPutMode_INSERT.

Parameters
idnon-zero
Returns
OBX_ERROR_ID_ALREADY_EXISTS if an insert fails because of a colliding ID

◆ obx_cursor_is_empty()

obx_err obx_cursor_is_empty ( OBX_cursor cursor,
bool *  out_is_empty 
)

Return true if there is no object available (false if at least one object is available)

◆ obx_cursor_next()

obx_err obx_cursor_next ( OBX_cursor cursor,
const void **  data,
size_t *  size 
)

◆ obx_cursor_put()

obx_err obx_cursor_put ( OBX_cursor cursor,
obx_id  id,
const void *  data,
size_t  size 
)

Puts the given object data using the given ID. A "put" in ObjectBox follows "insert or update" semantics; New objects (no pre-existing object for given ID) are inserted while existing objects are replaced/updated.

Parameters
idnon-zero

◆ obx_cursor_put4()

obx_err obx_cursor_put4 ( OBX_cursor cursor,
obx_id  id,
const void *  data,
size_t  size,
OBXPutMode  mode 
)

Like put obx_cursor_put(), but takes an additional parameter (4th parameter) for choosing a put mode.

Parameters
idnon-zero
modeChanges the put semantics to the given mode, e.g. OBXPutMode_INSERT or OBXPutMode_UPDATE.
Returns
OBX_SUCCESS if the put operation was successful
OBX_ERROR_ID_ALREADY_EXISTS OBXPutMode_INSERT was used, but an existing object was found using the given ID
OBX_ERROR_ID_NOT_FOUND OBXPutMode_UPDATE was used, but no object was found for the given ID

◆ obx_cursor_put_new()

obx_err obx_cursor_put_new ( OBX_cursor cursor,
obx_id  id,
const void *  data,
size_t  size 
)

An optimized version of obx_cursor_put() if you can ensure that the given ID is not used yet. Typically used right after getting a new ID via obx_cursor_id_for_put(). WARNING: using this incorrectly (an object with the given ID already exists) may result in inconsistent data (e.g. indexes do not get updated).

Parameters
idnon-zero

◆ obx_cursor_put_object()

obx_id obx_cursor_put_object ( OBX_cursor cursor,
void *  data,
size_t  size 
)

FB ID slot must be present; new entities must prepare the slot using the special value OBX_ID_NEW. Alternatively, you may also pass 0 to indicate a new entity if you are aware that FlatBuffers builders typically skip zero values by default. Thus, you have to "force" writing the zero in FlatBuffers.

Parameters
dataobject data, non-const because the ID slot will be written (mutated) for new entites (see above)
Returns
id if the object could be put, or 0 in case of an error

◆ obx_cursor_put_object4()

obx_id obx_cursor_put_object4 ( OBX_cursor cursor,
void *  data,
size_t  size,
OBXPutMode  mode 
)

◆ obx_cursor_rel_ids()

OBX_id_array* obx_cursor_rel_ids ( OBX_cursor cursor,
obx_schema_id  relation_id,
obx_id  source_id 
)
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_cursor_rel_put()

obx_err obx_cursor_rel_put ( OBX_cursor cursor,
obx_schema_id  relation_id,
obx_id  source_id,
obx_id  target_id 
)

◆ obx_cursor_rel_remove()

obx_err obx_cursor_rel_remove ( OBX_cursor cursor,
obx_schema_id  relation_id,
obx_id  source_id,
obx_id  target_id 
)

◆ obx_cursor_remove()

obx_err obx_cursor_remove ( OBX_cursor cursor,
obx_id  id 
)

◆ obx_cursor_remove_all()

obx_err obx_cursor_remove_all ( OBX_cursor cursor)

◆ obx_cursor_seek()

obx_err obx_cursor_seek ( OBX_cursor cursor,
obx_id  id 
)

◆ obx_cursor_ts_min_max()

obx_err obx_cursor_ts_min_max ( OBX_cursor cursor,
obx_id out_min_id,
int64_t *  out_min_value,
obx_id out_max_id,
int64_t *  out_max_value 
)

Time series: get the limits (min/max time values) over all objects.

Parameters
out_min_idpointer to receive an output (may be NULL)
out_min_valuepointer to receive an output (may be NULL)
out_max_idpointer to receive an output (may be NULL)
out_max_valuepointer to receive an output (may be NULL)
Returns
OBX_NOT_FOUND if no objects are stored

◆ obx_cursor_ts_min_max_range()

obx_err obx_cursor_ts_min_max_range ( OBX_cursor cursor,
int64_t  range_begin,
int64_t  range_end,
obx_id out_min_id,
int64_t *  out_min_value,
obx_id out_max_id,
int64_t *  out_max_value 
)

Time series: get the limits (min/max time values) over objects within the given time range.

Parameters
out_min_idpointer to receive an output (may be NULL)
out_min_valuepointer to receive an output (may be NULL)
out_max_idpointer to receive an output (may be NULL)
out_max_valuepointer to receive an output (may be NULL)
Returns
OBX_NOT_FOUND if no objects are stored in the given range

◆ obx_cursor_update()

obx_err obx_cursor_update ( OBX_cursor cursor,
obx_id  id,
const void *  data,
size_t  size 
)

Convenience for obx_cursor_put4() with OBXPutMode_UPDATE.

Parameters
idnon-zero
Returns
OBX_ERROR_ID_NOT_FOUND if an update fails because the given ID does not represent any object

◆ obx_double_array_free()

void obx_double_array_free ( OBX_double_array array)

Free the array struct.

◆ obx_float_array_free()

void obx_float_array_free ( OBX_float_array array)

Free the array struct.

◆ obx_has_feature()

bool obx_has_feature ( OBXFeature  feature)

Checks whether the given feature is available in the currently loaded library.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_id_array()

OBX_id_array* obx_id_array ( const obx_id ids,
size_t  count 
)

Create an ID array struct, copying the given IDs as the contents.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_id_array_free()

void obx_id_array_free ( OBX_id_array array)

◆ obx_int16_array_free()

void obx_int16_array_free ( OBX_int16_array array)

Free the array struct.

◆ obx_int32_array_free()

void obx_int32_array_free ( OBX_int32_array array)

Free the array struct.

◆ obx_int64_array_free()

void obx_int64_array_free ( OBX_int64_array array)

Free the array struct.

◆ obx_int8_array_free()

void obx_int8_array_free ( OBX_int8_array array)

Free the array struct.

◆ obx_last_error_clear()

void obx_last_error_clear ( void  )

Clear the error state on the current thread; e.g. obx_last_error_code() will now return OBX_SUCCESS. Note that clearing the error state does not happen automatically; API calls set the error state when they produce an error, but do not clear it on success. See also: obx_last_error_pop() to retrieve the error state and clear it.

◆ obx_last_error_code()

obx_err obx_last_error_code ( void  )

The last error raised by an ObjectBox API call on the current thread, or OBX_SUCCESS if no error occurred yet. Note that API calls do not clear this error code (also true for this method). Thus, if you receive an error from this, it's usually a good idea to call obx_last_error_clear() to clear the error state (or use obx_last_error_pop()) for future API calls.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_last_error_message()

const char* obx_last_error_message ( void  )

The error message string attached to the error returned by obx_last_error_code(). Like obx_last_error_code(), this is bound to the current thread, and this call does not clear the error state. The buffer returned is valid only until the next call into ObjectBox.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_last_error_pop()

bool obx_last_error_pop ( obx_err out_error,
const char **  out_message 
)

Return the error status on the current thread and clear the error state. The buffer returned in out_message is valid only until the next call into ObjectBox.

Parameters
out_errorreceives the error code; optional: may be NULL
out_messagereceives the pointer to the error messages; optional: may be NULL
Returns
true if an error was pending

◆ obx_last_error_secondary()

obx_err obx_last_error_secondary ( void  )

The underlying error for the error returned by obx_last_error_code(). Where obx_last_error_code() may be a generic error like OBX_ERROR_STORAGE_GENERAL, this will give a further underlying and possibly platform-specific error code.

◆ obx_last_error_set()

bool obx_last_error_set ( obx_err  code,
obx_err  secondary,
const char *  message 
)

Set the last error code and test - reserved for internal use from generated code.

◆ obx_model()

OBX_model* obx_model ( void  )

Create an (empty) data meta model which is to be consumed by obx_opt_model().

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details. Note that obx_model_* functions handle OBX_model NULL pointers (will indicate an error but not crash).

◆ obx_model_entity()

obx_err obx_model_entity ( OBX_model model,
const char *  name,
obx_schema_id  entity_id,
obx_uid  entity_uid 
)

Starts the definition of a new entity type for the meta data model. After this, call obx_model_property() to add properties to the entity type.

Parameters
nameA human readable name for the entity. Must be unique within the model
entity_idMust be unique within this version of the model
entity_uidUsed to identify entities between versions of the model. Must be globally unique.

◆ obx_model_entity_flags()

obx_err obx_model_entity_flags ( OBX_model model,
OBXEntityFlags  flags 
)

Refine the definition of the entity declared by the most recent obx_model_entity() call, specifying flags.

◆ obx_model_entity_last_property_id()

obx_err obx_model_entity_last_property_id ( OBX_model model,
obx_schema_id  property_id,
obx_uid  property_uid 
)

Set the highest ever known property id in the entity. Should always be equal to or higher than the last property id of the previous version of the entity.

◆ obx_model_error_code()

obx_err obx_model_error_code ( OBX_model model)

To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred.

Parameters
modelNULL-able; returns OBX_ERROR_ILLEGAL_ARGUMENT if model is NULL

◆ obx_model_error_message()

const char* obx_model_error_message ( OBX_model model)

To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred.

Parameters
modelNULL-able; returns NULL if model is NULL

◆ obx_model_free()

obx_err obx_model_free ( OBX_model model)

Only call when not calling obx_store_open() (which will free it internally)

Parameters
modelNULL-able; returns OBX_SUCCESS if model is NULL

◆ obx_model_last_entity_id()

void obx_model_last_entity_id ( OBX_model ,
obx_schema_id  entity_id,
obx_uid  entity_uid 
)

Set the highest ever known entity id in the model. Should always be equal to or higher than the last entity id of the previous version of the model.

◆ obx_model_last_index_id()

void obx_model_last_index_id ( OBX_model model,
obx_schema_id  index_id,
obx_uid  index_uid 
)

Set the highest ever known index id in the model. Should always be equal to or higher than the last index id of the previous version of the model.

◆ obx_model_last_relation_id()

void obx_model_last_relation_id ( OBX_model model,
obx_schema_id  relation_id,
obx_uid  relation_uid 
)

Set the highest every known relation id in the model. Should always be equal to or higher than the last relation id of the previous version of the model.

◆ obx_model_property()

obx_err obx_model_property ( OBX_model model,
const char *  name,
OBXPropertyType  type,
obx_schema_id  property_id,
obx_uid  property_uid 
)

Starts the definition of a new property for the entity type of the last obx_model_entity() call.

Parameters
nameA human readable name for the property. Must be unique within the entity
typeThe type of property required
property_idMust be unique within the entity
property_uidUsed to identify properties between versions of the entity. Must be global unique.

◆ obx_model_property_flags()

obx_err obx_model_property_flags ( OBX_model model,
OBXPropertyFlags  flags 
)

Refine the definition of the property declared by the most recent obx_model_property() call, specifying flags.

◆ obx_model_property_index_id()

obx_err obx_model_property_index_id ( OBX_model model,
obx_schema_id  index_id,
obx_uid  index_uid 
)

Refine the definition of the property declared by the most recent obx_model_property() call, adding an index.

Parameters
index_idMust be unique within this version of the model
index_uidUsed to identify relations between versions of the model. Must be globally unique.

◆ obx_model_property_relation()

obx_err obx_model_property_relation ( OBX_model model,
const char *  target_entity,
obx_schema_id  index_id,
obx_uid  index_uid 
)

Refine the definition of the property declared by the most recent obx_model_property() call, declaring it a relation.

Parameters
target_entityThe name of the entity linked to by the relation
index_idMust be unique within this version of the model
index_uidUsed to identify relations between versions of the model. Must be globally unique.

◆ obx_model_relation()

obx_err obx_model_relation ( OBX_model model,
obx_schema_id  relation_id,
obx_uid  relation_uid,
obx_schema_id  target_id,
obx_uid  target_uid 
)

Add a standalone relation between the active entity and the target entity to the model.

Parameters
relation_idMust be unique within this version of the model
relation_uidUsed to identify relations between versions of the model. Must be globally unique.
target_idThe id of the target entity of the relation
target_uidThe uid of the target entity of the relation

◆ obx_observe()

OBX_observer* obx_observe ( OBX_store store,
obx_observer callback,
void *  user_data 
)

Create an observer (callback) to be notified about all data changes (for all object types). The callback is invoked right after a successful commit.

Threading note
The given callback is called on the thread issuing the commit for the data change, e.g. via obx_txn_success(). Future versions might change that to a background thread, so be careful with threading assumptions. Also, it's a usually good idea to make the callback return quickly to let the calling thread continue.
Attention
Currently, you can not call any data operations from inside the call back.
More accurately, no transaction may be strated. (This restriction may be removed in a later version.)
Parameters
user_dataany value you want to be forwarded to the given observer callback (usually some context info).
callbackpointer to be called when the observed data changes.
Returns
NULL if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected (OBX_ERROR_ILLEGAL_STATE).

◆ obx_observe_single_type()

OBX_observer* obx_observe_single_type ( OBX_store store,
obx_schema_id  type_id,
obx_observer_single_type callback,
void *  user_data 
)

Create an observer (callback) to be notified about data changes for a given object type. The callback is invoked right after a successful commit.

Note
If you intend to observe more than one type, it is more efficient to use obx_observe().
Threading note
The given callback is called on the thread issuing the commit for the data change, e.g. via obx_txn_success(). Future versions might change that to a background thread, so be careful with threading assumptions. Also, it's a usually good idea to make the callback return quickly to let the calling thread continue.
Attention
Currently, you can not call any data operations from inside the call back.
More accurately, no transaction may be strated. (This restriction may be removed in a later version.)
Parameters
type_idID of the object type to be observer.
user_dataany value you want to be forwarded to the given observer callback (usually some context info).
callbackpointer to be called when the observed data changes.
Returns
NULL if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected (OBX_ERROR_ILLEGAL_STATE).

◆ obx_observer_close()

obx_err obx_observer_close ( OBX_observer observer)

Free the memory used by the given observer and unsubscribe it from its box or query.

Returns
OBX_ERROR_ILLEGAL_STATE if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected. In that case, the caller must try to close again in a valid situation not causing lock failures.

◆ obx_opt()

OBX_store_options* obx_opt ( )

Create a default set of store options.

Returns
NULL on failure, a default set of options on success
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_max_in_tx_duration()

void obx_opt_async_max_in_tx_duration ( OBX_store_options opt,
uint32_t  micros 
)

Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_max_in_tx_operations()

void obx_opt_async_max_in_tx_operations ( OBX_store_options opt,
uint32_t  value 
)

Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_max_queue_length()

void obx_opt_async_max_queue_length ( OBX_store_options opt,
size_t  value 
)

Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_max_tx_pool_size()

void obx_opt_async_max_tx_pool_size ( OBX_store_options opt,
size_t  value 
)

Default value: 10000, set to 0 to deactivate pooling.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_minor_refill_max_count()

void obx_opt_async_minor_refill_max_count ( OBX_store_options opt,
uint32_t  value 
)

If non-zero, this allows "minor refills" with small batches that came in (off by default).

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_minor_refill_threshold()

void obx_opt_async_minor_refill_threshold ( OBX_store_options opt,
size_t  queue_length 
)

Numbers of operations below this value are considered "minor refills".

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_object_bytes_max_cache_size()

void obx_opt_async_object_bytes_max_cache_size ( OBX_store_options opt,
uint64_t  value 
)

Total cache size; default: ~ 0.5 MB.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_object_bytes_max_size_to_cache()

void obx_opt_async_object_bytes_max_size_to_cache ( OBX_store_options opt,
uint64_t  value 
)

Maximal size for an object to be cached (only cache smaller ones)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_post_txn_delay()

void obx_opt_async_post_txn_delay ( OBX_store_options opt,
uint32_t  delay_micros 
)

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_post_txn_delay4()

void obx_opt_async_post_txn_delay4 ( OBX_store_options opt,
uint32_t  delay_micros,
uint32_t  delay2_micros,
size_t  min_queue_length_for_delay2 
)

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_pre_txn_delay()

void obx_opt_async_pre_txn_delay ( OBX_store_options opt,
uint32_t  delay_micros 
)

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_pre_txn_delay4()

void obx_opt_async_pre_txn_delay4 ( OBX_store_options opt,
uint32_t  delay_micros,
uint32_t  delay2_micros,
size_t  min_queue_length_for_delay2 
)

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_throttle_at_queue_length()

void obx_opt_async_throttle_at_queue_length ( OBX_store_options opt,
size_t  value 
)

Producers (AsyncTx submitter) is throttled when the queue size hits this.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_async_throttle_micros()

void obx_opt_async_throttle_micros ( OBX_store_options opt,
uint32_t  value 
)

Sleeping time for throttled producers on each submission.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_debug_flags()

void obx_opt_debug_flags ( OBX_store_options opt,
OBXDebugFlags  flags 
)

Configure debug logging. Defaults to NONE.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_directory()

obx_err obx_opt_directory ( OBX_store_options opt,
const char *  dir 
)

Set the store directory on the options. The default is "objectbox".

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_file_mode()

void obx_opt_file_mode ( OBX_store_options opt,
unsigned int  file_mode 
)

Set the file mode on the options. The default is 0644 (unix-style)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_free()

void obx_opt_free ( OBX_store_options opt)

Free the options. Note: Only free unused options, obx_store_open() frees the options internally.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_max_db_size_in_kb()

void obx_opt_max_db_size_in_kb ( OBX_store_options opt,
size_t  size_in_kb 
)

Set the maximum db size on the options. The default is 1Gb.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_max_readers()

void obx_opt_max_readers ( OBX_store_options opt,
unsigned int  max_readers 
)

Set the maximum number of readers on the options. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. Note: The internal default is currently around 120. So when hitting this limit, try values around 200-500.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_model()

obx_err obx_opt_model ( OBX_store_options opt,
OBX_model model 
)

Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_model_bytes()

obx_err obx_opt_model_bytes ( OBX_store_options opt,
const void *  bytes,
size_t  size 
)

Set the model on the options copying the given bytes. The default is no model.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_model_bytes_direct()

obx_err obx_opt_model_bytes_direct ( OBX_store_options opt,
const void *  bytes,
size_t  size 
)

Like obx_opt_model_bytes BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_put_padding_mode()

void obx_opt_put_padding_mode ( OBX_store_options opt,
OBXPutPaddingMode  mode 
)

Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_read_only()

void obx_opt_read_only ( OBX_store_options opt,
bool  value 
)

Open store in read-only mode: no schema update, no write transactions. Defaults to false.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_read_schema()

void obx_opt_read_schema ( OBX_store_options opt,
bool  value 
)

Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_use_previous_commit()

void obx_opt_use_previous_commit ( OBX_store_options opt,
bool  value 
)

Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_opt_validate_on_open()

void obx_opt_validate_on_open ( OBX_store_options opt,
size_t  page_limit,
bool  leaf_level 
)

When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync).

Parameters
page_limitlimits the number of checked pages (currently defaults to 0, but will be increased in the future)
leaf_levelenable for visiting leaf pages (defaults to false)
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_posix_sem_prefix_set()

void obx_posix_sem_prefix_set ( const char *  prefix)

Only for Apple platforms: set the prefix to use for mutexes based on POSIX semaphores. You must supply the application group identifier for sand-boxed macOS apps here; see also: https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24.

◆ obx_qb_all()

obx_qb_cond obx_qb_all ( OBX_query_builder builder,
const obx_qb_cond  conditions[],
size_t  count 
)

Combine conditions[] to a new condition using operator AND (all).

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_any()

obx_qb_cond obx_qb_any ( OBX_query_builder builder,
const obx_qb_cond  conditions[],
size_t  count 
)

Combine conditions[] to a new condition using operator OR (any).

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_any_equals_string()

obx_qb_cond obx_qb_any_equals_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

For OBXPropertyType_StringVector - matches if at least one vector item equals the given value.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_backlink_property()

OBX_query_builder* obx_qb_backlink_property ( OBX_query_builder builder,
obx_schema_id  source_entity_id,
obx_schema_id  source_property_id 
)

Create a backlink based on a property-relation used in reverse (one-to-many)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_backlink_standalone()

OBX_query_builder* obx_qb_backlink_standalone ( OBX_query_builder builder,
obx_schema_id  relation_id 
)

Create a backlink based on a standalone relation (many-to-many, reverse direction)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_between_2doubles()

obx_qb_cond obx_qb_between_2doubles ( OBX_query_builder builder,
obx_schema_id  property_id,
double  value_a,
double  value_b 
)

◆ obx_qb_between_2ints()

obx_qb_cond obx_qb_between_2ints ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value_a,
int64_t  value_b 
)

◆ obx_qb_close()

obx_err obx_qb_close ( OBX_query_builder builder)

Close the query builder; note that OBX_query objects outlive their builder and thus are not affected by this call.

Parameters
buildermay be NULL
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_contains_string()

obx_qb_cond obx_qb_contains_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_ends_with_string()

obx_qb_cond obx_qb_ends_with_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_equals_bytes()

obx_qb_cond obx_qb_equals_bytes ( OBX_query_builder builder,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_qb_equals_int()

obx_qb_cond obx_qb_equals_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_equals_string()

obx_qb_cond obx_qb_equals_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_error_code()

obx_err obx_qb_error_code ( OBX_query_builder builder)

To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred.

◆ obx_qb_error_message()

const char* obx_qb_error_message ( OBX_query_builder builder)

To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred.

◆ obx_qb_greater_or_equal_bytes()

obx_qb_cond obx_qb_greater_or_equal_bytes ( OBX_query_builder builder,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_qb_greater_or_equal_double()

obx_qb_cond obx_qb_greater_or_equal_double ( OBX_query_builder builder,
obx_schema_id  property_id,
double  value 
)

◆ obx_qb_greater_or_equal_int()

obx_qb_cond obx_qb_greater_or_equal_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_greater_or_equal_string()

obx_qb_cond obx_qb_greater_or_equal_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_greater_than_bytes()

obx_qb_cond obx_qb_greater_than_bytes ( OBX_query_builder builder,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_qb_greater_than_double()

obx_qb_cond obx_qb_greater_than_double ( OBX_query_builder builder,
obx_schema_id  property_id,
double  value 
)

◆ obx_qb_greater_than_int()

obx_qb_cond obx_qb_greater_than_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_greater_than_string()

obx_qb_cond obx_qb_greater_than_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_in_int32s()

obx_qb_cond obx_qb_in_int32s ( OBX_query_builder builder,
obx_schema_id  property_id,
const int32_t  values[],
size_t  count 
)

Note that all values are copied and thus do not need to be maintained by the calling code.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_in_int64s()

obx_qb_cond obx_qb_in_int64s ( OBX_query_builder builder,
obx_schema_id  property_id,
const int64_t  values[],
size_t  count 
)

Note that all values are copied and thus do not need to be maintained by the calling code.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_in_strings()

obx_qb_cond obx_qb_in_strings ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *const  values[],
size_t  count,
bool  case_sensitive 
)

Note that all string values are copied and thus do not need to be maintained by the calling code.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_less_or_equal_bytes()

obx_qb_cond obx_qb_less_or_equal_bytes ( OBX_query_builder builder,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_qb_less_or_equal_double()

obx_qb_cond obx_qb_less_or_equal_double ( OBX_query_builder builder,
obx_schema_id  property_id,
double  value 
)

◆ obx_qb_less_or_equal_int()

obx_qb_cond obx_qb_less_or_equal_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_less_or_equal_string()

obx_qb_cond obx_qb_less_or_equal_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_less_than_bytes()

obx_qb_cond obx_qb_less_than_bytes ( OBX_query_builder builder,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_qb_less_than_double()

obx_qb_cond obx_qb_less_than_double ( OBX_query_builder builder,
obx_schema_id  property_id,
double  value 
)

◆ obx_qb_less_than_int()

obx_qb_cond obx_qb_less_than_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_less_than_string()

obx_qb_cond obx_qb_less_than_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_link_property()

OBX_query_builder* obx_qb_link_property ( OBX_query_builder builder,
obx_schema_id  property_id 
)

Create a link based on a property-relation (many-to-one)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_link_standalone()

OBX_query_builder* obx_qb_link_standalone ( OBX_query_builder builder,
obx_schema_id  relation_id 
)

Create a link based on a standalone relation (many-to-many)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_link_time()

OBX_query_builder* obx_qb_link_time ( OBX_query_builder builder,
obx_schema_id  linked_entity_id,
obx_schema_id  begin_property_id,
obx_schema_id  end_property_id 
)

Link the (time series) entity type to another entity space using a time point or range defined in the given linked entity type and properties. Note: time series functionality must be available to use this.

Parameters
linked_entity_idEntity type that defines a time point or range
begin_property_idProperty of the linked entity defining a time point or the begin of a time range. Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).
end_property_idOptional property of the linked entity defining the end of a time range. Pass zero to only define a time point (begin_property_id). Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_not_equals_int()

obx_qb_cond obx_qb_not_equals_int ( OBX_query_builder builder,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_qb_not_equals_string()

obx_qb_cond obx_qb_not_equals_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_qb_not_in_int32s()

obx_qb_cond obx_qb_not_in_int32s ( OBX_query_builder builder,
obx_schema_id  property_id,
const int32_t  values[],
size_t  count 
)

Note that all values are copied and thus do not need to be maintained by the calling code.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_not_in_int64s()

obx_qb_cond obx_qb_not_in_int64s ( OBX_query_builder builder,
obx_schema_id  property_id,
const int64_t  values[],
size_t  count 
)

Note that all values are copied and thus do not need to be maintained by the calling code.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_not_null()

obx_qb_cond obx_qb_not_null ( OBX_query_builder builder,
obx_schema_id  property_id 
)

Add not-null check to the query.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_null()

obx_qb_cond obx_qb_null ( OBX_query_builder builder,
obx_schema_id  property_id 
)

Add null check to the query.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_order()

obx_err obx_qb_order ( OBX_query_builder builder,
obx_schema_id  property_id,
OBXOrderFlags  flags 
)

Configures an order of results in the query.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_qb_param_alias()

obx_err obx_qb_param_alias ( OBX_query_builder builder,
const char *  alias 
)

◆ obx_qb_starts_with_string()

obx_qb_cond obx_qb_starts_with_string ( OBX_query_builder builder,
obx_schema_id  property_id,
const char *  value,
bool  case_sensitive 
)

◆ obx_query()

OBX_query* obx_query ( OBX_query_builder builder)
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_builder()

OBX_query_builder* obx_query_builder ( OBX_store store,
obx_schema_id  entity_id 
)

Create a query builder which is used to collect conditions using the obx_qb_* functions. Once all conditions are applied, use obx_query() to build a OBX_query that is used to actually retrieve data. Use obx_qb_close() to close (free) the query builder.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_clone()

OBX_query* obx_query_clone ( OBX_query query)

Create a clone of the given query such that it can be run on a separate thread.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_close()

obx_err obx_query_close ( OBX_query query)

Close the query and free resources.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_count()

obx_err obx_query_count ( OBX_query query,
uint64_t *  out_count 
)

Return the number of matching objects.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_cursor_count()

obx_err obx_query_cursor_count ( OBX_query query,
OBX_cursor cursor,
uint64_t *  out_count 
)

◆ obx_query_cursor_find()

OBX_bytes_array* obx_query_cursor_find ( OBX_query query,
OBX_cursor cursor 
)

Find entities matching the query; NOTE: the returned data is only valid as long the transaction is active!

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_cursor_find_ids()

OBX_id_array* obx_query_cursor_find_ids ( OBX_query query,
OBX_cursor cursor 
)

◆ obx_query_cursor_remove()

obx_err obx_query_cursor_remove ( OBX_query query,
OBX_cursor cursor,
uint64_t *  out_count 
)

Remove (delete!) all matching objects.

◆ obx_query_cursor_visit()

obx_err obx_query_cursor_visit ( OBX_query query,
OBX_cursor cursor,
obx_data_visitor visitor,
void *  user_data 
)

◆ obx_query_describe()

const char* obx_query_describe ( OBX_query query)

The returned char* is valid until another call to describe() is made on the query or until the query is freed.

◆ obx_query_describe_params()

const char* obx_query_describe_params ( OBX_query query)

The returned char* is valid until another call to describe_params() is made on the query or until the query is freed.

◆ obx_query_find()

OBX_bytes_array* obx_query_find ( OBX_query query)

Find entities matching the query. NOTE: the returned data is only valid as long the transaction is active!

◆ obx_query_find_ids()

OBX_id_array* obx_query_find_ids ( OBX_query query)

Return the IDs of all matching objects.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_limit()

obx_err obx_query_limit ( OBX_query query,
uint64_t  limit 
)

Configure a limit for this query - all methods that support limit will return/process only the given number of objects. Example use case: use together with offset to get a slice of the whole result, e.g. for "result paging". Call with limit=0 to reset to the default behavior - zero limit means no limit applied.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_offset()

obx_err obx_query_offset ( OBX_query query,
uint64_t  offset 
)

Configure an offset for this query - all methods that support offset will return/process objects starting at this offset. Example use case: use together with limit to get a slice of the whole result, e.g. for "result paging". Call with offset=0 to reset to the default behavior, i.e. starting from the first element.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_offset_limit()

obx_err obx_query_offset_limit ( OBX_query query,
uint64_t  offset,
uint64_t  limit 
)

Configure an offset and a limit for this query - all methods that support an offset/limit will return/process objects starting at this offset and up to the given limit. Example use case: get a slice of the whole result, e.g. for "result paging". Call with offset/limit=0 to reset to the default behavior, i.e. starting from the first element without limit.

◆ obx_query_param_2doubles()

obx_err obx_query_param_2doubles ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
double  value_a,
double  value_b 
)

◆ obx_query_param_2ints()

obx_err obx_query_param_2ints ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
int64_t  value_a,
int64_t  value_b 
)

◆ obx_query_param_alias_2doubles()

obx_err obx_query_param_alias_2doubles ( OBX_query query,
const char *  alias,
double  value_a,
double  value_b 
)

◆ obx_query_param_alias_2ints()

obx_err obx_query_param_alias_2ints ( OBX_query query,
const char *  alias,
int64_t  value_a,
int64_t  value_b 
)

◆ obx_query_param_alias_bytes()

obx_err obx_query_param_alias_bytes ( OBX_query query,
const char *  alias,
const void *  value,
size_t  size 
)

◆ obx_query_param_alias_double()

obx_err obx_query_param_alias_double ( OBX_query query,
const char *  alias,
double  value 
)

◆ obx_query_param_alias_get_type_size()

size_t obx_query_param_alias_get_type_size ( OBX_query query,
const char *  alias 
)

Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints).

Returns
the size of the underlying property
0 if it does not have a fixed size (e.g. strings, vectors) or an error occurred

◆ obx_query_param_alias_int()

obx_err obx_query_param_alias_int ( OBX_query query,
const char *  alias,
int64_t  value 
)

◆ obx_query_param_alias_int32s()

obx_err obx_query_param_alias_int32s ( OBX_query query,
const char *  alias,
const int32_t  values[],
size_t  count 
)

◆ obx_query_param_alias_int64s()

obx_err obx_query_param_alias_int64s ( OBX_query query,
const char *  alias,
const int64_t  values[],
size_t  count 
)

◆ obx_query_param_alias_string()

obx_err obx_query_param_alias_string ( OBX_query query,
const char *  alias,
const char *  value 
)

◆ obx_query_param_alias_strings()

obx_err obx_query_param_alias_strings ( OBX_query query,
const char *  alias,
const char *const  values[],
size_t  count 
)

◆ obx_query_param_bytes()

obx_err obx_query_param_bytes ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
const void *  value,
size_t  size 
)

◆ obx_query_param_double()

obx_err obx_query_param_double ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
double  value 
)

◆ obx_query_param_get_type_size()

size_t obx_query_param_get_type_size ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id 
)

Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints).

Returns
the size of the underlying property
0 if it does not have a fixed size (e.g. strings, vectors) or an error occurred

◆ obx_query_param_int()

obx_err obx_query_param_int ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
int64_t  value 
)

◆ obx_query_param_int32s()

obx_err obx_query_param_int32s ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
const int32_t  values[],
size_t  count 
)

◆ obx_query_param_int64s()

obx_err obx_query_param_int64s ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
const int64_t  values[],
size_t  count 
)

◆ obx_query_param_string()

obx_err obx_query_param_string ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
const char *  value 
)

◆ obx_query_param_strings()

obx_err obx_query_param_strings ( OBX_query query,
obx_schema_id  entity_id,
obx_schema_id  property_id,
const char *const  values[],
size_t  count 
)

◆ obx_query_prop()

OBX_query_prop* obx_query_prop ( OBX_query query,
obx_schema_id  property_id 
)

Create a "property query" with results referring to single property (not complete objects). Also provides aggregates like for example obx_query_prop_avg().

◆ obx_query_prop_avg()

obx_err obx_query_prop_avg ( OBX_query_prop query,
double *  out_average,
int64_t *  out_count 
)

Calculate an average value for the given numeric property across all objects matching the query.

Parameters
querythe query to run
out_averagethe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. a floating point NaN value will trigger the short cut as the average will be a NaN no matter what values will follow.

◆ obx_query_prop_avg_int()

obx_err obx_query_prop_avg_int ( OBX_query_prop query,
int64_t *  out_average,
int64_t *  out_count 
)

Calculate an average value for the given numeric property across all objects matching the query.

Parameters
querythe query to run
out_averagethe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete.
Returns
OBX_ERROR_NUMERIC_OVERFLOW if the result does not fit into an int64_t

◆ obx_query_prop_close()

obx_err obx_query_prop_close ( OBX_query_prop query)

Close the property query and release resources.

◆ obx_query_prop_count()

obx_err obx_query_prop_count ( OBX_query_prop query,
uint64_t *  out_count 
)

Count the number of non-NULL values of the given property across all objects matching the query.

◆ obx_query_prop_distinct()

obx_err obx_query_prop_distinct ( OBX_query_prop query,
bool  distinct 
)

Configure the property query to work only on distinct values.

Note
not all methods support distinct, those that don't will return an error

◆ obx_query_prop_distinct_case()

obx_err obx_query_prop_distinct_case ( OBX_query_prop query,
bool  distinct,
bool  case_sensitive 
)

Configure the property query to work only on distinct values. This version is reserved for string properties and defines the case sensitivity for distinctness.

Note
not all methods support distinct, those that don't will return an error

◆ obx_query_prop_find_doubles()

OBX_double_array* obx_query_prop_find_doubles ( OBX_query_prop query,
const double *  value_if_null 
)

Return an array of doubles stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_floats()

OBX_float_array* obx_query_prop_find_floats ( OBX_query_prop query,
const float *  value_if_null 
)

Return an array of int stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_int16s()

OBX_int16_array* obx_query_prop_find_int16s ( OBX_query_prop query,
const int16_t *  value_if_null 
)

Return an array of ints stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_int32s()

OBX_int32_array* obx_query_prop_find_int32s ( OBX_query_prop query,
const int32_t *  value_if_null 
)

Return an array of ints stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_int64s()

OBX_int64_array* obx_query_prop_find_int64s ( OBX_query_prop query,
const int64_t *  value_if_null 
)

Return an array of ints stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_int8s()

OBX_int8_array* obx_query_prop_find_int8s ( OBX_query_prop query,
const int8_t *  value_if_null 
)

Return an array of ints stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details

◆ obx_query_prop_find_strings()

OBX_string_array* obx_query_prop_find_strings ( OBX_query_prop query,
const char *  value_if_null 
)

Return an array of strings stored as the given property across all objects matching the query.

Parameters
value_if_nullvalue that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified field are skipped

◆ obx_query_prop_max()

obx_err obx_query_prop_max ( OBX_query_prop query,
double *  out_maximum,
int64_t *  out_count 
)

Find the maximum value of the given floating-point property across all objects matching the query.

Parameters
querythe query to run
out_maximumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

◆ obx_query_prop_max_int()

obx_err obx_query_prop_max_int ( OBX_query_prop query,
int64_t *  out_maximum,
int64_t *  out_count 
)

Find the maximum value of the given property across all objects matching the query.

Parameters
querythe query to run
out_maximumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

◆ obx_query_prop_min()

obx_err obx_query_prop_min ( OBX_query_prop query,
double *  out_minimum,
int64_t *  out_count 
)

Find the minimum value of the given floating-point property across all objects matching the query.

Parameters
querythe query to run
out_minimumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

◆ obx_query_prop_min_int()

obx_err obx_query_prop_min_int ( OBX_query_prop query,
int64_t *  out_minimum,
int64_t *  out_count 
)

Find the minimum value of the given property across all objects matching the query.

Parameters
querythe query to run
out_minimumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

◆ obx_query_prop_sum()

obx_err obx_query_prop_sum ( OBX_query_prop query,
double *  out_sum,
int64_t *  out_count 
)

Calculate the sum of the given floating-point property across all objects matching the query.

Parameters
querythe query to run
out_sumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. a floating point NaN value will trigger the short cut as the average will be a NaN no matter what values will follow.

◆ obx_query_prop_sum_int()

obx_err obx_query_prop_sum_int ( OBX_query_prop query,
int64_t *  out_sum,
int64_t *  out_count 
)

Calculate the sum of the given property across all objects matching the query.

Parameters
querythe query to run
out_sumthe result of the query
out_count(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete.
Returns
OBX_ERROR_NUMERIC_OVERFLOW if the result does not fit into an int64_t

◆ obx_query_remove()

obx_err obx_query_remove ( OBX_query query,
uint64_t *  out_count 
)

Remove all matching objects from the database & return the number of deleted objects.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_query_visit()

obx_err obx_query_visit ( OBX_query query,
obx_data_visitor visitor,
void *  user_data 
)

Walk over matching objects using the given data visitor.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_remove_db_files()

obx_err obx_remove_db_files ( char const *  directory)

Delete the store files from the given directory.

◆ obx_store_await_async_completion()

bool obx_store_await_async_completion ( OBX_store store)

Await for all (including future) async submissions to be completed (the async queue becomes idle for a moment).

Returns
true if all submissions were completed or async processing was not started; false if shutting down
false if shutting down or an error occurred
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_store_await_async_submitted()

bool obx_store_await_async_submitted ( OBX_store store)

Await for previously submitted async operations to be completed (the async queue does not have to become idle).

Returns
true if all submissions were completed or async processing was not started
false if shutting down or an error occurred
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_store_close()

obx_err obx_store_close ( OBX_store store)

◆ obx_store_debug_flags()

obx_err obx_store_debug_flags ( OBX_store store,
OBXDebugFlags  flags 
)

Configure debug logging.

◆ obx_store_entity_id()

obx_schema_id obx_store_entity_id ( OBX_store store,
const char *  entity_name 
)

Look for an entity with the given name in the model and return its Entity ID.

◆ obx_store_entity_property_id()

obx_schema_id obx_store_entity_property_id ( OBX_store store,
obx_schema_id  entity_id,
const char *  property_name 
)

Return the property id from the property name or 0 if the name is not found.

◆ obx_store_open()

OBX_store* obx_store_open ( OBX_store_options opt)

Note: the given options are always freed by this function, including when an error occurs.

Parameters
optrequired parameter holding the data model (obx_opt_model()) and optional options (see obx_opt_*())
Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_store_opened_with_previous_commit()

bool obx_store_opened_with_previous_commit ( OBX_store store)
Returns
true if the store was opened with a previous commit
See also
obx_opt_use_previous_commit()

◆ obx_store_wrap()

OBX_store* obx_store_wrap ( void *  core_store)

For stores created outside of this C API, e.g. via C++ or Java, this is how you can use it via C too. Like this, it is OK to use the same store instance (same database) from multiple languages in parallel. Note: the store's life time will still be managed outside of the C API; thus ensure that store is not closed while calling any C function on it. Once you are done with the C specific OBX_store, call obx_store_close() to free any C related resources. This, however, will not close the "core store".

Parameters
core_storeA pointer to the core C++ ObjectStore, or the native JNI handle for a BoxStore.

◆ obx_string_array_free()

void obx_string_array_free ( OBX_string_array array)

Free the array struct.

◆ obx_supports_bytes_array()

bool obx_supports_bytes_array ( void  )

Check whether functions returning OBX_bytes_array are fully supported (depends on build, invariant during runtime)

Deprecated:
use obx_has_feature(OBXFeature_BytesArray) instead

◆ obx_supports_time_series()

bool obx_supports_time_series ( void  )

Check whether time series functions are available in the version of this library.

Deprecated:
use obx_has_feature(OBXFeature_TimeSeries) instead

◆ obx_sync()

OBX_sync* obx_sync ( OBX_store store,
const char *  server_uri 
)

Creates a sync client associated with the given store and sync server URI. This does not initiate any connection attempts yet: call obx_sync_start() to do so. Before obx_sync_start(), you must configure credentials via obx_sync_credentials. By default a sync client automatically receives updates from the server once login succeeded. To configure this differently, call obx_sync_request_updates_mode() with the wanted mode.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_available()

bool obx_sync_available ( )

Before calling any of the other sync APIs, ensure that those are actually available. If the application is linked a non-sync ObjectBox library, this allows you to fail gracefully.

Returns
true if this library comes with the sync API
Deprecated:
use obx_has_feature(OBXFeature_Sync)

◆ obx_sync_close()

obx_err obx_sync_close ( OBX_sync sync)

Stops and closes (deletes) the sync client freeing its resources.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_credentials()

obx_err obx_sync_credentials ( OBX_sync sync,
OBXSyncCredentialsType  type,
const void *  data,
size_t  size 
)

Sets credentials to authenticate the client with the server. See OBXSyncCredentialsType for available options. The accepted OBXSyncCredentials type depends on your sync-server configuration.

Parameters
datamay be NULL, i.e. in combination with OBXSyncCredentialsType_NONE
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_full()

obx_err obx_sync_full ( OBX_sync sync)

Experimental. This API is likely to be replaced/removed in a future version. Quickly bring our database up-to-date in a single transaction, without transmitting all the history. Good for initial sync of new clients.

Returns
OBX_SUCCESS if the request was likely sent (e.g. the sync client is in "logged in" state)
OBX_NO_SUCCESS if the request was not sent (and will not be sent in the future). Note: obx_last_error_code() is not set.

◆ obx_sync_listener_change()

void obx_sync_listener_change ( OBX_sync sync,
OBX_sync_listener_change listener,
void *  listener_arg 
)

Set or overwrite a previously set 'change' listener - provides information about incoming changes.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_listener_complete()

void obx_sync_listener_complete ( OBX_sync sync,
OBX_sync_listener_complete listener,
void *  listener_arg 
)

Set or overwrite a previously set 'complete' listener - notifies when the latest sync has finished.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_listener_connect()

void obx_sync_listener_connect ( OBX_sync sync,
OBX_sync_listener_connect listener,
void *  listener_arg 
)

Set or overwrite a previously set 'connect' listener.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_listener_disconnect()

void obx_sync_listener_disconnect ( OBX_sync sync,
OBX_sync_listener_disconnect listener,
void *  listener_arg 
)

Set or overwrite a previously set 'disconnect' listener.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_listener_login()

void obx_sync_listener_login ( OBX_sync sync,
OBX_sync_listener_login listener,
void *  listener_arg 
)

Set or overwrite a previously set 'login' listener.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_listener_login_failure()

void obx_sync_listener_login_failure ( OBX_sync sync,
OBX_sync_listener_login_failure listener,
void *  listener_arg 
)

Set or overwrite a previously set 'login failure' listener.

Parameters
listenerset NULL to reset
listener_argis a pass-through argument passed to the listener
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_max_messages_in_flight()

obx_err obx_sync_max_messages_in_flight ( OBX_sync sync,
int  value 
)

Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server.

Returns
OBX_ERROR_ILLEGAL_ARGUMENT if value is not in the range 1-20
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_outgoing_message_count()

obx_err obx_sync_outgoing_message_count ( OBX_sync sync,
uint64_t  limit,
uint64_t *  out_count 
)

Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server.

Parameters
limitpass 0 to count all messages without any limitation or a lower number that's enough for your app logic.
Note
This calls uses a (read) transaction internally: 1) it's not just a "cheap" return of a single number. While this will still be fast, avoid calling this function excessively. 2) the result follows transaction view semantics, thus it may not always match the actual value.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_request_updates_mode()

obx_err obx_sync_request_updates_mode ( OBX_sync sync,
OBXRequestUpdatesMode  mode 
)

Switches operation mode that's initialized after successful login Must be called before obx_sync_start (returns OBX_ERROR_ILLEGAL_STATE if it was already started)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_start()

obx_err obx_sync_start ( OBX_sync sync)

Once the sync client is configured, you can "start" it to initiate synchronization. This method triggers communication in the background and will return immediately. If the synchronization destination is reachable, this background thread will connect to the server, log in (authenticate) and, depending on "update request mode", start syncing data. If the device, network or server is currently offline, connection attempts will be retried later using increasing backoff intervals.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_state()

OBXSyncState obx_sync_state ( OBX_sync sync)

Gets the current state of the sync client (0 on error, e.g. given sync was NULL)

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_stop()

obx_err obx_sync_stop ( OBX_sync sync)

Stops this sync client and thus stopping the synchronization. Does nothing if it is already stopped.

Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_updates_cancel()

obx_err obx_sync_updates_cancel ( OBX_sync sync)

Cancel updates from the server (once received, the server stops sending updates). The counterpart to obx_sync_updates_request(). This should only be called in "logged in" state and there are no delivery guarantees given.

Returns
OBX_SUCCESS if the request was likely sent (e.g. the sync client is in "logged in" state)
OBX_NO_SUCCESS if the request was not sent (and will not be sent in the future). Note: obx_last_error_code() is not set.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_updates_request()

obx_err obx_sync_updates_request ( OBX_sync sync,
bool  subscribe_for_pushes 
)

Request updates from the server since we last synced our database.

Parameters
subscribe_for_pusheskeep sending us future updates as they come in. This should only be called in "logged in" state and there are no delivery guarantees given.
Returns
OBX_SUCCESS if the request was likely sent (e.g. the sync client is in "logged in" state)
OBX_NO_SUCCESS if the request was not sent (and will not be sent in the future). Note: obx_last_error_code() is not set.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_sync_wait_for_logged_in_state()

obx_err obx_sync_wait_for_logged_in_state ( OBX_sync sync,
uint64_t  timeout_millis 
)

Waits for the sync client to get into the given state or until the given timeout is reached. For an asynchronous alternative, please check the listeners.

Parameters
timeout_millisMust be greater than 0
Returns
OBX_SUCCESS if the LOGGED_IN state has been reached within the given timeout
OBX_TIMEOUT if the given timeout was reached before a relevant state change was detected. Note: obx_last_error_code() is not set.
OBX_NO_SUCCESS if a state was reached within the given timeout that is unlikely to result in a successful login, e.g. "disconnected". Note: obx_last_error_code() is not set.

◆ obx_txn_abort()

obx_err obx_txn_abort ( OBX_txn txn)

Abort the underlying transaction immediately and thus frees DB resources. Only obx_txn_close() is allowed to be called on the transaction after calling this.

◆ obx_txn_close()

obx_err obx_txn_close ( OBX_txn txn)

Close (free) the transaction (read or write); the given OBX_txn pointer must not be used afterwards. While this is the only way to release read transactions, this call is also an alternative to call obx_txn_success() on write transactions. In combination with obx_txn_mark_success(), this potentially commits or aborts a write transaction on the DB: 1) If it's an outermost TX and all (inner) TXs were marked successful, this commits the transaction. 2) If this transaction was not marked successful, this aborts the transaction (even if it's an inner TX). If an error is returned (e.g., a commit failed because DB is full), you can assume that the transaction was closed.

Parameters
txnmay be NULL
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_txn_mark_success()

obx_err obx_txn_mark_success ( OBX_txn txn,
bool  wasSuccessful 
)

Mark the given write transaction as successful or failed. You can call this method multiple times with different values before calling obx_txn_close() on the transaction.

Returns
OBX_ERROR_ILLEGAL_STATE if the given transaction is not a write transaction.

◆ obx_txn_read()

OBX_txn* obx_txn_read ( OBX_store store)

Create a read transaction (read only). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_txn_success()

obx_err obx_txn_success ( OBX_txn txn)

"Finish" this write transaction successfully and close it, performing a commit if this is the top level transaction and all inner transactions (if any) were also successful (obx_txn_success() was called on them). Because this also closes the given transaction, the given OBX_txn pointer must not be used afterwards.

Returns
OBX_ERROR_ILLEGAL_STATE if the given transaction is not a write transaction.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_txn_write()

OBX_txn* obx_txn_write ( OBX_store store)

Create a write transaction (read and write). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level.

Returns
NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if called when inside a read transaction.
Examples
/home/markus/dev/objectbox/objectbox-c/include/objectbox.hpp.

◆ obx_version()

void obx_version ( int *  major,
int *  minor,
int *  patch 
)

Return the version of the library as ints. Pointers may be null.

◆ obx_version_core_string()

const char* obx_version_core_string ( void  )

Return the version of the ObjectBox core to be printed. The format may change in any future release; only use for information purposes.

See also
obx_version() and obx_version_is_at_least()

◆ obx_version_is_at_least()

bool obx_version_is_at_least ( int  major,
int  minor,
int  patch 
)

Check if the version of the library is equal to or higher than the given version ints.

◆ obx_version_string()

const char* obx_version_string ( void  )

Return the version of the library to be printed. The format may change in any future release; only use for information purposes.

See also
obx_version() and obx_version_is_at_least()