CMDBM_ModuleInterface Struct Reference

The set of callbacks a DBMS module implements. More...

Data Fields
void(*	LibraryInit )(void)
	Prepare the client library, once per process.
void(*	LibraryClear )(void)
	Release what LibraryInit prepared.
const char *(*	GetDBMSKey )(void)
	Identify the client library this module drives.
void *(*	Initialize )(const char *dbcs, const char *prcs)
	Create the context of one datasource.
void(*	CleanUp )(void *initres)
	Release the context Initialize created.
char *(*	GetBindString )(void *initres, uint32_t index, char *buffer, CMJsonValueType vtype)
	Write the placeholder of one bind variable.
const char *(*	GetTestQuery )(void)
	The statement which proves a pooled connection still works.
void *(*	OpenConnection )(void *initres, CMUTIL_JsonObject *params)
	Open one connection to the database.
void(*	CloseConnection )(void *initres, void *connection)
	Close a connection OpenConnection opened.
CMBool(*	StartTransaction )(void *initres, void *connection)
	Begin a transaction on one connection.
void(*	EndTransaction )(void *initres, void *connection)
	End the transaction StartTransaction began.
CMBool(*	CommitTransaction )(void *initres, void *connection)
	Commit the running transaction.
void(*	RollbackTransaction )(void *initres, void *connection)
	Roll the running transaction back.
CMUTIL_JsonValue *(*	GetOneValue )(void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)
	Run a statement and return its first column of its first row.
CMUTIL_JsonObject *(*	GetRow )(void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)
	Run a statement and return its first row.
CMUTIL_JsonArray *(*	GetList )(void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)
	Run a statement and return all of its rows.
int(*	Execute )(void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)
	Run a statement for its effect.
void *(*	OpenCursor )(void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs, uint32_t fetchsize)
	Run a statement to be read row by row.
void(*	CloseCursor )(void *cursor)
	Close a cursor and release what it holds.
CMUTIL_JsonObject *(*	CursorNextRow )(void *cursor)
	Read the next row of a cursor.

Detailed Description

The set of callbacks a DBMS module implements.

Every member is called by the library only; an application fills the struct in and hands it to CMDBM_RegisterDBMS. The struct is copied into each datasource which uses it, so it may live on the stack of the registering function - but the registry keeps the pointer as well, so a static or heap instance is the safer choice.

Three opaque pointers travel through the interface:

• initres - whatever Initialize returned. One per datasource.
• connection - whatever OpenConnection returned. One per pooled connection.
• cursor - whatever OpenCursor returned. One per open iteration.

The statement callbacks share the same four arguments: the final SQL text, the values to bind in placeholder order, and the map of the OUT parameters to be written back. None of the JSON objects handed in is owned by the module - it must neither destroy them nor keep references to them beyond the call.

Field Documentation

LibraryInit

void(* CMDBM_ModuleInterface::LibraryInit) (void)

Prepare the client library, once per process.

Called before the first datasource which uses this client library is created, and never again while any datasource using it exists - the library is reference counted by the key GetDBMSKey reports, so a module registered under several names, or used by several datasources, still initializes once.

May be NULL when the client library needs no global setup.

LibraryClear

void(* CMDBM_ModuleInterface::LibraryClear) (void)

Release what LibraryInit prepared.

Called when the last datasource using this client library is destroyed. May be NULL - and should be, for client libraries whose global teardown cannot be undone by a later LibraryInit.

GetDBMSKey

const char *(* CMDBM_ModuleInterface::GetDBMSKey) (void)

Identify the client library this module drives.

The key is what the reference counting of LibraryInit and LibraryClear is keyed by, so modules which share a client library - the MySQL and MariaDB registrations are the same module - must report the same key. It is unrelated to the name the module is registered under.

Returns

A static string. If this member is NULL, or it returns NULL, the library callbacks are skipped altogether.

Initialize

void *(* CMDBM_ModuleInterface::Initialize) (const char *dbcs, const char *prcs)

Create the context of one datasource.

Called once per datasource, before any connection of it is opened. Nothing here talks to a database yet; this is where a module keeps what it needs for the lifetime of the datasource, character set conversion above all.

Parameters

dbcs	The character set the database stores text in, as configured for this datasource.
prcs	The character set the application works in - the one results are to be converted to.

Returns

The module context, handed back as initres to every other callback. NULL is allowed for a module which needs none, and then CleanUp is not called either.

CleanUp

void(* CMDBM_ModuleInterface::CleanUp) (void *initres)

Release the context Initialize created.

Called when the datasource is destroyed, after its connections are closed.

Parameters

initres

The module context.

GetBindString

char *(* CMDBM_ModuleInterface::GetBindString) (void *initres, uint32_t index, char *buffer, CMJsonValueType vtype)

Write the placeholder of one bind variable.

Called while the SQL text is being built, once for every #{...} expression, in the order the values will be bound in.

Parameters

initres	The module context.
index	Zero based position of the value among the bind variables of this statement. Client libraries which number their placeholders from one must add one, as the SQLite module does with its ?1 form.
buffer	Where to write the placeholder, at least 50 bytes.
vtype	JSON type of the value about to be bound, for the client libraries whose placeholder syntax depends on it.

Returns

buffer.

GetTestQuery

const char *(* CMDBM_ModuleInterface::GetTestQuery) (void)

The statement which proves a pooled connection still works.

