xref: /haiku/docs/user/storage/MimeType.dox

/*
 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Ingo Weinhold, bonefish@users.sf.net
 *		Axel D��rfler, axeld@pinc-software.de
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/storage/MimeType.h  hrev47402
 *		src/kits/storage/MimeType.cpp  hrev47402
 */


/*!
	\file MimeType.h
	\ingroup storage
	\ingroup libbe
	\brief Provides the BMimeType class.
*/


/*!
	\class BMimeType
	\ingroup storage
	\ingroup libbe
	\brief A class that represents a MIME (Multi-purpose Internet Mail
	       Extensions) type string.

	MIME types use, has grown beyond describing the content of email
	to describe the content types of applications and file formats.

	MIME types consist of a supertype and a subtype.

	\since BeOS R3
*/


/*!
	\fn BMimeType::BMimeType()
	\brief Creates an uninitialized BMimeType object.

	\since BeOS R3
*/


/*!
	\fn BMimeType::BMimeType(const char* mimeType)
	\brief Creates a BMimeType object and initializes it to the supplied
	       MIME type.

	The supplied string must specify a valid MIME type or supertype.

	\param mimeType The MIME string.

	\sa SetTo() for further information.

	\since BeOS R3
*/


/*!
	\fn BMimeType::~BMimeType()
	\brief Frees all resources associated with this object.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetTo(const char* mimeType)
	\brief Initializes this object to the supplied MIME type.

	The supplied string must specify a valid MIME type or supertype.
	Valid MIME types are given by the following grammar:

	MIMEType	::= Supertype "/" [ Subtype ]
	Supertype	::= "application" | "audio" | "image" | "message"
					| "multipart" | "text" | "video"
	Subtype		::= MIMEChar MIMEChar*
	MIMEChar	::= any character except white spaces, CTLs and '/', '<', '>',
					'@',, ',', ';', ':', '"', '(', ')', '[', ']', '?', '=', '\'
					(Note: RFC1341 also forbits '.', but it is allowed here.)

	Currently the supertype is not restricted to one of the seven types given,
	but can be an arbitrary string (obeying the same rule as the subtype).
	Nevertheless it is a very bad idea to use another supertype.
	The supplied MIME string is copied; the caller retains the ownership.

	\param mimeType The MIME string.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE Invalid \a mimeType string.
	\retval B_NO_INIT BMimeType was uninitialized.
	\retval B_NO_MEMORY Insufficient memory to copy the MIME string.

	\since BeOS R3
*/


/*!
	\fn void BMimeType::Unset()
	\brief Returns the object to an uninitialized state.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::InitCheck() const
	\brief Returns the result of the most recent constructor or SetTo() call.

	\returns \c B_OK If the object is properly initialized, a specific
	         error code otherwise.

	\since BeOS R3
*/


/*!
	\fn const char* BMimeType::Type() const
	\brief Returns the MIME string represented by this object.

	\return The MIME string, if the object is properly initialized, \c NULL
	        otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::IsValid() const
	\brief Returns whether the object represents a valid MIME type.

	\return \c true, if the object is properly initialized, \c false
	        otherwise.

	\sa SetTo() for further information.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::IsSupertypeOnly() const
	\brief Returns whether this objects represents a supertype.

	\return \c true, if the object is properly initialized and represents a
	        supertype, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::IsInstalled() const
	\brief Returns whether or not this type is currently installed in the
	       MIME database.

	To add the MIME type to the database, call \c Install().
	To remove the MIME type from the database, call \c Delete().

	\return A \c bool indicating whether or not this type is currently
	        installed in the MIME database.
	\retval true The MIME type is currently installed in the database.
	\retval false The MIME type is not currently installed in the database.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetSupertype(BMimeType* supertype) const
	\brief Gets the \a supertype of the MIME type represented by this object.

	The supplied object is initialized to this object's \a supertype. If this
	BMimeType is not properly initialized, the supplied object will be Unset().

	\param supertype A pointer to the BMimeType object that shall be
	       initialized to this object's \a supertype.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \c NULL \a superType, this object is not initialized,
	        or this object is a supertype only.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::operator==(const BMimeType &type) const
	\brief Returns whether this and the supplied MIME type are equal.

	Two BMimeType objects are said to be equal if they represent the same
	MIME string, ignoring case, or if both are not initialized.

	\warning In BeOS R5 two uninitialized BMimeType objects were not
	         considered to be equal, in Haiku they are.

	\param type The BMimeType to be compared with.

	\return \c true, if the objects are equal, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::operator==(const char* type) const
	\brief Returns whether this and the supplied MIME type are equal.

	A BMimeType objects equals a MIME string, if its MIME string equals the
	latter one, ignoring case, or if it is uninitialized and the MIME string
	is \c NULL.

	\warning In BeOS R5 an uninitialized BMimeType object was not
	         considered to be equal to \c NULL, in Haiku it is.

	\param type The MIME string to be compared with.

	\return \c true, if the MIME types are equal, \c false otherwise.

	\since BeOS R4
*/


