1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.system.wifi.mainline_supplicant; 18 19 import android.system.wifi.mainline_supplicant.IStaInterfaceCallback; 20 import android.system.wifi.mainline_supplicant.UsdMessageInfo; 21 import android.system.wifi.mainline_supplicant.UsdServiceProtoType; 22 23 /** 24 * Interface exposed by the supplicant for each station mode network 25 * interface (ex. wlan0) it controls. 26 */ 27 interface IStaInterface { 28 /** 29 * Capabilities supported by USD. Values are only valid if |isUsdPublisherSupported| 30 * and/or |isUsdSubscriberSupported| are true. 31 */ 32 parcelable UsdCapabilities { 33 /** 34 * Whether USD Publisher is supported on this device. 35 */ 36 boolean isUsdPublisherSupported; 37 38 /** 39 * Whether USD Subscriber is supported on this device. 40 */ 41 boolean isUsdSubscriberSupported; 42 43 /** 44 * Maximum allowed length (in bytes) for the Service Specific Info (SSI). 45 */ 46 int maxLocalSsiLengthBytes; 47 48 /** 49 * Maximum allowed length (in bytes) for the service name. 50 */ 51 int maxServiceNameLengthBytes; 52 53 /** 54 * Maximum allowed length (in bytes) for a match filter. 55 */ 56 int maxMatchFilterLengthBytes; 57 58 /** 59 * Maximum number of allowed publish sessions. 60 */ 61 int maxNumPublishSessions; 62 63 /** 64 * Maximum number of allowed subscribe sessions. 65 */ 66 int maxNumSubscribeSessions; 67 } 68 69 /** 70 * Data used in both USD publish and subscribe configurations. 71 */ 72 parcelable UsdBaseConfig { 73 /** 74 * Service name of the USD session. A UTF-8 encoded string from 1 to 255 bytes in length. 75 * The only acceptable single-byte UTF-8 symbols for a Service Name are alphanumeric 76 * values (A-Z, a-z, 0-9), hyphen ('-'), period ('.'), and underscore ('_'). All 77 * valid multi-byte UTF-8 characters are acceptable in a Service Name. 78 */ 79 @utf8InCpp String serviceName; 80 81 /** 82 * Service protocol type for the USD session (ex. Generic, CSA Matter). 83 */ 84 UsdServiceProtoType serviceProtoType; 85 86 /** 87 * Details about the service being offered or being looked for. This information is 88 * transmitted within Service Discovery frames, and is used to help devices find each other 89 * and establish connections. The format and content of the service specific information are 90 * flexible and can be determined by the application. 91 */ 92 byte[] serviceSpecificInfo; 93 94 /** 95 * Ordered sequence of <length, value> pairs (|length| uses 1 byte and contains the number 96 * of bytes in the |value| field) which specify further match criteria (beyond the service 97 * name). 98 * 99 * The match behavior is specified in details in the NAN spec. 100 * Publisher: used if provided. 101 * Subscriber: used (if provided) only in ACTIVE sessions. 102 * 103 * Max length: |UsdCapabilities.maxMatchFilterLength|. 104 * NAN Spec: matching_filter_tx and Service Descriptor Attribute (SDA) / Matching Filter 105 */ 106 @nullable byte[] txMatchFilter; 107 108 /** 109 * Ordered sequence of <length, value> pairs (|length| uses 1 byte and contains the number 110 * of bytes in the |value| field) which specify further match criteria (beyond the service 111 * name). 112 * 113 * The match behavior is specified in details in the NAN spec. 114 * Publisher: used in SOLICITED or SOLICITED_UNSOLICITED sessions. 115 * Subscriber: used in ACTIVE or PASSIVE sessions. 116 * 117 * Max length: |UsdCapabilities.maxMatchFilterLength|. 118 * NAN Spec: matching_filter_rx 119 */ 120 @nullable byte[] rxMatchFilter; 121 122 /** 123 * Time interval (in seconds) that a USD session will be alive. 124 * The session will be terminated when the time to live (TTL) is reached, triggering either 125 * |IStaInterfaceCallback.onPublishTerminated| for Publish, or 126 * |IStaInterfaceCallback.onSubscribeTerminated| for Subscribe. 127 */ 128 int ttlSec; 129 130 /** 131 * Frequency where the device should begin to dwell. Default value is channel 6 (2.437 GHz), 132 * but other values may be selected per regulation in the geographical location. 133 */ 134 int defaultFreqMhz; 135 136 /** 137 * Channels which can be switched to. May contain any of the 20 MHz channels in the 138 * 2.4 Ghz and/or 5 Ghz bands, per regulation in the geographical location. 139 */ 140 int[] freqsMhz; 141 } 142 143 /** 144 * Subscribe modes that this USD session can be configured in. 145 */ 146 @Backing(type="byte") 147 enum UsdSubscribeType { 148 /** 149 * Subscribe function does not request transmission of any Subscribe messages, but checks 150 * for matches in received Publish messages. 151 */ 152 PASSIVE_MODE = 0, 153 /** 154 * Subscribe function additionally requests transmission of Subscribe messages and processes 155 * Publish messages. 156 */ 157 ACTIVE_MODE = 1, 158 } 159 160 /** 161 * Parameters for configuring a USD subscribe session. 162 */ 163 parcelable UsdSubscribeConfig { 164 /** 165 * Base USD session parameters. 166 */ 167 UsdBaseConfig baseConfig; 168 169 /** 170 * Subscribe mode that this session should be configured in. 171 */ 172 UsdSubscribeType subscribeType; 173 174 /** 175 * Recommended periodicity (in milliseconds) of query transmissions for the session. 176 */ 177 int queryPeriodMillis; 178 } 179 180 /** 181 * Type of USD publishing. 182 */ 183 @Backing(type="byte") 184 enum UsdPublishType { 185 /** 186 * Only transmissions that are triggered by a specific event. 187 */ 188 SOLICITED_ONLY = 0, 189 190 /** 191 * Only transmissions that are not requested. 192 */ 193 UNSOLICITED_ONLY = 1, 194 195 /** 196 * Both solicited and unsolicited transmissions. 197 */ 198 SOLICITED_AND_UNSOLICITED = 2, 199 } 200 201 /** 202 * Types of USD publish transmissions. 203 */ 204 @Backing(type="byte") 205 enum UsdPublishTransmissionType { 206 /** 207 * Sends data from one device to a single, specific destination device. 208 */ 209 UNICAST = 0, 210 211 /** 212 * Sends data from one device to a group of devices on the network simultaneously. 213 */ 214 MULTICAST = 1, 215 } 216 217 /** 218 * Parameters for configuring a USD publish session. 219 */ 220 parcelable UsdPublishConfig { 221 /** 222 * Base USD session parameters. 223 */ 224 UsdBaseConfig baseConfig; 225 226 /** 227 * Types of transmissions (solicited vs. unsolicited) which should be generated. 228 */ 229 UsdPublishType publishType; 230 231 /** 232 * Whether Further Service Discovery (FSD) is enabled. 233 */ 234 boolean isFsd; 235 236 /** 237 * Interval (in milliseconds) for sending unsolicited publish transmissions. 238 */ 239 int announcementPeriodMillis; 240 241 /** 242 * Type of the publish transmission (ex. unicast, multicast). 243 */ 244 UsdPublishTransmissionType transmissionType; 245 246 /** 247 * Whether to enable publish replied events. If disabled, then 248 * |IStaInterfaceCallback.onUsdPublishReplied| will not be 249 * called for this session. 250 */ 251 boolean eventsEnabled; 252 } 253 254 /** 255 * Register for callbacks on this interface. 256 * 257 * @param callback Callback object to invoke. 258 */ registerCallback(in IStaInterfaceCallback callback)259 void registerCallback(in IStaInterfaceCallback callback); 260 261 /** 262 * Retrieve capabilities related to Unsynchronized Service Discovery (USD). 263 * 264 * @return Instance of |UsdCapabilities| containing the capability info. 265 */ getUsdCapabilities()266 UsdCapabilities getUsdCapabilities(); 267 268 /** 269 * Start a USD publish session. Triggers a response via |IStaInterfaceCallback.onPublishStarted| 270 * if successful, or |IStaInterfaceCallback.onUsdPublishConfigFailed| if failed. 271 * 272 * @param cmdId Identifier for this request. Will be returned in the callback to identify 273 * the request. 274 * @param publishConfig Parameters for the requested publish session. 275 * @throws ServiceSpecificException with one of the following values: 276 * |SupplicantStatusCode.FAILURE_UNKNOWN| 277 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 278 */ startUsdPublish(in int cmdId, in UsdPublishConfig publishConfig)279 void startUsdPublish(in int cmdId, in UsdPublishConfig publishConfig); 280 281 /** 282 * Start a USD subscribe session. Triggers a response via 283 * |IStaInterfaceCallback.onSubscribeStarted| if successful, or 284 * |IStaInterfaceCallback.onUsdSubscribeConfigFailed| if failed. 285 * 286 * @param cmdId Identifier for this request. Will be returned in the callback to identify 287 * the request. 288 * @param subscribeConfig Parameters for the requested subscribe session. 289 * @throws ServiceSpecificException with one of the following values: 290 * |SupplicantStatusCode.FAILURE_UNKNOWN| 291 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 292 */ startUsdSubscribe(in int cmdId, in UsdSubscribeConfig subscribeConfig)293 void startUsdSubscribe(in int cmdId, in UsdSubscribeConfig subscribeConfig); 294 295 /** 296 * Update the service-specific info for an active publish session. 297 * 298 * @param publishId Identifier for the active publish session. 299 * @param serviceSpecificInfo Byte array containing the service-specific info. Note that the 300 * maximum info length is |UsdCapabilities.maxLocalSsiLengthBytes|. 301 * @throws ServiceSpecificException with one of the following values: 302 * |SupplicantStatusCode.FAILURE_UNKNOWN| 303 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 304 */ updateUsdPublish(in int publishId, in byte[] serviceSpecificInfo)305 void updateUsdPublish(in int publishId, in byte[] serviceSpecificInfo); 306 307 /** 308 * Cancel an existing USD publish session. 309 * |IStaInterfaceCallback.onPublishTerminated| will be called upon completion. 310 * 311 * @param publishId Identifier for the publish session to cancel. 312 * @throws ServiceSpecificException with one of the following values: 313 * |SupplicantStatusCode.FAILURE_UNKNOWN| 314 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 315 */ cancelUsdPublish(in int publishId)316 void cancelUsdPublish(in int publishId); 317 318 /** 319 * Cancel an existing USD subscribe session. 320 * |IStaInterfaceCallback.onSubscribeTerminated| will be called upon completion. 321 * 322 * @param subscribeId Identifier for the subscribe session to cancel. 323 * @throws ServiceSpecificException with one of the following values: 324 * |SupplicantStatusCode.FAILURE_UNKNOWN| 325 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 326 */ cancelUsdSubscribe(in int subscribeId)327 void cancelUsdSubscribe(in int subscribeId); 328 329 /** 330 * Send a message to a peer device across an active USD link. 331 * 332 * @param messageInfo Information for the message to be sent. 333 * @throws ServiceSpecificException with one of the following values: 334 * |SupplicantStatusCode.FAILURE_UNKNOWN| 335 * |SupplicantStatusCode.FAILURE_UNSUPPORTED| 336 */ sendUsdMessage(in UsdMessageInfo messageInfo)337 void sendUsdMessage(in UsdMessageInfo messageInfo); 338 } 339