nRF5 SDK for Mesh v3.2.0  08c60f6
Address management

Functions for managing the set of addresses known to the device. More...

Functions

uint32_t dsm_address_publish_add (uint16_t raw_address, dsm_handle_t *p_address_handle)
 Adds an address to the DSM to be used as a publish address. More...
 
uint32_t dsm_address_publish_add_handle (dsm_handle_t address_handle)
 Adds a publication to an existing address handle. More...
 
uint32_t dsm_address_publish_virtual_add (const uint8_t *p_label_uuid, dsm_handle_t *p_address_handle)
 Adds a virtual address to the DSM to be used as a publish address. More...
 
uint32_t dsm_address_publish_remove (dsm_handle_t address_handle)
 Removes an address that has been used as a publish address. More...
 
uint32_t dsm_local_unicast_addresses_set (const dsm_local_unicast_address_t *p_address)
 Set the unicast addresses of the device. More...
 
void dsm_local_unicast_addresses_get (dsm_local_unicast_address_t *p_address)
 Get the local unicast address range of the device. More...
 
uint32_t dsm_address_subscription_add (uint16_t raw_address, dsm_handle_t *p_address_handle)
 Adds the specified address to the global subscription list. More...
 
uint32_t dsm_address_subscription_virtual_add (const uint8_t *p_label_uuid, dsm_handle_t *p_address_handle)
 Adds the specified virtual address to the global subscription list. More...
 
uint32_t dsm_address_subscription_add_handle (dsm_handle_t address_handle)
 Adds a subscription to an existing address handle. More...
 
_DEPRECATED bool dsm_address_subscription_get (dsm_handle_t address_handle)
 Returns whether the given address_handle is in the global subscription list. More...
 
_DEPRECATED bool dsm_address_is_rx (const nrf_mesh_address_t *p_addr)
 Returns whether the device will process packets received on the given destination address. More...
 
uint32_t dsm_address_subscription_count_get (dsm_handle_t address_handle, uint16_t *p_count)
 Returns the number of subscriptions registered for an address in the global subscription list. More...
 
uint32_t dsm_address_subscription_remove (dsm_handle_t address_handle)
 Removes the given address_handle from the global subscription list. More...
 
uint32_t dsm_address_get (dsm_handle_t address_handle, nrf_mesh_address_t *p_address)
 Retrieves the address for a given address handle and fills out the given nrf_mesh_address_t structure. More...
 
uint32_t dsm_address_get_all (dsm_handle_t *p_address_handle_list, uint32_t *p_count)
 Get a list of all address handles in the address pool. More...
 
uint32_t dsm_address_handle_get (const nrf_mesh_address_t *p_address, dsm_handle_t *p_address_handle)
 Retrieves the address handle for a given nrf_mesh_address_t structure. More...
 

Detailed Description

Functions for managing the set of addresses known to the device.

Function Documentation

◆ dsm_address_publish_add()

uint32_t dsm_address_publish_add ( uint16_t  raw_address,
dsm_handle_t p_address_handle 
)

Adds an address to the DSM to be used as a publish address.

This address can be either a unicast or a group address.

Parameters
[in]raw_addressThe address to add to the device.
[out]p_address_handlePointer to a variable where the handle assigned to this address is stored.
Return values
NRF_SUCCESSThe address was successfully added.
NRF_ERROR_INVALID_PARAMThe address provided was not a unicast or group address.
NRF_ERROR_NULLThe p_address_handle parameter was NULL.

◆ dsm_address_publish_add_handle()

uint32_t dsm_address_publish_add_handle ( dsm_handle_t  address_handle)

Adds a publication to an existing address handle.

Parameters
[in]address_handlehandle of the address.
Return values
NRF_SUCCESSThe publication was successfully added to the address.
NRF_ERROR_NOT_FOUNDThe handle did not point to a previously added address.

◆ dsm_address_publish_virtual_add()

uint32_t dsm_address_publish_virtual_add ( const uint8_t *  p_label_uuid,
dsm_handle_t p_address_handle 
)

Adds a virtual address to the DSM to be used as a publish address.

Parameters
[in]p_label_uuidPointer to the start of the virtual address label UUID.
[out]p_address_handlePointer to a variable where the handle assigned to this address is stored.
Return values
NRF_SUCCESSThe address was successfully added.
NRF_ERROR_NULLThe p_address_handle parameter was NULL.
NRF_ERROR_NO_MEMThe address could not be added due to resource constraints.

◆ dsm_address_publish_remove()

uint32_t dsm_address_publish_remove ( dsm_handle_t  address_handle)

Removes an address that has been used as a publish address.

Parameters
[in]address_handleHandle of the address to remove.
Return values
NRF_SUCCESSThe address was successfully removed.
NRF_ERROR_NOT_FOUNDThe address_handle was not pointing to a valid address.

◆ dsm_local_unicast_addresses_set()

uint32_t dsm_local_unicast_addresses_set ( const dsm_local_unicast_address_t p_address)

Set the unicast addresses of the device.

Note
This function can only be called once for the lifetime of a node, unless the node has been removed from the mesh and needs to be reprovisioned, in that case dsm_clear must be called first.
Parameters
[in]p_addressThe unicast addresses to assign to this device.
Return values
NRF_SUCCESSThe addresses has been successfully assigned.
NRF_ERROR_FORBIDDENThe unicast addresses have been set once before, and the device state must be reset before they can be changed again.
NRF_ERROR_INVALID_DATAThe given address range is invalid or it overlaps with non-unicast type addresses.

◆ dsm_local_unicast_addresses_get()

