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. @a location parameter passed to
  42         OpenFile() is relative to this path.
  43         @b Caution! Unless @a is_dir is @true the @a location parameter
  44         is not the directory name but the name of the file in this directory. All these
  45         commands change the path to "dir/subdir/":
  46
  47         @param location
  48             the new location. Its meaning depends on the value of is_dir
  49         @param is_dir
  50             if @true location is new directory. If @false (default)
  51             location is file in the new directory.
  52     */
  53     void ChangePathTo(const wxString& location, bool is_dir = false);
  54
  55     /**
  56         Converts filename into URL.
  57
  58         @see URLToFileName(), wxFileName
  59     */
  60     static wxString FileNameToURL(wxFileName filename);
  61
  62     /**
  63         Looks for the file with the given name @a file in a colon or semi-colon
  64         (depending on the current platform) separated list of directories in
  65         @e path. If the file is found in any directory, returns @true and the full
  66         path of the file in @e str, otherwise returns @false and doesn't modify
  67         @e str.
  68
  69         @param str
  70             Receives the full path of the file, must not be @NULL
  71         @param path
  72             wxPATH_SEP-separated list of directories
  73         @param file
  74             the name of the file to look for
  75     */
  76     bool FindFileInPath(wxString str, const wxString& path,
  77                         const wxString& file);
  78
  79     /**
  80         Works like wxFindFirstFile. Returns name of the first
  81         filename (within filesystem's current path) that matches @e wildcard. @a flags
  82         may be one of
  83         wxFILE (only files), wxDIR (only directories) or 0 (both).
  84     */
  85     wxString FindFirst(const wxString& wildcard, int flags = 0);
  86
  87     /**
  88         Returns the next filename that matches parameters passed to FindFirst().
  89     */
  90     wxString FindNext();
  91
  92     /**
  93         Returns actual path (set by wxFileSystem::ChangePathTo).
  94     */
  95     wxString GetPath();
  96
  97     /**
  98         This static function returns @true if there is a registered handler which can
  99         open the given
 100         location.
 101     */
 102     static bool HasHandlerForPath(const wxString& location);
 103
 104     /**
 105         Opens the file and returns a pointer to a wxFSFile object
 106         or @NULL if failed. It first tries to open the file in relative scope
 107         (based on value passed to ChangePathTo() method) and then as an
 108         absolute path.  Note that the user is responsible for deleting the returned
 109         wxFSFile.
 110         @a flags can be one or more of the following bit values ored together:
 111
 112         A stream opened with just the default @e wxFS_READ flag may
 113         or may not be seekable depending on the underlying source.
 114         Passing @e wxFS_READ | wxFS_SEEKABLE for @a flags will
 115         back a stream that is not natively seekable with memory or a file
 116         and return a stream that is always seekable.
 117     */
 118     wxFSFile* OpenFile(const wxString& location,
 119                        int flags = wxFS_READ);
 120
 121     /**
 122         Converts URL into a well-formed filename. The URL must use the @c file
 123         protocol.
 124     */
 125     static wxFileName URLToFileName(const wxString& url);
 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     @b 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     @seealso
 147     wxFileSystemHandler, wxFileSystem, Overview
 148 */
 149 class wxFSFile : public wxObject
 150 {
 151 public:
 152     /**
 153         Constructor. You probably won't use it. See Notes for details.
 154
 155         @param stream
 156             The input stream that will be used to access data
 157         @param location
 158             The full location (aka filename) of the file
 159         @param mimetype
 160             MIME type of this file. It may be left empty, in which
 161             case the type will be determined from file's extension (location must
 162             not be empty in this case).
 163         @param anchor
 164             Anchor. See GetAnchor() for details.
 165     */
 166     wxFSFile(wxInputStream stream, const wxString& loc,
 167              const wxString& mimetype,
 168              const wxString& anchor, wxDateTime modif);
 169
 170     /**
 171         Detaches the stream from the wxFSFile object. That is, the
 172         stream obtained with @c GetStream() will continue its existance
 173         after the wxFSFile object is deleted. You will have to delete
 174         the stream yourself.
 175     */
 176     void DetachStream();
 177
 178     /**
 179         Returns anchor (if present). The term of @b anchor can be easily
 180         explained using few examples:
 181
 182         Usually an anchor is presented only if the MIME type is 'text/html'.
 183         But it may have some meaning with other files;
 184         for example myanim.avi#200 may refer to position in animation
 185         or reality.wrl#MyView may refer to a predefined view in VRML.
 186     */
 187     const wxString GetAnchor();
 188
 189     /**
 190         Returns full location of the file, including path and protocol.
 191         Examples :
 192     */
 193     const wxString GetLocation();
 194
 195     /**
 196         Returns the MIME type of the content of this file. It is either
 197         extension-based (see wxMimeTypesManager) or extracted from
 198         HTTP protocol Content-Type header.
 199     */
 200     const wxString GetMimeType();
 201
 202     /**
 203         Returns time when this file was modified.
 204     */
 205     wxDateTime GetModificationTime();
 206
 207     /**
 208         Returns pointer to the stream. You can use the returned
 209         stream to directly access data. You may suppose
 210         that the stream provide Seek and GetSize functionality
 211         (even in the case of the HTTP protocol which doesn't provide
 212         this by default. wxHtml uses local cache to work around
 213         this and to speed up the connection).
 214     */
 215     wxInputStream* GetStream();
 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     @seealso
 243     wxFileSystem, wxFSFile, Overview
 244 */
 245 class wxFileSystemHandler : public wxObject
 246 {
 247 public:
 248     /**
 249         Constructor.
 250     */
 251     wxFileSystemHandler();
 252
 253     /**
 254         Returns @true if the handler is able to open this file. This function doesn't
 255         check whether the file exists or not, it only checks if it knows the protocol.
 256         Example:
 257
 258         Must be overridden in derived handlers.
 259     */
 260     virtual bool CanOpen(const wxString& location);
 261
 262     /**
 263         Works like wxFindFirstFile. Returns name of the first
 264         filename (within filesystem's current path) that matches @e wildcard. @a flags
 265         may be one of
 266         wxFILE (only files), wxDIR (only directories) or 0 (both).
 267         This method is only called if CanOpen() returns @true.
 268     */
 269     virtual wxString FindFirst(const wxString& wildcard,
 270                                int flags = 0);
 271
 272     /**
 273         Returns next filename that matches parameters passed to wxFileSystem::FindFirst.
 274         This method is only called if CanOpen() returns @true and FindFirst
 275         returned a non-empty string.
 276     */
 277     virtual wxString FindNext();
 278
 279     /**
 280         Returns the anchor if present in the location.
 281         See @ref wxFSFile::getanchor wxFSFile for details.
 282         Example: GetAnchor("index.htm#chapter2") == "chapter2"
 283         @b Note: the anchor is NOT part of the left location.
 284     */
 285     wxString GetAnchor(const wxString& location);
 286
 287     /**
 288         Returns the left location string extracted from @e location.
 289         Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") ==
 290         "file:myzipfile.zip"
 291     */
 292     wxString GetLeftLocation(const wxString& location);
 293
 294     /**
 295         Returns the MIME type based on @b extension of @e location. (While
 296         wxFSFile::GetMimeType
 297         returns real MIME type - either extension-based or queried from HTTP.)
 298         Example : GetMimeTypeFromExt("index.htm") == "text/html"
 299     */
 300     wxString GetMimeTypeFromExt(const wxString& location);
 301
 302     /**
 303         Returns the protocol string extracted from @e location.
 304         Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip"
 305     */
 306     wxString GetProtocol(const wxString& location);
 307
 308     /**
 309         Returns the right location string extracted from @e location.
 310         Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm"
 311     */
 312     wxString GetRightLocation(const wxString& location);
 313
 314     /**
 315         Opens the file and returns wxFSFile pointer or @NULL if failed.
 316         Must be overridden in derived handlers.
 317
 318         @param fs
 319             Parent FS (the FS from that OpenFile was called). See ZIP handler
 320             for details of how to use it.
 321         @param location
 322             The absolute location of file.
 323     */
 324     virtual wxFSFile* OpenFile(wxFileSystem& fs,
 325                                const wxString& location);
 326 };