OSCBundle.cpp

/*
 Written by Yotam Mann, The Center for New Music and Audio Technologies,
 University of California, Berkeley.  Copyright (c) 2012, The Regents of
 the University of California (Regents).
 
 Permission to use, copy, modify, distribute, and distribute modified versions
 of this software and its documentation without fee and without a signed
 licensing agreement, is hereby granted, provided that the above copyright
 notice, this paragraph and the following two paragraphs appear in all copies,
 modifications, and distributions.
 
 IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
 OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS
 BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED
 HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE
 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 
 For bug reports and feature requests please email me at yotam@cnmat.berkeley.edu
 */

#include "OSCBundle.h"
#include <stdlib.h>

#define OSCBUNDLE_PREALLOCATE 16

 /*=============================================================================
	CONSTRUCTORS / DESTRUCTOR
=============================================================================*/

OSCBundle::OSCBundle(osctime_t _timetag){
    setTimetag(_timetag);
    numMessages = 0;
    error = OSC_OK;
    messages = NULL;
    incomingBuffer = NULL;
    incomingBufferSize = 0;
    incomingBufferFree = 0;
    decodeState = STANDBY;
}

OSCBundle::~OSCBundle(){
    for (int i = 0; i < numMessages; i++){
        OSCMessage * msg = getOSCMessage(i);
        delete msg;
    }
    free(messages);
    free(incomingBuffer);
}

//clears all of the OSCMessages inside
OSCBundle& OSCBundle::empty(){
    error = OSC_OK;
    for (int i = 0; i < numMessages; i++){
        OSCMessage * msg = getOSCMessage(i);
        delete msg;
    }
    free(messages);
    messages = NULL;
    shrinkIncomingBuffer();
    numMessages = 0;
    //Reset the decoder too.  Without this a bundle left in any state other
    //than STANDBY stayed there forever, so the usual pattern of one long-lived
    //OSCBundle refilled in loop() accepted the first packet and then rejected
    //every packet after it, permanently.
    decodeState = STANDBY;
    return *this;
}

/*=============================================================================
 SETTERS
 =============================================================================*/

OSCMessage & OSCBundle::add(const char * _address){
	OSCMessage * msg = new OSCMessage(_address);
    if (!msg->hasError()){
        //realloc the array to fit the message
        OSCMessage ** messageMem = (OSCMessage **) realloc(messages, sizeof(OSCMessage *) * (numMessages + 1));
        if (messageMem != NULL){
            messages = messageMem;
            messages[numMessages] = msg;
            numMessages++;
        } else {
            error = ALLOCFAILED;
        }
    }
    return *msg;
}

OSCMessage & OSCBundle::add(){
	OSCMessage * msg = new OSCMessage();
    //realloc the array to fit the message
    OSCMessage ** messageMem = (OSCMessage **) realloc(messages, sizeof(OSCMessage *) * (numMessages + 1));
    if (messageMem != NULL){
        messages = messageMem;
        messages[numMessages] = msg;
        numMessages++;
    } else {
        error = ALLOCFAILED;
    }
    return *msg;
}

OSCMessage & OSCBundle::add(OSCMessage & _msg){
    OSCMessage * msg = new OSCMessage(&_msg);
    if (!msg->hasError()){
        //realloc the array to fit the message
        OSCMessage ** messageMem = (OSCMessage **) realloc(messages, sizeof(OSCMessage *) * (numMessages + 1));
        if (messageMem != NULL){
            messages = messageMem;
            messages[numMessages] = msg;
            numMessages++;
        } else {
            error = ALLOCFAILED;
        }
    }
    return *msg;
}

/*=============================================================================
    GETTERS
 =============================================================================*/

//returns the first fullMatch.
OSCMessage * OSCBundle::getOSCMessage( char * addr){
	for (int i = 0; i < numMessages; i++){
        OSCMessage * msg = getOSCMessage(i);
        if (msg->fullMatch(addr)){
            return msg;
        }
	}
	return NULL;
}

//the position is the same as the order they were declared in
OSCMessage * OSCBundle::getOSCMessage(int pos){
	if (pos < numMessages){
		return messages[pos];
	} 
	return NULL;
}

