2 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
6 * Ingo Weinhold, bonefish@users.sf.net
7 * Axel Dörfler, axeld@pinc-software.de
8 * John Scipione, jscipione@gmail.com
11 * headers/os/storage/MimeType.h hrev47402
12 * src/kits/storage/MimeType.cpp hrev47402
20 \brief Provides the BMimeType class.
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.
41 \fn BMimeType::BMimeType()
42 \brief Creates an uninitialized BMimeType object.
49 \fn BMimeType::BMimeType(const char* mimeType)
50 \brief Creates a BMimeType object and initializes it to the supplied
53 The supplied string must specify a valid MIME type or supertype.
55 \param mimeType The MIME string.
57 \sa SetTo() for further information.
64 \fn BMimeType::~BMimeType()
65 \brief Frees all resources associated with this object.
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.
104 \fn void BMimeType::Unset()
105 \brief Returns the object to an uninitialized state.
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.
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
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
140 \sa SetTo() for further information.
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.
158 \fn bool BMimeType::IsInstalled() const
159 \brief Returns whether or not this type is currently installed in the
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.
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.
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.
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
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.
232 \fn bool BMimeType::Contains(const BMimeType* type) const
233 \brief Returns whether this MIME type is a supertype of or equals the
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.
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.
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
274 \returns \c B_OK on success or another error code on failure.
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
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
298 \retval B_NO_INIT BMimeType was uninitialized.
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
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
318 \retval B_NO_INIT BMimeType was uninitialized.
325 \fn status_t BMimeType::GetPreferredApp(char* signature,
327 \brief Fetches the signature of the preferred application from
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.
349 \retval B_ENTRY_NOT_FOUND No preferred app exists for the given type
351 \retval B_NO_INIT BMimeType was uninitialized.
353 \see SetPreferredApp()
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:
371 <td><b>field name</b></td>
373 <td><b>element[0..n]</b></td>
376 <td> "attr:name"</td>
377 <td> \c B_STRING_TYPE </td>
378 <td> The name of each attribute </td>
381 <td> "attr:public_name"</td>
382 <td> \c B_STRING_TYPE </td>
383 <td> The human-readable name of each attribute </td>
386 <td> "attr:type"</td>
387 <td> \c B_INT32_TYPE </td>
388 <td> The type code for each attribute </td>
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>
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>
404 The \c BMessage::what value is set to decimal \c 233, but is otherwise
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.
419 \fn status_t BMimeType::GetFileExtensions(BMessage* extensions) const
420 \brief Fetches the MIME type's associated filename extensions from the
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()
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
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.
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()
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
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.
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()
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:
511 <td><b>field name</b></td>
513 <td><b>contains</b></td>
516 <td> "applications"</td>
517 <td> \c B_STRING_TYPE[] </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.
528 <td> \c B_INT32_TYPE </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.
538 <td> \c B_INT32_TYPE </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.
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()
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
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
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.
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
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
597 \param size Size of the provided buffer.
599 \returns \c B_OK on success or another error code on failure.
606 \fn status_t BMimeType::SetPreferredApp(const char* signature,
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.*/
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:
644 <td><b>field name</b></td>
646 <td><b>element[0..n]</b></td>
649 <td> "attr:name"</td>
650 <td> \c B_STRING_TYPE </td>
651 <td> The name of each attribute </td>
654 <td> "attr:public_name"</td>
655 <td> \c B_STRING_TYPE </td>
656 <td> The human-readable name of each attribute </td>
659 <td> "attr:type"</td>
660 <td> \c B_INT32_TYPE </td>
661 <td> The type code for each attribute </td>
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>
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>
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.
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
722 \returns \c B_OK on success or another error code on failure.
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.
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
760 \returns \c B_OK on success or another error code on failure.
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.
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.
801 \fn status_t BMimeType::GetInstalledTypes(const char* supertype,
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.
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
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.
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.
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.
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
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.
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
925 - The \c type parameter specifies the file type whose custom icon you
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
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.
947 \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
949 \retval B_NO_INIT BMimeType was uninitialized.
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
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
975 \retval B_NO_INIT BMimeType was uninitialized.
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
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
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
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.
1019 \fn status_t BMimeType::SetIconForType(const char* type, const uint8* data,
1021 \brief Sets the icon used by an application of this type for files of the
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
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
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.
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
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()
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
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()
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:
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 "]"
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*
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"
1135 Char :: <any character>
1136 QChar ::= <Char except "\", "&", "'" and '"'> | EscapedChar
1137 EscapedChar ::= "\" Char
1138 UChar ::= <QChar except LWSChar>
1142 - If a mask is specified for a pattern, this mask must have the same
1143 length as the pattern string.
1145 - 0 <= Priority <= 1
1146 - 0 <= Range begin <= Range end
1147 - Rules of the form "() | () | ..." are invalid.
1151 The file must start with the string "ABCD". The priority of the rule
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
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.
1166 - 0.20 ([0]"//" | [0]"/\*" | [0:32]"#include" | [0:32]"#ifndef"
1169 - 0.70 ("8BPS \000\000\000\000" & 0xffffffff0000ffffffff )
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.
1189 \fn status_t BMimeType::GuessMimeType(const entry_ref* file,
1191 \brief Guesses a MIME type for the entry referred to by the given
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.
1214 \fn status_t BMimeType::GuessMimeType(const void* buffer, int32 length,
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.
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.
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.
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.
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.