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