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 license (part of wxExtra library)
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_MIMETYPE_H_
  14 #define _WX_MIMETYPE_H_
  15
  16 #ifdef __GNUG__
  17     #pragma interface "mimetypebase.h"
  18 #endif // __GNUG__
  19
  20 // ----------------------------------------------------------------------------
  21 // headers and such
  22 // ----------------------------------------------------------------------------
  23
  24 #include "wx/defs.h"
  25
  26 // the things we really need
  27 #include "wx/string.h"
  28 #include "wx/dynarray.h"
  29
  30 // fwd decls
  31 class WXDLLEXPORT wxIcon;
  32 class WXDLLEXPORT wxFileTypeImpl;
  33 class WXDLLEXPORT wxMimeTypesManagerImpl;
  34
  35 /*
  36     TODO: would it be more convenient to have this class?
  37
  38 class WXDLLEXPORT wxMimeType : public wxString
  39 {
  40 public:
  41     // all string ctors here
  42
  43     wxString GetType() const { return BeforeFirst(_T('/')); }
  44     wxString GetSubType() const { return AfterFirst(_T('/')); }
  45
  46     void SetSubType(const wxString& subtype)
  47     {
  48         *this = GetType() + _T('/') + subtype;
  49     }
  50
  51     bool Matches(const wxMimeType& wildcard)
  52     {
  53         // implement using wxMimeTypesManager::IsOfType()
  54     }
  55 };
  56
  57 */
  58
  59 // ----------------------------------------------------------------------------
  60 // wxFileTypeInfo: static container of information accessed via wxFileType.
  61 //
  62 // This class is used with wxMimeTypesManager::AddFallbacks() and Associate()
  63 // ----------------------------------------------------------------------------
  64
  65 class WXDLLEXPORT wxFileTypeInfo
  66 {
  67 public:
  68     // ctors
  69         // a normal item
  70     wxFileTypeInfo(const char *mimeType,
  71                    const char *openCmd,
  72                    const char *printCmd,
  73                    const char *desc,
  74                    // the other parameters form a NULL terminated list of
  75                    // extensions
  76                    ...);
  77
  78         // invalid item - use this to terminate the array passed to
  79         // wxMimeTypesManager::AddFallbacks
  80     wxFileTypeInfo() { }
  81
  82     // test if this object can be used
  83     bool IsValid() const { return !m_mimeType.IsEmpty(); }
  84
  85     // setters
  86         // set the icon info
  87     void SetIcon(const wxString& iconFile, int iconIndex = 0)
  88     {
  89         m_iconFile = iconFile;
  90         m_iconIndex = iconIndex;
  91     }
  92         // set the short desc
  93     void SetShortDesc(const wxString& shortDesc) { m_shortDesc = shortDesc; }
  94
  95     // accessors
  96         // get the MIME type
  97     const wxString& GetMimeType() const { return m_mimeType; }
  98         // get the open command
  99     const wxString& GetOpenCommand() const { return m_openCmd; }
 100         // get the print command
 101     const wxString& GetPrintCommand() const { return m_printCmd; }
 102         // get the short description (only used under Win32 so far)
 103     const wxString& GetShortDesc() const { return m_shortDesc; }
 104         // get the long, user visible description
 105     const wxString& GetDescription() const { return m_desc; }
 106         // get the array of all extensions
 107     const wxArrayString& GetExtensions() const { return m_exts; }
 108         // get the icon info
 109     const wxString& GetIconFile() const { return m_iconFile; }
 110     int GetIconIndex() const { return m_iconIndex; }
 111
 112 private:
 113     wxString m_mimeType,    // the MIME type in "type/subtype" form
 114              m_openCmd,     // command to use for opening the file (%s allowed)
 115              m_printCmd,    // command to use for printing the file (%s allowed)
 116              m_shortDesc,   // a short string used in the registry
 117              m_desc;        // a free form description of this file type
 118
 119     // icon stuff
 120     wxString m_iconFile;    // the file containing the icon
 121     int      m_iconIndex;   // icon index in this file
 122
 123     wxArrayString m_exts;   // the extensions which are mapped on this filetype
 124
 125 #if 0 // TODO
 126     // the additional (except "open" and "print") command names and values
 127     wxArrayString m_commandNames,
 128                   m_commandValues;
 129 #endif // 0
 130 };
 131
 132 WX_DECLARE_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo);
 133
 134 // ----------------------------------------------------------------------------
 135 // wxFileType: gives access to all information about the files of given type.
 136 //
 137 // This class holds information about a given "file type". File type is the
 138 // same as MIME type under Unix, but under Windows it corresponds more to an
 139 // extension than to MIME type (in fact, several extensions may correspond to a
 140 // file type). This object may be created in many different ways and depending
 141 // on how it was created some fields may be unknown so the return value of all
 142 // the accessors *must* be checked!
 143 // ----------------------------------------------------------------------------
 144
 145 class WXDLLEXPORT wxFileType
 146 {
 147 friend class WXDLLEXPORT wxMimeTypesManagerImpl;  // it has access to m_impl
 148
 149 public:
 150     // An object of this class must be passed to Get{Open|Print}Command. The
 151     // default implementation is trivial and doesn't know anything at all about
 152     // parameters, only filename and MIME type are used (so it's probably ok for
 153     // Windows where %{param} is not used anyhow)
 154     class MessageParameters
 155     {
 156     public:
 157         // ctors
 158         MessageParameters() { }
 159         MessageParameters(const wxString& filename, const wxString& mimetype)
 160             : m_filename(filename), m_mimetype(mimetype) { }
 161
 162         // accessors (called by GetOpenCommand)
 163             // filename
 164         const wxString& GetFileName() const { return m_filename; }
 165             // mime type
 166         const wxString& GetMimeType() const { return m_mimetype; }
 167
 168         // override this function in derived class
 169         virtual wxString GetParamValue(const wxString& WXUNUSED(name)) const
 170             { return wxEmptyString; }
 171
 172         // virtual dtor as in any base class
 173         virtual ~MessageParameters() { }
 174
 175     protected:
 176         wxString m_filename, m_mimetype;
 177     };
 178
 179     // ctor from static data
 180     wxFileType(const wxFileTypeInfo& ftInfo);
 181
 182     // accessors: all of them return true if the corresponding information
 183     // could be retrieved/found, false otherwise (and in this case all [out]
 184     // parameters are unchanged)
 185         // return the MIME type for this file type
 186     bool GetMimeType(wxString *mimeType) const;
 187     bool GetMimeTypes(wxArrayString& mimeTypes) const;
 188         // fill passed in array with all extensions associated with this file
 189         // type
 190     bool GetExtensions(wxArrayString& extensions);
 191         // get the icon corresponding to this file type, the name of the file
 192         // where the icon resides is return in iconfile if !NULL and its index
 193         // in this file (Win-only) is in iconIndex
 194     bool GetIcon(wxIcon *icon,
 195                  wxString *iconFile = NULL,
 196                  int *iconIndex = NULL) const;
 197         // get a brief file type description ("*.txt" => "text document")
 198     bool GetDescription(wxString *desc) const;
 199
 200     // get the command to be used to open/print the given file.
 201         // get the command to execute the file of given type
 202     bool GetOpenCommand(wxString *openCmd,
 203                         const MessageParameters& params) const;
 204         // get the command to print the file of given type
 205     bool GetPrintCommand(wxString *printCmd,
 206                          const MessageParameters& params) const;
 207
 208
 209         // return the number of commands defined for this file type, 0 if none
 210     size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands,
 211                           const wxFileType::MessageParameters& params) const;
 212
 213     // remove the association for this filetype from the system MIME database:
 214     // notice that it will only work if the association is defined in the user
 215     // file/registry part, we will never modify the system-wide settings
 216     bool Unassociate();
 217
 218     // operations
 219         // expand a string in the format of GetOpenCommand (which may contain
 220         // '%s' and '%t' format specificators for the file name and mime type
 221         // and %{param} constructions).
 222     static wxString ExpandCommand(const wxString& command,
 223                                   const MessageParameters& params);
 224
 225     // dtor (not virtual, shouldn't be derived from)
 226     ~wxFileType();
 227
 228 private:
 229     // default ctor is private because the user code never creates us
 230     wxFileType();
 231
 232     // no copy ctor/assignment operator
 233     wxFileType(const wxFileType&);
 234     wxFileType& operator=(const wxFileType&);
 235
 236     // the static container of wxFileType data: if it's not NULL, it means that
 237     // this object is used as fallback only
 238     const wxFileTypeInfo *m_info;
 239
 240     // the object which implements the real stuff like reading and writing
 241     // to/from system MIME database
 242     wxFileTypeImpl *m_impl;
 243 };
 244
 245 // ----------------------------------------------------------------------------
 246 // wxMimeTypesManager: interface to system MIME database.
 247 //
 248 // This class accesses the information about all known MIME types and allows
 249 // the application to retrieve information (including how to handle data of
 250 // given type) about them.
 251 // ----------------------------------------------------------------------------
 252
 253 class WXDLLEXPORT wxMimeTypesManager
 254 {
 255 public:
 256     // static helper functions
 257     // -----------------------
 258
 259         // check if the given MIME type is the same as the other one: the
 260         // second argument may contain wildcards ('*'), but not the first. If
 261         // the types are equal or if the mimeType matches wildcard the function
 262         // returns TRUE, otherwise it returns FALSE
 263     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 264
 265     // ctor
 266     wxMimeTypesManager();
 267
 268     // Database lookup: all functions return a pointer to wxFileType object
 269     // whose methods may be used to query it for the information you're
 270     // interested in. If the return value is !NULL, caller is responsible for
 271     // deleting it.
 272         // get file type from file extension
 273     wxFileType *GetFileTypeFromExtension(const wxString& ext);
 274         // get file type from MIME type (in format <category>/<format>)
 275     wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
 276
 277     // other operations: return TRUE if there were no errors or FALSE if there
 278     // were some unreckognized entries (the good entries are always read anyhow)
 279         // read in additional file (the standard ones are read automatically)
 280         // in mailcap format (see mimetype.cpp for description)
 281         //
 282         // 'fallback' parameter may be set to TRUE to avoid overriding the
 283         // settings from other, previously parsed, files by this one: normally,
 284         // the files read most recently would override the older files, but with
 285         // fallback == TRUE this won't happen
 286     bool ReadMailcap(const wxString& filename, bool fallback = FALSE);
 287         // read in additional file in mime.types format
 288     bool ReadMimeTypes(const wxString& filename);
 289
 290     // enumerate all known MIME types
 291     //
 292     // returns the number of retrieved file types
 293     size_t EnumAllFileTypes(wxArrayString& mimetypes);
 294
 295     // these functions can be used to provide default values for some of the
 296     // MIME types inside the program itself (you may also use
 297     // ReadMailcap(filenameWithDefaultTypes, TRUE /* use as fallback */) to
 298     // achieve the same goal, but this requires having this info in a file).
 299     //
 300     // The filetypes array should be terminated by either NULL entry or an
 301     // invalid wxFileTypeInfo (i.e. the one created with default ctor)
 302     void AddFallbacks(const wxFileTypeInfo *filetypes);
 303     void AddFallback(const wxFileTypeInfo& ft) { m_fallbacks.Add(ft); }
 304
 305     // create or remove associations
 306
 307         // create a new association using the fields of wxFileTypeInfo (at least
 308         // the MIME type and the extension should be set)
 309     wxFileType *Associate(const wxFileTypeInfo& ftInfo);
 310
 311         // undo Associate()
 312     bool Unassociate(wxFileType *ft) { return ft->Unassociate(); }
 313
 314     // dtor (not virtual, shouldn't be derived from)
 315     ~wxMimeTypesManager();
 316
 317 private:
 318     // no copy ctor/assignment operator
 319     wxMimeTypesManager(const wxMimeTypesManager&);
 320     wxMimeTypesManager& operator=(const wxMimeTypesManager&);
 321
 322     // the fallback info which is used if the information is not found in the
 323     // real system database
 324     wxArrayFileTypeInfo m_fallbacks;
 325
 326     // the object working with the system MIME database
 327     wxMimeTypesManagerImpl *m_impl;
 328
 329     // if m_impl is NULL, create one
 330     void EnsureImpl();
 331
 332     friend class wxMimeTypeCmnModule;
 333 };
 334
 335
 336 // ----------------------------------------------------------------------------
 337 // global variables
 338 // ----------------------------------------------------------------------------
 339
 340 // the default mime manager for wxWindows programs
 341 WXDLLEXPORT_DATA(extern wxMimeTypesManager *) wxTheMimeTypesManager;
 342
 343 #endif
 344   //_WX_MIMETYPE_H_
 345
 346 /* vi: set cin tw=80 ts=4 sw=4: */