BAppFileInfo

Derived from: BNodeInfo
Declared in:  be/storage/AppFileInfo.h
Library: libbe.so
Summary:  more...

BAppFileInfo lets you get and set the signature, supported types, icons, app flags, and version info that's stored in an executable file's attributes and/or resources. The object also knows how to write certain particles of information into the File Type database and, if the executable is the progenitor of a running application, into the app roster (be_roster).

Most apps won't ever need to create or use a BAppFileInfo object. Setting an executable's info is best left to the file's creator, through the use of resource data that's compiled into the executable. Even the act of looking at a file's info should be rare for a normal application.

BAppFileInfo objects should only be used to examine and set the characteristics of applications and add-ons. Using the object on a non-executable file could corrupt the file.

Initialization

You initialize a BAppFileInfo object by passing it a BFile object that represents an application or add-on. The BFile needn't be open for reading, but it must be open for writing if you want to set information. The BAppFileInfo object doesn't take over ownership of the BFile that you pass it; in particular, deleting a BAppFileInfo doesn't cause the underlying BFile to be deleted.

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 appInfo; BFile file; BAppFileInfo appFileInfo; be_app->GetAppInfo(&appInfo); file.SetTo(&appInfo.ref, B_READ_WRITE); appFileInfo.SetTo(&file);

Attributes, Resources, and the File Type Database

When you ask a BAppFileInfo object to get some information, it looks in its BFile's attributes; if the information isn't there, it then looks in the file's resources. When you ask it to set some information, the info is written as an attribute and also stored as a resource. You can modify this behavior through SetInfoLocation(): You can tell the object to only access the file's attributes, or to only access the resources.

The signature, icons, and supported types that you set through the functions provided here (SetSignature(), SetIcon(), SetIconForType(), SetSupportedTypes()) are also recorded in the File Types database, as described in the various functions.

Functions Inherited From BNodeInfo

You should take care when using the following functions (inherited from BNodeInfo):

• SetPreferredApp(). Never set an application's preferred app; an application is automatically set to be its own preferred app—it won't work otherwise. An add-on's preferred app is usually itself, but it doesn't have to be. For example, you could set an add-on's preferred app to be the server or application that loads the add-on.

• SetType(). Never set the type of an application or add-on. The type is automatically set to be B_APP_MIME_TYPE (a platform-dependent value). If you change the type, your application or add-on will still run (probably), but other parts of the system (double-clicked documents, for example) may have a hard time finding it.

Errors

When you ask a BAppFileInfo to retrieve 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.

The common errors that BAppFileInfo functions return are these:

• B_OK. Success.

• B_NO_INIT. The BAppFileInfo is uninitialized, or its BFile isn't open for writing.

• B_ERROR. The BFile was locked when you initialized the BAppFileInfo.

The info-reading and -writing functions may also return the error codes declared by BNode::ReadAttr() and BNode::WriteAttr(), and by BResources::WriteResource().

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.

~BAppFileInfo()

~BAppFileInfo()

Destroys the object. The BFile that was used to initialize this 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 executable's "app flags." These are the constants that determine whether an executable 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; the 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

See the BApplication class for details on the meanings of these constants.

RETURN CODES

See "Functions Inherited From BNodeInfo" for return values.

GetIcon() , SetIcon() , GetIconForType() , SetIconForType()

status_t GetIcon(BBitmap *icon, icon_size which) const status_t SetIcon(const BBitmap *icon, icon_size which) 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)

GetIcon() and SetIcon() get and set the icons that are represent the executable. GetIconForType() and SetIconForType() get and set the icons that the executable uses when it writes (or otherwise "takes possession of") a file of the given type, identified by file_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 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 bitmap's color space must be B_CMAP8. For example:

BBitmap *bitmap = new BBitmap(BRect(0,0,31,31), B_CMAP8); appFileInfo.GetIcon(bitmap, B_LARGE_ICON);

You can remove an icon by passing NULL as the icon argument to SetIcon().

To create a BBitmap you must have a be_app object ; the object needn't be running.

RETURN CODES

• B_OK. Success

• B_BAD_VALUE. (Get...) NULL BBitmap, or invalid file_type.

• B_BAD_VALUE. (Set...) The bitmap data isn't the proper size.

• See "Functions Inherited From BNodeInfo" for other return values.

GetIconForType() see GetIcon()

GetPreferredApp() , SetPreferredApp()

See "Functions Inherited From BNodeInfo". An application's preferred app must be itself; an add-on is more flexible. For syntax, see BNodeInfo::SetPreferredApp().

GetSignature() , SetSignature()

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

These functions get and set the executable's MIME type signature. The signature buffer you pass to GetSignature() should be at least B_MIME_TYPE_LENGTH characters long; the SetSignature() buffer must be no longer than that.

When you set an executable's signature, the signature is installed in the File Type database if it's not there already. The old signature isn't removed from the database.

RETURN CODES

• B_OK. Success.

• B_ENTRY_NOT_FOUND. (Get...) The executable doesn't have a signature.

• B_BAD_VALUE. (Set...) signature is too long.

• See "Functions Inherited From BNodeInfo" for other return values.

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 MIME file types that this executable can read and/or write. The types BMessage that you pass in looks like this:

Field	Type	Meaning
"types" []	B_STRING_TYPE	An array of MIME strings.

GetSupportedTypes() copies the types into the "types" field; SetSupportedTypes() reads them from the field. The message's command constants (its what value) is ignored.

Here we print an executable's supported types:

BMessage msg; uint32 i=0; char *ptr; if (appFileInfo.GetSupportedTypes(&msg) != B_OK)    /* Handle the error. */ while (msg.FindString("types", i++, &ptr) == B_OK)    printf("> Supported Type: %sn", ptr);

If SetSupportedTypes() names a type that doesn't already appear in the File Type database, the new type is added to the database and its preferred handler is set to the executable that this BAppFileInfo object represents.

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

RETURN CODES

• B_OK. Success.

• B_NO_MEMORY. Insufficient memory to copy the types.

• See "Functions Inherited From BNodeInfo" for other return values.

See also: Supports()

GetType() , SetType()

Implementation detail; see "Functions Inherited From BNodeInfo". An executable's default file type (for both applications and add-ons) is B_APP_MIME_TYPE. This value mustn't be changed. For syntax, see BNodeInfo::SetType().

GetVersionInfo() , SetVersionInfo()

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

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 field names (and types) provide suggestions for the type of info they want to store.

There are two kinds of version info, as specified by the kind argument:

• B_APP_VERSION_KIND provides information about this specific app.

• B_SYSTEM_VERSION_KIND provides 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_OK. The version_info was found or set.

• B_ENTRY_NOT_FOUND. (Get...) the app doesn't have the requested version info.

• See "Functions Inherited From BNodeInfo" for other return values.

InitCheck()

status_t InitCheck(void) const

Returns the status of the most recent initialization.

RETURN CODES

• B_OK. The object was successfully initialized.

• B_BAD_VALUE. The object is uninitialized.

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

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 designated 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, and must not be locked. The BFile is not copied, or re-opened by BAppFileInfo. In particular, the BAppFileInfo uses file's file descriptor, and doesn't destroy the BFile object when it (the BAppFileInfo) is destroyed or reinitialized.

The BAppFileInfo object doesn't check to make sure that the file that you pass in really is an executable. Passing in a non-executable (a plain file, a directory, etc.) could corrupt the file.

RETURN CODES

• B_OK. The object was successfully initialized.

• B_BAD_VALUE. file is invalid (uninitialized).

	SetType()  see GetType()
	SetVersionInfo()  see GetVersionInfo()
	Supports()  see IsSupportedType()