Low-level OSC API


Typedefs
typedef long double	lo_hires
	Type used to represent numerical values in conversions between OSC types.
Functions
int	lo_send_message (lo_address targ, const char *path, lo_message msg)
	send a lo_message object to target targ
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_send_bundle (lo_address targ, lo_bundle b)
	send a lo_bundle object to address targ
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_message	lo_message_new ()
	Create a new lo_message object.
void	lo_message_free (lo_message m)
	Free memory allocated by lo_message_new and any subsequent lo_message_add*() calls.
void	lo_message_add_int32 (lo_message m, int32_t a)
	Append a data item and typechar of the specified type to a message.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
void	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 details.
lo_address	lo_message_get_source (lo_message m)
	Returns the source (lo_address) of an incoming message.
size_t	lo_message_length (lo_message m, const char *path)
	Return the length of a message in bytes.
void *	lo_message_serialise (lo_message m, const char path, void to, size_t *size)
	Serialise the message object to an area of memory and return a pointer to the serialised form.
const char *	lo_address_get_hostname (lo_address a)
	Return the hostname of a lo_address object.
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.
char *	lo_address_get_url (lo_address a)
	Return a URL representing an OSC address.
lo_bundle	lo_bundle_new (lo_timetag tt)
	Create a new bundle object.
void	lo_bundle_add_message (lo_bundle b, const char *path, lo_message m)
	Adds an OSC message to an existing bundle.
size_t	lo_bundle_length (lo_bundle b)
	Return the length of a bundle in bytes.
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_bundle_free (lo_bundle b)
	Frees the memory taken by a bundle 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_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_coerce (lo_type type_to, lo_arg to, lo_type type_from, lo_arg from)
	attempt to convert one OSC type to another.
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.
size_t	lo_arg_size (lo_type type, void *data)
	Return the storage size, in bytes, of the given argument.
void	lo_arg_host_endian (lo_type type, void *data)
	Convert the speficed argument to host endianness where neccesary.
lo_server	lo_server_new (const char *port, lo_err_handler err_h)
	Create a new server instance.
lo_server	lo_server_new_with_proto (const char *port, int proto, lo_err_handler err_h)
	Create a new server instance, specifying protocol.
void	lo_server_free (lo_server s)
	Free up memory used by the lo_server object.
int	lo_server_recv_noblock (lo_server s, int timeout)
	Look for an OSC message waiting to be received.
int	lo_server_recv (lo_server s)
	Block, waiting for an OSC message to be received.
lo_method	lo_server_add_method (lo_server s, const char path, const char typespec, lo_method_handler h, void *user_data)
	Add an OSC method to the specifed server.
void	lo_server_del_method (lo_server s, const char path, const char typespec)
	Delete an OSC method from the specifed server.
int	lo_server_get_socket_fd (lo_server s)
	Return the file descriptor of the server socket.
int	lo_server_get_port (lo_server s)
	Return the port number that the server has bound to.
int	lo_server_get_protocol (lo_server s)
	Return the protocol that the server is using.
char *	lo_server_get_url (lo_server s)
	Return an OSC URL that can be used to contact the 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.
double	lo_server_next_event_delay (lo_server s)
	Return the time in seconds until the next scheduled event.
char *	lo_url_get_protocol (const char *url)
	Return the protocol portion of an OSC URL, eg. udp, tcp.
char *	lo_url_get_hostname (const char *url)
	Return the hostname portion of an OSC URL.
char *	lo_url_get_port (const char *url)
	Return the port portion of an OSC URL.
char *	lo_url_get_path (const char *url)
	Return the path portion of an OSC URL.
int	lo_strsize (const char *s)
	A function to calculate the amount of OSC message space required by a C char *.
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_pattern_match (const char str, const char p)
	Test a string against an OSC pattern glob.
