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:


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


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:

RETURN CODES


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.

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

RETURN CODES


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.

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


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.

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

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


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:

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


InitCheck()


      status_t InitCheck(void) const

Returns the status of the most recent initialization.

RETURN 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


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.