Real Time Open Sound Control librtosc
Loading...
Searching...
No Matches
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
avThe input and output argument values
nThe size of av
port_argsThe port arguments string, e.g. i:c:s. The first non-colon letter sequence marks the canonical types
metaThe 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
metaThe metadata
valueThe 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
avThe input and output argument values
nThe size of av
metaThe 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
rootSee m
ma 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_portsMaximum number (or higher) of child ports in any of your app's ports.
msgbufBuffer for the reply message
bufsizeSize of the message buffer msgbuf
reply_with_queryWhether 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
rootsee m
strlocation under root to look up port, or empty-string to search directly at root
needleOnly port names starting with this string are returned (use empty-string or nullptr to match everything)
typesA buffer where the OSC type string is being written
max_typesshould be max_args +1 for best performance, see max_args
argsAn array where the argument values are being written
max_argsmaximum 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_queryWhether 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
baseThe base port of traversing
name_bufferBuffer which will be filled with the port name; must be reset to zero over the full length!
buffer_sizeSize of name_buffer
dataData that should be available in the callback
walkerCallback function
expand_bundlesWhether walking over bundles without subports invokes walking over each of the bundle's port
runtimeRuntime 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