Binding Table
EmberZNet Stack API Reference

EmberZNet binding table API.

Functions

EmberStatus emberSetBinding (uint8_t index, EmberBindingTableEntry *value)
Sets an entry in the binding table by copying the structure pointed to by value into the binding table.
EmberStatus emberGetBinding (uint8_t index, EmberBindingTableEntry *result)
Copies a binding table entry to the structure that the result points to.
EmberStatus emberDeleteBinding (uint8_t index)
Deletes a binding table entry.
bool emberBindingIsActive (uint8_t index)
Indicates whether any messages are currently being sent using this binding table entry.
EmberNodeId emberGetBindingRemoteNodeId (uint8_t index)
Returns the node ID for the binding's destination if the ID is known.
void emberSetBindingRemoteNodeId (uint8_t index, EmberNodeId id)
Sets the node ID for the binding's destination. See emberGetBindingRemoteNodeId() for a description.
EmberStatus emberClearBindingTable (void)
Deletes all binding table entries.
EmberZdoStatus emberRemoteSetBindingHandler ( EmberBindingTableEntry *entry)
A callback invoked when a remote node requests that a binding be added to the local binding table (via the ZigBee Device Object at endpoint 0).
EmberZdoStatus emberRemoteDeleteBindingHandler (uint8_t index)
A callback invoked when a remote node requests that a binding be removed from the local binding table (via the ZigBee Device Object at endpoint 0).
uint8_t emberGetBindingIndex (void)
Returns a binding index that matches the current incoming message, if known.
EmberStatus emberSetReplyBinding (uint8_t index, EmberBindingTableEntry *entry)
Creates a binding table entry for the sender of a message, which can be used to send messages to that sender.
EmberStatus emberNoteSendersBinding (uint8_t index)
Updates the routing information associated with a binding table entry for the sender of a message.

Detailed Description

EmberZNet binding table API.

See binding-table.h for source code.

Function Documentation

◆ emberBindingIsActive()

bool emberBindingIsActive ( uint8_t index )

Indicates whether any messages are currently being sent using this binding table entry.

Note that this function does not indicate whether a binding is clear. To determine whether a binding is clear, check the EmberBindingTableEntry structure that defines the binding. The type field should have the value EMBER_UNUSED_BINDING .

Parameters
index The index of a binding table entry.
Returns
True if the binding table entry is active, false otherwise.

◆ emberClearBindingTable()

EmberStatus emberClearBindingTable ( void )

Deletes all binding table entries.

Returns
An EmberStatus value that indicates the success or failure of the command.

◆ emberDeleteBinding()

EmberStatus emberDeleteBinding ( uint8_t index )

Deletes a binding table entry.

Parameters
index The index of a binding table entry.
Returns
An EmberStatus value that indicates the success or failure of the command.

◆ emberGetBinding()

EmberStatus emberGetBinding ( uint8_t index,
EmberBindingTableEntry * result
)

Copies a binding table entry to the structure that the result points to.

Parameters
index The index of a binding table entry.
result A pointer to the location to which to copy the binding table entry.
Returns
An EmberStatus value that indicates the success or failure of the command.

◆ emberGetBindingIndex()

uint8_t emberGetBindingIndex ( void )

Returns a binding index that matches the current incoming message, if known.

A binding matches the incoming message if:

  • The binding's source endpoint is the same as the message's destination endpoint.
  • The binding's destination endpoint is the same as the message's source endpoint.
  • The source of the message has been previously identified as the the binding's remote node by a successful address discovery or by the application via a call to either emberSetReplyBinding() or emberNoteSendersBinding() .
Note
This function can be called only from within emberIncomingMessageHandler() .
Returns
The index of a binding that matches the current incoming message or 0xFF if there is no matching binding.

◆ emberGetBindingRemoteNodeId()

EmberNodeId emberGetBindingRemoteNodeId ( uint8_t index )

Returns the node ID for the binding's destination if the ID is known.

If a message is sent using the binding and the destination's ID is not known, the stack will discover the ID by broadcasting a ZDO address request. The application can avoid the need for this discovery by calling emberNoteSendersBinding() whenever a message arrives from the binding's destination, or by calling emberSetBindingRemoteNodeId() when it knows the correct ID via some other means, such as having saved it in nonvolatile memory.

