Table of Contents

libIntegra static methods

libIntegra implements an OSC server, which handles communication between client software and Integra modules. Individual module address spaces are generated dynamically on the server at runtime. For example if a module has the attributes 'profile' and 'ambience', then these attributes will be addressable using the following generated address space: 

/foo.1/profile
/foo.1/ambience

However, the server also implements a number of 'static methods' that correspond to the server's API for loading, connecting, removing modules and querying both individual modules and the server for information.

Static Methods

Message Description Reply
/load <module class name> Load a module instance /loaded <module name> <instance count> <module id>
/remove <module id> Remove a module instance by id /removed <module id>
/connect <module id> <port id> <module id> <port id> Connect two modules giving source and target /connected <module id> <port id> <module id> <port id>
/disconnect <module id> <port id> <module id> <port id> Disconnect two modules giving source and target /disconnected <module id> <port id> <module id> <port id>
/send <module id> <port id> <value> Send a value to a given port None
/nodelist <node address> recursively list the sub-nodes under a given node /<node address>/<sub-node address>
/<node address>/<sub-node address>
…
/info <attribute OSC address> Get information about a module by attribute /<class name>/<attribute name>/minimum <value>
/<class name>/<attribute name>/maximum <value>
/<class name>/<attribute name>/default <value>
/<class name>/<attribute name>/unit <value>
/<class name>/<attribute name>/type <value>
/<class name>/<attribute name>/description <value>
/<class name>/<attribute name>/documentation <value>
/post <text> Post some text via the environment's output mechanism if it has one None
/register <ip address> <port> Register for replies from the server /registered <ip address> <port>

Getters and setters

In addition to these methods all generated module address support an implicit set/get mechanism where an address followed zero arguments is interpret as a 'get' request. Example: 

/filter.1/frequency 440   <- set filter frequency to 440
/filter.1/frequency           <- implicit get
-> /filter.1/frequency 440    <- reply to registered client

Since Integra implements OAV-style semantics, non-get messages must always have 1 or more arguments. It is therefore a moot point whether the address in question represents a method call with arguments or a variable assignment 

/player.1/play 1             <- a method call (We don't care!)
/player.1/title 'Foo'        <- a variable assignment

Addresses that expose methods respond in exactly the same way to implicit get. 

/player.1/play     <- implicit get
-> /player.1/play 1      <-reply to registered client

See here for further details on the Integra protocol and the implementation of OAV.

'oscplanet' support

There is currently a new protocol under development, arising out of discussions on the osc-dev mailing list including contributions from the rubyk, LiVES and Integra developers. The purpose of the protocol to provide a layer on top of OSC that can be used for automated discovery of a server's address space and 'meta data' using a standardised query interface. The proposal is under development, but so far there seems to be some consensus that the addresses used in the protocol should live at the root of the server's address space and be prefixed with a period '.' to identify them as 'meta methods'. So far we have:

New-style meta-address Integra equivalent
/.reply_to /register
/.info /info (Currently in Integra /info returns a series of messages to the registered client, whereas '/.info' in oscplanet returns a string representation
/.type None (Integra provides type information in response to the /info query. However this is currently the 'Integra type' of the data not the OSC type-tag type. Perhaps /.type could be used in Integra to return the type-tag codes as a string?)
/.nodelist /nodelist
/.reply <message> <message> ( I.e. in Integra replies from the server are currently implicitly identified)

Other differences

planetosc replies to message setters as well as implicit get. Example 

/midiout/channel 4.5       <- try to set channel to 4.5

→ /.reply ”/midiout/channel” 4

This is saying “could you please set the /midiout/channel to value 4.5 ?” and the answer is “I could only set it to 4”

Note: I'm not sure about supporting this in Integra. Do all set requests get a reply, or only setters that result in an 'error', in a data stream with a lot of values, how do we identify which replies correspond to which set requests?

Conclusion

Future versions of libIntegra will support the new protocol, which is likely to replace the existing static methods as appropriate.


Personal Tools