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