The destination's node ID is forgotten when the binding is changed, when the local node reboots or, much more rarely, when the destination node changes its ID in response to an ID conflict.

Parameters
index The index of a binding table entry.
Returns
The short ID of the destination node or EMBER_NULL_NODE_ID if no destination is known.

◆ emberNoteSendersBinding()

EmberStatus emberNoteSendersBinding ( uint8_t index )

Updates the routing information associated with a binding table entry for the sender of a message.

This function should be used in place of emberSetReplyBinding() when a message arrives from a remote endpoint for which a binding already exists.

Parameters
index The index of the binding to update.
Returns
An EmberStatus value that indicates the success or failure of the command.

◆ emberRemoteDeleteBindingHandler()

EmberZdoStatus emberRemoteDeleteBindingHandler ( uint8_t index )

A callback invoked when a remote node requests that a binding be removed from the local binding table (via the ZigBee Device Object at endpoint 0).

The application is free to remove the binding from the binding table, ignore the request, or take some other action.

If the application includes emberRemoteDeleteBindingHandler() , it must define EMBER_APPLICATION_HAS_REMOTE_BINDING_HANDLER in its CONFIGURATION_HEADER and also include emberRemoteSetBindingHandler() .

Parameters
index The index of the binding entry to be removed.
Returns
EMBER_ZDP_SUCCESS if the binding was removed from the table EMBER_ZDP_NOT_AUTHORIZED if permission was denied EMBER_ZDP_NOT_PERMITTED if the binding is active EMBER_ZDP_NO_ENTRY if the binding doesn't exist

◆ emberRemoteSetBindingHandler()

EmberZdoStatus emberRemoteSetBindingHandler ( EmberBindingTableEntry * entry )

A callback invoked when a remote node requests that a binding be added to the local binding table (via the ZigBee Device Object at endpoint 0).

The application is free to add the binding to the binding table, ignore the request, or take some other action. It is recommended that nonvolatile bindings be used for remote provisioning applications.

The binding's type defaults to EMBER_UNICAST_BINDING . The application should set the type as appropriate for the binding's local endpoint and cluster ID.

If the application includes emberRemoteSetBindingHandler() , it must define EMBER_APPLICATION_HAS_REMOTE_BINDING_HANDLER in its CONFIGURATION_HEADER and also include emberRemoteDeleteBindingHandler() .

Parameters
entry A pointer to a new binding table entry.
Returns
EMBER_ZDP_SUCCESS if the binding was added to the table EMBER_ZDP_NOT_AUTHORIZED if permission was denied EMBER_ZDP_NOT_PERMITTED if the binding is active EMBER_ZDP_TABLE_FULL if there is no more space in the binding table

◆ emberSetBinding()

EmberStatus emberSetBinding ( uint8_t index,
EmberBindingTableEntry * value
)

Sets an entry in the binding table by copying the structure pointed to by value into the binding table.

Note
You do not need to reserve memory for value .
Parameters
index The index of a binding table entry.
value A pointer to a structure.
Returns
An EmberStatus value that indicates the success or failure of the command.

◆ emberSetBindingRemoteNodeId()

void emberSetBindingRemoteNodeId ( uint8_t index,
EmberNodeId id
)

Sets the node ID for the binding's destination. See emberGetBindingRemoteNodeId() for a description.

Parameters
index The index of a binding table entry.
id The ID of the binding's destination.

◆ emberSetReplyBinding()

EmberStatus emberSetReplyBinding ( uint8_t index,
EmberBindingTableEntry * entry
)

Creates a binding table entry for the sender of a message, which can be used to send messages to that sender.

This function is identical to emberSetBinding() except that calling it tells the stack that this binding corresponds to the sender of the current message. The stack uses this information to associate the sender's routing info with the binding table entry.

Note
This function may only be called from within emberIncomingMessageHandler() .
Parameters
index The index of the binding to set.
entry A pointer to data for the binding.
Returns
An EmberStatus value that indicates the success or failure of the command.