Line data Source code
1 : /******************************************************************************
2 : *
3 : * Name: gdal_dataset.h
4 : * Project: GDAL Core
5 : * Purpose: Declaration of GDALDataset class
6 : * Author: Frank Warmerdam, warmerdam@pobox.com
7 : *
8 : ******************************************************************************
9 : * Copyright (c) 1998, Frank Warmerdam
10 : * Copyright (c) 2007-2014, Even Rouault <even dot rouault at spatialys.com>
11 : *
12 : * SPDX-License-Identifier: MIT
13 : ****************************************************************************/
14 :
15 : #ifndef GDALDATASET_H_INCLUDED
16 : #define GDALDATASET_H_INCLUDED
17 :
18 : #include "cpl_port.h"
19 : #include "gdal_fwd.h"
20 : #include "gdal.h"
21 : #include "gdal_geotransform.h"
22 : #include "gdal_majorobject.h"
23 : #include "gdal_defaultoverviews.h"
24 : #include "ogr_core.h" // for OGRErr
25 : #include "ogr_feature.h" // for OGRFeatureUniquePtr
26 :
27 : #include <cstddef>
28 : #include <iterator>
29 : #include <memory>
30 : #include <vector>
31 :
32 : /* ******************************************************************** */
33 : /* GDALDataset */
34 : /* ******************************************************************** */
35 :
36 : class OGRGeometry;
37 : class OGRLayer;
38 : class OGRSpatialReference;
39 : class OGRStyleTable;
40 : class swq_select;
41 : class swq_select_parse_options;
42 : class GDALAsyncReader;
43 : class GDALDriver;
44 : class GDALGroup;
45 : class GDALMDArray;
46 : class GDALRasterBand;
47 : class GDALRelationship;
48 :
49 : //! @cond Doxygen_Suppress
50 : typedef struct GDALSQLParseInfo GDALSQLParseInfo;
51 : //! @endcond
52 :
53 : //! @cond Doxygen_Suppress
54 : #if !defined(OPTIONAL_OUTSIDE_GDAL)
55 : #if defined(GDAL_COMPILATION)
56 : #define OPTIONAL_OUTSIDE_GDAL(val)
57 : #else
58 : #define OPTIONAL_OUTSIDE_GDAL(val) = val
59 : #endif
60 : #endif
61 : //! @endcond
62 :
63 : //! @cond Doxygen_Suppress
64 : // This macro can be defined to check that GDALDataset::IRasterIO()
65 : // implementations do not alter the passed panBandList. It is not defined
66 : // by default (and should not!), hence int* is used.
67 : #if defined(GDAL_BANDMAP_TYPE_CONST_SAFE)
68 : #define BANDMAP_TYPE const int *
69 : #else
70 : #define BANDMAP_TYPE int *
71 : #endif
72 : //! @endcond
73 :
74 : /** A set of associated raster bands, usually from one file. */
75 : class CPL_DLL GDALDataset : public GDALMajorObject
76 : {
77 : friend GDALDatasetH CPL_STDCALL
78 : GDALOpenEx(const char *pszFilename, unsigned int nOpenFlags,
79 : const char *const *papszAllowedDrivers,
80 : const char *const *papszOpenOptions,
81 : const char *const *papszSiblingFiles);
82 : friend CPLErr CPL_STDCALL GDALClose(GDALDatasetH hDS);
83 :
84 : friend class GDALDriver;
85 : friend class GDALDefaultOverviews;
86 : friend class GDALProxyDataset;
87 : friend class GDALDriverManager;
88 :
89 : CPL_INTERNAL void AddToDatasetOpenList();
90 :
91 : CPL_INTERNAL void UnregisterFromSharedDataset();
92 :
93 : CPL_INTERNAL static void ReportErrorV(const char *pszDSName,
94 : CPLErr eErrClass, CPLErrorNum err_no,
95 : const char *fmt, va_list args);
96 :
97 : protected:
98 : //! @cond Doxygen_Suppress
99 : GDALDriver *poDriver = nullptr;
100 : GDALAccess eAccess = GA_ReadOnly;
101 :
102 : // Stored raster information.
103 : int nRasterXSize = 512;
104 : int nRasterYSize = 512;
105 : int nBands = 0;
106 : GDALRasterBand **papoBands = nullptr;
107 :
108 : static constexpr int OPEN_FLAGS_CLOSED = -1;
109 : int nOpenFlags =
110 : 0; // set to OPEN_FLAGS_CLOSED after Close() has been called
111 :
112 : int nRefCount = 1;
113 : bool bForceCachedIO = false;
114 : bool bShared = false;
115 : bool bIsInternal = true;
116 : bool bSuppressOnClose = false;
117 :
118 : mutable std::map<std::string, std::unique_ptr<OGRFieldDomain>>
119 : m_oMapFieldDomains{};
120 :
121 : GDALDataset(void);
122 : explicit GDALDataset(int bForceCachedIO);
123 :
124 : void RasterInitialize(int, int);
125 : void SetBand(int nNewBand, GDALRasterBand *poBand);
126 : void SetBand(int nNewBand, std::unique_ptr<GDALRasterBand> poBand);
127 :
128 : GDALDefaultOverviews oOvManager{};
129 :
130 : virtual CPLErr IBuildOverviews(const char *pszResampling, int nOverviews,
131 : const int *panOverviewList, int nListBands,
132 : const int *panBandList,
133 : GDALProgressFunc pfnProgress,
134 : void *pProgressData,
135 : CSLConstList papszOptions);
136 :
137 : virtual CPLErr
138 : IRasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize, int nYSize,
139 : void *pData, int nBufXSize, int nBufYSize, GDALDataType eBufType,
140 : int nBandCount, BANDMAP_TYPE panBandMap, GSpacing nPixelSpace,
141 : GSpacing nLineSpace, GSpacing nBandSpace,
142 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
143 :
144 : /* This method should only be be overloaded by GDALProxyDataset */
145 : virtual CPLErr
146 : BlockBasedRasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
147 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
148 : GDALDataType eBufType, int nBandCount,
149 : const int *panBandMap, GSpacing nPixelSpace,
150 : GSpacing nLineSpace, GSpacing nBandSpace,
151 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
152 : CPLErr BlockBasedFlushCache(bool bAtClosing);
153 :
154 : CPLErr
155 : BandBasedRasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
156 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
157 : GDALDataType eBufType, int nBandCount,
158 : const int *panBandMap, GSpacing nPixelSpace,
159 : GSpacing nLineSpace, GSpacing nBandSpace,
160 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
161 :
162 : CPLErr
163 : RasterIOResampled(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
164 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
165 : GDALDataType eBufType, int nBandCount,
166 : const int *panBandMap, GSpacing nPixelSpace,
167 : GSpacing nLineSpace, GSpacing nBandSpace,
168 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
169 :
170 : CPLErr ValidateRasterIOOrAdviseReadParameters(
171 : const char *pszCallingFunc, int *pbStopProcessingOnCENone, int nXOff,
172 : int nYOff, int nXSize, int nYSize, int nBufXSize, int nBufYSize,
173 : int nBandCount, const int *panBandMap);
174 :
175 : CPLErr TryOverviewRasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff,
176 : int nXSize, int nYSize, void *pData,
177 : int nBufXSize, int nBufYSize,
178 : GDALDataType eBufType, int nBandCount,
179 : const int *panBandMap, GSpacing nPixelSpace,
180 : GSpacing nLineSpace, GSpacing nBandSpace,
181 : GDALRasterIOExtraArg *psExtraArg, int *pbTried);
182 :
183 : void ShareLockWithParentDataset(GDALDataset *poParentDataset);
184 :
185 : bool m_bCanBeReopened = false;
186 :
187 : virtual bool CanBeCloned(int nScopeFlags, bool bCanShareState) const;
188 :
189 : friend class GDALThreadSafeDataset;
190 : friend class MEMDataset;
191 : virtual std::unique_ptr<GDALDataset> Clone(int nScopeFlags,
192 : bool bCanShareState) const;
193 :
194 : //! @endcond
195 :
196 : void CleanupPostFileClosing();
197 :
198 : virtual int CloseDependentDatasets();
199 : //! @cond Doxygen_Suppress
200 : int ValidateLayerCreationOptions(const char *const *papszLCO);
201 :
202 : char **papszOpenOptions = nullptr;
203 :
204 : friend class GDALRasterBand;
205 :
206 : // The below methods related to read write mutex are fragile logic, and
207 : // should not be used by out-of-tree code if possible.
208 : int EnterReadWrite(GDALRWFlag eRWFlag);
209 : void LeaveReadWrite();
210 : void InitRWLock();
211 :
212 : void TemporarilyDropReadWriteLock();
213 : void ReacquireReadWriteLock();
214 :
215 : void DisableReadWriteMutex();
216 :
217 : int AcquireMutex();
218 : void ReleaseMutex();
219 :
220 : bool IsAllBands(int nBandCount, const int *panBandList) const;
221 : //! @endcond
222 :
223 : public:
224 : ~GDALDataset() override;
225 :
226 : virtual CPLErr Close(GDALProgressFunc pfnProgress = nullptr,
227 : void *pProgressData = nullptr);
228 :
229 : virtual bool GetCloseReportsProgress() const;
230 :
231 : virtual bool CanReopenWithCurrentDescription() const;
232 :
233 : int GetRasterXSize() const;
234 : int GetRasterYSize() const;
235 : int GetRasterCount() const;
236 : GDALRasterBand *GetRasterBand(int);
237 : const GDALRasterBand *GetRasterBand(int) const;
238 :
239 : /**
240 : * @brief SetQueryLoggerFunc
241 : * @param pfnQueryLoggerFuncIn query logger function callback
242 : * @param poQueryLoggerArgIn arguments passed to the query logger function
243 : * @return true on success
244 : */
245 : virtual bool SetQueryLoggerFunc(GDALQueryLoggerFunc pfnQueryLoggerFuncIn,
246 : void *poQueryLoggerArgIn);
247 :
248 : /** Class returned by GetBands() that act as a container for raster bands.
249 : */
250 : class CPL_DLL Bands
251 : {
252 : private:
253 : friend class GDALDataset;
254 : GDALDataset *m_poSelf;
255 :
256 7 : CPL_INTERNAL explicit Bands(GDALDataset *poSelf) : m_poSelf(poSelf)
257 : {
258 7 : }
259 :
260 6 : class CPL_DLL Iterator
261 : {
262 : struct Private;
263 : std::unique_ptr<Private> m_poPrivate;
264 :
265 : public:
266 : Iterator(GDALDataset *poDS, bool bStart);
267 : Iterator(const Iterator &oOther); // declared but not defined.
268 : // Needed for gcc 5.4 at least
269 : Iterator(Iterator &&oOther) noexcept; // declared but not defined.
270 : // Needed for gcc 5.4 at least
271 : ~Iterator();
272 : GDALRasterBand *operator*();
273 : Iterator &operator++();
274 : bool operator!=(const Iterator &it) const;
275 : };
276 :
277 : public:
278 : const Iterator begin() const;
279 :
280 : const Iterator end() const;
281 :
282 : size_t size() const;
283 :
284 : GDALRasterBand *operator[](int iBand);
285 : GDALRasterBand *operator[](size_t iBand);
286 : };
287 :
288 : Bands GetBands();
289 :
290 : /** Class returned by GetBands() that act as a container for raster bands.
291 : */
292 : class CPL_DLL ConstBands
293 : {
294 : private:
295 : friend class GDALDataset;
296 : const GDALDataset *const m_poSelf;
297 :
298 4 : CPL_INTERNAL explicit ConstBands(const GDALDataset *poSelf)
299 4 : : m_poSelf(poSelf)
300 : {
301 4 : }
302 :
303 2 : class CPL_DLL Iterator
304 : {
305 : struct Private;
306 : std::unique_ptr<Private> m_poPrivate;
307 :
308 : public:
309 : Iterator(const GDALDataset *poDS, bool bStart);
310 : ~Iterator();
311 : const GDALRasterBand *operator*() const;
312 : Iterator &operator++();
313 : bool operator!=(const Iterator &it) const;
314 : };
315 :
316 : public:
317 : const Iterator begin() const;
318 :
319 : const Iterator end() const;
320 :
321 : size_t size() const;
322 :
323 : const GDALRasterBand *operator[](int iBand) const;
324 : const GDALRasterBand *operator[](size_t iBand) const;
325 : };
326 :
327 : ConstBands GetBands() const;
328 :
329 : virtual CPLErr FlushCache(bool bAtClosing = false);
330 : virtual CPLErr DropCache();
331 :
332 : virtual GIntBig GetEstimatedRAMUsage();
333 :
334 : virtual const OGRSpatialReference *GetSpatialRef() const;
335 : virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS);
336 :
337 : virtual const OGRSpatialReference *GetSpatialRefRasterOnly() const;
338 : virtual const OGRSpatialReference *GetSpatialRefVectorOnly() const;
339 :
340 : // Compatibility layer
341 : const char *GetProjectionRef(void) const;
342 : CPLErr SetProjection(const char *pszProjection);
343 :
344 : virtual CPLErr GetGeoTransform(GDALGeoTransform >) const;
345 : virtual CPLErr SetGeoTransform(const GDALGeoTransform >);
346 :
347 : CPLErr GetGeoTransform(double *padfGeoTransform) const
348 : #if defined(GDAL_COMPILATION) && !defined(DOXYGEN_XML)
349 : CPL_WARN_DEPRECATED("Use GetGeoTransform(GDALGeoTransform&) instead")
350 : #endif
351 : ;
352 :
353 : CPLErr SetGeoTransform(const double *padfGeoTransform)
354 : #if defined(GDAL_COMPILATION) && !defined(DOXYGEN_XML)
355 : CPL_WARN_DEPRECATED(
356 : "Use SetGeoTransform(const GDALGeoTransform&) instead")
357 : #endif
358 : ;
359 :
360 : virtual CPLErr GetExtent(OGREnvelope *psExtent,
361 : const OGRSpatialReference *poCRS = nullptr) const;
362 : virtual CPLErr GetExtentWGS84LongLat(OGREnvelope *psExtent) const;
363 :
364 : CPLErr GeolocationToPixelLine(
365 : double dfGeolocX, double dfGeolocY, const OGRSpatialReference *poSRS,
366 : double *pdfPixel, double *pdfLine,
367 : CSLConstList papszTransformerOptions = nullptr) const;
368 :
369 : virtual CPLErr AddBand(GDALDataType eType, char **papszOptions = nullptr);
370 :
371 : virtual void *GetInternalHandle(const char *pszHandleName);
372 : virtual GDALDriver *GetDriver(void);
373 : virtual char **GetFileList(void);
374 :
375 : const char *GetDriverName() const;
376 :
377 : virtual const OGRSpatialReference *GetGCPSpatialRef() const;
378 : virtual int GetGCPCount();
379 : virtual const GDAL_GCP *GetGCPs();
380 : virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
381 : const OGRSpatialReference *poGCP_SRS);
382 :
383 : // Compatibility layer
384 : const char *GetGCPProjection() const;
385 : CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
386 : const char *pszGCPProjection);
387 :
388 : virtual CPLErr AdviseRead(int nXOff, int nYOff, int nXSize, int nYSize,
389 : int nBufXSize, int nBufYSize, GDALDataType eDT,
390 : int nBandCount, int *panBandList,
391 : char **papszOptions);
392 :
393 : virtual CPLErr CreateMaskBand(int nFlagsIn);
394 :
395 : virtual GDALAsyncReader *
396 : BeginAsyncReader(int nXOff, int nYOff, int nXSize, int nYSize, void *pBuf,
397 : int nBufXSize, int nBufYSize, GDALDataType eBufType,
398 : int nBandCount, int *panBandMap, int nPixelSpace,
399 : int nLineSpace, int nBandSpace, char **papszOptions);
400 : virtual void EndAsyncReader(GDALAsyncReader *poARIO);
401 :
402 : //! @cond Doxygen_Suppress
403 : struct RawBinaryLayout
404 : {
405 : enum class Interleaving
406 : {
407 : UNKNOWN,
408 : BIP,
409 : BIL,
410 : BSQ
411 : };
412 : std::string osRawFilename{};
413 : Interleaving eInterleaving = Interleaving::UNKNOWN;
414 : GDALDataType eDataType = GDT_Unknown;
415 : bool bLittleEndianOrder = false;
416 :
417 : vsi_l_offset nImageOffset = 0;
418 : GIntBig nPixelOffset = 0;
419 : GIntBig nLineOffset = 0;
420 : GIntBig nBandOffset = 0;
421 : };
422 :
423 : virtual bool GetRawBinaryLayout(RawBinaryLayout &);
424 : //! @endcond
425 :
426 : #ifndef DOXYGEN_SKIP
427 : CPLErr RasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
428 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
429 : GDALDataType eBufType, int nBandCount,
430 : const int *panBandMap, GSpacing nPixelSpace,
431 : GSpacing nLineSpace, GSpacing nBandSpace,
432 : GDALRasterIOExtraArg *psExtraArg
433 : OPTIONAL_OUTSIDE_GDAL(nullptr)) CPL_WARN_UNUSED_RESULT;
434 : #else
435 : CPLErr RasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
436 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
437 : GDALDataType eBufType, int nBandCount,
438 : const int *panBandMap, GSpacing nPixelSpace,
439 : GSpacing nLineSpace, GSpacing nBandSpace,
440 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
441 : #endif
442 :
443 : virtual CPLStringList GetCompressionFormats(int nXOff, int nYOff,
444 : int nXSize, int nYSize,
445 : int nBandCount,
446 : const int *panBandList);
447 : virtual CPLErr ReadCompressedData(const char *pszFormat, int nXOff,
448 : int nYOff, int nXSize, int nYSize,
449 : int nBands, const int *panBandList,
450 : void **ppBuffer, size_t *pnBufferSize,
451 : char **ppszDetailedFormat);
452 :
453 : int Reference();
454 : int Dereference();
455 : int ReleaseRef();
456 :
457 : /** Return access mode.
458 : * @return access mode.
459 : */
460 197684 : GDALAccess GetAccess() const
461 : {
462 197684 : return eAccess;
463 : }
464 :
465 : int GetShared() const;
466 : void MarkAsShared();
467 :
468 : void MarkSuppressOnClose();
469 : void UnMarkSuppressOnClose();
470 :
471 : /** Return MarkSuppressOnClose flag.
472 : * @return MarkSuppressOnClose flag.
473 : */
474 5772924 : bool IsMarkedSuppressOnClose() const
475 : {
476 5772924 : return bSuppressOnClose;
477 : }
478 :
479 : /** Return open options.
480 : * @return open options.
481 : */
482 144296 : char **GetOpenOptions()
483 : {
484 144296 : return papszOpenOptions;
485 : }
486 :
487 : bool IsThreadSafe(int nScopeFlags) const;
488 :
489 : #ifndef DOXYGEN_SKIP
490 : /** Return open options.
491 : * @return open options.
492 : */
493 8 : CSLConstList GetOpenOptions() const
494 : {
495 8 : return papszOpenOptions;
496 : }
497 : #endif
498 :
499 : static GDALDataset **GetOpenDatasets(int *pnDatasetCount);
500 :
501 : #ifndef DOXYGEN_SKIP
502 : CPLErr
503 : BuildOverviews(const char *pszResampling, int nOverviews,
504 : const int *panOverviewList, int nListBands,
505 : const int *panBandList, GDALProgressFunc pfnProgress,
506 : void *pProgressData,
507 : CSLConstList papszOptions OPTIONAL_OUTSIDE_GDAL(nullptr));
508 : #else
509 : CPLErr BuildOverviews(const char *pszResampling, int nOverviews,
510 : const int *panOverviewList, int nListBands,
511 : const int *panBandList, GDALProgressFunc pfnProgress,
512 : void *pProgressData, CSLConstList papszOptions);
513 : #endif
514 :
515 : virtual CPLErr AddOverviews(const std::vector<GDALDataset *> &apoSrcOvrDS,
516 : GDALProgressFunc pfnProgress,
517 : void *pProgressData, CSLConstList papszOptions);
518 :
519 : CPLErr GetInterBandCovarianceMatrix(
520 : double *padfCovMatrix, size_t nSize, int nBandCount = 0,
521 : const int *panBandList = nullptr, bool bApproxOK = false,
522 : bool bForce = false, bool bWriteIntoMetadata = true,
523 : int nDeltaDegreeOfFreedom = 1, GDALProgressFunc pfnProgress = nullptr,
524 : void *pProgressData = nullptr);
525 :
526 : std::vector<double> GetInterBandCovarianceMatrix(
527 : int nBandCount = 0, const int *panBandList = nullptr,
528 : bool bApproxOK = false, bool bForce = false,
529 : bool bWriteIntoMetadata = true, int nDeltaDegreeOfFreedom = 1,
530 : GDALProgressFunc pfnProgress = nullptr, void *pProgressData = nullptr);
531 :
532 : CPLErr ComputeInterBandCovarianceMatrix(
533 : double *padfCovMatrix, size_t nSize, int nBandCount = 0,
534 : const int *panBandList = nullptr, bool bApproxOK = false,
535 : bool bWriteIntoMetadata = true, int nDeltaDegreeOfFreedom = 1,
536 : GDALProgressFunc pfnProgress = nullptr, void *pProgressData = nullptr);
537 :
538 : std::vector<double> ComputeInterBandCovarianceMatrix(
539 : int nBandCount = 0, const int *panBandList = nullptr,
540 : bool bApproxOK = false, bool bWriteIntoMetadata = true,
541 : int nDeltaDegreeOfFreedom = 1, GDALProgressFunc pfnProgress = nullptr,
542 : void *pProgressData = nullptr);
543 :
544 : #ifndef DOXYGEN_XML
545 : void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,
546 : ...) const CPL_PRINT_FUNC_FORMAT(4, 5);
547 :
548 : static void ReportError(const char *pszDSName, CPLErr eErrClass,
549 : CPLErrorNum err_no, const char *fmt, ...)
550 : CPL_PRINT_FUNC_FORMAT(4, 5);
551 : #endif
552 :
553 : char **GetMetadata(const char *pszDomain = "") override;
554 :
555 : // Only defined when Doxygen enabled
556 : #ifdef DOXYGEN_SKIP
557 : CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override;
558 : CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
559 : const char *pszDomain) override;
560 : #endif
561 :
562 : char **GetMetadataDomainList() override;
563 :
564 : virtual void ClearStatistics();
565 :
566 : std::shared_ptr<GDALMDArray> AsMDArray(CSLConstList papszOptions = nullptr);
567 :
568 : /** Convert a GDALDataset* to a GDALDatasetH.
569 : */
570 36605 : static inline GDALDatasetH ToHandle(GDALDataset *poDS)
571 : {
572 36605 : return static_cast<GDALDatasetH>(poDS);
573 : }
574 :
575 : /** Convert a GDALDatasetH to a GDALDataset*.
576 : */
577 1535442 : static inline GDALDataset *FromHandle(GDALDatasetH hDS)
578 : {
579 1535442 : return static_cast<GDALDataset *>(hDS);
580 : }
581 :
582 : /** @see GDALOpenEx().
583 : */
584 31959 : static GDALDataset *Open(const char *pszFilename,
585 : unsigned int nOpenFlags = 0,
586 : const char *const *papszAllowedDrivers = nullptr,
587 : const char *const *papszOpenOptions = nullptr,
588 : const char *const *papszSiblingFiles = nullptr)
589 : {
590 31959 : return FromHandle(GDALOpenEx(pszFilename, nOpenFlags,
591 : papszAllowedDrivers, papszOpenOptions,
592 31959 : papszSiblingFiles));
593 : }
594 :
595 : /** Object returned by GetFeatures() iterators */
596 : struct FeatureLayerPair
597 : {
598 : /** Unique pointer to a OGRFeature. */
599 : OGRFeatureUniquePtr feature{};
600 :
601 : /** Layer to which the feature belongs to. */
602 : OGRLayer *layer = nullptr;
603 : };
604 :
605 : //! @cond Doxygen_Suppress
606 : // SetEnableOverviews() only to be used by GDALOverviewDataset
607 : void SetEnableOverviews(bool bEnable);
608 :
609 : // Only to be used by driver's GetOverviewCount() method.
610 : bool AreOverviewsEnabled() const;
611 :
612 : static void ReportUpdateNotSupportedByDriver(const char *pszDriverName);
613 : //! @endcond
614 :
615 : private:
616 : class Private;
617 : Private *m_poPrivate;
618 :
619 : CPL_INTERNAL OGRLayer *BuildLayerFromSelectInfo(
620 : swq_select *psSelectInfo, OGRGeometry *poSpatialFilter,
621 : const char *pszDialect, swq_select_parse_options *poSelectParseOptions);
622 : CPLStringList oDerivedMetadataList{};
623 :
624 : public:
625 : virtual int GetLayerCount() const;
626 : virtual const OGRLayer *GetLayer(int iLayer) const;
627 :
628 1866626 : OGRLayer *GetLayer(int iLayer)
629 : {
630 : return const_cast<OGRLayer *>(
631 1866626 : const_cast<const GDALDataset *>(this)->GetLayer(iLayer));
632 : }
633 :
634 : virtual bool IsLayerPrivate(int iLayer) const;
635 :
636 : /** Class returned by GetLayers() that acts as a range of layers.
637 : */
638 : class CPL_DLL Layers
639 : {
640 : private:
641 : friend class GDALDataset;
642 : GDALDataset *m_poSelf;
643 :
644 327 : CPL_INTERNAL explicit Layers(GDALDataset *poSelf) : m_poSelf(poSelf)
645 : {
646 327 : }
647 :
648 : public:
649 : /** Layer iterator.
650 : */
651 664 : class CPL_DLL Iterator
652 : {
653 : struct Private;
654 : std::unique_ptr<Private> m_poPrivate;
655 :
656 : public:
657 : using value_type = OGRLayer *; /**< value_type */
658 : using reference = OGRLayer *; /**< reference */
659 : using difference_type = void; /**< difference_type */
660 : using pointer = void; /**< pointer */
661 : using iterator_category =
662 : std::input_iterator_tag; /**< iterator_category */
663 :
664 : Iterator(); /**< Default constructor */
665 : Iterator(GDALDataset *poDS, bool bStart); /**< Constructor */
666 : Iterator(const Iterator &oOther); /**< Copy constructor */
667 : Iterator(Iterator &&oOther) noexcept; /**< Move constructor */
668 : ~Iterator(); /**< Destructor */
669 :
670 : Iterator &
671 : operator=(const Iterator &oOther); /**< Assignment operator */
672 : Iterator &operator=(
673 : Iterator &&oOther) noexcept; /**< Move assignment operator */
674 :
675 : value_type operator*() const; /**< Dereference operator */
676 : Iterator &operator++(); /**< Pre-increment operator */
677 : Iterator operator++(int); /**< Post-increment operator */
678 : bool operator!=(const Iterator &it)
679 : const; /**< Difference comparison operator */
680 : };
681 :
682 : Iterator begin() const;
683 : Iterator end() const;
684 :
685 : size_t size() const;
686 :
687 : OGRLayer *operator[](int iLayer);
688 : OGRLayer *operator[](size_t iLayer);
689 : OGRLayer *operator[](const char *pszLayername);
690 : };
691 :
692 : Layers GetLayers();
693 :
694 : /** Class returned by GetLayers() that acts as a range of layers.
695 : * @since GDAL 3.12
696 : */
697 : class CPL_DLL ConstLayers
698 : {
699 : private:
700 : friend class GDALDataset;
701 : const GDALDataset *m_poSelf;
702 :
703 17566 : CPL_INTERNAL explicit ConstLayers(const GDALDataset *poSelf)
704 17566 : : m_poSelf(poSelf)
705 : {
706 17566 : }
707 :
708 : public:
709 : /** Layer iterator.
710 : * @since GDAL 3.12
711 : */
712 35142 : class CPL_DLL Iterator
713 : {
714 : struct Private;
715 : std::unique_ptr<Private> m_poPrivate;
716 :
717 : public:
718 : using value_type = const OGRLayer *; /**< value_type */
719 : using reference = const OGRLayer *; /**< reference */
720 : using difference_type = void; /**< difference_type */
721 : using pointer = void; /**< pointer */
722 : using iterator_category =
723 : std::input_iterator_tag; /**< iterator_category */
724 :
725 : Iterator(); /**< Default constructor */
726 : Iterator(const GDALDataset *poDS, bool bStart); /**< Constructor */
727 : Iterator(const Iterator &oOther); /**< Copy constructor */
728 : Iterator(Iterator &&oOther) noexcept; /**< Move constructor */
729 : ~Iterator(); /**< Destructor */
730 :
731 : Iterator &
732 : operator=(const Iterator &oOther); /**< Assignment operator */
733 : Iterator &operator=(
734 : Iterator &&oOther) noexcept; /**< Move assignment operator */
735 :
736 : value_type operator*() const; /**< Dereference operator */
737 : Iterator &operator++(); /**< Pre-increment operator */
738 : Iterator operator++(int); /**< Post-increment operator */
739 : bool operator!=(const Iterator &it)
740 : const; /**< Difference comparison operator */
741 : };
742 :
743 : Iterator begin() const;
744 : Iterator end() const;
745 :
746 : size_t size() const;
747 :
748 : const OGRLayer *operator[](int iLayer);
749 : const OGRLayer *operator[](size_t iLayer);
750 : const OGRLayer *operator[](const char *pszLayername);
751 : };
752 :
753 : ConstLayers GetLayers() const;
754 :
755 : virtual OGRLayer *GetLayerByName(const char *);
756 :
757 : int GetLayerIndex(const char *pszName) const;
758 :
759 : virtual OGRErr DeleteLayer(int iLayer);
760 :
761 : virtual void ResetReading();
762 : virtual OGRFeature *GetNextFeature(OGRLayer **ppoBelongingLayer,
763 : double *pdfProgressPct,
764 : GDALProgressFunc pfnProgress,
765 : void *pProgressData);
766 :
767 : /** Class returned by GetFeatures() that act as a container for vector
768 : * features. */
769 : class CPL_DLL Features
770 : {
771 : private:
772 : friend class GDALDataset;
773 : GDALDataset *m_poSelf;
774 :
775 2 : CPL_INTERNAL explicit Features(GDALDataset *poSelf) : m_poSelf(poSelf)
776 : {
777 2 : }
778 :
779 4 : class CPL_DLL Iterator
780 : {
781 : struct Private;
782 : std::unique_ptr<Private> m_poPrivate;
783 :
784 : public:
785 : Iterator(GDALDataset *poDS, bool bStart);
786 : Iterator(const Iterator &oOther); // declared but not defined.
787 : // Needed for gcc 5.4 at least
788 : Iterator(Iterator &&oOther) noexcept; // declared but not defined.
789 : // Needed for gcc 5.4 at least
790 : ~Iterator();
791 : const FeatureLayerPair &operator*() const;
792 : Iterator &operator++();
793 : bool operator!=(const Iterator &it) const;
794 : };
795 :
796 : public:
797 : const Iterator begin() const;
798 :
799 : const Iterator end() const;
800 : };
801 :
802 : Features GetFeatures();
803 :
804 : virtual int TestCapability(const char *) const;
805 :
806 : virtual std::vector<std::string>
807 : GetFieldDomainNames(CSLConstList papszOptions = nullptr) const;
808 :
809 : virtual const OGRFieldDomain *GetFieldDomain(const std::string &name) const;
810 :
811 : virtual bool AddFieldDomain(std::unique_ptr<OGRFieldDomain> &&domain,
812 : std::string &failureReason);
813 :
814 : virtual bool DeleteFieldDomain(const std::string &name,
815 : std::string &failureReason);
816 :
817 : virtual bool UpdateFieldDomain(std::unique_ptr<OGRFieldDomain> &&domain,
818 : std::string &failureReason);
819 :
820 : virtual std::vector<std::string>
821 : GetRelationshipNames(CSLConstList papszOptions = nullptr) const;
822 :
823 : virtual const GDALRelationship *
824 : GetRelationship(const std::string &name) const;
825 :
826 : virtual bool
827 : AddRelationship(std::unique_ptr<GDALRelationship> &&relationship,
828 : std::string &failureReason);
829 :
830 : virtual bool DeleteRelationship(const std::string &name,
831 : std::string &failureReason);
832 :
833 : virtual bool
834 : UpdateRelationship(std::unique_ptr<GDALRelationship> &&relationship,
835 : std::string &failureReason);
836 :
837 : //! @cond Doxygen_Suppress
838 : OGRLayer *CreateLayer(const char *pszName);
839 :
840 : OGRLayer *CreateLayer(const char *pszName, std::nullptr_t);
841 : //! @endcond
842 :
843 : OGRLayer *CreateLayer(const char *pszName,
844 : const OGRSpatialReference *poSpatialRef,
845 : OGRwkbGeometryType eGType = wkbUnknown,
846 : CSLConstList papszOptions = nullptr);
847 :
848 : OGRLayer *CreateLayer(const char *pszName,
849 : const OGRGeomFieldDefn *poGeomFieldDefn,
850 : CSLConstList papszOptions = nullptr);
851 :
852 : virtual OGRLayer *CopyLayer(OGRLayer *poSrcLayer, const char *pszNewName,
853 : char **papszOptions = nullptr);
854 :
855 : virtual OGRStyleTable *GetStyleTable();
856 : virtual void SetStyleTableDirectly(OGRStyleTable *poStyleTable);
857 :
858 : virtual void SetStyleTable(OGRStyleTable *poStyleTable);
859 :
860 : virtual OGRLayer *ExecuteSQL(const char *pszStatement,
861 : OGRGeometry *poSpatialFilter,
862 : const char *pszDialect);
863 : virtual void ReleaseResultSet(OGRLayer *poResultsSet);
864 : virtual OGRErr AbortSQL();
865 :
866 : int GetRefCount() const;
867 : int GetSummaryRefCount() const;
868 : OGRErr Release();
869 :
870 : virtual OGRErr StartTransaction(int bForce = FALSE);
871 : virtual OGRErr CommitTransaction();
872 : virtual OGRErr RollbackTransaction();
873 :
874 : virtual std::shared_ptr<GDALGroup> GetRootGroup() const;
875 :
876 : static std::string BuildFilename(const char *pszFilename,
877 : const char *pszReferencePath,
878 : bool bRelativeToReferencePath);
879 :
880 : //! @cond Doxygen_Suppress
881 : static int IsGenericSQLDialect(const char *pszDialect);
882 :
883 : // Semi-public methods. Only to be used by in-tree drivers.
884 : GDALSQLParseInfo *
885 : BuildParseInfo(swq_select *psSelectInfo,
886 : swq_select_parse_options *poSelectParseOptions);
887 : static void DestroyParseInfo(GDALSQLParseInfo *psParseInfo);
888 : OGRLayer *ExecuteSQL(const char *pszStatement, OGRGeometry *poSpatialFilter,
889 : const char *pszDialect,
890 : swq_select_parse_options *poSelectParseOptions);
891 :
892 : static constexpr const char *const apszSpecialSubDatasetSyntax[] = {
893 : "NITF_IM:{ANY}:{FILENAME}", "PDF:{ANY}:{FILENAME}",
894 : "RASTERLITE:{FILENAME},{ANY}", "TILEDB:\"{FILENAME}\":{ANY}",
895 : "TILEDB:{FILENAME}:{ANY}"};
896 :
897 : //! @endcond
898 :
899 : protected:
900 : virtual OGRLayer *ICreateLayer(const char *pszName,
901 : const OGRGeomFieldDefn *poGeomFieldDefn,
902 : CSLConstList papszOptions);
903 :
904 : //! @cond Doxygen_Suppress
905 : OGRErr ProcessSQLCreateIndex(const char *);
906 : OGRErr ProcessSQLDropIndex(const char *);
907 : OGRErr ProcessSQLDropTable(const char *);
908 : OGRErr ProcessSQLAlterTableAddColumn(const char *);
909 : OGRErr ProcessSQLAlterTableDropColumn(const char *);
910 : OGRErr ProcessSQLAlterTableAlterColumn(const char *);
911 : OGRErr ProcessSQLAlterTableRenameColumn(const char *);
912 :
913 : OGRStyleTable *m_poStyleTable = nullptr;
914 :
915 : friend class GDALProxyPoolDataset;
916 : //! @endcond
917 :
918 : private:
919 : CPL_DISALLOW_COPY_ASSIGN(GDALDataset)
920 : };
921 :
922 : //! @cond Doxygen_Suppress
923 : struct CPL_DLL GDALDatasetUniquePtrDeleter
924 : {
925 101 : void operator()(GDALDataset *poDataset) const
926 : {
927 101 : GDALClose(poDataset);
928 101 : }
929 : };
930 :
931 : //! @endcond
932 :
933 : //! @cond Doxygen_Suppress
934 : struct CPL_DLL GDALDatasetUniquePtrReleaser
935 : {
936 2309 : void operator()(GDALDataset *poDataset) const
937 : {
938 2309 : if (poDataset)
939 2305 : poDataset->Release();
940 2309 : }
941 : };
942 :
943 : //! @endcond
944 :
945 : /** Unique pointer type for GDALDataset.
946 : * Appropriate for use on datasets open in non-shared mode and onto which
947 : * reference counter has not been manually modified.
948 : */
949 : using GDALDatasetUniquePtr =
950 : std::unique_ptr<GDALDataset, GDALDatasetUniquePtrDeleter>;
951 :
952 : #endif
|
