embeNET Border Router C API

Table of contents Table of contents

Detailed Description

This page documents the embeNET Border Router C API. The API consists of the following parts:

Border router process control
EMBENET_BR_Init Initializes the border router network process.
EMBENET_BR_Deinit Deinitializes the border router network process.
EMBENET_BR_Proc Advances (runs) the border router network process.
Network management
EMBENET_BR_StartNetwork Starts the network.
EMBENET_BR_StopNetwork Stops the network.
EMBENET_BR_GetOwnUid Gets own UID.
EMBENET_BR_GetNetworkPrefix Gets the network prefix.
Join rules management
EMBENET_BR_AddJoinRule Adds a join rule.
EMBENET_BR_RemoveJoinRule Removes the join rule.
EMBENET_BR_GetJoinRulesCount Gets the number of rules defined.
EMBENET_BR_GetJoinRuleByIndex Gets a rule based on its index.
List of joined devices
EMBENET_BR_GetJoinedNodesCount Gets the number of joined nodes.
EMBENET_BR_GetJoinedNodeUidByIndex Gets the UID of the joined node by its index.
EMBENET_BR_IsNodeJoined Checks if a given node is joined.
List of groups
EMBENET_BR_GetGroupCount Gets the number of groups in the network.
EMBENET_BR_GetGroupIdByIndex Gets the groupId based on the index.
EMBENET_BR_GetGroupCountForNode Gets the number of groups joined by the node.
EMBENET_BR_GetGroupIdForNodeByIndex Gets the groupId of a group joined by the node by the index.

Data Structures

struct  EMBENET_BR_Config
 Stores Border Router configuration needed to start the network. More...
 
struct  EMBENET_BR_JoinRule
 Single rule that governs the constrained join process. More...
 

Function Documentation

◆ EMBENET_BR_Init()

EMBENET_Result EMBENET_BR_Init ( void  )

Initializes the border router network process.

◆ EMBENET_BR_Deinit()

void EMBENET_BR_Deinit ( void  )

Deinitializes the border router network process.

◆ EMBENET_BR_Proc()

void EMBENET_BR_Proc ( void  )

Runs the border router process.

Note
This function MUST be called repeatedly e.g. in loop or as a thread body

◆ EMBENET_BR_StartNetwork()

EMBENET_Result EMBENET_BR_StartNetwork ( EMBENET_BR_Config const *  config,
EMBENET_BR_EventHandlers const *  eventHandlers,
unsigned  timeoutMs 
)

Starts network operation.

Parameters
[in]confignetwork configuration structure (see EMBENET_BR_Config)
[in]eventHandlersan optional set of event handlers that will be called upon specific network-related events
[in]timeoutMsoperation timeout [ms]. When non-zero, the communication check with network interfaces will be performed, thus the function will block for at most timeout ms; otherwise the function is non-blocking
Returns
EMBENET_RESULT_OK if the network was started successfully, or appropriate error status

◆ EMBENET_BR_StopNetwork()

void EMBENET_BR_StopNetwork ( void  )

Stops the network operation User will no longer be able to send and/or receive packets from the network. The list of connected nodes and registered multicast groups will be cleared List of join rules will not be cleared

◆ EMBENET_BR_GetOwnUid()

EMBENET_EUI64 EMBENET_BR_GetOwnUid ( void  )

Returns the UID of the node physically connected to the Border Router.

Returns
UID of this node or invalid value if the associated node is not initialized

◆ EMBENET_BR_GetNetworkPrefix()

EMBENET_NetworkPrefix EMBENET_BR_GetNetworkPrefix ( void  )

Gets the IPv6 Network Prefix (First 8 Bytes)

Returns
Network prefix

◆ EMBENET_BR_AddJoinRule()

EMBENET_Result EMBENET_BR_AddJoinRule ( EMBENET_BR_JoinRule rule)

Adds a constrained join rule, governing the joining process of remote nodes. See EMBENET_BR_JoinRule for more information on how joining rules work.

