CSL 5.2

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

Typedefs | Functions
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_int32 lo_message_add*() calls.
int | lo_message_add (lo_message m, const char *types,...)
| Append a number of arguments to a message.
int | lo_message_add_internal (lo_message m, const char *file, const int line, const char *types,...)
int | lo_message_add_varargs (lo_message m, const char *types, va_list ap)
| Append a varargs list to a message.
int | lo_message_add_varargs_internal (lo_message m, const char *types, va_list ap, const char *file, const int line)
int | lo_message_add_int32 (lo_message m, int32_t a)
| Append a data item and typechar of the specified type to a message.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
int | 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.
lo_timetag | lo_message_get_timestamp (lo_message m)
| Returns the timestamp (lo_timetag *) of a bundled incoming message.
char * | lo_message_get_types (lo_message m)
| Return the message type tag string.
int | lo_message_get_argc (lo_message m)
| Return the message argument count.
lo_arg ** | lo_message_get_argv (lo_message m)
| Return the message arguments. Do not free the returned data.
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 lo_message object to an area of memory and return a pointer to the serialised form. Opposite of lo_message_deserialise().
lo_message | lo_message_deserialise (void *data, size_t size, int *result)
| Deserialise a raw OSC message and return a new lo_message object. Opposite of lo_message_serialise().
int | lo_server_dispatch_data (lo_server s, void *data, size_t size)
| Dispatch a raw block of memory containing an OSC message.
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.
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.
lo_bundle | lo_bundle_new (lo_timetag tt)
| Create a new bundle object.
int | 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.
void | lo_bundle_free_messages (lo_bundle b)
| Frees the memory taken by a bundle object and messages in the bundle.
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.
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.
lo_server | lo_server_new_multicast (const char *group, const char *port, lo_err_handler err_h)
| Create a new server instance, and join a UDP multicast group.
void | lo_server_free (lo_server s)
| Free up memory used by the lo_server object.
int | lo_server_wait (lo_server s, int timeout)
| Wait for an OSC message to be received.
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.
int | lo_url_get_protocol_id (const char *url)
| Return the protocol ID of an OSC URL.
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,...)
int | lo_send_timestamped_internal (lo_address t, const char *file, const int line, lo_timetag ts, const char *path, const char *types,...)
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,...)
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.
size_t | lo_arg_size (lo_type type, void *data)
| Return the storage size, in bytes, of the given argument.
char * | lo_get_path (void *data, ssize_t size)
| Given a raw OSC message, return the message path.
void | lo_arg_host_endian (lo_type type, void *data)
| Convert the specified argument to host byte order where necessary.
void | lo_arg_network_endian (lo_type type, void *data)
| Convert the specified argument to network byte order where necessary.

## Detailed Description

Use these functions if you require more precise 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.

Definition at line 55 of file lo_lowlevel.h.

## Function Documentation

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.

Definition at line 445 of file send.c.

References lo_send_message_from().

Referenced by dispatch_method(), lo_send(), main(), and test_varargs().

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

Definition at line 450 of file send.c.

References data, lo_message_length(), lo_message_serialise(), LO_TCP, and send_data().

Referenced by lo_send_from(), and lo_send_message().

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.

Definition at line 471 of file send.c.

References lo_send_bundle_from().

Referenced by lo_send_timestamped(), and main().

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

Definition at line 477 of file send.c.

References data, lo_bundle_length(), lo_bundle_serialise(), and send_data().

Referenced by lo_send_bundle(), and lo_send_from().

lo_message lo_message_new | ( |  | ) |

Create a new lo_message object.

Definition at line 66 of file message.c.

References LO_DEF_TYPE_SIZE, and LO_TT_IMMEDIATE.

Referenced by create_message(), dispatch_method(), lo_send(), lo_send_from(), lo_send_timestamped(), main(), test_deserialise(), and test_varargs().

void lo_message_free | ( | lo_message | m | ) |

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

Definition at line 88 of file message.c.

Referenced by create_message(), dispatch_method(), dispatch_queued(), lo_bundle_free_messages(), lo_message_deserialise(), lo_send(), lo_send_from(), lo_send_timestamped(), lo_server_dispatch_data(), main(), test_deserialise(), and test_varargs().

int lo_message_add | ( | lo_message | m,
|  | const char * | types,
|  |  | ...
| ) |  |

Append a number of arguments to a message.

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

Parameters:

  m | The message to be extended.
  types | 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.

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

Definition at line 244 of file message.c.

Referenced by main().

int lo_message_add_internal | ( | lo_message | m,
|  | const char * | file,
|  | const int | line,
|  | const char * | types,
|  |  | ...
| ) |  |

