gdal_driver.h

/******************************************************************************
 *
 * Name:     gdal_driver.h
 * Project:  GDAL Core
 * Purpose:  Declaration of GDALDriver class
 * Author:   Frank Warmerdam, warmerdam@pobox.com
 *
 ******************************************************************************
 * Copyright (c) 1998, Frank Warmerdam
 * Copyright (c) 2007-2014, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/
 
#ifndef GDALDRIVER_H_INCLUDED
#define GDALDRIVER_H_INCLUDED
 
#include "cpl_port.h"
#include "gdal.h"
#include "gdal_majorobject.h"
 
#include <vector>
 
class GDALAlgorithm;
class GDALDataset;
class GDALOpenInfo;
 
/* ******************************************************************** */
/*                          GDALIdentifyEnum                            */
/* ******************************************************************** */

typedef enum
{
    GDAL_IDENTIFY_UNKNOWN = -1,
    GDAL_IDENTIFY_FALSE = 0,
    GDAL_IDENTIFY_TRUE = 1
} GDALIdentifyEnum;
 
/* ******************************************************************** */
/*                              GDALDriver                              */
/* ******************************************************************** */

 
class CPL_DLL GDALDriver : public GDALMajorObject
{
  public:
    GDALDriver();
    ~GDALDriver() override;
 
    const char *GetMetadataItem(const char *pszName,
                                const char *pszDomain = "") override;
 
    CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
                           const char *pszDomain = "") override;
 
    /* -------------------------------------------------------------------- */
    /*      Public C++ methods.                                             */
    /* -------------------------------------------------------------------- */
    GDALDataset *Create(const char *pszName, int nXSize, int nYSize, int nBands,
                        GDALDataType eType,
                        CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
 
    GDALDataset *
    CreateMultiDimensional(const char *pszName,
                           CSLConstList papszRootGroupOptions,
                           CSLConstList papszOptions) CPL_WARN_UNUSED_RESULT;
 
    CPLErr Delete(const char *pszName);
    CPLErr Delete(GDALDataset *poDS, CSLConstList papszFileList);
    CPLErr Rename(const char *pszNewName, const char *pszOldName);
    CPLErr CopyFiles(const char *pszNewName, const char *pszOldName);
 
    GDALDataset *CreateCopy(const char *, GDALDataset *, int,
                            CSLConstList papszOptions,
                            GDALProgressFunc pfnProgress,
                            void *pProgressData) CPL_WARN_UNUSED_RESULT;
 
    bool CanVectorTranslateFrom(const char *pszDestName,
                                GDALDataset *poSourceDS,
                                CSLConstList papszVectorTranslateArguments,
                                char ***ppapszFailureReasons);

    bool HasOpenOption(const char *pszOpenOptionName) const;

    bool HasLayerCreationOption(const char *pszOptionName) const;
 
    GDALDataset *
    VectorTranslateFrom(const char *pszDestName, GDALDataset *poSourceDS,
                        CSLConstList papszVectorTranslateArguments,
                        GDALProgressFunc pfnProgress,
                        void *pProgressData) CPL_WARN_UNUSED_RESULT;
 
    /* -------------------------------------------------------------------- */
    /*      The following are semiprivate, not intended to be accessed      */
    /*      by anyone but the formats instantiating and populating the      */
    /*      drivers.                                                        */
    /* -------------------------------------------------------------------- */
 
    // Not aimed at being used outside of GDAL. Use GDALDataset::Open() instead
    GDALDataset *Open(GDALOpenInfo *poOpenInfo, bool bSetOpenOptions);
 
    typedef GDALDataset *(*OpenCallback)(GDALOpenInfo *);
 
    OpenCallback pfnOpen = nullptr;
 
    virtual OpenCallback GetOpenCallback()
    {
        return pfnOpen;
    }
 
    typedef GDALDataset *(*CreateCallback)(const char *pszName, int nXSize,
                                           int nYSize, int nBands,
                                           GDALDataType eType,
                                           CSLConstList papszOptions);
 
    CreateCallback pfnCreate = nullptr;
 
    virtual CreateCallback GetCreateCallback()
    {
        return pfnCreate;
    }
 
    GDALDataset *(*pfnCreateEx)(GDALDriver *, const char *pszName, int nXSize,
                                int nYSize, int nBands, GDALDataType eType,
                                CSLConstList papszOptions) = nullptr;
 
    typedef GDALDataset *(*CreateMultiDimensionalCallback)(
        const char *pszName, CSLConstList papszRootGroupOptions,
        CSLConstList papszOptions);
 
    CreateMultiDimensionalCallback pfnCreateMultiDimensional = nullptr;
 
    virtual CreateMultiDimensionalCallback GetCreateMultiDimensionalCallback()
    {
        return pfnCreateMultiDimensional;
    }
 
    typedef CPLErr (*DeleteCallback)(const char *pszName);
    DeleteCallback pfnDelete = nullptr;
 
    virtual DeleteCallback GetDeleteCallback()
    {
        return pfnDelete;
    }
 
    typedef GDALDataset *(*CreateCopyCallback)(const char *, GDALDataset *, int,
                                               CSLConstList,
                                               GDALProgressFunc pfnProgress,
                                               void *pProgressData);
 
    CreateCopyCallback pfnCreateCopy = nullptr;
 
    virtual CreateCopyCallback GetCreateCopyCallback()
    {
        return pfnCreateCopy;
    }
 
    void *pDriverData = nullptr;
 
    void (*pfnUnloadDriver)(GDALDriver *) = nullptr;

    int (*pfnIdentify)(GDALOpenInfo *) = nullptr;
    int (*pfnIdentifyEx)(GDALDriver *, GDALOpenInfo *) = nullptr;
 
    typedef CPLErr (*RenameCallback)(const char *pszNewName,
                                     const char *pszOldName);
    RenameCallback pfnRename = nullptr;
 
    virtual RenameCallback GetRenameCallback()
    {
        return pfnRename;
    }
 
    typedef CPLErr (*CopyFilesCallback)(const char *pszNewName,
                                        const char *pszOldName);
    CopyFilesCallback pfnCopyFiles = nullptr;
 
    virtual CopyFilesCallback GetCopyFilesCallback()
    {
        return pfnCopyFiles;
    }
 
    // Used for legacy OGR drivers, and Python drivers
    GDALDataset *(*pfnOpenWithDriverArg)(GDALDriver *,
                                         GDALOpenInfo *) = nullptr;
 
    /* For legacy OGR drivers */
    GDALDataset *(*pfnCreateVectorOnly)(GDALDriver *, const char *pszName,
                                        CSLConstList papszOptions) = nullptr;
    CPLErr (*pfnDeleteDataSource)(GDALDriver *, const char *pszName) = nullptr;

    bool (*pfnCanVectorTranslateFrom)(
        const char *pszDestName, GDALDataset *poSourceDS,
        CSLConstList papszVectorTranslateArguments,
        char ***ppapszFailureReasons) = nullptr;

    GDALDataset *(*pfnVectorTranslateFrom)(
        const char *pszDestName, GDALDataset *poSourceDS,
        CSLConstList papszVectorTranslateArguments,
        GDALProgressFunc pfnProgress, void *pProgressData) = nullptr;

    GDALSubdatasetInfo *(*pfnGetSubdatasetInfoFunc)(const char *pszFileName) =
        nullptr;
 
    typedef GDALAlgorithm *(*InstantiateAlgorithmCallback)(
        const std::vector<std::string> &aosPath);
    InstantiateAlgorithmCallback pfnInstantiateAlgorithm = nullptr;
 
    virtual InstantiateAlgorithmCallback GetInstantiateAlgorithmCallback()
    {
        return pfnInstantiateAlgorithm;
    }

    GDALAlgorithm *
    InstantiateAlgorithm(const std::vector<std::string> &aosPath);

    void DeclareAlgorithm(const std::vector<std::string> &aosPath);

    void (*pfnClearCaches)(GDALDriver *) = nullptr;

 
    /* -------------------------------------------------------------------- */
    /*      Helper methods.                                                 */
    /* -------------------------------------------------------------------- */
    GDALDataset *DefaultCreateCopy(const char *, GDALDataset *, int,
                                   CSLConstList papszOptions,
                                   GDALProgressFunc pfnProgress,
                                   void *pProgressData) CPL_WARN_UNUSED_RESULT;
 
    static CPLErr DefaultCreateCopyMultiDimensional(
        GDALDataset *poSrcDS, GDALDataset *poDstDS, bool bStrict,
        CSLConstList /*papszOptions*/, GDALProgressFunc pfnProgress,
        void *pProgressData);
 
    static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
                                   int bStrict);
    static CPLErr DefaultCopyMasks(GDALDataset *poSrcDS, GDALDataset *poDstDS,
                                   int bStrict, CSLConstList papszOptions,
                                   GDALProgressFunc pfnProgress,
                                   void *pProgressData);
 
    CPLErr QuietDeleteForCreateCopy(const char *pszFilename,
                                    GDALDataset *poSrcDS);

    static CPLErr QuietDelete(const char *pszName,
                              CSLConstList papszAllowedDrivers = nullptr);

    static CPLErr DefaultRename(const char *pszNewName, const char *pszOldName);
    static CPLErr DefaultCopyFiles(const char *pszNewName,
                                   const char *pszOldName);
    static void DefaultCopyMetadata(GDALDataset *poSrcDS, GDALDataset *poDstDS,
                                    CSLConstList papszOptions,
                                    CSLConstList papszExcludedDomains);


    static inline GDALDriverH ToHandle(GDALDriver *poDriver)
    {
        return static_cast<GDALDriverH>(poDriver);
    }

    static inline GDALDriver *FromHandle(GDALDriverH hDriver)
    {
        return static_cast<GDALDriver *>(hDriver);
    }
 
  private:
    CPL_DISALLOW_COPY_ASSIGN(GDALDriver)
};
 
// Macro used so that Identify and driver metadata methods in drivers built
// as plugin can be duplicated in libgdal core and in the driver under different
// names
#ifdef PLUGIN_FILENAME
#define PLUGIN_SYMBOL_NAME(x) GDAL_core_##x
#else
#define PLUGIN_SYMBOL_NAME(x) GDAL_driver_##x
#endif
 
#endif