include/wx/filesys.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/filesys.h
   3 // Purpose:     class for opening files - virtual file system
   4 // Author:      Vaclav Slavik
   5 // Copyright:   (c) 1999 Vaclav Slavik
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 #ifndef __FILESYS_H__
  10 #define __FILESYS_H__
  11
  12 #include "wx/defs.h"
  13
  14 #if wxUSE_FILESYSTEM
  15
  16 #if !wxUSE_STREAMS
  17 #error You cannot compile virtual file systems without wxUSE_STREAMS
  18 #endif
  19
  20 #if wxUSE_HTML && !wxUSE_FILESYSTEM
  21 #error You cannot compile wxHTML without virtual file systems
  22 #endif
  23
  24 #include "wx/stream.h"
  25 #include "wx/datetime.h"
  26 #include "wx/filename.h"
  27 #include "wx/hashmap.h"
  28
  29 class WXDLLIMPEXP_FWD_BASE wxFSFile;
  30 class WXDLLIMPEXP_FWD_BASE wxFileSystemHandler;
  31 class WXDLLIMPEXP_FWD_BASE wxFileSystem;
  32
  33 //--------------------------------------------------------------------------------
  34 // wxFSFile
  35 //                  This class is a file opened using wxFileSystem. It consists of
  36 //                  input stream, location, mime type & optional anchor
  37 //                  (in 'index.htm#chapter2', 'chapter2' is anchor)
  38 //--------------------------------------------------------------------------------
  39
  40 class WXDLLIMPEXP_BASE wxFSFile : public wxObject
  41 {
  42 public:
  43     wxFSFile(wxInputStream *stream, const wxString& loc,
  44              const wxString& mimetype, const wxString& anchor
  45 #if wxUSE_DATETIME
  46              , wxDateTime modif
  47 #endif // wxUSE_DATETIME
  48              )
  49     {
  50         m_Stream = stream;
  51         m_Location = loc;
  52         m_MimeType = mimetype.Lower();
  53         m_Anchor = anchor;
  54 #if wxUSE_DATETIME
  55         m_Modif = modif;
  56 #endif // wxUSE_DATETIME
  57     }
  58
  59     virtual ~wxFSFile() { delete m_Stream; }
  60
  61     // returns stream. This doesn't give away ownership of the stream object.
  62     wxInputStream *GetStream() const { return m_Stream; }
  63
  64     // gives away the ownership of the current stream.
  65     wxInputStream *DetachStream()
  66     {
  67         wxInputStream *stream = m_Stream;
  68         m_Stream = NULL;
  69         return stream;
  70     }
  71
  72     // deletes the current stream and takes ownership of another.
  73     void SetStream(wxInputStream *stream)
  74     {
  75         delete m_Stream;
  76         m_Stream = stream;
  77     }
  78
  79     // returns file's mime type
  80     const wxString& GetMimeType() const;
  81
  82     // returns the original location (aka filename) of the file
  83     const wxString& GetLocation() const { return m_Location; }
  84
  85     const wxString& GetAnchor() const { return m_Anchor; }
  86
  87 #if wxUSE_DATETIME
  88     wxDateTime GetModificationTime() const { return m_Modif; }
  89 #endif // wxUSE_DATETIME
  90
  91 private:
  92     wxInputStream *m_Stream;
  93     wxString m_Location;
  94     wxString m_MimeType;
  95     wxString m_Anchor;
  96 #if wxUSE_DATETIME
  97     wxDateTime m_Modif;
  98 #endif // wxUSE_DATETIME
  99
 100     DECLARE_ABSTRACT_CLASS(wxFSFile)
 101     wxDECLARE_NO_COPY_CLASS(wxFSFile);
 102 };
 103
 104
 105
 106
 107
 108 //--------------------------------------------------------------------------------
 109 // wxFileSystemHandler
 110 //                  This class is FS handler for wxFileSystem. It provides
 111 //                  interface to access certain
 112 //                  kinds of files (HTPP, FTP, local, tar.gz etc..)
 113 //--------------------------------------------------------------------------------
 114
 115 class WXDLLIMPEXP_BASE wxFileSystemHandler : public wxObject
 116 {
 117 public:
 118     wxFileSystemHandler() : wxObject() {}
 119
 120     // returns true if this handler is able to open given location
 121     virtual bool CanOpen(const wxString& location) = 0;
 122
 123     // opens given file and returns pointer to input stream.
 124     // Returns NULL if opening failed.
 125     // The location is always absolute path.
 126     virtual wxFSFile* OpenFile(wxFileSystem& fs, const wxString& location) = 0;
 127
 128     // Finds first/next file that matches spec wildcard. flags can be wxDIR for restricting
 129     // the query to directories or wxFILE for files only or 0 for either.
 130     // Returns filename or empty string if no more matching file exists
 131     virtual wxString FindFirst(const wxString& spec, int flags = 0);
 132     virtual wxString FindNext();
 133
 134     // Returns MIME type of the file - w/o need to open it
 135     // (default behaviour is that it returns type based on extension)
 136     static wxString GetMimeTypeFromExt(const wxString& location);
 137
 138 protected:
 139     // returns protocol ("file", "http", "tar" etc.) The last (most right)
 140     // protocol is used:
 141     // {it returns "tar" for "file:subdir/archive.tar.gz#tar:/README.txt"}
 142     static wxString GetProtocol(const wxString& location);
 143
 144     // returns left part of address:
 145     // {it returns "file:subdir/archive.tar.gz" for "file:subdir/archive.tar.gz#tar:/README.txt"}
 146     static wxString GetLeftLocation(const wxString& location);
 147
 148     // returns anchor part of address:
 149     // {it returns "anchor" for "file:subdir/archive.tar.gz#tar:/README.txt#anchor"}
 150     // NOTE:  anchor is NOT a part of GetLeftLocation()'s return value
 151     static wxString GetAnchor(const wxString& location);
 152
 153     // returns right part of address:
 154     // {it returns "/README.txt" for "file:subdir/archive.tar.gz#tar:/README.txt"}
 155     static wxString GetRightLocation(const wxString& location);
 156
 157     DECLARE_ABSTRACT_CLASS(wxFileSystemHandler)
 158 };
 159
 160
 161
 162
 163 //--------------------------------------------------------------------------------
 164 // wxFileSystem
 165 //                  This class provides simple interface for opening various
 166 //                  kinds of files (HTPP, FTP, local, tar.gz etc..)
 167 //--------------------------------------------------------------------------------
 168
 169 // Open Bit Flags
 170 enum wxFileSystemOpenFlags
 171 {
 172     wxFS_READ = 1,      // Open for reading
 173     wxFS_SEEKABLE = 4   // Returned stream will be seekable
 174 };
 175
 176 WX_DECLARE_VOIDPTR_HASH_MAP_WITH_DECL(wxFileSystemHandler*, wxFSHandlerHash, class WXDLLIMPEXP_BASE);
 177
 178 class WXDLLIMPEXP_BASE wxFileSystem : public wxObject
 179 {
 180 public:
 181     wxFileSystem() : wxObject() { m_FindFileHandler = NULL;}
 182     virtual ~wxFileSystem();
 183
 184     // sets the current location. Every call to OpenFile is
 185     // relative to this location.
 186     // NOTE !!
 187     // unless is_dir = true 'location' is *not* the directory but
 188     // file contained in this directory
 189     // (so ChangePathTo("dir/subdir/xh.htm") sets m_Path to "dir/subdir/")
 190     void ChangePathTo(const wxString& location, bool is_dir = false);
 191
 192     wxString GetPath() const {return m_Path;}
 193
 194     // opens given file and returns pointer to input stream.
 195     // Returns NULL if opening failed.
 196     // It first tries to open the file in relative scope
 197     // (based on ChangePathTo()'s value) and then as an absolute
 198     // path.
 199     wxFSFile* OpenFile(const wxString& location, int flags = wxFS_READ);
 200
 201     // Finds first/next file that matches spec wildcard. flags can be wxDIR for restricting
 202     // the query to directories or wxFILE for files only or 0 for either.
 203     // Returns filename or empty string if no more matching file exists
 204     wxString FindFirst(const wxString& spec, int flags = 0);
 205     wxString FindNext();
 206
 207     // find a file in a list of directories, returns false if not found
 208     bool FindFileInPath(wxString *pStr,
 209                         const wxString& path, const wxString& file);
 210
 211     // Adds FS handler.
 212     // In fact, this class is only front-end to the FS handlers :-)
 213     static void AddHandler(wxFileSystemHandler *handler);
 214
 215     // Removes FS handler
 216     static wxFileSystemHandler* RemoveHandler(wxFileSystemHandler *handler);
 217
 218     // Returns true if there is a handler which can open the given location.
 219     static bool HasHandlerForPath(const wxString& location);
 220
 221     // remove all items from the m_Handlers list
 222     static void CleanUpHandlers();
 223
 224     // Returns the native path for a file URL
 225     static wxFileName URLToFileName(const wxString& url);
 226
 227     // Returns the file URL for a native path
 228     static wxString FileNameToURL(const wxFileName& filename);
 229
 230
 231 protected:
 232     wxFileSystemHandler *MakeLocal(wxFileSystemHandler *h);
 233
 234     wxString m_Path;
 235             // the path (location) we are currently in
 236             // this is path, not file!
 237             // (so if you opened test/demo.htm, it is
 238             // "test/", not "test/demo.htm")
 239     wxString m_LastName;
 240             // name of last opened file (full path)
 241     static wxList m_Handlers;
 242             // list of FS handlers
 243     wxFileSystemHandler *m_FindFileHandler;
 244             // handler that succeed in FindFirst query
 245     wxFSHandlerHash m_LocalHandlers;
 246             // Handlers local to this instance
 247
 248     DECLARE_DYNAMIC_CLASS(wxFileSystem)
 249     wxDECLARE_NO_COPY_CLASS(wxFileSystem);
 250 };
 251
 252
 253 /*
 254
 255 'location' syntax:
 256
 257 To determine FS type, we're using standard KDE notation:
 258 file:/absolute/path/file.htm
 259 file:relative_path/xxxxx.html
 260 /some/path/x.file               ('file:' is default)
 261 http://www.gnome.org
 262 file:subdir/archive.tar.gz#tar:/README.txt
 263
 264 special characters :
 265   ':' - FS identificator is before this char
 266   '#' - separator. It can be either HTML anchor ("index.html#news")
 267             (in case there is no ':' in the string to the right from it)
 268         or FS separator
 269             (example : http://www.wxhtml.org/wxhtml-0.1.tar.gz#tar:/include/wxhtml/filesys.h"
 270              this would access tgz archive stored on web)
 271   '/' - directory (path) separator. It is used to determine upper-level path.
 272         HEY! Don't use \ even if you're on Windows!
 273
 274 */
 275
 276
 277 class WXDLLIMPEXP_BASE wxLocalFSHandler : public wxFileSystemHandler
 278 {
 279 public:
 280     virtual bool CanOpen(const wxString& location);
 281     virtual wxFSFile* OpenFile(wxFileSystem& fs, const wxString& location);
 282     virtual wxString FindFirst(const wxString& spec, int flags = 0);
 283     virtual wxString FindNext();
 284
 285     // wxLocalFSHandler will prefix all filenames with 'root' before accessing
 286     // files on disk. This effectively makes 'root' the top-level directory
 287     // and prevents access to files outside this directory.
 288     // (This is similar to Unix command 'chroot'.)
 289     static void Chroot(const wxString& root) { ms_root = root; }
 290
 291 protected:
 292     static wxString ms_root;
 293 };
 294
 295 // Stream reading data from wxFSFile: this allows to use virtual files with any
 296 // wx functions accepting streams.
 297 class WXDLLIMPEXP_BASE wxFSInputStream : public wxWrapperInputStream
 298 {
 299 public:
 300     // Notice that wxFS_READ is implied in flags.
 301     wxFSInputStream(const wxString& filename, int flags = 0);
 302     virtual ~wxFSInputStream();
 303
 304 private:
 305     wxFSFile* m_file;
 306
 307     wxDECLARE_NO_COPY_CLASS(wxFSInputStream);
 308 };
 309
 310 #endif
 311   // wxUSE_FILESYSTEM
 312
 313 #endif
 314   // __FILESYS_H__