int lo_message_add_varargs | ( | lo_message | m,
|  | const char * | types,
|  | va_list | ap
| ) |  |

Append a varargs list to a message.

The data will be added in OSC byteorder (bigendian). IMPORTANT: args list must be terminated with LO_ARGS_END, or this call will fail. This is used to do simple error checking on the sizes of parameters passed.

Parameters:

  m | The message to be extended.
  types | The types of the data items in the message, types are defined in lo_types_common.h
  ap | The va_list created by a C function declared with an ellipsis (...) argument, and pre-initialised with "va_start(ap)". The types of the arguments passed here must agree with the types specified in the type parameter.

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

Referenced by test_varargs().

int lo_message_add_varargs_internal | ( | lo_message | m,
|  | const char * | types,
|  | va_list | ap,
|  | const char * | file,
|  | const int | line
| ) |  |

Definition at line 102 of file message.c.

Referenced by lo_message_add(), lo_send(), lo_send_from(), and lo_send_timestamped().

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

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

Definition at line 261 of file message.c.

References lo_pcast32::i, LO_INT32, lo_message_add_data(), lo_message_add_typechar(), and lo_pcast32::nl.

Referenced by create_message(), dispatch_method(), lo_message_add_varargs_internal(), main(), and test_deserialise().

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

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

Definition at line 274 of file message.c.

References lo_pcast32::f, LO_FLOAT, lo_message_add_data(), lo_message_add_typechar(), and lo_pcast32::nl.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 287 of file message.c.

References lo_message_add_data(), lo_message_add_typechar(), LO_STRING, and lo_strsize().

Referenced by create_message(), dispatch_method(), lo_message_add_varargs_internal(), main(), and test_deserialise().

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

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

Definition at line 299 of file message.c.

References LO_BLOB, lo_blob_dataptr(), lo_blob_datasize(), lo_blobsize(), lo_message_add_data(), lo_message_add_typechar(), and memcpy().

Referenced by lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 315 of file message.c.

References lo_pcast64::i, LO_INT64, lo_message_add_data(), lo_message_add_typechar(), and lo_pcast64::nl.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 328 of file message.c.

References lo_message_add_data(), lo_message_add_typechar(), LO_TIMETAG, lo_pcast64::nl, and lo_pcast64::tt.

Referenced by lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 341 of file message.c.

References lo_pcast64::f, LO_DOUBLE, lo_message_add_data(), lo_message_add_typechar(), and lo_pcast64::nl.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 354 of file message.c.

References lo_message_add_data(), lo_message_add_typechar(), lo_strsize(), and LO_SYMBOL.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 366 of file message.c.

References lo_pcast32::c, LO_CHAR, lo_message_add_data(), lo_message_add_typechar(), and lo_pcast32::nl.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 380 of file message.c.

References lo_message_add_data(), lo_message_add_typechar(), LO_MIDI, and memcpy().

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 392 of file message.c.

References lo_message_add_typechar(), and LO_TRUE.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 397 of file message.c.

References LO_FALSE, and lo_message_add_typechar().

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 402 of file message.c.

References lo_message_add_typechar(), and LO_NIL.

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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

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

Definition at line 407 of file message.c.

References LO_INFINITUM, and lo_message_add_typechar().

Referenced by create_message(), lo_message_add_varargs_internal(), and test_deserialise().

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.

Definition at line 707 of file message.c.

Referenced by reply_handler(), and subtest_handler().

lo_timetag lo_message_get_timestamp | ( | lo_message | m | ) |

Returns the timestamp (lo_timetag *) of a bundled incoming message.

Returns LO_TT_IMMEDIATE if the message is outgoing, or did not arrive contained in a bundle. Do not free the returned timetag.

Definition at line 712 of file message.c.

Referenced by timestamp_handler().

char* lo_message_get_types | ( | lo_message | m | ) |

Return the message type tag string.

The result is valid until further data is added with lo_message_add*().

Definition at line 750 of file message.c.

Referenced by test_deserialise().

int lo_message_get_argc | ( | lo_message | m | ) |

Return the message argument count.

The result is valid until further data is added with lo_message_add*().

Definition at line 722 of file message.c.

Referenced by test_deserialise().

lo_arg** lo_message_get_argv | ( | lo_message | m | ) |

Return the message arguments. Do not free the returned data.

The result is valid until further data is added with lo_message_add*().

Definition at line 727 of file message.c.

References lo_arg_size().

Referenced by test_deserialise().

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

Definition at line 717 of file message.c.

References lo_strsize().

