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
28 extern "C" {
29 #endif
30 
31 #include <stdarg.h>
32 #include <sys/types.h>
33 #ifdef _MSC_VER
34 typedef 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 
55 typedef long double lo_hires;
56 
57 
58 
59 
67 int 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 
145 int lo_message_add(lo_message m, const char *types, ...);
146 
148 int lo_message_add_internal(lo_message m, const char *file, const int line,
149  const char *types, ...);
150 
169 int lo_message_add_varargs(lo_message m, const char *types, va_list ap);
170 
172 int lo_message_add_varargs_internal(lo_message m, const char *types, va_list ap,
173  const char *file, const int line);
174 
185 int lo_message_add_int32(lo_message m, int32_t a);
186 
193 int lo_message_add_float(lo_message m, float a);
194 
201 int lo_message_add_string(lo_message m, const char *a);
202 
210 
217 int lo_message_add_int64(lo_message m, int64_t a);
218 
226 
233 int lo_message_add_double(lo_message m, double a);
234 
241 int lo_message_add_symbol(lo_message m, const char *a);
242 
249 int lo_message_add_char(lo_message m, char a);
250 
257 int lo_message_add_midi(lo_message m, uint8_t a[4]);
258 
266 
274 
282 
290 
297 
305 
312 
319 
326 
333 size_t lo_message_length(lo_message m, const char *path);
334 
349 void *lo_message_serialise(lo_message m, const char *path, void *to,
350  size_t *size);
351 
365 lo_message lo_message_deserialise(void *data, size_t size, int *result);
366 
382 int lo_server_dispatch_data(lo_server s, void *data, size_t size);
383 
390 const char *lo_address_get_hostname(lo_address a);
391 
398 const char *lo_address_get_port(lo_address a);
399 
406 
413 
424 void lo_address_set_ttl(lo_address t, int ttl);
425 
433 
451 int lo_address_set_iface(lo_address t, const char *iface, const char *ip);
452 
462 const char* lo_address_get_iface(lo_address t);
463 
470 int lo_address_set_tcp_nodelay(lo_address t, int enable);
471 
479 int lo_address_set_stream_slip(lo_address t, int enable);
480 
492 
502 
511 int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m);
512 
522 
530 size_t lo_bundle_length(lo_bundle b);
531 
537 unsigned int lo_bundle_count(lo_bundle b);
538 
547 
556 
566  const char **path);
567 
576 
590 void *lo_bundle_serialise(lo_bundle b, void *to, size_t *size);
591 
597 void lo_bundle_free(lo_bundle b);
598 
605 
612 
620 
628 
645 int lo_coerce(lo_type type_to, lo_arg *to, lo_type type_from, lo_arg *from);
646 
652 
669 lo_server lo_server_new(const char *port, lo_err_handler err_h);
670 
687 lo_server lo_server_new_with_proto(const char *port, int proto,
688  lo_err_handler err_h);
689 
702 lo_server lo_server_new_multicast(const char *group, const char *port,
703  lo_err_handler err_h);
704 
723 lo_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 
737 lo_server lo_server_new_from_url(const char *url,
738  lo_err_handler err_h);
739 
746 int lo_server_enable_coercion(lo_server server, int enable);
747 
751 void lo_server_free(lo_server s);
752 
764 int lo_server_wait(lo_server s, int timeout);
765 
779 int lo_servers_wait(lo_server *s, int *status, int num_servers, int timeout);
780 
792 int lo_server_recv_noblock(lo_server s, int timeout);
793 
807 int lo_servers_recv_noblock(lo_server *s, int *recvd, int num_servers,
808  int timeout);
809 
817 
833 lo_method lo_server_add_method(lo_server s, const char *path,
834  const char *typespec, lo_method_handler h,
835  const void *user_data);
836 
845 void 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 
927 int lo_server_enable_queue(lo_server s, int queue_enabled,
928  int dispatch_remaining);
929 
935 
942 
961 int lo_server_max_msg_size(lo_server s, int req_size);
962 
971 char *lo_url_get_protocol(const char *url);
972 
984 int lo_url_get_protocol_id(const char *url);
985 
991 char *lo_url_get_hostname(const char *url);
992 
998 char *lo_url_get_port(const char *url);
999 
1005 char *lo_url_get_path(const char *url);
1006 
1007 /* utility functions */
1008 
1015 int lo_strsize(const char *s);
1016 
1023 uint32_t lo_blobsize(lo_blob b);
1024 
1031 int lo_pattern_match(const char *str, const char *p);
1032 
1034 int lo_send_internal(lo_address t, const char *file, const int line,
1035  const char *path, const char *types, ...);
1037 int lo_send_timestamped_internal(lo_address t, const char *file, const int line,
1038  lo_timetag ts, const char *path, const char *types, ...);
1040 int 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 
1056 void lo_timetag_now(lo_timetag *t);
1057 
1061 size_t lo_arg_size(lo_type type, void *data);
1062 
1072 char *lo_get_path(void *data, ssize_t size);
1073 
1081 void lo_arg_host_endian(lo_type type, void *data);
1082 
1090 void lo_arg_network_endian(lo_type type, void *data);
1091 
1094 /* prettyprinters */
1095 
1105 void lo_bundle_pp(lo_bundle b);
1106 
1108 void lo_message_pp(lo_message m);
1109 
1115 void lo_arg_pp(lo_type type, void *data);
1116 
1118 void lo_server_pp(lo_server s);
1119 
1121 void lo_method_pp(lo_method m);
1122 
1125 void lo_method_pp_prefix(lo_method m, const char *p);
1126 
1129 #ifdef __cplusplus
1130 }
1131 #endif
1132 
1133 #endif
lo_message_get_types
char * lo_message_get_types(lo_message m)
Return the message type tag string.
lo_get_path
char * lo_get_path(void *data, ssize_t size)
Given a raw OSC message, return the message path.
lo_message_pp
void lo_message_pp(lo_message m)
Pretty-print a lo_message object.
lo_bundle_free_recursive
void lo_bundle_free_recursive(lo_bundle b)
Frees the memory taken by a bundle object and its messages and nested bundles recursively.
lo_message_add_int64
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...
lo_message_add_varargs
int lo_message_add_varargs(lo_message m, const char *types, va_list ap)
Append a varargs list to a message.
lo_bundle_end_handler
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
lo_address_get_url
char * lo_address_get_url(lo_address a)
Return a URL representing an OSC address.
lo_url_get_port
char * lo_url_get_port(const char *url)
Return the port portion of an OSC URL.
lo_bundle_get_bundle
lo_bundle lo_bundle_get_bundle(lo_bundle b, int index)
Gets a nested bundle contained within a bundle.
lo_url_get_protocol_id
int lo_url_get_protocol_id(const char *url)
Return the protocol ID of an OSC URL.
lo_address_get_port
const char * lo_address_get_port(lo_address a)
Return the port/service name of a lo_address object.
lo_server_add_method
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.
lo_message_add_false
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...
lo_timetag
A structure to store OSC TimeTag values.
Definition: lo_osc_types.h:35
lo_arg_pp
void lo_arg_pp(lo_type type, void *data)
Pretty-print a set of typed arguments.
lo_server
void * lo_server
An object representing an instance of an OSC server.
Definition: lo_types.h:85
lo_arg_size
size_t lo_arg_size(lo_type type, void *data)
Return the storage size, in bytes, of the given argument.
lo_method_pp
void lo_method_pp(lo_method m)
Pretty-print a lo_method object.
lo_coerce
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.
lo_address_set_tcp_nodelay
int lo_address_set_tcp_nodelay(lo_address t, int enable)
Set the TCP_NODELAY flag on outgoing TCP connections.
lo_server_new_with_proto
lo_server lo_server_new_with_proto(const char *port, int proto, lo_err_handler err_h)
Create a new server instance, specifying protocol.
lo_blobsize
uint32_t lo_blobsize(lo_blob b)
A function to calculate the amount of OSC message space required by a lo_blob object.
lo_server_get_port
int lo_server_get_port(lo_server s)
Return the port number that the server has bound to.
lo_url_get_hostname
char * lo_url_get_hostname(const char *url)
Return the hostname portion of an OSC URL.
lo_message_add_midi
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_length
size_t lo_bundle_length(lo_bundle b)
Return the length of a bundle in bytes.
lo_server_new
lo_server lo_server_new(const char *port, lo_err_handler err_h)
Create a new server instance.
lo_server_new_multicast_iface
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...
lo_server_get_protocol
int lo_server_get_protocol(lo_server s)
Return the protocol that the server is using.
lo_message_length
size_t lo_message_length(lo_message m, const char *path)
Return the length of a message in bytes.
lo_osc_types.h
lo_bundle_add_message
int lo_bundle_add_message(lo_bundle b, const char *path, lo_message m)
Adds an OSC message to an existing bundle.
lo_server_recv
int lo_server_recv(lo_server s)
Block, waiting for an OSC message to be received.
lo_method_pp_prefix
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.
lo_bundle_free_messages
void lo_bundle_free_messages(lo_bundle b)
Obsolete, use lo_bundle_free_recursive instead.
lo_address_get_iface
const char * lo_address_get_iface(lo_address t)
Get the name of the network interface assigned to an OSC address.
lo_types.h
lo_server_del_lo_method
int lo_server_del_lo_method(lo_server s, lo_method m)
Delete a specific OSC method from the specified server.
lo_server_events_pending
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.
lo_message_deserialise
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_address_get_ttl
int lo_address_get_ttl(lo_address t)
Get the Time-to-Live value for a given target address.
lo_message_incref
void lo_message_incref(lo_message m)
Add one to a message's reference count.
lo_method
void * lo_method
An object representing an method on a server.
Definition: lo_types.h:77
lo_bundle_get_message
lo_message lo_bundle_get_message(lo_bundle b, int index, const char **path)
Gets a message contained within a bundle.
lo_is_string_type
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.
lo_message_get_source
lo_address lo_message_get_source(lo_message m)
Returns the source (lo_address) of an incoming message.
lo_message_get_timestamp
lo_timetag lo_message_get_timestamp(lo_message m)
Returns the timestamp (lo_timetag *) of a bundled incoming message.
lo_address_set_iface
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.
lo_server_new_from_url
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.
lo_bundle_get_timestamp
lo_timetag lo_bundle_get_timestamp(lo_bundle b)
Get the timestamp associated with a bundle.
lo_server_next_event_delay
double lo_server_next_event_delay(lo_server s)
Return the time in seconds until the next scheduled event.
lo_blob
void * lo_blob
A object to store an opaque binary data object.
Definition: lo_types.h:52
lo_bundle_pp
void lo_bundle_pp(lo_bundle b)
Pretty-print a lo_bundle object.
lo_servers_recv_noblock
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.
lo_bundle_count
unsigned int lo_bundle_count(lo_bundle b)
Return the number of top-level elements in a bundle.
lo_address_set_ttl
void lo_address_set_ttl(lo_address t, int ttl)
Set the Time-to-Live value for a given target address.
lo_bundle_free
void lo_bundle_free(lo_bundle b)
Frees the memory taken by a bundle object.
lo_message_add_char
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_bundle_incref
void lo_bundle_incref(lo_bundle b)
Add one to a bundle's reference count.
lo_is_numerical_type
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.
lo_message_new
lo_message lo_message_new(void)
Create a new lo_message object.
lo_message_add_float
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_message_add_double
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_strsize
int lo_strsize(const char *s)
A function to calculate the amount of OSC message space required by a C char *.
lo_address_get_protocol
int lo_address_get_protocol(lo_address a)
Return the protocol of a lo_address object.
lo_pattern_match
int lo_pattern_match(const char *str, const char *p)
Test a string against an OSC pattern glob.
lo_server_new_multicast
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_arg_host_endian
void lo_arg_host_endian(lo_type type, void *data)
Convert the specified argument to host byte order where necessary.
lo_send_message
int lo_send_message(lo_address targ, const char *path, lo_message msg)
Send a lo_message object to target targ.
lo_timetag_now
void lo_timetag_now(lo_timetag *t)
Return a timetag for the current time.
lo_bundle
void * lo_bundle
A low-level object used to represent bundles of messages passed over OSC.
Definition: lo_types.h:69
lo_message_add_nil
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...
lo_server_max_msg_size
int lo_server_max_msg_size(lo_server s, int req_size)
Set the maximum message size accepted by a server.
lo_message_add_blob
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_serialise
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....
lo_message_add
int lo_message_add(lo_message m, const char *types,...)
Append a number of arguments to a message.
lo_bundle_start_handler
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_url_get_protocol
char * lo_url_get_protocol(const char *url)
Return the protocol portion of an OSC URL, eg. udp, tcp.
lo_arg
Union used to read values from incoming messages.
Definition: lo_osc_types.h:104
lo_message_add_symbol
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...
lo_bundle_serialise
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.
lo_message_get_argv
lo_arg ** lo_message_get_argv(lo_message m)
Return the message arguments. Do not free the returned data.
lo_server_enable_coercion
int lo_server_enable_coercion(lo_server server, int enable)
Enables or disables type coercion during message dispatch.
lo_type
lo_type
An enumeration of the OSC types liblo can send and receive.
Definition: lo_osc_types.h:61
lo_server_get_url
char * lo_server_get_url(lo_server s)
Return an OSC URL that can be used to contact the server.
lo_bundle_new
lo_bundle lo_bundle_new(lo_timetag tt)
Create a new bundle object.
lo_server_wait
int lo_server_wait(lo_server s, int timeout)
Wait for an OSC message to be received.
lo_element_type
lo_element_type
An enumeration of bundle element types liblo can handle.
Definition: lo_osc_types.h:48
lo_address_get_hostname
const char * lo_address_get_hostname(lo_address a)
Return the hostname of a lo_address object.
lo_message_get_argc
int lo_message_get_argc(lo_message m)
Return the message argument count.
lo_server_add_bundle_handlers
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_arg_network_endian
void lo_arg_network_endian(lo_type type, void *data)
Convert the specified argument to network byte order where necessary.
lo_method_handler
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
lo_message_add_infinitum
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...
lo_err_handler
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
lo_address
void * lo_address
A reference to an OSC service.
Definition: lo_types.h:45
lo_bundle_get_type
lo_element_type lo_bundle_get_type(lo_bundle b, int index)
Gets the element type contained within a bundle.
lo_send_bundle_from
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.
lo_server_pp
void lo_server_pp(lo_server s)
Pretty-print a lo_server object.
lo_server_enable_queue
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...
lo_message_clone
lo_message lo_message_clone(lo_message m)
Create a new lo_message object by cloning an already existing one.
lo_message_add_string
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...
lo_server_del_method
void lo_server_del_method(lo_server s, const char *path, const char *typespec)
Delete an OSC method from the specified server.
lo_servers_wait
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.
lo_timetag_diff
double lo_timetag_diff(lo_timetag a, lo_timetag b)
Find the time difference between two timetags.
lo_hires
long double lo_hires
Type used to represent numerical values in conversions between OSC types.
Definition: lo_lowlevel.h:55
lo_url_get_path
char * lo_url_get_path(const char *url)
Return the path portion of an OSC URL.
lo_message_add_int32
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_recv_noblock
int lo_server_recv_noblock(lo_server s, int timeout)
Look for an OSC message waiting to be received.
lo_message_free
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...
lo_send_bundle
int lo_send_bundle(lo_address targ, lo_bundle b)
Send a lo_bundle object to address targ.
lo_message_add_timetag
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...
lo_hires_val
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.
lo_server_free
void lo_server_free(lo_server s)
Free up memory used by the lo_server object.
lo_message_add_true
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...
lo_server_get_socket_fd
int lo_server_get_socket_fd(lo_server s)
Return the file descriptor of the server socket.
lo_send_message_from
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.
lo_bundle_add_bundle
int lo_bundle_add_bundle(lo_bundle b, lo_bundle n)
Adds an OSC bundle to an existing bundle.
lo_message
void * lo_message
A low-level object used to represent messages passed over OSC.
Definition: lo_types.h:60
lo_address_set_stream_slip
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_server_dispatch_data
int lo_server_dispatch_data(lo_server s, void *data, size_t size)
Dispatch a raw block of memory containing an OSC message.