liblo 0.31
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
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31#include <stdarg.h>
32#include <sys/types.h>
33#ifdef _MSC_VER
34typedef SSIZE_T ssize_t;
35#endif
36#include <stdint.h>
37
38
39#include "lo/lo_types.h"
40#include "lo/lo_errors.h"
41
55typedef long double lo_hires;
56
57
58
59
67int lo_send_message(lo_address targ, const char *path, lo_message msg);
68
83 const char *path, lo_message msg);
84
92
105
110
120
125
131
145int lo_message_add(lo_message m, const char *types, ...);
146
148int lo_message_add_internal(lo_message m, const char *file, const int line,
149 const char *types, ...);
150
169int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
170
172int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
173 const char *file, const int line);
174
186
194
201int lo_message_add_string(lo_message m, const char *a);
202
210
218
226
234
241int lo_message_add_symbol(lo_message m, const char *a);
242
250
257int lo_message_add_midi(lo_message m, uint8_t a[4]);
258
266
274
282
290
297
305
312
319
326
333size_t lo_message_length(lo_message m, const char *path);
334
349void *lo_message_serialise(lo_message m, const char *path, void *to,
350 size_t *size);
351
365lo_message lo_message_deserialise(void *data, size_t size, int *result);
366
382int lo_server_dispatch_data(lo_server s, void *data, size_t size);
383
391
399
406
413
425
433
451int lo_address_set_iface(lo_address t, const char *iface, const char *ip);
452
463
471
480
492
502
511int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
512
522
531
538
547
556
566 const char **path);
567
576
590void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
591
598
605
612
620
628
645int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from);
646
652
669lo_server lo_server_new(const char *port, lo_err_handler err_h);
670
687lo_server lo_server_new_with_proto(const char *port, int proto,
688 lo_err_handler err_h);
689
702lo_server lo_server_new_multicast(const char *group, const char *port,
703 lo_err_handler err_h);
704
723lo_server lo_server_new_multicast_iface(const char *group, const char *port,
724 const char *iface, const char *ip,
725 lo_err_handler err_h);
726
738 lo_err_handler err_h);
739
746int lo_server_enable_coercion(lo_server server, int enable);
747
752
764int lo_server_wait(lo_server s, int timeout);
765
779int lo_servers_wait(lo_server *s, int *status, int num_servers, int timeout);
780
793
807int lo_servers_recv_noblock(lo_server *s, int *recvd, int num_servers,
808 int timeout);
809
817
834 const char *typespec, lo_method_handler h,
835 const void *user_data);
836
845void lo_server_del_method(lo_server s, const char *path,
846 const char *typespec);
847
857
872 void *user_data);
873
887
895
902
909
927int lo_server_enable_queue(lo_server s, int queue_enabled,
928 int dispatch_remaining);
929
935
942
962
971char *lo_url_get_protocol(const char *url);
972
984int lo_url_get_protocol_id(const char *url);
985
991char *lo_url_get_hostname(const char *url);
992
998char *lo_url_get_port(const char *url);
999
1005char *lo_url_get_path(const char *url);
1006
1007/* utility functions */
1008
1015int lo_strsize(const char *s);
1016
1024
1031int lo_pattern_match(const char *str, const char *p);
1032
1034int lo_send_internal(lo_address t, const char *file, const int line,
1035 const char *path, const char *types, ...);
1037int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
1038 lo_timetag ts, const char *path, const char *types, ...);
1040int lo_send_from_internal(lo_address targ, lo_server from, const char *file,
1041 const int line, const lo_timetag ts,
1042 const char *path, const char *types, ...);
1043
1044
1050
1057
1061size_t lo_arg_size(lo_type type, void *data);
1062
1072char *lo_get_path(void *data, ssize_t size);
1073
1081void lo_arg_host_endian(lo_type type, void *data);
1082
1090void lo_arg_network_endian(lo_type type, void *data);
1091
1094/* prettyprinters */
1095
1106
1109
1115void lo_arg_pp(lo_type type, void *data);
1116
1119
1122
1125void lo_method_pp_prefix(lo_method m, const char *p);
1126
1129#ifdef __cplusplus
1130}
1131#endif
1132
1133#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:55
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_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.
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_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.
int lo_address_set_stream_slip(lo_address t, int enable)
Set outgoing stream connections (e.g., TCP) to be transmitted using the SLIP packetizing protocol.
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.
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.
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
void * lo_server
An object representing an instance of an OSC server.
Definition lo_types.h:85
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
void * lo_method
An object representing an method on a server.
Definition lo_types.h:77
void * lo_blob
A object to store an opaque binary data object.
Definition lo_types.h:52
void * lo_bundle
A low-level object used to represent bundles of messages passed over OSC.
Definition lo_types.h:69
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
void * lo_address
A reference to an OSC service.
Definition lo_types.h:45
void * lo_message
A low-level object used to represent messages passed over OSC.
Definition lo_types.h:60
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
A structure to store OSC TimeTag values.
Union used to read values from incoming messages.