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