[wxWidgets.git] / interface / mimetype.h

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

/**
    @class wxMimeTypesManager
    @wxheader{mimetype.h}
    
    This class allows the application to retrieve the information about all known
    MIME types from a system-specific location and the filename extensions to the
    MIME types and vice versa. After initialization the functions
    wxMimeTypesManager::GetFileTypeFromMimeType 
    and wxMimeTypesManager::GetFileTypeFromExtension 
    may be called: they will return a wxFileType object which
    may be further queried for file description, icon and other attributes.
    
    @b Windows: MIME type information is stored in the registry and no additional
    initialization is needed.
    
    @b Unix: MIME type information is stored in the files mailcap and mime.types
    (system-wide) and .mailcap and .mime.types in the current user's home directory:
    all of these files are searched for and loaded if found by default. However,
    additional functions 
    wxMimeTypesManager::ReadMailcap and 
    wxMimeTypesManager::ReadMimeTypes are
    provided to load additional files.
    
    If GNOME or KDE desktop environment is installed, then wxMimeTypesManager 
    gathers MIME information from respective files (e.g. .kdelnk files under KDE).
    
    NB: Currently, wxMimeTypesManager is limited to reading MIME type information
    but it will support modifying it as well in future versions.
    
    @library{wxbase}
    @category{misc}
    
    @seealso
    wxFileType
*/
class wxMimeTypesManager 
{
public:
    /**
        Constructor puts the object in the "working" state, no additional initialization
        are needed - but @ref init() ReadXXX may be used to load
        additional mailcap/mime.types files.
    */
    wxMimeTypesManager();

    /**
        Destructor is not virtual, so this class should not be derived from.
    */
    ~wxMimeTypesManager();

    /**
        This function may be used to provide hard-wired fallbacks for the MIME types
        and extensions that might not be present in the system MIME database.
        
        Please see the typetest sample for an example of using it.
    */
    void AddFallbacks(const wxFileTypeInfo * fallbacks);

    /**
        NB: You won't normally need to use more than one wxMimeTypesManager object in a
        program.
        
        @ref ctor() wxMimeTypesManager
        
        @ref dtor() ~wxMimeTypesManager
    */


    /**
        Gather information about the files with given extension and return the
        corresponding wxFileType object or @NULL if the extension
        is unknown.
        
        The @e extension parameter may have, or not, the leading dot, if it has it,
        it is stripped automatically. It must not however be empty.
    */
    wxFileType* GetFileTypeFromExtension(const wxString& extension);

    /**
        Gather information about the files with given MIME type and return the
        corresponding wxFileType object or @NULL if the MIME type
        is unknown.
    */
    wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);

    /**
        All of these functions are static (i.e. don't need a wxMimeTypesManager object
        to call them) and provide some useful operations for string representations of
        MIME types. Their usage is recommended instead of directly working with MIME
        types using wxString functions.
        
        IsOfType()
    */


    /**
        @b Unix: These functions may be used to load additional files (except for the
        default ones which are loaded automatically) containing MIME
        information in either mailcap(5) or mime.types(5) format.
        
        ReadMailcap()
        
        ReadMimeTypes()
        
        AddFallbacks()
    */


    /**
        This function returns @true if either the given @e mimeType is exactly the
        same as @e wildcard or if it has the same category and the subtype of
        @e wildcard is '*'. Note that the '*' wildcard is not allowed in
        @e mimeType itself.
        
        The comparison don by this function is case insensitive so it is not
        necessary to convert the strings to the same case before calling it.
    */
    bool IsOfType(const wxString& mimeType, const wxString& wildcard);

    /**
        These functions are the heart of this class: they allow to find a @ref
        overview_wxfiletype "file type" object
        from either file extension or MIME type.
        If the function is successful, it returns a pointer to the wxFileType object
        which @b must be deleted by the caller, otherwise @NULL will be returned.
        
        GetFileTypeFromMimeType()
        
        GetFileTypeFromExtension()
    */


    /**
        Load additional file containing information about MIME types and associated
        information in mailcap format. See metamail(1) and mailcap(5) for more
        information.
        
        @e fallback parameter may be used to load additional mailcap files without
        overriding the settings found in the standard files: normally, entries from
        files loaded with ReadMailcap will override the entries from files loaded
        previously (and the standard ones are loaded in the very beginning), but this
        will not happen if this parameter is set to @true (default is @false).
        
        The return value is @true if there were no errors in the file or @false
        otherwise.
    */
    bool ReadMailcap(const wxString& filename, bool fallback = @false);

    /**
        Load additional file containing information about MIME types and associated
        information in mime.types file format. See metamail(1) and mailcap(5) for more
        information.
        
        The return value is @true if there were no errors in the file or @false
        otherwise.
    */
    bool ReadMimeTypes(const wxString& filename);
};