Read when the datasource is created, and run through GetOneValue to validate a pooled connection, so it must return exactly one value - "select 1" for most databases, "select 1 from dual" for Oracle. It is what a datasource validates with unless its pool configuration names a statement of its own in CMDBM_PoolConfig::testsql.

Returns

A static string. It must not be NULL.

OpenConnection

void *(* CMDBM_ModuleInterface::OpenConnection) (void *initres, CMUTIL_JsonObject *params)

Open one connection to the database.

Parameters

initres	The module context.
params	The connection parameters of the datasource: the keys of its configuration object which are not meta keys of libcmdbm itself, with the values as configured. Owned by the datasource - read it, do not keep it.

Returns

The connection, handed back as connection to every statement callback, or NULL when the connection cannot be opened. Returning NULL is not fatal: the pool retries on the next checkout.

CloseConnection

void(* CMDBM_ModuleInterface::CloseConnection) (void *initres, void *connection)

Close a connection OpenConnection opened.

Parameters

initres	The module context.
connection	The connection to close.

StartTransaction

CMBool(* CMDBM_ModuleInterface::StartTransaction) (void *initres, void *connection)

Begin a transaction on one connection.

Called when a session which is in a transaction takes this connection, which for most client libraries means turning autocommit off.

Parameters

initres	The module context.
connection	The connection.

Returns

CMTrue when the connection is in a transaction afterwards.

EndTransaction

void(* CMDBM_ModuleInterface::EndTransaction) (void *initres, void *connection)

End the transaction StartTransaction began.

Called after the session committed or rolled back, and must leave the connection back in autocommit: it goes to the pool right afterwards and the next session must not inherit a transaction.

Parameters

initres	The module context.
connection	The connection.

CommitTransaction

CMBool(* CMDBM_ModuleInterface::CommitTransaction) (void *initres, void *connection)

Commit the running transaction.

Parameters

initres	The module context.
connection	The connection.

Returns

CMTrue when the commit succeeded.

RollbackTransaction

void(* CMDBM_ModuleInterface::RollbackTransaction) (void *initres, void *connection)

Roll the running transaction back.

Parameters

initres	The module context.
connection	The connection.

GetOneValue

CMUTIL_JsonValue *(* CMDBM_ModuleInterface::GetOneValue) (void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)

Run a statement and return its first column of its first row.

Parameters

initres	The module context.
connection	The connection.
query	The final SQL text.
binds	The values to bind, in placeholder order. References into the caller's parameter object: bind them, do not destroy or keep them.
outs	The OUT parameters, keyed by the decimal spelling of the zero based bind index of each. A module which can bind OUT parameters writes the returned values into these objects; one which cannot ignores the map.

Returns

The value, owned by the caller, or NULL when the statement failed or returned no row.

GetRow

CMUTIL_JsonObject *(* CMDBM_ModuleInterface::GetRow) (void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)

Run a statement and return its first row.

Column names become the keys of the object, in the case the database reports them.

Parameters

initres	The module context.
connection	The connection.
query	The final SQL text.
binds	The values to bind, in placeholder order.
outs	The OUT parameters - see GetOneValue.

Returns

The row, owned by the caller, or NULL when the statement failed or returned no row.

GetList

CMUTIL_JsonArray *(* CMDBM_ModuleInterface::GetList) (void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)

Run a statement and return all of its rows.

Parameters

initres	The module context.
connection	The connection.
query	The final SQL text.
binds	The values to bind, in placeholder order.
outs	The OUT parameters - see GetOneValue.

Returns

An array of row objects, owned by the caller - empty when the statement returned no row - or NULL when it failed. The difference matters: NULL is what the session reports as an error.

Execute

int(* CMDBM_ModuleInterface::Execute) (void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs)

Run a statement for its effect.

A statement executed this way may still produce rows - an insert ... returning does - and the module is expected to consume them.

Parameters

initres	The module context.
connection	The connection.
query	The final SQL text.
binds	The values to bind, in placeholder order.
outs	The OUT parameters - see GetOneValue.

Returns

The number of rows affected, or -1 when the statement failed.

OpenCursor

void *(* CMDBM_ModuleInterface::OpenCursor) (void *initres, void *connection, CMUTIL_String *query, CMUTIL_JsonArray *binds, CMUTIL_JsonObject *outs, uint32_t fetchsize)

Run a statement to be read row by row.

The cursor keeps the connection busy until CloseCursor, so a module must not need it for anything else in between.

Parameters

initres	The module context.
connection	The connection.
query	The final SQL text.
binds	The values to bind, in placeholder order.
outs	The OUT parameters - see GetOneValue.
fetchsize	The fetchSize attribute of the executed select, 0 when it is not given. It is a hint: modules which cannot control the fetch size of their client library may ignore it, and those which can read that many rows per round trip instead of buffering the whole result.

Returns

The cursor, handed back to CursorNextRow and CloseCursor, or NULL when the statement failed.

CloseCursor

void(* CMDBM_ModuleInterface::CloseCursor) (void *cursor)

Close a cursor and release what it holds.

Parameters

cursor

The cursor OpenCursor returned.

CursorNextRow

CMUTIL_JsonObject *(* CMDBM_ModuleInterface::CursorNextRow) (void *cursor)

Read the next row of a cursor.

Parameters

cursor

The cursor OpenCursor returned.

Returns

The row, owned by the caller, or NULL when the result is exhausted or the fetch failed.

---

The documentation for this struct was generated from the following file:

• /home/runner/work/libcmdbm/libcmdbm/src/libcmdbm.h