WOscMessage Class Reference

#include <WOscMessage.h>

Inherits WOscPacket.

List of all members.

Public Member Functions

 WOscMessage (const char *address)
 WOscMessage (const char *buffer, int bufferLen)
 WOscMessage (const WOscMessage *message)
 WOscMessage (const WOscMessage &rhs)
WOscMessageoperator= (const WOscMessage &rhs)
WOscMessageoperator+= (const WOscMessage &rhs)
WOscMessage operator+ (const WOscMessage &rhs)
virtual ~WOscMessage ()
void Add (float f)
void Add (int intArg)
void Add (const char *s)
void Add (WOscString &s)
void Add (WOscBlob *b)
int GetNumFloats () const
int GetNumInts () const
int GetNumStrings () const
int GetNumBlobs () const
const WOscStringGetOscAddress () const
const WOscStringGetOscTypeTag () const
float GetFloat (int idx) const
int GetInt (int idx) const
const WOscStringGetString (int idx) const
const WOscBlobGetBlob (int idx) const
void GetBuffer (char *buffer, int bufferLen)
virtual const char * GetBuffer ()
int GetBufferLen ()

Detailed Description

OSC-message containing type-tag and OSC-arguments.

Osc arguments can be added by using the add function.

Remarks:
The order of the added items can be reconstructed: The first integer added will be accessible with the first index when using getInt(int idx)
Examples:

WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 59 of file WOscMessage.h.


Constructor & Destructor Documentation

WOscMessage::WOscMessage ( const char *  address  ) 

Initialize an OSC-message with an OSC address. Constructs an OSC message without arguments what produces an "empty" type tag (",\0\0\0"). To add arguments, call add(int intArg) or similar.

Parameters:
address String with OSC address.
Exceptions:
WOscException If address is NULL or if address does not begin with a slash.
Remarks:
None.
See also:
WOscMessage::add(float floatArg) etc.
Todo:
Check complete OSC-address-syntax

Definition at line 71 of file WOscMessage.cpp.

References ERR_INVALID_ADDRESS_NO_SLASH, ERR_NULL_ADDRESS, W_OSC_EMPTY_TYPE_TAG, and WOscMessage().

Referenced by WOscMessage().

00071                                            {
00072 
00073     // check if valid address
00074     if ( address == NULL )
00075         throw WOscException(ERR_NULL_ADDRESS, __FILE__, __LINE__);
00076 
00077     if ( address[0] != '/' )
00078         throw WOscException(ERR_INVALID_ADDRESS_NO_SLASH, __FILE__, __LINE__);
00079 
00080     // init address
00081     m_address = address;
00082 
00083     // init type tag
00084     m_typeTag = W_OSC_EMPTY_TYPE_TAG;
00085 
00086     m_floats        = NULL;
00087     m_numFloats     = 0;
00088     m_ints          = NULL;
00089     m_numInts       = 0;
00090     m_strings       = NULL;
00091     m_numStrings    = 0;
00092     m_blobs         = NULL;
00093     m_numBlobs      = 0;
00094 
00095     m_buffer = NULL;
00096 
00097     GenerateBufferFromMembers();
00098 }

WOscMessage::WOscMessage ( const char *  buffer,
int  bufferLen 
)

Initialize an OSC-message with a raw byte-stream (for instance from a network receiver). The message object is reassembled from binary data. The length must be known. When successfully reassembled, the arguments (when existing) are accessable via the getNumXXX() and getXXX(int idx) interface functions.

Parameters:
buffer Packet data containing the whole message with arguments.
bufferLen Packet data length.
Exceptions:
WOscException When corrupt initialization data, inconsistent bufferlengths etc. found.
Todo:
Since a message is defined, when its beginning is known creating it from a byte stream without knowing the length would be possible. Write an initializer.
Remarks:
If an exception occurs, the construction of the message will be aborted, including the arguments.
Todo:
Add intensive exception handling for corrupt init data
See also:
WOscException | WOscString

Definition at line 130 of file WOscMessage.cpp.

References Add(), ERR_INVALID_ADDRESS_NO_SLASH, ERR_NULL_BUFFER, WOscString::GetBuffer(), WOscBlob::GetBufferLen(), WOscString::GetSize(), WOscUtil::OSC_FLOAT_SIZE, WOscUtil::OSC_INT_SIZE, W_OSC_EMPTY_TYPE_TAG, and WOscMessage().

