The Storage Kit: BMimeType

Derived from: none

Declared in: be/storage/Mime.h

Library: libbe.so

Overview

The BMimeType class provides three services:

It can parse a MIME string. It can tell you whether the string is valid, what it's supertype component is, and whether it has a subtype component. (The MIME string format is described in "Valid MIME Strings."
It gives you access to the File Type database. Given a MIME type, it can look in the database and retrieve that type's icon(s), "preferred handler" application, the filename extensions that correspond to it, and so on.
It can regard a MIME string as an application signature, and so get and set the executable file, the file types, and the document icons that correspond to that signature.

All three services operate on MIME strings. In other words, they answer questions such as "Does this string have a supertype?", "Is this string installed in the database?", and so on. You can get the MIME strings from anywhere: from a file's file type attribute, from and application's signature, from the header of an e-mail message, you can even make them up.

Valid MIME Strings

A valid MIME string takes the form...

supertype/[subtype]

...where supertype is one of the seven "media" strings:

text
application
image
audio
video
multipart
message

...and (the optional) subtype can be just about anything...Except it can't include spaces or any of these forbidden characters:

/ \\ < > @ , ; : " ( ) [ ] ? =

When you initialize a BMimeType object (through the constructor or SetTo() function), you have to tell it what MIME string you want it to represent:

