GDAL

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

Format specific driver. More...

`#include <gdal_driver.h>`

Inheritance diagram for GDALDriver:

## Public Member Functions
const char * | GetMetadataItem (const char *pszName, const char *pszDomain="") override
| Fetch single metadata item.
CPLErr | SetMetadataItem (const char *pszName, const char *pszValue, const char *pszDomain="") override
| Set single metadata item.
GDALDataset * | Create (const char *pszName, int nXSize, int nYSize, int nBands, GDALDataType eType, CSLConstList papszOptions)
| Create a new dataset with this driver.
GDALDataset * | CreateMultiDimensional (const char *pszName, CSLConstList papszRootGroupOptions, CSLConstList papszOptions)
| Create a new multidimensional dataset with this driver.
CPLErr | Delete (const char *pszName)
| Delete named dataset.
CPLErr | Delete (GDALDataset *poDS, CSLConstList papszFileList)
| Delete a currently opened dataset.
CPLErr | Rename (const char *pszNewName, const char *pszOldName)
| Rename a dataset.
CPLErr | CopyFiles (const char *pszNewName, const char *pszOldName)
| Copy the files of a dataset.
GDALDataset * | CreateCopy (const char *, GDALDataset *, int, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressData)
| Create a copy of a dataset.
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.
bool | HasOpenOption (const char *pszOpenOptionName) const
| Returns TRUE if the given open option is supported by the driver.
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.
int | GetMOFlags () const
| Returns the GMO_ flags.
void | SetMOFlags (int nFlagsIn)
| Assign GMO_flags.
virtual const char * | GetDescription () const
| Fetch object description.
virtual void | SetDescription (const char *)
| Set object description.
virtual char ** | GetMetadataDomainList ()
| Fetch list of metadata domains.
virtual char ** | GetMetadata (const char *pszDomain="")
| Fetch metadata.
virtual CPLErr | SetMetadata (char **papszMetadata, const char *pszDomain="")
| Set metadata.

## Static Public Member Functions
static CPLErr | QuietDelete (const char *pszName, CSLConstList papszAllowedDrivers=nullptr)
| Delete dataset if found.
static GDALDriverH | ToHandle (GDALDriver *poDriver)
| Convert a GDALDriver* to a GDALDriverH.
static GDALDriver * | FromHandle (GDALDriverH hDriver)
| Convert a GDALDriverH to a GDALDriver*.
static GDALMajorObjectH | ToHandle (GDALMajorObject *poMajorObject)
| Convert a GDALMajorObject* to a GDALMajorObjectH.

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

## Detailed Description

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.

## Member Function Documentation

## ◆ 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()

## ◆ CanVectorTranslateFrom()

bool GDALDriver::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.

Parameters

  | pszDestName | Target dataset name
  | poSourceDS | Source dataset
  | papszVectorTranslateArguments | Non-positional arguments passed to GDALVectorTranslate() (may be nullptr)
  [out] | ppapszFailureReasons | nullptr, or a pointer to an null-terminated array of strings to record the reason(s) for the impossibility.

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

Since
  GDAL 3.8

## ◆ CopyFiles()

CPLErr GDALDriver::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().

Parameters

  pszNewName | new name for the dataset.
  pszOldName | old name for the dataset.

Returns
  CE_None on success, or CE_Failure if the operation fails.

## ◆ Create()

GDALDataset * GDALDriver::Create | ( | const char * | pszFilename,
|  | 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).

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

Parameters

  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.

Returns
  NULL on failure, or a new GDALDataset.

## ◆ CreateCopy()

GDALDataset * GDALDriver::CreateCopy | ( | const char * | pszFilename,
|  | GDALDataset * | poSrcDS,
|  | int | bStrict,
|  | 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:".

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

Parameters

  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.

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

## ◆ CreateMultiDimensional()

GDALDataset * GDALDriver::CreateMultiDimensional | ( | const char * | pszFilename,
|  | 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().

Parameters

  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.

Returns
  a new dataset, or nullptr in case of failure.

Since
  GDAL 3.1

## ◆ Delete() [1/2]

CPLErr GDALDriver::Delete | ( | const char * | pszFilename | ) |

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

Parameters

  pszFilename | name of dataset to delete.

Returns
  CE_None on success, or CE_Failure if the operation fails.

## ◆ Delete() [2/2]

CPLErr GDALDriver::Delete | ( | GDALDataset * | poDS,
|  | CSLConstList | papszFileList
| ) |  |

Delete a currently opened dataset.

The driver will attempt to delete the passed 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.

Note that this will generally not work on Windows systems that don't accept deleting opened files.

At least one of poDS or papszFileList must not be NULL

Parameters

  poDS | dataset to delete, or NULL
  papszFileList | File list to delete, typically obtained with poDS->GetFileList(), or NULL

Returns
  CE_None on success, or CE_Failure if the operation fails.

Since
  3.12

## ◆ 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.

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

## ◆ 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()

Reimplemented in GDALDataset.

## ◆ GetMetadataItem()

const char * GDALDriver::GetMetadataItem | ( | const char * | pszName,
|  | const char * | pszDomain = `""`
| ) |  |
| override virtual

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 from GDALMajorObject.

Reimplemented in GDALPluginDriverProxy.

## ◆ GetMOFlags()

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

Returns the GMO_ flags.

Returns
  flags

## ◆ HasOpenOption()

bool GDALDriver::HasOpenOption | ( | const char * | pszOpenOptionName | ) | const

Returns TRUE if the given open option is supported by the driver.

Parameters

  pszOpenOptionName | name of the open option to be checked

Returns
  TRUE if the driver supports the open option

Since
  GDAL 3.11

## ◆ QuietDelete()

CPLErr GDALDriver::QuietDelete | ( | const char * | pszName,
|  | CSLConstList | papszAllowedDrivers = `nullptr`
| ) |  |
| static

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

Parameters

  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)

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

## ◆ Rename()

CPLErr GDALDriver::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().

Parameters

  pszNewName | new name for the dataset.
  pszOldName | old name for the dataset.

Returns
  CE_None on success, or CE_Failure if the operation fails.

## ◆ 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 GDALDriver::SetMetadataItem | ( | const char * | pszName,
|  | const char * | pszValue,
|  | const char * | pszDomain = `""`
| ) |  |
| override virtual

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 from GDALMajorObject.

Reimplemented in GDALPluginDriverProxy.

## ◆ SetMOFlags()

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

Assign GMO_flags.

Parameters

  nNewFlags | new flags.

## ◆ VectorTranslateFrom()

GDALDataset * GDALDriver::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.

Parameters

  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.

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

Since
  GDAL 3.8

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

- gdal_driver.h
- gdaldriver.cpp