/*
 * Copyright 2015 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel Dörfler, axeld@pinc-software.de
 *
 * Corresponds to:
 *		headers/private/app/LaunchRoster.h
 *		src/kits/app/LaunchRoster.cpp
 */


/*!
	\file LaunchRoster.h
	\ingroup app
	\ingroup libbe
	\brief Provides BLaunchRoster class.
*/


/*!
	\class BLaunchRoster
	\ingroup app
	\ingroup libbe
	\brief The BLaunchRoster class lets you communicate with the launch_daemon.

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

	\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
*/


/*!
	\fn BLaunchRoster::BLaunchRoster()
	\brief Creates a new BLaunchRoster and sets up the connection to the
			launch_daemon.

	\since Haiku R1
*/


/*!
	\fn BLaunchRoster::~BLaunchRoster()
	\brief Does nothing.

	\since Haiku R1
*/


/*!
	\name Querying
*/


//! @{


/*!
	\fn status_t BLaunchRoster::GetData(BMessage& data)
	\brief 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.

	\return \c B_OK if the launch data has been received successfully.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::GetData(const char* signature, BMessage& data)
	\brief 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.

	\param signature The app \a signature.
    \param data BMessage object to store the launch data in.
	\return \c B_OK if the launch data has been received successfully.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::GetPort(const char* name)
	\brief 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.

	\param name The name of the port, if \c NULL, the default port is returned.
	\return The port ID, if successful, or an error code.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::GetPort(const char* signature, const char* name)
	\brief 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.

	\param signature The app \a signature.
	\param name The name of the port, if \c NULL, the default port is returned.
	\return The port ID, if successful, or an error code.

	\since Haiku R1
*/


//! @}


/*!
	\name Controlling
*/


//! @{


/*!
	\fn status_t BLaunchRoster::Target(const char* name, const BMessage& data,
			const char* baseName)
	\brief Launches the specified target (or a clone of it), and attaches
			the specified data to it.

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

	\param name The target name, as specified in the configuration files
	\param data Additional data you can pass to the target. This argument
			is currently ignored.
	\param baseName The name of the target to be cloned. Use \c NULL if you
			do not want to clone the target.
	\return B_OK if the target could be launched, otherwise an error code.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::Target(const char* name, const BMessage* data,
			const char* baseName)
	\brief Launches the specified target (or a clone of it), and attaches
			the specified data to it.

	\see status_t BLaunchRoster::Target(const char* name, const BMessage& data,
			const char* baseName)

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::StartSession(const char* login)
	\brief 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.

	\param login The name of the user.
	\return B_OK if the session could be created, otherwise an error code.

	\since Haiku R1
*/


//! @}


/*!
	\name Events
*/


//! @{


/*!
	\fn status_t BLaunchRoster::RegisterEvent(const BMessenger& source,
			const char* name)
	\brief 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:
\code
on {
	event
}
\endcode
	Or
\code
on {
	last-part-of-signature/event
}
\endcode

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

	By specifying the \c 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.

	\param source The messenger the event is coming from.
	\param name The name of the event.
	\param flags Flags for the event as described.
	\return B_OK if the event could be registered, otherwise an error code.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::UnregisterEvent(const BMessenger& source,
			const char* name)
	\brief Unregisters an event previously registered with the launch_daemon.

	\param source The messenger the event is coming from.
	\param name The name of the event.
	\return B_OK if the event could be unregistered, otherwise an error code.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::NotifyEvent(const BMessenger& source,
			const char* name)
	\brief 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.

	\param source The messenger the event is coming from.
	\param name The name of the event.
	\return B_OK if the event could be notified, otherwise an error code.

	\since Haiku R1
*/


/*!
	\fn status_t BLaunchRoster::ResetStickyEvent(const BMessenger& source,
			const char* name);
	\brief Resets a previously triggered sticky event.

	When an event triggered that is marked as \c 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.

	\param source The messenger the event is coming from.
	\param name The name of the event.
	\return B_OK if the event could be reset, otherwise an error code.

	\since Haiku R1
*/


//! @}