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

Format specific driver. More...

#include <gdal_priv.h>

Inheritance diagram for GDALDriver:
GDALMajorObject OGRSFDriver

Public Member Functions

virtual CPLErr SetMetadataItem (const char *pszName, const char *pszValue, const char *pszDomain="") CPL_OVERRIDE
 Set single metadata item. More...
 
GDALDatasetCreate (const char *pszName, int nXSize, int nYSize, int nBands, GDALDataType eType, char **papszOptions) CPL_WARN_UNUSED_RESULT
 Create a new dataset with this driver. More...
 
CPLErr Delete (const char *pszName)
 Delete named dataset. More...
 
CPLErr Rename (const char *pszNewName, const char *pszOldName)
 Rename a dataset. More...
 
CPLErr CopyFiles (const char *pszNewName, const char *pszOldName)
 Copy the files of a dataset. More...
 
GDALDatasetCreateCopy (const char *, GDALDataset *, int, char **, GDALProgressFunc pfnProgress, void *pProgressData) CPL_WARN_UNUSED_RESULT
 Create a copy of a dataset. More...
 
- Public Member Functions inherited from GDALMajorObject
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...
 

Static Public Member Functions

static CPLErr QuietDelete (const char *pszName)
 Delete dataset if found. More...
 

Additional Inherited Members

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

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

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
pszNewNamenew name for the dataset.
pszOldNameold name for the dataset.
Returns
CE_None on success, or CE_Failure if the operation fails.
GDALDataset * GDALDriver::Create ( const char *  pszFilename,
int  nXSize,
int  nYSize,
int  nBands,
GDALDataType  eType,
char **  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 some situations, the new dataset can be created in another process through the GDAL API Proxy mechanism.

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

Parameters
pszFilenamethe name of the dataset to create. UTF-8 encoded.
nXSizewidth of created raster in pixels.
nYSizeheight of created raster in pixels.
nBandsnumber of bands.
eTypetype of raster.
papszOptionslist 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.
GDALDataset * GDALDriver::CreateCopy ( const char *  pszFilename,
GDALDataset poSrcDS,
int  bStrict,
char **  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.

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 some situations, the new dataset can be created in another process through the GDAL API Proxy mechanism.

Parameters
pszFilenamethe name for the new dataset. UTF-8 encoded.
poSrcDSthe dataset being duplicated.
bStrictTRUE if the copy must be strictly equivalent, or more normally FALSE indicating that the copy may adapt as needed for the output format.
papszOptionsadditional format dependent options controlling creation of the output file. The APPEND_SUBDATASET=YES option can be specified to avoid prior destruction of existing dataset.
pfnProgressa function to be used to report progress of the copy.
pProgressDataapplication data passed into progress function.
Returns
a pointer to the newly created dataset (may be read-only access).
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 behaviour when no driver specific behaviour is provided is to attempt to delete the passed name as a single file.

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

Equivalent of the C function GDALDeleteDataset().

Parameters
pszFilenamename of dataset to delete.
Returns
CE_None on success, or CE_Failure if the operation fails.
CPLErr GDALDriver::QuietDelete ( const char *  pszName)
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
pszNamethe dataset name to try and delete.
Returns
CE_None if the dataset does not exist, or is deleted without issues.
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
pszNewNamenew name for the dataset.
pszOldNameold name for the dataset.
Returns
CE_None on success, or CE_Failure if the operation fails.
CPLErr GDALDriver::SetMetadataItem ( const char *  pszName,
const char *  pszValue,
const char *  pszDomain = "" 
)
virtual

Set single metadata item.

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

Parameters
pszNamethe key for the metadata item to fetch.
pszValuethe value to assign to the key.
pszDomainthe domain to set within, use NULL for the default domain.
Returns
CE_None on success, or an error code on failure.

Reimplemented from GDALMajorObject.


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

Generated for GDAL by doxygen 1.8.8.