Public Member Functions | List of all members
BLaunchRoster Class Reference

The BLaunchRoster class lets you communicate with the launch_daemon. More...

Public Member Functions

 BLaunchRoster ()
 Creates a new BLaunchRoster and sets up the connection to the launch_daemon. More...
 
 ~BLaunchRoster ()
 Does nothing. More...
 
Querying
status_t GetData (BMessage &data)
 Returns the launch data for your own application. More...
 
status_t GetData (const char *signature, BMessage &data)
 Returns the launch data for the specified application. More...
 
port_id GetPort (const char *name=NULL)
 Returns the named or default port for your application. More...
 
port_id GetPort (const char *signature, const char *name)
 Returns the named or default port for the specified application. More...
 
Controlling
status_t Target (const char *name, const BMessage &data, const char *baseName=NULL)
 Launches the specified target (or a clone of it), and attaches the specified data to it. More...
 
status_t Target (const char *name, const BMessage *data=NULL, const char *baseName=NULL)
 Launches the specified target (or a clone of it), and attaches the specified data to it. More...
 
status_t StartSession (const char *login)
 Starts a new launch session for the specified login. More...
 
Events
status_t RegisterEvent (const BMessenger &source, const char *name, uint32 flags)
 Registers an event with the launch_daemon. More...
 
status_t UnregisterEvent (const BMessenger &source, const char *name)
 Unregisters an event previously registered with the launch_daemon. More...
 
status_t NotifyEvent (const BMessenger &source, const char *name)
 Notifies the launch_daemon that an event has been triggered. More...
 
status_t ResetStickyEvent (const BMessenger &source, const char *name)
 Resets a previously triggered sticky event. More...
 

Detailed Description

The BLaunchRoster class lets you communicate with the launch_daemon.

For an introduction to the launch_daemon's configuration files, see Introduction to the Launch Daemon .

Warning
This class is not yet finalized, if you use it in your software assume that it will break some time in the future.
Since
Haiku R1

Constructor & Destructor Documentation

◆ BLaunchRoster()

BLaunchRoster::BLaunchRoster ( )

Creates a new BLaunchRoster and sets up the connection to the launch_daemon.

Since
Haiku R1

◆ ~BLaunchRoster()

BLaunchRoster::~BLaunchRoster ( )

Does nothing.

Since
Haiku R1

Member Function Documentation

◆ GetData() [1/2]

status_t BLaunchRoster::GetData ( BMessage data)

Returns the launch data for your own application.

If your application has any data stored by the launch_daemon, you can retrieve this data with this method. Typically, this will contain the communication channels the launch_daemon created for your application, if any.

Returns
B_OK if the launch data has been received successfully.
Since
Haiku R1

◆ GetData() [2/2]

status_t BLaunchRoster::GetData ( const char *  signature,
BMessage data 
)

Returns the launch data for the specified application.

If the application has any data stored by the launch_daemon, you can retrieve this data with this method. Typically, this will contain the communication channels the launch_daemon created for this application, if any.

Parameters
signatureThe app signature.
dataBMessage object to store the launch data in.
Returns
B_OK if the launch data has been received successfully.
Since
Haiku R1

◆ GetPort() [1/2]

status_t BLaunchRoster::GetPort ( const char *  name = NULL)

Returns the named or default port for your application.

If the launch_daemon created a port for your application with the given name, you can retrieve it with this method. Note that this is not the actual port name, but the name the port has been registered with with the launch_daemon.

Parameters
nameThe name of the port, if NULL, the default port is returned.
Returns
The port ID, if successful, or an error code.
Since
Haiku R1

◆ GetPort() [2/2]

status_t BLaunchRoster::GetPort ( const char *  signature,
const char *  name 
)

Returns the named or default port for the specified application.

If the launch_daemon created a port for the application with the given name, you can retrieve it with this method. Note that this is not the actual port name, but the name the port has been registered with with the launch_daemon.

Parameters
signatureThe app signature.
nameThe name of the port, if NULL, the default port is returned.
Returns
The port ID, if successful, or an error code.
Since
Haiku R1

◆ NotifyEvent()

status_t BLaunchRoster::NotifyEvent ( const BMessenger source,
const char *  name 
)

Notifies the launch_daemon that an event has been triggered.

This causes the launch_daemon to notify all jobs, or targets listening to this event, eventually leading them to be started.

You must have previously registered the event, in order to make the launch_daemon do anything on a notification. Unknown event notifications will be ignored.

Parameters
sourceThe messenger the event is coming from.
nameThe name of the event.
Returns
B_OK if the event could be notified, otherwise an error code.
Since
Haiku R1

◆ RegisterEvent()

status_t BLaunchRoster::RegisterEvent ( const BMessenger source,
const char *  name,
uint32  flags 
)

Registers an event with the launch_daemon.

Registering an event allows other applications to be triggered by this event. If you register an event named "event", applications can listen to it like this:

on {
event
}

Or

on {
last-part-of-signature/event
}

The latter form can be used to solve ambiguous event definitions.

By specifying the B_STICKY_EVENT flag, you can mark the event as being a permanent change. Once triggered, such an event will stay triggered, ie. even new targets or jobs will consider it triggered.

Parameters
sourceThe messenger the event is coming from.
nameThe name of the event.
flagsFlags for the event as described.
Returns
B_OK if the event could be registered, otherwise an error code.
Since
Haiku R1

◆ ResetStickyEvent()

status_t BLaunchRoster::ResetStickyEvent ( const BMessenger source,
const char *  name 
)

Resets a previously triggered sticky event.

When an event triggered that is marked as B_STICKY_EVENT, its status will be reset when you call this method for it.

You must have previously registered the event, in order to make the launch_daemon do anything. Unknown event notifications will be ignored.

Parameters
sourceThe messenger the event is coming from.
nameThe name of the event.
Returns
B_OK if the event could be reset, otherwise an error code.
Since
Haiku R1

◆ StartSession()

status_t BLaunchRoster::StartSession ( const char *  login)

Starts a new launch session for the specified login.

This causes the launch_daemon to start itself under the specified user, and to evaluate and process the user's launch configuration.

Parameters
loginThe name of the user.
Returns
B_OK if the session could be created, otherwise an error code.
Since
Haiku R1

◆ Target() [1/2]

status_t BLaunchRoster::Target ( const char *  name,
const BMessage data,
const char *  baseName = NULL 
)

Launches the specified target (or a clone of it), and attaches the specified data to it.

The baseName will, if non NULL, cause the target by this name to be cloned, and named name. This allows you to create new targets with different data. For example. the app_server is using this to create different login targets for different displays.

Parameters
nameThe target name, as specified in the configuration files
dataAdditional data you can pass to the target. This argument is currently ignored.
baseNameThe name of the target to be cloned. Use NULL if you do not want to clone the target.
Returns
B_OK if the target could be launched, otherwise an error code.
Since
Haiku R1

◆ Target() [2/2]

status_t BLaunchRoster::Target ( const char *  name,
const BMessage data = NULL,
const char *  baseName = NULL 
)

Launches the specified target (or a clone of it), and attaches the specified data to it.

See also
status_t BLaunchRoster::Target(const char* name, const BMessage& data, const char* baseName)
Since
Haiku R1

◆ UnregisterEvent()

status_t BLaunchRoster::UnregisterEvent ( const BMessenger source,
const char *  name 
)

Unregisters an event previously registered with the launch_daemon.

Parameters
sourceThe messenger the event is coming from.
nameThe name of the event.
Returns
B_OK if the event could be unregistered, otherwise an error code.
Since
Haiku R1