Real Time Open Sound Control librtosc: include/rtosc/rtosc.h File Reference

Real Time Open Sound Control librtosc

Classes | Functions
rtosc.h File Reference

Functions handling messages and arguments. More...

`#include <stdarg.h>`
`#include <stdint.h>`
`#include <stddef.h>`
`#include <stdbool.h>`

Go to the source code of this file.

## Classes
struct | rtosc_blob_t
struct | array_start_t
| arg val element indicating an array, or a block of "nothing" blocks of "nothing" are just for internal use and indicate that the following array_start_t::len blocks must be ignored (they can contain rubbish) More...
struct | repeater_t
| a repeater is being followed by a delta argument (unless has_delta is 0) More...
struct | nothing_t
| indicates that the next nothing_t::len blocks count as if nonexistant they might contain rubbish More...
union | rtosc_arg_t
struct | rtosc_arg_val_t
struct | rtosc_arg_itr_t
struct | rtosc_cmp_options
struct | rtosc_arg_val_itr
| Iterator over arg values. More...
struct | rtosc_va_list_t
| va_list container, required for passing va_list as pointers to functions More...
struct | ring_t

## Functions
size_t | rtosc_message (char *buffer, size_t len, const char *address, const char *arguments,...)
| Write OSC message to fixed length buffer. More...
size_t | rtosc_vmessage (char *buffer, size_t len, const char *address, const char *arguments, va_list va)
size_t | rtosc_avmessage (char *buffer, size_t len, const char *address, size_t nargs, const rtosc_arg_val_t *args)
size_t | rtosc_amessage (char *buffer, size_t len, const char *address, const char *arguments, const rtosc_arg_t *args)
unsigned | rtosc_narguments (const char *msg)
| Returns the number of arguments found in a given message. More...
char | rtosc_type (const char *msg, unsigned i)
void | rtosc_arg_val_itr_init (rtosc_arg_val_itr *itr, const rtosc_arg_val_t *av)
const rtosc_arg_val_t * | rtosc_arg_val_itr_get (const rtosc_arg_val_itr *itr, rtosc_arg_val_t *buffer)
| this usually just returns the value from operand, except for range operands, where the value is being interpolated More...
void | rtosc_arg_val_itr_next (rtosc_arg_val_itr *itr)
void | rtosc_v2args (rtosc_arg_t *args, size_t nargs, const char *arg_str, rtosc_va_list_t *ap)
| Pack arguments into pre-allocated rtosc_arg_t array. More...
void | rtosc_v2argvals (rtosc_arg_val_t *args, size_t nargs, const char *arg_str, va_list ap)
| Pack parameters into pre-allocated rtosc_arg_val-t array. More...
void | rtosc_2argvals (rtosc_arg_val_t *args, size_t nargs, const char *arg_str,...)
| Pack parameters into pre-allocated rtosc_arg_val-t array. More...
rtosc_arg_itr_t | rtosc_itr_begin (const char *msg)
| Create an argument iterator for a message. More...
rtosc_arg_val_t | rtosc_itr_next (rtosc_arg_itr_t *itr)
| Gets the next argument in a message. More...
int | rtosc_itr_end (rtosc_arg_itr_t itr)
| Determines if the iterator is at the end of the argument list. More...
rtosc_arg_t | rtosc_argument (const char *msg, unsigned i)
| Blob data may be safely written to. More...
size_t | rtosc_message_length (const char *msg, size_t len)
size_t | rtosc_message_ring_length (ring_t *ring)
| Finds the length of the next message inside a ringbuffer structure. More...
bool | rtosc_valid_message_p (const char *msg, size_t len)
| Validate if an arbitrary byte sequence is an OSC message. More...
const char * | rtosc_argument_string (const char *msg)
size_t | rtosc_bundle (char *buffer, size_t len, uint64_t tt, int elms,...)
| Generate a bundle from sub-messages. More...
size_t | rtosc_bundle_elements (const char *msg, size_t len)
| Find the elements in a bundle. More...
const char * | rtosc_bundle_fetch (const char *msg, unsigned i)
| Fetch a message within the bundle. More...
size_t | rtosc_bundle_size (const char *msg, unsigned i)
| Get the size of a particular bundle element. More...
int | rtosc_bundle_p (const char *msg)
| Test if the buffer contains a bundle. More...
uint64_t | rtosc_bundle_timetag (const char *msg)
bool | rtosc_match (const char *pattern, const char *msg, const char **path_end)
| This is a non-compliant pattern matcher for dispatching OSC messages. More...
const char * | rtosc_match_path (const char *pattern, const char *msg, const char **path_end)
| Attempt to match a rtosc style path while ignoring arguments. More...

