xbmc/utils/Fanart.h

   1 /*
   2  *  Copyright (C) 2005-2018 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 // Fanart.h
  12 //////////////////////////////////////////////////////////////////////
  13
  14 #include <string>
  15 #include <vector>
  16
  17 ///
  18 /// /brief CFanart is the core of fanart support and contains all fanart data for a specific show
  19 ///
  20 /// CFanart stores all data related to all available fanarts for a given TV show and provides
  21 /// functions required to manipulate and access that data.
  22 /// In order to provide an interface between the fanart data and the XBMC database, all data
  23 /// is stored internally it its own form, as well as packed into an XML formatted string
  24 /// stored in the member variable m_xml.
  25 /// Information on multiple fanarts for a given show is stored, but XBMC only cares about the
  26 /// very first fanart stored.  These interfaces provide a means to access the data in that first
  27 /// fanart record, as well as to set which fanart is the first record.  Externally, all XBMC needs
  28 /// to care about is getting and setting that first record.  Everything else is maintained internally
  29 /// by CFanart.  This point is key to using the interface properly.
  30 class CFanart
  31 {
  32 public:
  33   ///
  34   /// Standard constructor doesn't need to do anything
  35   CFanart();
  36   ///
  37   /// Takes the internal fanart data and packs it into an XML formatted string in m_xml
  38   /// \sa m_xml
  39   void Pack();
  40   ///
  41   /// Takes the XML formatted string m_xml and unpacks the fanart data contained into the internal data
  42   /// \return A boolean indicating success or failure
  43   /// \sa m_xml
  44   bool Unpack();
  45   ///
  46   /// Retrieves the fanart full res image URL
  47   /// \param index - index of image to retrieve (defaults to 0)
  48   /// \return A string containing the full URL to the full resolution fanart image
  49   std::string GetImageURL(unsigned int index = 0) const;
  50   ///
  51   /// Retrieves the fanart preview image URL, or full res image URL if that doesn't exist
  52   /// \param index - index of image to retrieve (defaults to 0)
  53   /// \return A string containing the full URL to the full resolution fanart image
  54   std::string GetPreviewURL(unsigned int index = 0) const;
  55   ///
  56   /// Used to return a specified fanart theme color value
  57   /// \param index: 0 based index of the color to retrieve.  A fanart theme contains 3 colors, indices 0-2, arranged from darkest to lightest.
  58   const std::string GetColor(unsigned int index) const;
  59   ///
  60   /// Sets a particular fanart to be the "primary" fanart, or in other words, sets which fanart is actually used by XBMC
  61   ///
  62   /// This is the one of the only instances in the public interface where there is any hint that more than one fanart exists, but its by necessity.
  63   /// \param index: 0 based index of which fanart to set as the primary fanart
  64   /// \return A boolean value indicating success or failure.  This should only return false if the specified index is not a valid fanart
  65   bool SetPrimaryFanart(unsigned int index);
  66   ///
  67   /// Returns how many fanarts are stored
  68   /// \return An integer indicating how many fanarts are stored in the class.  Fanart indices are 0 to (GetNumFanarts() - 1)
  69   unsigned int GetNumFanarts() const;
  70   /// Adds an image to internal fanart data
  71   void AddFanart(const std::string& image, const std::string& preview, const std::string& colors);
  72   /// Clear all internal fanart data
  73   void Clear();
  74   ///
  75   /// m_xml contains an XML formatted string which is all fanart packed into one string.
  76   ///
  77   /// This string is the "interface" as it were to the XBMC database, and MUST be kept in sync with the rest of the class.  Therefore
  78   /// anytime this string is changed, the change should be followed up by a call to CFanart::UnPack().  This XML formatted string is
  79   /// also the interface used to pass the fanart data from the scraper to CFanart.
  80   std::string m_xml;
  81 private:
  82   static const unsigned int max_fanart_colors;
  83   ///
  84   /// Parse various color formats as returned by the sites scraped into a format we recognize
  85   ///
  86   /// Supported Formats:
  87   ///
  88   /// * The TVDB RGB Int Triplets, pipe separate with leading/trailing pipes "|68,69,59|69,70,58|78,78,68|"
  89   /// * XBMC ARGB Hexadecimal string comma separated "FFFFFFFF,DDDDDDDD,AAAAAAAA"
  90   ///
  91   /// \param colorsIn: string containing colors in some format to be converted
  92   /// \param colorsOut: XBMC ARGB Hexadecimal string comma separated "FFFFFFFF,DDDDDDDD,AAAAAAAA"
  93   /// \return boolean indicating success or failure.
  94   static bool ParseColors(const std::string&colorsIn, std::string&colorsOut);
  95
  96   struct SFanartData
  97   {
  98     std::string strImage;
  99     std::string strColors;
 100     std::string strPreview;
 101   };
 102
 103   ///
 104   /// std::vector that stores all our fanart data
 105   std::vector<SFanartData> m_fanart;
 106 };
 107