/**
    @class wxFileType
    @wxheader{mimetype.h}
    
    This class holds information about a given @e file type. File type is the same
    as
    MIME type under Unix, but under Windows it corresponds more to an extension than
    to MIME type (in fact, several extensions may correspond to a file type). This
    object may be created in several different ways: the program might know the file
    extension and wish to find out the corresponding MIME type or, conversely, it
    might want to find the right extension for the file to which it writes the
    contents of given MIME type. Depending on how it was created some fields may be
    unknown so the return value of all the accessors @b must be checked: @false
    will be returned if the corresponding information couldn't be found.
    
    The objects of this class are never created by the application code but are
    returned by wxMimeTypesManager::GetFileTypeFromMimeType and 
    wxMimeTypesManager::GetFileTypeFromExtension methods.
    But it is your responsibility to delete the returned pointer when you're done
    with it!
    
    A brief reminder about what the MIME types are (see the RFC 1341 for more
    information): basically, it is just a pair category/type (for example,
    "text/plain") where the category is a basic indication of what a file is.
    Examples of categories are "application", "image", "text", "binary", and
    type is a precise definition of the document format: "plain" in the example
    above means just ASCII text without any formatting, while "text/html" is the
    HTML document source.
    
    A MIME type may have one or more associated extensions: "text/plain" will
    typically correspond to the extension ".txt", but may as well be associated with
    ".ini" or ".conf".
    
    @library{wxbase}
    @category{FIXME}
    
    @seealso
    wxMimeTypesManager
*/
class wxFileType 
{
public:
    /**
        The default constructor is private because you should never create objects of
        this type: they are only returned by wxMimeTypesManager methods.
    */
    wxFileType();

    /**
        The destructor of this class is not virtual, so it should not be derived from.
    */
    ~wxFileType();

    /**
        This function is primarily intended for GetOpenCommand and GetPrintCommand
        usage but may be also used by the application directly if, for example, you want
        to use some non-default command to open the file.
        
        The function replaces all occurrences of
        
        
        format specification
        
        
        with
        
        %s
        
        
        the full file name
        
        %t
        
        
        the MIME type
        
        %{param}
        
        
        the value of the parameter @e param
        
        using the MessageParameters object you pass to it.
        
        If there is no '%s' in the command string (and the string is not empty), it is
        assumed that the command reads the data on stdin and so the effect is the same
        as " %s" were appended to the string.
        
        Unlike all other functions of this class, there is no error return for this
        function.
    */
    static wxString ExpandCommand(const wxString& command,
                                  MessageParameters& params);

    /**
        If the function returns @true, the string pointed to by @e desc is filled
        with a brief description for this file type: for example, "text document" for
        the "text/plain" MIME type.
    */
    bool GetDescription(wxString* desc);

