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