Line data Source code
1 : /******************************************************************************
2 : *
3 : * Project: OpenGIS Simple Features Reference Implementation
4 : * Purpose: The generic portions of the GDALDataset class.
5 : * Author: Frank Warmerdam, warmerdam@pobox.com
6 : *
7 : ******************************************************************************
8 : * Copyright (c) 1999, Les Technologies SoftMap Inc.
9 : * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
10 : *
11 : * SPDX-License-Identifier: MIT
12 : ****************************************************************************/
13 :
14 : #include "ogrsf_frmts.h"
15 : #include "ogr_api.h"
16 : #include "ograpispy.h"
17 :
18 : /************************************************************************/
19 : /* OGRDataSource() */
20 : /************************************************************************/
21 :
22 : OGRDataSource::OGRDataSource() = default;
23 :
24 : /************************************************************************/
25 : /* ~OGRDataSource() */
26 : /************************************************************************/
27 :
28 : OGRDataSource::~OGRDataSource() = default;
29 :
30 : /************************************************************************/
31 : /* DestroyDataSource() */
32 : /************************************************************************/
33 :
34 : //! @cond Doxygen_Suppress
35 0 : void OGRDataSource::DestroyDataSource(OGRDataSource *poDS)
36 :
37 : {
38 0 : delete poDS;
39 0 : }
40 :
41 : //! @endcond
42 :
43 : /************************************************************************/
44 : /* OGR_DS_Destroy() */
45 : /************************************************************************/
46 :
47 : /**
48 : \brief Closes opened datasource and releases allocated resources.
49 :
50 : This method is the same as the C++ method OGRDataSource::DestroyDataSource().
51 :
52 : @deprecated Use GDALClose()
53 :
54 : @param hDS handle to allocated datasource object.
55 : */
56 25 : void OGR_DS_Destroy(OGRDataSourceH hDS)
57 :
58 : {
59 25 : if (hDS == nullptr)
60 0 : return;
61 25 : GDALClose(reinterpret_cast<GDALDatasetH>(hDS));
62 : // VALIDATE_POINTER0( hDS, "OGR_DS_Destroy" );
63 : }
64 :
65 : /************************************************************************/
66 : /* OGR_DS_Reference() */
67 : /************************************************************************/
68 :
69 0 : int OGR_DS_Reference(OGRDataSourceH hDataSource)
70 :
71 : {
72 0 : VALIDATE_POINTER1(hDataSource, "OGR_DS_Reference", 0);
73 :
74 0 : return GDALDataset::FromHandle(hDataSource)->Reference();
75 : }
76 :
77 : /************************************************************************/
78 : /* OGR_DS_Dereference() */
79 : /************************************************************************/
80 :
81 0 : int OGR_DS_Dereference(OGRDataSourceH hDataSource)
82 :
83 : {
84 0 : VALIDATE_POINTER1(hDataSource, "OGR_DS_Dereference", 0);
85 :
86 0 : return GDALDataset::FromHandle(hDataSource)->Dereference();
87 : }
88 :
89 : /************************************************************************/
90 : /* OGR_DS_GetRefCount() */
91 : /************************************************************************/
92 :
93 3985 : int OGR_DS_GetRefCount(OGRDataSourceH hDataSource)
94 :
95 : {
96 3985 : VALIDATE_POINTER1(hDataSource, "OGR_DS_GetRefCount", 0);
97 :
98 3985 : return GDALDataset::FromHandle(hDataSource)->GetRefCount();
99 : }
100 :
101 : /************************************************************************/
102 : /* OGR_DS_GetSummaryRefCount() */
103 : /************************************************************************/
104 :
105 0 : int OGR_DS_GetSummaryRefCount(OGRDataSourceH hDataSource)
106 :
107 : {
108 0 : VALIDATE_POINTER1(hDataSource, "OGR_DS_GetSummaryRefCount", 0);
109 :
110 0 : return GDALDataset::FromHandle(hDataSource)->GetSummaryRefCount();
111 : }
112 :
113 : /************************************************************************/
114 : /* OGR_DS_CreateLayer() */
115 : /************************************************************************/
116 :
117 : /**
118 : \brief This function attempts to create a new layer on the data source with the indicated name, coordinate system, geometry type.
119 :
120 : The papszOptions argument
121 : can be used to control driver specific creation options. These options are
122 : normally documented in the format specific documentation.
123 :
124 : @deprecated Use GDALDatasetCreateLayer()
125 :
126 : @param hDS The dataset handle.
127 : @param pszName the name for the new layer. This should ideally not
128 : match any existing layer on the datasource.
129 : @param hSpatialRef handle to the coordinate system to use for the new layer,
130 : or NULL if no coordinate system is available. The driver might only increase
131 : the reference counter of the object to take ownership, and not make a full copy,
132 : so do not use OSRDestroySpatialReference(), but OSRRelease() instead when you
133 : are done with the object.
134 : @param eType the geometry type for the layer. Use wkbUnknown if there
135 : are no constraints on the types geometry to be written.
136 : @param papszOptions a StringList of name=value options. Options are driver
137 : specific.
138 :
139 : @return NULL is returned on failure, or a new OGRLayer handle on success.
140 :
141 : <b>Example:</b>
142 :
143 : \code
144 : #include "ogrsf_frmts.h"
145 : #include "cpl_string.h"
146 :
147 : ...
148 :
149 : OGRLayerH *hLayer;
150 : char **papszOptions;
151 :
152 : if( OGR_DS_TestCapability( hDS, ODsCCreateLayer ) )
153 : {
154 : ...
155 : }
156 :
157 : papszOptions = CSLSetNameValue( papszOptions, "DIM", "2" );
158 : hLayer = OGR_DS_CreateLayer( hDS, "NewLayer", NULL, wkbUnknown,
159 : papszOptions );
160 : CSLDestroy( papszOptions );
161 :
162 : if( hLayer == NULL )
163 : {
164 : ...
165 : }
166 : \endcode
167 : */
168 :
169 13 : OGRLayerH OGR_DS_CreateLayer(OGRDataSourceH hDS, const char *pszName,
170 : OGRSpatialReferenceH hSpatialRef,
171 : OGRwkbGeometryType eType, char **papszOptions)
172 :
173 : {
174 13 : VALIDATE_POINTER1(hDS, "OGR_DS_CreateLayer", nullptr);
175 :
176 13 : if (pszName == nullptr)
177 : {
178 0 : CPLError(CE_Failure, CPLE_ObjectNull,
179 : "Name was NULL in OGR_DS_CreateLayer");
180 0 : return nullptr;
181 : }
182 : OGRLayerH hLayer =
183 26 : OGRLayer::ToHandle(GDALDataset::FromHandle(hDS)->CreateLayer(
184 13 : pszName, OGRSpatialReference::FromHandle(hSpatialRef), eType,
185 : papszOptions));
186 :
187 : #ifdef OGRAPISPY_ENABLED
188 13 : if (bOGRAPISpyEnabled)
189 0 : OGRAPISpy_DS_CreateLayer(hDS, pszName, hSpatialRef, eType, papszOptions,
190 : hLayer);
191 : #endif
192 :
193 13 : return hLayer;
194 : }
195 :
196 : /************************************************************************/
197 : /* OGR_DS_CopyLayer() */
198 : /************************************************************************/
199 :
200 : /**
201 : \brief Duplicate an existing layer.
202 :
203 : This function creates a new layer, duplicate the field definitions of the
204 : source layer and then duplicate each features of the source layer.
205 : The papszOptions argument
206 : can be used to control driver specific creation options. These options are
207 : normally documented in the format specific documentation.
208 : The source layer may come from another dataset.
209 :
210 : @deprecated Use GDALDatasetCopyLayer()
211 :
212 : @param hDS handle to the data source where to create the new layer
213 : @param hSrcLayer handle to the source layer.
214 : @param pszNewName the name of the layer to create.
215 : @param papszOptions a StringList of name=value options. Options are driver
216 : specific.
217 :
218 : @return a handle to the layer, or NULL if an error occurs.
219 : */
220 :
221 0 : OGRLayerH OGR_DS_CopyLayer(OGRDataSourceH hDS, OGRLayerH hSrcLayer,
222 : const char *pszNewName, char **papszOptions)
223 :
224 : {
225 0 : VALIDATE_POINTER1(hDS, "OGR_DS_CopyLayer", nullptr);
226 0 : VALIDATE_POINTER1(hSrcLayer, "OGR_DS_CopyLayer", nullptr);
227 0 : VALIDATE_POINTER1(pszNewName, "OGR_DS_CopyLayer", nullptr);
228 :
229 0 : return OGRLayer::ToHandle(GDALDataset::FromHandle(hDS)->CopyLayer(
230 0 : OGRLayer::FromHandle(hSrcLayer), pszNewName, papszOptions));
231 : }
232 :
233 : /************************************************************************/
234 : /* OGR_DS_DeleteLayer() */
235 : /************************************************************************/
236 :
237 : /**
238 : \brief Delete the indicated layer from the datasource.
239 :
240 : If this method is supported
241 : the ODsCDeleteLayer capability will test TRUE on the OGRDataSource.
242 :
243 : @deprecated Use GDALDatasetDeleteLayer()
244 :
245 : @param hDS handle to the datasource
246 : @param iLayer the index of the layer to delete.
247 :
248 : @return OGRERR_NONE on success, or OGRERR_UNSUPPORTED_OPERATION if deleting
249 : layers is not supported for this datasource.
250 : */
251 :
252 7 : OGRErr OGR_DS_DeleteLayer(OGRDataSourceH hDS, int iLayer)
253 :
254 : {
255 7 : VALIDATE_POINTER1(hDS, "OGR_DS_DeleteLayer", OGRERR_INVALID_HANDLE);
256 :
257 : #ifdef OGRAPISPY_ENABLED
258 7 : if (bOGRAPISpyEnabled)
259 0 : OGRAPISpy_DS_DeleteLayer(reinterpret_cast<GDALDatasetH>(hDS), iLayer);
260 : #endif
261 :
262 7 : OGRErr eErr = GDALDataset::FromHandle(hDS)->DeleteLayer(iLayer);
263 :
264 7 : return eErr;
265 : }
266 :
267 : /************************************************************************/
268 : /* OGR_DS_GetLayerByName() */
269 : /************************************************************************/
270 :
271 : /**
272 : \brief Fetch a layer by name.
273 :
274 : The returned layer remains owned by the
275 : OGRDataSource and should not be deleted by the application.
276 :
277 : @deprecated Use GDALDatasetGetLayerByName()
278 :
279 : @param hDS handle to the data source from which to get the layer.
280 : @param pszLayerName Layer the layer name of the layer to fetch.
281 :
282 : @return a handle to the layer, or NULL if the layer is not found
283 : or an error occurs.
284 : */
285 :
286 3 : OGRLayerH OGR_DS_GetLayerByName(OGRDataSourceH hDS, const char *pszLayerName)
287 :
288 : {
289 3 : VALIDATE_POINTER1(hDS, "OGR_DS_GetLayerByName", nullptr);
290 :
291 3 : OGRLayerH hLayer = OGRLayer::ToHandle(
292 3 : GDALDataset::FromHandle(hDS)->GetLayerByName(pszLayerName));
293 :
294 : #ifdef OGRAPISPY_ENABLED
295 3 : if (bOGRAPISpyEnabled)
296 0 : OGRAPISpy_DS_GetLayerByName(reinterpret_cast<GDALDatasetH>(hDS),
297 : pszLayerName, hLayer);
298 : #endif
299 :
300 3 : return hLayer;
301 : }
302 :
303 : /************************************************************************/
304 : /* OGR_DS_ExecuteSQL() */
305 : /************************************************************************/
306 :
307 : /**
308 : \brief Execute an SQL statement against the data store.
309 :
310 : The result of an SQL query is either NULL for statements that are in error,
311 : or that have no results set, or an OGRLayer handle representing a results
312 : set from the query. Note that this OGRLayer is in addition to the layers
313 : in the data store and must be destroyed with
314 : OGR_DS_ReleaseResultSet() before the data source is closed
315 : (destroyed).
316 :
317 : For more information on the SQL dialect supported internally by OGR
318 : review the <a href="https://gdal.org/user/ogr_sql_dialect.html">OGR SQL</a> document. Some drivers (i.e.
319 : Oracle and PostGIS) pass the SQL directly through to the underlying RDBMS.
320 :
321 : The <a href="https://gdal.org/user/sql_sqlite_dialect.html">SQLITE dialect</a>
322 : can also be used.
323 :
324 : @deprecated Use GDALDatasetExecuteSQL()
325 :
326 : @param hDS handle to the data source on which the SQL query is executed.
327 : @param pszStatement the SQL statement to execute.
328 : @param hSpatialFilter handle to a geometry which represents a spatial filter. Can be NULL.
329 : @param pszDialect allows control of the statement dialect. If set to NULL, the
330 : OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine,
331 : unless OGRSQL is explicitly passed as the dialect. The SQLITE dialect
332 : can also be used.
333 :
334 : @return a handle to a OGRLayer containing the results of the query.
335 : Deallocate with OGR_DS_ReleaseResultSet().
336 : */
337 :
338 2 : OGRLayerH OGR_DS_ExecuteSQL(OGRDataSourceH hDS, const char *pszStatement,
339 : OGRGeometryH hSpatialFilter, const char *pszDialect)
340 :
341 : {
342 2 : VALIDATE_POINTER1(hDS, "OGR_DS_ExecuteSQL", nullptr);
343 :
344 : OGRLayerH hLayer =
345 4 : OGRLayer::ToHandle(GDALDataset::FromHandle(hDS)->ExecuteSQL(
346 2 : pszStatement, OGRGeometry::FromHandle(hSpatialFilter), pszDialect));
347 :
348 : #ifdef OGRAPISPY_ENABLED
349 2 : if (bOGRAPISpyEnabled)
350 0 : OGRAPISpy_DS_ExecuteSQL(reinterpret_cast<GDALDatasetH>(hDS),
351 : pszStatement, hSpatialFilter, pszDialect,
352 : hLayer);
353 : #endif
354 :
355 2 : return hLayer;
356 : }
357 :
358 : /************************************************************************/
359 : /* OGR_DS_ReleaseResultSet() */
360 : /************************************************************************/
361 :
362 : /**
363 : \brief Release results of OGR_DS_ExecuteSQL().
364 :
365 : This function should only be used to deallocate OGRLayers resulting from
366 : an OGR_DS_ExecuteSQL() call on the same OGRDataSource.
367 : Failure to deallocate a results set before destroying the OGRDataSource
368 : may cause errors.
369 :
370 : @deprecated Use GDALDatasetReleaseResultSet()
371 :
372 : @param hDS a handle to the data source on which was executed an
373 : SQL query.
374 : @param hLayer handle to the result of a previous OGR_DS_ExecuteSQL() call.
375 : */
376 :
377 2 : void OGR_DS_ReleaseResultSet(OGRDataSourceH hDS, OGRLayerH hLayer)
378 :
379 : {
380 2 : VALIDATE_POINTER0(hDS, "OGR_DS_ReleaseResultSet");
381 :
382 : #ifdef OGRAPISPY_ENABLED
383 2 : if (bOGRAPISpyEnabled)
384 0 : OGRAPISpy_DS_ReleaseResultSet(reinterpret_cast<GDALDatasetH>(hDS),
385 : hLayer);
386 : #endif
387 :
388 4 : GDALDataset::FromHandle(hDS)->ReleaseResultSet(
389 2 : OGRLayer::FromHandle(hLayer));
390 : }
391 :
392 : /************************************************************************/
393 : /* OGR_DS_TestCapability() */
394 : /************************************************************************/
395 :
396 : /**
397 : \brief Test if capability is available.
398 :
399 : One of the following data source capability names can be passed into this
400 : function, and a TRUE or FALSE value will be returned indicating whether
401 : or not the capability is available for this object.
402 :
403 : <ul>
404 : <li> <b>ODsCCreateLayer</b>: True if this datasource can create new layers.
405 : <li> <b>ODsCDeleteLayer</b>: True if this datasource can delete existing layers.<p>
406 : <li> <b>ODsCCreateGeomFieldAfterCreateLayer</b>: True if the layers of this
407 : datasource support CreateGeomField() just after layer creation.<p>
408 : <li> <b>ODsCCurveGeometries</b>: True if this datasource supports writing curve geometries.
409 : In that case, OLCCurveGeometries must also be declared in layers of that dataset.<p>
410 : <p>
411 : </ul>
412 :
413 : The \#define macro forms of the capability names should be used in preference
414 : to the strings themselves to avoid misspelling.
415 :
416 : @deprecated Use GDALDatasetTestCapability()
417 :
418 : @param hDS handle to the data source against which to test the capability.
419 : @param pszCapability the capability to test.
420 :
421 : @return TRUE if capability available otherwise FALSE.
422 : */
423 :
424 1 : int OGR_DS_TestCapability(OGRDataSourceH hDS, const char *pszCapability)
425 :
426 : {
427 1 : VALIDATE_POINTER1(hDS, "OGR_DS_TestCapability", 0);
428 1 : VALIDATE_POINTER1(pszCapability, "OGR_DS_TestCapability", 0);
429 :
430 1 : return GDALDataset::FromHandle(hDS)->TestCapability(pszCapability);
431 : }
432 :
433 : /************************************************************************/
434 : /* OGR_DS_GetLayerCount() */
435 : /************************************************************************/
436 :
437 : /**
438 : \brief Get the number of layers in this data source.
439 :
440 : @deprecated Use GDALDatasetGetLayerCount()
441 :
442 : @param hDS handle to the data source from which to get the number of layers.
443 : @return layer count.
444 :
445 : */
446 27 : int OGR_DS_GetLayerCount(OGRDataSourceH hDS)
447 :
448 : {
449 27 : VALIDATE_POINTER1(hDS, "OGR_DS_GetLayerCount", 0);
450 :
451 : #ifdef OGRAPISPY_ENABLED
452 27 : if (bOGRAPISpyEnabled)
453 0 : OGRAPISpy_DS_GetLayerCount(reinterpret_cast<GDALDatasetH>(hDS));
454 : #endif
455 :
456 27 : return GDALDataset::FromHandle(hDS)->GetLayerCount();
457 : }
458 :
459 : /************************************************************************/
460 : /* OGR_DS_GetLayer() */
461 : /************************************************************************/
462 :
463 : /**
464 : \brief Fetch a layer by index.
465 :
466 : The returned layer remains owned by the
467 : OGRDataSource and should not be deleted by the application.
468 :
469 : @deprecated Use GDALDatasetGetLayer()
470 :
471 : @param hDS handle to the data source from which to get the layer.
472 : @param iLayer a layer number between 0 and OGR_DS_GetLayerCount()-1.
473 :
474 : @return a handle to the layer, or NULL if iLayer is out of range
475 : or an error occurs.
476 : */
477 :
478 32 : OGRLayerH OGR_DS_GetLayer(OGRDataSourceH hDS, int iLayer)
479 :
480 : {
481 32 : VALIDATE_POINTER1(hDS, "OGR_DS_GetLayer", nullptr);
482 :
483 : OGRLayerH hLayer =
484 32 : OGRLayer::ToHandle(GDALDataset::FromHandle(hDS)->GetLayer(iLayer));
485 :
486 : #ifdef OGRAPISPY_ENABLED
487 32 : if (bOGRAPISpyEnabled)
488 0 : OGRAPISpy_DS_GetLayer(reinterpret_cast<GDALDatasetH>(hDS), iLayer,
489 : hLayer);
490 : #endif
491 :
492 32 : return hLayer;
493 : }
494 :
495 : /************************************************************************/
496 : /* OGR_DS_GetName() */
497 : /************************************************************************/
498 :
499 : /**
500 : \brief Returns the name of the data source.
501 :
502 : This string should be sufficient to
503 : open the data source if passed to the same OGRSFDriver that this data
504 : source was opened with, but it need not be exactly the same string that
505 : was used to open the data source. Normally this is a filename.
506 :
507 : @deprecated Use GDALGetDescription()
508 :
509 : @param hDS handle to the data source to get the name from.
510 : @return pointer to an internal name string which should not be modified
511 : or freed by the caller.
512 : */
513 :
514 0 : const char *OGR_DS_GetName(OGRDataSourceH hDS)
515 :
516 : {
517 0 : VALIDATE_POINTER1(hDS, "OGR_DS_GetName", nullptr);
518 :
519 0 : return GDALDataset::FromHandle(hDS)->GetDescription();
520 : }
521 :
522 : /************************************************************************/
523 : /* OGR_DS_SyncToDisk() */
524 : /************************************************************************/
525 :
526 0 : OGRErr OGR_DS_SyncToDisk(OGRDataSourceH hDS)
527 :
528 : {
529 0 : VALIDATE_POINTER1(hDS, "OGR_DS_SyncToDisk", OGRERR_INVALID_HANDLE);
530 :
531 0 : GDALDataset::FromHandle(hDS)->FlushCache(false);
532 0 : if (CPLGetLastErrorType() != 0)
533 0 : return OGRERR_FAILURE;
534 : else
535 0 : return OGRERR_NONE;
536 : }
537 :
538 : /************************************************************************/
539 : /* OGR_DS_GetDriver() */
540 : /************************************************************************/
541 :
542 : /**
543 : \brief Returns the driver that the dataset was opened with.
544 :
545 : NOTE: It is *NOT* safe to cast the returned handle to
546 : OGRSFDriver*. If a C++ object is needed, the handle should be cast to GDALDriver*.
547 :
548 : @deprecated Use GDALGetDatasetDriver()
549 :
550 : @param hDS handle to the datasource
551 : @return NULL if driver info is not available, or pointer to a driver owned
552 : by the OGRSFDriverManager.
553 : */
554 :
555 5 : OGRSFDriverH OGR_DS_GetDriver(OGRDataSourceH hDS)
556 :
557 : {
558 5 : VALIDATE_POINTER1(hDS, "OGR_DS_GetDriver", nullptr);
559 :
560 : return reinterpret_cast<OGRSFDriverH>(
561 5 : reinterpret_cast<OGRDataSource *>(hDS)->GetDriver());
562 : }
563 :
564 : /************************************************************************/
565 : /* OGR_DS_GetStyleTable() */
566 : /************************************************************************/
567 :
568 0 : OGRStyleTableH OGR_DS_GetStyleTable(OGRDataSourceH hDS)
569 :
570 : {
571 0 : VALIDATE_POINTER1(hDS, "OGR_DS_GetStyleTable", nullptr);
572 :
573 : return reinterpret_cast<OGRStyleTableH>(
574 0 : GDALDataset::FromHandle(hDS)->GetStyleTable());
575 : }
576 :
577 : /************************************************************************/
578 : /* OGR_DS_SetStyleTableDirectly() */
579 : /************************************************************************/
580 :
581 0 : void OGR_DS_SetStyleTableDirectly(OGRDataSourceH hDS,
582 : OGRStyleTableH hStyleTable)
583 :
584 : {
585 0 : VALIDATE_POINTER0(hDS, "OGR_DS_SetStyleTableDirectly");
586 :
587 0 : GDALDataset::FromHandle(hDS)->SetStyleTableDirectly(
588 0 : reinterpret_cast<OGRStyleTable *>(hStyleTable));
589 : }
590 :
591 : /************************************************************************/
592 : /* OGR_DS_SetStyleTable() */
593 : /************************************************************************/
594 :
595 0 : void OGR_DS_SetStyleTable(OGRDataSourceH hDS, OGRStyleTableH hStyleTable)
596 :
597 : {
598 0 : VALIDATE_POINTER0(hDS, "OGR_DS_SetStyleTable");
599 0 : VALIDATE_POINTER0(hStyleTable, "OGR_DS_SetStyleTable");
600 :
601 0 : GDALDataset::FromHandle(hDS)->SetStyleTable(
602 0 : reinterpret_cast<OGRStyleTable *>(hStyleTable));
603 : }
|
