o2.h File Reference

#include "o2base.h"
#include "hostip.h"

Go to the source code of this file.

Classes
struct	O2msg_data
	data part of an O2 message More...
struct	O2message
	an O2 message container More...
struct	O2blob
	The structure for binary large object. More...
union	O2arg
	union of all O2 parameter types More...

Macros
#define	O2_VERSION   0x020000
#define	O2_MARKER_A   (void *) 0xdeadbeefdeadbeefL
#define	O2_MARKER_B   (void *) 0xf00baa23f00baa23L
#define	O2MEM_ALIGN   8
	get the type string from o2_msg_data_ptr More...
#define	O2MEM_ALIGNUP(s)   ( ((s)+(O2MEM_ALIGN-1)) & ~(O2MEM_ALIGN-1) )
#define	O2MEM_BIT32_ALIGN_PTR(p)   ((char *) (((size_t) (p)) & ~3))
#define	O2_MSG_DATA_END(data)   (PTR(&(data)->misc) + (data)->length)
#define	o2_msg_data_types(data)   (o2_next_o2string((data)->address) + 1)
#define	o2_msg_types(msg)   o2_msg_data_types(&msg->data)
#define	o2_msg_data_params(types)    o2_next_o2string((const char *) ((intptr_t) (types) & ~3))
#define	O2_MSG_PAYLOAD(msg)   PTR(&(msg)->data.misc)
	The address of the actual message, not including the length field:
#define	o2_send(path, time, ...)
	Construct and send O2 message with best effort protocol. More...
#define	o2_send_cmd(path, time, ...)
	Construct and send an O2 message reliably. More...
#define	o2_add_symbol(s)   o2_add_string_or_symbol(O2_SYMBOL, s)
	add a symbol to the message (see o2_send_start)
#define	o2_add_string(s)   o2_add_string_or_symbol(O2_STRING, s)
	add a string to the message (see o2_send_start)
#define	o2_add_double(d)   o2_add_double_or_time(O2_DOUBLE, d)
	add a double to the message (see o2_send_start)
#define	o2_add_time(t)   o2_add_double_or_time(O2_TIME, t)
	add a time (double) to the message (see o2_send_start)
#define	o2_add_int32(i)   o2_add_int32_or_char(O2_INT32, i)
	add an int32 to the message (see o2_send_start)
#define	o2_add_char(c)   o2_add_int32_or_char(O2_CHAR, c)
	add a char to the message (see o2_send_start)
#define	o2_add_true()   o2_add_only_typecode(O2_TRUE);
	add "true" to the message (see o2_send_start)
#define	o2_add_false()   o2_add_only_typecode(O2_FALSE);
	add a "false" to the message (see o2_send_start)
#define	o2_add_tf(x)   o2_add_only_typecode((x) != 0 ? O2_TRUE : O2_FALSE)
	add a boolean typecode T or F (this differs from o2_add_bool which uses typecode B and adds a 0 or 1 as data)
#define	o2_add_bool(x)   o2_add_int32_or_char(O2_BOOL, (x) != 0)
	add 0 (false) or 1 (true) to the message (see o2_send_start)
#define	o2_add_nil()   o2_add_only_typecode(O2_NIL);
	add "nil" to the message (see o2_send_start)
#define	o2_add_infinitum()   o2_add_only_typecode(O2_INFINITUM);
	add "infinitum" to the message (see o2_send_start)
#define	o2_add_start_array()   o2_add_only_typecode(O2_ARRAY_START);
	start adding an array
#define	o2_add_end_array()   o2_add_only_typecode(O2_ARRAY_END);
	finish adding an array
#define	O2_NO_HOSTNAME   "\001"

Typedefs
typedef double	O2time
	O2 timestamps are doubles representing seconds since the approximate start time of the ensemble.
typedef struct O2msg_data	O2msg_data
	data part of an O2 message More...
typedef struct O2msg_data *	o2_msg_data_ptr
typedef struct O2message	O2message
	an O2 message container More...
typedef struct O2message *	O2message_ptr
typedef struct O2blob	O2blob
	The structure for binary large object. More...