/*=============================================================================
    PATTERN MATCHING
 =============================================================================*/


bool OSCBundle::dispatch(const char * pattern, void (*callback)(OSCMessage&), int initial_offset){
	bool called = false;
	for (int i = 0; i < numMessages; i++){
        //Use the message in place. This used to be `OSCMessage msg = getOSCMessage(i)`,
        //which - because getOSCMessage returns a pointer and OSCMessage(OSCMessage*)
        //is a converting constructor - deep-copied every message in the bundle on
        //every dispatch, allocating a fresh address string and a fresh OSCData per
        //argument and then freeing the lot. A sketch calling route() four times per
        //packet paid that four times over. It also meant callbacks were handed a
        //temporary, so anything they wrote to the message was discarded.
        OSCMessage * msg = getOSCMessage(i);
        if (msg == NULL) continue;
		called = msg->dispatch(pattern, callback, initial_offset) || called ;
	}
	return called;
}


bool OSCBundle::route(const char * pattern, void (*callback)(OSCMessage&, int), int initial_offset){
	bool called = false;
	for (int i = 0; i < numMessages; i++){
        OSCMessage * msg = getOSCMessage(i);       //in place; see dispatch() above
        if (msg == NULL) continue;
		called =  msg->route(pattern, callback, initial_offset) || called;
	}
	return called;
}

/*=============================================================================
    SIZE
 =============================================================================*/


int OSCBundle::size(){
	return numMessages;
}

/*=============================================================================
 ERROR HANDLING
 =============================================================================*/

bool OSCBundle::hasError(){
    bool retError = error != OSC_OK;
    //test each of the data
    for (int i = 0; i < numMessages; i++){
        OSCMessage * msg = getOSCMessage(i);
        retError |= msg->hasError();
    }
	return retError;
}

OSCErrorCode OSCBundle::getError(){
    return error;
}


/*=============================================================================
 SENDING
 =============================================================================*/

OSCBundle& OSCBundle::send(Print &p){
    //don't send a bundle with errors
    if (hasError()){
        return *this;
    }
    //write the bundle header
    static const uint8_t header[] = {'#', 'b', 'u', 'n', 'd', 'l', 'e', 0};
    p.write(header, 8);
    //write the timetag
{
    osctime_t time =  timetag;
    uint32_t d = BigEndian(time.seconds);
    uint8_t * ptr = (uint8_t *)    &d;
    p.write(ptr, 4);
    d = BigEndian(time.fractionofseconds);
    ptr = (uint8_t *)    &d;
    p.write(ptr, 4);
}

    //send the messages
    for (int i = 0; i < numMessages; i++){
        const auto msg = getOSCMessage(i);
        int msgSize = msg->bytes();
        //turn the message size into a pointer
        const uint32_t s32 = BigEndian((uint32_t) msgSize);
        const uint8_t * sptr = (uint8_t *) &s32;
        //write the message size
        p.write(sptr, 4);
        msg->send(p);
    }
    return *this;
}

/*=============================================================================
    FILLING
 =============================================================================*/

OSCBundle& OSCBundle::fill(uint8_t incomingByte){
    decode(incomingByte);
    return *this;
}

OSCBundle& OSCBundle::fill(const uint8_t * incomingBytes, int length){
    while (length--){
        decode(*incomingBytes++);
    }
    return *this;
}

/*=============================================================================
    DECODING
 =============================================================================*/

void OSCBundle::decodeTimetag(){
    //parse the incoming buffer as a uint64; setTimetag handles the endianness
    setTimetag(incomingBuffer);
    decodeState = MESSAGE_SIZE;
    clearIncomingBuffer();
}

void OSCBundle::decodeHeader(){
    const char * header = "#bundle";
    if (strcmp(header, (char *) incomingBuffer)!=0){
        //otherwise go back to the top and wait for a new bundle header
        decodeState = STANDBY;
        error = INVALID_OSC;
    } else {
        decodeState = TIMETAG;
    }
    clearIncomingBuffer();
}

