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
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, 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, 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.
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.
int lo_server_get_port (lo_server s)
 Return the port number that the server has bound to.
char * lo_server_get_url (lo_server s)
 Return an OSC URL that can be used to contact the server.
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_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)

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

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.

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:
a 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:
a 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,
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,
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_message lo_message_new  ) 
 

Create a new lo_message object.

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.

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

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

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.

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 Thu Sep 2 17:29:13 2004 for Liblo by doxygen 1.3.8