/******************************************************************************
* $Id$
*
* Project: OpenGIS Simple Features Reference Implementation
* Purpose: Documentation for ogrsf_frmts.h classes.
* Author: Frank Warmerdam, warmerda@home.com
*
******************************************************************************
* Copyright (c) 1999, Les Technologies SoftMap Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
******************************************************************************/
/************************************************************************/
/* OGRSFDriverRegistrar */
/************************************************************************/
/**
\fn OGRDataSourceH OGROpen( const char *pszName, int bUpdate,
OGRSFDriverH *pahDriverList );
\brief Open a file / data source with one of the registered drivers.
This function loops through all the drivers registered with the driver
manager trying each until one succeeds with the given data source.
If this function fails, CPLGetLastErrorMsg() can be used to check if there
is an error message explaining why.
For drivers supporting the VSI virtual file API, it is possible to open
a file in a .zip archive (see VSIInstallZipFileHandler()), in a .tar/.tar.gz/.tgz archive
(see VSIInstallTarFileHandler()) or on a HTTP / FTP server (see VSIInstallCurlFileHandler())
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*.
Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and
*NOT* OGRSFDriver*.
@deprecated Use GDALOpenEx() in GDAL 2.0
@param pszName the name of the file, or data source to open.
@param bUpdate FALSE for read-only access (the default) or TRUE for
read-write access.
@param pahDriverList if non-NULL, this argument will be updated with a
pointer to the driver which was used to open the data source.
@return NULL on error or if the pass name is not supported by this driver,
otherwise an handle to a GDALDataset. This GDALDataset should be
closed by deleting the object when it is no longer needed.
Example:
OGRDataSourceH hDS;
OGRSFDriverH *pahDriver;
hDS = OGROpen( "polygon.shp", 0, pahDriver );
if( hDS == NULL )
{
return;
}
... use the data source ...
OGRReleaseDataSource( hDS );
*/
/**
\fn OGRDataSourceH OGROpenShared( const char *pszName, int bUpdate,
OGRSFDriverH *pahDriverList );
\brief Open a file / data source with one of the registered drivers if not
already opened, or increment reference count of already opened data source
previously opened with OGROpenShared()
This function loops through all the drivers registered with the driver
manager trying each until one succeeds with the given data source.
If this function fails, CPLGetLastErrorMsg() can be used to check if there
is an error message explaining why.
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*.
Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and
*NOT* OGRSFDriver*.
@deprecated Use GDALOpenEx() in GDAL 2.0
@param pszName the name of the file, or data source to open.
@param bUpdate FALSE for read-only access (the default) or TRUE for
read-write access.
@param pahDriverList if non-NULL, this argument will be updated with a
pointer to the driver which was used to open the data source.
@return NULL on error or if the pass name is not supported by this driver,
otherwise an handle to a GDALDataset. This GDALDataset should be
closed by deleting the object when it is no longer needed.
Example:
OGRDataSourceH hDS;
OGRSFDriverH *pahDriver;
hDS = OGROpenShared( "polygon.shp", 0, pahDriver );
if( hDS == NULL )
{
return;
}
... use the data source ...
OGRReleaseDataSource( hDS );
*/
/**
\fn int OGRGetDriverCount();
\brief Fetch the number of registered drivers.
@deprecated Use GDALGetDriverCount() in GDAL 2.0
@return the drivers count.
*/
/**
\fn OGRSFDriverH OGRGetDriver( int iDriver );
\brief Fetch the indicated driver.
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*.
@deprecated Use GDALGetDriver() in GDAL 2.0
@param iDriver the driver index, from 0 to GetDriverCount()-1.
@return handle to the driver, or NULL if iDriver is out of range.
*/
/**
\fn OGRSFDriverH OGRGetDriverByName( const char *pszName );
\brief Fetch the indicated driver.
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*.
@deprecated Use GDALGetDriverByName() in GDAL 2.0
@param pszName the driver name
@return the driver, or NULL if no driver with that name is found
*/
/**
\fn int OGRRegisterAll();
\brief Register all drivers.
@deprecated Use GDALAllRegister() in GDAL 2.0
*/
/************************************************************************/
/* OGRSFDriver */
/************************************************************************/
/**
\fn const char *OGR_Dr_GetName( OGRSFDriverH hDriver );
\brief Fetch name of driver (file format).
This name should be relatively short
(10-40 characters), and should reflect the underlying file format. For
instance "ESRI Shapefile".
This function is the same as the C++ method OGRSFDriver::GetName().
@param hDriver handle to the driver to get the name from.
@return driver name. This is an internal string and should not be modified
or freed.
*/
/**
\fn OGRDataSourceH OGR_Dr_Open( OGRSFDriverH hDriver, const char *pszName,
int bUpdate );
\brief Attempt to open file with this driver.
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*.
Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and
*NOT* OGRSFDriver*.
@deprecated Use GDALOpenEx() in GDAL 2.0
@param hDriver handle to the driver that is used to open file.
@param pszName the name of the file, or data source to try and open.
@param bUpdate TRUE if update access is required, otherwise FALSE (the
default).
@return NULL on error or if the pass name is not supported by this driver,
otherwise an handle to a GDALDataset. This GDALDataset should be
closed by deleting the object when it is no longer needed.
*/
/**
\fn int OGR_Dr_TestCapability( OGRSFDriverH hDriver, const char *pszCap );
\brief Test if capability is available.
One of the following data source capability names can be passed into this
function, and a TRUE or FALSE value will be returned indicating whether
or not the capability is available for this object.
- ODrCCreateDataSource: True if this driver can support creating data sources.
- ODrCDeleteDataSource: True if this driver supports deleting data sources.
The \#define macro forms of the capability names should be used in preference
to the strings themselves to avoid misspelling.
@deprecated Use GDALGetMetadataItem(hDriver, GDAL_DCAP_CREATE) in GDAL 2.0
@param hDriver handle to the driver to test the capability against.
@param pszCap the capability to test.
@return TRUE if capability available otherwise FALSE.
*/
/**
\fn OGRErr OGR_Dr_DeleteDataSource( OGRSFDriverH hDriver,
const char *pszDataSource )
\brief Delete a datasource.
Delete (from the disk, in the database, ...) the named datasource.
Normally it would be safest if the datasource was not open at the time.
Whether this is a supported operation on this driver case be tested
using TestCapability() on ODrCDeleteDataSource.
@deprecated Use GDALDeleteDataset() in GDAL 2
@param hDriver handle to the driver on which data source deletion is
based.
@param pszDataSource the name of the datasource to delete.
@return OGRERR_NONE on success, and OGRERR_UNSUPPORTED_OPERATION if this
is not supported by this driver.
*/
/**
\fn OGRDataSourceH OGR_Dr_CreateDataSource( OGRSFDriverH hDriver,
const char *pszName,
char ** papszOptions )
\brief This function attempts to create a new data source based on the passed driver.
The papszOptions argument can be used to control driver specific
creation options. These options are normally documented in the format
specific documentation.
It is important to call OGR_DS_Destroy() when the datasource is no longer
used to ensure that all data has been properly flushed to disk.
@deprecated Use GDALCreate() in GDAL 2.0
@param hDriver handle to the driver on which data source creation is
based.
@param pszName the name for the new data source. UTF-8 encoded.
@param papszOptions a StringList of name=value options. Options are driver
specific, and driver information can be found at the following url:
http://www.gdal.org/ogr_formats.html
@return NULL is returned on failure, or a new OGRDataSource handle on
success.
*/
/**
\fn OGRDataSourceH OGR_Dr_CopyDataSource( OGRSFDriverH hDriver,
OGRDataSourceH hSrcDS,
const char *pszNewName,
char **papszOptions )
\brief This function creates a new datasource by copying all the layers from the source datasource.
It is important to call OGR_DS_Destroy() when the datasource is no longer
used to ensure that all data has been properly flushed to disk.
@deprecated Use GDALCreateCopy() in GDAL 2.0
@param hDriver handle to the driver on which data source creation is
based.
@param hSrcDS source datasource
@param pszNewName the name for the new data source.
@param papszOptions a StringList of name=value options. Options are driver
specific, and driver information can be found at the following url:
http://www.gdal.org/ogr_formats.html
@return NULL is returned on failure, or a new OGRDataSource handle on
success.
*/
/************************************************************************/
/* OGRDataSource */
/************************************************************************/
/**
\fn void OGR_DS_Destroy( OGRDataSourceH hDataSource )
\brief Closes opened datasource and releases allocated resources.
This method is the same as the C++ method OGRDataSource::DestroyDataSource().
@deprecated Use GDALClose() in GDAL 2.0
@param hDataSource handle to allocated datasource object.
*/
/**
\fn const char *OGR_DS_GetName( OGRDataSourceH hDS );
\brief 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.
@deprecated Use GDALGetDescription() in GDAL 2.0
@param hDS handle to the data source to get the name from.
@return pointer to an internal name string which should not be modified
or freed by the caller.
*/
/**
\fn int OGR_DS_GetLayerCount( OGRDataSourceH hDS );
\brief Get the number of layers in this data source.
@deprecated Use GDALDatasetGetLayerCount() in GDAL 2.0
@param hDS handle to the data source from which to get the number of layers.
@return layer count.
*/
/**
\fn OGRLayerH OGR_DS_GetLayer( OGRDataSourceH hDS, int iLayer );
\brief Fetch a layer by index.
The returned layer remains owned by the
OGRDataSource and should not be deleted by the application.
@deprecated Use GDALDatasetGetLayer() in GDAL 2.0
@param hDS handle to the data source from which to get the layer.
@param iLayer a layer number between 0 and OGR_DS_GetLayerCount()-1.
@return an handle to the layer, or NULL if iLayer is out of range
or an error occurs.
*/
/**
\fn OGRLayerH OGR_DS_GetLayerByName(OGRDataSourceH hDS,
const char *pszLayerName );
\brief Fetch a layer by name.
The returned layer remains owned by the
OGRDataSource and should not be deleted by the application.
@deprecated Use GDALDatasetGetLayerByName() in GDAL 2.0
@param hDS handle to the data source from which to get the layer.
@param pszLayerName Layer the layer name of the layer to fetch.
@return an handle to the layer, or NULL if the layer is not found
or an error occurs.
*/
/**
\fn OGRLayerH OGR_DS_CopyLayer( OGRDataSourceH hDS,
OGRLayerH hSrcLayer, const char *pszNewName,
char **papszOptions )
\brief Duplicate an existing layer.
This function 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.
@deprecated Use GDALDatasetCopyLayer() in GDAL 2.0
@param hDS handle to the data source where to create the new layer
@param hSrcLayer handle to the source layer.
@param pszNewName the name of the layer to create.
@param papszOptions a StringList of name=value options. Options are driver
specific.
@return an handle to the layer, or NULL if an error occurs.
*/
/**
\fn OGRErr OGR_DS_DeleteLayer(OGRDataSourceH hDS, int iLayer);
\brief Delete the indicated layer from the datasource.
If this method is supported
the ODsCDeleteLayer capability will test TRUE on the OGRDataSource.
@deprecated Use GDALDatasetDeleteLayer() in GDAL 2.0
@param hDS handle to the datasource
@param iLayer the index of the layer to delete.
@return OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting
layers is not supported for this datasource.
*/
/**
\fn OGRLayerH OGR_DS_ExecuteSQL( OGRDataSourceH hDS,
const char *pszSQLCommand,
OGRGeometryH hSpatialFilter,
const char *pszDialect );
\brief 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 handle 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
OGR_DS_ReleaseResultSet() before the data source is closed
(destroyed).
For more information on the SQL dialect supported internally by OGR
review the OGR SQL document. Some drivers (i.e.
Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.
Starting with OGR 1.10, the SQLITE dialect
can also be used.
@deprecated Use GDALDatasetExecuteSQL() in GDAL 2.0
@param hDS handle to the data source on which the SQL query is executed.
@param pszSQLCommand the SQL statement to execute.
@param hSpatialFilter handle to a geometry which represents a spatial filter. Can be NULL.
@param pszDialect allows control of the statement dialect. If set to NULL, the
OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine,
unless OGRSQL is explicitly passed as the dialect. Starting with OGR 1.10, the SQLITE dialect
can also be used.
@return an handle to a OGRLayer containing the results of the query.
Deallocate with OGR_DS_ReleaseResultSet().
*/
/**
\fn void OGR_DS_ReleaseResultSet( OGRDataSourceH hDS, OGRLayerH hLayer );
\brief Release results of OGR_DS_ExecuteSQL().
This function should only be used to deallocate OGRLayers resulting from
an OGR_DS_ExecuteSQL() call on the same OGRDataSource.
Failure to deallocate a results set before destroying the OGRDataSource
may cause errors.
@deprecated Use GDALDatasetReleaseResultSet() in GDAL 2.0
@param hDS an handle to the data source on which was executed an
SQL query.
@param hLayer handle to the result of a previous OGR_DS_ExecuteSQL() call.
*/
/**
\fn int OGR_DS_TestCapability( OGRDataSourceH hDS, const char *pszCapability );
\brief Test if capability is available.
One of the following data source capability names can be passed into this
function, 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.
- ODsCDeleteLayer: True if this datasource can delete existing layers.
- ODsCCreateGeomFieldAfterCreateLayer: True if the layers of this
datasource support CreateGeomField() just after layer creation.
- ODsCCurveGeometries: True if this datasource supports writing curve geometries. (GDAL 2.0).
In that case, OLCCurveGeometries must also be declared in layers of that dataset.
The \#define macro forms of the capability names should be used in preference
to the strings themselves to avoid misspelling.
@deprecated Use GDALDatasetTestCapability() in GDAL 2.0
@param hDS handle to the data source against which to test the capability.
@param pszCapability the capability to test.
@return TRUE if capability available otherwise FALSE.
*/
/**
\fn OGRLayerH OGR_DS_CreateLayer( OGRDataSourceH hDS,
const char * pszName,
OGRSpatialReferenceH hSpatialRef,
OGRwkbGeometryType eType,
char ** papszOptions );
\brief This function 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.
@deprecated Use GDALDatasetCreateLayer() in GDAL 2.0
@param hDS The dataset handle.
@param pszName the name for the new layer. This should ideally not
match any existing layer on the datasource.
@param hSpatialRef handle to the coordinate system to use for the new layer,
or NULL if no coordinate system is available. The driver might only increase
the reference counter of the object to take ownership, and not make a full copy,
so do not use OSRDestroySpatialReference(), but OSRRelease() instead when you
are done with the object.
@param eType the geometry type for the layer. Use wkbUnknown if there
are no constraints on the types geometry to be written.
@param papszOptions a StringList of name=value options. Options are driver
specific, and driver information can be found at the following url:
http://www.gdal.org/ogr_formats.html
@return NULL is returned on failure, or a new OGRLayer handle on success.
Example:
\code
#include "ogrsf_frmts.h"
#include "cpl_string.h"
...
OGRLayerH *hLayer;
char **papszOptions;
if( OGR_DS_TestCapability( hDS, ODsCCreateLayer ) )
{
...
}
papszOptions = CSLSetNameValue( papszOptions, "DIM", "2" );
hLayer = OGR_DS_CreateLayer( hDS, "NewLayer", NULL, wkbUnknown,
papszOptions );
CSLDestroy( papszOptions );
if( hLayer == NULL )
{
...
}
\endcode
*/
/**
\fn OGRErr OGRReleaseDataSource( OGRDataSourceH hDS )
\brief 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.
@deprecated Use GDALClose() in GDAL 2.0
@param hDS handle to the data source to release
@return OGRERR_NONE on success or an error code.
*/
/**
\fn OGRSFDriverH OGR_DS_GetDriver( OGRDataSourceH hDS );
\brief Returns the driver that the dataset was opened with.
NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to
OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*.
@deprecated Use GDALGetDatasetDriver() in GDAL 2.0
@param hDS handle to the datasource
@return NULL if driver info is not available, or pointer to a driver owned
by the OGRSFDriverManager.
*/
/************************************************************************/
/* OGRLayer */
/************************************************************************/
/**
\fn const char* OGRLayer::GetName();
\brief Return the layer name.
This returns the same content as GetLayerDefn()->OGRFeatureDefn::GetName(), but for a
few drivers, calling GetName() directly can avoid lengthy layer
definition initialization.
This method is the same as the C function OGR_L_GetName().
If this method is derived in a driver, it must be done such that it
returns the same content as GetLayerDefn()->OGRFeatureDefn::GetName().
@return the layer name (must not been freed)
@since OGR 1.8.0
*/
/**
\fn const char* OGR_L_GetName( OGRLayerH hLayer );
\brief Return the layer name.
This returns the same content as OGR_FD_GetName(OGR_L_GetLayerDefn(hLayer)),
but for a few drivers, calling OGR_L_GetName() directly can avoid lengthy
layer definition initialization.
This function is the same as the C++ method OGRLayer::GetName().
@param hLayer handle to the layer.
@return the layer name (must not been freed)
@since OGR 1.8.0
*/
/**
\fn OGRwkbGeometryType OGRLayer::GetGeomType();
\brief Return the layer geometry type.
This returns the same result as GetLayerDefn()->OGRFeatureDefn::GetGeomType(), but for a
few drivers, calling GetGeomType() directly can avoid lengthy layer
definition initialization.
For layers with multiple geometry fields, this method only returns the geometry
type of the first geometry column. For other columns, use
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(i)->GetType().
For layers without any geometry field, this method returns wkbNone.
This method is the same as the C function OGR_L_GetGeomType().
If this method is derived in a driver, it must be done such that it
returns the same content as GetLayerDefn()->OGRFeatureDefn::GetGeomType().
@return the geometry type
@since OGR 1.8.0
*/
/**
\fn OGRwkbGeometryType OGR_L_GetGeomType( OGRLayerH hLayer );
\brief Return the layer geometry type.
This returns the same result as OGR_FD_GetGeomType(OGR_L_GetLayerDefn(hLayer)),
but for a few drivers, calling OGR_L_GetGeomType() directly can avoid lengthy
layer definition initialization.
For layers with multiple geometry fields, this method only returns the geometry
type of the first geometry column. For other columns, use
OGR_GFld_GetType(OGR_FD_GetGeomFieldDefn(OGR_L_GetLayerDefn(hLayer), i)).
For layers without any geometry field, this method returns wkbNone.
This function is the same as the C++ method OGRLayer::GetGeomType().
@param hLayer handle to the layer.
@return the geometry type
@since OGR 1.8.0
*/
/**
\fn void OGRLayer::ResetReading();
\brief Reset feature reading to start on the first feature.
This affects GetNextFeature().
This method is the same as the C function OGR_L_ResetReading().
*/
/**
\fn void OGR_L_ResetReading( OGRLayerH hLayer );
\brief Reset feature reading to start on the first feature.
This affects GetNextFeature().
This function is the same as the C++ method OGRLayer::ResetReading().
@param hLayer handle to the layer on which features are read.
*/
/**
\fn OGRFeature *OGRLayer::GetNextFeature();
\brief Fetch the next available feature from this layer.
The returned feature becomes the responsibility of the caller to
delete with OGRFeature::DestroyFeature(). It is critical that all
features associated with an OGRLayer (more specifically an
OGRFeatureDefn) be deleted before that layer/datasource is deleted.
Only features matching the current spatial filter (set with
SetSpatialFilter()) will be returned.
This method implements sequential access to the features of a layer. The
ResetReading() method can be used to start at the beginning again.
Features returned by GetNextFeature() may or may not be affected by
concurrent modifications depending on drivers. A guaranteed way of seeing
modifications in effect is to call ResetReading() on layers where
GetNextFeature() has been called, before reading again. Structural changes
in layers (field addition, deletion, ...) when a read is in progress may or
may not be possible depending on drivers. If a transaction is
committed/aborted, the current sequential reading may or may not be valid
after that operation and a call to ResetReading() might be needed.
This method is the same as the C function OGR_L_GetNextFeature().
@return a feature, or NULL if no more features are available.
*/
/**
\fn OGRFeatureH OGR_L_GetNextFeature( OGRLayerH hLayer );
\brief Fetch the next available feature from this layer.
The returned feature becomes the responsibility of the caller to
delete with OGR_F_Destroy(). It is critical that all features
associated with an OGRLayer (more specifically an OGRFeatureDefn) be
deleted before that layer/datasource is deleted.
Only features matching the current spatial filter (set with
SetSpatialFilter()) will be returned.
This function implements sequential access to the features of a layer.
The OGR_L_ResetReading() function can be used to start at the beginning
again.
Features returned by OGR_GetNextFeature() may or may not be affected by
concurrent modifications depending on drivers. A guaranteed way of seeing
modifications in effect is to call OGR_L_ResetReading() on layers where
OGR_GetNextFeature() has been called, before reading again. Structural
changes in layers (field addition, deletion, ...) when a read is in progress
may or may not be possible depending on drivers. If a transaction is
committed/aborted, the current sequential reading may or may not be valid
after that operation and a call to OGR_L_ResetReading() might be needed.
This function is the same as the C++ method OGRLayer::GetNextFeature().
@param hLayer handle to the layer from which feature are read.
@return an handle to a feature, or NULL if no more features are available.
*/
/**
\fn GIntBig OGRLayer::GetFeatureCount( int bForce = TRUE );
\brief Fetch the feature count in this layer.
Returns the number of features in the layer. For dynamic databases the
count may not be exact. If bForce is FALSE, and it would be expensive
to establish the feature count a value of -1 may be returned indicating
that the count isn't know. If bForce is TRUE some implementations will
actually scan the entire layer once to count objects.
The returned count takes the spatial filter into account.
Note that some implementations of this method may alter the read cursor
of the layer.
This method is the same as the C function OGR_L_GetFeatureCount().
Note: since GDAL 2.0, this method returns a GIntBig (previously a int)
@param bForce Flag indicating whether the count should be computed even
if it is expensive.
@return feature count, -1 if count not known.
*/
/**
\fn GIntBig OGR_L_GetFeatureCount( OGRLayerH hLayer, int bForce );
\brief Fetch the feature count in this layer.
Returns the number of features in the layer. For dynamic databases the
count may not be exact. If bForce is FALSE, and it would be expensive
to establish the feature count a value of -1 may be returned indicating
that the count isn't know. If bForce is TRUE some implementations will
actually scan the entire layer once to count objects.
The returned count takes the spatial filter into account.
Note that some implementations of this method may alter the read cursor
of the layer.
This function is the same as the CPP OGRLayer::GetFeatureCount().
Note: since GDAL 2.0, this method returns a GIntBig (previously a int)
@param hLayer handle to the layer that owned the features.
@param bForce Flag indicating whether the count should be computed even
if it is expensive.
@return feature count, -1 if count not known.
*/
/**
\fn OGRErr OGRLayer::GetExtent( OGREnvelope *psExtent, int bForce = TRUE );
\brief Fetch the extent of this layer.
Returns the extent (MBR) of the data in the layer. If bForce is FALSE,
and it would be expensive to establish the extent then OGRERR_FAILURE
will be returned indicating that the extent isn't know. If bForce is
TRUE then some implementations will actually scan the entire layer once
to compute the MBR of all the features in the layer.
Depending on the drivers, the returned extent may or may not take the
spatial filter into account. So it is safer to call GetExtent() without
setting a spatial filter.
Layers without any geometry may return OGRERR_FAILURE just indicating that
no meaningful extents could be collected.
Note that some implementations of this method may alter the read cursor
of the layer.
This method is the same as the C function OGR_L_GetExtent().
@param psExtent the structure in which the extent value will be returned.
@param bForce Flag indicating whether the extent should be computed even
if it is expensive.
@return OGRERR_NONE on success, OGRERR_FAILURE if extent not known.
*/
/**
\fn OGRErr OGR_L_GetExtent( OGRLayerH hLayer, OGREnvelope *psExtent, int bForce);
\brief Fetch the extent of this layer.
Returns the extent (MBR) of the data in the layer. If bForce is FALSE,
and it would be expensive to establish the extent then OGRERR_FAILURE
will be returned indicating that the extent isn't know. If bForce is
TRUE then some implementations will actually scan the entire layer once
to compute the MBR of all the features in the layer.
Depending on the drivers, the returned extent may or may not take the
spatial filter into account. So it is safer to call OGR_L_GetExtent() without
setting a spatial filter.
Layers without any geometry may return OGRERR_FAILURE just indicating that
no meaningful extents could be collected.
Note that some implementations of this method may alter the read cursor
of the layer.
This function is the same as the C++ method OGRLayer::GetExtent().
@param hLayer handle to the layer from which to get extent.
@param psExtent the structure in which the extent value will be returned.
@param bForce Flag indicating whether the extent should be computed even
if it is expensive.
@return OGRERR_NONE on success, OGRERR_FAILURE if extent not known.
*/
/**
\fn OGRErr OGRLayer::GetExtent( int iGeomField,OGREnvelope *psExtent, int bForce = TRUE );
\brief Fetch the extent of this layer, on the specified geometry field.
Returns the extent (MBR) of the data in the layer. If bForce is FALSE,
and it would be expensive to establish the extent then OGRERR_FAILURE
will be returned indicating that the extent isn't know. If bForce is
TRUE then some implementations will actually scan the entire layer once
to compute the MBR of all the features in the layer.
Depending on the drivers, the returned extent may or may not take the
spatial filter into account. So it is safer to call GetExtent() without
setting a spatial filter.
Layers without any geometry may return OGRERR_FAILURE just indicating that
no meaningful extents could be collected.
Note that some implementations of this method may alter the read cursor
of the layer.
Note to driver implementer: if you implement GetExtent(int,OGREnvelope*,int),
you must also implement GetExtent(OGREnvelope*, int) to make it call
GetExtent(0,OGREnvelope*,int).
This method is the same as the C function OGR_L_GetExtentEx().
@param iGeomField the index of the geometry field on which to compute the extent.
@param psExtent the structure in which the extent value will be returned.
@param bForce Flag indicating whether the extent should be computed even
if it is expensive.
@return OGRERR_NONE on success, OGRERR_FAILURE if extent not known.
*/
/**
\fn OGRErr OGR_L_GetExtentEx( OGRLayerH hLayer, int iGeomField, OGREnvelope *psExtent, int bForce);
\brief Fetch the extent of this layer, on the specified geometry field.
Returns the extent (MBR) of the data in the layer. If bForce is FALSE,
and it would be expensive to establish the extent then OGRERR_FAILURE
will be returned indicating that the extent isn't know. If bForce is
TRUE then some implementations will actually scan the entire layer once
to compute the MBR of all the features in the layer.
Depending on the drivers, the returned extent may or may not take the
spatial filter into account. So it is safer to call OGR_L_GetExtent() without
setting a spatial filter.
Layers without any geometry may return OGRERR_FAILURE just indicating that
no meaningful extents could be collected.
Note that some implementations of this method may alter the read cursor
of the layer.
This function is the same as the C++ method OGRLayer::GetExtent().
@param hLayer handle to the layer from which to get extent.
@param iGeomField the index of the geometry field on which to compute the extent.
@param psExtent the structure in which the extent value will be returned.
@param bForce Flag indicating whether the extent should be computed even
if it is expensive.
@return OGRERR_NONE on success, OGRERR_FAILURE if extent not known.
*/
/**
\fn void OGRLayer::SetSpatialFilter( OGRGeometry * poFilter );
\brief Set a new spatial filter.
This method set the geometry to be used as a spatial filter when
fetching features via the GetNextFeature() method. Only features that
geometrically intersect the filter geometry will be returned.
Currently this test is may be inaccurately implemented, but it is
guaranteed that all features whose envelope (as returned by
OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter
will be returned. This can result in more shapes being returned that
should strictly be the case.
Starting with GDAL 2.3, features with null or empty geometries will never
be considered as matching a spatial filter.
This method makes an internal copy of the passed geometry. The
passed geometry remains the responsibility of the caller, and may
be safely destroyed.
For the time being the passed filter geometry should be in the same
SRS as the layer (as returned by OGRLayer::GetSpatialRef()). In the
future this may be generalized.
This method is the same as the C function OGR_L_SetSpatialFilter().
@param poFilter the geometry to use as a filtering region. NULL may
be passed indicating that the current spatial filter should be cleared,
but no new one instituted.
*/
/**
\fn void OGR_L_SetSpatialFilter( OGRLayerH hLayer, OGRGeometryH hGeom );
\brief Set a new spatial filter.
This function set the geometry to be used as a spatial filter when
fetching features via the OGR_L_GetNextFeature() function. Only
features that geometrically intersect the filter geometry will be
returned.
Currently this test is may be inaccurately implemented, but it is
guaranteed that all features whose envelope (as returned by
OGR_G_GetEnvelope()) overlaps the envelope of the spatial filter
will be returned. This can result in more shapes being returned that
should strictly be the case.
Starting with GDAL 2.3, features with null or empty geometries will never
be considered as matching a spatial filter.
This function makes an internal copy of the passed geometry. The
passed geometry remains the responsibility of the caller, and may
be safely destroyed.
For the time being the passed filter geometry should be in the same
SRS as the layer (as returned by OGR_L_GetSpatialRef()). In the
future this may be generalized.
This function is the same as the C++ method OGRLayer::SetSpatialFilter.
@param hLayer handle to the layer on which to set the spatial filter.
@param hGeom handle to the geometry to use as a filtering region. NULL may
be passed indicating that the current spatial filter should be cleared,
but no new one instituted.
*/
/**
\fn void OGRLayer::SetSpatialFilterRect( double dfMinX, double dfMinY,
double dfMaxX, double dfMaxY );
\brief Set a new rectangular spatial filter.
This method set rectangle to be used as a spatial filter when
fetching features via the GetNextFeature() method. Only features that
geometrically intersect the given rectangle will be returned.
The x/y values should be in the same coordinate system as the layer as
a whole (as returned by OGRLayer::GetSpatialRef()). Internally this
method is normally implemented as creating a 5 vertex closed rectangular
polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as
a convenience.
The only way to clear a spatial filter set with this method is to
call OGRLayer::SetSpatialFilter(NULL).
This method is the same as the C function OGR_L_SetSpatialFilterRect().
@param dfMinX the minimum X coordinate for the rectangular region.
@param dfMinY the minimum Y coordinate for the rectangular region.
@param dfMaxX the maximum X coordinate for the rectangular region.
@param dfMaxY the maximum Y coordinate for the rectangular region.
*/
/**
\fn void OGR_L_SetSpatialFilterRect( OGRLayerH hLayer,
double dfMinX, double dfMinY,
double dfMaxX, double dfMaxY );
\brief Set a new rectangular spatial filter.
This method set rectangle to be used as a spatial filter when
fetching features via the OGR_L_GetNextFeature() method. Only features that
geometrically intersect the given rectangle will be returned.
The x/y values should be in the same coordinate system as the layer as
a whole (as returned by OGRLayer::GetSpatialRef()). Internally this
method is normally implemented as creating a 5 vertex closed rectangular
polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as
a convenience.
The only way to clear a spatial filter set with this method is to
call OGRLayer::SetSpatialFilter(NULL).
This method is the same as the C++ method OGRLayer::SetSpatialFilterRect().
@param hLayer handle to the layer on which to set the spatial filter.
@param dfMinX the minimum X coordinate for the rectangular region.
@param dfMinY the minimum Y coordinate for the rectangular region.
@param dfMaxX the maximum X coordinate for the rectangular region.
@param dfMaxY the maximum Y coordinate for the rectangular region.
*/
/**
\fn void OGRLayer::SetSpatialFilter( int iGeomField, OGRGeometry * poFilter );
\brief Set a new spatial filter.
This method set the geometry to be used as a spatial filter when
fetching features via the GetNextFeature() method. Only features that
geometrically intersect the filter geometry will be returned.
Currently this test is may be inaccurately implemented, but it is
guaranteed that all features who's envelope (as returned by
OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter
will be returned. This can result in more shapes being returned that
should strictly be the case.
This method makes an internal copy of the passed geometry. The
passed geometry remains the responsibility of the caller, and may
be safely destroyed.
For the time being the passed filter geometry should be in the same
SRS as the geometry field definition it corresponds to (as returned by
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). In the
future this may be generalized.
Note that only the last spatial filter set is applied, even if several
successive calls are done with different iGeomField values.
Note to driver implementer: if you implement SetSpatialFilter(int,OGRGeometry*),
you must also implement SetSpatialFilter(OGRGeometry*) to make it call
SetSpatialFilter(0,OGRGeometry*).
This method is the same as the C function OGR_L_SetSpatialFilterEx().
@param iGeomField index of the geometry field on which the spatial filter
operates.
@param poFilter the geometry to use as a filtering region. NULL may
be passed indicating that the current spatial filter should be cleared,
but no new one instituted.
@since GDAL 1.11
*/
/**
\fn void OGR_L_SetSpatialFilterEx( OGRLayerH hLayer, int iGeomField, OGRGeometryH hGeom );
\brief Set a new spatial filter.
This function set the geometry to be used as a spatial filter when
fetching features via the OGR_L_GetNextFeature() function. Only
features that geometrically intersect the filter geometry will be
returned.
Currently this test is may be inaccurately implemented, but it is
guaranteed that all features who's envelope (as returned by
OGR_G_GetEnvelope()) overlaps the envelope of the spatial filter
will be returned. This can result in more shapes being returned that
should strictly be the case.
This function makes an internal copy of the passed geometry. The
passed geometry remains the responsibility of the caller, and may
be safely destroyed.
For the time being the passed filter geometry should be in the same
SRS as the geometry field definition it corresponds to (as returned by
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). In the
future this may be generalized.
Note that only the last spatial filter set is applied, even if several
successive calls are done with different iGeomField values.
This function is the same as the C++ method OGRLayer::SetSpatialFilter.
@param hLayer handle to the layer on which to set the spatial filter.
@param iGeomField index of the geometry field on which the spatial filter
operates.
@param hGeom handle to the geometry to use as a filtering region. NULL may
be passed indicating that the current spatial filter should be cleared,
but no new one instituted.
@since GDAL 1.11
*/
/**
\fn void OGRLayer::SetSpatialFilterRect( int iGeomField,
double dfMinX, double dfMinY,
double dfMaxX, double dfMaxY );
\brief Set a new rectangular spatial filter.
This method set rectangle to be used as a spatial filter when
fetching features via the GetNextFeature() method. Only features that
geometrically intersect the given rectangle will be returned.
The x/y values should be in the same coordinate system as as the geometry
field definition it corresponds to (as returned by
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). Internally this
method is normally implemented as creating a 5 vertex closed rectangular
polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as
a convenience.
The only way to clear a spatial filter set with this method is to
call OGRLayer::SetSpatialFilter(NULL).
This method is the same as the C function OGR_L_SetSpatialFilterRectEx().
@param iGeomField index of the geometry field on which the spatial filter
operates.
@param dfMinX the minimum X coordinate for the rectangular region.
@param dfMinY the minimum Y coordinate for the rectangular region.
@param dfMaxX the maximum X coordinate for the rectangular region.
@param dfMaxY the maximum Y coordinate for the rectangular region.
@since GDAL 1.11
*/
/**
\fn void OGR_L_SetSpatialFilterRectEx( OGRLayerH hLayer,
int iGeomField,
double dfMinX, double dfMinY,
double dfMaxX, double dfMaxY );
\brief Set a new rectangular spatial filter.
This method set rectangle to be used as a spatial filter when
fetching features via the OGR_L_GetNextFeature() method. Only features that
geometrically intersect the given rectangle will be returned.
The x/y values should be in the same coordinate system as as the geometry
field definition it corresponds to (as returned by
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). Internally this
method is normally implemented as creating a 5 vertex closed rectangular
polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as
a convenience.
The only way to clear a spatial filter set with this method is to
call OGRLayer::SetSpatialFilter(NULL).
This method is the same as the C++ method OGRLayer::SetSpatialFilterRect().
@param hLayer handle to the layer on which to set the spatial filter.
@param iGeomField index of the geometry field on which the spatial filter
operates.
@param dfMinX the minimum X coordinate for the rectangular region.
@param dfMinY the minimum Y coordinate for the rectangular region.
@param dfMaxX the maximum X coordinate for the rectangular region.
@param dfMaxY the maximum Y coordinate for the rectangular region.
@since GDAL 1.11
*/
/**
\fn OGRGeometry *OGRLayer::GetSpatialFilter();
\brief This method returns the current spatial filter for this layer.
The returned pointer is to an internally owned object, and should not
be altered or deleted by the caller.
This method is the same as the C function OGR_L_GetSpatialFilter().
@return spatial filter geometry.
*/
/**
\fn OGRGeometryH OGR_L_GetSpatialFilter( OGRLayerH hLayer );
\brief This function returns the current spatial filter for this layer.
The returned pointer is to an internally owned object, and should not
be altered or deleted by the caller.
This function is the same as the C++ method OGRLayer::GetSpatialFilter().
@param hLayer handle to the layer to get the spatial filter from.
@return an handle to the spatial filter geometry.
*/
/**
\fn void OGRLayer::SetAttributeFilter( const char *pszQuery );
\brief Set a new attribute query.
This method sets the attribute query string to be used when
fetching features via the GetNextFeature() method. Only features for which
the query evaluates as true will be returned.
The query string should be in the format of an SQL WHERE clause. For
instance "population > 1000000 and population < 5000000" where population
is an attribute in the layer. The query format is normally a restricted
form of SQL WHERE clause as described in the "WHERE" section of the
OGR SQL tutorial. In some cases (RDBMS
backed drivers) the native capabilities of the database may be used to
interpret the WHERE clause in which case the capabilities will be broader
than those of OGR SQL.
Note that installing a query string will generally result in resetting
the current reading position (ala ResetReading()).
This method is the same as the C function OGR_L_SetAttributeFilter().
@param pszQuery query in restricted SQL WHERE format, or NULL to clear the
current query.
@return OGRERR_NONE if successfully installed, or an error code if the
query expression is in error, or some other failure occurs.
*/
/**
\fn OGRErr OGR_L_SetAttributeFilter(OGRLayerH hLayer, const char *pszQuery);
\brief Set a new attribute query.
This function sets the attribute query string to be used when
fetching features via the OGR_L_GetNextFeature() function.
Only features for which the query evaluates as true will be returned.
The query string should be in the format of an SQL WHERE clause. For
instance "population > 1000000 and population < 5000000" where population
is an attribute in the layer. The query format is a restricted form of SQL
WHERE clause as defined "eq_format=restricted_where" about half way through
this document:
http://ogdi.sourceforge.net/prop/6.2.CapabilitiesMetadata.html
Note that installing a query string will generally result in resetting
the current reading position (ala OGR_L_ResetReading()).
This function is the same as the C++ method OGRLayer::SetAttributeFilter().
@param hLayer handle to the layer on which attribute query will be executed.
@param pszQuery query in restricted SQL WHERE format, or NULL to clear the
current query.
@return OGRERR_NONE if successfully installed, or an error code if the
query expression is in error, or some other failure occurs.
*/
/**
\fn OGRFeatureDefn *OGRLayer::GetLayerDefn();
\brief Fetch the schema information for this layer.
The returned OGRFeatureDefn is owned by the OGRLayer, and should not be
modified or freed by the application. It encapsulates the attribute schema
of the features of the layer.
This method is the same as the C function OGR_L_GetLayerDefn().
@return feature definition.
*/
/**
\fn OGRFeatureDefnH OGR_L_GetLayerDefn( OGRLayerH hLayer );
\brief Fetch the schema information for this layer.
The returned handle to the OGRFeatureDefn is owned by the OGRLayer,
and should not be modified or freed by the application. It encapsulates
the attribute schema of the features of the layer.
This function is the same as the C++ method OGRLayer::GetLayerDefn().
@param hLayer handle to the layer to get the schema information.
@return an handle to the feature definition.
*/
/**
\fn int OGR_L_FindFieldIndex( OGRLayerH hLayer, const char *, int bExactMatch );
\brief Find the index of field in a layer.
The returned number is the index of the field in the layers, or -1 if the
field doesn't exist.
If bExactMatch is set to FALSE and the field doesn't exists in the given form
the driver might apply some changes to make it match, like those it might do
if the layer was created (eg. like LAUNDER in the OCI driver).
This method is the same as the C++ method OGRLayer::FindFieldIndex().
@return field index, or -1 if the field doesn't exist
*/
/**
\fn int OGRLayer::FindFieldIndex( const char *, int bExactMatch );
\brief Find the index of field in the layer.
The returned number is the index of the field in the layers, or -1 if the
field doesn't exist.
If bExactMatch is set to FALSE and the field doesn't exists in the given form
the driver might apply some changes to make it match, like those it might do
if the layer was created (eg. like LAUNDER in the OCI driver).
This method is the same as the C function OGR_L_FindFieldIndex().
@return field index, or -1 if the field doesn't exist
*/
/**
\fn OGRSpatialReference *OGRLayer::GetSpatialRef();
\brief Fetch the spatial reference system for this layer.
The returned object is owned by the OGRLayer and should not be modified
or freed by the application.
Starting with OGR 1.11, several geometry fields can be associated to a
feature definition. Each geometry field can have its own spatial reference
system, which is returned by OGRGeomFieldDefn::GetSpatialRef().
OGRLayer::GetSpatialRef() is equivalent to
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(0)->GetSpatialRef()
This method is the same as the C function OGR_L_GetSpatialRef().
@return spatial reference, or NULL if there isn't one.
*/
/**
\fn OGRSpatialReferenceH OGR_L_GetSpatialRef( OGRLayerH hLayer );
\brief Fetch the spatial reference system for this layer.
The returned object is owned by the OGRLayer and should not be modified
or freed by the application.
This function is the same as the C++ method OGRLayer::GetSpatialRef().
@param hLayer handle to the layer to get the spatial reference from.
@return spatial reference, or NULL if there isn't one.
*/
/**
\fn OGRFeature *OGRLayer::GetFeature( GIntBig nFID );
\brief Fetch a feature by its identifier.
This function will attempt to read the identified feature. The nFID
value cannot be OGRNullFID. Success or failure of this operation is
unaffected by the spatial or attribute filters (and specialized implementations
in drivers should make sure that they do not take into account spatial or
attribute filters).
If this method returns a non-NULL feature, it is guaranteed that its
feature id (OGRFeature::GetFID()) will be the same as nFID.
Use OGRLayer::TestCapability(OLCRandomRead) to establish if this layer
supports efficient random access reading via GetFeature(); however, the
call should always work if the feature exists as a fallback implementation
just scans all the features in the layer looking for the desired feature.
Sequential reads (with GetNextFeature()) are generally considered interrupted
by a GetFeature() call.
The returned feature should be free with OGRFeature::DestroyFeature().
This method is the same as the C function OGR_L_GetFeature().
@param nFID the feature id of the feature to read.
@return a feature now owned by the caller, or NULL on failure.
*/
/**
\fn OGRFeatureH OGR_L_GetFeature( OGRLayerH hLayer, GIntBig nFeatureId );
\brief Fetch a feature by its identifier.
This function will attempt to read the identified feature. The nFID
value cannot be OGRNullFID. Success or failure of this operation is
unaffected by the spatial or attribute filters (and specialized implementations
in drivers should make sure that they do not take into account spatial or
attribute filters).
If this function returns a non-NULL feature, it is guaranteed that its
feature id (OGR_F_GetFID()) will be the same as nFID.
Use OGR_L_TestCapability(OLCRandomRead) to establish if this layer
supports efficient random access reading via OGR_L_GetFeature(); however,
the call should always work if the feature exists as a fallback
implementation just scans all the features in the layer looking for the
desired feature.
Sequential reads (with OGR_L_GetNextFeature()) are generally considered interrupted by a
OGR_L_GetFeature() call.
The returned feature should be free with OGR_F_Destroy().
This function is the same as the C++ method OGRLayer::GetFeature( ).
@param hLayer handle to the layer that owned the feature.
@param nFeatureId the feature id of the feature to read.
@return an handle to a feature now owned by the caller, or NULL on failure.
*/
/**
\fn OGRErr OGRLayer::SetFeature( OGRFeature * poFeature );
\brief Rewrite an existing feature.
This method will write a feature to the layer, based on the feature id
within the OGRFeature.
Use OGRLayer::TestCapability(OLCRandomWrite) to establish if this layer
supports random access writing via SetFeature().
Starting with GDAL 2.0, drivers should specialize the ISetFeature() method,
since SetFeature() is no longer virtual.
This method is the same as the C function OGR_L_SetFeature().
@param poFeature the feature to write.
@return OGRERR_NONE if the operation works, otherwise an appropriate error
code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist).
*/
/**
\fn OGRErr OGRLayer::ISetFeature( OGRFeature * poFeature );
\brief Rewrite an existing feature.
This method is implemented by drivers and not called directly. User code should
use SetFeature() instead.
This method will write a feature to the layer, based on the feature id
within the OGRFeature.
@param poFeature the feature to write.
@return OGRERR_NONE if the operation works, otherwise an appropriate error
code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist).
@since GDAL 2.0
*/
/**
\fn OGRErr OGR_L_SetFeature( OGRLayerH hLayer, OGRFeatureH hFeat );
\brief Rewrite an existing feature.
This function will write a feature to the layer, based on the feature id
within the OGRFeature.
Use OGR_L_TestCapability(OLCRandomWrite) to establish if this layer
supports random access writing via OGR_L_SetFeature().
This function is the same as the C++ method OGRLayer::SetFeature().
@param hLayer handle to the layer to write the feature.
@param hFeat the feature to write.
@return OGRERR_NONE if the operation works, otherwise an appropriate error
code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist).
*/
/**
\fn OGRErr OGRLayer::CreateFeature( OGRFeature * poFeature );
\brief Create and write a new feature within a layer.
The passed feature is written to the layer as a new feature, rather than
overwriting an existing one. If the feature has a feature id other than
OGRNullFID, then the native implementation may use that as the feature id
of the new feature, but not necessarily. Upon successful return the
passed feature will have been updated with the new feature id.
Starting with GDAL 2.0, drivers should specialize the ICreateFeature() method,
since CreateFeature() is no longer virtual.
This method is the same as the C function OGR_L_CreateFeature().
@param poFeature the feature to write to disk.
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGRLayer::ICreateFeature( OGRFeature * poFeature );
\brief Create and write a new feature within a layer.
This method is implemented by drivers and not called directly. User code should
use CreateFeature() instead.
The passed feature is written to the layer as a new feature, rather than
overwriting an existing one. If the feature has a feature id other than
OGRNullFID, then the native implementation may use that as the feature id
of the new feature, but not necessarily. Upon successful return the
passed feature will have been updated with the new feature id.
@param poFeature the feature to write to disk.
@return OGRERR_NONE on success.
@since GDAL 2.0
*/
/**
\fn OGRErr OGR_L_CreateFeature( OGRLayerH hLayer, OGRFeatureH hFeat );
\brief Create and write a new feature within a layer.
The passed feature is written to the layer as a new feature, rather than
overwriting an existing one. If the feature has a feature id other than
OGRNullFID, then the native implementation may use that as the feature id
of the new feature, but not necessarily. Upon successful return the
passed feature will have been updated with the new feature id.
This function is the same as the C++ method OGRLayer::CreateFeature().
@param hLayer handle to the layer to write the feature to.
@param hFeat the handle of the feature to write to disk.
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGRLayer::DeleteFeature( GIntBig nFID );
\brief Delete feature from layer.
The feature with the indicated feature id is deleted from the layer if
supported by the driver. Most drivers do not support feature deletion,
and will return OGRERR_UNSUPPORTED_OPERATION. The TestCapability()
layer method may be called with OLCDeleteFeature to check if the driver
supports feature deletion.
This method is the same as the C function OGR_L_DeleteFeature().
@param nFID the feature id to be deleted from the layer
@return OGRERR_NONE if the operation works, otherwise an appropriate error
code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist).
*/
/**
\fn OGRErr OGR_L_DeleteFeature( OGRLayerH hLayer, GIntBig nFID );
\brief Delete feature from layer.
The feature with the indicated feature id is deleted from the layer if
supported by the driver. Most drivers do not support feature deletion,
and will return OGRERR_UNSUPPORTED_OPERATION. The OGR_L_TestCapability()
function may be called with OLCDeleteFeature to check if the driver
supports feature deletion.
This method is the same as the C++ method OGRLayer::DeleteFeature().
@param hLayer handle to the layer
@param nFID the feature id to be deleted from the layer
@return OGRERR_NONE if the operation works, otherwise an appropriate error
code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist).
*/
/**
\fn int OGRLayer::TestCapability( const char * pszCap );
\brief Test if this layer supported the named capability.
The capability codes that can be tested are represented as strings, but
\#defined constants exists to ensure correct spelling. Specific layer
types may implement class specific capabilities, but this can't generally
be discovered by the caller.
- OLCRandomRead / "RandomRead": TRUE if the GetFeature() method
is implemented in an optimized way for this layer, as opposed to the default
implementation using ResetReading() and GetNextFeature() to find the requested
feature id.
- OLCSequentialWrite / "SequentialWrite": TRUE if the
CreateFeature() method works for this layer. Note this means that this
particular layer is writable. The same OGRLayer class may returned FALSE
for other layer instances that are effectively read-only.
- OLCRandomWrite / "RandomWrite": TRUE if the SetFeature() method
is operational on this layer. Note this means that this
particular layer is writable. The same OGRLayer class may returned FALSE
for other layer instances that are effectively read-only.
- OLCFastSpatialFilter / "FastSpatialFilter": TRUE if this layer
implements spatial filtering efficiently. Layers that effectively read all
features, and test them with the OGRFeature intersection methods should
return FALSE. This can be used as a clue by the application whether it
should build and maintain its own spatial index for features in this layer.
- OLCFastFeatureCount / "FastFeatureCount":
TRUE if this layer can return a feature
count (via GetFeatureCount()) efficiently. i.e. without counting
the features. In some cases this will return TRUE until a spatial filter is
installed after which it will return FALSE.
- OLCFastGetExtent / "FastGetExtent":
TRUE if this layer can return its data extent (via GetExtent())
efficiently, i.e. without scanning all the features. In some cases this
will return TRUE until a spatial filter is installed after which it will
return FALSE.
- OLCFastSetNextByIndex / "FastSetNextByIndex":
TRUE if this layer can perform the SetNextByIndex() call efficiently, otherwise
FALSE.
- OLCCreateField / "CreateField": TRUE if this layer can create
new fields on the current layer using CreateField(), otherwise FALSE.
- OLCCreateGeomField / "CreateGeomField": (GDAL >= 1.11) TRUE if this layer can create
new geometry fields on the current layer using CreateGeomField(), otherwise FALSE.
- OLCDeleteField / "DeleteField": TRUE if this layer can delete
existing fields on the current layer using DeleteField(), otherwise FALSE.
- OLCReorderFields / "ReorderFields": TRUE if this layer can reorder
existing fields on the current layer using ReorderField() or ReorderFields(), otherwise FALSE.
- OLCAlterFieldDefn / "AlterFieldDefn": TRUE if this layer can alter
the definition of an existing field on the current layer using AlterFieldDefn(), otherwise FALSE.
- OLCDeleteFeature / "DeleteFeature": TRUE if the DeleteFeature()
method is supported on this layer, otherwise FALSE.
- OLCStringsAsUTF8 / "StringsAsUTF8": TRUE if values of OFTString
fields are assured to be in UTF-8 format. If FALSE the encoding of fields
is uncertain, though it might still be UTF-8.
- OLCTransactions / "Transactions": TRUE if the StartTransaction(),
CommitTransaction() and RollbackTransaction() methods work in a meaningful way,
otherwise FALSE.
- OLCIgnoreFields / "IgnoreFields": TRUE if fields, geometry and style
will be omitted when fetching features as set by SetIgnoredFields() method.
- OLCCurveGeometries / "CurveGeometries": TRUE if this layer supports
writing curve geometries or may return such geometries. (GDAL 2.0).
This method is the same as the C function OGR_L_TestCapability().
@param pszCap the name of the capability to test.
@return TRUE if the layer has the requested capability, or FALSE otherwise.
OGRLayers will return FALSE for any unrecognized capabilities.
*/
/**
\fn int OGR_L_TestCapability( OGRLayerH hLayer, const char *pszCap );
\brief Test if this layer supported the named capability.
The capability codes that can be tested are represented as strings, but
\#defined constants exists to ensure correct spelling. Specific layer
types may implement class specific capabilities, but this can't generally
be discovered by the caller.
- OLCRandomRead / "RandomRead": TRUE if the GetFeature() method
is implemented in an optimized way for this layer, as opposed to the default
implementation using ResetReading() and GetNextFeature() to find the requested
feature id.
- OLCSequentialWrite / "SequentialWrite": TRUE if the
CreateFeature() method works for this layer. Note this means that this
particular layer is writable. The same OGRLayer class may returned FALSE
for other layer instances that are effectively read-only.
- OLCRandomWrite / "RandomWrite": TRUE if the SetFeature() method
is operational on this layer. Note this means that this
particular layer is writable. The same OGRLayer class may returned FALSE
for other layer instances that are effectively read-only.
- OLCFastSpatialFilter / "FastSpatialFilter": TRUE if this layer
implements spatial filtering efficiently. Layers that effectively read all
features, and test them with the OGRFeature intersection methods should
return FALSE. This can be used as a clue by the application whether it
should build and maintain its own spatial index for features in this
layer.
- OLCFastFeatureCount / "FastFeatureCount":
TRUE if this layer can return a feature
count (via OGR_L_GetFeatureCount()) efficiently, i.e. without counting
the features. In some cases this will return TRUE until a spatial filter is
installed after which it will return FALSE.
- OLCFastGetExtent / "FastGetExtent":
TRUE if this layer can return its data extent (via OGR_L_GetExtent())
efficiently, i.e. without scanning all the features. In some cases this
will return TRUE until a spatial filter is installed after which it will
return FALSE.
- OLCFastSetNextByIndex / "FastSetNextByIndex":
TRUE if this layer can perform the SetNextByIndex() call efficiently, otherwise
FALSE.
- OLCCreateField / "CreateField": TRUE if this layer can create
new fields on the current layer using CreateField(), otherwise FALSE.
- OLCCreateGeomField / "CreateGeomField": (GDAL >= 1.11) TRUE if this layer can create
new geometry fields on the current layer using CreateGeomField(), otherwise FALSE.
- OLCDeleteField / "DeleteField": TRUE if this layer can delete
existing fields on the current layer using DeleteField(), otherwise FALSE.
- OLCReorderFields / "ReorderFields": TRUE if this layer can reorder
existing fields on the current layer using ReorderField() or ReorderFields(), otherwise FALSE.
- OLCAlterFieldDefn / "AlterFieldDefn": TRUE if this layer can alter
the definition of an existing field on the current layer using AlterFieldDefn(), otherwise FALSE.
- OLCDeleteFeature / "DeleteFeature": TRUE if the DeleteFeature()
method is supported on this layer, otherwise FALSE.
- OLCStringsAsUTF8 / "StringsAsUTF8": TRUE if values of OFTString
fields are assured to be in UTF-8 format. If FALSE the encoding of fields
is uncertain, though it might still be UTF-8.
- OLCTransactions / "Transactions": TRUE if the StartTransaction(),
CommitTransaction() and RollbackTransaction() methods work in a meaningful way,
otherwise FALSE.
- OLCCurveGeometries / "CurveGeometries": TRUE if this layer supports
writing curve geometries or may return such geometries. (GDAL 2.0).
This function is the same as the C++ method OGRLayer::TestCapability().
@param hLayer handle to the layer to get the capability from.
@param pszCap the name of the capability to test.
@return TRUE if the layer has the requested capability, or FALSE otherwise.
OGRLayers will return FALSE for any unrecognized capabilities.
*/
/**
\fn OGRErr OGRLayer::SyncToDisk();
\brief Flush pending changes to disk.
This call is intended to force the layer 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 layers do not implement this method, and will still return
OGRERR_NONE. The default implementation just returns OGRERR_NONE. An error
is only returned if an error occurs while attempting to flush to disk.
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_L_SyncToDisk().
@return OGRERR_NONE if no error occurs (even if nothing is done) or an
error code.
*/
/**
\fn OGRErr OGR_L_SyncToDisk(OGRLayerH hLayer);
\brief Flush pending changes to disk.
This call is intended to force the layer 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 layers do not implement this method, and will still return
OGRERR_NONE. The default implementation just returns OGRERR_NONE. An error
is only returned if an error occurs while attempting to flush to disk.
In any event, you should always close any opened datasource with
OGR_DS_Destroy() that will ensure all data is correctly flushed.
This method is the same as the C++ method OGRLayer::SyncToDisk()
@param hLayer handle to the layer
@return OGRERR_NONE if no error occurs (even if nothing is done) or an
error code.
*/
/**
\fn OGRErr OGRLayer::SetNextByIndex( GIntBig nIndex );
\brief Move read cursor to the nIndex'th feature in the current resultset.
This method allows positioning of a layer such that the GetNextFeature()
call will read the requested feature, where nIndex is an absolute index
into the current result set. So, setting it to 3 would mean the next
feature read with GetNextFeature() would have been the 4th feature to have
been read if sequential reading took place from the beginning of the layer,
including accounting for spatial and attribute filters.
Only in rare circumstances is SetNextByIndex() efficiently implemented.
In all other cases the default implementation which calls ResetReading()
and then calls GetNextFeature() nIndex times is used. To determine if
fast seeking is available on the current layer use the TestCapability()
method with a value of OLCFastSetNextByIndex.
This method is the same as the C function OGR_L_SetNextByIndex().
@param nIndex the index indicating how many steps into the result set
to seek.
@return OGRERR_NONE on success or an error code.
*/
/**
\fn OGRErr OGR_L_SetNextByIndex( OGRLayerH hLayer, GIntBig nIndex );
\brief Move read cursor to the nIndex'th feature in the current resultset.
This method allows positioning of a layer such that the GetNextFeature()
call will read the requested feature, where nIndex is an absolute index
into the current result set. So, setting it to 3 would mean the next
feature read with GetNextFeature() would have been the 4th feature to have
been read if sequential reading took place from the beginning of the layer,
including accounting for spatial and attribute filters.
Only in rare circumstances is SetNextByIndex() efficiently implemented.
In all other cases the default implementation which calls ResetReading()
and then calls GetNextFeature() nIndex times is used. To determine if
fast seeking is available on the current layer use the TestCapability()
method with a value of OLCFastSetNextByIndex.
This method is the same as the C++ method OGRLayer::SetNextByIndex()
@param hLayer handle to the layer
@param nIndex the index indicating how many steps into the result set
to seek.
@return OGRERR_NONE on success or an error code.
*/
/**
\fn int OGRLayer::Reference();
\brief Increment layer reference count.
This method is the same as the C function OGR_L_Reference().
@return the reference count after incrementing.
*/
/**
\fn int OGRLayer::Dereference();
\brief Decrement layer reference count.
This method is the same as the C function OGR_L_Dereference().
@return the reference count after decrementing.
*/
/**
\fn int OGRLayer::GetRefCount() const;
\brief Fetch reference count.
This method is the same as the C function OGR_L_GetRefCount().
@return the current reference count for the layer object itself.
*/
/**
\fn OGRErr OGRLayer::CreateField( OGRFieldDefn *poField,
int bApproxOK = TRUE );
\brief Create a new field on a layer.
You must use this to create new fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the new field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCCreateField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
Drivers may or may not support not-null constraints. If they support creating
fields with not-null constraints, this is generally before creating any feature to the layer.
This function is the same as the C function OGR_L_CreateField().
@param poField field definition to write to disk.
@param bApproxOK If TRUE, the field may be created in a slightly different
form depending on the limitations of the format driver.
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGR_L_CreateField( OGRLayerH hLayer, OGRFieldDefnH hField,
int bApproxOK );
\brief Create a new field on a layer.
You must use this to create new fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the new field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCCreateField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
Drivers may or may not support not-null constraints. If they support creating
fields with not-null constraints, this is generally before creating any feature to the layer.
This function is the same as the C++ method OGRLayer::CreateField().
@param hLayer handle to the layer to write the field definition.
@param hField handle of the field definition to write to disk.
@param bApproxOK If TRUE, the field may be created in a slightly different
form depending on the limitations of the format driver.
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGRLayer::DeleteField( int iField );
\brief Delete an existing field on a layer.
You must use this to delete existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the deleted field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCDeleteField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C function OGR_L_DeleteField().
@param iField index of the field to delete.
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGR_L_DeleteField( OGRLayerH hLayer, int iField);
\brief Delete an existing field on a layer.
You must use this to delete existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the deleted field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCDeleteField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C++ method OGRLayer::DeleteField().
@param hLayer handle to the layer.
@param iField index of the field to delete.
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGRLayer::ReorderFields( int* panMap );
\brief Reorder all the fields of a layer.
You must use this to reorder existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
panMap is such that,for each field definition at position i after reordering,
its position before reordering was panMap[i].
For example, let suppose the fields were "0","1","2","3","4" initially.
ReorderFields([0,2,3,1,4]) will reorder them as "0","2","3","1","4".
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCReorderFields capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C function OGR_L_ReorderFields().
@param panMap an array of GetLayerDefn()->OGRFeatureDefn::GetFieldCount() elements which
is a permutation of [0, GetLayerDefn()->OGRFeatureDefn::GetFieldCount()-1].
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGR_L_ReorderFields( OGRLayerH hLayer, int* panMap );
\brief Reorder all the fields of a layer.
You must use this to reorder existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
panMap is such that,for each field definition at position i after reordering,
its position before reordering was panMap[i].
For example, let suppose the fields were "0","1","2","3","4" initially.
ReorderFields([0,2,3,1,4]) will reorder them as "0","2","3","1","4".
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCReorderFields capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C++ method OGRLayer::ReorderFields().
@param hLayer handle to the layer.
@param panMap an array of GetLayerDefn()->OGRFeatureDefn::GetFieldCount() elements which
is a permutation of [0, GetLayerDefn()->OGRFeatureDefn::GetFieldCount()-1].
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGRLayer::ReorderField( int iOldFieldPos, int iNewFieldPos );
\brief Reorder an existing field on a layer.
This method is a convenience wrapper of ReorderFields() dedicated to move a single field.
It is a non-virtual method, so drivers should implement ReorderFields() instead.
You must use this to reorder existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
The field definition that was at initial position iOldFieldPos will be moved at
position iNewFieldPos, and elements between will be shuffled accordingly.
For example, let suppose the fields were "0","1","2","3","4" initially.
ReorderField(1, 3) will reorder them as "0","2","3","1","4".
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCReorderFields capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C function OGR_L_ReorderField().
@param iOldFieldPos previous position of the field to move. Must be in the range [0,GetFieldCount()-1].
@param iNewFieldPos new position of the field to move. Must be in the range [0,GetFieldCount()-1].
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGR_L_ReorderField( OGRLayerH hLayer, int iOldFieldPos, int iNewFieldPos );
\brief Reorder an existing field on a layer.
This function is a convenience wrapper of OGR_L_ReorderFields() dedicated to move a single field.
You must use this to reorder existing fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
The field definition that was at initial position iOldFieldPos will be moved at
position iNewFieldPos, and elements between will be shuffled accordingly.
For example, let suppose the fields were "0","1","2","3","4" initially.
ReorderField(1, 3) will reorder them as "0","2","3","1","4".
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCReorderFields capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
This function is the same as the C++ method OGRLayer::ReorderField().
@param hLayer handle to the layer.
@param iOldFieldPos previous position of the field to move. Must be in the range [0,GetFieldCount()-1].
@param iNewFieldPos new position of the field to move. Must be in the range [0,GetFieldCount()-1].
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGRLayer::AlterFieldDefn( int iField, OGRFieldDefn* poNewFieldDefn, int nFlags );
\brief Alter the definition of an existing field on a layer.
You must use this to alter the definition of an existing field of a real layer.
Internally the OGRFeatureDefn for the layer will be updated
to reflect the altered field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCAlterFieldDefn capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly. Some drivers might also not support
all update flags.
This function is the same as the C function OGR_L_AlterFieldDefn().
@param iField index of the field whose definition must be altered.
@param poNewFieldDefn new field definition
@param nFlags combination of ALTER_NAME_FLAG, ALTER_TYPE_FLAG, ALTER_WIDTH_PRECISION_FLAG,
ALTER_NULLABLE_FLAG and ALTER_DEFAULT_FLAG
to indicate which of the name and/or type and/or width and precision fields and/or nullability from the new field
definition must be taken into account.
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGR_L_AlterFieldDefn( OGRLayerH hLayer, int iField, OGRFieldDefnH hNewFieldDefn, int nFlags )
\brief Alter the definition of an existing field on a layer.
You must use this to alter the definition of an existing field of a real layer.
Internally the OGRFeatureDefn for the layer will be updated
to reflect the altered field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCAlterFieldDefn capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly. Some drivers might also not support
all update flags.
This function is the same as the C++ method OGRLayer::AlterFieldDefn().
@param hLayer handle to the layer.
@param iField index of the field whose definition must be altered.
@param hNewFieldDefn new field definition
@param nFlags combination of ALTER_NAME_FLAG, ALTER_TYPE_FLAG, ALTER_WIDTH_PRECISION_FLAG,
ALTER_NULLABLE_FLAG and ALTER_DEFAULT_FLAG
to indicate which of the name and/or type and/or width and precision fields and/or nullability from the new field
definition must be taken into account.
@return OGRERR_NONE on success.
@since OGR 1.9.0
*/
/**
\fn OGRErr OGRLayer::CreateGeomField( OGRGeomFieldDefn *poField,
int bApproxOK = TRUE );
\brief Create a new geometry field on a layer.
You must use this to create new geometry fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the new field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This method should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this method. You can query a layer to check if it supports it
with the OLCCreateGeomField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
Drivers may or may not support not-null constraints. If they support creating
fields with not-null constraints, this is generally before creating any feature to the layer.
This function is the same as the C function OGR_L_CreateGeomField().
@param poField geometry field definition to write to disk.
@param bApproxOK If TRUE, the field may be created in a slightly different
form depending on the limitations of the format driver.
@return OGRERR_NONE on success.
@since OGR 1.11
*/
/**
\fn OGRErr OGR_L_CreateGeomField( OGRLayerH hLayer, OGRGeomFieldDefnH hField,
int bApproxOK );
\brief Create a new geometry field on a layer.
You must use this to create new geometry fields
on a real layer. Internally the OGRFeatureDefn for the layer will be updated
to reflect the new field. Applications should never modify the OGRFeatureDefn
used by a layer directly.
This function should not be called while there are feature objects in existence that
were obtained or created with the previous layer definition.
Not all drivers support this function. You can query a layer to check if it supports it
with the OLCCreateField capability. Some drivers may only support this method while
there are still no features in the layer. When it is supported, the existing features of the
backing file/database should be updated accordingly.
Drivers may or may not support not-null constraints. If they support creating
fields with not-null constraints, this is generally before creating any feature to the layer.
This function is the same as the C++ method OGRLayer::CreateField().
@param hLayer handle to the layer to write the field definition.
@param hField handle of the geometry field definition to write to disk.
@param bApproxOK If TRUE, the field may be created in a slightly different
form depending on the limitations of the format driver.
@return OGRERR_NONE on success.
@since OGR 1.11
*/
/**
\fn void OGRLayer::GetStyleTable();
\brief Returns layer style table.
This method is the same as the C function OGR_L_GetStyleTable().
@return pointer to a style table which should not be modified or freed by the
caller.
*/
/**
\fn void OGRLayer::SetStyleTable(OGRStyleTable *poStyleTable);
\brief Set layer style table.
This method operate exactly as OGRLayer::SetStyleTableDirectly() except
that it does not assume ownership of the passed table.
This method is the same as the C function OGR_L_SetStyleTable().
@param poStyleTable pointer to style table to set
*/
/**
\fn void OGRLayer::SetStyleTableDirectly(OGRStyleTable *poStyleTable);
\brief Set layer style table.
This method operate exactly as OGRLayer::SetStyleTable() except that it
assumes ownership of the passed table.
This method is the same as the C function OGR_L_SetStyleTableDirectly().
@param poStyleTable pointer to style table to set
*/
/**
\fn OGRErr OGRLayer::StartTransaction():
\brief For datasources which support transactions, StartTransaction creates a transaction.
If starting the transaction fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
Note: as of GDAL 2.0, use of this API is discouraged when the dataset offers
dataset level transaction with GDALDataset::StartTransaction(). The reason is
that most drivers can only offer transactions at dataset level, and not layer level.
Very few drivers really support transactions at layer scope.
This function is the same as the C function OGR_L_StartTransaction().
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGR_L_StartTransaction( OGRLayerH hLayer );
\brief For datasources which support transactions, StartTransaction creates a transaction.
If starting the transaction fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
Note: as of GDAL 2.0, use of this API is discouraged when the dataset offers
dataset level transaction with GDALDataset::StartTransaction(). The reason is
that most drivers can only offer transactions at dataset level, and not layer level.
Very few drivers really support transactions at layer scope.
This function is the same as the C++ method OGRLayer::StartTransaction().
@param hLayer handle to the layer
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGRLayer::CommitTransaction():
\brief For datasources which support transactions, CommitTransaction commits a transaction.
If no transaction is active, or the commit fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
This function is the same as the C function OGR_L_CommitTransaction().
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGR_L_CommitTransaction( OGRLayerH hLayer );
\brief For datasources which support transactions, CommitTransaction commits a transaction.
If no transaction is active, or the commit fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
This function is the same as the C++ method OGRLayer::CommitTransaction().
@param hLayer handle to the layer
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGRLayer::RollbackTransaction():
\brief For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.
If no transaction is active, or the rollback fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
This function is the same as the C function OGR_L_RollbackTransaction().
@return OGRERR_NONE on success.
*/
/**
\fn OGRErr OGR_L_RollbackTransaction( OGRLayerH hLayer );
\brief For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction.
If no transaction is active, or the rollback fails, will return
OGRERR_FAILURE. Datasources which do not support transactions will
always return OGRERR_NONE.
This function is the same as the C++ method OGRLayer::RollbackTransaction().
@param hLayer handle to the layer
@return OGRERR_NONE on success.
*/
/**
\fn const char *OGRLayer::GetFIDColumn();
\brief This method returns the name of the underlying database column being used as the FID column, or "" if not supported.
This method is the same as the C function OGR_L_GetFIDColumn().
@return fid column name.
*/
/**
\fn const char* OGR_L_GetFIDColumn(OGRLayerH hLayer);
\brief This method returns the name of the underlying database column being used as the FID column, or "" if not supported.
This method is the same as the C++ method OGRLayer::GetFIDColumn()
@param hLayer handle to the layer
@return fid column name.
*/
/**
\fn const char *OGRLayer::GetGeometryColumn();
\brief This method returns the name of the underlying database column being used as the geometry column, or "" if not supported.
For layers with multiple geometry fields, this method only returns the name
of the first geometry column. For other columns, use
GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(i)->GetNameRef().
This method is the same as the C function OGR_L_GetGeometryColumn().
@return geometry column name.
*/
/**
\fn const char* OGR_L_GetGeometryColumn(OGRLayerH hLayer);
\brief This method returns the name of the underlying database column being used as the geometry column, or "" if not supported.
For layers with multiple geometry fields, this method only returns the geometry
type of the first geometry column. For other columns, use
OGR_GFld_GetNameRef(OGR_FD_GetGeomFieldDefn(OGR_L_GetLayerDefn(hLayer), i)).
This method is the same as the C++ method OGRLayer::GetGeometryColumn()
@param hLayer handle to the layer
@return geometry column name.
*/
/**
\fn OGRErr OGRLayer::SetIgnoredFields( const char **papszFields );
\brief Set which fields can be omitted when retrieving features from the layer.
If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields
in subsequent calls to GetFeature() / GetNextFeature() and thus save some processing time and/or bandwidth.
Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and
"OGR_STYLE" to ignore layer style.
By default, no fields are ignored.
This method is the same as the C function OGR_L_SetIgnoredFields()
@param papszFields an array of field names terminated by NULL item. If NULL is passed, the ignored list is cleared.
@return OGRERR_NONE if all field names have been resolved (even if the driver does not support this method)
*/
/**
\fn OGRErr OGR_L_SetIgnoredFields( OGRLayerH, const char** papszFields);
\brief Set which fields can be omitted when retrieving features from the layer.
If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields
in subsequent calls to GetFeature() / GetNextFeature() and thus save some processing time and/or bandwidth.
Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and
"OGR_STYLE" to ignore layer style.
By default, no fields are ignored.
This method is the same as the C++ method OGRLayer::SetIgnoredFields()
@param papszFields an array of field names terminated by NULL item. If NULL is passed, the ignored list is cleared.
@return OGRERR_NONE if all field names have been resolved (even if the driver does not support this method)
*/