Parameters
[in]rulepointer to a structure describing the rule to be added. The rule's storage duration may be automatic, as its content will be copied to internal storage
Returns
EMBENET_RESULT_OK if the rule was successfully added
EMBENET_RESULT_JOIN_RULE_REGISTER_FULL when there is no more space to store the rule
EMBENET_RESULT_JOIN_RULE_ALREADY_EXISTS when the rule is already present
EMBENET_RESULT_INVALID_ARGUMENT when nullptr was passed

◆ EMBENET_BR_RemoveJoinRule()

EMBENET_Result EMBENET_BR_RemoveJoinRule ( EMBENET_BR_JoinRule rule)

Removes a constrained join rule from the list of rules. See EMBENET_BR_JoinRule for more information on joining rules.

Parameters
[in]ruleto a structure describing the rule to be removed. The rule's storage duration may be automatic
Returns
EMBENET_RESULT_OK if the rule was successfully removed
EMBENET_RESULT_JOIN_RULE_NOT_FOUND when given rule was not found
EMBENET_RESULT_INVALID_ARGUMENT when nullptr was passed

◆ EMBENET_BR_GetJoinRulesCount()

size_t EMBENET_BR_GetJoinRulesCount ( void  )

Gets the number of constrained join rules currently added to the list of rules. See EMBENET_BR_JoinRule for more information on joining rules.

Returns
number of rules currently on the rule list

◆ EMBENET_BR_GetJoinRuleByIndex()

const EMBENET_BR_JoinRule * EMBENET_BR_GetJoinRuleByIndex ( size_t  index)

Gets the join rule from the list under a given index. See Join rules management for more information on joining rules.

Parameters
[in]indexzero-based rule list index
Returns
pointer to a structure describing the joining rule under given index or NULL if there is no rule under given index

◆ EMBENET_BR_GetJoinedNodesCount()

size_t EMBENET_BR_GetJoinedNodesCount ( void  )

Gets the total number of network nodes (remote devices) joined to this instance of border router.

Returns
number of network nodes joined to this border router

◆ EMBENET_BR_GetJoinedNodeUidByIndex()

EMBENET_EUI64 EMBENET_BR_GetJoinedNodeUidByIndex ( size_t  index)

Gets the descriptor of the joined node by index.

Parameters
[in]indexzero-based

◆ EMBENET_BR_IsNodeJoined()

bool EMBENET_BR_IsNodeJoined ( EMBENET_EUI64  uid)

Checks if the node is joined or not.

Parameters
[in]uidUnique Identifier of node to check
Returns
true when node is connected; false otherwise

◆ EMBENET_BR_GetGroupCount()

size_t EMBENET_BR_GetGroupCount ( void  )

Gets the number of multicast groups currently registered in the network

Returns
number of Multicast groups currently registered in the network

◆ EMBENET_BR_GetGroupIdByIndex()

EMBENET_GroupId EMBENET_BR_GetGroupIdByIndex ( size_t  index)

Gets the Multicast Group Identifier by index Last index shall be computed as EMBENET_BR_GetGroupCount() - 1

Returns
groudId

◆ EMBENET_BR_GetGroupCountForNode()

size_t EMBENET_BR_GetGroupCountForNode ( EMBENET_EUI64  uid)

Returns amount of multicast groups joined by the node with given UID.

Parameters
[in]uidUID of the node to check
Returns
number of joined multicast groups

◆ EMBENET_BR_GetGroupIdForNodeByIndex()

EMBENET_GroupId EMBENET_BR_GetGroupIdForNodeByIndex ( EMBENET_EUI64  uid,
size_t  index 
)

Returns Mutlicast Group ID at given index from UID joined group list The maximum allowed index can be retrieved by calling EMBENET_BR_GetJoinedNodeMulticastGroupCount.

Parameters
[in]uidUID of the node
[in]indexindex of Group ID to get
Returns
GID

Contact us

Any question or remarks? Just write us a message!

Contact Information

Feel free to get in touch