Real Time Open Sound Control librtosc
rtosc.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2012 Mark McCurry
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and associated documentation files (the "Software"),
6  * to deal in the Software without restriction, including without limitation
7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8  * and/or sell copies of the Software, and to permit persons to whom the
9  * Software is furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice (including the next
12  * paragraph) shall be included in all copies or substantial portions of the
13  * Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  * DEALINGS IN THE SOFTWARE.
23  */
24 
30 #ifndef RTOSC_H
31 #define RTOSC_H
32 #include <stdarg.h>
33 #include <stdint.h>
34 #include <stddef.h>
35 #include <stdbool.h>
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 typedef struct {
42  int32_t len;
43  uint8_t *data;
44 } rtosc_blob_t;
45 
50 typedef struct {
51  char type;
52  int32_t len;
54 
56 typedef struct
57 {
59  int32_t num;
60  int32_t has_delta;
61 } repeater_t;
62 
65 typedef struct
66 {
67  int32_t len;
68 } nothing_t;
69 
70 typedef union {
71 // types that can be used in messages
72  int32_t i; //i,c,r
73  char T; //I,T,F,N (F=>0, T=>1, I=>n/a, N=>n/a)
74  float f; //f
75  double d; //d
76  int64_t h; //h
77  uint64_t t; //t
78  uint8_t m[4];//m
79  const char *s; //s,S
80  rtosc_blob_t b; //b
81 // types that can *not* be used in messages
82  array_start_t a; //a,' '
83  repeater_t r; //-
84 } rtosc_arg_t;
85 
86 typedef struct {
87  char type;
88  rtosc_arg_t val;
90 
116 size_t rtosc_message(char *buffer,
117  size_t len,
118  const char *address,
119  const char *arguments,
120  ...);
121 
125 size_t rtosc_vmessage(char *buffer,
126  size_t len,
127  const char *address,
128  const char *arguments,
129  va_list va);
130 
134 size_t rtosc_avmessage(char *buffer,
135  size_t len,
136  const char *address,
137  size_t nargs,
138  const rtosc_arg_val_t *args);
139 
143 size_t rtosc_amessage(char *buffer,
144  size_t len,
145  const char *address,
146  const char *arguments,
147  const rtosc_arg_t *args);
148 
155 unsigned rtosc_narguments(const char *msg);
156 
162 char rtosc_type(const char *msg, unsigned i);
163 
164 typedef struct {
165  const char *type_pos;
166  const uint8_t *value_pos;
168 
169 typedef struct
170 {
174 
175 /*
176  * arg val iterators
177  */
185 typedef struct
186 {
188  size_t i;
189  int range_i;
191 
192 void rtosc_arg_val_itr_init(rtosc_arg_val_itr* itr,
193  const rtosc_arg_val_t* av);
198  const rtosc_arg_val_itr* itr,
199  rtosc_arg_val_t* buffer);
202 
204 typedef struct { va_list a; } rtosc_va_list_t;
205 
214 void rtosc_v2args(rtosc_arg_t* args, size_t nargs,
215  const char* arg_str, rtosc_va_list_t* ap);
216 
221 void rtosc_v2argvals(rtosc_arg_val_t* args, size_t nargs,
222  const char* arg_str, va_list ap);
223 
228 void rtosc_2argvals(rtosc_arg_val_t* args, size_t nargs,
229  const char* arg_str, ...);
230 
236 rtosc_arg_itr_t rtosc_itr_begin(const char *msg);
237 
244 
251 
258 rtosc_arg_t rtosc_argument(const char *msg, unsigned i);
259 
265 size_t rtosc_message_length(const char *msg, size_t len);
266 
267 typedef struct {
268  char *data;
269  size_t len;
270 } ring_t;
271 
279 size_t rtosc_message_ring_length(ring_t *ring);
280 
281 
287 bool rtosc_valid_message_p(const char *msg, size_t len);
288 
293 const char *rtosc_argument_string(const char *msg);
294 
305 size_t rtosc_bundle(char *buffer, size_t len, uint64_t tt, int elms, ...);
306 
314 size_t rtosc_bundle_elements(const char *msg, size_t len);
315 
323 const char *rtosc_bundle_fetch(const char *msg, unsigned i);
324 
332 size_t rtosc_bundle_size(const char *msg, unsigned i);
333 
340 int rtosc_bundle_p(const char *msg);
341 
345 uint64_t rtosc_bundle_timetag(const char *msg);
346 
347 
360 bool rtosc_match(const char *pattern,
361  const char *msg, const char** path_end);
362 
363 
372 const char *rtosc_match_path(const char *pattern,
373  const char *msg, const char** path_end);
374 
375 #ifdef __cplusplus
376 };
377 #endif
378 #endif
indicates that the next nothing_t::len blocks count as if nonexistant they might contain rubbish
Definition: rtosc.h:65
Definition: rtosc.h:70
const char * rtosc_match_path(const char *pattern, const char *msg, const char **path_end)
Attempt to match a rtosc style path while ignoring arguments.
void rtosc_arg_val_itr_next(rtosc_arg_val_itr *itr)
a repeater is being followed by a delta argument (unless has_delta is 0)
Definition: rtosc.h:56
Definition: rtosc.h:41
size_t rtosc_bundle(char *buffer, size_t len, uint64_t tt, int elms,...)
Generate a bundle from sub-messages.
char type
common type of the elements
Definition: rtosc.h:51
va_list container, required for passing va_list as pointers to functions
Definition: rtosc.h:204
const rtosc_arg_val_t * av
the arg val referenced
Definition: rtosc.h:187
Definition: rtosc.h:86
size_t rtosc_bundle_size(const char *msg, unsigned i)
Get the size of a particular bundle element.
size_t rtosc_vmessage(char *buffer, size_t len, const char *address, const char *arguments, va_list va)
double float_tolerance
< tolerance to when two floats or doubles are equal
Definition: rtosc.h:172
Definition: rtosc.h:164
size_t rtosc_message(char *buffer, size_t len, const char *address, const char *arguments,...)
Write OSC message to fixed length buffer.
arg val element indicating an array, or a block of "nothing" blocks of "nothing" are just for interna...
Definition: rtosc.h:50
uint64_t rtosc_bundle_timetag(const char *msg)
rtosc_arg_val_t rtosc_itr_next(rtosc_arg_itr_t *itr)
Gets the next argument in a message.
size_t i
position of this arg val
Definition: rtosc.h:188
size_t rtosc_bundle_elements(const char *msg, size_t len)
Find the elements in a bundle.
rtosc_arg_itr_t rtosc_itr_begin(const char *msg)
Create an argument iterator for a message.
const char * rtosc_argument_string(const char *msg)
int32_t has_delta
if not 0, the next argument is the delta
Definition: rtosc.h:60
int rtosc_itr_end(rtosc_arg_itr_t itr)
Determines if the iterator is at the end of the argument list.
char rtosc_type(const char *msg, unsigned i)
size_t rtosc_message_length(const char *msg, size_t len)
const rtosc_arg_val_t * rtosc_arg_val_itr_get(const rtosc_arg_val_itr *itr, rtosc_arg_val_t *buffer)
this usually just returns the value from operand, except for range operands, where the value is being...
size_t rtosc_message_ring_length(ring_t *ring)
Finds the length of the next message inside a ringbuffer structure.
int rtosc_bundle_p(const char *msg)
Test if the buffer contains a bundle.
int32_t num
how often the first element is being repeated, including itself
Definition: rtosc.h:59
int range_i
position of this arg val in its range
Definition: rtosc.h:189
void rtosc_v2argvals(rtosc_arg_val_t *args, size_t nargs, const char *arg_str, va_list ap)
Pack parameters into pre-allocated rtosc_arg_val-t array.
bool rtosc_valid_message_p(const char *msg, size_t len)
Validate if an arbitrary byte sequence is an OSC message.
unsigned rtosc_narguments(const char *msg)
Returns the number of arguments found in a given message.
rtosc_arg_t rtosc_argument(const char *msg, unsigned i)
Blob data may be safely written to.
Definition: rtosc.h:267
size_t rtosc_amessage(char *buffer, size_t len, const char *address, const char *arguments, const rtosc_arg_t *args)
const char * rtosc_bundle_fetch(const char *msg, unsigned i)
Fetch a message within the bundle.
void rtosc_2argvals(rtosc_arg_val_t *args, size_t nargs, const char *arg_str,...)
Pack parameters into pre-allocated rtosc_arg_val-t array.
int32_t len
number of arg_val_t (or "nothing") contained
Definition: rtosc.h:52
Iterator over arg values.
Definition: rtosc.h:185
bool rtosc_match(const char *pattern, const char *msg, const char **path_end)
This is a non-compliant pattern matcher for dispatching OSC messages.
void rtosc_v2args(rtosc_arg_t *args, size_t nargs, const char *arg_str, rtosc_va_list_t *ap)
Pack arguments into pre-allocated rtosc_arg_t array.
Definition: rtosc.h:169
size_t rtosc_avmessage(char *buffer, size_t len, const char *address, size_t nargs, const rtosc_arg_val_t *args)