/*!
	\fn bool BMimeType::Contains(const BMimeType* type) const
	\brief Returns whether this MIME type is a supertype of or equals the
	supplied one.

	\param type The MIME type.

	\returns \c true, if this MIME type is a supertype of or equals the
	         supplied one, \c false otherwise.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::Install()
	\brief Adds the MIME type to the MIME database.

	To check if the MIME type is already installed, call \c IsInstalled().
	To remove the MIME type from the database, call \c Delete().

	\note The R5 implementation returns random values if the type is already
	installed, so be sure to check \c IsInstalled() first.

	\returns \c B_OK on success or another error code on failure.

	\see Delete()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::Delete()
	\brief Removes the MIME type from the MIME database.

	To check if the MIME type is already installed, call \c IsInstalled().
	To add the MIME type to the database, call \c Install().

	\note Calling \c BMimeType::Delete() does not uninitialize or otherwise
	      deallocate the \c BMimeType object; it simply removes the type from
	      the database.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetIcon(BBitmap* icon, icon_size size) const
	\brief Fetches the large or mini icon associated with the MIME type.

	The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
	must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
	icon. Additionally, the bitmap must be in the \c B_CMAP8 color space
	(8-bit color).

	\param icon Pointer to a pre-allocated \c BBitmap of proper size and
	       colorspace into which the icon is copied.
	\param size Value that specifies which icon to return.
	       Currently \c B_LARGE_ICON and \c B_MINI_ICON are supported.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
	        given type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetIcon(uint8** data, size_t* size) const
	\brief Fetches the vector icon associated with the MIME type
		The icon data is returned in \c data.

	\param data Pointer in which the allocated icon data is returned. You
	       need to delete the buffer when you are done with it.
	\param size Pointer in which the size of the allocated icon data is
	       returned.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_ENTRY_NOT_FOUND No icon of the given size found for the given
	        type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetPreferredApp(char* signature,
		app_verb verb) const
	\brief Fetches the signature of the preferred application from
	       the MIME database.

	The preferred app is the application that's used to access a file when,
	for example, the user double-clicks the file in a Tracker window. Unless
	the file identifies in its attributes a "custom" preferred app, Tracker
	will ask the file type database for the preferred app
	that's associated with the file's type.

	The string pointed to by \c signature must be long enough to
	hold the preferred applications signature; a length of
	\c B_MIME_TYPE_LENGTH is recommended.

	\param signature Pointer to a pre-allocated string into which the
	       signature of the preferred app is copied. If the function fails,
	       the contents of the string are undefined.
	\param verb \c app_verb value that specifies the type of access for
		which you are requesting the preferred app. Currently, the only
		supported app verb is \c B_OPEN.

	\returns A status code.
	\retval B_OK Success
	\retval B_ENTRY_NOT_FOUND No preferred app exists for the given type
	        and app_verb.
	\retval B_NO_INIT BMimeType was uninitialized.

	\see SetPreferredApp()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetAttrInfo(BMessage* info) const
	\brief Fetches from the MIME database a BMessage describing the attributes
	       typically associated with files of the given MIME type.

	The attribute information is returned in a pre-allocated BMessage pointed
	to by the \c info parameter (note that the any prior contents of the
	message will be destroyed). If the method succeeds, the format of the
	BMessage pointed to by \c info will be the following:

	<table>
		<tr>
			<td><b>field name</b></td>
			<td><b>type</b></td>
			<td><b>element[0..n]</b></td>
		</tr>
		<tr>
			<td> "attr:name"</td>
			<td> \c B_STRING_TYPE </td>
			<td> The name of each attribute </td>
		</tr>
		<tr>
			<td> "attr:public_name"</td>
			<td> \c B_STRING_TYPE </td>
			<td> The human-readable name of each attribute </td>
		</tr>
		<tr>
			<td> "attr:type"</td>
			<td> \c B_INT32_TYPE </td>
			<td> The type code for each attribute </td>
		</tr>
		<tr>
			<td> "attr:viewable"</td>
			<td> \c B_BOOL_TYPE </td>
			<td> For each attribute: \c true if the attribute is public,
				\c false if it's private </td>
		</tr>
		<tr>
			<td> "attr:editable"</td>
			<td> \c B_BOOL_TYPE </td>
			<td> For each attribute: \c true if the attribute should be user
				editable, \c false if not </td>
		</tr>
	</table>

	The \c BMessage::what value is set to decimal \c 233, but is otherwise
	meaningless.

	\param info Pointer to a pre-allocated BMessage into which information about
	       the MIME type's associated file attributes is stored.

	\returns \c B_OK on success or another error code on failure.

	\see SetAttrInfo()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetFileExtensions(BMessage* extensions) const
	\brief Fetches the MIME type's associated filename extensions from the
		MIME database.

	The MIME database associates a list of filename extensions (a character
	string following the rightmost dot, \c ".", character in the filename)
	with each type. These extensions can then be used to help determine the
	type of any untyped files that may be encountered.

	The list of extensions is returned in a pre-allocated BMessage pointed
	to by the \c extensions parameter (note that the any prior contents of
	the message will be destroyed). If the method succeeds, the format of
	the BMessage pointed to by \c extensions will be the following:

	- The message's \c "extensions" field will contain an indexed array
	  of strings, one for each extension. The extensions are given
	  without the preceding \c "." character by convention.
	- The message's \c "type" field will be a string containing the
	  MIME type whose associated file extensions you are fetching.
	- The \c what member of the BMessage will be set to \c 234, but
	  is otherwise irrelevant.

	Note that any other fields present in the BMessage passed to the most
	recent \c SetFileExtensions() call will also be returned.

	\param extensions Pointer to a pre-allocated BMessage into which the
	       MIME type's associated file extensions will be stored.

	\returns \c B_OK on success or another error code on failure.

	\see SetFileExtensions()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetShortDescription(char* description) const
	\brief Fetches the MIME type's short description from the MIME database.

	The string pointed to by \c description must be long enough to
	hold the short description; a length of \c B_MIME_TYPE_LENGTH is
	recommended.

	\param description Pointer to a pre-allocated string into which the long
	       description is copied. If the function fails, the contents of the
	       string are undefined.

	\returns A status code.
	\retval B_OK Success
	\retval B_ENTRY_NOT_FOUND No short description exists for the given type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\see SetShortDescription()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetLongDescription(char* description) const
	\brief Fetches the MIME type's long description from the MIME database.

	The string pointed to by \c description must be long enough to
	hold the long description; a length of \c B_MIME_TYPE_LENGTH is
	recommended.

	\param description Pointer to a pre-allocated string into which the
	       long description is copied. If the function fails, the contents
	       of the string are undefined.

	\returns A status code.
	\retval B_OK Success
	\retval B_ENTRY_NOT_FOUND No long description exists for the given type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\see SetLongDescription()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetSupportingApps(BMessage* signatures) const
	\brief Fetches a \c BMessage containing a list of MIME signatures of
	       applications that are able to handle files of this MIME type.

	If successful, the BMessage containing the MIME signatures will be of
	the following format:

	<table>
		<tr>
			<td><b>field name</b></td>
			<td><b>type</b></td>
			<td><b>contains</b></td>
		</tr>
		<tr>
			<td> "applications"</td>
			<td> \c B_STRING_TYPE[] </td>
			<td>
				An array of MIME signatures. The first <i> n </i> signatures
				(where <i> n </i> is the value in the \c "be:sub" field of the
				message) are able to handle the full type (supertype
				<i> and </i> subtype). The remaining signatures are of
				applications that handle the supertype only.
			</td>
		</tr>
		<tr>
			<td> "be:sub"</td>
			<td> \c B_INT32_TYPE </td>
			<td>
				The number of applications in the \c "applications" array that
				can handle the object's full MIME type. These applications are
				listed first in the array. This field is omitted if the object
				represents a supertype only.
			</td>
		</tr>
		<tr>
			<td> "be:super"</td>
			<td> \c B_INT32_TYPE </td>
			<td>
				The number of applications in the "applications" array that can
				handle the object's supertype (not counting those that can
				handle the full type).
				These applications are listed after the full-MIME-type
				supporters. By definition, the \c GetWildcardApps() function
				never returns supertype-only apps.
			</td>
		</tr>
	</table>

	The \c BMessage::what value is meaningless and should be ignored.

	\param signatures Pointer to a pre-allocated BMessage into which the
	       signatures of the supporting applications will be copied.

	\returns \c B_OK on success or an error code on failure.

	\see SetSupportingApps()

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetIcon(const BBitmap* icon, icon_size which)
	\brief Sets the large or mini icon for the MIME type.

	The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
	must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
	icon. Additionally, the bitmap must be in the \c B_CMAP8 color space (8-bit
	color).

	If you want to erase the current icon, pass \c NULL as the \c icon argument.

	\param icon Pointer to a pre-allocated \c BBitmap of proper size and
	       colorspace containing the new icon, or \c NULL to clear the current
	       icon.
	\param which Value that specifies which icon to update. Currently
	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetIcon(const uint8* data, size_t size)
	\brief Sets the vector icon for the MIME type

	The icon is copied from the provided \a data which must contain
	\a size bytes.

	If you want to erase the current icon, pass \c NULL as the \a data argument.

	\param data Pointer to a buffer containing the new icon, or \c NULL to clear
	       the current icon.
	\param size Size of the provided buffer.

	\returns \c B_OK on success or another error code on failure.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::SetPreferredApp(const char* signature,
		app_verb verb)
	\brief Sets the preferred application for the MIME type.

	The preferred app is the application that's used to access a file when,
	for example, the user double-clicks the file in a Tracker window. Unless
	the file identifies in its attributes a "custom" preferred app, Tracker
	will ask the file type database for the preferred app that's associated
	with the file's type.

	The string pointed to by \c signature must be of length less than
	\c B_MIME_TYPE_LENGTH characters.

	\note If the MIME type is not installed, it will first be installed,
	and then the preferred app will be set.

	\param signature Pointer to a pre-allocated string containing the
	       signature of the new preferred app.
	\param verb \c app_verb value that specifies the type of access for
	       which you are setting the preferred app. Currently, the only
	       supported app verb is \c B_OPEN.

	\returns \c B_OK on success or another error code on failure.*/

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetAttrInfo(const BMessage* info)
	\brief Sets the description of the attributes typically associated
		with files of the given MIME type

	The attribute information is technically arbitrary, but the expected
	format of the BMessage pointed to by the \c info parameter is as follows:

	<table>
		<tr>
			<td><b>field name</b></td>
			<td><b>type</b></td>
			<td><b>element[0..n]</b></td>
		</tr>
		<tr>
			<td> "attr:name"</td>
			<td> \c B_STRING_TYPE </td>
			<td> The name of each attribute </td>
		</tr>
		<tr>
			<td> "attr:public_name"</td>
			<td> \c B_STRING_TYPE </td>
			<td> The human-readable name of each attribute </td>
		</tr>
		<tr>
			<td> "attr:type"</td>
			<td> \c B_INT32_TYPE </td>
			<td> The type code for each attribute </td>
		</tr>
		<tr>
			<td> "attr:viewable"</td>
			<td> \c B_BOOL_TYPE </td>
			<td> For each attribute: \c true if the attribute is public,
				\c false if it's private </td>
		</tr>
		<tr>
			<td> "attr:editable"</td>
			<td> \c B_BOOL_TYPE </td>
			<td> For each attribute: \c true if the attribute should be
				user editable, \c false if not </td>
		</tr>
	</table>

	The \c BMessage::what value is ignored.

	\param info Pointer to a pre-allocated and properly formatted BMessage
	       containing information about the file attributes typically
	       associated with the MIME type.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetFileExtensions(const BMessage* extensions)
	\brief Sets the list of filename extensions associated with the MIME type.

	The MIME database associates a list of filename extensions (a character
	string following the rightmost dot, \c ".", character in the filename)
	with each type. These extensions can then be used to help determine the
	type of any untyped files that may be encountered.

	The list of extensions is given in a pre-allocated BMessage pointed to by
	the \c extensions parameter. The format of the message should be as follows:
	- The message's \c "extensions" field should contain an indexed array of
	  strings, one for each extension. The extensions are to be given
	  without the preceding \c "." character (i.e. \c "html" or \c "mp3",
	  not \c ".html" or \c ".mp3" ).
	- The \c what member of the BMessage is ignored.

	\note Any other fields present in the \c BMessage will currently be
	      retained and returned by calls to \c GetFileExtensions(); however,
	      this may change in the future, so it is recommended that you not rely
	      on this behavior, and that no other fields be present. Also, note that
	      no checking is performed to verify the \c BMessage is properly
	      formatted; it's up to you to do things right.

	Finally, bear in mind that \c SetFileExtensions() clobbers the existing set
	of extensions. If you want to augment a type's extensions, you should
	retrieve the existing set, add the new ones, and then call
	\c SetFileExtensions().

	\param extensions Pointer to a pre-allocated, properly formatted BMessage
	       containing the new list of file extensions to associate with this
	       MIME type.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetShortDescription(const char* description)
	\brief Sets the short description field for the MIME type.

	The string pointed to by \c description must be of length less than
	\c B_MIME_TYPE_LENGTH characters.

	\note If the MIME type is not installed, it will first be installed,
	and then the short description will be set.

	\param description Pointer to a pre-allocated string containing the
	       new short description.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetLongDescription(const char* description)
	\brief Sets the long description field for the MIME type.

	The string pointed to by \c description must be of length less than
	\c B_MIME_TYPE_LENGTH characters.

	\note If the MIME type is not installed, it will first be installed,
	and then the long description will be set.

	\param description Pointer to a pre-allocated string containing the new
	       long description

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes)
	\brief Fetches a BMessage listing all the MIME \a supertypes currently
	       installed in the MIME database.

	The types are copied into the \c "super_types" field of the passed-in
	\c BMessage. The \c BMessage must be pre-allocated.

	\param supertypes Pointer to a pre-allocated \c BMessage into which the
	       MIME \a supertypes will be copied.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetInstalledTypes(BMessage* types)
	\brief Fetches a BMessage listing all the MIME types currently installed
	in the MIME database.

	The types are copied into the \c "types" field of the passed-in \c BMessage.
	The \c BMessage must be pre-allocated.

	\param types Pointer to a pre-allocated \c BMessage into which the
	       MIME types will be copied.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetInstalledTypes(const char* supertype,
		BMessage* types)
	\brief Fetches a BMessage listing all the MIME subtypes of the given
	       \a supertype currently installed in the MIME database.

	The types are copied into the \c "types" field of the passed-in
	\c BMessage. The \c BMessage must be pre-allocated.

	\param supertype Pointer to a string containing the MIME \a supertype whose
	       subtypes you wish to retrieve.
	\param types Pointer to a pre-allocated \c BMessage into which the
	       appropriate MIME subtypes will be copied.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetWildcardApps(BMessage* wild_ones)
	\brief Fetches a \c BMessage containing a list of MIME signatures of
	       applications that are able to handle files of any type.

	This function is the same as calling \c GetSupportingApps() on a
	\c BMimeType object initialized to a MIME type of]
	\c "application/octet-stream".

	\param wild_ones Pointer to a pre-allocated BMessage into which
	       signatures of applications supporting files of any type
	       are copied.

	\returns \c B_OK on success or another error code on failure.

	\sa GetSupportingApps() for details on the format of the data returned in
	    the \c BMessage pointed to by \c wild_ones.

	\since BeOS R3
