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