1 /**
2 * Java docs licensed under the Apache License, Version 2.0
3 * http://www.apache.org/licenses/LICENSE-2.0
4 * (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
5 *
6 *
7 * @version $Id: DiscoveryListener.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9
10 package javax.bluetooth;
11
12 /**
13 * The <code>DiscoveryListener</code> interface allows an application to
14 * receive device discovery and service discovery events. This interface
15 * provides four methods, two for discovering devices and two for discovering
16 * services.
17 *
18 * @version 1.0 February 11, 2002
19 *
20 * @since 1.1 The JSR 82 specification does not require that implementations
21 * create individual threads for event delivery. Thus, if a
22 * DiscoveryListener method does not return or the return is delayed, the
23 * system may be blocked. So the following note is given for application
24 * developers :
25 * <p>
26 *
27 * The following DiscoveryListener methods SHOULD return immediately :
28 * <ul>
29 * <li>DiscoveryListener.deviceDiscovered</li>
30 * <li>DiscoveryListener.inquiryCompleted</li>
31 * <li>DiscoveryListener.servicesDiscovered</li>
32 * <li>DiscoveryListener.serviceSearchCompleted</li>
33 * </ul>
34 *
35 */
36 public interface DiscoveryListener {
37
38 /**
39 * Indicates the normal completion of device discovery. Used with the
40 * {@link #inquiryCompleted(int)} method.
41 * <p>
42 * The value of INQUIRY_COMPLETED is 0x00 (0).
43 *
44 * @see #inquiryCompleted(int)
45 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
46 */
47 public static final int INQUIRY_COMPLETED = 0x00;
48
49 /**
50 * Indicates device discovery has been canceled by the application and did
51 * not complete. Used with the {@link #inquiryCompleted(int)} method.
52 * <p>
53 * The value of INQUIRY_TERMINATED is 0x05 (5).
54 *
55 * @see #inquiryCompleted(int)
56 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
57 * @see DiscoveryAgent#cancelInquiry(javax.bluetooth.DiscoveryListener)
58 */
59 public static final int INQUIRY_TERMINATED = 0x05;
60
61 /**
62 * Indicates that the inquiry request failed to complete normally, but was
63 * not cancelled.
64 * <p>
65 * The value of INQUIRY_ERROR is 0x07 (7).
66 *
67 * @see #inquiryCompleted(int)
68 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
69 */
70 public static final int INQUIRY_ERROR = 0x07;
71
72 /**
73 * Indicates the normal completion of service discovery. Used with the
74 * {@link #serviceSearchCompleted(int, int)} method.
75 * <p>
76 * The value of SERVICE_SEARCH_COMPLETED is 0x01 (1).
77 *
78 * @see #serviceSearchCompleted(int, int)
79 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
80 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
81 */
82 public static final int SERVICE_SEARCH_COMPLETED = 0x01;
83
84 /**
85 * Indicates the service search has been canceled by the application and did
86 * not complete. Used with the {@link #serviceSearchCompleted(int, int)} method.
87 * <p>
88 * The value of SERVICE_SEARCH_TERMINATED is 0x02 (2).
89 *
90 * @see #serviceSearchCompleted(int, int)
91 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
92 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
93 * @see DiscoveryAgent#cancelServiceSearch(int)
94 */
95 public static final int SERVICE_SEARCH_TERMINATED = 0x02;
96
97 /**
98 * Indicates the service search terminated with an error. Used with the
99 * {@link #serviceSearchCompleted(int, int)} method.
100 * <p>
101 * The value of SERVICE_SEARCH_ERROR is 0x03 (3).
102 *
103 * @see #serviceSearchCompleted(int, int)
104 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
105 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
106 */
107 public static final int SERVICE_SEARCH_ERROR = 0x03;
108
109 /**
110 * Indicates the service search has completed with no service records found
111 * on the device. Used with the {@link #serviceSearchCompleted(int, int)} method.
112 * <p>
113 * The value of SERVICE_SEARCH_NO_RECORDS is 0x04 (4).
114 *
115 * @see #serviceSearchCompleted(int, int)
116 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
117 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
118 */
119 public static final int SERVICE_SEARCH_NO_RECORDS = 0x04;
120
121 /**
122 * Indicates the service search could not be completed because the remote
123 * device provided to {@link DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
124 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
125 * DiscoveryAgent.searchServices()} could not be reached.
126 * Used with the {@link #serviceSearchCompleted(int, int)} method.
127 * <P>
128 * The value of SERVICE_SEARCH_DEVICE_NOT_REACHABLE is 0x06 (6).
129 *
130 * @see #serviceSearchCompleted(int, int)
131 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
132 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
133 */
134 public static final int SERVICE_SEARCH_DEVICE_NOT_REACHABLE = 0x06;
135
136 /**
137 * Called when a device is found during an inquiry. An inquiry searches for
138 * devices that are discoverable. The same device may be returned multiple
139 * times.
140 *
141 * @param btDevice the device that was found during the inquiry
142 * @param cod - the service classes, major device class, and minor device
143 * class of the remote device
144 * @see DiscoveryAgent#startInquiry(int, javax.bluetooth.DiscoveryListener)
145 */
146 public void deviceDiscovered(RemoteDevice btDevice, DeviceClass cod);
147
148 /**
149 * Called when service(s) are found during a service search.
150 *
151 * @param transID the transaction ID of the service search that is posting the
152 * result
153 * @param servRecord a list of services found during the search request
154 * @see DiscoveryAgent#searchServices(int[], javax.bluetooth.UUID[],
155 * javax.bluetooth.RemoteDevice, javax.bluetooth.DiscoveryListener)
156 */
157 public void servicesDiscovered(int transID, ServiceRecord[] servRecord);
158
159 /**
160 * Called when a service search is completed or was terminated because of an
161 * error. Legal status values in the {@code respCode} argument include
162 * {@link #SERVICE_SEARCH_COMPLETED}, {@link #SERVICE_SEARCH_TERMINATED},
163 * {@link #SERVICE_SEARCH_ERROR}, {@link #SERVICE_SEARCH_NO_RECORDS} and
164 * {@link #SERVICE_SEARCH_DEVICE_NOT_REACHABLE}. The following table describes when
165 * each {@code respCode} will be used:
166 * <table><tr><th>respCode</th><th>Reason</th></tr>
167 * <tr><td>{@link #SERVICE_SEARCH_COMPLETED}</td>
168 * <td>if the service search completed normally</td></tr>
169 * <tr><td>{@link #SERVICE_SEARCH_TERMINATED}</td>
170 * <td>if the service search request was cancelled by a call to
171 * {@link DiscoveryAgent#cancelServiceSearch(int)}</td></tr>
172 * <tr><td>{@link #SERVICE_SEARCH_ERROR}</td>
173 * <td>if an error occurred while processing the request</td></tr>
174 * <tr><td>{@link #SERVICE_SEARCH_NO_RECORDS}</td>
175 * <td>if no records were found during the service search</td></tr>
176 * <tr><td>{@link #SERVICE_SEARCH_DEVICE_NOT_REACHABLE}</td>
177 * <td>if the device specified in the search request could not be reached or
178 * the local device could not establish a connection to the remote device
179 * </td></tr></table>
180 *
181 * @param transID the transaction ID identifying the request which
182 * initiated the service search
183 * @param respCode the response code that indicates the status of the transaction
184 */
185 public void serviceSearchCompleted(int transID, int respCode);
186
187 /**
188 * Called when an inquiry is completed. The {@code discType} will be
189 * {@link #INQUIRY_COMPLETED} if the inquiry ended normally or {@link #INQUIRY_TERMINATED}
190 * if the inquiry was canceled by a call to
191 * {@link DiscoveryAgent#cancelInquiry(DiscoveryListener)}. The {@code discType} will be
192 * {@link #INQUIRY_ERROR} if an error occurred while processing the inquiry causing the
193 * inquiry to end abnormally.
194 *
195 * @param discType the type of request that was completed; either
196 * {@link #INQUIRY_COMPLETED}, {@link #INQUIRY_TERMINATED},
197 * or {@link #INQUIRY_ERROR}
198 * @see #INQUIRY_COMPLETED
199 * @see #INQUIRY_TERMINATED
200 * @see #INQUIRY_ERROR
201 */
202 public void inquiryCompleted(int discType);
203 }