interface/filesys.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filesys.h
   3 // Purpose:     interface of wxFileSystem, wxFileSystemHandler, wxFSFile
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Open Bit Flags
  12 */
  13 enum wxFileSystemOpenFlags
  14 {
  15     wxFS_READ = 1,      /**< Open for reading */
  16     wxFS_SEEKABLE = 4   /**< Returned stream will be seekable */
  17 };
  18
  19
  20 /**
  21     @class wxFileSystem
  22     @wxheader{filesys.h}
  23
  24     This class provides an interface for opening files on different file systems.
  25     It can handle absolute and/or local filenames.
  26
  27     It uses a system of handlers (see wxFileSystemHandler) to provide access to
  28     user-defined virtual file systems.
  29
  30     @library{wxbase}
  31     @category{vfs}
  32
  33     @see wxFileSystemHandler, wxFSFile, @ref overview_fs
  34 */
  35 class wxFileSystem : public wxObject
  36 {
  37 public:
  38     /**
  39         Constructor.
  40     */
  41     wxFileSystem();
  42
  43     /**
  44         This static function adds new handler into the list of handlers
  45         (see wxFileSystemHandler) which provide access to virtual FS.
  46
  47         Note that if two handlers for the same protocol are added, the last
  48         added one takes precedence.
  49
  50         @note You can call:
  51               @code
  52               wxFileSystem::AddHandler(new My_FS_Handler);
  53               @endcode
  54               This is because (a) AddHandler is a static method, and (b) the
  55               handlers are deleted in wxFileSystem's destructor so that you
  56               don't have to care about it.
  57     */
  58     static void AddHandler(wxFileSystemHandler handler);
  59
  60     /**
  61         Sets the current location. @a location parameter passed to OpenFile() is
  62         relative to this path.
  63
  64         @remarks Unless @a is_dir is @true the @a location parameter is not the
  65                  directory name but the name of the file in this directory.
  66
  67         All these commands change the path to "dir/subdir/":
  68
  69         @code
  70         ChangePathTo("dir/subdir/xh.htm");
  71         ChangePathTo("dir/subdir", true);
  72         ChangePathTo("dir/subdir/", true);
  73         @endcode
  74
  75         Example:
  76         @code
  77         f = fs->OpenFile("hello.htm"); // opens file 'hello.htm'
  78         fs->ChangePathTo("subdir/folder", true);
  79         f = fs->OpenFile("hello.htm"); // opens file 'subdir/folder/hello.htm' !!
  80         @endcode
  81
  82         @param location
  83             the new location. Its meaning depends on the value of is_dir
  84         @param is_dir
  85             if @true location is new directory.
  86             If @false (the default) location is file in the new directory.
  87     */
  88     void ChangePathTo(const wxString& location, bool is_dir = false);
  89
  90     /**
  91         Converts a wxFileName into an URL.
  92
  93         @see URLToFileName(), wxFileName
  94     */
  95     static wxString FileNameToURL(const wxFileName& filename);
  96
  97     /**
  98         Looks for the file with the given name @a file in a colon or semi-colon
  99         (depending on the current platform) separated list of directories in @a path.
 100
 101         If the file is found in any directory, returns @true and the full path
 102         of the file in @a str, otherwise returns @false and doesn't modify @a str.
 103
 104         @param str
 105             Receives the full path of the file, must not be @NULL
 106         @param path
 107             wxPATH_SEP-separated list of directories
 108         @param file
 109             the name of the file to look for
 110     */
 111     bool FindFileInPath(wxString str, const wxString& path,
 112                         const wxString& file);
 113
 114     /**
 115         Works like ::wxFindFirstFile().
 116
 117         Returns the name of the first filename (within filesystem's current path)
 118         that matches @a wildcard.
 119
 120         @param wildcard
 121             The wildcard that the filename must match
 122         @param flags
 123             One of wxFILE (only files), wxDIR (only directories) or 0 (both).
 124     */
 125     wxString FindFirst(const wxString& wildcard, int flags = 0);
 126
 127     /**
 128         Returns the next filename that matches the parameters passed to FindFirst().
 129     */
 130     wxString FindNext();
 131
 132     /**
 133         Returns the actual path (set by wxFileSystem::ChangePathTo).
 134     */
 135     wxString GetPath();
 136
 137     /**
 138         This static function returns @true if there is a registered handler which can
 139         open the given location.
 140     */
 141     static bool HasHandlerForPath(const wxString& location);
 142
 143     /**
 144         Opens the file and returns a pointer to a wxFSFile object or @NULL if failed.
 145
 146         It first tries to open the file in relative scope (based on value passed to
 147         ChangePathTo() method) and then as an absolute path.
 148
 149         Note that the user is responsible for deleting the returned wxFSFile.
 150         @a flags can be one or more of the ::wxFileSystemOpenFlags values
 151         combined together.
 152
 153         A stream opened with just the default @e wxFS_READ flag may
 154         or may not be seekable depending on the underlying source.
 155
 156         Passing @e "wxFS_READ | wxFS_SEEKABLE" for @a flags will back
 157         a stream that is not natively seekable with memory or a file
 158         and return a stream that is always seekable.
 159     */
 160     wxFSFile* OpenFile(const wxString& location,
 161                        int flags = wxFS_READ);
 162
 163     /**
 164         Converts URL into a well-formed filename.
 165         The URL must use the @c file protocol.
 166     */
 167     static wxFileName URLToFileName(const wxString& url);
 168 };
 169
 170
 171
 172 /**
 173     @class wxFSFile
 174     @wxheader{filesys.h}
 175
 176     This class represents a single file opened by wxFileSystem.
 177     It provides more information than wxWindow's input stream
 178     (stream, filename, mime type, anchor).
 179
 180     @note Any pointer returned by a method of wxFSFile is valid only as long as
 181           the wxFSFile object exists. For example a call to GetStream()
 182           doesn't @e create the stream but only returns the pointer to it.
 183           In other words after 10 calls to GetStream() you will have obtained
 184           ten identical pointers.
 185
 186     @library{wxbase}
 187     @category{vfs}
 188
 189     @see wxFileSystemHandler, wxFileSystem, @ref overview_fs
 190 */
 191 class wxFSFile : public wxObject
 192 {
 193 public:
 194     /**
 195         Constructor. You probably won't use it. See the Note for details.
 196
 197         It is seldom used by the application programmer but you will need it if
 198         you are writing your own virtual FS. For example you may need something
 199         similar to wxMemoryInputStream, but because wxMemoryInputStream doesn't
 200         free the memory when destroyed and thus passing a memory stream pointer
 201         into wxFSFile constructor would lead to memory leaks, you can write your
 202         own class derived from wxFSFile:
 203
 204         @code
 205         class wxMyFSFile : public wxFSFile
 206         {
 207             private:
 208                 void *m_Mem;
 209             public:
 210                 wxMyFSFile(.....)
 211                 ~wxMyFSFile() {free(m_Mem);}
 212                     // of course dtor is virtual ;-)
 213         };
 214         @endcode
 215
 216         If you are not sure of the meaning of these params, see the description
 217         of the GetXXXX() functions.
 218
 219         @param stream
 220             The input stream that will be used to access data
 221         @param location
 222             The full location (aka filename) of the file
 223         @param mimetype
 224             MIME type of this file. It may be left empty, in which
 225             case the type will be determined from file's extension (location must
 226             not be empty in this case).
 227         @param anchor
 228             Anchor. See GetAnchor() for details.
 229     */
 230     wxFSFile(wxInputStream stream, const wxString& loc,
 231              const wxString& mimetype,
 232              const wxString& anchor, wxDateTime modif);
 233
 234     /**
 235         Detaches the stream from the wxFSFile object. That is, the
 236         stream obtained with GetStream() will continue its existance
 237         after the wxFSFile object is deleted.
 238
 239         You will have to delete the stream yourself.
 240     */
 241     void DetachStream();
 242
 243     /**
 244         Returns anchor (if present). The term of @b anchor can be easily
 245         explained using few examples:
 246
 247         @verbatim
 248         index.htm#anchor                      // 'anchor' is anchor
 249         index/wx001.htm                       // NO anchor here!
 250         archive/main.zip#zip:index.htm#global // 'global'
 251         archive/main.zip#zip:index.htm        // NO anchor here!
 252         @endverbatim
 253
 254         Usually an anchor is presented only if the MIME type is 'text/html'.
 255         But it may have some meaning with other files; for example myanim.avi#200
 256         may refer to position in animation or reality.wrl#MyView may refer
 257         to a predefined view in VRML.
 258     */
 259     const wxString& GetAnchor() const;
 260
 261     /**
 262         Returns full location of the file, including path and protocol.
 263
 264         Examples:
 265         @verbatim
 266         http://www.wxwidgets.org
 267         http://www.ms.mff.cuni.cz/~vsla8348/wxhtml/archive.zip#zip:info.txt
 268         file:/home/vasek/index.htm
 269         relative-file.htm
 270         @endverbatim
 271     */
 272     const wxString& GetLocation() const;
 273
 274     /**
 275         Returns the MIME type of the content of this file.
 276
 277         It is either extension-based (see wxMimeTypesManager) or extracted from
 278         HTTP protocol Content-Type header.
 279     */
 280     const wxString& GetMimeType() const;
 281
 282     /**
 283         Returns time when this file was modified.
 284     */
 285     wxDateTime GetModificationTime() const;
 286
 287     /**
 288         Returns pointer to the stream.
 289
 290         You can use the returned stream to directly access data.
 291         You may suppose that the stream provide Seek and GetSize functionality
 292         (even in the case of the HTTP protocol which doesn't provide
 293         this by default. wxHtml uses local cache to work around
 294         this and to speed up the connection).
 295     */
 296     wxInputStream* GetStream() const;
 297 };
 298
 299
 300
 301 /**
 302     @class wxFileSystemHandler
 303     @wxheader{filesys.h}
 304
 305     Classes derived from wxFileSystemHandler are used to access virtual file systems.
 306
 307     Its public interface consists of two methods: wxFileSystemHandler::CanOpen
 308     and wxFileSystemHandler::OpenFile.
 309
 310     It provides additional protected methods to simplify the process
 311     of opening the file: GetProtocol(), GetLeftLocation(), GetRightLocation(),
 312     GetAnchor(), GetMimeTypeFromExt().
 313
 314     Please have a look at overview (see wxFileSystem) if you don't know how locations
 315     are constructed.
 316
 317     Also consult the @ref overview_fs_wxhtmlfs "list of available handlers".
 318
 319     Note that the handlers are shared by all instances of wxFileSystem.
 320
 321     @remarks
 322     wxHTML library provides handlers for local files and HTTP or FTP protocol.
 323
 324     @note
 325     The location parameter passed to OpenFile() or CanOpen() methods is always an
 326     absolute path. You don't need to check the FS's current path.
 327
 328     @beginWxPerlOnly
 329     In wxPerl, you need to derive your file system handler class
 330     from Wx::PlFileSystemHandler.
 331     @endWxPerlOnly
 332
 333     @library{wxbase}
 334     @category{vfs}
 335
 336     @see wxFileSystem, wxFSFile, @ref overview_fs
 337 */
 338 class wxFileSystemHandler : public wxObject
 339 {
 340 public:
 341     /**
 342         Constructor.
 343     */
 344     wxFileSystemHandler();
 345
 346     /**
 347         Returns @true if the handler is able to open this file. This function doesn't
 348         check whether the file exists or not, it only checks if it knows the protocol.
 349         Example:
 350
 351         @code
 352         bool MyHand::CanOpen(const wxString& location)
 353         {
 354             return (GetProtocol(location) == "http");
 355         }
 356         @endcode
 357
 358         Must be overridden in derived handlers.
 359     */
 360     virtual bool CanOpen(const wxString& location);
 361
 362     /**
 363         Works like ::wxFindFirstFile().
 364
 365         Returns the name of the first filename (within filesystem's current path)
 366         that matches @e wildcard. @a flags may be one of wxFILE (only files),
 367         wxDIR (only directories) or 0 (both).
 368
 369         This method is only called if CanOpen() returns @true.
 370     */
 371     virtual wxString FindFirst(const wxString& wildcard,
 372                                int flags = 0);
 373
 374     /**
 375         Returns next filename that matches parameters passed to wxFileSystem::FindFirst.
 376
 377         This method is only called if CanOpen() returns @true and FindFirst()
 378         returned a non-empty string.
 379     */
 380     virtual wxString FindNext();
 381
 382     /**
 383         Returns the anchor if present in the location.
 384         See wxFSFile::GetAnchor for details.
 385
 386         Example:
 387         @code
 388         GetAnchor("index.htm#chapter2") == "chapter2"
 389         @endcode
 390
 391         @note the anchor is NOT part of the left location.
 392     */
 393     wxString GetAnchor(const wxString& location) const;
 394
 395     /**
 396         Returns the left location string extracted from @e location.
 397
 398         Example:
 399         @code
 400         GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip"
 401         @endcode
 402     */
 403     wxString GetLeftLocation(const wxString& location) const;
 404
 405     /**
 406         Returns the MIME type based on @b extension of @a location.
 407         (While wxFSFile::GetMimeType() returns real MIME type - either
 408          extension-based or queried from HTTP.)
 409
 410         Example:
 411         @code
 412         GetMimeTypeFromExt("index.htm") == "text/html"
 413         @endcode
 414     */
 415     wxString GetMimeTypeFromExt(const wxString& location);
 416
 417     /**
 418         Returns the protocol string extracted from @a location.
 419
 420         Example:
 421         @code
 422         GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip"
 423         @endcode
 424     */
 425     wxString GetProtocol(const wxString& location) const;
 426
 427     /**
 428         Returns the right location string extracted from @a location.
 429
 430         Example:
 431         @code
 432         GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm"
 433         @endcode
 434     */
 435     wxString GetRightLocation(const wxString& location) const;
 436
 437     /**
 438         Opens the file and returns wxFSFile pointer or @NULL if failed.
 439         Must be overridden in derived handlers.
 440
 441         @param fs
 442             Parent FS (the FS from that OpenFile was called).
 443             See the ZIP handler for details of how to use it.
 444         @param location
 445             The absolute location of file.
 446     */
 447     virtual wxFSFile* OpenFile(wxFileSystem& fs,
 448                                const wxString& location);
 449 };
 450