O2 1.2
Inter-process communication system for media applications
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
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_datao2_msg_data_ptr
 
typedef struct o2_message o2_message
 an O2 message container
 
typedef struct o2_messageo2_message_ptr
 
typedef struct o2_blob o2_blob
 The structure for binary large object.
 
typedef struct o2_blobo2_blob_ptr
 
typedef enum o2_typeo2_type_ptr
 
typedef union o2_argo2_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.