interface/filesys.h

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