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