8.2KB
OSCMessage
An OSCMessage is an address followed by any number of data. Messages can have mixed data types like an integer followed by a string followed by a float, etc.
Constructor
OSCMessages can be constructed with or without an address.
OSCMessage(const char *)
Set the address of the message in the constructor
OSCMessage msg("/address");
OSCMessage()
An OSCMessage constructed without an address is not valid until it is given an address.
Add/Set Data
OSCMessage& add(int i)
Append an integer to the OSCMessage.
msg.add(1);
OSCMessage& add(float f)
Append a float to the OSCMessage.
OSCMessage& add(bool b)
Append a boolean to the OSCMessage.
OSCMessage& add(const char * str)
Append a string to the OSCMessage.
msg.add("hello");
OSCMessage& add(uint8_t * blob, int length)
Append a blob to the OSCMessage. Pass in the length of the blob as the second argument.
OSCMessage& set(int position, Type data)
Replace the data at the given position with the data. Type can be any of the supported data types.
//replace the data at the 0th position with a string
msg.set(0, "string");
OSCMessage& set(int position, uint8_t * data, int length)
Set the data at the given position to be a blob of the given length.
OSCMessage& add(double d)
Append a double precision floating point value to the OSCMessage. NOTE: double is not supported on most Arduino platforms. It will fall back to float, when double is not supported.
Get Data
int getInt(int position)
Returns the integer at the given position
//returns the integer at the third position
msg.getInt(2);
float getFloat(int position)
Returns the float at the given position
bool getBoolean(int position)
Returns the boolean at the given position
double getDouble(int position)
Returns the double at the given position. NOTE: double is not supported by most Arduino platforms. This will fail silently if double is not supported.
int getString(int position, char * str, int length)
Copy length number of characters from the given position into the str buffer. Returns the number of copied characters.
char str[8];
//fill str with 8 characters from the 0th datum
msg.getString(0, str, 8);
int getBlob(int position, uint8_t * blob, int length)
Copy length number of bytes from the given position into the blob buffer. Returns the number of copied bytes.
char getType(int position)
Returns the type of the data at the given position.
OSCMessage msg("/address");
msg.add(1);
msg.getType(0); //-> returns 'i'
Query Data
bool isInt(int position)
Returns true when the data at the given position is an integer.
bool isFloat(int position)
Returns true when the data at the given position is a float.
bool isBoolean(int position)
Returns true when the data at the given position is a boolean.
bool isString(int position)
Returns true when the data at the given position is a string.
bool isBlob(int position)
Returns true when the data at the given position is a blob.
bool isDouble(int position)
Returns true when the data at the given position is a double.
int size()
Returns the number of data the OSCMessage has.
int bytes()
Returns the size of the OSCMessage in bytes (if everything is 32-bit aligned).
Address
OSCMessage& setAddress(const char * address)
Set the address of the OSCMessage.
OSCMessage& getAddress(char * str, int offset=0)
Copy the address of the OSCMessage into the str buffer. Copy after the given address offset (defaults to 0).
Send Receive
OSCMessage& send(Print &p)
Output the message to the given transport layer which extends Arduino’s Print class like the Serial out.
msg.send(SLIPSerial);
OSCMessage& fill(uint8_t incomingByte)
Add the incoming byte to the OSCMessage where it will be decoded.
OSCMessage& fill(uint8_t * bytes, int length)
Add and decode the array of bytes as an OSCMessage.
Matching / Routing
bool fullMatch( const char * pattern, int offset = 0)
Returns true if the message’s address is a full match to the given pattern after the offset.
OSCMessage msg("/a/0");
msg.fullMatch("/0", 2); // ->returns true
int match( const char * pattern, int offset = 0)
Returns the number of matched characters of the message’s address against the given pattern (optionally with an offset). Unlike fullMatch, match allows for partial matches
OSCMessage msg("/a/0");
msg.match("/a"); // ->returns 2
bool dispatch(const char * pattern, void (*callback)(OSCMessage &), int offset = 0)
Invoke the given callback if the address if a full match with the pattern (after the offset). The message is passed into the callback function. Returns true if the pattern was a match and the callback function was invoked.
bool route(const char * pattern, void (*callback)(OSCMessage &, int), int offset = 0)
Invoke the given callback if the address if a match with the pattern (after the offset). The OSCMessage and the address offset is passed into the callback function. Returns true if the pattern was a match and the callback function was invoked.
//define a callback function for matching messages
void routeCallback(OSCMessage & message, int addressOffset){
//do something with the message...
//with the message below, the addressOffset will equal 2.
}
OSCMessage msg("/a/0");
msg.route("/a", routeCallback);
Address Patterns
OSCMessages can be constructed with patterns and later routed or dispatched against addresses.
OSCMessage msg("/{a,b}/[0-9]");
msg.route("/a/0", a0_callback); //matches the address
msg.route("/b/2", b2_callback); //matches the address
msg.route("/c/11", c11_callback); //not invoked
OSCBundle
A bundle is a group of OSCMessages with a timetag.
Constructor
OSCBundle()
Construct an empty OSCBundle.
OSCBundle(osctime_t = zerotime)
Construct the bundle with a timetag. timetag defaults to 0 (immediate).
Add OSCMessage
OSCMessage & add(char * address)
Create a new message with the given address in the bundle. Returns the newly created OSCMessage.
//create a new OSCMessage and add some data to it
bundle.add("/message").add("data");
Get OSCMessage
OSCMessage * getOSCMessage(int position)
Return the OSCMessage in the bundle at the given position.
OSCBundle bundle
bundle.add("/a");
bundle.add("/b");
bundle.getOSCMessage(0);//returns the OSCMessage with the address "/a".
OSCMessage * getOSCMessage(char * address)
Return the OSCMessage in the bundle which matches the given address.
OSCBundle bundle
bundle.add("/a");
bundle.add("/b");
bundle.getOSCMessage("/b");//returns the second OSCMessage in the bundle
Routing
bool dispatch(const char * pattern, void (*callback)(OSCMessage&), int offset = 0)
Invoke the callback function with all messages in the bundle which match the given pattern after the offset.
bundle.add("/a/0");
bundle.add("/b/0");
bundle.dispatch("/0", dispatchZero, 2);
bool route(const char * pattern, void (*callback)(OSCMessage &, int), int offset = 0)
Invoke the callback with all the OSCMessages in the bundle which match the given pattern. route allows for partial matches.
Send/Receive
OSCBundle& send(Print &p)
Output the bundle to the given transport layer which extends Arduino’s Print class (such as SLIPSerial out).
bundle.send(SLIPSerial);
OSCBundle& fill(uint8_t incomingByte)
Add the incoming byte to the OSCBundle where it will be decoded.
OSCBundle& fill(uint8_t * bytes, int length)
Add and decode the array of bytes as an OSCBundle.
Chaining
Many methods return this which enables you to string together multiple commands.
This technique allows multiple lines to be condensed into one:
bundle.add("/address").add("data").add(0).send(SLIPSerial).empty();