int	lo_send_internal (lo_address t, const char file, const int line, const char path, const char *types,...)
	the real send function (don't call directly)
int	lo_send_timestamped_internal (lo_address t, const char file, const int line, lo_timetag ts, const char path, const char *types,...)
	the real send_timestamped function (don't call directly)
int	lo_send_from_internal (lo_address targ, lo_server from, const char file, const int line, const lo_timetag ts, const char path, const char *types,...)
	the real lo_send_from function (don't call directly)
double	lo_timetag_diff (lo_timetag a, lo_timetag b)
	Find the time difference between two timetags.
void	lo_timetag_now (lo_timetag *t)
	Return a timetag for the current time.

Detailed Description

Use these functions if you require more precices control over OSC message contruction or handling that what is provided in the high-level functions described in liblo.

Typedef Documentation

typedef long double lo_hires

Type used to represent numerical values in conversions between OSC types.

Function Documentation

const char* lo_address_get_hostname ( lo_address a )

Return the hostname of a lo_address object.

Returned value most not be modified or free'd. Value will be a dotted quad, colon'd IPV6 address, or resolvable name.

const char* lo_address_get_port ( lo_address a )

Return the port/service name of a lo_address object.

Returned value most not be modified or free'd. Value will be a service name or ASCII representation of the port number.

int lo_address_get_protocol ( lo_address a )

Return the protocol of a lo_address object.

Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.

char* lo_address_get_url ( lo_address a )

Return a URL representing an OSC address.

Returned value must be free'd.

void lo_arg_host_endian	(	lo_type	type,
		void *	data
	)

Convert the speficed argument to host endianness where neccesary.

Parameters:

	type	The OSC type of the data item (eg. LO_FLOAT).
	data	A pointer to the data item to be converted. It is change in-place.

size_t lo_arg_size	(	lo_type	type,
		void *	data
	)

Return the storage size, in bytes, of the given argument.

uint32_t lo_blobsize ( lo_blob b )

A function to calculate the amount of OSC message space required by a lo_blob object.

Returns the storage size in bytes, will always be a multiple of four.

void lo_bundle_add_message	(	lo_bundle	b,
		const char *	path,
		lo_message	m
	)

Adds an OSC message to an existing bundle.

The message passsed is appended to the list of messages in the bundle to be dispatched to 'path'.

void lo_bundle_free ( lo_bundle b )

Frees the memory taken by a bundle object.

size_t lo_bundle_length ( lo_bundle b )

Return the length of a bundle in bytes.

Includes the marker and typetage length.

Parameters:

The bundle to be sized

lo_bundle lo_bundle_new ( lo_timetag tt )

Create a new bundle object.

OSC Bundles ecapsulate one or more OSC messages and may include a timestamp indicating when the bundle should be dispatched.

Parameters:

The timestamp when the bundle should be handled by the receiver. Pass LO_TT_IMMEDIATE if you want the receiving server to dispatch the bundle as soon as it receives it.

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.

Parameters:

	b	The bundle to be serialised
	to	The address to serialise to, memory will be allocated if to is NULL.
	size	If this pointer is non-NULL the size of the memory area will be written here

The returned form is suitable to be sent over a low level OSC transport, having the correct endianess and bit-packed structure.

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.

Numerical types (eg LO_INT32, LO_FLOAT etc.) may be converted to other numerical types and string types (LO_STRING and LO_SYMBOL) may be converted to the other type. This is done automatically if a received message matches the path, but not the exact types, and is coercible (ie. all numerical types in numerical positions).

On failure no translation occurs and false is returned.

Parameters:

	type_to	The type of the destination variable.
	to	A pointer to the destination variable.
	type_from	The type of the source variable.
	from	A pointer to the source variable.

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_is_numerical_type ( lo_type a )

return true if the type specified has a numerical value, such as LO_INT32, LO_FLOAT etc.

Parameters:

The type to be tested.

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.

Parameters:

The type to be tested.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void lo_message_add_int32	(	lo_message	m,
		int32_t	a
	)

Append a data item and typechar of the specified type to a message.

The data will be added in OSC byteorder (bigendian).

Parameters:

	m	The message to be extended.
	a	The data item.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void 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 details.

void lo_message_free ( lo_message m )

Free memory allocated by lo_message_new and any subsequent lo_message_add*() calls.

lo_address lo_message_get_source ( lo_message m )

Returns the source (lo_address) of an incoming message.

Returns NULL if the message is outgoing. Do not free the returned address.

size_t lo_message_length	(	lo_message	m,
		const char *	path
	)

Return the length of a message in bytes.

Parameters:

	m	The message to be sized
	path	The path the message will be sent to

lo_message lo_message_new ( )

Create a new lo_message object.

void* lo_message_serialise	(	lo_message	m,
		const char *	path,
		void *	to,
		size_t *	size
	)

Serialise the message object to an area of memory and return a pointer to the serialised form.

Parameters:

	m	The mesaage to be serialised
	path	The path the message will be sent to
	to	The address to serialise to, memory will be allocated if to is NULL.
	size	If this pointer is non-NULL the size of the memory area will be written here

The returned form is suitable to be sent over a low level OSC transport, having the correct endianess and bit-packed structure.

int lo_pattern_match	(	const char *	str,
		const char *	p
	)

Test a string against an OSC pattern glob.

Parameters:

	str	The tring to test
	p	The pattern to test against

int lo_send_bundle	(	lo_address	targ,
		lo_bundle	b
	)

send a lo_bundle object to address targ

Bundles are constructed with the lo_bundle_new() and lo_bundle_add_message() functions.

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

Bundles are constructed with the lo_bundle_new() and lo_bundle_add_message() functions.

Parameters:

	targ	The address to send the bundle to
	serv	The server socket to send the bundle from (can be NULL to use new socket)
	b	The bundle itself

int lo_send_from_internal	(	lo_address	targ,
		lo_server	from,
		const char *	file,
		const int	line,
		const lo_timetag	ts,
		const char *	path,
		const char *	types,
			...
	)

the real lo_send_from function (don't call directly)

int lo_send_internal	(	lo_address	t,
		const char *	file,
		const int	line,
		const char *	path,
		const char *	types,
			...
	)

the real send function (don't call directly)

int lo_send_message	(	lo_address	targ,
		const char *	path,
		lo_message	msg
	)

send a lo_message object to target targ

This is slightly more efficient than lo_send if you want to send a lot of similar messages. The messages are constructed with the lo_message_new() and lo_message_add*() functions.

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

This is slightly more efficient than lo_send if you want to send a lot of similar messages. The messages are constructed with the lo_message_new() and lo_message_add*() functions.

Parameters:

	targ	The address to send the message to
	serv	The server socket to send the message from (can be NULL to use new socket)
	path	The path to send the message to
	msg	The bundle itself

int lo_send_timestamped_internal	(	lo_address	t,
		const char *	file,
		const int	line,
		lo_timetag	ts,
		const char *	path,
		const char *	types,
			...
	)

the real send_timestamped function (don't call directly)

lo_method lo_server_add_method	(	lo_server	s,
		const char *	path,
		const char *	typespec,
		lo_method_handler	h,
		void *	user_data
	)

Add an OSC method to the specifed server.

Parameters:

	s	The server 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 if 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.

void lo_server_del_method	(	lo_server	s,
		const char *	path,
		const char *	typespec
	)

Delete an OSC method from the specifed server.

Parameters:

	s	The server 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.

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_server_free ( lo_server s )

Free up memory used by the lo_server object.

int lo_server_get_port ( lo_server s )

Return the port number that the server has bound to.

Useful when NULL is passed for the port number and you wish to know how to address the server.

int lo_server_get_protocol ( lo_server s )

Return the protocol that the server is using.

Returned value will be one of LO_UDP, LO_TCP or LO_UNIX.

int lo_server_get_socket_fd ( lo_server s )

Return the file descriptor of the server socket.

If the server protocol supports exposing the server's underlying receive mechanism for monitoring with select() or poll(), this function returns the file descriptor needed, otherwise, it returns -1.

WARNING: when using this function beware that not all OSC packets that are received are dispatched immediatly. lo_server_events_pending() and lo_server_next_event_delay() can be used to tell if there are pending events and how long before you should attempt to receive them.

char* lo_server_get_url ( lo_server s )

Return an OSC URL that can be used to contact the server.

The return value should bee free()'d when it is no longer needed.

lo_server lo_server_new	(	const char *	port,
		lo_err_handler	err_h
	)

Create a new server instance.

lo_servers block until they receive OSC messages. if you want non-blocking behaviour see the lo_server_thread_* functions.

Parameters:

	port	If NULL is passed then an unused UDP port will be chosen by the system, its number may be retreived 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	An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.

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_servers block until they receive OSC messages. if you want non-blocking behaviour see the lo_server_thread_* functions.

Parameters:

	port	If using UDP then NULL may be passed to find an unused port. Otherwise a decimal port number orservice name or may be passed. If using UNIX domain sockets then a socket path should be passed here.
	proto	The protocol to use, should be one of LO_UDP, LO_TCP or LO_UNIX.
	err_h	An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.

double lo_server_next_event_delay ( lo_server s )

Return the time in seconds until the next scheduled event.

If the delay is greater than 100 seconds then it will return 100.0.

int lo_server_recv ( lo_server s )

Block, waiting for an OSC message to be received.

The return value is the number of bytes in the received message. The message will be dispatched to a matching method if one is found.

int lo_server_recv_noblock	(	lo_server	s,
		int	timeout
	)

Look for an OSC message waiting to be received.

Parameters:

	s	The server to wait for connections on.
	timeout	A timeout in milliseconds to wait for the incoming packet. a value of 0 will return immediatly.

The return value is the number of bytes in the received message or 0 is there is no message. The message will be dispatched to a matching method if one is found.

int lo_strsize ( const char * s )

A function to calculate the amount of OSC message space required by a C char *.

Returns the storage size in bytes, will always be a multiple of four.

double lo_timetag_diff	(	lo_timetag	a,
		lo_timetag	b
	)

Find the time difference between two timetags.

Returns a - b in seconds.

void lo_timetag_now ( lo_timetag * t )

Return a timetag for the current time.

On exit the timetag pointed to by t is filled with the OSC represenation of this instant in time.

char* lo_url_get_hostname ( const char * url )

Return the hostname portion of an OSC URL.

The return value should bee free()'d when it is no longer needed.

char* lo_url_get_path ( const char * url )

Return the path portion of an OSC URL.

The return value should bee free()'d when it is no longer needed.

char* lo_url_get_port ( const char * url )

Return the port portion of an OSC URL.

The return value should bee free()'d when it is no longer needed.

char* lo_url_get_protocol ( const char * url )

Return the protocol portion of an OSC URL, eg. udp, tcp.

This library uses OSC URLs of the form: osc.prot://hostname:port/path if the prot part is missing, UDP is assumed.

The return value should bee free()'d when it is no longer needed.

Generated on Tue Jul 10 15:56:30 2007 for liblo by

1.5.2

Low-level OSC API

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation