OGRDataSource Class Reference

#include <ogrsf_frmts.h>

List of all members.

Public Member Functions

virtual const char * GetName ()=0

Returns the name of the data source.

virtual int GetLayerCount ()=0

Get the number of layers in this data source.

virtual OGRLayer * GetLayer (int)=0

Fetch a layer by index.

virtual OGRLayer * GetLayerByName (const char *)

Fetch a layer by name.

virtual OGRErr DeleteLayer (int)

Delete the indicated layer from the datasource.

virtual int TestCapability (const char *)=0

Test if capability is available.

virtual OGRLayer * CreateLayer (const char *pszName, OGRSpatialReference *poSpatialRef=NULL, OGRwkbGeometryType eGType=wkbUnknown, char **papszOptions=NULL)

This method attempts to create a new layer on the data source with the indicated name, coordinate system, geometry type.

virtual OGRLayer * CopyLayer (OGRLayer *poSrcLayer, const char *pszNewName, char **papszOptions=NULL)

Duplicate an existing layer.

OGRStyleTable * GetStyleTable ()

Returns data source style table.

void SetStyleTableDirectly (OGRStyleTable *poStyleTable)

Set data source style table.

void SetStyleTable (OGRStyleTable *poStyleTable)

Set data source style table.

virtual OGRLayer * ExecuteSQL (const char *pszStatement, OGRGeometry *poSpatialFilter, const char *pszDialect)

Execute an SQL statement against the data store.

virtual void ReleaseResultSet (OGRLayer *poResultsSet)

Release results of ExecuteSQL().

virtual OGRErr SyncToDisk ()

Flush pending changes to disk.

int Reference ()

Increment datasource reference count.

int Dereference ()

Decrement datasource reference count.

int GetRefCount () const

Fetch reference count.

int GetSummaryRefCount () const

Fetch reference count of datasource and all owned layers.

OGRErr Release ()

Drop a reference to this datasource, and if the reference count drops to zero close (destroy) the datasource.

OGRSFDriver * GetDriver () const

Returns the driver that the dataset was opened with.

void SetDriver (OGRSFDriver *poDriver)

Sets the driver that the dataset was created or opened with.

Static Public Member Functions

static void DestroyDataSource (OGRDataSource *)

Closes opened datasource and releases allocated resources.

Friends

class OGRSFDriverRegistrar

Detailed Description

This class represents a data source. A data source potentially consists of many layers (OGRLayer). A data source normally consists of one, or a related set of files, though the name doesn't have to be a real item in the file system.

When an OGRDataSource is destroyed, all it's associated OGRLayers objects are also destroyed.

Member Function Documentation

OGRLayer * OGRDataSource::CopyLayer	(	OGRLayer *	poSrcLayer,
		const char *	pszNewName,
		char **	papszOptions = `NULL`
	)			`[virtual]`

Duplicate an existing layer.

This method creates a new layer, duplicate the field definitions of the source layer and then duplicate each features of the source layer. The papszOptions argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation. The source layer may come from another dataset.

This method is the same as the C function OGR_DS_CopyLayer().

Parameters:

	poSrcLayer	source layer.
	pszNewName	the name of the layer to create.
	papszOptions	a StringList of name=value options. Options are driver specific.

Returns:: an handle to the layer, or NULL if an error occurs.

References OGRLayer::CreateFeature(), OGRFeature::CreateFeature(), OGRLayer::CreateField(), CreateLayer(), OGRFeature::DestroyFeature(), OGRFeature::GetFID(), OGRFeatureDefn::GetFieldCount(), OGRFeatureDefn::GetFieldDefn(), OGRFeatureDefn::GetGeomType(), OGRLayer::GetLayerDefn(), OGRFeatureDefn::GetName(), OGRLayer::GetNextFeature(), OGRLayer::GetSpatialRef(), OGRLayer::ResetReading(), OGRFeature::SetFID(), OGRFeature::SetFrom(), and TestCapability().

Referenced by OGRSFDriver::CopyDataSource().

OGRLayer * OGRDataSource::CreateLayer	(	const char *	pszName,
		OGRSpatialReference *	poSpatialRef = `NULL`,
		OGRwkbGeometryType	eGType = `wkbUnknown`,
		char **	papszOptions = `NULL`
	)			`[virtual]`

