Extensions

Service Query

A client should be able to find out what services are available:

int o2_service_count(); // return the number of services
int o2_get_services(int maxlen, char **services); // copy service names into services

A count is returned from o2_get_services. The strings copied to services must be eventually freed with O2_FREE() as they are copied to the heap. (Services might disappear and be deallocated, which is why o2_get_services() has to make copies.)

Service Properties

A client should be able to add attribute/value properties to services:

int o2_service_property_set(const char *service, const char *attribute, const char *value);

The service property is transmitted to all other o2 processes, and can be queried by clients:

char *o2_service_property_get(const char *service, char *attribute);

Gets a property from a service. If the service or its property do not exist, NULL is returned. If a string is returned, it must be freed eventually with O2_FREE().

Queries

O2 messages should allow one to query properties of other services and processes. In the following, /process refer to a process, typically named with the IP address and port number, e.g. /192.0.5.40:45678. However, the local process can be addressed using /_o2. Also, reply-to refers to a path to which replies should be sent, e.g. if /rbd/services is the reply-to parameter to /_o2/services, then the known service names will be returned to service rbd using path /rbd/services.

/service/getproc reply-to     -- send the process name (also a service) to reply-to
                                 (a path)
/process/getrtt reply-to      -- send the clock-sync round trip time for this process
                                 to reply-to (a path)
/process/getsrvcnt reply-to   -- send count of known services to reply-to (a path)
/process/getservices reply-to -- send known services to reply-to (a path). The message 
                                 parameters are the service names known to the local process.
/process/getprop service-name attribute reply-to -- send the value of the `attribute` 
                                 property for service `service` to path `reply-to` 
                                 (all parameters are strings).

One possibility is to connect to O2 with OSC and send OSC messages to query O2. That would allow you to run an "O2 connector" process that offers no special services, it just acts as a gateway between a local process running OSC and a network of other O2 processes. (Inspired by LANdini, which is only "gateway" server processes and is used only by OSC clients. To start interacting with O2, an OSC process needs to know it's O2 service name. Knowing the service name allows OSC to construct an O2 reply-to path that will direct messages to the OSC client.

/_o2 -- OSC messages are directed to a service *unless* the OSC path begins with "/_o2", 
        in which case the message is delivered as is, to the _o2 service, which is the
        local process. See messages above for information that can be queried. In addition:
/_o2/getoscsrv ip port reply-to -- send an OSC message to the OSC server addressed by ip
        (a string) and port (an int32), with the path given by reply-to (a string). The
        message is a single string with the service name that corresponds to the OSC
        port. If o2_osc_delegate() has not been called to map a service to an OSC server,
        no reply is sent. When the reply is sent, the string in the reply provides a
        service name that can be used to get replies to other queries. E.g. if the service
        name for this OSC server is "osc", then the OSC server can get a list of all
        O2 services by sending `/_o2/getservices /osc/setservices`, where `/osc/setservices`
        is a string parameter (the reply-to parameter) of the message.