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