1 /* 2 * Copyright (c) 2020 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup wifiaware 18 * @{ 19 * 20 * @brief Enables devices to interact with neighboring devices without connecting to a Wi-Fi network. 21 * 22 * 23 * Using the capabilities provided by this module, a Wi-Fi device can quickly discover and connect to other devices. \n 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 29 /** 30 * @file wifiaware.h 31 * 32 * @brief Defines functions of the Wi-Fi Aware module. 33 * 34 * You can use the functions to: \n 35 * <ul> 36 * <li>Initialize and deinitialize the module.</li> 37 * <li>Start and stop the Wi-Fi Aware subscription service.</li> 38 * <li>Send data to and receive data from a peer device.</li> 39 * <li>Enable and disable short-distance transmission.</li> 40 * </ul> 41 * 42 * @since 1.0 43 * @version 1.0 44 */ 45 46 #ifndef WIFI_AWARE_H 47 #define WIFI_AWARE_H 48 49 #ifdef __cplusplus 50 #if __cplusplus 51 extern "C" { 52 #endif 53 #endif /* __cplusplus */ 54 55 /** 56 * @brief Indicates that short-distance transmission is enabled. 57 * 58 */ 59 #define WIFIAWARE_LOW_POWER_SWITCH_ON 1 60 /** 61 * @brief Indicates that short-distance transmission is disabled. 62 * 63 */ 64 #define WIFIAWARE_LOW_POWER_SWITCH_OFF 0 65 66 /** 67 * @brief Indicates a successful operation. 68 * 69 */ 70 #define WIFIAWARE_SUCCESS 0 71 /** 72 * @brief Indicates an operation failure. 73 * 74 */ 75 #define WIFIAWARE_FAIL (-1) 76 77 /** 78 * @brief Indicates the default channel of Wi-Fi Aware, which is channel 6. 79 * 80 */ 81 #define WIFIAWARE_DEFAULT_CHANNEL 6 82 83 /** 84 * @brief Enumerates Neighbor Awareness Networking (NAN) synchronization modes. 85 * 86 */ 87 enum NanSyncMode { 88 /** Huawei private NAN synchronization */ 89 NAN_SYNC_MODE_PRIVATE, 90 /** Standard NAN synchronization */ 91 NAN_SYNC_MODE_STANDARD, 92 /** Both Huawei private and standard NAN synchronization */ 93 NAN_SYNC_MODE_BOTH, 94 /** BUTT value, which represents the total number of enumerated values (excluding the BUTT value itself) */ 95 NAN_SYNC_MODE_BUTT 96 }; 97 98 /** 99 * @brief Defines the type of the callback that is invoked when the subscription service receives a message. 100 * 101 * This callback only processes time-efficient transactions. To process time-consuming transactions, you need to create 102 * specific tasks. 103 * 104 * @param macAddr Indicates the MAC address of the device that sends the message. 105 * @param peerHandle Indicates the instance ID of the device that sends the message. 106 * @param localHandle Indicates the instance ID of the device that receives the message. 107 * @param msg Indicates the message received. 108 * @param len Indicates the length of the message received. 109 * @return Returns {@link WIFIAWARE_SUCCESS} if the callback is invoked successfully; returns {@link WIFIAWARE_FAIL} 110 * otherwise. 111 * @since 1.0 112 * @version 1.0 113 */ 114 typedef int (*RecvCallback)(unsigned char* macAddr, unsigned char peerHandle, unsigned char localHandle, 115 unsigned char* msg, unsigned char len); 116 117 /** 118 * @brief Initializes the Wi-Fi Aware module. 119 * 120 * Before using this function, ensure that the access point (AP) interface is enabled on the device and channel 6 is 121 * used. Otherwise, calling this function will fail. \n 122 * You can enable the AP interface using the corresponding function or AT command. \n 123 * 124 * @return Returns {@link WIFIAWARE_SUCCESS} if the Wi-Fi Aware module is initialized; returns {@link WIFIAWARE_FAIL} 125 * otherwise. 126 * @since 1.0 127 * @version 1.0 128 */ 129 int InitNAN(void); 130 131 /** 132 * @brief Deinitializes the Wi-Fi Aware module. 133 * 134 * This function takes effect regardless of whether the module has been initialized. \n 135 * 136 * @return Returns {@link WIFIAWARE_SUCCESS} if the Wi-Fi Aware module is deinitialized; returns {@link WIFIAWARE_FAIL} 137 * otherwise. 138 * @since 1.0 139 * @version 1.0 140 */ 141 int DeinitNAN(void); 142 143 /** 144 * @brief Starts the Wi-Fi Aware subscription service. 145 * 146 * 147 * Before using this function, call {@link InitNAN} to initialize the Wi-Fi Aware module. \n 148 * 149 * @param svcName Indicates the service name. It is a string and cannot be <b>NULL</b>. 150 * @param localHandle Indicates the instance ID of the local device associated with the service name. The value ranges 151 * from 1 to 255. It is used for identify authentication during device interaction. 152 * @param recvCB Indicates the callback invoked when the Wi-Fi Aware subscription service receives a message. 153 * @return Returns {@link WIFIAWARE_SUCCESS} if the Wi-Fi Aware subscription service is started; 154 * returns {@link WIFIAWARE_FAIL} otherwise. 155 * @since 1.0 156 * @version 1.0 157 */ 158 int SubscribeService(const char* svcName, unsigned char localHandle, RecvCallback recvCB); 159 160 /** 161 * @brief Sends user data to the peer device. 162 * 163 * 164 * This is an asynchronous function. The return value only indicates whether the user data has been sent to 165 * the hardware driver. \n 166 * As this function does not check whether the MAC address and instance ID are valid, the caller should 167 * ensure their validity. \n 168 * 169 * @param macAddr Indicates the MAC address of the peer device. It contains 6 bytes. 170 * @param peerHandle Indicates the instance ID of the peer device. It contains 1 to 255 bytes. 171 * @param localHandle Indicates the instance ID of the local device specified when starting the Wi-Fi Aware 172 * subscription service. 173 * @param msg Indicates the user data to send. It cannot exceed 255 bytes. 174 * @param len Indicates the length of the user data to send. 175 * @return Returns {@link WIFIAWARE_SUCCESS} if the user data is sent to the hardware driver; 176 * returns {@link WIFIAWARE_FAIL} otherwise. 177 * @since 1.0 178 * @version 1.0 179 */ 180 int SendData(unsigned char* macAddr, unsigned char peerHandle, unsigned char localHandle, 181 unsigned char* msg, int len); 182 183 /** 184 * @brief Stops the Wi-Fi Aware subscription service. 185 * 186 * 187 * Before using this function, call {@link InitNAN} to initialize the Wi-Fi Aware module. \n 188 * This function takes effect regardless of whether the Wi-Fi Aware subscription service has been started. \n 189 * 190 * @param localHandle Indicates the instance ID of the local device specified when starting the Wi-Fi Aware 191 * subscription service. 192 * @return Returns {@link WIFIAWARE_SUCCESS} if the Wi-Fi Aware subscription service is stopped; 193 * returns {@link WIFIAWARE_FAIL} otherwise. 194 * @since 1.0 195 * @version 1.0 196 */ 197 int StopSubscribe(unsigned char localHandle); 198 199 /** 200 * @brief Sets whether to enable short-distance transmission. 201 * 202 * Short-distance transmission is determined by {@link WIFIAWARE_LOW_POWER_SWITCH_ON} 203 * and {@link WIFIAWARE_LOW_POWER_SWITCH_OFF}. \n 204 * When short-distance transmission is enabled, messages can be sent to devices 205 * within a distance of 30 cm from the local device. \n 206 * Before using this function, ensure that the AP interface is enabled. \n 207 * 208 * @param powerSwitch Specifies whether to enable short-distance transmission. The value can be 209 * {@link WIFIAWARE_LOW_POWER_SWITCH_ON} or {@link WIFIAWARE_LOW_POWER_SWITCH_OFF}. 210 * @return Returns {@link WIFIAWARE_SUCCESS} if short-distance transmission is set; 211 * returns {@link WIFIAWARE_FAIL} otherwise. 212 * @since 1.0 213 * @version 1.0 214 */ 215 int SetLowPower(int powerSwitch); 216 217 /** 218 * @brief Sets the transmit power in short-distance transmission mode. 219 * 220 * If you call {@link SetLowPower} with <b>powerSwitch</b> set to {@link WIFIAWARE_LOW_POWER_SWITCH_ON},the Wi-Fi Aware 221 * module enters the short-distance transmission mode and sends data at the transmit power set by this function. \n 222 * Before using this function, ensure that the AP has been started. \n 223 * 224 * @param power Indicates the transmit power to set. The recommended value range is -70 dB to -42 dB, and the default 225 * value is <b>-61 dB</b>. 226 * @return Returns {@link WIFIAWARE_SUCCESS} if the transmit power is set; returns {@link WIFIAWARE_FAIL} otherwise. 227 * @since 2.2 228 * @version 1.0 229 */ 230 int SetPower(signed char value); 231 232 /** 233 * @brief Sets whether the AP can be discovered. 234 * 235 * By default, the AP can be discovered. 236 * Before using this function, ensure that the AP has been started. \n 237 * 238 * @param enable Specifies whether the AP can be discovered. The value <b>true</b> indicates that the AP can be 239 * discovered, and <b>false</b> indicates the opposite. 240 * @return Returns {@link WIFIAWARE_SUCCESS} if the setting is successful; returns {@link WIFIAWARE_FAIL} otherwise. 241 * @since 2.2 242 * @version 1.0 243 */ 244 int NanBeaconSwitch(unsigned char enable); 245 246 /** 247 * @brief Sets the number of NAN packet retransmissions in short-distance transmission mode. 248 * 249 * When you call {@link SendData} to send packets, the Wi-Fi Aware module will retransmit the packets based on the 250 * number set using this function once packet transmission fails. \n 251 * Before using this function, ensure that the AP has been started. \n 252 * 253 * @param retries Indicates the number of NAN packet retransmissions to set. The recommended value range is 0 to 200, 254 * and the default value is <b>200</b>. 255 * @return Returns {@link WIFIAWARE_SUCCESS} if the number of NAN packet retransmissions is set; 256 * returns {@link WIFIAWARE_FAIL} otherwise. 257 * @since 2.2 258 * @version 1.0 259 */ 260 int NanSetRetryTimes(unsigned int retries); 261 262 /** 263 * @brief Obtains the NAN synchronization mode supported by the Wi-Fi Aware module. 264 * 265 * @return Returns the NAN synchronization mode, as enumerated in {@link NanSyncMode}. 266 * @since 2.2 267 * @version 1.0 268 */ 269 int NanGetSyncMode(void); 270 271 #ifdef __cplusplus 272 #if __cplusplus 273 } 274 #endif 275 #endif /* __cplusplus */ 276 277 #endif 278 /** @} */