1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: mimetype.h 3 // Purpose: interface of wxMimeTypesManager 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 @class wxMimeTypesManager 10 11 This class allows the application to retrieve information about all known 12 MIME types from a system-specific location and the filename extensions to the 13 MIME types and vice versa. 14 15 MIME stands for "Multipurpose Internet Mail Extensions" and was originally 16 used in mail protocols. It's standardized by several RFCs. 17 18 Under Windows, the MIME type information is queried from registry. 19 Under Linux and Unix, it is queried from the XDG data directories. 20 21 Currently, wxMimeTypesManager is limited to @e reading MIME type information. 22 23 The application should not construct its own manager: it should use the 24 object pointer ::wxTheMimeTypesManager. 25 The functions GetFileTypeFromMimeType() and GetFileTypeFromExtension() 26 return a wxFileType object which may be further queried for file description, 27 icon and other attributes. 28 29 @section mimetypemanager_helpers Helper functions 30 31 All of these functions are static (i.e. don't need a wxMimeTypesManager object 32 to call them) and provide some useful operations for string representations of 33 MIME types. Their usage is recommended instead of directly working with MIME 34 types using wxString functions. 35 36 - wxMimeTypesManager::IsOfType() 37 38 @section mimetypemanager_query Query database 39 40 These functions are the heart of this class: they allow to find a file type 41 object from either file extension or MIME type. 42 If the function is successful, it returns a pointer to the wxFileType object 43 which must be deleted by the caller, otherwise @NULL will be returned. 44 45 - wxMimeTypesManager::GetFileTypeFromMimeType() 46 - wxMimeTypesManager::GetFileTypeFromExtension() 47 48 @library{wxbase} 49 @category{cfg} 50 51 @see wxFileType 52 */ 53 class wxMimeTypesManager 54 { 55 public: 56 /** 57 Constructor puts the object in the "working" state. 58 */ 59 wxMimeTypesManager(); 60 61 /** 62 Destructor is not virtual, so this class should not be derived from. 63 */ 64 ~wxMimeTypesManager(); 65 66 /** 67 This function may be used to provide hard-wired fallbacks for the MIME types 68 and extensions that might not be present in the system MIME database. 69 Please see the typetest sample for an example of using it. 70 */ 71 void AddFallbacks(const wxFileTypeInfo* fallbacks); 72 73 /** 74 Gather information about the files with given extension and return the 75 corresponding wxFileType object or @NULL if the extension is unknown. 76 77 The @a extension parameter may have, or not, the leading dot, if it has it, 78 it is stripped automatically. It must not however be empty. 79 */ 80 wxFileType* GetFileTypeFromExtension(const wxString& extension); 81 82 /** 83 Gather information about the files with given MIME type and return the 84 corresponding wxFileType object or @NULL if the MIME type is unknown. 85 */ 86 wxFileType* GetFileTypeFromMimeType(const wxString& mimeType); 87 88 89 /** 90 This function returns @true if either the given @a mimeType is exactly 91 the same as @a wildcard or if it has the same category and the subtype of 92 @a wildcard is '*'. Note that the '*' wildcard is not allowed in 93 @a mimeType itself. 94 95 The comparison don by this function is case insensitive so it is not 96 necessary to convert the strings to the same case before calling it. 97 */ 98 static bool IsOfType(const wxString& mimeType, const wxString& wildcard); 99 100 101 /** 102 Create a new association using the fields of wxFileTypeInfo (at least 103 the MIME type and the extension should be set). 104 */ 105 wxFileType *Associate(const wxFileTypeInfo& ftInfo); 106 107 /** 108 Undo Associate(). 109 */ 110 bool Unassociate(wxFileType *ft) ; 111 112 /** 113 Enumerate all known file types. Returns the number of retrieved items. 114 */ 115 size_t EnumAllFileTypes(wxArrayString& mimetypes); 116 117 }; 118 119 120 /** 121 The global wxMimeTypesManager instance. 122 */ 123 wxMimeTypesManager* wxTheMimeTypesManager; 124 125 126 127 /** 128 @class wxFileType 129 130 This class holds information about a given @e file type. 131 132 File type is the same as MIME type under Unix, but under Windows it corresponds 133 more to an extension than to MIME type (in fact, several extensions may 134 correspond to a file type). 135 136 This object may be created in several different ways: the program might know the 137 file extension and wish to find out the corresponding MIME type or, conversely, it 138 might want to find the right extension for the file to which it writes the 139 contents of given MIME type. Depending on how it was created some fields may be 140 unknown so the return value of all the accessors @b must be checked: @false 141 will be returned if the corresponding information couldn't be found. 142 143 The objects of this class are never created by the application code but are 144 returned by wxMimeTypesManager::GetFileTypeFromMimeType and 145 wxMimeTypesManager::GetFileTypeFromExtension methods. 146 But it is your responsibility to delete the returned pointer when you're done 147 with it! 148 149 A brief reminder about what the MIME types are (see the RFC 1341 for more 150 information): basically, it is just a pair category/type (for example, 151 "text/plain") where the category is a basic indication of what a file is. 152 Examples of categories are "application", "image", "text", "binary", and 153 type is a precise definition of the document format: "plain" in the example 154 above means just ASCII text without any formatting, while "text/html" is the 155 HTML document source. 156 157 A MIME type may have one or more associated extensions: "text/plain" will 158 typically correspond to the extension ".txt", but may as well be associated with 159 ".ini" or ".conf". 160 161 162 @section filetype_example MessageParameters class 163 164 One of the most common usages of MIME is to encode an e-mail message. 165 The MIME type of the encoded message is an example of a message parameter. 166 These parameters are found in the message headers ("Content-XXX"). 167 168 At the very least, they must specify the MIME type and the version of MIME 169 used, but almost always they provide additional information about the message 170 such as the original file name or the charset (for the text documents). 171 These parameters may be useful to the program used to open, edit, view or 172 print the message, so, for example, an e-mail client program will have to 173 pass them to this program. Because wxFileType itself cannot know about 174 these parameters, it uses MessageParameters class to query them. 175 176 The default implementation only requires the caller to provide the file name 177 (always used by the program to be called - it must know which file to open) 178 and the MIME type and supposes that there are no other parameters. 179 180 If you wish to supply additional parameters, you must derive your own class 181 from MessageParameters and override GetParamValue() function, for example: 182 183 @code 184 // provide the message parameters for the MIME type manager 185 class MailMessageParameters : public wxFileType::MessageParameters 186 { 187 public: 188 MailMessageParameters(const wxString& filename, 189 const wxString& mimetype) 190 : wxFileType::MessageParameters(filename, mimetype) 191 { 192 } 193 194 virtual wxString GetParamValue(const wxString& name) const 195 { 196 // parameter names are not case-sensitive 197 if ( name.CmpNoCase("charset") == 0 ) 198 return "US-ASCII"; 199 else 200 return wxFileType::MessageParameters::GetParamValue(name); 201 } 202 }; 203 @endcode 204 205 Now you only need to create an object of this class and pass it to, for example, 206 GetOpenCommand like this: 207 208 @code 209 wxString command; 210 if ( filetype->GetOpenCommand(&command, 211 MailMessageParameters("foo.txt", "text/plain")) ) 212 { 213 // the full command for opening the text documents is in 'command' 214 // (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix) 215 } 216 else 217 { 218 // we don't know how to handle such files... 219 } 220 @endcode 221 222 Windows: As only the file name is used by the program associated with the 223 given extension anyhow (but no other message parameters), there is no need 224 to ever derive from MessageParameters class for a Windows-only program. 225 226 227 @library{wxbase} 228 @category{data} 229 230 @see wxMimeTypesManager 231 */ 232 class wxFileType 233 { 234 private: 235 /** 236 The default constructor is private because you should never create objects of 237 this type: they are only returned by wxMimeTypesManager methods. 238 */ 239 wxFileType(); 240 241 public: 242 /** 243 Class representing message parameters. 244 245 An object of this class may be passed to wxFileType::GetOpenCommand() 246 and GetPrintCommand() if more than the file name needs to be specified. 247 */ 248 class MessageParameters 249 { 250 public: 251 /// Trivial default constructor. 252 MessageParameters(); 253 254 /// Constructor taking a filename and a mime type. 255 MessageParameters(const wxString& filename, 256 const wxString& mimetype = wxEmptyString); 257 258 /// Return the filename. 259 const wxString& GetFileName() const; 260 261 /// Return the MIME type. 262 const wxString& GetMimeType() const; 263 264 /// Overridable method for derived classes. Returns empty string by default. 265 virtual wxString GetParamValue(const wxString& name) const; 266 267 /// Trivial but virtual dtor as this class can be inherited from. 268 virtual ~MessageParameters(); 269 }; 270 271 /** 272 Copy ctor. 273 */ 274 wxFileType(const wxFileTypeInfo& ftInfo); 275 276 /** 277 The destructor of this class is not virtual, so it should not be derived from. 278 */ 279 ~wxFileType(); 280 281 /** 282 This function is primarily intended for GetOpenCommand and GetPrintCommand 283 usage but may be also used by the application directly if, for example, you 284 want to use some non-default command to open the file. 285 286 The function replaces all occurrences of: 287 - %s with the full file name 288 - %t with the MIME type 289 - %{param} with the value of the parameter @e param 290 using the MessageParameters object you pass to it. 291 292 If there is no '%s' in the command string (and the string is not empty), it is 293 assumed that the command reads the data on stdin and so the effect is the same 294 as " %s" were appended to the string. 295 296 Unlike all other functions of this class, there is no error return for this 297 function. 298 */ 299 static wxString ExpandCommand(const wxString& command, 300 const MessageParameters& params); 301 302 /** 303 If the function returns @true, the string pointed to by @a desc is filled 304 with a brief description for this file type: for example, "text document" for 305 the "text/plain" MIME type. 306 */ 307 bool GetDescription(wxString* desc) const; 308 309 /** 310 If the function returns @true, the array @a extensions is filled 311 with all extensions associated with this file type: for example, it may 312 contain the following two elements for the MIME type "text/html" 313 (notice the absence of the leading dot): "html" and "htm". 314 315 @b Windows: This function is currently not implemented: there is no 316 (efficient) way to retrieve associated extensions from the given MIME type 317 on this platform, so it will only return @true if the wxFileType object was 318 created by wxMimeTypesManager::GetFileTypeFromExtension function in the 319 first place. 320 */ 321 bool GetExtensions(wxArrayString& extensions); 322 323 /** 324 If the function returns @true, the @c iconLoc is filled with the 325 location of the icon for this MIME type. 326 327 A wxIcon may be created from @a iconLoc later. 328 329 \note Under Unix MIME manager gathers information about icons from 330 GNOME and KDE settings and thus GetIcon's success depends on 331 availability of these desktop environments. 332 */ 333 bool GetIcon(wxIconLocation* iconLoc) const; 334 335 /** 336 If the function returns @true, the string pointed to by @a mimeType is filled 337 with full MIME type specification for this file type: for example, "text/plain". 338 */ 339 bool GetMimeType(wxString* mimeType) const; 340 341 /** 342 Same as GetMimeType() but returns array of MIME types. 343 344 This array will contain only one item in most cases but sometimes, 345 notably under Unix with KDE, may contain more MIME types. 346 This happens when one file extension is mapped to different MIME types 347 by KDE, mailcap and mime.types. 348 */ 349 bool GetMimeTypes(wxArrayString& mimeTypes) const; 350 351 //@{ 352 /** 353 With the first version of this method, if the @true is returned, the 354 string pointed to by @a command is filled with the command which must be 355 executed (see wxExecute()) in order to open the file of the given type. 356 357 In this case, the name of the file as well as any other parameters 358 is retrieved from MessageParameters() class. 359 360 In the second case, only the filename is specified and the command to be used 361 to open this kind of file is returned directly. An empty string is returned to 362 indicate that an error occurred (typically meaning that there is no standard way 363 to open this kind of files). 364 */ 365 bool GetOpenCommand(wxString* command, const MessageParameters& params); 366 wxString GetOpenCommand(const wxString& filename) const; 367 //@} 368 369 /** 370 If the function returns @true, the string pointed to by @a command is filled 371 with the command which must be executed (see wxExecute()) in order to 372 print the file of the given type. 373 374 The name of the file is retrieved from the MessageParameters class. 375 */ 376 bool GetPrintCommand(wxString* command, 377 const MessageParameters& params) const; 378 379 /** 380 Returns the number of commands for this mime type, and fills the verbs 381 and commands arrays with the command information. 382 */ 383 size_t GetAllCommands(wxArrayString *verbs, wxArrayString *commands, 384 const wxFileType::MessageParameters& params) const; 385 }; 386 387 388 389 /** 390 Container of information about wxFileType. 391 392 This class simply stores information associated with the file type. It 393 doesn't do anything on its own and is used only to allow constructing 394 wxFileType from it (instead of specifying all the constituent pieces 395 separately) and also with wxMimeTypesManager::AddFallbacks(). 396 */ 397 class wxFileTypeInfo 398 { 399 public: 400 /** 401 Default constructor creates an invalid file type info object. 402 403 Such invalid/empty object should be used to terminate the list of file 404 types passed to wxMimeTypesManager::AddFallbacks(). 405 */ 406 wxFileTypeInfo(); 407 408 /** 409 Constructor specifying just the MIME type name. 410 411 Use the various setter methods below to fully initialize the object. 412 413 @since 2.9.2 414 */ 415 wxFileTypeInfo(const wxString& mimeType); 416 417 /** 418 Constructor allowing to specify all the fields at once. 419 420 This is a vararg constructor taking an arbitrary number of extensions 421 after the first four required parameters. The list must be terminated 422 by @c wxNullPtr, notice that @c NULL can't be used here in portable 423 code (C++0x @c nullptr can be used as well if your compiler supports 424 it). 425 */ 426 wxFileTypeInfo(const wxString& mimeType, 427 const wxString& openCmd, 428 const wxString& printCmd, 429 const wxString& description, 430 const wxString& extension, 431 ...); 432 433 /** 434 Constuctor using an array of string elements corresponding to the 435 parameters of the ctor above in the same order. 436 */ 437 wxFileTypeInfo(const wxArrayString& sArray); 438 439 /** 440 Add another extension associated with this file type. 441 442 @since 2.9.2 443 */ 444 void AddExtension(const wxString& ext); 445 446 /** 447 Set the file type description. 448 449 @since 2.9.2 450 */ 451 void SetDescription(const wxString& description); 452 453 /** 454 Set the command to be used for opening files of this type. 455 456 @since 2.9.2 457 */ 458 void SetOpenCommand(const wxString& command); 459 460 /** 461 Set the command to be used for printing files of this type. 462 463 @since 2.9.2 464 */ 465 void SetPrintCommand(const wxString& command); 466 467 /** 468 Set the short description for the files of this type. 469 470 This is only used under MSW for some of the registry keys used for the 471 file type registration. 472 */ 473 void SetShortDesc(const wxString& shortDesc); 474 475 /** 476 Set the icon information. 477 */ 478 void SetIcon(const wxString& iconFile, int iconIndex = 0); 479 480 /** 481 Get the MIME type 482 */ 483 const wxString& GetMimeType() const; 484 485 /** 486 Get the open command 487 */ 488 const wxString& GetOpenCommand() const; 489 490 /** 491 Get the print command 492 */ 493 const wxString& GetPrintCommand() const; 494 495 /** 496 Get the short description (only used under Win32 so far) 497 */ 498 const wxString& GetShortDesc() const; 499 500 /** 501 Get the long, user visible description 502 */ 503 const wxString& GetDescription() const; 504 505 /** 506 Get the array of all extensions 507 */ 508 const wxArrayString& GetExtensions() const; 509 510 /** 511 Get the number of extensions. 512 */ 513 size_t GetExtensionsCount() const; 514 515 /** 516 Get the icon filename 517 */ 518 const wxString& GetIconFile() const; 519 520 /** 521 Get the index of the icon within the icon file. 522 */ 523 int GetIconIndex() const; 524 525 }; 526