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