Class for managing the registration of file format drivers. More...

#include <gdal_priv.h>

Inheritance diagram for GDALDriverManager:

Public Member Functions
int	GetDriverCount (void) const
	Fetch the number of registered drivers. More...

GDALDriver *	GetDriver (int)
	Fetch driver by index. More...

GDALDriver *	GetDriverByName (const char *)
	Fetch a driver based on the short name. More...

int	RegisterDriver (GDALDriver *)
	Register a driver for use. More...

void	DeregisterDriver (GDALDriver *)
	Deregister the passed driver. More...

void	AutoLoadDrivers ()
	Auto-load GDAL drivers from shared libraries. More...

void	AutoSkipDrivers ()
	This method unload undesirable drivers. More...

void	ReorderDrivers ()
	Reorder drivers according to the order of the drivers.ini file. More...

int	GetMOFlags () const
	Returns the GMO_ flags. More...

void	SetMOFlags (int nFlagsIn)
	Assign GMO_flags. More...

virtual const char *	GetDescription () const
	Fetch object description. More...

virtual void	SetDescription (const char *)
	Set object description. More...

virtual char **	GetMetadataDomainList ()
	Fetch list of metadata domains. More...

virtual char **	GetMetadata (const char *pszDomain="")
	Fetch metadata. More...

virtual CPLErr	SetMetadata (char *papszMetadata, const char pszDomain="")
	Set metadata. More...

virtual const char *	GetMetadataItem (const char pszName, const char pszDomain="")
	Fetch single metadata item. More...

virtual CPLErr	SetMetadataItem (const char pszName, const char pszValue, const char *pszDomain="")
	Set single metadata item. More...

Static Public Member Functions
static void	AutoLoadPythonDrivers ()
	Auto-load GDAL drivers from Python scripts. More...

static GDALMajorObjectH	ToHandle (GDALMajorObject *poMajorObject)
	Convert a GDALMajorObject* to a GDALMajorObjectH. More...

static GDALMajorObject *	FromHandle (GDALMajorObjectH hMajorObject)
	Convert a GDALMajorObjectH to a GDALMajorObject*. More...

Protected Member Functions
char **	BuildMetadataDomainList (char **papszList, int bCheckNonEmpty,...) CPL_NULL_TERMINATED
	Helper function for custom implementations of GetMetadataDomainList() More...

Detailed Description

Class for managing the registration of file format drivers.

Use GetGDALDriverManager() to fetch the global singleton instance of this class.

Member Function Documentation

◆ AutoLoadDrivers()

void GDALDriverManager::AutoLoadDrivers ( )

Auto-load GDAL drivers from shared libraries.

This function will automatically load drivers from shared libraries. It searches the "driver path" for .so (or .dll) files that start with the prefix "gdal_X.so". It then tries to load them and then tries to call a function within them called GDALRegister_X() where the 'X' is the same as the remainder of the shared library basename ('X' is case sensitive), or failing that to call GDALRegisterMe().

There are a few rules for the driver path. If the GDAL_DRIVER_PATH environment variable it set, it is taken to be a list of directories to search separated by colons on UNIX, or semi-colons on Windows. Otherwise the /usr/local/lib/gdalplugins directory, and (if known) the lib/gdalplugins subdirectory of the gdal home directory are searched on UNIX and \gdalplugins on Windows.

Auto loading can be completely disabled by setting the GDAL_DRIVER_PATH config option to "disable".

Starting with gdal 3.5, the default search path /lib/gdalplugins can be overridden at compile time by passing -DINSTALL_PLUGIN_DIR=/another/path to cmake.

◆ AutoLoadPythonDrivers()

void GDALDriverManager::AutoLoadPythonDrivers ( )

static

Auto-load GDAL drivers from Python scripts.

This function will automatically load drivers from Python scripts. It searches them first from the directory pointed by the GDAL_PYTHON_DRIVER_PATH configuration option. If not defined, it will use GDAL_DRIVER_PATH. If not defined, it will use the path for drivers hardcoded at build time. Scripts must begin with gdal_ or ogr_ and end up with .py

Since: GDAL 3.1

◆ AutoSkipDrivers()

void GDALDriverManager::AutoSkipDrivers ( )

