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 licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMimeTypesManager
  11
  12     This class allows the application to retrieve informations about all known
  13     MIME types from a system-specific location and the filename extensions to the
  14     MIME types and vice versa.
  15
  16     MIME stands for "Multipurpose Internet Mail Extensions" and was originally
  17     used in mail protocols. It's standardized by several RFCs.
  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 @e reading MIME type information.
  23
  24     The application should not construct its own manager: it should use the
  25     object pointer ::wxTheMimeTypesManager.
  26     The functions GetFileTypeFromMimeType() and GetFileTypeFromExtension()
  27     return a wxFileType object which may be further queried for file description,
  28     icon and other attributes.
  29
  30     @section mimetypemanager_helpers Helper functions
  31
  32     All of these functions are static (i.e. don't need a wxMimeTypesManager object
  33     to call them) and provide some useful operations for string representations of
  34     MIME types. Their usage is recommended instead of directly working with MIME
  35     types using wxString functions.
  36
  37     - wxMimeTypesManager::IsOfType()
  38
  39     @section mimetypemanager_query Query database
  40
  41     These functions are the heart of this class: they allow to find a file type
  42     object from either file extension or MIME type.
  43     If the function is successful, it returns a pointer to the wxFileType object
  44     which must be deleted by the caller, otherwise @NULL will be returned.
  45
  46     - wxMimeTypesManager::GetFileTypeFromMimeType()
  47     - wxMimeTypesManager::GetFileTypeFromExtension()
  48
  49     @library{wxbase}
  50     @category{cfg}
  51
  52     @see wxFileType
  53 */
  54 class wxMimeTypesManager
  55 {
  56 public:
  57     /**
  58         Constructor puts the object in the "working" state.
  59     */
  60     wxMimeTypesManager();
  61
  62     /**
  63         Destructor is not virtual, so this class should not be derived from.
  64     */
  65     ~wxMimeTypesManager();
  66
  67     /**
  68         This function may be used to provide hard-wired fallbacks for the MIME types
  69         and extensions that might not be present in the system MIME database.
  70         Please see the typetest sample for an example of using it.
  71     */
  72     void AddFallbacks(const wxFileTypeInfo* fallbacks);
  73
  74     /**
  75         Gather information about the files with given extension and return the
  76         corresponding wxFileType object or @NULL if the extension is unknown.
  77
  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 is unknown.
  86     */
  87     wxFileType* GetFileTypeFromMimeType(const wxString& mimeType);
  88
  89
  90     /**
  91         This function returns @true if either the given @a mimeType is exactly
  92         the same as @a wildcard or if it has the same category and the subtype of
  93         @a wildcard is '*'. Note that the '*' wildcard is not allowed in
  94         @a mimeType itself.
  95
  96         The comparison don by this function is case insensitive so it is not
  97         necessary to convert the strings to the same case before calling it.
  98     */
  99     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 100 };
 101
 102
 103 /**
 104     The global wxMimeTypesManager instance.
 105 */
 106 wxMimeTypesManager* wxTheMimeTypesManager;
 107
 108
 109 /**
 110     @class wxFileType
 111
 112     This class holds information about a given @e file type.
 113
 114     File type is the same as MIME type under Unix, but under Windows it corresponds
 115     more to an extension than to MIME type (in fact, several extensions may
 116     correspond to a file type).
 117
 118     This object may be created in several different ways: the program might know the
 119     file extension and wish to find out the corresponding MIME type or, conversely, it
 120     might want to find the right extension for the file to which it writes the
 121     contents of given MIME type. Depending on how it was created some fields may be
 122     unknown so the return value of all the accessors @b must be checked: @false
 123     will be returned if the corresponding information couldn't be found.
 124
 125     The objects of this class are never created by the application code but are
 126     returned by wxMimeTypesManager::GetFileTypeFromMimeType and
 127     wxMimeTypesManager::GetFileTypeFromExtension methods.
 128     But it is your responsibility to delete the returned pointer when you're done
 129     with it!
 130
 131     A brief reminder about what the MIME types are (see the RFC 1341 for more
 132     information): basically, it is just a pair category/type (for example,
 133     "text/plain") where the category is a basic indication of what a file is.
 134     Examples of categories are "application", "image", "text", "binary", and
 135     type is a precise definition of the document format: "plain" in the example
 136     above means just ASCII text without any formatting, while "text/html" is the
 137     HTML document source.
 138
 139     A MIME type may have one or more associated extensions: "text/plain" will
 140     typically correspond to the extension ".txt", but may as well be associated with
 141     ".ini" or ".conf".
 142
 143
 144     @section filetype_example MessageParameters class
 145
 146     One of the most common usages of MIME is to encode an e-mail message.
 147     The MIME type of the encoded message is an example of a message parameter.
 148     These parameters are found in the message headers ("Content-XXX").
 149
 150     At the very least, they must specify the MIME type and the version of MIME
 151     used, but almost always they provide additional information about the message
 152     such as the original file name or the charset (for the text documents).
 153     These parameters may be useful to the program used to open, edit, view or
 154     print the message, so, for example, an e-mail client program will have to
 155     pass them to this program. Because wxFileType itself cannot know about
 156     these parameters, it uses MessageParameters class to query them.
 157
 158     The default implementation only requires the caller to provide the file name
 159     (always used by the program to be called - it must know which file to open)
 160     and the MIME type and supposes that there are no other parameters.
 161
 162     If you wish to supply additional parameters, you must derive your own class
 163     from MessageParameters and override GetParamValue() function, for example:
 164
 165     @code
 166     // provide the message parameters for the MIME type manager
 167     class MailMessageParameters : public wxFileType::MessageParameters
 168     {
 169     public:
 170         MailMessageParameters(const wxString& filename,
 171                                 const wxString& mimetype)
 172             : wxFileType::MessageParameters(filename, mimetype)
 173         {
 174         }
 175
 176         virtual wxString GetParamValue(const wxString& name) const
 177         {
 178             // parameter names are not case-sensitive
 179             if ( name.CmpNoCase("charset") == 0 )
 180                 return "US-ASCII";
 181             else
 182                 return wxFileType::MessageParameters::GetParamValue(name);
 183         }
 184     };
 185     @endcode
 186
 187     Now you only need to create an object of this class and pass it to, for example,
 188     GetOpenCommand like this:
 189
 190     @code
 191     wxString command;
 192     if ( filetype->GetOpenCommand(&command,
 193                                 MailMessageParameters("foo.txt", "text/plain")) )
 194     {
 195         // the full command for opening the text documents is in 'command'
 196         // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
 197     }
 198     else
 199     {
 200         // we don't know how to handle such files...
 201     }
 202     @endcode
 203
 204     Windows: As only the file name is used by the program associated with the
 205     given extension anyhow (but no other message parameters), there is no need
 206     to ever derive from MessageParameters class for a Windows-only program.
 207
 208
 209     @library{wxbase}
 210     @category{data}
 211
 212     @see wxMimeTypesManager
 213 */
 214 class wxFileType
 215 {
 216 private:
 217     /**
 218         The default constructor is private because you should never create objects of
 219         this type: they are only returned by wxMimeTypesManager methods.
 220     */
 221     wxFileType();
 222
 223 public:
 224     /**
 225         Class representing message parameters.
 226
 227         An object of this class may be passed to wxFileType::GetOpenCommand()
 228         and GetPrintCommand() if more than the file name needs to be specified.
 229      */
 230     class MessageParameters
 231     {
 232     public:
 233         /// Trivial default constructor.
 234         MessageParameters();
 235
 236         /// Constructor taking a filename and a mime type.
 237         MessageParameters(const wxString& filename,
 238                           const wxString& mimetype = wxEmptyString);
 239
 240         /// Return the filename.
 241         const wxString& GetFileName() const;
 242
 243         /// Return the MIME type.
 244         const wxString& GetMimeType() const;
 245
 246         /// Overridable method for derived classes. Returns empty string by default.
 247         virtual wxString GetParamValue(const wxString& name) const;
 248
 249         /// Trivial but virtual dtor as this class can be inherited from.
 250         virtual ~MessageParameters();
 251     };
 252
 253     /**
 254         Copy ctor.
 255     */
 256     wxFileType(const wxFileTypeInfo& ftInfo);
 257
 258     /**
 259         The destructor of this class is not virtual, so it should not be derived from.
 260     */
 261     ~wxFileType();
 262
 263     /**
 264         This function is primarily intended for GetOpenCommand and GetPrintCommand
 265         usage but may be also used by the application directly if, for example, you
 266         want to use some non-default command to open the file.
 267
 268         The function replaces all occurrences of:
 269         - %s with the full file name
 270         - %t with the MIME type
 271         - %{param} with the value of the parameter @e param
 272         using the MessageParameters object you pass to it.
 273
 274         If there is no '%s' in the command string (and the string is not empty), it is
 275         assumed that the command reads the data on stdin and so the effect is the same
 276         as " %s" were appended to the string.
 277
 278         Unlike all other functions of this class, there is no error return for this
 279         function.
 280     */
 281     static wxString ExpandCommand(const wxString& command,
 282                                   const MessageParameters& params);
 283
 284     /**
 285         If the function returns @true, the string pointed to by @a desc is filled
 286         with a brief description for this file type: for example, "text document" for
 287         the "text/plain" MIME type.
 288     */
 289     bool GetDescription(wxString* desc) const;
 290
 291     /**
 292         If the function returns @true, the array @a extensions is filled
 293         with all extensions associated with this file type: for example, it may
 294         contain the following two elements for the MIME type "text/html"
 295         (notice the absence of the leading dot): "html" and "htm".
 296
 297         @b Windows: This function is currently not implemented: there is no
 298         (efficient) way to retrieve associated extensions from the given MIME type
 299         on this platform, so it will only return @true if the wxFileType object was
 300         created by wxMimeTypesManager::GetFileTypeFromExtension function in the
 301         first place.
 302     */
 303     bool GetExtensions(wxArrayString& extensions);
 304
 305     /**
 306         If the function returns @true, the @c iconLoc is filled with the
 307         location of the icon for this MIME type.
 308         A wxIcon may be created from @a iconLoc later.
 309
 310         @b Windows: The function returns the icon shown by Explorer for the files of
 311         the specified type.
 312
 313         @b Mac: This function is not implemented and always returns @false.
 314
 315         @b Unix: MIME manager gathers information about icons from GNOME
 316         and KDE settings and thus GetIcon's success depends on availability
 317         of these desktop environments.
 318     */
 319     bool GetIcon(wxIconLocation* iconLoc) const;
 320
 321     /**
 322         If the function returns @true, the string pointed to by @a mimeType is filled
 323         with full MIME type specification for this file type: for example, "text/plain".
 324     */
 325     bool GetMimeType(wxString* mimeType) const;
 326
 327     /**
 328         Same as GetMimeType() but returns array of MIME types.
 329
 330         This array will contain only one item in most cases but sometimes,
 331         notably under Unix with KDE, may contain more MIME types.
 332         This happens when one file extension is mapped to different MIME types
 333         by KDE, mailcap and mime.types.
 334     */
 335     bool GetMimeTypes(wxArrayString& mimeTypes) const;
 336
 337     //@{
 338     /**
 339         With the first version of this method, if the @true is returned, the
 340         string pointed to by @a command is filled with the command which must be
 341         executed (see wxExecute()) in order to open the file of the given type.
 342
 343         In this case, the name of the file as well as any other parameters
 344         is retrieved from MessageParameters() class.
 345
 346         In the second case, only the filename is specified and the command to be used
 347         to open this kind of file is returned directly. An empty string is returned to
 348         indicate that an error occurred (typically meaning that there is no standard way
 349         to open this kind of files).
 350     */
 351     bool GetOpenCommand(wxString* command, const MessageParameters& params);
 352     wxString GetOpenCommand(const wxString& filename) const;
 353     //@}
 354
 355     /**
 356         If the function returns @true, the string pointed to by @a command is filled
 357         with the command which must be executed (see wxExecute()) in order to
 358         print the file of the given type.
 359
 360         The name of the file is retrieved from the MessageParameters class.
 361     */
 362     bool GetPrintCommand(wxString* command,
 363                          const MessageParameters& params) const;
 364 };
 365
 366 /**
 367     Container of information about wxFileType.
 368
 369     This class simply stores information associated with the file type. It
 370     doesn't do anything on its own and is used only to allow constructing
 371     wxFileType from it (instead of specifying all the constituent pieces
 372     separately) and also with wxMimeTypesManager::AddFallbacks().
 373  */
 374 class wxFileTypeInfo
 375 {
 376 public:
 377     /**
 378         Default constructor creates an invalid file type info object.
 379
 380         Such invalid/empty object should be used to terminate the list of file
 381         types passed to wxMimeTypesManager::AddFallbacks().
 382      */
 383     wxFileTypeInfo();
 384
 385     /**
 386         Constructor specifying just the MIME type name.
 387
 388         Use the various setter methods below to fully initialize the object.
 389
 390         @since 2.9.2
 391      */
 392     wxFileTypeInfo(const wxString& mimeType);
 393
 394     /**
 395         Constructor allowing to specify all the fields at once.
 396
 397         This is a vararg constructor taking an arbitrary number of extensions
 398         after the first four required parameters. The list must be terminated
 399         by @c wxNullPtr, notice that @c NULL can't be used here in portable
 400         code (C++0x @c nullptr can be used as well if your compiler supports
 401         it).
 402      */
 403     wxFileTypeInfo(const wxString& mimeType,
 404                    const wxString& openCmd,
 405                    const wxString& printCmd,
 406                    const wxString& description,
 407                    const wxString& extension,
 408                    ...);
 409
 410     /**
 411         Add another extension associated with this file type.
 412
 413         @since 2.9.2
 414      */
 415     void AddExtension(const wxString& ext);
 416
 417     /**
 418         Set the file type description.
 419
 420         @since 2.9.2
 421      */
 422     void SetDescription(const wxString& description);
 423
 424     /**
 425         Set the command to be used for opening files of this type.
 426
 427         @since 2.9.2
 428      */
 429     void SetOpenCommand(const wxString& command);
 430
 431     /**
 432         Set the command to be used for printing files of this type.
 433
 434         @since 2.9.2
 435      */
 436     void SetPrintCommand(const wxString& command);
 437
 438     /**
 439         Set the short description for the files of this type.
 440
 441         This is only used under MSW for some of the registry keys used for the
 442         file type registration.
 443      */
 444     void SetShortDesc(const wxString& shortDesc);
 445 };