O2  1.1
Inter-process communication system for media applications
Macros
Return Codes

Macros

#define O2_SUCCESS   0
 function was successful
 
#define O2_FAIL   (-1)
 an error return value: a non-specific error occurred. More...
 
#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 More...
 
#define O2_REMOTE_NOTIME   1
 return value for o2_status(): remote service but no clock sync yet More...
 
#define O2_BRIDGE_NOTIME   2
 return value for o2_status(): service is connected but no clock sync yet. More...
 
#define O2_TO_OSC_NOTIME   3
 return value for o2_status(): service is connected but no clock sync yet. More...
 
#define O2_LOCAL   4
 return value for o2_status(): local service with clock sync. More...
 
#define O2_REMOTE   5
 return value for o2_status(): remote service with clock sync. More...
 
#define O2_BRIDGE   6
 return value for o2_status(): connected with clock sync. More...
 
#define O2_TO_OSC   7
 return value for o2_status(): connected with clock sync. More...
 

Detailed Description

Macro Definition Documentation

◆ O2_BRIDGE

#define O2_BRIDGE   6

return value for o2_status(): connected with clock sync.

The service is attached by a non-IP link, and this process is synchronized. If the bridged process is also synchronized, timed messages are sent immediately and dispatched according to the synchronized clock; if the bridged process is not synchronized, timed messages are scheduled locally and sent according to the timestamp, resulting in some added network latency.

◆ O2_BRIDGE_NOTIME

#define O2_BRIDGE_NOTIME   2

return value for o2_status(): service is connected but no clock sync yet.

The service is attached to this process by a non-IP link. Clock sync has not yet been established between the master clock and this process, so non-zero timestamped messages to this service will be dropped. Note that within other processes, the status for this service will be O2_REMOTE_NOTIME rather than O2_BRIDGE_NOTIME. Note also that O2 does not require the remote bridged process to have a synchronized clock, so "NOTIME" only means that this process is not synchronized and therefore cannot (and will not) schedule a timestamped message for timed delivery.

◆ O2_FAIL

#define O2_FAIL   (-1)

an error return value: a non-specific error occurred.

In general, any return value < 0 indicates an error. Testing for only O2_FAIL will not detect more specific error return values such as O2_SERVICE_CONFLICT, O2_NO_MEMORY, etc.

◆ O2_LOCAL

#define O2_LOCAL   4

return value for o2_status(): local service with clock sync.

Note that even though the service is local to the process and therefore shares a local clock, clocks are not considered to be synchronized until the local clock is synchronized to the master clock. If this process provides the master clock, it is considered to be synchronized immediately.

◆ O2_LOCAL_NOTIME

#define O2_LOCAL_NOTIME   0

return value for o2_status(): local service, no clock sync yet

This is a local service but clock sync has not yet been established so messages with non-zero timestamps will be dropped.

◆ O2_REMOTE

#define O2_REMOTE   5

return value for o2_status(): remote service with clock sync.

Messages with non-zero timestamps can be sent because clock sync has been established.

◆ O2_REMOTE_NOTIME

#define O2_REMOTE_NOTIME   1

return value for o2_status(): remote service but no clock sync yet

This is a remote service but clock sync has not yet been established so messages with non-zero timestamps will be dropped. The remote service may represent a bridge to a non-IP destination or to an OSC server.

◆ O2_TO_OSC

#define O2_TO_OSC   7

return value for o2_status(): connected with clock sync.

The service forwards messages directly from the current process to an OSC server, and the process is synchronized. The status of the OSC server is not reported by O2 (and in the typical UDP case, there is no way to determine if the OSC server is operational). Non-bundle O2 messages will be scheduled locally and sent according to the timestamp to avoid creating a timestamped bundle, but this will result in some added network latency. O2 bundles will be converted to OSC bundles with timestamps based on Unix gettimeofday() or Windows GetSystemTimeAsFileTime() which are then converted to OSC-compatible NTP timestamps (this is all based on liblo; timestamped message to liblo implementations of OSC will be correctly interpreted). The resulting OSC bundles are sent immediately.

◆ O2_TO_OSC_NOTIME

#define O2_TO_OSC_NOTIME   3

return value for o2_status(): service is connected but no clock sync yet.

The service is local and forwards messages to an OSC server. The status of the OSC server is not reported by O2 (and in the typical UDP case, there is no way to determine if the OSC server is operational, so "connected" may just mean that the service has been defined). Clock sync has not yet been established between the master clock and this process, so messages with non-zero timestamps to this service will be dropped. Note that within other processes, the status for this service will be O2_REMOTE_NOTIME rather than O2_TO_OSC_NOTIME. Note also that O2 does not require the OSC server to have a synchronized clock, so "NOTIME" only means that this process is not synchronized to O2 and therefore cannot (and will not) schedule a timestamped message for timed delivery.