void OSCBundle::decodeMessage(uint8_t incomingByte){
    //get the current message
    if (numMessages > 0){
       OSCMessage * lastMessage = messages[numMessages - 1];
        //put the bytes in there
        lastMessage->fill(incomingByte);
        //if it's all done
        if (incomingBufferSize == incomingMessageSize){
            //move onto the next message
            decodeState = MESSAGE_SIZE;
            clearIncomingBuffer();
        } else if (incomingMessageSize > 0 && incomingBufferSize > incomingMessageSize){
            error = INVALID_OSC;
        }
    }
}

//does not validate the incoming OSC for correctness
void OSCBundle::decode(uint8_t incomingByte){
    addToIncomingBuffer(incomingByte);
    switch (decodeState){
        case STANDBY:
            if (incomingByte == '#'){
                decodeState = HEADER;
            } else if (incomingByte == '/'){
                add();//add a simple message to the bundle
                decodeMessage(incomingByte);
                decodeState = MESSAGE;
                //in this special case we initialize the message size
                //to zero to skip the later error check
                incomingMessageSize = 0;
            }
            break;
        case HEADER:
			if (incomingBufferSize == 8){
                decodeHeader();
                decodeState = TIMETAG;
            }
			break;
		case TIMETAG:
            if (incomingBufferSize == 8){
                decodeTimetag();
                decodeState = MESSAGE_SIZE;
            }
			break;
		case MESSAGE_SIZE:
            if (incomingBufferSize == 4){
                //make sure the message size is valid
                int32_t msgSize;
                memcpy(&msgSize, incomingBuffer, 4);
                msgSize = BigEndian(msgSize);
                //msgSize <= 0, not just == 0: the element size is a signed
                //value taken straight off the wire, so a negative one passed
                //both of the old tests and was then used as a byte count.
                if (msgSize <= 0 || msgSize % 4 != 0){
                    error = INVALID_OSC;
                } else {
                    //add a message to the buffer
                    decodeState = MESSAGE;
                    incomingMessageSize = msgSize;
                    clearIncomingBuffer();
                    //add a new empty message
                    add();
                }
            }
            break;
		case MESSAGE:
            decodeMessage(incomingByte);
            break;
    }
}


/*=============================================================================
 INCOMING BUFFER MANAGEMENT
 =============================================================================*/

void OSCBundle::addToIncomingBuffer(uint8_t incomingByte){
    //refuse to grow without bound on a length taken from the wire
    if (incomingBufferSize >= OSC_MAX_INCOMING){
        error = BUFFER_FULL;
        return;
    }
    //Grow in blocks. This used to realloc for every single byte, which on a
    //part with no heap compaction is both slow and fragmenting.
    if (incomingBufferFree == 0){
        //double, clamped to the cap
        int capacity = incomingBufferSize + incomingBufferFree;
        int want = capacity ? capacity * 2 : OSCBUNDLE_PREALLOCATE;
        if (want > OSC_MAX_INCOMING){
            want = OSC_MAX_INCOMING;
        }
        if (want <= incomingBufferSize){
            want = incomingBufferSize + 1;
        }
        uint8_t * mem = (uint8_t *) realloc(incomingBuffer, want);
        if (mem == NULL){
            error = ALLOCFAILED;
            return;
        }
        incomingBuffer = mem;
        incomingBufferFree = want - incomingBufferSize;
    }
    incomingBuffer[incomingBufferSize++] = incomingByte;
    incomingBufferFree--;
}

//Called at every message boundary inside a bundle, so like OSCMessage's this
//is a hot path. It used to free the buffer outright and force the next message
//to build it again from nothing. Keep the capacity; empty() gives it back.
void OSCBundle::clearIncomingBuffer(){
    incomingBufferFree += incomingBufferSize;
    incomingBufferSize = 0;
}

//Release capacity acquired by an unusually large bundle. Only from empty().
void OSCBundle::shrinkIncomingBuffer(){
    incomingBufferSize = 0;
    incomingBufferFree = 0;
    free(incomingBuffer);
    incomingBuffer = NULL;
}