/******************************************************************************
 *
 * 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                            */
/* ******************************************************************** */

/**
 * Enumeration used by GDALDriver::pfnIdentify().
 *
 */
typedef enum
{
    /** Identify could not determine if the file is recognized or not by the
       probed driver. */
    GDAL_IDENTIFY_UNKNOWN = -1,
    /** Identify determined the file is not recognized by the probed driver. */
    GDAL_IDENTIFY_FALSE = 0,
    /** Identify determined the file is recognized by the probed driver. */
    GDAL_IDENTIFY_TRUE = 1
} GDALIdentifyEnum;

/* ******************************************************************** */
/*                              GDALDriver                              */
/* ******************************************************************** */

/**
 * \brief Format specific driver.
 *
 * An instance of this class is created for each supported format, and
 * manages information about the format.
 *
 * This roughly corresponds to a file format, though some
 * drivers may be gateways to many formats through a secondary
 * multi-library.
 */

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);

    /**
     * \brief Returns TRUE if the given open option is supported by the driver.
     * @param pszOpenOptionName name of the open option to be checked
     * @return TRUE if the driver supports the open option
     * @since GDAL 3.11
     */
    bool HasOpenOption(const char *pszOpenOptionName) const;

    /**
     * \brief Returns TRUE if the given layer creation option is supported by the driver.
     * @param pszOptionName name of the layer creation option to be checked
     * @return TRUE if the driver supports the layer creation option
     * @since GDAL 3.13
     */
    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.                                                        */
    /* -------------------------------------------------------------------- */
    //! @cond Doxygen_Suppress

    // 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;

    /** Identify() if the file is recognized or not by the driver.

       Return GDAL_IDENTIFY_TRUE (1) if the passed file is certainly recognized
       by the driver. Return GDAL_IDENTIFY_FALSE (0) if the passed file is
       certainly NOT recognized by the driver. Return GDAL_IDENTIFY_UNKNOWN (-1)
       if the passed file may be or may not be recognized by the driver, and
       that a potentially costly test must be done with pfnOpen.
    */
    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;

    /** Whether pfnVectorTranslateFrom() can be run given the source dataset
     * and the non-positional arguments of GDALVectorTranslate() stored
     * in papszVectorTranslateArguments.
     */
    bool (*pfnCanVectorTranslateFrom)(
        const char *pszDestName, GDALDataset *poSourceDS,
        CSLConstList papszVectorTranslateArguments,
        char ***ppapszFailureReasons) = nullptr;

    /** Creates a copy from the specified source dataset, using the
     * non-positional arguments of GDALVectorTranslate() stored
     * in papszVectorTranslateArguments.
     */
    GDALDataset *(*pfnVectorTranslateFrom)(
        const char *pszDestName, GDALDataset *poSourceDS,
        CSLConstList papszVectorTranslateArguments,
        GDALProgressFunc pfnProgress, void *pProgressData) = nullptr;

    /**
     * Returns a (possibly null) pointer to the Subdataset informational function
     * from the subdataset file name.
     */
    GDALSubdatasetInfo *(*pfnGetSubdatasetInfoFunc)(const char *pszFileName) =
        nullptr;

    typedef GDALAlgorithm *(*InstantiateAlgorithmCallback)(
        const std::vector<std::string> &aosPath);
    InstantiateAlgorithmCallback pfnInstantiateAlgorithm = nullptr;

    virtual InstantiateAlgorithmCallback GetInstantiateAlgorithmCallback()
    {
        return pfnInstantiateAlgorithm;
    }

    /** Instantiate an algorithm by its full path (omitting leading "gdal").
     * For example {"driver", "pdf", "list-layers"}
     */
    GDALAlgorithm *
    InstantiateAlgorithm(const std::vector<std::string> &aosPath);

    /** Declare an algorithm by its full path (omitting leading "gdal").
     * For example {"driver", "pdf", "list-layers"}
     */
    void DeclareAlgorithm(const std::vector<std::string> &aosPath);

    /** Callback to clear driver-specific in-memory caches.
     * Called by GDALClearMemoryCaches().
     */
    void (*pfnClearCaches)(GDALDriver *) = nullptr;

    //! @endcond

    /* -------------------------------------------------------------------- */
    /*      Helper methods.                                                 */
    /* -------------------------------------------------------------------- */
    //! @cond Doxygen_Suppress
    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);

    //! @endcond
    static CPLErr QuietDelete(const char *pszName,
                              CSLConstList papszAllowedDrivers = nullptr);

    //! @cond Doxygen_Suppress
    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);

    //! @endcond

    /** Convert a GDALDriver* to a GDALDriverH.
     */
    static inline GDALDriverH ToHandle(GDALDriver *poDriver)
    {
        return static_cast<GDALDriverH>(poDriver);
    }

    /** Convert a GDALDriverH to a GDALDriver*.
     */
    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