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             :  * Permission is hereby granted, free of charge, to any person obtaining a
      11             :  * copy of this software and associated documentation files (the "Software"),
      12             :  * to deal in the Software without restriction, including without limitation
      13             :  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
      14             :  * and/or sell copies of the Software, and to permit persons to whom the
      15             :  * Software is furnished to do so, subject to the following conditions:
      16             :  *
      17             :  * The above copyright notice and this permission notice shall be included
      18             :  * in all copies or substantial portions of the Software.
      19             :  *
      20             :  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
      21             :  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      22             :  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
      23             :  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      24             :  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
      25             :  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
      26             :  * DEALINGS IN THE SOFTWARE.
      27             :  *                                                                         *
      28             :  ***************************************************************************/
      29             : #ifndef GDALSUBDATASETINFO_H
      30             : #define GDALSUBDATASETINFO_H
      31             : 
      32             : #include "cpl_port.h"
      33             : #include <string>
      34             : 
      35             : /**
      36             :  * The GDALSubdatasetInfo abstract class provides methods to extract and
      37             :  * manipulate subdataset information from a file name that contains subdataset
      38             :  * information.
      39             :  *
      40             :  * Drivers offering this functionality must override the parseFileName() method.
      41             :  */
      42             : struct CPL_DLL GDALSubdatasetInfo
      43             : {
      44             : 
      45             :   public:
      46             :     /**
      47             :      * @brief Construct a GDALSubdatasetInfo object from a subdataset file descriptor.
      48             :      * @param fileName          The subdataset file name descriptor.
      49             :      */
      50             :     GDALSubdatasetInfo(const std::string &fileName);
      51             : 
      52         107 :     virtual ~GDALSubdatasetInfo() = default;
      53             : 
      54             :     /**
      55             :  * @brief Returns the unquoted and unescaped path component of the complete file descriptor
      56             :  *        stripping any subdataset, prefix and additional information.
      57             :  * @return                      The path to the file
      58             :  * @since                       GDAL 3.8
      59             :  */
      60             :     std::string GetPathComponent() const;
      61             : 
      62             :     /**
      63             :  * @brief Replaces the path component of the complete file descriptor
      64             :  *        by keeping the subdataset and any other component unaltered.
      65             :  *        The returned string must be freed with CPLFree()
      66             :  * @param newPathName           New path name with no subdataset information.
      67             :  * @note                        This method does not check if the subdataset actually exists.
      68             :  * @return                      The original file name with the old path component replaced by newPathName.
      69             :  * @since                       GDAL 3.8
      70             :  */
      71             :     std::string ModifyPathComponent(const std::string &newPathName) const;
      72             : 
      73             :     /**
      74             :  * @brief Returns the subdataset component of the file name.
      75             :  *
      76             :  * @return                      The subdataset name
      77             :  * @since                       GDAL 3.8
      78             :  */
      79             :     std::string GetSubdatasetComponent() const;
      80             : 
      81             :     //! @cond Doxygen_Suppress
      82             :   protected:
      83             :     /**
      84             :      * This method is called once to parse the fileName and populate the member variables.
      85             :      * It must be reimplemented by concrete derived classes.
      86             :      */
      87             :     virtual void parseFileName() = 0;
      88             : 
      89             :     /**
      90             :      * Adds double quotes to paths and escape double quotes inside the path.
      91             :      */
      92             :     static std::string quote(const std::string &path);
      93             : 
      94             :     /**
      95             :      * Removes double quotes and unescape double quotes.
      96             :      */
      97             :     static std::string unquote(const std::string &path);
      98             : 
      99             :     //! The original unparsed complete file name passed to the constructor (e.g. GPKG:/path/to/file.gpkg:layer_name)
     100             :     std::string m_fileName;
     101             :     //! The unmodified path component of the file name (e.g. "\"C:\path\to\file.gpkg\"", "/path/to/file.gpkg")
     102             :     std::string m_pathComponent;
     103             :     //! The unquoted and unescaped path component of the file name (e.g. "C:\path\to\file.gpkg", "/path/to/file.gpkg")
     104             :     std::string m_cleanedPathComponent;
     105             :     //! The subdataset component (e.g. layer_name)
     106             :     std::string m_subdatasetComponent;
     107             :     //! The driver prefix component (e.g. GPKG)
     108             :     std::string m_driverPrefixComponent;
     109             :     //! If the path is enclosed in double quotes.
     110             :     bool m_isQuoted = false;
     111             : 
     112             :   private:
     113             :     mutable bool m_initialized = false;
     114             : 
     115             :     void init() const;
     116             : 
     117             :     //! @endcond
     118             : };
     119             : 
     120             : #endif  // GDALSUBDATASETINFO_H