The Storage Kit: BMimeType

The Storage Kit Table of Contents | The Storage Kit Index

# BMimeType

Derived from: none

Declared in: be/storage/Mime.h

Library: libbe.so

###### Summary

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.

### ~BMimeType()

virtual `~BMimeType() `

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 a path 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 application hint. This hint is converted to an `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.

`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 path corresponding to 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.

RETURN CODES

`B_OK`. The ref was successfully retrieved or set.

- `B_NO_INIT`. The BMimeType is uninitialized.

- `B_BAD_VALUE`. (Set) The ref is uninitialized.

See also: `BNodeInfo::GetAppHint()`

### GetAttrInfo() , SetAttrInfo()

status_t `GetAttrInfo(` BMessage *info`)` const
status_t `SetAttrInfo(` BMessage *info`) `

These functions use a BMessage to get and set the list of attributes that are typically associated with files of the MIME type. The BMessage must have the following fields:

Field Name | Type | element[0..n]
--- | --- | ---
"attr:name" | `B_STRING_TYPE` | Each element is the name of one attribute.
"attr:public_name" | `B_STRING_TYPE` | Each element is the human-readable name of one attribute.
"attr:type" | `B_INT32_TYPE` | Each element is the type code for the corresponding attribute.
"attr:public" | `B_BOOL_TYPE` | `true` if the attribute is public, `false` if it's private.
"attr:editable" | `B_BOOL_TYPE` | `true` if the attribute should be user-editable, `false` if not.

You can actually have any fields you want; it's up to applications to determine which attributes they recognize and which they don't.

Each element in each field describes the next attribute. If a file has three attributes, there should be three elements in each field, one per attribute.

RETURN CODES

- `B_OK`. No error.

- `B_BAD_VALUE`. Invalid file.

