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