Derived from: BNodeInfo
Declared in: be/nustorage/AppFileInfo.h
Library: libbe.so
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. |
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 itin. |
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);
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.
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();
}
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.
BAppFileInfo(void)
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(void)
Destroys the object. The BFile object that was used to initialize the object isn't touched.
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...
...plus either of these two:
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
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_SMALL_ICON as the which argument.
|
Note that the which value does not default the way it does for BNodeInfo. |
The icon is passed in or returned through the icon argument:
|
The icons that you set through SetIcon() are also recorded in the File Type database, based on the application's signature. |
RETURN CODES
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.
|
The icons that you set are recorded in the File Type database, based on the app's signature. |
RETURN CODES
|
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.
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.
|
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
status_t GetSupportedTypes(BMessage *types) const
status_t SetSupportedTypes(const BMessage *types)
These functions get and set the file types that this app understands.
 |
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 that 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 the existing set of 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
|
Bug: SetSupportedTypes() sometimes returns B_ERROR even when it's successful. |
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 "application/x-be-application". You should rarely need to reset the default. |
RETURN CODES
status_t GetVersionInfo(version_info *info, version_kind kind) const
status_t SetVersionInfo(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:
structu version_info {
uint32 major;
uint32 middle;
uint32 minor;
uint32 variety;
uint32 internal;
char short_info[64];
char long_info[64];
}
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:
Again, the uses of the two kinds is up to the app developer:
|
Nothing in the BeOS system depends on any information being stored in either version_info structure. |
RETURN CODES
status_t InitCheck(void) const
Returns the status of the most recent initialization.
RETURN CODES
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
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified July 17, 1997.