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