Client Code Usage

Please note that functions exist to wrap some of the sample code shown on this page into single functions. Check the Documentation page for the exact available API functions and the Test programs for more usage examples.

Including the headers

The "SADB-Client" folder should be copied to the project folder (or placed somewhere that can be found by the compiler) so that the header file may be included. The "SADB-Client" folder can be renamed for convenience. The only file that needs to be directly included is "SADB-Clinet/SADB.h", which includes the other required files.

#include "SADB-C++/SADB.hpp"

Connecting to the server

Connecting to an SADB server simply requires the creation of a Blackboard object and calling the ConnectToServer method with the address of the server.

#include "SADB-C++/SADB.hpp"
int main(void){
 Blackboard Board;
 Board.ConnectToServer("127.0.0.1");
}

Creating an object

The following code snippet demonstrates how an object can be created on the blackboard. The data types currently supported are bytes (BOByte), integers (BOInteger), floats (BOFloat), and double precision floats (BODouble).

 BlackboardObject p1;
 p1.SetBlackboard(&Board); // Associate the object with the Blackboard object
 p1.AddToBlackboard(); // Creates the object on the blackboard and retrieve the OUID
 p1.SetDataType(BOFloat);
 p1.SetDimensionsf(1,2);// 1 dimensional vector, 2 components
 p1.SetName("Ball1 Position");
 p1.SetDescription("Position of the ball 1");
 // Set the initial value of the object
 p1.SetTimestampNow(); // Current time
 p1.SetFloat(1.5, 0); // First component
 p1.SetFloat(2.83, 1); // Second component
 p1.Send(); // Send the value to the server

Creating a Category

Creating categories is a fairly straight-forward task, it requires 3 lines of code:

 SADBu64 Position=Board.CreateCategory();
 Board.SetCategoryName(Position,"Position");
 Board.SetCategoryDescription(Position,"Contains position vectors in the form p=(x,y)");

The SADBu64 is the ID of the category on the server.

Managing Categories

Objects can be added to categories by referencing the category by name.

p1.AddToCategory("Position"); // Add the object tot the category

The BlackboardObject class in version 0.32 does not contain a convenience method to remove an object from a category (will be included in the next version). For now, to remove an object from a category, the code is the following: (Position is the SADBu64 ID of the category)

Board.RemoveObjectFromCategory(Position,p1.ID);

Retrieving an object

Objects can be retrieved in different ways. The simplest, if the exact name of the object is know, is by to request the object by name.

 BlackboardObject p1;
 p1.SetBlackboard(&SADB);
 p1.GetByName("Ball1 Position");

If multiple objects with the same name have been created (which is allowed), the object with the smallest ID will be returned. A more elegant way of finding object is by set operations. This requires the objects on the SADB server to be properly classified into descriptive categories.

 SADBu64*List=NULL; // Will store the list of IDs matching the request
 SADBu8*Name=NULL; // Used to store the name of an object
 int n; // Number of objects that match the query
 n=Board.FindObjects("intersection(Ball1,Position)",&List);
 printf("Found %d object(s):\n",n);
 for(int i=0;i<n;i++){
  Board.GetObjectName(List[i],&Name);
  printf("  %08x - %s\n",List[i],Name); // Prints the ID and the name of the object
  free(Name);
 }

Getting the value of an object

The BlackboardObject class presents three main methods of getting an object value:

 void GetLatestValue(void);
 void GetValueAtNearestTimestamp(Timestamp Time);
 void GetValueAtTimestamp(Timestamp Time);

TIP: Creating a new object only if it does not exist

The following code snippet can be used to get the current value of an object or create the object if it does not already exist.

 BlackboardObject CameraPosition;
 CameraPosition.SetBlackboard(&SADB);
 CameraPosition.GetByName("Camera Position");//Get the ID of the camera position from SADB
 if(CameraPosition.ID==0){//Object does not exist yet
  CameraPosition.SetDataType(BOFloat);
  CameraPosition.SetName("Camera Position");
  CameraPosition.SetDescription("Position of the Camera");
  CameraPosition.SetDimensionsf(1,3);//# element vector (x,y,z)
  CameraPosition.SetTimestampNow();//Initial value
  CameraPosition.SetFloat(0,0); // Some default value
  CameraPosition.SetFloat(0,1);
  CameraPosition.SetFloat(-40,2);
  CameraPosition.AddToBlackboard();//Create object on the blackboard
  CameraPosition.Send();//Send initial value to the blackboard
 }else{//if the object exists, get its current value
  CameraPosition.GetLatestValue();
 }