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