This method unload undesirable drivers.

All drivers specified in the comma delimited list in the GDAL_SKIP environment variable) will be deregistered and destroyed. This method should normally be called after registration of standard drivers to allow the user a way of unloading undesired drivers. The GDALAllRegister() function already invokes AutoSkipDrivers() at the end, so if that functions is called, it should not be necessary to call this method from application code.

Note: space separator is also accepted for backward compatibility, but some vector formats have spaces in their names, so it is encouraged to use comma to avoid issues.

◆ BuildMetadataDomainList()

char ** GDALMajorObject::BuildMetadataDomainList	(	char **	papszList,
		int	bCheckNonEmpty,
			...
	)

protectedinherited

Helper function for custom implementations of GetMetadataDomainList()

Parameters

papszList	initial list of domains. May be NULL. Will become invalid after function call (use return value)
bCheckNonEmpty	if TRUE, each candidate domain will be tested to be non empty
...	NULL terminated variadic list of candidate domains.

Returns: NULL or a string list. Must be freed with CSLDestroy()

Since: GDAL 1.11

◆ DeregisterDriver()

void GDALDriverManager::DeregisterDriver ( GDALDriver * poDriver )

Deregister the passed driver.

If the driver isn't found no change is made.

The C analog is GDALDeregisterDriver().

Parameters

poDriver the driver to deregister.

◆ FromHandle()

static GDALMajorObject* GDALMajorObject::FromHandle ( GDALMajorObjectH hMajorObject )

inlinestaticinherited

Convert a GDALMajorObjectH to a GDALMajorObject*.

Since: GDAL 2.3

◆ GetDescription()

const char * GDALMajorObject::GetDescription ( ) const

virtualinherited

Fetch object description.

The semantics of the returned description are specific to the derived type. For GDALDatasets it is the dataset name. For GDALRasterBands it is actually a description (if supported) or "".

This method is the same as the C function GDALGetDescription().

Returns: non-null pointer to internal description string.

◆ GetDriver()

GDALDriver * GDALDriverManager::GetDriver ( int iDriver )

Fetch driver by index.

This C analog to this is GDALGetDriver().

Parameters

iDriver the driver index from 0 to GetDriverCount()-1.

Returns: the driver identified by the index or NULL if the index is invalid

◆ GetDriverByName()

GDALDriver * GDALDriverManager::GetDriverByName ( const char * pszName )

Fetch a driver based on the short name.

The C analog is the GDALGetDriverByName() function.

Parameters

pszName the short name, such as GTiff, being searched for.

Returns: the identified driver, or NULL if no match is found.

◆ GetDriverCount()

int GDALDriverManager::GetDriverCount ( void ) const

Fetch the number of registered drivers.

This C analog to this is GDALGetDriverCount().

Returns: the number of registered drivers.

◆ GetMetadata()

char ** GDALMajorObject::GetMetadata ( const char * pszDomain = "" )

virtualinherited

Fetch metadata.

The returned string list is owned by the object, and may change at any time. It is formatted as a "Name=value" list with the last pointer value being NULL. Use the CPL StringList functions such as CSLFetchNameValue() to manipulate it.

Note that relatively few formats return any metadata at this time.

This method does the same thing as the C function GDALGetMetadata().

Parameters

pszDomain the domain of interest. Use "" or NULL for the default domain.

Returns: NULL or a string list.

Reimplemented in GDALDataset, and GDALPamDataset.

◆ GetMetadataDomainList()

char ** GDALMajorObject::GetMetadataDomainList ( )

virtualinherited

Fetch list of metadata domains.

The returned string list is the list of (non-empty) metadata domains.

This method does the same thing as the C function GDALGetMetadataDomainList().

Returns: NULL or a string list. Must be freed with CSLDestroy()

Since: GDAL 1.11

Reimplemented in GDALDataset.

◆ GetMetadataItem()

const char * GDALMajorObject::GetMetadataItem	(	const char *	pszName,
		const char *	pszDomain = `""`
	)

virtualinherited

Fetch single metadata item.

The C function GDALGetMetadataItem() does the same thing as this method.

Parameters

pszName	the key for the metadata item to fetch.
pszDomain	the domain to fetch for, use NULL for the default domain.