00130                                                          {
00131 
00132     m_floats        = NULL;
00133     m_numFloats     = 0;
00134     m_ints          = NULL;
00135     m_numInts       = 0;
00136     m_strings       = NULL;
00137     m_numStrings    = 0;
00138     m_blobs         = NULL;
00139     m_numBlobs      = 0;
00140 
00141     m_buffer = NULL;
00142 
00143     // check address
00144     if (bufferLen < 1)
00145         throw WOscException(ERR_NULL_BUFFER, __FILE__, __LINE__);
00146     // check address
00147     if (buffer[0] != '/')
00148         throw WOscException(ERR_INVALID_ADDRESS_NO_SLASH, __FILE__, __LINE__);
00149 
00150     // extract address
00151     m_address = buffer;
00152 
00153     // get type tag
00154     int pos = m_address.GetSize();
00155 
00156     m_typeTag = W_OSC_EMPTY_TYPE_TAG; // init type tag
00157     
00158 
00159     if (bufferLen <= pos){
00160         // no type tag in buffer -> leave empty type tag
00161         GenerateBufferFromMembers();
00162         return;
00163     }
00164 
00165     WOscString OscTypeTag = buffer + pos;
00166 
00167     // get args by scanning typetag string
00168     const char* typeTag = OscTypeTag.GetBuffer();
00169     int typeTagSize = OscTypeTag.GetSize();
00170     pos += typeTagSize; // offset in buffer (beginning of argument data)
00171 
00172     for ( int i = 0; i < typeTagSize; i++ ){
00173         switch (typeTag[i]){
00174             case 'i':
00175                 Add(WOscUtil::BufferTo<int>(buffer + pos));
00176                 pos += WOscUtil::OSC_INT_SIZE;
00177                 break;
00178             case 'f':
00179                 Add(WOscUtil::BufferTo<float>(buffer + pos));
00180                 pos += WOscUtil::OSC_FLOAT_SIZE;
00181                 break;
00182             case 's':
00183                 Add(buffer+pos);
00184                 pos += m_strings[m_numStrings-1].GetSize();
00185                 break;
00186             case 'b':{
00187                 WOscBlob* blob = new WOscBlob(buffer + pos);
00188                 Add( blob );
00189                 pos += blob->GetBufferLen();
00190                 delete blob;
00191                 break;
00192                      }
00193 
00194             case ',':
00195                 break;
00196             case '\0':
00197                 i = typeTagSize; // jump to end
00198                 break;
00199             default: // error
00200                 i = typeTagSize; // jump to end
00201                 break;
00202         }
00203     }
00204 
00205     GenerateBufferFromMembers(); // generate arrays of arguments for later use with getXXX(int idx)
00206 }

WOscMessage::WOscMessage ( const WOscMessage message  ) 

Copy construction by pointer. The same as WOscMessage::WOscMessage(WOscMessage& rhs) but with pointer as parameter.

Parameters:
message Pointer to the object, which should be used as copying source.
See also:
WOscMessage::WOscMessage(WOscMessage& rhs)

Definition at line 304 of file WOscMessage.cpp.

References WOscMessage().

00304                                                   {
00305     Copy(*message);
00306 }

WOscMessage::WOscMessage ( const WOscMessage rhs  ) 

Copy constructor. Initializes a new WOscMessage-object by copying data from another, allready existing object.

Parameters:
rhs Reference of the initializing object.

Definition at line 236 of file WOscMessage.cpp.

References WOscMessage().

00236                                               {
00237     Copy(rhs);
00238 }

WOscMessage::~WOscMessage (  )  [virtual]

Cleans up. Since the OSC-address and the type-tag are automatic, only the dynamic array members and buffers have to be cleaned up.

Definition at line 213 of file WOscMessage.cpp.

00213                          {
00214 
00215     if ( m_buffer )
00216         delete [] m_buffer;
00217 
00218     if (m_floats) delete [] m_floats;
00219     if (m_ints) delete [] m_ints;
00220     if (m_strings) delete [] m_strings;
00221     if (m_blobs){
00222         for(int i=0; i<m_numBlobs; i++)
00223             delete m_blobs[i];
00224         delete [] m_blobs;
00225     }
00226 
00227 }


Member Function Documentation

void WOscMessage::Add ( WOscBlob b  ) 

Adds a n OSC-blob to the current message. Inserts it in the type tag and adds it to the string array.

Parameters:
b Pointer to a OSC-blob message-argument to be added.
Remarks:
Because the typetags are appended to the end of the typetag, the order of the arguments can be reconstructed always. perhaps in later versions only the references of a blob are
Todo:
: take ownership of blob or do reference counting instead of allocating multiple times.

Definition at line 617 of file WOscMessage.cpp.

