// Create a cursor handle.
//
// A cursor is associated with a specific transaction and database.
// A cursor cannot be used when its database handle is closed.  Nor
// when its transaction has ended, except with [[cursor_renew]].
//
// It can be discarded with [[cursor_close]].
//
// A cursor in a write-transaction can be closed before its transaction
// ends, and will otherwise be closed when its transaction ends.
//
// A cursor in a read-only transaction must be closed explicitly, before
// or after its transaction ends. It can be reused with
// [[cursor_renew]] before finally closing it.
//
// - txn: A transaction handle returned by [[txn_begin]]
// - dbi: A database handle returned by [[dbi_open]]
// - cursor: Address where the new [[cursor]] handle will be stored
// - return: EINVAL on failure and 0 on success.
export @symbol("mdb_cursor_open") fn cursor_open(txn: *txn, dbi: *dbi, cursor: *nullable *cursor) int;

// Close a cursor handle.
//
// The cursor handle will be freed and must not be used again after this call.
// Its transaction must still be live if it is a write-transaction.
//
// - cursor: A cursor handle returned by [[cursor_open]]
export @symbol("mdb_cursor_close") fn cursor_close(cursor: *cursor) void;

// Retrieve by cursor.
//
// This function retrieves key/data pairs from the database. The address and length
// of the key are returned in the object to which key refers (except for the
// case of the [[SET]] option, in which the key object is unchanged), and
// the address and length of the data are returned in the object to which data
// refers.
//
// See [[get]] for restrictions on using the output values.
//
// Parameters:
// - cursor: A cursor handle returned by [[cursor_open]]
// - key: The key for a retrieved item
// - data: The data of a retrieved item
// - op: A cursor operation [[cursor_op]]
//
// Return value: A non-zero error value on failure and 0 on success.
// Some possible errors are:
// - [[NOTFOUND]] - no matching key found;
// - [[EINVAL]] - an invalid parameter was specified.
export @symbol("mdb_cursor_get") fn cursor_get(cursor: *cursor, key: *val, data: *val, op: cursor_op) int;


// Delete current key/data pair
// 
// This function deletes the key/data pair to which the cursor refers.
// This does not invalidate the cursor, so operations such as MDB_NEXT
// can still be used on it.
//
// Both MDB_NEXT and MDB_GET_CURRENT will return the same record after
// this operation.
//
// Parameters:
// - cursor: A cursor handle returned by [[cursor_open]]
// - flags: Options for this operation. This parameter
//   must be set to 0 or one of the values described here.
//
// Flags:
// - [[NODUPDATA]] - delete all of the data items for the current key. This flag
//   may only be specified if the database was opened with [[DUPSORT]].
//
// Return value: A non-zero error value on failure and 0 on success. Some
// possible errors are:
// - EACCES - an attempt was made to write in a read-only transaction.
// - EINVAL - an invalid parameter was specified.
// 
export @symbol("mdb_cursor_del") fn cursor_del(cursor: *cursor, flags: uint) int;

use types::c;

// Open a database in the environment.
//
// A database handle denotes the name and parameters of a database,
// independently of whether such a database actually exists. The database
// handle may be discarded by calling [[dbi_close]]. If the database was
// already open, this function returns the old handle. The handle may only
// be closed once.
//
// The database handle will be private to the current transaction until the
// transaction is successfully committed. If the transaction is aborted, the
// handle will be closed automatically. After a successful commit, the handle
// will reside in the shared environment and may be used by other transactions.
//
// This function must not be called from multiple concurrent transactions in
// the same process. A transaction that uses this function must finish (either
// commit or abort) before any other transaction in the process may use this
// function.
//
// To use named databases (with name != NULL), [[env_set_maxdbs]] must be
// called before opening the environment. Database names are keys in the unnamed
// database, and may be read but not written.
//
// Parameters:
// - txn: A transaction handle returned by [[txn_begin]]
// - name: The name of the database to open. If only a single database is
//   needed in the environment, this value may be NULL.
// - flags: Special options for this database. Must be set to 0 or by
//   bitwise OR'ing together one or more of the defined flags.
// - dbi: Address where the new [[dbi]] handle will be stored.
//
// Flags:
// - [[REVERSEKEY]]: Keys are compared in reverse order (from end to start)
// - [[DUPSORT]]: Duplicate keys may be used in the database
// - [[INTEGERKEY]]: Keys are binary integers in native byte order
// - [[DUPFIXED]]: Requires [[DUPSORT]]. Data items are all the same size
// - [[INTEGERDUP]]: Duplicate data items are binary integers
// - [[REVERSEDUP]]: Duplicate data items are compared in reverse order
// - [[CREATE]]: Create the named database if it does not exist
//
// Return value: A non-zero error value on failure and 0 on success. Some
// possible errors are:
// - [[NOTFOUND]]: The specified database doesn’t exist and [[CREATE]] was not specified
// - [[DBS_FULL]]: Too many databases have been opened (see [[env_set_maxdbs]])
export @symbol("mdb_dbi_open") fn dbi_open(txn: *txn, name: const nullable *c::char, flags: uint, dbi: *dbi) int;