The string can be supertype-only, or it can be supertype/subtype.
Currently, the supertype is not restricted to the seven types listed above, but you're probably making a mistake if you make up a new, unrecognized supertype.
Neither the supertype nor the subtype can include any of the forbidden characters.
The entire string must be no longer than B_MIME_TYPE_LENGTH characters long. (That's about 240 characters. More than enough.)

You can check the validity of a MIME string without constructing a BMimeType object by calling the static IsValid() function:

   BMimeType::IsValid("text/qwerty");

Constructor and Destructor

BMimeType()

      BMimeType(void)
      BMimeType(const char *MIME_string)

Constructs a new BMimeType object and initializes its MIME type to a copy of MIME_string (if the argument is given). The rules of validity apply (see "Valid MIME Strings", above). To see if the initialization was successful, call InitCheck() after you construct a new BMimeType object.

You can also set the MIME type through the SetTo() function.

~MimeType()

      virtual ~MimeType()

Frees the object's MIME string and destroys the object.

Member Functions

Contains()

      bool Contains(const BMimeType *other) const

Compares the MIME string with other, returning true if they are identical. If the object is a supertype and it's the supertype of other, then the method returns true. Otherwise, it returns false.

Delete() see Install()

GetAppHint(), SetAppHint()

      status_t GetAppHint(entry_ref *app_ref) const

      status_t SetAppHint(const entry_ref *app_ref)

These functions get and set the "app hint" for the object's application signature. The app hint is an entry_ref that identifies the executable that should be used when launching an application that has this signature. For example, when the Tracker needs to launch an app of type "application/YourAppHere", it asks the database for the entry_ref hint. Of course, the entry_ref 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.

GetAppHint() function initializes the entry_ref to the hint recorded in the database; the argument must be allocated before it's passed in.

SetAppHint() copies the entry_ref into the database. app_ref should point to an executable file that has the same signature as this object's MIME type. Keep in mind that entry_refs aren't guaranteed to be persistent.

RETURN CODES

B_NO_ERROR. The ref was successfully retrieved or set.
B_NO_INIT. The BMimeType is uninitialized.
B_BAD_VALUE. (Set) The ref is uninitialized.

GetFileExtensions(), SetFileExtensions()

      status_t GetFileExtensions(BMessage *msg) const

      status_t SetFileExtensions(const BMessage *msg)

The database associates a list of file extensions (".xxx..." filename appendages) with each file type. If a file is otherwise untyped, clients of the database can figure out its type by matching the file's extension to the lists in the database.

These functions get and set the file extensions that are associated with the object's MIME type.

If you're getting the extensions, you'll find them copied into your BMessage's "extensions" field (the BMessage must be allocated). They're given as an indexed array of strings (B_STRING_TYPE).
Similarly, you pass in the extensions by adding strings to the message's "extensions" field.
The BMessage's what field is unimportant.

For example, to retrieve all the extensions that correspond to this object's MIME type, you would do the following:

   BMessage msg();
   uint32 i=0;
   char *ptr;
   
   if (mime.GetFileExtensions(&msg) != B_NO_ERROR)
      /* Handle the error. */
   
   while (true) {
      if (msg.FindString("extensions", i++, &ptr) != B_NO_ERROR)
         break;
      printf("> Extension:  %s\\n", ptr);
   }

A given extension can be associated with more than one MIME type.

A NULL msg to SetFileExtensions() clears the type's extension list.

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 SetFileExtensions().

RETURN CODES

B_NO_ERROR. The extensions were found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_NO_MEMORY. Insufficient memory to copy the extensions.

GetIcon(), SetIcon()

      status_t GetIcon(BBitmap *icon, icon_size which) const
      status_t SetIcon(const BBitmap *icon, icon_size which)

GetIcon() and SetIcon() get and set the icons that are associated (in the database) with this object's MIME type. You specify which icon you want (large or small) by passing B_LARGE_ICON or B_MINI_ICON as the which argument. The icon is passed in or returned through the icon argument. The icon data is copied out of or into the BBitmap object.

If you're setting the icon, the bitmap must be the proper size: 32x32 for the large icon, 16x16 for the small one. If you want to erase the node's icon, pass NULL as the icon argument to SetIcon().

RETURN CODES

B_NO_ERROR. The icon was found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_BAD_VALUE (Set... only). The bitmap wasn't the proper size.

GetIconForType(), SetIconForType()

      status_t GetIconForType(const char *file_type, BBitmap *icon, 
         icon_size which) const

      status_t SetIconForType(const char *file_type, const BBitmap *icon, icon_size which)

These functions get and set the icons that an application that has this object's MIME type as a signature uses to display the given file type. file_type must be a valid MIME string.

The icon is passed in or returned through the icon argument:

If you're getting the icon, the BBitmap must be allocated; the icon data is copied into your BBitmap object.
If you're setting the icon, the bitmap must be the proper size: 32x32 for the large icon, 16x16 for the small one. In BRect lingo, that's BRect(0, 0, 31, 31) and BRect(0, 0, 15, 15).
You can remove an icon by passing NULL as the icon argument to SetIconForType().

RETURN CODES

B_NO_ERROR. The icon was found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_BAD_VALUE. (Get) NULL BBitmap pointer, or file_type is invalid.
B_BAD_VALUE. (Set) The bitmap data isn't the proper size, or file_type is invalid.

GetInstalledTypes(), GetInstalledSupertypes()

      static status_t GetInstalledTypes(BMessage *types) 
      static status_t GetInstalledTypes(const char *supertype, BMessage *subtypes) 

      static status_t GetInstalledSupertypes(BMessage *supertypes)

These static functions retrieve all the file types that are currently installed in the database, all the installed subtypes for a given supertype, and all the installed supertypes. The types are copied into the "types" field of the passed-in BMessage (which must be allocated).

RETURN CODES

B_NO_ERROR. The types were found.
B_BAD_VALUE. The supertype string isn't valid.
B_NO_MEMORY. Insufficient memory to copy the types.

GetLongDescription(), SetLongDescription(), GetShortDescription(), SetShortDescription()

      status_t GetLongDescription(char *description) const
      status_t SetLongDescription(const char *description)

      status_t GetShortDescription(char *description) const
      status_t SetShortDescription(const char *description)

Each file type has a couple of human-readable description strings associated with it. Neither description string may be longer than B_MIME_TYPE_LENGTH characters.

These functions get and set the long and short description strings. The Get functions copy the string into the argument (which must be allocated). The Set functions copy the string that the argument points to.

RETURN CODES

B_NO_ERROR. The description was found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_BAD_VALUE. (Set) description is too long.
B_NO_MEMORY. Insufficient memory to copy the description.

GetPreferredApp(), SetPreferredApp()

      status_t GetPreferredApp(char *signature, app_verb verb = B_OPEN) const
      status_t SetPreferredApp(const char *signature, app_verb verb = B_OPEN)

These functions get and set the "preferred app" for this object's 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, the Tracker will ask the File Type database for the preferred app that's associated with the file's type.

The preferred app is identified by signature, a MIME string. A value of NULL indicates that there is no preferred app for the MIME type.
The app_verb argument specifies the type of access; currently, the only app_verb is B_OPEN.

RETURN CODES

B_NO_ERROR. The preferred app was found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_BAD_VALUE (Set... only). The signature argument is too long (greater than B_MIME_TYPE_LENGTH).

GetShortDescription() see GetLongDescription()

GetSupertype() see Type()

GetSupportingApps(), SetSupportingApps(), GetWildcardApps()

      status_t GetSupportingApps(BMessage *msg) const

      status_t SetSupportingApps(const BMessage *msg)

      static status_t GetWildcardApps(BMessage *msg)

These functions get and set the list of the MIME type's "supporting apps." These are the applications that know how to deal with the type (and its supertype, if appropriate). The apps are identified by their signatures.

If you're getting the apps, you'll find their signatures copied into your BMessage's "applications" field (the BMessage must be allocated). They're given as an indexed array of strings (B_STRING_TYPE). The applications that support the MIME subtype are stored first in the "applications" array, followed by those that only support its supertype. The number of applications that support the supertype is stored in "be:super" as an int32 and the number of applications that support the subtype is stored in "be:sub" as an int32. Applications supporting both the supertype and the subtype are stored only once. If the MIME type is a supertype, then the "be:super" field is omitted and the "applications" field is only filled with the signatures of the applications supporting the supertype.
Similarly, you pass in the signatures by adding strings to the message's "applications" field.
The BMessage's what field is unimportant.

For example, to retrieve all the application (signatures) that support this object's MIME type, you would do the following:

   BMessage msg();
   uint32 i=0;
   char *ptr;
   
   if (mime.GetSupportingApps(&msg) != B_NO_ERROR)
      /* Handle the error. */
   
   while (true) {
      if (msg.FindString("applications", i++, &ptr) != B_NO_ERROR)
         break;
      printf("> Supporting App:  %s\\n", ptr);
   }

A given application can be associated with more than one MIME type.

GetWildcardApps() returns, in the "applications" field, a list of the signatures of the applications that support all file types (MIME string "application/octet-stream").

A NULL msg to SetSupportingApps() clears the type's application signature list.

SetSupportingApps() clobbers the existing set of signatures. If you want to augment a type's signatures, you should retrieve the existing set, add the new ones, and then call SetSupportingApps().

RETURN CODES

B_NO_ERROR. The signatures were found or set.
B_NO_INIT. The BMimeType is uninitialized.
B_NO_MEMORY. Insufficient memory to copy the signatures.

GetWildcardApps() see GetSupportingApps()

InitCheck()

      status_t InitCheck(void) const

Returns the status of the most recent construction or SetTo() call.

RETURN CODES

See SetTo().

Install(), Delete(), IsInstalled()

      status_t Install(void)
      status_t Delete(void)
      bool IsInstalled(void) const

Install() adds the object's MIME type to the File Type database. Delete() removes the type from the database. IsInstalled() tells you if the type is currently installed.

None of these functions affect the object's copy of the MIME type; for instance, deleting a MIME type from the database doesn't uninitialize the object.

RETURN CODES

B_NO_ERROR. The type was successfully added or deleted.
B_BAD_VALUE. The object is uninitialized.

Currently, Install() may return a random value if the object is already installed. To avoid confusion, you should call IsInstalled() first:

   if (!mime.IsInstalled())
      mime.Install();

IsInstalled() see Install()

IsValid(), IsSupertypeOnly()

      static bool IsValid(const char *MIME_string)
      bool IsValid(void) const
      bool IsSupertypeOnly(void) const

The static IsValid() tests its argument for MIME validity. See "Valid MIME Strings" for the rules. The non-static version checks the validity of the object's MIME string.

IsSupertypeOnly() returns true if the object's MIME string doesn't include a subtype.

SetAppHint() see GetAppHint()

GetFileExtensions()

GetIcon()

GetIconForType()

GetLongDescription()

GetPreferredApp()

GetLongDescription()

GetSupportingApps()

SetTo(), Unset()

      status_t SetTo(const char *MIME_string)

      void Unset(void)

SetTo() initializes this BMimeType object to represent MIME_string. The object's previous MIME string is freed; the argument is then copied. The argument can be a full supertype/subtype string, or simply a supertype. In any case, it must pass the validity test described in Valid MIME Strings .

Unset() frees the object's current MIME string, and sets the object's status to B_NO_INIT.

RETURN CODES

These return codes are also returned by the InitCheck() function.

B_NO_ERROR. The initialization was successful.
B_NO_INIT. MIME_string is NULL or invalid.
B_NO_MEMORY. Not enough memory to allocate a copy of the argument.

See also: InitCheck()

Type(), GetSupertype()

      const char *Type(void) const
      status_t GetSupertype(BMimeType *super) const

Type() returns a pointer to the object's MIME string. If the object isn't initialized, this returns a pointer to NULL.

GetSupertype() initializes the argument with this object's supertype. (You can then call GetType() on the argument to see the supertype.) super must be allocated before it's passed in. If this object isn't initialized, super is uninitialized.

RETURN CODES

The errors apply to GetSupertype() only.

B_NO_ERROR. Everything's fine.
B_BAD_VALUE. This object isn't initialized.

SetTo()

Operators

== (comparison)

      BMimeType& operator==(const BMimeType &type)

Two MIME types are equal if they are both initialized to the same string (without regard to case).

The Be Book, in lovely HTML, for BeOS Release 3.

Last modified March 26, 1998.

Museum

The Storage Kit: BMimeType

GetAppHint(), SetAppHint()

GetFileExtensions(), SetFileExtensions()

GetIcon(), SetIcon()

GetIconForType(), SetIconForType()

GetInstalledTypes(), GetInstalledSupertypes()

GetLongDescription(), SetLongDescription(), GetShortDescription(), SetShortDescription()

GetPreferredApp(), SetPreferredApp()

GetSupportingApps(), SetSupportingApps(), GetWildcardApps()

Install(), Delete(), IsInstalled()

IsValid(), IsSupertypeOnly()

GetFileExtensions()

GetIcon()

GetIconForType()

GetLongDescription()

GetPreferredApp()

GetLongDescription()

GetSupportingApps()

SetTo(), Unset()

Type(), GetSupertype()

SetTo()

== (comparison)