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