1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_HS_ID_ 21 #define H_BLE_HS_ID_ 22 23 /** 24 * @brief Bluetooth Host Identity 25 * @defgroup bt_host_id Bluetooth Host Identity 26 * @ingroup bt_host 27 * @{ 28 */ 29 30 #include <inttypes.h> 31 #include "nimble/ble.h" 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /** 38 * Generates a new random address. This function does not configure the device 39 * with the new address; the caller can use the address in subsequent 40 * operations. 41 * 42 * @param nrpa The type of random address to generate: 43 * 0: static 44 * 1: non-resolvable private 45 * @param out_addr On success, the generated address gets written 46 * here. 47 * 48 * @return 0 on success; nonzero on failure. 49 */ 50 int ble_hs_id_gen_rnd(int nrpa, ble_addr_t *out_addr); 51 52 /** 53 * Sets the device's random address. The address type (static vs. 54 * non-resolvable private) is inferred from the most-significant byte of the 55 * address. The address is specified in host byte order (little-endian!). 56 * 57 * @param rnd_addr The random address to set. 58 * 59 * @return 0 on success; 60 * BLE_HS_EINVAL if the specified address is not a 61 * valid static random or non-resolvable 62 * private address. 63 * Other nonzero on error. 64 */ 65 int ble_hs_id_set_rnd(const uint8_t *rnd_addr); 66 67 /** 68 * Retrieves one of the device's identity addresses. The device can have two 69 * identity addresses: one public and one random. The id_addr_type argument 70 * specifies which of these two addresses to retrieve. 71 * 72 * @param id_addr_type The type of identity address to retrieve. 73 * Valid values are: 74 * o BLE_ADDR_PUBLIC 75 * o BLE_ADDR_RANDOM 76 * @param out_id_addr On success, the requested identity address is 77 * copied into this buffer. The buffer must 78 * be at least six bytes in size. Pass NULL 79 * if you do not require this information. 80 * @param out_is_nrpa On success, the pointed-to value indicates 81 * whether the retrieved address is a 82 * non-resolvable private address. Pass NULL 83 * if you do not require this information. 84 * 85 * @return 0 on success; 86 * BLE_HS_EINVAL if an invalid address type was 87 * specified; 88 * BLE_HS_ENOADDR if the device does not have an 89 * identity address of the requested type; 90 * Other BLE host core code on error. 91 */ 92 int ble_hs_id_copy_addr(uint8_t id_addr_type, uint8_t *out_id_addr, 93 int *out_is_nrpa); 94 95 /** 96 * Determines the best address type to use for automatic address type 97 * resolution. Calculation of the best address type is done as follows: 98 * 99 * if privacy requested: 100 * if we have a random static address: 101 * --> RPA with static random ID 102 * else 103 * --> RPA with public ID 104 * end 105 * else 106 * if we have a random static address: 107 * --> random static address 108 * else 109 * --> public address 110 * end 111 * end 112 * 113 * @param privacy (0/1) Whether to use a private address. 114 * @param out_addr_type On success, the "own addr type" code gets 115 * written here. 116 * 117 * @return 0 if an address type was successfully inferred. 118 * BLE_HS_ENOADDR if the device does not have a 119 * suitable address. 120 * Other BLE host core code on error. 121 */ 122 int ble_hs_id_infer_auto(int privacy, uint8_t *out_addr_type); 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 /** 129 * @} 130 */ 131 132 #endif 133