text: /* mbed Microcontroller Library
   * Copyright (c) 2020 ARM Limited
   * SPDX-License-Identifier: Apache-2.0
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  #ifndef BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
  #define BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
  
  #if BLE_FEATURE_PRIVACY
  
  #include "ble/common/BLETypes.h"
  #include "ble/common/blecommon.h"
  #include "GapTypes.h"
  
  namespace ble {
  
  /**
   * Control the controller resolution list, resolve private addresses and generate
   * new ones.
   */
  struct PalPrivateAddressController {
      struct EventHandler {
  #if BLE_GAP_HOST_BASED_PRIVATE_ADDRESS_RESOLUTION
          /** Called when the address resolution request has completed.
           *
           * @param success true if the address has been resolved and false otherwise.
           */
          virtual void on_private_address_resolved(bool success) = 0;
  #endif // BLE_GAP_HOST_BASED_PRIVATE_ADDRESS_RESOLUTION
  
          /** Called when the resolvable private address request has completed.
           *
           * @param rpa The address generated. In case of failure, the address is
           * equal to an invalid address (default value from address_t).
           */
          virtual void on_resolvable_private_address_generated(const address_t &rpa) = 0;
  
          /**
           * Called when a new item has been added or removed to the resolving list
           * or if the resolving list has been cleared.
           */
          virtual void on_resolving_list_action_complete() = 0;
      };
  
      /**
       * Initialize the address registry module
       * @return BLE_ERROR_NONE in case of success.
       */
      virtual ble_error_t initialize() = 0;
  
      /**
       * Terminate the address registry module
       * @return BLE_ERROR_NONE in case of success.
       */
      virtual ble_error_t terminate() = 0;
  
      /** Generate a new resolvable private address from an IRK
       *
       * The completion of the request is signaled by the stack with a call to
       * PalPrivateAddressController::on_resolvable_private_address_generated.
       *
       * @param local_irk The IRK to use to generate the address.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note Addresses are generated one at a time, this function should not be
       * called while an address is being generated.
       *
       * @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.2 Private Device Address Generation
       */
      virtual ble_error_t generate_resolvable_private_address(const irk_t& local_irk) = 0;
  
      /** Generate a new non-resolvable private address
       *
       * @return The address generated.
       *
       * @note The address generated might be invalid (all zeros).
       *
       * @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.2 Private Device Address Generation
       */
      virtual address_t generate_non_resolvable_private_address() = 0;
  
      /** Attempt to resolve a resolvable private address received with an IRK.
       *
       * The completion of the request is signaled by the stack with a call to
       * PalGapEventHandler::on_private_address_resolved.
       *
       * @param address The address to resole
       * @param irk The IRK used for the resolution of the address.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note Addresses are resolved one at a time, this function should not be
       * called while an address is being resolved.
       *
       * @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.3 Private Device Address Resolution
       */
      virtual ble_error_t resolve_private_address(
          const address_t &address,
          const irk_t& irk
      ) = 0;
  
      ////////////////////////////////////////////////////////////////////////////
      // LL resolution and generation management
      //
  
      /** Check if privacy feature is supported by LL implementation
       *
       * @return true if privacy is supported, false otherwise.
       *
       * @note: See Bluetooth 5 Vol 3 Part C: 10.7 Privacy feature.
       */
      virtual bool is_ll_privacy_supported() = 0;
  
      /** Enable or disable private addresses resolution
       *
       * @param enable whether to enable private addresses resolution
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.44 LE Set Address Resolution Enable command.
       */
      virtual ble_error_t set_ll_address_resolution(
          bool enable
      ) = 0;
  
      /** Set the timeout for LL resolvable private address rotation.
       *
       * @param timeout The timeout after which the resolvable private address in
       * the controller is changed.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.45 LE Set Resolvable Private Address Timeout Command
       */
      virtual ble_error_t set_ll_resolvable_private_address_timeout(resolvable_address_timeout_t timeout) = 0;
  
      ////////////////////////////////////////////////////////////////////////////
      // Resolving list management
      //
  
      /** Return the resolving list capacity
       *
       * @return A positive number if LL privacy is supported, 0 if not.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.41 LE Read Resolving List Size Command.
       */
      virtual uint8_t read_resolving_list_capacity() = 0;
  
      /** Add a device definition into the resolving list.
       *
       * @param peer_address_type The type of the identity address received from the
       * peer during bonding.
       * @param peer_identity_address The identity address of the peer received
       * during bonding.
       * @param peer_irk The irk of the peer.
       * @param local_irk The irk sent to the peer during bonding.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: Cannot be used if address translation is enabled and the device is
       * advertising/scanning or initiating.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.38 LE Add Device To Resolving List Command
       */
      virtual ble_error_t add_device_to_resolving_list(
          target_peer_address_type_t peer_address_type,
          const address_t &peer_identity_address,
          const irk_t& peer_irk,
          const irk_t& local_irk
      ) = 0;
  
      /** Remove a device definition from the resolving list.
       *
       * @param peer_address_type The type of the identity address received from the
       * peer during bonding.
       * @param peer_identity_address The identity address of the peer received
       * during bonding.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: Cannot be used if address translation is enabled and the device is
       * advertising/scanning or initiating.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.39 LE Remove Device From Resolving List Command
       */
      virtual ble_error_t remove_device_from_resolving_list(
          target_peer_address_type_t peer_address_type,
          const address_t &peer_identity_address
      ) = 0;
  
      /** Remove all entries from the resolving list.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: Cannot be used if address translation is enabled and the device is
       * advertising/scanning or initiating.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.40 LE Clear Resolving List Command
       */
      virtual ble_error_t clear_resolving_list() = 0;
  
      /** Set the privacy mode (for LL controllers)
       *
       * @param peer_address_type The identity address type of the peer
       * @param peer_address The identity address of the peer
       * @param privacy_mode whether network or device privacy should be used for
       * the peer.
       *
       * @return BLE_ERROR_NONE if the request has been successfully sent or the
       * appropriate error otherwise.
       *
       * @note: See Bluetooth 5 Vol 2 PartE: 7.8.77 LE Set Privacy Mode Command
       */
      virtual ble_error_t set_peer_privacy_mode(
          target_peer_address_type_t peer_address_type,
          const address_t &peer_address,
          privacy_mode_t privacy_mode
      ) = 0;
  
      /**
       * Set the event handler receiving events from this instance.
       * @param handler The handler to use when an event happen.
       */
      virtual void set_event_handler(EventHandler *handler) = 0;
  };
  
  } // namespace ble
  
  #endif // BLE_FEATURE_PRIVACY
  
  #endif //BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
  