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