The Application Kit: BRoster


The Application Kit: BRoster

Derived from: none

Declared in: <app/Roster.h>


Overview

The BRoster object keeps a roster of all applications currently running on the BeBox. It can provide information about any of those applications, add another application to the roster by launching it, or get information about an application to help you decide whether to launch it.

There's just one roster and it's shared by all applications. When an application starts up, a global variable, be_roster , is initialized to point to the shared object. You always access the roster through this variable; you never directly instantiate a BRoster in application code.

The BRoster identifies applications in three ways:

If an application is launched more than once, the roster will include one entry for each instance of the application that's running. These instances will have the same signature, but different team identifiers.


Constructor and Destructor

The BRoster class doesn't have a public constructor or destructor. This is because an application doesn't need to construct or destroy a BRoster of its own. The system constructs one BRoster object for all applications and assigns it to the be_roster global variable. A BRoster is therefore readily available from the time the application is launched until the time it quits.


Member Functions


GetAppInfo(), GetRunningAppInfo() , GetActiveAppInfo()

      long GetAppInfo(ulong signature, app_info *appInfo) const
      long GetAppInfo(record_ref executable, app_info *appInfo) const

      long GetRunningAppInfo(team_id team, app_info *appInfo) const
      long GetActiveAppInfo(app_info *appInfo) const

These functions provide information about the application identified by its signature, by a database reference to its executable file, by its team, or simply by its status as the current active application. They place the information in the structure referred to by appInfo.

GetRunningAppInfo() reports on a particular instance of a running application, the one that was assigned the team identifier at launch. GetActiveAppInfo() similarly reports on a running application, the one that happens to be the current active application.

If it can, GetAppInfo() also tries to get information about an application that's running. If a running application has the signature identifier or was launched from the executable file, GetAppInfo() queries it for the information. If more than one instance of the signature application is running, or if more than one instance was launched from the same executable file, it arbitrarily picks one of the instances to report on.

Even if the application isn't running--if none of the applications currently in the roster are identified by signature or were launched from the executable file-- GetAppInfo() can still provide some information about it, perhaps enough information for you to call Launch() to get it started.

If they're able to fill in the app_info structure with meaningful values, these functions return B_NO_ERROR. However, GetActiveAppInfo() returns B_ERROR if there's no active application. GetRunningAppInfo() returns B_BAD_TEAM_ID if team isn't, on the face of it, a valid team identifier for a running application. GetAppInfo() returns B_BAD_VALUE if the signature doesn't correspond to an application on-disk, and simply B_ERROR if the executable doesn't refer to a valid record in the database or doesn't refer to a record for an executable file.

The app_info structure contains the following fields:

ulong signature The signature of the application. (This will be the same as the signature passed to GetAppInfo().)
thread_id thread The identifier for the application's main thread of execution, or -1 if the application isn't running. (The main thread is the thread in which the application is launched and in which its main() function runs.)
team_id team The identifier for the application's team, or -1 if the application isn't running. (This will be the same as the team passed to GetRunningAppInfo().)
port_id port The port where the application's main thread receives messages, or -1 if the application isn't running.
record_ref ref A reference to the file that was, or could be, executed to run the application. (This will be the same as the executable passed to GetAppInfo().)
ulong flags A mask that contains information about the behavior of the application.

The flags mask can be tested (with the bitwise & operator) against these two constants:

B_BACKGROUND_APP The application won't appear in the Browser's application menu (because it doesn't have a user interface).
B_ARGV_ONLY The application can't receive messages. Information can be passed to it at launch only, in an array of argument strings (as on the command line).

The flags mask also contains a value that explains the application's launch behavior. This value must be filtered out of flags by combining flags with the B_LAUNCH_MASK constant. For example:

   ulong behavior = theInfo.flags & B_LAUNCH_MASK;

The result will match one of these three constants:

B_EXCLUSIVE_LAUNCH The application can be launched only if an application with the same signature isn't already running.
B_SINGLE_LAUNCH The application can be launched only once from the same executable file. However, an application with the same signature might be launched from a different executable. For example, if the user copies an executable file to another directory, a separate instance of the application can be launched from each copy.
B_MULTIPLE_LAUNCH There are no restrictions. The application can be launched any number of times from the same executable file.

These flags affect BRoster's Launch() function. Launch() can always start up a B_MULTIPLE_LAUNCH application. However, it can't launch a B_SINGLE_LAUNCH application if a running application was already launched from the same executable file. It can't launch a B_EXCLUSIVE_LAUNCH application if an application with the same signature is already running.

See also: Launch Information of the chapter introduction, Launch(), BApplication::GetAppInfo()


GetAppList()

      void GetAppList(BList *teams) const
      void GetAppList(ulong signature, BList *teams) const

Fills in the teams BList with team identifiers for applications in the roster. Each item in the list will be of type team_id . It must be cast to that type when retrieving it from the list, as follows:

   team_id who = (team_id)teams->ItemAt(someIndex);

The list will contain one item for each instance of an application that's running. For example, if the same application has been launched three times, the list will include the team_ids for all three running instances of that application.

If a signature is passed, the list identifies only applications running under that signature. If a signature isn't specified, the list identifies all running applications.

See also: TeamFor(), the BMessenger constructor


IsRunning() see TeamFor()


Launch()

      long Launch(ulong signature, BMessage *message = NULL, 
         team_id *team = NULL) 
      long Launch(ulong signature, BList *messages, 
         team_id *team = NULL) 

      long Launch(ulong signature, long argc, char **argv, 
         team_id *team = NULL) 

      long Launch(record_ref executable, BMessage *message = NULL, 
         team_id *team = NULL) 
      long Launch(record_ref executable, BList *messages, 
         team_id *team = NULL) 

      long Launch(record_ref executable, long argc, char **argv, 
         team_id *team = NULL) 

Launches the application identified by its signature or by a reference to its executable file in the database.

If a message is specified, it will be sent to the application on-launch where it will be received and responded to before the application is notified that it's ready to run. Similarly, if a list of messages is specified, each one will be delivered on-launch. The BMessage objects (and the container BList) will be deleted for you.

Sending an on-launch message is appropriate only if it helps the launched application configure itself before it starts getting other messages. To launch an application and send it an ordinary message, call Launch() to get it running, then set up a BMessenger object for the application and call BMessenger's SendMessage() function.

Instead of messages, you can launch an application with an array of argument strings that will be passed to its main() function. argv contains the array and argc counts the number of strings. If the application accepts messages, this information will also be packaged in a B_ARGV_RECEIVED message that the application will receive on-launch.

If successful, Launch() places the identifier for the newly launched application in the variable referred to by team and returns B_NO_ERROR. If unsuccessful, it sets the team variable to -1, destroys all the messages it was passed (and the BList that contained them), and returns one of the following error codes:

B_BAD_VALUE The signature passed is not valid or it doesn't designate an available application.
This return value may also signify that an attempt is being made to send an on-launch message to an application that doesn't accept messages (that is, to a B_ARGV_ONLY application).
B_ERROR The executable file can't be found.
B_ALREADY_RUNNING The application is already running and can't be launched again (it's a B_SINGLE_LAUNCH or B_EXCLUSIVE_LAUNCH application).
B_LAUNCH_FAILED The attempt to launch the application failed for some other reason, such as insufficient memory.

See also: the BMessenger class, GetAppInfo()


RemoveApp()

      void RemoveApp(team_id team) 

Removes the application identified by team from the roster of running applications.


TeamFor(), IsRunning()

      team_id TeamFor(ulong signature) const
      team_id TeamFor(record_ref executable) const

      bool IsRunning(ulong signature) const
      bool IsRunning(record_ref executable) const

Both these functions query whether the application identified by its signature, or by a reference to its executable file in the database, is running. TeamFor() returns its team identifier if it is, and B_ERROR if it's not. IsRunning() returns TRUE if it is, and FALSE if it's not.

If the application is running, you probably will want its team identifier (to set up a BMessenger, for example). Therefore, it's most economical to simply call TeamFor() and forego IsRunning().

If more than one instance of the signature application is running, or if more than one instance was launched from the same executable file, TeamFor() arbitrarily picks one of the instances and returns its team_id.

See also: GetAppList()






The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.