interface/wx/filesys.h

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