Classes
struct	lo_timetag
	A structure to store OSC TimeTag values. More...
union	lo_arg
	Union used to read values from incoming messages. More...

Macros
#define	LO_TT_IMMEDIATE ((lo_timetag){0U,1U})
	A timetag constant representing "now".

Enumerations
enum	lo_type { LO_INT32 = 'i', LO_FLOAT = 'f', LO_STRING = 's', LO_BLOB = 'b', LO_INT64 = 'h', LO_TIMETAG = 't', LO_DOUBLE = 'd', LO_SYMBOL = 'S', LO_CHAR = 'c', LO_MIDI = 'm', LO_TRUE = 'T', LO_FALSE = 'F', LO_NIL = 'N', LO_INFINITUM = 'I' }
	An enumeration of the OSC types liblo can send and receive. More...

Functions
lo_address	lo_address_new (const char host, const char port)
	Declare an OSC destination, given IP address and port number. Same as lo_address_new_with_proto(), but using UDP.
lo_address	lo_address_new_with_proto (int proto, const char host, const char port)
	Declare an OSC destination, given IP address and port number, specifying protocol.
lo_address	lo_address_new_from_url (const char *url)
	Create a lo_address object from an OSC URL.
void	lo_address_free (lo_address t)
	Free the memory used by the 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_address_get_ttl (lo_address t)
	Get the Time-to-Live value for a given target address.
int	lo_send (lo_address targ, const char path, const char type,...)
	Send a OSC formatted message to the address specified.
int	lo_send_from (lo_address targ, lo_server from, lo_timetag ts, const char path, const char type,...)
	Send a OSC formatted message to the address specified, from the same socket as the specificied server.
int	lo_send_timestamped (lo_address targ, lo_timetag ts, const char path, const char type,...)
	Send a OSC formatted message to the address specified, scheduled to be dispatch at some time in the future.
int	lo_address_errno (lo_address a)
	Return the error number from the last failed lo_send() or lo_address_new() call.
const char *	lo_address_errstr (lo_address a)
	Return the error string from the last failed lo_send() or lo_address_new() call.
lo_server_thread	lo_server_thread_new (const char *port, lo_err_handler err_h)
	Create a new server thread to handle incoming OSC messages.
lo_server_thread	lo_server_thread_new_multicast (const char group, const char port, lo_err_handler err_h)
	Create a new server thread to handle incoming OSC messages, and join a UDP multicast group.
lo_server_thread	lo_server_thread_new_with_proto (const char *port, int proto, lo_err_handler err_h)
	Create a new server thread to handle incoming OSC messages, specifying protocol.
void	lo_server_thread_free (lo_server_thread st)
	Free memory taken by a server thread.
lo_method	lo_server_thread_add_method (lo_server_thread st, const char path, const char typespec, lo_method_handler h, void *user_data)
	Add an OSC method to the specifed server thread.
void	lo_server_thread_del_method (lo_server_thread st, const char path, const char typespec)
	Delete an OSC method from the specifed server thread.
int	lo_server_thread_start (lo_server_thread st)
	Start the server thread.
int	lo_server_thread_stop (lo_server_thread st)
	Stop the server thread.
int	lo_server_thread_get_port (lo_server_thread st)
	Return the port number that the server thread has bound to.
char *	lo_server_thread_get_url (lo_server_thread st)
	Return a URL describing the address of the server thread.
lo_server	lo_server_thread_get_server (lo_server_thread st)
	Return the lo_server for a lo_server_thread.
int	lo_server_thread_events_pending (lo_server_thread st)
	Return true if there are scheduled events (eg. from bundles) waiting to be dispatched by the thread.
lo_blob	lo_blob_new (int32_t size, const void *data)
	Create a new OSC blob type.
void	lo_blob_free (lo_blob b)
	Free the memory taken by a blob.
uint32_t	lo_blob_datasize (lo_blob b)
	Return the amount of valid data in a lo_blob object.
void *	lo_blob_dataptr (lo_blob b)
	Return a pointer to the start of the blob data to allow contents to be changed.

Detailed Description

Defines the high-level API functions necessary to implement OSC support. Should be adequate for most applications, but if you require lower level control you can use the functions defined in lo_lowlevel.h

Macro Definition Documentation

#define LO_TT_IMMEDIATE ((lo_timetag){0U,1U})

A timetag constant representing "now".

Definition at line 136 of file lo_osc_types.h.

Referenced by lo_message_deserialise(), lo_message_new(), lo_send_from(), lo_server_dispatch_data(), test_multicast(), and timestamp_handler().

Enumeration Type Documentation

enum lo_type

An enumeration of the OSC types liblo can send and receive.

The value of the enumeration is the typechar used to tag messages and to specify arguments with lo_send().

Enumerator:

