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, char **papszOptions = nullptr);
371 :
372 : virtual void *GetInternalHandle(const char *pszHandleName);
373 : virtual GDALDriver *GetDriver(void);
374 : virtual char **GetFileList(void);
375 :
376 : const char *GetDriverName() const;
377 :
378 : virtual const OGRSpatialReference *GetGCPSpatialRef() const;
379 : virtual int GetGCPCount();
380 : virtual const GDAL_GCP *GetGCPs();
381 : virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
382 : const OGRSpatialReference *poGCP_SRS);
383 :
384 : // Compatibility layer
385 : const char *GetGCPProjection() const;
386 : CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
387 : const char *pszGCPProjection);
388 :
389 : virtual CPLErr AdviseRead(int nXOff, int nYOff, int nXSize, int nYSize,
390 : int nBufXSize, int nBufYSize, GDALDataType eDT,
391 : int nBandCount, int *panBandList,
392 : char **papszOptions);
393 :
394 : virtual CPLErr CreateMaskBand(int nFlagsIn);
395 :
396 : virtual GDALAsyncReader *
397 : BeginAsyncReader(int nXOff, int nYOff, int nXSize, int nYSize, void *pBuf,
398 : int nBufXSize, int nBufYSize, GDALDataType eBufType,
399 : int nBandCount, int *panBandMap, int nPixelSpace,
400 : int nLineSpace, int nBandSpace, char **papszOptions);
401 : virtual void EndAsyncReader(GDALAsyncReader *poARIO);
402 :
403 : //! @cond Doxygen_Suppress
404 : struct RawBinaryLayout
405 : {
406 : enum class Interleaving
407 : {
408 : UNKNOWN,
409 : BIP,
410 : BIL,
411 : BSQ
412 : };
413 : std::string osRawFilename{};
414 : Interleaving eInterleaving = Interleaving::UNKNOWN;
415 : GDALDataType eDataType = GDT_Unknown;
416 : bool bLittleEndianOrder = false;
417 :
418 : vsi_l_offset nImageOffset = 0;
419 : GIntBig nPixelOffset = 0;
420 : GIntBig nLineOffset = 0;
421 : GIntBig nBandOffset = 0;
422 : };
423 :
424 : virtual bool GetRawBinaryLayout(RawBinaryLayout &);
425 : //! @endcond
426 :
427 : #ifndef DOXYGEN_SKIP
428 : CPLErr RasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
429 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
430 : GDALDataType eBufType, int nBandCount,
431 : const int *panBandMap, GSpacing nPixelSpace,
432 : GSpacing nLineSpace, GSpacing nBandSpace,
433 : GDALRasterIOExtraArg *psExtraArg
434 : OPTIONAL_OUTSIDE_GDAL(nullptr)) CPL_WARN_UNUSED_RESULT;
435 : #else
436 : CPLErr RasterIO(GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize,
437 : int nYSize, void *pData, int nBufXSize, int nBufYSize,
438 : GDALDataType eBufType, int nBandCount,
439 : const int *panBandMap, GSpacing nPixelSpace,
440 : GSpacing nLineSpace, GSpacing nBandSpace,
441 : GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT;
442 : #endif
443 :
444 : virtual CPLStringList GetCompressionFormats(int nXOff, int nYOff,
445 : int nXSize, int nYSize,
446 : int nBandCount,
447 : const int *panBandList);
448 : virtual CPLErr ReadCompressedData(const char *pszFormat, int nXOff,
449 : int nYOff, int nXSize, int nYSize,
450 : int nBands, const int *panBandList,
451 : void **ppBuffer, size_t *pnBufferSize,
452 : char **ppszDetailedFormat);
453 :
454 : int Reference();
455 : int Dereference();
456 : int ReleaseRef();
457 :
458 : /** Return access mode.
459 : * @return access mode.
460 : */
461 191529 : GDALAccess GetAccess() const
462 : {
463 191529 : return eAccess;
464 : }
465 :
466 : int GetShared() const;
467 : void MarkAsShared();
468 :
469 : void MarkSuppressOnClose();
470 : void UnMarkSuppressOnClose();
471 :
472 : /** Return MarkSuppressOnClose flag.
473 : * @return MarkSuppressOnClose flag.
474 : */
475 5784579 : bool IsMarkedSuppressOnClose() const
476 : {
477 5784579 : return bSuppressOnClose;
478 : }
479 :
480 : /** Return open options.
481 : * @return open options.
482 : */
483 144296 : char **GetOpenOptions()
484 : {
485 144296 : return papszOpenOptions;
486 : }
487 :
488 : bool IsThreadSafe(int nScopeFlags) const;
489 :
490 : #ifndef DOXYGEN_SKIP
491 : /** Return open options.
492 : * @return open options.
493 : */
494 8 : CSLConstList GetOpenOptions() const
495 : {
496 8 : return papszOpenOptions;
497 : }
498 : #endif
499 :
500 : static GDALDataset **GetOpenDatasets(int *pnDatasetCount);
501 :
502 : #ifndef DOXYGEN_SKIP
503 : CPLErr
504 : BuildOverviews(const char *pszResampling, int nOverviews,
505 : const int *panOverviewList, int nListBands,
506 : const int *panBandList, GDALProgressFunc pfnProgress,
507 : void *pProgressData,
508 : CSLConstList papszOptions OPTIONAL_OUTSIDE_GDAL(nullptr));
509 : #else
510 : CPLErr BuildOverviews(const char *pszResampling, int nOverviews,
511 : const int *panOverviewList, int nListBands,
512 : const int *panBandList, GDALProgressFunc pfnProgress,
513 : void *pProgressData, CSLConstList papszOptions);
514 : #endif
515 :
516 : virtual CPLErr AddOverviews(const std::vector<GDALDataset *> &apoSrcOvrDS,
517 : GDALProgressFunc pfnProgress,
518 : void *pProgressData, CSLConstList papszOptions);
519 :
520 : CPLErr GetInterBandCovarianceMatrix(
521 : double *padfCovMatrix, size_t nSize, int nBandCount = 0,
522 : const int *panBandList = nullptr, bool bApproxOK = false,
523 : bool bForce = false, bool bWriteIntoMetadata = true,
524 : int nDeltaDegreeOfFreedom = 1, GDALProgressFunc pfnProgress = nullptr,
525 : void *pProgressData = nullptr);
526 :
527 : std::vector<double> GetInterBandCovarianceMatrix(
528 : int nBandCount = 0, const int *panBandList = nullptr,
529 : bool bApproxOK = false, bool bForce = false,
530 : bool bWriteIntoMetadata = true, int nDeltaDegreeOfFreedom = 1,
531 : GDALProgressFunc pfnProgress = nullptr, void *pProgressData = nullptr);
532 :
533 : CPLErr ComputeInterBandCovarianceMatrix(
534 : double *padfCovMatrix, size_t nSize, int nBandCount = 0,
535 : const int *panBandList = nullptr, bool bApproxOK = false,
536 : bool bWriteIntoMetadata = true, int nDeltaDegreeOfFreedom = 1,
537 : GDALProgressFunc pfnProgress = nullptr, void *pProgressData = nullptr);
538 :
539 : std::vector<double> ComputeInterBandCovarianceMatrix(
540 : int nBandCount = 0, const int *panBandList = nullptr,
541 : bool bApproxOK = false, bool bWriteIntoMetadata = true,
542 : int nDeltaDegreeOfFreedom = 1, GDALProgressFunc pfnProgress = nullptr,
543 : void *pProgressData = nullptr);
544 :
545 : #ifndef DOXYGEN_XML
546 : void ReportError(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,
547 : ...) const CPL_PRINT_FUNC_FORMAT(4, 5);
548 :
549 : static void ReportError(const char *pszDSName, CPLErr eErrClass,
550 : CPLErrorNum err_no, const char *fmt, ...)
551 : CPL_PRINT_FUNC_FORMAT(4, 5);
552 : #endif
553 :
554 : char **GetMetadata(const char *pszDomain = "") override;
555 :
556 : // Only defined when Doxygen enabled
557 : #ifdef DOXYGEN_SKIP
558 : CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override;
559 : CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
560 : const char *pszDomain) override;
561 : #endif
562 :
563 : char **GetMetadataDomainList() override;
564 :
565 : virtual void ClearStatistics();
566 :
567 : std::shared_ptr<GDALMDArray> AsMDArray(CSLConstList papszOptions = nullptr);
568 :
569 : /** Convert a GDALDataset* to a GDALDatasetH.
570 : */
571 36645 : static inline GDALDatasetH ToHandle(GDALDataset *poDS)
572 : {
573 36645 : return static_cast<GDALDatasetH>(poDS);
574 : }
575 :
576 : /** Convert a GDALDatasetH to a GDALDataset*.
577 : */
578 1537812 : static inline GDALDataset *FromHandle(GDALDatasetH hDS)
579 : {
580 1537812 : return static_cast<GDALDataset *>(hDS);
581 : }
582 :
583 : /** @see GDALOpenEx().
584 : */
585 32008 : static GDALDataset *Open(const char *pszFilename,
586 : unsigned int nOpenFlags = 0,
587 : const char *const *papszAllowedDrivers = nullptr,
588 : const char *const *papszOpenOptions = nullptr,
589 : const char *const *papszSiblingFiles = nullptr)
590 : {
591 32008 : return FromHandle(GDALOpenEx(pszFilename, nOpenFlags,
592 : papszAllowedDrivers, papszOpenOptions,
593 32008 : papszSiblingFiles));
594 : }
595 :
596 : static std::unique_ptr<GDALDataset>
597 : Open(GDALOpenInfo *poOpenInfo,
598 : const char *const *papszAllowedDrivers = nullptr,
599 : const char *const *papszOpenOptions = nullptr);
600 :
601 : /** Object returned by GetFeatures() iterators */
602 : struct FeatureLayerPair
603 : {
604 : /** Unique pointer to a OGRFeature. */
605 : OGRFeatureUniquePtr feature{};
606 :
607 : /** Layer to which the feature belongs to. */
608 : OGRLayer *layer = nullptr;
609 : };
610 :
611 : //! @cond Doxygen_Suppress
612 : // SetEnableOverviews() only to be used by GDALOverviewDataset
613 : void SetEnableOverviews(bool bEnable);
614 :
615 : // Only to be used by driver's GetOverviewCount() method.
616 : bool AreOverviewsEnabled() const;
617 :
618 : static void ReportUpdateNotSupportedByDriver(const char *pszDriverName);
619 : //! @endcond
620 :
621 : private:
622 : class Private;
623 : Private *m_poPrivate;
624 :
625 : CPL_INTERNAL OGRLayer *BuildLayerFromSelectInfo(
626 : swq_select *psSelectInfo, OGRGeometry *poSpatialFilter,
627 : const char *pszDialect, swq_select_parse_options *poSelectParseOptions);
628 : CPLStringList oDerivedMetadataList{};
629 :
630 : public:
631 : virtual int GetLayerCount() const;
632 : virtual const OGRLayer *GetLayer(int iLayer) const;
633 :
634 1866776 : OGRLayer *GetLayer(int iLayer)
635 : {
636 : return const_cast<OGRLayer *>(
637 1866776 : const_cast<const GDALDataset *>(this)->GetLayer(iLayer));
638 : }
639 :
640 : virtual bool IsLayerPrivate(int iLayer) const;
641 :
642 : /** Class returned by GetLayers() that acts as a range of layers.
643 : */
644 : class CPL_DLL Layers
645 : {
646 : private:
647 : friend class GDALDataset;
648 : GDALDataset *m_poSelf;
649 :
650 388 : CPL_INTERNAL explicit Layers(GDALDataset *poSelf) : m_poSelf(poSelf)
651 : {
652 388 : }
653 :
654 : public:
655 : /** Layer iterator.
656 : */
657 786 : class CPL_DLL Iterator
658 : {
659 : struct Private;
660 : std::unique_ptr<Private> m_poPrivate;
661 :
662 : public:
663 : using value_type = OGRLayer *; /**< value_type */
664 : using reference = OGRLayer *; /**< reference */
665 : using difference_type = void; /**< difference_type */
666 : using pointer = void; /**< pointer */
667 : using iterator_category =
668 : std::input_iterator_tag; /**< iterator_category */
669 :
670 : Iterator(); /**< Default constructor */
671 : Iterator(GDALDataset *poDS, bool bStart); /**< Constructor */
672 : Iterator(const Iterator &oOther); /**< Copy constructor */
673 : Iterator(Iterator &&oOther) noexcept; /**< Move constructor */
674 : ~Iterator(); /**< Destructor */
675 :
676 : Iterator &
677 : operator=(const Iterator &oOther); /**< Assignment operator */
678 : Iterator &operator=(
679 : Iterator &&oOther) noexcept; /**< Move assignment operator */
680 :
681 : value_type operator*() const; /**< Dereference operator */
682 : Iterator &operator++(); /**< Pre-increment operator */
683 : Iterator operator++(int); /**< Post-increment operator */
684 : bool operator!=(const Iterator &it)
685 : const; /**< Difference comparison operator */
686 : };
687 :
688 : Iterator begin() const;
689 : Iterator end() const;
690 :
691 : size_t size() const;
692 :
693 : OGRLayer *operator[](int iLayer);
694 : OGRLayer *operator[](size_t iLayer);
695 : OGRLayer *operator[](const char *pszLayername);
696 : };
697 :
698 : Layers GetLayers();
699 :
700 : /** Class returned by GetLayers() that acts as a range of layers.
701 : * @since GDAL 3.12
702 : */
703 : class CPL_DLL ConstLayers
704 : {
705 : private:
706 : friend class GDALDataset;
707 : const GDALDataset *m_poSelf;
708 :
709 17588 : CPL_INTERNAL explicit ConstLayers(const GDALDataset *poSelf)
710 17588 : : m_poSelf(poSelf)
711 : {
712 17588 : }
713 :
714 : public:
715 : /** Layer iterator.
716 : * @since GDAL 3.12
717 : */
718 35186 : class CPL_DLL Iterator
719 : {
720 : struct Private;
721 : std::unique_ptr<Private> m_poPrivate;
722 :
723 : public:
724 : using value_type = const OGRLayer *; /**< value_type */
725 : using reference = const OGRLayer *; /**< reference */
726 : using difference_type = void; /**< difference_type */
727 : using pointer = void; /**< pointer */
728 : using iterator_category =
729 : std::input_iterator_tag; /**< iterator_category */
730 :
731 : Iterator(); /**< Default constructor */
732 : Iterator(const GDALDataset *poDS, bool bStart); /**< Constructor */
733 : Iterator(const Iterator &oOther); /**< Copy constructor */
734 : Iterator(Iterator &&oOther) noexcept; /**< Move constructor */
735 : ~Iterator(); /**< Destructor */
736 :
737 : Iterator &
738 : operator=(const Iterator &oOther); /**< Assignment operator */
739 : Iterator &operator=(
740 : Iterator &&oOther) noexcept; /**< Move assignment operator */
741 :
742 : value_type operator*() const; /**< Dereference operator */
743 : Iterator &operator++(); /**< Pre-increment operator */
744 : Iterator operator++(int); /**< Post-increment operator */
745 : bool operator!=(const Iterator &it)
746 : const; /**< Difference comparison operator */
747 : };
748 :
749 : Iterator begin() const;
750 : Iterator end() const;
751 :
752 : size_t size() const;
753 :
754 : const OGRLayer *operator[](int iLayer);
755 : const OGRLayer *operator[](size_t iLayer);
756 : const OGRLayer *operator[](const char *pszLayername);
757 : };
758 :
759 : ConstLayers GetLayers() const;
760 :
761 : virtual OGRLayer *GetLayerByName(const char *);
762 :
763 : int GetLayerIndex(const char *pszName) const;
764 :
765 : virtual OGRErr DeleteLayer(int iLayer);
766 :
767 : virtual void ResetReading();
768 : virtual OGRFeature *GetNextFeature(OGRLayer **ppoBelongingLayer,
769 : double *pdfProgressPct,
770 : GDALProgressFunc pfnProgress,
771 : void *pProgressData);
772 :
773 : /** Class returned by GetFeatures() that act as a container for vector
774 : * features. */
775 : class CPL_DLL Features
776 : {
777 : private:
778 : friend class GDALDataset;
779 : GDALDataset *m_poSelf;
780 :
781 2 : CPL_INTERNAL explicit Features(GDALDataset *poSelf) : m_poSelf(poSelf)
782 : {
783 2 : }
784 :
785 4 : class CPL_DLL Iterator
786 : {
787 : struct Private;
788 : std::unique_ptr<Private> m_poPrivate;
789 :
790 : public:
791 : Iterator(GDALDataset *poDS, bool bStart);
792 : Iterator(const Iterator &oOther); // declared but not defined.
793 : // Needed for gcc 5.4 at least
794 : Iterator(Iterator &&oOther) noexcept; // declared but not defined.
795 : // Needed for gcc 5.4 at least
796 : ~Iterator();
797 : const FeatureLayerPair &operator*() const;
798 : Iterator &operator++();
799 : bool operator!=(const Iterator &it) const;
800 : };
801 :
802 : public:
803 : const Iterator begin() const;
804 :
805 : const Iterator end() const;
806 : };
807 :
808 : Features GetFeatures();
809 :
810 : virtual int TestCapability(const char *) const;
811 :
812 : virtual std::vector<std::string>
813 : GetFieldDomainNames(CSLConstList papszOptions = nullptr) const;
814 :
815 : virtual const OGRFieldDomain *GetFieldDomain(const std::string &name) const;
816 :
817 : virtual bool AddFieldDomain(std::unique_ptr<OGRFieldDomain> &&domain,
818 : std::string &failureReason);
819 :
820 : virtual bool DeleteFieldDomain(const std::string &name,
821 : std::string &failureReason);
822 :
823 : virtual bool UpdateFieldDomain(std::unique_ptr<OGRFieldDomain> &&domain,
824 : std::string &failureReason);
825 :
826 : virtual std::vector<std::string>
827 : GetRelationshipNames(CSLConstList papszOptions = nullptr) const;
828 :
829 : virtual const GDALRelationship *
830 : GetRelationship(const std::string &name) const;
831 :
832 : virtual bool
833 : AddRelationship(std::unique_ptr<GDALRelationship> &&relationship,
834 : std::string &failureReason);
835 :
836 : virtual bool DeleteRelationship(const std::string &name,
837 : std::string &failureReason);
838 :
839 : virtual bool
840 : UpdateRelationship(std::unique_ptr<GDALRelationship> &&relationship,
841 : std::string &failureReason);
842 :
843 : //! @cond Doxygen_Suppress
844 : OGRLayer *CreateLayer(const char *pszName);
845 :
846 : OGRLayer *CreateLayer(const char *pszName, std::nullptr_t);
847 : //! @endcond
848 :
849 : OGRLayer *CreateLayer(const char *pszName,
850 : const OGRSpatialReference *poSpatialRef,
851 : OGRwkbGeometryType eGType = wkbUnknown,
852 : CSLConstList papszOptions = nullptr);
853 :
854 : OGRLayer *CreateLayer(const char *pszName,
855 : const OGRGeomFieldDefn *poGeomFieldDefn,
856 : CSLConstList papszOptions = nullptr);
857 :
858 : virtual OGRLayer *CopyLayer(OGRLayer *poSrcLayer, const char *pszNewName,
859 : char **papszOptions = nullptr);
860 :
861 : virtual OGRStyleTable *GetStyleTable();
862 : virtual void SetStyleTableDirectly(OGRStyleTable *poStyleTable);
863 :
864 : virtual void SetStyleTable(OGRStyleTable *poStyleTable);
865 :
866 : virtual OGRLayer *ExecuteSQL(const char *pszStatement,
867 : OGRGeometry *poSpatialFilter,
868 : const char *pszDialect);
869 : virtual void ReleaseResultSet(OGRLayer *poResultsSet);
870 : virtual OGRErr AbortSQL();
871 :
872 : int GetRefCount() const;
873 : int GetSummaryRefCount() const;
874 : OGRErr Release();
875 :
876 : virtual OGRErr StartTransaction(int bForce = FALSE);
877 : virtual OGRErr CommitTransaction();
878 : virtual OGRErr RollbackTransaction();
879 :
880 : virtual std::shared_ptr<GDALGroup> GetRootGroup() const;
881 :
882 : static std::string BuildFilename(const char *pszFilename,
883 : const char *pszReferencePath,
884 : bool bRelativeToReferencePath);
885 :
886 : //! @cond Doxygen_Suppress
887 : static int IsGenericSQLDialect(const char *pszDialect);
888 :
889 : // Semi-public methods. Only to be used by in-tree drivers.
890 : GDALSQLParseInfo *
891 : BuildParseInfo(swq_select *psSelectInfo,
892 : swq_select_parse_options *poSelectParseOptions);
893 : static void DestroyParseInfo(GDALSQLParseInfo *psParseInfo);
894 : OGRLayer *ExecuteSQL(const char *pszStatement, OGRGeometry *poSpatialFilter,
895 : const char *pszDialect,
896 : swq_select_parse_options *poSelectParseOptions);
897 :
898 : static constexpr const char *const apszSpecialSubDatasetSyntax[] = {
899 : "NITF_IM:{ANY}:{FILENAME}", "PDF:{ANY}:{FILENAME}",
900 : "RASTERLITE:{FILENAME},{ANY}", "TILEDB:\"{FILENAME}\":{ANY}",
901 : "TILEDB:{FILENAME}:{ANY}"};
902 :
903 : //! @endcond
904 :
905 : protected:
906 : virtual OGRLayer *ICreateLayer(const char *pszName,
907 : const OGRGeomFieldDefn *poGeomFieldDefn,
908 : CSLConstList papszOptions);
909 :
910 : //! @cond Doxygen_Suppress
911 : OGRErr ProcessSQLCreateIndex(const char *);
912 : OGRErr ProcessSQLDropIndex(const char *);
913 : OGRErr ProcessSQLDropTable(const char *);
914 : OGRErr ProcessSQLAlterTableAddColumn(const char *);
915 : OGRErr ProcessSQLAlterTableDropColumn(const char *);
916 : OGRErr ProcessSQLAlterTableAlterColumn(const char *);
917 : OGRErr ProcessSQLAlterTableRenameColumn(const char *);
918 :
919 : OGRStyleTable *m_poStyleTable = nullptr;
920 :
921 : friend class GDALProxyPoolDataset;
922 : //! @endcond
923 :
924 : private:
925 : CPL_DISALLOW_COPY_ASSIGN(GDALDataset)
926 : };
927 :
928 : //! @cond Doxygen_Suppress
929 : struct CPL_DLL GDALDatasetUniquePtrDeleter
930 : {
931 101 : void operator()(GDALDataset *poDataset) const
932 : {
933 101 : GDALClose(poDataset);
934 101 : }
935 : };
936 :
937 : //! @endcond
938 :
939 : //! @cond Doxygen_Suppress
940 : struct CPL_DLL GDALDatasetUniquePtrReleaser
941 : {
942 2309 : void operator()(GDALDataset *poDataset) const
943 : {
944 2309 : if (poDataset)
945 2305 : poDataset->Release();
946 2309 : }
947 : };
948 :
949 : //! @endcond
950 :
951 : /** Unique pointer type for GDALDataset.
952 : * Appropriate for use on datasets open in non-shared mode and onto which
953 : * reference counter has not been manually modified.
954 : */
955 : using GDALDatasetUniquePtr =
956 : std::unique_ptr<GDALDataset, GDALDatasetUniquePtrDeleter>;
957 :
958 : #endif
|
