HelpSource/Classes/OSCdef.schelp

   1 CLASS:: OSCdef
   2 summary:: OSC response reference definition
   3 categories:: OpenSoundControl
   4 related:: Guides/OSC_communication, Classes/OSCFunc, Classes/OSCresponderNode, Classes/NetAddr
   5
   6 DESCRIPTION::
   7 OSCdef provides a global reference to the functionality of its superclass link::Classes/OSCFunc::. Essentially it stores itself at a key within a global dictionary, allowing replacement at any time. Most methods are inherited from its superclass.
   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. link::Classes/OSCFunc:: and OSCdef are faster, safer, have more logical argument order, and support pattern matching. 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
  14
  15 METHOD:: all
  16 Get the global dictionary of all OSCdefs.
  17
  18 returns:: An link::Classes/IdentityDictionary::.
  19
  20 METHOD:: new
  21 Create a new, enabled OSCdef. If an OSCdef already exists at this key, its parameters will be replaced with the ones provided (args for which nil is passed will use the old values).
  22
  23 argument:: key
  24 The key at which to store this OSCdef in the global collection. Generally this will be a link::Classes/Symbol::.
  25
  26 argument:: func
  27 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, 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/OSCArgMatcher:: or similar object.
  28
  29 argument:: path
  30 A link::Classes/Symbol:: indicating the path of the OSC address of this object. Note that OSCdef demands OSC compliant addresses. If the path does not begin with a / one will be added automatically.
  31
  32 argument:: srcID
  33 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.
  34
  35 argument:: recvPort
  36 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.
  37
  38 argument:: dispatcher
  39 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.
  40
  41 returns:: An instance of OSCdef.
  42
  43 METHOD:: newMatching
  44 A convenience method to create a new, enabled OSCdef whose dispatcher will perform pattern matching on incoming OSC messages to see if their address patterns match this object's path.
  45
  46 argument:: key
  47 The key at which to store this OSCdef in the global collection. Generally this will be a link::Classes/Symbol::.
  48
  49 argument:: func
  50 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/OSCArgMatcher:: or similar object.
  51
  52 argument:: path
  53 A link::Classes/Symbol:: indicating the path of the OSC address of this object. Note that OSCdef 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
  54
  55 argument:: srcID
  56 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.
  57
  58 argument:: recvPort
  59 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.
  60
  61 returns:: An instance of OSCdef.
  62
  63
  64 INSTANCEMETHODS::
  65 private:: addToAll, printOn
  66
  67 METHOD:: key
  68 Get this OSCdef's key.
  69
  70 returns:: Usually a link::Classes/Symbol::.
  71
  72 METHOD:: free
  73 Clears this MIDIdef from the global collection and deactivates it.
  74
  75
  76 EXAMPLES::
  77
  78 code::
  79 n = NetAddr("127.0.0.1", 57120); // local machine
  80
  81 OSCdef(\test, {|time, msg, addr| \unmatching.postln}, '/chat', n); // def style
  82 OSCdef.newMatching(\test2, {|time, msg, addr| \matching.postln}, '/chat', n); // path matching
  83 OSCdef(\test3, {|time, msg, addr| \oneShot.postln}, '/chat', n).oneShot; // once only
  84
  85
  86 m = NetAddr("127.0.0.1", 57120); // loopback
  87
  88 m.sendMsg("/chat", "Hello App 1");
  89 m.sendMsg("/chat", "Hello App 1"); // oneshot gone
  90 m.sendMsg("/ch?t", "Hello App 1");
  91 m.sendMsg("/*", "Hello App 1");
  92 m.sendMsg("/chit", "Hello App 1"); // nothing
  93
  94 // Introspection
  95
  96 AbstractResponderFunc.allFuncProxies
  97 AbstractResponderFunc.allEnabled
  98 OSCdef(\test).disable;
  99 AbstractResponderFunc.allDisabled
 100
 101 // change funcs
 102 OSCdef(\test).enable;
 103 OSCdef(\test, {|time, msg, addr| 'Changed Unmatching'.postln}, '/chat', n); // replace at key \test
 104 m.sendMsg("/chat", "Hello App 1");
 105 OSCdef(\test).add(f = {\foo.postln}); // add another func
 106 m.sendMsg("/chat", "Hello App 1");
 107 OSCdef(\test).clear; // remove all functions
 108 m.sendMsg("/chat", "Hello App 1");
 109
 110
 111 //////// Use an OSCArgsMatcher for finer grained matching
 112
 113 s.boot;
 114 x = Synth(\default);
 115 OSCdef(\watchForXEnd, OSCArgsMatcher([x.nodeID], { 'ended!'.postln }), '/n_end', s.addr).oneShot;
 116 x.release(3);
 117 ::