1/*
2 * Copyright 2001-2015 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		John Scipione, jscipione@gmail.com
7 *		Ingo Weinhold, bonefish@users.sf.net
8 *
9 * Corresponds to:
10 *		headers/os/app/Messenger.h	hrev48689
11 *		src/kits/app/Messenger.cpp	hrev48689
12 */
13
14
15/*!
16	\file Messenger.h
17	\ingroup app
18	\ingroup libbe
19	\brief Provides the BMessenger class and some BMessenger operator
20	       functions.
21*/
22
23
24/*!
25	\class BMessenger
26	\ingroup app
27	\ingroup libbe
28	\brief A class to send messages to a target BLooper or BHandler.
29
30	A BMessenger can send messages to local and remote targets. If the target
31	belongs to the same team as the BMessenger it is a local target, otherwise
32	if the target lives in a separate address space it is a remote target.
33
34	The most significant (set of) method(s) in the class is SendMessage(),
35	which sends its message to the target. For a local target SendMessage()
36	is roughly equivalent in terms of efficiency to posting a message
37	directly to the messenger's target (i.e. BLooper::PostMessage()).
38
39	If you supply a target BMessenger or BHandler to SendMessage() the method
40	will return immediately after delivery and the response will be handled
41	asynchronously, otherwise the method will return once the reply has been
42	delivered or after a set timeout.
43
44	The global \a be_app_messenger pointer targets the main message
45	loop of \a be_app is automatically initialized for you when you create
46	a BApplication object, you can use it wherever a BMessenger is called for.
47
48	\since BeOS R3
49*/
50
51
52/*!
53	\fn BMessenger::BMessenger()
54	\brief Creates an uninitialized BMessenger.
55
56	\since BeOS R3
57*/
58
59
60/*!
61	\fn BMessenger::BMessenger(const char* signature, team_id team,
62		status_t* result)
63	\brief Creates a BMessenger and initializes it to target the already
64	       running application identified by its signature and/or team ID.
65
66	When only a \a signature is given, and multiple instances of the application
67	are running it is indeterminate which one is chosen as the target. In case
68	only a \a team ID is passed, the target application is identified uniquely.
69	If both are supplied, the application identified by the \a team ID must have
70	a matching signature, otherwise the initialization fails.
71
72	\param signature The target application's signature. May be \c NULL.
73	\param team The target application's team ID. May be < 0.
74	\param result An optional pointer to a pre-allocated status_t into which
75	       the result of the initialization is written.
76
77	\since BeOS R3
78*/
79
80
81/*!
82	\fn BMessenger::BMessenger(const BHandler* handler, const BLooper* looper,
83		status_t* _result)
84	\brief Creates a BMessenger and initializes it to target the local
85	       BHandler and/or BLooper.
86
87	When a \c NULL \a handler is supplied, the preferred handler in the
88	\a looper is targeted. If no \a looper is supplied the looper that \a handler
89	belongs to is used instead -- that means in particular, that the \a handler
90	must already belong to a looper. If both are supplied the \a handler must
91	belong to the \a looper.
92
93	\param handler The target handler. May be \c NULL.
94	\param looper The target looper. May be \c NULL.
95	\param _result An optional pointer to a pre-allocated status_t into which
96	       the result of the initialization is written.
97
98	\since BeOS R3
99*/
100
101
102/*!
103	\fn	BMessenger::BMessenger(const BMessenger& other)
104	\brief Creates a BMessenger and initializes it to have the same target
105	       as the supplied messenger.
106
107	\since BeOS R3
108*/
109
110
111/*!
112	\fn	BMessenger::~BMessenger()
113	\brief Frees all resources associated with this object.
114
115	\since BeOS R3
116*/
117
118
119/*!
120	\name Target
121*/
122
123
124//! @{
125
126
127/*!
128	\fn	bool BMessenger::IsTargetLocal() const
129	\brief Returns whether the messenger and target belong to the same team.
130
131	\return \c true if the messenger is properly initialized and its target
132	        belong ot the same team, \c false if they reside in separate
133	        address spaces.
134
135	\since BeOS R3
136*/
137
138
139
140/*!
141	\fn BHandler* BMessenger::Target(BLooper** _looper) const
142	\brief Returns the handler and looper targeted by the messenger
143	       (if the target is local).
144
145	The handler is returned directly, the looper by reference. If both are
146	\c NULL, the object is either not properly initialized, the target
147	objects have been deleted or the target is remote. If only the returned
148	handler is \c NULL, either the looper's preferred handler is targeted or
149	the handler has been deleted.
150
151	\param _looper A pointer to a pre-allocated BLooper pointer into which
152	               the pointer to the targeted looper is written.
153
154	\return The BHandler targeted by the messenger.
155
156	\since BeOS R3
157*/
158
159
160/*!
161	\fn	bool BMessenger::LockTarget() const
162	\brief Locks the BLooper targeted by the messenger
163	       (if the target is local).
164
165	This method is a shorthand for retrieving the targeted looper via
166	Target() and calling BLooper::Lock() on the looper afterwards.
167
168	\see BLooper::Lock() for details.
169
170	\return \c true, if the looper was locked successfully, \c false, if
171	        the messenger was not properly initialized, the target was remote,
172	        or the targeted looper was invalid.
173
174	\since BeOS R3
175*/
176
177
178
179/*!
180	\fn status_t BMessenger::LockTargetWithTimeout(bigtime_t timeout) const
181	\brief Locks the BLooper targeted by the messenger with a \a timeout
182	       (if the target is local).
183
184	This method is a shorthand for retrieving the targeted looper via
185	Target() and calling BLooper::LockWithTimeout() on the looper afterwards.
186
187	\see BLooper::LockWithTimeout() for details.
188
189	\return A status code, \c B_OK on success or an error code otherwise,
190	        all other error codes returned by BLooper::LockWithTimeout().
191	\retval B_OK if the looper could be locked successfully,
192	\retval B_BAD_VALUE if the messenger is not properly initialized,
193	        the target is remote, or the targeted looper is invalid.
194
195	\see BLooper::LockWithTimeout() for more error codes.
196
197	\since BeOS R3
198*/
199
200
201//! @}
202
203
204/*!
205	\name SendMessage
206*/
207
208
209//! @{
210
211
212/*!
213	\fn	status_t BMessenger::SendMessage(uint32 command, BHandler* replyTo) const
214	\brief Delivers a BMessage with \a command \c what identifier to the
215	       messenger's target. A response may be sent to the \a replyTo handler
216	       asynchronously.
217
218	If the target's message port is full, the method waits indefinitely, until
219	space becomes available in the port. After delivery the method returns
220	immediately. It does not wait until the target processes the message or
221	even sends a reply.
222
223	\param command The what field of the message to deliver.
224	\param replyTo The handler to which a reply to the message shall be sent.
225	       May be \c NULL.
226
227	\return A status code, \c B_OK on success or an error code otherwise.
228	\retval B_OK Everything went fine.
229	\retval B_BAD_PORT_ID The messenger is not properly initialized or its
230	        target doesn't exist anymore.
231
232	\since BeOS R3
233*/
234
235
236/*!
237	\fn status_t BMessenger::SendMessage(BMessage* message, BHandler* replyTo,
238		bigtime_t timeout) const
239	\brief Delivers a \a message to the messenger's target. A response message
240	       may be sent back to the \a replyTo handler asynchronously.
241
242	A copy of the supplied message is sent and the caller retains ownership
243	of \a message.
244
245	If the target's message port is full, the method waits until space becomes
246	available in the port or the specified timeout occurs (whichever happens
247	first). After delivery the method returns immediately. It does not wait
248	until the target processes the message or even sends a reply.
249
250	This method does not return by default until the message has been delivered.
251	You can set a delivery \a timeout in microseconds.
252
253	\param message The message to be sent.
254	\param replyTo The handler for a response message to be sent.
255	       May be \c NULL.
256	\param timeout The message delivery timeout in microseconds. (optional)
257
258	\return A status code, \c B_OK on success or an error code otherwise.
259	\retval B_OK Everything went fine.
260	\retval B_BAD_PORT_ID The messenger was not properly initialized or its
261	        target didn't exist.
262	\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
263	        port was full when trying to deliver the message.
264	\retval B_TIMED_OUT The timeout expired while trying to deliver the
265	        message.
266
267	\since BeOS R3
268*/
269
270
271/*!
272	\fn	status_t BMessenger::SendMessage(BMessage* message, BMessenger replyTo,
273		bigtime_t timeout) const
274	\brief Delivers a \a message to the messenger's target. A response message
275	       may be sent back to the \a replyTo messenger's target asynchronously.
276
277	A copy of the supplied message is sent and the caller retains ownership
278	of \a message.
279
280	If the target's message port is full, the method waits until space becomes
281	available in the port or the specified timeout occurs (whichever happens
282	first). After delivery the method returns immediately. It does not wait
283	until the target processes the message or even sends a reply.
284
285	This method does not return by default until the message has been delivered.
286	You can set a delivery \a timeout in microseconds.
287
288	\param message The message to be sent.
289	\param replyTo A messenger specifying the target for a response message.
290	\param timeout The message delivery timeout in microseconds. (optional)
291
292	\return A status code, \c B_OK on success or an error code otherwise.
293	\retval B_OK Everything went fine.
294	\retval B_BAD_PORT_ID The messenger was not properly initialized or its
295	        target didn't exist.
296	\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
297	        port was full when trying to deliver the message.
298	\retval B_TIMED_OUT The timeout expired while trying to deliver the
299	        message.
300
301	\since BeOS R4
302*/
303
304
305/*!
306	\fn	status_t BMessenger::SendMessage(uint32 command, BMessage* reply) const
307	\brief Delivers a BMessage with \a command \c what identifier to the
308	       messenger's target and waits for a \a reply BMessage synchronously.
309
310	The method does wait for a reply. The reply message is copied into
311	\a reply. If the target doesn't send a reply, the \c what field of
312	\a reply is set to \c B_NO_REPLY.
313
314	\param command The what field of the message to deliver.
315	\param reply A pointer to a pre-allocated BMessage object which the reply
316	       message will be copied into.
317
318	\return A status code, \c B_OK on success or an error code otherwise.
319	\retval B_OK Everything went fine.
320	\retval B_BAD_PORT_ID The messenger was not properly initialized or its
321	        target didn't exist.
322	\retval B_NO_MORE_PORTS All reply ports were in use.
323
324	\since BeOS R3
325*/
326
327
328/*!
329	\fn	status_t BMessenger::SendMessage(BMessage* message, BMessage* reply,
330		bigtime_t deliveryTimeout, bigtime_t replyTimeout) const
331	\brief Delivers a \a message to the messenger's target and waits for a
332	       \a reply to come back synchronously.
333
334	A copy of the supplied message is sent and the caller retains ownership
335	of \a message.
336
337	The method does wait for a reply. The reply message is copied into
338	\a reply. If the target doesn't send a reply or if a reply timeout occurs,
339	the \c what field of \a reply is set to \c B_NO_REPLY.
340
341	This method does not return by default until the message has been delivered
342	and the reply has come back. You can set a \a deliveryTimeout and a
343	\a replyTimeout in microseconds.
344
345	\param message The message to be sent.
346	\param reply A pointer to a pre-allocated BMessage which the reply
347		   message will be copied into.
348	\param deliveryTimeout The message delivery timeout in microseconds.
349	       (optional)
350	\param replyTimeout The reply message timeout in microseconds. (optional)
351
352	\return A status code, \c B_OK on success or an error code otherwise.
353	\retval B_OK Everything went fine.
354	\retval B_BAD_PORT_ID The messenger was not properly initialized or its
355	        target didn't exist.
356	\retval B_WOULD_BLOCK A delivery timeout of 0 was supplied and the target
357	        port was full when trying to deliver the message.
358	\retval B_TIMED_OUT The timeout expired while trying to deliver the
359	        message.
360	\retval B_NO_MORE_PORTS All reply ports were in use.
361
362	\since BeOS R3
363*/
364
365
366//! @}
367
368
369/*!
370	\name SetTo
371*/
372
373
374//! @{
375
376
377/*!
378	\fn	status_t BMessenger::SetTo(const char* signature, team_id team)
379	\brief Reinitializes a BMessenger to target the already running application
380	       identified by the supplied signature and/or team ID.
381
382	When only a signature is given, and multiple instances of the application
383	are running it is indeterminate which one is chosen as the target. In case
384	only a team ID is passed, the target application is identified uniquely.
385	If both are supplied, the application identified by the team ID must have
386	a matching signature, otherwise the initialization fails.
387
388	\param signature The target application's signature. May be \c NULL.
389	\param team The target application's team ID. May be negative.
390
391	\return A status code, \c B_OK if the reinitialization was successful or an
392	        error code otherwise.
393	\retval B_OK The reinitialization was successful.
394	\retval B_BAD_VALUE No application with the given \a signature or \a team
395	        ID was running.
396	\retval B_BAD_TYPE No \a team ID was given and the \a signature was \c NULL.
397	\retval B_MISMATCHED_VALUES The supplied \a signature and the signature of
398	        the team didn't match.
399
400	\since Haiku R1
401*/
402
403
404/*!
405	\fn	status_t BMessenger::SetTo(const BHandler* handler,
406		const BLooper* looper)
407	\brief Reinitializes a BMessenger to target the local BHandler and/or
408	       BLooper.
409
410	When a \c NULL handler is supplied, the preferred handler in the given
411	looper is targeted. If no looper is supplied the looper the given handler
412	belongs to is used -- that means in particular, that the handler must
413	already belong to a looper. If both are supplied the handler must actually
414	belong to looper.
415
416	\param handler The target handler. May be \c NULL.
417	\param looper The target looper. May be \c NULL.
418
419	\return A status code, \c B_OK if the reinitialization was successful or an
420	        error code otherwise.
421	\retval B_OK The reinitialization was successful.
422	\retval B_BAD_VALUE Both \a handler and \a looper were \c NULL or invalid.
423	\retval B_MISMATCHED_VALUES The looper of the supplied \a handler and
424	        \a looper didn't match.
425
426	\since Haiku R1
427*/
428
429
430//! @}
431
432
433/*!
434	\name Operators
435*/
436
437
438//! @{
439
440
441/*!
442	\fn	BMessenger& BMessenger::operator=(const BMessenger& other)
443	\brief Assignment operator, makes this BMessenger a copy of \a other.
444
445	\param other the messenger to be copied.
446
447	\return A reference to this object.
448
449	\since BeOS R3
450*/
451
452
453/*!
454	\fn	bool BMessenger::operator==(const BMessenger& other) const
455	\brief Comparison operator, returns whether this and \a other have the same
456	       target.
457
458	\param other The messenger to be compared to.
459
460	\return \c true, if the messengers have the same target or if both aren't
461	        properly initialized, \c false otherwise.
462
463	\since BeOS R3
464*/
465
466
467//! @}
468
469
470/*!
471	\fn	bool BMessenger::IsValid() const
472	\brief Returns whether the messenger's target looper still exists.
473
474	\warning This method does not check whether the target handler
475	         also still exists.
476
477	\return \c true, if the messenger's target looper still exists,
478	        \c false otherwise.
479
480	\since BeOS R3
481*/
482
483
484/*!
485	\fn	team_id BMessenger::Team() const
486	\brief Returns the ID of the team that the messenger's target belongs to.
487
488	\return The team of the messenger's target.
489
490	\since BeOS R3
491*/
492
493
494/*!
495	\fn	uint32 BMessenger::HashValue() const
496	\brief Returns a hash value that uniquely identifies the messenger.
497
498	\since Haiku R1
499*/
500
501
502/*!
503	\fn bool operator<(const BMessenger& _a, const BMessenger& _b)
504	\brief Returns whether the first messenger is less than the second one.
505
506	This method defines an order on BMessengers based on their member
507	variables \c fPort, \c fHandlerToken and \c fPreferredTarget.
508
509	\param _a The first messenger.
510	\param _b The second messenger.
511
512	\return \c true, if \a a was less than \a b, \c false otherwise.
513*/
514
515
516/*!
517	\fn bool operator!=(const BMessenger& a, const BMessenger& b)
518	\brief Returns whether two BMessengers do NOT have the same target.
519
520	\param a The first messenger.
521	\param b The second messenger.
522
523	\return \c false, if \a a and \a b had the same targets or both were not
524	        properly initialized, \c true otherwise.
525*/
526