Message.h revision 08a4536b
1/*
2 * Copyright 2005-2017 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Michael Lotz, mmlr@mlotz.ch
7 */
8#ifndef _MESSAGE_H
9#define _MESSAGE_H
10
11
12#include <new>
13
14#include <BeBuild.h>
15#include <DataIO.h>
16#include <Flattenable.h>
17#include <OS.h>
18#include <Rect.h>
19#include <Size.h>
20
21#include <AppDefs.h>		/* For convenience */
22#include <TypeConstants.h>	/* For convenience */
23
24
25class BAlignment;
26class BBlockCache;
27class BMessenger;
28class BHandler;
29class BString;
30class BStringList;
31struct entry_ref;
32struct rgb_color;
33
34
35// Name lengths and Scripting specifiers
36#define B_FIELD_NAME_LENGTH			255
37#define B_PROPERTY_NAME_LENGTH		255
38
39enum {
40	B_NO_SPECIFIER = 0,
41	B_DIRECT_SPECIFIER = 1,
42	B_INDEX_SPECIFIER,
43	B_REVERSE_INDEX_SPECIFIER,
44	B_RANGE_SPECIFIER,
45	B_REVERSE_RANGE_SPECIFIER,
46	B_NAME_SPECIFIER,
47	B_ID_SPECIFIER,
48
49	B_SPECIFIERS_END = 128
50	// app-defined specifiers start at B_SPECIFIERS_END + 1
51};
52
53
54class BMessage {
55public:
56			uint32				what;
57
58								BMessage();
59								BMessage(uint32 what);
60								BMessage(const BMessage& other);
61	virtual						~BMessage();
62
63			BMessage&			operator=(const BMessage& other);
64
65	// Statistics and misc info
66			status_t			GetInfo(type_code typeRequested, int32 index,
67									char** nameFound, type_code* typeFound,
68									int32* countFound = NULL) const;
69			status_t			GetInfo(const char* name, type_code* typeFound,
70									int32* countFound = NULL) const;
71			status_t			GetInfo(const char* name, type_code* typeFound,
72									bool* fixedSize) const;
73			status_t			GetInfo(const char* name, type_code* typeFound,
74									int32* countFound, bool* fixedSize) const;
75
76			int32				CountNames(type_code type) const;
77			bool				IsEmpty() const;
78			bool				IsSystem() const;
79			bool				IsReply() const;
80			void				PrintToStream() const;
81
82			status_t			Rename(const char* oldEntry,
83									const char* newEntry);
84
85	// Delivery info
86			bool				WasDelivered() const;
87			bool				IsSourceWaiting() const;
88			bool				IsSourceRemote() const;
89			BMessenger			ReturnAddress() const;
90			const BMessage*		Previous() const;
91			bool				WasDropped() const;
92			BPoint				DropPoint(BPoint* offset = NULL) const;
93
94	// Replying
95			status_t			SendReply(uint32 command,
96									BHandler* replyTo = NULL);
97			status_t			SendReply(BMessage* reply,
98									BHandler* replyTo = NULL,
99									bigtime_t timeout = B_INFINITE_TIMEOUT);
100			status_t			SendReply(BMessage* reply, BMessenger replyTo,
101									bigtime_t timeout = B_INFINITE_TIMEOUT);
102
103			status_t			SendReply(uint32 command,
104									BMessage* replyToReply);
105			status_t			SendReply(BMessage* reply,
106									BMessage* replyToReply,
107									bigtime_t sendTimeout = B_INFINITE_TIMEOUT,
108									bigtime_t replyTimeout
109										= B_INFINITE_TIMEOUT);
110
111	// Flattening data
112			ssize_t				FlattenedSize() const;
113			status_t			Flatten(char* buffer, ssize_t size) const;
114			status_t			Flatten(BDataIO* stream,
115									ssize_t* size = NULL) const;
116			status_t			Unflatten(const char* flatBuffer);
117			status_t			Unflatten(BDataIO* stream);
118
119	// Specifiers (scripting)
120			status_t			AddSpecifier(const char* property);
121			status_t			AddSpecifier(const char* property, int32 index);
122			status_t			AddSpecifier(const char* property, int32 index,
123									int32 range);
124			status_t			AddSpecifier(const char* property,
125									const char* name);
126			status_t			AddSpecifier(const BMessage* specifier);
127
128			status_t			SetCurrentSpecifier(int32 index);
129			status_t			GetCurrentSpecifier(int32* index,
130									BMessage* specifier = NULL,
131									int32* what = NULL,
132									const char** property = NULL) const;
133			bool				HasSpecifiers() const;
134			status_t			PopSpecifier();
135
136	// Adding data
137			status_t			AddAlignment(const char* name,
138									const BAlignment& alignment);
139			status_t			AddRect(const char* name, BRect rect);
140			status_t			AddPoint(const char* name, BPoint point);
141			status_t			AddSize(const char* name, BSize size);
142			status_t			AddString(const char* name, const char* string);
143			status_t			AddString(const char* name,
144									const BString& string);
145			status_t			AddStrings(const char* name,
146									const BStringList& list);
147			status_t			AddInt8(const char* name, int8 value);
148			status_t			AddUInt8(const char* name, uint8 value);
149			status_t			AddInt16(const char* name, int16 value);
150			status_t			AddUInt16(const char* name, uint16 value);
151			status_t			AddInt32(const char* name, int32 value);
152			status_t			AddUInt32(const char* name, uint32 value);
153			status_t			AddInt64(const char* name, int64 value);
154			status_t			AddUInt64(const char* name, uint64 value);
155			status_t			AddBool(const char* name, bool value);
156			status_t			AddFloat(const char* name, float value);
157			status_t			AddDouble(const char* name, double value);
158			status_t			AddColor(const char* name, rgb_color value);
159			status_t			AddPointer(const char* name,
160									const void* pointer);
161			status_t			AddMessenger(const char* name,
162									BMessenger messenger);
163			status_t			AddRef(const char* name, const entry_ref* ref);
164			status_t			AddMessage(const char* name,
165									const BMessage* message);
166			status_t			AddFlat(const char* name, BFlattenable* object,
167									int32 count = 1);
168			status_t			AddFlat(const char* name,
169									const BFlattenable* object, int32 count = 1);
170			status_t			AddData(const char* name, type_code type,
171									const void* data, ssize_t numBytes,
172									bool isFixedSize = true, int32 count = 1);
173
174			status_t			Append(const BMessage& message);
175
176	// Removing data
177			status_t			RemoveData(const char* name, int32 index = 0);
178			status_t			RemoveName(const char* name);
179			status_t			MakeEmpty();
180
181	// Finding data
182			status_t			FindAlignment(const char* name,
183									BAlignment* alignment) const;
184			status_t			FindAlignment(const char* name, int32 index,
185									BAlignment* alignment) const;
186
187			status_t			FindRect(const char* name, BRect* rect) const;
188			status_t			FindRect(const char* name, int32 index,
189									BRect* rect) const;
190			status_t			FindPoint(const char* name,
191									BPoint* point) const;
192			status_t			FindPoint(const char* name, int32 index,
193									BPoint* point) const;
194
195			status_t			FindSize(const char* name, BSize* size) const;
196			status_t			FindSize(const char* name, int32 index,
197									BSize* size) const;
198
199			status_t			FindString(const char* name,
200									const char** string) const;
201			status_t			FindString(const char* name, int32 index,
202									const char** string) const;
203			status_t			FindString(const char* name,
204									BString* string) const;
205			status_t			FindString(const char* name, int32 index,
206									BString* string) const;
207			status_t			FindStrings(const char* name,
208									BStringList* list) const;
209			status_t			FindInt8(const char* name, int8* value) const;
210			status_t			FindInt8(const char* name, int32 index,
211									int8* value) const;
212			status_t			FindUInt8(const char* name, uint8* value) const;
213			status_t			FindUInt8(const char* name, int32 index,
214									uint8* value) const;
215			status_t			FindInt16(const char* name, int16* value) const;
216			status_t			FindInt16(const char* name, int32 index,
217									int16* value) const;
218			status_t			FindUInt16(const char* name,
219									uint16* value) const;
220			status_t			FindUInt16(const char* name, int32 index,
221									uint16* value) const;
222			status_t			FindInt32(const char* name, int32* value) const;
223			status_t			FindInt32(const char* name, int32 index,
224									int32* value) const;
225			status_t			FindUInt32(const char* name,
226									uint32* value) const;
227			status_t			FindUInt32(const char* name, int32 index,
228									uint32* value) const;
229			status_t			FindInt64(const char* name, int64* value) const;
230			status_t			FindInt64(const char* name, int32 index,
231									int64* value) const;
232			status_t			FindUInt64(const char* name,
233									uint64* value) const;
234			status_t			FindUInt64(const char* name, int32 index,
235									uint64* value) const;
236			status_t			FindBool(const char* name, bool* value) const;
237			status_t			FindBool(const char* name, int32 index,
238									bool* value) const;
239			status_t			FindFloat(const char* name, float* value) const;
240			status_t			FindFloat(const char* name, int32 index,
241									float* value) const;
242			status_t			FindDouble(const char* name,
243									double* value) const;
244			status_t			FindDouble(const char* name, int32 index,
245									double* value) const;
246			status_t			FindColor(const char* name,
247									rgb_color* value) const;
248			status_t			FindColor(const char* name, int32 index,
249									rgb_color* value) const;
250			status_t			FindPointer(const char* name,
251									void** pointer) const;
252			status_t			FindPointer(const char* name, int32 index,
253									void** pointer) const;
254			status_t			FindMessenger(const char* name,
255									BMessenger* messenger) const;
256			status_t			FindMessenger(const char* name, int32 index,
257									BMessenger* messenger) const;
258			status_t			FindRef(const char* name, entry_ref* ref) const;
259			status_t			FindRef(const char* name, int32 index,
260									entry_ref* ref) const;
261			status_t			FindMessage(const char* name,
262									BMessage* message) const;
263			status_t			FindMessage(const char* name, int32 index,
264									BMessage* message) const;
265			status_t			FindFlat(const char* name,
266									BFlattenable* object) const;
267			status_t			FindFlat(const char* name, int32 index,
268									BFlattenable* object) const;
269			status_t			FindData(const char* name, type_code type,
270									const void** data, ssize_t* numBytes) const;
271			status_t			FindData(const char* name, type_code type,
272									int32 index, const void** data,
273									ssize_t* numBytes) const;
274
275	// Replacing data
276			status_t			ReplaceAlignment(const char* name,
277									const BAlignment& alignment);
278			status_t			ReplaceAlignment(const char* name, int32 index,
279									const BAlignment& alignment);
280
281			status_t			ReplaceRect(const char* name, BRect rect);
282			status_t			ReplaceRect(const char* name, int32 index,
283									BRect rect);
284
285			status_t			ReplacePoint(const char* name, BPoint aPoint);
286			status_t			ReplacePoint(const char* name, int32 index,
287									BPoint aPoint);
288			status_t			ReplaceSize(const char* name, BSize aSize);
289			status_t			ReplaceSize(const char* name, int32 index,
290									BSize aSize);
291
292			status_t			ReplaceString(const char* name,
293									const char* string);
294			status_t			ReplaceString(const char* name, int32 index,
295									const char* string);
296			status_t			ReplaceString(const char* name,
297									const BString& string);
298			status_t			ReplaceString(const char* name, int32 index,
299									const BString& string);
300			status_t			ReplaceInt8(const char* name, int8 value);
301			status_t			ReplaceInt8(const char* name, int32 index,
302									int8 value);
303			status_t			ReplaceUInt8(const char* name, uint8 value);
304			status_t			ReplaceUInt8(const char* name, int32 index,
305									uint8 value);
306			status_t			ReplaceInt16(const char* name, int16 value);
307			status_t			ReplaceInt16(const char* name, int32 index,
308									int16 value);
309			status_t			ReplaceUInt16(const char* name, uint16 value);
310			status_t			ReplaceUInt16(const char* name, int32 index,
311									uint16 value);
312			status_t			ReplaceInt32(const char* name, int32 value);
313			status_t			ReplaceInt32(const char* name, int32 index,
314									int32 value);
315			status_t			ReplaceUInt32(const char* name, uint32 value);
316			status_t			ReplaceUInt32(const char* name, int32 index,
317									uint32 value);
318			status_t			ReplaceInt64(const char* name, int64 value);
319			status_t			ReplaceInt64(const char* name, int32 index,
320									int64 value);
321			status_t			ReplaceUInt64(const char* name, uint64 value);
322			status_t			ReplaceUInt64(const char* name, int32 index,
323									uint64 value);
324			status_t			ReplaceBool(const char* name, bool aBoolean);
325			status_t			ReplaceBool(const char* name, int32 index,
326									bool value);
327			status_t			ReplaceFloat(const char* name, float value);
328			status_t			ReplaceFloat(const char* name, int32 index,
329									float value);
330			status_t			ReplaceDouble(const char* name, double value);
331			status_t			ReplaceDouble(const char* name, int32 index,
332									double value);
333			status_t			ReplaceColor(const char* name,
334									rgb_color value);
335			status_t			ReplaceColor(const char* name, int32 index,
336									rgb_color value);
337			status_t			ReplacePointer(const char* name,
338									const void* pointer);
339			status_t			ReplacePointer(const char* name, int32 index,
340									const void* pointer);
341			status_t			ReplaceMessenger(const char* name,
342									BMessenger messenger);
343			status_t			ReplaceMessenger(const char* name, int32 index,
344									BMessenger messenger);
345			status_t			ReplaceRef(const char* name,
346									const entry_ref* ref);
347			status_t			ReplaceRef(const char* name, int32 index,
348									const entry_ref* ref);
349			status_t			ReplaceMessage(const char* name,
350									const BMessage* message);
351			status_t			ReplaceMessage(const char* name, int32 index,
352									const BMessage* message);
353			status_t			ReplaceFlat(const char* name,
354									BFlattenable* object);
355			status_t			ReplaceFlat(const char* name, int32 index,
356									BFlattenable* object);
357			status_t			ReplaceData(const char* name, type_code type,
358									const void* data, ssize_t numBytes);
359			status_t			ReplaceData(const char* name, type_code type,
360									int32 index, const void* data,
361									ssize_t numBytes);
362
363	// Comparing data - Haiku experimental API
364			bool				HasSameData(const BMessage& other,
365									bool ignoreFieldOrder = true,
366									bool deep = false) const;
367
368			void*				operator new(size_t size);
369			void*				operator new(size_t, void* pointer);
370			void*				operator new(size_t,
371									const std::nothrow_t& noThrow);
372			void				operator delete(void* pointer, size_t size);
373
374	// Private, reserved, or obsolete
375			bool				HasAlignment(const char* name,
376									int32 n = 0) const;
377			bool				HasRect(const char* name, int32 n = 0) const;
378			bool				HasPoint(const char* name, int32 n = 0) const;
379			bool				HasSize(const char* name, int32 n = 0) const;
380			bool				HasString(const char* name, int32 n = 0) const;
381			bool				HasInt8(const char* name, int32 n = 0) const;
382			bool				HasUInt8(const char* name, int32 n = 0) const;
383			bool				HasInt16(const char* name, int32 n = 0) const;
384			bool				HasUInt16(const char* name, int32 n = 0) const;
385			bool				HasInt32(const char* name, int32 n = 0) const;
386			bool				HasUInt32(const char* name, int32 n = 0) const;
387			bool				HasInt64(const char* name, int32 n = 0) const;
388			bool				HasUInt64(const char* name, int32 n = 0) const;
389			bool				HasBool(const char* name, int32 n = 0) const;
390			bool				HasFloat(const char* name, int32 n = 0) const;
391			bool				HasDouble(const char* name, int32 n = 0) const;
392			bool				HasColor(const char* name, int32 n = 0) const;
393			bool				HasPointer(const char* name, int32 n = 0) const;
394			bool				HasMessenger(const char* name,
395									int32 n = 0) const;
396			bool				HasRef(const char* name, int32 n = 0) const;
397			bool				HasMessage(const char* name, int32 n = 0) const;
398			bool				HasFlat(const char* name,
399									const BFlattenable* object) const;
400			bool				HasFlat(const char* name, int32 n,
401									const BFlattenable* object) const;
402			bool				HasData(const char* name, type_code ,
403									int32 n = 0) const;
404			BRect				FindRect(const char* name, int32 n = 0) const;
405			BPoint				FindPoint(const char* name, int32 n = 0) const;
406			const char*			FindString(const char* name, int32 n = 0) const;
407			int8				FindInt8(const char* name, int32 n = 0) const;
408			int16				FindInt16(const char* name, int32 n = 0) const;
409			int32				FindInt32(const char* name, int32 n = 0) const;
410			int64				FindInt64(const char* name, int32 n = 0) const;
411			bool				FindBool(const char* name, int32 n = 0) const;
412			float				FindFloat(const char* name, int32 n = 0) const;
413			double				FindDouble(const char* name, int32 n = 0) const;
414
415	// Convenience methods
416			bool				GetBool(const char* name,
417									bool defaultValue = false) const;
418			bool				GetBool(const char* name, int32 index,
419									bool defaultValue) const;
420			int8				GetInt8(const char* name,
421									int8 defaultValue) const;
422			int8				GetInt8(const char* name, int32 index,
423									int8 defaultValue) const;
424			uint8				GetUInt8(const char* name,
425									uint8 defaultValue) const;
426			uint8				GetUInt8(const char* name, int32 index,
427									uint8 defaultValue) const;
428			int16				GetInt16(const char* name,
429									int16 defaultValue) const;
430			int16				GetInt16(const char* name, int32 index,
431									int16 defaultValue) const;
432			uint16				GetUInt16(const char* name,
433									uint16 defaultValue) const;
434			uint16				GetUInt16(const char* name, int32 index,
435									uint16 defaultValue) const;
436			int32				GetInt32(const char* name,
437									int32 defaultValue) const;
438			int32				GetInt32(const char* name, int32 index,
439									int32 defaultValue) const;
440			uint32				GetUInt32(const char* name,
441									uint32 defaultValue) const;
442			uint32				GetUInt32(const char* name, int32 index,
443									uint32 defaultValue) const;
444			int64				GetInt64(const char* name,
445									int64 defaultValue) const;
446			int64				GetInt64(const char* name, int32 index,
447									int64 defaultValue) const;
448			uint64				GetUInt64(const char* name,
449									uint64 defaultValue) const;
450			uint64				GetUInt64(const char* name, int32 index,
451									uint64 defaultValue) const;
452			float				GetFloat(const char* name,
453									float defaultValue) const;
454			float				GetFloat(const char* name, int32 index,
455									float defaultValue) const;
456			double				GetDouble(const char* name,
457									double defaultValue) const;
458			double				GetDouble(const char* name, int32 index,
459									double defaultValue) const;
460			rgb_color			GetColor(const char* name,
461									rgb_color defaultValue) const;
462			rgb_color			GetColor(const char* name, int32 index,
463									rgb_color defaultValue) const;
464			const void*			GetPointer(const char* name, int32 index,
465									const void* defaultValue = NULL) const;
466			const void*			GetPointer(const char* name,
467									const void* defaultValue = NULL) const;
468			const char*			GetString(const char* name,
469									const char* defaultValue = NULL) const;
470			const char*			GetString(const char* name, int32 index,
471									const char* defaultValue) const;
472			BAlignment			GetAlignment(const char* name, int32 index,
473									const BAlignment& defaultValue) const;
474			BAlignment			GetAlignment(const char* name,
475									const BAlignment& defaultValue) const;
476			BRect				GetRect(const char* name, int32 index,
477									const BRect& defaultValue) const;
478			BRect				GetRect(const char* name,
479									const BRect& defaultValue) const;
480			BPoint				GetPoint(const char* name, int32 index,
481									const BPoint& defaultValue) const;
482			BPoint				GetPoint(const char* name,
483									const BPoint& defaultValue) const;
484			BSize				GetSize(const char* name, int32 index,
485									const BSize& defaultValue) const;
486			BSize				GetSize(const char* name,
487									const BSize& defaultValue) const;
488
489	// fixed size fields only
490			status_t			SetBool(const char* name, bool value);
491			status_t			SetInt8(const char* name, int8 value);
492			status_t			SetUInt8(const char* name, uint8 value);
493			status_t			SetInt16(const char* name, int16 value);
494			status_t			SetUInt16(const char* name, uint16 value);
495			status_t			SetInt32(const char* name, int32 value);
496			status_t			SetUInt32(const char* name, uint32 value);
497			status_t			SetInt64(const char* name, int64 value);
498			status_t			SetUInt64(const char* name, uint64 value);
499			status_t			SetColor(const char* name, rgb_color value);
500			status_t			SetPointer(const char* name, const void* value);
501			status_t			SetString(const char* name, const char* string);
502			status_t			SetString(const char* name,
503									const BString& string);
504			status_t			SetFloat(const char* name, float value);
505			status_t			SetDouble(const char* name, double value);
506			status_t			SetAlignment(const char* name,
507									const BAlignment& value);
508			status_t			SetPoint(const char* name, const BPoint& value);
509			status_t			SetRect(const char* name, const BRect& value);
510			status_t			SetSize(const char* name, const BSize& value);
511			status_t			SetData(const char* name, type_code type,
512									const void* data, ssize_t numBytes,
513									bool fixedSize = true, int count = 1);
514
515	class Private;
516	struct message_header;
517	struct field_header;
518
519private:
520	friend class Private;
521	friend class BMessageQueue;
522
523			status_t			_InitCommon(bool initHeader);
524			status_t			_InitHeader();
525			status_t			_Clear();
526
527			status_t			_FlattenToArea(message_header** _header) const;
528			status_t			_CopyForWrite();
529			status_t			_Reference();
530			status_t			_Dereference();
531
532			status_t			_ValidateMessage();
533
534			void				_UpdateOffsets(uint32 offset, int32 change);
535			status_t			_ResizeData(uint32 offset, int32 change);
536
537			uint32				_HashName(const char* name) const;
538			status_t			_FindField(const char* name, type_code type,
539									field_header** _result) const;
540			status_t			_AddField(const char* name, type_code type,
541									bool isFixedSize, field_header** _result);
542			status_t			_RemoveField(field_header* field);
543
544			void				_PrintToStream(const char* indent) const;
545
546private:
547								BMessage(BMessage* message);
548									// deprecated
549
550	virtual	void				_ReservedMessage1();
551	virtual	void				_ReservedMessage2();
552	virtual	void				_ReservedMessage3();
553
554			status_t			_SendMessage(port_id port, team_id portOwner,
555									int32 token, bigtime_t timeout,
556									bool replyRequired,
557									BMessenger& replyTo) const;
558			status_t			_SendMessage(port_id port, team_id portOwner,
559									int32 token, BMessage* reply,
560									bigtime_t sendTimeout,
561									bigtime_t replyTimeout) const;
562	static	status_t			_SendFlattenedMessage(void* data, int32 size,
563									port_id port, int32 token,
564									bigtime_t timeout);
565
566	static	void				_StaticInit();
567	static	void				_StaticReInitForkedChild();
568	static	void				_StaticCleanup();
569	static	void				_StaticCacheCleanup();
570	static	int32				_StaticGetCachedReplyPort();
571
572private:
573			message_header*		fHeader;
574			field_header*		fFields;
575			uint8*				fData;
576
577			uint32				fFieldsAvailable;
578			size_t				fDataAvailable;
579
580			mutable	BMessage*	fOriginal;
581
582			BMessage*			fQueueLink;
583				// fQueueLink is used by BMessageQueue to build a linked list
584
585			void*				fArchivingPointer;
586
587			uint32				fReserved[8];
588
589			enum				{ sNumReplyPorts = 3 };
590	static	port_id				sReplyPorts[sNumReplyPorts];
591	static	int32				sReplyPortInUse[sNumReplyPorts];
592	static	int32				sGetCachedReplyPort();
593
594	static	BBlockCache*		sMsgCache;
595};
596
597
598#endif	// _MESSAGE_H
599