## Detailed Description

Functions handling messages and arguments.

## Function Documentation

## ◆ rtosc_2argvals()

void rtosc_2argvals | ( | rtosc_arg_val_t * | args,
|  | size_t | nargs,
|  | const char * | arg_str,
|  |  | ...
| ) |  |

Pack parameters into pre-allocated rtosc_arg_val-t array.

See also
  rtosc_v2args

## ◆ rtosc_amessage()

size_t rtosc_amessage | ( | char * | buffer,
|  | size_t | len,
|  | const char * | address,
|  | const char * | arguments,
|  | const rtosc_arg_t * | args
| ) |  |

See also
  rtosc_message()

## ◆ rtosc_arg_val_itr_get()

const rtosc_arg_val_t* rtosc_arg_val_itr_get | ( | const rtosc_arg_val_itr * | itr,
|  | rtosc_arg_val_t * | buffer
| ) |  |

this usually just returns the value from operand, except for range operands, where the value is being interpolated

Parameters

  buffer | Temporary. Don't access it afterwards.

## ◆ rtosc_arg_val_itr_next()

void rtosc_arg_val_itr_next | ( | rtosc_arg_val_itr * | itr | ) |

Warning
  will loop forever on infinite ranges!

## ◆ rtosc_argument()

rtosc_arg_t rtosc_argument | ( | const char * | msg,
|  | unsigned | i
| ) |  |

Blob data may be safely written to.

Parameters

  msg | OSC message
  i | index of argument

Returns
  an argument by value via the rtosc_arg_t union

## ◆ rtosc_argument_string()

const char* rtosc_argument_string | ( | const char * | msg | ) |

Parameters

  OSC | message

Returns
  the argument string of a given message

## ◆ rtosc_avmessage()

size_t rtosc_avmessage | ( | char * | buffer,
|  | size_t | len,
|  | const char * | address,
|  | size_t | nargs,
|  | const rtosc_arg_val_t * | args
| ) |  |

See also
  rtosc_message()

## ◆ rtosc_bundle()

size_t rtosc_bundle | ( | char * | buffer,
|  | size_t | len,
|  | uint64_t | tt,
|  | int | elms,
|  |  | ...
| ) |  |

Generate a bundle from sub-messages.

Parameters

  buffer | Destination buffer
  len | Length of buffer
  tt | OSC time tag
  elms | Number of sub messages
  ... | Messages

Returns
  length of generated bundle or zero on failure

## ◆ rtosc_bundle_elements()

size_t rtosc_bundle_elements | ( | const char * | msg,
|  | size_t | len
| ) |  |

Find the elements in a bundle.

Parameters

  msg | OSC bundle
  len | Upper bound on the length of the bundle

Returns
  The number of messages contained within the bundle

## ◆ rtosc_bundle_fetch()

const char* rtosc_bundle_fetch | ( | const char * | msg,
|  | unsigned | i
| ) |  |

Fetch a message within the bundle.

Parameters

  msg | OSC bundle
  i | index of sub-message

Returns
  The ith message within the bundle

## ◆ rtosc_bundle_p()

int rtosc_bundle_p | ( | const char * | msg | ) |

Test if the buffer contains a bundle.

Parameters

  msg | OSC message

Returns
  true if message is a bundle

## ◆ rtosc_bundle_size()

size_t rtosc_bundle_size | ( | const char * | msg,
|  | unsigned | i
| ) |  |

Get the size of a particular bundle element.

Parameters

  msg | OSC bundle
  i | Index of sub-message

Returns
  The size of the ith sub-message in bytes

## ◆ rtosc_bundle_timetag()

uint64_t rtosc_bundle_timetag | ( | const char * | msg | ) |

Returns
  Time Tag for a bundle

## ◆ rtosc_itr_begin()

rtosc_arg_itr_t rtosc_itr_begin | ( | const char * | msg | ) |

Create an argument iterator for a message.

Parameters

  msg | OSC message

Returns
  an initialized iterator

## ◆ rtosc_itr_end()

int rtosc_itr_end | ( | rtosc_arg_itr_t | itr | ) |

Determines if the iterator is at the end of the argument list.

Parameters

  itr | OSC message iterator

Returns
  1 if there are no more elements, 0 otherwise

## ◆ rtosc_itr_next()

rtosc_arg_val_t rtosc_itr_next | ( | rtosc_arg_itr_t * | itr | ) |

Gets the next argument in a message.

Parameters

  itr | OSC message iterator

