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