BluetoothProfile.java revision 62c37efc9e894809b29a004c142a8e0a6b374db7 
1/*
2 * Copyright (C) 2010 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
18package android.bluetooth;
19
20import android.annotation.SdkConstant;
21import android.annotation.SdkConstant.SdkConstantType;
22
23import java.util.Set;
24
25/**
26 * Public APIs for the Bluetooth Profiles.
27 *
28 * <p> Clients should call {@link BluetoothAdapter#getProfileProxy},
29 * to get the Profile Proxy. Each public profile implements this
30 * interface.
31 */
32public interface BluetoothProfile {
33
34    /**
35     * Extra for the connection state intents of the individual profiles.
36     *
37     * This extra represents the current connection state of the profile of the
38     * Bluetooth device.
39     */
40    public static final String EXTRA_STATE = "android.bluetooth.profile.extra.STATE";
41
42    /**
43     * Extra for the connection state intents of the individual profiles.
44     *
45     * This extra represents the previous connection state of the profile of the
46     * Bluetooth device.
47     */
48    public static final String EXTRA_PREVIOUS_STATE =
49        "android.bluetooth.profile.extra.PREVIOUS_STATE";
50
51    /** The profile is in disconnected state */
52    public static final int STATE_DISCONNECTED  = 0;
53    /** The profile is in connecting state */
54    public static final int STATE_CONNECTING    = 1;
55    /** The profile is in connected state */
56    public static final int STATE_CONNECTED     = 2;
57    /** The profile is in disconnecting state */
58    public static final int STATE_DISCONNECTING = 3;
59
60    /**
61     * Headset and Handsfree profile
62     */
63    public static final int HEADSET = 1;
64    /**
65     * A2DP profile.
66     */
67    public static final int A2DP = 2;
68
69    /**
70     * Default priority for devices that we try to auto-connect to and
71     * and allow incoming connections for the profile
72     * @hide
73     **/
74    public static final int PRIORITY_AUTO_CONNECT = 1000;
75
76    /**
77     *  Default priority for devices that allow incoming
78     * and outgoing connections for the profile
79     * @hide
80     **/
81    public static final int PRIORITY_ON = 100;
82
83    /**
84     * Default priority for devices that does not allow incoming
85     * connections and outgoing connections for the profile.
86     * @hide
87     **/
88    public static final int PRIORITY_OFF = 0;
89
90    /**
91     * Default priority when not set or when the device is unpaired
92     * @hide
93     * */
94    public static final int PRIORITY_UNDEFINED = -1;
95
96    /**
97     * Initiate connection to a profile of the remote bluetooth device.
98     *
99     * <p> Currently, the system supports only 1 connection to the
100     * A2DP and Headset/Handsfree profile. The API will automatically
101     * disconnect connected devices before connecting.
102     *
103     * <p> This API returns false in scenarios like the profile on the
104     * device is already connected or Bluetooth is not turned on.
105     * When this API returns true, it is guaranteed that
106     * connection state intent for the profile will be broadcasted with
107     * the state. Users can get the connection state of the profile
108     * from this intent.
109     *
110     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
111     *
112     * @param device Remote Bluetooth Device
113     * @return false on immediate error,
114     *               true otherwise
115     * @hide
116     */
117    public boolean connect(BluetoothDevice device);
118
119    /**
120     * Initiate disconnection from a profile
121     *
122     * <p> This API will return false in scenarios like the profile on the
123     * Bluetooth device is not in connected state etc. When this API returns,
124     * true, it is guaranteed that the connection state change
125     * intent will be broadcasted with the state. Users can get the
126     * disconnection state of the profile from this intent.
127     *
128     * <p> If the disconnection is initiated by a remote device, the state
129     * will transition from {@link #STATE_CONNECTED} to
130     * {@link #STATE_DISCONNECTED}. If the disconnect is initiated by the
131     * host (local) device the state will transition from
132     * {@link #STATE_CONNECTED} to state {@link #STATE_DISCONNECTING} to
133     * state {@link #STATE_DISCONNECTED}. The transition to
134     * {@link #STATE_DISCONNECTING} can be used to distinguish between the
135     * two scenarios.
136     *
137     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
138     *
139     * @param device Remote Bluetooth Device
140     * @return false on immediate error,
141     *               true otherwise
142     * @hide
143     */
144    public boolean disconnect(BluetoothDevice device);
145
146    /**
147     * Get connected devices for this specific profile.
148     *
149     * <p> Return the set of devices which are in state {@link #STATE_CONNECTED}
150     *
151     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
152     *
153     * @return An unmodifiable set of devices. The set will be empty on error.
154     */
155    public Set<BluetoothDevice> getConnectedDevices();
156
157    /**
158     * Get a set of devices that match any of the given connection
159     * states.
160     *
161     * <p> If none of devices match any of the given states,
162     * an empty set will be returned.
163     *
164     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
165     *
166     * @param states Array of states. States can be one of
167     *              {@link #STATE_CONNECTED}, {@link #STATE_CONNECTING},
168     *              {@link #STATE_DISCONNECTED}, {@link #STATE_DISCONNECTING},
169     * @return An unmodifiable set of devices. The set will be empty on error.
170     */
171    public Set<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states);
172
173    /**
174     * Get the current connection state of the profile
175     *
176     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
177     *
178     * @param device Remote bluetooth device.
179     * @return State of the profile connection. One of
180     *               {@link #STATE_CONNECTED}, {@link #STATE_CONNECTING},
181     *               {@link #STATE_DISCONNECTED}, {@link #STATE_DISCONNECTING}
182     */
183    public int getConnectionState(BluetoothDevice device);
184
185    /**
186     * Set priority of the profile
187     *
188     * <p> The device should already be paired.
189     *  Priority can be one of {@link #PRIORITY_ON} or
190     * {@link #PRIORITY_OFF},
191     *
192     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
193     *
194     * @param device Paired bluetooth device
195     * @param priority
196     * @return true if priority is set, false on error
197     * @hide
198     */
199    public boolean setPriority(BluetoothDevice device, int priority);
200
201    /**
202     * Get the priority of the profile.
203     *
204     * <p> The priority can be any of:
205     * {@link #PRIORITY_AUTO_CONNECT}, {@link #PRIORITY_OFF},
206     * {@link #PRIORITY_ON}, {@link #PRIORITY_UNDEFINED}
207     *
208     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
209     *
210     * @param device Bluetooth device
211     * @return priority of the device
212     * @hide
213     */
214    public int getPriority(BluetoothDevice device);
215
216    /**
217     * An interface for notifying BluetoothProfile IPC clients when they have
218     * been connected or disconnected to the service.
219     */
220    public interface ServiceListener {
221        /**
222         * Called to notify the client when the proxy object has been
223         * connected to the service.
224         * @param profile - One of {@link #HEADSET} or
225         *                  {@link #A2DP}
226         * @param proxy - One of {@link BluetoothHeadset} or
227         *                {@link BluetoothA2dp}
228         */
229        public void onServiceConnected(int profile, BluetoothProfile proxy);
230
231        /**
232         * Called to notify the client that this proxy object has been
233         * disconnected from the service.
234         * @param profile - One of {@link #HEADSET} or
235         *                  {@link #A2DP}
236         */
237        public void onServiceDisconnected(int profile);
238    }
239}
240