typedef struct O2blob *	O2blob_ptr
typedef enum O2type *	O2type_ptr
typedef union O2arg *	O2arg_ptr
typedef void(*	O2method_handler) (const o2_msg_data_ptr msg, const char *types, O2arg_ptr *argv, int argc, const void *user_data)
	callback function to receive an O2 message More...
typedef O2time(*	o2_time_callback) (void *rock)
	signature for callback that defines the reference clock More...

Enumerations
enum	O2err {   O2_SUCCESS = 0 , O2_FAIL = -1 , O2_SERVICE_EXISTS = -2 , O2_NO_SERVICE = -3 ,   O2_NO_MEMORY = -4 , O2_ALREADY_RUNNING = -5 , O2_BAD_NAME = -6 , O2_BAD_TYPE = -7 ,   O2_BAD_ARGS = -8 , O2_TCP_HUP = -9 , O2_HOSTNAME_TO_NETADDR_FAIL = -10 , O2_TCP_CONNECT_FAIL = -11 ,   O2_NO_CLOCK = -12 , O2_NO_HANDLER = -13 , O2_INVALID_MSG = -14 , O2_SEND_FAIL = -15 ,   O2_SOCKET_ERROR = -16 , O2_NOT_INITIALIZED = -17 , O2_BLOCKED = -18 , O2_NO_PORT = -19 ,   O2_NO_NETWORK = -20 }
	return values used generally by O2 functions More...
enum	O2status {   O2_UNKNOWN = -1 , O2_LOCAL_NOTIME = 0 , O2_REMOTE_NOTIME = 1 , O2_BRIDGE_NOTIME = 2 ,   O2_TO_OSC_NOTIME = 3 , O2_LOCAL = 4 , O2_REMOTE = 5 , O2_BRIDGE = 6 ,   O2_TO_OSC = 7 , O2_TAP = 8 }
	Status return codes for the o2_status function. More...
enum	O2type {   O2_INT32 = 'i' , O2_FLOAT = 'f' , O2_STRING = 's' , O2_BLOB = 'b' ,   O2_ARRAY_START = '[' , O2_ARRAY_END = ']' , O2_INT64 = 'h' , O2_TIME = 't' ,   O2_DOUBLE = 'd' , O2_SYMBOL = 'S' , O2_CHAR = 'c' , O2_MIDI = 'm' ,   O2_TRUE = 'T' , O2_FALSE = 'F' , O2_NIL = 'N' , O2_INFINITUM = 'I' ,   O2_BOOL = 'B' , O2_VECTOR = 'v' }
	An enumeration of the O2 message types. More...
enum	O2tap_send_mode { TAP_KEEP , TAP_RELIABLE , TAP_BEST_EFFORT }

Functions
void	o2_debug_flags (const char *flags)
	Enable debugging output. More...
const char *	o2_error_to_string (O2err i)
	Return text representation of an O2 error. More...
O2err	o2_internet_enable (bool enable)
	Disable Internet connections. More...
O2err	o2_network_enable (bool enable)
	Disable external nework connections. More...
const char *	o2_next_o2string (const char *str)
void	o2_message_print (O2message_ptr msg)
	print an O2 message to stdout More...
void	o2_msg_data_print (o2_msg_data_ptr msg)
	print a message from msg_data_ptr to stdout More...
O2err	o2_initialize (const char *ensemble_name)
	Start O2. More...
int	o2_version (char *version)
	get O2 version number More...
int	o2_memory (void *((*malloc)(size_t size)), void((*free)(void *)), char *first_chunk, int64_t size, bool mallocp)
	Tell O2 how to allocate/free memory. More...
O2time	o2_set_discovery_period (O2time period)
	Set discovery period. More...
O2err	o2_hub (int version, const char *public_ip, const char *internal_ip, int tcp_port, int udp_port)
	Connect to a hub. More...
O2err	o2_get_addresses (const char **public_ip, const char **internal_ip, int *port)
	Get IP address and TCP connection port number. More...