*/


/*!
	\fn bool BMimeType::IsValid(const char* string)
	\brief Returns whether the given string represents a valid MIME type.

	\param string The MIME type string.

	\return \c true, if the given string represents a valid MIME type.

	\sa SetTo() for further information.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetAppHint(entry_ref* ref) const
	\brief Fetches an \c entry_ref that serves as a hint as to where the MIME
	       type's preferred application might live

	The app hint is a path that identifies the executable that should be used
	when launching an application that has this signature. For example, when
	Tracker needs to launch an app of type \c "application/YourAppHere",
	it asks the database for the application hint. This hint is converted to an
	\c entry_ref before it is passed to the caller. Of course, the path may not
	point to an application, or it might point to an application
	with the wrong signature (and so on); that's why this is merely a hint.

	The \c entry_ref pointed to by \c ref must be pre-allocated.

	\param ref Pointer to a pre-allocated \c entry_ref into which the location
	       of the app hint is copied. If the function fails, the contents of
	       the \c entry_ref are undefined.

	\return A status code, B_OK on success or an error code otherwise.
	\retval B_OK The ref was retrieved successfully.
	\retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetAppHint(const entry_ref* ref)
	\brief Sets the app hint field for the MIME type

	The app hint is a path that identifies the executable that should be used
	when launching an application that has this signature. For example, when
	Tracker needs to launch an app of type \c "application/YourAppHere",
	it asks the database for the application hint. This hint is converted to an
	\c entry_ref before it is passed to the caller. Of course, the path may not
	point to an application, or it might point to an application with the wrong
	signature (and so on); that's why this is merely a hint.

	The \c entry_ref pointed to by \c ref must be pre-allocated. It must be a
	valid \c entry_ref (i.e. <code>entry_ref(-1, -1, "some_file")</code> will
	trigger an error), but it need not point to an existing file, nor need
	it actually point to an application. That's not to say that it shouldn't;
	such an \c entry_ref would render the app hint useless.

	\param ref Pointer to a pre-allocated \c entry_ref containting the location
	       of the new app hint

	\returns \c B_OK on success or another error code on failure.
	\retval B_OK The ref was retrieved successfully.
	\retval B_NO_INIT BMimeType was uninitialized.
	\retval B_BAD_VALUE \a ref was \c NULL.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetIconForType(const char* type, BBitmap* icon,
		icon_size which) const
	\brief Fetches the large or mini icon used by an application of this type
	       for files of the given type.

	This can be confusing, so here's how this function is intended to be used:
	- The actual \c BMimeType object should be set to the MIME signature
	  of an application for whom you want to look up custom icons for
	  custom MIME types.
	- The \c type parameter specifies the file type whose custom icon you
	  are fetching.

	The type of the \c BMimeType object is not required to actually be a
	subtype of \c "application/"; that is the intended use however, and calling
	\c GetIconForType() on a non-application type will likely return
	\c B_ENTRY_NOT_FOUND.

	The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap
	must be the proper size: \c 32x32 for the large icon, \c 16x16 for the
	mini icon. Additionally, the bitmap must be in the \c B_CMAP8 color space
	(8-bit color).

	\param type Pointer to a pre-allocated string containing the MIME type
	       whose custom icon you wish to fetch.
	\param icon Pointer to a pre-allocated \c BBitmap of proper size and
	       colorspace into which the icon is copied.
	\param which Value that specifies which icon to return. Currently
	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.

	\returns A status code, \c B_OK on success or an error code otherwise.
	\retval B_OK Success
	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
	        given type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::GetIconForType(const char* type,
		uint8** _data, size_t* _size) const
	\brief Fetches the vector icon used by an application of this type for
	       files of the given type.

	The icon data is returned in \c data.
	See the other GetIconForType() for more information.

	\param type Pointer to a pre-allocated string containing the MIME type whose
	       custom icon you wish to fetch.
	\param _data Pointer in which the allocated icon data is returned. You need
	       to delete the buffer when you are done with it.
	\param _size Pointer in which the size of the allocated icon data is
	       filled out.

	\returns A status code, \c B_OK on success or an error code otherwise.
	\retval B_OK Success.
	\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
	        given type.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::SetIconForType(const char* type,
		const BBitmap* icon, icon_size which)
	\brief Sets the large or mini icon used by an application of this type
	       for files of the given \a type.

	This can be confusing, so here's how this function is intended to be used:
	- The actual \c BMimeType object should be set to the MIME signature of an
	  application to whom you want to assign custom icons for custom MIME types.
	- The \c type parameter specifies the file type whose custom icon you are
	  setting.

	The type of the \c BMimeType object is not required to actually be a subtype
	of \c "application/"; that is the intended use however, and
	application-specific icons are not expected to be present for
	non-application types.

	The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
	must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
	icon.

	If you want to erase the current icon, pass \c NULL as the \c icon argument.

	\param type Pointer to a pre-allocated string containing the MIME type whose
	       custom icon you wish to set.
	\param icon Pointer to a pre-allocated \c BBitmap of proper size and
	       colorspace containing the new icon, or \c NULL to clear the current
	       icon.
	\param which Value that specifies which icon to update. Currently
	       \c B_LARGE_ICON and \c B_MINI_ICON are supported.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R3
*/


