OSCMessage

#Overview
OSCMessage is the basic class which implements all of the OSC 1.0 specification which includes the data types 32-bit integer, 32-bit float, string, and blobs (byte array), as well as pattern matching and two-way communication over a transport layer.

#Making an OSCMessage
OSCMessages, once declared, can be filled with data using the add method. The start and add methods return the OSCMessage allowing these methods to be chained together.

For example, to create an OSC message with the address "/OSC" and a float data type of value 1.0:

OSCMessage msg("/OSC");
msg.add(1.0);


To get the float value stored in the first datum of a message, use the get command of the corresponding data type:
float val = msg.getFloat(0).


OSCMessage msg("/sensor");
msg.add(3);
msg.add(analogRead(3));
int sensorPinNumber = msg.getInt(0); //returns 3
int sensorValue = msg.getInt(1); //returns the result of the analogRead


#Data Transmission

Sending and receiving an OSCMessage is simple using the
send method will send the OSCMessage as an OSC formatted stream to any output that extends the Arduino's Print class (i.e. Serial, EthernetUDP). Similarly, fill allows OSC messages to be filled byte by byte, or using a byte array. The fill method combines easily with any Arduino Stream.

For example, this simple sketch sends a message over the Ethernet port :

void setup() {
  Ethernet.begin(mac,ip);
}
void loop(){
  //the message wants an OSC address as first argument
  OSCMessage msg("/analog/0");
  msg.add(analogRead(0));
  
  Udp.beginPacket(outIp, outPort);
  msg.send(Udp); // send the bytes to the SLIP stream
  Udp.endPacket(); // mark the end of the OSC Packet
  msg.empty(); // free space occupied by message

  delay(20);
}

#Matching
Pattern matching is a powerful feature of OSC (to read more about pattern matching see the "OSC Message Dispatching and Pattern Matching" subsection of the OSC Spec). OSCMessage allows for full and partial matches of a pattern against an address.

fullMatch returns true only in the case of a complete match.

OSCMessage msg("/a/*/c"); //the asterisk matches any sequence of 0 or more characters
msg.fullMatch("/a/anything/c"); //returns true
msg.fullMatch("/a/b/c"); //returns true
msg.fullMatch("/a/b/a"); //returns false


match allows for partial matches. It returns the number of characters matched. Note that matches must match to the address gets to the end or the '/' character.

OSCMessage msg("/alpha/beta");

msg.match("/alpha"); //returns 6
msg.match("/alph"); //returns 0
msg.match("/alpha/beta"); //returns 11
//both match and fullMatch can also be passed in an address offset
//address offsets allow for multi-level routing
msg.match("/beta", 6); //returns 5

OSCMessage can conditionally call a function if the message's address matches a pattern. There are two methods that do this: dispatch which requires a full match in order to call the callback function with the matched OSCMessage as the argument, or route which allows for partial matches and calls the callback function with both the matched OSCMessage and the number of matched characters. Both functions return true if the callback function was invoked, and false otherwise.

OSCMessage msg("/alpha");
msg.add(125); 
msg.dispatch("/alpha", callback); //full match callback invoked and returns true
msg.dispatch("/beta", callback); //no match returns false. 

void callback(OSCMessage & m){
   int val = m.getInt(); 
}