interface/mimetype.h

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