Returns: NULL on failure to find the key, or a pointer to an internal copy of the value string on success.

Reimplemented in GDALPamDataset.

◆ GetMOFlags()

int GDALMajorObject::GetMOFlags ( ) const

inherited

Returns the GMO_ flags.

Returns: flags

◆ RegisterDriver()

int GDALDriverManager::RegisterDriver ( GDALDriver * poDriver )

Register a driver for use.

The C analog is GDALRegisterDriver().

Normally this method is used by format specific C callable registration entry points such as GDALRegister_GTiff() rather than being called directly by application level code.

If this driver (based on the object pointer, not short name) is already registered, then no change is made, and the index of the existing driver is returned. Otherwise the driver list is extended, and the new driver is added at the end.

Parameters

poDriver the driver to register.

Returns: the index of the new installed driver.

◆ ReorderDrivers()

void GDALDriverManager::ReorderDrivers ( )

Reorder drivers according to the order of the drivers.ini file.

This function is called by GDALAllRegister(), at the end of driver loading, in particular after plugin loading. It will load the drivers.ini configuration file located next to plugins and will use it to reorder the registration order of drivers. This can be important in some situations where multiple drivers could open the same dataset.

◆ SetDescription()

void GDALMajorObject::SetDescription ( const char * pszNewDesc )

virtualinherited

Set object description.

The semantics of the description are specific to the derived type. For GDALDatasets it is the dataset name. For GDALRasterBands it is actually a description (if supported) or "".

Normally application code should not set the "description" for GDALDatasets. It is handled internally.

This method is the same as the C function GDALSetDescription().

Reimplemented in GDALPamRasterBand.

◆ SetMetadata()

CPLErr GDALMajorObject::SetMetadata	(	char **	papszMetadataIn,
		const char *	pszDomain = `""`
	)

virtualinherited

Set metadata.

The C function GDALSetMetadata() does the same thing as this method.

Parameters

papszMetadataIn	the metadata in name=value string list format to apply.
pszDomain	the domain of interest. Use "" or NULL for the default domain.

Returns: CE_None on success, CE_Failure on failure and CE_Warning if the metadata has been accepted, but is likely not maintained persistently by the underlying object between sessions.

Reimplemented in GDALPamRasterBand, GDALPamDataset, GDALRasterBand, and GDALDataset.

◆ SetMetadataItem()

CPLErr GDALMajorObject::SetMetadataItem	(	const char *	pszName,
		const char *	pszValue,
		const char *	pszDomain = `""`
	)

virtualinherited

Set single metadata item.

The C function GDALSetMetadataItem() does the same thing as this method.

Parameters

pszName	the key for the metadata item to fetch.
pszValue	the value to assign to the key.
pszDomain	the domain to set within, use NULL for the default domain.

Returns: CE_None on success, or an error code on failure.

Reimplemented in GDALDriver, GDALPamRasterBand, GDALPamDataset, GDALRasterBand, and GDALDataset.

◆ SetMOFlags()

void GDALMajorObject::SetMOFlags ( int nNewFlags )

inherited

Assign GMO_flags.

Parameters

nNewFlags new flags.

◆ ToHandle()

static GDALMajorObjectH GDALMajorObject::ToHandle ( GDALMajorObject * poMajorObject )

inlinestaticinherited

Convert a GDALMajorObject* to a GDALMajorObjectH.

Since: GDAL 2.3

The documentation for this class was generated from the following files:

gdal_priv.h
gdaldrivermanager.cpp
gdalpythondriverloader.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ AutoLoadDrivers()

◆ AutoLoadPythonDrivers()

◆ AutoSkipDrivers()

◆ BuildMetadataDomainList()

◆ DeregisterDriver()

◆ FromHandle()

◆ GetDescription()

◆ GetDriver()

◆ GetDriverByName()

◆ GetDriverCount()

◆ GetMetadata()

◆ GetMetadataDomainList()

◆ GetMetadataItem()

◆ GetMOFlags()

◆ RegisterDriver()

◆ ReorderDrivers()

◆ SetDescription()

◆ SetMetadata()

◆ SetMetadataItem()

◆ SetMOFlags()

◆ ToHandle()