1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
CLASS:: OSCdef
summary:: OSC response reference definition
categories:: External Control>OSC>Dispatchers
related:: Guides/OSC_communication, Classes/OSCFunc, Classes/NetAddr
DESCRIPTION::
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.
CLASSMETHODS::
private:: initClass
METHOD:: all
Get the global dictionary of all OSCdefs.
returns:: An link::Classes/IdentityDictionary::.
METHOD:: new
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).
argument:: key
The key at which to store this OSCdef in the global collection. Generally this will be a link::Classes/Symbol::.
argument:: func
A link::Classes/Function:: or similar object which will respond to the incoming message. When evaluated it will be passed the following arguments:
table::
## msg || message as an link::Classes/Array:: in the form code::[OSC address, args1, arg2, ...]::
## time || the time received (for messages) / the OSC bundle's timestamp (if the message was in a bundle)
## addr || a link::Classes/NetAddr:: corresponding to the IP address of the strong::sender::
## recvPort || link::Classes/Integer:: corresponding to the port on which the message was strong::received::.
::
argument:: path
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.
argument:: srcID
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.
argument:: recvPort
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. This method calls link::Classes/Main#-openUDPPort:: to ensure that the port is opened.
argument:: argTemplate
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 OSCdef should respond (providing all other arguments match). Template values of nil will match any incoming argument value.
argument:: dispatcher
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.
returns:: An instance of OSCdef.
METHOD:: newMatching
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.
argument:: key
The key at which to store this OSCdef in the global collection. Generally this will be a link::Classes/Symbol::.
argument:: func
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:: [OSC address, args1, arg2, ...], 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.
argument:: path
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
argument:: srcID
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.
argument:: recvPort
An optional link::Classes/Integer:: indicating the port on which messages will be received.
argument:: argTemplate
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.
returns:: An instance of OSCdef.
METHOD:: freeAll
Clears and deactivates all OSCdefs from the global collection.
INSTANCEMETHODS::
private:: addToAll, printOn
METHOD:: key
Get this OSCdef's key.
returns:: Usually a link::Classes/Symbol::.
METHOD:: free
Clears this OSCdef from the global collection and deactivates it.
SECTION::Timing in incoming bundles
The time argument indicates the time the message was sent plus, if given, the latency added to the bundle:
CODE::
(
OSCdef(\x, { |msg, time|
"reception time: %\nscheduling time: %\ndelta: %\n\n".postf(Main.elapsedTime, time, time - Main.elapsedTime)
}, \time);
n = NetAddr("127.0.0.1", 57120);
)
(
n.sendBundle(0.0, [\time]);
n.sendBundle(1.0, [\time]);
)
::
EXAMPLES::
code::
n = NetAddr("127.0.0.1", 57120); // local machine
OSCdef(\test, {|msg, time, addr, recvPort| \unmatching.postln}, '/chat', n); // def style
OSCdef.newMatching(\test2, {|msg, time, addr, recvPort| \matching.postln}, '/chat', n); // path matching
OSCdef(\test3, {|msg, time, addr, recvPort| \oneShot.postln}, '/chat', n).oneShot; // once only
m = NetAddr("127.0.0.1", 57120); // 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");
OSCdef(\test).free; // unregister OSCdef
//////// Use an argTemplate for finer grained matching
s.boot;
x = Synth(\default);
OSCdef(\watchForXEnd, { 'ended!'.postln }, '/n_end', s.addr, nil, [x.nodeID]).oneShot;
x.release(3);
// Args for which nil is passed will use the old values. While this facilitates swapping only parts of an OSCdef, such as the function, it also means you will have to free and recreate an OSCdef to remove parts.
OSCdef(\argtest, {|msg ... args| msg[1].postln}, '/hey', argTemplate: ['you']);
m.sendMsg("/hey", "you"); // oscdef will respond
m.sendMsg("/hey", "there"); // oscdef will not respond, filtered out by argTemplate
OSCdef(\argtest, argTemplate: nil); // this has no effect
m.sendMsg("/hey", "you"); // oscdef will respond
m.sendMsg("/hey", "there"); // oscdef will not respond, still filtered out by argTemplate
OSCdef(\argtest).free; // in order to get rid of the argTemplate, free the def...
OSCdef(\argtest, {|msg ... args| msg[1].postln}, '/hey'); // ... and recreate it.
m.sendMsg("/hey", "you"); // oscdef will respond
m.sendMsg("/hey", "there"); // oscdef will respond
::
|
