o2.h

Go to the documentation of this file.

// o2.h -- public header file for o2 system
// Roger B. Dannenberg and Zhang Chi
// see license.txt for license
// June 2016
 
#ifndef O2_H
#define O2_H
 
// Version is 2.0.0:
#define O2_VERSION 0x020000
 
#ifdef O2_NO_O2DISCOVERY
#define O2_NO_HUB 1
#endif
#if defined(O2_NO_O2DISCOVERY) && defined(O2_NO_ZEROCONF)
#error O2_NO_O2DISCOVERY and O2_NO_ZEROCONF are defined, therefore no discovery
#endif
#if !defined(O2_NO_O2DISCOVERY) && !defined(O2_NO_ZEROCONF)
#warning O2DISCOVERY and ZEROCONF are *both* enabled
#endif
 
 
#include "o2base.h"
#include "hostip.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
void o2_debug_flags(const char *flags);
 
const char *o2_error_to_string(O2err i);
 
typedef enum {
    //
    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
 
} O2err;
 
 
typedef enum {
    //
    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
} O2status;    
 
// Macros for o2 protocol
/* an internal value, ignored in transmission but check against O2_MARKER in the
 * argument list. Used to do primitive bounds checking */
#define O2_MARKER_A (void *) 0xdeadbeefdeadbeefL
#define O2_MARKER_B (void *) 0xf00baa23f00baa23L
//#endif
 
O2err o2_internet_enable(bool enable);
 
O2err o2_network_enable(bool enable);
 
typedef double O2time;
 
typedef struct O2msg_data {
    int32_t length; // msg length, not including this length field
    // we could put a nice structure here, but alignment and network vs host
    // byte ordering is confusing, so we use and int: flags are low-order bits,
    // and ttl is (misc >> 8). Note: ttl starts at zero and is incremented
    // each time the message is copied and forwarded to a tap. The message
    // is not forwarded if the count exceeds 3 (O2_MAX_TAP_FORWARDING).
    int32_t misc; // flags and ttl
    O2time timestamp;   
    char address[4];
} O2msg_data, *o2_msg_data_ptr;
 
 
#define O2MEM_ALIGN 8
#define O2MEM_ALIGNUP(s) ( ((s)+(O2MEM_ALIGN-1)) & ~(O2MEM_ALIGN-1) )
#define O2MEM_BIT32_ALIGN_PTR(p) ((char *) (((size_t) (p)) & ~3))
// returns the address of the byte AFTER the message
#define O2_MSG_DATA_END(data) (PTR(&(data)->misc) + (data)->length)
 
// find the next word-aligned string after str in a message:
const char *o2_next_o2string(const char *str);
// find the type string from o2_msg_data_ptr, skips initial ',':
#define o2_msg_data_types(data) (o2_next_o2string((data)->address) + 1)
#define o2_msg_types(msg) o2_msg_data_types(&msg->data)
// find the first parameter of the message, given the type string address
#define o2_msg_data_params(types) \
    o2_next_o2string((const char *) ((intptr_t) (types) & ~3))
 
typedef struct O2message {
    union {
        struct O2message *next; 
        int64_t pad_if_needed;   
    };
    O2msg_data data;
} O2message, *O2message_ptr;
 
#define O2_MSG_PAYLOAD(msg) PTR(&(msg)->data.misc)
 
 
typedef struct O2blob {
  uint32_t size;  
  char data[4];   
} O2blob, *O2blob_ptr;
 
 
typedef enum {
    // basic O2 types
    O2_INT32 =     'i',     
    O2_FLOAT =     'f',     
    O2_STRING =    's',     
    O2_BLOB =      'b',     
    O2_ARRAY_START = '[',   
    O2_ARRAY_END = ']',     
    
    // extended O2 types
    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 types
    O2_BOOL =      'B',     
    O2_VECTOR =    'v',     
} O2type, *O2type_ptr;
 
 
typedef union {
    int32_t    i32;  
    int32_t    i;    
    int64_t    i64;  
    int64_t    h;    
    float      f;    
    float      f32;  
    double     d;    
    double     f64;  
    char       s[4]; 
    char       S[4];
    int        c;    
    uint32_t   m;    
    O2time    t;    
    O2blob     b;    
    int32_t    B;    
    struct {
        int32_t len; 
        int32_t typ; 
        union {
            int32_t    *vi;  
            int64_t    *vh;  
            double     *vd;  
            float      *vf;  
            // note that a blob is basically a vector of bytes;
            // there is no type conversion from blob to vector though,
            // and no vector of shorts or bytes because if you converted
            // to a vector of int64_t, it would take 8x the message
            // space, forcing us to allocate very big buffers to
            // unpack messages.
        };
    } v;
} O2arg, *O2arg_ptr;
 
 
extern O2arg_ptr o2_got_start_array;
extern O2arg_ptr o2_got_end_array;
 
 
extern bool o2_stop_flag;
 