LO_INT32	32 bit signed integer.
LO_FLOAT	32 bit IEEE-754 float.
LO_STRING	Standard C, NULL terminated string.
LO_BLOB	OSC binary blob type. Accessed using the lo_blob_*() functions.
LO_INT64	64 bit signed integer.
LO_TIMETAG	OSC TimeTag type, represented by the lo_timetag structure.
LO_DOUBLE	64 bit IEEE-754 double.
LO_SYMBOL	Standard C, NULL terminated, string. Used in systems which distinguish strings and symbols.
LO_CHAR	Standard C, 8 bit, char variable.
LO_MIDI	A 4 byte MIDI packet.
LO_TRUE	Sybol representing the value True.
LO_FALSE	Sybol representing the value False.
LO_NIL	Sybol representing the value Nil.
LO_INFINITUM	Sybol representing the value Infinitum.

Definition at line 57 of file lo_osc_types.h.

Function Documentation

lo_address lo_address_new	(	const char *	host,
		const char *	port
	)

Declare an OSC destination, given IP address and port number. Same as lo_address_new_with_proto(), but using UDP.

Parameters:

host	An IP address or number, or NULL for the local machine.
port	a decimal port number or service name.

The lo_address object may be used as the target of OSC messages.

Note: if you wish to receive replies from the target of this address, you must first create a lo_server_thread or lo_server object which will receive the replies. The last lo_server(_thread) object creted will be the receiver.

Definition at line 78 of file address.c.

References lo_address_new_with_proto(), and LO_UDP.

Referenced by dispatch_method(), main(), and test_multicast().

lo_address lo_address_new_with_proto	(	int	proto,
		const char *	host,
		const char *	port
	)

Declare an OSC destination, given IP address and port number, specifying protocol.

Parameters:

proto	The protocol to use, must be one of LO_UDP, LO_TCP or LO_UNIX.
host	An IP address or number, or NULL for the local machine.
port	a decimal port number or service name.

The lo_address object may be used as the target of OSC messages.

Note: if you wish to receive replies from the target of this address, you must first create a lo_server_thread or lo_server object which will receive the replies. The last lo_server(_thread) object creted will be the receiver.

Definition at line 41 of file address.c.

References LO_TCP, LO_UDP, and LO_UNIX.

Referenced by lo_address_new(), lo_address_new_from_url(), and main().

lo_address lo_address_new_from_url ( const char * url )

Create a lo_address object from an OSC URL.

example: "osc.udp://localhost:4444/my/path/"

Definition at line 83 of file address.c.

References lo_address_new_with_proto(), LO_TCP, LO_UDP, LO_UNIX, lo_url_get_hostname(), lo_url_get_path(), lo_url_get_port(), lo_url_get_protocol(), lo_url_get_protocol_id(), and PACKAGE_NAME.

Referenced by main().

void lo_address_free ( lo_address t )

Free the memory used by the lo_address object.

Definition at line 188 of file address.c.

Referenced by dispatch_method(), main(), and test_multicast().

void lo_address_set_ttl	(	lo_address	t,
		int	ttl
	)

Set the Time-to-Live value for a given target address.

This is required for sending multicast UDP messages. A value of 1 (the usual case) keeps the message within the subnet, while 255 means a global, unrestricted scope.

Parameters:

t	An OSC address.
ttl	An integer specifying the scope of a multicast UDP message.

Definition at line 335 of file address.c.

Referenced by test_multicast().

int lo_address_get_ttl ( lo_address t )

Get the Time-to-Live value for a given target address.

Parameters:

t	An OSC address.

Returns:: An integer specifying the scope of a multicast UDP message.

Definition at line 341 of file address.c.

int lo_send	(	lo_address	targ,
		const char *	path,
		const char *	type,
			...
	)

Send a OSC formatted message to the address specified.

Parameters:

targ	The target OSC address
path	The OSC path the message will be delivered to
type	The types of the data items in the message, types are defined in lo_osc_types.h
...	The data values to be transmitted. The types of the arguments passed here must agree with the types specified in the type parameter.

example:

lo_send(t, "/foo/bar", "ff", 0.1f, 23.0f);

Returns:: -1 on failure.

Definition at line 77 of file send.c.

Referenced by main(), noteLoop(), and subtest_handler().

int lo_send_from	(	lo_address	targ,
		lo_server	from,
		lo_timetag	ts,
		const char *	path,
		const char *	type,
			...
	)

Send a OSC formatted message to the address specified, from the same socket as the specificied server.

Parameters:

targ	The target OSC address
from	The server to send message from (can be NULL to use new socket)
ts	The OSC timetag timestamp at which the message will be processed (can be LO_TT_IMMEDIATE if you don't want to attach a timetag)
path	The OSC path the message will be delivered to
type	The types of the data items in the message, types are defined in lo_osc_types.h
...	The data values to be transmitted. The types of the arguments passed here must agree with the types specified in the type parameter.

example:

   serv = lo_server_new(NULL, err);
   lo_server_add_method(serv, "/reply", "ss", reply_handler, NULL);
   lo_send_from(t, serv, LO_TT_IMMEDIATE, "/foo/bar", "ff", 0.1f, 23.0f);

Returns:: on success, the number of bytes sent, or -1 on failure.

Definition at line 160 of file send.c.

Referenced by test_multicast().

int lo_send_timestamped	(	lo_address	targ,
		lo_timetag	ts,
		const char *	path,
		const char *	type,
			...
	)

Send a OSC formatted message to the address specified, scheduled to be dispatch at some time in the future.

Parameters:

targ	The target OSC address
ts	The OSC timetag timestamp at which the message will be processed
path	The OSC path the message will be delivered to
type	The types of the data items in the message, types are defined in lo_osc_types.h
...	The data values to be transmitted. The types of the arguments passed here must agree with the types specified in the type parameter.

example:

   lo_timetag now;<br>
   lo_timetag_now(&now);<br>
   lo_send_timestamped(t, now, "/foo/bar", "ff", 0.1f, 23.0f);

Returns:: on success, the number of bytes sent, or -1 on failure.

Definition at line 118 of file send.c.

Referenced by main().

int lo_address_errno ( lo_address a )

Return the error number from the last failed lo_send() or lo_address_new() call.

Definition at line 201 of file address.c.

Referenced by main(), noteLoop(), subtest_handler(), and test_multicast().

const char* lo_address_errstr ( lo_address a )

Return the error string from the last failed lo_send() or lo_address_new() call.

Definition at line 206 of file address.c.

Referenced by main(), noteLoop(), subtest_handler(), and test_multicast().

lo_server_thread lo_server_thread_new	(	const char *	port,
		lo_err_handler	err_h
	)

Create a new server thread to handle incoming OSC messages.

Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. Use this if you do not want to handle the threading yourself.

Parameters:

port	If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. Otherwise a decimal port number, service name or UNIX domain socket path may be passed.
err_h	A function that will be called in the event of an error being raised. The function prototype is defined in lo_types.h

Definition at line 38 of file server_thread.c.

References LO_DEFAULT, and lo_server_thread_new_with_proto().

Referenced by initOSCReceive(), and main().

lo_server_thread lo_server_thread_new_multicast	(	const char *	group,
		const char *	port,
		lo_err_handler	err_h
	)

Create a new server thread to handle incoming OSC messages, and join a UDP multicast group.

Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. Use this if you do not want to handle the threading yourself.

Parameters:

group	The multicast group to join. See documentation on IP multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html
port	If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. Otherwise a decimal port number, service name or UNIX domain socket path may be passed.
err_h	A function that will be called in the event of an error being raised. The function prototype is defined in lo_types.h

Definition at line 43 of file server_thread.c.

References lo_server_new_multicast().

lo_server_thread lo_server_thread_new_with_proto	(	const char *	port,
		int	proto,
		lo_err_handler	err_h
	)

Create a new server thread to handle incoming OSC messages, specifying protocol.

Server threads take care of the message reception and dispatch by transparently creating a system thread to handle incoming messages. Use this if you do not want to handle the threading yourself.

Parameters:

port	If NULL is passed then an unused port will be chosen by the system, its number may be retrieved with lo_server_thread_get_port() so it can be passed to clients. Otherwise a decimal port number, service name or UNIX domain socket path may be passed.
proto	The protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX.
err_h	A function that will be called in the event of an error being raised. The function prototype is defined in lo_types.h

Definition at line 60 of file server_thread.c.

References lo_server_new_with_proto().

Referenced by lo_server_thread_new().

void lo_server_thread_free ( lo_server_thread st )

Free memory taken by a server thread.

Frees the memory, and, if currently running will stop the associated thread.

Definition at line 78 of file server_thread.c.

References lo_server_free(), and lo_server_thread_stop().

Referenced by main().

lo_method lo_server_thread_add_method	(	lo_server_thread	st,
		const char *	path,
		const char *	typespec,
		lo_method_handler	h,
		void *	user_data
	)

Add an OSC method to the specifed server thread.

Parameters:

st	The server thread the method is to be added to.
path	The OSC path to register the method to. If NULL is passed the method will match all paths.
typespec	The typespec the method accepts. Incoming messages with similar typespecs (e.g. ones with numerical types in the same position) will be coerced to the typespec given here.
h	The method handler callback function that will be called it a matching message is received
user_data	A value that will be passed to the callback function, h, when its invoked matching from this method.

Definition at line 89 of file server_thread.c.

References lo_server_add_method().

Referenced by main(), and mainOSCLoop().

void lo_server_thread_del_method	(	lo_server_thread	st,
		const char *	path,
		const char *	typespec
	)

Delete an OSC method from the specifed server thread.

Parameters:

st	The server thread the method is to be removed from.
path	The OSC path of the method to delete. If NULL is passed the method will match the generic handler.
typespec	The typespec the method accepts.

Definition at line 96 of file server_thread.c.

References lo_server_del_method().

Referenced by main().

int lo_server_thread_start ( lo_server_thread st )

Start the server thread.

Parameters: