Real Time Open Sound Control librtosc: /build/rtosc/src/rtosc-0.3.1/include/rtosc/ports.h File Reference

Real Time Open Sound Control librtosc

Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions
ports.h File Reference

Collection of functions for ports. More...

`#include <vector>`
`#include <functional>`
`#include <initializer_list>`
`#include <rtosc/rtosc.h>`
`#include <string>`
`#include <cstdio>`
`#include <iosfwd>`

Go to the source code of this file.

## Classes
struct | rtosc::RtData
| data object for the dispatch routine More...
struct | rtosc::Port
| Port in rtosc dispatching hierarchy. More...
class | rtosc::Port::MetaIterator
class | rtosc::Port::MetaContainer
struct | rtosc::Ports
| Ports - a dispatchable collection of Port entries. More...
struct | rtosc::ClonePort
struct | rtosc::ClonePorts
struct | rtosc::MergePorts
struct | rtosc::OscDocFormatter

## Typedefs
typedef const char * | rtosc::msg_t
typedef void(* | rtosc::port_walker_t) (const Port *, const char *, const char *, const Ports &, void *, void *)
| Function pointer type for port walking.

## Enumerations
enum class | rtosc::path_search_opts { unmodified , sorted , sorted_and_unique_prefix }
| Options for path_search. More...

## Functions
int | rtosc::canonicalize_arg_vals (rtosc_arg_val_t *av, size_t n, const char *port_args, Port::MetaContainer meta)
| Convert given argument values to their canonical representation.
void | rtosc::map_arg_vals (rtosc_arg_val_t *av, size_t n, Port::MetaContainer meta)
| Convert each of the given arguments to their mapped symbol, if possible.
void | rtosc::walk_ports (const Ports *base, char *name_buffer, size_t buffer_size, void *data, port_walker_t walker, bool expand_bundles=true, void *runtime=NULL, bool ranges=false)
| Call a function on all ports and subports.
void | rtosc::path_search (const rtosc::Ports &root, const char *str, const char *needle, char *types, std::size_t max_types, rtosc_arg_t *args, std::size_t max_args, path_search_opts opts=path_search_opts::sorted_and_unique_prefix, bool reply_with_query=false)
| Returns paths and metadata of all direct children of a port, or of the port itself if that port has no children.
std::size_t | rtosc::path_search (const rtosc::Ports &root, const char *m, std::size_t max_ports, char *msgbuf, std::size_t bufsize, path_search_opts opts=path_search_opts::sorted_and_unique_prefix, bool reply_with_query=false)
| Returns a messages of all paths and metadata of all direct children of a port, or of the port itself if that port has no children.
int | rtosc::enum_key (Port::MetaContainer meta, const char *value)
| Return the index with value `value` from the metadata's enumeration.
std::ostream & | rtosc::operator<< (std::ostream &o, OscDocFormatter &formatter)

## Detailed Description

Collection of functions for ports.

This includes dispatchin, reading metadata etc.

## Typedef Documentation

## ◆ port_walker_t

typedef void(* rtosc::port_walker_t) (const Port *, const char *, const char *, const Ports &, void *, void *)

Function pointer type for port walking.

accepts:

- the currently walked port
- the port's absolute location
- the part of the location which makes up the port; this is usually the location's substring after the last slash, but it can also contain multiple slashes
- the port's base, i.e. it's parent Ports struct
- the custom data supplied to walk_ports
- the runtime object (which may be NULL if not known)

## Enumeration Type Documentation

## ◆ path_search_opts

enum class rtosc::path_search_opts
| strong

Options for path_search.

Examples see path-search tests.

Test:
  path-search.cpp

Enumerator
unmodified | Return ports in the order they are found. Fastest option. For "a/", "a/b", "a/", this will return "a/", "a/b", "a/".
sorted | Return ports sorted, but not filtered. For "a/", "a/b", "a/", this will return "a/", "a/", "a/b".
sorted_and_unique_prefix | Sorted and prefix-filtered: If "a/" is found, don't add any "a/...". Duplicate ports are still returned twice, because recursing into one of them will not help to access the other (and because duplicate ports shall be reported to port-checker). For "a/", "a/b", "a/", this will return "a/", "a/".

## Function Documentation

## ◆ canonicalize_arg_vals()

int rtosc::canonicalize_arg_vals | ( | rtosc_arg_val_t * | av,
|  | size_t | n,
|  | const char * | port_args,
|  | Port::MetaContainer | meta
| ) |  |

Convert given argument values to their canonical representation.

The ports first (or-wise) argument types are defined as canonical. E.g. if passing two 'S' argument values, the port could be `portname::ii:cc:SS` or `portname::ii:t`.

Parameters

  av | The input and output argument values
  n | The size of `av`
  port_args | The port arguments string, e.g. `::i:c:s`. The first non-colon letter sequence marks the canonical types
  meta | The port's metadata container

Returns
  The number of argument values that should have need conversion, but failed, e.g. because of values missing in rMap.

## ◆ enum_key()

int rtosc::enum_key | ( | Port::MetaContainer | meta,
|  | const char * | value
| ) |  |

Return the index with value `value` from the metadata's enumeration.

Parameters

  meta | The metadata
  value | The value to search the key for

Returns
  The first key holding value, or `std::numeric_limits<int>::min()` if none was found

## ◆ map_arg_vals()

void rtosc::map_arg_vals | ( | rtosc_arg_val_t * | av,
|  | size_t | n,
|  | Port::MetaContainer | meta
| ) |  |

Convert each of the given arguments to their mapped symbol, if possible.

Parameters

  av | The input and output argument values
  n | The size of `av`
  meta | The port's metadata container

## ◆ path_search() [1/2]

std::size_t rtosc::path_search | ( | const rtosc::Ports & | root,
|  | const char * | m,
|  | std::size_t | max_ports,
|  | char * | msgbuf,
|  | std::size_t | bufsize,
|  | path_search_opts | opts = `path_search_opts::sorted_and_unique_prefix`,
|  | bool | reply_with_query = `false`
| ) |  |

Returns a messages of all paths and metadata of all direct children of a port, or of the port itself if that port has no children.

Your app should always have a port "path-search", calling this function directly, and replying the resulting buffer `msgbuf` directly. That way, it will be ready for oscprompt, port-checker etc.

Parameters

  root | See `m`
  m | a valid OSC message requesting the path search. The corresponding port args must be of types "s" (location under `root` to look up port, or empty-string to search directly at `root`) "s" (only port names starting with this sting are returned, use empty-string or nullptr to match everything)
  max_ports | Maximum number (or higher) of child ports in any of your app's ports.
  msgbuf | Buffer for the reply message
  bufsize | Size of the message buffer `msgbuf`
  reply_with_query | Whether the reply message shall contain the two query strings in the beginning

Returns
  The length of the reply message (0 means error)

## ◆ path_search() [2/2]

void rtosc::path_search | ( | const rtosc::Ports & | root,
|  | const char * | str,
|  | const char * | needle,
|  | char * | types,
|  | std::size_t | max_types,
|  | rtosc_arg_t * | args,
|  | std::size_t | max_args,
|  | path_search_opts | opts = `path_search_opts::sorted_and_unique_prefix`,
|  | bool | reply_with_query = `false`
| ) |  |

Returns paths and metadata of all direct children of a port, or of the port itself if that port has no children.

If you just want to generate a reply message, use the overloaded function.

Parameters

  root | see `m`
  str | location under `root` to look up port, or empty-string to search directly at `root`
  needle | Only port names starting with this string are returned (use empty-string or nullptr to match everything)
  types | A buffer where the OSC type string is being written
  max_types | should be `max_args` +1 for best performance, see `max_args`
  args | An array where the argument values are being written
  max_args | maximum number of arguments in array at `args`. Should be greater or equal than 2 * (maximum no. of child ports of your app's ports).
  reply_with_query | Whether the reply message shall contain the two query strings in the beginning

## ◆ walk_ports()

void rtosc::walk_ports | ( | const Ports * | base,
|  | char * | name_buffer,
|  | size_t | buffer_size,
|  | void * | data,
|  | port_walker_t | walker,
|  | bool | expand_bundles = `true`,
|  | void * | runtime = `NULL`,
|  | bool | ranges = `false`
| ) |  |

Call a function on all ports and subports.

Parameters

  base | The base port of traversing
  name_buffer | Buffer which will be filled with the port name; must be reset to zero over the full length!
  buffer_size | Size of name_buffer
  data | Data that should be available in the callback
  walker | Callback function
  expand_bundles | Whether walking over bundles without subports invokes walking over each of the bundle's port
  runtime | Runtime object corresponding to `base` . If given, checks the runtime object will be used stop recursion if the Ports are disabled (using the "enabled by" property) and it will be passed to the walker