From 58fd8acd7850f24e39eb1d8bbc413aec11893a40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Axel=20D=C3=B6rfler?= Date: Fri, 17 Jul 2015 21:54:23 +0200 Subject: [PATCH] Added BLaunchRoster documentation. * Untested, and could use some more love when it comes to possible error codes. --- docs/user/app/LaunchRoster.dox | 255 +++++++++++++++++++++++++++++++++ docs/user/app/_app_intro.dox | 5 +- 2 files changed, 258 insertions(+), 2 deletions(-) create mode 100644 docs/user/app/LaunchRoster.dox diff --git a/docs/user/app/LaunchRoster.dox b/docs/user/app/LaunchRoster.dox new file mode 100644 index 0000000000..0fe375e424 --- /dev/null +++ b/docs/user/app/LaunchRoster.dox @@ -0,0 +1,255 @@ +/* + * 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. + + \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. + \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. + + \param source The messenger the event is coming from. + \param name The name of the event. + \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 +*/ + + +//! @} diff --git a/docs/user/app/_app_intro.dox b/docs/user/app/_app_intro.dox index ec40ad156d..556c283e97 100644 --- a/docs/user/app/_app_intro.dox +++ b/docs/user/app/_app_intro.dox @@ -1,5 +1,5 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2015 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -14,7 +14,7 @@ native Haiku applications with a GUI. The application kit does exactly as its name suggests; it is the basis for Haiku applications. You should read through this document and the documents referenced here before - moving on to any other part of the API. + moving on to any other part of the API. The Application Kit classes can be divided into two groups: the "messaging" classes and the "system interaction" classes. The larger group contains @@ -37,6 +37,7 @@ - BApplication - BClipboard - BCursor + - BLaunchRoster - BPropertyInfo - BRoster */