1Copyright 2017 The Android Open Source Project 2 3Licensed under the Apache License, Version 2.0 (the "License"); 4you may not use this file except in compliance with the License. 5You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9Unless required by applicable law or agreed to in writing, software 10distributed under the License is distributed on an "AS IS" BASIS, 11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12See the License for the specific language governing permissions and 13limitations under the License. 14 15# Wi-Fi Aware (NAN) HAL API Usage 16 17The Wi-Fi Aware (NAN) HAL API is defined in (<i>hardware/interfaces/wifi/1.0/</i>): 18 19* IWifiNanIface.hal 20* IWifiNanIfaceEventCallback.hal 21* types.hal (structure definitions) 22 23The Wi-Fi Aware (NAN) HAL API surface is very large - only a subset is used from the framework. 24 25Understanding of the HAL API subset which is actively used by the Android framework can be deduced 26by reviewing framework code, specifically (<i>frameworks/opt/net/wifi/</i>): 27 28* WifiAwareNativeApi.java 29* WifiAwareNativeCallback.java 30 31The above framework files determine the API usage - and should be consulted as the authoritative 32reference. Please consult the primary HAL file for documentation - they will not be replicated 33in this document. APIs which are in the HAL but are not listed in this README file are not used by 34the framework. 35 36Note: the HAL API is translated to the legacy HAL API (<i>wifi_nan.h</i>). This README file covers 37the new HAL API only. To understand the mapping between new and legacy HALs please consult 38<i>hardware/interfaces/wifi/\<version\>/default/hidl_struct_util.cpp</i>. 39 40## IWifiNanIface 41 42Format: 43* Hard-coded values are in <b>bold</b>, e.g. <b>true</b> or <b>5</b> 44* Assigned but not fixed values are specified using the <i>variable</i> keyword, possibly with some 45details/constraints 46* Unassigned values are specified using the <i>N/A</i> keyword. Unassigned usually means initialized 47to 0. 48 49APIs: 50 51* registerEventCallback(IWifiNanIfaceEventCallback callback) 52* getCapabilitiesRequest 53* enableRequest 54 * NanEnableRequest 55 * bool[2] operateInBand 56 * Index [NanBandIndex.NAN_BAND_24GHZ] = <b>true</b> 57 * Index [NanBandIndex.NAN_BAND_5GHZ] = <i>variable</i> 58 * uint8_t hopCountMax = <b>2</b> 59 * NanConfigRequest configParams 60 * uint8_t masterPref = <i>variable</i> 61 * bool disableDiscoveryAddressChangeIndication = <i>variable</i> 62 * bool disableStartedClusterIndication = <i>variable</i> 63 * bool disableJoinedClusterIndication = <i>variable</i> 64 * bool includePublishServiceIdsInBeacon = <b>true</b> 65 * uint8_t numberOfPublishServiceIdsInBeacon = <b>0</b> 66 * bool includeSubscribeServiceIdsInBeacon = <b>true</b> 67 * uint8_t numberOfSubscribeServiceIdsInBeacon = <b>0</b> 68 * uint16_t rssiWindowSize = <b>8</b> 69 * uint32_t macAddressRandomizationIntervalSec = <i>variable</i> 70 * Normal run-time: set to <b>1800</b> (30 minutes) 71 * Tests: set to <b>120</b> (2 minutes) 72 * NanBandSpecificConfig[2] bandSpecificConfig 73 * Index [NanBandIndex.NAN_BAND_24GHZ] 74 * uint8_t rssiClose = <b>60</b> 75 * uint8_t rssiMiddle = <b>70</b> 76 * uint8_t rssiCloseProximity = <b>60</b> 77 * uint8_t dwellTimeMs = <b>200</b> 78 * uint16_t scanPeriodSec = <b>20</b> 79 * bool validDiscoveryWindowIntervalVal = <i>variable</i> 80 * uint8_t discoveryWindowIntervalVal = <i>variable</i> 81 * Index [NanBandIndex.NAN_BAND_5GHZ] 82 * uint8_t rssiClose = <b>60</b> 83 * uint8_t rssiMiddle = <b>75</b> 84 * uint8_t rssiCloseProximity = <b>60</b> 85 * uint8_t dwellTimeMs = <b>200</b> 86 * uint16_t scanPeriodSec = <b>20</b> 87 * bool validDiscoveryWindowIntervalVal = <i>variable</i> 88 * uint8_t discoveryWindowIntervalVal = <i>variable</i> 89 * NanDebugConfig debugConfigs 90 * bool validClusterIdVals = <b>true</b> 91 * uint16_t clusterIdBottomRangeVal = <i>variable</i> 92 * uint16_t clusterIdTopRangeVal = <i>variable</i> 93 * bool validIntfAddrVal = <b>false</b> 94 * MacAddress intfAddrVal = <i>N/A</i> 95 * bool validOuiVal = <b>false</b> 96 * uint32_t ouiVal = <i>N/A</i> 97 * bool validRandomFactorForceVal = <b>false</b> 98 * uint8_t randomFactorForceVal = <i>N/A</i> 99 * bool validHopCountForceVal = <b>false</b> 100 * uint8_t hopCountForceVal = <i>N/A</i> 101 * bool validDiscoveryChannelVal = <b>false</b> 102 * WifiChannelInMhz[2] discoveryChannelMhzVal = <i>N/A</i> 103 * bool validUseBeaconsInBandVal = <b>false</b> 104 * bool[2] useBeaconsInBandVal = <i>N/A</i> 105 * bool validUseSdfInBandVal = <b>false</b> 106 * bool[2] useSdfInBandVal = <i>N/A</i> 107* configRequest 108 * NanConfigRequest: same as for <i>enableRequest</i> 109* disableRequest 110* startPublishRequest 111 * NanPublishRequest 112 * NanDiscoveryCommonConfig baseConfigs 113 * uint8_t sessionId = <i>variable</i> 114 * uint16_t ttlSec = <i>variable</i> 115 * uint16_t discoveryWindowPeriod = <b>1</b> 116 * uint8_t discoveryCount = <b>0</b> 117 * vec<uint8_t> serviceName = <i>variable</i> 118 * NanMatchAlg discoveryMatchIndicator = <b>NanMatchAlg.MATCH_NEVER</b> 119 * vec<uint8_t> serviceSpecificInfo = <i>variable</i> 120 * vec<uint8_t> extendedServiceSpecificInfo = <i>N/A</i> 121 * vec<uint8_t> rxMatchFilter = <i>variable</i> 122 * vec<uint8_t> txMatchFilter = <i>variable</i> 123 * bool useRssiThreshold = <b>false</b> 124 * bool disableDiscoveryTerminationIndication = <i>variable</i> 125 * bool disableMatchExpirationIndication = <b>true</b> 126 * bool disableFollowupReceivedIndication = <b>false</b> 127 * NanDataPathSecurityConfig securityConfig = <b>NanDataPathSecurityType.OPEN</b> 128 * bool rangingRequired = <b>false</b> 129 * uint32_t rangingIntervalMsec = <i>N/A</i> 130 * bitfield<NanRangingIndication> configRangingIndications = <i>N/A</i> 131 * uint16_t distanceIngressCm = <i>N/A</i> 132 * uint16_t distanceEgressCm = <i>N/A</i> 133 * NanPublishType publishType = <i>variable</i> 134 * NanTxType txType = <b>NanTxType.BROADCAST</b> 135 * bool autoAcceptDataPathRequests = <b>false</b> 136* stopPublishRequest 137* startSubscribeRequest 138 * NanSubscribeRequest 139 * NanDiscoveryCommonConfig baseConfigs 140 * Mostly same as <i>publish</i> above except: 141 * NanMatchAlg discoveryMatchIndicator = <b>NanMatchAlg.MATCH_ONCE</b> 142 * NanSubscribeType subscribeType = <i>variable</i> 143 * NanSrfType srfType = <i>N/A</i> 144 * bool srfRespondIfInAddressSet = <i>N/A</i> 145 * bool shouldUseSrf = <i>N/A</i> 146 * bool isSsiRequiredForMatch = <i>N/A</i> 147 * vec<MacAddress> intfAddr = <i>N/A</i> 148* stopSubscribeRequest 149* transmitFollowupRequest 150 * NanTransmitFollowupRequest 151 * uint8_t discoverySessionId = <i>variable</i> 152 * uint32_t peerId = <i>variable</i> 153 * MacAddress addr = <i>variable</i> 154 * bool isHighPriority = <b>false</b> 155 * bool shouldUseDiscoveryWindow = <b>true</b> 156 * vec<uint8_t> serviceSpecificInfo = <i>variable</i> 157 * vec<uint8_t> extendedServiceSpecificInfo = <i>N/A</i> 158 * bool disableFollowupResultIndication = <b>false</b> 159* createDataInterfaceRequest 160* deleteDataInterfaceRequest 161* initiateDataPathRequest 162 * NanInitiateDataPathRequest 163 * uint32_t peerId = <i>variable</i> 164 * MacAddress peerDiscMacAddr = <i>variable</i> 165 * NanDataPathChannelCfg channelRequestType = 166 <i>NanDataPathChannelCfg.CHANNEL_NOT_REQUESTED</i> 167 * WifiChannelInMhz channel = <b>2437</b> (note that should be ignored though - 168 CHANNEL_NOT_REQUESTED!) 169 * string ifaceName = <i>variable</i> 170 * NanDataPathSecurityConfig securityConfig = <i>variable</i> 171 * vec<uint8_t> appInfo = <i>N/A</i> 172 * vec<uint8_t> serviceNameOutOfBand = <i>variable</i> 173* respondToDataPathIndicationRequest 174 * NanRespondToDataPathIndicationRequest 175 * bool acceptRequest = <i>variable</i> 176 * uint32_t ndpInstanceId = <i>variable</i> 177 * string ifaceName = <i>variable</i> 178 * NanDataPathSecurityConfig securityConfig = <i>variable</i> 179 * vec<uint8_t> appInfo = <i>N/A</i> 180 * vec<uint8_t> serviceNameOutOfBand = <i>variable</i> 181* terminateDataPathRequest 182 183## IWifiNanIfaceEventCallback 184 185Format: 186* Parameters whose values are <i>ignored</i> will be flagged, otherwise the parameter value is used 187by the framework. 188 189API: 190 191* notifyXxxResponse: all callbacks are used by framework 192* eventClusterEvent 193* eventDisabled 194* eventPublishTerminated 195* eventSubscribeTerminated 196* eventMatch 197 * NanMatchInd (all parameters are used except those listed below) 198 * vec<uint8_t> extendedServiceSpecificInfo: <i>ignored</i> 199 * bool matchOccuredInBeaconFlag: <i>ignored</i> 200 * bool outOfResourceFlag: <i>ignored</i> 201 * uint8_t rssiValue: <i>ignored</i> 202 * NanCipherSuiteType peerCipherType: <i>ignored</i> 203 * bool peerRequiresSecurityEnabledInNdp: <i>ignored</i> 204 * bool peerRequiresRanging: <i>ignored</i> 205 * uint32_t rangingMeasurementInCm: <i>ignored</i> 206 * bitfield<NanRangingIndication> rangingIndicationType: <i>ignored</i> 207* eventMatchExpired: <i>ignored</i> 208* eventFollowupReceived 209 * NanFollowupReceivedInd (all parameters are used except those listed below) 210 * bool receivedInFaw: <i>ignored</i> 211 * vec<uint8_t> extendedServiceSpecificInfo: <i>ignored</i> 212* eventTransmitFollowup 213* eventDataPathRequest 214 * NanDataPathRequestInd (all parameters are used except those listed below) 215 * bool securityRequired: <i>ignored</i> 216 * vec<uint8_t> appInfo: <i>ignored</i> 217* eventDataPathConfirm 218 * NanDataPathConfirmInd (all parameters are used except those listed below) 219 * vec<uint8_t> appInfo: <i>ignored</i> 220* eventDataPathTerminated 221 222