ARINC 661 client API

The Client API allows to create a generic UA application and use it to send Buffers to a CDS. The Client API won't show any Client Interface but will allow to manage the communication with the Server, including receiving Server widget or exception events.

This allows to send Buffers and receive events to the Server programmatically.

For more information on how to use the API, go to j661.sourceforge.net.

API runtime

Overview

You must note that the communication will only be possible after the API has been connected. Also sending commands and requests is done in two phases:

• First the Buffer is populated with commands and requests
• Then the content of the Buffer is sent

For example:

      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_VISIBLE, true);
      api.sendAll();

ARINC 661 keywords

The list of ARINC 661 keywords (widget IDs, widget parameters, widget event IDs, ARINC 661 enum values) for the standard are available with the arinc661.client.api.ARINC661 interface. For example, the value of the A661_POS_X keyword is available by arinc661.client.api.ARINC661.A661_POS_X.

Connect to the Server

      api.connect();

Disconnect to the Server

      api.disconnect();

Set a Request for a Layer

Suppose that we want a layer to be visible. For example:

      api.setLayerRequest(LAYER_ID, ARINC661.A661_REQ_LAYER_VISIBLE, true);

Set values for widgets parameters

The methods to set a value for a widget parameter are:

public class StatefullAPI

The api instance to communicate with the ARINC661 server.

Modifier and Type	Method and Description
void	setWidgetParameter(int appliID, int layerID, int widgetID, int parameterID, Object value) Sets the value of the specified parameter for the specified widget
void	setWidgetParameter(int layerID, int widgetID, int parameterID, Object value) Sets the value of the specified parameter for the specified widget. This method can be used if there is only one layer of the specified ID for all the Server

Suppose that we want a Label to be visible, with specific parameters for this label. For example:

      api.setWidgetParameter(APPLI_ID, LAYER_ID, LABEL_ID_1, ARINC661.A661_POS_X, 5000);
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_VISIBLE, true);
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_STRING, "CANNIBAL CORPSE");
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_STYLE_SET, 12);
      api.sendAll();

Listen to layers or widget events

The methods to listen to a widget event are:

public class StatefullAPI

The api instance to communicate with the ARINC661 server.

Modifier and Type	Method and Description
void	addWidgetEventListener(int appliID, int layerID, arinc661.client.api.ARINCEventListener listener) Listens to any widget event on the specified Layer
void	addWidgetEventListener(int appliID, int layerID, int widgetID, arinc661.client.api.ARINCEventListener listener) Listens to any event on the specified Layer and widget
void	addWidgetEventListener2(int layerID, int widgetID, arinc661.client.api.ARINCEventListener listener) Listens to any event on the specified Layer and widget. This method can be used if there is only one layer of the specified ID for all the Server

Example when listening for a A661_EVT_SELECTION event on a PushButton:

      api.addWidgetEventListener(LAYER_ID, PUSHBUTTON_ID, new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          System.out.println("Button Pressed");
        }
      });

To check the event ID, check the associated event ID. For example, to check if the cursor enters or exits the area of an A661_CURSOR_OVER widget:

      api.addWidgetEventListener(LAYER_ID, CURSOROVER_ID, new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
            System.out.println("Cursor Enter");
          } else if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_EXIT) {
            System.out.println("Cursor Exit");
          }
        });
      });

If the event has associated values, you can retrieve these values with the getFirstValue() or getValues() methods on the WidgetEvent class. For example, to get the PosX and PosY coordinates of the cursor relative to the A661_CURSOR_OVER widget:

      api.addWidgetEventListener(LAYER_ID, CURSOROVER_ID, new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
            long posX = (long)widgetEvt.getValues.get(0);
            long posY = (long)widgetEvt.getValues.get(1);
            System.out.println("Cursor Enter at " + posY + " and " + posY);
          }
        });

Setting the Map reference

To set the A661_MAPHORZ widget reference coordinates^[1]

or widgets#A661_MAPVERT widget reference

, you can:

• Set the A661_MAPHORZ widget PRP coordinates (or the the A661_MAPHORZ widget screen PRP position)
• Set the A661_MAPHORZ widget range (or the the A661_MAPHORZ widget screen Prange)
• Set the A661_MAPHORZ widget orientation relative to true North

Sending a BufferOfMapItems

The API has a helper class which can simplify the sending of BufferOfMapItems to the CDS.

Buffer sending frequency cap

It is possible to cap the frequency of the Buffers sent by the API to a Server (uncapped by default). This can be set by the configuration though the "client.layersUpdateCap" property.

This sets the minimum time in ms between two Buffers sent by the Client API. If this value is greater than 0, Buffers sending will be merged until the update cap has been reached. The default value is -1, meaning that there is not update cap at all for Buffers sending.

The usage of this property is not to bother about the Buffer sending rate by the Client API. For example, one could call call the sendAll() method every 2 ms, but only perform the sending every 40 ms to the Server.

Locking

The StatefullAPI is optionally lockable, to allow for a safe use by more than one Thread. Clients of the API will block until the lock has been released. This can for example manage safely a Use Case when the UA updates widgets parameters regularly (such as temperature values, or a MapHorz content) in a Thread, and change widgets parameters when answering to user events.