WOscBundle Class Reference

#include <WOscBundle.h>

Public Types
enum	Constants { END_OF_BUFFER = -1, BUNDLE_HEADER_SIZE = 8, SIZE_SIZE = 4 }
Public Member Functions
	WOscBundle ()
	WOscBundle (WOscTimeTag timeTag)
virtual	~WOscBundle ()
void	Reset ()
void	Add (WOscBundle *bundle)
void	Add (WOscMessage *message)
int	GetNumMessages ()
int	GetNumBundles ()
WOscMessage *	GetMessage (int idx)
WOscBundle *	GetBundle (int idx)
virtual void	GetBuffer (char *buffer, int bufferLen)
virtual const char *	GetBuffer ()
virtual int	GetBufferLen ()

Detailed Description

An OSC bundle bundles messages and bundles together which have to be invoked at the same time.

Remarks:: A bundle element (Message or Bundle) is saved internally as a reference. If the element is not removed by GetBundle or GetMessage, the destructor cleans them up. This speeds up the passing around of elements because only the references (pointers) have to be managed/copied.

See also:: None.

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

Definition at line 225 of file WOscBundle.h.

Member Enumeration Documentation

enum WOscBundle::Constants

Bundle related constants.

Enumerator:

END_OF_BUFFER	Return value for CheckSize(int relReadPos, int dataLen, const char* rawData) .
BUNDLE_HEADER_SIZE	Size of the "#bundle\0" header at the beginnning of every bundle.
SIZE_SIZE	Size of bundle the bundle "size"-field which comes before every bundle element.

Reimplemented from WOscTimeTag.

Definition at line 250 of file WOscBundle.h.

00250                   {
00251         END_OF_BUFFER = -1,     /**< Return value for CheckSize(int relReadPos, int dataLen, const char* rawData) .*/
00252         BUNDLE_HEADER_SIZE = 8, /**< Size of the "#bundle\0" header at the beginnning of every bundle.*/
00253         SIZE_SIZE = 4,          /**< Size of bundle the bundle "size"-field which comes before every bundle element.*/
00254     };

Constructor & Destructor Documentation

WOscBundle::WOscBundle ( )

Construct an empty bundle. The network return address of its base-class is initialized with NULL. The WOscTimeTag of the queue item will be 'immediate'.

Definition at line 61 of file WOscBundle.cpp.

00061                        : WOscTimeTag(WOscTimeTag::GetImmediateTime())
00062 {
00063     InitEmpty();
00064 }

WOscBundle::WOscBundle ( WOscTimeTag timeTag )

Construct an empty bundle and tag it with a time-tag. The network return address of its base-class is initialized with NULL.

Parameters:

timeTag

Tagging time-tag.

Definition at line 52 of file WOscBundle.cpp.

00052                                           : WOscTimeTag(timeTag)
00053 { 
00054     InitEmpty();
00055 }

WOscBundle::~WOscBundle ( ) [virtual]

Destructor. Cleans up all messages and bundles which have not been removed by GetBundle or GetMessage .

Cleans up the buffer when it was used (invokation of one of the getBuffer(...)-members).

Definition at line 74 of file WOscBundle.cpp.

00074                        {
00075     
00076     /* clean up buffer */
00077     if ( m_buffer )
00078         delete [] m_buffer;
00079 
00080     /* clean up leftover elements */
00081     if ( m_messages ){
00082         for( int i = 0; i < m_numMessages; i++ )
00083             delete m_messages[i];
00084         delete [] m_messages;
00085     }
00086     if ( m_bundles ){
00087         for( int i = 0; i < m_numBundles; i++ )
00088             delete m_bundles[i];
00089         delete [] m_bundles;
00090     }
00091 }

Member Function Documentation

void WOscBundle::Add ( WOscMessage * message )

Adds an OSC-message to the bundle. The internal element counter is increased and the message is added.

Parameters:

message

Pointer of the message to be added. The bundle deallocates it on deletion.

