/******************************************************************************
 * $Id: ogrsf_frmts.dox,v 1.8 2002/03/27 21:24:55 warmerda Exp $
 *
 * 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.
 ******************************************************************************
 *
 * $Log: ogrsf_frmts.dox,v $
 * Revision 1.8  2002/03/27 21:24:55  warmerda
 * updates notes on GetFeature()
 *
 * Revision 1.7  2001/10/02 14:24:24  warmerda
 * added SetAttributeFilter docs
 *
 * Revision 1.6  2001/03/15 04:01:43  danmo
 * Added OGRLayer::GetExtent()
 *
 * Revision 1.5  1999/10/13 13:19:22  warmerda
 * Fixed CreateFeature() documentation.
 *
 * Revision 1.4  1999/07/27 00:50:34  warmerda
 * added a number of OGRLayer methods
 *
 * Revision 1.3  1999/07/08 20:23:07  warmerda
 * Added help for GetFeatureCount(), and spatial filtering.
 *
 * Revision 1.2  1999/07/06 20:37:32  warmerda
 * Added header.
 *
 */

/************************************************************************/
/*                         OGRSFDriverRegistrar                         */
/************************************************************************/

/**
 
  \fn OGRDataSource *OGRSFDriverRegistrar::Open( const char *pszName, int bUpdate = FALSE, OGRSFDriver **ppoDriver=NULL);

  Open a file / data source with one of the registered drivers.

  This method loops through all the drivers registered with the driver
  manager trying each until one succeeds with the give data source.  This
  method is static.  Applications don't normally need to use any other
  OGRSFDriverRegistrar methods directly, not do they normally need to have
  a pointer to an OGRSFDriverRegistrar instance.

  If this method fails, CPLGetLastErrorMsg() can be used to check if there
  is an error message explaining why.

  @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 ppoDriver 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 a pointer to an OGRDataSource.  This OGRDataSource should be
  closed by deleting the object when it is no longer needed.

  <b>Example:</b>

  <pre>
    OGRDataSource	*poDS;

    poDS = OGRSFDriverRegistrar::Open( "polygon.shp" );
    if( poDS == NULL )
    {
        return;
    }

    ... use the data source ...

    delete poDS;
  </pre>

*/

/**
  \fn OGRSFDriverRegistrar *OGRSFDriverRegistrar::GetRegistrar();

  Return the driver manager, creating one if none exist. 

  @return the driver manager.

*/

/** 
  \fn void OGRSFDriverRegistrar::RegisterDriver( OGRSFDriver * poDriver );
  
  Add a driver to the list of registered drivers.

  If the passed driver is already registered (based on pointer comparison) 
  then the driver isn't registered.  New drivers are added at the end of
  the list of registered drivers.

  @param poDriver the driver to add.

*/

/**

  \fn int OGRSFDriverRegistrar::GetDriverCount();

  Fetch the number of registered drivers.

  @return the driver count.

*/

/**
 
  \fn OGRSFDriver * OGRSFDriverRegistrar::GetDriver( int iDriver );

  Fetch the indicated driver.

  @param iDriver the driver index, from 0 to GetDriverCount()-1.

  @return pointer to the driver, or NULL if iDriver is out of range.

*/


/************************************************************************/
/*                             OGRSFDriver                              */
/************************************************************************/


/** 

  \fn const char *OGRSFDriver::GetName();

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

  @return driver name.  This is an internal string and should not be modified
  or freed. 
*/

/**

  \fn OGRDataSource *OGRSFDriver::Open( const char *pszName, int bUpdate );

  Attempt to open file with this driver. 

  This method is what OGRSFDriverRegistrar uses to implement its Open() method.
  See it for more details.

  @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 a pointer to an OGRDataSource.  This OGRDataSource should be
  closed by deleting the object when it is no longer needed.

*/

/************************************************************************/
/*                            OGRDataSource                             */
/************************************************************************/

/** 
 \fn const char *OGRDataSource::GetName();

 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 a filename. 

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

*/

/**
 \fn int OGRDataSource::GetLayerCount();

 Get the number of layers in this data source.

 @return layer count.

*/