    /**
        If the function returns @true, the array @e extensions is filled
        with all extensions associated with this file type: for example, it may
        contain the following two elements for the MIME type "text/html" (notice the
        absence of the leading dot): "html" and "htm".
        
        @b Windows: This function is currently not implemented: there is no
        (efficient) way to retrieve associated extensions from the given MIME type on
        this platform, so it will only return @true if the wxFileType object was
        created
        by wxMimeTypesManager::GetFileTypeFromExtension 
        function in the first place.
    */
    bool GetExtensions(wxArrayString& extensions);

    /**
        If the function returns @true, the @c iconLoc is filled with the
        location of the icon for this MIME type. A wxIcon may be
        created from @e iconLoc later.
        
        @b Windows: The function returns the icon shown by Explorer for the files of
        the specified type.
        
        @b Mac: This function is not implemented and always returns @false.
        
        @b Unix: MIME manager gathers information about icons from GNOME
        and KDE settings and thus GetIcon's success depends on availability
        of these desktop environments.
    */
    bool GetIcon(wxIconLocation * iconLoc);

    /**
        If the function returns @true, the string pointed to by @e mimeType is filled
        with full MIME type specification for this file type: for example, "text/plain".
    */
    bool GetMimeType(wxString* mimeType);

    /**
        Same as GetMimeType() but returns array of MIME
        types. This array will contain only one item in most cases but sometimes,
        notably under Unix with KDE, may contain more MIME types. This happens when
        one file extension is mapped to different MIME types by KDE, mailcap and
        mime.types.
    */
    bool GetMimeType(wxArrayString& mimeTypes);

    //@{
    /**
        With the first version of this method, if the @true is returned, the
        string pointed to by @e command is filled with the command which must be
        executed (see wxExecute) in order to open the file of the
        given type. In this case, the name of the file as well as any other parameters
        is retrieved from MessageParameters() 
        class.
        
        In the second case, only the filename is specified and the command to be used
        to open this kind of file is returned directly. An empty string is returned to
        indicate that an error occurred (typically meaning that there is no standard way
        to open this kind of files).
    */
    bool GetOpenCommand(wxString* command,
                        MessageParameters& params);
        wxString GetOpenCommand(const wxString& filename);
    //@}

    /**
        If the function returns @true, the string pointed to by @e command is filled
        with the command which must be executed (see wxExecute) in
        order to print the file of the given type. The name of the file is
        retrieved from MessageParameters() class.
    */
    bool GetPrintCommand(wxString* command,
                         MessageParameters& params);

