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