Message.h

/* This file is Copyright 2000-2008 Meyer Sound Laboratories Inc.  See the included LICENSE.txt file for details. */

/******************************************************************************
/
/   File:       Message.h
/
/   Description:   OS-independent version of Be's BMessage class.
/         Doesn't contain all of BMessage's functionality,
/         but keeps enough of it to be useful as a portable
/         data object (dictionary) in cross-platform apps.
/         Also adds some functionality that BMessage doesn't have,
/         such as iterators and optional direct (non-copying) access to internal
/         data (for efficiency)
/
*******************************************************************************/

#ifndef MuscleMessage_h
#define MuscleMessage_h

#include "support/Point.h"
#include "support/Rect.h"
#include "util/ByteBuffer.h"
#include "util/String.h"
#include "util/Hashtable.h"

BEGIN_NAMESPACE(muscle);

class Message;
typedef Ref<Message> MessageRef;

const Message & GetEmptyMessage();

const MessageRef & GetEmptyMessageRef();

MessageRef::ItemPool * GetMessagePool();

MessageRef GetMessageFromPool(uint32 what = 0L);

MessageRef GetMessageFromPool(ObjectPool<Message> & pool, uint32 what = 0L);

MessageRef GetMessageFromPool(const Message & copyMe);

MessageRef GetMessageFromPool(ObjectPool<Message> & pool, const Message & copyMe);

// this declaration is for internal use only
class AbstractDataArray;

class MessageFieldNameIterator : private HashtableIterator<String, GenericRef>
{
public:
   MessageFieldNameIterator() : _typeCode(B_ANY_TYPE) {/* empty */}

   MessageFieldNameIterator(const Message & msg, uint32 type = B_ANY_TYPE, uint32 flags = 0);

   ~MessageFieldNameIterator() {/* empty */}

   void operator++(int) {(void) GetNextFieldNameString();}

   void operator--(int) {bool b = IsBackwards(); SetBackwards(!b); (void) GetNextFieldNameString(); SetBackwards(b);}

   bool HasMoreFieldNames() const {return (PeekNextFieldNameString() != NULL);}

   const String & GetFieldName() const {return *PeekNextFieldNameString();}

   status_t GetNextFieldName(String & name);

   const char * GetNextFieldName() {const String * r = GetNextFieldNameString(); return r ? r->Cstr() : NULL;}

   const String * GetNextFieldNameString();

   status_t PeekNextFieldName(String & name) const;

   const char * PeekNextFieldName() const {const String * r = PeekNextFieldNameString(); return r ? r->Cstr() : NULL;}

   const String * PeekNextFieldNameString() const;

private:
   friend class Message;
   MessageFieldNameIterator(const HashtableIterator<String, GenericRef> & iter, uint32 tc) : HashtableIterator<String, GenericRef>(iter), _typeCode(tc) {/* empty */}

   uint32 _typeCode;
};

// Version number of the Message serialization protocol.
// Will be the first four bytes of each serialized Message buffer.
// Only buffers beginning with version numbers between these two 
// constants (inclusive) will be Unflattened as Messages.
#define OLDEST_SUPPORTED_PROTOCOL_VERSION 1347235888 // 'PM00'
#define CURRENT_PROTOCOL_VERSION          1347235888 // 'PM00'

class Message : public FlatCountable
{
public:
   uint32 what;

   Message() : what(0) {/* empty */}

   Message(uint32 what) : what(what) {/* empty */}

   Message(const Message & copyMe) : FlatCountable() {*this = copyMe;}

   virtual ~Message() {/* empty */}

   Message &operator=(const Message &msg);

   bool operator ==(const Message & rhs) const;

   bool operator !=(const Message & rhs) const {return !(*this == rhs);}

   status_t GetInfo(const String & name, uint32 *type, uint32 *c = NULL, bool *fixed_size = NULL) const;

   uint32 CountNames(uint32 type = B_ANY_TYPE) const;

   bool HasNames(uint32 type = B_ANY_TYPE) const {return (CountNames(type) > 0);}

   bool IsEmpty() const {return (_entries.IsEmpty());}

   void PrintToStream(bool recursive = true, int indentLevel = 0) const;

   String ToString(bool recursive = true, int indentLevel = 0) const;

