CSL 5.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

Classes | Macros | Enumerations | Functions
High-level OSC API

## 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:

  st | the server thread to start.

Returns:
  Less than 0 on failure, 0 on success.

Definition at line 102 of file server_thread.c.

References thread_func().

Referenced by main(), and mainOSCLoop().

int lo_server_thread_stop | ( | lo_server_thread | st | ) |

Stop the server thread.

Parameters:

  st | the server thread to start.

Returns:
  Less than 0 on failure, 0 on success.

Definition at line 122 of file server_thread.c.

Referenced by lo_server_thread_free(), and main().

int lo_server_thread_get_port | ( | lo_server_thread | st | ) |

Return the port number that the server thread has bound to.

Definition at line 143 of file server_thread.c.

References lo_server_get_port().

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.

Definition at line 148 of file server_thread.c.

References lo_server_get_url().

Referenced by main().

lo_server lo_server_thread_get_server | ( | lo_server_thread | st | ) |

Return the lo_server for a lo_server_thread.

This function is useful for passing a thread's lo_server to lo_send_from().

Definition at line 153 of file server_thread.c.

Referenced by main(), and test_multicast().

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.

Definition at line 158 of file server_thread.c.

References lo_server_events_pending().

Referenced by main().

lo_blob lo_blob_new | ( | int32_t | size,
|  | const void * | data
| ) |  |

Create a new OSC blob type.

Parameters:

  size | The amount of space to allocate in the blob structure.
  data | The data that will be used to initialise the blob, should be size bytes long.

Definition at line 23 of file blob.c.

References memcpy().

Referenced by main(), and test_deserialise().

void lo_blob_free | ( | lo_blob | b | ) |

Free the memory taken by a blob.

Definition at line 42 of file blob.c.

Referenced by main(), and test_deserialise().

uint32_t lo_blob_datasize | ( | lo_blob | b | ) |

Return the amount of valid data in a lo_blob object.

If you want to know the storage size, use lo_arg_size().

Definition at line 47 of file blob.c.

Referenced by lo_message_add_blob(), lots_handler(), main(), and test_deserialise().

void* lo_blob_dataptr | ( | lo_blob | b | ) |

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

Definition at line 52 of file blob.c.

Referenced by lo_message_add_blob(), lots_handler(), and test_deserialise().