C API

Detailed Description

C bindings of libossia. Covers networking and presets.

API core concepts and ideas:

The API can be used to declare or interact with a tree of parameters.

There are multiple namespaces :

• The ossia_protocol_* functions allow interoperation with protocols supported by libossia.
• The ossia_device_*, ossia_node_*, ossia_parameter_* functions are used to configure local or remote device trees.
• The ossia_domain_* functions allow to define domains (min / max, or range of admissible values) for parameters.
• The ossia_value_* functions allow to create and read the content of libossia values. Simply put, such a value is an union of various types: int, float, string, etc.
• The ossia_logger_* functions can be usd to set-up a simple WebSocket-based logging infrastructure. The format of the logger messages is given in this example.
• The ossia_mq_* functions can be used when a thread-safe lock-free queue is needed. In particular, note that callbacks will be executed in different threads. Hence, this mechanism is needed if the user of this API cannot make its program thread-safe.

Multithreading notes:

Most functions are safe when called with different devices. When working on the same device, however, one has to take care to lock. e.g. the following cases are unsafe:

Thread 1	Thread 2
ossia_node_find(my_dev, "/foo");	ossia_node_create(my_dev, "/bar");
ossia_device_free(my_dev);	ossia_device_get_root_node(my_dev);

While the following cases are safe:

Thread 1	Thread 2
ossia_node_find(my_dev, "/foo");	ossia_node_create(other, "/bar");
ossia_parameter_push_i(addr, 123);	ossia_parameter_get_value(addr);

• Unsafe: Cannot be safely called from multiple threads.
• Safe: Can be safely called from multiple threads, may block.
• MT-Safe: Can be safely called from multiple threads, won't block.
• Data-safe: Can be safely called from multiple threads with the same device. For instance, ossia_parameter_set_value and ossia_parameter_get_value.

Only functions marked as data-safe can be called in parallel on the same device, and no function with weaker guarantees shall be called on the device at the same time in another thread.

Modules
	Protocol
	Instantiation of various protocols such as OSC, Minuit, OSCQuery...
	Device
	Device tree management.
	Parameter
	Parameter creation, and attributes.
	Node
	Node creation, removal, finding.
	Domain
	Parameter min / max.
	Value
	Tools to create various kinds of values.
	Logging
	Log various messages in JSON to a websocket server, and send heartbeats.
	Message queue
	When threads cannot be used from the client side.
	Network context
	Event loop to process messages.

Files
file	ossia-c.h

Typedefs
typedef struct ossia_protocol *	ossia_protocol_t
typedef struct ossia_device *	ossia_device_t
typedef struct ossia_domain *	ossia_domain_t
typedef struct ossia_value *	ossia_value_t
typedef struct ossia_logger *	ossia_logger_t
typedef void *	ossia_node_t
typedef void *	ossia_parameter_t
typedef void(*	ossia_node_callback_t) (void *ctx, ossia_node_t)
typedef struct ossia_node_callback_index *	ossia_node_callback_idx_t
typedef void(*	ossia_parameter_callback_t) (void *ctx, ossia_parameter_t)
typedef struct ossia_parameter_callback_index *	ossia_parameter_callback_idx_t
typedef void(*	ossia_value_callback_t) (void *ctx, ossia_value_t)
typedef struct ossia_value_callback_index *	ossia_value_callback_idx_t