Loading...
Searching...
No Matches
o2.h File Reference
`#include <stdlib.h>`
`#include <stdint.h>`

Go to the source code of this file.

## Data Structures

struct | o2_msg_data
| data part of an O2 message More...
struct | o2_message
| an O2 message container More...
struct | o2_blob
| The structure for binary large object. More...
union | o2_arg
| union of all O2 parameter types More...

## Macros

#define | TRUE 1
#define | FALSE 0
#define | O2_SUCCESS 0
| function was successful
#define | O2_FAIL (-1)
| an error return value: a non-specific error occurred.
#define | O2_SERVICE_CONFLICT (-2)
| an error return value: path to handler specifies a remote service
#define | O2_NO_SERVICE (-3)
| an error return value: path to handler specifies non-existant service
#define | O2_NO_MEMORY (-4)
| an error return value: process is out of free memory
#define | O2_ALREADY_RUNNING (-5)
| an error return value for o2_initialize(): O2 is already running.
#define | O2_BAD_NAME (-6)
| an error return value for o2_initialize(): invalid name parameter.
#define | O2_BAD_TYPE (-7)
| an error return value for o2_add_vector(): invalid element type
#define | O2_BAD_ARGS (-8)
| an error return value: mismatched types and arguments returned by o2_message_build(), o2_send(), o2_send_cmd()
#define | O2_TCP_HUP (-9)
| an error return value for o2_initialize(): the socket is closed.
#define | O2_HOSTNAME_TO_NETADDR_FAIL (-10)
| an error return value indicating inet_pton() failed to convert a string to an IP address
#define | O2_TCP_CONNECT_FAIL (-11)
| an error return value: attempt to make a TCP connection failed
#define | O2_NO_CLOCK (-12)
| an error return value: message was not scheduled or delivered because the current time is not available
#define | O2_NO_HANDLER (-13)
| an error return value: no handler for an address
#define | O2_INVALID_MSG (-14)
| an error return value: an O2 message is invalid
#define | O2_SEND_FAIL (-15)
| an error return value: could not write to socket or send datagram
#define | O2_BAD_SERVICE_NAME (-16)
| an error return value: a service name was NULL or contained a slash (/)
#define | O2_SERVICE_EXISTS (-17)
| an error return value: attempt to create a local service when one exists already
#define | O2_NOT_INITIALIZED (-18)
| an error return value: O2 has not been initialized
#define | O2_LOCAL_NOTIME 0
| return value for o2_status(): local service, no clock sync yet
#define | O2_REMOTE_NOTIME 1
| return value for o2_status(): remote service but no clock sync yet
#define | O2_BRIDGE_NOTIME 2
| return value for o2_status(): service is connected but no clock sync yet.
#define | O2_TO_OSC_NOTIME 3
| return value for o2_status(): service is connected but no clock sync yet.
#define | O2_LOCAL 4
| return value for o2_status(): local service with clock sync.
#define | O2_REMOTE 5
| return value for o2_status(): remote service with clock sync.
#define | O2_BRIDGE 6
| return value for o2_status(): connected with clock sync.
#define | O2_TO_OSC 7
| return value for o2_status(): connected with clock sync.
#define | O2_MARKER_A (void *) 0xdeadbeefdeadbeefL
#define | O2_MARKER_B (void *) 0xf00baa23f00baa23L
#define | O2_MALLOC(x) o2_dbg_malloc(x, __FILE__, __LINE__)
#define | O2_FREE(x) o2_dbg_free(x, __FILE__, __LINE__)
#define | O2_CALLOC(n, s) o2_dbg_calloc((n), (s), __FILE__, __LINE__)
#define | MSG_DATA_LENGTH(m) (((int32_t *) &((m)->timestamp))[-1])
#define | WORD_ALIGN_PTR(p) ((char *) (((size_t) (p)) & ~3))
| get the type string from o2_msg_data_ptr
#define | O2_MSG_TYPES(msg) WORD_ALIGN_PTR((msg)->address + strlen((msg)->address) + 4) + 1;
#define | o2_send(path, time, ...)
| Construct and send O2 message with best effort protocol.
#define | o2_send_cmd(path, time, ...)
| Construct and send an O2 message reliably.
#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_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

## Typedefs

typedef double | o2_time
| O2 timestamps are doubles representing seconds since the approximate start time of the application.
typedef struct o2_msg_data | o2_msg_data
| data part of an O2 message
typedef struct o2_msg_data * | o2_msg_data_ptr
typedef struct o2_message | o2_message
| an O2 message container
typedef struct o2_message * | o2_message_ptr
typedef struct o2_blob | o2_blob
| The structure for binary large object.
typedef struct o2_blob * | o2_blob_ptr
typedef enum o2_type * | o2_type_ptr
typedef union o2_arg * | o2_arg_ptr
typedef void(* | o2_method_handler) (const o2_msg_data_ptr msg, const char *types, o2_arg_ptr *argv, int argc, void *user_data)
| callback function to receive an O2 message
typedef o2_time(* | o2_time_callback) (void *rock)
| signature for callback that defines the master clock

## Enumerations

