1Low-level OSC API(3) Liblo Low-level OSC API(3)
2
6 Low-level OSC API -
7 Typedefs
9 typedef long double lo_hires
10 Type used to represent numerical values in conversions between OSC
11 types.
12 Functions
14 int lo_send_message (lo_address targ, const char *path, lo_message msg)
15 send a lo_message object to target targ
16 int lo_send_message_from (lo_address targ, lo_server serv, const char
17 *path, lo_message msg)
18 send a lo_message object to target targ from address of serv
19 int lo_send_bundle (lo_address targ, lo_bundle b)
20 send a lo_bundle object to address targ
21 int lo_send_bundle_from (lo_address targ, lo_server serv, lo_bundle b)
22 send a lo_bundle object to address targ from address of serv
23 lo_message lo_message_new ()
24 Create a new lo_message object.
25 void lo_message_free (lo_message m)
26 Free memory allocated by lo_message_new and any subsequent
27 lo_message_add*() calls.
28 void lo_message_add_int32 (lo_message m, int32_t a)
29 Append a data item and typechar of the specified type to a message.
30 void lo_message_add_float (lo_message m, float a)
31 Append a data item and typechar of the specified type to a message.
32 See lo_message_add_int32() for details.
33 void lo_message_add_string (lo_message m, const char *a)
34 Append a data item and typechar of the specified type to a message.
35 See lo_message_add_int32() for details.
36 void lo_message_add_blob (lo_message m, lo_blob a)
37 Append a data item and typechar of the specified type to a message.
38 See lo_message_add_int32() for details.
39 void lo_message_add_int64 (lo_message m, int64_t a)
40 Append a data item and typechar of the specified type to a message.
41 See lo_message_add_int32() for details.
42 void lo_message_add_timetag (lo_message m, lo_timetag a)
43 Append a data item and typechar of the specified type to a message.
44 See lo_message_add_int32() for details.
45 void lo_message_add_double (lo_message m, double a)
46 Append a data item and typechar of the specified type to a message.
47 See lo_message_add_int32() for details.
48 void lo_message_add_symbol (lo_message m, const char *a)
49 Append a data item and typechar of the specified type to a message.
50 See lo_message_add_int32() for details.
51 void lo_message_add_char (lo_message m, char a)
52 Append a data item and typechar of the specified type to a message.
53 See lo_message_add_int32() for details.
54 void lo_message_add_midi (lo_message m, uint8_t a[4])
55 Append a data item and typechar of the specified type to a message.
56 See lo_message_add_int32() for details.
57 void lo_message_add_true (lo_message m)
58 Append a data item and typechar of the specified type to a message.
59 See lo_message_add_int32() for details.
60 void lo_message_add_false (lo_message m)
61 Append a data item and typechar of the specified type to a message.
62 See lo_message_add_int32() for details.
63 void lo_message_add_nil (lo_message m)
64 Append a data item and typechar of the specified type to a message.
65 See lo_message_add_int32() for details.
66 void lo_message_add_infinitum (lo_message m)
67 Append a data item and typechar of the specified type to a message.
68 See lo_message_add_int32() for details.
69 lo_address lo_message_get_source (lo_message m)
70 Returns the source (lo_address) of an incoming message.
71 size_t lo_message_length (lo_message m, const char *path)
72 Return the length of a message in bytes.
73 void * lo_message_serialise (lo_message m, const char *path, void *to,
74 size_t *size)
75 Serialise the message object to an area of memory and return a
76 pointer to the serialised form.
77 const char * lo_address_get_hostname (lo_address a)
78 Return the hostname of a lo_address object.
79 const char * lo_address_get_port (lo_address a)
80 Return the port/service name of a lo_address object.
81 char * lo_address_get_url (lo_address a)
82 Return a URL representing an OSC address.
83 lo_bundle lo_bundle_new (lo_timetag tt)
84 Create a new bundle object.
85 void lo_bundle_add_message (lo_bundle b, const char *path, lo_message
86 m)
87 Adds an OSC message to an existing bundle.
88 size_t lo_bundle_length (lo_bundle b)
89 Return the length of a bundle in bytes.
90 void * lo_bundle_serialise (lo_bundle b, void *to, size_t *size)
91 Serialise the bundle object to an area of memory and return a
92 pointer to the serialised form.
93 void lo_bundle_free (lo_bundle b)
94 Frees the memory taken by a bundle object.
95 int lo_is_numerical_type (lo_type a)
96 return true if the type specified has a numerical value, such as
97 LO_INT32, LO_FLOAT etc.
98 int lo_is_string_type (lo_type a)
99 return true if the type specified has a textual value, such as
100 LO_STRING or LO_SYMBOL.
101 int lo_coerce (lo_type type_to, lo_arg *to, lo_type type_from, lo_arg
102 *from)
103 attempt to convert one OSC type to another.
104 lo_hires lo_hires_val (lo_type type, lo_arg *p)
105 return the numerical value of the given argument with the maximum
106 native system precision.
107 size_t lo_arg_size (lo_type type, void *data)
108 Return the storage size, in bytes, of the given argument.
109 void lo_arg_host_endian (lo_type type, void *data)
110 Convert the speficed argument to host endianness where neccesary.
111 lo_server lo_server_new (const char *port, lo_err_handler err_h)
112 Create a new server instance.
113 lo_server lo_server_new_with_proto (const char *port, int proto,
114 lo_err_handler err_h)
115 Create a new server instance, specifying protocol.
116 void lo_server_free (lo_server s)
117 Free up memory used by the lo_server object.
118 int lo_server_recv_noblock (lo_server s, int timeout)
119 Look for an OSC message waiting to be received.
120 int lo_server_recv (lo_server s)
121 Block, waiting for an OSC message to be received.
122 lo_method lo_server_add_method (lo_server s, const char *path, const
123 char *typespec, lo_method_handler h, void *user_data)
124 Add an OSC method to the specifed server.
125 void lo_server_del_method (lo_server s, const char *path, const char
126 *typespec)
127 Delete an OSC method from the specifed server.
128 int lo_server_get_socket_fd (lo_server s)
129 Return the file descriptor of the server socket.
130 int lo_server_get_port (lo_server s)
131 Return the port number that the server has bound to.
132 char * lo_server_get_url (lo_server s)
133 Return an OSC URL that can be used to contact the server.
134 int lo_server_events_pending (lo_server s)
135 Return true if there are scheduled events (eg. from bundles)
136 waiting to be dispatched by the server.
137 double lo_server_next_event_delay (lo_server s)
138 Return the time in seconds until the next scheduled event.
139 char * lo_url_get_protocol (const char *url)
140 Return the protocol portion of an OSC URL, eg. udp, tcp.
141 char * lo_url_get_hostname (const char *url)
142 Return the hostname portion of an OSC URL.
143 char * lo_url_get_port (const char *url)
144 Return the port portion of an OSC URL.
145 char * lo_url_get_path (const char *url)
146 Return the path portion of an OSC URL.
147 int lo_strsize (const char *s)
148 A function to calculate the amount of OSC message space required by
149 a C char *.
150 uint32_t lo_blobsize (lo_blob b)
151 A function to calculate the amount of OSC message space required by
152 a lo_blob object.
153 int lo_pattern_match (const char *str, const char *p)
154 Test a string against an OSC pattern glob.
155 int lo_send_internal (lo_address t, const char *file, const int line,
156 const char *path, const char *types,...)
157 the real send function (don't call directly)
158 int lo_send_timestamped_internal (lo_address t, const char *file, const
159 int line, lo_timetag ts, const char *path, const char *types,...)
160 the real send_timestamped function (don't call directly)
161 int lo_send_from_internal (lo_address targ, lo_server from, const char
162 *file, const int line, const lo_timetag ts, const char *path, const
163 char *types,...)
164 the real lo_send_from function (don't call directly)
165 double lo_timetag_diff (lo_timetag a, lo_timetag b)
166 Find the time difference between two timetags.
167 void lo_timetag_now (lo_timetag *t)
168 Return a timetag for the current time.
169
171 Use these functions if you require more precices control over OSC
172 message contruction or handling that what is provided in the high-level
173 functions described in liblo.
174
176 typedef long double lo_hires
177 Type used to represent numerical values in conversions between OSC
178 types.
179
181 const char* lo_address_get_hostname (lo_address a)
182 Return the hostname of a lo_address object.
183 Returned value most not be modified or free'd. Value will be a dotted
185 quad, colon'd IPV6 address, or resolvable name.
186 const char* lo_address_get_port (lo_address a)
188 Return the port/service name of a lo_address object.
189 Returned value most not be modified or free'd. Value will be a service
191 name or ASCII representation of the port number.
192 char* lo_address_get_url (lo_address a)
194 Return a URL representing an OSC address.
195 Returned value must be free'd.
197 void lo_arg_host_endian (lo_type type, void * data)
199 Convert the speficed argument to host endianness where neccesary.
200 Parameters:
202 type The OSC type of the data item (eg. LO_FLOAT).
203 data A pointer to the data item to be converted. It is change in-
204 place.
205 size_t lo_arg_size (lo_type type, void * data)
207 Return the storage size, in bytes, of the given argument.
208 uint32_t lo_blobsize (lo_blob b)
210 A function to calculate the amount of OSC message space required by a
211 lo_blob object.
212 Returns the storage size in bytes, will always be a multiple of four.
214 void lo_bundle_add_message (lo_bundle b, const char * path, lo_message m)
216 Adds an OSC message to an existing bundle.
217 The message passsed is appended to the list of messages in the bundle
219 to be dispatched to 'path'.
220 void lo_bundle_free (lo_bundle b)
222 Frees the memory taken by a bundle object.
223 size_t lo_bundle_length (lo_bundle b)
225 Return the length of a bundle in bytes.
226 Includes the marker and typetage length.
228 Parameters:
230 b The bundle to be sized
231 lo_bundle lo_bundle_new (lo_timetag tt)
233 Create a new bundle object.
234 OSC Bundles ecapsulate one or more OSC messages and may include a
236 timestamp indicating when the bundle should be dispatched.
237 Parameters:
239 tt The timestamp when the bundle should be handled by the receiver.
240 Pass LO_TT_IMMEDIATE if you want the receiving server to dispatch
241 the bundle as soon as it receives it.
242 void* lo_bundle_serialise (lo_bundle b, void * to, size_t * size)
244 Serialise the bundle object to an area of memory and return a pointer
245 to the serialised form.
246 Parameters:
248 b The bundle to be serialised
249 to The address to serialise to, memory will be allocated if to is
250 NULL.
251 size If this pointer is non-NULL the size of the memory area will
252 be written here
253 The returned form is suitable to be sent over a low level OSC
255 transport, having the correct endianess and bit-packed structure.
256 int lo_coerce (lo_type type_to, lo_arg * to, lo_type type_from, lo_arg *
258 from)
259 attempt to convert one OSC type to another.
260 Numerical types (eg LO_INT32, LO_FLOAT etc.) may be converted to other
262 numerical types and string types (LO_STRING and LO_SYMBOL) may be
263 converted to the other type. This is done automatically if a received
264 message matches the path, but not the exact types, and is coercible
265 (ie. all numerical types in numerical positions).
266 On failure no translation occurs and false is returned.
268 Parameters:
270 type_to The type of the destination variable.
271 to A pointer to the destination variable.
272 type_from The type of the source variable.
273 from A pointer to the source variable.
274 lo_hires lo_hires_val (lo_type type, lo_arg * p)
276 return the numerical value of the given argument with the maximum
277 native system precision.
278 int lo_is_numerical_type (lo_type a)
280 return true if the type specified has a numerical value, such as
281 LO_INT32, LO_FLOAT etc.
282 Parameters:
284 a The type to be tested.
285 int lo_is_string_type (lo_type a)
287 return true if the type specified has a textual value, such as
288 LO_STRING or LO_SYMBOL.
289 Parameters:
291 a The type to be tested.
292 void lo_message_add_blob (lo_message m, lo_blob a)
294 Append a data item and typechar of the specified type to a message. See
295 lo_message_add_int32() for details.
296 void lo_message_add_char (lo_message m, char a)
298 Append a data item and typechar of the specified type to a message. See
299 lo_message_add_int32() for details.
300 void lo_message_add_double (lo_message m, double a)
302 Append a data item and typechar of the specified type to a message. See
303 lo_message_add_int32() for details.
304 void lo_message_add_false (lo_message m)
306 Append a data item and typechar of the specified type to a message. See
307 lo_message_add_int32() for details.
308 void lo_message_add_float (lo_message m, float a)
310 Append a data item and typechar of the specified type to a message. See
311 lo_message_add_int32() for details.
312 void lo_message_add_infinitum (lo_message m)
314 Append a data item and typechar of the specified type to a message. See
315 lo_message_add_int32() for details.
316 void lo_message_add_int32 (lo_message m, int32_t a)
318 Append a data item and typechar of the specified type to a message.
319 The data will be added in OSC byteorder (bigendian).
321 Parameters:
323 m The message to be extended.
324 a The data item.
325 void lo_message_add_int64 (lo_message m, int64_t a)
327 Append a data item and typechar of the specified type to a message. See
328 lo_message_add_int32() for details.
329 void lo_message_add_midi (lo_message m, uint8_t a[4])
331 Append a data item and typechar of the specified type to a message. See
332 lo_message_add_int32() for details.
333 void lo_message_add_nil (lo_message m)
335 Append a data item and typechar of the specified type to a message. See
336 lo_message_add_int32() for details.
337 void lo_message_add_string (lo_message m, const char * a)
339 Append a data item and typechar of the specified type to a message. See
340 lo_message_add_int32() for details.
341 void lo_message_add_symbol (lo_message m, const char * a)
343 Append a data item and typechar of the specified type to a message. See
344 lo_message_add_int32() for details.
345 void lo_message_add_timetag (lo_message m, lo_timetag a)
347 Append a data item and typechar of the specified type to a message. See
348 lo_message_add_int32() for details.
349 void lo_message_add_true (lo_message m)
351 Append a data item and typechar of the specified type to a message. See
352 lo_message_add_int32() for details.
353 void lo_message_free (lo_message m)
355 Free memory allocated by lo_message_new and any subsequent
356 lo_message_add*() calls.
357 lo_address lo_message_get_source (lo_message m)
359 Returns the source (lo_address) of an incoming message.
360 Returns NULL if the message is outgoing. Do not free the returned
362 address.
363 size_t lo_message_length (lo_message m, const char * path)
365 Return the length of a message in bytes.
366 Parameters:
368 m The message to be sized
369 path The path the message will be sent to
370 lo_message lo_message_new ()
372 Create a new lo_message object.
373 void* lo_message_serialise (lo_message m, const char * path, void * to,
375 size_t * size)
376 Serialise the message object to an area of memory and return a pointer
377 to the serialised form.
378 Parameters:
380 m The mesaage to be serialised
381 path The path the message will be sent to
382 to The address to serialise to, memory will be allocated if to is
383 NULL.
384 size If this pointer is non-NULL the size of the memory area will
385 be written here
386 The returned form is suitable to be sent over a low level OSC
388 transport, having the correct endianess and bit-packed structure.
389 int lo_pattern_match (const char * str, const char * p)
391 Test a string against an OSC pattern glob.
392 Parameters:
394 str The tring to test
395 p The pattern to test against
396 int lo_send_bundle (lo_address targ, lo_bundle b)
398 send a lo_bundle object to address targ
399 Bundles are constructed with the lo_bundle_new() and
401 lo_bundle_add_message() functions.
402 int lo_send_bundle_from (lo_address targ, lo_server serv, lo_bundle b)
404 send a lo_bundle object to address targ from address of serv
405 Bundles are constructed with the lo_bundle_new() and
407 lo_bundle_add_message() functions.
408 Parameters:
410 targ The address to send the bundle to
411 serv The server socket to send the bundle from (can be NULL to use
412 new socket)
413 b The bundle itself
414 int lo_send_from_internal (lo_address targ, lo_server from, const char *
416 file, const int line, const lo_timetag ts, const char * path, const
417 char * types, ...)
418 the real lo_send_from function (don't call directly)
419 int lo_send_internal (lo_address t, const char * file, const int line,
421 const char * path, const char * types, ...)
422 the real send function (don't call directly)
423 int lo_send_message (lo_address targ, const char * path, lo_message msg)
425 send a lo_message object to target targ
426 This is slightly more efficient than lo_send if you want to send a lot
428 of similar messages. The messages are constructed with the
429 lo_message_new() and lo_message_add*() functions.
430 int lo_send_message_from (lo_address targ, lo_server serv, const char *
432 path, lo_message msg)
433 send a lo_message object to target targ from address of serv
434 This is slightly more efficient than lo_send if you want to send a lot
436 of similar messages. The messages are constructed with the
437 lo_message_new() and lo_message_add*() functions.
438 Parameters:
440 targ The address to send the message to
441 serv The server socket to send the message from (can be NULL to use
442 new socket)
443 path The path to send the message to
444 msg The bundle itself
445 int lo_send_timestamped_internal (lo_address t, const char * file, const
447 int line, lo_timetag ts, const char * path, const char * types, ...)
448 the real send_timestamped function (don't call directly)
449 lo_method lo_server_add_method (lo_server s, const char * path, const char
451 * typespec, lo_method_handler h, void * user_data)
452 Add an OSC method to the specifed server.
453 Parameters:
455 s The server the method is to be added to.
456 path The OSC path to register the method to. If NULL is passed the
457 method will match all paths.
458 typespec The typespec the method accepts. Incoming messages with
459 similar typespecs (e.g. ones with numerical types in the same
460 position) will be coerced to the typespec given here.
461 h The method handler callback function that will be called if a
462 matching message is received
463 user_data A value that will be passed to the callback function, h,
464 when its invoked matching from this method.
465 void lo_server_del_method (lo_server s, const char * path, const char *
467 typespec)
468 Delete an OSC method from the specifed server.
469 Parameters:
471 s The server the method is to be removed from.
472 path The OSC path of the method to delete. If NULL is passed the
473 method will match the generic handler.
474 typespec The typespec the method accepts.
475 int lo_server_events_pending (lo_server s)
477 Return true if there are scheduled events (eg. from bundles) waiting to
478 be dispatched by the server.
479 void lo_server_free (lo_server s)
481 Free up memory used by the lo_server object.
482 int lo_server_get_port (lo_server s)
484 Return the port number that the server has bound to.
485 Useful when NULL is passed for the port number and you wish to know how
487 to address the server.
488 int lo_server_get_socket_fd (lo_server s)
490 Return the file descriptor of the server socket.
491 If the server protocol supports exposing the server's underlying
493 receive mechanism for monitoring with select() or poll(), this function
494 returns the file descriptor needed, otherwise, it returns -1.
495 WARNING: when using this function beware that not all OSC packets that
497 are received are dispatched immediatly. lo_server_events_pending() and
498 lo_server_next_event_delay() can be used to tell if there are pending
499 events and how long before you should attempt to receive them.
500 char* lo_server_get_url (lo_server s)
502 Return an OSC URL that can be used to contact the server.
503 The return value should bee free()'d when it is no longer needed.
505 lo_server lo_server_new (const char * port, lo_err_handler err_h)
507 Create a new server instance.
508 lo_servers block until they receive OSC messages. if you want non-
510 blocking behaviour see the lo_server_thread_* functions.
511 Parameters:
513 port If NULL is passed then an unused UDP port will be chosen by
514 the system, its number may be retreived with
515 lo_server_thread_get_port() so it can be passed to clients.
516 Otherwise a decimal port number, service name or UNIX domain socket
517 path may be passed.
518 err_h An error callback function that will be called if there is an
519 error in messge reception or server creation. Pass NULL if you do
520 not want error handling.
521 lo_server lo_server_new_with_proto (const char * port, int proto,
523 lo_err_handler err_h)
524 Create a new server instance, specifying protocol.
525 lo_servers block until they receive OSC messages. if you want non-
527 blocking behaviour see the lo_server_thread_* functions.
528 Parameters:
530 port If using UDP then NULL may be passed to find an unused port.
531 Otherwise a decimal port number orservice name or may be passed. If
532 using UNIX domain sockets then a socket path should be passed here.
533 proto The protocol to use, should be one of LO_UDP, LO_TCP or
534 LO_UNIX.
535 err_h An error callback function that will be called if there is an
536 error in messge reception or server creation. Pass NULL if you do
537 not want error handling.
538 double lo_server_next_event_delay (lo_server s)
540 Return the time in seconds until the next scheduled event.
541 If the delay is greater than 100 seconds then it will return 100.0.
543 int lo_server_recv (lo_server s)
545 Block, waiting for an OSC message to be received.
546 The return value is the number of bytes in the received message. The
548 message will be dispatched to a matching method if one is found.
549 int lo_server_recv_noblock (lo_server s, int timeout)
551 Look for an OSC message waiting to be received.
552 Parameters:
554 s The server to wait for connections on.
555 timeout A timeout in milliseconds to wait for the incoming packet.
556 a value of 0 will return immediatly.
557 The return value is the number of bytes in the received message or 0 is
559 there is no message. The message will be dispatched to a matching
560 method if one is found.
561 int lo_strsize (const char * s)
563 A function to calculate the amount of OSC message space required by a C
564 char *.
565 Returns the storage size in bytes, will always be a multiple of four.
567 double lo_timetag_diff (lo_timetag a, lo_timetag b)
569 Find the time difference between two timetags.
570 Returns a - b in seconds.
572 void lo_timetag_now (lo_timetag * t)
574 Return a timetag for the current time.
575 On exit the timetag pointed to by t is filled with the OSC
577 represenation of this instant in time.
578 char* lo_url_get_hostname (const char * url)
580 Return the hostname portion of an OSC URL.
581 The return value should bee free()'d when it is no longer needed.
583 char* lo_url_get_path (const char * url)
585 Return the path portion of an OSC URL.
586 The return value should bee free()'d when it is no longer needed.
588 char* lo_url_get_port (const char * url)
590 Return the port portion of an OSC URL.
591 The return value should bee free()'d when it is no longer needed.
593 char* lo_url_get_protocol (const char * url)
595 Return the protocol portion of an OSC URL, eg. udp, tcp.
596 This library uses OSC URLs of the form: osc.prot://hostname:port/path
598 if the prot part is missing, UDP is assumed.
599 The return value should bee free()'d when it is no longer needed.
601Version 0.23 22 Feb 2007 Low-level OSC API(3)