liblo  0.29
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
28 extern "C" {
29 #endif
30 
31 #include <stdarg.h>
32 #include <sys/types.h>
33 #ifdef _MSC_VER
34 #define ssize_t SSIZE_T
35 #define uint32_t unsigned __int32
36 #else
37 #include <stdint.h>
38 #endif
39 
40 #include "lo/lo_types.h"
41 #include "lo/lo_errors.h"
42 
56 typedef long double lo_hires;
57 
58 
59 
60 
68 int lo_send_message(lo_address targ, const char *path, lo_message msg);
69 
84  const char *path, lo_message msg);
85 
93 
106 
111 
121 
126 
132 
146 int lo_message_add(lo_message m, const char *types, ...);
147 
149 int lo_message_add_internal(lo_message m, const char *file, const int line,
150  const char *types, ...);
151 
170 int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
171 
173 int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
174  const char *file, const int line);
175 
186 int lo_message_add_int32(lo_message m, int32_t a);
187 
194 int lo_message_add_float(lo_message m, float a);
195 
202 int lo_message_add_string(lo_message m, const char *a);
203 
211 
218 int lo_message_add_int64(lo_message m, int64_t a);
219 
227 
234 int lo_message_add_double(lo_message m, double a);
235 
242 int lo_message_add_symbol(lo_message m, const char *a);
243 
250 int lo_message_add_char(lo_message m, char a);
251 
258 int lo_message_add_midi(lo_message m, uint8_t a[4]);
259 
267 
275 
283 
291 
298 
306 
313 
320 
327 
334 size_t lo_message_length(lo_message m, const char *path);
335 
350 void *lo_message_serialise(lo_message m, const char *path, void *to,
351  size_t *size);
352 
366 lo_message lo_message_deserialise(void *data, size_t size, int *result);
367 
383 int lo_server_dispatch_data(lo_server s, void *data, size_t size);
384 
391 const char *lo_address_get_hostname(lo_address a);
392 
399 const char *lo_address_get_port(lo_address a);
400 
407 
414 
425 void lo_address_set_ttl(lo_address t, int ttl);
426 
434 
452 int lo_address_set_iface(lo_address t, const char *iface, const char *ip);
453 
463 const char* lo_address_get_iface(lo_address t);
464 
471 int lo_address_set_tcp_nodelay(lo_address t, int enable);
472 
480 int lo_address_set_stream_slip(lo_address t, int enable);
481 
493 
503 
512 int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
513 
523 
531 size_t lo_bundle_length(lo_bundle b);
532 
538 unsigned int lo_bundle_count(lo_bundle b);
539 
548 
557 
567  const char **path);
568 
577 
591 void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
592 
598 void lo_bundle_free(lo_bundle b);
599 
606 
613 
621 
629 
646 int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from);
647 
652 lo_hires lo_hires_val(lo_type type, lo_arg *p);
653 
670 lo_server lo_server_new(const char *port, lo_err_handler err_h);
671 
688 lo_server lo_server_new_with_proto(const char *port, int proto,
689  lo_err_handler err_h);
690 
703 lo_server lo_server_new_multicast(const char *group, const char *port,
704  lo_err_handler err_h);
705 
724 lo_server lo_server_new_multicast_iface(const char *group, const char *port,
725  const char *iface, const char *ip,
726  lo_err_handler err_h);
727 
738 lo_server lo_server_new_from_url(const char *url,
739  lo_err_handler err_h);
740 
747 int lo_server_enable_coercion(lo_server server, int enable);
748 
752 void lo_server_free(lo_server s);
753 
765 int lo_server_wait(lo_server s, int timeout);
766 
778 int lo_server_recv_noblock(lo_server s, int timeout);
779 
787 
803 lo_method lo_server_add_method(lo_server s, const char *path,
804  const char *typespec, lo_method_handler h,
805  const void *user_data);
806 
815 void lo_server_del_method(lo_server s, const char *path,
816  const char *typespec);
817 
827 
842  void *user_data);
843 
857 
865 
872 
879 
897 int lo_server_enable_queue(lo_server s, int queue_enabled,
898  int dispatch_remaining);
899 
905 
912 
931 int lo_server_max_msg_size(lo_server s, int req_size);
932 
941 char *lo_url_get_protocol(const char *url);
942 
954 int lo_url_get_protocol_id(const char *url);
955 
961 char *lo_url_get_hostname(const char *url);
962 
968 char *lo_url_get_port(const char *url);
969 
975 char *lo_url_get_path(const char *url);
976 
977 /* utility functions */
978 
985 int lo_strsize(const char *s);
986 
993 uint32_t lo_blobsize(lo_blob b);
994 
1001 int lo_pattern_match(const char *str, const char *p);
1002 
1004 int lo_send_internal(lo_address t, const char *file, const int line,
1005  const char *path, const char *types, ...);
1007 int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
1008  lo_timetag ts, const char *path, const char *types, ...);
1010 int lo_send_from_internal(lo_address targ, lo_server from, const char *file,
1011  const int line, const lo_timetag ts,
1012  const char *path, const char *types, ...);
1013 
1014 
1020 
1026 void lo_timetag_now(lo_timetag *t);
1027 
1031 size_t lo_arg_size(lo_type type, void *data);
1032 
1042 char *lo_get_path(void *data, ssize_t size);
1043 
1051 void lo_arg_host_endian(lo_type type, void *data);
1052 
1060 void lo_arg_network_endian(lo_type type, void *data);
1061 
1064 /* prettyprinters */
1065 
1075 void lo_bundle_pp(lo_bundle b);
1076 
1078 void lo_message_pp(lo_message m);
1079 
1085 void lo_arg_pp(lo_type type, void *data);
1086 
1088 void lo_server_pp(lo_server s);
1089 
1091 void lo_method_pp(lo_method m);
1092 
1095 void lo_method_pp_prefix(lo_method m, const char *p);
1096 
1099 #ifdef __cplusplus
1100 }
1101 #endif
1102 
1103 #endif
void lo_arg_host_endian(lo_type type, void *data)
Convert the specified argument to host byte order where necessary.
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_message lo_bundle_get_message(lo_bundle b, int index, const char **path)
Gets a message contained within a bundle.
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...
void lo_bundle_free_messages(lo_bundle b)
Obsolete, use lo_bundle_free_recursive instead.
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...
lo_timetag lo_bundle_get_timestamp(lo_bundle b)
Get the timestamp associated with a bundle.
lo_timetag lo_message_get_timestamp(lo_message m)
Returns the timestamp (lo_timetag *) of a bundled incoming message.
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...
char * lo_url_get_hostname(const char *url)
Return the hostname portion of an OSC URL.
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...
lo_message lo_message_new()
Create a new lo_message object.
lo_message lo_message_clone(lo_message m)
Create a new lo_message object by cloning an already existing one.
lo_server lo_server_new(const char *port, lo_err_handler err_h)
Create a new server instance.
int lo_message_get_argc(lo_message m)
Return the message argument count.
Union used to read values from incoming messages.
Definition: lo_osc_types.h:115
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_element_type
An enumeration of bundle element types liblo can handle.
Definition: lo_osc_types.h:59
lo_element_type lo_bundle_get_type(lo_bundle b, int index)
Gets the element type contained within a bundle.
int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m)
Adds an OSC message to an existing bundle.
void lo_bundle_incref(lo_bundle b)
Add one to a bundle&#39;s reference count.
void lo_method_pp(lo_method m)
Pretty-print a lo_method object.
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...
int lo_message_add(lo_message m, const char *types,...)
Append a number of arguments to a message.
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_address_get_ttl(lo_address t)
Get the Time-to-Live value for a given target address.
int lo_send_bundle(lo_address targ, lo_bundle b)
Send a lo_bundle object to address targ.
A structure to store OSC TimeTag values.
Definition: lo_osc_types.h:46
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_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_strsize(const char *s)
A function to calculate the amount of OSC message space required by a C char *.
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...
void lo_server_del_method(lo_server s, const char *path, const char *typespec)
Delete an OSC method from the specified server.
lo_address lo_message_get_source(lo_message m)
Returns the source (lo_address) of an incoming message.
void lo_arg_pp(lo_type type, void *data)
Pretty-print a set of typed arguments.
long double lo_hires
Type used to represent numerical values in conversions between OSC types.
Definition: lo_lowlevel.h:56
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.
char * lo_url_get_path(const char *url)
Return the path portion of an OSC URL.
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.
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...
char * lo_url_get_port(const char *url)
Return the port portion of an OSC URL.
lo_bundle lo_bundle_new(lo_timetag tt)
Create a new bundle object.
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...
char * lo_url_get_protocol(const char *url)
Return the protocol portion of an OSC URL, eg. udp, tcp.
void lo_server_free(lo_server s)
Free up memory used by the lo_server 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
lo_arg ** lo_message_get_argv(lo_message m)
Return the message arguments. Do not free the returned data.
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_bundle_pp(lo_bundle b)
Pretty-print a lo_bundle object.
char * lo_get_path(void *data, ssize_t size)
Given a raw OSC message, return the message path.
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.
const char * lo_address_get_port(lo_address a)
Return the port/service name of a lo_address object.
int lo_address_get_protocol(lo_address a)
Return the protocol of a lo_address object.
int lo_pattern_match(const char *str, const char *p)
Test a string against an OSC pattern glob.
size_t lo_message_length(lo_message m, const char *path)
Return the length of a message in bytes.
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_send_message(lo_address targ, const char *path, lo_message msg)
Send a lo_message object to target targ.
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...
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...
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
int lo_server_enable_coercion(lo_server server, int enable)
Enables or disables type coercion during message dispatch.
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, int enable)
Set outgoing stream connections (e.g., TCP) to be transmitted using the SLIP packetizing protocol...
lo_bundle lo_bundle_get_bundle(lo_bundle b, int index)
Gets a nested bundle contained within a bundle.
const char * lo_address_get_iface(lo_address t)
Get the name of the network interface assigned to an OSC address.
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.
int lo_address_set_tcp_nodelay(lo_address t, int enable)
Set the TCP_NODELAY flag on outgoing TCP connections.
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()...
const char * lo_address_get_hostname(lo_address a)
Return the hostname of a lo_address object.
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_recv_noblock(lo_server s, int timeout)
Look for an OSC message waiting to be received.
size_t lo_arg_size(lo_type type, void *data)
Return the storage size, in bytes, of the given argument.
int lo_bundle_add_bundle(lo_bundle b, lo_bundle n)
Adds an OSC bundle to an existing bundle.
void * lo_blob
A object to store an opaque binary data object.
Definition: lo_types.h:52
char * lo_server_get_url(lo_server s)
Return an OSC URL that can be used to contact the server.
void * lo_address
A reference to an OSC service.
Definition: lo_types.h:45
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_server_get_port(lo_server s)
Return the port number that the server has bound to.
double lo_server_next_event_delay(lo_server s)
Return the time in seconds until the next scheduled event.
size_t lo_bundle_length(lo_bundle b)
Return the length of a bundle in bytes.
void lo_arg_network_endian(lo_type type, void *data)
Convert the specified argument to network byte order where necessary.
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...
int lo_message_add_varargs(lo_message m, const char *types, va_list ap)
Append a varargs list to a message.
double lo_timetag_diff(lo_timetag a, lo_timetag b)
Find the time difference between two timetags.
char * lo_address_get_url(lo_address a)
Return a URL representing an OSC address.
int lo_server_get_socket_fd(lo_server s)
Return the file descriptor of the server socket.
void lo_bundle_free(lo_bundle b)
Frees the memory taken by a bundle object.
int lo_server_dispatch_data(lo_server s, void *data, size_t size)
Dispatch a raw block of memory containing an OSC message.
void * lo_message
A low-level object used to represent messages passed over OSC.
Definition: lo_types.h:60
int lo_server_del_lo_method(lo_server s, lo_method m)
Delete a specific OSC method from the specified server.
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...
void lo_bundle_free_recursive(lo_bundle b)
Frees the memory taken by a bundle object and its messages and nested bundles recursively.
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_server_get_protocol(lo_server s)
Return the protocol that the server is using.
int lo_server_recv(lo_server s)
Block, waiting for an OSC message to be received.
void * lo_server
An object representing an instance of an OSC server.
Definition: lo_types.h:85
int lo_server_max_msg_size(lo_server s, int req_size)
Set the maximum message size accepted by a server.
void lo_message_incref(lo_message m)
Add one to a message&#39;s reference count.
void lo_server_pp(lo_server s)
Pretty-print a lo_server object.
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
void lo_timetag_now(lo_timetag *t)
Return a timetag for the current time.
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.
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...
char * lo_message_get_types(lo_message m)
Return the message type tag string.
int lo_url_get_protocol_id(const char *url)
Return the protocol ID of an OSC URL.
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.
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...
unsigned int lo_bundle_count(lo_bundle b)
Return the number of top-level elements in 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_server_wait(lo_server s, int timeout)
Wait for an OSC message to be received.
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.
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_method
An object representing an method on a server.
Definition: lo_types.h:77
void * lo_bundle
A low-level object used to represent bundles of messages passed over OSC.
Definition: lo_types.h:69
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_type
An enumeration of the OSC types liblo can send and receive.
Definition: lo_osc_types.h:72
void lo_message_pp(lo_message m)
Pretty-print a lo_message object.
void lo_address_set_ttl(lo_address t, int ttl)
Set the Time-to-Live value for a given target address.