/**
 \fn OGRLayer *OGRDataSource::GetLayer(int iLayer);

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

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

 @return the layer, or NULL if iLayer is out of range or an error occurs.

*/

/************************************************************************/
/*                               OGRLayer                               */
/************************************************************************/

/**
 \fn void OGRLayer::ResetReading();

 Reset feature reading to start on the first feature.  This affects 
 GetNextFeature().

*/

/**
 \fn OGRFeature *OGRLayer::GetNextFeature();

 Fetch the next available feature from this layer.  The returned feature
 becomes the responsiblity of the caller to delete.  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.  Random
 reading, writing and spatial filtering will be added to the OGRLayer in 
 the future.

 @return a feature, or NULL if no more features are available. 

*/

/**

 \fn int OGRLayer::GetFeatureCount( int bForce = TRUE );

 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. 

 @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 );

 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.

 The returned extent does not take the spatial filter into account.  If
 a spatial filter was previously set then it should be ignored but some
 implementations may be unable to do that, so it is safer to call 
 GetExtent() without setting a spatial filter.

 @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 );

 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 layer (as returned by OGRLayer::GetSpatialRef()).  In the
 future this may be generalized. 

 @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 OGRGeometry *OGRLayer::GetSpatialFilter();

 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.  

 @return spatial filter geometry.
 
 */

/** 
 \fn void OGRLayer::SetAttributeFilter( const char *pszQuery );

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

 @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();

 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. 

 @return feature definition.

*/

/**

 \fn OGRSpatialReference *OGRLayer::GetSpatialRef();

 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.  

 @return spatial reference, or NULL if there isn't one.

*/

/**

 \fn OGRFeature *OGRLayer::GetFeature( long nFID );

 Fetch a feature by it's 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.

 If this method returns a non-NULL feature, it is guaranteed that it's 
 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 are generally considered interrupted bya GetFeature() call.

 @param nFID the feature id of the feature to read. 

 @return a feature now owned by the caller, or NULL on failure. 

*/

/**
 
 \fn OGRErr OGRLayer::SetFeature( OGRFeature * poFeature );

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

 @param poFeature the feature to write.

 @return OGRERR_NONE if the operation works, otherwise an appropriate error
 code.

*/

/**

 \fn OGRErr OGRLayer::CreateFeature( OGRFeature * poFeature );

 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. 

 @param poFeature the feature to write to disk. 

 @return OGRERR_NONE on success.

*/

/**

 \fn int OGRLayer::TestCapability( const char * pszCap );

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

 <ul>

 <li> <b>OLCRandomRead</b> / "RandomRead": TRUE if the GetFeature() method 
works for this layer.<p>

 <li> <b>OLCSequentialWrite</b> / "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.<p>

 <li> <b>OLCRandomWrite</b> / "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.<p>

 <li> <b>OLCFastSpatialFilter</b> / "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 it's own spatial index for features in this layer.<p>

 <li> <b>OLCFastFeatureCount</b> / "FastFeatureCount": 
TRUE if this layer can return a feature
count (via OGRLayer::GetFeatureCount()) efficiently ... ie. without counting
the features.  In some cases this will return TRUE until a spatial filter is
installed after which it will return FALSE.<p>

 <li> <b>OLCFastGetExtent</b> / "FastGetExtent": 
TRUE if this layer can return its data extent (via OGRLayer::GetExtent()) efficiently ... ie. without scanning all the features.  In some cases this will return TRUE until a spatial filter is installed after which it will return FALSE.<p>

</ul>

 @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 unrecognised capabilities.<p>

*/

/**
 \fn const char *OGRLayer::GetInfo( const char *pszTag );

 Fetch metadata from layer.

 This method can be used to fetch various kinds of metadata or layer 
 specific information encoded as a string.  It is anticipated that various
 tag values will be defined with well known semantics, while other tags will
 be used for driver/application specific purposes.  

 @param pszTag the tag for which information is being requested.

 @return the value of the requested tag, or NULL if that tag does not
 have a value, or is unknown.

*/

