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)
WOscContainer *	GetAddressSpace ()
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.

Remarks:

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:

None.

Examples:

WOscClient.cpp, and WOscServer.cpp.

Definition at line 77 of file WOscReceiver.h.

---

Member Enumeration Documentation

enum WOscReceiver::Constants

Constants related to a WOscReceiver.

Enumerator:

DEFAULT_QUEUE_CAPACITY

Default capacity of the priority queue.

Definition at line 119 of file WOscReceiver.h.

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

---

Constructor & Destructor Documentation

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

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

Parameters:

	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.

                                    : WOscPriorityQueue(initialQueueCapacity)
#else
/** Constructor.
 * Constructs a receiver and initilizes its priority-
 * queue.
 * 
 * \param 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.
 */
WOscReceiver::WOscReceiver(WOscSystemTime* systemTime)
#endif  //  #if WOSC_USE_PRIORITY_QUEUE == 1
/* init inherited class */
{
    /* reset address space */
    m_addrSpaceRootContainer = NULL;

    /* set system time generator to NULL when not specified*/
    m_systemTime = systemTime;
}

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.

{
    if ( m_systemTime ) 
        delete m_systemTime;
}

---

Member Function Documentation

WOscContainer * WOscReceiver::GetAddressSpace

(

)

Returns the internal address-space reference.

Returns:

Internal address-space, if there is none NULL.

Definition at line 116 of file WOscReceiver.cpp.

{
    return m_addrSpaceRootContainer;
}

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.

Parameters:

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

Implemented in WOscTcpClient, and WOscTcpServerHandler.

Examples:

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.

Parameters:

	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.

Examples:

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.

Exceptions:

WOscException

Bundle or message internal exceptions, there should be none. Internal exceptions point to library bugs.

Remarks:

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().

{
    // run as long there is something ready
    while ( (GetEarliestTimeTag() < WOscTimeTag::GetCurrentTime(m_systemTime) ) && (GetNumItems() > 0) ) {
        WOscQueueBundle* bundle = NULL;
        WOscNetReturn* netReturn = NULL;
        try {
            // get element from queue
            WOscQueueBundle* bundle = static_cast<WOscQueueBundle*>(RemoveEarliestItem());
            // remove network return address from it
            netReturn = bundle->RemoveNetworkReturnAddress();
            // process it (if it runs through properly also the reference
            // counter of netReturn gets decremented
            ProcessBundle(bundle->GetData(), bundle->GetDataLen(), netReturn);

        } catch(const WOscException& exception) {
            // call user defined exception handler
            HandleOffendingPackets(NULL, 0, exception);
            if ( netReturn )
                netReturn->RemoveParent();
        }
        delete bundle;
    }
}

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.

Parameters:

	data	Binary OSC-packet data.
	dataLen	Length of binary OSC-packet data.
	networkReturnAddress	Network packet origin.

Exceptions:

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().

{
    /* check data length to not read wrong data 
     * when guessing OSC-object
     */
    if ( dataLen < 1 )
        return;

    // Guess if bundle or message. If bundle, the return address gets managed
    // by the bundle and priority-queue. If not, the return-address has to be
    // deleted manually after the message has been processed.
    if ( data[0] == '#' ){
        // probably a bundle. We try to parse it here.
        try {
            ProcessBundle(data, dataLen, networkReturnAddress);
        } catch(const WOscException& exception) {
            // call user defined exception handler
            HandleOffendingPackets(data, dataLen, exception);
            // clean up (no message constructed -> netreturn has to be deleted manually
            networkReturnAddress->RemoveParent();
            return;
        }
    } else {
        // probably a message -> invoke
        try{
            ProcessMessage(data, dataLen, networkReturnAddress);
        } catch(const WOscException& exception) {
            // call user defined exception handler
            HandleOffendingPackets(data, dataLen, exception);
            // clean up (no message constructed -> netreturn has to be deleted manually
            networkReturnAddress->RemoveParent();
            return;
        }

        /* clean up return address.
         * if received OSC-object is not a bundle the network-return address 
         * is not managed by it and has to be deleted manually.
         */
        networkReturnAddress->RemoveParent();
    }
}

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.

Parameters:

	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.

Examples:

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.

Parameters:

addrSpaceRootContainer

Root-container. Can not be a child.

Exceptions:

WOscException

If root-container is not root.

Remarks:

If currently no address-space should be available, pass NULL. This disables the invokation of messages.

Examples:

WOscStreamingServer.cpp.

Definition at line 103 of file WOscReceiver.cpp.

References ERR_NOT_ROOT_CONTAINER, and WOscContainer::IsRoot().

{
    if ( ! addrSpaceRootContainer->IsRoot() )
        throw WOscException(ERR_NOT_ROOT_CONTAINER, __FILE__, __LINE__);
    m_addrSpaceRootContainer = addrSpaceRootContainer;
}

---

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

• WOscReceiver.h
• WOscReceiver.cpp