GDALDriver Class Reference

Format specific driver. More...

#include <gdal_priv.h>

Inheritance diagram for GDALDriver:

List of all members.

Public Member Functions

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

Create a new dataset with this driver.

CPLErr Delete (const char *pszName)

Delete named 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, char **, GDALProgressFunc pfnProgress, void *pProgressData)

Create a copy of a dataset.

GDALDataset * DefaultCreateCopy (const char *, GDALDataset *, int, char **, GDALProgressFunc pfnProgress, void *pProgressData)

Static Public Member Functions

static CPLErr DefaultCopyMasks (GDALDataset *poSrcDS, GDALDataset *poDstDS, int bStrict)

static CPLErr QuietDelete (const char *pszName)

Delete dataset if found.

Public Attributes

GDALDataset *(* pfnOpen )(GDALOpenInfo *)

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

CPLErr(* pfnDelete )(const char *pszName)

GDALDataset *(* pfnCreateCopy )(const char *, GDALDataset *, int, char **, GDALProgressFunc pfnProgress, void *pProgressData)

void * pDriverData

void(* pfnUnloadDriver )(GDALDriver *)

int(* pfnIdentify )(GDALOpenInfo *)

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

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

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.

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

References CPLCorrespondingPaths(), GA_ReadOnly, GDALClose(), GDALGetFileList(), GDALOpen(), and VSIUnlink().

GDALDataset * GDALDriver::Create	(	const char *	pszFilename,
		int	nXSize,
		int	nYSize,
		int	nBands,
		GDALDataType	eType,
		char **	papszParmList
	)

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

Equivelent of the C function GDALCreate().

Parameters:

	pszFilename	the name of the dataset to create.
	nXSize	width of created raster in pixels.
	nYSize	height of created raster in pixels.
	nBands	number of bands.
	eType	type of raster.
	papszParmList	list of driver specific control parameters.

Returns:: NULL on failure, or a new GDALDataset.

References GDALGetDataTypeName(), GDALValidateCreationOptions(), GDALMajorObject::GetDescription(), GDALDataset::poDriver, QuietDelete(), and GDALMajorObject::SetDescription().

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.

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

Parameters:

	pszFilename	the name for the new dataset.
	poSrcDS	the dataset being duplicated.
	bStrict	TRUE if the copy must be strictly equivelent, 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.
	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).

References GDALDummyProgress(), GDALValidateCreationOptions(), GDALMajorObject::GetDescription(), GDALDataset::poDriver, QuietDelete(), and GDALMajorObject::SetDescription().

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.

Equivelent of the C function GDALDeleteDataset().

Parameters:

pszFilename

name of dataset to delete.

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

References GA_ReadOnly, GDALClose(), GDALGetFileList(), GDALOpen(), and VSIUnlink().

Referenced by QuietDelete().

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:

pszName

the dataset name to try and delete.

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

References Delete(), and GDALIdentifyDriver().

Referenced by Create(), and CreateCopy().

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.

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

References CPLCorrespondingPaths(), GA_ReadOnly, GDALClose(), GDALGetFileList(), and GDALOpen().

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

gdal_priv.h
gdaldriver.cpp


Public Member Functions
GDALDataset *	Create (const char pszName, int nXSize, int nYSize, int nBands, GDALDataType eType, char *papszOptions)
	Create a new dataset with this driver.
CPLErr	Delete (const char *pszName)
	Delete named 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, char *, GDALProgressFunc pfnProgress, void pProgressData)
	Create a copy of a dataset.
GDALDataset *	DefaultCreateCopy (const char , GDALDataset , int, char *, GDALProgressFunc pfnProgress, void pProgressData)
Static Public Member Functions
static CPLErr	DefaultCopyMasks (GDALDataset poSrcDS, GDALDataset poDstDS, int bStrict)
static CPLErr	QuietDelete (const char *pszName)
	Delete dataset if found.
Public Attributes
GDALDataset (	pfnOpen )(GDALOpenInfo *)
GDALDataset (	pfnCreate )(const char pszName, int nXSize, int nYSize, int nBands, GDALDataType eType, char *papszOptions)
CPLErr(*	pfnDelete )(const char *pszName)
GDALDataset (	pfnCreateCopy )(const char , GDALDataset , int, char *, GDALProgressFunc pfnProgress, void pProgressData)
void *	pDriverData
void(*	pfnUnloadDriver )(GDALDriver *)
int(*	pfnIdentify )(GDALOpenInfo *)
CPLErr(*	pfnRename )(const char pszNewName, const char pszOldName)
CPLErr(*	pfnCopyFiles )(const char pszNewName, const char pszOldName)