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//! \cond INTERNAL 15 16 17/*! 18 \file LaunchRoster.h 19 \ingroup app 20 \ingroup libbe 21 \brief Provides BLaunchRoster class. 22*/ 23 24 25/*! 26 \class BLaunchRoster 27 \ingroup app 28 \ingroup libbe 29 \brief The BLaunchRoster class lets you communicate with the launch_daemon. 30 31 For an introduction to the launch_daemon's configuration files, see 32 \link launch_intro Introduction to the Launch Daemon \endlink. 33 34 \warning This class is not yet finalized, if you use it in your software 35 assume that it will break some time in the future. 36 37 \since Haiku R1 38*/ 39 40 41/*! 42 \fn BLaunchRoster::BLaunchRoster() 43 \brief Creates a new BLaunchRoster and sets up the connection to the 44 launch_daemon. 45 46 \since Haiku R1 47*/ 48 49 50/*! 51 \fn BLaunchRoster::~BLaunchRoster() 52 \brief Does nothing. 53 54 \since Haiku R1 55*/ 56 57 58/*! 59 \name Querying 60*/ 61 62 63//! @{ 64 65 66/*! 67 \fn status_t BLaunchRoster::GetData(BMessage& data) 68 \brief Returns the launch data for your own application. 69 70 If your application has any data stored by the launch_daemon, you can 71 retrieve this data with this method. Typically, this will contain the 72 communication channels the launch_daemon created for your application, 73 if any. 74 75 \return \c B_OK if the launch data has been received successfully. 76 77 \since Haiku R1 78*/ 79 80 81/*! 82 \fn status_t BLaunchRoster::GetData(const char* signature, BMessage& data) 83 \brief Returns the launch data for the specified application. 84 85 If the application has any data stored by the launch_daemon, you can 86 retrieve this data with this method. Typically, this will contain the 87 communication channels the launch_daemon created for this application, 88 if any. 89 90 \param signature The app \a signature. 91 \param data BMessage object to store the launch data in. 92 \return \c B_OK if the launch data has been received successfully. 93 94 \since Haiku R1 95*/ 96 97 98/*! 99 \fn status_t BLaunchRoster::GetPort(const char* name) 100 \brief Returns the named or default port for your application. 101 102 If the launch_daemon created a port for your application with the given 103 name, you can retrieve it with this method. Note that this is not the 104 actual port name, but the name the port has been registered with with 105 the launch_daemon. 106 107 \param name The name of the port, if \c NULL, the default port is returned. 108 \return The port ID, if successful, or an error code. 109 110 \since Haiku R1 111*/ 112 113 114/*! 115 \fn status_t BLaunchRoster::GetPort(const char* signature, const char* name) 116 \brief Returns the named or default port for the specified application. 117 118 If the launch_daemon created a port for the application with the given name, 119 you can retrieve it with this method. Note that this is not the actual port 120 name, but the name the port has been registered with with the launch_daemon. 121 122 \param signature The app \a signature. 123 \param name The name of the port, if \c NULL, the default port is returned. 124 \return The port ID, if successful, or an error code. 125 126 \since Haiku R1 127*/ 128 129 130//! @} 131 132 133/*! 134 \name Controlling 135*/ 136 137 138//! @{ 139 140 141/*! 142 \fn status_t BLaunchRoster::Target(const char* name, const BMessage& data, 143 const char* baseName) 144 \brief Launches the specified target (or a clone of it), and attaches 145 the specified data to it. 146 147 The \a baseName will, if non \c NULL, cause the target by this name to 148 be cloned, and named \a name. This allows you to create new targets with 149 different \a data. 150 For example. the app_server is using this to create different login 151 targets for different displays. 152 153 \param name The target name, as specified in the configuration files 154 \param data Additional data you can pass to the target. This argument 155 is currently ignored. 156 \param baseName The name of the target to be cloned. Use \c NULL if you 157 do not want to clone the target. 158 \return B_OK if the target could be launched, otherwise an error code. 159 160 \since Haiku R1 161*/ 162 163 164/*! 165 \fn status_t BLaunchRoster::Target(const char* name, const BMessage* data, 166 const char* baseName) 167 \brief Launches the specified target (or a clone of it), and attaches 168 the specified data to it. 169 170 \see status_t BLaunchRoster::Target(const char* name, const BMessage& data, 171 const char* baseName) 172 173 \since Haiku R1 174*/ 175 176 177/*! 178 \fn status_t BLaunchRoster::StartSession(const char* login) 179 \brief Starts a new launch session for the specified login. 180 181 This causes the launch_daemon to start itself under the specified 182 user, and to evaluate and process the user's launch configuration. 183 184 \param login The name of the user. 185 \return B_OK if the session could be created, otherwise an error code. 186 187 \since Haiku R1 188*/ 189 190 191//! @} 192 193 194/*! 195 \name Events 196*/ 197 198 199//! @{ 200 201 202/*! 203 \fn status_t BLaunchRoster::RegisterEvent(const BMessenger& source, 204 const char* name) 205 \brief Registers an event with the launch_daemon. 206 207 Registering an event allows other applications to be triggered by this 208 event. If you register an event named "event", applications can listen 209 to it like this: 210\code 211on { 212 event 213} 214\endcode 215 Or 216\code 217on { 218 last-part-of-signature/event 219} 220\endcode 221 222 The latter form can be used to solve ambiguous event definitions. 223 224 By specifying the \c B_STICKY_EVENT flag, you can mark the event as being 225 a permanent change. Once triggered, such an event will stay triggered, ie. 226 even new targets or jobs will consider it triggered. 227 228 \param source The messenger the event is coming from. 229 \param name The name of the event. 230 \param flags Flags for the event as described. 231 \return B_OK if the event could be registered, otherwise an error code. 232 233 \since Haiku R1 234*/ 235 236 237/*! 238 \fn status_t BLaunchRoster::UnregisterEvent(const BMessenger& source, 239 const char* name) 240 \brief Unregisters an event previously registered with the launch_daemon. 241 242 \param source The messenger the event is coming from. 243 \param name The name of the event. 244 \return B_OK if the event could be unregistered, otherwise an error code. 245 246 \since Haiku R1 247*/ 248 249 250/*! 251 \fn status_t BLaunchRoster::NotifyEvent(const BMessenger& source, 252 const char* name) 253 \brief Notifies the launch_daemon that an event has been triggered. 254 255 This causes the launch_daemon to notify all jobs, or targets listening 256 to this event, eventually leading them to be started. 257 258 You must have previously registered the event, in order to make the 259 launch_daemon do anything on a notification. Unknown event notifications 260 will be ignored. 261 262 \param source The messenger the event is coming from. 263 \param name The name of the event. 264 \return B_OK if the event could be notified, otherwise an error code. 265 266 \since Haiku R1 267*/ 268 269 270/*! 271 \fn status_t BLaunchRoster::ResetStickyEvent(const BMessenger& source, 272 const char* name); 273 \brief Resets a previously triggered sticky event. 274 275 When an event triggered that is marked as \c B_STICKY_EVENT, its status 276 will be reset when you call this method for it. 277 278 You must have previously registered the event, in order to make the 279 launch_daemon do anything. Unknown event notifications will be ignored. 280 281 \param source The messenger the event is coming from. 282 \param name The name of the event. 283 \return B_OK if the event could be reset, otherwise an error code. 284 285 \since Haiku R1 286*/ 287 288 289//! @} 290 291 292/*! 293 \fn status_t BLaunchRoster::GetJobInfo(const char *name, BMessage &info) 294 \brief Undocumented public method 295 296 \param name Undocumented 297 \param info Undocumented 298 299 \return Undocumented 300 \retval <value> Undocumented 301 302 \since Haiku R1 303*/ 304 305 306/*! 307 \fn status_t BLaunchRoster::GetJobs(const char *target, BStringList &jobs) 308 \brief Undocumented public method 309 310 \param target Undocumented 311 \param jobs Undocumented 312 313 \return Undocumented 314 \retval <value> Undocumented 315 316 \since Haiku R1 317*/ 318 319 320/*! 321 \fn status_t BLaunchRoster::GetLog(BMessage &info) 322 \brief Undocumented public method 323 324 \param info Undocumented 325 326 \return Undocumented 327 \retval <value> Undocumented 328 \since Haiku R1 329*/ 330 331 332/*! 333 \fn status_t BLaunchRoster::GetLog(const BMessage &filter, BMessage &info) 334 \brief Undocumented public method 335 336 \param filter Undocumented 337 \param info Undocumented 338 339 \return Undocumented 340 \retval <value> Undocumented 341 342 \since Haiku R1 343*/ 344 345 346/*! 347 \fn status_t BLaunchRoster::GetTargetInfo(const char *name, BMessage &info) 348 \brief Undocumented public method 349 350 \param name Undocumented 351 \param info Undocumented 352 353 \return Undocumented 354 \retval <value> Undocumented 355 356 \since Haiku R1 357*/ 358 359 360/*! 361 \fn status_t BLaunchRoster::GetTargets(BStringList &targets) 362 \brief Undocumented public method 363 364 \param targets Undocumented 365 366 \return Undocumented 367 \retval <value> Undocumented 368 369 \since Haiku R1 370*/ 371 372 373/*! 374 \fn status_t BLaunchRoster::InitCheck() const 375 \brief Undocumented public method 376 377 \return Undocumented 378 \retval <value> Undocumented 379 380 \since Haiku R1 381*/ 382 383 384/*! 385 \fn status_t BLaunchRoster::SetEnabled(const char *name, bool enabled) 386 \brief Undocumented public method 387 388 \param name Undocumented 389 \param enabled Undocumented 390 391 \return Undocumented 392 \retval <value> Undocumented 393 394 \since Haiku R1 395*/ 396 397 398/*! 399 \fn status_t BLaunchRoster::Start(const char *name) 400 \brief Undocumented public method 401 402 \param name Undocumented 403 404 \return Undocumented 405 \retval <value> Undocumented 406 407 \since Haiku R1 408*/ 409 410 411/*! 412 \fn status_t BLaunchRoster::Stop(const char *name, bool force=false) 413 \brief Undocumented public method 414 415 \param name Undocumented 416 \param force Undocumented 417 418 \return Undocumented 419 \retval <value> Undocumented 420 421 \since Haiku R1 422*/ 423 424 425/*! 426 \fn status_t BLaunchRoster::StopTarget(const char *name, bool force=false) 427 \brief Undocumented public method 428 429 \param name Undocumented 430 \param force Undocumented 431 432 \return Undocumented 433 \retval <value> Undocumented 434 435 \since Haiku R1 436*/ 437 438 439//! \endcond INTERNAL 440