   void AddToString(String & s, bool recursive = true, int indentLevel = 0) const;

   status_t Rename(const String & old_entry, const String & new_entry);

   virtual bool IsFixedSize() const {return false;}

   virtual uint32 TypeCode() const {return B_MESSAGE_TYPE;}

   virtual uint32 FlattenedSize() const;
 
   virtual void Flatten(uint8 *buffer) const;

   virtual status_t Unflatten(const uint8 *buf, uint32 size);

   status_t AddString(const String & name, const String & val);

   status_t AddInt8(const String & name, int8 val);

   status_t AddInt16(const String & name, int16 val);

   status_t AddInt32(const String & name, int32 val);

   status_t AddInt64(const String & name, int64 val);

   status_t AddBool(const String & name, bool val);

   status_t AddFloat(const String & name, float val);

   status_t AddDouble(const String & name, double val);

   status_t AddMessage(const String & name, const Message & msg) {return AddMessage(name, GetMessageFromPool(msg));}

   status_t AddMessage(const String & name, const MessageRef & msgRef); 

   status_t AddPointer(const String & name, const void * ptr);

   status_t AddPoint(const String & name, const Point & point);

   status_t AddRect(const String & name, const Rect & rect);

   status_t AddFlat(const String & name, const Flattenable &obj);

   status_t AddFlat(const String & name, const FlatCountableRef & ref);

   status_t AddFlat(const String & name, const ByteBufferRef & ref)
   {
      FlatCountableRef fcRef;
      fcRef.SetFromGenericUnchecked(ref.GetGeneric());
      return AddFlat(name, fcRef);
   }

   status_t AddTag(const String & name, const GenericRef & tagRef);

   status_t AddData(const String & name, uint32 type, const void *data, uint32 numBytes) {return AddDataAux(name, data, numBytes, type, false);}

   status_t PrependString(const String & name, const String & val);

   status_t PrependInt8(const String & name, int8 val);

   status_t PrependInt16(const String & name, int16 val);

   status_t PrependInt32(const String & name, int32 val);

   status_t PrependInt64(const String & name, int64 val);

   status_t PrependBool(const String & name, bool val);

   status_t PrependFloat(const String & name, float val);

   status_t PrependDouble(const String & name, double val);

   status_t PrependMessage(const String & name, const Message & msg) {return PrependMessage(name, GetMessageFromPool(msg));}

   status_t PrependMessage(const String & name, const MessageRef & msgRef); 

   status_t PrependPointer(const String & name, const void * ptr);

   status_t PrependPoint(const String & name, const Point & point);

   status_t PrependRect(const String & name, const Rect & rect);

   status_t PrependFlat(const String & name, const Flattenable &obj);

   status_t PrependFlat(const String & name, const FlatCountableRef & flatRef);

   status_t PrependFlat(const String & name, const ByteBufferRef & ref)
   {
      FlatCountableRef fcRef;
      fcRef.SetFromGenericUnchecked(ref.GetGeneric());
      return PrependFlat(name, fcRef);
   }

   status_t PrependTag(const String & name, const GenericRef & tagRef);

   status_t PrependData(const String & name, uint32 type, const void *data, uint32 numBytes) {return AddDataAux(name, data, numBytes, type, true);}

   status_t RemoveData(const String & name, uint32 index = 0);

   status_t RemoveName(const String & name);

   void Clear(bool releaseCachedBuffers = false) {_entries.Clear(releaseCachedBuffers);}

   status_t FindString(const String & name, uint32 index, const String ** setMe) const;

   status_t FindString(const String & name, const String ** setMe) const {return FindString(name, 0, setMe);}

   status_t FindString(const String & name, uint32 index, const char ** setMe) const;

   status_t FindString(const String & name, const char ** setMe) const {return FindString(name, 0, setMe);}

   status_t FindString(const String & name, uint32 index, String & setMe) const;

   status_t FindString(const String & name, String & setMe) const {return FindString(name, 0, setMe);}

   status_t FindInt8(const String & name, uint32 index, int8 *val) const {return FindDataItemAux(name, index, B_INT8_TYPE, val, sizeof(int8));}

   status_t FindInt8(const String & name, int8 *value) const {return FindInt8(name, 0, value);}