/*!
	\fn status_t BMimeType::SetIconForType(const char* type, const uint8* data,
		size_t dataSize)
	\brief Sets the icon used by an application of this type for files of the
	       given \a type.

	This can be confusing, so here's how this function is intended to be used:
	- The actual \c BMimeType object should be set to the MIME signature of an
	  application to whom you want to assign custom icons for custom MIME types.
	- The \c type parameter specifies the file type whose custom icon you are
	  setting.

	The type of the \c BMimeType object is not required to actually be a subtype
	of \c "application/"; that is the intended use however, and
	application-specific icons are not expected to be present for
	non-application types.

	The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap
	must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini
	icon.

	If you want to erase the current icon, pass \c NULL as the \c icon argument.

	\param type Pointer to a pre-allocated string containing the MIME type whose
	       custom icon you wish to set.
	\param data Pointer to a pre-allocated uint8 array of the proper size to
	       contain the new icon, or \c NULL to clear the current icon.
	\param dataSize The size of \a data in bytes.

	\returns \c B_OK on success or another error code on failure.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::GetSnifferRule(BString* result) const
	\brief Retrieves the MIME type's sniffer rule.

	\param result Pointer to a pre-allocated BString into which the value is
	       copied.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType.
	\retval B_ENTRY_NOT_FOUND The MIME type is not installed.
	\retval B_NO_INIT BMimeType was uninitialized.

	\see SetSnifferRule()

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::SetSnifferRule(const char* rule)
	\brief Sets the MIME type's sniffer rule.

	If the supplied \a rule is \c NULL, the MIME type's sniffer rule is
	unset.

	SetSnifferRule() does also return \c B_OK, if the type is not installed,
	but the call will have no effect in this case.

	\param rule The rule string, may be \c NULL.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE Uninitialized BMimeType.
	\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid.
	\retval B_NO_INIT BMimeType was uninitialized.

	\sa CheckSnifferRule()

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::CheckSnifferRule(const char* rule,
		BString* parseError)
	\brief Checks whether a MIME sniffer rule is valid or not.

	A MIME sniffer rule is valid, if it is well-formed with respect to the
	following grammar and fulfills some further conditions listed thereafter:

\verbatim
	Rule			::= LWS Priority LWS ExprList LWS
	ExprList		::= Expression (LWS Expression)*
	Expression		::= "(" LWS (PatternList | RPatternList) LWS ")"
						| Range LWS "(" LWS PatternList LWS ")"
	RPatternList	::= RPattern (LWS "|" LWS RPattern)*
	PatternList		::= Pattern (LWS "|" LWS Pattern)*
	RPattern		::= Range LWS Pattern
	Pattern			::= PString [ LWS "&" LWS Mask ]
	Range			::=	"[" LWS SDecimal [LWS ":" LWS SDecimal] LWS "]"

	Priority		::= Float
	Mask			::= PString
	PString			::= HexString | QuotedString | Octal [UnquotedString]
						EscapedChar [UnquotedString]
	HexString		::= "0x" HexPair HexPair*
	HexPair			::= HexChar HexChar
	QuotedString	::= '"' QChar QChar* '"' | "'" QChar QChar* "'"
	Octal			::= "\" OctChar [OctChar [OctChar]]
	SDecimal		::= ["+" | "-"] Decimal
	Decimal			::= DecChar DecChar*
	Float			::= Fixed [("E" | "e") Decimal]
	Fixed			::= SDecimal ["." [Decimal]] | [SDecimal] "." Decimal
	UnquotedString	::= UChar UChar*
	LWS				::= LWSChar*

	LWSChar			::= LF | " " | TAB
	OctChar			::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
	DecChar			::= OctChar | "8" | "9"
	HexChar			::= DecChar | "a" | "b" | "c" | "d" | "e" | "A" | "B" | "C"
						| "D" | "E"
	Char			:: <any character>
	QChar			::= <Char except "\", "&", "'" and '"'> | EscapedChar
	EscapedChar		::= "\" Char
	UChar			::= <QChar except LWSChar>

	Conditions:
	(checked)
	- If a mask is specified for a pattern, this mask must have the same
	  length as the pattern string.
	(not checked)
	- 0 <= Priority <= 1
	- 0 <= Range begin <= Range end
	- Rules of the form "() | () | ..." are invalid.

	Examples:
	- 1.0 ('ABCD')
	  The file must start with the string "ABCD". The priority of the rule
	  is 1.0 (maximal).
	- 0.8 [0:3] ('ABCD' | 'abcd')
	  The file must contain the string "ABCD" or "abcd" starting somewhere in
	  the first four bytes. The rule priority is 0.8.
	- 0.5 ([0:3] 'ABCD' | [0:3] 'abcd' | [13] 'EFGH')
	  The file must contain the string "ABCD" or "abcd" starting somewhere in
	  the first four bytes or the string "EFGH" at position 13. The rule
	  priority is 0.5.
	- 0.8 [0:3] ('ABCD' & 0xff00ffff | 'abcd' & 0xffff00ff)
	  The file must contain the string "A.CD" or "ab.d" (whereas "." is an
	  arbitrary character) starting somewhere in the first four bytes. The
	  rule priority is 0.8.

	Real examples:
	- 0.20 ([0]"//" | [0]"/\*" | [0:32]"#include" | [0:32]"#ifndef"
	        | [0:32]"#ifdef")
	  text/x-source-code
	- 0.70 ("8BPS  \000\000\000\000" & 0xffffffff0000ffffffff )
	  image/x-photoshop
\endverbatim

	\param rule The rule string.
	\param parseError A pointer to a pre-allocated BString into which a
	       description of the parse error is written (if any), may be \c NULL.

	\returns A status code.
	\retval B_OK The supplied sniffer rule is valid.
	\retval B_BAD_VALUE \c NULL \a rule.
	\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A
	        description of the error is written to \a parseError, if supplied.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::GuessMimeType(const entry_ref* file,
		BMimeType* type)
	\brief Guesses a MIME type for the entry referred to by the given
	       entry_ref.

	This version of GuessMimeType() combines the features of the other
	versions: First the data of the given file are checked (sniffed). Only
	if the result of this operation is inconclusive, i.e.
	"application/octet-stream", the filename is examined for extensions.

	\param file Pointer to the entry_ref referring to the entry.
	\param type Pointer to a pre-allocated BMimeType which is set to the
	       resulting MIME type.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \c NULL \a ref or \a result.
	\retval B_NAME_NOT_FOUND \a ref refers to an abstract entry.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::GuessMimeType(const void* buffer, int32 length,
		BMimeType* type)
	\brief Guesses a MIME type for the supplied chunk of data.

	\param buffer Pointer to the data buffer.
	\param length Size of the buffer in bytes.
	\param type Pointer to a pre-allocated BMimeType which is set to the
	       resulting MIME type.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \c NULL \a buffer or \a result.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::GuessMimeType(const char* filename, BMimeType* type)
	\brief Guesses a MIME type for the given filename.

	Only the filename itself is taken into consideration (in particular its
	name extension), not the entry it refers to. I.e. an entry with that name
	doesn't need to exist at all.

	\param filename The filename.
	\param type Pointer to a pre-allocated BMimeType which is set to the
	       resulting MIME type.

	\returns A status code.
	\retval B_OK Everything went fine.
	\retval B_BAD_VALUE \c NULL \a ref or \a result.
	\retval B_NO_INIT BMimeType was uninitialized.

	\since Haiku R1
*/


/*!
	\fn status_t BMimeType::StartWatching(BMessenger target)
	\brief Starts monitoring the MIME database for a given target.

	Until StopWatching() is called for the target, an update message is sent
	to it whenever the MIME database changes.

	\param target A BMessenger identifying the target for the update messages.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R4
*/


/*!
	\fn status_t BMimeType::StopWatching(BMessenger target)
	\brief Stops monitoring the MIME database for a given target (previously
	       started via StartWatching()).

	\param target A BMessenger identifying the target for the update messages.

	\returns \c B_OK on success or another error code on failure.

	\since BeOS R4
*/


/*!
	\fn status_t BMimeType::SetType(const char* mimeType)
	\brief Initializes this object to the supplied MIME type.

	\deprecated This method has the same semantics as SetTo().
	            Use SetTo() instead.

	\since BeOS R3
*/