Definition at line 212 of file WOscBundle.cpp.

00212                                         {
00213     if ( !m_messages ){
00214         m_messages = new WOscMessage*[1];
00215         m_messages[0] = message;
00216         m_numMessages++;
00217     }else{
00218         m_numMessages++;
00219         WOscMessage** newMsgArray = new WOscMessage*[m_numMessages];
00220         for( int i = 0; i < m_numMessages-1; i++ )
00221             newMsgArray[i] = m_messages[i];
00222         newMsgArray[m_numMessages-1] = message;
00223         delete [] m_messages;
00224         m_messages = newMsgArray;
00225     }
00226 }

void WOscBundle::Add ( WOscBundle * bundle )

Adds an OSC-bundle to the bundle. The internal element counter is increased and the bundle is added.

Parameters:

bundle

Reference of the bundle to be added.

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

Definition at line 187 of file WOscBundle.cpp.

00187                                       {
00188     if ( !m_bundles ){
00189         m_bundles = new WOscBundle*[1];
00190         m_bundles[0] = bundle;
00191         m_numBundles++;
00192     }else{
00193         m_numBundles++;
00194         WOscBundle** newBndlArray = new WOscBundle*[m_numBundles];
00195         for( int i = 0; i < m_numBundles-1; i++ )
00196             newBndlArray[i] = m_bundles[i];
00197         newBndlArray[m_numBundles-1] = bundle;
00198 
00199         delete [] m_bundles;
00200         m_bundles = newBndlArray;
00201     }
00202 }

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

Generates internal buffer filled with the binary representation of the bundle. The buffer-size can be queried through "getBufferLen()".

Returns:: A temporary pointer to the binary representation of the bundle.

Remarks:: The pointer remains valid until the next time an element will be added to the bundle, the bundle is destination of an operation (check operators), the bundle will be deleted or one of the getBuffer functions is called. If you are not sure about that issue, please use the other getBuffer function.

See also:: WOscBundle::getBuffer(char* buffer, int bufferLen)

Implements WOscPacket.

Definition at line 378 of file WOscBundle.cpp.

00378                                  {
00379 
00380     if (m_buffer){
00381         delete [] m_buffer;
00382         m_buffer = NULL;
00383     }
00384 
00385     /* generate bundle buffer */
00386     GenerateBufferFromElements();
00387 
00388     /* user cleans up */
00389     return m_buffer;
00390 }

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

Fills the buffer with the raw bytestream of this packet.

Parameters:

	buffer	Description of parameter buffer.
	bufferLen	Description of parameter bufferLen.

Exceptions:

<exception

class> Description of criteria for throwing this exception.

Write detailed description for getBuffer here.

Remarks:: Write remarks for getBuffer here.

See also:: Separate items with the '|' character.

Implements WOscPacket.

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

Definition at line 339 of file WOscBundle.cpp.

References ERR_BUFFER_TO_SMALL.

00339                                                      {
00340     if (m_buffer){
00341         delete [] m_buffer;
00342         m_buffer = NULL;
00343     }
00344 
00345     /* generate bundle buffer */
00346     GenerateBufferFromElements();
00347 
00348     /* copy buffer */
00349     if ( m_bufferSize > bufferLen ){
00350         /* clean up */
00351         delete m_buffer;
00352         m_buffer = NULL;
00353         m_bufferSize = 0;
00354         throw WOscException(ERR_BUFFER_TO_SMALL, __FILE__, __LINE__);
00355     }
00356     memcpy(buffer, m_buffer, m_bufferSize);
00357 
00358 }

int WOscBundle::GetBufferLen ( ) [virtual]

Returns the required buffer size when calling WOscBundle::getBuffer(char* buffer, int bufferLen). Use for determine the right buffer size when using WOscBundle::getBuffer(char* buffer, int bufferLen) or getting size of the the buffer when called char* WOscBundle::getBuffer().