This method attempts to create a new layer on the data source with the indicated name, coordinate system, geometry type.

The papszOptions argument can be used to control driver specific creation options. These options are normally documented in the format specific documentation.

Parameters:

	pszName	the name for the new layer. This should ideally not match any existing layer on the datasource.
	poSpatialRef	the coordinate system to use for the new layer, or NULL if no coordinate system is available.
	eGType	the geometry type for the layer. Use wkbUnknown if there are no constraints on the types geometry to be written.
	papszOptions	a StringList of name=value options. Options are driver specific.

Returns:: NULL is returned on failure, or a new OGRLayer handle on success.

Example:

#include "ogrsf_frmts.h" 
#include "cpl_string.h"

...

        OGRLayer *poLayer;
        char     *papszOptions;

        if( !poDS->TestCapability( ODsCCreateLayer ) )
        {
            ...
        }

        papszOptions = CSLSetNameValue( papszOptions, "DIM", "2" );
        poLayer = poDS->CreateLayer( "NewLayer", NULL, wkbUnknown,
                                     papszOptions );
        CSLDestroy( papszOptions );

        if( poLayer == NULL )
        {
            ...
        }

Referenced by CopyLayer().

OGRErr OGRDataSource::DeleteLayer ( int iLayer ) [virtual]

Delete the indicated layer from the datasource.

If this method is supported the ODsCDeleteLayer capability will test TRUE on the OGRDataSource.

This method is the same as the C function OGR_DS_DeleteLayer().

Parameters:

iLayer

the index of the layer to delete.

Returns:: OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting layers is not supported for this datasource.

int OGRDataSource::Dereference ( )

Decrement datasource reference count.

This method is the same as the C function OGR_DS_Dereference().

Returns:: the reference count after decrementing.

Referenced by ExecuteSQL().

void OGRDataSource::DestroyDataSource ( OGRDataSource * poDS ) [static]

Closes opened datasource and releases allocated resources.

This static method will close and destroy a datasource. It is equivelent to calling delete on the object, but it ensures that the deallocation is properly executed within the GDAL libraries heap on platforms where this can matter (win32).

This method is the same as the C function OGR_DS_Destroy().

Parameters:

poDS

pointer to allocated datasource object.

OGRLayer * OGRDataSource::ExecuteSQL	(	const char *	pszStatement,
		OGRGeometry *	poSpatialFilter,
		const char *	pszDialect
	)			`[virtual]`

Execute an SQL statement against the data store.

The result of an SQL query is either NULL for statements that are in error, or that have no results set, or an OGRLayer pointer representing a results set from the query. Note that this OGRLayer is in addition to the layers in the data store and must be destroyed with OGRDataSource::ReleaseResultsSet() before the data source is closed (destroyed).

This method is the same as the C function OGR_DS_ExecuteSQL().

