BTRFS: Reimplement TreeIterator, add some error checks and remove redundancies.
[haiku.git] / docs / user / storage / MimeType.dox
blob2b5e11bc367cf295e85a1770cd4cf5190a3afbc6
1 /*
2  * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3  * Distributed under the terms of the MIT License.
4  *
5  * Authors:
6  *              Ingo Weinhold, bonefish@users.sf.net
7  *              Axel Dörfler, axeld@pinc-software.de
8  *              John Scipione, jscipione@gmail.com
9  *
10  * Corresponds to:
11  *              headers/os/storage/MimeType.h  hrev47402
12  *              src/kits/storage/MimeType.cpp  hrev47402
13  */
16 /*!
17         \file MimeType.h
18         \ingroup storage
19         \ingroup libbe
20         \brief Provides the BMimeType class.
24 /*!
25         \class BMimeType
26         \ingroup storage
27         \ingroup libbe
28         \brief A class that represents a MIME (Multi-purpose Internet Mail
29                Extensions) type string.
31         MIME types use, has grown beyond describing the content of email
32         to describe the content types of applications and file formats.
34         MIME types consist of a supertype and a subtype.
36         \since BeOS R3
40 /*!
41         \fn BMimeType::BMimeType()
42         \brief Creates an uninitialized BMimeType object.
44         \since BeOS R3
48 /*!
49         \fn BMimeType::BMimeType(const char* mimeType)
50         \brief Creates a BMimeType object and initializes it to the supplied
51                MIME type.
53         The supplied string must specify a valid MIME type or supertype.
55         \param mimeType The MIME string.
57         \sa SetTo() for further information.
59         \since BeOS R3
63 /*!
64         \fn BMimeType::~BMimeType()
65         \brief Frees all resources associated with this object.
67         \since BeOS R3
71 /*!
72         \fn status_t BMimeType::SetTo(const char* mimeType)
73         \brief Initializes this object to the supplied MIME type.
75         The supplied string must specify a valid MIME type or supertype.
76         Valid MIME types are given by the following grammar:
78         MIMEType        ::= Supertype "/" [ Subtype ]
79         Supertype       ::= "application" | "audio" | "image" | "message"
80                                         | "multipart" | "text" | "video"
81         Subtype         ::= MIMEChar MIMEChar*
82         MIMEChar        ::= any character except white spaces, CTLs and '/', '<', '>',
83                                         '@',, ',', ';', ':', '"', '(', ')', '[', ']', '?', '=', '\'
84                                         (Note: RFC1341 also forbits '.', but it is allowed here.)
86         Currently the supertype is not restricted to one of the seven types given,
87         but can be an arbitrary string (obeying the same rule as the subtype).
88         Nevertheless it is a very bad idea to use another supertype.
89         The supplied MIME string is copied; the caller retains the ownership.
91         \param mimeType The MIME string.
93         \returns A status code.
94         \retval B_OK Everything went fine.
95         \retval B_BAD_VALUE Invalid \a mimeType string.
96         \retval B_NO_INIT BMimeType was uninitialized.
97         \retval B_NO_MEMORY Insufficient memory to copy the MIME string.
99         \since BeOS R3
104         \fn void BMimeType::Unset()
105         \brief Returns the object to an uninitialized state.
107         \since BeOS R3
112         \fn status_t BMimeType::InitCheck() const
113         \brief Returns the result of the most recent constructor or SetTo() call.
115         \returns \c B_OK If the object is properly initialized, a specific
116                  error code otherwise.
118         \since BeOS R3
123         \fn const char* BMimeType::Type() const
124         \brief Returns the MIME string represented by this object.
126         \return The MIME string, if the object is properly initialized, \c NULL
127                 otherwise.
129         \since BeOS R3
134         \fn bool BMimeType::IsValid() const
135         \brief Returns whether the object represents a valid MIME type.
137         \return \c true, if the object is properly initialized, \c false
138                 otherwise.
140         \sa SetTo() for further information.
142         \since BeOS R3
147         \fn bool BMimeType::IsSupertypeOnly() const
148         \brief Returns whether this objects represents a supertype.
150         \return \c true, if the object is properly initialized and represents a
151                 supertype, \c false otherwise.
153         \since BeOS R3
158         \fn bool BMimeType::IsInstalled() const
159         \brief Returns whether or not this type is currently installed in the
160                MIME database.
162         To add the MIME type to the database, call \c Install().
163         To remove the MIME type from the database, call \c Delete().
165         \return A \c bool indicating whether or not this type is currently
166                 installed in the MIME database.
167         \retval true The MIME type is currently installed in the database.
168         \retval false The MIME type is not currently installed in the database.
170         \since BeOS R3
175         \fn status_t BMimeType::GetSupertype(BMimeType* supertype) const
176         \brief Gets the \a supertype of the MIME type represented by this object.
178         The supplied object is initialized to this object's \a supertype. If this
179         BMimeType is not properly initialized, the supplied object will be Unset().
181         \param supertype A pointer to the BMimeType object that shall be
182                initialized to this object's \a supertype.
184         \returns A status code.
185         \retval B_OK Everything went fine.
186         \retval B_BAD_VALUE \c NULL \a superType, this object is not initialized,
187                 or this object is a supertype only.
188         \retval B_NO_INIT BMimeType was uninitialized.
190         \since BeOS R3
195         \fn bool BMimeType::operator==(const BMimeType &type) const
196         \brief Returns whether this and the supplied MIME type are equal.
198         Two BMimeType objects are said to be equal if they represent the same
199         MIME string, ignoring case, or if both are not initialized.
201         \warning In BeOS R5 two uninitialized BMimeType objects were not
202                  considered to be equal, in Haiku they are.
204         \param type The BMimeType to be compared with.
206         \return \c true, if the objects are equal, \c false otherwise.
208         \since BeOS R3
213         \fn bool BMimeType::operator==(const char* type) const
214         \brief Returns whether this and the supplied MIME type are equal.
216         A BMimeType objects equals a MIME string, if its MIME string equals the
217         latter one, ignoring case, or if it is uninitialized and the MIME string
218         is \c NULL.
220         \warning In BeOS R5 an uninitialized BMimeType object was not
221                  considered to be equal to \c NULL, in Haiku it is.
223         \param type The MIME string to be compared with.
225         \return \c true, if the MIME types are equal, \c false otherwise.
227         \since BeOS R4
232         \fn bool BMimeType::Contains(const BMimeType* type) const
233         \brief Returns whether this MIME type is a supertype of or equals the
234         supplied one.
236         \param type The MIME type.
238         \returns \c true, if this MIME type is a supertype of or equals the
239                  supplied one, \c false otherwise.
241         \since BeOS R3
246         \fn status_t BMimeType::Install()
247         \brief Adds the MIME type to the MIME database.
249         To check if the MIME type is already installed, call \c IsInstalled().
250         To remove the MIME type from the database, call \c Delete().
252         \note The R5 implementation returns random values if the type is already
253         installed, so be sure to check \c IsInstalled() first.
255         \returns \c B_OK on success or another error code on failure.
257         \see Delete()
259         \since BeOS R3
264         \fn status_t BMimeType::Delete()
265         \brief Removes the MIME type from the MIME database.
267         To check if the MIME type is already installed, call \c IsInstalled().
268         To add the MIME type to the database, call \c Install().
270         \note Calling \c BMimeType::Delete() does not uninitialize or otherwise
271               deallocate the \c BMimeType object; it simply removes the type from
272               the database.
274         \returns \c B_OK on success or another error code on failure.
276         \since BeOS R3
281         \fn status_t BMimeType::GetIcon(BBitmap* icon, icon_size size) const
282         \brief Fetches the large or mini icon associated with the MIME type.
284         The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
285         must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
286         icon. Additionally, the bitmap must be in the \c B_CMAP8 color space
287         (8-bit color).
289         \param icon Pointer to a pre-allocated \c BBitmap of proper size and
290                colorspace into which the icon is copied.
291         \param size Value that specifies which icon to return.
292                Currently \c B_LARGE_ICON and \c B_MINI_ICON are supported.
294         \returns A status code.
295         \retval B_OK Everything went fine.
296         \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
297                 given type.
298         \retval B_NO_INIT BMimeType was uninitialized.
300         \since BeOS R3
305         \fn status_t BMimeType::GetIcon(uint8** data, size_t* size) const
306         \brief Fetches the vector icon associated with the MIME type
307                 The icon data is returned in \c data.
309         \param data Pointer in which the allocated icon data is returned. You
310                need to delete the buffer when you are done with it.
311         \param size Pointer in which the size of the allocated icon data is
312                returned.
314         \returns A status code.
315         \retval B_OK Everything went fine.
316         \retval B_ENTRY_NOT_FOUND No icon of the given size found for the given
317                 type.
318         \retval B_NO_INIT BMimeType was uninitialized.
320         \since BeOS R3
325         \fn status_t BMimeType::GetPreferredApp(char* signature,
326                 app_verb verb) const
327         \brief Fetches the signature of the preferred application from
328                the MIME database.
330         The preferred app is the application that's used to access a file when,
331         for example, the user double-clicks the file in a Tracker window. Unless
332         the file identifies in its attributes a "custom" preferred app, Tracker
333         will ask the file type database for the preferred app
334         that's associated with the file's type.
336         The string pointed to by \c signature must be long enough to
337         hold the preferred applications signature; a length of
338         \c B_MIME_TYPE_LENGTH is recommended.
340         \param signature Pointer to a pre-allocated string into which the
341                signature of the preferred app is copied. If the function fails,
342                the contents of the string are undefined.
343         \param verb \c app_verb value that specifies the type of access for
344                 which you are requesting the preferred app. Currently, the only
345                 supported app verb is \c B_OPEN.
347         \returns A status code.
348         \retval B_OK Success
349         \retval B_ENTRY_NOT_FOUND No preferred app exists for the given type
350                 and app_verb.
351         \retval B_NO_INIT BMimeType was uninitialized.
353         \see SetPreferredApp()
355         \since BeOS R3
360         \fn status_t BMimeType::GetAttrInfo(BMessage* info) const
361         \brief Fetches from the MIME database a BMessage describing the attributes
362                typically associated with files of the given MIME type.
364         The attribute information is returned in a pre-allocated BMessage pointed
365         to by the \c info parameter (note that the any prior contents of the
366         message will be destroyed). If the method succeeds, the format of the
367         BMessage pointed to by \c info will be the following:
369         <table>
370                 <tr>
371                         <td><b>field name</b></td>
372                         <td><b>type</b></td>
373                         <td><b>element[0..n]</b></td>
374                 </tr>
375                 <tr>
376                         <td> "attr:name"</td>
377                         <td> \c B_STRING_TYPE </td>
378                         <td> The name of each attribute </td>
379                 </tr>
380                 <tr>
381                         <td> "attr:public_name"</td>
382                         <td> \c B_STRING_TYPE </td>
383                         <td> The human-readable name of each attribute </td>
384                 </tr>
385                 <tr>
386                         <td> "attr:type"</td>
387                         <td> \c B_INT32_TYPE </td>
388                         <td> The type code for each attribute </td>
389                 </tr>
390                 <tr>
391                         <td> "attr:viewable"</td>
392                         <td> \c B_BOOL_TYPE </td>
393                         <td> For each attribute: \c true if the attribute is public,
394                                 \c false if it's private </td>
395                 </tr>
396                 <tr>
397                         <td> "attr:editable"</td>
398                         <td> \c B_BOOL_TYPE </td>
399                         <td> For each attribute: \c true if the attribute should be user
400                                 editable, \c false if not </td>
401                 </tr>
402         </table>
404         The \c BMessage::what value is set to decimal \c 233, but is otherwise
405         meaningless.
407         \param info Pointer to a pre-allocated BMessage into which information about
408                the MIME type's associated file attributes is stored.
410         \returns \c B_OK on success or another error code on failure.
412         \see SetAttrInfo()
414         \since BeOS R3
419         \fn status_t BMimeType::GetFileExtensions(BMessage* extensions) const
420         \brief Fetches the MIME type's associated filename extensions from the
421                 MIME database.
423         The MIME database associates a list of filename extensions (a character
424         string following the rightmost dot, \c ".", character in the filename)
425         with each type. These extensions can then be used to help determine the
426         type of any untyped files that may be encountered.
428         The list of extensions is returned in a pre-allocated BMessage pointed
429         to by the \c extensions parameter (note that the any prior contents of
430         the message will be destroyed). If the method succeeds, the format of
431         the BMessage pointed to by \c extensions will be the following:
433         - The message's \c "extensions" field will contain an indexed array
434           of strings, one for each extension. The extensions are given
435           without the preceding \c "." character by convention.
436         - The message's \c "type" field will be a string containing the
437           MIME type whose associated file extensions you are fetching.
438         - The \c what member of the BMessage will be set to \c 234, but
439           is otherwise irrelevant.
441         Note that any other fields present in the BMessage passed to the most
442         recent \c SetFileExtensions() call will also be returned.
444         \param extensions Pointer to a pre-allocated BMessage into which the
445                MIME type's associated file extensions will be stored.
447         \returns \c B_OK on success or another error code on failure.
449         \see SetFileExtensions()
451         \since BeOS R3
456         \fn status_t BMimeType::GetShortDescription(char* description) const
457         \brief Fetches the MIME type's short description from the MIME database.
459         The string pointed to by \c description must be long enough to
460         hold the short description; a length of \c B_MIME_TYPE_LENGTH is
461         recommended.
463         \param description Pointer to a pre-allocated string into which the long
464                description is copied. If the function fails, the contents of the
465                string are undefined.
467         \returns A status code.
468         \retval B_OK Success
469         \retval B_ENTRY_NOT_FOUND No short description exists for the given type.
470         \retval B_NO_INIT BMimeType was uninitialized.
472         \see SetShortDescription()
474         \since BeOS R3
479         \fn status_t BMimeType::GetLongDescription(char* description) const
480         \brief Fetches the MIME type's long description from the MIME database.
482         The string pointed to by \c description must be long enough to
483         hold the long description; a length of \c B_MIME_TYPE_LENGTH is
484         recommended.
486         \param description Pointer to a pre-allocated string into which the
487                long description is copied. If the function fails, the contents
488                of the string are undefined.
490         \returns A status code.
491         \retval B_OK Success
492         \retval B_ENTRY_NOT_FOUND No long description exists for the given type.
493         \retval B_NO_INIT BMimeType was uninitialized.
495         \see SetLongDescription()
497         \since BeOS R3
502         \fn status_t BMimeType::GetSupportingApps(BMessage* signatures) const
503         \brief Fetches a \c BMessage containing a list of MIME signatures of
504                applications that are able to handle files of this MIME type.
506         If successful, the BMessage containing the MIME signatures will be of
507         the following format:
509         <table>
510                 <tr>
511                         <td><b>field name</b></td>
512                         <td><b>type</b></td>
513                         <td><b>contains</b></td>
514                 </tr>
515                 <tr>
516                         <td> "applications"</td>
517                         <td> \c B_STRING_TYPE[] </td>
518                         <td>
519                                 An array of MIME signatures. The first <i> n </i> signatures
520                                 (where <i> n </i> is the value in the \c "be:sub" field of the
521                                 message) are able to handle the full type (supertype
522                                 <i> and </i> subtype). The remaining signatures are of
523                                 applications that handle the supertype only.
524                         </td>
525                 </tr>
526                 <tr>
527                         <td> "be:sub"</td>
528                         <td> \c B_INT32_TYPE </td>
529                         <td>
530                                 The number of applications in the \c "applications" array that
531                                 can handle the object's full MIME type. These applications are
532                                 listed first in the array. This field is omitted if the object
533                                 represents a supertype only.
534                         </td>
535                 </tr>
536                 <tr>
537                         <td> "be:super"</td>
538                         <td> \c B_INT32_TYPE </td>
539                         <td>
540                                 The number of applications in the "applications" array that can
541                                 handle the object's supertype (not counting those that can
542                                 handle the full type).
543                                 These applications are listed after the full-MIME-type
544                                 supporters. By definition, the \c GetWildcardApps() function
545                                 never returns supertype-only apps.
546                         </td>
547                 </tr>
548         </table>
550         The \c BMessage::what value is meaningless and should be ignored.
552         \param signatures Pointer to a pre-allocated BMessage into which the
553                signatures of the supporting applications will be copied.
555         \returns \c B_OK on success or an error code on failure.
557         \see SetSupportingApps()
559         \since BeOS R3
564         \fn status_t BMimeType::SetIcon(const BBitmap* icon, icon_size which)
565         \brief Sets the large or mini icon for the MIME type.
567         The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
568         must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
569         icon. Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit
570         color).
572         If you want to erase the current icon, pass \c NULL as the \c icon argument.
574         \param icon Pointer to a pre-allocated \c BBitmap of proper size and
575                colorspace containing the new icon, or \c NULL to clear the current
576                icon.
577         \param which Value that specifies which icon to update. Currently
578                \c B_LARGE_ICON and \c B_MINI_ICON are supported.
580         \returns \c B_OK on success or another error code on failure.
582         \since BeOS R3
587         \fn status_t BMimeType::SetIcon(const uint8* data, size_t size)
588         \brief Sets the vector icon for the MIME type
590         The icon is copied from the provided \a data which must contain
591         \a size bytes.
593         If you want to erase the current icon, pass \c NULL as the \a data argument.
595         \param data Pointer to a buffer containing the new icon, or \c NULL to clear
596                the current icon.
597         \param size Size of the provided buffer.
599         \returns \c B_OK on success or another error code on failure.
601         \since Haiku R1
606         \fn status_t BMimeType::SetPreferredApp(const char* signature,
607                 app_verb verb)
608         \brief Sets the preferred application for the MIME type.
610         The preferred app is the application that's used to access a file when,
611         for example, the user double-clicks the file in a Tracker window. Unless
612         the file identifies in its attributes a "custom" preferred app, Tracker
613         will ask the file type database for the preferred app that's associated
614         with the file's type.
616         The string pointed to by \c signature must be of length less than
617         \c B_MIME_TYPE_LENGTH characters.
619         \note If the MIME type is not installed, it will first be installed,
620         and then the preferred app will be set.
622         \param signature Pointer to a pre-allocated string containing the
623                signature of the new preferred app.
624         \param verb \c app_verb value that specifies the type of access for
625                which you are setting the preferred app. Currently, the only
626                supported app verb is \c B_OPEN.
628         \returns \c B_OK on success or another error code on failure.*/
630         \since BeOS R3
635         \fn status_t BMimeType::SetAttrInfo(const BMessage* info)
636         \brief Sets the description of the attributes typically associated
637                 with files of the given MIME type
639         The attribute information is technically arbitrary, but the expected
640         format of the BMessage pointed to by the \c info parameter is as follows:
642         <table>
643                 <tr>
644                         <td><b>field name</b></td>
645                         <td><b>type</b></td>
646                         <td><b>element[0..n]</b></td>
647                 </tr>
648                 <tr>
649                         <td> "attr:name"</td>
650                         <td> \c B_STRING_TYPE </td>
651                         <td> The name of each attribute </td>
652                 </tr>
653                 <tr>
654                         <td> "attr:public_name"</td>
655                         <td> \c B_STRING_TYPE </td>
656                         <td> The human-readable name of each attribute </td>
657                 </tr>
658                 <tr>
659                         <td> "attr:type"</td>
660                         <td> \c B_INT32_TYPE </td>
661                         <td> The type code for each attribute </td>
662                 </tr>
663                 <tr>
664                         <td> "attr:viewable"</td>
665                         <td> \c B_BOOL_TYPE </td>
666                         <td> For each attribute: \c true if the attribute is public,
667                                 \c false if it's private </td>
668                 </tr>
669                 <tr>
670                         <td> "attr:editable"</td>
671                         <td> \c B_BOOL_TYPE </td>
672                         <td> For each attribute: \c true if the attribute should be
673                                 user editable, \c false if not </td>
674                 </tr>
675         </table>
677         The \c BMessage::what value is ignored.
679         \param info Pointer to a pre-allocated and properly formatted BMessage
680                containing information about the file attributes typically
681                associated with the MIME type.
683         \returns \c B_OK on success or another error code on failure.
685         \since BeOS R3
690         \fn status_t BMimeType::SetFileExtensions(const BMessage* extensions)
691         \brief Sets the list of filename extensions associated with the MIME type.
693         The MIME database associates a list of filename extensions (a character
694         string following the rightmost dot, \c ".", character in the filename)
695         with each type. These extensions can then be used to help determine the
696         type of any untyped files that may be encountered.
698         The list of extensions is given in a pre-allocated BMessage pointed to by
699         the \c extensions parameter. The format of the message should be as follows:
700         - The message's \c "extensions" field should contain an indexed array of
701           strings, one for each extension. The extensions are to be given
702           without the preceding \c "." character (i.e. \c "html" or \c "mp3",
703           not \c ".html" or \c ".mp3" ).
704         - The \c what member of the BMessage is ignored.
706         \note Any other fields present in the \c BMessage will currently be
707               retained and returned by calls to \c GetFileExtensions(); however,
708               this may change in the future, so it is recommended that you not rely
709               on this behavior, and that no other fields be present. Also, note that
710               no checking is performed to verify the \c BMessage is properly
711               formatted; it's up to you to do things right.
713         Finally, bear in mind that \c SetFileExtensions() clobbers the existing set
714         of extensions. If you want to augment a type's extensions, you should
715         retrieve the existing set, add the new ones, and then call
716         \c SetFileExtensions().
718         \param extensions Pointer to a pre-allocated, properly formatted BMessage
719                containing the new list of file extensions to associate with this
720                MIME type.
722         \returns \c B_OK on success or another error code on failure.
724         \since BeOS R3
729         \fn status_t BMimeType::SetShortDescription(const char* description)
730         \brief Sets the short description field for the MIME type.
732         The string pointed to by \c description must be of length less than
733         \c B_MIME_TYPE_LENGTH characters.
735         \note If the MIME type is not installed, it will first be installed,
736         and then the short description will be set.
738         \param description Pointer to a pre-allocated string containing the
739                new short description.
741         \returns \c B_OK on success or another error code on failure.
743         \since BeOS R3
748         \fn status_t BMimeType::SetLongDescription(const char* description)
749         \brief Sets the long description field for the MIME type.
751         The string pointed to by \c description must be of length less than
752         \c B_MIME_TYPE_LENGTH characters.
754         \note If the MIME type is not installed, it will first be installed,
755         and then the long description will be set.
757         \param description Pointer to a pre-allocated string containing the new
758                long description
760         \returns \c B_OK on success or another error code on failure.
762         \since BeOS R3
767         \fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes)
768         \brief Fetches a BMessage listing all the MIME \a supertypes currently
769                installed in the MIME database.
771         The types are copied into the \c "super_types" field of the passed-in
772         \c BMessage. The \c BMessage must be pre-allocated.
774         \param supertypes Pointer to a pre-allocated \c BMessage into which the
775                MIME \a supertypes will be copied.
777         \returns \c B_OK on success or another error code on failure.
779         \since BeOS R3
784         \fn status_t BMimeType::GetInstalledTypes(BMessage* types)
785         \brief Fetches a BMessage listing all the MIME types currently installed
786         in the MIME database.
788         The types are copied into the \c "types" field of the passed-in \c BMessage.
789         The \c BMessage must be pre-allocated.
791         \param types Pointer to a pre-allocated \c BMessage into which the
792                MIME types will be copied.
794         \returns \c B_OK on success or another error code on failure.
796         \since BeOS R3
801         \fn status_t BMimeType::GetInstalledTypes(const char* supertype,
802                 BMessage* types)
803         \brief Fetches a BMessage listing all the MIME subtypes of the given
804                \a supertype currently installed in the MIME database.
806         The types are copied into the \c "types" field of the passed-in
807         \c BMessage. The \c BMessage must be pre-allocated.
809         \param supertype Pointer to a string containing the MIME \a supertype whose
810                subtypes you wish to retrieve.
811         \param types Pointer to a pre-allocated \c BMessage into which the
812                appropriate MIME subtypes will be copied.
814         \returns \c B_OK on success or another error code on failure.
816         \since BeOS R3
821         \fn status_t BMimeType::GetWildcardApps(BMessage* wild_ones)
822         \brief Fetches a \c BMessage containing a list of MIME signatures of
823                applications that are able to handle files of any type.
825         This function is the same as calling \c GetSupportingApps() on a
826         \c BMimeType object initialized to a MIME type of]
827         \c "application/octet-stream".
829         \param wild_ones Pointer to a pre-allocated BMessage into which
830                signatures of applications supporting files of any type
831                are copied.
833         \returns \c B_OK on success or another error code on failure.
835         \sa GetSupportingApps() for details on the format of the data returned in
836             the \c BMessage pointed to by \c wild_ones.
838         \since BeOS R3
843         \fn bool BMimeType::IsValid(const char* string)
844         \brief Returns whether the given string represents a valid MIME type.
846         \param string The MIME type string.
848         \return \c true, if the given string represents a valid MIME type.
850         \sa SetTo() for further information.
852         \since BeOS R3
857         \fn status_t BMimeType::GetAppHint(entry_ref* ref) const
858         \brief Fetches an \c entry_ref that serves as a hint as to where the MIME
859                type's preferred application might live
861         The app hint is a path that identifies the executable that should be used
862         when launching an application that has this signature. For example, when
863         Tracker needs to launch an app of type \c "application/YourAppHere",
864         it asks the database for the application hint. This hint is converted to an
865         \c entry_ref before it is passed to the caller. Of course, the path may not
866         point to an application, or it might point to an application
867         with the wrong signature (and so on); that's why this is merely a hint.
869         The \c entry_ref pointed to by \c ref must be pre-allocated.
871         \param ref Pointer to a pre-allocated \c entry_ref into which the location
872                of the app hint is copied. If the function fails, the contents of
873                the \c entry_ref are undefined.
875         \return A status code, B_OK on success or an error code otherwise.
876         \retval B_OK The ref was retrieved successfully.
877         \retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref.
878         \retval B_NO_INIT BMimeType was uninitialized.
880         \since BeOS R3
885         \fn status_t BMimeType::SetAppHint(const entry_ref* ref)
886         \brief Sets the app hint field for the MIME type
888         The app hint is a path that identifies the executable that should be used
889         when launching an application that has this signature. For example, when
890         Tracker needs to launch an app of type \c "application/YourAppHere",
891         it asks the database for the application hint. This hint is converted to an
892         \c entry_ref before it is passed to the caller. Of course, the path may not
893         point to an application, or it might point to an application with the wrong
894         signature (and so on); that's why this is merely a hint.
896         The \c entry_ref pointed to by \c ref must be pre-allocated. It must be a
897         valid \c entry_ref (i.e. <code>entry_ref(-1, -1, "some_file")</code> will
898         trigger an error), but it need not point to an existing file, nor need
899         it actually point to an application. That's not to say that it shouldn't;
900         such an \c entry_ref would render the app hint useless.
902         \param ref Pointer to a pre-allocated \c entry_ref containting the location
903                of the new app hint
905         \returns \c B_OK on success or another error code on failure.
906         \retval B_OK The ref was retrieved successfully.
907         \retval B_NO_INIT BMimeType was uninitialized.
908         \retval B_BAD_VALUE \a ref was \c NULL.
909         \retval B_NO_INIT BMimeType was uninitialized.
911         \since BeOS R3
916         \fn status_t BMimeType::GetIconForType(const char* type, BBitmap* icon,
917                 icon_size which) const
918         \brief Fetches the large or mini icon used by an application of this type
919                for files of the given type.
921         This can be confusing, so here's how this function is intended to be used:
922         - The actual \c BMimeType object should be set to the MIME signature
923           of an application for whom you want to look up custom icons for
924           custom MIME types.
925         - The \c type parameter specifies the file type whose custom icon you
926           are fetching.
928         The type of the \c BMimeType object is not required to actually be a
929         subtype of \c "application/"; that is the intended use however, and calling
930         \c GetIconForType() on a non-application type will likely return
931         \c B_ENTRY_NOT_FOUND.
933         The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
934         must be the proper size: \c 32x32 for the large icon, \c 16x16 for the
935         mini icon. Additionally, the bitmap must be in the \c B_CMAP8 color space
936         (8-bit color).
938         \param type Pointer to a pre-allocated string containing the MIME type
939                whose custom icon you wish to fetch.
940         \param icon Pointer to a pre-allocated \c BBitmap of proper size and
941                colorspace into which the icon is copied.
942         \param which Value that specifies which icon to return. Currently
943                \c B_LARGE_ICON and \c B_MINI_ICON are supported.
945         \returns A status code, \c B_OK on success or an error code otherwise.
946         \retval B_OK Success
947         \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
948                 given type.
949         \retval B_NO_INIT BMimeType was uninitialized.
951         \since BeOS R3
956         \fn status_t BMimeType::GetIconForType(const char* type,
957                 uint8** _data, size_t* _size) const
958         \brief Fetches the vector icon used by an application of this type for
959                files of the given type.
961         The icon data is returned in \c data.
962         See the other GetIconForType() for more information.
964         \param type Pointer to a pre-allocated string containing the MIME type whose
965                custom icon you wish to fetch.
966         \param _data Pointer in which the allocated icon data is returned. You need
967                to delete the buffer when you are done with it.
968         \param _size Pointer in which the size of the allocated icon data is
969                filled out.
971         \returns A status code, \c B_OK on success or an error code otherwise.
972         \retval B_OK Success.
973         \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
974                 given type.
975         \retval B_NO_INIT BMimeType was uninitialized.
977         \since Haiku R1
982         \fn status_t BMimeType::SetIconForType(const char* type,
983                 const BBitmap* icon, icon_size which)
984         \brief Sets the large or mini icon used by an application of this type
985                for files of the given \a type.
987         This can be confusing, so here's how this function is intended to be used:
988         - The actual \c BMimeType object should be set to the MIME signature of an
989           application to whom you want to assign custom icons for custom MIME types.
990         - The \c type parameter specifies the file type whose custom icon you are
991           setting.
993         The type of the \c BMimeType object is not required to actually be a subtype
994         of \c "application/"; that is the intended use however, and
995         application-specific icons are not expected to be present for
996         non-application types.
998         The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
999         must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
1000         icon.
1002         If you want to erase the current icon, pass \c NULL as the \c icon argument.
1004         \param type Pointer to a pre-allocated string containing the MIME type whose
1005                custom icon you wish to set.
1006         \param icon Pointer to a pre-allocated \c BBitmap of proper size and
1007                colorspace containing the new icon, or \c NULL to clear the current
1008                icon.
1009         \param which Value that specifies which icon to update. Currently
1010                \c B_LARGE_ICON and \c B_MINI_ICON are supported.
1012         \returns \c B_OK on success or another error code on failure.
1014         \since BeOS R3
1019         \fn status_t BMimeType::SetIconForType(const char* type, const uint8* data,
1020                 size_t dataSize)
1021         \brief Sets the icon used by an application of this type for files of the
1022                given \a type.
1024         This can be confusing, so here's how this function is intended to be used:
1025         - The actual \c BMimeType object should be set to the MIME signature of an
1026           application to whom you want to assign custom icons for custom MIME types.
1027         - The \c type parameter specifies the file type whose custom icon you are
1028           setting.
1030         The type of the \c BMimeType object is not required to actually be a subtype
1031         of \c "application/"; that is the intended use however, and
1032         application-specific icons are not expected to be present for
1033         non-application types.
1035         The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
1036         must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
1037         icon.
1039         If you want to erase the current icon, pass \c NULL as the \c icon argument.
1041         \param type Pointer to a pre-allocated string containing the MIME type whose
1042                custom icon you wish to set.
1043         \param data Pointer to a pre-allocated uint8 array of the proper size to
1044                contain the new icon, or \c NULL to clear the current icon.
1045         \param dataSize The size of \a data in bytes.
1047         \returns \c B_OK on success or another error code on failure.
1049         \since Haiku R1
1054         \fn status_t BMimeType::GetSnifferRule(BString* result) const
1055         \brief Retrieves the MIME type's sniffer rule.
1057         \param result Pointer to a pre-allocated BString into which the value is
1058                copied.
1060         \returns A status code.
1061         \retval B_OK Everything went fine.
1062         \retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType.
1063         \retval B_ENTRY_NOT_FOUND The MIME type is not installed.
1064         \retval B_NO_INIT BMimeType was uninitialized.
1066         \see SetSnifferRule()
1068         \since Haiku R1
1073         \fn status_t BMimeType::SetSnifferRule(const char* rule)
1074         \brief Sets the MIME type's sniffer rule.
1076         If the supplied \a rule is \c NULL, the MIME type's sniffer rule is
1077         unset.
1079         SetSnifferRule() does also return \c B_OK, if the type is not installed,
1080         but the call will have no effect in this case.
1082         \param rule The rule string, may be \c NULL.
1084         \returns A status code.
1085         \retval B_OK Everything went fine.
1086         \retval B_BAD_VALUE Uninitialized BMimeType.
1087         \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid.
1088         \retval B_NO_INIT BMimeType was uninitialized.
1090         \sa CheckSnifferRule()
1092         \since Haiku R1
1097         \fn status_t BMimeType::CheckSnifferRule(const char* rule,
1098                 BString* parseError)
1099         \brief Checks whether a MIME sniffer rule is valid or not.
1101         A MIME sniffer rule is valid, if it is well-formed with respect to the
1102         following grammar and fulfills some further conditions listed thereafter:
1104 \verbatim
1105         Rule                    ::= LWS Priority LWS ExprList LWS
1106         ExprList                ::= Expression (LWS Expression)*
1107         Expression              ::= "(" LWS (PatternList | RPatternList) LWS ")"
1108                                                 | Range LWS "(" LWS PatternList LWS ")"
1109         RPatternList    ::= RPattern (LWS "|" LWS RPattern)*
1110         PatternList             ::= Pattern (LWS "|" LWS Pattern)*
1111         RPattern                ::= Range LWS Pattern
1112         Pattern                 ::= PString [ LWS "&" LWS Mask ]
1113         Range                   ::=     "[" LWS SDecimal [LWS ":" LWS SDecimal] LWS "]"
1115         Priority                ::= Float
1116         Mask                    ::= PString
1117         PString                 ::= HexString | QuotedString | Octal [UnquotedString]
1118                                                 EscapedChar [UnquotedString]
1119         HexString               ::= "0x" HexPair HexPair*
1120         HexPair                 ::= HexChar HexChar
1121         QuotedString    ::= '"' QChar QChar* '"' | "'" QChar QChar* "'"
1122         Octal                   ::= "\" OctChar [OctChar [OctChar]]
1123         SDecimal                ::= ["+" | "-"] Decimal
1124         Decimal                 ::= DecChar DecChar*
1125         Float                   ::= Fixed [("E" | "e") Decimal]
1126         Fixed                   ::= SDecimal ["." [Decimal]] | [SDecimal] "." Decimal
1127         UnquotedString  ::= UChar UChar*
1128         LWS                             ::= LWSChar*
1130         LWSChar                 ::= LF | " " | TAB
1131         OctChar                 ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
1132         DecChar                 ::= OctChar | "8" | "9"
1133         HexChar                 ::= DecChar | "a" | "b" | "c" | "d" | "e" | "A" | "B" | "C"
1134                                                 | "D" | "E"
1135         Char                    :: <any character>
1136         QChar                   ::= <Char except "\", "&", "'" and '"'> | EscapedChar
1137         EscapedChar             ::= "\" Char
1138         UChar                   ::= <QChar except LWSChar>
1140         Conditions:
1141         (checked)
1142         - If a mask is specified for a pattern, this mask must have the same
1143           length as the pattern string.
1144         (not checked)
1145         - 0 <= Priority <= 1
1146         - 0 <= Range begin <= Range end
1147         - Rules of the form "() | () | ..." are invalid.
1149         Examples:
1150         - 1.0 ('ABCD')
1151           The file must start with the string "ABCD". The priority of the rule
1152           is 1.0 (maximal).
1153         - 0.8 [0:3] ('ABCD' | 'abcd')
1154           The file must contain the string "ABCD" or "abcd" starting somewhere in
1155           the first four bytes. The rule priority is 0.8.
1156         - 0.5 ([0:3] 'ABCD' | [0:3] 'abcd' | [13] 'EFGH')
1157           The file must contain the string "ABCD" or "abcd" starting somewhere in
1158           the first four bytes or the string "EFGH" at position 13. The rule
1159           priority is 0.5.
1160         - 0.8 [0:3] ('ABCD' & 0xff00ffff | 'abcd' & 0xffff00ff)
1161           The file must contain the string "A.CD" or "ab.d" (whereas "." is an
1162           arbitrary character) starting somewhere in the first four bytes. The
1163           rule priority is 0.8.
1165         Real examples:
1166         - 0.20 ([0]"//" | [0]"/\*" | [0:32]"#include" | [0:32]"#ifndef"
1167                 | [0:32]"#ifdef")
1168           text/x-source-code
1169         - 0.70 ("8BPS  \000\000\000\000" & 0xffffffff0000ffffffff )
1170           image/x-photoshop
1171 \endverbatim
1173         \param rule The rule string.
1174         \param parseError A pointer to a pre-allocated BString into which a
1175                description of the parse error is written (if any), may be \c NULL.
1177         \returns A status code.
1178         \retval B_OK The supplied sniffer rule is valid.
1179         \retval B_BAD_VALUE \c NULL \a rule.
1180         \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A
1181                 description of the error is written to \a parseError, if supplied.
1182         \retval B_NO_INIT BMimeType was uninitialized.
1184         \since Haiku R1
1189         \fn status_t BMimeType::GuessMimeType(const entry_ref* file,
1190                 BMimeType* type)
1191         \brief Guesses a MIME type for the entry referred to by the given
1192                entry_ref.
1194         This version of GuessMimeType() combines the features of the other
1195         versions: First the data of the given file are checked (sniffed). Only
1196         if the result of this operation is inconclusive, i.e.
1197         "application/octet-stream", the filename is examined for extensions.
1199         \param file Pointer to the entry_ref referring to the entry.
1200         \param type Pointer to a pre-allocated BMimeType which is set to the
1201                resulting MIME type.
1203         \returns A status code.
1204         \retval B_OK Everything went fine.
1205         \retval B_BAD_VALUE \c NULL \a ref or \a result.
1206         \retval B_NAME_NOT_FOUND \a ref refers to an abstract entry.
1207         \retval B_NO_INIT BMimeType was uninitialized.
1209         \since Haiku R1
1214         \fn status_t BMimeType::GuessMimeType(const void* buffer, int32 length,
1215                 BMimeType* type)
1216         \brief Guesses a MIME type for the supplied chunk of data.
1218         \param buffer Pointer to the data buffer.
1219         \param length Size of the buffer in bytes.
1220         \param type Pointer to a pre-allocated BMimeType which is set to the
1221                resulting MIME type.
1223         \returns A status code.
1224         \retval B_OK Everything went fine.
1225         \retval B_BAD_VALUE \c NULL \a buffer or \a result.
1226         \retval B_NO_INIT BMimeType was uninitialized.
1228         \since Haiku R1
1233         \fn status_t BMimeType::GuessMimeType(const char* filename, BMimeType* type)
1234         \brief Guesses a MIME type for the given filename.
1236         Only the filename itself is taken into consideration (in particular its
1237         name extension), not the entry it refers to. I.e. an entry with that name
1238         doesn't need to exist at all.
1240         \param filename The filename.
1241         \param type Pointer to a pre-allocated BMimeType which is set to the
1242                resulting MIME type.
1244         \returns A status code.
1245         \retval B_OK Everything went fine.
1246         \retval B_BAD_VALUE \c NULL \a ref or \a result.
1247         \retval B_NO_INIT BMimeType was uninitialized.
1249         \since Haiku R1
1254         \fn status_t BMimeType::StartWatching(BMessenger target)
1255         \brief Starts monitoring the MIME database for a given target.
1257         Until StopWatching() is called for the target, an update message is sent
1258         to it whenever the MIME database changes.
1260         \param target A BMessenger identifying the target for the update messages.
1262         \returns \c B_OK on success or another error code on failure.
1264         \since BeOS R4
1269         \fn status_t BMimeType::StopWatching(BMessenger target)
1270         \brief Stops monitoring the MIME database for a given target (previously
1271                started via StartWatching()).
1273         \param target A BMessenger identifying the target for the update messages.
1275         \returns \c B_OK on success or another error code on failure.
1277         \since BeOS R4
1282         \fn status_t BMimeType::SetType(const char* mimeType)
1283         \brief Initializes this object to the supplied MIME type.
1285         \deprecated This method has the same semantics as SetTo().
1286                     Use SetTo() instead.
1288         \since BeOS R3