interface/mimetype.h

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