GDALDriver C++ API

Include file

gdal_priv.h

GDALDriver class

class GDALDriver : public GDALMajorObject

Format specific driver.

An instance of this class is created for each supported format, and manages information about the format.

This roughly corresponds to a file format, though some drivers may be gateways to many formats through a secondary multi-library.

Subclassed by GDALPluginDriverProxy, OGRSFDriver, PythonPluginDriver

Public Functions

virtual CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain = "") override

Set single metadata item.

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

パラメータ:

  • 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.

戻り値:

CE_None on success, or an error code on failure.

GDALDataset *Create(const char *pszName, int nXSize, int nYSize, int nBands, GDALDataType eType, CSLConstList papszOptions)

Create a new dataset with this driver.

What argument values are legal for particular drivers is driver specific, and there is no way to query in advance to establish legal values.

That function will try to validate the creation option list passed to the driver with the GDALValidateCreationOptions() method. This check can be disabled by defining the configuration option GDAL_VALIDATE_CREATION_OPTIONS=NO.

After you have finished working with the returned dataset, it is required to close it with GDALClose(). This does not only close the file handle, but also ensures that all the data and metadata has been written to the dataset (GDALFlushCache() is not sufficient for that purpose).

In GDAL 2, the arguments nXSize, nYSize and nBands can be passed to 0 when creating a vector-only dataset for a compatible driver.

Equivalent of the C function GDALCreate().

パラメータ:

  • pszFilename -- the name of the dataset to create. UTF-8 encoded.

  • nXSize -- width of created raster in pixels.

  • nYSize -- height of created raster in pixels.

  • nBands -- number of bands.

  • eType -- type of raster.

  • papszOptions -- list of driver specific control parameters. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset.

戻り値:

NULL on failure, or a new GDALDataset.

GDALDataset *CreateMultiDimensional(const char *pszName, CSLConstList papszRootGroupOptions, CSLConstList papszOptions)

Create a new multidimensional dataset with this driver.

Only drivers that advertise the GDAL_DCAP_MULTIDIM_RASTER capability and implement the pfnCreateMultiDimensional method might return a non nullptr GDALDataset.

This is the same as the C function GDALCreateMultiDimensional().

Since

GDAL 3.1

パラメータ:

  • pszFilename -- the name of the dataset to create. UTF-8 encoded.

  • papszRootGroupOptions -- driver specific options regarding the creation of the root group. Might be nullptr.

  • papszOptions -- driver specific options regarding the creation of the dataset. Might be nullptr.

戻り値:

a new dataset, or nullptr in case of failure.

CPLErr Delete(const char *pszName)

Delete named dataset.

The driver will attempt to delete the named dataset in a driver specific fashion. Full featured drivers will delete all associated files, database objects, or whatever is appropriate. The default behavior when no driver specific behavior is provided is to attempt to delete all the files that are returned by GDALGetFileList() on the dataset handle.

It is unwise to have open dataset handles on this dataset when it is deleted.

Equivalent of the C function GDALDeleteDataset().

パラメータ:

pszFilename -- name of dataset to delete.

戻り値:

CE_None on success, or CE_Failure if the operation fails.

CPLErr Rename(const char *pszNewName, const char *pszOldName)

Rename a dataset.

Rename a dataset. This may including moving the dataset to a new directory or even a new filesystem.

It is unwise to have open dataset handles on this dataset when it is being renamed.

Equivalent of the C function GDALRenameDataset().

パラメータ:

  • pszNewName -- new name for the dataset.

  • pszOldName -- old name for the dataset.

戻り値:

CE_None on success, or CE_Failure if the operation fails.

CPLErr CopyFiles(const char *pszNewName, const char *pszOldName)

Copy the files of a dataset.

Copy all the files associated with a dataset.

Equivalent of the C function GDALCopyDatasetFiles().

パラメータ:

  • pszNewName -- new name for the dataset.

  • pszOldName -- old name for the dataset.

戻り値:

CE_None on success, or CE_Failure if the operation fails.

GDALDataset *CreateCopy(const char*, GDALDataset*, int, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Create a copy of a dataset.

This method will attempt to create a copy of a raster dataset with the indicated filename, and in this drivers format. Band number, size, type, projection, geotransform and so forth are all to be copied from the provided template dataset.

Note that many sequential write once formats (such as JPEG and PNG) don't implement the Create() method but do implement this CreateCopy() method. If the driver doesn't implement CreateCopy(), but does implement Create() then the default CreateCopy() mechanism built on calling Create() will be used. So to test if CreateCopy() is available, you can test if GDAL_DCAP_CREATECOPY or GDAL_DCAP_CREATE is set in the GDAL metadata.

It is intended that CreateCopy() will often be used with a source dataset which is a virtual dataset allowing configuration of band types, and other information without actually duplicating raster data (see the VRT driver). This is what is done by the gdal_translate utility for example.

That function will try to validate the creation option list passed to the driver with the GDALValidateCreationOptions() method. This check can be disabled by defining the configuration option GDAL_VALIDATE_CREATION_OPTIONS=NO.

This function copy all metadata from the default domain ("")

Even is bStrict is TRUE, only the value of the data is equivalent, but the data layout (INTERLEAVE as PIXEL/LINE/BAND) of the dst dataset is controlled by the papszOptions creation options, and may differ from the poSrcDS src dataset. Starting from GDAL 3.5, if no INTERLEAVE and COMPRESS creation option has been specified in papszOptions, and if the driver supports equivalent interleaving as the src dataset, the CreateCopy() will internally add the proper creation option to get the same data interleaving.

After you have finished working with the returned dataset, it is required to close it with GDALClose(). This does not only close the file handle, but also ensures that all the data and metadata has been written to the dataset (GDALFlushCache() is not sufficient for that purpose).

For multidimensional datasets, papszOptions can contain array creation options, if they are prefixed with "ARRAY:".

参考

GDALGroup::CopyFrom() documentation for further details regarding such options.

パラメータ:

  • pszFilename -- the name for the new dataset. UTF-8 encoded.

  • poSrcDS -- the dataset being duplicated.

  • bStrict -- TRUE if the copy must be strictly equivalent, or more normally FALSE indicating that the copy may adapt as needed for the output format.

  • papszOptions -- additional format dependent options controlling creation of the output file. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset. Starting with GDAL 3.8.0, the following options are recognized by the GTiff, COG, VRT, PNG au JPEG drivers:

    • COPY_SRC_MDD=AUTO/YES/NO: whether metadata domains of the source dataset should be copied to the destination dataset. In the default AUTO mode, only "safe" domains will be copied, which include the default metadata domain (some drivers may include other domains such as IMD, RPC, GEOLOCATION). When setting YES, all domains will be copied (but a few reserved ones like IMAGE_STRUCTURE or DERIVED_SUBDATASETS). When setting NO, no source metadata will be copied.

    • SRC_MDD=domain_name: which source metadata domain should be copied. This option restricts the list of source metadata domains to be copied (it implies COPY_SRC_MDD=YES if it is not set). This option may be specified as many times as they are source domains. The default metadata domain is the empty string "" ("_DEFAULT_") may also be used when empty string is not practical)

  • pfnProgress -- a function to be used to report progress of the copy.

  • pProgressData -- application data passed into progress function.

