High-level OSC API

Data Structures
struct	lo_timetag
	A structure to store OSC TimeTag values. More...
union	lo_arg
	Union used to read values from incoming messages. More...
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.
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.
int	lo_send (lo_address targ, const char *path, const char *type,...)
	Send a OSC formatted message to the address specified.
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.
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_start (lo_server_thread st)
	Start the server thread.
void	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_blob	lo_blob_new (int32_t size, 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 ammount 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 neccesary to implement OSC support. Should be adequate for most applications, but ig you require lower level control you can use the functions defined in lo_lowlevel.h.

---

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 arguemnts with lo_send(). Enumeration values: 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.

---

Function Documentation

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.

void lo_address_free (  lo_address  t  )

Free the memory used by the lo_address object.

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

Declare an OSC destination, given IP address and port number. 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.

lo_address lo_address_new_from_url (  const char *  url  )

Create a lo_address object from an OSC URL. example: osc://localhost:4444/my/path/

void* lo_blob_dataptr (  lo_blob  b  )

Return a pointer to the start of the blob data to allow contents to be changed.

uint32_t lo_blob_datasize (  lo_blob  b  )

Return the ammount of valid data in a lo blob object. If you want to know the storage size, use lo_arg_size().

void lo_blob_free (  lo_blob  b  )

Free the memory taken by a blob.

lo_blob lo_blob_new (  int32_t  size, void *  data )

Create a new OSC blob type. Parameters: size  The ammount of space to allocate in the blob structure. data  The data that will be used to initialise the blob, should be size bytes long.

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_types_common.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.

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.

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.

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. Return value must be free()'d to reclaim memory.

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 systme 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 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  A function that will be called in the event of an error being raised. The function prototype is defined in lo_types.h

void lo_server_thread_start (  lo_server_thread  st  )

Start the server thread. Parameters: st  the server thread to start.

void lo_server_thread_stop (  lo_server_thread  st  )

Stop the server thread. Parameters: st  the server thread to start.

---