Return Codes

Enumerations
enum	O2err {   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 }
	return values used generally by O2 functions More...
enum	O2status {   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 }
	Status return codes for the o2_status function. More...

Detailed Description

Enumeration Type Documentation

O2err

enum O2err

return values used generally by O2 functions

Enumerator
O2_SUCCESS	function was successful
O2_FAIL	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_EXISTS, O2_NO_MEMORY, etc.
O2_SERVICE_EXISTS	not (re)creating service attempt to create or delegate a local service when one exists already
O2_NO_SERVICE	path to handler specifies non-existant service
O2_NO_MEMORY	process is out of free memory
O2_ALREADY_RUNNING	o2_initialize called, but O2 is already running.
O2_BAD_NAME	invalid ensemble name parameter A service name was NULL or contained a slash (/) or was too long (o2_service_new). The path was NULL or did not start with a slash or the service name did not start with a letter (o2_method_new). (Exception: o2_method_new can be called with path "/_o2/si".)
O2_BAD_TYPE	in o2_add_vector, invalid element type
O2_BAD_ARGS	mismatched types and arguments returned by #o2_message_build, o2_send, o2_send_cmd
O2_TCP_HUP	in o2_initialize, the socket is closed.
O2_HOSTNAME_TO_NETADDR_FAIL	inet_pton() failed to convert a string to an IP address
O2_TCP_CONNECT_FAIL	attempt to make a TCP connection failed
O2_NO_CLOCK	timed message but time is unknown Messages with non-zero timestamps are not scheduled or delivered until the current time is not available through the clock synchronization protocol.
O2_NO_HANDLER	no handler for an address
O2_INVALID_MSG	an O2 message is invalid
O2_SEND_FAIL	could not write to socket or send datagram
O2_SOCKET_ERROR	SOCKET_ERROR in select call.
O2_NOT_INITIALIZED	O2 has not been initialized.
O2_BLOCKED	TCP send would block. O2 is holding the message locally to send later
O2_NO_PORT	unable to allocate a discovery port
O2_NO_NETWORK	networking is disabled Either a network connection was not found or no public IP IP address found.

O2status

enum O2status

Status return codes for the o2_status function.

Enumerator
O2_UNKNOWN	status is unknown, e.g. service does not exist
O2_LOCAL_NOTIME	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_NOTIME	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_BRIDGE_NOTIME	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 reference 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_TO_OSC_NOTIME	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 reference 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.
O2_LOCAL	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 reference clock. If this process provides the reference clock, it is considered to be synchronized immediately.
O2_REMOTE	remote service with clock sync. Messages with non-zero timestamps can be sent because clock sync has been established.
O2_BRIDGE	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_TO_OSC	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_TAP	tag value for o2_services_list