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