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