code.vuplus.com Git - vuplus_xbmc/blob - xbmc/filesystem/IDirectory.h

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