Returns
  a type value pair from the message

## ◆ rtosc_match()

bool rtosc_match | ( | const char * | pattern,
|  | const char * | msg,
|  | const char ** | path_end
| ) |  |

This is a non-compliant pattern matcher for dispatching OSC messages.

Overall the pattern specification is (normal-path)(#digit-specifier)?(/)?(:argument-restrictor)*

Parameters

  pattern | The pattern string stored in the Port
  msg | The OSC message to be matched
  path_end | if non-NULL, will point to where parsing stopped in the path (in case of a match, *path_end is always '/' or '\0')

Returns
  true if a normal match and false if unmatched

## ◆ rtosc_match_path()

const char* rtosc_match_path | ( | const char * | pattern,
|  | const char * | msg,
|  | const char ** | path_end
| ) |  |

Attempt to match a rtosc style path while ignoring arguments.

Parameters

  pattern | rtosc pattern
  msg | a normal C string or a rtosc message
  path_end | if non-NULL, will point to where parsing stopped in the path (in case of a match, *path_end is always '/' or '\0')

## ◆ rtosc_message()

size_t rtosc_message | ( | char * | buffer,
|  | size_t | len,
|  | const char * | address,
|  | const char * | arguments,
|  |  | ...
| ) |  |

Write OSC message to fixed length buffer.

On error, buffer will be zeroed. When buffer is NULL, the function returns the size of the buffer required to store the message

//Example messages
char buffer[128];
rtosc_message(buffer,128,"/path","TFI");
rtosc_message(buffer,128,"/path","s","foobar");
rtosc_message(buffer,128,"/path","i",128);
rtosc_message(buffer,128,"/path","f",128.0);
const char blob[4] = {'a','b','c','d'};
rtosc_message(buffer,128,"/path","b",4,blob);

Parameters

  buffer | Memory to write to
  len | Length of buffer
  address | OSC pattern to send message to
  arguments | String consisting of the types of the following arguments
  ... | OSC arguments to pass forward

Returns
  length of resulting message or zero if bounds exceeded

## ◆ rtosc_message_length()

size_t rtosc_message_length | ( | const char * | msg,
|  | size_t | len
| ) |  |

Parameters

  msg | OSC message
  len | Message length upper bound

Returns
  the size of a message given a chunk of memory.

## ◆ rtosc_message_ring_length()

size_t rtosc_message_ring_length | ( | ring_t * | ring | ) |

Finds the length of the next message inside a ringbuffer structure.

Parameters

  ring | The addresses and lengths of the split buffer, in a compatible format to jack's ringbuffer

Returns
  size of message stored in ring datastructure

## ◆ rtosc_narguments()

unsigned rtosc_narguments | ( | const char * | msg | ) |

Returns the number of arguments found in a given message.

Parameters

  msg | well formed OSC message

Returns
  number of arguments in message

## ◆ rtosc_type()

char rtosc_type | ( | const char * | msg,
|  | unsigned | i
| ) |  |

Parameters

  msg | well formed OSC message
  i | index of argument

Returns
  the type of the ith argument in msg

## ◆ rtosc_v2args()

void rtosc_v2args | ( | rtosc_arg_t * | args,
|  | size_t | nargs,
|  | const char * | arg_str,
|  | rtosc_va_list_t * | ap
| ) |  |

Pack arguments into pre-allocated rtosc_arg_t array.

Parameters

  args | Pre-allocated array; size must be greater or equal `nargs`
  nargs | Size of elements to pack
  arg_str | Rtosc string specifying the arguments' types
  ap | The parameters that shall be packed

## ◆ rtosc_v2argvals()

void rtosc_v2argvals | ( | rtosc_arg_val_t * | args,
|  | size_t | nargs,
|  | const char * | arg_str,
|  | va_list | ap
| ) |  |

Pack parameters into pre-allocated rtosc_arg_val-t array.

See also
  rtosc_v2args

## ◆ rtosc_valid_message_p()

bool rtosc_valid_message_p | ( | const char * | msg,
|  | size_t | len
| ) |  |

Validate if an arbitrary byte sequence is an OSC message.

Parameters

  msg | pointer to memory buffer
  len | length of buffer

## ◆ rtosc_vmessage()

size_t rtosc_vmessage | ( | char * | buffer,
|  | size_t | len,
|  | const char * | address,
|  | const char * | arguments,
|  | va_list | va
| ) |  |

See also
  rtosc_message()

rtosc_message
size_t rtosc_message(char *buffer, size_t len, const char *address, const char *arguments,...)
Write OSC message to fixed length buffer.