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"). 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.

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

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.

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.

See Also: BNodeInfo::GetAppHint()

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:

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.

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.

Warning

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.

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

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

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

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.

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.

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:

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.

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

See SetTo().

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.

Warning

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();

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.

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.

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

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:

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:

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.

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

The errors apply to GetSupertype() only.

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