GDAL

gdal_driver.h
1/******************************************************************************
2 *
3 * Name: gdal_driver.h
4 * Project: GDAL Core
5 * Purpose: Declaration of GDALDriver 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 GDALDRIVER_H_INCLUDED
16#define GDALDRIVER_H_INCLUDED
17
18#include "cpl_port.h"
19#include "gdal.h"
20#include "gdal_majorobject.h"
21
22#include <vector>
23
24 class GDALAlgorithm;
25 class GDALDataset;
26 class GDALOpenInfo;
27
28/* ******************************************************************** */
29/* GDALIdentifyEnum */
30/* ******************************************************************** */
31
36 typedef enum
37{
40 GDAL_IDENTIFY_UNKNOWN = -1,
42 GDAL_IDENTIFY_FALSE = 0,
44 GDAL_IDENTIFY_TRUE = 1
45} GDALIdentifyEnum;
46
47/* ******************************************************************** */
48/* GDALDriver */
49/* ******************************************************************** */
50
62 class CPL_DLL GDALDriver : public GDALMajorObject
63{
64 public:
65 GDALDriver();
66 ~GDALDriver() override;
67
68 const char *GetMetadataItem(const char *pszName,
69 const char *pszDomain = "") override;
70
71 CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
72 const char *pszDomain = "") override;
73
74 /* -------------------------------------------------------------------- */
75 /* Public C++ methods. */
76 /* -------------------------------------------------------------------- */
77 GDALDataset *Create(const char *pszName, int nXSize, int nYSize, int nBands,
78 GDALDataType eType,
79 CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
80
81 GDALDataset *
82 CreateMultiDimensional(const char *pszName,
83 CSLConstList papszRootGroupOptions,
84 CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
85
86 CPLErr Delete(const char *pszName);
87 CPLErr Delete(GDALDataset *poDS, CSLConstList papszFileList);
88 CPLErr Rename(const char *pszNewName, const char *pszOldName);
89 CPLErr CopyFiles(const char *pszNewName, const char *pszOldName);
90
91 GDALDataset *CreateCopy(const char *, GDALDataset *, int,
92 CSLConstList papszOptions,
93 GDALProgressFunc pfnProgress,
94 void *pProgressData) CPL_WARN_UNUSED_RESULT;
95
96 bool CanVectorTranslateFrom(const char *pszDestName,
97 GDALDataset *poSourceDS,
98 CSLConstList papszVectorTranslateArguments,
99 char ***ppapszFailureReasons);
100
107 bool HasOpenOption(const char *pszOpenOptionName) const;
108
109 GDALDataset *
110 VectorTranslateFrom(const char *pszDestName, GDALDataset *poSourceDS,
111 CSLConstList papszVectorTranslateArguments,
112 GDALProgressFunc pfnProgress,
113 void *pProgressData) CPL_WARN_UNUSED_RESULT;
114
115 /* -------------------------------------------------------------------- */
116 /* The following are semiprivate, not intended to be accessed */
117 /* by anyone but the formats instantiating and populating the */
118 /* drivers. */
119 /* -------------------------------------------------------------------- */
121
122 // Not aimed at being used outside of GDAL. Use GDALDataset::Open() instead
123 GDALDataset *Open(GDALOpenInfo *poOpenInfo, bool bSetOpenOptions);
124
125 typedef GDALDataset *(*OpenCallback)(GDALOpenInfo *);
126
127 OpenCallback pfnOpen = nullptr;
128
129 virtual OpenCallback GetOpenCallback()
130 {
131 return pfnOpen;
132 }
133
134 typedef GDALDataset *(*CreateCallback)(const char *pszName, int nXSize,
135 int nYSize, int nBands,
136 GDALDataType eType,
137 char **papszOptions);
138
139 CreateCallback pfnCreate = nullptr;
140
141 virtual CreateCallback GetCreateCallback()
142 {
143 return pfnCreate;
144 }
145
146 GDALDataset *(*pfnCreateEx)(GDALDriver *, const char *pszName, int nXSize,
147 int nYSize, int nBands, GDALDataType eType,
148 char **papszOptions) = nullptr;
149
150 typedef GDALDataset *(*CreateMultiDimensionalCallback)(
151 const char *pszName, CSLConstList papszRootGroupOptions,
152 CSLConstList papszOptions);
153
154 CreateMultiDimensionalCallback pfnCreateMultiDimensional = nullptr;
155
156 virtual CreateMultiDimensionalCallback GetCreateMultiDimensionalCallback()
157 {
158 return pfnCreateMultiDimensional;
159 }
160
161 typedef CPLErr (*DeleteCallback)(const char *pszName);
162 DeleteCallback pfnDelete = nullptr;
163
164 virtual DeleteCallback GetDeleteCallback()
165 {
166 return pfnDelete;
167 }
168
169 typedef GDALDataset *(*CreateCopyCallback)(const char *, GDALDataset *, int,
170 char **,
171 GDALProgressFunc pfnProgress,
172 void *pProgressData);
173
174 CreateCopyCallback pfnCreateCopy = nullptr;
175
176 virtual CreateCopyCallback GetCreateCopyCallback()
177 {
178 return pfnCreateCopy;
179 }
180
181 void *pDriverData = nullptr;
182
183 void (*pfnUnloadDriver)(GDALDriver *) = nullptr;
184
193 int (*pfnIdentify)(GDALOpenInfo *) = nullptr;
194 int (*pfnIdentifyEx)(GDALDriver *, GDALOpenInfo *) = nullptr;
195
196 typedef CPLErr (*RenameCallback)(const char *pszNewName,
197 const char *pszOldName);
198 RenameCallback pfnRename = nullptr;
199
200 virtual RenameCallback GetRenameCallback()
201 {
202 return pfnRename;
203 }
204
205 typedef CPLErr (*CopyFilesCallback)(const char *pszNewName,
206 const char *pszOldName);
207 CopyFilesCallback pfnCopyFiles = nullptr;
208
209 virtual CopyFilesCallback GetCopyFilesCallback()
210 {
211 return pfnCopyFiles;
212 }
213
214 // Used for legacy OGR drivers, and Python drivers
215 GDALDataset *(*pfnOpenWithDriverArg)(GDALDriver *,
216 GDALOpenInfo *) = nullptr;
217
218 /* For legacy OGR drivers */
219 GDALDataset *(*pfnCreateVectorOnly)(GDALDriver *, const char *pszName,
220 char **papszOptions) = nullptr;
221 CPLErr (*pfnDeleteDataSource)(GDALDriver *, const char *pszName) = nullptr;
222
227 bool (*pfnCanVectorTranslateFrom)(
228 const char *pszDestName, GDALDataset *poSourceDS,
229 CSLConstList papszVectorTranslateArguments,
230 char ***ppapszFailureReasons) = nullptr;
231
236 GDALDataset *(*pfnVectorTranslateFrom)(
237 const char *pszDestName, GDALDataset *poSourceDS,
238 CSLConstList papszVectorTranslateArguments,
239 GDALProgressFunc pfnProgress, void *pProgressData) = nullptr;
240
245 GDALSubdatasetInfo *(*pfnGetSubdatasetInfoFunc)(const char *pszFileName) =
246 nullptr;
247
248 typedef GDALAlgorithm *(*InstantiateAlgorithmCallback)(
249 const std::vector<std::string> &aosPath);
250 InstantiateAlgorithmCallback pfnInstantiateAlgorithm = nullptr;
251
252 virtual InstantiateAlgorithmCallback GetInstantiateAlgorithmCallback()
253 {
254 return pfnInstantiateAlgorithm;
255 }
256
260 GDALAlgorithm *
261 InstantiateAlgorithm(const std::vector<std::string> &aosPath);
262
266 void DeclareAlgorithm(const std::vector<std::string> &aosPath);
267
269
270 /* -------------------------------------------------------------------- */
271 /* Helper methods. */
272 /* -------------------------------------------------------------------- */
274 GDALDataset *DefaultCreateCopy(const char *, GDALDataset *, int,
275 CSLConstList papszOptions,
276 GDALProgressFunc pfnProgress,
277 void *pProgressData) CPL_WARN_UNUSED_RESULT;
278
279 static CPLErr DefaultCreateCopyMultiDimensional(
280 GDALDataset *poSrcDS, GDALDataset *poDstDS, bool bStrict,
281 CSLConstList /*papszOptions*/, GDALProgressFunc pfnProgress,
282 void *pProgressData);
283
284 static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
285 int bStrict);
286 static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
287 int bStrict, CSLConstList papszOptions,
288 GDALProgressFunc pfnProgress,
289 void *pProgressData);
290
291 CPLErr QuietDeleteForCreateCopy(const char *pszFilename,
292 GDALDataset *poSrcDS);
293
295 static CPLErr QuietDelete(const char *pszName,
296 CSLConstList papszAllowedDrivers = nullptr);
297
299 static CPLErr DefaultRename(const char *pszNewName, const char *pszOldName);
300 static CPLErr DefaultCopyFiles(const char *pszNewName,
301 const char *pszOldName);
302 static void DefaultCopyMetadata(GDALDataset *poSrcDS, GDALDataset *poDstDS,
303 CSLConstList papszOptions,
304 CSLConstList papszExcludedDomains);
305
307
310 static inline GDALDriverH ToHandle(GDALDriver *poDriver)
311 {
312 return static_cast<GDALDriverH>(poDriver);
313 }
314
317 static inline GDALDriver *FromHandle(GDALDriverH hDriver)
318 {
319 return static_cast<GDALDriver *>(hDriver);
320 }
321
322 private:
323 CPL_DISALLOW_COPY_ASSIGN(GDALDriver)
324};
325
326// Macro used so that Identify and driver metadata methods in drivers built
327// as plugin can be duplicated in libgdal core and in the driver under different
328// names
329#ifdef PLUGIN_FILENAME
330#define PLUGIN_SYMBOL_NAME(x) GDAL_core_##x
331#else
332#define PLUGIN_SYMBOL_NAME(x) GDAL_driver_##x
333#endif
334
335#endif
GDALAlgorithm
GDAL algorithm.
Definition gdalalgorithm_cpp.h:2261
GDALDataset
A set of associated raster bands, usually from one file.
Definition gdal_dataset.h:76
GDALDriver
Format specific driver.
Definition gdal_driver.h:63
GDALDriver::FromHandle
static GDALDriver * FromHandle(GDALDriverH hDriver)
Convert a GDALDriverH to a GDALDriver*.
Definition gdal_driver.h:317
GDALDriver::ToHandle
static GDALDriverH ToHandle(GDALDriver *poDriver)
Convert a GDALDriver* to a GDALDriverH.
Definition gdal_driver.h:310
GDALMajorObject
Object with metadata.
Definition gdal_majorobject.h:43
GDALMajorObject::SetMetadataItem
virtual CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain="")
Set single metadata item.
Definition gdalmajorobject.cpp:366
GDALMajorObject::GetMetadataItem
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition gdalmajorobject.cpp:322
GDALOpenInfo
Class for dataset open functions.
Definition gdal_openinfo.h:28
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
cpl_port.h
Core portability definitions for CPL.
CPL_DISALLOW_COPY_ASSIGN
#define CPL_DISALLOW_COPY_ASSIGN(ClassName)
Helper to remove the copy and assignment constructors so that the compiler will not generate the defa...
Definition cpl_port.h:936
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition cpl_port.h:1087
CPL_WARN_UNUSED_RESULT
#define CPL_WARN_UNUSED_RESULT
Qualifier to warn when the return value of a function is not used.
Definition cpl_port.h:870
gdal.h
Public (C callable) GDAL entry points.
GDALDataType
GDALDataType
Definition gdal.h:48
GDALDriverH
void * GDALDriverH
Opaque type used for the C bindings of the C++ GDALDriver class.
Definition gdal_fwd.h:51
GDALSubdatasetInfo
The GDALSubdatasetInfo abstract class provides methods to extract and manipulate subdataset informati...
Definition gdalsubdatasetinfo.h:27