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