# The Application Kit: BRoster

Derived from: none

Declared in: be/app/Roster.h

Library: libbe.so

## Overview

The BRoster object represents a service that keeps a roster of all applications currently running. It can provide information about any of those applications, activate one of them, 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 BRoster object is constructed and assigned to a global variable, `be_roster`. You always access the roster through this variable; you never have to instantiate a BRoster in application code.

The BRoster identifies applications in three ways:

- By `entry_ref` references to the executable files where they reside.

- By their signatures. The signature is a unique identifier for the application assigned as a file-system attribute or resource at compile time or by the BApplication constructor at run time. You can obtain signatures for the applications you develop by contacting Be's developer support staff. They can also tell you what the signatures of other applications are.

- At run time, by their `team_id`s. A team is a group of threads sharing an address space; every application is a team.

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

### BRoster()

          BRoster(void)

Sets up the object's connection to the roster service.

When an application constructs its BApplication object, the system constructs a BRoster object and assigns it to the `be_roster` global variable. A BRoster is therefore readily available from the time the application is initialized until the time it quits; you don't have to construct one. The constructor is public only to give programs that don't have BApplication objects access to the roster.

### ~BRoster()

          ~BRoster()

Does nothing.

## Member Functions

### ActivateApp()

          status_t ActivateApp(team_id team) const

Activates the team application (by bringing one of its windows to the front and making it the active window). This function works only if the target application has a window on-screen. The newly activated application is notified with a `B_APP_ACTIVATED` message.

See also: `BApplication::AppActivated()`

### Broadcast()

          status_t Broadcast(BMessage *message) const

Sends the message to every running application, except to those applications (`B_ARGV_ONLY`) that don't accept messages. The message is sent asynchronously with a timeout of 0. As is the case for other message-sending functions, the caller retains ownership of the message.

This function returns immediately after setting up the broadcast operation. It doesn't wait for the messages to be sent and doesn't report any errors encountered when they are. It returns an error only if it can't start the broadcast operation. If successful in getting the operation started, it returns `B_OK`.

See also: `BMessenger::SendMessage()`

### FindApp()

          status_t FindApp(const char *type, entry_ref *app) const
          status_t FindApp(entry_ref *file, entry_ref *app) const

Finds the application associated with the MIME data type or with the specified file, and modifies the app `entry_ref` structure so that it refers to the executable file for that application. If the type is an application signature, this function finds the application that has that signature. Otherwise, it finds the preferred application for the type. If the file is an application executable, `FindApp()` merely copies the file reference to the app argument. Otherwise, it finds the preferred application for the file type.

In other words, this function goes about finding an application in the same way that `Launch()` finds the application it will launch.

If it can translate the type or file into a reference to an application executable, `FindApp()` returns `B_OK`. If not, it returns an error code, typically one describing a file system error.

See also: `Launch()`

### GetAppInfo(), GetRunningAppInfo(), GetActiveAppInfo()

          status_t GetAppInfo(cons char *signature, app_info *appInfo) const
          status_t GetAppInfo(entry_ref *executable, app_info *appInfo) const

          status_t GetRunningAppInfo(team_id team, app_info *appInfo) const

          status_t GetActiveAppInfo(app_info *appInfo) const

These functions return (in appInfo) information about a specific application. In all cases, the application must be running.

- `GetAppInfo()` finds an app that has the given signature, or that was launched from the executable file. If there's more than one such app, the function chooses one at random.

- `GetRunningAppInfo()` reports on the app that corresponds to the given team identifier.
- `GetActiveAppInfo()` reports on the currently active app.

If they're able to fill in the `app_info` structure with meaningful values, these functions return `B_OK`. `GetActiveAppInfo()` returns `B_ERROR` if there's no active application. `GetRunningAppInfo()` returns `B_BAD_TEAM_ID` if team isn't a valid team identifier for a running application. `GetAppInfo()` returns `B_ERROR` if the application isn't running.

The `app_info` structure contains the following fields:

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.

uint32 `flags
` A mask that contains information about the behavior of the application.

entry_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()`.)

char `signature`[]
The signature of the application. (This will be the same as the signature passed to `GetAppInfo()`.)

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

- `B_BACKGROUND_APP`. The application won't appear in the track bar (because it doesn't have a user interface or because it can't become the active application).

- `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:

       unit32 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()`, `BApplication::GetAppInfo()`

### GetAppList()

          void GetAppList(BList *teams) const
          void GetAppList(const char *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:

       BList *teams = new BList;
       be_roster->GetAppList(teams);
       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_id`s 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()

          status_t Launch(const char *type,
             BMessage *message = NULL,
             team_id *team = NULL) const
          status_t Launch(const char *type,
             BList *messages,
             team_id *team = NULL) const
          status_t Launch(const char *type,
             int argc,
             char **argv,
             team_id *team = NULL) const

          status_t Launch(entry_ref *file,
             BMessage *message = NULL,
             team_id *team = NULL) const
          status_t Launch(entry_ref *file,
             BList *messages,
             team_id *team = NULL) const
          status_t Launch(entry_ref *file,
             int argc,
             char **argv,
             team_id *team = NULL) const

Launches the application associated with a MIME type or with a particular file. If the MIME type is an application signature, this function launches the application with that signature. Otherwise, it launches the preferred application for the type. If the file is an application executable, it launches that application. Otherwise, it launches the preferred application for the file type and passes the file reference to the application in a `B_REFS_RECEIVED` message. In other words, `Launch()` finds the application to launch just as `FindApp()` finds the application for a particular type or file.

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 caller retains ownership of the BMessage objects (and the container BList); they won't be deleted for you.

Sending an on-launch message is appropriate 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.

If the target application is already running, `Launch()` won't launch it again, unless it permits multiple instances to run concurrently (it doesn't wait for the messages to be sent or report errors encountered when they are). It fails for `B_SINGLE_LAUNCH` and `B_EXCLUSIVE_LAUNCH` applications that have already been launched. Nevertheless, it assumes that you want the messages to get to the application and so delivers them to the currently running instance.

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_OK`. If unsuccessful, it sets the team variable to -1 and returns an error code, typically one of the following:

- `B_BAD_VALUE`. The type or file is not valid, or 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_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.

- A file system error. The file or type can't be matched to an application.

See also: the BMessenger class, `GetAppInfo()`, `FindApp()`

### TeamFor(), IsRunning()

          team_id TeamFor(const char *signature) const
          team_id TeamFor(entry_ref *executable) const

          bool IsRunning(const char *signature) const
          bool IsRunning(entry_ref *executable) const

Both these functions query whether the application identified by its signature or by a reference to its executable file 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, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.