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 // Created:     23.09.98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license (part of wxExtra library)
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _MIMETYPE_H
  13 #define _MIMETYPE_H
  14
  15 #ifdef __GNUG__
  16 #pragma interface "mimetypebase.h"
  17 #endif
  18
  19
  20 // fwd decls
  21 class wxIcon;
  22 class wxFileTypeImpl;
  23 class wxMimeTypesManagerImpl;
  24
  25 #include "wx/defs.h"
  26
  27 #if wxUSE_FILE
  28
  29 // the things we really need
  30 #include "wx/string.h"
  31 #include "wx/dynarray.h"
  32
  33 class wxMimeTypeCmnModule;
  34
  35 // This class holds information about a given "file type". File type is the
  36 // same as MIME type under Unix, but under Windows it corresponds more to an
  37 // extension than to MIME type (in fact, several extensions may correspond to a
  38 // file type). This object may be created in many different ways and depending
  39 // on how it was created some fields may be unknown so the return value of all
  40 // the accessors *must* be checked!
  41 class WXDLLEXPORT wxFileType
  42 {
  43 friend class WXDLLEXPORT wxMimeTypesManagerImpl;  // it has access to m_impl
  44
  45 public:
  46     // An object of this class must be passed to Get{Open|Print}Command. The
  47     // default implementation is trivial and doesn't know anything at all about
  48     // parameters, only filename and MIME type are used (so it's probably ok for
  49     // Windows where %{param} is not used anyhow)
  50     class MessageParameters
  51     {
  52     public:
  53         // ctors
  54         MessageParameters() { }
  55         MessageParameters(const wxString& filename, const wxString& mimetype)
  56             : m_filename(filename), m_mimetype(mimetype) { }
  57
  58         // accessors (called by GetOpenCommand)
  59             // filename
  60         const wxString& GetFileName() const { return m_filename; }
  61             // mime type
  62         const wxString& GetMimeType() const { return m_mimetype; }
  63
  64         // override this function in derived class
  65         virtual wxString GetParamValue(const wxString& WXUNUSED(paramName)) const
  66             { return ""; }
  67
  68         // virtual dtor as in any base class
  69         virtual ~MessageParameters() { }
  70
  71     protected:
  72         wxString m_filename, m_mimetype;
  73     };
  74
  75     // accessors: all of them return true if the corresponding information
  76     // could be retrieved/found, false otherwise (and in this case all [out]
  77     // parameters are unchanged)
  78         // return the MIME type for this file type
  79     bool GetMimeType(wxString *mimeType) const;
  80     bool GetMimeTypes(wxArrayString& mimeTypes) const;
  81         // fill passed in array with all extensions associated with this file
  82         // type
  83     bool GetExtensions(wxArrayString& extensions);
  84         // get the icon corresponding to this file type
  85     bool GetIcon(wxIcon *icon) const;
  86         // get a brief file type description ("*.txt" => "text document")
  87     bool GetDescription(wxString *desc) const;
  88
  89     // get the command to be used to open/print the given file.
  90         // get the command to execute the file of given type
  91     bool GetOpenCommand(wxString *openCmd,
  92                         const MessageParameters& params) const;
  93         // get the command to print the file of given type
  94     bool GetPrintCommand(wxString *printCmd,
  95                          const MessageParameters& params) const;
  96
  97     // operations
  98         // expand a string in the format of GetOpenCommand (which may contain
  99         // '%s' and '%t' format specificators for the file name and mime type
 100         // and %{param} constructions).
 101     static wxString ExpandCommand(const wxString& command,
 102                                   const MessageParameters& params);
 103
 104     // dtor (not virtual, shouldn't be derived from)
 105     ~wxFileType();
 106
 107 private:
 108     // default ctor is private because the user code never creates us
 109     wxFileType();
 110
 111     // no copy ctor/assignment operator
 112     wxFileType(const wxFileType&);
 113     wxFileType& operator=(const wxFileType&);
 114
 115     wxFileTypeImpl *m_impl;
 116 };
 117
 118 // This class is only used wuth wxMimeTypesManager::AddFallbacks() and is meant
 119 // just as the container for the wxFileType data.
 120 class WXDLLEXPORT wxFileTypeInfo
 121 {
 122 public:
 123     // ctors
 124         // a normal item
 125     wxFileTypeInfo(const char *mimeType,
 126                    const char *openCmd,
 127                    const char *printCmd,
 128                    const char *desc,
 129                    // the other parameters form a NULL terminated list of
 130                    // extensions
 131                    ...);
 132
 133         // invalid item - use this to terminate the array passed to
 134         // wxMimeTypesManager::AddFallbacks
 135     wxFileTypeInfo() { }
 136
 137     bool IsValid() const { return !m_mimeType.IsEmpty(); }
 138
 139     // accessors
 140         // get the MIME type
 141     const wxString& GetMimeType() const { return m_mimeType; }
 142         // get the open command
 143     const wxString& GetOpenCommand() const { return m_openCmd; }
 144         // get the print command
 145     const wxString& GetPrintCommand() const { return m_printCmd; }
 146         // get the description
 147     const wxString& GetDescription() const { return m_desc; }
 148         // get the array of all extensions
 149     const wxArrayString& GetExtensions() const { return m_exts; }
 150
 151 private:
 152     wxString m_mimeType,    // the MIME type in "type/subtype" form
 153              m_openCmd,     // command to use for opening the file (%s allowed)
 154              m_printCmd,    // command to use for printing the file (%s allowed)
 155              m_desc;        // a free form description of this file type
 156
 157     wxArrayString m_exts;   // the extensions which are mapped on this filetype
 158 };
 159
 160 WX_DECLARE_EXPORTED_OBJARRAY(wxFileTypeInfo, wxArrayFileTypeInfo);
 161
 162
 163 // This class accesses the information about all known MIME types and allows
 164 // the application to retrieve information (including how to handle data of
 165 // given type) about them.
 166 //
 167 // NB: currently it doesn't support modifying MIME database (read-only access).
 168 class WXDLLEXPORT wxMimeTypesManager
 169 {
 170 public:
 171     // static helper functions
 172     // -----------------------
 173
 174         // check if the given MIME type is the same as the other one: the second
 175         // argument may contain wildcards ('*'), but not the first. If the
 176         // types are equal or if the mimeType matches wildcard the function
 177         // returns TRUE, otherwise it returns FALSE
 178     static bool IsOfType(const wxString& mimeType, const wxString& wildcard);
 179
 180     // ctor
 181     wxMimeTypesManager();
 182
 183     // Database lookup: all functions return a pointer to wxFileType object
 184     // whose methods may be used to query it for the information you're
 185     // interested in. If the return value is !NULL, caller is responsible for
 186     // deleting it.
 187         // get file type from file extension
 188     wxFileType *GetFileTypeFromExtension(const wxString& ext);
 189         // get file type from MIME type (in format <category>/<format>)
 190     wxFileType *GetFileTypeFromMimeType(const wxString& mimeType);
 191
 192     // other operations: return TRUE if there were no errors or FALSE if there
 193     // were some unreckognized entries (the good entries are always read anyhow)
 194         // read in additional file (the standard ones are read automatically)
 195         // in mailcap format (see mimetype.cpp for description)
 196         //
 197         // 'fallback' parameter may be set to TRUE to avoid overriding the
 198         // settings from other, previously parsed, files by this one: normally,
 199         // the files read most recently would override the older files, but with
 200         // fallback == TRUE this won't happen
 201     bool ReadMailcap(const wxString& filename, bool fallback = FALSE);
 202         // read in additional file in mime.types format
 203     bool ReadMimeTypes(const wxString& filename);
 204
 205     // enumerate all known MIME types
 206     //
 207     // returns the number of retrieved file types
 208     size_t EnumAllFileTypes(wxArrayString& mimetypes);
 209
 210     // these functions can be used to provide default values for some of the
 211     // MIME types inside the program itself (you may also use
 212     // ReadMailcap(filenameWithDefaultTypes, TRUE /* use as fallback */) to
 213     // achieve the same goal, but this requires having this info in a file).
 214     //
 215     // It isn't possible (currently) to provide fallback icons using this
 216     // function.
 217     //
 218     // The filetypes array should be terminated by a NULL entry
 219     void AddFallbacks(const wxFileTypeInfo *filetypes);
 220
 221     // dtor (not virtual, shouldn't be derived from)
 222     ~wxMimeTypesManager();
 223
 224 private:
 225     // no copy ctor/assignment operator
 226     wxMimeTypesManager(const wxMimeTypesManager&);
 227     wxMimeTypesManager& operator=(const wxMimeTypesManager&);
 228
 229     wxMimeTypesManagerImpl *m_impl;
 230
 231     // if m_impl is NULL, create one
 232     void EnsureImpl();
 233
 234     friend class wxMimeTypeCmnModule;
 235 };
 236
 237
 238 // ----------------------------------------------------------------------------
 239 // global variables
 240 // ----------------------------------------------------------------------------
 241
 242 // the default mime manager for wxWindows programs
 243 WXDLLEXPORT_DATA(extern wxMimeTypesManager *) wxTheMimeTypesManager;
 244
 245 #endif
 246   // wxUSE_FILE
 247
 248 #endif
 249   //_MIMETYPE_H
 250
 251 /* vi: set cin tw=80 ts=4 sw=4: */