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