### 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_OK)
          /* Handle the error. */

       while (true) {
          if (msg.FindString("extensions", i++, &ptr) != B_OK)
             break;
          printf("> Extension:  %sn", 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()`.

Also, there's no way to ask the database to give you a set of file types that map to a given extension. To find a type for an extension, you have to get all the installed types with `GetInstalledTypes()` and ask each one for its set of extensions.

RETURN CODES

- `B_OK`. 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.

The bitmap (if you're calling `SetIcon()`) or icon (if you're calling `GetIcon()`) must be the proper size: 32x32 for the large icon, 16x16 for the small one. Additionally, the bitmap must be in the `B_CMAP8` color space (8-bit color), or the application will crash.

If you want to erase the node's icon, pass `NULL` as the icon argument to `SetIcon()`.

RETURN CODES

- `B_OK`. The icon was found or set.

- `B_NO_INIT`. The BMimeType is uninitialized.

- `B_BAD_VALUE`. The bitmap or icon 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).

- If you're setting the icon, the bitmap must be in the `B_CMAP8` color space (8-bit color), or the application will crash.

- You can remove an icon by passing `NULL` as the icon argument to `SetIconForType()`.

RETURN CODES

- `B_OK`. 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_OK`. 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_OK`. 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_OK`. 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() , GetWildcardApps()

status_t `GetSupportingApps(` BMessage *msg`)` const
static status_t `GetWildcardApps(` BMessage *msg`) `

These functions retrieve a list of applications (identified by signature) that know how to handle the object's MIME type (for `GetSupportingApps()`) or all MIME types (`GetWildCardApps()`). The information is returned in msg, which must be allocated by the caller. The msg format is:

Field name | Type | Meaning
--- | --- | ---
"applications" | B_STRING_TYPE (array) | The signatures of the application that know how to handle the MIME type. The first n applications (where n is defined by "be:sub", below) can handle the full type (supertype and subtype). The rest of the applications in the array handle the supertype only.
"be:sub" | B_INT32_TYPE | The number of applications in the "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.
"be:super" | B_INT32_TYPE | 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 `GetWildcardApps()` function never returns supertype-only apps.

For example, here we print the signatures of the apps that can handle "text/plain" and "text" (without checking for errors):

       BMessage msg();
       BMimeType mime("text/plain");
       int32 subs=0, supers=0, n, hold;
       char *ptr;

       mime.GetSupportingApps(&msg);
       msg.FindInt32("be:subs", &subs);
       msg.FindInt32("be:supers", &supers);

       for (n = 0; n < subs; n++) {
          msg.FindString("applications", n, &ptr);
          printf("Full support: %sn", ptr);
       }
       hold = n;
       for (n = 0; n < supers; n++) {
          msg.FindString("applications", n+hold, &ptr);
          printf("Supertype support: %sn", ptr);
       }

If an application supports both the full type and the supertype, it will be listed only once in the "applications" array (as a full supporter).

To set the types that an application supports, use `BAppFileInfo::SetSupportedTypes()`. To tell an app to support all types, add "application/octet-stream" to its supported-types list.

See also:

RETURN CODES

`B_OK`. The signatures were found.

- `B_BAD_PORT`. No `be_app` found.

- `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_OK`. 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 I`sValid(`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()

### SetAttrInfo() see GetAttrInfo()

### GetFileExtensions()

### GetIcon()

### GetIconForType()

### GetLongDescription()

### GetPreferredApp()

### GetLongDescription()

### 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_INITGetLongDescription()` .

RETURN CODES

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

- `B_OK`. 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()`

### StartWatching() , StopWatching()

static status_t `StartWatching(` BMessenger target`)`
static status_t `StopWatching(` BMessenger target`)`

`StartWatching()` initiates the MIME monitor, which is used for keeping track of changes to the File Types database. Change notifications will be sent via the BMessenger target in a BMessage with the what field set to `B_META_MIME_CHANGED`.

Notification messages have the following fields:

Name | Type | Description
--- | --- | ---
be:which | int32 | Change bitmap (see below for a list)
be:type | string | MIME type whose database information was changed
be:extra_type | string | Extra MIME field used for some notifications
be:large_icon | bool | For notifications involving icon changes,`true` if the large icon was changed; `false` otherwise

"be:which" is a bitmask describing the changes made to the database for MIME type "be:type". The following masks are defined along with the BMimeType methods used to effect the changes they signal:

`B_ICON_CHANGED` | `SetIcon()`
B_PREFERRED_APP_CHANGED | `SetPreferredApp()`
B_ATTR_INFO_CHANGED | `SetAttrInfo()`
B_FILE_EXTENSIONS_CHANGED | `SetFileExtensions()`
B_SHORT_DESCRIPTION_CHANGED | `SetShortDescription()`
B_LONG_DESCRIPTION_CHANGED | `SetLongDescription()`
B_ICON_FOR_TYPE_CHANGED | `SetIconForType()`
B_APP_HINT_CHANGED | `SetAppHint()`

The BMimeType methods are given for illustrative purposes only –– anything that alters the database for a MIME type will also trigger a notification message. The "be:extra_type" field is used only in the `B_ICON_FOR_TYPE_CHANGED` message and indicates the application signature for which the change is valid.

`StopWatching()` terminates the MIME monitor previously initiated for the given BMessenger.

### StartWatching()

### 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()StartWatching()` 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_OK`. Everything's fine.

- `B_BAD_VALUE`. This object isn't initialized.

### SetTo()

## Operators

### == (comparison)

bool `operator``==(`const BMimeType &type`)` const
bool `operator``==(`const char *type`)` const

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

## C Functions

### create_app_meta_mime

status_t `create_app_meta_mime``(`const char *path, int recursive, int synchronous, int force`) `

Creates an entry in the File Types database for a specific application, or for all applications:

- To create an entry for a specific application, pass the path to the application in path. Information is taken from the app and written into the database.

- To create entries for all applications, pass a `NULL` path.

The recursive flag is currently unused.

If synchronous is `true`, the function doesn't return until the operation is complete. If it's `false`, the function returns immediately while the operation continues in the background.

If force is `true`, entries are created even if they already exist.

RETURN CODES

`B_OKSetTo()` . No error.

- `B_BAD_VALUE`. You can't request recursive operation when a path is specified.

### get_device_icon

status_t `get_device_icon``(`const char *device, void *icon, int32 size`) `

`Returns` the icons that are associated with the given device. You specify which icon you want (large or small) by passing 32 or 16 as the size argument. The icon is then returned through the icon argument.

See also: `BVolume::GetIcon()`

### update_mime_info

int `update_mime_info``(`const char *path, int recursive, int synchronous, int force`) `

Updates the MIME information for one or more files, specified by path. If path is `NULL`, all files are scanned recursively, and the value of recursive is ignored.

If recursive is `true` and path indicates a directory, the directory tree contained by path is scanned, with every file in the tree being updated; otherwise, just the file indicated by path is updated.

If synchronous is `true`, `update_mime_info()` doesn't return until the update operation is complete. If it's `false`, `update_mime_info()` runs asynchronously, and returns immediately while updating continues in the background.

If force is `true`, files are updated even if they've been updated already.

If an error occurs, `update_mime_info()` returns a negative error code; otherwise, it returns `B_OK`.

The Storage Kit Table of Contents | The Storage Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..