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