Referenced by lo_bundle_length(), lo_message_serialise(), lo_send_message_from(), and test_deserialise().

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

Serialise the lo_message object to an area of memory and return a pointer to the serialised form. Opposite of lo_message_deserialise().

Parameters:

  m | The message 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.

Definition at line 755 of file message.c.

References lo_arg_network_endian(), lo_arg_size(), lo_message_length(), lo_strsize(), and memcpy().

Referenced by lo_bundle_serialise(), lo_send_message_from(), and test_deserialise().

lo_message lo_message_deserialise | ( | void * | data,
|  | size_t | size,
|  | int * | result
| ) |  |

Deserialise a raw OSC message and return a new lo_message object. Opposite of lo_message_serialise().

Parameters:

  data | Pointer to the raw OSC message data in network transmission form (network byte order where appropriate).
  size | The size of data in bytes
  result | If this pointer is non-NULL, the result or error code will be written here.

Returns a new lo_message, or NULL if deserialisation fails. Use lo_message_free() to free the resulting object.

Definition at line 789 of file message.c.

References lo_arg_host_endian(), LO_EALLOC, LO_EBADTYPE, LO_EINVALIDARG, LO_EINVALIDPATH, LO_EINVALIDTYPE, LO_ENOTYPE, LO_ESIZE, lo_message_free(), LO_TT_IMMEDIATE, lo_validate_arg(), lo_validate_string(), and memcpy().

Referenced by lo_server_dispatch_data(), and test_deserialise().

int lo_server_dispatch_data | ( | lo_server | s,
|  | void * | data,
|  | size_t | size
| ) |  |

Dispatch a raw block of memory containing an OSC message.

This is useful when a raw block of memory is available that is structured as OSC, and you wish to use liblo to dispatch the message to a handler function as if it had been received over the network.

Parameters:

  s | The lo_server to use for dispatching.
  data | Pointer to the raw OSC message data in network transmission form (network byte order where appropriate).
  size | The size of data in bytes

Returns the number of bytes used if successful, or less than 0 otherwise.

Definition at line 854 of file server.c.

References data, dispatch_method(), lo_timetag::frac, lo_message_deserialise(), lo_message_free(), lo_otoh32, lo_throw(), lo_timetag_diff(), lo_timetag_now(), LO_TT_IMMEDIATE, lo_validate_bundle(), lo_validate_string(), queue_data(), and lo_timetag::sec.

Referenced by lo_server_recv().

const char* lo_address_get_hostname | ( | lo_address | a | ) |

Return the hostname of a lo_address object.

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

Definition at line 118 of file address.c.

Referenced by main().

const char* lo_address_get_port | ( | lo_address | a | ) |

Return the port/service name of a lo_address object.

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

Definition at line 136 of file address.c.

Referenced by main().

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.

Definition at line 127 of file address.c.

Referenced by main().

char* lo_address_get_url | ( | lo_address | a | ) |

Return a URL representing an OSC address.

Returned value must be free'd.

Definition at line 161 of file address.c.

References get_protocol_name().

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

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.

References LO_UDP.

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.

lo_bundle lo_bundle_new | ( | lo_timetag | tt | ) |

Create a new bundle object.

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

Parameters:

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

Definition at line 24 of file bundle.c.

Referenced by lo_send_from(), lo_send_timestamped(), and main().

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

Adds an OSC message to an existing bundle.

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

Returns:
  0 if successful, less than 0 otherwise.

Definition at line 37 of file bundle.c.

Referenced by lo_send_from(), lo_send_timestamped(), and main().

size_t lo_bundle_length | ( | lo_bundle | b | ) |

Return the length of a bundle in bytes.

Includes the marker and typetage length.

Parameters:

  b | The bundle to be sized

Definition at line 57 of file bundle.c.

References lo_message_length().

Referenced by lo_bundle_serialise(), and lo_send_bundle_from().

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.

Definition at line 74 of file bundle.c.

References lo_bundle_length(), lo_htoo32, lo_message_serialise(), memcpy(), and lo_pcast32::nl.

Referenced by lo_send_bundle_from().

void lo_bundle_free | ( | lo_bundle | b | ) |

Frees the memory taken by a bundle object.

Parameters:

  b | The bundle to be freed.

Definition at line 127 of file bundle.c.

Referenced by lo_send_from(), lo_send_timestamped(), and main().

void lo_bundle_free_messages | ( | lo_bundle | b | ) |

Frees the memory taken by a bundle object and messages in the bundle.

Parameters:

  b | The bundle, which may contain messages, to be freed.

Definition at line 145 of file bundle.c.

References _lo_internal_compare_ptrs(), and lo_message_free().

