Loading...
Searching...
No Matches
Return Codes

## Macros

#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.

## 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.