xbmc/imagefiles/ImageFileURL.h

   1 /*
   2  *  Copyright (C) 2024 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include <map>
  12 #include <string>
  13
  14 class CURL;
  15
  16 namespace IMAGE_FILES
  17 {
  18 /*!
  19  * \brief A mostly-typed representation of a URL to any image, whether a simple path to an image
  20  *        file, embedded in another file, or generated in some way.
  21  *
  22  * A URL string is good to pass between most classes, store, and transmit, but use this if you need
  23  * to _create_ or _modify_ a special image path, or are working on the details of such image files.
  24  *
  25  * URL string format is `image://[type@]<url_encoded_path>?options`
  26 */
  27 class CImageFileURL
  28 {
  29 public:
  30   /*!
  31    * \brief Create an ImageFileURL from a string representation.
  32   */
  33   CImageFileURL(const std::string& imageFileURL);
  34
  35   /*!
  36    * \brief Create an ImageFileURL pointing to a specific file.
  37    *
  38    * Provide a 'specialType' parameter to specify a special image loader.
  39    *
  40    * \param specialType set a special image type - an implementation of \ref ISpecialImageFileLoader
  41   */
  42   static CImageFileURL FromFile(const std::string& filePath, std::string specialType = "");
  43
  44   void AddOption(std::string key, std::string value);
  45
  46   std::string GetOption(const std::string& key) const;
  47
  48   /*!
  49    * \brief Build a complete string representation of this ImageFileURL.
  50   */
  51   std::string ToString() const;
  52
  53   /*!
  54    * \brief Build a cache key for this ImageFileURL.
  55    *
  56    * Return base filePath if not special and multiple options are in a stable order,
  57    * otherwise return a complete string representation.
  58   */
  59   std::string ToCacheKey() const;
  60
  61   const std::string& GetTargetFile() const { return m_filePath; }
  62
  63   bool IsSpecialImage() const { return !m_specialType.empty(); }
  64   const std::string& GetSpecialType() const { return m_specialType; }
  65
  66   bool flipped{false};
  67
  68 private:
  69   CImageFileURL();
  70   std::string m_filePath;
  71   std::string m_specialType;
  72
  73   std::map<std::string, std::string> m_options{};
  74 };
  75
  76 /*!
  77  * \brief Build an ImageFileURL string from a file path.
  78  *
  79  * Provide a 'specialType' parameter to specify a special image loader.
  80  *
  81  * \param specialType set a special image type - an implementation of \ref ISpecialImageFileLoader
  82 */
  83 std::string URLFromFile(const std::string& filePath, std::string specialType = "");
  84
  85 /*!
  86  * \brief Build a cache key for an ImageFileURL string.
  87 */
  88 std::string ToCacheKey(const std::string& imageFileURL);
  89
  90 } // namespace IMAGE_FILES