[wxWidgets.git] / interface / filesys.h

/////////////////////////////////////////////////////////////////////////////
// Name:        filesys.h
// Purpose:     documentation for wxFileSystem class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxFileSystem
    @wxheader{filesys.h}
    
    This class provides an interface for opening files on different
    file systems. It can handle absolute and/or local filenames.
    It uses a system of handlers to
    provide access to user-defined virtual file systems.
    
    @library{wxbase}
    @category{vfs}
    
    @seealso
    wxFileSystemHandler, wxFSFile, Overview
*/
class wxFileSystem : public wxObject
{
public:
    /**
        Constructor.
    */
    wxFileSystem();

    /**
        This static function adds new handler into the list of 
        handlers which provide access to virtual FS.
        Note that if two handlers for the same protocol are added, the last one added
        takes precedence.
    */
    static void AddHandler(wxFileSystemHandler handler);

    /**
        Sets the current location. @e location parameter passed to 
        OpenFile() is relative to this path.
        
        @b Caution! Unless @e is_dir is @true the @e location parameter
        is not the directory name but the name of the file in this directory. All these
        commands change the path to "dir/subdir/":
        
        @param location 
        the new location. Its meaning depends on the value of is_dir
        
        @param is_dir 
        if @true location is new directory. If @false (default) 
        location is file in the new directory.
    */
    void ChangePathTo(const wxString& location, bool is_dir = @false);

    /**
        Converts filename into URL.
        
        @sa URLToFileName(), wxFileName
    */
    static wxString FileNameToURL(wxFileName filename);

    /**
        Looks for the file with the given name @e file in a colon or semi-colon
        (depending on the current platform) separated list of directories in
        @e path. If the file is found in any directory, returns @true and the full
        path of the file in @e str, otherwise returns @false and doesn't modify 
        @e str.
        
        @param str 
        Receives the full path of the file, must not be @NULL
        
        @param path 
        wxPATH_SEP-separated list of directories
        
        @param file 
        the name of the file to look for
    */
    bool FindFileInPath(wxString str, const wxString& path,
                        const wxString& file);

    /**
        Works like wxFindFirstFile. Returns name of the first
        filename (within filesystem's current path) that matches @e wildcard. @e flags
        may be one of
        wxFILE (only files), wxDIR (only directories) or 0 (both).
    */
    wxString FindFirst(const wxString& wildcard, int flags = 0);

    /**
        Returns the next filename that matches parameters passed to FindFirst().
    */
    wxString FindNext();

    /**
        Returns actual path (set by wxFileSystem::ChangePathTo).
    */
    wxString GetPath();

    /**
        This static function returns @true if there is a registered handler which can
        open the given
        location.
    */
    static bool HasHandlerForPath(const wxString & location);

    /**
        Opens the file and returns a pointer to a wxFSFile object
        or @NULL if failed. It first tries to open the file in relative scope
        (based on value passed to ChangePathTo() method) and then as an
        absolute path.  Note that the user is responsible for deleting the returned
        wxFSFile.  
        
        @e flags can be one or more of the following bit values ored together:
        A stream opened with just the default @e wxFS_READ flag may
        or may not be seekable depending on the underlying source.
        Passing @e wxFS_READ | wxFS_SEEKABLE for @e flags will
        back a stream that is not natively seekable with memory or a file
        and return a stream that is always seekable.
    */
    wxFSFile* OpenFile(const wxString& location,
                       int flags = wxFS_READ);

    /**
        Converts URL into a well-formed filename. The URL must use the @c file 
        protocol.
    */
    static wxFileName URLToFileName(const wxString& url);
};


/**
    @class wxFSFile
    @wxheader{filesys.h}
    
    This class represents a single file opened by wxFileSystem.
    It provides more information than wxWindow's input stream 
    (stream, filename, mime type, anchor).
    
    @b Note: Any pointer returned by a method of wxFSFile is valid
    only as long as the wxFSFile object exists. For example a call to GetStream()
    doesn't @e create the stream but only returns the pointer to it. In
    other words after 10 calls to GetStream() you will have obtained ten identical
    pointers.
    
    @library{wxbase}
    @category{vfs}
    
    @seealso
    wxFileSystemHandler, wxFileSystem, Overview
*/
class wxFSFile : public wxObject
{
public:
    /**
        Constructor. You probably won't use it. See Notes for details.
        
        @param stream 
        The input stream that will be used to access data
        
        @param location 
        The full location (aka filename) of the file
        
        @param mimetype 
        MIME type of this file. It may be left empty, in which
        case the type will be determined from file's extension (location must
        not be empty in this case).
        
        @param anchor 
        Anchor. See GetAnchor() for details.
    */
    wxFSFile(wxInputStream stream, const wxString& loc,
             const wxString& mimetype,
             const wxString& anchor, wxDateTime modif);

