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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<class name = "zosc" state = "draft">
<!--
Copyright (c) the Contributors as noted in the AUTHORS file.
This file is part of CZMQ, the high-level C binding for 0MQ:
http://czmq.zeromq.org.
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
Create and decode Open Sound Control messages. (OSC)
OSC is a serialisation format (and usually transported over UDP) which is
supported by many applications and appliances. It is a de facto protocol
for networking sound synthesizers, computers, and other multimedia devices
for purposes such as musical performance or show control. It is also often
used for rapid prototyping purposes due to the support by many applications
and frameworks in this field. With ZeroMQ's DGRAM sockets it is possible
to use ZeroMQ to send and receive OSC messages which can be understood by
any device supporting OSC.
Example creating an OSC message:
zosc_t* conm = zosc_create("/someaddress", "iihfdscF",
1, 2, 3, 3.14, 6.283185307179586, "greetings", 'q');
Decoding a message:
int rc = zosc_retr(oscmsg, "iihfdscF", &intx, &inty, &intz, &floatz,
&doublez, &strings, &charq, &someBool);
See the class's test method for more examples how to use the class.
<constructor>
Create a new empty OSC message with the specified address string.
<argument name = "address" type = "string" />
</constructor>
<constructor name = "fromframe">
Create a new OSC message from the specified zframe. Takes ownership of
the zframe.
<argument name = "frame" type = "zframe" />
</constructor>
<constructor name = "frommem" state = "draft">
Create a new zosc message from memory. Take ownership of the memory
and calling free on the data after construction.
<argument name = "data" type = "buffer" c_type = "char *" />
<argument name = "size" type = "size" />
</constructor>
<constructor name = "create">
Create a new zosc message from the given format and arguments.
The format type tags are as follows:
i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob
<argument name = "address" type = "string" />
<argument name = "format" type = "string" variadic = "1" />
</constructor>
<destructor>
Destroy an OSC message
</destructor>
<method name = "size">
Return chunk data size
<return type = "size" />
</method>
<method name = "data">
Return OSC chunk data. Caller does not own the data!
<return type = "buffer" mutable = "1" size = ".size" />
</method>
<method name = "address">
Return the OSC address string
<return type = "string" />
</method>
<method name = "format">
Return the OSC format of the message.
i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob
<return type = "string" />
</method>
<method name = "append">
Append data to the osc message. The format describes the data that
needs to be appended in the message. This essentially relocates all
data!
The format type tags are as follows:
i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob
<argument name = "format" type = "string" variadic = "1" />
<return type = "integer" />
</method>
<method name = "retr">
Retrieve the values provided by the given format. Note that zosc_retr
creates the objects and the caller must destroy them when finished.
The supplied pointers do not need to be initialized. Returns 0 if
successful, or -1 if it failed to retrieve a value in which case the
pointers are not modified. If an argument pointer is NULL is skips the
value. See the format method for a detailed list op type tags for the
format string.
<argument name = "format" type = "string" variadic = "1" />
<return type = "integer" />
</method>
<method name = "dup">
Create copy of the message, as new chunk object. Returns a fresh zosc_t
object, or null if there was not enough heap memory. If chunk is null,
returns null.
<return type = "zosc" fresh = "1" />
</method>
<method name = "pack">
Transform zosc into a zframe that can be sent in a message.
<return type = "zframe" fresh = "1" />
</method>
<method name = "packx" state = "draft" singleton = "1">
Transform zosc into a zframe that can be sent in a message.
Take ownership of the chunk.
<argument name = "self_p" type = "zosc" by_reference = "1" />
<return type = "zframe" fresh = "1" />
</method>
<method name = "unpack" singleton = "1">
Transform a zframe into a zosc.
<argument name = "frame" type = "zframe" mutable = "1" />
<return type = "zosc" fresh = "1" />
</method>
<method name = "print">
Dump OSC message to stdout, for debugging and tracing.
</method>
<method name = "is" singleton = "1">
Probe the supplied object, and report if it looks like a zosc_t.
<argument name = "self" type = "anything" mutable = "1" />
<return type = "boolean" />
</method>
<method name = "first">
Return a pointer to the item at the head of the OSC data.
Sets the given char argument to the type tag of the data.
If the message is empty, returns NULL and the sets the
given char to NULL.
<argument name = "type" type = "char" by_reference = "1" />
<return type = "anything" mutable = "0" />
</method>
<method name = "next">
Return the next item of the OSC message. If the list is empty, returns
NULL. To move to the start of the OSC message call zosc_first ().
<argument name = "type" type = "char" by_reference = "1" />
<return type = "anything" mutable = "0" />
</method>
<method name = "last">
Return a pointer to the item at the tail of the OSC message.
Sets the given char argument to the type tag of the data. If
the message is empty, returns NULL.
<argument name = "type" type = "char" by_reference = "1" />
<return type = "anything" mutable = "0" />
</method>
<method name = "pop int32">
Set the provided 32 bit integer from value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success.
<argument name = "val" type = "integer" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop int64">
Set the provided 64 bit integer from the value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success.
<argument name = "val" type = "msecs" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop float">
Set the provided float from the value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success.
<argument name = "val" type = "real" size = "4" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop double">
Set the provided double from the value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success.
<argument name = "val" type = "real" size = "8" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop string">
Set the provided string from the value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success. Caller owns the string!
<argument name = "val" type = "string" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop char">
Set the provided char from the value at the current cursor position in the message.
If the type tag at the current position does not correspond it will fail and
return -1. Returns 0 on success.
<argument name = "val" type = "char" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop bool">
Set the provided boolean from the type tag in the message. Booleans are not represented
in the data in the message, only in the type tag. If the type tag at the current
position does not correspond it will fail and return -1. Returns 0 on success.
<argument name = "val" type = "boolean" by_reference = "1" />
<return type = "integer" />
</method>
<method name = "pop midi">
Set the provided 4 bytes (unsigned 32bit int) from the value at the current
cursor position in the message. If the type tag at the current position does
not correspond it will fail and return -1. Returns 0 on success.
<argument name = "val" type = "number" size = "4" by_reference = "1" />
<return type = "integer" />
</method>
</class>
|
