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