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 #if !wxUSE_UTF8_LOCALE_ONLY
 129     void VarArgInitWchar(const wxChar *mimeType,
 130                          const wxChar *openCmd,
 131                          const wxChar *printCmd,
 132                          const wxChar *desc,
 133                          // the other parameters form a NULL terminated list of
 134                          // extensions
 135                          ...);
 136 #endif
 137 #if wxUSE_UNICODE_UTF8
 138     void VarArgInitUtf8(const char *mimeType,
 139                         const char *openCmd,
 140                         const char *printCmd,
 141                         const char *desc,
 142                         // the other parameters form a NULL terminated list of
 143                         // extensions
 144                         ...);
 145 #endif
 146 public:
 147     // ctors
 148         // a normal item
 149
 150     // wxFileTypeInfo(const wxString& mimeType,
 151     //               const wxString& openCmd,
 152     //               const wxString& printCmd,
 153     //               const wxString& desc,
 154     //               // the other parameters form a list of extensions for this
 155     //               // file type and should be terminated with wxNullPtr (not
 156     //               // just NULL!)
 157     //               ...);
 158     WX_DEFINE_VARARG_FUNC_CTOR(wxFileTypeInfo,
 159                                // NB: these are not format strings, using
 160                                //     wxFormatString here is a hack to get
 161                                //     implicit conversion to wchar_t*/char*
 162                                4, (const wxFormatString&,
 163                                    const wxFormatString&,
 164                                    const wxFormatString&,
 165                                    const wxFormatString&),
 166                                VarArgInitWchar, VarArgInitUtf8)
 167 #ifdef __WATCOMC__
 168     // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
 169     WX_VARARG_WATCOM_WORKAROUND_CTOR(
 170                                 wxFileTypeInfo,
 171                                 4, (const wxString&,
 172                                     const wxString&,
 173                                     const wxString&,
 174                                     const wxString&),
 175                                 (wxFormatString(f1),
 176                                  wxFormatString(f2),
 177                                  wxFormatString(f3),
 178                                  wxFormatString(f4)));
 179     WX_VARARG_WATCOM_WORKAROUND_CTOR(
 180                                 wxFileTypeInfo,
 181                                 4, (const wxCStrData&,
 182                                     const wxCStrData&,
 183                                     const wxCStrData&,
 184                                     const wxCStrData&),
 185                                 (wxFormatString(f1),
 186                                  wxFormatString(f2),
 187                                  wxFormatString(f3),
 188                                  wxFormatString(f4)));
 189     WX_VARARG_WATCOM_WORKAROUND_CTOR(
 190                                 wxFileTypeInfo,
 191                                 4, (const char*,
 192                                     const char*,
 193                                     const char*,
 194                                     const char*),
 195                                 (wxFormatString(f1),
 196                                  wxFormatString(f2),
 197                                  wxFormatString(f3),
 198                                  wxFormatString(f4)));
 199     WX_VARARG_WATCOM_WORKAROUND_CTOR(
 200                                 wxFileTypeInfo,
 201                                 4, (const wchar_t*,
 202                                     const wchar_t*,
 203                                     const wchar_t*,
 204                                     const wchar_t*),
 205                                 (wxFormatString(f1),
 206                                  wxFormatString(f2),
 207                                  wxFormatString(f3),
 208                                  wxFormatString(f4)));
 209 #endif
 210
 211         // the array elements correspond to the parameters of the ctor above in
 212         // the same order
 213     wxFileTypeInfo(const wxArrayString& sArray);
 214
 215         // invalid item - use this to terminate the array passed to
 216         // wxMimeTypesManager::AddFallbacks
 217     wxFileTypeInfo() { }
 218
 219     // test if this object can be used
 220     bool IsValid() const { return !m_mimeType.empty(); }
 221
 222     // setters
 223         // set the icon info
 224     void SetIcon(const wxString& iconFile, int iconIndex = 0)
 225     {
 226         m_iconFile = iconFile;
 227         m_iconIndex = iconIndex;
 228     }
 229         // set the short desc
 230     void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }
 231
 232     // accessors
 233         // get the MIME type
 234     const wxString& GetMimeType() const { return m_mimeType; }
 235         // get the open command
 236     const wxString& GetOpenCommand() const { return m_openCmd; }
 237         // get the print command
 238     const wxString& GetPrintCommand() const { return m_printCmd; }
 239         // get the short description (only used under Win32 so far)
 240     const wxString& GetShortDesc() const { return m_shortDesc; }
 241         // get the long, user visible description
 242     const wxString& GetDescription() const { return m_desc; }
 243         // get the array of all extensions
 244     const wxArrayString& GetExtensions() const { return m_exts; }
 245     size_t GetExtensionsCount() const {return m_exts.GetCount(); }
 246         // get the icon info
 247     const wxString& GetIconFile() const { return m_iconFile; }
 248     int GetIconIndex() const { return m_iconIndex; }
 249
 250 private:
 251     wxString m_mimeType,    // the MIME type in "type/subtype" form
 252              m_openCmd,     // command to use for opening the file (%s allowed)
 253              m_printCmd,    // command to use for printing the file (%s allowed)
 254              m_shortDesc,   // a short string used in the registry
 255              m_desc;        // a free form description of this file type
 256
 257     // icon stuff
 258     wxString m_iconFile;    // the file containing the icon
 259     int      m_iconIndex;   // icon index in this file
 260
 261     wxArrayString m_exts;   // the extensions which are mapped on this filetype
 262
 263
 264 #if 0 // TODO
 265     // the additional (except "open" and "print") command names and values
 266     wxArrayString m_commandNames,
 267                   m_commandValues;
 268 #endif // 0
 269 };
 270
 271 WX_DECLARE_USER_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo,
 272                                   WXDLLIMPEXP_BASE);
 273
 274 // ----------------------------------------------------------------------------
 275 // wxFileType: gives access to all information about the files of given type.
 276 //
 277 // This class holds information about a given "file type". File type is the
 278 // same as MIME type under Unix, but under Windows it corresponds more to an
 279 // extension than to MIME type (in fact, several extensions may correspond to a
 280 // file type). This object may be created in many different ways and depending
 281 // on how it was created some fields may be unknown so the return value of all
 282 // the accessors *must* be checked!
 283 // ----------------------------------------------------------------------------
 284
 285 class WXDLLIMPEXP_BASE wxFileType
 286 {
 287 friend class WXDLLIMPEXP_FWD_BASE wxMimeTypesManagerImpl;  // it has access to m_impl
 288
 289 public:
 290     // An object of this class must be passed to Get{Open|Print}Command. The
 291     // default implementation is trivial and doesn't know anything at all about
 292     // parameters, only filename and MIME type are used (so it's probably ok for
 293     // Windows where %{param} is not used anyhow)
 294     class MessageParameters
 295     {
 296     public:
 297         // ctors
 298         MessageParameters() { }
 299         MessageParameters(const wxString& filename,
 300                           const wxString& mimetype = wxEmptyString)
 301             : m_filename(filename), m_mimetype(mimetype) { }
 302
 303         // accessors (called by GetOpenCommand)
 304             // filename
 305         const wxString& GetFileName() const { return m_filename; }
 306             // mime type
 307         const wxString& GetMimeType() const { return m_mimetype; }
 308
 309         // override this function in derived class
 310         virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
 311             { return wxEmptyString; }
 312
 313         // virtual dtor as in any base class
 314         virtual ~MessageParameters() { }
 315
 316     protected:
 317         wxString m_filename, m_mimetype;
 318     };
 319
 320     // ctor from static data
 321     wxFileType(const wxFileTypeInfo& ftInfo);
 322
 323     // accessors: all of them return true if the corresponding information
 324     // could be retrieved/found, false otherwise (and in this case all [out]
 325     // parameters are unchanged)
 326         // return the MIME type for this file type
 327     bool GetMimeType(wxString *mimeType) const;
 328     bool GetMimeTypes(wxArrayString& mimeTypes) const;
 329         // fill passed in array with all extensions associated with this file
 330         // type
 331     bool GetExtensions(wxArrayString& extensions);
 332         // get the icon corresponding to this file type and of the given size
 333     bool GetIcon(wxIconLocation *iconloc) const;
 334     bool GetIcon(wxIconLocation *iconloc,
 335                  const MessageParameters& params) const;
 336         // get a brief file type description ("*.txt" => "text document")
 337     bool GetDescription(wxString *desc) const;
 338
 339     // get the command to be used to open/print the given file.
 340         // get the command to execute the file of given type
 341     bool GetOpenCommand(wxString *openCmd,
 342                         const MessageParameters& params) const;
 343         // a simpler to use version of GetOpenCommand() -- it only takes the
 344         // filename and returns an empty string on failure
 345     wxString GetOpenCommand(const wxString& filename) const;
 346         // get the command to print the file of given type
 347     bool GetPrintCommand(wxString *printCmd,
 348                          const MessageParameters& params) const;
 349
 350
 351         // return the number of commands defined for this file type, 0 if none
 352     size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
 353                           const wxFileType::MessageParameters& params) const;
 354
 355     // set an arbitrary command, ask confirmation if it already exists and
 356     // overwriteprompt is true
 357     bool SetCommand(const wxString& cmd, const wxString& verb,
 358         bool overwriteprompt = true);
 359
 360     bool SetDefaultIcon(const wxString& cmd = wxEmptyString, int index = 0);
 361
 362
 363     // remove the association for this filetype from the system MIME database:
 364     // notice that it will only work if the association is defined in the user
 365     // file/registry part, we will never modify the system-wide settings
 366     bool Unassociate();
 367
 368     // operations
 369         // expand a string in the format of GetOpenCommand (which may contain
 370         // '%s' and '%t' format specificators for the file name and mime type
 371         // and %{param} constructions).
 372     static wxString ExpandCommand(const wxString& command,
 373                                   const MessageParameters& params);
 374
 375     // dtor (not virtual, shouldn't be derived from)
 376     ~wxFileType();
 377
 378 private:
 379     // default ctor is private because the user code never creates us
 380     wxFileType();
 381
 382     // no copy ctor/assignment operator
 383     wxFileType(const wxFileType&);
 384     wxFileType& operator=(const wxFileType&);
 385
 386     // the static container of wxFileType data: if it's not NULL, it means that
 387     // this object is used as fallback only
 388     const wxFileTypeInfo *m_info;
 389
 390     // the object which implements the real stuff like reading and writing
 391     // to/from system MIME database
 392     wxFileTypeImpl *m_impl;
 393 };
 394
 395 //----------------------------------------------------------------------------
 396 // wxMimeTypesManagerFactory
 397 //----------------------------------------------------------------------------
 398
 399 class WXDLLIMPEXP_BASE wxMimeTypesManagerFactory
 400 {
 401 public:
 402     wxMimeTypesManagerFactory() {}
 403     virtual ~wxMimeTypesManagerFactory() {}
 404
 405     virtual wxMimeTypesManagerImpl *CreateMimeTypesManagerImpl();
 406
 407     static void Set( wxMimeTypesManagerFactory *factory );
 408     static wxMimeTypesManagerFactory *Get();
 409
 410 private:
 411     static wxMimeTypesManagerFactory *m_factory;
 412 };
 413
 414 // ----------------------------------------------------------------------------
 415 // wxMimeTypesManager: interface to system MIME database.
 416 //
 417 // This class accesses the information about all known MIME types and allows
 418 // the application to retrieve information (including how to handle data of
 419 // given type) about them.
 420 // ----------------------------------------------------------------------------
 421
 422 class WXDLLIMPEXP_BASE wxMimeTypesManager
 423 {
 424 public:
 425     // static helper functions
 426     // -----------------------
 427
 428         // check if the given MIME type is the same as the other one: the
 429         // second argument may contain wildcards ('*'), but not the first. If
 430         // the types are equal or if the mimeType matches wildcard the function
 431         // returns true, otherwise it returns false
 432     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 433
 434     // ctor
 435     wxMimeTypesManager();
 436
 437     // NB: the following 2 functions are for Unix only and don't do anything
 438     //     elsewhere
 439
 440     // loads data from standard files according to the mailcap styles
 441     // specified: this is a bitwise OR of wxMailcapStyle values
 442     //
 443     // use the extraDir parameter if you want to look for files in another
 444     // directory
 445     void Initialize(int mailcapStyle = wxMAILCAP_ALL,
 446                     const wxString& extraDir = wxEmptyString);
 447
 448     // and this function clears all the data from the manager
 449     void ClearData();
 450
 451     // Database lookup: all functions return a pointer to wxFileType object
 452     // whose methods may be used to query it for the information you're
 453     // interested in. If the return value is !NULL, caller is responsible for
 454     // deleting it.
 455         // get file type from file extension
 456     wxFileType *GetFileTypeFromExtension(const wxString& ext);
 457         // get file type from MIME type (in format <category>/<format>)
 458     wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
 459
 460     // other operations: return true if there were no errors or false if there
 461     // were some unrecognized entries (the good entries are always read anyhow)
 462     //
 463     // FIXME: These ought to be private ??
 464
 465         // read in additional file (the standard ones are read automatically)
 466         // in mailcap format (see mimetype.cpp for description)
 467         //
 468         // 'fallback' parameter may be set to true to avoid overriding the
 469         // settings from other, previously parsed, files by this one: normally,
 470         // the files read most recently would override the older files, but with
 471         // fallback == true this won't happen
 472
 473     bool ReadMailcap(const wxString& filename, bool fallback = false);
 474         // read in additional file in mime.types format
 475     bool ReadMimeTypes(const wxString& filename);
 476
 477     // enumerate all known MIME types
 478     //
 479     // returns the number of retrieved file types
 480     size_t EnumAllFileTypes(wxArrayString& mimetypes);
 481
 482     // these functions can be used to provide default values for some of the
 483     // MIME types inside the program itself (you may also use
 484     // ReadMailcap(filenameWithDefaultTypes, true /* use as fallback */) to
 485     // achieve the same goal, but this requires having this info in a file).
 486     //
 487     // The filetypes array should be terminated by either NULL entry or an
 488     // invalid wxFileTypeInfo (i.e. the one created with default ctor)
 489     void AddFallbacks(const wxFileTypeInfo *filetypes);
 490     void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
 491
 492     // create or remove associations
 493
 494         // create a new association using the fields of wxFileTypeInfo (at least
 495         // the MIME type and the extension should be set)
 496         // if the other fields are empty, the existing values should be left alone
 497     wxFileType *Associate(const wxFileTypeInfo& ftInfo);
 498
 499         // undo Associate()
 500     bool Unassociate(wxFileType *ft) ;
 501
 502     // dtor (not virtual, shouldn't be derived from)
 503     ~wxMimeTypesManager();
 504
 505 private:
 506     // no copy ctor/assignment operator
 507     wxMimeTypesManager(const wxMimeTypesManager&);
 508     wxMimeTypesManager& operator=(const wxMimeTypesManager&);
 509
 510     // the fallback info which is used if the information is not found in the
 511     // real system database
 512     wxArrayFileTypeInfo m_fallbacks;
 513
 514     // the object working with the system MIME database
 515     wxMimeTypesManagerImpl *m_impl;
 516
 517     // if m_impl is NULL, create one
 518     void EnsureImpl();
 519
 520     friend class wxMimeTypeCmnModule;
 521 };
 522
 523
 524 // ----------------------------------------------------------------------------
 525 // global variables
 526 // ----------------------------------------------------------------------------
 527
 528 // the default mime manager for wxWidgets programs
 529 extern WXDLLIMPEXP_DATA_BASE(wxMimeTypesManager *) wxTheMimeTypesManager;
 530
 531 #endif // wxUSE_MIMETYPE
 532
 533 #endif
 534   //_WX_MIMETYPE_H_