void dsm_local_unicast_addresses_get ( dsm_local_unicast_address_t p_address)

Get the local unicast address range of the device.

Parameters
[out]p_addressReturns the unicast addresses assigned to this device.

◆ dsm_address_subscription_add()

uint32_t dsm_address_subscription_add ( uint16_t  raw_address,
dsm_handle_t p_address_handle 
)

Adds the specified address to the global subscription list.

This function can only be called for group addresses.

Parameters
[in]raw_addressThe raw 16-bit address to subscribe to.
[out]p_address_handlePointer to a variable where the handle of the address is stored.
Return values
NRF_SUCCESSThe given address has been successfully added to the global subscription list.
NRF_ERROR_INVALID_PARAMThe provided address handle does not represent a group address.
NRF_ERROR_NO_MEMThe rx list for group addresses is full, DSM_SUBS_LIST_MAX.
NRF_ERROR_NOT_FOUNDThe given address handle does not represent a valid address.

◆ dsm_address_subscription_virtual_add()

uint32_t dsm_address_subscription_virtual_add ( const uint8_t *  p_label_uuid,
dsm_handle_t p_address_handle 
)

Adds the specified virtual address to the global subscription list.

Parameters
[in]p_label_uuidPointer to the start of the virtual address label UUID.
[out]p_address_handlePointer to a variable where the handle assigned to this address is stored.
Return values
NRF_SUCCESSThe specified address has been successfully added to the global subscription list.
NRF_ERROR_NO_MEMThe list of RX addresses is full, DSM_SUBS_LIST_MAX.

◆ dsm_address_subscription_add_handle()

uint32_t dsm_address_subscription_add_handle ( dsm_handle_t  address_handle)

Adds a subscription to an existing address handle.

Parameters
[in]address_handlehandle of the address.
Return values
NRF_SUCCESSThe subscription was successfully added to the address.
NRF_ERROR_NOT_FOUNDThe handle did not point to a previously added address.

◆ dsm_address_subscription_get()

_DEPRECATED bool dsm_address_subscription_get ( dsm_handle_t  address_handle)

Returns whether the given address_handle is in the global subscription list.

Parameters
[in]address_handleThe reserved handle of the address.
Returns
Whether the given address handle is present in the global subscription list.

◆ dsm_address_is_rx()

_DEPRECATED bool dsm_address_is_rx ( const nrf_mesh_address_t p_addr)

Returns whether the device will process packets received on the given destination address.

Parameters
[in]p_addrThe raw address to check for.
Returns
Whether the device will process packets received on the given destination address.

◆ dsm_address_subscription_count_get()

uint32_t dsm_address_subscription_count_get ( dsm_handle_t  address_handle,
uint16_t *  p_count 
)

Returns the number of subscriptions registered for an address in the global subscription list.

Parameters
[in]address_handleThe reserved handle of the address.
[out]p_countA pointer to a variable where the subscription count is stored.
Return values
NRF_SUCCESSThe subscription count was successfully returned.
NRF_ERROR_NOT_FOUNDThe address was not found in the address list.
NRF_ERROR_NULLThe p_count parameter was NULL.

◆ dsm_address_subscription_remove()

uint32_t dsm_address_subscription_remove ( dsm_handle_t  address_handle)

Removes the given address_handle from the global subscription list.

This function can only be called for group and virtual addresses. The address will only be removed from the rx list, but it will still be available in the relevant address list. Therefore, after the removal a valid address can still be retreived with the same handle.

Parameters
[in]address_handleThe reserved handle of the address.
Return values
NRF_SUCCESSThe given address has been successfully removed from the rx list.
NRF_ERROR_FORBIDDENUnicast addresses can't be removed from the rx list.
NRF_ERROR_NOT_FOUNDThe given address handle does not exist in the subscription lists.

◆ dsm_address_get()

uint32_t dsm_address_get ( dsm_handle_t  address_handle,
nrf_mesh_address_t p_address 
)

Retrieves the address for a given address handle and fills out the given nrf_mesh_address_t structure.

Parameters
[in]address_handleThe reserved handle of the address.
[in,out]p_addressThe address retrieved via the given address_handle.
Return values
NRF_SUCCESSAn address has been found and returned via the p_address.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_NOT_FOUNDThe given address handle does not exist in the subscription lists.

◆ dsm_address_get_all()

uint32_t dsm_address_get_all ( dsm_handle_t p_address_handle_list,
uint32_t *  p_count 
)

Get a list of all address handles in the address pool.

Parameters
[in,out]p_address_handle_listPointer to the array for storing all the address handles.
[in,out]p_countThe size of the p_address_handle_list array. Will be changed to the number of address handles returned via the p_address_handle_list.
Return values
NRF_SUCCESSThe p_address_handle_list has been successfully populated by all known address handles.
NRF_ERROR_NULLAn unexpected NULL pointer is given.
NRF_ERROR_INVALID_LENGTHThe p_address_handle_list is not large enough to store all address handles, so only a partial list (the first *p_count indices) is returned.

◆ dsm_address_handle_get()

uint32_t dsm_address_handle_get ( const nrf_mesh_address_t p_address,
dsm_handle_t p_address_handle 
)

Retrieves the address handle for a given nrf_mesh_address_t structure.

Parameters
[in]p_addressThe address.
[in,out]p_address_handleThe address handle retrieved via the given p_address.
Return values
NRF_SUCCESSAn address has been found and returned via the p_address.
NRF_ERROR_NULLUnexpected NULL pointer is given.
NRF_ERROR_NOT_FOUNDThe given address handle does not exist in the subscription lists.