WOscContainer Class Reference

#include <WOscContainer.h>

Inherits WOscPatternMatch.

List of all members.

Public Member Functions
	WOscContainer (const WOscContainerInfo &info=WOscContainerInfo("root container"), int defNumChildren=32, int defNumMethods=32)
	WOscContainer (WOscContainer *parent, const char *name, const WOscContainerInfo &info=WOscContainerInfo(), int defNumChildren=32, int defNumMethods=32)
void	AddContainerAlias (WOscContainer *parent, const char *alias)
void	DispatchMessage (WOscCallbackList &methods, WOscMessage *msg)
WOscString	GetName () const
WOscString	GetAddress () const
WOscString	GetAddressSpace () const
WOscString	GetMethodList () const
const WOscContainer *	FindContainer (const char *address) const
bool	RemoveContainer (const char *name)
bool	RemoveMethod (const char *name)
const WOscContainer *	FindRoot () const
bool	IsRoot () const
void	RemoveAll ()
Friends
class	WOscMethod

---

Detailed Description

OSC Address-space node. An OSC-address space consists of a tree of containers with methods as leaves.

Todo:

More elaborate documentation of WOscContainer class.

Remarks:

ALL CONTAINERS EXCEPT THE ROOT CONTAINER MUST BE ALLOCATED DYNAMICALLY, since the root container deletes all its children during its destruction!!

See also:

See the examples for address-tree generation and deletion.

Examples:

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

Definition at line 104 of file WOscContainer.h.

---

Constructor & Destructor Documentation

WOscContainer::WOscContainer	(	const WOscContainerInfo &	info = WOscContainerInfo("root container"),
		int	defNumChildren = 32,
		int	defNumMethods = 32
	)

