WOscReceiver Class Reference

#include <WOscReceiver.h>

Inherits WOscPriorityQueue.

Inherited by WOscTcpHandler.

List of all members.

Public Types

enum  Constants { DEFAULT_QUEUE_CAPACITY = 32 }

Public Member Functions

 WOscReceiver (int initialQueueCapacity=DEFAULT_QUEUE_CAPACITY, WOscSystemTime *systemTime=NULL)
virtual ~WOscReceiver ()
void SetAddressSpace (WOscContainer *addrSpaceRootContainer)
WOscContainerGetAddressSpace ()
void NetworkReceive (const char *data, int dataLen, WOscNetReturn *networkReturnAddress)
void ManagePriorityQueue ()
virtual void NetworkSend (const char *data, int dataLen, const WOscNetReturn *networkReturnAddress)=0

Protected Member Functions

virtual void HandleOffendingPackets (const char *const data, int dataLen, const WOscException &exception)=0
virtual void HandleNonmatchedMessages (const WOscMessage *msg, const WOscNetReturn *networkReturnAddress)=0

Detailed Description

An OSC-receiving-system. The WOscReceiver-class is a complete system for processing incoming OSC-data (i.e. bundles or messages). It queues bundles, which have to be delayed because of their time-tags, unbundles bundles, passes the correct return addresses to the methods or errorhandlers.

The address space can be set dynamically, new methods/containers can be added/removed.

The receiver can be wrapped into a thread easily: Poll periodically for network packets while calling the priority-queue management function ( managePriorityQueue() ). When receiving a network packet, pass it to the networkReceive(char* data, int dataLen, WOscNetReturn *networkReturnAddress) function.

Override the networkSend(char* data, int dataLen, WOscNetReturn *networkReturnAddress) function for providing a network return-path and a handler for defective packets, handleOffendingPackets(char* data, int dataLen, WOscNetReturn *networkReturnAddress)
See also:

WOscClient.cpp, and WOscServer.cpp.

Definition at line 77 of file WOscReceiver.h.

Member Enumeration Documentation

Constants related to a WOscReceiver.


Default capacity of the priority queue.

Definition at line 119 of file WOscReceiver.h.

00119                   {
00120         DEFAULT_QUEUE_CAPACITY = 32,    /**< Default capacity of the priority queue.*/
00121     };

Constructor & Destructor Documentation

