liblo 0.32
lo_lowlevel.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2014 Steve Harris et al. (see AUTHORS)
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public License
6 * as published by the Free Software Foundation; either version 2.1
7 * of the License, or (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU Lesser General Public License for more details.
13 *
14 * $Id$
15 */
16
17#ifndef LO_LOWLEVEL_H
18#define LO_LOWLEVEL_H
19
20#include "lo/lo_osc_types.h"
21
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31#include <stdarg.h>
32#include <sys/types.h>
33#ifdef _MSC_VER
34#include <BaseTsd.h>
35typedef SSIZE_T ssize_t;
36#endif
37#include <stdint.h>
38
39
40#include "lo/lo_types.h"
41#include "lo/lo_errors.h"
42
51
56typedef long double lo_hires;
57
58
69typedef struct {
70 size_t size;
71 const char *group;
72 const char *port;
73 const char *iface;
74 const char *ip;
75 int proto;
76 lo_err_handler err_handler;
77 void *err_handler_context;
79
85typedef enum {
86 LO_SLIP_NONE = 0,
87 LO_SLIP_SINGLE = 1,
88 LO_SLIP_DOUBLE = 2
90
98int lo_send_message(lo_address targ, const char *path, lo_message msg);
99
114 const char *path, lo_message msg);
115
123
136
141
151
156
162
176int lo_message_add(lo_message m, const char *types, ...);
177
179int lo_message_add_internal(lo_message m, const char *file, const int line,
180 const char *types, ...);
181
200int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
201
203int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
204 const char *file, const int line);
205
217
225
232int lo_message_add_string(lo_message m, const char *a);
233
241
249
257
265
272int lo_message_add_symbol(lo_message m, const char *a);
273
281
288int lo_message_add_midi(lo_message m, uint8_t a[4]);
289
297
305
313
321
331
339
346
353
360
367size_t lo_message_length(lo_message m, const char *path);
368
383void *lo_message_serialise(lo_message m, const char *path, void *to,
384 size_t *size);
385
399lo_message lo_message_deserialise(void *data, size_t size, int *result);
400
416int lo_server_dispatch_data(lo_server s, void *data, size_t size);
417
425
433
440
447
459
467
485int lo_address_set_iface(lo_address t, const char *iface, const char *ip);
486
497
505
514
526
536
545int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
546
556
565
572
581
590
600 const char **path);
601
610
624void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
625
632
639
646
654
662
679int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from);
680
686
703lo_server lo_server_new(const char *port, lo_err_handler err_h);
704
721lo_server lo_server_new_with_proto(const char *port, int proto,
722 lo_err_handler err_h);
723
736lo_server lo_server_new_multicast(const char *group, const char *port,
737 lo_err_handler err_h);
738
757lo_server lo_server_new_multicast_iface(const char *group, const char *port,
758 const char *iface, const char *ip,
759 lo_err_handler err_h);
760
772 lo_err_handler err_h);
773
781
788int lo_server_enable_coercion(lo_server server, int enable);
789
794
806int lo_server_wait(lo_server s, int timeout);
807
821int lo_servers_wait(lo_server *s, int *status, int num_servers, int timeout);
822
835
849int lo_servers_recv_noblock(lo_server *s, int *recvd, int num_servers,
850 int timeout);
851
859
876 const char *typespec, lo_method_handler h,
877 const void *user_data);
878
887void lo_server_del_method(lo_server s, const char *path,
888 const char *typespec);
889
899
914 void *user_data);
915
929
937
944
951
969int lo_server_enable_queue(lo_server s, int queue_enabled,
970 int dispatch_remaining);
971
977
984
1004
1013char *lo_url_get_protocol(const char *url);
1014
1026int lo_url_get_protocol_id(const char *url);
1027
1033char *lo_url_get_hostname(const char *url);
1034
1040char *lo_url_get_port(const char *url);
1041
1047char *lo_url_get_path(const char *url);
1048
1049/* utility functions */
1050
1057int lo_strsize(const char *s);
1058
1066
1074int lo_pattern_match(const char *str, const char *p);
1075
1082int lo_string_contains_pattern(const char *str);
1083
1085int lo_send_internal(lo_address t, const char *file, const int line,
1086 const char *path, const char *types, ...);
1088int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
1089 lo_timetag ts, const char *path, const char *types, ...);
1091int lo_send_from_internal(lo_address targ, lo_server from, const char *file,
1092 const int line, const lo_timetag ts,
1093 const char *path, const char *types, ...);
1094
1095
1101
1108
1112size_t lo_arg_size(lo_type type, void *data);
1113
1123char *lo_get_path(void *data, ssize_t size);
1124
1132void lo_arg_host_endian(lo_type type, void *data);
1133
1141void lo_arg_network_endian(lo_type type, void *data);
1142
1144
1145/* prettyprinters */
1146
1154
1157
1160
1166void lo_arg_pp(lo_type type, void *data);
1167
1170
1173
1176void lo_method_pp_prefix(lo_method m, const char *p);
1177
1179
1180#ifdef __cplusplus
1181}
1182#endif
1183
1184#endif
lo_element_type
An enumeration of bundle element types liblo can handle.
lo_type
An enumeration of the OSC types liblo can send and receive.
long double lo_hires
Type used to represent numerical values in conversions between OSC types.
Definition lo_lowlevel.h:56
void * lo_message_serialise(lo_message m, const char *path, void *to, size_t *size)
Serialise the lo_message object to an area of memory and return a pointer to the serialised form....
int lo_message_add_timetag(lo_message m, lo_timetag a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_server_events_pending(lo_server s)
Return true if there are scheduled events (eg. from bundles) waiting to be dispatched by the server.
int lo_url_get_protocol_id(const char *url)
Return the protocol ID of an OSC URL.
size_t lo_message_length(lo_message m, const char *path)
Return the length of a message in bytes.
const char * lo_address_get_hostname(lo_address a)
Return the hostname of a lo_address object.
lo_server lo_server_new_from_config(lo_server_config *config)
Create a new server instance, using a configuration struct.
lo_server lo_server_new_from_url(const char *url, lo_err_handler err_h)
Create a new server instance, taking port and the optional multicast group IP from an URL string.
int lo_server_add_bundle_handlers(lo_server s, lo_bundle_start_handler sh, lo_bundle_end_handler eh, void *user_data)
Add bundle notification handlers to the specified server.
lo_timetag lo_message_get_timestamp(lo_message m)
Returns the timestamp (lo_timetag *) of a bundled incoming message.
int lo_send_message(lo_address targ, const char *path, lo_message msg)
Send a lo_message object to target targ.
int lo_server_enable_coercion(lo_server server, int enable)
Enables or disables type coercion during message dispatch.
char * lo_server_get_url(lo_server s)
Return an OSC URL that can be used to contact the server.
lo_message lo_bundle_get_message(lo_bundle b, int index, const char **path)
Gets a message contained within a bundle.
int lo_message_add_false(lo_message m)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m)
Adds an OSC message to an existing bundle.
lo_message lo_message_new(void)
Create a new lo_message object.
lo_address lo_message_get_source(lo_message m)
Returns the source (lo_address) of an incoming message.
uint32_t lo_blobsize(lo_blob b)
A function to calculate the amount of OSC message space required by a lo_blob object.
int lo_string_contains_pattern(const char *str)
Test if a string contains any OSC pattern characters.
void lo_bundle_free_messages(lo_bundle b)
Obsolete, use lo_bundle_free_recursive instead.
int lo_message_add_int64(lo_message m, int64_t a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
char * lo_message_get_types(lo_message m)
Return the message type tag string.
void lo_arg_host_endian(lo_type type, void *data)
Convert the specified argument to host byte order where necessary.
int lo_servers_recv_noblock(lo_server *s, int *recvd, int num_servers, int timeout)
Look for an OSC message waiting to be received on multiple servers.
void lo_bundle_free(lo_bundle b)
Frees the memory taken by a bundle object.
lo_message lo_message_deserialise(void *data, size_t size, int *result)
Deserialise a raw OSC message and return a new lo_message object. Opposite of lo_message_serialise().
lo_slip_encoding
Used with lo_address_set_stream_slip() to specify whether sent messages should be encoded with SLIP,...
Definition lo_lowlevel.h:85
lo_bundle lo_bundle_new(lo_timetag tt)
Create a new bundle object.
int lo_server_wait(lo_server s, int timeout)
Wait for an OSC message to be received.
int lo_address_get_ttl(lo_address t)
Get the Time-to-Live value for a given target address.
int lo_server_enable_queue(lo_server s, int queue_enabled, int dispatch_remaining)
Toggle event queue. If queueing is enabled, timetagged messages that are sent in advance of the curre...
int lo_message_add_float(lo_message m, float a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
lo_server lo_server_new_with_proto(const char *port, int proto, lo_err_handler err_h)
Create a new server instance, specifying protocol.
int lo_message_add_infinitum(lo_message m)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_message_add(lo_message m, const char *types,...)
Append a number of arguments to a message.
int lo_message_add_string(lo_message m, const char *a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_server_get_port(lo_server s)
Return the port number that the server has bound to.
lo_method lo_server_add_method(lo_server s, const char *path, const char *typespec, lo_method_handler h, const void *user_data)
Add an OSC method to the specifed server.
int lo_message_get_argc(lo_message m)
Return the message argument count.
lo_arg ** lo_message_get_argv(lo_message m)
Return the message arguments. Do not free the returned data.
int lo_address_set_iface(lo_address t, const char *iface, const char *ip)
Set the network interface to use for a given target address.
double lo_server_next_event_delay(lo_server s)
Return the time in seconds until the next scheduled event.
int lo_server_recv_noblock(lo_server s, int timeout)
Look for an OSC message waiting to be received.
lo_server lo_server_new(const char *port, lo_err_handler err_h)
Create a new server instance.
unsigned int lo_bundle_count(lo_bundle b)
Return the number of top-level elements in a bundle.
int lo_message_add_int32(lo_message m, int32_t a)
Append a data item and typechar of the specified type to a message.
int lo_address_set_stream_slip(lo_address t, lo_slip_encoding encoding)
Set outgoing stream connections (e.g., TCP) to be transmitted using the SLIP packetizing protocol.
lo_server lo_server_new_multicast(const char *group, const char *port, lo_err_handler err_h)
Create a new server instance, and join a UDP multicast group.
lo_element_type lo_bundle_get_type(lo_bundle b, int index)
Gets the element type contained within a bundle.
lo_message lo_message_clone(lo_message m)
Create a new lo_message object by cloning an already existing one.
void lo_bundle_free_recursive(lo_bundle b)
Frees the memory taken by a bundle object and its messages and nested bundles recursively.
int lo_message_add_symbol(lo_message m, const char *a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
const char * lo_address_get_iface(lo_address t)
Get the name of the network interface assigned to an OSC address.
void lo_message_free(lo_message m)
Free memory allocated by lo_message_new() and any subsequent lo_message_add_int32 lo_message_add*() c...
int lo_server_max_msg_size(lo_server s, int req_size)
Set the maximum message size accepted by a server.
char * lo_url_get_hostname(const char *url)
Return the hostname portion of an OSC URL.
double lo_timetag_diff(lo_timetag a, lo_timetag b)
Find the time difference between two timetags.
int lo_message_add_varargs(lo_message m, const char *types, va_list ap)
Append a varargs list to a message.
int lo_send_message_from(lo_address targ, lo_server serv, const char *path, lo_message msg)
Send a lo_message object to target targ from address of serv.
int lo_address_set_tcp_nodelay(lo_address t, int enable)
Set the TCP_NODELAY flag on outgoing TCP connections.
int lo_message_add_true(lo_message m)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_server_dispatch_data(lo_server s, void *data, size_t size)
Dispatch a raw block of memory containing an OSC message.
size_t lo_bundle_length(lo_bundle b)
Return the length of a bundle in bytes.
int lo_servers_wait(lo_server *s, int *status, int num_servers, int timeout)
Wait on multiple servers for an OSC message to be received.
int lo_address_get_protocol(lo_address a)
Return the protocol of a lo_address object.
int lo_message_add_midi(lo_message m, uint8_t a[4])
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
lo_bundle lo_bundle_get_bundle(lo_bundle b, int index)
Gets a nested bundle contained within a bundle.
int lo_message_add_char(lo_message m, char a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_server_get_protocol(lo_server s)
Return the protocol that the server is using.
int lo_send_bundle_from(lo_address targ, lo_server serv, lo_bundle b)
Send a lo_bundle object to address targ from address of serv.
int lo_server_del_lo_method(lo_server s, lo_method m)
Delete a specific OSC method from the specified server.
int lo_message_add_nil(lo_message m)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_message_add_blob(lo_message m, lo_blob a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
int lo_pattern_match(const char *str, const char *p)
Test a string against an OSC pattern glob.
const char * lo_address_get_port(lo_address a)
Return the port/service name of a lo_address object.
void lo_address_set_ttl(lo_address t, int ttl)
Set the Time-to-Live value for a given target address.
int lo_is_numerical_type(lo_type a)
Return true if the type specified has a numerical value, such as LO_INT32, LO_FLOAT etc.
char * lo_address_get_url(lo_address a)
Return a URL representing an OSC address.
int lo_send_bundle(lo_address targ, lo_bundle b)
Send a lo_bundle object to address targ.
char * lo_get_path(void *data, ssize_t size)
Given a raw OSC message, return the message path.
int lo_bundle_add_bundle(lo_bundle b, lo_bundle n)
Adds an OSC bundle to an existing bundle.
void lo_server_free(lo_server s)
Free up memory used by the lo_server object.
void lo_timetag_now(lo_timetag *t)
Return a timetag for the current time.
void lo_arg_network_endian(lo_type type, void *data)
Convert the specified argument to network byte order where necessary.
char * lo_url_get_protocol(const char *url)
Return the protocol portion of an OSC URL, eg. udp, tcp.
int lo_message_add_double(lo_message m, double a)
Append a data item and typechar of the specified type to a message. See lo_message_add_int32() for de...
lo_server lo_server_new_multicast_iface(const char *group, const char *port, const char *iface, const char *ip, lo_err_handler err_h)
Create a new server instance, and join a UDP multicast group, optionally specifying which network int...
int lo_server_get_socket_fd(lo_server s)
Return the file descriptor of the server socket.
void lo_message_incref(lo_message m)
Add one to a message's reference count.
int lo_strsize(const char *s)
A function to calculate the amount of OSC message space required by a C char *.
int lo_is_string_type(lo_type a)
Return true if the type specified has a textual value, such as LO_STRING or LO_SYMBOL.
int lo_server_recv(lo_server s)
Block, waiting for an OSC message to be received.
char * lo_url_get_port(const char *url)
Return the port portion of an OSC URL.
lo_timetag lo_bundle_get_timestamp(lo_bundle b)
Get the timestamp associated with a bundle.
void lo_bundle_incref(lo_bundle b)
Add one to a bundle's reference count.
size_t lo_arg_size(lo_type type, void *data)
Return the storage size, in bytes, of the given argument.
void * lo_bundle_serialise(lo_bundle b, void *to, size_t *size)
Serialise the bundle object to an area of memory and return a pointer to the serialised form.
void lo_server_del_method(lo_server s, const char *path, const char *typespec)
Delete an OSC method from the specified server.
int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from)
Attempt to convert one OSC type to another.
char * lo_url_get_path(const char *url)
Return the path portion of an OSC URL.
lo_hires lo_hires_val(lo_type type, lo_arg *p)
Return the numerical value of the given argument with the maximum native system precision.
void lo_arg_pp(lo_type type, void *data)
Pretty-print a set of typed arguments.
void lo_method_pp_prefix(lo_method m, const char *p)
Pretty-print a lo_method object, but prepend a given prefix to all field names.
void lo_method_pp(lo_method m)
Pretty-print a lo_method object.
void lo_server_pp(lo_server s)
Pretty-print a lo_server object.
void lo_message_pp(lo_message m)
Pretty-print a lo_message object.
void lo_bundle_pp(lo_bundle b)
Pretty-print a lo_bundle object.
struct lo_server_ * lo_server
An object representing an instance of an OSC server.
Definition lo_types.h:85
int(* lo_bundle_start_handler)(lo_timetag time, void *user_data)
A callback function to receive notification of a bundle being dispatched by the server or server thre...
Definition lo_types.h:155
struct lo_address_ * lo_address
A reference to an OSC service.
Definition lo_types.h:45
struct lo_message_ * lo_message
A low-level object used to represent messages passed over OSC.
Definition lo_types.h:60
int(* lo_method_handler)(const char *path, const char *types, lo_arg **argv, int argc, lo_message msg, void *user_data)
A callback function to receive notification of matching message arriving in the server or server thre...
Definition lo_types.h:134
struct lo_blob_ * lo_blob
A object to store an opaque binary data object.
Definition lo_types.h:52
void(* lo_err_handler)(int num, const char *msg, const char *where)
A callback function to receive notification of an error in a server or server thread.
Definition lo_types.h:105
int(* lo_bundle_end_handler)(void *user_data)
A callback function to receive notification of a bundle dispatch being completed by the server or ser...
Definition lo_types.h:166
struct lo_bundle_ * lo_bundle
A low-level object used to represent bundles of messages passed over OSC.
Definition lo_types.h:69
struct lo_method_ * lo_method
An object representing an method on a server.
Definition lo_types.h:77
A configuration struct for initializing lo_server using lo_server_new_from_config().
Definition lo_lowlevel.h:69
A structure to store OSC TimeTag values.
Union used to read values from incoming messages.