enum | o2_type { 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...

## Functions

void | o2_debug_flags (const char *flags)
| Enable debugging output.
| void ((*o2_free)(void *))
void * | o2_calloc (size_t n, size_t s)
void * | o2_dbg_malloc (size_t size, const char *file, int line)
void | o2_dbg_free (void *obj, const char *file, int line)
void * | o2_dbg_calloc (size_t n, size_t s, const char *file, int line)
| allocate memory
int | o2_initialize (const char *application_name)
| Start O2.
int | o2_memory (void *((*malloc)(size_t size)), void((*free)(void *)))
| Tell O2 how to allocate/free memory.
o2_time | o2_set_discovery_period (o2_time period)
| Set discovery period.
int | o2_hub (const char *ipaddress, int port)
| Connect to a hub.
int | o2_get_address (const char **ipaddress, int *port)
| Get IP address and TCP connection port number.
int | o2_service_new (const char *service_name)
| Add a service to the current application.
int | o2_tap (const char *tappee, const char *tapper)
| copy messages from one service to another
int | o2_service_free (const char *service_name)
| Remove a local service.
int | o2_method_new (const char *path, const char *typespec, o2_method_handler h, void *user_data, int coerce, int parse)
| Add a handler for an address.
int | o2_poll ()
| Process current O2 messages.
int | o2_run (int rate)
| Run O2.
int | o2_status (const char *service)
| Check the status of the service.
int | o2_roundtrip (double *mean, double *min)
| Get network round-trip information.
int | o2_clock_set (o2_time_callback gettime, void *rock)
| Provide a time reference to O2.
int | o2_message_send (o2_message_ptr msg)
| Send an O2 message. (See also macros o2_send and o2_send_cmd).
o2_time | o2_time_get ()
| Get the estimated synchronized global O2 time.
o2_time | o2_local_time ()
| Get the real time using the local O2 clock.
const char * | o2_error_to_string (int i)
| Return text representation of an O2 error.
int | o2_finish ()
| release the memory and shut down O2.
int | o2_osc_port_new (const char *service_name, int port_num, int tcp_flag)
| Create a port to receive OSC messages.
int | o2_osc_port_free (int port_num)
| Remove a port receiving OSC messages.
int | 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.
uint64_t | o2_osc_time_offset (uint64_t offset)
| Set the OSC time offset.
o2_blob_ptr | o2_blob_new (uint32_t size)
| Allocate a blob.
int | o2_send_start ()
| Prepare to build a message.
int | o2_add_float (float f)
| add a `float` to the message (see o2_send_start())
int | o2_add_string_or_symbol (o2_type tcode, const char *s)
| This function suppports o2_add_symbol() and o2_add_string() Normally, you should not call this directly.
int | o2_add_blob (o2_blob_ptr b)
| add an `o2_blob` to the message (see o2_send_start()), where the blob is given as a pointer to an o2_blob object.
int | o2_add_blob_data (uint32_t size, void *data)
| add an `o2_blob` to the message (see o2_send_start()), where the blob is specified by a size and a data address.
int | o2_add_int64 (int64_t i)
| add an `int64` to the message (see o2_send_start())
int | o2_add_double_or_time (o2_type tchar, double d)
| This function supports o2_add_double() and o2_add_time() Normally, you should not call this directly.
int | o2_add_int32_or_char (o2_type tcode, int32_t i)
| This function supports o2_add_int32() and o2_add_char() Normally, you should not call this directly.
int | o2_add_midi (uint32_t m)
| add a short midi message to the message (see o2_send_start())
int | o2_add_only_typecode (o2_type 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.
int | o2_add_vector (o2_type element_type, int length, void *data)
| add a vector
int | o2_add_message (o2_message_ptr msg)
| add a message to a bundle
o2_message_ptr | o2_message_finish (o2_time time, const char *address, int tcp_flag)
| finish and return the message.
o2_message_ptr | o2_service_message_finish (o2_time time, const char *service, const char *address, int tcp_flag)
| finish and return a message, prepending service name
void | o2_message_free (o2_message_ptr msg)
| free a message allocated by o2_send_start().
int | o2_send_finish (o2_time time, const char *address, int tcp_flag)
| send a message allocated by o2_send_start().
int | o2_extract_start (o2_msg_data_ptr msg)
| initialize internal state to parse, extract, and coerce message arguments.
o2_arg_ptr | o2_get_next (o2_type type_code)
| get the next message parameter
int | o2_schedule (o2_sched_ptr scheduler, o2_message_ptr msg)

## Variables

void *(* | o2_malloc )(size_t size))
o2_arg_ptr | o2_got_start_array
o2_arg_ptr | o2_got_end_array
int | o2_stop_flag
| set this flag to stop o2_run()
const char * | o2_application_name
int | o2_clock_is_synchronized
| A variable indicating that the clock is the master or is synchronized to the master.
o2_sched | o2_gtsched
| Scheduler that schedules according to global (master) clock time.
o2_sched | o2_ltsched
| Scheduler that schedules according to local clock time.
o2_sched_ptr | o2_active_sched
| Current scheduler.