   status_t FindInt16(const String & name, uint32 index, int16 *val) const {return FindDataItemAux(name, index, B_INT16_TYPE, val, sizeof(int16));} 

   status_t FindInt16(const String & name, int16 *value) const {return FindInt16(name, 0, value);}

   status_t FindInt32(const String & name, uint32 index, int32 *val) const {return FindDataItemAux(name, index, B_INT32_TYPE, val, sizeof(int32));} 

   status_t FindInt32(const String & name, int32 *value) const {return FindInt32(name, 0, value);}

   status_t FindInt64(const String & name, uint32 index, int64 *val) const {return FindDataItemAux(name, index, B_INT64_TYPE, val, sizeof(int64));}  

   status_t FindInt64(const String & name, int64 *value) const {return FindInt64(name, 0, value);}

   status_t FindBool(const String & name, uint32 index, bool *val) const {return FindDataItemAux(name, index, B_BOOL_TYPE, val, sizeof(bool));} 

   status_t FindBool(const String & name, bool *value) const {return FindBool(name, 0, value);}

   status_t FindFloat(const String & name, uint32 index, float *val) const {return FindDataItemAux(name, index, B_FLOAT_TYPE, val, sizeof(float));}

   status_t FindFloat(const String & name, float *f) const {return FindFloat(name, 0, f);}

   status_t FindDouble(const String & name, uint32 index, double * val) const {return FindDataItemAux(name, index, B_DOUBLE_TYPE, val, sizeof(double));}

   status_t FindDouble(const String & name, double *d) const {return FindDouble(name, 0, d);}

   status_t FindMessage(const String & name, uint32 index, Message &msg) const;

   status_t FindMessage(const String & name, Message &msg) const {return FindMessage(name, 0, msg);}

   status_t FindMessage(const String & name, uint32 index, MessageRef &msgRef) const;

   status_t FindMessage(const String & name, MessageRef &msgRef) const {return FindMessage(name, 0, msgRef);}

   status_t FindPointer(const String & name, uint32 index, void ** val) const {return FindDataItemAux(name, index, B_POINTER_TYPE, val, sizeof(void *));}

   status_t FindPointer(const String & name, void ** ptr) const {return FindPointer(name, 0, ptr);}

   status_t FindPoint(const String & name, uint32 index, Point & point) const;

   status_t FindPoint(const String & name, Point & point) const {return FindPoint(name, 0, point);}

   status_t FindRect(const String & name, uint32 index, Rect & rect) const;

   status_t FindRect(const String & name, Rect & rect) const {return FindRect(name, 0, rect);}

   status_t FindFlat(const String & name, uint32 index, Flattenable &obj) const;

   status_t FindFlat(const String & name, Flattenable &obj) const {return FindFlat(name, 0, obj);}

   status_t FindFlat(const String & name, uint32 index, FlatCountableRef & ref) const;

   status_t FindFlat(const String & name, FlatCountableRef &ref) const {return FindFlat(name, 0, ref);}

   status_t FindFlat(const String & name, uint32 index, ByteBufferRef & ref) const
   {
      FlatCountableRef fcRef;
      return (FindFlat(name, index, fcRef) == B_NO_ERROR) ? ref.SetFromGeneric(fcRef.GetGeneric()) : B_ERROR;
   }

   status_t FindFlat(const String & name, ByteBufferRef &ref) const {return FindFlat(name, 0, ref);}

   status_t FindTag(const String & name, uint32 index, GenericRef & tagRef) const;

   status_t FindTag(const String & name, GenericRef &tagRef) const {return FindTag(name, 0, tagRef);}

   status_t FindData(const String & name, uint32 type, uint32 index, const void **data, uint32 *numBytes) const;

   status_t FindData(const String & name, uint32 type, const void **data, uint32 *numBytes) const {return FindData(name, type, 0, data, numBytes);}

   status_t FindDataPointer(const String & name, uint32 type, uint32 index, void **data, uint32 *numBytes) const;

   status_t FindDataPointer(const String & name, uint32 type, void **data, uint32 *numBytes) const {return FindDataPointer(name, type, 0, data, numBytes);}

   status_t ReplaceString(bool okayToAdd, const String & name, uint32 index, const String & newString);

   status_t ReplaceString(bool okayToAdd, const String & name, const String & newString) {return ReplaceString(okayToAdd, name, 0, newString);}