戻り値:

a pointer to the newly created dataset (may be read-only access).

bool CanVectorTranslateFrom(const char *pszDestName, GDALDataset *poSourceDS, CSLConstList papszVectorTranslateArguments, char ***ppapszFailureReasons)

Returns whether the driver can translate from a vector dataset, using the arguments passed to GDALVectorTranslate() stored in papszVectorTranslateArguments.

This is used to determine if the driver supports the VectorTranslateFrom() operation.

Since

GDAL 3.8

パラメータ:

  • pszDestName -- Target dataset name

  • poSourceDS -- Source dataset

  • papszVectorTranslateArguments -- Non-positional arguments passed to GDALVectorTranslate() (may be nullptr)

  • ppapszFailureReasons -- [out] nullptr, or a pointer to an null-terminated array of strings to record the reason(s) for the impossibility.

戻り値:

true if VectorTranslateFrom() can be called with the same arguments.

GDALDataset *VectorTranslateFrom(const char *pszDestName, GDALDataset *poSourceDS, CSLConstList papszVectorTranslateArguments, GDALProgressFunc pfnProgress, void *pProgressData)

Create a copy of a vector dataset, using the arguments passed to GDALVectorTranslate() stored in papszVectorTranslateArguments.

This may be implemented by some drivers that can convert from an existing dataset in an optimized way.

This is for example used by the PMTiles to convert from MBTiles.

Since

GDAL 3.8

パラメータ:

  • pszDestName -- Target dataset name

  • poSourceDS -- Source dataset

  • papszVectorTranslateArguments -- Non-positional arguments passed to GDALVectorTranslate() (may be nullptr)

  • pfnProgress -- a function to be used to report progress of the copy.

  • pProgressData -- application data passed into progress function.

戻り値:

a new dataset in case of success, or nullptr in case of error.

Public Static Functions

static CPLErr QuietDelete(const char *pszName, CSLConstList papszAllowedDrivers = nullptr)

Delete dataset if found.

This is a helper method primarily used by Create() and CreateCopy() to predelete any dataset of the name soon to be created. It will attempt to delete the named dataset if one is found, otherwise it does nothing. An error is only returned if the dataset is found but the delete fails.

This is a static method and it doesn't matter what driver instance it is invoked on. It will attempt to discover the correct driver using Identify().

パラメータ:

  • pszName -- the dataset name to try and delete.

  • papszAllowedDrivers -- NULL to consider all candidate drivers, or a NULL terminated list of strings with the driver short names that must be considered. (Note: implemented only starting with GDAL 3.4.1)

戻り値:

CE_None if the dataset does not exist, or is deleted without issues.

static inline GDALDriverH ToHandle(GDALDriver *poDriver)

Convert a GDALDriver* to a GDALDriverH.

Since

GDAL 2.3

static inline GDALDriver *FromHandle(GDALDriverH hDriver)

Convert a GDALDriverH to a GDALDriver*.

Since

GDAL 2.3

GDALDriverManager class

class GDALDriverManager : public GDALMajorObject

Class for managing the registration of file format drivers.

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

Public Functions

int GetDriverCount(void) const

Fetch the number of registered drivers.

This C analog to this is GDALGetDriverCount().

戻り値:

the number of registered drivers.

GDALDriver *GetDriver(int)

Fetch driver by index.

This C analog to this is GDALGetDriver().

パラメータ:

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

戻り値:

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

GDALDriver *GetDriverByName(const char*)

Fetch a driver based on the short name.

The C analog is the GDALGetDriverByName() function.

パラメータ:

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

戻り値:

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

int RegisterDriver(GDALDriver*)

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.

パラメータ:

poDriver -- the driver to register.

戻り値:

the index of the new installed driver.

void DeregisterDriver(GDALDriver*)

Deregister the passed driver.

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

The C analog is GDALDeregisterDriver().

パラメータ:

poDriver -- the driver to deregister.

void 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.

void 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.

void 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.

void DeclareDeferredPluginDriver(GDALPluginDriverProxy *poProxyDriver)

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

Since

3.9

パラメータ:

poProxyDriver -- Plugin driver proxy

Public Static Functions

static CPLErr LoadPlugin(const char *name)

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().

参考

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

static void AutoLoadPythonDrivers()

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