1/****************************************************************************** 2 * $Id: ogrsf_frmts.dox d2970d9cd578d6a84bfd4a091fe8251e0f31914f 2020-12-14 22:04:12 +0100 Even Rouault $ 3 * 4 * Project: OpenGIS Simple Features Reference Implementation 5 * Purpose: Documentation for ogrsf_frmts.h classes. 6 * Author: Frank Warmerdam, warmerda@home.com 7 * 8 ****************************************************************************** 9 * Copyright (c) 1999, Les Technologies SoftMap Inc. 10 * 11 * Permission is hereby granted, free of charge, to any person obtaining a 12 * copy of this software and associated documentation files (the "Software"), 13 * to deal in the Software without restriction, including without limitation 14 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 15 * and/or sell copies of the Software, and to permit persons to whom the 16 * Software is furnished to do so, subject to the following conditions: 17 * 18 * The above copyright notice and this permission notice shall be included 19 * in all copies or substantial portions of the Software. 20 * 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 22 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 24 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 27 * DEALINGS IN THE SOFTWARE. 28 ******************************************************************************/ 29 30/************************************************************************/ 31/* OGRSFDriverRegistrar */ 32/************************************************************************/ 33 34/** 35 36 \fn OGRDataSourceH OGROpen( const char *pszName, int bUpdate, 37 OGRSFDriverH *pahDriverList ); 38 39 \brief Open a file / data source with one of the registered drivers. 40 41 This function loops through all the drivers registered with the driver 42 manager trying each until one succeeds with the given data source. 43 44 If this function fails, CPLGetLastErrorMsg() can be used to check if there 45 is an error message explaining why. 46 47 For drivers supporting the VSI virtual file API, it is possible to open 48 a file in a .zip archive (see VSIInstallZipFileHandler()), in a .tar/.tar.gz/.tgz archive 49 (see VSIInstallTarFileHandler()) or on a HTTP / FTP server (see VSIInstallCurlFileHandler()) 50 51 NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 52 OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*. 53 Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and 54 *NOT* OGRSFDriver*. 55 56 @deprecated Use GDALOpenEx() in GDAL 2.0 57 58 @param pszName the name of the file, or data source to open. 59 @param bUpdate FALSE for read-only access (the default) or TRUE for 60 read-write access. 61 @param pahDriverList if non-NULL, this argument will be updated with a 62 pointer to the driver which was used to open the data source. 63 64 @return NULL on error or if the pass name is not supported by this driver, 65 otherwise a handle to a GDALDataset. This GDALDataset should be 66 closed by deleting the object when it is no longer needed. 67 68 <b>Example:</b> 69 70 <pre> 71 OGRDataSourceH hDS; 72 OGRSFDriverH *pahDriver; 73 74 hDS = OGROpen( "polygon.shp", 0, pahDriver ); 75 if( hDS == NULL ) 76 { 77 return; 78 } 79 80 ... use the data source ... 81 82 OGRReleaseDataSource( hDS ); 83 </pre> 84 85*/ 86 87 88/** 89 90 \fn OGRDataSourceH OGROpenShared( const char *pszName, int bUpdate, 91 OGRSFDriverH *pahDriverList ); 92 93 \brief Open a file / data source with one of the registered drivers if not 94 already opened, or increment reference count of already opened data source 95 previously opened with OGROpenShared() 96 97 This function loops through all the drivers registered with the driver 98 manager trying each until one succeeds with the given data source. 99 100 If this function fails, CPLGetLastErrorMsg() can be used to check if there 101 is an error message explaining why. 102 103 NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 104 OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*. 105 Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and 106 *NOT* OGRSFDriver*. 107 108 @deprecated Use GDALOpenEx() in GDAL 2.0 109 110 @param pszName the name of the file, or data source to open. 111 @param bUpdate FALSE for read-only access (the default) or TRUE for 112 read-write access. 113 @param pahDriverList if non-NULL, this argument will be updated with a 114 pointer to the driver which was used to open the data source. 115 116 @return NULL on error or if the pass name is not supported by this driver, 117 otherwise a handle to a GDALDataset. This GDALDataset should be 118 closed by deleting the object when it is no longer needed. 119 120 <b>Example:</b> 121 122 <pre> 123 OGRDataSourceH hDS; 124 OGRSFDriverH *pahDriver; 125 126 hDS = OGROpenShared( "polygon.shp", 0, pahDriver ); 127 if( hDS == NULL ) 128 { 129 return; 130 } 131 132 ... use the data source ... 133 134 OGRReleaseDataSource( hDS ); 135 </pre> 136 137*/ 138 139/** 140 141 \fn int OGRGetDriverCount(); 142 143 \brief Fetch the number of registered drivers. 144 145 @deprecated Use GDALGetDriverCount() in GDAL 2.0 146 147 @return the drivers count. 148 149*/ 150 151/** 152 153 \fn OGRSFDriverH OGRGetDriver( int iDriver ); 154 155 \brief Fetch the indicated driver. 156 157 NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 158 OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*. 159 160 @deprecated Use GDALGetDriver() in GDAL 2.0 161 162 @param iDriver the driver index, from 0 to GetDriverCount()-1. 163 164 @return handle to the driver, or NULL if iDriver is out of range. 165 166*/ 167 168/** 169 \fn OGRSFDriverH OGRGetDriverByName( const char *pszName ); 170 171 \brief Fetch the indicated driver. 172 173 NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 174 OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*. 175 176 @deprecated Use GDALGetDriverByName() in GDAL 2.0 177 178 @param pszName the driver name 179 180 @return the driver, or NULL if no driver with that name is found 181*/ 182 183/** 184 185 \fn int OGRRegisterAll(); 186 187 \brief Register all drivers. 188 189 @deprecated Use GDALAllRegister() in GDAL 2.0 190*/ 191 192/************************************************************************/ 193/* OGRSFDriver */ 194/************************************************************************/ 195 196/** 197 198 \fn const char *OGR_Dr_GetName( OGRSFDriverH hDriver ); 199 200 \brief Fetch name of driver (file format). 201 This name should be relatively short 202 (10-40 characters), and should reflect the underlying file format. For 203 instance "ESRI Shapefile". 204 205 This function is the same as the C++ method OGRSFDriver::GetName(). 206 207 @param hDriver handle to the driver to get the name from. 208 @return driver name. This is an internal string and should not be modified 209 or freed. 210*/ 211 212/** 213 214 \fn OGRDataSourceH OGR_Dr_Open( OGRSFDriverH hDriver, const char *pszName, 215 int bUpdate ); 216 217 \brief Attempt to open file with this driver. 218 219 NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 220 OGRDataSource*. If a C++ object is needed, the handle should be cast to GDALDataset*. 221 Similarly, the returned OGRSFDriverH handle should be cast to GDALDriver*, and 222 *NOT* OGRSFDriver*. 223 224 @deprecated Use GDALOpenEx() in GDAL 2.0 225 226 @param hDriver handle to the driver that is used to open file. 227 @param pszName the name of the file, or data source to try and open. 228 @param bUpdate TRUE if update access is required, otherwise FALSE (the 229 default). 230 231 @return NULL on error or if the pass name is not supported by this driver, 232 otherwise a handle to a GDALDataset. This GDALDataset should be 233 closed by deleting the object when it is no longer needed. 234 235*/ 236 237/** 238 \fn int OGR_Dr_TestCapability( OGRSFDriverH hDriver, const char *pszCap ); 239 240 \brief Test if capability is available. 241 242 One of the following data source capability names can be passed into this 243 function, and a TRUE or FALSE value will be returned indicating whether 244 or not the capability is available for this object. 245 246 <ul> 247 <li> <b>ODrCCreateDataSource</b>: True if this driver can support creating data sources.<p> 248 <li> <b>ODrCDeleteDataSource</b>: True if this driver supports deleting data sources.<p> 249 </ul> 250 251 The \#define macro forms of the capability names should be used in preference 252 to the strings themselves to avoid misspelling. 253 254 @deprecated Use GDALGetMetadataItem(hDriver, GDAL_DCAP_CREATE) in GDAL 2.0 255 256 @param hDriver handle to the driver to test the capability against. 257 @param pszCap the capability to test. 258 259 @return TRUE if capability available otherwise FALSE. 260 261*/ 262 263/** 264 \fn OGRErr OGR_Dr_DeleteDataSource( OGRSFDriverH hDriver, 265 const char *pszDataSource ) 266 267 \brief Delete a datasource. 268 269 Delete (from the disk, in the database, ...) the named datasource. 270 Normally it would be safest if the datasource was not open at the time. 271 272 Whether this is a supported operation on this driver case be tested 273 using TestCapability() on ODrCDeleteDataSource. 274 275 @deprecated Use GDALDeleteDataset() in GDAL 2 276 277 @param hDriver handle to the driver on which data source deletion is 278based. 279 280 @param pszDataSource the name of the datasource to delete. 281 282 @return OGRERR_NONE on success, and OGRERR_UNSUPPORTED_OPERATION if this 283 is not supported by this driver. 284 285*/ 286 287/** 288 289 \fn OGRDataSourceH OGR_Dr_CreateDataSource( OGRSFDriverH hDriver, 290 const char *pszName, 291 char ** papszOptions ) 292 293 \brief This function attempts to create a new data source based on the passed driver. 294 295 The papszOptions argument can be used to control driver specific 296 creation options. These options are normally documented in the format 297 specific documentation. 298 299 It is important to call OGR_DS_Destroy() when the datasource is no longer 300 used to ensure that all data has been properly flushed to disk. 301 302 @deprecated Use GDALCreate() in GDAL 2.0 303 304 @param hDriver handle to the driver on which data source creation is 305based. 306 @param pszName the name for the new data source. UTF-8 encoded. 307 @param papszOptions a StringList of name=value options. Options are driver 308specific, and driver information can be found at the following url: 309http://www.gdal.org/ogr_formats.html 310 311 @return NULL is returned on failure, or a new OGRDataSource handle on 312success. 313*/ 314 315/** 316 317 \fn OGRDataSourceH OGR_Dr_CopyDataSource( OGRSFDriverH hDriver, 318 OGRDataSourceH hSrcDS, 319 const char *pszNewName, 320 char **papszOptions ) 321 322 \brief This function creates a new datasource by copying all the layers from the source datasource. 323 324 It is important to call OGR_DS_Destroy() when the datasource is no longer 325 used to ensure that all data has been properly flushed to disk. 326 327 @deprecated Use GDALCreateCopy() in GDAL 2.0 328 329 @param hDriver handle to the driver on which data source creation is 330based. 331 @param hSrcDS source datasource 332 @param pszNewName the name for the new data source. 333 @param papszOptions a StringList of name=value options. Options are driver 334specific, and driver information can be found at the following url: 335http://www.gdal.org/ogr_formats.html 336 337 @return NULL is returned on failure, or a new OGRDataSource handle on 338success. 339*/ 340 341/************************************************************************/ 342/* OGRDataSource */ 343/************************************************************************/ 344 345/** 346 \fn void OGR_DS_Destroy( OGRDataSourceH hDS ) 347 348 \brief Closes opened datasource and releases allocated resources. 349 350 This method is the same as the C++ method OGRDataSource::DestroyDataSource(). 351 352 @deprecated Use GDALClose() in GDAL 2.0 353 354 @param hDS handle to allocated datasource object. 355*/ 356 357/** 358 \fn const char *OGR_DS_GetName( OGRDataSourceH hDS ); 359 360 \brief Returns the name of the data source. 361 362 This string should be sufficient to 363 open the data source if passed to the same OGRSFDriver that this data 364 source was opened with, but it need not be exactly the same string that 365 was used to open the data source. Normally this is a filename. 366 367 @deprecated Use GDALGetDescription() in GDAL 2.0 368 369 @param hDS handle to the data source to get the name from. 370 @return pointer to an internal name string which should not be modified 371 or freed by the caller. 372 373*/ 374 375 376/** 377 \fn int OGR_DS_GetLayerCount( OGRDataSourceH hDS ); 378 379 \brief Get the number of layers in this data source. 380 381 @deprecated Use GDALDatasetGetLayerCount() in GDAL 2.0 382 383 @param hDS handle to the data source from which to get the number of layers. 384 @return layer count. 385 386*/ 387 388/** 389 \fn OGRLayerH OGR_DS_GetLayer( OGRDataSourceH hDS, int iLayer ); 390 391 \brief Fetch a layer by index. 392 393 The returned layer remains owned by the 394 OGRDataSource and should not be deleted by the application. 395 396 @deprecated Use GDALDatasetGetLayer() in GDAL 2.0 397 398 @param hDS handle to the data source from which to get the layer. 399 @param iLayer a layer number between 0 and OGR_DS_GetLayerCount()-1. 400 401 @return a handle to the layer, or NULL if iLayer is out of range 402 or an error occurs. 403 404*/ 405 406/** 407 \fn OGRLayerH OGR_DS_GetLayerByName(OGRDataSourceH hDS, 408 const char *pszLayerName ); 409 410 \brief Fetch a layer by name. 411 412 The returned layer remains owned by the 413 OGRDataSource and should not be deleted by the application. 414 415 @deprecated Use GDALDatasetGetLayerByName() in GDAL 2.0 416 417 @param hDS handle to the data source from which to get the layer. 418 @param pszLayerName Layer the layer name of the layer to fetch. 419 420 @return a handle to the layer, or NULL if the layer is not found 421 or an error occurs. 422 423*/ 424 425/** 426 \fn OGRLayerH OGR_DS_CopyLayer( OGRDataSourceH hDS, 427 OGRLayerH hSrcLayer, const char *pszNewName, 428 char **papszOptions ) 429 430 \brief Duplicate an existing layer. 431 432 This function creates a new layer, duplicate the field definitions of the 433 source layer and then duplicate each features of the source layer. 434 The papszOptions argument 435 can be used to control driver specific creation options. These options are 436 normally documented in the format specific documentation. 437 The source layer may come from another dataset. 438 439 @deprecated Use GDALDatasetCopyLayer() in GDAL 2.0 440 441 @param hDS handle to the data source where to create the new layer 442 @param hSrcLayer handle to the source layer. 443 @param pszNewName the name of the layer to create. 444 @param papszOptions a StringList of name=value options. Options are driver 445 specific. 446 447 @return a handle to the layer, or NULL if an error occurs. 448*/ 449 450/** 451 \fn OGRErr OGR_DS_DeleteLayer(OGRDataSourceH hDS, int iLayer); 452 453 \brief Delete the indicated layer from the datasource. 454 455 If this method is supported 456 the ODsCDeleteLayer capability will test TRUE on the OGRDataSource. 457 458 @deprecated Use GDALDatasetDeleteLayer() in GDAL 2.0 459 460 @param hDS handle to the datasource 461 @param iLayer the index of the layer to delete. 462 463 @return OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting 464 layers is not supported for this datasource. 465 466*/ 467 468/** 469 \fn OGRLayerH OGR_DS_ExecuteSQL( OGRDataSourceH hDS, 470 const char *pszStatement, 471 OGRGeometryH hSpatialFilter, 472 const char *pszDialect ); 473 474 \brief Execute an SQL statement against the data store. 475 476 The result of an SQL query is either NULL for statements that are in error, 477 or that have no results set, or an OGRLayer handle representing a results 478 set from the query. Note that this OGRLayer is in addition to the layers 479 in the data store and must be destroyed with 480 OGR_DS_ReleaseResultSet() before the data source is closed 481 (destroyed). 482 483 For more information on the SQL dialect supported internally by OGR 484 review the <a href="https://gdal.org/user/ogr_sql_dialect.html">OGR SQL</a> document. Some drivers (i.e. 485 Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS. 486 487 The <a href="https://gdal.org/user/sql_sqlite_dialect.html">SQLITE dialect</a> 488 can also be used. 489 490 @deprecated Use GDALDatasetExecuteSQL() in GDAL 2.0 491 492 @param hDS handle to the data source on which the SQL query is executed. 493 @param pszStatement the SQL statement to execute. 494 @param hSpatialFilter handle to a geometry which represents a spatial filter. Can be NULL. 495 @param pszDialect allows control of the statement dialect. If set to NULL, the 496OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine, 497unless OGRSQL is explicitly passed as the dialect. The SQLITE dialect 498can also be used. 499 500 @return a handle to a OGRLayer containing the results of the query. 501 Deallocate with OGR_DS_ReleaseResultSet(). 502 503*/ 504 505 506/** 507 \fn void OGR_DS_ReleaseResultSet( OGRDataSourceH hDS, OGRLayerH hLayer ); 508 509 \brief Release results of OGR_DS_ExecuteSQL(). 510 511 This function should only be used to deallocate OGRLayers resulting from 512 an OGR_DS_ExecuteSQL() call on the same OGRDataSource. 513 Failure to deallocate a results set before destroying the OGRDataSource 514 may cause errors. 515 516 @deprecated Use GDALDatasetReleaseResultSet() in GDAL 2.0 517 518 @param hDS a handle to the data source on which was executed an 519 SQL query. 520 @param hLayer handle to the result of a previous OGR_DS_ExecuteSQL() call. 521 522*/ 523 524/** 525 \fn int OGR_DS_TestCapability( OGRDataSourceH hDS, const char *pszCapability ); 526 527 \brief Test if capability is available. 528 529 One of the following data source capability names can be passed into this 530 function, and a TRUE or FALSE value will be returned indicating whether 531 or not the capability is available for this object. 532 533 <ul> 534 <li> <b>ODsCCreateLayer</b>: True if this datasource can create new layers. 535 <li> <b>ODsCDeleteLayer</b>: True if this datasource can delete existing layers.<p> 536 <li> <b>ODsCCreateGeomFieldAfterCreateLayer</b>: True if the layers of this 537 datasource support CreateGeomField() just after layer creation.<p> 538 <li> <b>ODsCCurveGeometries</b>: True if this datasource supports writing curve geometries. (GDAL 2.0). 539 In that case, OLCCurveGeometries must also be declared in layers of that dataset.<p> 540 <p> 541 </ul> 542 543 The \#define macro forms of the capability names should be used in preference 544 to the strings themselves to avoid misspelling. 545 546 @deprecated Use GDALDatasetTestCapability() in GDAL 2.0 547 548 @param hDS handle to the data source against which to test the capability. 549 @param pszCapability the capability to test. 550 551 @return TRUE if capability available otherwise FALSE. 552 553*/ 554 555/** 556 \fn OGRLayerH OGR_DS_CreateLayer( OGRDataSourceH hDS, 557 const char * pszName, 558 OGRSpatialReferenceH hSpatialRef, 559 OGRwkbGeometryType eType, 560 char ** papszOptions ); 561 562\brief This function attempts to create a new layer on the data source with the indicated name, coordinate system, geometry type. 563 564The papszOptions argument 565can be used to control driver specific creation options. These options are 566normally documented in the format specific documentation. 567 568@deprecated Use GDALDatasetCreateLayer() in GDAL 2.0 569 570 @param hDS The dataset handle. 571 @param pszName the name for the new layer. This should ideally not 572match any existing layer on the datasource. 573 @param hSpatialRef handle to the coordinate system to use for the new layer, 574or NULL if no coordinate system is available. The driver might only increase 575the reference counter of the object to take ownership, and not make a full copy, 576so do not use OSRDestroySpatialReference(), but OSRRelease() instead when you 577are done with the object. 578 @param eType the geometry type for the layer. Use wkbUnknown if there 579are no constraints on the types geometry to be written. 580 @param papszOptions a StringList of name=value options. Options are driver 581specific, and driver information can be found at the following url: 582http://www.gdal.org/ogr_formats.html 583 584 @return NULL is returned on failure, or a new OGRLayer handle on success. 585 586<b>Example:</b> 587 588\code 589#include "ogrsf_frmts.h" 590#include "cpl_string.h" 591 592... 593 594 OGRLayerH *hLayer; 595 char **papszOptions; 596 597 if( OGR_DS_TestCapability( hDS, ODsCCreateLayer ) ) 598 { 599 ... 600 } 601 602 papszOptions = CSLSetNameValue( papszOptions, "DIM", "2" ); 603 hLayer = OGR_DS_CreateLayer( hDS, "NewLayer", NULL, wkbUnknown, 604 papszOptions ); 605 CSLDestroy( papszOptions ); 606 607 if( hLayer == NULL ) 608 { 609 ... 610 } 611\endcode 612*/ 613 614/** 615 \fn OGRErr OGRReleaseDataSource( OGRDataSourceH hDS ) 616 617\brief Drop a reference to this datasource, and if the reference count drops to zero close (destroy) the datasource. 618 619Internally this actually calls 620the OGRSFDriverRegistrar::ReleaseDataSource() method. This method is 621essentially a convenient alias. 622 623@deprecated Use GDALClose() in GDAL 2.0 624 625@param hDS handle to the data source to release 626 627@return OGRERR_NONE on success or an error code. 628*/ 629 630/** 631 \fn OGRSFDriverH OGR_DS_GetDriver( OGRDataSourceH hDS ); 632 633\brief Returns the driver that the dataset was opened with. 634 635NOTE: Starting with GDAL 2.0, it is *NOT* safe to cast the returned handle to 636OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*. 637 638@deprecated Use GDALGetDatasetDriver() in GDAL 2.0 639 640@param hDS handle to the datasource 641@return NULL if driver info is not available, or pointer to a driver owned 642by the OGRSFDriverManager. 643*/ 644 645/************************************************************************/ 646/* OGRLayer */ 647/************************************************************************/ 648 649/** 650 \fn const char* OGRLayer::GetName(); 651 652 \brief Return the layer name. 653 654 This returns the same content as GetLayerDefn()->OGRFeatureDefn::GetName(), but for a 655 few drivers, calling GetName() directly can avoid lengthy layer 656 definition initialization. 657 658 This method is the same as the C function OGR_L_GetName(). 659 660 If this method is derived in a driver, it must be done such that it 661 returns the same content as GetLayerDefn()->OGRFeatureDefn::GetName(). 662 663 @return the layer name (must not been freed) 664 @since OGR 1.8.0 665 666*/ 667 668/** 669 \fn const char* OGR_L_GetName( OGRLayerH hLayer ); 670 671 \brief Return the layer name. 672 673 This returns the same content as OGR_FD_GetName(OGR_L_GetLayerDefn(hLayer)), 674 but for a few drivers, calling OGR_L_GetName() directly can avoid lengthy 675 layer definition initialization. 676 677 This function is the same as the C++ method OGRLayer::GetName(). 678 679 @param hLayer handle to the layer. 680 @return the layer name (must not been freed) 681 @since OGR 1.8.0 682*/ 683 684 685/** 686 \fn OGRwkbGeometryType OGRLayer::GetGeomType(); 687 688 \brief Return the layer geometry type. 689 690 This returns the same result as GetLayerDefn()->OGRFeatureDefn::GetGeomType(), but for a 691 few drivers, calling GetGeomType() directly can avoid lengthy layer 692 definition initialization. 693 694 For layers with multiple geometry fields, this method only returns the geometry 695 type of the first geometry column. For other columns, use 696 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(i)->GetType(). 697 For layers without any geometry field, this method returns wkbNone. 698 699 This method is the same as the C function OGR_L_GetGeomType(). 700 701 If this method is derived in a driver, it must be done such that it 702 returns the same content as GetLayerDefn()->OGRFeatureDefn::GetGeomType(). 703 704 @return the geometry type 705 @since OGR 1.8.0 706 707*/ 708 709/** 710 \fn OGRwkbGeometryType OGR_L_GetGeomType( OGRLayerH hLayer ); 711 712 \brief Return the layer geometry type. 713 714 This returns the same result as OGR_FD_GetGeomType(OGR_L_GetLayerDefn(hLayer)), 715 but for a few drivers, calling OGR_L_GetGeomType() directly can avoid lengthy 716 layer definition initialization. 717 718 For layers with multiple geometry fields, this method only returns the geometry 719 type of the first geometry column. For other columns, use 720 OGR_GFld_GetType(OGR_FD_GetGeomFieldDefn(OGR_L_GetLayerDefn(hLayer), i)). 721 For layers without any geometry field, this method returns wkbNone. 722 723 This function is the same as the C++ method OGRLayer::GetGeomType(). 724 725 @param hLayer handle to the layer. 726 @return the geometry type 727 @since OGR 1.8.0 728*/ 729 730 731/** 732 \fn void OGRLayer::ResetReading(); 733 734 \brief Reset feature reading to start on the first feature. 735 736 This affects GetNextFeature(). 737 738 This method is the same as the C function OGR_L_ResetReading(). 739 740*/ 741 742/** 743 \fn void OGR_L_ResetReading( OGRLayerH hLayer ); 744 745 \brief Reset feature reading to start on the first feature. 746 747 This affects GetNextFeature(). 748 749 This function is the same as the C++ method OGRLayer::ResetReading(). 750 751 @param hLayer handle to the layer on which features are read. 752 753*/ 754 755/** 756 \fn OGRFeature *OGRLayer::GetNextFeature(); 757 758 \brief Fetch the next available feature from this layer. 759 760 The returned feature becomes the responsibility of the caller to 761 delete with OGRFeature::DestroyFeature(). It is critical that all 762 features associated with an OGRLayer (more specifically an 763 OGRFeatureDefn) be deleted before that layer/datasource is deleted. 764 765 Only features matching the current spatial filter (set with 766 SetSpatialFilter()) will be returned. 767 768 This method implements sequential access to the features of a layer. The 769 ResetReading() method can be used to start at the beginning again. 770 771 Features returned by GetNextFeature() may or may not be affected by 772 concurrent modifications depending on drivers. A guaranteed way of seeing 773 modifications in effect is to call ResetReading() on layers where 774 GetNextFeature() has been called, before reading again. Structural changes 775 in layers (field addition, deletion, ...) when a read is in progress may or 776 may not be possible depending on drivers. If a transaction is 777 committed/aborted, the current sequential reading may or may not be valid 778 after that operation and a call to ResetReading() might be needed. 779 780 This method is the same as the C function OGR_L_GetNextFeature(). 781 782 @return a feature, or NULL if no more features are available. 783 784*/ 785 786 787/** 788 \fn OGRFeatureH OGR_L_GetNextFeature( OGRLayerH hLayer ); 789 790 \brief Fetch the next available feature from this layer. 791 792 The returned feature becomes the responsibility of the caller to 793 delete with OGR_F_Destroy(). It is critical that all features 794 associated with an OGRLayer (more specifically an OGRFeatureDefn) be 795 deleted before that layer/datasource is deleted. 796 797 Only features matching the current spatial filter (set with 798 SetSpatialFilter()) will be returned. 799 800 This function implements sequential access to the features of a layer. 801 The OGR_L_ResetReading() function can be used to start at the beginning 802 again. 803 804 Features returned by OGR_GetNextFeature() may or may not be affected by 805 concurrent modifications depending on drivers. A guaranteed way of seeing 806 modifications in effect is to call OGR_L_ResetReading() on layers where 807 OGR_GetNextFeature() has been called, before reading again. Structural 808 changes in layers (field addition, deletion, ...) when a read is in progress 809 may or may not be possible depending on drivers. If a transaction is 810 committed/aborted, the current sequential reading may or may not be valid 811 after that operation and a call to OGR_L_ResetReading() might be needed. 812 813 This function is the same as the C++ method OGRLayer::GetNextFeature(). 814 815 @param hLayer handle to the layer from which feature are read. 816 @return a handle to a feature, or NULL if no more features are available. 817 818*/ 819 820/** 821 822 \fn GIntBig OGRLayer::GetFeatureCount( int bForce = TRUE ); 823 824 \brief Fetch the feature count in this layer. 825 826 Returns the number of features in the layer. For dynamic databases the 827 count may not be exact. If bForce is FALSE, and it would be expensive 828 to establish the feature count a value of -1 may be returned indicating 829 that the count isn't know. If bForce is TRUE some implementations will 830 actually scan the entire layer once to count objects. 831 832 The returned count takes the spatial filter into account. 833 834 Note that some implementations of this method may alter the read cursor 835 of the layer. 836 837 This method is the same as the C function OGR_L_GetFeatureCount(). 838 839 Note: since GDAL 2.0, this method returns a GIntBig (previously a int) 840 841 @param bForce Flag indicating whether the count should be computed even 842 if it is expensive. 843 844 @return feature count, -1 if count not known. 845 846*/ 847 848/** 849 \fn GIntBig OGR_L_GetFeatureCount( OGRLayerH hLayer, int bForce ); 850 851 \brief Fetch the feature count in this layer. 852 853 Returns the number of features in the layer. For dynamic databases the 854 count may not be exact. If bForce is FALSE, and it would be expensive 855 to establish the feature count a value of -1 may be returned indicating 856 that the count isn't know. If bForce is TRUE some implementations will 857 actually scan the entire layer once to count objects. 858 859 The returned count takes the spatial filter into account. 860 861 Note that some implementations of this method may alter the read cursor 862 of the layer. 863 864 This function is the same as the CPP OGRLayer::GetFeatureCount(). 865 866 Note: since GDAL 2.0, this method returns a GIntBig (previously a int) 867 868 @param hLayer handle to the layer that owned the features. 869 @param bForce Flag indicating whether the count should be computed even 870 if it is expensive. 871 872 @return feature count, -1 if count not known. 873 874*/ 875 876/** 877 878 \fn OGRErr OGRLayer::GetExtent( OGREnvelope *psExtent, int bForce = TRUE ); 879 880 \brief Fetch the extent of this layer. 881 882 Returns the extent (MBR) of the data in the layer. If bForce is FALSE, 883 and it would be expensive to establish the extent then OGRERR_FAILURE 884 will be returned indicating that the extent isn't know. If bForce is 885 TRUE then some implementations will actually scan the entire layer once 886 to compute the MBR of all the features in the layer. 887 888 Depending on the drivers, the returned extent may or may not take the 889 spatial filter into account. So it is safer to call GetExtent() without 890 setting a spatial filter. 891 892 Layers without any geometry may return OGRERR_FAILURE just indicating that 893 no meaningful extents could be collected. 894 895 Note that some implementations of this method may alter the read cursor 896 of the layer. 897 898 This method is the same as the C function OGR_L_GetExtent(). 899 900 @param psExtent the structure in which the extent value will be returned. 901 @param bForce Flag indicating whether the extent should be computed even 902 if it is expensive. 903 904 @return OGRERR_NONE on success, OGRERR_FAILURE if extent not known. 905 906*/ 907 908 909/** 910 911 \fn OGRErr OGR_L_GetExtent( OGRLayerH hLayer, OGREnvelope *psExtent, int bForce); 912 913 \brief Fetch the extent of this layer. 914 915 Returns the extent (MBR) of the data in the layer. If bForce is FALSE, 916 and it would be expensive to establish the extent then OGRERR_FAILURE 917 will be returned indicating that the extent isn't know. If bForce is 918 TRUE then some implementations will actually scan the entire layer once 919 to compute the MBR of all the features in the layer. 920 921 Depending on the drivers, the returned extent may or may not take the 922 spatial filter into account. So it is safer to call OGR_L_GetExtent() without 923 setting a spatial filter. 924 925 Layers without any geometry may return OGRERR_FAILURE just indicating that 926 no meaningful extents could be collected. 927 928 Note that some implementations of this method may alter the read cursor 929 of the layer. 930 931 This function is the same as the C++ method OGRLayer::GetExtent(). 932 933 @param hLayer handle to the layer from which to get extent. 934 @param psExtent the structure in which the extent value will be returned. 935 @param bForce Flag indicating whether the extent should be computed even 936 if it is expensive. 937 938 @return OGRERR_NONE on success, OGRERR_FAILURE if extent not known. 939 940*/ 941 942/** 943 944 \fn OGRErr OGRLayer::GetExtent( int iGeomField,OGREnvelope *psExtent, int bForce = TRUE ); 945 946 \brief Fetch the extent of this layer, on the specified geometry field. 947 948 Returns the extent (MBR) of the data in the layer. If bForce is FALSE, 949 and it would be expensive to establish the extent then OGRERR_FAILURE 950 will be returned indicating that the extent isn't know. If bForce is 951 TRUE then some implementations will actually scan the entire layer once 952 to compute the MBR of all the features in the layer. 953 954 Depending on the drivers, the returned extent may or may not take the 955 spatial filter into account. So it is safer to call GetExtent() without 956 setting a spatial filter. 957 958 Layers without any geometry may return OGRERR_FAILURE just indicating that 959 no meaningful extents could be collected. 960 961 Note that some implementations of this method may alter the read cursor 962 of the layer. 963 964 Note to driver implementer: if you implement GetExtent(int,OGREnvelope*,int), 965 you must also implement GetExtent(OGREnvelope*, int) to make it call 966 GetExtent(0,OGREnvelope*,int). 967 968 This method is the same as the C function OGR_L_GetExtentEx(). 969 970 @param iGeomField the index of the geometry field on which to compute the extent. 971 @param psExtent the structure in which the extent value will be returned. 972 @param bForce Flag indicating whether the extent should be computed even 973 if it is expensive. 974 975 @return OGRERR_NONE on success, OGRERR_FAILURE if extent not known. 976 977*/ 978 979 980/** 981 982 \fn OGRErr OGR_L_GetExtentEx( OGRLayerH hLayer, int iGeomField, OGREnvelope *psExtent, int bForce); 983 984 \brief Fetch the extent of this layer, on the specified geometry field. 985 986 Returns the extent (MBR) of the data in the layer. If bForce is FALSE, 987 and it would be expensive to establish the extent then OGRERR_FAILURE 988 will be returned indicating that the extent isn't know. If bForce is 989 TRUE then some implementations will actually scan the entire layer once 990 to compute the MBR of all the features in the layer. 991 992 Depending on the drivers, the returned extent may or may not take the 993 spatial filter into account. So it is safer to call OGR_L_GetExtent() without 994 setting a spatial filter. 995 996 Layers without any geometry may return OGRERR_FAILURE just indicating that 997 no meaningful extents could be collected. 998 999 Note that some implementations of this method may alter the read cursor 1000 of the layer. 1001 1002 This function is the same as the C++ method OGRLayer::GetExtent(). 1003 1004 @param hLayer handle to the layer from which to get extent. 1005 @param iGeomField the index of the geometry field on which to compute the extent. 1006 @param psExtent the structure in which the extent value will be returned. 1007 @param bForce Flag indicating whether the extent should be computed even 1008 if it is expensive. 1009 1010 @return OGRERR_NONE on success, OGRERR_FAILURE if extent not known. 1011 1012*/ 1013 1014/** 1015 \fn void OGRLayer::SetSpatialFilter( OGRGeometry * poFilter ); 1016 1017 \brief Set a new spatial filter. 1018 1019 This method set the geometry to be used as a spatial filter when 1020 fetching features via the GetNextFeature() method. Only features that 1021 geometrically intersect the filter geometry will be returned. 1022 1023 Currently this test is may be inaccurately implemented, but it is 1024 guaranteed that all features whose envelope (as returned by 1025 OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter 1026 will be returned. This can result in more shapes being returned that 1027 should strictly be the case. 1028 1029 Starting with GDAL 2.3, features with null or empty geometries will never 1030 be considered as matching a spatial filter. 1031 1032 This method makes an internal copy of the passed geometry. The 1033 passed geometry remains the responsibility of the caller, and may 1034 be safely destroyed. 1035 1036 For the time being the passed filter geometry should be in the same 1037 SRS as the layer (as returned by OGRLayer::GetSpatialRef()). In the 1038 future this may be generalized. 1039 1040 This method is the same as the C function OGR_L_SetSpatialFilter(). 1041 1042 @param poFilter the geometry to use as a filtering region. NULL may 1043 be passed indicating that the current spatial filter should be cleared, 1044 but no new one instituted. 1045 1046 */ 1047 1048/** 1049 \fn void OGR_L_SetSpatialFilter( OGRLayerH hLayer, OGRGeometryH hGeom ); 1050 1051 \brief Set a new spatial filter. 1052 1053 This function set the geometry to be used as a spatial filter when 1054 fetching features via the OGR_L_GetNextFeature() function. Only 1055 features that geometrically intersect the filter geometry will be 1056 returned. 1057 1058 Currently this test is may be inaccurately implemented, but it is 1059 guaranteed that all features whose envelope (as returned by 1060 OGR_G_GetEnvelope()) overlaps the envelope of the spatial filter 1061 will be returned. This can result in more shapes being returned that 1062 should strictly be the case. 1063 1064 Starting with GDAL 2.3, features with null or empty geometries will never 1065 be considered as matching a spatial filter. 1066 1067 This function makes an internal copy of the passed geometry. The 1068 passed geometry remains the responsibility of the caller, and may 1069 be safely destroyed. 1070 1071 For the time being the passed filter geometry should be in the same 1072 SRS as the layer (as returned by OGR_L_GetSpatialRef()). In the 1073 future this may be generalized. 1074 1075 This function is the same as the C++ method OGRLayer::SetSpatialFilter. 1076 1077 @param hLayer handle to the layer on which to set the spatial filter. 1078 @param hGeom handle to the geometry to use as a filtering region. NULL may 1079 be passed indicating that the current spatial filter should be cleared, 1080 but no new one instituted. 1081 1082 */ 1083 1084/** 1085 \fn void OGRLayer::SetSpatialFilterRect( double dfMinX, double dfMinY, 1086 double dfMaxX, double dfMaxY ); 1087 1088 \brief Set a new rectangular spatial filter. 1089 1090 This method set rectangle to be used as a spatial filter when 1091 fetching features via the GetNextFeature() method. Only features that 1092 geometrically intersect the given rectangle will be returned. 1093 1094 The x/y values should be in the same coordinate system as the layer as 1095 a whole (as returned by OGRLayer::GetSpatialRef()). Internally this 1096 method is normally implemented as creating a 5 vertex closed rectangular 1097 polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as 1098 a convenience. 1099 1100 The only way to clear a spatial filter set with this method is to 1101 call OGRLayer::SetSpatialFilter(NULL). 1102 1103 This method is the same as the C function OGR_L_SetSpatialFilterRect(). 1104 1105 @param dfMinX the minimum X coordinate for the rectangular region. 1106 @param dfMinY the minimum Y coordinate for the rectangular region. 1107 @param dfMaxX the maximum X coordinate for the rectangular region. 1108 @param dfMaxY the maximum Y coordinate for the rectangular region. 1109 1110 */ 1111 1112/** 1113 \fn void OGR_L_SetSpatialFilterRect( OGRLayerH hLayer, 1114 double dfMinX, double dfMinY, 1115 double dfMaxX, double dfMaxY ); 1116 1117 \brief Set a new rectangular spatial filter. 1118 1119 This method set rectangle to be used as a spatial filter when 1120 fetching features via the OGR_L_GetNextFeature() method. Only features that 1121 geometrically intersect the given rectangle will be returned. 1122 1123 The x/y values should be in the same coordinate system as the layer as 1124 a whole (as returned by OGRLayer::GetSpatialRef()). Internally this 1125 method is normally implemented as creating a 5 vertex closed rectangular 1126 polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as 1127 a convenience. 1128 1129 The only way to clear a spatial filter set with this method is to 1130 call OGRLayer::SetSpatialFilter(NULL). 1131 1132 This method is the same as the C++ method OGRLayer::SetSpatialFilterRect(). 1133 1134 @param hLayer handle to the layer on which to set the spatial filter. 1135 @param dfMinX the minimum X coordinate for the rectangular region. 1136 @param dfMinY the minimum Y coordinate for the rectangular region. 1137 @param dfMaxX the maximum X coordinate for the rectangular region. 1138 @param dfMaxY the maximum Y coordinate for the rectangular region. 1139 1140 */ 1141 1142 1143/** 1144 \fn void OGRLayer::SetSpatialFilter( int iGeomField, OGRGeometry * poFilter ); 1145 1146 \brief Set a new spatial filter. 1147 1148 This method set the geometry to be used as a spatial filter when 1149 fetching features via the GetNextFeature() method. Only features that 1150 geometrically intersect the filter geometry will be returned. 1151 1152 Currently this test is may be inaccurately implemented, but it is 1153 guaranteed that all features who's envelope (as returned by 1154 OGRGeometry::getEnvelope()) overlaps the envelope of the spatial filter 1155 will be returned. This can result in more shapes being returned that 1156 should strictly be the case. 1157 1158 This method makes an internal copy of the passed geometry. The 1159 passed geometry remains the responsibility of the caller, and may 1160 be safely destroyed. 1161 1162 For the time being the passed filter geometry should be in the same 1163 SRS as the geometry field definition it corresponds to (as returned by 1164 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). In the 1165 future this may be generalized. 1166 1167 Note that only the last spatial filter set is applied, even if several 1168 successive calls are done with different iGeomField values. 1169 1170 Note to driver implementer: if you implement SetSpatialFilter(int,OGRGeometry*), 1171 you must also implement SetSpatialFilter(OGRGeometry*) to make it call 1172 SetSpatialFilter(0,OGRGeometry*). 1173 1174 This method is the same as the C function OGR_L_SetSpatialFilterEx(). 1175 1176 @param iGeomField index of the geometry field on which the spatial filter 1177 operates. 1178 @param poFilter the geometry to use as a filtering region. NULL may 1179 be passed indicating that the current spatial filter should be cleared, 1180 but no new one instituted. 1181 1182 @since GDAL 1.11 1183 1184 */ 1185 1186/** 1187 \fn void OGR_L_SetSpatialFilterEx( OGRLayerH hLayer, int iGeomField, OGRGeometryH hGeom ); 1188 1189 \brief Set a new spatial filter. 1190 1191 This function set the geometry to be used as a spatial filter when 1192 fetching features via the OGR_L_GetNextFeature() function. Only 1193 features that geometrically intersect the filter geometry will be 1194 returned. 1195 1196 Currently this test is may be inaccurately implemented, but it is 1197 guaranteed that all features who's envelope (as returned by 1198 OGR_G_GetEnvelope()) overlaps the envelope of the spatial filter 1199 will be returned. This can result in more shapes being returned that 1200 should strictly be the case. 1201 1202 This function makes an internal copy of the passed geometry. The 1203 passed geometry remains the responsibility of the caller, and may 1204 be safely destroyed. 1205 1206 For the time being the passed filter geometry should be in the same 1207 SRS as the geometry field definition it corresponds to (as returned by 1208 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). In the 1209 future this may be generalized. 1210 1211 Note that only the last spatial filter set is applied, even if several 1212 successive calls are done with different iGeomField values. 1213 1214 This function is the same as the C++ method OGRLayer::SetSpatialFilter. 1215 1216 @param hLayer handle to the layer on which to set the spatial filter. 1217 @param iGeomField index of the geometry field on which the spatial filter 1218 operates. 1219 @param hGeom handle to the geometry to use as a filtering region. NULL may 1220 be passed indicating that the current spatial filter should be cleared, 1221 but no new one instituted. 1222 1223 @since GDAL 1.11 1224 1225 */ 1226 1227/** 1228 \fn void OGRLayer::SetSpatialFilterRect( int iGeomField, 1229 double dfMinX, double dfMinY, 1230 double dfMaxX, double dfMaxY ); 1231 1232 \brief Set a new rectangular spatial filter. 1233 1234 This method set rectangle to be used as a spatial filter when 1235 fetching features via the GetNextFeature() method. Only features that 1236 geometrically intersect the given rectangle will be returned. 1237 1238 The x/y values should be in the same coordinate system as as the geometry 1239 field definition it corresponds to (as returned by 1240 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). Internally this 1241 method is normally implemented as creating a 5 vertex closed rectangular 1242 polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as 1243 a convenience. 1244 1245 The only way to clear a spatial filter set with this method is to 1246 call OGRLayer::SetSpatialFilter(NULL). 1247 1248 This method is the same as the C function OGR_L_SetSpatialFilterRectEx(). 1249 1250 @param iGeomField index of the geometry field on which the spatial filter 1251 operates. 1252 @param dfMinX the minimum X coordinate for the rectangular region. 1253 @param dfMinY the minimum Y coordinate for the rectangular region. 1254 @param dfMaxX the maximum X coordinate for the rectangular region. 1255 @param dfMaxY the maximum Y coordinate for the rectangular region. 1256 1257 @since GDAL 1.11 1258 */ 1259 1260/** 1261 \fn void OGR_L_SetSpatialFilterRectEx( OGRLayerH hLayer, 1262 int iGeomField, 1263 double dfMinX, double dfMinY, 1264 double dfMaxX, double dfMaxY ); 1265 1266 \brief Set a new rectangular spatial filter. 1267 1268 This method set rectangle to be used as a spatial filter when 1269 fetching features via the OGR_L_GetNextFeature() method. Only features that 1270 geometrically intersect the given rectangle will be returned. 1271 1272 The x/y values should be in the same coordinate system as as the geometry 1273 field definition it corresponds to (as returned by 1274 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(iGeomField)->GetSpatialRef()). Internally this 1275 method is normally implemented as creating a 5 vertex closed rectangular 1276 polygon and passing it to OGRLayer::SetSpatialFilter(). It exists as 1277 a convenience. 1278 1279 The only way to clear a spatial filter set with this method is to 1280 call OGRLayer::SetSpatialFilter(NULL). 1281 1282 This method is the same as the C++ method OGRLayer::SetSpatialFilterRect(). 1283 1284 @param hLayer handle to the layer on which to set the spatial filter. 1285 @param iGeomField index of the geometry field on which the spatial filter 1286 operates. 1287 @param dfMinX the minimum X coordinate for the rectangular region. 1288 @param dfMinY the minimum Y coordinate for the rectangular region. 1289 @param dfMaxX the maximum X coordinate for the rectangular region. 1290 @param dfMaxY the maximum Y coordinate for the rectangular region. 1291 1292 @since GDAL 1.11 1293 */ 1294 1295 1296/** 1297 \fn OGRGeometry *OGRLayer::GetSpatialFilter(); 1298 1299 \brief This method returns the current spatial filter for this layer. 1300 1301 The returned pointer is to an internally owned object, and should not 1302 be altered or deleted by the caller. 1303 1304 This method is the same as the C function OGR_L_GetSpatialFilter(). 1305 1306 @return spatial filter geometry. 1307 1308 */ 1309 1310 1311/** 1312 \fn OGRGeometryH OGR_L_GetSpatialFilter( OGRLayerH hLayer ); 1313 1314 \brief This function returns the current spatial filter for this layer. 1315 1316 The returned pointer is to an internally owned object, and should not 1317 be altered or deleted by the caller. 1318 1319 This function is the same as the C++ method OGRLayer::GetSpatialFilter(). 1320 1321 @param hLayer handle to the layer to get the spatial filter from. 1322 @return a handle to the spatial filter geometry. 1323 1324 */ 1325 1326/** 1327 \fn void OGRLayer::SetAttributeFilter( const char *pszQuery ); 1328 1329 \brief Set a new attribute query. 1330 1331 This method sets the attribute query string to be used when 1332 fetching features via the GetNextFeature() method. Only features for which 1333 the query evaluates as true will be returned. 1334 1335 The query string should be in the format of an SQL WHERE clause. For 1336 instance "population > 1000000 and population < 5000000" where population 1337 is an attribute in the layer. The query format is normally a restricted 1338 form of SQL WHERE clause as described in the "WHERE" section of the 1339 <a href="https://gdal.org/user/ogr_sql_dialect.html">OGR SQL</a> tutorial. In some cases (RDBMS 1340 backed drivers) the native capabilities of the database may be used to 1341 interpret the WHERE clause in which case the capabilities will be broader 1342 than those of OGR SQL. 1343 1344 Note that installing a query string will generally result in resetting 1345 the current reading position (ala ResetReading()). 1346 1347 This method is the same as the C function OGR_L_SetAttributeFilter(). 1348 1349 @param pszQuery query in restricted SQL WHERE format, or NULL to clear the 1350 current query. 1351 1352 @return OGRERR_NONE if successfully installed, or an error code if the 1353 query expression is in error, or some other failure occurs. 1354 1355 */ 1356 1357/** 1358 \fn OGRErr OGR_L_SetAttributeFilter(OGRLayerH hLayer, const char *pszQuery); 1359 1360 \brief Set a new attribute query. 1361 1362 This function sets the attribute query string to be used when 1363 fetching features via the OGR_L_GetNextFeature() function. 1364 Only features for which the query evaluates as true will be returned. 1365 1366 The query string should be in the format of an SQL WHERE clause. For 1367 instance "population > 1000000 and population < 5000000" where population 1368 is an attribute in the layer. The query format is a restricted form of SQL 1369 WHERE clause as defined "eq_format=restricted_where" about half way through 1370 this document: 1371 1372 http://ogdi.sourceforge.net/prop/6.2.CapabilitiesMetadata.html 1373 1374 Note that installing a query string will generally result in resetting 1375 the current reading position (ala OGR_L_ResetReading()). 1376 1377 This function is the same as the C++ method OGRLayer::SetAttributeFilter(). 1378 1379 @param hLayer handle to the layer on which attribute query will be executed. 1380 @param pszQuery query in restricted SQL WHERE format, or NULL to clear the 1381 current query. 1382 1383 @return OGRERR_NONE if successfully installed, or an error code if the 1384 query expression is in error, or some other failure occurs. 1385 1386 */ 1387 1388/** 1389 \fn OGRFeatureDefn *OGRLayer::GetLayerDefn(); 1390 1391 \brief Fetch the schema information for this layer. 1392 1393 The returned OGRFeatureDefn is owned by the OGRLayer, and should not be 1394 modified or freed by the application. It encapsulates the attribute schema 1395 of the features of the layer. 1396 1397 This method is the same as the C function OGR_L_GetLayerDefn(). 1398 1399 @return feature definition. 1400 1401*/ 1402 1403/** 1404 \fn OGRFeatureDefnH OGR_L_GetLayerDefn( OGRLayerH hLayer ); 1405 1406 \brief Fetch the schema information for this layer. 1407 1408 The returned handle to the OGRFeatureDefn is owned by the OGRLayer, 1409 and should not be modified or freed by the application. It encapsulates 1410 the attribute schema of the features of the layer. 1411 1412 This function is the same as the C++ method OGRLayer::GetLayerDefn(). 1413 1414 @param hLayer handle to the layer to get the schema information. 1415 @return a handle to the feature definition. 1416 1417*/ 1418 1419/** 1420 1421 \fn int OGR_L_FindFieldIndex( OGRLayerH hLayer, const char *, int bExactMatch ); 1422 1423 \brief Find the index of field in a layer. 1424 1425 The returned number is the index of the field in the layers, or -1 if the 1426 field doesn't exist. 1427 1428 If bExactMatch is set to FALSE and the field doesn't exists in the given form 1429 the driver might apply some changes to make it match, like those it might do 1430 if the layer was created (eg. like LAUNDER in the OCI driver). 1431 1432 This method is the same as the C++ method OGRLayer::FindFieldIndex(). 1433 1434 @return field index, or -1 if the field doesn't exist 1435 1436*/ 1437 1438/** 1439 1440 \fn int OGRLayer::FindFieldIndex( const char *, int bExactMatch ); 1441 1442 \brief Find the index of field in the layer. 1443 1444 The returned number is the index of the field in the layers, or -1 if the 1445 field doesn't exist. 1446 1447 If bExactMatch is set to FALSE and the field doesn't exists in the given form 1448 the driver might apply some changes to make it match, like those it might do 1449 if the layer was created (eg. like LAUNDER in the OCI driver). 1450 1451 This method is the same as the C function OGR_L_FindFieldIndex(). 1452 1453 @return field index, or -1 if the field doesn't exist 1454 1455*/ 1456 1457/** 1458 1459 \fn OGRSpatialReference *OGRLayer::GetSpatialRef(); 1460 1461 \brief Fetch the spatial reference system for this layer. 1462 1463 The returned object is owned by the OGRLayer and should not be modified 1464 or freed by the application. 1465 1466 Starting with OGR 1.11, several geometry fields can be associated to a 1467 feature definition. Each geometry field can have its own spatial reference 1468 system, which is returned by OGRGeomFieldDefn::GetSpatialRef(). 1469 OGRLayer::GetSpatialRef() is equivalent to 1470 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(0)->GetSpatialRef() 1471 1472 This method is the same as the C function OGR_L_GetSpatialRef(). 1473 1474 @return spatial reference, or NULL if there isn't one. 1475 1476*/ 1477 1478 1479/** 1480 1481 \fn OGRSpatialReferenceH OGR_L_GetSpatialRef( OGRLayerH hLayer ); 1482 1483 \brief Fetch the spatial reference system for this layer. 1484 1485 The returned object is owned by the OGRLayer and should not be modified 1486 or freed by the application. 1487 1488 This function is the same as the C++ method OGRLayer::GetSpatialRef(). 1489 1490 @param hLayer handle to the layer to get the spatial reference from. 1491 @return spatial reference, or NULL if there isn't one. 1492 1493*/ 1494 1495/** 1496 1497 \fn OGRFeature *OGRLayer::GetFeature( GIntBig nFID ); 1498 1499 \brief Fetch a feature by its identifier. 1500 1501 This function will attempt to read the identified feature. The nFID 1502 value cannot be OGRNullFID. Success or failure of this operation is 1503 unaffected by the spatial or attribute filters (and specialized implementations 1504 in drivers should make sure that they do not take into account spatial or 1505 attribute filters). 1506 1507 If this method returns a non-NULL feature, it is guaranteed that its 1508 feature id (OGRFeature::GetFID()) will be the same as nFID. 1509 1510 Use OGRLayer::TestCapability(OLCRandomRead) to establish if this layer 1511 supports efficient random access reading via GetFeature(); however, the 1512 call should always work if the feature exists as a fallback implementation 1513 just scans all the features in the layer looking for the desired feature. 1514 1515 Sequential reads (with GetNextFeature()) are generally considered interrupted 1516 by a GetFeature() call. 1517 1518 The returned feature should be free with OGRFeature::DestroyFeature(). 1519 1520 This method is the same as the C function OGR_L_GetFeature(). 1521 1522 @param nFID the feature id of the feature to read. 1523 1524 @return a feature now owned by the caller, or NULL on failure. 1525 1526*/ 1527 1528 1529/** 1530 1531 \fn OGRFeatureH OGR_L_GetFeature( OGRLayerH hLayer, GIntBig nFeatureId ); 1532 1533 \brief Fetch a feature by its identifier. 1534 1535 This function will attempt to read the identified feature. The nFID 1536 value cannot be OGRNullFID. Success or failure of this operation is 1537 unaffected by the spatial or attribute filters (and specialized implementations 1538 in drivers should make sure that they do not take into account spatial or 1539 attribute filters). 1540 1541 If this function returns a non-NULL feature, it is guaranteed that its 1542 feature id (OGR_F_GetFID()) will be the same as nFID. 1543 1544 Use OGR_L_TestCapability(OLCRandomRead) to establish if this layer 1545 supports efficient random access reading via OGR_L_GetFeature(); however, 1546 the call should always work if the feature exists as a fallback 1547 implementation just scans all the features in the layer looking for the 1548 desired feature. 1549 1550 Sequential reads (with OGR_L_GetNextFeature()) are generally considered interrupted by a 1551 OGR_L_GetFeature() call. 1552 1553 The returned feature should be free with OGR_F_Destroy(). 1554 1555 This function is the same as the C++ method OGRLayer::GetFeature( ). 1556 1557 @param hLayer handle to the layer that owned the feature. 1558 @param nFeatureId the feature id of the feature to read. 1559 1560 @return a handle to a feature now owned by the caller, or NULL on failure. 1561 1562*/ 1563 1564/** 1565 1566 \fn OGRErr OGRLayer::SetFeature( OGRFeature * poFeature ); 1567 1568 \brief Rewrite an existing feature. 1569 1570 This method will write a feature to the layer, based on the feature id 1571 within the OGRFeature. 1572 1573 Use OGRLayer::TestCapability(OLCRandomWrite) to establish if this layer 1574 supports random access writing via SetFeature(). 1575 1576 Starting with GDAL 2.0, drivers should specialize the ISetFeature() method, 1577 since SetFeature() is no longer virtual. 1578 1579 This method is the same as the C function OGR_L_SetFeature(). 1580 1581 @param poFeature the feature to write. 1582 1583 @return OGRERR_NONE if the operation works, otherwise an appropriate error 1584 code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist). 1585 1586*/ 1587 1588/** 1589 1590 \fn OGRErr OGRLayer::ISetFeature( OGRFeature * poFeature ); 1591 1592 \brief Rewrite an existing feature. 1593 1594 This method is implemented by drivers and not called directly. User code should 1595 use SetFeature() instead. 1596 1597 This method will write a feature to the layer, based on the feature id 1598 within the OGRFeature. 1599 1600 @param poFeature the feature to write. 1601 1602 @return OGRERR_NONE if the operation works, otherwise an appropriate error 1603 code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist). 1604 @since GDAL 2.0 1605 1606*/ 1607 1608/** 1609 1610 \fn OGRErr OGR_L_SetFeature( OGRLayerH hLayer, OGRFeatureH hFeat ); 1611 1612 \brief Rewrite an existing feature. 1613 1614 This function will write a feature to the layer, based on the feature id 1615 within the OGRFeature. 1616 1617 Use OGR_L_TestCapability(OLCRandomWrite) to establish if this layer 1618 supports random access writing via OGR_L_SetFeature(). 1619 1620 This function is the same as the C++ method OGRLayer::SetFeature(). 1621 1622 @param hLayer handle to the layer to write the feature. 1623 @param hFeat the feature to write. 1624 1625 @return OGRERR_NONE if the operation works, otherwise an appropriate error 1626 code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist). 1627 1628*/ 1629 1630/** 1631 1632 \fn OGRErr OGRLayer::CreateFeature( OGRFeature * poFeature ); 1633 1634 \brief Create and write a new feature within a layer. 1635 1636 The passed feature is written to the layer as a new feature, rather than 1637 overwriting an existing one. If the feature has a feature id other than 1638 OGRNullFID, then the native implementation may use that as the feature id 1639 of the new feature, but not necessarily. Upon successful return the 1640 passed feature will have been updated with the new feature id. 1641 1642 Starting with GDAL 2.0, drivers should specialize the ICreateFeature() method, 1643 since CreateFeature() is no longer virtual. 1644 1645 This method is the same as the C function OGR_L_CreateFeature(). 1646 1647 @param poFeature the feature to write to disk. 1648 1649 @return OGRERR_NONE on success. 1650 1651*/ 1652 1653/** 1654 1655 \fn OGRErr OGRLayer::ICreateFeature( OGRFeature * poFeature ); 1656 1657 \brief Create and write a new feature within a layer. 1658 1659 This method is implemented by drivers and not called directly. User code should 1660 use CreateFeature() instead. 1661 1662 The passed feature is written to the layer as a new feature, rather than 1663 overwriting an existing one. If the feature has a feature id other than 1664 OGRNullFID, then the native implementation may use that as the feature id 1665 of the new feature, but not necessarily. Upon successful return the 1666 passed feature will have been updated with the new feature id. 1667 1668 @param poFeature the feature to write to disk. 1669 1670 @return OGRERR_NONE on success. 1671 @since GDAL 2.0 1672 1673*/ 1674 1675/** 1676 1677 \fn OGRErr OGR_L_CreateFeature( OGRLayerH hLayer, OGRFeatureH hFeat ); 1678 1679 \brief Create and write a new feature within a layer. 1680 1681 The passed feature is written to the layer as a new feature, rather than 1682 overwriting an existing one. If the feature has a feature id other than 1683 OGRNullFID, then the native implementation may use that as the feature id 1684 of the new feature, but not necessarily. Upon successful return the 1685 passed feature will have been updated with the new feature id. 1686 1687 This function is the same as the C++ method OGRLayer::CreateFeature(). 1688 1689 @param hLayer handle to the layer to write the feature to. 1690 @param hFeat the handle of the feature to write to disk. 1691 1692 @return OGRERR_NONE on success. 1693 1694*/ 1695 1696/** 1697 1698 \fn OGRErr OGRLayer::DeleteFeature( GIntBig nFID ); 1699 1700 \brief Delete feature from layer. 1701 1702 The feature with the indicated feature id is deleted from the layer if 1703 supported by the driver. Most drivers do not support feature deletion, 1704 and will return OGRERR_UNSUPPORTED_OPERATION. The TestCapability() 1705 layer method may be called with OLCDeleteFeature to check if the driver 1706 supports feature deletion. 1707 1708 This method is the same as the C function OGR_L_DeleteFeature(). 1709 1710 @param nFID the feature id to be deleted from the layer 1711 1712 @return OGRERR_NONE if the operation works, otherwise an appropriate error 1713 code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist). 1714 1715*/ 1716 1717/** 1718 1719 \fn OGRErr OGR_L_DeleteFeature( OGRLayerH hLayer, GIntBig nFID ); 1720 1721 \brief Delete feature from layer. 1722 1723 The feature with the indicated feature id is deleted from the layer if 1724 supported by the driver. Most drivers do not support feature deletion, 1725 and will return OGRERR_UNSUPPORTED_OPERATION. The OGR_L_TestCapability() 1726 function may be called with OLCDeleteFeature to check if the driver 1727 supports feature deletion. 1728 1729 This method is the same as the C++ method OGRLayer::DeleteFeature(). 1730 1731 @param hLayer handle to the layer 1732 @param nFID the feature id to be deleted from the layer 1733 1734 @return OGRERR_NONE if the operation works, otherwise an appropriate error 1735 code (e.g OGRERR_NON_EXISTING_FEATURE if the feature does not exist). 1736 1737*/ 1738 1739 1740/** 1741 1742 \fn int OGRLayer::TestCapability( const char * pszCap ); 1743 1744 \brief Test if this layer supported the named capability. 1745 1746 The capability codes that can be tested are represented as strings, but 1747 \#defined constants exists to ensure correct spelling. Specific layer 1748 types may implement class specific capabilities, but this can't generally 1749 be discovered by the caller. <p> 1750 1751<ul> 1752 1753 <li> <b>OLCRandomRead</b> / "RandomRead": TRUE if the GetFeature() method 1754is implemented in an optimized way for this layer, as opposed to the default 1755implementation using ResetReading() and GetNextFeature() to find the requested 1756feature id.<p> 1757 1758 <li> <b>OLCSequentialWrite</b> / "SequentialWrite": TRUE if the 1759CreateFeature() method works for this layer. Note this means that this 1760particular layer is writable. The same OGRLayer class may returned FALSE 1761for other layer instances that are effectively read-only.<p> 1762 1763 <li> <b>OLCRandomWrite</b> / "RandomWrite": TRUE if the SetFeature() method 1764is operational on this layer. Note this means that this 1765particular layer is writable. The same OGRLayer class may returned FALSE 1766for other layer instances that are effectively read-only.<p> 1767 1768 <li> <b>OLCFastSpatialFilter</b> / "FastSpatialFilter": TRUE if this layer 1769implements spatial filtering efficiently. Layers that effectively read all 1770features, and test them with the OGRFeature intersection methods should 1771return FALSE. This can be used as a clue by the application whether it 1772should build and maintain its own spatial index for features in this layer.<p> 1773 1774 <li> <b>OLCFastFeatureCount</b> / "FastFeatureCount": 1775TRUE if this layer can return a feature 1776count (via GetFeatureCount()) efficiently. i.e. without counting 1777the features. In some cases this will return TRUE until a spatial filter is 1778installed after which it will return FALSE.<p> 1779 1780 <li> <b>OLCFastGetExtent</b> / "FastGetExtent": 1781TRUE if this layer can return its data extent (via GetExtent()) 1782efficiently, i.e. without scanning all the features. In some cases this 1783will return TRUE until a spatial filter is installed after which it will 1784return FALSE.<p> 1785 1786 <li> <b>OLCFastSetNextByIndex</b> / "FastSetNextByIndex": 1787TRUE if this layer can perform the SetNextByIndex() call efficiently, otherwise 1788FALSE.<p> 1789 1790 <li> <b>OLCCreateField</b> / "CreateField": TRUE if this layer can create 1791new fields on the current layer using CreateField(), otherwise FALSE.<p> 1792 1793 <li> <b>OLCCreateGeomField</b> / "CreateGeomField": (GDAL >= 1.11) TRUE if this layer can create 1794new geometry fields on the current layer using CreateGeomField(), otherwise FALSE.<p> 1795 1796 <li> <b>OLCDeleteField</b> / "DeleteField": TRUE if this layer can delete 1797existing fields on the current layer using DeleteField(), otherwise FALSE.<p> 1798 1799 <li> <b>OLCReorderFields</b> / "ReorderFields": TRUE if this layer can reorder 1800existing fields on the current layer using ReorderField() or ReorderFields(), otherwise FALSE.<p> 1801 1802 <li> <b>OLCAlterFieldDefn</b> / "AlterFieldDefn": TRUE if this layer can alter 1803the definition of an existing field on the current layer using AlterFieldDefn(), otherwise FALSE.<p> 1804 1805 <li> <b>OLCDeleteFeature</b> / "DeleteFeature": TRUE if the DeleteFeature() 1806method is supported on this layer, otherwise FALSE.<p> 1807 1808 <li> <b>OLCStringsAsUTF8</b> / "StringsAsUTF8": TRUE if values of OFTString 1809fields are assured to be in UTF-8 format. If FALSE the encoding of fields 1810is uncertain, though it might still be UTF-8.<p> 1811 1812<li> <b>OLCTransactions</b> / "Transactions": TRUE if the StartTransaction(), 1813CommitTransaction() and RollbackTransaction() methods work in a meaningful way, 1814otherwise FALSE.<p> 1815 1816<li> <b>OLCIgnoreFields</b> / "IgnoreFields": TRUE if fields, geometry and style 1817will be omitted when fetching features as set by SetIgnoredFields() method. 1818 1819<li> <b>OLCCurveGeometries</b> / "CurveGeometries": TRUE if this layer supports 1820writing curve geometries or may return such geometries. (GDAL 2.0). 1821 1822<p> 1823 1824</ul> 1825 1826 This method is the same as the C function OGR_L_TestCapability(). 1827 1828 @param pszCap the name of the capability to test. 1829 1830 @return TRUE if the layer has the requested capability, or FALSE otherwise. 1831OGRLayers will return FALSE for any unrecognized capabilities.<p> 1832 1833*/ 1834 1835 1836/** 1837 1838 \fn int OGR_L_TestCapability( OGRLayerH hLayer, const char *pszCap ); 1839 1840 \brief Test if this layer supported the named capability. 1841 1842 The capability codes that can be tested are represented as strings, but 1843 \#defined constants exists to ensure correct spelling. Specific layer 1844 types may implement class specific capabilities, but this can't generally 1845 be discovered by the caller. <p> 1846 1847<ul> 1848 1849 <li> <b>OLCRandomRead</b> / "RandomRead": TRUE if the GetFeature() method 1850is implemented in an optimized way for this layer, as opposed to the default 1851implementation using ResetReading() and GetNextFeature() to find the requested 1852feature id.<p> 1853 1854 <li> <b>OLCSequentialWrite</b> / "SequentialWrite": TRUE if the 1855CreateFeature() method works for this layer. Note this means that this 1856particular layer is writable. The same OGRLayer class may returned FALSE 1857for other layer instances that are effectively read-only.<p> 1858 1859 <li> <b>OLCRandomWrite</b> / "RandomWrite": TRUE if the SetFeature() method 1860is operational on this layer. Note this means that this 1861particular layer is writable. The same OGRLayer class may returned FALSE 1862for other layer instances that are effectively read-only.<p> 1863 1864 <li> <b>OLCFastSpatialFilter</b> / "FastSpatialFilter": TRUE if this layer 1865implements spatial filtering efficiently. Layers that effectively read all 1866features, and test them with the OGRFeature intersection methods should 1867return FALSE. This can be used as a clue by the application whether it 1868should build and maintain its own spatial index for features in this 1869layer.<p> 1870 1871 <li> <b>OLCFastFeatureCount</b> / "FastFeatureCount": 1872TRUE if this layer can return a feature 1873count (via OGR_L_GetFeatureCount()) efficiently, i.e. without counting 1874the features. In some cases this will return TRUE until a spatial filter is 1875installed after which it will return FALSE.<p> 1876 1877 <li> <b>OLCFastGetExtent</b> / "FastGetExtent": 1878TRUE if this layer can return its data extent (via OGR_L_GetExtent()) 1879efficiently, i.e. without scanning all the features. In some cases this 1880will return TRUE until a spatial filter is installed after which it will 1881return FALSE.<p> 1882 1883 <li> <b>OLCFastSetNextByIndex</b> / "FastSetNextByIndex": 1884TRUE if this layer can perform the SetNextByIndex() call efficiently, otherwise 1885FALSE.<p> 1886 1887 <li> <b>OLCCreateField</b> / "CreateField": TRUE if this layer can create 1888new fields on the current layer using CreateField(), otherwise FALSE.<p> 1889 1890 <li> <b>OLCCreateGeomField</b> / "CreateGeomField": (GDAL >= 1.11) TRUE if this layer can create 1891new geometry fields on the current layer using CreateGeomField(), otherwise FALSE.<p> 1892 1893 <li> <b>OLCDeleteField</b> / "DeleteField": TRUE if this layer can delete 1894existing fields on the current layer using DeleteField(), otherwise FALSE.<p> 1895 1896 <li> <b>OLCReorderFields</b> / "ReorderFields": TRUE if this layer can reorder 1897existing fields on the current layer using ReorderField() or ReorderFields(), otherwise FALSE.<p> 1898 1899 <li> <b>OLCAlterFieldDefn</b> / "AlterFieldDefn": TRUE if this layer can alter 1900the definition of an existing field on the current layer using AlterFieldDefn(), otherwise FALSE.<p> 1901 1902 <li> <b>OLCDeleteFeature</b> / "DeleteFeature": TRUE if the DeleteFeature() 1903method is supported on this layer, otherwise FALSE.<p> 1904 1905 <li> <b>OLCStringsAsUTF8</b> / "StringsAsUTF8": TRUE if values of OFTString 1906fields are assured to be in UTF-8 format. If FALSE the encoding of fields 1907is uncertain, though it might still be UTF-8.<p> 1908 1909<li> <b>OLCTransactions</b> / "Transactions": TRUE if the StartTransaction(), 1910CommitTransaction() and RollbackTransaction() methods work in a meaningful way, 1911otherwise FALSE.<p> 1912 1913<li> <b>OLCCurveGeometries</b> / "CurveGeometries": TRUE if this layer supports 1914writing curve geometries or may return such geometries. (GDAL 2.0). 1915 1916<p> 1917 1918</ul> 1919 1920 This function is the same as the C++ method OGRLayer::TestCapability(). 1921 1922 @param hLayer handle to the layer to get the capability from. 1923 @param pszCap the name of the capability to test. 1924 1925 @return TRUE if the layer has the requested capability, or FALSE otherwise. 1926OGRLayers will return FALSE for any unrecognized capabilities.<p> 1927 1928*/ 1929 1930/** 1931 \fn OGRErr OGRLayer::SyncToDisk(); 1932 1933\brief Flush pending changes to disk. 1934 1935This call is intended to force the layer to flush any pending writes to 1936disk, and leave the disk file in a consistent state. It would not normally 1937have any effect on read-only datasources. 1938 1939Some layers do not implement this method, and will still return 1940OGRERR_NONE. The default implementation just returns OGRERR_NONE. An error 1941is only returned if an error occurs while attempting to flush to disk. 1942 1943In any event, you should always close any opened datasource with 1944OGRDataSource::DestroyDataSource() that will ensure all data is correctly flushed. 1945 1946This method is the same as the C function OGR_L_SyncToDisk(). 1947 1948@return OGRERR_NONE if no error occurs (even if nothing is done) or an 1949error code. 1950*/ 1951 1952/** 1953 \fn OGRErr OGR_L_SyncToDisk(OGRLayerH hLayer); 1954 1955\brief Flush pending changes to disk. 1956 1957This call is intended to force the layer to flush any pending writes to 1958disk, and leave the disk file in a consistent state. It would not normally 1959have any effect on read-only datasources. 1960 1961Some layers do not implement this method, and will still return 1962OGRERR_NONE. The default implementation just returns OGRERR_NONE. An error 1963is only returned if an error occurs while attempting to flush to disk. 1964 1965In any event, you should always close any opened datasource with 1966OGR_DS_Destroy() that will ensure all data is correctly flushed. 1967 1968This method is the same as the C++ method OGRLayer::SyncToDisk() 1969 1970@param hLayer handle to the layer 1971 1972@return OGRERR_NONE if no error occurs (even if nothing is done) or an 1973error code. 1974*/ 1975 1976/** 1977 \fn OGRErr OGRLayer::SetNextByIndex( GIntBig nIndex ); 1978 1979 \brief Move read cursor to the nIndex'th feature in the current resultset. 1980 1981 This method allows positioning of a layer such that the GetNextFeature() 1982 call will read the requested feature, where nIndex is an absolute index 1983 into the current result set. So, setting it to 3 would mean the next 1984 feature read with GetNextFeature() would have been the 4th feature to have 1985 been read if sequential reading took place from the beginning of the layer, 1986 including accounting for spatial and attribute filters. 1987 1988 Only in rare circumstances is SetNextByIndex() efficiently implemented. 1989 In all other cases the default implementation which calls ResetReading() 1990 and then calls GetNextFeature() nIndex times is used. To determine if 1991 fast seeking is available on the current layer use the TestCapability() 1992 method with a value of OLCFastSetNextByIndex. 1993 1994 This method is the same as the C function OGR_L_SetNextByIndex(). 1995 1996 @param nIndex the index indicating how many steps into the result set 1997 to seek. 1998 1999 @return OGRERR_NONE on success or an error code. 2000 2001*/ 2002 2003 2004/** 2005 \fn OGRErr OGR_L_SetNextByIndex( OGRLayerH hLayer, GIntBig nIndex ); 2006 2007 \brief Move read cursor to the nIndex'th feature in the current resultset. 2008 2009 This method allows positioning of a layer such that the GetNextFeature() 2010 call will read the requested feature, where nIndex is an absolute index 2011 into the current result set. So, setting it to 3 would mean the next 2012 feature read with GetNextFeature() would have been the 4th feature to have 2013 been read if sequential reading took place from the beginning of the layer, 2014 including accounting for spatial and attribute filters. 2015 2016 Only in rare circumstances is SetNextByIndex() efficiently implemented. 2017 In all other cases the default implementation which calls ResetReading() 2018 and then calls GetNextFeature() nIndex times is used. To determine if 2019 fast seeking is available on the current layer use the TestCapability() 2020 method with a value of OLCFastSetNextByIndex. 2021 2022 This method is the same as the C++ method OGRLayer::SetNextByIndex() 2023 2024 @param hLayer handle to the layer 2025 @param nIndex the index indicating how many steps into the result set 2026 to seek. 2027 2028 @return OGRERR_NONE on success or an error code. 2029 2030*/ 2031 2032/** 2033 \fn int OGRLayer::Reference(); 2034 2035\brief Increment layer reference count. 2036 2037This method is the same as the C function OGR_L_Reference(). 2038 2039@return the reference count after incrementing. 2040*/ 2041 2042/** 2043 \fn int OGRLayer::Dereference(); 2044 2045\brief Decrement layer reference count. 2046 2047This method is the same as the C function OGR_L_Dereference(). 2048 2049@return the reference count after decrementing. 2050*/ 2051 2052/** 2053 \fn int OGRLayer::GetRefCount() const; 2054 2055\brief Fetch reference count. 2056 2057This method is the same as the C function OGR_L_GetRefCount(). 2058 2059@return the current reference count for the layer object itself. 2060*/ 2061 2062/** 2063\fn OGRErr OGRLayer::CreateField( OGRFieldDefn *poField, 2064 int bApproxOK = TRUE ); 2065 2066\brief Create a new field on a layer. 2067 2068You must use this to create new fields 2069on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2070to reflect the new field. Applications should never modify the OGRFeatureDefn 2071used by a layer directly. 2072 2073This method should not be called while there are feature objects in existence that 2074were obtained or created with the previous layer definition. 2075 2076Not all drivers support this method. You can query a layer to check if it supports it 2077with the OLCCreateField capability. Some drivers may only support this method while 2078there are still no features in the layer. When it is supported, the existing features of the 2079backing file/database should be updated accordingly. 2080 2081Drivers may or may not support not-null constraints. If they support creating 2082fields with not-null constraints, this is generally before creating any feature to the layer. 2083 2084This function is the same as the C function OGR_L_CreateField(). 2085 2086@param poField field definition to write to disk. 2087@param bApproxOK If TRUE, the field may be created in a slightly different 2088form depending on the limitations of the format driver. 2089 2090@return OGRERR_NONE on success. 2091*/ 2092 2093/** 2094 2095 \fn OGRErr OGR_L_CreateField( OGRLayerH hLayer, OGRFieldDefnH hField, 2096 int bApproxOK ); 2097 2098\brief Create a new field on a layer. 2099 2100You must use this to create new fields 2101on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2102to reflect the new field. Applications should never modify the OGRFeatureDefn 2103used by a layer directly. 2104 2105This function should not be called while there are feature objects in existence that 2106were obtained or created with the previous layer definition. 2107 2108Not all drivers support this function. You can query a layer to check if it supports it 2109with the OLCCreateField capability. Some drivers may only support this method while 2110there are still no features in the layer. When it is supported, the existing features of the 2111backing file/database should be updated accordingly. 2112 2113Drivers may or may not support not-null constraints. If they support creating 2114fields with not-null constraints, this is generally before creating any feature to the layer. 2115 2116 This function is the same as the C++ method OGRLayer::CreateField(). 2117 2118 @param hLayer handle to the layer to write the field definition. 2119 @param hField handle of the field definition to write to disk. 2120 @param bApproxOK If TRUE, the field may be created in a slightly different 2121form depending on the limitations of the format driver. 2122 2123 @return OGRERR_NONE on success. 2124 2125*/ 2126 2127/** 2128\fn OGRErr OGRLayer::DeleteField( int iField ); 2129 2130\brief Delete an existing field on a layer. 2131 2132You must use this to delete existing fields 2133on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2134to reflect the deleted field. Applications should never modify the OGRFeatureDefn 2135used by a layer directly. 2136 2137This method should not be called while there are feature objects in existence that 2138were obtained or created with the previous layer definition. 2139 2140Not all drivers support this method. You can query a layer to check if it supports it 2141with the OLCDeleteField capability. Some drivers may only support this method while 2142there are still no features in the layer. When it is supported, the existing features of the 2143backing file/database should be updated accordingly. 2144 2145This function is the same as the C function OGR_L_DeleteField(). 2146 2147@param iField index of the field to delete. 2148 2149@return OGRERR_NONE on success. 2150 2151@since OGR 1.9.0 2152*/ 2153 2154/** 2155 2156\fn OGRErr OGR_L_DeleteField( OGRLayerH hLayer, int iField); 2157 2158\brief Delete an existing field on a layer. 2159 2160You must use this to delete existing fields 2161on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2162to reflect the deleted field. Applications should never modify the OGRFeatureDefn 2163used by a layer directly. 2164 2165This function should not be called while there are feature objects in existence that 2166were obtained or created with the previous layer definition. 2167 2168Not all drivers support this function. You can query a layer to check if it supports it 2169with the OLCDeleteField capability. Some drivers may only support this method while 2170there are still no features in the layer. When it is supported, the existing features of the 2171backing file/database should be updated accordingly. 2172 2173This function is the same as the C++ method OGRLayer::DeleteField(). 2174 2175@param hLayer handle to the layer. 2176@param iField index of the field to delete. 2177 2178@return OGRERR_NONE on success. 2179 2180@since OGR 1.9.0 2181*/ 2182 2183/** 2184\fn OGRErr OGRLayer::ReorderFields( int* panMap ); 2185 2186\brief Reorder all the fields of a layer. 2187 2188You must use this to reorder existing fields 2189on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2190to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn 2191used by a layer directly. 2192 2193This method should not be called while there are feature objects in existence that 2194were obtained or created with the previous layer definition. 2195 2196panMap is such that,for each field definition at position i after reordering, 2197its position before reordering was panMap[i]. 2198 2199For example, let suppose the fields were "0","1","2","3","4" initially. 2200ReorderFields([0,2,3,1,4]) will reorder them as "0","2","3","1","4". 2201 2202Not all drivers support this method. You can query a layer to check if it supports it 2203with the OLCReorderFields capability. Some drivers may only support this method while 2204there are still no features in the layer. When it is supported, the existing features of the 2205backing file/database should be updated accordingly. 2206 2207This function is the same as the C function OGR_L_ReorderFields(). 2208 2209@param panMap an array of GetLayerDefn()->OGRFeatureDefn::GetFieldCount() elements which 2210is a permutation of [0, GetLayerDefn()->OGRFeatureDefn::GetFieldCount()-1]. 2211 2212@return OGRERR_NONE on success. 2213 2214@since OGR 1.9.0 2215*/ 2216 2217/** 2218 2219\fn OGRErr OGR_L_ReorderFields( OGRLayerH hLayer, int* panMap ); 2220 2221\brief Reorder all the fields of a layer. 2222 2223You must use this to reorder existing fields 2224on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2225to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn 2226used by a layer directly. 2227 2228This function should not be called while there are feature objects in existence that 2229were obtained or created with the previous layer definition. 2230 2231panMap is such that,for each field definition at position i after reordering, 2232its position before reordering was panMap[i]. 2233 2234For example, let suppose the fields were "0","1","2","3","4" initially. 2235ReorderFields([0,2,3,1,4]) will reorder them as "0","2","3","1","4". 2236 2237Not all drivers support this function. You can query a layer to check if it supports it 2238with the OLCReorderFields capability. Some drivers may only support this method while 2239there are still no features in the layer. When it is supported, the existing features of the 2240backing file/database should be updated accordingly. 2241 2242This function is the same as the C++ method OGRLayer::ReorderFields(). 2243 2244@param hLayer handle to the layer. 2245@param panMap an array of GetLayerDefn()->OGRFeatureDefn::GetFieldCount() elements which 2246is a permutation of [0, GetLayerDefn()->OGRFeatureDefn::GetFieldCount()-1]. 2247 2248@return OGRERR_NONE on success. 2249 2250@since OGR 1.9.0 2251*/ 2252 2253/** 2254\fn OGRErr OGRLayer::ReorderField( int iOldFieldPos, int iNewFieldPos ); 2255 2256\brief Reorder an existing field on a layer. 2257 2258This method is a convenience wrapper of ReorderFields() dedicated to move a single field. 2259It is a non-virtual method, so drivers should implement ReorderFields() instead. 2260 2261You must use this to reorder existing fields 2262on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2263to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn 2264used by a layer directly. 2265 2266This method should not be called while there are feature objects in existence that 2267were obtained or created with the previous layer definition. 2268 2269The field definition that was at initial position iOldFieldPos will be moved at 2270position iNewFieldPos, and elements between will be shuffled accordingly. 2271 2272For example, let suppose the fields were "0","1","2","3","4" initially. 2273ReorderField(1, 3) will reorder them as "0","2","3","1","4". 2274 2275Not all drivers support this method. You can query a layer to check if it supports it 2276with the OLCReorderFields capability. Some drivers may only support this method while 2277there are still no features in the layer. When it is supported, the existing features of the 2278backing file/database should be updated accordingly. 2279 2280This function is the same as the C function OGR_L_ReorderField(). 2281 2282@param iOldFieldPos previous position of the field to move. Must be in the range [0,GetFieldCount()-1]. 2283@param iNewFieldPos new position of the field to move. Must be in the range [0,GetFieldCount()-1]. 2284 2285@return OGRERR_NONE on success. 2286 2287@since OGR 1.9.0 2288*/ 2289 2290/** 2291 2292\fn OGRErr OGR_L_ReorderField( OGRLayerH hLayer, int iOldFieldPos, int iNewFieldPos ); 2293 2294\brief Reorder an existing field on a layer. 2295 2296This function is a convenience wrapper of OGR_L_ReorderFields() dedicated to move a single field. 2297 2298You must use this to reorder existing fields 2299on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2300to reflect the reordering of the fields. Applications should never modify the OGRFeatureDefn 2301used by a layer directly. 2302 2303This function should not be called while there are feature objects in existence that 2304were obtained or created with the previous layer definition. 2305 2306The field definition that was at initial position iOldFieldPos will be moved at 2307position iNewFieldPos, and elements between will be shuffled accordingly. 2308 2309For example, let suppose the fields were "0","1","2","3","4" initially. 2310ReorderField(1, 3) will reorder them as "0","2","3","1","4". 2311 2312Not all drivers support this function. You can query a layer to check if it supports it 2313with the OLCReorderFields capability. Some drivers may only support this method while 2314there are still no features in the layer. When it is supported, the existing features of the 2315backing file/database should be updated accordingly. 2316 2317This function is the same as the C++ method OGRLayer::ReorderField(). 2318 2319@param hLayer handle to the layer. 2320@param iOldFieldPos previous position of the field to move. Must be in the range [0,GetFieldCount()-1]. 2321@param iNewFieldPos new position of the field to move. Must be in the range [0,GetFieldCount()-1]. 2322 2323@return OGRERR_NONE on success. 2324 2325@since OGR 1.9.0 2326*/ 2327 2328/** 2329\fn OGRErr OGRLayer::AlterFieldDefn( int iField, OGRFieldDefn* poNewFieldDefn, int nFlags ); 2330 2331\brief Alter the definition of an existing field on a layer. 2332 2333You must use this to alter the definition of an existing field of a real layer. 2334Internally the OGRFeatureDefn for the layer will be updated 2335to reflect the altered field. Applications should never modify the OGRFeatureDefn 2336used by a layer directly. 2337 2338This method should not be called while there are feature objects in existence that 2339were obtained or created with the previous layer definition. 2340 2341Not all drivers support this method. You can query a layer to check if it supports it 2342with the OLCAlterFieldDefn capability. Some drivers may only support this method while 2343there are still no features in the layer. When it is supported, the existing features of the 2344backing file/database should be updated accordingly. Some drivers might also not support 2345all update flags. 2346 2347This function is the same as the C function OGR_L_AlterFieldDefn(). 2348 2349@param iField index of the field whose definition must be altered. 2350@param poNewFieldDefn new field definition 2351@param nFlags combination of ALTER_NAME_FLAG, ALTER_TYPE_FLAG, ALTER_WIDTH_PRECISION_FLAG, 2352ALTER_NULLABLE_FLAG and ALTER_DEFAULT_FLAG 2353to indicate which of the name and/or type and/or width and precision fields and/or nullability from the new field 2354definition must be taken into account. 2355 2356@return OGRERR_NONE on success. 2357 2358@since OGR 1.9.0 2359*/ 2360 2361/** 2362\fn OGRErr OGR_L_AlterFieldDefn( OGRLayerH hLayer, int iField, OGRFieldDefnH hNewFieldDefn, int nFlags ) 2363 2364\brief Alter the definition of an existing field on a layer. 2365 2366You must use this to alter the definition of an existing field of a real layer. 2367Internally the OGRFeatureDefn for the layer will be updated 2368to reflect the altered field. Applications should never modify the OGRFeatureDefn 2369used by a layer directly. 2370 2371This function should not be called while there are feature objects in existence that 2372were obtained or created with the previous layer definition. 2373 2374Not all drivers support this function. You can query a layer to check if it supports it 2375with the OLCAlterFieldDefn capability. Some drivers may only support this method while 2376there are still no features in the layer. When it is supported, the existing features of the 2377backing file/database should be updated accordingly. Some drivers might also not support 2378all update flags. 2379 2380This function is the same as the C++ method OGRLayer::AlterFieldDefn(). 2381 2382@param hLayer handle to the layer. 2383@param iField index of the field whose definition must be altered. 2384@param hNewFieldDefn new field definition 2385@param nFlags combination of ALTER_NAME_FLAG, ALTER_TYPE_FLAG, ALTER_WIDTH_PRECISION_FLAG, 2386ALTER_NULLABLE_FLAG and ALTER_DEFAULT_FLAG 2387to indicate which of the name and/or type and/or width and precision fields and/or nullability from the new field 2388definition must be taken into account. 2389 2390@return OGRERR_NONE on success. 2391 2392@since OGR 1.9.0 2393*/ 2394 2395 2396/** 2397\fn OGRErr OGRLayer::CreateGeomField( OGRGeomFieldDefn *poField, 2398 int bApproxOK = TRUE ); 2399 2400\brief Create a new geometry field on a layer. 2401 2402You must use this to create new geometry fields 2403on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2404to reflect the new field. Applications should never modify the OGRFeatureDefn 2405used by a layer directly. 2406 2407This method should not be called while there are feature objects in existence that 2408were obtained or created with the previous layer definition. 2409 2410Not all drivers support this method. You can query a layer to check if it supports it 2411with the OLCCreateGeomField capability. Some drivers may only support this method while 2412there are still no features in the layer. When it is supported, the existing features of the 2413backing file/database should be updated accordingly. 2414 2415Drivers may or may not support not-null constraints. If they support creating 2416fields with not-null constraints, this is generally before creating any feature to the layer. 2417 2418This function is the same as the C function OGR_L_CreateGeomField(). 2419 2420@param poField geometry field definition to write to disk. 2421@param bApproxOK If TRUE, the field may be created in a slightly different 2422form depending on the limitations of the format driver. 2423 2424@return OGRERR_NONE on success. 2425 2426@since OGR 1.11 2427*/ 2428 2429/** 2430 2431 \fn OGRErr OGR_L_CreateGeomField( OGRLayerH hLayer, OGRGeomFieldDefnH hField, 2432 int bApproxOK ); 2433 2434\brief Create a new geometry field on a layer. 2435 2436You must use this to create new geometry fields 2437on a real layer. Internally the OGRFeatureDefn for the layer will be updated 2438to reflect the new field. Applications should never modify the OGRFeatureDefn 2439used by a layer directly. 2440 2441This function should not be called while there are feature objects in existence that 2442were obtained or created with the previous layer definition. 2443 2444Not all drivers support this function. You can query a layer to check if it supports it 2445with the OLCCreateField capability. Some drivers may only support this method while 2446there are still no features in the layer. When it is supported, the existing features of the 2447backing file/database should be updated accordingly. 2448 2449Drivers may or may not support not-null constraints. If they support creating 2450fields with not-null constraints, this is generally before creating any feature to the layer. 2451 2452 This function is the same as the C++ method OGRLayer::CreateField(). 2453 2454 @param hLayer handle to the layer to write the field definition. 2455 @param hField handle of the geometry field definition to write to disk. 2456 @param bApproxOK If TRUE, the field may be created in a slightly different 2457form depending on the limitations of the format driver. 2458 2459 @return OGRERR_NONE on success. 2460 2461 @since OGR 1.11 2462*/ 2463 2464/** 2465 \fn void OGRLayer::GetStyleTable(); 2466 2467 \brief Returns layer style table. 2468 2469 This method is the same as the C function OGR_L_GetStyleTable(). 2470 2471 @return pointer to a style table which should not be modified or freed by the 2472 caller. 2473*/ 2474 2475/** 2476 \fn void OGRLayer::SetStyleTable(OGRStyleTable *poStyleTable); 2477 2478 \brief Set layer style table. 2479 2480 This method operate exactly as OGRLayer::SetStyleTableDirectly() except 2481 that it does not assume ownership of the passed table. 2482 2483 This method is the same as the C function OGR_L_SetStyleTable(). 2484 2485 @param poStyleTable pointer to style table to set 2486 2487*/ 2488 2489/** 2490 \fn void OGRLayer::SetStyleTableDirectly(OGRStyleTable *poStyleTable); 2491 2492 \brief Set layer style table. 2493 2494 This method operate exactly as OGRLayer::SetStyleTable() except that it 2495 assumes ownership of the passed table. 2496 2497 This method is the same as the C function OGR_L_SetStyleTableDirectly(). 2498 2499 @param poStyleTable pointer to style table to set 2500 2501*/ 2502 2503/** 2504 2505 \fn OGRErr OGRLayer::StartTransaction(): 2506 2507 \brief For datasources which support transactions, StartTransaction creates a transaction. 2508 2509 If starting the transaction fails, will return 2510 OGRERR_FAILURE. Datasources which do not support transactions will 2511 always return OGRERR_NONE. 2512 2513 Note: as of GDAL 2.0, use of this API is discouraged when the dataset offers 2514 dataset level transaction with GDALDataset::StartTransaction(). The reason is 2515 that most drivers can only offer transactions at dataset level, and not layer level. 2516 Very few drivers really support transactions at layer scope. 2517 2518 This function is the same as the C function OGR_L_StartTransaction(). 2519 2520 @return OGRERR_NONE on success. 2521 2522*/ 2523 2524/** 2525 2526 \fn OGRErr OGR_L_StartTransaction( OGRLayerH hLayer ); 2527 2528 \brief For datasources which support transactions, StartTransaction creates a transaction. 2529 2530 If starting the transaction fails, will return 2531 OGRERR_FAILURE. Datasources which do not support transactions will 2532 always return OGRERR_NONE. 2533 2534 Note: as of GDAL 2.0, use of this API is discouraged when the dataset offers 2535 dataset level transaction with GDALDataset::StartTransaction(). The reason is 2536 that most drivers can only offer transactions at dataset level, and not layer level. 2537 Very few drivers really support transactions at layer scope. 2538 2539 This function is the same as the C++ method OGRLayer::StartTransaction(). 2540 2541 @param hLayer handle to the layer 2542 2543 @return OGRERR_NONE on success. 2544 2545*/ 2546 2547/** 2548 2549 \fn OGRErr OGRLayer::CommitTransaction(): 2550 2551 \brief For datasources which support transactions, CommitTransaction commits a transaction. 2552 2553 If no transaction is active, or the commit fails, will return 2554 OGRERR_FAILURE. Datasources which do not support transactions will 2555 always return OGRERR_NONE. 2556 2557 This function is the same as the C function OGR_L_CommitTransaction(). 2558 2559 @return OGRERR_NONE on success. 2560 2561*/ 2562 2563/** 2564 2565 \fn OGRErr OGR_L_CommitTransaction( OGRLayerH hLayer ); 2566 2567 \brief For datasources which support transactions, CommitTransaction commits a transaction. 2568 2569 If no transaction is active, or the commit fails, will return 2570 OGRERR_FAILURE. Datasources which do not support transactions will 2571 always return OGRERR_NONE. 2572 2573 This function is the same as the C++ method OGRLayer::CommitTransaction(). 2574 2575 @param hLayer handle to the layer 2576 2577 @return OGRERR_NONE on success. 2578 2579*/ 2580 2581/** 2582 2583 \fn OGRErr OGRLayer::RollbackTransaction(): 2584 2585 \brief For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction. 2586 If no transaction is active, or the rollback fails, will return 2587 OGRERR_FAILURE. Datasources which do not support transactions will 2588 always return OGRERR_NONE. 2589 2590 This function is the same as the C function OGR_L_RollbackTransaction(). 2591 2592 @return OGRERR_NONE on success. 2593 2594*/ 2595 2596/** 2597 2598 \fn OGRErr OGR_L_RollbackTransaction( OGRLayerH hLayer ); 2599 2600 \brief For datasources which support transactions, RollbackTransaction will roll back a datasource to its state before the start of the current transaction. 2601 If no transaction is active, or the rollback fails, will return 2602 OGRERR_FAILURE. Datasources which do not support transactions will 2603 always return OGRERR_NONE. 2604 2605 This function is the same as the C++ method OGRLayer::RollbackTransaction(). 2606 2607 @param hLayer handle to the layer 2608 2609 @return OGRERR_NONE on success. 2610 2611*/ 2612 2613/** 2614 \fn const char *OGRLayer::GetFIDColumn(); 2615 2616 \brief This method returns the name of the underlying database column being used as the FID column, or "" if not supported. 2617 2618 This method is the same as the C function OGR_L_GetFIDColumn(). 2619 2620 @return fid column name. 2621 2622 */ 2623 2624/** 2625 \fn const char* OGR_L_GetFIDColumn(OGRLayerH hLayer); 2626 2627 \brief This method returns the name of the underlying database column being used as the FID column, or "" if not supported. 2628 2629 This method is the same as the C++ method OGRLayer::GetFIDColumn() 2630 2631 @param hLayer handle to the layer 2632 @return fid column name. 2633 2634 */ 2635 2636/** 2637 \fn const char *OGRLayer::GetGeometryColumn(); 2638 2639 \brief This method returns the name of the underlying database column being used as the geometry column, or "" if not supported. 2640 2641 For layers with multiple geometry fields, this method only returns the name 2642 of the first geometry column. For other columns, use 2643 GetLayerDefn()->OGRFeatureDefn::GetGeomFieldDefn(i)->GetNameRef(). 2644 2645 This method is the same as the C function OGR_L_GetGeometryColumn(). 2646 2647 @return geometry column name. 2648 2649 */ 2650 2651/** 2652 \fn const char* OGR_L_GetGeometryColumn(OGRLayerH hLayer); 2653 2654 \brief This method returns the name of the underlying database column being used as the geometry column, or "" if not supported. 2655 2656 For layers with multiple geometry fields, this method only returns the geometry 2657 type of the first geometry column. For other columns, use 2658 OGR_GFld_GetNameRef(OGR_FD_GetGeomFieldDefn(OGR_L_GetLayerDefn(hLayer), i)). 2659 2660 This method is the same as the C++ method OGRLayer::GetGeometryColumn() 2661 2662 @param hLayer handle to the layer 2663 @return geometry column name. 2664 2665 */ 2666 2667/** 2668 \fn OGRErr OGRLayer::SetIgnoredFields( const char **papszFields ); 2669 2670 \brief Set which fields can be omitted when retrieving features from the layer. 2671 2672 If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields 2673 in subsequent calls to GetFeature() / GetNextFeature() and thus save some processing time and/or bandwidth. 2674 2675 Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and 2676 "OGR_STYLE" to ignore layer style. 2677 2678 By default, no fields are ignored. 2679 2680 This method is the same as the C function OGR_L_SetIgnoredFields() 2681 2682 @param papszFields an array of field names terminated by NULL item. If NULL is passed, the ignored list is cleared. 2683 @return OGRERR_NONE if all field names have been resolved (even if the driver does not support this method) 2684 2685 */ 2686 2687/** 2688 \fn OGRErr OGR_L_SetIgnoredFields( OGRLayerH hLayer, const char** papszFields); 2689 2690 \brief Set which fields can be omitted when retrieving features from the layer. 2691 2692 If the driver supports this functionality (testable using OLCIgnoreFields capability), it will not fetch the specified fields 2693 in subsequent calls to GetFeature() / GetNextFeature() and thus save some processing time and/or bandwidth. 2694 2695 Besides field names of the layers, the following special fields can be passed: "OGR_GEOMETRY" to ignore geometry and 2696 "OGR_STYLE" to ignore layer style. 2697 2698 By default, no fields are ignored. 2699 2700 This method is the same as the C++ method OGRLayer::SetIgnoredFields() 2701 2702 @param hLayer handle to the layer 2703 @param papszFields an array of field names terminated by NULL item. If NULL is passed, the ignored list is cleared. 2704 @return OGRERR_NONE if all field names have been resolved (even if the driver does not support this method) 2705 2706 */ 2707