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