path: root/src/include/wiredtiger.in

/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2008-2011 WiredTiger, Inc.
 *	All rights reserved.
 */

#ifndef	__WIREDTIGER_H_
#define	__WIREDTIGER_H_

#if defined(__cplusplus)
extern "C" {
#endif

/*******************************************
 * Version information
 *******************************************/
#define	WIREDTIGER_VERSION_MAJOR	@WIREDTIGER_VERSION_MAJOR@
#define	WIREDTIGER_VERSION_MINOR	@WIREDTIGER_VERSION_MINOR@
#define	WIREDTIGER_VERSION_PATCH	@WIREDTIGER_VERSION_PATCH@
#define	WIREDTIGER_VERSION_STRING	@WIREDTIGER_VERSION_STRING@

/*******************************************
 * Required includes
 *******************************************/
@wiredtiger_includes_decl@

/*******************************************
 * Portable type names
 *******************************************/
@int8_decl@
@u_int8_decl@
@int16_decl@
@u_int16_decl@
@int32_decl@
@u_int32_decl@
@int64_decl@
@u_int64_decl@

@u_char_decl@
@u_short_decl@
@u_int_decl@
@u_long_decl@
@u_quad_decl@

@uintmax_t_decl@
@uintptr_t_decl@

#if defined(DOXYGEN) || defined(SWIG)
#define	__F(func) func
#else
#define	__F(func) (*func)
#endif

#ifdef SWIG
%{
#include <wiredtiger.h>
%}
#endif

/*! @defgroup wt WiredTiger API
 * The commonly-used functions, handles and methods that applications use to
 * access and manage data with WiredTiger.
 *
 * @{
 */

/*******************************************
 * Exported types
 *******************************************/
/*! Logical record numbers. */
typedef uint64_t wiredtiger_recno_t;

/*******************************************
 * Forward structure declarations
 *******************************************/
struct wt_collator;	    typedef struct wt_collator WT_COLLATOR;
struct wt_connection;	    typedef struct wt_connection WT_CONNECTION;
struct wt_cursor;	    typedef struct wt_cursor WT_CURSOR;
struct wt_cursor_type;	    typedef struct wt_cursor_type WT_CURSOR_TYPE;
struct wt_event_handler;    typedef struct wt_event_handler WT_EVENT_HANDLER;
struct wt_extractor;	    typedef struct wt_extractor WT_EXTRACTOR;
struct wt_item;		    typedef struct wt_item WT_ITEM;
struct wt_session;	    typedef struct wt_session WT_SESSION;

/*!
 * A raw item of data to be managed.  Data items have a pointer to the data and
 * a length (limited to 4GB for items stored in tables).  Records consist of a
 * pair of items: a key and an associated value.
 */
struct wt_item {
	/*!
	 * The memory reference of the data item.
	 *
	 * For items returned by a WT_CURSOR, the pointer is only valid until
	 * the next operation on that cursor.  Applications that need to keep
	 * an item across multiple cursor operations must make a copy.
	 */
	const void *data;

	/*!
	 * The number of bytes in the data item.
	 */
	uint32_t size;
};

/*!
 * @internal
 * A data item with memory management.  Used internally to manage returned keys
 * and values in the WT_CURSOR implementation.
 */
typedef struct {
	/*
	 * Note: the first two fields must match WT_ITEM, we cast between
	 * those types.
	 */
	const void *data;
	uint32_t size;

	/*
	 * Managed memory chunk.  We swap the order here to avoid padding on
	 * 64-bit systems.
	 */
	uint32_t mem_size;
	void *mem;

#define	WT_BUF_INUSE					0x00000001
	uint32_t flags;
} WT_BUF;
/*!
 * @endinternal
 */

/*!
 * A WT_CURSOR handle is the interface to a cursor.
 *
 * Cursors allow data to be searched, stepped through and updated: the
 * so-called CRUD operations (create, read, update and delete).
 *
 * Raw data is represented by key/value pairs of WT_ITEM structures, but
 * cursors can also provide access to fields within the key and value if the
 * formats are described in the WT_SESSION::create method.
 *
 * A cursor can be positioned in a collection of data.  Cursors are opened in
 * the context of a session (which may have an associated transaction), and can
 * query and update records.  In the common case, a cursor is used to access
 * records in a table.  However, cursors can be used on subsets of tables (such
 * as a single column or a projection of multiple columns), as an interface to
 * statistics, configuration data or application-specific data sources.  See
 * WT_SESSION::open_cursor for more information.
 *
 * <b>Thread safety:</b> A WT_CURSOR handle cannot be shared between threads:
 * it may only be used within the same thread as the encapsulating WT_SESSION.
 */
struct wt_cursor {
	WT_SESSION *session;	/*!< The session handle for this cursor. */

	/*!
	 * The format of the data packed into key items.  See @ref packing for
	 * details.  If not set, a default value of "u" is assumed, and
	 * applications use WT_ITEM to manipulate raw byte arrays.
	 */
	const char *key_format;

	/*!
	 * The format of the data packed into value items.  See @ref packing
	 * for details.  If not set, a default value of "u" is assumed, and
	 * applications use WT_ITEM to manipulate raw byte arrays.
	 */
	const char *value_format;

	/*! @name Data access
	 * @{
	 */
	/*! Get the key for the current record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline get_key
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(get_key)(WT_CURSOR *cursor, ...);

	/*! Get the value for the current record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline get_value
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(get_value)(WT_CURSOR *cursor, ...);

	/*! Set the key for the next operation.
	 *
	 * @dontinclude ex_all.c
	 * @skip key =
	 * @until set_key
	 *
	 * @param cursor the cursor handle
	 *
	 * If an error occurs during this operation, a flag will be set in the
	 * cursor, and the next operation to access the key will fail.  This
	 * simplifies error handling in applications.
	 */
	void __F(set_key)(WT_CURSOR *cursor, ...);

	/*! Set the data for the next operation.
	 *
	 * @dontinclude ex_all.c
	 * @skip value =
	 * @until set_value
	 *
	 * @param cursor the cursor handle
	 *
	 * If an error occurs during this operation, a flag will be set in the
	 * cursor, and the next operation to access the value will fail.  This
	 * simplifies error handling in applications.
	 */
	void __F(set_value)(WT_CURSOR *cursor, ...);
	/*! @} */

	/*! @name Cursor positioning
	 * @{
	 */
	/*! Move to the first record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->first
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(first)(WT_CURSOR *cursor);

	/*! Move to the last record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->last
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(last)(WT_CURSOR *cursor);

	/*! Move to the next record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->next
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(next)(WT_CURSOR *cursor);

	/*! Move to the previous record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->prev
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(prev)(WT_CURSOR *cursor);

	/*! Search for a record.
	 *
	 * @dontinclude ex_all.c
	 * @skip ->prev
	 * @skip ->set_key
	 * @until ->search
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(search)(WT_CURSOR *cursor);

	/*! Search for a record.
	 *
	 * @dontinclude ex_all.c
	 * @skip ->search
	 * @skip ->set_key
	 * @until }
	 *
	 * @param cursor the cursor handle
	 * @param exactp the status of the search: 0 if an exact match is
	 * found, -1 if a smaller key is found, +1 if a larger key is found
	 * @errors
	 */
	int __F(search_near)(WT_CURSOR *cursor, int *exactp);
	/*! @} */

	/*! @name Data modification
	 * @{
	 */
	/*! Insert a record.
	 *
	 * @dontinclude ex_all.c
	 * @skip ->search_near
	 * @skip ->set_key
	 * @until ->insert
	 *
	 * @todo describe append
	 * @todo describe how to unconditionally overwrite
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(insert)(WT_CURSOR *cursor);

	/*! Update the current record.  The cursor must be positioned on a
	 * record and the value of the record will be updated.  If the record
	 * is part of a sorted duplicate set, its position must not change as
	 * a result of the update.
	 *
	 * @dontinclude ex_all.c
	 * @skip ->insert
	 * @skip ->set_value
	 * @until ->update
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(update)(WT_CURSOR *cursor);

	/*! Remove the current record.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->remove
	 *
	 * @param cursor the cursor handle
	 * @errors
	 */
	int __F(remove)(WT_CURSOR *cursor);
	/*! @} */

	/*! Close the cursor.
	 *
	 * This releases the resources associated with the cursor handle.
	 * Cursors are closed implicitly by ending the enclosing transaction or
	 * closing the session in which they were opened.
	 *
	 * @dontinclude ex_all.c
	 * @skipline cursor->close
	 *
	 * @param cursor the cursor handle
	 * @configstart{cursor.close, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(close)(WT_CURSOR *cursor, const char *config);

	/*
	 * Protected fields, only to be used by cursor implementations.
	 */

#ifndef SWIG
	/*
	 * !!!
	 * Explicit representations of structures from queue.h.
	 * TAILQ_ENTRY(wt_cursor) q;
	 */
	struct {
		WT_CURSOR *tqe_next;
		WT_CURSOR **tqe_prev;
	} q;                            /* Linked list of WT_CURSORs. */

	wiredtiger_recno_t recno;
	WT_BUF key, value;
	int saved_err;			/* Saved error in set_{key,value}. */

#define	WT_CURSTD_KEY_RAW	0x01
#define	WT_CURSTD_KEY_SET	0x02
#define	WT_CURSTD_POSITIONED	0x04
#define	WT_CURSTD_PRINT		0x08
#define	WT_CURSTD_RAW		0x10
#define	WT_CURSTD_VALUE_RAW	0x20
#define	WT_CURSTD_VALUE_SET	0x40
	uint32_t flags;
#endif
};

/*!
 * All data operations are performed in the context of a WT_SESSION.  This
 * encapsulates the thread and transactional context of the operation.
 *
 * <b>Thread safety:</b> A WT_SESSION handle cannot be shared between threads:
 * it may only be used within a single thread.  Each thread accessing a
 * database should open a separate WT_SESSION handle.
 */
struct wt_session {
	/*! The connection for this session. */
	WT_CONNECTION *connection;

	/*! Close the session handle.
	 *
	 * This will release the resources associated with the session handle,
	 * including rolling any active transactions and closing any cursors
	 * that remain open in the session.
	 *
	 * @dontinclude ex_all.c
	 * @skipline session->close
	 *
	 * @param session the session handle
	 * @configstart{session.close, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(close)(WT_SESSION *session, const char *config);

	/*! @name Cursor handles
	 * @{
	 */

	/*! Open a cursor.
	 *
	 * Open a new cursor on the specified data source.  An existing cursor
	 * can be duplicated by passing it as the \c to_dup parameter.  Cursor
	 * handles should be closed by calling WT_CURSOR::close to release
	 * resources associated with the cursor.
	 *
	 * Cursors are opened in the context of the current transaction.  The
	 * cursor must be closed before the transaction can end.  If
	 * WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction
	 * are called with cursors open in the transaction, the cursor handles
	 * will be closed implicitly and must not be accessed again.
	 *
	 * Cursors are commonly opened on ordinary tables.  However, cursors
	 * can be opened on any data source, regardless of whether it is
	 * ultimately stored in a table.  Some cursor types may have limited
	 * functionality (e.g., be read-only, or not support transactional
	 * updates).
	 *
	 * These are some of the common builtin cursor types:
	 *   <table>
	 *   @hrow{URI, Function}
	 *   @row{<tt>table:[\<tablename\>]</tt>, ordinary table cursor}
	 *   @row{<tt>column:[\<tablename\>.\<columnname\>]</tt>, column cursor}
	 *   @row{<tt>config:[table:\<tablename\>]</tt>,
	 *   		database or table configuration}
	 *   @row{<tt>join:\<cursor1\>&\<cursor2\>[&\<cursor3\>...]</tt>,
	 *   		Join the contents of multiple cursors together.}
	 *   @row{<tt>statistics:[table:\<tablename\>]</tt>,
	 *   		database or table statistics
	 *   		(key=(string)keyname\, data=(int64_t)value)}
	 *   </table>
	 *
	 * See @ref cursor_types for more information.
	 *
	 * @dontinclude ex_all.c
	 * @skip cursor;
	 * @until ->open_cursor
	 *
	 * @param session the session handle
	 * @param uri the data source on which the cursor operates
	 * @param to_dup a cursor to duplicate
	 * @param session the session handle
	 * @configstart{session.open_cursor, see dist/api_data.py}
	 * @config{bulk, configure the cursor for bulk loads}
	 * @config{dump, configure the cursor for dump format inputs and
	 * outputs.}
	 * @config{isolation, the isolation level for this cursor\, one of \c
	 * "snapshot" or \c "read-committed" or \c "read-uncommitted". Ignored
	 * for transactional cursors}
	 * @config{overwrite, if an existing key is inserted\, overwrite the
	 * existing value}
	 * @config{printable, for dump cursors\, pass through printable bytes
	 * unmodified.}
	 * @config{raw, ignore the encodings for the key and value\, manage data
	 * as if the formats were \c "u"}
	 * @configend
	 * @param cursorp a pointer to the newly opened cursor
	 * @errors
	 */
	int __F(open_cursor)(WT_SESSION *session,
	    const char *uri, WT_CURSOR *to_dup,
	    const char *config, WT_CURSOR **cursorp);
	/*! @} */

	/*! @name Table operations
	 * @{
	 */
	/*! Create a table.
	 *
	 * @todo Allow both sets of syntax for describing schemas.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->create
	 *
	 * @param session the session handle
	 * @param name the uri of the object to create, such as \c "table:stock"
	 * @configstart{session.create, see dist/api_data.py}
	 * @config{allocation_size, file unit allocation size\, in bytes}
	 * @config{columns, list of the column names.  Comma-separated list of
	 * the form <code>(column[\,...])</code>.  The number of entries must
	 * match the total number of values in \c key_format and \c
	 * value_format.}
	 * @config{colgroup.\<name\>, named group of columns to store together.
	 * Comma-separated list of the form <code>(column[\,...])</code>.  Each
	 * column group is stored separately\, keyed by the primary key of the
	 * table.  Any column that does not appear in a column group is stored
	 * in a default\, unnamed\, column group for the table.}
	 * @config{exclusive, fail if the table exists (if "no"\, the default\,
	 * verifies that the table exists and has the specified schema.}
	 * @config{huffman_key, use Huffman encoding for the key.  Permitted
	 * values are empty (off) or \c "english"}
	 * @config{huffman_value, use Huffman encoding for the value.  Permitted
	 * values are empty (off) or \c "english"}
	 * @config{index.\<name\>, named index on a list of columns.  Comma-
	 * separated list of the form <code>(column[\,...])</code>.}
	 * @config{intl_node_max, maximum page size for internal nodes\, in
	 * bytes}
	 * @config{intl_node_min, minimum page size for internal nodes\, in
	 * bytes}
	 * @config{key_format, the format of the data packed into key items.
	 * See @ref packing for details.  If not set\, a default value of \c "u"
	 * is assumed\, and applications use the WT_ITEM struct to manipulate
	 * raw byte arrays.}
	 * @config{leaf_node_max, maximum page size for leaf nodes\, in bytes}
	 * @config{leaf_node_min, minimum page size for leaf nodes\, in bytes}
	 * @config{runlength_encoding, compress repeated adjacent values}
	 * @config{value_format, the format of the data packed into value items.
	 * See @ref packing for details.  If not set\, a default value of \c "u"
	 * is assumed\, and applications use the WT_ITEM struct to manipulate
	 * raw byte arrays.}
	 * @configend
	 * @errors
	 */
	int __F(create)(WT_SESSION *session,
	    const char *name, const char *config);

	/*! Drop (delete) a table.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->drop
	 *
	 * @param session the session handle
	 * @param name the uri of the table to drop, such as \c "table:stock"
	 * @configstart{session.drop, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(drop)(WT_SESSION *session,
	    const char *name, const char *config);

	/*! Rename a table.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->rename
	 *
	 * @param session the session handle
	 * @param oldname the current uri of the table, such as \c "table:old"
	 * @param newname the new name of the table, e.g., \c "table:new"
	 * @configstart{session.rename, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(rename)(WT_SESSION *session,
	    const char *oldname, const char *newname, const char *config);

	/*! Salvage a table.
	 *
	 * @todo describe salvage
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->salvage
	 *
	 * @param session the session handle
	 * @param name the uri of the table to salvage
	 * @configstart{session.salvage, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(salvage)(WT_SESSION *session,
	    const char *name, const char *config);

	/*! Sync a table.
	 *
	 * @todo describe sync
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->sync
	 *
	 * @param session the session handle
	 * @param name the uri of the table to sync
	 * @configstart{session.sync, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(sync)(WT_SESSION *session,
	    const char *name, const char *config);

	/*! Truncate a table.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->truncate
	 *
	 * @param session the session handle
	 * @param name the uri of the table to truncate
	 * @param start optional cursor marking the start of the truncate
	 * operation.  If <code>NULL</code>, the truncate starts from the
	 * beginning of the table
	 * @param end optional cursor marking the end of the truncate
	 * operation.  If <code>NULL</code>, the truncate continues to the end
	 * of the table
	 * @param name the name of the table
	 * @configstart{session.truncate, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(truncate)(WT_SESSION *session,
	    const char *name,
	    WT_CURSOR *start, WT_CURSOR *end, const char *config);

	/*! Verify a table.
	 *
	 * @todo describe salvage
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->verify
	 *
	 * @param session the session handle
	 * @param name the uri of the table to verify
	 * @configstart{session.verify, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(verify)(WT_SESSION *session,
	    const char *name, const char *config);
	/*! @} */

	/*! @name Transactions
	 * @{
	 */
	/*! Start a transaction in this session.
	 *
	 * All cursors opened in this session that support transactional
	 * semantics will operate in the context of the transaction.  The
	 * transaction remains active until ended with
	 * WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction.
	 *
	 * Ignored if a transaction is in progress.
	 *
	 * @todo describe nested transactions / savepoints
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->begin_transaction
	 *
	 * @param session the session handle
	 * @configstart{session.begin_transaction, see dist/api_data.py}
	 * @config{isolation, the isolation level for this transaction\, one of
	 * "serializable"\, "snapshot"\, "read-committed" or "read-uncommitted";
	 * default "serializable"}
	 * @config{name, name of the transaction for tracing and debugging}
	 * @config{sync, how to sync log records when the transaction commits\,
	 * one of "full"\, "flush"\, "write" or "none"}
	 * @config{priority, priority of the transaction for resolving
	 * conflicts\, an integer between -100 and 100.  Transactions with
	 * higher values are less likely to abort}
	 * @configend
	 * @errors
	 */
	int __F(begin_transaction)(WT_SESSION *session, const char *config);

	/*! Commit the current transaction.
	 *
	 * Any cursors opened during the transaction will be closed before
	 * the commit is processed.
	 *
	 * Ignored if no transaction is in progress.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->commit_transaction
	 *
	 * @param session the session handle
	 * @configstart{session.commit_transaction, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(commit_transaction)(WT_SESSION *session, const char *config);

	/*! Roll back the current transaction.
	 *
	 * Any cursors opened during the transaction will be closed before
	 * the rollback is processed.
	 *
	 * Ignored if no transaction is in progress.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->rollback_transaction
	 *
	 * @param session the session handle
	 * @configstart{session.rollback_transaction, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(rollback_transaction)(WT_SESSION *session, const char *config);

	/*! Flush the cache and/or the log and optionally archive log files.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->checkpoint
	 *
	 * @param session the session handle
	 * @configstart{session.checkpoint, see dist/api_data.py}
	 * @config{archive, remove log files no longer required for
	 * transactional durabilty}
	 * @config{force, write a new checkpoint even if nothing has changed
	 * since the last one}
	 * @config{flush_cache, flush the cache}
	 * @config{flush_log, flush the log}
	 * @config{log_size, only proceed if more than the specified number of
	 * bytes of log records have been written since the last checkpoint}
	 * @config{timeout, only proceed if more than the specified number of
	 * milliseconds have elapsed since the last checkpoint}
	 * @configend
	 * @errors
	 */
	int __F(checkpoint)(WT_SESSION *session, const char *config);

	/*! Put a string into the log for debugging.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->log_printf
	 *
	 * @param session the session handle
	 * @param fmt a printf-like format specification
	 * @errors
	 */
	int __F(log_printf)(WT_SESSION *session, const char *fmt, ...);
	/*! @} */
};

/*!
 * A connection to a WiredTiger database.  The connection may be opened within
 * the same address space as the caller or accessed over a socket connection.
 *
 * Most applications will open a single connection to a database for each
 * process.  The first process to open a connection to a database will access
 * the database in its own address space.  Subsequent connections (if allowed)
 * will communicate with the first process over a socket connection to perform
 * their operations.
 */
struct wt_connection {
	/*! Load an extension.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->load_extension
	 *
	 * @param connection the connection handle
	 * @param path the filename of the extension module
	 * @configstart{connection.load_extension, see dist/api_data.py}
	 * @config{entry, the entry point of the extension}
	 * @config{prefix, a prefix for all names registered by this extension
	 * (e.g.\, to make namespaces distinct or during upgrades}
	 * @configend
	 * @errors
	 */
	int __F(load_extension)(WT_CONNECTION *connection,
	    const char *path, const char *config);

	/*! Add a new type of cursor.
	 *
	 * @dontinclude ex_all.c
	 *
	 * First the application must implement the WT_CURSOR_TYPE interface
	 * as follows:
	 * @skip Implementation of WT_CURSOR_TYPE
	 * @until End implementation
	 *
	 * Then the implementation is registered with WiredTiger as follows:
	 * @skip WT_CURSOR_TYPE
	 * @until add_cursor_type
	 *
	 * @param connection the connection handle
	 * @param prefix the prefix for location strings passed to
	 * WT_SESSION::open_cursor
	 * @param ctype the application-supplied code to manage cursors of
	 * this type
	 * @configstart{connection.add_cursor_type, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(add_cursor_type)(WT_CONNECTION *connection,
	    const char *prefix, WT_CURSOR_TYPE *ctype, const char *config);

	/*! Add a custom collation function.
	 *
	 * @dontinclude ex_all.c
	 *
	 * First the application has to implement the WT_COLLATOR interface
	 * as follows:
	 * @skip Implementation of WT_COLLATOR
	 * @until End implementation
	 *
	 * Then the implementation is registered with WiredTiger as follows:
	 * @skip WT_COLLATOR
	 * @until add_collator
	 *
	 * @param connection the connection handle
	 * @param name the name of the collation to be used in calls to
	 * 	WT_SESSION::create
	 * @param collator the application-supplied collation handler
	 * @configstart{connection.add_collator, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(add_collator)(WT_CONNECTION *connection,
	    const char *name, WT_COLLATOR *collator, const char *config);

	/*! Add a custom extractor for index keys or column groups.
	 *
	 * @dontinclude ex_all.c
	 *
	 * First the application has to implement the WT_EXTRACTOR interface
	 * as follows:
	 * @skip Implementation of WT_EXTRACTOR
	 * @until End implementation
	 *
	 * Then the implementation is registered with WiredTiger as follows:
	 * @skip WT_EXTRACTOR
	 * @until add_extractor
	 *
	 * @param connection the connection handle
	 * @param name the name of the extractor to be used in calls to
	 * 	WT_SESSION::create
	 * @param extractor the application-supplied extractor
	 * @configstart{connection.add_extractor, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(add_extractor)(WT_CONNECTION *connection, const char *name,
	    WT_EXTRACTOR *extractor, const char *config);

	/*! Close a connection.
	 *
	 * Any open sessions will be closed.
	 *
	 * @dontinclude ex_all.c
	 * @skipline conn->close
	 *
	 * @param connection the connection handle
	 * @configstart{connection.close, see dist/api_data.py}
	 * @configend
	 * @errors
	 */
	int __F(close)(WT_CONNECTION *connection, const char *config);

	/*! The home directory of the connection.
	 *
	 * @dontinclude ex_all.c
	 * @skipline ->get_home
	 *
	 * @param connection the connection handle
	 * @returns a pointer to a string naming the home directory
	 */
	const char *__F(get_home)(WT_CONNECTION *connection);

	/*! Did opening this handle create the database?
	 *
	 * @dontinclude ex_all.c
	 * @skip ->is_new
	 * @until }
	 *
	 * @param connection the connection handle
	 * @returns false (zero) if the connection existed before the call to
	 *    ::wiredtiger_open, true (non-zero) if it was created by opening
	 *    this handle.
	 */
	int __F(is_new)(WT_CONNECTION *connection);

	/*! Open a session.
	 *
	 * @dontinclude ex_all.c
	 * @skip session;
	 * @until open_session
	 *
	 * @param connection the connection handle
	 * @param errhandler An error handler.  If <code>NULL</code>, the
	 * connection's error handler is used
	 * @configempty
	 * @param sessionp the new session handle
	 * @errors
	 */
	int __F(open_session)(WT_CONNECTION *connection,
	    WT_EVENT_HANDLER *errhandler, const char *config,
	    WT_SESSION **sessionp);
};

/*! Open a connection to a database.
 *
 * @dontinclude ex_all.c
 * @skip conn;
 * @until wiredtiger_open
 *
 * @param home The path to the database home directory
 * @param errhandler An error handler.  If <code>NULL</code>, a builtin error
 * handler is installed that writes error messages to stderr
 * @configstart{wiredtiger_open, see dist/api_data.py}
 * @config{cache_size, maximum heap memory to allocate for the cache}
 * @config{create, create the database if it does not exist}
 * @config{data_update_max, maximum update buffer size for a session}
 * @config{data_update_min, minimum update buffer size for a session}
 * @config{exclusive, fail if the database already exists}
 * @config{error_prefix, Prefix string for error messages}
 * @config{hazard_max, number of hazard references per session}
 * @config{logging, enable logging}
 * @config{session_max, maximum expected number of sessions (including server
 * threads)}
 * @config{multiprocess, permit sharing between processes (will automatically
 * start an RPC server for primary processes and use RPC for secondary
 * processes)}
 * @config{verbose, enable messages for various events.  One or more of "all"\,
 * "evict"\, "fileops"\, "hazard"\, "mutex"\, "read".  Multiple options are
 * given as a list such as \c "verbose=[evict\,read]"}
 * @configend
 * @param connectionp A pointer to the newly opened connection handle
 * @errors
 */
int wiredtiger_open(const char *home,
    WT_EVENT_HANDLER *errhandler, const char *config,
    WT_CONNECTION **connectionp);

/*! Get information about an error as a string.
 *
 * @dontinclude ex_all.c
 * @skipline wiredtiger_strerror
 *
 * @param err a return value from a WiredTiger call
 * @returns a string representation of the error
 */
const char *wiredtiger_strerror(int err);

/*!
 * The interface implemented by applications in order to handle errors messages,
 * information messages and progress.
 */
struct wt_event_handler {
	/*! Callback to handle errors. */
	void (*handle_error)(WT_EVENT_HANDLER *handler,
	    int error, const char *errmsg);

	/*! Callback to handle informational messages. */
	int (*handle_message)(WT_EVENT_HANDLER *handler, const char *message);

	/*! Callback to handle informational messages. */
	int (*handle_progress)(WT_EVENT_HANDLER *handler,
	    const char *operation, uint64_t progress);
};

/*! Pack a structure into a buffer.
 *
 * See @ref packing for a description of the permitted format strings.
 *
 * @section pack_examples Packing Examples
 *
 * For example, the string <code>"iSh"</code> will pack a 32-bit integer
 * followed by a NUL-terminated string, followed by a 16-bit integer.  The
 * default, big-endian encoding will be used, with no alignment.  This could
 * be used in C as follows:
 *
 * @dontinclude ex_all.c
 * @skip char buf
 * @until wiredtiger_struct_pack
 *
 * Then later, the values can be unpacked as follows:
 *
 * @until wiredtiger_struct_unpack
 *
 * @param buffer a pointer to a packed byte array
 * @param size the number of valid bytes in the buffer
 * @param format the data format, see ::wiredtiger_struct_pack
 * @errors
 */
int wiredtiger_struct_pack(void *buffer, size_t size, const char *format, ...);

/*! Pack a structure into a buffer.
 *
 * stdarg version of ::wiredtiger_struct_pack.
 *
 * @param buffer a pointer to a packed byte array
 * @param size the number of valid bytes in the buffer
 * @param format the data format, see ::wiredtiger_struct_pack
 * @param ap the list of values to pack
 * @errors
 */
int wiredtiger_struct_packv(void *buffer, size_t size,
    const char *format, va_list ap);

/*! Calculate the size required to pack a structure.
 *
 * Note that for variable-sized fields including variable-sized strings and
 * integers, the calculated sized merely reflects the expected sizes specified
 * in the format string itself.
 *
 * @dontinclude ex_all.c
 * @skip size_t size;
 * @until assert
 *
 * @param format the data format, see ::wiredtiger_struct_pack
 * @returns the number of bytes needed for the matching call to
 * ::wiredtiger_struct_pack
 */
size_t wiredtiger_struct_size(const char *format, ...);

/*! Calculate the size required to pack a structure.
 *
 * stdarg version of ::wiredtiger_struct_size.
 *
 * @param format the data format, see ::wiredtiger_struct_pack
 * @param ap the list of values to be packed
 * @returns the number of bytes needed for the matching call to
 * ::wiredtiger_struct_pack
 */
size_t wiredtiger_struct_sizev(const char *format, va_list ap);

/*! Unpack a structure from a buffer.
 *
 * Reverse of ::wiredtiger_struct_pack: gets values out of a packed byte string.
 *
 * @dontinclude ex_all.c
 * @skip int i;
 * @until wiredtiger_struct_unpack
 *
 * @param buffer a pointer to a packed byte array
 * @param size the number of valid bytes in the buffer
 * @param format the data format, see ::wiredtiger_struct_pack
 * @errors
 */
int wiredtiger_struct_unpack(const void *buffer, size_t size,
    const char *format, ...);

/*! Unpack a structure from a buffer.
 *
 * stdarg version of ::wiredtiger_struct_unpack.
 *
 * @param buffer a pointer to a packed byte array
 * @param size the number of valid bytes in the buffer
 * @param format the data format, see ::wiredtiger_struct_pack
 * @param ap the list of locations where values are unpacked
 * @errors
 */
int wiredtiger_struct_unpackv(const void *buffer, size_t size,
    const char *format, va_list ap);

/*! Get version information.
 *
 * @dontinclude ex_all.c
 * @skip int major
 * @until wiredtiger_version
 *
 * @param majorp a location where the major version number is returned
 * @param minorp a location where the minor version number is returned
 * @param patchp a location where the patch version number is returned
 * @returns a string representation of the version
 */
const char *wiredtiger_version(int *majorp, int *minorp, int *patchp);

/*******************************************
 * Error returns
 *******************************************/
/*
 * DO NOT EDIT: automatically built by dist/api_err.py.
 * Error return section: BEGIN
 */
/*! Conflict with concurrent operation. */
#define	WT_DEADLOCK	-31800
/*! Non-specific WiredTiger error. */
#define	WT_ERROR	-31801
/*! Item not found. */
#define	WT_NOTFOUND	-31802
/*! Attempt to modify a read-only value. */
#define	WT_READONLY	-31803
/*! Restart the operation (internal). */
#define	WT_RESTART	-31804
/*! Buffer too small. */
#define	WT_TOOSMALL	-31805
/*
 * Error return section: END
 * DO NOT EDIT: automatically built by dist/api_err.py.
 */

/*! @} */

/*! @defgroup wt_ext WiredTiger Extension API
 * The functions and interfaces that applications use to customize and extend
 * the behavior of WiredTiger.
 *
 * @{
 */

/*!
 * The interface implemented by applications to provide custom ordering of
 * records.  Applications register their implementation with WiredTiger by
 * calling WT_CONNECTION::add_collator.
 */
struct wt_collator {
	/*! Callback to compare keys.
	 *
	 * @param[out] cmp set to -1 if <code>key1 < key2</code>,
	 * 	0 if <code>key1 == key2</code>,
	 * 	1 if <code>key1 > key2</code>.
	 * @param[out] minprefix set to the minimum number of bytes
	 * 	required to distinguish between the two items.
	 * @returns zero for success, non-zero to indicate an error.
	 */
	int (*compare)(WT_SESSION *session, WT_COLLATOR *collator,
	    const WT_ITEM *key1, const WT_ITEM *key2,
	    int *cmp, uint32_t *minprefix);
};

/*!
 * Applications can extend WiredTiger by providing new implementation of the
 * WT_CURSOR class.  This is done by implementing the WT_CURSOR_TYPE
 * interface, then calling WT_CONNECTION::add_cursor_type.
 *
 * <b>Thread safety:</b> WiredTiger may invoke methods on the WT_CURSOR_TYPE
 * interface from multiple threads concurrently.  It is the responsibility of
 * the implementation to protect any shared data.
 */
struct wt_cursor_type {
	/*! Callback to determine how much space to allocate for a cursor.
	 *
	 * If the callback is NULL, no additional space is allocated in the
	 * WT_CURSOR implementation.
	 *
	 * @errors
	 */
	int (*cursor_size)(WT_CURSOR_TYPE *ctype,
	    const char *obj, size_t *sizep);

	/*! Callback to initialize a cursor. */
	int (*init_cursor)(WT_CURSOR_TYPE *ctype,
	    WT_SESSION *session, const char *obj, WT_CURSOR *old_cursor,
	    const char *config, WT_CURSOR *new_cursor);
};

/*!
 * The interface implemented by applications to provide custom extraction of
 * index keys or column group values.  Applications register implementations
 * with WiredTiger by calling WT_CONNECTION::add_extractor.
 */
struct wt_extractor {
	/*! Callback to extract a value for an index or column group.
	 *
	 * @errors
	 */
	int (*extract)(WT_SESSION *session, WT_EXTRACTOR *extractor,
	    const WT_ITEM *key, const WT_ITEM *value,
	    WT_ITEM *result);
};

/*! Entry point to an extension, implemented by loadable modules.
 *
 * @param connection the connection handle
 * @configempty
 * @errors
 */
extern int wiredtiger_extension_init(WT_CONNECTION *connection,
    const char *config);

#ifdef __cplusplus
}
#endif

/*! @} */

#if defined(__cplusplus)
}
#endif
#endif /* __WIREDTIGER_H_ */