/*
 * A collection of cooperating O2 processes forms an
 * *ensemble*. Ensembles must have unique names. This allows
 * more than one ensemble to exist within a single network without
 * conflict. For example, there could be two ensembles, "joe" and
 * "sue", each with services named "synth." Since the ensemble
 * names are different, joe's messages to the synth service go to
 * joe's synth and not to sue's synth.
 *
 * Do not set, modify or free this variable! Consider it to be
 * read-only. It is managed by O2 using #o2_initialize and #o2_finish.
 */
extern const char *o2_ensemble_name; // also used to detect initialization
 
 
void o2_message_print(O2message_ptr msg);
 
 
void o2_msg_data_print(o2_msg_data_ptr msg);
 
 
typedef void (*O2method_handler)(const o2_msg_data_ptr msg, const char *types,
                                  O2arg_ptr *argv, int argc,
                                  const void *user_data);
 
O2err o2_initialize(const char *ensemble_name);
 
 
int o2_version(char *version);
 
 
int o2_memory(void *((*malloc)(size_t size)), void ((*free)(void *)),
              char *first_chunk, int64_t size, bool mallocp);
 
 
O2time o2_set_discovery_period(O2time period);
 
#ifndef O2_NO_HUB
O2err o2_hub(int version, const char *public_ip, const char *internal_ip,
             int tcp_port, int udp_port);
#endif
 
 
O2err o2_get_addresses(const char **public_ip, const char **internal_ip,
                        int *port);
 
const char *o2_get_proc_name(void);
 
int o2_parse_name(const char *name, char *public_ip,
                  char *internal_ip, int *port);
    
O2err o2_service_new(const char *service_name);
 
 
O2err o2_services_list(void);
 
 
O2err o2_services_list_free(void);
 
 
const char *o2_service_name(int i);
 
 
int o2_service_type(int i);
 
 
const char *o2_service_process(int i);
 
 
const char *o2_service_tapper(int i);
 
 
const char *o2_service_properties(int i);
 
 
const char *o2_service_getprop(int i, const char *attr);
 
int o2_service_search(int i, const char *attr, const char *value);
 
 
O2err o2_service_set_property(const char *service, const char *attr,
                              const char *value);
 
 
O2err o2_service_property_free(const char *service, const char *attr);
 
typedef enum {TAP_KEEP, TAP_RELIABLE, TAP_BEST_EFFORT} O2tap_send_mode;
 
O2err o2_tap(const char *tappee, const char *tapper, O2tap_send_mode send_mode);
 
 
O2err o2_untap(const char *tappee, const char *tapper);
 
 
O2err o2_service_free(const char *service_name);
 
 
O2err o2_method_new(const char *path, const char *typespec,
                    O2method_handler h, const void *user_data,
                    bool coerce, bool parse);
 
 
O2err o2_method_free(const char *path);
 
 
void o2_message_drop_warning(const char *warn, o2_msg_data_ptr msg);
 
void o2_drop_message(const char *warn, bool free_the_msg);
 
void o2_message_warnings(
        void (*warning)(const char *warn, o2_msg_data_ptr msg));
 
 
O2err o2_poll(void);
 
int o2_run(int rate);
 
int o2_status(const char *service);
 
 
#ifndef O2_NO_DEBUG
const char *o2_status_to_string(int status);
#endif
 
 
O2err o2_can_send(const char *service);
 
 
extern bool o2_clock_is_synchronized;
 
int o2_roundtrip(double *mean, double *min);
 
 
typedef O2time (*o2_time_callback)(void *rock);
 
 
int o2_clock_set(o2_time_callback gettime, void *rock);
 
 // turn off Doxygen report on #o2_send_marker
#define o2_send(path, time, ...)         \
    o2_send_marker(path, time, false,    \
                   __VA_ARGS__, O2_MARKER_A, O2_MARKER_B)
 \
O2err o2_send_marker(const char *path, double time, int tcp_flag,
                          const char *typestring, ...); // turn off Doxygen report on #o2_send_marker
#define o2_send_cmd(path, time, ...) \
    o2_send_marker(path, time, true, \
                   __VA_ARGS__, O2_MARKER_A, O2_MARKER_B)
 
 
O2err o2_message_send(O2message_ptr msg);
 
O2time o2_time_get(void);
 
 
O2time o2_local_time(void);
 
O2err o2_finish(void);
 // end of Basics
 
 
#ifndef O2_NO_OSC
O2err o2_osc_port_new(const char *service_name, int port_num,
                           int tcp_flag);
 
O2err o2_osc_port_free(int port_num);
 
 
O2err o2_osc_delegate(const char *service_name, const char *ip,
                           int port_num, int tcp_flag);
 