Referenced by main().

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.

Definition at line 1007 of file message.c.

References lo_numerical_types.

Referenced by lo_can_coerce(), and lo_coerce().

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.

Definition at line 1012 of file message.c.

References lo_string_types.

Referenced by lo_can_coerce(), and lo_coerce().

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.

Definition at line 1017 of file message.c.

References lo_arg::d, lo_arg::f, lo_arg::i, lo_arg::i64, lo_arg_size(), LO_DOUBLE, LO_FLOAT, lo_hires_val(), LO_INT32, LO_INT64, lo_is_numerical_type(), lo_is_string_type(), and memcpy().

Referenced by dispatch_method().

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.

Definition at line 1060 of file message.c.

References lo_arg::d, lo_arg::f, lo_arg::h, lo_arg::i, LO_DOUBLE, LO_FLOAT, LO_INT32, and LO_INT64.

Referenced by lo_coerce().

lo_server lo_server_new | ( | const char * | port,
|  | lo_err_handler | err_h
| ) |  |

Create a new server instance.

Using lo_server_recv(), lo_servers block until they receive OSC messages. If you want non-blocking behaviour see lo_server_recv_noblock() or 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 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 | 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.

Definition at line 141 of file server.c.

References LO_DEFAULT, and lo_server_new_with_proto().

Referenced by main().

lo_server lo_server_new_with_proto | ( | const char * | port,
|  | int | proto,
|  | lo_err_handler | err_h
| ) |  |

Create a new server instance, specifying protocol.

Using lo_server_recv(), lo_servers block until they receive OSC messages. If you want non-blocking behaviour see lo_server_recv_noblock() or 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.

Definition at line 152 of file server.c.

References lo_server_new_with_proto_internal().

Referenced by lo_server_new(), lo_server_thread_new_with_proto(), and main().

lo_server lo_server_new_multicast | ( | const char * | group,
|  | const char * | port,
|  | lo_err_handler | err_h
| ) |  |

Create a new server instance, and join a UDP multicast group.

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 using UDP then NULL may be passed to find an unused port. Otherwise a decimal port number or service name or may be passed. If using UNIX domain sockets then a socket path should be passed here.
  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.

Definition at line 146 of file server.c.

References lo_server_new_with_proto_internal(), and LO_UDP.

Referenced by lo_server_thread_new_multicast(), and test_multicast().

void lo_server_free | ( | lo_server | s | ) |

Free up memory used by the lo_server object.

Definition at line 454 of file server.c.

References LO_TCP, LO_UDP, LO_UNIX, lo_cs::tcp, and lo_cs::udp.

Referenced by lo_server_join_multicast_group(), lo_server_new_with_proto_internal(), lo_server_thread_free(), main(), and test_multicast().

int lo_server_wait | ( | lo_server | s,
|  | int | timeout
| ) |  |

Wait for an OSC message 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 immediately.

The return value is 1 if there is a message waiting or 0 if there is no message. If there is a message waiting you can now call lo_server_recv() to receive that message.

Referenced by lo_server_recv_noblock().

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

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

Definition at line 703 of file server.c.

References lo_server_recv(), and lo_server_wait().

Referenced by main(), and thread_func().

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.

Definition at line 713 of file server.c.

References data, dispatch_queued(), lo_server_dispatch_data(), lo_server_next_event_delay(), lo_server_recv_raw(), lo_server_recv_raw_stream(), and LO_TCP.

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

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.

Definition at line 1205 of file server.c.

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

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.

Definition at line 1244 of file server.c.

References lo_pattern_match().

Referenced by lo_server_thread_del_method(), and main().

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

Definition at line 1285 of file server.c.

References LO_TCP, LO_UDP, and LO_UNIX.

Referenced by main().

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.

Definition at line 1298 of file server.c.

Referenced by lo_server_thread_get_port().

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.

Definition at line 1307 of file server.c.

Referenced by main().

char* lo_server_get_url | ( | lo_server | s | ) |

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

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

Definition at line 1317 of file server.c.

References LO_TCP, LO_UDP, and LO_UNIX.

Referenced by lo_server_thread_get_url(), and main().

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.

Definition at line 1131 of file server.c.

Referenced by lo_server_thread_events_pending().

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.

Definition at line 924 of file server.c.

References lo_timetag_diff(), and lo_timetag_now().

Referenced by lo_server_recv().

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 be free()'d when it is no longer needed.

Definition at line 224 of file address.c.

References PACKAGE_NAME.

Referenced by lo_address_new_from_url(), and main().

int lo_url_get_protocol_id | ( | const char * | url | ) |

