aDiscovery.h

group aDiscovery

Link Discovery Interface.

aDiscovery.h provides an interface for locating BrainStem modules accross multiple transports. It provides a way to find all modules for a give transport as well as specific modules by serial number, or first found.

enum linkType

Enum linkType.

The linkType enum specifies the connection transport type.

Values:

enumerator INVALID

  • Undefined link type.

enumerator USB

  • USB link type.

enumerator TCPIP

  • TCPIP link type.

enumerator SERIAL

  • Serial link type.

enumerator AETHER

  • aEther link type.

struct linkSpec

Struct linkSpec.

The linkSpec contains the necessary information for connecting to a BrainStem module.

Module Specifics

linkType type

The transport type of this spec.

uint32_t serial_num

The serial number of the module

uint32_t module

The module address

uint32_t router

The BrainStem network router address

uint32_t router_serial_num

The BrainStem network router serial number

uint32_t model

The model type

Transport Specifics

The transport specifics are contained in a union named t. The union contains either of two structs usb or ip.

The USB struct contains a single element:

  • usb_id - uint32_t the usb_id of the BrainStem module.

The TCP/IP struct contains two elements:

  • ip_address - uint32_t the IP4 address of the module.

  • ip_port - uint32_t the TCP port for socket connection on the module.

The Serial struct contains two elements:

  • buadrate - uint32_t the serial port baudrate

  • port - *char** the serial port path or name

Address this member like spec.t.usb or spec.t.ip

union linkSpec::[anonymous] t

transport union member.

typedef bool bContinueSearch

Typedef bContinueSearch.

Semantic typdef for continuing the search for modules.

typedef bContinueSearch (*aDiscoveryModuleFoundProc)(const linkSpec *spec, bool *bSuccess, void *vpRef)

Typedef aDiscoveryModuleFoundProc.

This procedure is the callback to determine whether modules match the ones we are looking for.

  • spec - linkSpec passed into the continueSearch callback.

  • bSuccess - bool Filled with true if a module was found. false otherwise

  • vpRef - void* A reference to environment, or other element needed within the callback.

  • *bContinueSearch - Return true to continue, false to stop the search.

uint8_t aDiscovery_EnumerateModules(const linkType type, aDiscoveryModuleFoundProc cbFound, void *vpCBRef, const uint32_t networkInterface)

Function aDiscovery_EnumerateModules.

Enumerates the discoverable modules for the given link type. Takes a aDiscoveryModuleFoundProc which will determine when to stop the enumeration.

Parameters:

  • type – The trasport type on which search for devices. Valid linkType “linktypes” are accepted

  • cbFound – The aDiscoveryModuleFoundProc to call for each module found.

  • vpCBRef – The vpRef passed into the callback.

  • networkInterface – Defines the network interface to use when multiple are present. A value of 0 or LOCALHOST_IP_ADDRESS will result in local searches only. Values other than this will have firewall implications.

Returns:

Returns the number of modules found.

linkSpec *aDiscovery_FindModule(const linkType type, const uint32_t serialNum, const uint32_t networkInterface)

Function aDiscovery_FindModule.

Finds the module with the given serial number on the given transport type.

Parameters:

  • type – The trasport type on which search for devices. Valid linkType “linktypes” are accepted

  • serialNum – The serial number of the Module to find.

  • networkInterface – Defines the network interface to use when multiple are present. A value of 0 or LOCALHOST_IP_ADDRESS will result in local searches only. Values other than this will have firewall implications.

Returns:

A pointer to the linkSpec for the requested module if found or NULL otherwise. This call Allocates memory that must be freed by a call to aLinkSpec_Destroy.

linkSpec *aDiscovery_FindFirstModule(const linkType type, const uint32_t networkInterface)

Function aDiscovery_FindFirstModule.

Finds the first module found on the given transport.

Parameters:

  • type – The transport type on which search for devices. Valid linkType “linktypes” are accepted

  • networkInterface – Defines the network interface to use when multiple are present. A value of 0 or LOCALHOST_IP_ADDRESS will result in local searches only. Values other than this will have firewall implications.

Returns:

A pointer to the linkSpec for the requested module if found or NULL otherwise. This call Allocates memory that must be freed by a call to aLinkSpec_Destroy.

LinkSpec Functions

linkSpec *aLinkSpec_Create(const linkType type)

Function aLinkSpec_Create.

Creates a linkSpec object with transport set to the given type.

Parameters:

type – The transport type on which search for devices. Valid linkType “linktypes” are accepted

Returns:

A pointer to the linkSpec for the requested module or NULL if there was an error allocating memory. This call Allocates memory that must be freed by a call to aLinkSpec_Destroy.

aErr aLinkSpec_Destroy(linkSpec **spec)

Function aLinkSpec_Destroy.

Destroys and clears the referenced linkSpec.

Parameters:

spec – A pointer to the linkSpec pointer previously allocated.

Returns:

aErrNone on success or an error if there was an error encountered deallocating the linkSpec.