WOscReceiver::WOscReceiver ( int  initialQueueCapacity = DEFAULT_QUEUE_CAPACITY,
WOscSystemTime systemTime = NULL 

Constructor. Constructs a receiver and initilizes its priority- queue.

initialQueueCapacity Optional size of priority queue. Grows automatically quadratically if too small.
systemTime Optional system-time object (inherited class from WOscSystemTime) which supplies the receiver with system dependent time information. Passed objects will be deleted by the receiver object destructor.

Definition at line 55 of file WOscReceiver.cpp.

00056                                     : WOscPriorityQueue(initialQueueCapacity)
00057 #else
00058 /** Constructor.
00059  * Constructs a receiver and initilizes its priority-
00060  * queue.
00061  * 
00062  * \param systemTime
00063  * Optional system-time object (inherited class from WOscSystemTime) which
00064  * supplies the receiver with system dependent time information. Passed
00065  * objects will be deleted by the receiver object destructor.
00066  */
00067 WOscReceiver::WOscReceiver(WOscSystemTime* systemTime)
00068 #endif  //  #if WOSC_USE_PRIORITY_QUEUE == 1
00069 /* init inherited class */
00070 {
00071     /* reset address space */
00072     m_addrSpaceRootContainer = NULL;
00074     /* set system time generator to NULL when not specified*/
00075     m_systemTime = systemTime;
00076 }

WOscReceiver::~WOscReceiver (  )  [virtual]

Cleans up the receiver. All elements which are not removed from the priority-queue get deleted automatically.

Definition at line 82 of file WOscReceiver.cpp.

00083 {
00084     if ( m_systemTime ) 
00085         delete m_systemTime;
00086 }

Member Function Documentation

WOscContainer * WOscReceiver::GetAddressSpace (  ) 

Returns the internal address-space reference.

Internal address-space, if there is none NULL.

Definition at line 116 of file WOscReceiver.cpp.

00117 {
00118     return m_addrSpaceRootContainer;
00119 }

virtual void WOscReceiver::HandleNonmatchedMessages ( const WOscMessage msg,
const WOscNetReturn networkReturnAddress 
) [protected, pure virtual]

Handler for OSC messages which didn't match any address in the OSC address space. The user can define an own action by overriding this pure virtual function.

msg Pointer to Message which hasn't been processed.
networkReturnAddress Network address of the sender of this message.

Implemented in WOscTcpClient, and WOscTcpServerHandler.

WOscClient.cpp, and WOscServer.cpp.
virtual void WOscReceiver::HandleOffendingPackets ( const char *const   data,
int  dataLen,
const WOscException exception 
) [protected, pure virtual]

Handler for packets which caused either an internal exception or another error. The user can decide what to do with such packets by overriding this function.

data Pointer to the buffer containing the offending packet data.
dataLen Lenght of the buffer containg the offending packet data.
exception Exception which has been generated during processing this packet.

Implemented in WOscTcpClient, and WOscTcpServerHandler.

WOscClient.cpp, and WOscServer.cpp.

Referenced by ManagePriorityQueue(), and NetworkReceive().

void WOscReceiver::ManagePriorityQueue (  ) 

Keep the internal priority-queue running. If there are any ready-to-process-elements, they are removed from the priority-queue and processed.

WOscException Bundle or message internal exceptions, there should be none. Internal exceptions point to library bugs.
Call this method perodically to keep the priority-queue running.

Definition at line 296 of file WOscReceiver.cpp.

References WOscTimeTag::GetCurrentTime(), WOscPriorityQueue::GetEarliestTimeTag(), WOscPriorityQueue::GetNumItems(), HandleOffendingPackets(), WOscPriorityQueue::RemoveEarliestItem(), WOscQueueItem::RemoveNetworkReturnAddress(), and WOscNetReturn::RemoveParent().

00297 {
00298     // run as long there is something ready
00299     while ( (GetEarliestTimeTag() < WOscTimeTag::GetCurrentTime(m_systemTime) ) && (GetNumItems() > 0) ) {
00300         WOscQueueBundle* bundle = NULL;
00301         WOscNetReturn* netReturn = NULL;
00302         try {
00303             // get element from queue
00304             WOscQueueBundle* bundle = static_cast<WOscQueueBundle*>(RemoveEarliestItem());
00305             // remove network return address from it
00306             netReturn = bundle->RemoveNetworkReturnAddress();
00307             // process it (if it runs through properly also the reference
00308             // counter of netReturn gets decremented
00309             ProcessBundle(bundle->GetData(), bundle->GetDataLen(), netReturn);
00311         } catch(const WOscException& exception) {
00312             // call user defined exception handler
00313             HandleOffendingPackets(NULL, 0, exception);
00314             if ( netReturn )
00315                 netReturn->RemoveParent();
00316         }
00317         delete bundle;
00318     }
00319 }

void WOscReceiver::NetworkReceive ( const char *  data,
int  dataLen,
WOscNetReturn networkReturnAddress 

Parses a received packet, constructs messages and/or bundles of it and passes it to the invocation-engine, which scans the address-space for matching methods, takes care of time-tags and queues bundles, which have to be delayed, in the priority-queue.

data Binary OSC-packet data.
dataLen Length of binary OSC-packet data.
networkReturnAddress Network packet origin.
None,but if an internal exception occurs, the user-defined exception-handler is called, see below.
See also:
handleOffendingPackets(const char* const data, int dataLen, WOscNetReturn networkReturnAddress, WOscException* exception)

Definition at line 143 of file WOscReceiver.cpp.

References HandleOffendingPackets(), and WOscNetReturn::RemoveParent().

00145 {
00146     /* check data length to not read wrong data 
00147      * when guessing OSC-object
00148      */
00149     if ( dataLen < 1 )
00150         return;
00152     // Guess if bundle or message. If bundle, the return address gets managed
00153     // by the bundle and priority-queue. If not, the return-address has to be
00154     // deleted manually after the message has been processed.
00155     if ( data[0] == '#' ){
00156         // probably a bundle. We try to parse it here.
00157         try {
00158             ProcessBundle(data, dataLen, networkReturnAddress);
00159         } catch(const WOscException& exception) {
00160             // call user defined exception handler
00161             HandleOffendingPackets(data, dataLen, exception);
00162             // clean up (no message constructed -> netreturn has to be deleted manually
00163             networkReturnAddress->RemoveParent();
00164             return;
00165         }
00166     } else {
00167         // probably a message -> invoke
00168         try{
00169             ProcessMessage(data, dataLen, networkReturnAddress);
00170         } catch(const WOscException& exception) {
00171             // call user defined exception handler
00172             HandleOffendingPackets(data, dataLen, exception);
00173             // clean up (no message constructed -> netreturn has to be deleted manually
00174             networkReturnAddress->RemoveParent();
00175             return;
00176         }
00178         /* clean up return address.
00179          * if received OSC-object is not a bundle the network-return address 
00180          * is not managed by it and has to be deleted manually.
00181          */
00182         networkReturnAddress->RemoveParent();
00183     }
00184 }

virtual void WOscReceiver::NetworkSend ( const char *  data,
int  dataLen,
const WOscNetReturn networkReturnAddress 
) [pure virtual]

Virtual function which has to be overridden by the user. It then can be used to send OSC messages from within WOscReceiverMethod message callbacks. It is the interface to the network layer for sending messages.

data Pointer to buffer containning the data to be sent.
dataLen Length of the data in the buffer.
networkReturnAddress Destination network address for the data.

Implemented in WOscTcpHandler.

WOscClient.cpp, and WOscServer.cpp.
void WOscReceiver::SetAddressSpace ( WOscContainer addrSpaceRootContainer  ) 

Sets the address-space of the WOscReceiver. The address-space can be modified dynamically and externally, desired, if the root-container remains valid.

addrSpaceRootContainer Root-container. Can not be a child.
WOscException If root-container is not root.
If currently no address-space should be available, pass NULL. This disables the invokation of messages.

Definition at line 103 of file WOscReceiver.cpp.

References ERR_NOT_ROOT_CONTAINER, and WOscContainer::IsRoot().

00104 {
00105     if ( ! addrSpaceRootContainer->IsRoot() )
00106         throw WOscException(ERR_NOT_ROOT_CONTAINER, __FILE__, __LINE__);
00107     m_addrSpaceRootContainer = addrSpaceRootContainer;
00108 }

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