# The Storage Kit: BAppFileInfo

Derived from: BNodeInfo

Declared in: be/storage/AppFileInfo.h

Library: libbe.so

## Overview

BAppFileInfo lets you get and set information about a specific application (executable) file. The class knows about:

- The application's signature; this is the MIME type by which the application is known to the File Type database.

- The file types that the application knows how to deal with (its "supported types").

- The application's icons, for itself as well as its supported types.

- The flags that are applied when the app is launched.

- Version information about the application.

- If you're setting information through a BAppFileInfo object, you must have a running application object.

### Initialization

You initialize a BAppFileInfo object by passing it an open BFile object. The BAppFileInfo object has its own pointer to the BFile you pass in: It doesn't take ownership of the BFile, nor does it create a separate file descriptor to the file.

Like BNodeInfo, BAppFileInfo can get information even if the BFile isn't open for reading. But (unlike its parent), the BFile must be open for writing if you want to set information (as explained in the next section).

If the BFile that you use to initialize the BAppFileInfo is open for writing, the file will be locked until you re-initialize (or delete) the BAppFileInfo object. The BFile should be unlocked when you pass it in.

To initialize a BAppFileInfo to point to the executable of `be_app`, you do this:

       /* To get app file info for be_app. */
       app_info ai;
       BFile file;
       BAppFileInfo afi;

       be_app->GetAppInfo(&ai);
       file.SetTo(&ai.ref, B_READ_WRITE);
       afi.SetTo(&file);

For any other running app, you have to consult the roster:

       /* To get app file info for any app. */
       app_info ai;
       BFile file;
       BAppFileInfo afi;

       /* Here we look for the app by its signature; we could also
        * call GetRunningAppInfo(), or walk down the app list, etc.
        */
       be_roster->GetAppInfo("application/whatever", &ai);
       file.SetTo(&ai.ref, B_READ_WRITE);
       afi.SetTo(&file);

### Attributes and Resources

When you ask a BAppFileInfo object to get some information, it looks in its file's attributes. But when you ask to set some information, the info is written to the file's attributes and it's stored in the resources portion of the file, as well. This explains why the BFile must be open for writing. Also, because the resources portion must be open, BAppFileInfo isn't just a cover for attribute-accessing functions, the way BNodeInfo is.

### The File Type Database and the App's Signature

