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