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