1/* 2 * Copyright 2015 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel Dörfler, axeld@pinc-software.de 7 * 8 * Corresponds to: 9 * headers/private/app/LaunchRoster.h 10 * src/kits/app/LaunchRoster.cpp 11 */ 12 13 14/*! 15 \file LaunchRoster.h 16 \ingroup app 17 \ingroup libbe 18 \brief Provides BLaunchRoster class. 19*/ 20 21 22/*! 23 \class BLaunchRoster 24 \ingroup app 25 \ingroup libbe 26 \brief The BLaunchRoster class lets you communicate with the launch_daemon. 27 28 For an introduction to the launch_daemon's configuration files, see 29 \link launch_intro Introduction to the Launch Daemon \endlink. 30 31 \warning This class is not yet finalized, if you use it in your software 32 assume that it will break some time in the future. 33 34 \since Haiku R1 35*/ 36 37 38/*! 39 \fn BLaunchRoster::BLaunchRoster() 40 \brief Creates a new BLaunchRoster and sets up the connection to the 41 launch_daemon. 42 43 \since Haiku R1 44*/ 45 46 47/*! 48 \fn BLaunchRoster::~BLaunchRoster() 49 \brief Does nothing. 50 51 \since Haiku R1 52*/ 53 54 55/*! 56 \name Querying 57*/ 58 59 60//! @{ 61 62 63/*! 64 \fn status_t BLaunchRoster::GetData(BMessage& data) 65 \brief Returns the launch data for your own application. 66 67 If your application has any data stored by the launch_daemon, you can 68 retrieve this data with this method. Typically, this will contain the 69 communication channels the launch_daemon created for your application, 70 if any. 71 72 \return \c B_OK if the launch data has been received successfully. 73 74 \since Haiku R1 75*/ 76 77 78/*! 79 \fn status_t BLaunchRoster::GetData(const char* signature, BMessage& data) 80 \brief Returns the launch data for the specified application. 81 82 If the application has any data stored by the launch_daemon, you can 83 retrieve this data with this method. Typically, this will contain the 84 communication channels the launch_daemon created for this application, 85 if any. 86 87 \param signature The app \a signature. 88 \param data BMessage object to store the launch data in. 89 \return \c B_OK if the launch data has been received successfully. 90 91 \since Haiku R1 92*/ 93 94 95/*! 96 \fn status_t BLaunchRoster::GetPort(const char* name) 97 \brief Returns the named or default port for your application. 98 99 If the launch_daemon created a port for your application with the given 100 name, you can retrieve it with this method. Note that this is not the 101 actual port name, but the name the port has been registered with with 102 the launch_daemon. 103 104 \param name The name of the port, if \c NULL, the default port is returned. 105 \return The port ID, if successful, or an error code. 106 107 \since Haiku R1 108*/ 109 110 111/*! 112 \fn status_t BLaunchRoster::GetPort(const char* signature, const char* name) 113 \brief Returns the named or default port for the specified application. 114 115 If the launch_daemon created a port for the application with the given name, 116 you can retrieve it with this method. Note that this is not the actual port 117 name, but the name the port has been registered with with the launch_daemon. 118 119 \param signature The app \a signature. 120 \param name The name of the port, if \c NULL, the default port is returned. 121 \return The port ID, if successful, or an error code. 122 123 \since Haiku R1 124*/ 125 126 127//! @} 128 129 130/*! 131 \name Controlling 132*/ 133 134 135//! @{ 136 137 138/*! 139 \fn status_t BLaunchRoster::Target(const char* name, const BMessage& data, 140 const char* baseName) 141 \brief Launches the specified target (or a clone of it), and attaches 142 the specified data to it. 143 144 The \a baseName will, if non \c NULL, cause the target by this name to 145 be cloned, and named \a name. This allows you to create new targets with 146 different \a data. 147 For example. the app_server is using this to create different login 148 targets for different displays. 149 150 \param name The target name, as specified in the configuration files 151 \param data Additional data you can pass to the target. This argument 152 is currently ignored. 153 \param baseName The name of the target to be cloned. Use \c NULL if you 154 do not want to clone the target. 155 \return B_OK if the target could be launched, otherwise an error code. 156 157 \since Haiku R1 158*/ 159 160 161/*! 162 \fn status_t BLaunchRoster::Target(const char* name, const BMessage* data, 163 const char* baseName) 164 \brief Launches the specified target (or a clone of it), and attaches 165 the specified data to it. 166 167 \see status_t BLaunchRoster::Target(const char* name, const BMessage& data, 168 const char* baseName) 169 170 \since Haiku R1 171*/ 172 173 174/*! 175 \fn status_t BLaunchRoster::StartSession(const char* login) 176 \brief Starts a new launch session for the specified login. 177 178 This causes the launch_daemon to start itself under the specified 179 user, and to evaluate and process the user's launch configuration. 180 181 \param login The name of the user. 182 \return B_OK if the session could be created, otherwise an error code. 183 184 \since Haiku R1 185*/ 186 187 188//! @} 189 190 191/*! 192 \name Events 193*/ 194 195 196//! @{ 197 198 199/*! 200 \fn status_t BLaunchRoster::RegisterEvent(const BMessenger& source, 201 const char* name) 202 \brief Registers an event with the launch_daemon. 203 204 Registering an event allows other applications to be triggered by this 205 event. If you register an event named "event", applications can listen 206 to it like this: 207\code 208on { 209 event 210} 211\endcode 212 Or 213\code 214on { 215 last-part-of-signature/event 216} 217\endcode 218 219 The latter form can be used to solve ambiguous event definitions. 220 221 By specifying the \c B_STICKY_EVENT flag, you can mark the event as being 222 a permanent change. Once triggered, such an event will stay triggered, ie. 223 even new targets or jobs will consider it triggered. 224 225 \param source The messenger the event is coming from. 226 \param name The name of the event. 227 \param flags Flags for the event as described. 228 \return B_OK if the event could be registered, otherwise an error code. 229 230 \since Haiku R1 231*/ 232 233 234/*! 235 \fn status_t BLaunchRoster::UnregisterEvent(const BMessenger& source, 236 const char* name) 237 \brief Unregisters an event previously registered with the launch_daemon. 238 239 \param source The messenger the event is coming from. 240 \param name The name of the event. 241 \return B_OK if the event could be unregistered, otherwise an error code. 242 243 \since Haiku R1 244*/ 245 246 247/*! 248 \fn status_t BLaunchRoster::NotifyEvent(const BMessenger& source, 249 const char* name) 250 \brief Notifies the launch_daemon that an event has been triggered. 251 252 This causes the launch_daemon to notify all jobs, or targets listening 253 to this event, eventually leading them to be started. 254 255 You must have previously registered the event, in order to make the 256 launch_daemon do anything on a notification. Unknown event notifications 257 will be ignored. 258 259 \param source The messenger the event is coming from. 260 \param name The name of the event. 261 \return B_OK if the event could be notified, otherwise an error code. 262 263 \since Haiku R1 264*/ 265 266 267/*! 268 \fn status_t BLaunchRoster::ResetStickyEvent(const BMessenger& source, 269 const char* name); 270 \brief Resets a previously triggered sticky event. 271 272 When an event triggered that is marked as \c B_STICKY_EVENT, its status 273 will be reset when you call this method for it. 274 275 You must have previously registered the event, in order to make the 276 launch_daemon do anything. Unknown event notifications will be ignored. 277 278 \param source The messenger the event is coming from. 279 \param name The name of the event. 280 \return B_OK if the event could be reset, otherwise an error code. 281 282 \since Haiku R1 283*/ 284 285 286//! @} 287