1 /* 2 * Copyright (C) 2010-2016 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.bluetooth; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.RequiresNoPermission; 22 import android.annotation.SuppressLint; 23 import android.annotation.SystemApi; 24 import android.compat.annotation.UnsupportedAppUsage; 25 import android.os.Build; 26 import android.os.IBinder; 27 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 import java.util.List; 31 32 /** 33 * Public APIs for the Bluetooth Profiles. 34 * 35 * <p>Clients should call {@link BluetoothAdapter#getProfileProxy}, to get the Profile Proxy. Each 36 * public profile implements this interface. 37 */ 38 public interface BluetoothProfile { 39 40 /** 41 * Extra for the connection state intents of the individual profiles. 42 * 43 * <p>This extra represents the current connection state of the profile of the Bluetooth device. 44 */ 45 @SuppressLint("ActionValue") 46 String EXTRA_STATE = "android.bluetooth.profile.extra.STATE"; 47 48 /** 49 * Extra for the connection state intents of the individual profiles. 50 * 51 * <p>This extra represents the previous connection state of the profile of the Bluetooth 52 * device. 53 */ 54 @SuppressLint("ActionValue") 55 String EXTRA_PREVIOUS_STATE = "android.bluetooth.profile.extra.PREVIOUS_STATE"; 56 57 /** The profile is in disconnected state */ 58 int STATE_DISCONNECTED = 0; 59 60 /** The profile is in connecting state */ 61 int STATE_CONNECTING = 1; 62 63 /** The profile is in connected state */ 64 int STATE_CONNECTED = 2; 65 66 /** The profile is in disconnecting state */ 67 int STATE_DISCONNECTING = 3; 68 69 /** @hide */ 70 @IntDef({ 71 STATE_DISCONNECTED, 72 STATE_CONNECTING, 73 STATE_CONNECTED, 74 STATE_DISCONNECTING, 75 }) 76 @Retention(RetentionPolicy.SOURCE) 77 public @interface BtProfileState {} 78 79 /** Headset and Handsfree profile */ 80 int HEADSET = 1; 81 82 /** A2DP profile. */ 83 int A2DP = 2; 84 85 /** 86 * Health Profile 87 * 88 * @deprecated Health Device Profile (HDP) and MCAP protocol are no longer used. New apps should 89 * use Bluetooth Low Energy based solutions such as {@link BluetoothGatt}, {@link 90 * BluetoothAdapter#listenUsingL2capChannel()}, or {@link 91 * BluetoothDevice#createL2capChannel(int)} 92 */ 93 @Deprecated int HEALTH = 3; 94 95 /** 96 * HID Host 97 * 98 * @hide 99 */ 100 @SystemApi int HID_HOST = 4; 101 102 /** 103 * PAN Profile 104 * 105 * @hide 106 */ 107 @SystemApi int PAN = 5; 108 109 /** 110 * PBAP 111 * 112 * @hide 113 */ 114 @SystemApi int PBAP = 6; 115 116 /** GATT */ 117 int GATT = 7; 118 119 /** GATT_SERVER */ 120 int GATT_SERVER = 8; 121 122 /** 123 * MAP Profile 124 * 125 * @hide 126 */ 127 @SystemApi int MAP = 9; 128 129 /* 130 * SAP Profile 131 * @hide 132 */ 133 int SAP = 10; 134 135 /** 136 * A2DP Sink Profile 137 * 138 * @hide 139 */ 140 @SystemApi int A2DP_SINK = 11; 141 142 /** 143 * AVRCP Controller Profile 144 * 145 * @hide 146 */ 147 @SystemApi int AVRCP_CONTROLLER = 12; 148 149 /** 150 * AVRCP Target Profile 151 * 152 * @hide 153 */ 154 int AVRCP = 13; 155 156 /** 157 * Headset Client - HFP HF Role 158 * 159 * @hide 160 */ 161 @SystemApi int HEADSET_CLIENT = 16; 162 163 /** 164 * PBAP Client 165 * 166 * @hide 167 */ 168 @SystemApi int PBAP_CLIENT = 17; 169 170 /** 171 * MAP Messaging Client Equipment (MCE) 172 * 173 * @hide 174 */ 175 @SystemApi int MAP_CLIENT = 18; 176 177 /** HID Device */ 178 int HID_DEVICE = 19; 179 180 /** 181 * Object Push Profile (OPP) 182 * 183 * @hide 184 */ 185 @SystemApi int OPP = 20; 186 187 /** Hearing Aid Device */ 188 int HEARING_AID = 21; 189 190 /** LE Audio Device */ 191 int LE_AUDIO = 22; 192 193 /** 194 * Volume Control profile 195 * 196 * @hide 197 */ 198 @SystemApi int VOLUME_CONTROL = 23; 199 200 /** 201 * @hide Media Control Profile server 202 */ 203 int MCP_SERVER = 24; 204 205 /** Coordinated Set Identification Profile set coordinator */ 206 int CSIP_SET_COORDINATOR = 25; 207 208 /** 209 * LE Audio Broadcast Source 210 * 211 * @hide 212 */ 213 @SystemApi int LE_AUDIO_BROADCAST = 26; 214 215 /** 216 * @hide Telephone Bearer Service from Call Control Profile 217 */ 218 int LE_CALL_CONTROL = 27; 219 220 /* 221 * Hearing Access Profile Client 222 * 223 */ 224 int HAP_CLIENT = 28; 225 226 /** 227 * LE Audio Broadcast Assistant 228 * 229 * @hide 230 */ 231 @SystemApi int LE_AUDIO_BROADCAST_ASSISTANT = 29; 232 233 /** 234 * Battery Service 235 * 236 * @hide 237 */ 238 int BATTERY = 30; 239 240 /** 241 * Max profile ID. This value should be updated whenever a new profile is added to match the 242 * largest value assigned to a profile. 243 * 244 * @hide 245 */ 246 int MAX_PROFILE_ID = 30; 247 248 /** 249 * Default priority for devices that we try to auto-connect to and allow incoming connections 250 * for the profile 251 * 252 * @hide 253 */ 254 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 255 int PRIORITY_AUTO_CONNECT = 1000; 256 257 /** 258 * Default priority for devices that allow incoming and outgoing connections for the profile 259 * 260 * @hide 261 * @deprecated Replaced with {@link #CONNECTION_POLICY_ALLOWED} 262 */ 263 @Deprecated @SystemApi int PRIORITY_ON = 100; 264 265 /** 266 * Default priority for devices that does not allow incoming connections and outgoing 267 * connections for the profile. 268 * 269 * @hide 270 * @deprecated Replaced with {@link #CONNECTION_POLICY_FORBIDDEN} 271 */ 272 @Deprecated @SystemApi int PRIORITY_OFF = 0; 273 274 /** 275 * Default priority when not set or when the device is unpaired 276 * 277 * @hide 278 */ 279 @UnsupportedAppUsage int PRIORITY_UNDEFINED = -1; 280 281 /** @hide */ 282 @IntDef( 283 prefix = "CONNECTION_POLICY_", 284 value = { 285 CONNECTION_POLICY_ALLOWED, 286 CONNECTION_POLICY_FORBIDDEN, 287 CONNECTION_POLICY_UNKNOWN 288 }) 289 @Retention(RetentionPolicy.SOURCE) 290 public @interface ConnectionPolicy {} 291 292 /** 293 * Default connection policy for devices that allow incoming and outgoing connections for the 294 * profile 295 * 296 * @hide 297 */ 298 @SystemApi int CONNECTION_POLICY_ALLOWED = 100; 299 300 /** 301 * Default connection policy for devices that do not allow incoming or outgoing connections for 302 * the profile. 303 * 304 * @hide 305 */ 306 @SystemApi int CONNECTION_POLICY_FORBIDDEN = 0; 307 308 /** 309 * Default connection policy when not set or when the device is unpaired 310 * 311 * @hide 312 */ 313 @SystemApi int CONNECTION_POLICY_UNKNOWN = -1; 314 315 /** 316 * Get connected devices for this specific profile. 317 * 318 * <p>Return the set of devices which are in state {@link #STATE_CONNECTED} 319 * 320 * @return List of devices. The list will be empty on error. 321 */ getConnectedDevices()322 List<BluetoothDevice> getConnectedDevices(); 323 324 /** 325 * Get a list of devices that match any of the given connection states. 326 * 327 * <p>If none of the devices match any of the given states, an empty list will be returned. 328 * 329 * @param states Array of states. States can be one of {@link #STATE_CONNECTED}, {@link 330 * #STATE_CONNECTING}, {@link #STATE_DISCONNECTED}, {@link #STATE_DISCONNECTING}, 331 * @return List of devices. The list will be empty on error. 332 */ getDevicesMatchingConnectionStates(int[] states)333 List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states); 334 335 /** 336 * Get the current connection state of the profile 337 * 338 * @param device Remote bluetooth device. 339 * @return State of the profile connection. One of {@link #STATE_CONNECTED}, {@link 340 * #STATE_CONNECTING}, {@link #STATE_DISCONNECTED}, {@link #STATE_DISCONNECTING} 341 */ 342 @BtProfileState getConnectionState(BluetoothDevice device)343 int getConnectionState(BluetoothDevice device); 344 345 /** 346 * Called by the BluetoothAdapter when the Bluetooth service is connected with a Binder instance 347 * corresponding to the service associated with the profile 348 * 349 * @hide 350 */ onServiceConnected(IBinder service)351 void onServiceConnected(IBinder service); 352 353 /** 354 * Called by the BluetoothAdapter when the Bluetooth service connection has been lost 355 * 356 * @hide 357 */ onServiceDisconnected()358 void onServiceDisconnected(); 359 360 /** 361 * Get the BluetoothAdapter that created this proxy 362 * 363 * @hide 364 */ getAdapter()365 BluetoothAdapter getAdapter(); 366 367 /** 368 * An interface for notifying BluetoothProfile IPC clients when they have been connected or 369 * disconnected to the service. 370 */ 371 public interface ServiceListener { 372 /** 373 * Called to notify the client when the proxy object has been connected to the service. 374 * 375 * @param profile - One of {@link #HEADSET} or {@link #A2DP} 376 * @param proxy - One of {@link BluetoothHeadset} or {@link BluetoothA2dp} 377 */ 378 @RequiresNoPermission onServiceConnected(int profile, BluetoothProfile proxy)379 void onServiceConnected(int profile, BluetoothProfile proxy); 380 381 /** 382 * Called to notify the client that this proxy object has been disconnected from the 383 * service. 384 * 385 * @param profile - One of {@link #HEADSET} or {@link #A2DP} 386 */ 387 @RequiresNoPermission onServiceDisconnected(int profile)388 void onServiceDisconnected(int profile); 389 } 390 391 /** 392 * Convert an integer value of connection state into human readable string 393 * 394 * @param connectionState - One of {@link #STATE_DISCONNECTED}, {@link #STATE_CONNECTING}, 395 * {@link #STATE_CONNECTED}, or {@link #STATE_DISCONNECTED} 396 * @return a string representation of the connection state, STATE_UNKNOWN if the state is not 397 * defined 398 * @hide 399 */ 400 @SystemApi 401 @NonNull 402 @RequiresNoPermission getConnectionStateName(int connectionState)403 static String getConnectionStateName(int connectionState) { 404 switch (connectionState) { 405 case STATE_DISCONNECTED: 406 return "STATE_DISCONNECTED"; 407 case STATE_CONNECTING: 408 return "STATE_CONNECTING"; 409 case STATE_CONNECTED: 410 return "STATE_CONNECTED"; 411 case STATE_DISCONNECTING: 412 return "STATE_DISCONNECTING"; 413 default: 414 return "STATE_UNKNOWN"; 415 } 416 } 417 418 /** 419 * Convert an integer value of profile ID into human readable string 420 * 421 * @param profile profile ID 422 * @return profile name as String, UNKNOWN_PROFILE if the profile ID is not defined. 423 * @hide 424 */ 425 @SystemApi 426 @NonNull 427 @RequiresNoPermission getProfileName(int profile)428 static String getProfileName(int profile) { 429 switch (profile) { 430 case HEADSET: 431 return "HEADSET"; 432 case A2DP: 433 return "A2DP"; 434 case HID_HOST: 435 return "HID_HOST"; 436 case PAN: 437 return "PAN"; 438 case PBAP: 439 return "PBAP"; 440 case GATT: 441 return "GATT"; 442 case GATT_SERVER: 443 return "GATT_SERVER"; 444 case MAP: 445 return "MAP"; 446 case SAP: 447 return "SAP"; 448 case A2DP_SINK: 449 return "A2DP_SINK"; 450 case AVRCP_CONTROLLER: 451 return "AVRCP_CONTROLLER"; 452 case AVRCP: 453 return "AVRCP"; 454 case HEADSET_CLIENT: 455 return "HEADSET_CLIENT"; 456 case PBAP_CLIENT: 457 return "PBAP_CLIENT"; 458 case MAP_CLIENT: 459 return "MAP_CLIENT"; 460 case HID_DEVICE: 461 return "HID_DEVICE"; 462 case OPP: 463 return "OPP"; 464 case HEARING_AID: 465 return "HEARING_AID"; 466 case LE_AUDIO: 467 return "LE_AUDIO"; 468 case VOLUME_CONTROL: 469 return "VOLUME_CONTROL"; 470 case MCP_SERVER: 471 return "MCP_SERVER"; 472 case CSIP_SET_COORDINATOR: 473 return "CSIP_SET_COORDINATOR"; 474 case LE_AUDIO_BROADCAST: 475 return "LE_AUDIO_BROADCAST"; 476 case LE_CALL_CONTROL: 477 return "LE_CALL_CONTROL"; 478 case HAP_CLIENT: 479 return "HAP_CLIENT"; 480 case LE_AUDIO_BROADCAST_ASSISTANT: 481 return "LE_AUDIO_BROADCAST_ASSISTANT"; 482 case BATTERY: 483 return "BATTERY"; 484 default: 485 return "UNKNOWN_PROFILE (" + profile + ")"; 486 } 487 } 488 } 489