In some cases, the information that you set through a BAppFileInfo object is also recorded also in the File Type database (based on the app's signature) and in the app roster. This only works, however, if the application's signature is recognized by the database. The BAppFileInfo class doesn't tell the database about the signature; to do this, you have to go through a BMimeType object:

       char buf[B_MIME_TYPE_LENGTH];
       BMimeType mime;

       if (afi.GetSignature(buf) == B_NO_ERROR) {
          mime.SetTo(buf);
          mime.Install();
       }

### Errors

Unlike most of the other Storage Kit classes, when you ask a BAppFileInfo to retrieve some information by reference, the object doesn't clear the reference argument if it fails. Because of this, you should always check the error code that's returned by the `Get...()` functions.

## Constructor and Destructor

### BAppFileInfo()

          BAppFileInfo(void)
          BAppFileInfo(BFile *file)

The default constructor creates a new, uninitialized BAppFileInfo object. To initialize you have to follow this construction with a call to `SetTo()`.

The BFile version intializes the BAppFileInfo by passing the argument to `SetTo()`. See `SetTo()` for details (and error codes).

### ~BAppFileInfo()

          ~BAppFileInfo()

Destroys the object. The BFile object that was used to initialize the object isn't touched.

## Member Functions

### GetAppFlags(), SetAppFlags()

          status_t GetAppFlags(uint32 *flags) const

          status_t SetAppFlags(uint32 flags)

These functions get and set the application's "app flags." These are the constants that determine whether the app can only be launched once, whether it runs in the background, and so on. The app flag constants are defined in be/app/Roster.h; an application's flags must include one of the following...

B_SINGLE_LAUNCH
B_MULTIPLE_LAUNCH
B_EXCLUSIVE_LAUNCH

...plus either of these two:

B_BACKGROUND_APP
B_ARGV_ONLY

While an app is running, it records its app flags in the `flags` field of its `app_info` structure. See the BApplication and BRoster classes (in the Application Kit) for details.

RETURN CODES

- `B_NO_ERROR`. The flags were successfully retrieved or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### 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 stored in the app file. You specify which icon you want (large or small) by passing `B_LARGE_ICON` or `B_MINI_ICON` as the which argument.

|  | The which value does not default the way it does for BNodeInfo.

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

- If you're getting the icon, the icon argument 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). The icons that you set through `SetIcon()` are also recorded in the File Type database, based on the application's signature.

- You can remove an app's icon by passing `NULL` as the icon argument to `SetIcon()`.

RETURN CODES

- `B_NO_ERROR`. The icon was successfully found or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- `B_BAD_VALUE`. (`Get`) `NULL` BBitmap pointer.
- `B_BAD_VALUE`. (`Set`) The bitmap data isn't the proper size.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### 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 this application uses to display the given file type.

- file_type must be a valid MIME string.

- The icon and which rules are the same as for `GetIcon()`/`SetIcon()`.

The icons that you set are recorded in the File Type database, based on the app's signature.

RETURN CODES

- `B_NO_ERROR`. The icon was found or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- `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.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### GetPreferredApp(), SetPreferredApp()

|  | Don't use these functions. An application's preferred app is itself; mucking with this setting is asking for trouble. These functions are inherited from BNodeInfo.

### GetSignature(), SetSignature()

          status_t GetSignature(char *signature) const
          status_t SetSignature(const char *signature)

These functions get and set the signature (a MIME string) by which this application is known to the File Type database.

- The signature buffer that you pass to `GetSignature()` should be at least `B_MIME_TYPE_LENGTH` characters long; the signature is copied into the buffer.

- The length of the signature you pass to`SetSignature()` must be no longer than `B_MIME_TYPE_LENGTH`.

|  | `SetSignature()` does not install the signature (as a file type) in the File Type database. See "The File Type Database and the App's Signature" for details.

RETURN CODES

- `B_NO_ERROR`. The signature was found or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- `B_ENTRY_NOT_FOUND`. (`Get`) The app doesn't have a signature.
- `B_BAD_VALUE`. (`Set`) signature is too long.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### GetSupportedTypes(), SetSupportedTypes()

          status_t GetSupportedTypes(BMessage *types) const
          status_t SetSupportedTypes(const BMessage *types)
          status_t SetSupportedTypes(const BMessage *types, bool sync_all)

These functions get and set the file types that this app understands.

- If you're getting the types, you'll find them copied into your BMessage's "types" field (the BMessage must be allocated). They're given as an indexed array of strings (`B_STRING_TYPE`).

- Similarly, you pass in the supported types by adding strings to the message's "types" field.

- The BMessage's `what` field is unimportant.

Here we print all the supported types for a particular app:

       /* afi is a valid BAppFileInfo object. */
       BMessage msg;
       uint32 i=0;
       char *ptr;

       if (afi.GetSupportedTypes(&msg) != B_NO_ERROR)
          /* Handle the error. */

       while (true) {
          if (msg.FindString("types", i++, &ptr)
                != B_NO_ERROR)
             break;
          printf("> Supported Type:  %s\\n", ptr);
       }

The supported types that you set are recorded in the File Type database, based on the app's signature, and they're recorded by the app roster

When you set a new supported type, the File Type database makes sure that the type is "installed" (that the type is understood by the database). If the type wasn't previously installed, the type's preferred app is set to this app's signature.

|  | `SetSupportedTypes()` clobbers an app's existing set of supported types. If you want to augment an app's supported types, you should retrieve the existing set, add the new ones, and then call `SetSupportedTypes()`.

RETURN CODES

- `B_NO_ERROR`. The types were found (including no types) or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_NO_MEMORY.` Insufficient memory to copy the types.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

See also: `Supports()`

### GetType(), SetType()

          virtual status_t GetType(char *type) const
          virtual status_t SetType(const char *type)

These functions get and set the app's file type. The file type, passed in or returned through type, is a MIME string.

A Be-native application's default file type is `B_APP_MIME_TYPE` ("application/x-be-application").

RETURN CODES

- `B_NO_ERROR`. The type was found (including no type) or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- `B_BAD_VALUE`. (`Set`) type is too long.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### GetVersionInfo(), SetVersionInfo(), version_info, version_kind

          status_t GetVersionInfo(version_info *info, version_kind kind) const
          status_t SetVersionInfo(const version_info *info, version_kind kind)

          struct version_info {}

The functions get and set the application's "version info." The information is recorded in the `version_info` structure:

       struct version_info {
          uint32 major;

       uint32 middle;
          uint32 minor;
          uint32 variety;
          uint32 internal;
          char short_info[64];
          char long_info[256];
       }

The fields have no prescribed uses: You can stuff whatever information you want in them. Obviously, the field names (and types) provide suggestions for the type of info they want to store.

There are two kinds of version info; the kind you want to look at or set is encoded in the kind argument:

- `B_APP_VERSION_KIND` records information about this specific app.

- `B_SYSTEM_VERSION_KIND` records information about the "suite," or other grouping of apps, that this app belongs to.

Again, the uses of the two kinds is up to the app developer--currently, nothing in the BeOS depends on any information being stored in either `version_info` structure.

RETURN CODES

- `B_NO_ERROR`. The `version_info` was found or set.
- `B_NO_INIT`. The BAppFileInfo is uninitialized.
- `B_NO_INIT`. (`Set`) The BFile isn't open for writing.
- `B_ERROR`. (`Set`) The BFile was locked when you initialized this object.
- `B_ENTRY_NOT_FOUND`. (`Get`) the app doesn't have the requested version info.
- Attribute errors. See the error codes for `BNode::ReadAttr()` and `BNode::WriteAttr()`.
- BResources errors. See the error codes for `BResources::WriteResource()`.

### InitCheck()

          status_t InitCheck(void) const

Returns the status of the most recent initialization.

RETURN CODES

- `B_NO_ERROR`. The object was successfully initialized.
- `B_NO_INIT`. The object is uninitialized.
- See `SetTo()` for more error codes.

### IsSupportedType(), Supports()

          bool IsSupportedType(const char *type) const

          bool Supports(BMimeType *type) const

Returns `true` if the app supports the given MIME type and `false` if it doesn't. `IsSupportedType()` always returns true if the application supports "application/octet-stream", while Supports() returns true only if type is explicitly supported.

See also: `GetSupportedTypes()`, `SetSupportedTypes()`

### IsUsingAttributes() see SetInfoLocation()

### IsUsingResources() see SetInfoLocation()

### SetAppFlags() see GetAppFlags()

### SetIcon() see GetIcon()

### SetIconForType() see GetIconForType()

### SetInfoLocation(), IsUsingAttributes(), IsUsingResources()

          void SetInfoLocation(info_location loc)

          bool IsUsingAttributes(void) const

          bool IsUsingResources(void) const

`SetInfoLocation()` sets the location where the BAppFileInfo object stores its information. It can store them as either attributes, resources, or both. loc takes the following values:

B_USE_ATTRIBUTES
B_USE_RESOURCES
B_USE_BOTH

`IsUsingAttributes()` and `IsUsingResources()` return `true` if the BAppFileInfo object is storing information in the appropriate location and `false` otherwise.

### SetPreferredApp() see GetPreferredApp()

### SetSignature() see GetSignature()

### SetSupportedTypes() see GetSupportedTypes()

### SetTo()

          status_t SetTo(BFile *file)

Initializes the BAppFileInfo object by pointing it to file, which must be a valid (initialized) BFile object. The BFile is not copied, or re-opened by BAppFileInfo. In particular, the BAppFileInfo uses file's file descriptor.

If the BFile is open for writing, it will be locked by this function. The BFile should be unlocked when you pass it in.

RETURN CODES

- `B_NO_ERROR`. The object was successfully initialized.
- `B_BAD_VALUE`. file is uninitialized.

### GetTypes()

### SetVersionInfo() see GetVersionInfo()

### Supports() see IsSupportedType()

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.