HelpSource/Classes/OSCFunc.schelp

   1 CLASS:: OSCFunc
   2 summary:: Fast Responder for incoming Open Sound Control Messages
   3 categories:: OpenSoundControl
   4 related:: Guides/OSC_communication, Classes/OSCdef, Classes/OSCresponderNode, Classes/NetAddr
   5
   6 DESCRIPTION::
   7 OSCFunc (and its subclass link::Classes/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 link::Classes/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 link::#*newMatching:: method, or by passing a matching dispatcher to link::#*new::. For details on the Open Sound Control protocol, see http://opensoundcontrol.org/spec-1_0
   8
   9 note:: Use of the older classes OSCresponder, OSCresponderNode, and OSCpathResponder can be unsafe, since responders in user and class code can override each other unintentionally. OSCFunc and link::Classes/OSCdef:: are faster, safer, have more logical argument order, and support pattern matching and custom listening ports. Thus they are the recommended way of registering for incoming OSC messages as of SC 3.5. (See below for an example demonstrating OSCpathResponder-type arg matching.)::
  10
  11
  12 CLASSMETHODS::
  13 private:: initClass, cmdPeriod
  14
  15 METHOD:: defaultDispatcher
  16 Get or set the default dispatcher object for OSCFuncs (this is what you get if you pass nil as the dispatcher argument to link::#*new::). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message.
  17
  18 returns:: By default this will be an link::Classes/OSCMessageDispatcher::, but it can be set to any instance of an appropriate subclass of link::Classes/AbstractDispatcher::.
  19
  20 METHOD:: defaultMatchingDispatcher
  21 Get or set the default matching dispatcher object for OSCFuncs (this is what you get if when you create an OSCFunc using link::#*newMatching::). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message using pattern matching.
  22
  23 returns:: By default this will be an link::Classes/OSCMessagePatternDispatcher::, but it can be set to any instance of an appropriate subclass of link::Classes/AbstractDispatcher::.
  24
  25 METHOD:: new
  26 Create a new, enabled OSCFunc.
  27
  28 argument:: func
  29 A link::Classes/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 link::Classes/Array:: in the form code::[OSCAddress, ...otherArgs]::, the time that the message was sent, a link::Classes/NetAddr:: corresponding to the IP address of the sender, and an link::Classes/Integer:: corresponding to the port on which the message was received. For more complicated matching, one can use an link::Classes/OSCArgsMatcher:: or similar object.
  30
  31 argument:: path
  32 A link::Classes/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.
  33
  34 argument:: srcID
  35 An optional instance of link::Classes/NetAddr:: indicating the IP address of the sender. If set this object will only respond to messages from that source.
  36
  37 argument:: recvPort
  38 An optional link::Classes/Integer:: indicating the port on which messages will be received. If set this object will only respond to message received on that port. Note that you will have to use the link::Classes/Main#-openUDPPort:: method to enable listening on that port.
  39
  40 argument:: argTemplate
  41 An optional link::Classes/Array:: composed of instances of link::Classes/Integer:: or link::Classes/Function:: (or objects which respond to the method link::Overviews/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 link::Classes/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.
  42
  43 argument:: dispatcher
  44 An optional instance of an appropriate subclass of link::Classes/AbstractDispatcher::. This can be used to allow for customised dispatching. Normally this should not be needed.
  45
  46 returns:: A new instance of OSCFunc.
  47
  48 METHOD:: newMatching
  49 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.
  50
  51 argument:: func
  52 A link::Classes/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 link::Classes/Array:: [OSCAddress, other args], the time that the message was sent, a link::Classes/NetAddr:: corresponding to the IP address of the sender, and an link::Classes/Integer:: corresponding to the port on which the message was received. For more complicated matching, one can use an link::Classes/OSCArgsMatcher:: or similar object.
  53
  54 argument:: path
  55 A link::Classes/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
  56
  57 argument:: srcID
  58 An optional instance of link::Classes/NetAddr:: indicating the IP address of the sender. If set this object will only respond to messages from that source.
  59
  60 argument:: recvPort
  61 An optional link::Classes/Integer:: indicating the port on which messages will be received. Note that you will have to use the link::Classes/Main#-openUDPPort:: method to enable listening on that port.
  62
  63 argument:: argTemplate
  64 An optional link::Classes/Array:: composed of instances of link::Classes/Integer:: or link::Classes/Function:: (or objects which respond to the method link::Overviews/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 link::Classes/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.
  65
  66 returns:: A new instance of OSCFunc.
  67
  68 METHOD:: trace
  69 A convenience method which dumps all incoming OSC messages.
  70
  71 argument:: bool
  72 A link::Classes/Boolean:: indicating whether dumping is on or off.
  73
  74
  75 INSTANCEMETHODS::
  76
  77 private:: init, printOn
  78
  79 METHOD:: path
  80 Get the path of this OSCFunc's OSC Address.
  81
  82 returns:: A link::Classes/String::
  83
  84 METHOD:: recvPort
  85 Get this OSCFunc's receiving port.
  86
  87 returns:: An link::Classes/Integer::
  88
  89
  90
  91 EXAMPLES::
  92
  93 code::
  94 n = NetAddr("127.0.0.1", NetAddr.langPort); // local machine
  95
  96 OSCFunc.newMatching({|time, msg, addr| \matching.postln}, '/chat', n); // path matching
  97 OSCFunc({|time, msg, addr| \oneShot.postln}, '/chat', n).oneShot; // once only
  98 OSCdef(\test, {|time, msg, addr| \unmatching.postln}, '/chat', n); // def style
  99
 100 m = NetAddr("127.0.0.1", NetAddr.langPort); // loopback
 101
 102 m.sendMsg("/chat", "Hello App 1");
 103 m.sendMsg("/chat", "Hello App 1"); // oneshot gone
 104 m.sendMsg("/ch?t", "Hello App 1");
 105 m.sendMsg("/*", "Hello App 1");
 106 m.sendMsg("/chit", "Hello App 1"); // nothing
 107
 108 // Introspection
 109
 110 AbstractResponderFunc.allFuncProxies
 111 AbstractResponderFunc.allEnabled
 112 OSCdef(\test).disable;
 113 AbstractResponderFunc.allDisabled
 114
 115 // change funcs
 116 OSCdef(\test).enable;
 117 OSCdef(\test, {|time, msg, addr| 'Changed Unmatching'.postln}, '/chat', n); // replace at key \test
 118 m.sendMsg("/chat", "Hello App 1");
 119 OSCdef(\test).add(f = {\foo.postln}); // add another func
 120 m.sendMsg("/chat", "Hello App 1");
 121 OSCdef(\test).clear; // remove all functions
 122 m.sendMsg("/chat", "Hello App 1");
 123
 124 //////// Use an argTemplate for finer grained matching
 125
 126 s.boot;
 127 x = Synth(\default);
 128 OSCFunc({ 'ended!'.postln }, '/n_end', s.addr, nil, [x.nodeID]).oneShot;
 129 x.release(3);
 130 ::