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      412275 : 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             :     /**
     110             :      * \brief Returns TRUE if the given layer creation option is supported by the driver.
     111             :      * @param pszOptionName name of the layer creation option to be checked
     112             :      * @return TRUE if the driver supports the layer creation option
     113             :      * @since GDAL 3.13
     114             :      */
     115             :     bool HasLayerCreationOption(const char *pszOptionName) const;
     116             : 
     117             :     GDALDataset *
     118             :     VectorTranslateFrom(const char *pszDestName, GDALDataset *poSourceDS,
     119             :                         CSLConstList papszVectorTranslateArguments,
     120             :                         GDALProgressFunc pfnProgress,
     121             :                         void *pProgressData) CPL_WARN_UNUSED_RESULT;
     122             : 
     123             :     /* -------------------------------------------------------------------- */
     124             :     /*      The following are semiprivate, not intended to be accessed      */
     125             :     /*      by anyone but the formats instantiating and populating the      */
     126             :     /*      drivers.                                                        */
     127             :     /* -------------------------------------------------------------------- */
     128             :     //! @cond Doxygen_Suppress
     129             : 
     130             :     // Not aimed at being used outside of GDAL. Use GDALDataset::Open() instead
     131             :     GDALDataset *Open(GDALOpenInfo *poOpenInfo, bool bSetOpenOptions);
     132             : 
     133             :     typedef GDALDataset *(*OpenCallback)(GDALOpenInfo *);
     134             : 
     135             :     OpenCallback pfnOpen = nullptr;
     136             : 
     137      514111 :     virtual OpenCallback GetOpenCallback()
     138             :     {
     139      514111 :         return pfnOpen;
     140             :     }
     141             : 
     142             :     typedef GDALDataset *(*CreateCallback)(const char *pszName, int nXSize,
     143             :                                            int nYSize, int nBands,
     144             :                                            GDALDataType eType,
     145             :                                            CSLConstList papszOptions);
     146             : 
     147             :     CreateCallback pfnCreate = nullptr;
     148             : 
     149       25401 :     virtual CreateCallback GetCreateCallback()
     150             :     {
     151       25401 :         return pfnCreate;
     152             :     }
     153             : 
     154             :     GDALDataset *(*pfnCreateEx)(GDALDriver *, const char *pszName, int nXSize,
     155             :                                 int nYSize, int nBands, GDALDataType eType,
     156             :                                 CSLConstList papszOptions) = nullptr;
     157             : 
     158             :     typedef GDALDataset *(*CreateMultiDimensionalCallback)(
     159             :         const char *pszName, CSLConstList papszRootGroupOptions,
     160             :         CSLConstList papszOptions);
     161             : 
     162             :     CreateMultiDimensionalCallback pfnCreateMultiDimensional = nullptr;
     163             : 
     164         566 :     virtual CreateMultiDimensionalCallback GetCreateMultiDimensionalCallback()
     165             :     {
     166         566 :         return pfnCreateMultiDimensional;
     167             :     }
     168             : 
     169             :     typedef CPLErr (*DeleteCallback)(const char *pszName);
     170             :     DeleteCallback pfnDelete = nullptr;
     171             : 
     172        5250 :     virtual DeleteCallback GetDeleteCallback()
     173             :     {
     174        5250 :         return pfnDelete;
     175             :     }
     176             : 
     177             :     typedef GDALDataset *(*CreateCopyCallback)(const char *, GDALDataset *, int,
     178             :                                                CSLConstList,
     179             :                                                GDALProgressFunc pfnProgress,
     180             :                                                void *pProgressData);
     181             : 
     182             :     CreateCopyCallback pfnCreateCopy = nullptr;
     183             : 
     184       11646 :     virtual CreateCopyCallback GetCreateCopyCallback()
     185             :     {
     186       11646 :         return pfnCreateCopy;
     187             :     }
     188             : 
     189             :     void *pDriverData = nullptr;
     190             : 
     191             :     void (*pfnUnloadDriver)(GDALDriver *) = nullptr;
     192             : 
     193             :     /** Identify() if the file is recognized or not by the driver.
     194             : 
     195             :        Return GDAL_IDENTIFY_TRUE (1) if the passed file is certainly recognized
     196             :        by the driver. Return GDAL_IDENTIFY_FALSE (0) if the passed file is
     197             :        certainly NOT recognized by the driver. Return GDAL_IDENTIFY_UNKNOWN (-1)
     198             :        if the passed file may be or may not be recognized by the driver, and
     199             :        that a potentially costly test must be done with pfnOpen.
     200             :     */
     201             :     int (*pfnIdentify)(GDALOpenInfo *) = nullptr;
     202             :     int (*pfnIdentifyEx)(GDALDriver *, GDALOpenInfo *) = nullptr;
     203             : 
     204             :     typedef CPLErr (*RenameCallback)(const char *pszNewName,
     205             :                                      const char *pszOldName);
     206             :     RenameCallback pfnRename = nullptr;
     207             : 
     208         177 :     virtual RenameCallback GetRenameCallback()
     209             :     {
     210         177 :         return pfnRename;
     211             :     }
     212             : 
     213             :     typedef CPLErr (*CopyFilesCallback)(const char *pszNewName,
     214             :                                         const char *pszOldName);
     215             :     CopyFilesCallback pfnCopyFiles = nullptr;
     216             : 
     217          14 :     virtual CopyFilesCallback GetCopyFilesCallback()
     218             :     {
     219          14 :         return pfnCopyFiles;
     220             :     }
     221             : 
     222             :     // Used for legacy OGR drivers, and Python drivers
     223             :     GDALDataset *(*pfnOpenWithDriverArg)(GDALDriver *,
     224             :                                          GDALOpenInfo *) = nullptr;
     225             : 
     226             :     /* For legacy OGR drivers */
     227             :     GDALDataset *(*pfnCreateVectorOnly)(GDALDriver *, const char *pszName,
     228             :                                         CSLConstList papszOptions) = nullptr;
     229             :     CPLErr (*pfnDeleteDataSource)(GDALDriver *, const char *pszName) = nullptr;
     230             : 
     231             :     /** Whether pfnVectorTranslateFrom() can be run given the source dataset
     232             :      * and the non-positional arguments of GDALVectorTranslate() stored
     233             :      * in papszVectorTranslateArguments.
     234             :      */
     235             :     bool (*pfnCanVectorTranslateFrom)(
     236             :         const char *pszDestName, GDALDataset *poSourceDS,
     237             :         CSLConstList papszVectorTranslateArguments,
     238             :         char ***ppapszFailureReasons) = nullptr;
     239             : 
     240             :     /** Creates a copy from the specified source dataset, using the
     241             :      * non-positional arguments of GDALVectorTranslate() stored
     242             :      * in papszVectorTranslateArguments.
     243             :      */
     244             :     GDALDataset *(*pfnVectorTranslateFrom)(
     245             :         const char *pszDestName, GDALDataset *poSourceDS,
     246             :         CSLConstList papszVectorTranslateArguments,
     247             :         GDALProgressFunc pfnProgress, void *pProgressData) = nullptr;
     248             : 
     249             :     /**
     250             :      * Returns a (possibly null) pointer to the Subdataset informational function
     251             :      * from the subdataset file name.
     252             :      */
     253             :     GDALSubdatasetInfo *(*pfnGetSubdatasetInfoFunc)(const char *pszFileName) =
     254             :         nullptr;
     255             : 
     256             :     typedef GDALAlgorithm *(*InstantiateAlgorithmCallback)(
     257             :         const std::vector<std::string> &aosPath);
     258             :     InstantiateAlgorithmCallback pfnInstantiateAlgorithm = nullptr;
     259             : 
     260        1127 :     virtual InstantiateAlgorithmCallback GetInstantiateAlgorithmCallback()
     261             :     {
     262        1127 :         return pfnInstantiateAlgorithm;
     263             :     }
     264             : 
     265             :     /** Instantiate an algorithm by its full path (omitting leading "gdal").
     266             :      * For example {"driver", "pdf", "list-layers"}
     267             :      */
     268             :     GDALAlgorithm *
     269             :     InstantiateAlgorithm(const std::vector<std::string> &aosPath);
     270             : 
     271             :     /** Declare an algorithm by its full path (omitting leading "gdal").
     272             :      * For example {"driver", "pdf", "list-layers"}
     273             :      */
     274             :     void DeclareAlgorithm(const std::vector<std::string> &aosPath);
     275             : 
     276             :     /** Callback to clear driver-specific in-memory caches.
     277             :      * Called by GDALClearMemoryCaches().
     278             :      */
     279             :     void (*pfnClearCaches)(GDALDriver *) = nullptr;
     280             : 
     281             :     //! @endcond
     282             : 
     283             :     /* -------------------------------------------------------------------- */
     284             :     /*      Helper methods.                                                 */
     285             :     /* -------------------------------------------------------------------- */
     286             :     //! @cond Doxygen_Suppress
     287             :     GDALDataset *DefaultCreateCopy(const char *, GDALDataset *, int,
     288             :                                    CSLConstList papszOptions,
     289             :                                    GDALProgressFunc pfnProgress,
     290             :                                    void *pProgressData) CPL_WARN_UNUSED_RESULT;
     291             : 
     292             :     static CPLErr DefaultCreateCopyMultiDimensional(
     293             :         GDALDataset *poSrcDS, GDALDataset *poDstDS, bool bStrict,
     294             :         CSLConstList /*papszOptions*/, GDALProgressFunc pfnProgress,
     295             :         void *pProgressData);
     296             : 
     297             :     static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
     298             :                                    int bStrict);
     299             :     static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
     300             :                                    int bStrict, CSLConstList papszOptions,
     301             :                                    GDALProgressFunc pfnProgress,
     302             :                                    void *pProgressData);
     303             : 
     304             :     CPLErr QuietDeleteForCreateCopy(const char *pszFilename,
     305             :                                     GDALDataset *poSrcDS);
     306             : 
     307             :     //! @endcond
     308             :     static CPLErr QuietDelete(const char *pszName,
     309             :                               CSLConstList papszAllowedDrivers = nullptr);
     310             : 
     311             :     //! @cond Doxygen_Suppress
     312             :     static CPLErr DefaultRename(const char *pszNewName, const char *pszOldName);
     313             :     static CPLErr DefaultCopyFiles(const char *pszNewName,
     314             :                                    const char *pszOldName);
     315             :     static void DefaultCopyMetadata(GDALDataset *poSrcDS, GDALDataset *poDstDS,
     316             :                                     CSLConstList papszOptions,
     317             :                                     CSLConstList papszExcludedDomains);
     318             : 
     319             :     //! @endcond
     320             : 
     321             :     /** Convert a GDALDriver* to a GDALDriverH.
     322             :      */
     323      194846 :     static inline GDALDriverH ToHandle(GDALDriver *poDriver)
     324             :     {
     325      194846 :         return static_cast<GDALDriverH>(poDriver);
     326             :     }
     327             : 
     328             :     /** Convert a GDALDriverH to a GDALDriver*.
     329             :      */
     330     8957763 :     static inline GDALDriver *FromHandle(GDALDriverH hDriver)
     331             :     {
     332     8957763 :         return static_cast<GDALDriver *>(hDriver);
     333             :     }
     334             : 
     335             :   private:
     336             :     CPL_DISALLOW_COPY_ASSIGN(GDALDriver)
     337             : };
     338             : 
     339             : // Macro used so that Identify and driver metadata methods in drivers built
     340             : // as plugin can be duplicated in libgdal core and in the driver under different
     341             : // names
     342             : #ifdef PLUGIN_FILENAME
     343             : #define PLUGIN_SYMBOL_NAME(x) GDAL_core_##x
     344             : #else
     345             : #define PLUGIN_SYMBOL_NAME(x) GDAL_driver_##x
     346             : #endif
     347             : 
     348             : #endif