Line data    Source code

       1             : /***************************************************************************
       2             :   gdal_subdatasetinfo.h - GDALSubdatasetInfo
       3             : 
       4             :  ---------------------
       5             :  begin                : 21.7.2023
       6             :  copyright            : (C) 2023 by Alessndro Pasotti
       7             :  email                : elpaso@itopen.it
       8             :  ***************************************************************************
       9             :  *                                                                         *
      10             :  * SPDX-License-Identifier: MIT
      11             :  *                                                                         *
      12             :  ***************************************************************************/
      13             : #ifndef GDALSUBDATASETINFO_H
      14             : #define GDALSUBDATASETINFO_H
      15             : 
      16             : #include "cpl_port.h"
      17             : #include <string>
      18             : 
      19             : /**
      20             :  * The GDALSubdatasetInfo abstract class provides methods to extract and
      21             :  * manipulate subdataset information from a file name that contains subdataset
      22             :  * information.
      23             :  *
      24             :  * Drivers offering this functionality must override the parseFileName() method.
      25             :  */
      26             : struct CPL_DLL GDALSubdatasetInfo
      27             : {
      28             : 
      29             :   public:
      30             :     /**
      31             :      * @brief Construct a GDALSubdatasetInfo object from a subdataset file descriptor.
      32             :      * @param fileName          The subdataset file name descriptor.
      33             :      */
      34             :     GDALSubdatasetInfo(const std::string &fileName);
      35             : 
      36         109 :     virtual ~GDALSubdatasetInfo() = default;
      37             : 
      38             :     /**
      39             :  * @brief Returns the unquoted and unescaped path component of the complete file descriptor
      40             :  *        stripping any subdataset, prefix and additional information.
      41             :  * @return                      The path to the file
      42             :  * @since                       GDAL 3.8
      43             :  */
      44             :     std::string GetPathComponent() const;
      45             : 
      46             :     /**
      47             :  * @brief Replaces the path component of the complete file descriptor
      48             :  *        by keeping the subdataset and any other component unaltered.
      49             :  *        The returned string must be freed with CPLFree()
      50             :  * @param newPathName           New path name with no subdataset information.
      51             :  * @note                        This method does not check if the subdataset actually exists.
      52             :  * @return                      The original file name with the old path component replaced by newPathName.
      53             :  * @since                       GDAL 3.8
      54             :  */
      55             :     std::string ModifyPathComponent(const std::string &newPathName) const;
      56             : 
      57             :     /**
      58             :  * @brief Returns the subdataset component of the file name.
      59             :  *
      60             :  * @return                      The subdataset name
      61             :  * @since                       GDAL 3.8
      62             :  */
      63             :     std::string GetSubdatasetComponent() const;
      64             : 
      65             :     //! @cond Doxygen_Suppress
      66             :   protected:
      67             :     /**
      68             :      * This method is called once to parse the fileName and populate the member variables.
      69             :      * It must be reimplemented by concrete derived classes.
      70             :      */
      71             :     virtual void parseFileName() = 0;
      72             : 
      73             :     /**
      74             :      * Adds double quotes to paths and escape double quotes inside the path.
      75             :      */
      76             :     static std::string quote(const std::string &path);
      77             : 
      78             :     /**
      79             :      * Removes double quotes and unescape double quotes.
      80             :      */
      81             :     static std::string unquote(const std::string &path);
      82             : 
      83             :     //! The original unparsed complete file name passed to the constructor (e.g. GPKG:/path/to/file.gpkg:layer_name)
      84             :     std::string m_fileName;
      85             :     //! The unmodified path component of the file name (e.g. "\"C:\path\to\file.gpkg\"", "/path/to/file.gpkg")
      86             :     std::string m_pathComponent;
      87             :     //! The unquoted and unescaped path component of the file name (e.g. "C:\path\to\file.gpkg", "/path/to/file.gpkg")
      88             :     std::string m_cleanedPathComponent;
      89             :     //! The subdataset component (e.g. layer_name)
      90             :     std::string m_subdatasetComponent;
      91             :     //! The driver prefix component (e.g. GPKG)
      92             :     std::string m_driverPrefixComponent;
      93             :     //! If the path is enclosed in double quotes.
      94             :     bool m_isQuoted = false;
      95             : 
      96             :   private:
      97             :     mutable bool m_initialized = false;
      98             : 
      99             :     void init() const;
     100             : 
     101             :     //! @endcond
     102             : };
     103             : 
     104             : #endif  // GDALSUBDATASETINFO_H