1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221

/**
 *  BlueCove - Java library for Bluetooth
 *
 *  Java docs licensed under the Apache License, Version 2.0
 *  http://www.apache.org/licenses/LICENSE-2.0 
 *   (c) Copyright 2001, 2002 Motorola, Inc.  ALL RIGHTS RESERVED.
 *
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 *  
 *  @version $Id$
 */
package javax.bluetooth;

/**
 * The <code>DiscoveryListener</code> interface allows an application to receive
 * device discovery and service discovery events. This interface provides four
 * methods, two for discovering devices and two for discovering services.
 * 
 * The JSR 82 specification does not require that implementations create
 * individual threads for event delivery. Thus, if a DiscoveryListener method
 * does not return or the return is delayed, the system may be blocked. So the
 * following note is given for application developers :
 * <p>
 * 
 * The following DiscoveryListener methods SHOULD return immediately :
 * <ul>
 * <li><code>DiscoveryListener.deviceDiscovered</code></li>
 * <li><code>DiscoveryListener.inquiryCompleted</code></li>
 * <li><code>DiscoveryListener.servicesDiscovered</code></li>
 * <li><code>DiscoveryListener.serviceSearchCompleted</code></li>
 * </ul>
 * 
 */
public interface DiscoveryListener {

	/**
	 * Indicates the normal completion of device discovery. Used with the
	 * {@link #inquiryCompleted(int)} method. 
	 * <p>
	 * The value of INQUIRY_COMPLETED is 0x00 (0).
	 * 
	 * @see #inquiryCompleted(int)
	 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
	 */
	public static final int INQUIRY_COMPLETED = 0x00;

	/**
	 * Indicates device discovery has been canceled by the application and did
	 * not complete. Used with the {@link #inquiryCompleted(int)} method. 
	 * <p>
	 * The value of INQUIRY_TERMINATED is 0x05 (5).
	 * 
	 * @see  #inquiryCompleted(int)
	 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
	 * @see DiscoveryAgent#cancelInquiry(javax.bluetooth.DiscoveryListener)
	 */
	public static final int INQUIRY_TERMINATED = 0x05;

	/**
	 * Indicates that the inquiry request failed to complete normally, but was
	 * not cancelled. 
	 * <p>
	 * The value of INQUIRY_ERROR is 0x07 (7).
	 * 
	 * @see  #inquiryCompleted(int)
	 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
	 */
	public static final int INQUIRY_ERROR = 0x07;

	/**
	 * Indicates the normal completion of service discovery. Used with the
	 * {@link #serviceSearchCompleted(int, int)} method. 
	 * <p>
	 * The value of SERVICE_SEARCH_COMPLETED is 0x01 (1).
	 * 
	 * @see #serviceSearchCompleted(int, int)
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 */
	public static final int SERVICE_SEARCH_COMPLETED = 0x01;

	/**
	 * Indicates the service search has been canceled by the application and did
	 * not complete. Used with the {@link #serviceSearchCompleted(int, int)} method. 
	 * <p>
	 * The value of SERVICE_SEARCH_TERMINATED is 0x02 (2).
	 * 
	 * @see  #serviceSearchCompleted(int, int)
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 * @see DiscoveryAgent#cancelServiceSearch(int)
	 */
	public static final int SERVICE_SEARCH_TERMINATED = 0x02;

	/**
	 * Indicates the service search terminated with an error. Used with the
	 * {@link #serviceSearchCompleted(int, int)} method. 
	 * <p>
	 * The value of SERVICE_SEARCH_ERROR is 0x03 (3).
	 * 
	 * @see #serviceSearchCompleted(int, int)
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 */
	public static final int SERVICE_SEARCH_ERROR = 0x03;

	/**
	 * Indicates the service search has completed with no service records found
	 * on the device. Used with the {@link #serviceSearchCompleted(int, int)} method. 
	 * <p>
	 * The value of SERVICE_SEARCH_NO_RECORDS is 0x04 (4).
	 * 
	 * @see #serviceSearchCompleted(int, int)
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 */
	public static final int SERVICE_SEARCH_NO_RECORDS = 0x04;

