Classes | External Control > OSC

OSCFunc : AbstractResponderFunc : Object

Fast Responder for incoming Open Sound Control Messages
Subclasses: OSCdef

Description

OSCFunc (and its subclass OSCdef) registers one or more functions to respond to an incoming OSC message which matches a specified OSC Address. Many of its methods are inherited from its superclass AbstractResponderFunc. OSCFunc supports pattern matching of wildcards etc. in incoming messages. For efficiency reasons you must specify that an OSCFunc will employ pattern matching by creating it with the *newMatching method, or by passing a matching dispatcher to *new. For details on the Open Sound Control protocol, see http://opensoundcontrol.org/spec-1_0

Class Methods

OSCFunc.defaultDispatcher

OSCFunc.defaultDispatcher = value

Get or set the default dispatcher object for OSCFuncs (this is what you get if you pass nil as the dispatcher argument to *new). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message.

Returns:

By default this will be an OSCMessageDispatcher, but it can be set to any instance of an appropriate subclass of AbstractDispatcher.

OSCFunc.defaultMatchingDispatcher

OSCFunc.defaultMatchingDispatcher = value

Get or set the default matching dispatcher object for OSCFuncs (this is what you get if when you create an OSCFunc using *newMatching). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message using pattern matching.

Returns:

By default this will be an OSCMessagePatternDispatcher, but it can be set to any instance of an appropriate subclass of AbstractDispatcher.

OSCFunc.new(func, path, srcID, recvPort, argTemplate, dispatcher)

Create a new, enabled OSCFunc.

Arguments:

func

A Function or similar object which will respond to the incoming message. When evaluated it will be passed the arguments msg, time, addr, and recvPort, corresponding to the message as an Array in the form [OSCAddress, ...otherArgs], the time that the message was sent (plus the latency if the message was in a bundle), a NetAddr corresponding to the IP address of the sender, and an Integer corresponding to the port on which the message was received.

path

A Symbol indicating the path of the OSC address of this object. Note that OSCFunc demands OSC compliant addresses. If the path does not begin with a / one will be added automatically.

srcID

An optional instance of NetAddr indicating the IP address of the sender. If set this object will only respond to messages from that source.

recvPort

An optional Integer indicating the port on which messages will be received. If set this object will only respond to message received on that port. This method calls Main: -openUDPPort to ensure that the port is opened.

argTemplate

An optional Array composed of instances of Integer or Function (or objects which respond to the method Methods: matchItem) used to match the arguments of an incoming OSC message. If a Function, it will be evaluated with the corresponding message arg as an argument, and should return a Boolean indicating whether the argument matches and this OSCFunc should respond (providing all other arguments match). Template values of nil will match any incoming argument value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed.

Returns:

A new instance of OSCFunc.

OSCFunc.newMatching(func, path, srcID, recvPort, argTemplate)

A convenience method to create a new, enabled OSCFunc whose dispatcher will perform pattern matching on incoming OSC messages to see if their address patterns match this object's path.

Arguments:

func

A Function or similar object which will respond to the incoming message. When evaluated it will be passed the arguments msg, time, addr, and recvPort, corresponding to the message as an Array [OSCAddress, other args], the time that the message was sent, a NetAddr corresponding to the IP address of the sender, and an Integer corresponding to the port on which the message was received.

path

A Symbol indicating the path of the OSC address of this object. Note that OSCFunc demands OSC compliant addresses. If the path does not begin with a / one will be added automatically. Pattern matching will be applied to any incoming messages to see if they match this address. Note that according to the OSC spec, regular expression wildcards are only permitted in the incoming message's address pattern. Thus path should not contain wildcards. For more details on OSC pattern matching, see http://opensoundcontrol.org/spec-1_0

srcID

An optional instance of NetAddr indicating the IP address of the sender. If set this object will only respond to messages from that source.

recvPort

An optional Integer indicating the port on which messages will be received.

argTemplate

An optional Array composed of instances of Integer or Function (or objects which respond to the method Methods: matchItem) used to match the arguments of an incoming OSC message. If a Function, it will be evaluated with the corresponding message arg as an argument, and should return a Boolean indicating whether the argument matches and this OSCFunc should respond (providing all other arguments match). Template values of nil will match any incoming argument value.

Returns:

A new instance of OSCFunc.

OSCFunc.trace(bool: true, hideStatusMsg: false)

A convenience method which dumps all incoming OSC messages.

Arguments:

bool

A Boolean indicating whether dumping is on or off.

hideStatusMsg

A Boolean indicating whether server status messages are excluded from the dump or not.

Inherited class methods

Instance Methods

.path

Get the path of this OSCFunc's OSC Address.

Returns:

.recvPort

Get this OSCFunc's receiving port.

Returns:

Inherited instance methods

Undocumented instance methods

.argTemplate

Examples

n = NetAddr("127.0.0.1", NetAddr.langPort); // local machine

OSCFunc.newMatching({|msg, time, addr, recvPort| \matching.postln}, '/chat', n); // path matching
OSCFunc({|msg, time, addr, recvPort| \oneShot.postln}, '/chat', n).oneShot; // once only
OSCdef(\test, {|msg, time, addr, recvPort| \unmatching.postln}, '/chat', n); // def style

m = NetAddr("127.0.0.1", NetAddr.langPort); // loopback

m.sendMsg("/chat", "Hello App 1");
m.sendMsg("/chat", "Hello App 1"); // oneshot gone
m.sendMsg("/ch?t", "Hello App 1");
m.sendMsg("/*", "Hello App 1");
m.sendMsg("/chit", "Hello App 1"); // nothing

// Introspection

AbstractResponderFunc.allFuncProxies
AbstractResponderFunc.allEnabled
OSCdef(\test).disable;
AbstractResponderFunc.allDisabled

// change funcs
OSCdef(\test).enable;
OSCdef(\test, {|msg, time, addr, recvPort| 'Changed Unmatching'.postln}, '/chat', n); // replace at key \test
m.sendMsg("/chat", "Hello App 1");
OSCdef(\test).add(f = {\foo.postln}); // add another func
m.sendMsg("/chat", "Hello App 1");
OSCdef(\test).clear; // remove all functions
m.sendMsg("/chat", "Hello App 1");

//////// Use an argTemplate for finer grained matching

s.boot;
x = Synth(\default);
OSCFunc({ 'ended!'.postln }, '/n_end', s.addr, nil, [x.nodeID]).oneShot;
x.release(3);