include/wx/mimetype.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/mimetype.h
   3 // Purpose:     classes and functions to manage MIME types
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 //  Chris Elliott (biol75@york.ac.uk) 5 Dec 00: write support for Win32
   7 // Created:     23.09.98
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
  10 // Licence:     wxWindows licence (part of wxExtra library)
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_MIMETYPE_H_
  14 #define _WX_MIMETYPE_H_
  15
  16 // ----------------------------------------------------------------------------
  17 // headers and such
  18 // ----------------------------------------------------------------------------
  19
  20 #include "wx/defs.h"
  21
  22 #if wxUSE_MIMETYPE
  23
  24 // the things we really need
  25 #include "wx/string.h"
  26 #include "wx/dynarray.h"
  27 #include "wx/arrstr.h"
  28
  29 // fwd decls
  30 class WXDLLIMPEXP_BASE wxIconLocation;
  31 class WXDLLIMPEXP_BASE wxFileTypeImpl;
  32 class WXDLLIMPEXP_BASE wxMimeTypesManagerImpl;
  33
  34 // these constants define the MIME informations source under UNIX and are used
  35 // by wxMimeTypesManager::Initialize()
  36 enum wxMailcapStyle
  37 {
  38     wxMAILCAP_STANDARD = 1,
  39     wxMAILCAP_NETSCAPE = 2,
  40     wxMAILCAP_KDE = 4,
  41     wxMAILCAP_GNOME = 8,
  42
  43     wxMAILCAP_ALL = 15
  44 };
  45
  46 /*
  47     TODO: would it be more convenient to have this class?
  48
  49 class WXDLLIMPEXP_BASE wxMimeType : public wxString
  50 {
  51 public:
  52     // all string ctors here
  53
  54     wxString GetType() const { return BeforeFirst(_T('/')); }
  55     wxString GetSubType() const { return AfterFirst(_T('/')); }
  56
  57     void SetSubType(const wxString& subtype)
  58     {
  59         *this = GetType() + _T('/') + subtype;
  60     }
  61
  62     bool Matches(const wxMimeType& wildcard)
  63     {
  64         // implement using wxMimeTypesManager::IsOfType()
  65     }
  66 };
  67
  68 */
  69
  70 // wxMimeTypeCommands stores the verbs defined for the given MIME type with
  71 // their values
  72 class WXDLLIMPEXP_BASE wxMimeTypeCommands
  73 {
  74 public:
  75     wxMimeTypeCommands() {}
  76
  77     wxMimeTypeCommands(const wxArrayString& verbs,
  78                        const wxArrayString& commands)
  79         : m_verbs(verbs),
  80           m_commands(commands)
  81     {
  82     }
  83
  84     // add a new verb with the command or replace the old value
  85     void AddOrReplaceVerb(const wxString& verb, const wxString& cmd)
  86     {
  87         int n = m_verbs.Index(verb, false /* ignore case */);
  88         if ( n == wxNOT_FOUND )
  89         {
  90             m_verbs.Add(verb);
  91             m_commands.Add(cmd);
  92         }
  93         else
  94         {
  95             m_commands[n] = cmd;
  96         }
  97     }
  98
  99     void Add(const wxString& s)
 100     {
 101         m_verbs.Add(s.BeforeFirst(wxT('=')));
 102         m_commands.Add(s.AfterFirst(wxT('=')));
 103     }
 104
 105     // access the commands
 106     size_t GetCount() const { return m_verbs.GetCount(); }
 107     const wxString& GetVerb(size_t n) const { return m_verbs[n]; }
 108     const wxString& GetCmd(size_t n) const { return m_commands[n]; }
 109
 110     bool HasVerb(const wxString& verb) const
 111         { return m_verbs.Index(verb) != wxNOT_FOUND; }
 112
 113     wxString GetCommandForVerb(const wxString& verb, size_t *idx = NULL) const
 114     {
 115         wxString s;
 116
 117         int n = m_verbs.Index(verb);
 118         if ( n != wxNOT_FOUND )
 119         {
 120             s = m_commands[(size_t)n];
 121             if ( idx )
 122                 *idx = n;
 123         }
 124         else if ( idx )
 125         {
 126             // different from any valid index
 127             *idx = (size_t)-1;
 128         }
 129
 130         return s;
 131     }
 132
 133     // get a "verb=command" string
 134     wxString GetVerbCmd(size_t n) const
 135     {
 136         return m_verbs[n] + wxT('=') + m_commands[n];
 137     }
 138
 139 private:
 140     wxArrayString m_verbs;
 141     wxArrayString m_commands;
 142 };
 143
 144 // ----------------------------------------------------------------------------
 145 // wxFileTypeInfo: static container of information accessed via wxFileType.
 146 //
 147 // This class is used with wxMimeTypesManager::AddFallbacks() and Associate()
 148 // ----------------------------------------------------------------------------
 149
 150 class WXDLLIMPEXP_BASE wxFileTypeInfo
 151 {
 152 public:
 153     // ctors
 154         // a normal item
 155     wxFileTypeInfo(const wxChar *mimeType,
 156                    const wxChar *openCmd,
 157                    const wxChar *printCmd,
 158                    const wxChar *desc,
 159                    // the other parameters form a NULL terminated list of
 160                    // extensions
 161                    ...);
 162
 163         // the array elements correspond to the parameters of the ctor above in
 164         // the same order
 165     wxFileTypeInfo(const wxArrayString& sArray);
 166
 167         // invalid item - use this to terminate the array passed to
 168         // wxMimeTypesManager::AddFallbacks
 169     wxFileTypeInfo() { }
 170
 171     // test if this object can be used
 172     bool IsValid() const { return !m_mimeType.empty(); }
 173
 174     // setters
 175         // set the icon info
 176     void SetIcon(const wxString& iconFile, int iconIndex = 0)
 177     {
 178         m_iconFile = iconFile;
 179         m_iconIndex = iconIndex;
 180     }
 181         // set the short desc
 182     void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }
 183
 184     // accessors
 185         // get the MIME type
 186     const wxString& GetMimeType() const { return m_mimeType; }
 187         // get the open command
 188     const wxString& GetOpenCommand() const { return m_openCmd; }
 189         // get the print command
 190     const wxString& GetPrintCommand() const { return m_printCmd; }
 191         // get the short description (only used under Win32 so far)
 192     const wxString& GetShortDesc() const { return m_shortDesc; }
 193         // get the long, user visible description
 194     const wxString& GetDescription() const { return m_desc; }
 195         // get the array of all extensions
 196     const wxArrayString& GetExtensions() const { return m_exts; }
 197     size_t GetExtensionsCount() const {return m_exts.GetCount(); }
 198         // get the icon info
 199     const wxString& GetIconFile() const { return m_iconFile; }
 200     int GetIconIndex() const { return m_iconIndex; }
 201
 202 private:
 203     wxString m_mimeType,    // the MIME type in "type/subtype" form
 204              m_openCmd,     // command to use for opening the file (%s allowed)
 205              m_printCmd,    // command to use for printing the file (%s allowed)
 206              m_shortDesc,   // a short string used in the registry
 207              m_desc;        // a free form description of this file type
 208
 209     // icon stuff
 210     wxString m_iconFile;    // the file containing the icon
 211     int      m_iconIndex;   // icon index in this file
 212
 213     wxArrayString m_exts;   // the extensions which are mapped on this filetype
 214
 215
 216 #if 0 // TODO
 217     // the additional (except "open" and "print") command names and values
 218     wxArrayString m_commandNames,
 219                   m_commandValues;
 220 #endif // 0
 221 };
 222
 223 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo,
 224                                   WXDLLIMPEXP_BASE);
 225
 226 // ----------------------------------------------------------------------------
 227 // wxFileType: gives access to all information about the files of given type.
 228 //
 229 // This class holds information about a given "file type". File type is the
 230 // same as MIME type under Unix, but under Windows it corresponds more to an
 231 // extension than to MIME type (in fact, several extensions may correspond to a
 232 // file type). This object may be created in many different ways and depending
 233 // on how it was created some fields may be unknown so the return value of all
 234 // the accessors *must* be checked!
 235 // ----------------------------------------------------------------------------
 236
 237 class WXDLLIMPEXP_BASE wxFileType
 238 {
 239 friend class WXDLLIMPEXP_BASE wxMimeTypesManagerImpl;  // it has access to m_impl
 240
 241 public:
 242     // An object of this class must be passed to Get{Open|Print}Command. The
 243     // default implementation is trivial and doesn't know anything at all about
 244     // parameters, only filename and MIME type are used (so it's probably ok for
 245     // Windows where %{param} is not used anyhow)
 246     class MessageParameters
 247     {
 248     public:
 249         // ctors
 250         MessageParameters() { }
 251         MessageParameters(const wxString& filename,
 252                           const wxString& mimetype = wxEmptyString)
 253             : m_filename(filename), m_mimetype(mimetype) { }
 254
 255         // accessors (called by GetOpenCommand)
 256             // filename
 257         const wxString& GetFileName() const { return m_filename; }
 258             // mime type
 259         const wxString& GetMimeType() const { return m_mimetype; }
 260
 261         // override this function in derived class
 262         virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
 263             { return wxEmptyString; }
 264
 265         // virtual dtor as in any base class
 266         virtual ~MessageParameters() { }
 267
 268     protected:
 269         wxString m_filename, m_mimetype;
 270     };
 271
 272     // ctor from static data
 273     wxFileType(const wxFileTypeInfo& ftInfo);
 274
 275     // accessors: all of them return true if the corresponding information
 276     // could be retrieved/found, false otherwise (and in this case all [out]
 277     // parameters are unchanged)
 278         // return the MIME type for this file type
 279     bool GetMimeType(wxString *mimeType) const;
 280     bool GetMimeTypes(wxArrayString& mimeTypes) const;
 281         // fill passed in array with all extensions associated with this file
 282         // type
 283     bool GetExtensions(wxArrayString& extensions);
 284         // get the icon corresponding to this file type and of the given size
 285     bool GetIcon(wxIconLocation *iconloc) const;
 286     bool GetIcon(wxIconLocation *iconloc,
 287                  const MessageParameters& params) const;
 288         // get a brief file type description ("*.txt" => "text document")
 289     bool GetDescription(wxString *desc) const;
 290
 291     // get the command to be used to open/print the given file.
 292         // get the command to execute the file of given type
 293     bool GetOpenCommand(wxString *openCmd,
 294                         const MessageParameters& params) const;
 295         // a simpler to use version of GetOpenCommand() -- it only takes the
 296         // filename and returns an empty string on failure
 297     wxString GetOpenCommand(const wxString& filename) const;
 298         // get the command to print the file of given type
 299     bool GetPrintCommand(wxString *printCmd,
 300                          const MessageParameters& params) const;
 301
 302
 303         // return the number of commands defined for this file type, 0 if none
 304     size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
 305                           const wxFileType::MessageParameters& params) const;
 306
 307     // set an arbitrary command, ask confirmation if it already exists and
 308     // overwriteprompt is true
 309     bool SetCommand(const wxString& cmd, const wxString& verb,
 310         bool overwriteprompt = true);
 311
 312     bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);
 313
 314
 315     // remove the association for this filetype from the system MIME database:
 316     // notice that it will only work if the association is defined in the user
 317     // file/registry part, we will never modify the system-wide settings
 318     bool Unassociate();
 319
 320     // operations
 321         // expand a string in the format of GetOpenCommand (which may contain
 322         // '%s' and '%t' format specificators for the file name and mime type
 323         // and %{param} constructions).
 324     static wxString ExpandCommand(const wxString& command,
 325                                   const MessageParameters& params);
 326
 327     // dtor (not virtual, shouldn't be derived from)
 328     ~wxFileType();
 329
 330 private:
 331     // default ctor is private because the user code never creates us
 332     wxFileType();
 333
 334     // no copy ctor/assignment operator
 335     wxFileType(const wxFileType&);
 336     wxFileType& operator=(const wxFileType&);
 337
 338     // the static container of wxFileType data: if it's not NULL, it means that
 339     // this object is used as fallback only
 340     const wxFileTypeInfo *m_info;
 341
 342     // the object which implements the real stuff like reading and writing
 343     // to/from system MIME database
 344     wxFileTypeImpl *m_impl;
 345 };
 346
 347 //----------------------------------------------------------------------------
 348 // wxMimeTypesManagerFactory
 349 //----------------------------------------------------------------------------
 350
 351 class WXDLLIMPEXP_BASE wxMimeTypesManagerFactory
 352 {
 353 public:
 354     wxMimeTypesManagerFactory() {}
 355     virtual ~wxMimeTypesManagerFactory() {}
 356
 357     virtual wxMimeTypesManagerImpl *CreateMimeTypesManagerImpl();
 358
 359     static void Set( wxMimeTypesManagerFactory *factory );
 360     static wxMimeTypesManagerFactory *Get();
 361
 362 private:
 363     static wxMimeTypesManagerFactory *m_factory;
 364 };
 365
 366 // ----------------------------------------------------------------------------
 367 // wxMimeTypesManager: interface to system MIME database.
 368 //
 369 // This class accesses the information about all known MIME types and allows
 370 // the application to retrieve information (including how to handle data of
 371 // given type) about them.
 372 // ----------------------------------------------------------------------------
 373
 374 class WXDLLIMPEXP_BASE wxMimeTypesManager
 375 {
 376 public:
 377     // static helper functions
 378     // -----------------------
 379
 380         // check if the given MIME type is the same as the other one: the
 381         // second argument may contain wildcards ('*'), but not the first. If
 382         // the types are equal or if the mimeType matches wildcard the function
 383         // returns true, otherwise it returns false
 384     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 385
 386     // ctor
 387     wxMimeTypesManager();
 388
 389     // NB: the following 2 functions are for Unix only and don't do anything
 390     //     elsewhere
 391
 392     // loads data from standard files according to the mailcap styles
 393     // specified: this is a bitwise OR of wxMailcapStyle values
 394     //
 395     // use the extraDir parameter if you want to look for files in another
 396     // directory
 397     void Initialize(int mailcapStyle = wxMAILCAP_ALL,
 398                     const wxString& extraDir = wxEmptyString);
 399
 400     // and this function clears all the data from the manager
 401     void ClearData();
 402
 403     // Database lookup: all functions return a pointer to wxFileType object
 404     // whose methods may be used to query it for the information you're
 405     // interested in. If the return value is !NULL, caller is responsible for
 406     // deleting it.
 407         // get file type from file extension
 408     wxFileType *GetFileTypeFromExtension(const wxString& ext);
 409         // get file type from MIME type (in format <category>/<format>)
 410     wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
 411
 412     // other operations: return true if there were no errors or false if there
 413     // were some unrecognized entries (the good entries are always read anyhow)
 414     //
 415     // FIXME: These ought to be private ??
 416
 417         // read in additional file (the standard ones are read automatically)
 418         // in mailcap format (see mimetype.cpp for description)
 419         //
 420         // 'fallback' parameter may be set to true to avoid overriding the
 421         // settings from other, previously parsed, files by this one: normally,
 422         // the files read most recently would override the older files, but with
 423         // fallback == true this won't happen
 424
 425     bool ReadMailcap(const wxString& filename, bool fallback = false);
 426         // read in additional file in mime.types format
 427     bool ReadMimeTypes(const wxString& filename);
 428
 429     // enumerate all known MIME types
 430     //
 431     // returns the number of retrieved file types
 432     size_t EnumAllFileTypes(wxArrayString& mimetypes);
 433
 434     // these functions can be used to provide default values for some of the
 435     // MIME types inside the program itself (you may also use
 436     // ReadMailcap(filenameWithDefaultTypes, true /* use as fallback */) to
 437     // achieve the same goal, but this requires having this info in a file).
 438     //
 439     // The filetypes array should be terminated by either NULL entry or an
 440     // invalid wxFileTypeInfo (i.e. the one created with default ctor)
 441     void AddFallbacks(const wxFileTypeInfo *filetypes);
 442     void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
 443
 444     // create or remove associations
 445
 446         // create a new association using the fields of wxFileTypeInfo (at least
 447         // the MIME type and the extension should be set)
 448         // if the other fields are empty, the existing values should be left alone
 449     wxFileType *Associate(const wxFileTypeInfo& ftInfo);
 450
 451         // undo Associate()
 452     bool Unassociate(wxFileType *ft) ;
 453
 454     // dtor (not virtual, shouldn't be derived from)
 455     ~wxMimeTypesManager();
 456
 457 private:
 458     // no copy ctor/assignment operator
 459     wxMimeTypesManager(const wxMimeTypesManager&);
 460     wxMimeTypesManager& operator=(const wxMimeTypesManager&);
 461
 462     // the fallback info which is used if the information is not found in the
 463     // real system database
 464     wxArrayFileTypeInfo m_fallbacks;
 465
 466     // the object working with the system MIME database
 467     wxMimeTypesManagerImpl *m_impl;
 468
 469     // if m_impl is NULL, create one
 470     void EnsureImpl();
 471
 472     friend class wxMimeTypeCmnModule;
 473 };
 474
 475
 476 // ----------------------------------------------------------------------------
 477 // global variables
 478 // ----------------------------------------------------------------------------
 479
 480 // the default mime manager for wxWidgets programs
 481 extern WXDLLIMPEXP_DATA_BASE(wxMimeTypesManager *) wxTheMimeTypesManager;
 482
 483 #endif // wxUSE_MIMETYPE
 484
 485 #endif
 486   //_WX_MIMETYPE_H_