const char *	o2_get_proc_name (void)
	Get Public:Local:Port service name string. More...
int	o2_parse_name (const char *name, char *public_ip, char *internal_ip, int *port)
	Parse Public:Local:Port string and extract fields. More...
O2err	o2_service_new (const char *service_name)
	Add a service to the current process. More...
O2err	o2_services_list (void)
	list known services and taps More...
O2err	o2_services_list_free (void)
	free the list of known services and taps More...
const char *	o2_service_name (int i)
	get a service name from a saved list of services More...
int	o2_service_type (int i)
	get a type from a saved list of services More...
const char *	o2_service_process (int i)
	get a process name from a saved list of services More...
const char *	o2_service_tapper (int i)
	get a tapper name from a saved list of services More...
const char *	o2_service_properties (int i)
	get the properties string from a saved list of services More...
const char *	o2_service_getprop (int i, const char *attr)
	get a property value from a saved list of services More...
int	o2_service_search (int i, const char *attr, const char *value)
	find a service matching attribute/value pair More...
O2err	o2_service_set_property (const char *service, const char *attr, const char *value)
	set an attribute and value property for a service More...
O2err	o2_service_property_free (const char *service, const char *attr)
	remove an attribute and value property from a service More...
O2err	o2_tap (const char *tappee, const char *tapper, O2tap_send_mode send_mode)
	install tap to copy messages from one service to another More...
O2err	o2_untap (const char *tappee, const char *tapper)
	remove tap from service More...
O2err	o2_service_free (const char *service_name)
	Remove a local service. More...
O2err	o2_method_new (const char *path, const char *typespec, O2method_handler h, const void *user_data, bool coerce, bool parse)
	Add a handler for an address. More...
O2err	o2_method_free (const char *path)
	remove a path – remove a path and associated handler More...
void	o2_message_drop_warning (const char *warn, o2_msg_data_ptr msg)
	Default dropped message alert. More...
void	o2_drop_message (const char *warn, bool free_the_msg)
	Tell world that a message was dropped. More...
void	o2_message_warnings (void(*warning)(const char *warn, o2_msg_data_ptr msg))
	Enable/Disable warnings for dropped messages. More...
O2err	o2_poll (void)
	Process current O2 messages. More...
int	o2_run (int rate)
	Run O2. More...
int	o2_status (const char *service)
	Check the status of the service. More...
const char *	o2_status_to_string (int status)
	retrieve text version of an O2status More...
O2err	o2_can_send (const char *service)
	Test if send_cmd will block. More...
int	o2_roundtrip (double *mean, double *min)
	Get network round-trip information. More...
int	o2_clock_set (o2_time_callback gettime, void *rock)
	Provide a time reference to O2. More...
O2err	o2_message_send (O2message_ptr msg)
	Send an O2 message. (See also macros o2_send and o2_send_cmd). More...
O2time	o2_time_get (void)
	Get the estimated synchronized global O2 time. More...
O2time	o2_local_time (void)
	Get the real time using the local O2 clock. More...
O2err	o2_finish (void)
	release the memory and shut down O2. More...
O2err	o2_osc_port_new (const char *service_name, int port_num, int tcp_flag)
	Create a port to receive OSC messages. More...
O2err	o2_osc_port_free (int port_num)
	Remove a port receiving OSC messages. More...
O2err	o2_osc_delegate (const char *service_name, const char *ip, int port_num, int tcp_flag)
	Create a service that forwards O2 messages to an OSC server. More...
uint64_t	o2_osc_time_offset (uint64_t offset)
	Set the OSC time offset. More...
O2blob_ptr	o2_blob_new (uint32_t size)
	Allocate a blob. More...
O2err	o2_send_start (void)
	Prepare to build a message. More...
O2err	o2_add_float (float f)
	add a float to the message (see o2_send_start)
O2err	o2_add_string_or_symbol (O2type tcode, const char *s)
	This function suppports o2_add_symbol and o2_add_string Normally, you should not call this directly.
O2err	o2_add_blob (O2blob_ptr b)
	add an O2blob to the message (see o2_send_start), where the blob is given as a pointer to an O2blob object.