    /**
        Detaches the stream from the wxFSFile object. That is, the
        stream obtained with @c GetStream() will continue its existance
        after the wxFSFile object is deleted. You will have to delete
        the stream yourself.
    */
    void DetachStream();

    /**
        Returns anchor (if present). The term of @b anchor can be easily
        explained using few examples:
        Usually an anchor is presented only if the MIME type is 'text/html'.
        But it may have some meaning with other files;
        for example myanim.avi#200 may refer to position in animation
        or reality.wrl#MyView may refer to a predefined view in VRML.
    */
    const wxString GetAnchor();

    /**
        Returns full location of the file, including path and protocol. 
        Examples :
    */
    const wxString GetLocation();

    /**
        Returns the MIME type of the content of this file. It is either
        extension-based (see wxMimeTypesManager) or extracted from
        HTTP protocol Content-Type header.
    */
    const wxString GetMimeType();

    /**
        Returns time when this file was modified.
    */
    wxDateTime GetModificationTime();

    /**
        Returns pointer to the stream. You can use the returned
        stream to directly access data. You may suppose
        that the stream provide Seek and GetSize functionality
        (even in the case of the HTTP protocol which doesn't provide
        this by default. wxHtml uses local cache to work around
        this and to speed up the connection).
    */
    wxInputStream* GetStream();
};


/**
    @class wxFileSystemHandler
    @wxheader{filesys.h}
    
    Classes derived from wxFileSystemHandler are used
    to access virtual file systems. Its public interface consists
    of two methods: wxFileSystemHandler::CanOpen 
    and wxFileSystemHandler::OpenFile. 
    It provides additional protected methods to simplify the process
    of opening the file: GetProtocol, GetLeftLocation, GetRightLocation,
    GetAnchor, GetMimeTypeFromExt.
    
    Please have a look at overview if you don't know how locations
    are constructed.
    
    Also consult @ref overview_fs "list of available handlers".
    
    @b wxPerl note: In wxPerl, you need to derive your file system handler class
    from Wx::PlFileSystemHandler.
    
    @library{wxbase}
    @category{vfs}
    
    @seealso
    wxFileSystem, wxFSFile, Overview
*/
class wxFileSystemHandler : public wxObject
{
public:
    /**
        Constructor.
    */
    wxFileSystemHandler();

    /**
        Returns @true if the handler is able to open this file. This function doesn't
        check whether the file exists or not, it only checks if it knows the protocol.
        Example:
        Must be overridden in derived handlers.
    */
    virtual bool CanOpen(const wxString& location);

    /**
        Works like wxFindFirstFile. Returns name of the first
        filename (within filesystem's current path) that matches @e wildcard. @e flags
        may be one of
        wxFILE (only files), wxDIR (only directories) or 0 (both).
        
        This method is only called if CanOpen() returns @true.
    */
    virtual wxString FindFirst(const wxString& wildcard,
                               int flags = 0);

    /**
        Returns next filename that matches parameters passed to wxFileSystem::FindFirst.
        
        This method is only called if CanOpen() returns @true and FindFirst
        returned a non-empty string.
    */
    virtual wxString FindNext();

    /**
        Returns the anchor if present in the location.
        See @ref wxFSFile::getanchor wxFSFile for details.
        
        Example: GetAnchor("index.htm#chapter2") == "chapter2"
        
        @b Note: the anchor is NOT part of the left location.
    */
    wxString GetAnchor(const wxString& location);

    /**
        Returns the left location string extracted from @e location. 
        
        Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") ==
        "file:myzipfile.zip"
    */
    wxString GetLeftLocation(const wxString& location);

    /**
        Returns the MIME type based on @b extension of @e location. (While
        wxFSFile::GetMimeType
        returns real MIME type - either extension-based or queried from HTTP.)
        
        Example : GetMimeTypeFromExt("index.htm") == "text/html"
    */
    wxString GetMimeTypeFromExt(const wxString& location);

    /**
        Returns the protocol string extracted from @e location. 
        
        Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip"
    */
    wxString GetProtocol(const wxString& location);

    /**
        Returns the right location string extracted from @e location. 
        
        Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm"
    */
    wxString GetRightLocation(const wxString& location);

    /**
        Opens the file and returns wxFSFile pointer or @NULL if failed.
        
        Must be overridden in derived handlers.
        
        @param fs 
        Parent FS (the FS from that OpenFile was called). See ZIP handler
        for details of how to use it.
        
        @param location 
        The absolute location of file.
    */
    virtual wxFSFile* OpenFile(wxFileSystem& fs,
                               const wxString& location);
};
Commit	Line	Data
23324ae1 FM	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	};