Chapter 3. Receiving

Table of Contents

Tags and callbacks
A few examples

Tags and callbacks

Most of the messages received from the URBI server are the results of a previously sent command. The mechanism of URBI tags enables to link a message to its reply: with each command is associated a tag, and this tag is repeated in the reply message. The liburbi.main.UClient class handles the reception of those messages in the independant thread created by the constructor, parses them and fills a UMessage structure.

In your Java program, you can have classes extending liburbi.main.UCallbackInterface and redefining its method onMessage. You can the register these classes with the UClient method setCallback and associate them with a tag. Then each time a message with this tag is sent by the server, the redefined onMessage function will be called with a liburbi.main.UMessage class as a parameter.

The liburbi.main.UCallbackInterface class is defined as follow:

package liburbi.main;

public class UCallbackInterface {
  public UCallbackAction onMessage(UMessage msg);

The onMessage function take as parameter a liburbi.main.UMessage and return an enum: liburbi.main.UCallbackAction which can have two values: liburbi.main.UCallbackAction.URBI_CONTINUE or liburbi.main.UCallbackAction.URBI_REMOVE (in which case the callback is removed, and wont be called anymore, even if you receive a message with the same tag).

The setCallback function is defined as follow:

package liburbi.main;

public class UClient {

  public long setCallback(UCallbackInterface ref, String tag);

Give as first parameter your class redefining liburbi.main.UCallbackInterface, and give as second argument a String corresponding to the tag you want to associated the callback with.