adbc_driver_manager.h File Reference

#include <arrow-adbc/adbc.h>
#include <stdint.h>

Go to the source code of this file.

Macros
#define	ADBC_LOAD_FLAG_SEARCH_ENV   1
#define	ADBC_LOAD_FLAG_SEARCH_USER   2
#define	ADBC_LOAD_FLAG_SEARCH_SYSTEM   4
#define	ADBC_LOAD_FLAG_ALLOW_RELATIVE_PATHS   8
#define	ADBC_LOAD_FLAG_DEFAULT

Typedefs
typedef uint32_t	AdbcLoadFlags

Functions
AdbcStatusCode	AdbcLoadDriver (const char *driver_name, const char *entrypoint, int version, void *driver, struct AdbcError *error)
	Common entry point for drivers via the driver manager.
AdbcStatusCode	AdbcFindLoadDriver (const char *driver_name, const char *entrypoint, const int version, const AdbcLoadFlags load_options, void *driver, struct AdbcError *error)
	Common entry point to search for and load a driver or manifest.
AdbcStatusCode	AdbcLoadDriverFromInitFunc (AdbcDriverInitFunc init_func, int version, void *driver, struct AdbcError *error)
	Common entry point for drivers via the driver manager.
AdbcStatusCode	AdbcDriverManagerDatabaseSetInitFunc (struct AdbcDatabase *database, AdbcDriverInitFunc init_func, struct AdbcError *error)
	Set the AdbcDriverInitFunc to use.
AdbcStatusCode	AdbcDriverManagerDatabaseSetLoadFlags (struct AdbcDatabase *database, AdbcLoadFlags flags, struct AdbcError *error)
	Set the load flags for the driver manager.
const char *	AdbcStatusCodeMessage (AdbcStatusCode code)
	Get a human-friendly description of a status code.

Detailed Description

ADBC Driver Manager

A helper library to dynamically load and use multiple ADBC drivers in the same process.

Macro Definition Documentation

ADBC_LOAD_FLAG_DEFAULT

#define ADBC_LOAD_FLAG_DEFAULT

Value:

  (ADBC_LOAD_FLAG_SEARCH_ENV | ADBC_LOAD_FLAG_SEARCH_USER | \
   ADBC_LOAD_FLAG_SEARCH_SYSTEM | ADBC_LOAD_FLAG_ALLOW_RELATIVE_PATHS)

Function Documentation

AdbcDriverManagerDatabaseSetInitFunc()

AdbcStatusCode AdbcDriverManagerDatabaseSetInitFunc	(	struct AdbcDatabase *	database,
		AdbcDriverInitFunc	init_func,
		struct AdbcError *	error )

Set the AdbcDriverInitFunc to use.

This is an extension to the ADBC API. The driver manager shims the AdbcDatabase* functions to allow you to specify the driver/entrypoint dynamically. This function lets you set the entrypoint explicitly, for applications that can dynamically load drivers on their own.

AdbcDriverManagerDatabaseSetLoadFlags()

AdbcStatusCode AdbcDriverManagerDatabaseSetLoadFlags	(	struct AdbcDatabase *	database,
		AdbcLoadFlags	flags,
		struct AdbcError *	error )

Set the load flags for the driver manager.

This is an extension to the ADBC API. The driver manager shims the AdbcDatabase* functions to allow you to specify the driver/entrypoint dynamically. This function lets you set the load flags explicitly, for applications that can dynamically load drivers on their own.

If this function isn't called, the default load flags are just to allow relative paths, disallowing the lookups of manifests.

AdbcFindLoadDriver()

AdbcStatusCode AdbcFindLoadDriver	(	const char *	driver_name,
		const char *	entrypoint,
		const int	version,
		const AdbcLoadFlags	load_options,
		void *	driver,
		struct AdbcError *	error )

Common entry point to search for and load a driver or manifest.

The driver manager can fill in default implementations of some ADBC functions for drivers. Drivers must implement a minimum level of functionality for this to be possible, however, and some functions must be implemented by the driver.

This function is different from AdbcLoadDriver in that it also accepts the name of a driver manifest file, and allows specifying options to control what directories it will search through. The behavior is as follows:

If the passed in driver_name is an absolute path:

• If the path has a .toml extension, it will attempt to parse the manifest and load the driver specified within it. Erroring if this fails.
• If the path has an extension other than .toml, it will attempt to load the path as a shared library. Erroring if this fails.

If the passed in driver_name does not have an extension and is not an absolute path:

• The load_options parameter will control whether the driver manager will search the ADBC_CONFIG_PATH environment variable, the user configuration directory, and/or the system level directory of /etc/adbc for either a manifest file or a shared library.
• For each path to be searched, it will first look for <path>/<driver_name>.toml. If that file exists, it will attempt to parse the manifest and load the driver specified within it, erroring if this fails.
• If the manifest file does not exist, it will then look for <path>/<driver_name>.<extension> where <extension> is one of the following: .so, .dll, .dylib. If it can load that shared library, then success is returned. Otherwise it moves to the next directory until the search is either successful, or all directories have been searched.

Parameters

[in]	driver_name	An identifier for the driver (e.g. a path to a shared library on Linux or the basename of a manifest file).
[in]	entrypoint	An identifier for the entrypoint (e.g. the symbol to call for AdbcDriverInitFunc on Linux). If not provided, search for an entrypoint based on the driver name.
[in]	version	The ADBC revision to attempt to initialize.
[in]	load_options	bit mask of AdbcLoadFlags to control the directories searched
[out]	raw_driver	The table of function pointers to initialize
[out]	error	An optional location to return an error message

Returns

AdbcLoadDriver()

AdbcStatusCode AdbcLoadDriver	(	const char *	driver_name,
		const char *	entrypoint,
		int	version,
		void *	driver,
		struct AdbcError *	error )

Common entry point for drivers via the driver manager.

The driver manager can fill in default implementations of some ADBC functions for drivers. Drivers must implement a minimum level of functionality for this to be possible, however, and some functions must be implemented by the driver.

Parameters

[in]	driver_name	An identifier for the driver (e.g. a path to a shared library on Linux).
[in]	entrypoint	An identifier for the entrypoint (e.g. the symbol to call for AdbcDriverInitFunc on Linux). If not provided, search for an entrypoint based on the driver name.
[in]	version	The ADBC revision to attempt to initialize.
[out]	driver	The table of function pointers to initialize.
[out]	error	An optional location to return an error message if necessary.

AdbcLoadDriverFromInitFunc()

AdbcStatusCode AdbcLoadDriverFromInitFunc	(	AdbcDriverInitFunc	init_func,
		int	version,
		void *	driver,
		struct AdbcError *	error )

Common entry point for drivers via the driver manager.

The driver manager can fill in default implementations of some ADBC functions for drivers. Drivers must implement a minimum level of functionality for this to be possible, however, and some functions must be implemented by the driver.

Parameters

[in]	init_func	The entrypoint to call.
[in]	version	The ADBC revision to attempt to initialize.
[out]	driver	The table of function pointers to initialize.
[out]	error	An optional location to return an error message if necessary.

AdbcStatusCodeMessage()

const char * AdbcStatusCodeMessage

(

AdbcStatusCode

code

)

Get a human-friendly description of a status code.