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: RemoteDevice.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9
10 package javax.bluetooth;
11
12 import java.io.IOException;
13
14 import javax.microedition.io.Connection;
15
16 /**
17 * The <code>RemoteDevice</code> class represents a remote Bluetooth device.
18 * It provides basic
19 * information about a remote device including the device's Bluetooth address and
20 * its friendly name.
21 *
22 * @version 1.0 February 11, 2002
23 */
24 public class RemoteDevice {
25
26 /**
27 * Creates a Bluetooth device based upon its address. The Bluetooth
28 * address must be 12 hex characters long. Valid characters are 0-9, a-f,
29 * and A-F. There is no preceding "0x" in the string. For example, valid
30 * Bluetooth addresses include but are not limited to:<BR>
31 * <code>008037144297</code><BR>
32 * <code>00af8300cd0b</code><BR>
33 * <code>014bd91DA8FC</code>
34 *
35 * @param address the address of the Bluetooth device as a 12 character
36 * hex string
37 *
38 * @exception NullPointerException if <code>address</code> is
39 * <code>null</code>
40 *
41 * @exception IllegalArgumentException if <code>address</code> is the
42 * address of the local device or is not a valid Bluetooth address
43 */
44 protected RemoteDevice(String address) {
45 if(address == null) {
46 throw new NullPointerException("address is null");
47 }
48 throw new RuntimeException("Can't initialize bluetooth support");
49 }
50
51 /**
52 * Determines if this is a trusted device according to the BCC.
53 *
54 * @return <code>true</code> if the device is a trusted device, otherwise
55 * <code>false</code>
56 */
57 public boolean isTrustedDevice() {
58 return false;
59 }
60
61 /**
62 * Returns the name of this device. The Bluetooth
63 * specification calls this name the "Bluetooth device name" or the
64 * "user-friendly name". This method will only contact
65 * the remote device if the name is not known or
66 * <code>alwaysAsk</code> is <code>true</code>.
67 *
68 * @param alwaysAsk if <code>true</code> then the device will be
69 * contacted for its name, otherwise, if there exists a known
70 * name for this device, the name will be returned without
71 * contacting the remote device
72 *
73 * @return the name of the device, or <code>null</code> if the
74 * Bluetooth system does not support this feature; if the local device
75 * is able to contact the remote device, the result will never be
76 * <code>null</code>; if the remote device does not have a name
77 * then an empty string will be returned
78 *
79 * @exception IOException if the remote device can not be contacted or the
80 * remote device could not provide its name
81 */
82 public String getFriendlyName(boolean alwaysAsk) throws IOException {
83 return null;
84 }
85
86 /**
87 * Retrieves the Bluetooth address of this device. The Bluetooth address
88 * will be 12 characters long. Valid characters are 0-9 and A-F. This
89 * method will never return <code>null</code>.
90 *
91 * @return the Bluetooth address of the remote device
92 */
93 public final String getBluetoothAddress() {
94 return null;
95 }
96
97 /**
98 * Determines if two <code>RemoteDevice</code>s are equal. Two devices are
99 * equal if they have the same Bluetooth device address.
100 *
101 * @param obj the object to compare to
102 *
103 * @return <code>true</code> if both devices have the same Bluetooth
104 * address; <code>false</code> if both devices do not have the same address;
105 * <code>false</code> if <code>obj</code> is <code>null</code>;
106 * <code>false</code> if <code>obj</code> is not a
107 * <code>RemoteDevice</code>
108 */
109 public boolean equals(Object obj) {
110 return false;
111 }
112
113 /**
114 * Computes the hash code for this object. This method will return the
115 * same value when it is called multiple times on the same object.
116 *
117 * @return the hash code for this object
118 */
119 public int hashCode() {
120 return 0;
121 }
122
123 /**
124 * Retrieves the Bluetooth device that is at the other end of the Bluetooth
125 * Serial Port Profile connection, L2CAP connection, or OBEX over RFCOMM
126 * connection provided. This method will never return <code>null</code>.
127 *
128 * @param conn the Bluetooth Serial Port connection, L2CAP connection,
129 * or OBEX over RFCOMM connection whose remote Bluetooth device is needed
130 *
131 * @return the remote device involved in the connection
132 *
133 * @exception IllegalArgumentException if <code>conn</code> is not a
134 * Bluetooth Serial Port Profile connection, L2CAP connection, or OBEX
135 * over RFCOMM connection; if <code>conn</code> is a
136 * <code>L2CAPConnectionNotifier</code>,
137 * <code>StreamConnectionNotifier</code>, or
138 * <code>SessionNotifier</code>
139 *
140 * @exception IOException if the connection is closed
141 *
142 * @exception NullPointerException if <code>conn</code> is
143 * <code>null</code>
144 */
145 public static RemoteDevice getRemoteDevice(Connection conn) throws IOException {
146 return null;
147 }
148
149 /**
150 * Attempts to authenticate this <code>RemoteDevice</code>.
151 * Authentication is a means of verifying the identity of a remote
152 * device. Authentication involves a device-to-device challenge and
153 * response scheme that requires a 128-bit common secret link key
154 * derived from a PIN code shared by both devices. If either side's
155 * PIN code does not match, the authentication process fails and the
156 * method returns <code>false</code>. The method will also return
157 * <code>false</code> if authentication is incompatible with the
158 * current security settings of the local device established by the
159 * BCC, if the stack does not
160 * support authentication at all, or if the stack does not support
161 * authentication subsequent to connection establishment.
162 *
163 * <p> If this <code>RemoteDevice</code> has previously been
164 * authenticated, then this method returns <code>true</code>
165 * without attempting to re-authenticate this
166 * <code>RemoteDevice</code>.
167 *
168 * @return <code>true</code> if authentication is successful;
169 * otherwise <code>false</code>
170 *
171 * @exception IOException if there are no open connections between
172 * the local device and this <code>RemoteDevice</code>
173 */
174 public boolean authenticate() throws IOException {
175 return false;
176 }
177
178 /**
179 * Determines if this <code>RemoteDevice</code> should be allowed
180 * to continue to access the local service provided by the
181 * <code>Connection</code>. In Bluetooth, authorization is
182 * defined as the process of deciding if device X is allowed to
183 * access service Y. The implementation of the
184 * <code>authorize(Connection conn)</code> method asks the
185 * Bluetooth Control Center (BCC) to decide if it is acceptable
186 * for <code>RemoteDevice</code> to continue to access a local
187 * service over the connection <code>conn</code>. In devices with
188 * a user interface, the BCC is expected to consult with the user
189 * to obtain approval.
190 *
191 * <p> Some Bluetooth systems may allow the user to permanently
192 * authorize a remote device for all local services. When a device
193 * is authorized in this way, it is known as a "trusted device"
194 * -- see {@link #isTrustedDevice() isTrustedDevice()}.
195 *
196 * <p> The <code>authorize()</code> method will also check that the
197 * identity of the <code>RemoteDevice</code> can be verified through authentication.
198 * If this <code>RemoteDevice</code> has been authorized for
199 * <code>conn</code> previously, then this method returns
200 * <code>true</code> without attempting to re-authorize this
201 * <code>RemoteDevice</code>.
202 *
203 * @see #isTrustedDevice
204 *
205 * @param conn the connection that this <code>RemoteDevice</code> is
206 * using to access a local service
207 *
208 * @return <code>true</code> if this <code>RemoteDevice</code> is
209 * successfully authenticated and authorized, otherwise
210 * <code>false</code> if authentication or authorization fails
211 *
212 * @exception IllegalArgumentException if <code>conn</code> is not
213 * a connection to this <code>RemoteDevice</code>, or if the local
214 * device initiated the connection, i.e., the local device is the
215 * client rather than the server. This exception is also thrown if
216 * <code>conn</code> was created by <code>RemoteDevice</code>
217 * using a scheme other than <code>btspp</code>,
218 * <code>btl2cap</code>, or <code>btgoep</code>. This exception
219 * is thrown if <code>conn</code> is a notifier used by a server
220 * to wait for a client connection, since the notifier is not a
221 * connection to this <code>RemoteDevice</code>.
222 *
223 * @exception IOException if <code>conn</code> is closed
224 */
225 public boolean authorize(javax.microedition.io.Connection conn) throws IOException {
226 return false;
227 }
228
229 /**
230 * Attempts to turn encryption on or off for an existing
231 * connection. In the case where the parameter <code>on</code> is
232 * <code>true</code>, this method will first authenticate this
233 * <code>RemoteDevice</code> if it has not already been
234 * authenticated. Then it will attempt to turn on encryption. If
235 * the connection is already encrypted then this method
236 * returns <code>true</code>. Otherwise, when the parameter <code>on</code>
237 * is <code>true</code>, either: <UL> <LI> the method succeeds in
238 * turning on encryption for the connection and returns
239 * <code>true</code>, or <LI> the method was unsuccessful in
240 * turning on encryption and returns <code>false</code>. This
241 * could happen because the stack does not support encryption or
242 * because encryption conflicts with the user's security settings
243 * for the device. </UL>
244 *
245 * <p> In the case where the parameter <code>on</code> is
246 * <code>false</code>, there are again two possible outcomes: <UL>
247 * <LI> encryption is turned off on the connection and
248 * <code>true</code> is returned, or <LI> encryption is left on
249 * for the connection and <code>false</code> is returned. </UL>
250 * Encryption may be left on following <code>encrypt(conn,
251 * false)</code> for a variety of reasons. The user's current
252 * security settings for the device may require encryption or the
253 * stack may not have a mechanism to turn off encryption. Also,
254 * the BCC may have determined that encryption will be kept on for
255 * the physical link to this <code>RemoteDevice</code>. The
256 * details of the BCC are implementation dependent, but encryption
257 * might be left on because other connections to the same device
258 * need encryption. (All of the connections over the same
259 * physical link must be encrypted if any of them are encrypted.)
260 *
261 * <p> While attempting to turn encryption off may not succeed
262 * immediately because other connections need encryption on, there
263 * may be a delayed effect. At some point, all of the connections
264 * over this physical link needing encryption could be closed or
265 * also have had the method <code>encrypt(conn, false)</code>
266 * invoked for them. In this case, the BCC may turn off
267 * encryption for all connections over this physical link. (The
268 * policy used by the BCC is implementation dependent.) It is
269 * recommended that applications do <code>encrypt(conn,
270 * false)</code> once they no longer need encryption to allow the
271 * BCC to determine if it can reduce the overhead on connections
272 * to this <code>RemoteDevice</code>.
273 *
274 * <p> The fact that <code>encrypt(conn, false)</code> may not
275 * succeed in turning off encryption has very few consequences for
276 * applications. The stack handles encryption and decryption, so
277 * the application does not have to do anything different
278 * depending on whether the connection is still encrypted or not.
279 *
280 * @param conn the connection whose need for encryption has changed
281 *
282 * @param on <code>true</code> attempts to turn on encryption;
283 * <code>false</code> attempts to turn off encryption
284 *
285 * @return <code>true</code> if the change succeeded, otherwise
286 * <code>false</code> if it failed
287 *
288 * @exception IOException if <code>conn</code> is closed
289 *
290 * @exception IllegalArgumentException if <code>conn</code> is not
291 * a connection to this <code>RemoteDevice</code>; if <code>conn</code> was
292 * created by the
293 * client side of the connection using a scheme other than
294 * <code>btspp</code>, <code>btl2cap</code>, or
295 * <code>btgoep</code> (for example, this exception will be
296 * thrown if <code>conn</code> was created using the
297 * <code>file</code> or <code>http</code> schemes.);
298 * if <code>conn</code> is a notifier used by a server
299 * to wait for a client connection, since the notifier is not a
300 * connection to this <code>RemoteDevice</code>
301 */
302 public boolean encrypt(javax.microedition.io.Connection conn, boolean on) throws IOException {
303 return false;
304 }
305
306 /**
307 * Determines if this <code>RemoteDevice</code> has been
308 * authenticated.
309 * <P>
310 * A device may have been authenticated by this application
311 * or another application. Authentication applies to an ACL link between
312 * devices and not on a specific L2CAP, RFCOMM, or OBEX connection.
313 * Therefore, if <code>authenticate()</code> is performed when an L2CAP
314 * connection is made to device A, then <code>isAuthenticated()</code> may
315 * return <code>true</code> when tested as part of making an RFCOMM
316 * connection to device A.
317 *
318 * @return <code>true</code> if this <code>RemoteDevice</code> has
319 * previously been authenticated; <code>false</code> if it has not
320 * been authenticated or there are no open connections between the
321 * local device and this <code>RemoteDevice</code>
322 */
323 public boolean isAuthenticated() {
324 return false;
325 }
326
327 /**
328 * Determines if this <code>RemoteDevice</code> has been
329 * authorized previously by the BCC of the local device to
330 * exchange data related to the service associated with the
331 * connection. Both clients and servers can call this method.
332 * However, for clients this method returns <code>false</code> for
333 * all legal values of the <code>conn</code> argument.
334 *
335 * @param conn a connection that this <code>RemoteDevice</code> is
336 * using to access a service or provide a service
337 *
338 * @return <code>true</code> if <code>conn</code> is a server-side
339 * connection and this <code>RemoteDevice</code> has been
340 * authorized; <code>false</code> if <code>conn</code> is a
341 * client-side connection, or a server-side connection that has not
342 * been authorized
343 *
344 * @exception IllegalArgumentException if <code>conn</code> is not
345 * a connection to this <code>RemoteDevice</code>; if
346 * <code>conn</code> was not created using one of the schemes
347 * <code>btspp</code>, <code>btl2cap</code>, or
348 * <code>btgoep</code>; or if <code>conn</code> is a notifier
349 * used by a server to wait for a client connection, since the
350 * notifier is not a connection to this <code>RemoteDevice</code>.
351 *
352 * @exception IOException if <code>conn</code> is closed
353 */
354 public boolean isAuthorized(javax.microedition.io.Connection conn) throws IOException {
355 return false;
356 }
357
358 /**
359 * Determines if data exchanges with this <code>RemoteDevice</code>
360 * are currently being encrypted.
361 * <P>
362 * Encryption may have been previously turned on by this or another
363 * application. Encryption applies to an ACL link
364 * between devices and not on a specific L2CAP, RFCOMM, or OBEX connection.
365 * Therefore, if <code>encrypt()</code> is performed with the
366 * <code>on</code> parameter set to <code>true</code> when an L2CAP
367 * connection is made to device A, then <code>isEncrypted()</code> may
368 * return <code>true</code> when tested as part of making an RFCOMM
369 * connection to device A.
370 *
371 * @return <code>true</code> if data exchanges with this
372 * <code>RemoteDevice</code> are being encrypted; <code>false</code>
373 * if they are not being encrypted, or there are no open connections
374 * between the local device and this <code>RemoteDevice</code>
375 */
376 public boolean isEncrypted() {
377 return false;
378 }
379
380 }