GDAL

Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
GDALDriverManager Class Reference

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...
void | DeclareDeferredPluginDriver (GDALPluginDriverProxy *poProxyDriver)
| Declare a driver that will be loaded as a plugin, when actually needed. 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 CPLErr | LoadPlugin (const char *name)
| Load a single GDAL driver/plugin from shared libraries. More...
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...

## Friends
class | GDALPluginDriverProxy
GDALDatasetH | GDALOpenEx (const char *pszFilename, unsigned int nOpenFlags, const char *const *papszAllowedDrivers, const char *const *papszOpenOptions, const char *const *papszSiblingFiles)
| Open a raster or vector file as a GDALDataset. 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,
|  |  | ...
| ) |  |
| protected inherited

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

## ◆ DeclareDeferredPluginDriver()

void GDALDriverManager::DeclareDeferredPluginDriver | ( | GDALPluginDriverProxy * | poProxyDriver | ) |

Declare a driver that will be loaded as a plugin, when actually needed.

Parameters

  poProxyDriver | Plugin driver proxy

Since
  3.9

## ◆ 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 | ) |
| inline static inherited

Convert a GDALMajorObjectH to a GDALMajorObject*.

Since
  GDAL 2.3

## ◆ GetDescription()

const char * GDALMajorObject::GetDescription | ( |  | ) | const
| virtual inherited

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 = `""` | ) |
| virtual inherited

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 GDALPluginDriverProxy, GDALPamDataset, and GDALDataset.

## ◆ GetMetadataDomainList()

char ** GDALMajorObject::GetMetadataDomainList | ( |  | ) |
| virtual inherited

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 = `""`
| ) |  |
| virtual inherited

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, GDALRasterBand, and GDALPluginDriverProxy.

## ◆ GetMOFlags()

int GDALMajorObject::GetMOFlags | ( |  | ) | const
| inherited

Returns the GMO_ flags.

Returns
  flags

## ◆ LoadPlugin()

CPLErr GDALDriverManager::LoadPlugin | ( | const char * | name | ) |
| static

Load a single GDAL driver/plugin from shared libraries.

This function will load a single named driver/plugin from shared libraries. It searches the "driver path" for .so (or .dll) files named "gdal_{name}.[so|dll|dylib]" or "ogr_{name}.[so|dll|dylib]", then tries to call a function within them called GDALRegister_{name}(), or failing that called GDALRegisterMe().

See also
  GDALDriverManager::AutoLoadDrivers() for the rules used to determine which paths are searched for plugin library files.

## ◆ 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 | ) |
| virtual inherited

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 = `""`
| ) |  |
| virtual inherited

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 GDALDataset, GDALRasterBand, GDALPamDataset, and GDALPamRasterBand.

## ◆ SetMetadataItem()

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

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 GDALDataset, GDALRasterBand, GDALPamDataset, GDALPamRasterBand, GDALDriver, and GDALPluginDriverProxy.

## ◆ SetMOFlags()

void GDALMajorObject::SetMOFlags | ( | int | nNewFlags | ) |
| inherited

Assign GMO_flags.

Parameters

  nNewFlags | new flags.

## ◆ ToHandle()

static GDALMajorObjectH GDALMajorObject::ToHandle | ( | GDALMajorObject * | poMajorObject | ) |
| inline static inherited

Convert a GDALMajorObject* to a GDALMajorObjectH.

Since
  GDAL 2.3

## Friends And Related Function Documentation

## ◆ GDALOpenEx

GDALDatasetH GDALOpenEx | ( | const char * | pszFilename,
|  | unsigned int | nOpenFlags,
|  | const char *const * | papszAllowedDrivers,
|  | const char *const * | papszOpenOptions,
|  | const char *const * | papszSiblingFiles
| ) |  |
| friend

Open a raster or vector file as a GDALDataset.

This function will try to open the passed file, or virtual dataset name by invoking the Open method of each registered GDALDriver in turn. The first successful open will result in a returned dataset. If all drivers fail then NULL is returned and an error is issued.

Several recommendations :