O2err	o2_add_blob_data (uint32_t size, void *data)
	add an O2blob to the message (see o2_send_start), where the blob is specified by a size and a data address.
O2err	o2_add_int64 (int64_t i)
	add an int64 to the message (see o2_send_start)
O2err	o2_add_double_or_time (O2type tchar, double d)
	This function supports o2_add_double and o2_add_time Normally, you should not call this directly.
O2err	o2_add_int32_or_char (O2type tcode, int32_t i)
	This function supports o2_add_int32 and o2_add_char Normally, you should not call this directly.
O2err	o2_add_midi (uint32_t m)
	add a short midi message to the message (see o2_send_start)
O2err	o2_add_only_typecode (O2type typecode)
	This function supports o2_add_true, o2_add_false, o2_add_bool, o2_add_nil, o2_add_infinitum, and others. Normally, you should not call this directly.
O2err	o2_add_vector (O2type element_type, int length, void *data)
	add a vector More...
O2err	o2_add_message (O2message_ptr msg)
	add a message to a bundle More...
O2message_ptr	o2_message_finish (O2time time, const char *address, bool tcp_flag)
	finish and return the message. More...
O2message_ptr	o2_service_message_finish (O2time time, const char *service, const char *address, bool tcp_flag)
	finish and return a message, prepending service name More...
O2err	o2_send_finish (O2time time, const char *address, bool tcp_flag)
	send a message allocated by o2_send_start. More...
int	o2_extract_start (o2_msg_data_ptr msg)
	initialize internal state to parse, extract, and coerce message arguments. More...
O2arg_ptr	o2_get_next (O2type type_code)
	get the next message parameter More...
O2err	o2_schedule_msg (O2sched_ptr scheduler, O2message_ptr msg)
O2err	o2lite_initialize ()
	enable O2lite protocol connections to this proces
O2message_ptr	o2_current_message ()
void	o2_complete_delivery ()
O2message_ptr	o2_postpone_delivery ()
O2err	o2_mqtt_enable (const char *broker, int port_num)
	Enable MQTT to form wide-area-network connections between O2 processes. More...
O2err	o2_shmem_initialize ()
O2err	http_initialize (int port, const char *root)
	Enable HTTP and Websocket access to an O2 host. More...

Variables
O2arg_ptr	o2_got_start_array
O2arg_ptr	o2_got_end_array
bool	o2_stop_flag
	set this flag to stop o2_run More...
const char *	o2_ensemble_name
bool	o2_clock_is_synchronized
	A variable indicating that the clock is the reference or is synchronized to the reference.
O2sched	o2_gtsched
	Scheduler that schedules according to global (reference) clock time. More...
O2sched	o2_ltsched
	Scheduler that schedules according to local clock time. More...
O2sched_ptr	o2_active_sched
	Current scheduler. More...

Function Documentation

o2_complete_delivery()

void o2_complete_delivery

(

)

/brief Free the message being sent.

This function is for use within a #bridge_send callback. It takes ownership of the current message being sent and frees its memory. Both of these are required for correctness of #bridge_send callbacks, but if the message is to be freed later, use o2_postpone_delivery instead. Never call this function from a message handler passed to o2_method_new.

o2_current_message()

O2message_ptr o2_current_message

(

)

/brief Obtain the message being sent.

This function is for use within a #bridge_send callback. It obtains a reference to the message to be sent, but it does not assume ownership of the message.

o2_postpone_delivery()

O2message_ptr o2_postpone_delivery

(

)

/brief Take ownership of the current message being delivered.

This function is for use within a #bridge_send callback. It takes ownership of and returns the current message. It is then the callback's responsibility to (eventually) free the message using #O2_FREE. Typically, this function is used to hold the message in a queue for delivery, and the message is freed after the data is transferred via the protocol supported by this bridge. The message should also be freed if the bridge is deleted, i.e. when the #bridge_finish callback is called. Never call this function from a message handler passed to o2_method_new. These handlers may not take ownership of messages.