    /**
        One of the most common usages of MIME is to encode an e-mail message. The MIME
        type of the encoded message is an example of a @e message parameter. These
        parameters are found in the message headers ("Content-XXX"). At the very least,
        they must specify the MIME type and the version of MIME used, but almost always
        they provide additional information about the message such as the original file
        name or the charset (for the text documents).
        
        These parameters may be useful to the program used to open, edit, view or print
        the message, so, for example, an e-mail client program will have to pass them to
        this program. Because wxFileType itself can not know about these parameters,
        it uses MessageParameters class to query them. The default implementation only
        requires the caller to provide the file name (always used by the program to be
        called - it must know which file to open) and the MIME type and supposes that
        there are no other parameters. If you wish to supply additional parameters, you
        must derive your own class from MessageParameters and override GetParamValue()
        function, for example:
        Now you only need to create an object of this class and pass it to, for example,
        GetOpenCommand() like this:
        @b Windows: As only the file name is used by the program associated with the
        given extension anyhow (but no other message parameters), there is no need to
        ever derive from MessageParameters class for a Windows-only program.
    */
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: mimetype.h
	3	// Purpose: documentation for wxMimeTypesManager class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxMimeTypesManager
	11	@wxheader{mimetype.h}
	12
	13	This class allows the application to retrieve the information about all known
	14	MIME types from a system-specific location and the filename extensions to the
	15	MIME types and vice versa. After initialization the functions
	16	wxMimeTypesManager::GetFileTypeFromMimeType
	17	and wxMimeTypesManager::GetFileTypeFromExtension
	18	may be called: they will return a wxFileType object which
	19	may be further queried for file description, icon and other attributes.
	20
	21	@b Windows: MIME type information is stored in the registry and no additional
	22	initialization is needed.
	23
	24	@b Unix: MIME type information is stored in the files mailcap and mime.types
	25	(system-wide) and .mailcap and .mime.types in the current user's home directory:
	26	all of these files are searched for and loaded if found by default. However,
	27	additional functions
	28	wxMimeTypesManager::ReadMailcap and
	29	wxMimeTypesManager::ReadMimeTypes are
	30	provided to load additional files.
	31
	32	If GNOME or KDE desktop environment is installed, then wxMimeTypesManager
	33	gathers MIME information from respective files (e.g. .kdelnk files under KDE).
	34
	35	NB: Currently, wxMimeTypesManager is limited to reading MIME type information
	36	but it will support modifying it as well in future versions.
	37
	38	@library{wxbase}
	39	@category{misc}
	40
	41	@seealso
	42	wxFileType
	43	*/
	44	class wxMimeTypesManager
	45	{
	46	public:
	47	/**
	48	Constructor puts the object in the "working" state, no additional initialization
	49	are needed - but @ref init() ReadXXX may be used to load
	50	additional mailcap/mime.types files.
	51	*/
	52	wxMimeTypesManager();
	53
	54	/**
	55	Destructor is not virtual, so this class should not be derived from.
	56	*/
	57	~wxMimeTypesManager();
	58
	59	/**
	60	This function may be used to provide hard-wired fallbacks for the MIME types
	61	and extensions that might not be present in the system MIME database.
	62
	63	Please see the typetest sample for an example of using it.
	64	*/
65	void AddFallbacks(const wxFileTypeInfo * fallbacks);
66
67	/**
68	NB: You won't normally need to use more than one wxMimeTypesManager object in a
69	program.
70
71	@ref ctor() wxMimeTypesManager
72
73	@ref dtor() ~wxMimeTypesManager
74	*/
75
76
77	/**
78	Gather information about the files with given extension and return the
79	corresponding wxFileType object or @NULL if the extension
80	is unknown.
81
82	The @e extension parameter may have, or not, the leading dot, if it has it,
83	it is stripped automatically. It must not however be empty.
84	*/
85	wxFileType* GetFileTypeFromExtension(const wxString& extension);
86
87	/**
88	Gather information about the files with given MIME type and return the
89	corresponding wxFileType object or @NULL if the MIME type
90	is unknown.
91	*/
92	wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);
93
94	/**
95	All of these functions are static (i.e. don't need a wxMimeTypesManager object
96	to call them) and provide some useful operations for string representations of
97	MIME types. Their usage is recommended instead of directly working with MIME
98	types using wxString functions.
99
100	IsOfType()
101	*/
102
103
104	/**
105	@b Unix: These functions may be used to load additional files (except for the
106	default ones which are loaded automatically) containing MIME
107	information in either mailcap(5) or mime.types(5) format.
108
109	ReadMailcap()
110
111	ReadMimeTypes()
112
113	AddFallbacks()
114	*/
115
116
117	/**
118	This function returns @true if either the given @e mimeType is exactly the
119	same as @e wildcard or if it has the same category and the subtype of
120	@e wildcard is ''. Note that the '' wildcard is not allowed in
121	@e mimeType itself.
122
123	The comparison don by this function is case insensitive so it is not
124	necessary to convert the strings to the same case before calling it.
125	*/
126	bool IsOfType(const wxString& mimeType, const wxString& wildcard);
127
128	/**
129	These functions are the heart of this class: they allow to find a @ref
130	overview_wxfiletype "file type" object
131	from either file extension or MIME type.
132	If the function is successful, it returns a pointer to the wxFileType object
133	which @b must be deleted by the caller, otherwise @NULL will be returned.
134
135	GetFileTypeFromMimeType()
136
137	GetFileTypeFromExtension()
138	*/
139
140
141	/**
142	Load additional file containing information about MIME types and associated
143	information in mailcap format. See metamail(1) and mailcap(5) for more
144	information.
145
146	@e fallback parameter may be used to load additional mailcap files without
147	overriding the settings found in the standard files: normally, entries from
148	files loaded with ReadMailcap will override the entries from files loaded
149	previously (and the standard ones are loaded in the very beginning), but this
150	will not happen if this parameter is set to @true (default is @false).
151
152	The return value is @true if there were no errors in the file or @false
153	otherwise.
154	*/
155	bool ReadMailcap(const wxString& filename, bool fallback = @false);
156
157	/**
158	Load additional file containing information about MIME types and associated
159	information in mime.types file format. See metamail(1) and mailcap(5) for more
160	information.
161
162	The return value is @true if there were no errors in the file or @false
163	otherwise.
164	*/
165	bool ReadMimeTypes(const wxString& filename);
166	};
167
168
169	/**
170	@class wxFileType
171	@wxheader{mimetype.h}
172
173	This class holds information about a given @e file type. File type is the same
174	as
175	MIME type under Unix, but under Windows it corresponds more to an extension than
176	to MIME type (in fact, several extensions may correspond to a file type). This
177	object may be created in several different ways: the program might know the file
178	extension and wish to find out the corresponding MIME type or, conversely, it
179	might want to find the right extension for the file to which it writes the
180	contents of given MIME type. Depending on how it was created some fields may be
181	unknown so the return value of all the accessors @b must be checked: @false
182	will be returned if the corresponding information couldn't be found.
183
184	The objects of this class are never created by the application code but are
185	returned by wxMimeTypesManager::GetFileTypeFromMimeType and
186	wxMimeTypesManager::GetFileTypeFromExtension methods.
187	But it is your responsibility to delete the returned pointer when you're done
188	with it!
189
190	A brief reminder about what the MIME types are (see the RFC 1341 for more
191	information): basically, it is just a pair category/type (for example,
192	"text/plain") where the category is a basic indication of what a file is.
193	Examples of categories are "application", "image", "text", "binary", and
194	type is a precise definition of the document format: "plain" in the example
195	above means just ASCII text without any formatting, while "text/html" is the
196	HTML document source.
197
198	A MIME type may have one or more associated extensions: "text/plain" will
199	typically correspond to the extension ".txt", but may as well be associated with
200	".ini" or ".conf".
201
202	@library{wxbase}
203	@category{FIXME}
204
205	@seealso
206	wxMimeTypesManager
207	*/
208	class wxFileType
209	{
210	public:
211	/**
212	The default constructor is private because you should never create objects of
213	this type: they are only returned by wxMimeTypesManager methods.
214	*/
215	wxFileType();
216
217	/**
218	The destructor of this class is not virtual, so it should not be derived from.
219	*/
220	~wxFileType();
221
222	/**
223	This function is primarily intended for GetOpenCommand and GetPrintCommand
224	usage but may be also used by the application directly if, for example, you want
225	to use some non-default command to open the file.
226
227	The function replaces all occurrences of
228
229
230	format specification
231
232
233	with
234
235	%s
236
237
238	the full file name
239
240	%t
241
242
243	the MIME type
244
245	%{param}
246
247
248	the value of the parameter @e param
249
250	using the MessageParameters object you pass to it.
251
252	If there is no '%s' in the command string (and the string is not empty), it is
253	assumed that the command reads the data on stdin and so the effect is the same
254	as " %s" were appended to the string.
255
256	Unlike all other functions of this class, there is no error return for this
257	function.
258	*/
259	static wxString ExpandCommand(const wxString& command,
260	MessageParameters& params);
261
262	/**
263	If the function returns @true, the string pointed to by @e desc is filled
264	with a brief description for this file type: for example, "text document" for
265	the "text/plain" MIME type.
266	*/
267	bool GetDescription(wxString* desc);
268
269	/**
270	If the function returns @true, the array @e extensions is filled
271	with all extensions associated with this file type: for example, it may
272	contain the following two elements for the MIME type "text/html" (notice the
273	absence of the leading dot): "html" and "htm".
274
275	@b Windows: This function is currently not implemented: there is no
276	(efficient) way to retrieve associated extensions from the given MIME type on
277	this platform, so it will only return @true if the wxFileType object was
278	created
279	by wxMimeTypesManager::GetFileTypeFromExtension
280	function in the first place.
281	*/
282	bool GetExtensions(wxArrayString& extensions);
283
284	/**
285	If the function returns @true, the @c iconLoc is filled with the
286	location of the icon for this MIME type. A wxIcon may be
287	created from @e iconLoc later.
288
289	@b Windows: The function returns the icon shown by Explorer for the files of
290	the specified type.
291
292	@b Mac: This function is not implemented and always returns @false.
293
294	@b Unix: MIME manager gathers information about icons from GNOME
295	and KDE settings and thus GetIcon's success depends on availability
296	of these desktop environments.
297	*/
298	bool GetIcon(wxIconLocation * iconLoc);
299
300	/**
301	If the function returns @true, the string pointed to by @e mimeType is filled
302	with full MIME type specification for this file type: for example, "text/plain".
303	*/
304	bool GetMimeType(wxString* mimeType);
305
306	/**
307	Same as GetMimeType() but returns array of MIME
308	types. This array will contain only one item in most cases but sometimes,
309	notably under Unix with KDE, may contain more MIME types. This happens when
310	one file extension is mapped to different MIME types by KDE, mailcap and
311	mime.types.
312	*/
313	bool GetMimeType(wxArrayString& mimeTypes);
314
315	//@{
316	/**
317	With the first version of this method, if the @true is returned, the
318	string pointed to by @e command is filled with the command which must be
319	executed (see wxExecute) in order to open the file of the
320	given type. In this case, the name of the file as well as any other parameters
321	is retrieved from MessageParameters()
322	class.
323
324	In the second case, only the filename is specified and the command to be used
325	to open this kind of file is returned directly. An empty string is returned to
326	indicate that an error occurred (typically meaning that there is no standard way
327	to open this kind of files).
328	*/
329	bool GetOpenCommand(wxString* command,
330	MessageParameters& params);
331	wxString GetOpenCommand(const wxString& filename);
332	//@}
333
334	/**
335	If the function returns @true, the string pointed to by @e command is filled
336	with the command which must be executed (see wxExecute) in
337	order to print the file of the given type. The name of the file is
338	retrieved from MessageParameters() class.
339	*/
340	bool GetPrintCommand(wxString* command,
341	MessageParameters& params);
342
343	/**
344	One of the most common usages of MIME is to encode an e-mail message. The MIME
345	type of the encoded message is an example of a @e message parameter. These
346	parameters are found in the message headers ("Content-XXX"). At the very least,
347	they must specify the MIME type and the version of MIME used, but almost always
348	they provide additional information about the message such as the original file
349	name or the charset (for the text documents).
350
351	These parameters may be useful to the program used to open, edit, view or print
352	the message, so, for example, an e-mail client program will have to pass them to
353	this program. Because wxFileType itself can not know about these parameters,
354	it uses MessageParameters class to query them. The default implementation only
355	requires the caller to provide the file name (always used by the program to be
356	called - it must know which file to open) and the MIME type and supposes that
357	there are no other parameters. If you wish to supply additional parameters, you
358	must derive your own class from MessageParameters and override GetParamValue()
359	function, for example:
360	Now you only need to create an object of this class and pass it to, for example,
361	GetOpenCommand() like this:
362	@b Windows: As only the file name is used by the program associated with the
363	given extension anyhow (but no other message parameters), there is no need to
364	ever derive from MessageParameters class for a Windows-only program.
365	*/
366	};