- If you open a dataset object with GDAL_OF_UPDATE access, it is not recommended to open a new dataset on the same underlying file.
- The returned dataset should only be accessed by one thread at a time. If you want to use it from different threads, you must add all necessary code (mutexes, etc.) to avoid concurrent use of the object. (Some drivers, such as GeoTIFF, maintain internal state variables that are updated each time a new block is read, thus preventing concurrent use.)

For drivers supporting the VSI virtual file API, it is possible to open a file in a .zip archive (see VSIInstallZipFileHandler()), in a .tar/.tar.gz/.tgz archive (see VSIInstallTarFileHandler()) or on a HTTP / FTP server (see VSIInstallCurlFileHandler())

In order to reduce the need for searches through the operating system file system machinery, it is possible to give an optional list of files with the papszSiblingFiles parameter. This is the list of all files at the same level in the file system as the target file, including the target file. The filenames must not include any path components, are essentially just the output of VSIReadDir() on the parent directory. If the target object does not have filesystem semantics then the file list should be NULL.

Parameters

  pszFilename | the name of the file to access. In the case of exotic drivers this may not refer to a physical file, but instead contain information for the driver on how to access a dataset. It should be in UTF-8 encoding.
  nOpenFlags | a combination of GDAL_OF_ flags that may be combined through logical or operator. Driver kind: GDAL_OF_RASTER for raster drivers, GDAL_OF_MULTIDIM_RASTER for multidimensional raster drivers, GDAL_OF_VECTOR for vector drivers, GDAL_OF_GNM for Geographic Network Model drivers. GDAL_OF_RASTER and GDAL_OF_MULTIDIM_RASTER are generally mutually exclusive. If none of the value is specified, GDAL_OF_RASTER | GDAL_OF_VECTOR | GDAL_OF_GNM is implied. Access mode: GDAL_OF_READONLY (exclusive)or GDAL_OF_UPDATE. Shared mode: GDAL_OF_SHARED. If set, it allows the sharing of GDALDataset handles for a dataset with other callers that have set GDAL_OF_SHARED. In particular, GDALOpenEx() will first consult its list of currently open and shared GDALDataset's, and if the GetDescription() name for one exactly matches the pszFilename passed to GDALOpenEx() it will be referenced and returned, if GDALOpenEx() is called from the same thread. Thread safe mode: GDAL_OF_THREAD_SAFE (added in 3.10). This must be use in combination with GDAL_OF_RASTER, and is mutually exclusive with GDAL_OF_UPDATE, GDAL_OF_VECTOR, GDAL_OF_MULTIDIM_RASTER or GDAL_OF_GNM. Verbose error: GDAL_OF_VERBOSE_ERROR. If set, a failed attempt to open the file will lead to an error message to be reported.
  papszAllowedDrivers | NULL to consider all candidate drivers, or a NULL terminated list of strings with the driver short names that must be considered.
  papszOpenOptions | NULL, or a NULL terminated list of strings with open options passed to candidate drivers. An option exists for all drivers, OVERVIEW_LEVEL=level, to select a particular overview level of a dataset. The level index starts at 0. The level number can be suffixed by "only" to specify that only this overview level must be visible, and not sub-levels. Open options are validated by default, and a warning is emitted in case the option is not recognized. In some scenarios, it might be not desirable (e.g. when not knowing which driver will open the file), so the special open option VALIDATE_OPEN_OPTIONS can be set to NO to avoid such warnings. Alternatively, since GDAL 2.1, an option name can be preceded by the @ character to indicate that it may not cause a warning if the driver doesn't declare this option. Starting with GDAL 3.3, OVERVIEW_LEVEL=NONE is supported to indicate that no overviews should be exposed.
  papszSiblingFiles | NULL, or a NULL terminated list of strings that are filenames that are auxiliary to the main filename. If NULL is passed, a probing of the file system will be done.

Returns
  A GDALDatasetH handle or NULL on failure. For C++ applications this handle can be cast to a GDALDataset *.

Since
  GDAL 2.0

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

- gdal_priv.h
- gdaldrivermanager.cpp
- gdalpythondriverloader.cpp