interface/wx/mimetype.h

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