For more information on the SQL dialect supported internally by OGR review the OGR SQL document. Some drivers (ie. Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.

Parameters:

	pszStatement	the SQL statement to execute.
	poSpatialFilter	geometry which represents a spatial filter.
	pszDialect	allows control of the statement dialect. By default it is assumed to be "generic" SQL, whatever that is.

Returns:: an OGRLayer containing the results of the query. Deallocate with ReleaseResultsSet().

References Dereference(), OGRFeatureDefn::GetFieldCount(), OGRFeatureDefn::GetFieldDefn(), GetLayerByName(), OGRLayer::GetLayerDefn(), OGRFieldDefn::GetNameRef(), OGRSFDriverRegistrar::GetRegistrar(), OGRFieldDefn::GetType(), OFTInteger, OFTReal, OFTString, and OGRSFDriverRegistrar::ReleaseDataSource().

OGRSFDriver * OGRDataSource::GetDriver ( ) const

Returns the driver that the dataset was opened with.

This method is the same as the C function OGR_DS_GetDriver().

Returns:: NULL if driver info is not available, or pointer to a driver owned by the OGRSFDriverManager.

Referenced by OGR_Dr_CreateDataSource(), OGR_Dr_Open(), and OGRSFDriverRegistrar::Open().

OGRLayer * OGRDataSource::GetLayer ( int iLayer ) [pure virtual]

Fetch a layer by index.

The returned layer remains owned by the OGRDataSource and should not be deleted by the application.

This method is the same as the C function OGR_DS_GetLayer().

Parameters:

iLayer

a layer number between 0 and GetLayerCount()-1.

Returns:: the layer, or NULL if iLayer is out of range or an error occurs.

Referenced by OGRSFDriver::CopyDataSource(), GetLayerByName(), GetSummaryRefCount(), and SyncToDisk().

OGRLayer * OGRDataSource::GetLayerByName ( const char * pszLayerName ) [virtual]

Fetch a layer by name.

The returned layer remains owned by the OGRDataSource and should not be deleted by the application.

This method is the same as the C function OGR_DS_GetLayerByName().

Parameters:

pszLayerName

the layer name of the layer to fetch.

Returns:: the layer, or NULL if Layer is not found or an error occurs.

References GetLayer(), GetLayerCount(), OGRLayer::GetLayerDefn(), and OGRFeatureDefn::GetName().

Referenced by ExecuteSQL().

int OGRDataSource::GetLayerCount ( ) [pure virtual]

Get the number of layers in this data source.

This method is the same as the C function OGR_DS_GetLayerCount().

Returns:: layer count.

Referenced by OGRSFDriver::CopyDataSource(), GetLayerByName(), GetSummaryRefCount(), and SyncToDisk().

const char * OGRDataSource::GetName ( ) [pure virtual]

Returns the name of the data source.

This string should be sufficient to open the data source if passed to the same OGRSFDriver that this data source was opened with, but it need not be exactly the same string that was used to open the data source. Normally this is a filename.

This method is the same as the C function OGR_DS_GetName().

Returns:: pointer to an internal name string which should not be modified or freed by the caller.

int OGRDataSource::GetRefCount ( ) const

Fetch reference count.

This method is the same as the C function OGR_DS_GetRefCount().

Returns:: the current reference count for the datasource object itself.

void OGRDataSource::GetStyleTable ( ) [inline]

Returns data source style table.

This method is the same as the C function OGR_DS_GetStyleTable().

Returns:: pointer to a style table which should not be modified or freed by the caller.

int OGRDataSource::GetSummaryRefCount ( ) const

Fetch reference count of datasource and all owned layers.

This method is the same as the C function OGR_DS_GetSummaryRefCount().

Returns:: the current summary reference count for the datasource and its layers.

References GetLayer(), GetLayerCount(), and OGRLayer::GetRefCount().

int OGRDataSource::Reference ( )

Increment datasource reference count.

This method is the same as the C function OGR_DS_Reference().

Returns:: the reference count after incrementing.

Referenced by OGRSFDriverRegistrar::Open().

OGRErr OGRDataSource::Release ( )

Drop a reference to this datasource, and if the reference count drops to zero close (destroy) the datasource.

Internally this actually calls the OGRSFDriverRegistrar::ReleaseDataSource() method. This method is essentially a convenient alias.

This method is the same as the C function OGRReleaseDataSource().

Returns:: OGRERR_NONE on success or an error code.

References OGRSFDriverRegistrar::GetRegistrar(), and OGRSFDriverRegistrar::ReleaseDataSource().

void OGRDataSource::ReleaseResultSet ( OGRLayer * poResultsSet ) [virtual]

Release results of ExecuteSQL().

This method should only be used to deallocate OGRLayers resulting from an ExecuteSQL() call on the same OGRDataSource. Failure to deallocate a results set before destroying the OGRDataSource may cause errors.

This method is the same as the C function OGR_L_ReleaseResultsSet().

Parameters:

poResultsSet

the result of a previous ExecuteSQL() call.

void OGRDataSource::SetDriver ( OGRSFDriver * poDriver )

Sets the driver that the dataset was created or opened with.

Note:: This method is not exposed as the OGR C API function.

Parameters:

poDriver

pointer to driver instance associated with the data source.

Referenced by OGR_Dr_CreateDataSource(), and OGR_Dr_Open().

void OGRDataSource::SetStyleTable ( OGRStyleTable * poStyleTable ) [inline]

Set data source style table.

This method operate exactly as OGRDataSource::SetStyleTableDirectly() except that it does not assume ownership of the passed table.

This method is the same as the C function OGR_DS_SetStyleTable().

Parameters:

poStyleTable

pointer to style table to set

References OGRStyleTable::Clone().

void OGRDataSource::SetStyleTableDirectly ( OGRStyleTable * poStyleTable ) [inline]

Set data source style table.

This method operate exactly as OGRDataSource::SetStyleTable() except that it assumes ownership of the passed table.

This method is the same as the C function OGR_DS_SetStyleTableDirectly().

Parameters:

poStyleTable

pointer to style table to set

OGRErr OGRDataSource::SyncToDisk ( ) [virtual]

Flush pending changes to disk.

This call is intended to force the datasource to flush any pending writes to disk, and leave the disk file in a consistent state. It would not normally have any effect on read-only datasources.

Some data sources do not implement this method, and will still return OGRERR_NONE. An error is only returned if an error occurs while attempting to flush to disk.

The default implementation of this method just calls the SyncToDisk() method on each of the layers. Conceptionally, calling SyncToDisk() on a datasource should include any work that might be accomplished by calling SyncToDisk() on layers in that data source.

In any event, you should always close any opened datasource with OGRDataSource::DestroyDataSource() that will ensure all data is correctly flushed.

This method is the same as the C function OGR_DS_SyncToDisk().

Returns:: OGRERR_NONE if no error occurs (even if nothing is done) or an error code.

References GetLayer(), GetLayerCount(), and OGRLayer::SyncToDisk().

int OGRDataSource::TestCapability ( const char * pszCapability ) [pure virtual]

Test if capability is available.

One of the following data source capability names can be passed into this method, and a TRUE or FALSE value will be returned indicating whether or not the capability is available for this object.

ODsCCreateLayer: True if this datasource can create new layers.

The #define macro forms of the capability names should be used in preference to the strings themselves to avoid mispelling.

This method is the same as the C function OGR_DS_TestCapability().

Parameters:

pszCapability

the capability to test.

Returns:: TRUE if capability available otherwise FALSE.

Referenced by CopyLayer().

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

ogrsf_frmts.h
ogrsf_frmts.dox
ogrdatasource.cpp


Public Member Functions
virtual const char *	GetName ()=0
	Returns the name of the data source.
virtual int	GetLayerCount ()=0
	Get the number of layers in this data source.
virtual OGRLayer *	GetLayer (int)=0
	Fetch a layer by index.
virtual OGRLayer *	GetLayerByName (const char *)
	Fetch a layer by name.
virtual OGRErr	DeleteLayer (int)
	Delete the indicated layer from the datasource.
virtual int	TestCapability (const char *)=0
	Test if capability is available.
virtual OGRLayer *	CreateLayer (const char pszName, OGRSpatialReference poSpatialRef=NULL, OGRwkbGeometryType eGType=wkbUnknown, char **papszOptions=NULL)
	This method attempts to create a new layer on the data source with the indicated name, coordinate system, geometry type.
virtual OGRLayer *	CopyLayer (OGRLayer poSrcLayer, const char pszNewName, char **papszOptions=NULL)
	Duplicate an existing layer.
OGRStyleTable *	GetStyleTable ()
	Returns data source style table.
void	SetStyleTableDirectly (OGRStyleTable *poStyleTable)
	Set data source style table.
void	SetStyleTable (OGRStyleTable *poStyleTable)
	Set data source style table.
virtual OGRLayer *	ExecuteSQL (const char pszStatement, OGRGeometry poSpatialFilter, const char *pszDialect)
	Execute an SQL statement against the data store.
virtual void	ReleaseResultSet (OGRLayer *poResultsSet)
	Release results of ExecuteSQL().
virtual OGRErr	SyncToDisk ()
	Flush pending changes to disk.
int	Reference ()
	Increment datasource reference count.
int	Dereference ()
	Decrement datasource reference count.
int	GetRefCount () const
	Fetch reference count.
int	GetSummaryRefCount () const
	Fetch reference count of datasource and all owned layers.
OGRErr	Release ()
	Drop a reference to this datasource, and if the reference count drops to zero close (destroy) the datasource.
OGRSFDriver *	GetDriver () const
	Returns the driver that the dataset was opened with.
void	SetDriver (OGRSFDriver *poDriver)
	Sets the driver that the dataset was created or opened with.
Static Public Member Functions
static void	DestroyDataSource (OGRDataSource *)
	Closes opened datasource and releases allocated resources.
Friends
class	OGRSFDriverRegistrar