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