LCOV - code coverage report
Current view: top level - zephyr/bluetooth/mesh - cfg.h Hit Total Coverage
Test: new.info Lines: 39 62 62.9 %
Date: 2024-12-21 18:13:37

          Line data    Source code
       1           1 : /** @file
       2             :  *  @brief Runtime configuration APIs.
       3             :  */
       4             : 
       5             : /*
       6             :  * Copyright (c) 2020 Nordic Semiconductor
       7             :  *
       8             :  * SPDX-License-Identifier: Apache-2.0
       9             :  */
      10             : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_
      11             : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_
      12             : 
      13             : #include <stdbool.h>
      14             : #include <stddef.h>
      15             : 
      16             : #include <sys/types.h>
      17             : 
      18             : /**
      19             :  * @brief Runtime Configuration
      20             :  * @defgroup bt_mesh_cfg Runtime Configuration
      21             :  * @ingroup bt_mesh
      22             :  * @{
      23             :  */
      24             : 
      25             : #ifdef __cplusplus
      26             : extern "C" {
      27             : #endif
      28             : 
      29             : /** Bluetooth Mesh feature states */
      30           1 : enum bt_mesh_feat_state {
      31             :         /** Feature is supported, but disabled. */
      32             :         BT_MESH_FEATURE_DISABLED,
      33             :         /** Feature is supported and enabled. */
      34             :         BT_MESH_FEATURE_ENABLED,
      35             :         /** Feature is not supported, and cannot be enabled. */
      36             :         BT_MESH_FEATURE_NOT_SUPPORTED,
      37             : };
      38             : 
      39             : /* Key Refresh Phase */
      40           0 : #define BT_MESH_KR_NORMAL                   0x00
      41           0 : #define BT_MESH_KR_PHASE_1                  0x01
      42           0 : #define BT_MESH_KR_PHASE_2                  0x02
      43           0 : #define BT_MESH_KR_PHASE_3                  0x03
      44             : 
      45             : /* Legacy feature defines */
      46           0 : #define BT_MESH_RELAY_DISABLED              BT_MESH_FEATURE_DISABLED
      47           0 : #define BT_MESH_RELAY_ENABLED               BT_MESH_FEATURE_ENABLED
      48           0 : #define BT_MESH_RELAY_NOT_SUPPORTED         BT_MESH_FEATURE_NOT_SUPPORTED
      49             : 
      50           0 : #define BT_MESH_BEACON_DISABLED             BT_MESH_FEATURE_DISABLED
      51           0 : #define BT_MESH_BEACON_ENABLED              BT_MESH_FEATURE_ENABLED
      52             : 
      53           0 : #define BT_MESH_PRIV_BEACON_DISABLED        BT_MESH_FEATURE_DISABLED
      54           0 : #define BT_MESH_PRIV_BEACON_ENABLED         BT_MESH_FEATURE_ENABLED
      55             : 
      56           0 : #define BT_MESH_GATT_PROXY_DISABLED         BT_MESH_FEATURE_DISABLED
      57           0 : #define BT_MESH_GATT_PROXY_ENABLED          BT_MESH_FEATURE_ENABLED
      58           0 : #define BT_MESH_GATT_PROXY_NOT_SUPPORTED    BT_MESH_FEATURE_NOT_SUPPORTED
      59             : 
      60           0 : #define BT_MESH_PRIV_GATT_PROXY_DISABLED      BT_MESH_FEATURE_DISABLED
      61           0 : #define BT_MESH_PRIV_GATT_PROXY_ENABLED       BT_MESH_FEATURE_ENABLED
      62           0 : #define BT_MESH_PRIV_GATT_PROXY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
      63             : 
      64           0 : #define BT_MESH_FRIEND_DISABLED             BT_MESH_FEATURE_DISABLED
      65           0 : #define BT_MESH_FRIEND_ENABLED              BT_MESH_FEATURE_ENABLED
      66           0 : #define BT_MESH_FRIEND_NOT_SUPPORTED        BT_MESH_FEATURE_NOT_SUPPORTED
      67             : 
      68           0 : #define BT_MESH_NODE_IDENTITY_STOPPED       BT_MESH_FEATURE_DISABLED
      69           0 : #define BT_MESH_NODE_IDENTITY_RUNNING       BT_MESH_FEATURE_ENABLED
      70           0 : #define BT_MESH_NODE_IDENTITY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
      71             : 
      72             : /** @brief Enable or disable sending of the Secure Network Beacon.
      73             :  *
      74             :  *  @param beacon New Secure Network Beacon state.
      75             :  */
      76           1 : void bt_mesh_beacon_set(bool beacon);
      77             : 
      78             : /** @brief Get the current Secure Network Beacon state.
      79             :  *
      80             :  *  @returns Whether the Secure Network Beacon feature is enabled.
      81             :  */
      82           1 : bool bt_mesh_beacon_enabled(void);
      83             : 
      84             : /** @brief Enable or disable sending of the Mesh Private beacon.
      85             :  *
      86             :  *  Support for the Private beacon state must be enabled with @c
      87             :  *  CONFIG_BT_MESH_PRIV_BEACONS.
      88             :  *
      89             :  *  @param priv_beacon New Mesh Private beacon state. Must be one of
      90             :  *                     @ref BT_MESH_FEATURE_ENABLED and
      91             :  *                     @ref BT_MESH_FEATURE_DISABLED.
      92             :  *
      93             :  *  @retval 0         Successfully changed the Mesh Private beacon feature state.
      94             :  *  @retval -ENOTSUP  The Mesh Private beacon feature is not supported.
      95             :  *  @retval -EINVAL   Invalid parameter.
      96             :  *  @retval -EALREADY Already in the given state.
      97             :  */
      98           1 : int bt_mesh_priv_beacon_set(enum bt_mesh_feat_state priv_beacon);
      99             : 
     100             : /** @brief Get the current Mesh Private beacon state.
     101             :  *
     102             :  *  @returns The Mesh Private beacon feature state.
     103             :  */
     104           1 : enum bt_mesh_feat_state bt_mesh_priv_beacon_get(void);
     105             : 
     106             : /** @brief Set the current Mesh Private beacon update interval.
     107             :  *
     108             :  *  The Mesh Private beacon's randomization value is updated regularly to
     109             :  *  maintain the node's privacy. The update interval controls how often
     110             :  *  the beacon is updated, in 10 second increments.
     111             :  *
     112             :  * @param interval Private beacon update interval in 10 second steps, or 0 to
     113             :  *        update on every beacon transmission.
     114             :  */
     115           1 : void bt_mesh_priv_beacon_update_interval_set(uint8_t interval);
     116             : 
     117             : /** @brief Get the current Mesh Private beacon update interval.
     118             :  *
     119             :  *  The Mesh Private beacon's randomization value is updated regularly to
     120             :  *  maintain the node's privacy. The update interval controls how often
     121             :  *  the beacon is updated, in 10 second increments.
     122             :  *
     123             :  * @returns The Private beacon update interval in 10 second steps, or 0 if
     124             :  *          the beacon is updated every time it's transmitted.
     125             :  */
     126           1 : uint8_t bt_mesh_priv_beacon_update_interval_get(void);
     127             : 
     128             : /** @brief Set the default TTL value.
     129             :  *
     130             :  *  The default TTL value is used when no explicit TTL value is set. Models will
     131             :  *  use the default TTL value when @ref bt_mesh_msg_ctx::send_ttl is
     132             :  *  @ref BT_MESH_TTL_DEFAULT.
     133             :  *
     134             :  *  @param default_ttl The new default TTL value. Valid values are 0x00 and 0x02
     135             :  *                     to @ref BT_MESH_TTL_MAX.
     136             :  *
     137             :  *  @retval 0       Successfully set the default TTL value.
     138             :  *  @retval -EINVAL Invalid TTL value.
     139             :  */
     140           1 : int bt_mesh_default_ttl_set(uint8_t default_ttl);
     141             : 
     142             : /** @brief Get the current default TTL value.
     143             :  *
     144             :  *  @return The current default TTL value.
     145             :  */
     146           1 : uint8_t bt_mesh_default_ttl_get(void);
     147             : 
     148             : /** @brief Get the current Mesh On-Demand Private Proxy state.
     149             :  *
     150             :  *  @retval 0 or positive value  represents On-Demand Private Proxy feature state
     151             :  *  @retval -ENOTSUP  The On-Demand Private Proxy feature is not supported.
     152             :  */
     153           1 : int bt_mesh_od_priv_proxy_get(void);
     154             : 
     155             : /** @brief Set state of Mesh On-Demand Private Proxy.
     156             :  *
     157             :  *  Support for the On-Demand Private Proxy state must be enabled with @c
     158             :  *  BT_MESH_OD_PRIV_PROXY_SRV.
     159             :  *
     160             :  *  @param on_demand_proxy New Mesh On-Demand Private Proxy state. Value of 0x00 means that
     161             :  *                         advertising with Private Network Identity cannot be enabled on demand.
     162             :  *                         Values in range 0x01 - 0xFF set interval of this advertising after
     163             :  *                         valid Solicitation PDU is received or client disconnects.
     164             :  *
     165             :  *  @retval 0         Successfully changed the Mesh On-Demand Private Proxy feature state.
     166             :  *  @retval -ENOTSUP  The On-Demand Private Proxy feature is not supported.
     167             :  *  @retval -EINVAL   Invalid parameter.
     168             :  *  @retval -EALREADY Already in the given state.
     169             :  */
     170           1 : int bt_mesh_od_priv_proxy_set(uint8_t on_demand_proxy);
     171             : 
     172             : /** @brief Set the Network Transmit parameters.
     173             :  *
     174             :  *  The Network Transmit parameters determine the parameters local messages are
     175             :  *  transmitted with.
     176             :  *
     177             :  *  @see BT_MESH_TRANSMIT
     178             :  *
     179             :  *  @param xmit New Network Transmit parameters. Use @ref BT_MESH_TRANSMIT for
     180             :  *              encoding.
     181             :  */
     182           1 : void bt_mesh_net_transmit_set(uint8_t xmit);
     183             : 
     184             : /** @brief Get the current Network Transmit parameters.
     185             :  *
     186             :  *  The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be
     187             :  *  used to decode the Network Transmit parameters.
     188             :  *
     189             :  *  @return The current Network Transmit parameters.
     190             :  */
     191           1 : uint8_t bt_mesh_net_transmit_get(void);
     192             : 
     193             : /** @brief Configure the Relay feature.
     194             :  *
     195             :  *  Enable or disable the Relay feature, and configure the parameters to
     196             :  *  transmit relayed messages with.
     197             :  *
     198             :  *  Support for the Relay feature must be enabled through the
     199             :  *  @c CONFIG_BT_MESH_RELAY configuration option.
     200             :  *
     201             :  *  @see BT_MESH_TRANSMIT
     202             :  *
     203             :  *  @param relay New Relay feature state. Must be one of
     204             :  *               @ref BT_MESH_FEATURE_ENABLED and
     205             :  *               @ref BT_MESH_FEATURE_DISABLED.
     206             :  *  @param xmit  New Relay retransmit parameters. Use @ref BT_MESH_TRANSMIT for
     207             :  *               encoding.
     208             :  *
     209             :  *  @retval 0         Successfully changed the Relay configuration.
     210             :  *  @retval -ENOTSUP  The Relay feature is not supported.
     211             :  *  @retval -EINVAL   Invalid parameter.
     212             :  *  @retval -EALREADY Already using the given parameters.
     213             :  */
     214           1 : int bt_mesh_relay_set(enum bt_mesh_feat_state relay, uint8_t xmit);
     215             : 
     216             : /** @brief Get the current Relay feature state.
     217             :  *
     218             :  *  @returns The Relay feature state.
     219             :  */
     220           1 : enum bt_mesh_feat_state bt_mesh_relay_get(void);
     221             : 
     222             : /** @brief Get the current Relay Retransmit parameters.
     223             :  *
     224             :  *  The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be
     225             :  *  used to decode the Relay Retransmit parameters.
     226             :  *
     227             :  *  @return The current Relay Retransmit parameters, or 0 if relay is not
     228             :  *          supported.
     229             :  */
     230           1 : uint8_t bt_mesh_relay_retransmit_get(void);
     231             : 
     232             : /** @brief Enable or disable the GATT Proxy feature.
     233             :  *
     234             :  *  Support for the GATT Proxy feature must be enabled through the
     235             :  *  @c CONFIG_BT_MESH_GATT_PROXY configuration option.
     236             :  *
     237             :  *  @note The GATT Proxy feature only controls a Proxy node's ability to relay
     238             :  *        messages to the mesh network. A node that supports GATT Proxy will
     239             :  *        still advertise Connectable Proxy beacons, even if the feature is
     240             :  *        disabled. The Proxy feature can only be fully disabled through compile
     241             :  *        time configuration.
     242             :  *
     243             :  *  @param gatt_proxy New GATT Proxy state. Must be one of
     244             :  *                    @ref BT_MESH_FEATURE_ENABLED and
     245             :  *                    @ref BT_MESH_FEATURE_DISABLED.
     246             :  *
     247             :  *  @retval 0         Successfully changed the GATT Proxy feature state.
     248             :  *  @retval -ENOTSUP  The GATT Proxy feature is not supported.
     249             :  *  @retval -EINVAL   Invalid parameter.
     250             :  *  @retval -EALREADY Already in the given state.
     251             :  */
     252           1 : int bt_mesh_gatt_proxy_set(enum bt_mesh_feat_state gatt_proxy);
     253             : 
     254             : /** @brief Get the current GATT Proxy state.
     255             :  *
     256             :  *  @returns The GATT Proxy feature state.
     257             :  */
     258           1 : enum bt_mesh_feat_state bt_mesh_gatt_proxy_get(void);
     259             : 
     260             : /** @brief Enable or disable the Private GATT Proxy feature.
     261             :  *
     262             :  *  Support for the Private GATT Proxy feature must be enabled through the
     263             :  *  @kconfig{CONFIG_BT_MESH_PRIV_BEACONS} and @kconfig{CONFIG_BT_MESH_GATT_PROXY}
     264             :  *  configuration options.
     265             :  *
     266             :  *  @param priv_gatt_proxy New Private GATT Proxy state. Must be one of
     267             :  *                         @ref BT_MESH_FEATURE_ENABLED and
     268             :  *                         @ref BT_MESH_FEATURE_DISABLED.
     269             :  *
     270             :  *  @retval 0         Successfully changed the Private GATT Proxy feature state.
     271             :  *  @retval -ENOTSUP  The Private GATT Proxy feature is not supported.
     272             :  *  @retval -EINVAL   Invalid parameter.
     273             :  *  @retval -EALREADY Already in the given state.
     274             :  */
     275           1 : int bt_mesh_priv_gatt_proxy_set(enum bt_mesh_feat_state priv_gatt_proxy);
     276             : 
     277             : /** @brief Get the current Private GATT Proxy state.
     278             :  *
     279             :  *  @returns The Private GATT Proxy feature state.
     280             :  */
     281           1 : enum bt_mesh_feat_state bt_mesh_priv_gatt_proxy_get(void);
     282             : 
     283             : /** @brief Enable or disable the Friend feature.
     284             :  *
     285             :  *  Any active friendships will be terminated immediately if the Friend feature
     286             :  *  is disabled.
     287             :  *
     288             :  *  Support for the Friend feature must be enabled through the
     289             :  *  @c CONFIG_BT_MESH_FRIEND configuration option.
     290             :  *
     291             :  *  @param friendship New Friend feature state. Must be one of
     292             :  *                    @ref BT_MESH_FEATURE_ENABLED and
     293             :  *                    @ref BT_MESH_FEATURE_DISABLED.
     294             :  *
     295             :  *  @retval 0        Successfully changed the Friend feature state.
     296             :  *  @retval -ENOTSUP The Friend feature is not supported.
     297             :  *  @retval -EINVAL  Invalid parameter.
     298             :  *  @retval -EALREADY Already in the given state.
     299             :  */
     300           1 : int bt_mesh_friend_set(enum bt_mesh_feat_state friendship);
     301             : 
     302             : /** @brief Get the current Friend state.
     303             :  *
     304             :  *  @returns The Friend feature state.
     305             :  */
     306           1 : enum bt_mesh_feat_state bt_mesh_friend_get(void);
     307             : 
     308             : /**
     309             :  * @brief Subnet Configuration
     310             :  * @defgroup bt_mesh_cfg_subnet Subnet Configuration
     311             :  * @{
     312             :  */
     313             : 
     314             : /** @brief Add a Subnet.
     315             :  *
     316             :  *  Adds a subnet with the given network index and network key to the list of
     317             :  *  known Subnets. All messages sent on the given Subnet will be processed by
     318             :  *  this node, and the node may send and receive Network Beacons on the given
     319             :  *  Subnet.
     320             :  *
     321             :  *  @param net_idx Network index.
     322             :  *  @param key     Root network key of the Subnet. All other keys are derived
     323             :  *                 from this.
     324             :  *
     325             :  *  @retval STATUS_SUCCESS The Subnet was successfully added.
     326             :  *  @retval STATUS_INSUFF_RESOURCES No room for this Subnet.
     327             :  *  @retval STATUS_UNSPECIFIED The Subnet couldn't be created for some reason.
     328             :  */
     329           1 : uint8_t bt_mesh_subnet_add(uint16_t net_idx, const uint8_t key[16]);
     330             : 
     331             : /** @brief Update the given Subnet.
     332             :  *
     333             :  *  Starts the Key Refresh procedure for this Subnet by adding a second set of
     334             :  *  encryption keys. The Subnet will continue sending with the old key (but
     335             :  *  receiving messages using both) until the Subnet enters Key Refresh phase 2.
     336             :  *
     337             :  *  This allows a network configurator to replace old network and application
     338             :  *  keys for the entire network, effectively removing access for all nodes that
     339             :  *  aren't given the new keys.
     340             :  *
     341             :  *  @param net_idx Network index.
     342             :  *  @param key     New root network key of the Subnet.
     343             :  *
     344             :  *  @retval STATUS_SUCCESS The Subnet was updated with a second key.
     345             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     346             :  *  @retval STATUS_IDX_ALREADY_STORED The @c key value is the same as the
     347             :  *                                    current key.
     348             :  *  @retval STATUS_CANNOT_UPDATE The Subnet cannot be updated for some reason.
     349             :  */
     350           1 : uint8_t bt_mesh_subnet_update(uint16_t net_idx, const uint8_t key[16]);
     351             : 
     352             : /** @brief Delete a Subnet.
     353             :  *
     354             :  *  Removes the Subnet with the given network index from the node. The node will
     355             :  *  stop sending Network Beacons with the given Subnet, and can no longer
     356             :  *  process messages on this Subnet.
     357             :  *
     358             :  *  All Applications bound to this Subnet are also deleted.
     359             :  *
     360             :  *  @param net_idx Network index.
     361             :  *
     362             :  *  @retval STATUS_SUCCESS The Subnet was deleted.
     363             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     364             :  */
     365           1 : uint8_t bt_mesh_subnet_del(uint16_t net_idx);
     366             : 
     367             : /** @brief Check whether a Subnet is known.
     368             :  *
     369             :  *  @param net_idx Network index
     370             :  *
     371             :  *  @return true if a Subnet with the given index exists, false otherwise.
     372             :  */
     373           1 : bool bt_mesh_subnet_exists(uint16_t net_idx);
     374             : 
     375             : /** @brief Set the Subnet's Key Refresh phase.
     376             :  *
     377             :  *  The Key Refresh procedure is started by updating the Subnet keys through
     378             :  *  @ref bt_mesh_subnet_update. This puts the Subnet in Key Refresh Phase 1.
     379             :  *  Once all nodes have received the new Subnet key, Key Refresh Phase 2 can be
     380             :  *  activated through this function to start transmitting with the new network
     381             :  *  key. Finally, to revoke the old key, set the Key Refresh Phase to 3. This
     382             :  *  removes the old keys from the node, and returns the Subnet back to normal
     383             :  *  single-key operation with the new key set.
     384             :  *
     385             :  *  @param net_idx Network index.
     386             :  *  @param phase   Pointer to the new Key Refresh phase. Will return the actual
     387             :  *                 Key Refresh phase after updating.
     388             :  *
     389             :  *  @retval STATUS_SUCCESS The Key Refresh phase of the Subnet was successfully
     390             :  *                         changed.
     391             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     392             :  *  @retval STATUS_CANNOT_UPDATE The given phase change is invalid.
     393             :  */
     394           1 : uint8_t bt_mesh_subnet_kr_phase_set(uint16_t net_idx, uint8_t *phase);
     395             : 
     396             : /** @brief Get the Subnet's Key Refresh phase.
     397             :  *
     398             :  *  @param net_idx Network index.
     399             :  *  @param phase   Pointer to the Key Refresh variable to fill.
     400             :  *
     401             :  *  @retval STATUS_SUCCESS Successfully populated the @c phase variable.
     402             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     403             :  */
     404           1 : uint8_t bt_mesh_subnet_kr_phase_get(uint16_t net_idx, uint8_t *phase);
     405             : 
     406             : /** @brief Set the Node Identity state of the Subnet.
     407             :  *
     408             :  *  The Node Identity state of a Subnet determines whether the Subnet advertises
     409             :  *  connectable Node Identity beacons for Proxy Clients to connect to.
     410             :  *  Once started, the Node Identity beacon runs for 60 seconds, or until it is
     411             :  *  stopped.
     412             :  *
     413             :  *  This function serves the same purpose as @ref bt_mesh_proxy_identity_enable,
     414             :  *  but only acts on a single Subnet.
     415             :  *
     416             :  *  GATT Proxy support must be enabled through
     417             :  *  @kconfig{CONFIG_BT_MESH_GATT_PROXY}.
     418             :  *
     419             :  *  @param net_idx Network index.
     420             :  *  @param node_id New Node Identity state, must be either @ref
     421             :  *                 BT_MESH_FEATURE_ENABLED or @ref BT_MESH_FEATURE_DISABLED.
     422             :  *
     423             :  *  @retval STATUS_SUCCESS Successfully set the Node Identity state of the
     424             :  *                         Subnet.
     425             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     426             :  *  @retval STATUS_FEAT_NOT_SUPP The Node Identity feature is not supported.
     427             :  *  @retval STATUS_CANNOT_SET Couldn't set the Node Identity state.
     428             :  */
     429           1 : uint8_t bt_mesh_subnet_node_id_set(uint16_t net_idx,
     430             :                                    enum bt_mesh_feat_state node_id);
     431             : 
     432             : /** @brief Get the Node Identity state of the Subnet.
     433             :  *
     434             :  *  @param net_idx Network index.
     435             :  *  @param node_id Node Identity variable to fill.
     436             :  *
     437             :  *  @retval STATUS_SUCCESS Successfully populated the @c node_id variable.
     438             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     439             :  */
     440           1 : uint8_t bt_mesh_subnet_node_id_get(uint16_t net_idx,
     441             :                                    enum bt_mesh_feat_state *node_id);
     442             : 
     443             : /** @brief Set the Private Node Identity state of the Subnet.
     444             :  *
     445             :  *  The Private Node Identity state of a Subnet determines whether the Subnet
     446             :  *  advertises connectable Private Node Identity beacons for Proxy Clients to
     447             :  *  connect to. Once started, the Node Identity beacon runs for 60 seconds,
     448             :  *  or until it is stopped.
     449             :  *
     450             :  *  Private Node Identity can only be enabled if regular Node Identity is not
     451             :  *  enabled for any subnet.
     452             :  *
     453             :  *  GATT Proxy and Private Beacon support must be enabled through
     454             :  *  @kconfig{CONFIG_BT_MESH_GATT_PROXY} and
     455             :  *  @kconfig{CONFIG_BT_MESH_PRIV_BEACONS}.
     456             :  *
     457             :  *  @param net_idx      Network index.
     458             :  *  @param priv_node_id New Private Node Identity state, must be either @ref
     459             :  *                      BT_MESH_FEATURE_ENABLED or @ref BT_MESH_FEATURE_DISABLED.
     460             :  *
     461             :  *  @retval STATUS_SUCCESS Successfully set the Private Node Identity state of the Subnet.
     462             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     463             :  *  @retval STATUS_FEAT_NOT_SUPP The Private Node Identity feature is not supported.
     464             :  *  @retval STATUS_TEMP_STATE_CHG_FAIL The Private Node Identity state cannot be enabled, because
     465             :  *                                     Node Identity state is already enabled.
     466             :  *  @retval STATUS_CANNOT_SET Couldn't set the Private Node Identity state.
     467             :  */
     468           1 : uint8_t bt_mesh_subnet_priv_node_id_set(uint16_t net_idx,
     469             :                                         enum bt_mesh_feat_state priv_node_id);
     470             : 
     471             : /** @brief Get the Private Node Identity state of the Subnet.
     472             :  *
     473             :  *  @param net_idx      Network index.
     474             :  *  @param priv_node_id Private Node Identity variable to fill.
     475             :  *
     476             :  *  @retval STATUS_SUCCESS Successfully populated the @c priv_node_id variable.
     477             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     478             :  */
     479           1 : uint8_t bt_mesh_subnet_priv_node_id_get(uint16_t net_idx,
     480             :                                         enum bt_mesh_feat_state *priv_node_id);
     481             : 
     482             : /** @brief Get a list of all known Subnet indexes.
     483             :  *
     484             :  *  Builds a list of all known Subnet indexes in the @c net_idxs array.
     485             :  *  If the @c net_idxs array is smaller than the list of known Subnets, this
     486             :  *  function fills all available entries and returns @c -ENOMEM. In this
     487             :  *  case, the next @c max entries of the list can be read out by calling
     488             :  *  @code
     489             :  *  bt_mesh_subnets_get(list, max, max);
     490             :  *  @endcode
     491             :  *
     492             :  *  Note that any changes to the Subnet list between calls to this function
     493             :  *  could change the order and number of entries in the list.
     494             :  *
     495             :  *  @param net_idxs Array to fill.
     496             :  *  @param max      Max number of indexes to return.
     497             :  *  @param skip     Number of indexes to skip. Enables batched processing of the
     498             :  *                  list.
     499             :  *
     500             :  *  @return The number of indexes added to the @c net_idxs array, or @c -ENOMEM
     501             :  *          if the number of known Subnets exceeds the @c max parameter.
     502             :  */
     503           1 : ssize_t bt_mesh_subnets_get(uint16_t net_idxs[], size_t max, off_t skip);
     504             : 
     505             : /**
     506             :  * @}
     507             :  */
     508             : 
     509             : /**
     510             :  * @brief Application Configuration
     511             :  * @defgroup bt_mesh_cfg_app Application Configuration
     512             :  * @{
     513             :  */
     514             : 
     515             : /** @brief Add an Application key.
     516             :  *
     517             :  *  Adds the Application with the given index to the list of known applications.
     518             :  *  Allows the node to send and receive model messages encrypted with this
     519             :  *  Application key.
     520             :  *
     521             :  *  Every Application is bound to a specific Subnet. The node must know the
     522             :  *  Subnet the Application is bound to before it can add the Application.
     523             :  *
     524             :  *  @param app_idx Application index.
     525             :  *  @param net_idx Network index the Application is bound to.
     526             :  *  @param key     Application key value.
     527             :  *
     528             :  *  @retval STATUS_SUCCESS The Application was successfully added.
     529             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     530             :  *  @retval STATUS_INSUFF_RESOURCES There's no room for storing this
     531             :  *                                  Application.
     532             :  *  @retval STATUS_INVALID_BINDING This AppIdx is already bound to another
     533             :  *                                 Subnet.
     534             :  *  @retval STATUS_IDX_ALREADY_STORED This AppIdx is already stored with a
     535             :  *                                    different key value.
     536             :  *  @retval STATUS_CANNOT_SET Cannot set the Application key for some reason.
     537             :  */
     538           1 : uint8_t bt_mesh_app_key_add(uint16_t app_idx, uint16_t net_idx,
     539             :                             const uint8_t key[16]);
     540             : 
     541             : /** @brief Update an Application key.
     542             :  *
     543             :  *  Update an Application with a second Application key, as part of the
     544             :  *  Key Refresh procedure of the bound Subnet. The node will continue
     545             :  *  transmitting with the old application key (but receiving on both) until the
     546             :  *  Subnet enters Key Refresh phase 2. Once the Subnet enters Key Refresh phase
     547             :  *  3, the old application key will be deleted.
     548             :  *
     549             :  *  @note The Application key can only be updated if the bound Subnet is in Key
     550             :  *        Refresh phase 1.
     551             :  *
     552             :  *  @param app_idx Application index.
     553             :  *  @param net_idx Network index the Application is bound to, or
     554             :  *                 @ref BT_MESH_KEY_ANY to skip the binding check.
     555             :  *  @param key     New key value.
     556             :  *
     557             :  *  @retval STATUS_SUCCESS The Application key was successfully updated.
     558             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     559             :  *  @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx.
     560             :  *  @retval STATUS_CANNOT_UPDATE The Application key cannot be updated for some
     561             :  *                               reason.
     562             :  *  @retval STATUS_IDX_ALREADY_STORED This AppIdx is already updated with a
     563             :  *                                    different key value.
     564             :  */
     565           1 : uint8_t bt_mesh_app_key_update(uint16_t app_idx, uint16_t net_idx,
     566             :                                const uint8_t key[16]);
     567             : 
     568             : /** @brief Delete an Application key.
     569             :  *
     570             :  *  All models bound to this application will remove this binding.
     571             :  *  All models publishing with this application will stop publishing.
     572             :  *
     573             :  *  @param app_idx Application index.
     574             :  *  @param net_idx Network index.
     575             :  *
     576             :  *  @retval STATUS_SUCCESS The Application key was successfully deleted.
     577             :  *  @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
     578             :  *  @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx.
     579             :  */
     580           1 : uint8_t bt_mesh_app_key_del(uint16_t app_idx, uint16_t net_idx);
     581             : 
     582             : /** @brief Check if an Application key is known.
     583             :  *
     584             :  *  @param app_idx Application index.
     585             :  *
     586             :  *  @return true if the Application is known, false otherwise.
     587             :  */
     588           1 : bool bt_mesh_app_key_exists(uint16_t app_idx);
     589             : 
     590             : /** @brief Get a list of all known Application key indexes.
     591             :  *
     592             :  *  Builds a list of all Application indexes for the given network index in the
     593             :  *  @c app_idxs array. If the @c app_idxs array cannot fit all bound
     594             :  *  Applications, this function fills all available entries and returns @c
     595             :  *  -ENOMEM. In this case, the next @c max entries of the list can be read out
     596             :  *  by calling
     597             :  *  @code
     598             :  *  bt_mesh_app_keys_get(net_idx, list, max, max);
     599             :  *  @endcode
     600             :  *
     601             :  *  Note that any changes to the Application key list between calls to this
     602             :  *  function could change the order and number of entries in the list.
     603             :  *
     604             :  *  @param net_idx  Network Index to get the Applications of, or @ref
     605             :  *                  BT_MESH_KEY_ANY to get all Applications.
     606             :  *  @param app_idxs Array to fill.
     607             :  *  @param max      Max number of indexes to return.
     608             :  *  @param skip     Number of indexes to skip. Enables batched processing of the
     609             :  *                  list.
     610             :  *
     611             :  *  @return The number of indexes added to the @c app_idxs array, or @c -ENOMEM
     612             :  *          if the number of known Applications exceeds the @c max parameter.
     613             :  */
     614           1 : ssize_t bt_mesh_app_keys_get(uint16_t net_idx, uint16_t app_idxs[], size_t max,
     615             :                              off_t skip);
     616             : 
     617             : /**
     618             :  * @}
     619             :  */
     620             : 
     621             : #ifdef __cplusplus
     622             : }
     623             : #endif
     624             : 
     625             : /**
     626             :  * @}
     627             :  */
     628             : 
     629             : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_ */

Generated by: LCOV version 1.14