interface/filesys.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filesys.h
   3 // Purpose:     interface of wxFileSystem
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFileSystem
  11     @wxheader{filesys.h}
  12
  13     This class provides an interface for opening files on different
  14     file systems. It can handle absolute and/or local filenames.
  15     It uses a system of handlers() to
  16     provide access to user-defined virtual file systems.
  17
  18     @library{wxbase}
  19     @category{vfs}
  20
  21     @see wxFileSystemHandler, wxFSFile, Overview()
  22 */
  23 class wxFileSystem : public wxObject
  24 {
  25 public:
  26     /**
  27         Constructor.
  28     */
  29     wxFileSystem();
  30
  31     /**
  32         This static function adds new handler into the list of
  33         handlers() which provide access to virtual FS.
  34         Note that if two handlers for the same protocol are added, the last one added
  35         takes precedence.
  36     */
  37     static void AddHandler(wxFileSystemHandler handler);
  38
  39     /**
  40         Sets the current location. @a location parameter passed to
  41         OpenFile() is relative to this path.
  42         @b Caution! Unless @a is_dir is @true the @a location parameter
  43         is not the directory name but the name of the file in this directory. All these
  44         commands change the path to "dir/subdir/":
  45
  46         @param location
  47             the new location. Its meaning depends on the value of is_dir
  48         @param is_dir
  49             if @true location is new directory. If @false (default)
  50             location is file in the new directory.
  51     */
  52     void ChangePathTo(const wxString& location, bool is_dir = false);
  53
  54     /**
  55         Converts filename into URL.
  56
  57         @see URLToFileName(), wxFileName
  58     */
  59     static wxString FileNameToURL(wxFileName filename);
  60
  61     /**
  62         Looks for the file with the given name @a file in a colon or semi-colon
  63         (depending on the current platform) separated list of directories in
  64         @e path. If the file is found in any directory, returns @true and the full
  65         path of the file in @e str, otherwise returns @false and doesn't modify
  66         @e str.
  67
  68         @param str
  69             Receives the full path of the file, must not be @NULL
  70         @param path
  71             wxPATH_SEP-separated list of directories
  72         @param file
  73             the name of the file to look for
  74     */
  75     bool FindFileInPath(wxString str, const wxString& path,
  76                         const wxString& file);
  77
  78     /**
  79         Works like wxFindFirstFile(). Returns name of the first
  80         filename (within filesystem's current path) that matches @e wildcard. @a flags
  81         may be one of
  82         wxFILE (only files), wxDIR (only directories) or 0 (both).
  83     */
  84     wxString FindFirst(const wxString& wildcard, int flags = 0);
  85
  86     /**
  87         Returns the next filename that matches parameters passed to FindFirst().
  88     */
  89     wxString FindNext();
  90
  91     /**
  92         Returns actual path (set by wxFileSystem::ChangePathTo).
  93     */
  94     wxString GetPath();
  95
  96     /**
  97         This static function returns @true if there is a registered handler which can
  98         open the given
  99         location.
 100     */
 101     static bool HasHandlerForPath(const wxString& location);
 102
 103     /**
 104         Opens the file and returns a pointer to a wxFSFile object
 105         or @NULL if failed. It first tries to open the file in relative scope
 106         (based on value passed to ChangePathTo() method) and then as an
 107         absolute path.  Note that the user is responsible for deleting the returned
 108         wxFSFile.
 109         @a flags can be one or more of the following bit values ored together:
 110
 111         A stream opened with just the default @e wxFS_READ flag may
 112         or may not be seekable depending on the underlying source.
 113         Passing @e wxFS_READ | wxFS_SEEKABLE for @a flags will
 114         back a stream that is not natively seekable with memory or a file
 115         and return a stream that is always seekable.
 116     */
 117     wxFSFile* OpenFile(const wxString& location,
 118                        int flags = wxFS_READ);
 119
 120     /**
 121         Converts URL into a well-formed filename. The URL must use the @c file
 122         protocol.
 123     */
 124     static wxFileName URLToFileName(const wxString& url);
 125 };
 126
 127
 128
 129 /**
 130     @class wxFSFile
 131     @wxheader{filesys.h}
 132
 133     This class represents a single file opened by wxFileSystem.
 134     It provides more information than wxWindow's input stream
 135     (stream, filename, mime type, anchor).
 136
 137     @note Any pointer returned by a method of wxFSFile is valid
 138     only as long as the wxFSFile object exists. For example a call to GetStream()
 139     doesn't @e create the stream but only returns the pointer to it. In
 140     other words after 10 calls to GetStream() you will have obtained ten identical
 141     pointers.
 142
 143     @library{wxbase}
 144     @category{vfs}
 145
 146     @see wxFileSystemHandler, wxFileSystem, Overview()
 147 */
 148 class wxFSFile : public wxObject
 149 {
 150 public:
 151     /**
 152         Constructor. You probably won't use it. See Notes for details.
 153
 154         @param stream
 155             The input stream that will be used to access data
 156         @param location
 157             The full location (aka filename) of the file
 158         @param mimetype
 159             MIME type of this file. It may be left empty, in which
 160             case the type will be determined from file's extension (location must
 161             not be empty in this case).
 162         @param anchor
 163             Anchor. See GetAnchor() for details.
 164     */
 165     wxFSFile(wxInputStream stream, const wxString& loc,
 166              const wxString& mimetype,
 167              const wxString& anchor, wxDateTime modif);
 168
 169     /**
 170         Detaches the stream from the wxFSFile object. That is, the
 171         stream obtained with @c GetStream() will continue its existance
 172         after the wxFSFile object is deleted. You will have to delete
 173         the stream yourself.
 174     */
 175     void DetachStream();
 176
 177     /**
 178         Returns anchor (if present). The term of @b anchor can be easily
 179         explained using few examples:
 180
 181         Usually an anchor is presented only if the MIME type is 'text/html'.
 182         But it may have some meaning with other files;
 183         for example myanim.avi#200 may refer to position in animation
 184         or reality.wrl#MyView may refer to a predefined view in VRML.
 185     */
 186     const wxString GetAnchor() const;
 187
 188     /**
 189         Returns full location of the file, including path and protocol.
 190         Examples :
 191     */
 192     const wxString GetLocation() const;
 193
 194     /**
 195         Returns the MIME type of the content of this file. It is either
 196         extension-based (see wxMimeTypesManager) or extracted from
 197         HTTP protocol Content-Type header.
 198     */
 199     const wxString GetMimeType() const;
 200
 201     /**
 202         Returns time when this file was modified.
 203     */
 204     wxDateTime GetModificationTime() const;
 205
 206     /**
 207         Returns pointer to the stream. You can use the returned
 208         stream to directly access data. You may suppose
 209         that the stream provide Seek and GetSize functionality
 210         (even in the case of the HTTP protocol which doesn't provide
 211         this by default. wxHtml uses local cache to work around
 212         this and to speed up the connection).
 213     */
 214     wxInputStream* GetStream() const;
 215 };
 216
 217
 218
 219 /**
 220     @class wxFileSystemHandler
 221     @wxheader{filesys.h}
 222
 223     Classes derived from wxFileSystemHandler are used
 224     to access virtual file systems. Its public interface consists
 225     of two methods: wxFileSystemHandler::CanOpen
 226     and wxFileSystemHandler::OpenFile.
 227     It provides additional protected methods to simplify the process
 228     of opening the file: GetProtocol, GetLeftLocation, GetRightLocation,
 229     GetAnchor, GetMimeTypeFromExt.
 230
 231     Please have a look at overview() if you don't know how locations
 232     are constructed.
 233
 234     Also consult @ref overview_fs "list of available handlers".
 235
 236     @b wxPerl note: In wxPerl, you need to derive your file system handler class
 237     from Wx::PlFileSystemHandler.
 238
 239     @library{wxbase}
 240     @category{vfs}
 241
 242     @see wxFileSystem, wxFSFile, Overview()
 243 */
 244 class wxFileSystemHandler : public wxObject
 245 {
 246 public:
 247     /**
 248         Constructor.
 249     */
 250     wxFileSystemHandler();
 251
 252     /**
 253         Returns @true if the handler is able to open this file. This function doesn't
 254         check whether the file exists or not, it only checks if it knows the protocol.
 255         Example:
 256
 257         Must be overridden in derived handlers.
 258     */
 259     virtual bool CanOpen(const wxString& location);
 260
 261     /**
 262         Works like wxFindFirstFile(). Returns name of the first
 263         filename (within filesystem's current path) that matches @e wildcard. @a flags
 264         may be one of
 265         wxFILE (only files), wxDIR (only directories) or 0 (both).
 266         This method is only called if CanOpen() returns @true.
 267     */
 268     virtual wxString FindFirst(const wxString& wildcard,
 269                                int flags = 0);
 270
 271     /**
 272         Returns next filename that matches parameters passed to wxFileSystem::FindFirst.
 273         This method is only called if CanOpen() returns @true and FindFirst
 274         returned a non-empty string.
 275     */
 276     virtual wxString FindNext();
 277
 278     /**
 279         Returns the anchor if present in the location.
 280         See @ref wxFSFile::getanchor wxFSFile for details.
 281         Example: GetAnchor("index.htm#chapter2") == "chapter2"
 282         @note the anchor is NOT part of the left location.
 283     */
 284     wxString GetAnchor(const wxString& location) const;
 285
 286     /**
 287         Returns the left location string extracted from @e location.
 288         Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") ==
 289         "file:myzipfile.zip"
 290     */
 291     wxString GetLeftLocation(const wxString& location) const;
 292
 293     /**
 294         Returns the MIME type based on @b extension of @e location. (While
 295         wxFSFile::GetMimeType
 296         returns real MIME type - either extension-based or queried from HTTP.)
 297         Example : GetMimeTypeFromExt("index.htm") == "text/html"
 298     */
 299     wxString GetMimeTypeFromExt(const wxString& location);
 300
 301     /**
 302         Returns the protocol string extracted from @e location.
 303         Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip"
 304     */
 305     wxString GetProtocol(const wxString& location) const;
 306
 307     /**
 308         Returns the right location string extracted from @e location.
 309         Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm"
 310     */
 311     wxString GetRightLocation(const wxString& location) const;
 312
 313     /**
 314         Opens the file and returns wxFSFile pointer or @NULL if failed.
 315         Must be overridden in derived handlers.
 316
 317         @param fs
 318             Parent FS (the FS from that OpenFile was called). See ZIP handler
 319             for details of how to use it.
 320         @param location
 321             The absolute location of file.
 322     */
 323     virtual wxFSFile* OpenFile(wxFileSystem& fs,
 324                                const wxString& location);
 325 };
 326