Constructor for a root container. Root container do not have parents (what's implicated by the name). The root-container is responsible for clean-up. Deletion is not allowed for WOscContainer and WOscMethod objects. The address space can be removed only as whole or be manipulated by dedicated functions.

Parameters:

	info	Container information.
	defNumChildren	Default internal array-size for children-references. If not sufficient during later use, the array-sizes double themselves automatically.
	defNumMethods	See parameter defNumChildren.

Definition at line 67 of file WOscContainer.cpp.

{

    /* a root container does not have any parents */
    m_parent = NULL;

    m_containerEntries.reserve(defNumChildren);
    m_methodEntries.reserve(defNumMethods);

    /* container info */
    m_info = info;
}

WOscContainer::WOscContainer	(	WOscContainer *	parent,
		const char *	name,
		const WOscContainerInfo &	info = WOscContainerInfo(),
		int	defNumChildren = 32,
		int	defNumMethods = 32
	)

Constructor for child containers. Child containers must supply a parent. They get added to the parent-container list of children and can be parents if constructed.

Parameters:

	info	Container information.
	parent	Pointer to the parent-container. Must not be NULL.
	name	OSC-pattern with the name of the container. This name will be later a part of the OSC-address (/the/"name"/of/mama/mia/is/method ...). If WOSC_ADDR_WILDCARDS is defined 1, wildcard matching will be performed on the address path segments.
	defNumChildren	(Optional) See WOscContainer::WOscContainer(WOscContainerInfo* info, int defNumChildren, int defNumMethods)
	defNumMethods	(Optional) See WOscContainer::WOscContainer(WOscContainerInfo* info, int defNumChildren, int defNumMethods)

Exceptions:

WOscException

If parent pointer NULL. That's illegal. Children should have parents

See also:

WOscContainer::WOscContainer(WOscContainerInfo* info, int defNumChildren , int defNumMethods )

Definition at line 108 of file WOscContainer.cpp.

References ERR_PARENT_POINTER_NULL.

                                                                                                                                         {

    if ( parent == NULL )
        throw WOscException(ERR_PARENT_POINTER_NULL, __FILE__, __LINE__);

    m_parent    = parent;
    m_info      = info;

    m_containerEntries.reserve(defNumChildren);
    m_methodEntries.reserve(defNumMethods);

    m_parent->AddContainer(this, name, false);
}

---

Member Function Documentation

void WOscContainer::AddContainerAlias	(	WOscContainer *	parent,
		const char *	alias
	)

Adds an alias of this container to the parent list-of-children.

Parameters:

	parent	Pointer to container, which becomes the parent of the alias.
	alias	New name of container under which the parent saves the alias.

Exceptions:

WOscException

When this container is the root-container, the root-container can not be aliased. When the parent pointer is this container itself. When invalid parent-container pointer (NULL) is passed.

Remarks:

Aliases are not real children and won't be deleted during recursive deletion.

Examples:

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

Definition at line 191 of file WOscContainer.cpp.

References ERR_PARENT_POINTER_NULL, and ERR_RECURSIVE_ALIAS.

{
    if ( m_parent == NULL )
        throw WOscException(ERR_ROOT_ALIAS, __FILE__, __LINE__);

    if ( parent == this )
        throw WOscException(ERR_RECURSIVE_ALIAS, __FILE__, __LINE__);
    
    if ( parent == NULL ) 
        throw WOscException(ERR_PARENT_POINTER_NULL, __FILE__, __LINE__);

    parent->AddContainer(this, alias, true);
}

void WOscContainer::DispatchMessage	(	WOscCallbackList &	methods,
		WOscMessage *	msg
	)

Creates a list of methods which match the address of the message passed as argument. Those lists reflect the effect of an OSC-message. The list can then be used to invoke all matching methods.

Parameters:

msg

Message to be scanned for.

Returns:

A list containing all matching functions. Its the task of the list if none are found and an invocation is issued. The caller must free the returned list.

Exceptions:

WOscException

When dispatching is not executed from a root container. (can be removed by first searching for root. discussion?).

Remarks:

Code stolen from Matt Wright's OSC-Kit and adapted to this architecture (Thank You!).

See also:

WOscContainer::dispatchSubMessage(char* pattern)

Definition at line 361 of file WOscContainer.cpp.

References ERR_INVALID_ADDRESS_NO_SLASH, ERR_NOT_DISPATCHING_FROM_ROOT, WOscString::GetBuffer(), and WOscMessage::GetOscAddress().

{
    if ( m_parent != NULL )
        throw WOscException(ERR_NOT_DISPATCHING_FROM_ROOT, __FILE__, __LINE__);

    const char* pattern = msg->GetOscAddress().GetBuffer();

    if ( pattern == NULL || pattern[0] != '/')
        throw WOscException(ERR_INVALID_ADDRESS_NO_SLASH, __FILE__, __LINE__);

    // dispatch address pattern (note: leading slash removed!)
    DispatchSubMessage(methods, pattern+1);
}

const WOscContainer * WOscContainer::FindContainer

(

const char *

address

)

const

Tries to find a certain container by its OSC-address. Not pattern but address (/hello/world/whats/up).

Parameters:

address

String containing OSC-address to be searched for.

Returns:

Pointer to container if found else NULL.

Todo:

Verify/test this function.

Definition at line 270 of file WOscContainer.cpp.

References WOscPatternMatch::NextSlashOrNull().

{
    unsigned int addrlen = strlen(address);
    
    if ( addrlen == 0 )                     // no address
        return NULL;
    if ( address[0] != '/' )                // invalid address
        return NULL;
    if ( addrlen == 1 && *address == '/' )  // root container "/"
        return this;
    
    // find next slash (if any)
    const char* next = NextSlashOrNull(address+1);
    
    if ( *next == 0 ) {
        // leaf
        for (int i = m_containerEntries.size()-1; i >= 0; i-- )
            if ( m_containerEntries[i].m_name == (address+1) )
                return m_containerEntries[i].m_container;
    } else {
        // not a leaf. just compare node name
        unsigned int thisNodeStrLen = next-address;
        for ( int i = m_containerEntries.size()-1; i >= 0; i-- ) {
            if ( strncmp(m_containerEntries[i].m_name.c_str(), address+1, thisNodeStrLen) == 0 ) {
                const WOscContainer* ctnr = m_containerEntries[i].m_container->FindContainer(next);
                if ( ctnr )
                    return ctnr;
            }
        }
    }
        
    return NULL;
}

const WOscContainer * WOscContainer::FindRoot

(

)

const

Traverses the container-tree upwards until root is reached.

Returns:

The pointer of the root-container.

Definition at line 525 of file WOscContainer.cpp.

Referenced by WOscMethod::GetAddressSpace(), GetAddressSpace(), and RemoveAll().

{

    const WOscContainer* momentaryParent = m_parent;
    const WOscContainer* lastParent = this;

    /* traverse tree upwards until root is reached */
    while ( momentaryParent != NULL ){
        lastParent = momentaryParent;
        momentaryParent = momentaryParent->m_parent;
    }
    return lastParent;
}

WOscString WOscContainer::GetAddress

(

)

const

Traverses the container-tree upwards until root is reached and assembles its unaliased address.

Returns:

OSC-address of this container.

Remarks:

OSC-addresses of containers end with a slash ('\'), OSC-addresses of methods end with nothing.

Definition at line 449 of file WOscContainer.cpp.

References GetName().

Referenced by GetMethodList().

{

    if ( m_parent == NULL)
        return WOscString("/");

    WOscContainer* momentaryParent = m_parent;
    WOscString address = GetName();
    address += '/';

    /* traverse tree upwards until root is reached */
    while ( momentaryParent != NULL ) {
        address = momentaryParent->GetName() + address;
        momentaryParent = momentaryParent->m_parent;
    }
    
    return address;
}

WOscString WOscContainer::GetAddressSpace

(

)

const

Returns a line-break('\n')-separated list of all OSC-addresses of methods as seen from root.

Returns:

WOscString containing the list.

Remarks:

OSC-addresses of containers end with a slash ('\'), OSC-addresses of methods end with nothing.

Examples:

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

Definition at line 479 of file WOscContainer.cpp.

References FindRoot(), and GetMethodList().

{
    const WOscContainer* root = FindRoot();
    return root->GetMethodList();
}

WOscString WOscContainer::GetMethodList

(

)

const

Scans for all local methods and aliased methods.

Returns:

A list as described in WOscContainer::getAddressSpace() containing the addresses of all method-leaves reachable from this node/container.

Todo:

Does not handle aliased containers !!!!

Definition at line 492 of file WOscContainer.cpp.

References GetAddress().

Referenced by WOscMethod::GetAddressSpace(), and GetAddressSpace().

{
    WOscString methodList;

    // scan for local methods
    for ( int m = m_methodEntries.size()-1; m >= 0; m-- ){
        if ( m_methodEntries[m].m_isAlias ) {
            methodList += GetAddress();
            methodList += m_methodEntries[m].m_name.c_str();
        } else {
            methodList += m_methodEntries[m].m_method->GetAddress();
        }
        methodList += '\n';
    }

    // scan children containers
    for ( int c = m_containerEntries.size()-1; c >= 0; c-- ) {
        if ( m_containerEntries[c].m_isAlias ) {
            /** \todo Does not handle aliased containers !!!! */
        } else {
            methodList += m_containerEntries[c].m_container->GetMethodList();
        }
    }
    
    return methodList;
}

WOscString WOscContainer::GetName

(

)

const

Returns the not aliased name (OSC-pattern, not address) of this container.

Returns:

WOscString containing the name-pattern of this container.

Definition at line 424 of file WOscContainer.cpp.

Referenced by WOscMethod::GetAddress(), and GetAddress().

{
    if ( m_parent != NULL ) {
        /* search all children of parent for not aliased name */
        const std::vector<WOscContainerEntry>& entries = m_parent->m_containerEntries;
        for ( int i = entries.size()-1; i >= 0; i-- )
            if ( (entries[i].m_container == this) && (!(entries[i].m_isAlias))){
                return WOscString(entries[i].m_name.c_str());
                break;
            }
    }
    return WOscString("/");
}

bool WOscContainer::IsRoot

(

)

const

Checks if the current container is the root-container.

Returns:

True if it is, false else.

Definition at line 545 of file WOscContainer.cpp.

Referenced by WOscReceiver::SetAddressSpace().

{
    return m_parent == NULL ? true : false;
}

void WOscContainer::RemoveAll

(

)

Public function for deletion of a whole container-/method-tree. Searches the root and starts a recursive deletion.

See also:

WOscContainer::~WOscContainer()

Examples:

WOscClient.cpp, and WOscServer.cpp.

Definition at line 169 of file WOscContainer.cpp.

References FindRoot().

{
    delete FindRoot();
}

bool WOscContainer::RemoveContainer

(

const char *

name

)

Removes child container or container alias by name (not address).

Definition at line 308 of file WOscContainer.cpp.

{
    for ( int i = m_containerEntries.size()-1; i >= 0; i-- )
        if ( m_containerEntries[i].m_name == name ) {
            // deallocated only if not an alias.
            if ( ! m_containerEntries[i].m_isAlias )
                delete m_containerEntries[i].m_container;
            m_containerEntries.erase(m_containerEntries.begin() + i);
            return true;
        }
    return false;
}

bool WOscContainer::RemoveMethod

(

const char *

name

)

Removes child method or container alias by name (not address).

Definition at line 325 of file WOscContainer.cpp.

{
    for ( int i = m_methodEntries.size()-1; i >= 0; i-- )
        if ( m_methodEntries[i].m_name == name ) {
            // deallocated only if not an alias.
            if ( ! m_methodEntries[i].m_isAlias )
                delete m_methodEntries[i].m_method;
            m_methodEntries.erase(m_methodEntries.begin() + i);
            return true;
        }
    return false;
}

---

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

• WOscContainer.h
• WOscContainer.cpp