Returns:: Length of the required buffer size for calling

Implements WOscPacket.

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

Definition at line 399 of file WOscBundle.cpp.

References BUNDLE_HEADER_SIZE, SIZE_SIZE, and WOscTimeTag::TIME_TAG_SIZE.

00399                             {
00400     int bufSize, i;
00401 
00402     bufSize =  BUNDLE_HEADER_SIZE + WOscTimeTag::TIME_TAG_SIZE;
00403 
00404     for ( i = 0; i < m_numMessages; i++ )
00405         bufSize += SIZE_SIZE + m_messages[i]->GetBufferLen();
00406 
00407     for ( i = 0; i < m_numBundles; i++ )
00408         bufSize += SIZE_SIZE + m_bundles[i]->GetBufferLen();
00409 
00410     return bufSize;
00411 }

WOscBundle * WOscBundle::GetBundle ( int idx )

Returns a reference of a specific sub-bundle contained in the bundle. Removes the reference from the internal reference array (the desctructor does not remove it when the bundle is destoyed).

Parameters:

idx

Index of the subbundle in the subbundle array. The number of subbundles contained in this array can be queried by WOscBundle::GetNumBundles() .

Returns:: Reference of the element (a subbundle) with index 'idx'.

Exceptions:

WOscException

If index lies out of the array bounds (i.e. < 0 and >= GetNumBundles())

Remarks:: Subbundles which were removed with this interface will not deleted by the bundle-destructor. The caller must keep track of them.

See also:: WOscBundle::GetNumBundles() | WOscMessage* WOscBundle::GetMessage(int idx)

Definition at line 307 of file WOscBundle.cpp.

References ERR_INVALID_INDEX.

00307                                         {
00308     if ( idx < 0 || idx >= m_numBundles )
00309         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00310     else{
00311         WOscBundle* retBundle =  m_bundles[idx]; // copy bundle reference
00312         RemoveBundle(idx); // remove bundle from reference list
00313 
00314         /* return reference */
00315         return retBundle;
00316     }
00317 }

WOscMessage * WOscBundle::GetMessage ( int idx )

Returns a reference of a specific message contained in the bundle. Removes the reference from the internal reference array.

Parameters:

idx

Index of the message in the message array. The number of messages contained in this array can be queried by GetNumMessages() .

Returns:: Reference of the element with index 'idx'

Exceptions:

WOscException

If index lies out of the array bounds (i.e. < 0 and >= GetNumMessages())

Remarks:: Messages which were removed with this interface will not deleted by the bundles destructor. The caller must keep track of them.

See also:: GetNumMessages()

Definition at line 276 of file WOscBundle.cpp.

References ERR_INVALID_INDEX.

00276                                           {
00277     if ( idx < 0 || idx >= m_numMessages )
00278         throw WOscException(ERR_INVALID_INDEX, __FILE__, __LINE__);
00279     else{
00280         WOscMessage* retMsg = m_messages[idx]; // copy message reference
00281         RemoveMessage(idx); // remove message from reference list
00282         return retMsg; // return reference
00283     }
00284 }

int WOscBundle::GetNumBundles ( )

Returns the number of bundles contained in this bundle. Before extracting bundles, get the number of bundle-internal bundles to avoid access-exceptions.

Returns:: The number of bundles contained in this bundle.

See also:: WOscBundle::GetBundle(int idx)

Definition at line 252 of file WOscBundle.cpp.

00252                              {
00253     return m_numBundles;
00254 }

int WOscBundle::GetNumMessages ( )

Returns the number of messages contained in this bundle. Before extracting messages, get the number of bundle-internal messages to avoid access-exceptions.

Returns:: The number of messages contained in this bundle.

See also:: WOscBundle::GetMessage(int idx)

Definition at line 238 of file WOscBundle.cpp.

00238                               {
00239     return m_numMessages;
00240 }

The documentation for this class was generated from the following files:

WOscBundle Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation