Difference between revisions of "OLA Client API"

Revision as of 14:54, 17 February 2009

Note: This refers to the most recent version of LLA [>= 0.3.0]

LLA provides a client library which allows other applications to send/receive DMX as well as control the LLA server. To cater for different application requirements, helper classes as provided which can be used to do most of the client setup / management.

Example I: Sending an DMX update

This first client simply connects to the LLA Server and sends one DMX update. It's about as simple as you can get because it requires no callbacks and exits immediately. We use two classes in this example, lla::SimpleClient, and lla::LlaClient.

#include <lla/SimpleClient.h>
 
int main() {
  // some dummy dmx data
  dmx_t dmx_data[] = {0, 128, 255};

  lla::SimpleClient simple_client;
  if (!simple_client.Setup())
    //setup failed
    return -1;

  // Get the underlying LlaClient
  lla::LlaClient *client = simple_client.GetClient();

  // Send the DMX data 
  client->SendDmx(1, dmx_data, sizeof(dmx_data));
}

The main class used to communicate with the LLA Server is LlaClient. For ease of use, the SimpleClient class sets up LlaClient with a connection to an LLA Server running on the localhost:LLA_DEFAULT_PORT. You can call GetClient() on a SimpleClient instance to get a pointer to the underlying LlaClient.

Example II: Sending multiple updates

The previous example only sent a single DMX update before quitting. This next example adds a timeout which sends DMX every 50ms. This introduces a new class SelectServer which is used for registering timeouts.

#include <lla/SimpleClient.h>

// Maximum value of a dmx channel
static const unsigned int MAX_DMX = 255;
// How often to send updates
static const unsigned int TIMEOUT_MS = 50;

class DmxTimeout: public lla::select_server::TimeoutListener {
  public:
    DmxTimeout(lla::LlaClient *client):
      TimeoutListener(), m_tick(0), m_client(client) {}

    // Called on timeout
    int Timeout() {
      m_dmx_data[0] = MAX_DMX;
      m_dmx_data[1] = m_tick;
      m_dmx_data[2] = MAX_DMX - m_tick;
      m_client->SendDmx(1, m_dmx_data, sizeof(m_dmx_data));
      m_tick++;
      m_tick %= MAX_DMX + 1;
    }
  private:
    unsigned int m_tick;
    dmx_t m_dmx_data[3];
    lla::LlaClient *m_client;
};

int main() {
  lla::SimpleClient simple_client;

  if (!simple_client.Setup())
    return -1;
                                                                                                                                               
  lla::select_server::SelectServer *ss = simple_client.GetSelectServer();
  // Create a timeout and register it
  DmxTimeout timeout(simple_client.GetClient());
  ss->RegisterTimeout(TIMEOUT_MS, &timeout);
  
  // Start the main loop
  ss->Run();
}

In this example we create DmxTimeout class whose Timeout() method is called every time the timer expires. We use the Timeout() method to send DMX data.

The other important part here is the SelectServer. As well as the RegisterTimeout method we've used above, this can also be used to register sockets so we can respond to network activity. The Run() method starts the main event processing loop which will halt if an error occurs or Terminate() is called.

Example III: Receiving DMX data

The third example shows how to listen and respond to event from the LLA server.

#include <lla/SimpleClient.h>

static const unsigned int UNIVERSE = 1;

class OurObserver: public lla::LlaClientObserver {
  public:
    // Called when new DMX values arrive
    void NewDmx(unsigned int universe, unsigned int length,
                dmx_t *data, const std::string &error) {
      printf("received %d channels for universe %d\n",
             length, universe);
    }
};

int main() {
  lla::SimpleClient simple_client;
  OurObserver observer;

  if (!simple_client.Setup())
    return -1;

  lla::LlaClient *client = simple_client.GetClient();
  // Set the observer and register our interest in this universe
  client->SetObserver(&observer);
  client->RegisterUniverse(UNIVERSE, lla::REGISTER);
  simple_client.GetSelectServer()->Run();
}

Here we inherit from the LlaClientObserver class and override the methods we're interested in receiving notification for.

In the main function we set the observer object and register our interest in a universe.

Example IV: More complex client