Return the protocol ID of an OSC URL.

This library uses OSC URLs of the form: osc.prot://hostname:port/path if the prot part is missing, UDP is assumed. Returned value will be one of LO_UDP, LO_TCP, LO_UNIX or -1.

Returns:
  An integer specifying the protocol. Return -1 when the protocol is not supported by liblo.

Definition at line 249 of file address.c.

References LO_TCP, LO_UDP, LO_UNIX, and PACKAGE_NAME.

Referenced by lo_address_new_from_url(), and main().

char* lo_url_get_hostname | ( | const char * | url | ) |

Return the hostname portion of an OSC URL.

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

Definition at line 269 of file address.c.

Referenced by lo_address_new_from_url(), and main().

char* lo_url_get_port | ( | const char * | url | ) |

Return the port portion of an OSC URL.

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

Definition at line 289 of file address.c.

Referenced by lo_address_new_from_url(), and main().

char* lo_url_get_path | ( | const char * | url | ) |

Return the path portion of an OSC URL.

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

Definition at line 312 of file address.c.

Referenced by lo_address_new_from_url(), and main().

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, which will always be a multiple of four.

Definition at line 461 of file message.c.

Referenced by lo_arg_size(), lo_message_add_string(), lo_message_add_symbol(), lo_message_length(), and lo_message_serialise().

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, which will always be a multiple of four.

Definition at line 57 of file blob.c.

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

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

Test a string against an OSC pattern glob.

Parameters:

  str | The string to test
  p | The pattern to test against

Definition at line 87 of file pattern_match.c.

References lo_pattern_match(), and NEGATE.

Referenced by dispatch_method(), lo_pattern_match(), and lo_server_del_method().

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

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

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

double lo_timetag_diff | ( | lo_timetag | a,
|  | lo_timetag | b
| ) |  |

Find the time difference between two timetags.

Returns a - b in seconds.

Definition at line 29 of file timetag.c.

References lo_timetag::frac, and lo_timetag::sec.

Referenced by dispatch_queued(), jitter_handler(), lo_server_dispatch_data(), lo_server_next_event_delay(), and queue_data().

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 representation of this instant in time.

Definition at line 35 of file timetag.c.

References lo_timetag::frac, JAN_1970, and lo_timetag::sec.

Referenced by jitter_handler(), lo_server_dispatch_data(), lo_server_next_event_delay(), and main().

size_t lo_arg_size | ( | lo_type | type,
|  | void * | data
| ) |  |

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

Definition at line 466 of file message.c.

References LO_BLOB, lo_blobsize(), LO_CHAR, LO_DOUBLE, LO_FALSE, LO_FLOAT, LO_INFINITUM, LO_INT32, LO_INT64, LO_MIDI, LO_NIL, LO_STRING, lo_strsize(), LO_SYMBOL, LO_TIMETAG, and LO_TRUE.

Referenced by dispatch_method(), lo_arg_pp_internal(), lo_coerce(), lo_message_get_argv(), lo_message_pp(), and lo_message_serialise().

char* lo_get_path | ( | void * | data,
|  | ssize_t | size
| ) |  |

Given a raw OSC message, return the message path.

Parameters:

  data | A pointer to the raw OSC message data.
  size | The size of data in bytes (total buffer bytes).

Returns the message path or NULL if an error occurs. Do not free() the returned pointer.

Definition at line 501 of file message.c.

References lo_validate_string().

Referenced by test_deserialise().

void lo_arg_host_endian | ( | lo_type | type,
|  | void * | data
| ) |  |

Convert the specified argument to host byte order where necessary.

Parameters:

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

Definition at line 640 of file message.c.

References data, LO_BLOB, LO_CHAR, LO_DOUBLE, LO_FALSE, LO_FLOAT, LO_INFINITUM, LO_INT32, LO_INT64, LO_MIDI, LO_NIL, lo_otoh32, lo_otoh64, LO_STRING, LO_SYMBOL, LO_TIMETAG, and LO_TRUE.

Referenced by lo_message_deserialise().

void lo_arg_network_endian | ( | lo_type | type,
|  | void * | data
| ) |  |

Convert the specified argument to network byte order where necessary.

Parameters:

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

Definition at line 674 of file message.c.

References data, LO_BLOB, LO_CHAR, LO_DOUBLE, LO_FALSE, LO_FLOAT, lo_htoo32, lo_htoo64, LO_INFINITUM, LO_INT32, LO_INT64, LO_MIDI, LO_NIL, LO_STRING, LO_SYMBOL, LO_TIMETAG, and LO_TRUE.

Referenced by lo_message_serialise().