00617                                 {
00618     m_typeTag += 'b';
00619 
00620     if ( m_blobs ){
00621         m_numBlobs++;
00622         WOscBlob** newBlobs = new WOscBlob*[m_numStrings];
00623         for( int i = 0; i < m_numBlobs-1; i++ )
00624             newBlobs[i] = m_blobs[i]; // copy old pointers
00625         newBlobs[m_numBlobs-1] = new WOscBlob(b); // add new element
00626         delete [] m_blobs; // delete old array
00627         m_blobs = newBlobs; // assign new array
00628     }else{
00629         m_blobs = new WOscBlob*[1];
00630         m_blobs[0] = new WOscBlob(b);
00631         m_numBlobs++;
00632     }
00633     GenerateBufferFromMembers();
00634 }

void WOscMessage::Add ( WOscString s  ) 

Adds a string to the current message. Inserts it in the type tag and adds it to the string array.

Parameters:
s String message-argument to be added.
Exceptions:
None. 
Remarks:
Because the typetags are appended to the end of the typetag, the order of the arguments can be reconstructed always.

Definition at line 582 of file WOscMessage.cpp.

00582                                   {
00583 
00584     m_typeTag += 's';
00585 
00586     if ( m_strings == NULL ){
00587         m_strings = new WOscString[1];
00588         m_strings[0] = s;
00589         m_numStrings = 1;
00590     }else{
00591         m_numStrings++;
00592         WOscString* newStrings = new WOscString[m_numStrings];
00593         for( int i = 0; i < m_numStrings-1; i++ )
00594             newStrings[i] = m_strings[i];
00595         newStrings[m_numStrings-1] = s;
00596         delete [] m_strings;
00597         m_strings = newStrings;
00598     }
00599     GenerateBufferFromMembers();
00600 }

void WOscMessage::Add ( const char *  s  ) 

Adds a string to the current message. Inserts it in the type tag and adds it to the string array.

Parameters:
s String message-argument to be added.
Remarks:
Because the typetags are appended to the end of the typetag, the order of the arguments can be reconstructed always.

Definition at line 550 of file WOscMessage.cpp.

00550                                   { 
00551     m_typeTag += 's';
00552 
00553     if ( m_strings == NULL ){
00554         m_strings = new WOscString[1];
00555         m_strings[0] = s;
00556         m_numStrings = 1;
00557     }else{
00558         m_numStrings++;
00559         WOscString* newStrings = new WOscString[m_numStrings];
00560         for( int i = 0; i < m_numStrings-1; i++ )
00561             newStrings[i] = m_strings[i];
00562         newStrings[m_numStrings-1] = s;
00563         delete [] m_strings;
00564         m_strings = newStrings;
00565     }
00566     GenerateBufferFromMembers();
00567 }

void WOscMessage::Add ( int  intArg  ) 

Adds an integer to the current message. Inserts it in the type tag and adds it to the integer array.

Parameters:
intArg Integer message-argument to be added.
Remarks:
Because the typetags are appended to the end of the typetag, the order of the arguments can be reconstructed always.

Definition at line 519 of file WOscMessage.cpp.

00519                                {
00520 
00521     m_typeTag += 'i';
00522 
00523     if ( m_ints == NULL ){
00524         m_ints = new int[1];
00525         m_ints[0] = intArg;
00526         m_numInts = 1;
00527     }else{
00528         m_numInts++;
00529         int* newInts = new int[m_numInts];
00530         for( int i = 0; i < m_numInts-1; i++ )
00531             newInts[i] = m_ints[i];
00532         newInts[m_numInts-1] = intArg;
00533         delete [] m_ints;
00534         m_ints = newInts;
00535     }
00536     GenerateBufferFromMembers();
00537 }

void WOscMessage::Add ( float  floatArg  ) 

Adds a float to the current message. Inserts it in the type tag and adds it to the float array.

Parameters:
floatArg Float message-argument to be added.
Remarks:
Because the typetags are appended to the end of the typetag, the order of the arguments can be reconstructed always.
Examples:
WOscClient.cpp, and WOscStreamingClient.cpp.

Definition at line 488 of file WOscMessage.cpp.

Referenced by WOscMessage().

00488                                    {
00489     
00490     m_typeTag += 'f';
00491 
00492     if ( m_floats == NULL ){
00493         m_floats = new float[1];
00494         m_floats[0] = floatArg;
00495         m_numFloats = 1;
00496     }else{
00497         m_numFloats++;
00498         float* newFloats = new float[m_numFloats];
00499         for( int i = 0; i < m_numFloats-1; i++ )
00500             newFloats[i] = m_floats[i];
00501         newFloats[m_numFloats-1] = floatArg;
00502         delete [] m_floats;
00503         m_floats = newFloats;
00504     }
00505     GenerateBufferFromMembers();
00506 }

const WOscBlob * WOscMessage::GetBlob ( int  idx  )  const

Returns a pointer to the WOscBlob argument with the index 'idx'. Argument data is kept internally in array data-structures. This function is an safe interface.

Parameters:
idx Index of the WOscBlob-argument contained in the message.
Returns:
The WOscBlob-argument with index "idx".
Exceptions:
WOscException When idx is bigger than the number of WOscBlob-arguments contained in the message an exception will be thrown.
See also:
WOscException::ErrorCodes | WOscBlob

Definition at line 780 of file WOscMessage.cpp.

References ERR_INVALID_INDEX.

00781 {
00782     if ( idx > m_numBlobs )
00783         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00784     return m_blobs[idx];
00785 }

const char * WOscMessage::GetBuffer (  )  [virtual]

Returns a pointer to an internal buffer containing the current binary representation of this message. Please See remarks for safety issues.

Returns:
Pointer to internal array data.
Remarks:
The pointer remains valid until the modification of this message object. The next time an argument will be added to the message, the message is destination of an operation (check operators), the message will be deleted or one of the getBuffer functions is called this pointer gets invalid. If you are not sure about that issue, please use the other getBuffer()- function.
See also:
WOscMessage::getBuffer(char* buffer, int bufferLen)

Implements WOscPacket.

Definition at line 833 of file WOscMessage.cpp.

00833                                   {
00834     return m_buffer;
00835 }

void WOscMessage::GetBuffer ( char *  buffer,
int  bufferLen 
) [virtual]

Fills the buffer with the raw bytestream of this packet. The user must supply the buffer of apropriate size.

Parameters:
buffer Caller supplied destination buffer.
bufferLen Length of the supplied buffer.
Exceptions:
WOscException When caller supplied buffer too small.
Remarks:
This interface makes sure that the buffer remains valid when modifying the message-object afterwards. (contrary to WOscMessage::getBuffer() )
See also:
WOscMessage::getBuffer()

Implements WOscPacket.

Examples:
WOscClient.cpp, WOscServer.cpp, and WOscStreamingClient.cpp.

Definition at line 808 of file WOscMessage.cpp.

References ERR_OSC_STR_BUFF_TOO_SMALL.

00809 {
00810     if ( bufferLen < m_bufferLen )
00811         throw WOscException(ERR_OSC_STR_BUFF_TOO_SMALL, __FILE__, __LINE__);
00812     for ( int i = 0; i < bufferLen; i++ )
00813         buffer[i] = m_buffer[i];
00814 }

int WOscMessage::GetBufferLen (  )  [virtual]

Returns the size of the binary message representation. Can be used to allocate memory for instance.

Returns:
Size of the internal binary buffer.
Remarks:
Remains valid: see remarks of WOscMessage::getBuffer().

Implements WOscPacket.

Examples:
WOscClient.cpp, WOscServer.cpp, and WOscStreamingClient.cpp.

Definition at line 846 of file WOscMessage.cpp.

00846                               {
00847     return m_bufferLen;
00848 }

float WOscMessage::GetFloat ( int  idx  )  const

Returns the float argument with the index 'idx'. Argument data is kept internally in array data-structures. This function is an safe interface.

Parameters:
idx Index of float argument contained in the message.
Returns:
The float with index "idx".
Exceptions:
WOscException When idx is bigger than the number of floats contained in the message an exception will be thrown.
See also:
WOscException::ErrorCodes
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 707 of file WOscMessage.cpp.

References ERR_INVALID_INDEX.

00708 {
00709     if ( idx > m_numFloats )
00710         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00711     return m_floats[idx];
00712 }

int WOscMessage::GetInt ( int  idx  )  const

Returns the integer argument with the index 'idx'. Argument data is kept internally in array data-structures. This function is an safe interface.

Parameters:
idx Index of integer argument contained in the message.
Returns:
The integer with index "idx".
Exceptions:
WOscException When idx is bigger than the number of integers contained in the message an exception will be thrown.
See also:
WOscException::ErrorCodes
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 732 of file WOscMessage.cpp.

References ERR_INVALID_INDEX.

00733 {
00734     if ( idx > m_numInts )
00735         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00736     return m_ints[idx];
00737 }

int WOscMessage::GetNumBlobs (  )  const

