1/* 2 * Copyright (C) 2013 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 17package android.bluetooth; 18 19import android.os.Parcel; 20import android.os.ParcelUuid; 21import android.os.Parcelable; 22 23import java.util.UUID; 24 25/** 26 * Represents a Bluetooth GATT Descriptor 27 * 28 * <p> GATT Descriptors contain additional information and attributes of a GATT 29 * characteristic, {@link BluetoothGattCharacteristic}. They can be used to describe 30 * the characteristic's features or to control certain behaviours of the characteristic. 31 */ 32public class BluetoothGattDescriptor implements Parcelable { 33 34 /** 35 * Value used to enable notification for a client configuration descriptor 36 */ 37 public static final byte[] ENABLE_NOTIFICATION_VALUE = {0x01, 0x00}; 38 39 /** 40 * Value used to enable indication for a client configuration descriptor 41 */ 42 public static final byte[] ENABLE_INDICATION_VALUE = {0x02, 0x00}; 43 44 /** 45 * Value used to disable notifications or indicatinos 46 */ 47 public static final byte[] DISABLE_NOTIFICATION_VALUE = {0x00, 0x00}; 48 49 /** 50 * Descriptor read permission 51 */ 52 public static final int PERMISSION_READ = 0x01; 53 54 /** 55 * Descriptor permission: Allow encrypted read operations 56 */ 57 public static final int PERMISSION_READ_ENCRYPTED = 0x02; 58 59 /** 60 * Descriptor permission: Allow reading with man-in-the-middle protection 61 */ 62 public static final int PERMISSION_READ_ENCRYPTED_MITM = 0x04; 63 64 /** 65 * Descriptor write permission 66 */ 67 public static final int PERMISSION_WRITE = 0x10; 68 69 /** 70 * Descriptor permission: Allow encrypted writes 71 */ 72 public static final int PERMISSION_WRITE_ENCRYPTED = 0x20; 73 74 /** 75 * Descriptor permission: Allow encrypted writes with man-in-the-middle 76 * protection 77 */ 78 public static final int PERMISSION_WRITE_ENCRYPTED_MITM = 0x40; 79 80 /** 81 * Descriptor permission: Allow signed write operations 82 */ 83 public static final int PERMISSION_WRITE_SIGNED = 0x80; 84 85 /** 86 * Descriptor permission: Allow signed write operations with 87 * man-in-the-middle protection 88 */ 89 public static final int PERMISSION_WRITE_SIGNED_MITM = 0x100; 90 91 /** 92 * The UUID of this descriptor. 93 * 94 * @hide 95 */ 96 protected UUID mUuid; 97 98 /** 99 * Instance ID for this descriptor. 100 * 101 * @hide 102 */ 103 protected int mInstance; 104 105 /** 106 * Permissions for this descriptor 107 * 108 * @hide 109 */ 110 protected int mPermissions; 111 112 /** 113 * Back-reference to the characteristic this descriptor belongs to. 114 * 115 * @hide 116 */ 117 protected BluetoothGattCharacteristic mCharacteristic; 118 119 /** 120 * The value for this descriptor. 121 * 122 * @hide 123 */ 124 protected byte[] mValue; 125 126 /** 127 * Create a new BluetoothGattDescriptor. 128 * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission. 129 * 130 * @param uuid The UUID for this descriptor 131 * @param permissions Permissions for this descriptor 132 */ 133 public BluetoothGattDescriptor(UUID uuid, int permissions) { 134 initDescriptor(null, uuid, 0, permissions); 135 } 136 137 /** 138 * Create a new BluetoothGattDescriptor. 139 * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission. 140 * 141 * @param characteristic The characteristic this descriptor belongs to 142 * @param uuid The UUID for this descriptor 143 * @param permissions Permissions for this descriptor 144 */ 145 /*package*/ BluetoothGattDescriptor(BluetoothGattCharacteristic characteristic, UUID uuid, 146 int instance, int permissions) { 147 initDescriptor(characteristic, uuid, instance, permissions); 148 } 149 150 /** 151 * @hide 152 */ 153 public BluetoothGattDescriptor(UUID uuid, int instance, int permissions) { 154 initDescriptor(null, uuid, instance, permissions); 155 } 156 157 private void initDescriptor(BluetoothGattCharacteristic characteristic, UUID uuid, 158 int instance, int permissions) { 159 mCharacteristic = characteristic; 160 mUuid = uuid; 161 mInstance = instance; 162 mPermissions = permissions; 163 } 164 165 @Override 166 public int describeContents() { 167 return 0; 168 } 169 170 @Override 171 public void writeToParcel(Parcel out, int flags) { 172 out.writeParcelable(new ParcelUuid(mUuid), 0); 173 out.writeInt(mInstance); 174 out.writeInt(mPermissions); 175 } 176 177 public static final Parcelable.Creator<BluetoothGattDescriptor> CREATOR = 178 new Parcelable.Creator<BluetoothGattDescriptor>() { 179 public BluetoothGattDescriptor createFromParcel(Parcel in) { 180 return new BluetoothGattDescriptor(in); 181 } 182 183 public BluetoothGattDescriptor[] newArray(int size) { 184 return new BluetoothGattDescriptor[size]; 185 } 186 }; 187 188 private BluetoothGattDescriptor(Parcel in) { 189 mUuid = ((ParcelUuid) in.readParcelable(null)).getUuid(); 190 mInstance = in.readInt(); 191 mPermissions = in.readInt(); 192 } 193 194 /** 195 * Returns the characteristic this descriptor belongs to. 196 * 197 * @return The characteristic. 198 */ 199 public BluetoothGattCharacteristic getCharacteristic() { 200 return mCharacteristic; 201 } 202 203 /** 204 * Set the back-reference to the associated characteristic 205 * 206 * @hide 207 */ 208 /*package*/ void setCharacteristic(BluetoothGattCharacteristic characteristic) { 209 mCharacteristic = characteristic; 210 } 211 212 /** 213 * Returns the UUID of this descriptor. 214 * 215 * @return UUID of this descriptor 216 */ 217 public UUID getUuid() { 218 return mUuid; 219 } 220 221 /** 222 * Returns the instance ID for this descriptor. 223 * 224 * <p>If a remote device offers multiple descriptors with the same UUID, 225 * the instance ID is used to distuinguish between descriptors. 226 * 227 * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission. 228 * 229 * @return Instance ID of this descriptor 230 * @hide 231 */ 232 public int getInstanceId() { 233 return mInstance; 234 } 235 236 /** 237 * Force the instance ID. 238 * 239 * @hide 240 */ 241 public void setInstanceId(int instanceId) { 242 mInstance = instanceId; 243 } 244 245 /** 246 * Returns the permissions for this descriptor. 247 * 248 * @return Permissions of this descriptor 249 */ 250 public int getPermissions() { 251 return mPermissions; 252 } 253 254 /** 255 * Returns the stored value for this descriptor 256 * 257 * <p>This function returns the stored value for this descriptor as 258 * retrieved by calling {@link BluetoothGatt#readDescriptor}. The cached 259 * value of the descriptor is updated as a result of a descriptor read 260 * operation. 261 * 262 * @return Cached value of the descriptor 263 */ 264 public byte[] getValue() { 265 return mValue; 266 } 267 268 /** 269 * Updates the locally stored value of this descriptor. 270 * 271 * <p>This function modifies the locally stored cached value of this 272 * descriptor. To send the value to the remote device, call 273 * {@link BluetoothGatt#writeDescriptor} to send the value to the 274 * remote device. 275 * 276 * @param value New value for this descriptor 277 * @return true if the locally stored value has been set, false if the requested value could not 278 * be stored locally. 279 */ 280 public boolean setValue(byte[] value) { 281 mValue = value; 282 return true; 283 } 284} 285