xbmc/filesystem/IDirectory.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 #include "utils/Variant.h"
  12
  13 #include <string>
  14
  15 class CFileItemList;
  16 class CProfileManager;
  17 class CURL;
  18
  19 namespace XFILE
  20 {
  21   enum DIR_CACHE_TYPE
  22   {
  23     DIR_CACHE_NEVER = 0, ///< Never cache this directory to memory
  24     DIR_CACHE_ONCE,      ///< Cache this directory to memory for each fetch (so that FileExists() checks are fast)
  25     DIR_CACHE_ALWAYS     ///< Always cache this directory to memory, so that each additional fetch of this folder will utilize the cache (until it's cleared)
  26   };
  27
  28   /*! \brief Available directory flags
  29    The defaults are to allow file directories, no prompting, retrieve file information, hide hidden files, and utilise the directory cache
  30    based on the implementation's wishes.
  31    */
  32   enum DIR_FLAG
  33   {
  34     DIR_FLAG_DEFAULTS      = 0,
  35     DIR_FLAG_NO_FILE_DIRS  = (2 << 0), ///< Don't convert files (zip, rar etc.) to directories
  36     DIR_FLAG_ALLOW_PROMPT  = (2 << 1), ///< Allow prompting for further info (passwords etc.)
  37     DIR_FLAG_NO_FILE_INFO  = (2 << 2), ///< Don't read additional file info (stat for example)
  38     DIR_FLAG_GET_HIDDEN    = (2 << 3), ///< Get hidden files
  39     DIR_FLAG_READ_CACHE    = (2 << 4), ///< Force reading from the directory cache (if available)
  40     DIR_FLAG_BYPASS_CACHE  = (2 << 5)  ///< Completely bypass the directory cache (no reading, no writing)
  41   };
  42 /*!
  43  \ingroup filesystem
  44  \brief Interface to the directory on a file system.
  45
  46  This Interface is retrieved from CDirectoryFactory and can be used to
  47  access the directories on a filesystem.
  48  \sa CDirectoryFactory
  49  */
  50 class IDirectory
  51 {
  52 public:
  53   static void RegisterProfileManager(const CProfileManager &profileManager);
  54   static void UnregisterProfileManager();
  55
  56   IDirectory();
  57   virtual ~IDirectory(void);
  58   /*!
  59    \brief Get the \e items of the directory \e strPath.
  60    \param url Directory to read.
  61    \param items Retrieves the directory entries.
  62    \return Returns \e true, if successful.
  63    \sa CDirectoryFactory
  64    */
  65   virtual bool GetDirectory(const CURL& url, CFileItemList &items) = 0;
  66   /*!
  67    \brief Retrieve the progress of the current directory fetch (if possible).
  68    \return the progress as a float in the range 0..100.
  69    \sa GetDirectory, CancelDirectory
  70    */
  71   virtual float GetProgress() const { return 0.0f; }
  72   /*!
  73    \brief Cancel the current directory fetch (if possible).
  74    \sa GetDirectory
  75    */
  76   virtual void CancelDirectory() {}
  77   /*!
  78   \brief Create the directory
  79   \param url Directory to create.
  80   \return Returns \e true, if directory is created or if it already exists
  81   \sa CDirectoryFactory
  82   */
  83   virtual bool Create(const CURL& url) { return false; }
  84   /*!
  85   \brief Check for directory existence
  86   \param url Directory to check.
  87   \return Returns \e true, if directory exists
  88   \sa CDirectoryFactory
  89   */
  90   virtual bool Exists(const CURL& url) { return false; }
  91   /*!
  92   \brief Removes the directory
  93   \param url Directory to remove.
  94   \return Returns \e false if not successful
  95   */
  96   virtual bool Remove(const CURL& url) { return false; }
  97
  98   /*!
  99   \brief Recursively removes the directory
 100   \param url Directory to remove.
 101   \return Returns \e false if not successful
 102   */
 103   virtual bool RemoveRecursive(const CURL& url) { return false; }
 104
 105   /*!
 106   \brief Whether this file should be listed
 107   \param url File to test.
 108   \return Returns \e true if the file should be listed
 109   */
 110   virtual bool IsAllowed(const CURL& url) const;
 111
 112   /*! \brief Whether to allow all files/folders to be listed.
 113    \return Returns \e true if all files/folder should be listed.
 114    */
 115   virtual bool AllowAll() const { return false; }
 116
 117   /*!
 118   \brief How this directory should be cached
 119   \param url Directory at hand.
 120   \return Returns the cache type.
 121   */
 122   virtual DIR_CACHE_TYPE GetCacheType(const CURL& url) const { return DIR_CACHE_ONCE; }
 123
 124   void SetMask(const std::string& strMask);
 125   void SetFlags(int flags);
 126
 127   /*! \brief Process additional requirements before the directory fetch is performed.
 128    Some directory fetches may require authentication, keyboard input etc.  The IDirectory subclass
 129    should call GetKeyboardInput, SetErrorDialog or RequireAuthentication and then return false
 130    from the GetDirectory method. CDirectory will then prompt for input from the user, before
 131    re-calling the GetDirectory method.
 132    \sa GetKeyboardInput, SetErrorDialog, RequireAuthentication
 133    */
 134   bool ProcessRequirements();
 135
 136 protected:
 137   /*! \brief Prompt the user for some keyboard input
 138    Call this method from the GetDirectory method to retrieve additional input from the user.
 139    If this function returns false then no input has been received, and the GetDirectory call
 140    should return false.
 141    \param heading an integer or string heading for the keyboard dialog
 142    \param input [out] the returned input (if available).
 143    \return true if keyboard input has been received. False if it hasn't.
 144    \sa ProcessRequirements
 145    */
 146   bool GetKeyboardInput(const CVariant &heading, std::string &input, bool hiddenInput = false);
 147
 148   /*! \brief Show an error dialog on failure of GetDirectory call
 149    Call this method from the GetDirectory method to set an error message to be shown to the user
 150    \param heading an integer or string heading for the error dialog.
 151    \param line1 the first line to be displayed (integer or string).
 152    \param line2 the first line to be displayed (integer or string).
 153    \param line3 the first line to be displayed (integer or string).
 154    \sa ProcessRequirements
 155    */
 156   void SetErrorDialog(const CVariant &heading, const CVariant &line1, const CVariant &line2 = 0, const CVariant &line3 = 0);
 157
 158   /*! \brief Prompt the user for authentication of a URL.
 159    Call this method from the GetDirectory method when authentication is required from the user, before returning
 160    false from the GetDirectory call. The user will be prompted for authentication, and GetDirectory will be
 161    re-called.
 162    \param url the URL to authenticate.
 163    \sa ProcessRequirements
 164    */
 165   void RequireAuthentication(const CURL& url);
 166
 167   static const CProfileManager *m_profileManager;
 168
 169   std::string m_strFileMask;  ///< Holds the file mask specified by SetMask()
 170
 171   int m_flags; ///< Directory flags - see DIR_FLAG
 172
 173   CVariant m_requirements;
 174 };
 175 }