Line data Source code
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 :
32 : /**
33 : * Enumeration used by GDALDriver::pfnIdentify().
34 : *
35 : */
36 : typedef enum
37 : {
38 : /** Identify could not determine if the file is recognized or not by the
39 : probed driver. */
40 : GDAL_IDENTIFY_UNKNOWN = -1,
41 : /** Identify determined the file is not recognized by the probed driver. */
42 : GDAL_IDENTIFY_FALSE = 0,
43 : /** Identify determined the file is recognized by the probed driver. */
44 : GDAL_IDENTIFY_TRUE = 1
45 : } GDALIdentifyEnum;
46 :
47 : /* ******************************************************************** */
48 : /* GDALDriver */
49 : /* ******************************************************************** */
50 :
51 : /**
52 : * \brief Format specific driver.
53 : *
54 : * An instance of this class is created for each supported format, and
55 : * manages information about the format.
56 : *
57 : * This roughly corresponds to a file format, though some
58 : * drivers may be gateways to many formats through a secondary
59 : * multi-library.
60 : */
61 :
62 400050 : 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 :
101 : /**
102 : * \brief Returns TRUE if the given open option is supported by the driver.
103 : * @param pszOpenOptionName name of the open option to be checked
104 : * @return TRUE if the driver supports the open option
105 : * @since GDAL 3.11
106 : */
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 : /* -------------------------------------------------------------------- */
120 : //! @cond Doxygen_Suppress
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 453586 : virtual OpenCallback GetOpenCallback()
130 : {
131 453586 : 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 23851 : virtual CreateCallback GetCreateCallback()
142 : {
143 23851 : 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 523 : virtual CreateMultiDimensionalCallback GetCreateMultiDimensionalCallback()
157 : {
158 523 : return pfnCreateMultiDimensional;
159 : }
160 :
161 : typedef CPLErr (*DeleteCallback)(const char *pszName);
162 : DeleteCallback pfnDelete = nullptr;
163 :
164 5226 : virtual DeleteCallback GetDeleteCallback()
165 : {
166 5226 : 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 11135 : virtual CreateCopyCallback GetCreateCopyCallback()
177 : {
178 11135 : return pfnCreateCopy;
179 : }
180 :
181 : void *pDriverData = nullptr;
182 :
183 : void (*pfnUnloadDriver)(GDALDriver *) = nullptr;
184 :
185 : /** Identify() if the file is recognized or not by the driver.
186 :
187 : Return GDAL_IDENTIFY_TRUE (1) if the passed file is certainly recognized
188 : by the driver. Return GDAL_IDENTIFY_FALSE (0) if the passed file is
189 : certainly NOT recognized by the driver. Return GDAL_IDENTIFY_UNKNOWN (-1)
190 : if the passed file may be or may not be recognized by the driver, and
191 : that a potentially costly test must be done with pfnOpen.
192 : */
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 175 : virtual RenameCallback GetRenameCallback()
201 : {
202 175 : return pfnRename;
203 : }
204 :
205 : typedef CPLErr (*CopyFilesCallback)(const char *pszNewName,
206 : const char *pszOldName);
207 : CopyFilesCallback pfnCopyFiles = nullptr;
208 :
209 12 : virtual CopyFilesCallback GetCopyFilesCallback()
210 : {
211 12 : 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 :
223 : /** Whether pfnVectorTranslateFrom() can be run given the source dataset
224 : * and the non-positional arguments of GDALVectorTranslate() stored
225 : * in papszVectorTranslateArguments.
226 : */
227 : bool (*pfnCanVectorTranslateFrom)(
228 : const char *pszDestName, GDALDataset *poSourceDS,
229 : CSLConstList papszVectorTranslateArguments,
230 : char ***ppapszFailureReasons) = nullptr;
231 :
232 : /** Creates a copy from the specified source dataset, using the
233 : * non-positional arguments of GDALVectorTranslate() stored
234 : * in papszVectorTranslateArguments.
235 : */
236 : GDALDataset *(*pfnVectorTranslateFrom)(
237 : const char *pszDestName, GDALDataset *poSourceDS,
238 : CSLConstList papszVectorTranslateArguments,
239 : GDALProgressFunc pfnProgress, void *pProgressData) = nullptr;
240 :
241 : /**
242 : * Returns a (possibly null) pointer to the Subdataset informational function
243 : * from the subdataset file name.
244 : */
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 56 : virtual InstantiateAlgorithmCallback GetInstantiateAlgorithmCallback()
253 : {
254 56 : return pfnInstantiateAlgorithm;
255 : }
256 :
257 : /** Instantiate an algorithm by its full path (omitting leading "gdal").
258 : * For example {"driver", "pdf", "list-layers"}
259 : */
260 : GDALAlgorithm *
261 : InstantiateAlgorithm(const std::vector<std::string> &aosPath);
262 :
263 : /** Declare an algorithm by its full path (omitting leading "gdal").
264 : * For example {"driver", "pdf", "list-layers"}
265 : */
266 : void DeclareAlgorithm(const std::vector<std::string> &aosPath);
267 :
268 : //! @endcond
269 :
270 : /* -------------------------------------------------------------------- */
271 : /* Helper methods. */
272 : /* -------------------------------------------------------------------- */
273 : //! @cond Doxygen_Suppress
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 :
294 : //! @endcond
295 : static CPLErr QuietDelete(const char *pszName,
296 : CSLConstList papszAllowedDrivers = nullptr);
297 :
298 : //! @cond Doxygen_Suppress
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 :
306 : //! @endcond
307 :
308 : /** Convert a GDALDriver* to a GDALDriverH.
309 : */
310 175853 : static inline GDALDriverH ToHandle(GDALDriver *poDriver)
311 : {
312 175853 : return static_cast<GDALDriverH>(poDriver);
313 : }
314 :
315 : /** Convert a GDALDriverH to a GDALDriver*.
316 : */
317 3970323 : static inline GDALDriver *FromHandle(GDALDriverH hDriver)
318 : {
319 3970323 : 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
|