uint64_t o2_osc_time_offset(uint64_t offset); // end of OSC Interoperation
#endif
 
O2blob_ptr o2_blob_new(uint32_t size);
 
 
O2err o2_send_start(void);
 
 
O2err o2_add_float(float f);
 
O2err o2_add_string_or_symbol(O2type tcode, const char *s);
 
#define o2_add_symbol(s) o2_add_string_or_symbol(O2_SYMBOL, s)
 
#define o2_add_string(s) o2_add_string_or_symbol(O2_STRING, s)
 
O2err o2_add_blob(O2blob_ptr b);
 
O2err o2_add_blob_data(uint32_t size, void *data);
 
O2err o2_add_int64(int64_t i);
 
O2err o2_add_double_or_time(O2type tchar, double d);
 
#define o2_add_double(d) o2_add_double_or_time(O2_DOUBLE, d)
 
#define o2_add_time(t) o2_add_double_or_time(O2_TIME, t)
 
O2err o2_add_int32_or_char(O2type tcode, int32_t i);
 
#define o2_add_int32(i) o2_add_int32_or_char(O2_INT32, i)
 
#define o2_add_char(c) o2_add_int32_or_char(O2_CHAR, c)
 
O2err o2_add_midi(uint32_t m);
 
O2err o2_add_only_typecode(O2type typecode);
 
#define o2_add_true() o2_add_only_typecode(O2_TRUE);
 
#define o2_add_false() o2_add_only_typecode(O2_FALSE);
 
#define o2_add_tf(x) o2_add_only_typecode((x) != 0 ? O2_TRUE : O2_FALSE)
 
#define o2_add_bool(x) o2_add_int32_or_char(O2_BOOL, (x) != 0)
 
#define o2_add_nil() o2_add_only_typecode(O2_NIL);
 
#define o2_add_infinitum() o2_add_only_typecode(O2_INFINITUM);
 
#define o2_add_start_array() o2_add_only_typecode(O2_ARRAY_START);
 
#define o2_add_end_array() o2_add_only_typecode(O2_ARRAY_END);
 
O2err o2_add_vector(O2type element_type,
                  int length, void *data);
 
#ifndef O2_NO_BUNDLES
O2err o2_add_message(O2message_ptr msg);
#endif
 
O2message_ptr o2_message_finish(O2time time, const char *address,
                                 bool tcp_flag);
 
O2message_ptr o2_service_message_finish(O2time time,
             const char *service, const char *address, bool tcp_flag);
 
 
O2err o2_send_finish(O2time time, const char *address, bool tcp_flag);
 
 
int o2_extract_start(o2_msg_data_ptr msg);
 
O2arg_ptr o2_get_next(O2type type_code);
 
/* Scheduling */
// Messages are stored in the table modulo their timestamp, so the
// table acts sort of like a hash table (this is also called the
// timing wheel structure). Messages are stored as linked lists sorted
// by increasing timestamps when there are collisions.
 \
// Size of scheduler table.
#define O2_SCHED_TABLE_LEN 128
 
// Scheduler data structure.
typedef struct O2sched {
    int64_t last_bin;
    double last_time;
    O2message_ptr table[O2_SCHED_TABLE_LEN];
} O2sched, *O2sched_ptr;
extern O2sched o2_gtsched;
 
extern O2sched o2_ltsched;
 
extern O2sched_ptr o2_active_sched; // the scheduler that should be used
 
 
O2err o2_schedule_msg(O2sched_ptr scheduler, O2message_ptr msg);
 // end of a basics group
 
#ifndef O2_NO_MQTT
 // end of a mqttapi group
#endif
 
#ifndef O2_NO_BRIDGES
O2err o2lite_initialize();
 
 // end of a bridgeapi group
#endif
 
O2message_ptr o2_current_message();
 
 
void o2_complete_delivery();
 
 
O2message_ptr o2_postpone_delivery();
 
 
#ifndef O2_NO_MQTT
 O2err o2_mqtt_enable(const char *broker, int port_num);
 // end of a mqttapi group
#endif
 
// note: shared mem process support depends on bridge support
#ifndef O2_NO_SHAREDMEM
O2err o2_shmem_initialize();
#endif
 
 
#ifndef O2_NO_WEBSOCKETS
#ifdef O2_NO_BRIDGES
#error WEBSOCKETS feature depends on BRIDGES
#error You must define O2_NO_WEBSOCKETS or undefine O2_NO_BRIDGES
#endif
#endif 
 
#define O2_NO_HOSTNAME "\001"   // a non-text marker string
 
O2err http_initialize(int port, const char *root);
 // end of a httpapi group
 
#ifdef __cplusplus
}
#endif
 
#endif /* O2_H */