	/**
	 * Indicates the service search could not be completed because the remote
	 * device provided to {@link DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener) 
	 * DiscoveryAgent.searchServices()} could not be reached.
	 * Used with the {@link #serviceSearchCompleted(int, int)} method. 
	 * <P>
	 * The value of SERVICE_SEARCH_DEVICE_NOT_REACHABLE is 0x06 (6).
	 * 
	 * @see #serviceSearchCompleted(int, int)
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 */
	public static final int SERVICE_SEARCH_DEVICE_NOT_REACHABLE = 0x06;

    /**
     * Called when a device is found during an inquiry. An inquiry searches for
     * devices that are discoverable. During Bluetooth inquiry, a Bluetooth API
     * implementation MUST report each discovered remote Bluetooth device only
     * once. In other words, a Bluetooth API implementation MUST call the
     * <code>DiscoveryListener.deviceDiscovered()</code> method only once for each
     * individual discovered remote device.
     * 
     * @param btDevice
     *            the device that was found during the inquiry
     * @param cod
     *            - the service classes, major device class, and minor device
     *            class of the remote device
     * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
     */
	public void deviceDiscovered(RemoteDevice btDevice, DeviceClass cod);

	/**
	 * Called when service(s) are found during a service search. 
	 * 
	 * @param transID the transaction ID of the service search that is posting the
	 * result 
	 * @param servRecord  a list of services found during the search request 
	 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
	 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
	 */
	public void servicesDiscovered(int transID, ServiceRecord[] servRecord);

	/**
	 * Called when a service search is completed or was terminated because of an
	 * error. Legal status values in the {@code respCode} argument include
	 * {@link #SERVICE_SEARCH_COMPLETED}, {@link #SERVICE_SEARCH_TERMINATED},
	 * {@link #SERVICE_SEARCH_ERROR}, {@link #SERVICE_SEARCH_NO_RECORDS} and
	 * {@link #SERVICE_SEARCH_DEVICE_NOT_REACHABLE}. The following table describes when
	 * each {@code respCode} will be used: 
	 * <table><tr><th>respCode</th><th>Reason</th></tr>
	 * <tr><td>{@link #SERVICE_SEARCH_COMPLETED}</td>
	 * 			<td>if the service search completed normally</td></tr>
	 * <tr><td>{@link #SERVICE_SEARCH_TERMINATED}</td>
	 * 			<td>if the service search request was cancelled by a call to
	 * 			{@link DiscoveryAgent#cancelServiceSearch(int)}</td></tr>
	 * <tr><td>{@link #SERVICE_SEARCH_ERROR}</td>
	 * 			<td>if an error occurred while processing the request</td></tr>
	 * <tr><td>{@link #SERVICE_SEARCH_NO_RECORDS}</td>
	 * 			<td>if no records were found during the service search</td></tr>
	 * <tr><td>{@link #SERVICE_SEARCH_DEVICE_NOT_REACHABLE}</td>
	 * 			<td>if the device specified in the search request could not be reached or 
	 * 			the local device could not establish a connection to the remote device
	 * </td></tr></table>
	 * 
	 * @param transID the transaction ID identifying the request which
	 * initiated the service search 
	 * @param respCode  the response code that indicates the status of the transaction
	 */
	public void serviceSearchCompleted(int transID, int respCode);

	/**
	 * Called when an inquiry is completed. The {@code discType} will be
	 * {@link #INQUIRY_COMPLETED} if the inquiry ended normally or {@link #INQUIRY_TERMINATED}
	 * if the inquiry was canceled by a call to 
	 * {@link DiscoveryAgent#cancelInquiry(DiscoveryListener)}. The {@code discType} will be 
	 * {@link #INQUIRY_ERROR} if an error occurred while processing the inquiry causing the 
	 * inquiry to end abnormally. 
	 * 
	 * @param discType the type of request that was completed; either 
	 * 				{@link #INQUIRY_COMPLETED}, {@link #INQUIRY_TERMINATED}, 
	 * 				or {@link #INQUIRY_ERROR}
	 * @see #INQUIRY_COMPLETED
	 * @see #INQUIRY_TERMINATED
	 * @see #INQUIRY_ERROR
	 */
	public void inquiryCompleted(int discType);
}