Returns the number of OSC-blob arguments contained in this message. Use it for accessing arguments without generating out-of-bound-exceptions ( take a look at WOscException::ErrorCodes and the corresponding ERR_INVALID_INDEX code).

Returns:
The number of OSC-blob arguments contained in this message.

Definition at line 683 of file WOscMessage.cpp.

00683                                    {
00684     return m_numBlobs;
00685 }

int WOscMessage::GetNumFloats (  )  const

Returns the number of floating-point arguments contained in this message. Use it for accessing arguments without generating out-of-bound-exceptions ( take a look at WOscException::ErrorCodes and the corresponding ERR_INVALID_INDEX code).

Returns:
The number of floating-point arguments contained in this message.
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 645 of file WOscMessage.cpp.

00645                                     {
00646     return m_numFloats;
00647 }

int WOscMessage::GetNumInts (  )  const

Returns the number of integer arguments contained in this message. Use it for accessing arguments without generating out-of-bound-exceptions ( take a look at WOscException::ErrorCodes and the corresponding ERR_INVALID_INDEX code).

Returns:
The number of integer arguments condained in this message.
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 658 of file WOscMessage.cpp.

00658                                   {
00659     return m_numInts;
00660 }

int WOscMessage::GetNumStrings (  )  const

Returns the number of string arguments contained in this message. Use it for accessing arguments without generating out-of-bound-exceptions ( take a look at WOscException::ErrorCodes and the corresponding ERR_INVALID_INDEX code).

Returns:
The number of string arguments contained in this message.
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 671 of file WOscMessage.cpp.

00671                                      {
00672     return m_numStrings;
00673 }

const WOscString & WOscMessage::GetOscAddress (  )  const

Returns the OSC address of this message.

Returns:
OSC string containing the OSC address.
Examples:
WOscClient.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 857 of file WOscMessage.cpp.

Referenced by WOscContainer::DispatchMessage().

00858 {
00859     return m_address;
00860 }

const WOscString & WOscMessage::GetString ( int  idx  )  const

Returns the WOscString argument with the index 'idx'. Argument data is kept internally in array data-structures. This function is an safe interface.

Parameters:
idx Index of the WOscString-argument contained in the message.
Returns:
The WOscString-argument with index "idx".
Exceptions:
WOscException When idx is bigger than the number of WOscString-arguments contained in the message an exception will be thrown.
See also:
WOscException::ErrorCodes | WOscString
Examples:
WOscClient.cpp, WOscServer.cpp, WOscStreamingClient.cpp, and WOscStreamingServer.cpp.

Definition at line 756 of file WOscMessage.cpp.

References ERR_INVALID_INDEX.

00756                                                       {
00757     if ( idx > m_numStrings )
00758         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00759     return m_strings[idx];
00760 }

WOscMessage WOscMessage::operator+ ( const WOscMessage rhs  ) 

Merges two messages but does not overwrite the left hand side object. The same as WOscMessage::operator+= (WOscMessage& rhs) but it does not modify the lhs object.

Parameters:
rhs Reference to class which arguments should be merged into the combined class.
Returns:
The merged version of the lhs and rhs objects.
See also:
WOscMessage::operator+= (WOscMessage& rhs)

Definition at line 288 of file WOscMessage.cpp.

00288                                                          {
00289     WOscMessage tmp(*this);
00290     tmp += rhs;
00291     return tmp;
00292 }

WOscMessage & WOscMessage::operator+= ( const WOscMessage rhs  ) 

Merges the arguments of two messages, the right hand address will be ignored. Merges the right hand side (rhs) object reference into the left hand side (lhs) object and returns a reference to it. The merging keeps the argument order of both messages but only the OSC-address of the lhs object remains. The order of the arguments of the resulting message is: First the lhs arguments in its prior order the the rhs arguments in its prior order.

Parameters:
rhs Reference to class which arguments should be merged into this class.
Returns:
A reference to the merged (this) class.

Definition at line 268 of file WOscMessage.cpp.

00268                                                            {
00269     // merge messages   
00270     return *this;
00271 }

WOscMessage & WOscMessage::operator= ( const WOscMessage rhs  ) 

Copy operator. Overwrites the content of a WOscMessage-object by copying data from another, allready existing object.

Parameters:
rhs Initializing object (Right Hand Side).
Returns:
The reference to the initialized object (allows nesting).

Definition at line 249 of file WOscMessage.cpp.

00249                                                           {
00250     Copy(rhs);
00251     return *this;
00252 }


The documentation for this class was generated from the following files:
Generated on Sat Oct 23 03:05:59 2010 for WOscLib by  doxygen 1.6.3