   status_t ReplaceInt8(bool okayToAdd, const String & name, uint32 index, int8 val);

   status_t ReplaceInt8(bool okayToAdd, const String & name, int8 val) {return ReplaceInt8(okayToAdd, name, 0, val);}

   status_t ReplaceInt16(bool okayToAdd, const String & name, uint32 index, int16 val);

   status_t ReplaceInt16(bool okayToAdd, const String & name, int16 val) {return ReplaceInt16(okayToAdd, name, 0, val);}

   status_t ReplaceInt32(bool okayToAdd, const String & name, uint32 index, int32 val);

   status_t ReplaceInt32(bool okayToAdd, const String & name, int32 val) {return ReplaceInt32(okayToAdd, name, 0, val);}

   status_t ReplaceInt64(bool okayToAdd, const String & name, uint32 index, int64 val);

   status_t ReplaceInt64(bool okayToAdd, const String & name, int64 val) {return ReplaceInt64(okayToAdd, name, 0, val);}

   status_t ReplaceBool(bool okayToAdd, const String & name, uint32 index, bool val);

   status_t ReplaceBool(bool okayToAdd, const String & name, bool val) {return ReplaceBool(okayToAdd, name, 0, val);}

   status_t ReplaceFloat(bool okayToAdd, const String & name, uint32 index, float val);

   status_t ReplaceFloat(bool okayToAdd, const String & name, float val) {return ReplaceFloat(okayToAdd, name, 0, val);}

   status_t ReplaceDouble(bool okayToAdd, const String & name, uint32 index, double val);

   status_t ReplaceDouble(bool okayToAdd, const String & name, double val) {return ReplaceDouble(okayToAdd, name, 0, val);}

   status_t ReplacePointer(bool okayToAdd, const String & name, uint32 index, const void * ptr);

   status_t ReplacePointer(bool okayToAdd, const String & name, const void * ptr) {return ReplacePointer(okayToAdd, name, 0, ptr);}

   status_t ReplacePoint(bool okayToAdd, const String & name, uint32 index, const Point & point);

   status_t ReplacePoint(bool okayToAdd, const String & name, const Point & point) {return ReplacePoint(okayToAdd, name, 0, point);}

   status_t ReplaceRect(bool okayToAdd, const String & name, uint32 index, const Rect & rect);

   status_t ReplaceRect(bool okayToAdd, const String & name, const Rect & rect) {return ReplaceRect(okayToAdd, name, 0, rect);}

   status_t ReplaceMessage(bool okayToAdd, const String & name, uint32 index, const Message &msg) {return ReplaceMessage(okayToAdd, name, index, GetMessageFromPool(msg));}

   status_t ReplaceMessage(bool okayToAdd, const String & name, const Message &msg) {return ReplaceMessage(okayToAdd, name, 0, msg);}

   status_t ReplaceMessage(bool okayToAdd, const String & name, uint32 index, const MessageRef & msgRef);

   status_t ReplaceMessage(bool okayToAdd, const String & name, const MessageRef & msgRef) {return ReplaceMessage(okayToAdd, name, 0, msgRef);}

   status_t ReplaceFlat(bool okayToAdd, const String & name, uint32 index, const Flattenable &obj);

   status_t ReplaceFlat(bool okayToAdd, const String & name, const Flattenable &obj) {return ReplaceFlat(okayToAdd, name, 0, obj);}

   status_t ReplaceFlat(bool okayToAdd, const String & name, uint32 index, const FlatCountableRef & ref);

   status_t ReplaceFlat(bool okayToAdd, const String & name, FlatCountableRef &ref) {return ReplaceFlat(okayToAdd, name, 0, ref);}

   status_t ReplaceFlat(bool okayToAdd, const String & name, uint32 index, const ByteBufferRef & ref) 
   {
      FlatCountableRef fcRef;
      fcRef.SetFromGenericUnchecked(ref.GetGeneric());
      return ReplaceFlat(okayToAdd, name, index, fcRef);
   }

   status_t ReplaceFlat(bool okayToAdd, const String & name, ByteBufferRef &ref) {return ReplaceFlat(okayToAdd, name, 0, ref);}

   status_t ReplaceTag(bool okayToAdd, const String & name, uint32 index, const GenericRef & tag);

   status_t ReplaceTag(bool okayToAdd, const String & name, const GenericRef & tag) {return ReplaceTag(okayToAdd, name, 0, tag);}

   status_t ReplaceData(bool okayToAdd, const String & name, uint32 type, uint32 index, const void *data, uint32 numBytes);

   status_t ReplaceData(bool okayToAdd, const String & name, uint32 type, const void *data, uint32 numBytes) {return ReplaceData(okayToAdd, name, type, 0, data, numBytes);}

   const String * GetFirstFieldNameString(uint32 optTypeCode = B_ANY_TYPE) const {return GetExtremeFieldNameStringAux(optTypeCode, false);}

   const String * GetLastFieldNameString(uint32 optTypeCode = B_ANY_TYPE) const {return GetExtremeFieldNameStringAux(optTypeCode, true);}

   bool HasName(const String & fieldName, uint32 type = B_ANY_TYPE) const {return (GetArray(fieldName, type) != NULL);}

   uint32 GetNumValuesInName(const String & fieldName, uint32 type = B_ANY_TYPE) const;

   status_t MoveName(const String & name, Message &moveTo);

   status_t CopyName(const String & name, Message &copyTo) const;

   void SwapContents(Message & swapWith);

   uint32 CalculateChecksum(bool countNonFlattenableFields = false) const;

   MessageFieldNameIterator GetFieldNameIterator(uint32 type = B_ANY_TYPE, uint32 flags = 0) const {return MessageFieldNameIterator(_entries.GetIterator(flags), type);}

   MessageFieldNameIterator GetFieldNameIteratorAt(const String & startFieldName, uint32 type = B_ANY_TYPE, uint32 flags = 0) const {return MessageFieldNameIterator(_entries.GetIteratorAt(startFieldName, flags), type);}

protected:
   virtual status_t CopyFromImplementation(const Flattenable & copyFrom);

private:
   // Helper functions
   status_t AddDataAux(const String &name, uint32 type, const void *data, uint32 numBytes, bool prepend);

   // Given a known uint32, returns the size of an item of that type.
   // Returns zero if items of the given type are variable length.
   uint32 GetElementSize(uint32 type) const;

   GenericRef GetArrayRef(const String & arrayName, uint32 etc) const;
   AbstractDataArray * GetArray(const String & arrayName, uint32 etc) const;
   AbstractDataArray * GetOrCreateArray(const String & arrayName, uint32 tc);

   status_t AddFlatBuffer(const String & name, const Flattenable & flat, uint32 etc, bool prepend);
   status_t AddFlatRef(const String & name, const FlatCountableRef & flat, uint32 etc, bool prepend);
   status_t AddDataAux(const String & name, const void * data, uint32 size, uint32 etc, bool prepend);

   status_t FindFlatAux(const String & name, uint32 index, Flattenable & flat) const;
   status_t FindDataItemAux(const String & name, uint32 index, uint32 tc, void * setValue, uint32 valueSize) const;

   status_t ReplaceFlatItemBuffer(bool okayToAdd, const String & name, uint32 index, const Flattenable & flat, uint32 tc);
   status_t ReplaceDataAux(bool okayToAdd, const String & name, uint32 index, void * dataBuf, uint32 bufSize, uint32 tc);
 
   bool FieldsAreSubsetOf(const Message & rhs, bool compareData) const;

   const String * GetExtremeFieldNameStringAux(uint32 optTypeCode, bool isLast) const
   {
      return (optTypeCode == B_ANY_TYPE) ? (isLast ? _entries.GetLastKey() : _entries.GetFirstKey()) 
                                         : MessageFieldNameIterator(*this, optTypeCode, HTIT_FLAG_NOREGISTER|(isLast?HTIT_FLAG_BACKWARDS:0)).GetNextFieldNameString();
   }

   // Iterator support methods
   friend class MessageFieldNameIterator;
   Hashtable<String, GenericRef> _entries;   
};

inline MessageFieldNameIterator :: MessageFieldNameIterator(const Message & msg, uint32 type, uint32 flags) : HashtableIterator<String, GenericRef>(msg._entries.GetIterator(flags)), _typeCode(type) {/* empty */}

END_NAMESPACE(muscle);

#endif /* _MUSCLEMESSAGE_H */

---