Heimbase

Registers a DB type for use with heim_db_create().

Registers a DB type for use with heim_db_create().

heim_db_register

Parameters

  dbtype | Name of DB type
  data | Private data argument to the dbtype's openf method
  plugin | Structure with DB type methods (function pointers)

Backends that provide begin/commit/rollback methods must provide ACID semantics.

The registered DB type will have ACID semantics for backends that do not provide begin/commit/rollback methods but do provide lock/unlock and rdjournal/wrjournal methods (using a replay log journalling scheme).

If the registered DB type does not natively provide read vs. write transaction isolation but does provide a lock method then the DB will provide read/write transaction isolation.

Returns
  ENOMEM on failure, else 0.

Open a database of the given dbtype.

Database type names can be composed of one or more pseudo-DB types and one concrete DB type joined with a '+' between each. For example: "transaction+bdb" might be a Berkeley DB with a layer above that provides transactions.

Options may be provided via a dict (an associative array). Existing options include:

- "create", with any value (create if DB doesn't exist)
- "exclusive", with any value (exclusive create)
- "truncate", with any value (truncate the DB)
- "read-only", with any value (disallow writes)
- "sync", with any value (make transactions durable)
- "journal-name", with a string value naming a journal file name

Parameters

  dbtype | Name of DB type
  dbname | Name of DB (likely a file path)
  options | Options dict
  db | Output open DB handle
  error | Output error object

Returns
  a DB handle

Clone (duplicate) an open DB handle.

This is useful for multi-threaded applications. Applications must synchronize access to any given DB handle.

Returns EBUSY if there is an open transaction for the input db.

Parameters

  db | Open DB handle
  error | Output error object

Returns
  a DB handle

Open a transaction on the given db.

Parameters

  db | Open DB handle
  error | Output error object

Returns
  0 on success, system error otherwise

Commit an open transaction on the given db.

Parameters

  db | Open DB handle
  error | Output error object

Returns
  0 on success, system error otherwise

Rollback an open transaction on the given db.

Parameters

  db | Open DB handle
  error | Output error object

Returns
  0 on success, system error otherwise

Get type ID of heim_db_t objects.

Lookup a key's value in the DB.

Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure.

Parameters

  db | Open DB handle
  key | Key
  error | Output error object

Returns
  the value (retained), if there is one for the given key

Set a key's value in the DB.

Parameters

  db | Open DB handle
  key | Key
  value | Value (if NULL the key will be deleted, but empty is OK)
  error | Output error object

Returns
  0 on success, system error otherwise

Delete a key and its value from the DB

Parameters

  db | Open DB handle
  key | Key
  error | Output error object

Returns
  0 on success, system error otherwise

Iterate a callback function over keys and values from a DB.

Parameters

  db | Open DB handle
  iter_data | Callback function's private data
  iter_f | Callback function, called once per-key/value pair
  error | Output error object

Get a node in a heim_object tree by path

Parameters

  ptr | tree
  error | error (output)
  ap | NULL-terminated va_list of heim_object_ts that form a path

Returns
  object (not retained) if found

Get a node in a tree by path, with retained reference

Parameters

  ptr | tree
  error | error (output)
  ap | NULL-terminated va_list of heim_object_ts that form a path

Returns
  retained object if found

Get a node in a tree by path

Parameters

  ptr | tree
  error | error (output)
  ... | NULL-terminated va_list of heim_object_ts that form a path

Returns
  object (not retained) if found

Get a node in a tree by path, with retained reference

Parameters

  ptr | tree
  error | error (output)
  ... | NULL-terminated va_list of heim_object_ts that form a path

Returns
  retained object if found

Create a path in a heim_object_t tree

Parameters

  ptr | the tree
  size | the size of the heim_dict_t nodes to be created
  leaf | leaf node to be added, if any
  error | error (output)
  ap | NULL-terminated of path component objects

Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted).

Returns
  0 on success, else a system error

Create a path in a heim_object_t tree

Parameters

  ptr | the tree
  size | the size of the heim_dict_t nodes to be created
  leaf | leaf node to be added, if any
  error | error (output)
  ... | NULL-terminated list of path component objects

Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted).

Returns
  0 on success, else a system error

Delete leaf node named by a path in a heim_object_t tree

Parameters

  ptr | the tree
  error | error (output)
  ap | NULL-terminated list of path component objects

Dump a heimbase object to stderr (useful from the debugger!)

Parameters

  obj | object to dump using JSON or JSON-like format