javax.bluetooth.RemoteDevice Maven / Gradle / Ivy
/**
* BlueCove - Java library for Bluetooth
* Copyright (C) 2004 Intel Corporation
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*
* 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.
*
*
* @version $Id: RemoteDevice.java 816 2007-07-22 16:08:00Z skarzhevskyy $
*/
package javax.bluetooth;
import java.io.IOException;
import javax.microedition.io.Connection;
import com.intel.bluetooth.DebugLog;
import com.intel.bluetooth.NotImplementedError;
import com.intel.bluetooth.NotImplementedIOException;
import com.intel.bluetooth.RemoteDeviceHelper;
/**
* The RemoteDevice class represents a remote Bluetooth device.
* It provides basic
* information about a remote device including the device's Bluetooth address and
* its friendly name.
*
* @version 1.0 February 11, 2002
*/
public class RemoteDevice {
/**
* A bluetooth hex address
*/
private String addressStr;
/**
* A bluetooth address for internal use
*/
private long addressLong;
/**
* Creates a Bluetooth device based upon its address. The Bluetooth
* address must be 12 hex characters long. Valid characters are 0-9, a-f,
* and A-F. There is no preceding "0x" in the string. For example, valid
* Bluetooth addresses include but are not limited to:
* 008037144297
* 00af8300cd0b
* 014bd91DA8FC
*
* @param address the address of the Bluetooth device as a 12 character
* hex string
*
* @exception NullPointerException if address is
* null
*
* @exception IllegalArgumentException if address is the
* address of the local device or is not a valid Bluetooth address
*/
protected RemoteDevice(String address) {
if(address == null) {
throw new NullPointerException("address is null");
}
String errorMsg = "Malformed address: " + address;
if(address.length() != 12) {
throw new IllegalArgumentException(errorMsg);
}
if(address.startsWith("-")) {
throw new IllegalArgumentException(errorMsg);
}
DebugLog.debug("new RemoteDevice", address);
this.addressStr = RemoteDeviceHelper.getBluetoothAddress(address);
try {
if (this.addressStr.equals(LocalDevice.getLocalDevice().getBluetoothAddress())) {
throw new IllegalArgumentException("can't use the LocalDevice address.");
}
} catch (BluetoothStateException e) {
throw new RuntimeException("Can't initialize bluetooth support");
}
this.addressLong = RemoteDeviceHelper.getAddress(address);
}
/**
* Determines if this is a trusted device according to the BCC.
*
* @return true if the device is a trusted device, otherwise
* false
*/
public boolean isTrustedDevice() {
return RemoteDeviceHelper.isTrustedDevice(this);
}
/**
* Returns the name of this device. The Bluetooth
* specification calls this name the "Bluetooth device name" or the
* "user-friendly name". This method will only contact
* the remote device if the name is not known or
* alwaysAsk is true.
*
* @param alwaysAsk if true then the device will be
* contacted for its name, otherwise, if there exists a known
* name for this device, the name will be returned without
* contacting the remote device
*
* @return the name of the device, or null if the
* Bluetooth system does not support this feature; if the local device
* is able to contact the remote device, the result will never be
* null; if the remote device does not have a name
* then an empty string will be returned
*
* @exception IOException if the remote device can not be contacted or the
* remote device could not provide its name
*/
public String getFriendlyName(boolean alwaysAsk) throws IOException {
return RemoteDeviceHelper.getFriendlyName(this, this.addressLong, alwaysAsk);
}
/**
* Retrieves the Bluetooth address of this device. The Bluetooth address
* will be 12 characters long. Valid characters are 0-9 and A-F. This
* method will never return null.
*
* @return the Bluetooth address of the remote device
*/
public final String getBluetoothAddress() {
return this.addressStr;
}
/**
* Determines if two RemoteDevices are equal. Two devices are
* equal if they have the same Bluetooth device address.
*
* @param obj the object to compare to
*
* @return true if both devices have the same Bluetooth
* address; false if both devices do not have the same address;
* false if obj is null;
* false if obj is not a
* RemoteDevice
*/
public boolean equals(Object obj) {
return obj != null && obj instanceof RemoteDevice && ((RemoteDevice) obj).addressLong == addressLong;
}
/**
* Computes the hash code for this object. This method will return the
* same value when it is called multiple times on the same object.
*
* @return the hash code for this object
*/
public int hashCode() {
return new Long(addressLong).hashCode();
}
/**
* Retrieves the Bluetooth device that is at the other end of the Bluetooth
* Serial Port Profile connection, L2CAP connection, or OBEX over RFCOMM
* connection provided. This method will never return null.
*
* @param conn the Bluetooth Serial Port connection, L2CAP connection,
* or OBEX over RFCOMM connection whose remote Bluetooth device is needed
*
* @return the remote device involved in the connection
*
* @exception IllegalArgumentException if conn is not a
* Bluetooth Serial Port Profile connection, L2CAP connection, or OBEX
* over RFCOMM connection; if conn is a
* L2CAPConnectionNotifier,
* StreamConnectionNotifier, or
* SessionNotifier
*
* @exception IOException if the connection is closed
*
* @exception NullPointerException if conn is
* null
*/
public static RemoteDevice getRemoteDevice(Connection conn) throws IOException {
return RemoteDeviceHelper.getRemoteDevice(conn);
}
/**
* Attempts to authenticate this RemoteDevice.
* Authentication is a means of verifying the identity of a remote
* device. Authentication involves a device-to-device challenge and
* response scheme that requires a 128-bit common secret link key
* derived from a PIN code shared by both devices. If either side's
* PIN code does not match, the authentication process fails and the
* method returns false. The method will also return
* false if authentication is incompatible with the
* current security settings of the local device established by the
* BCC, if the stack does not
* support authentication at all, or if the stack does not support
* authentication subsequent to connection establishment.
*
* If this RemoteDevice has previously been
* authenticated, then this method returns true
* without attempting to re-authenticate this
* RemoteDevice.
*
* @return true if authentication is successful;
* otherwise false
*
* @exception IOException if there are no open connections between
* the local device and this RemoteDevice
*/
public boolean authenticate() throws IOException {
if (NotImplementedError.enabled) {
throw new NotImplementedIOException();
} else {
return false;
}
}
/**
* Determines if this RemoteDevice should be allowed
* to continue to access the local service provided by the
* Connection. In Bluetooth, authorization is
* defined as the process of deciding if device X is allowed to
* access service Y. The implementation of the
* authorize(Connection conn) method asks the
* Bluetooth Control Center (BCC) to decide if it is acceptable
* for RemoteDevice to continue to access a local
* service over the connection conn. In devices with
* a user interface, the BCC is expected to consult with the user
* to obtain approval.
*
*
Some Bluetooth systems may allow the user to permanently
* authorize a remote device for all local services. When a device
* is authorized in this way, it is known as a "trusted device"
* -- see {@link #isTrustedDevice() isTrustedDevice()}.
*
*
The authorize() method will also check that the
* identity of the RemoteDevice can be verified through authentication.
* If this RemoteDevice has been authorized for
* conn previously, then this method returns
* true without attempting to re-authorize this
* RemoteDevice.
*
* @see #isTrustedDevice
*
* @param conn the connection that this RemoteDevice is
* using to access a local service
*
* @return true if this RemoteDevice is
* successfully authenticated and authorized, otherwise
* false if authentication or authorization fails
*
* @exception IllegalArgumentException if conn is not
* a connection to this RemoteDevice, or if the local
* device initiated the connection, i.e., the local device is the
* client rather than the server. This exception is also thrown if
* conn was created by RemoteDevice
* using a scheme other than btspp,
* btl2cap, or btgoep. This exception
* is thrown if conn is a notifier used by a server
* to wait for a client connection, since the notifier is not a
* connection to this RemoteDevice.
*
* @exception IOException if conn is closed
*/
public boolean authorize(javax.microedition.io.Connection conn) throws IOException {
if (NotImplementedError.enabled) {
throw new NotImplementedIOException();
} else {
return false;
}
}
/**
* Attempts to turn encryption on or off for an existing
* connection. In the case where the parameter on is
* true, this method will first authenticate this
* RemoteDevice if it has not already been
* authenticated. Then it will attempt to turn on encryption. If
* the connection is already encrypted then this method
* returns true. Otherwise, when the parameter on
* is true, either:
- the method succeeds in
* turning on encryption for the connection and returns
*
true, or - the method was unsuccessful in
* turning on encryption and returns
false. This
* could happen because the stack does not support encryption or
* because encryption conflicts with the user's security settings
* for the device.
*
* In the case where the parameter on is
* false, there are again two possible outcomes:
* - encryption is turned off on the connection and
*
true is returned, or - encryption is left on
* for the connection and
false is returned.
* Encryption may be left on following encrypt(conn,
* false) for a variety of reasons. The user's current
* security settings for the device may require encryption or the
* stack may not have a mechanism to turn off encryption. Also,
* the BCC may have determined that encryption will be kept on for
* the physical link to this RemoteDevice. The
* details of the BCC are implementation dependent, but encryption
* might be left on because other connections to the same device
* need encryption. (All of the connections over the same
* physical link must be encrypted if any of them are encrypted.)
*
* While attempting to turn encryption off may not succeed
* immediately because other connections need encryption on, there
* may be a delayed effect. At some point, all of the connections
* over this physical link needing encryption could be closed or
* also have had the method encrypt(conn, false)
* invoked for them. In this case, the BCC may turn off
* encryption for all connections over this physical link. (The
* policy used by the BCC is implementation dependent.) It is
* recommended that applications do encrypt(conn,
* false) once they no longer need encryption to allow the
* BCC to determine if it can reduce the overhead on connections
* to this RemoteDevice.
*
*
The fact that encrypt(conn, false) may not
* succeed in turning off encryption has very few consequences for
* applications. The stack handles encryption and decryption, so
* the application does not have to do anything different
* depending on whether the connection is still encrypted or not.
*
* @param conn the connection whose need for encryption has changed
*
* @param on true attempts to turn on encryption;
* false attempts to turn off encryption
*
* @return true if the change succeeded, otherwise
* false if it failed
*
* @exception IOException if conn is closed
*
* @exception IllegalArgumentException if conn is not
* a connection to this RemoteDevice; if conn was
* created by the
* client side of the connection using a scheme other than
* btspp, btl2cap, or
* btgoep (for example, this exception will be
* thrown if conn was created using the
* file or http schemes.);
* if conn is a notifier used by a server
* to wait for a client connection, since the notifier is not a
* connection to this RemoteDevice
*/
public boolean encrypt(javax.microedition.io.Connection conn, boolean on) throws IOException {
if (NotImplementedError.enabled) {
throw new NotImplementedIOException();
} else {
return false;
}
}
/**
* Determines if this RemoteDevice has been
* authenticated.
*
* A device may have been authenticated by this application
* or another application. Authentication applies to an ACL link between
* devices and not on a specific L2CAP, RFCOMM, or OBEX connection.
* Therefore, if authenticate() is performed when an L2CAP
* connection is made to device A, then isAuthenticated() may
* return true when tested as part of making an RFCOMM
* connection to device A.
*
* @return true if this RemoteDevice has
* previously been authenticated; false if it has not
* been authenticated or there are no open connections between the
* local device and this RemoteDevice
*/
public boolean isAuthenticated() {
return RemoteDeviceHelper.isAuthenticated(this);
}
/**
* Determines if this RemoteDevice has been
* authorized previously by the BCC of the local device to
* exchange data related to the service associated with the
* connection. Both clients and servers can call this method.
* However, for clients this method returns false for
* all legal values of the conn argument.
*
* @param conn a connection that this RemoteDevice is
* using to access a service or provide a service
*
* @return true if conn is a server-side
* connection and this RemoteDevice has been
* authorized; false if conn is a
* client-side connection, or a server-side connection that has not
* been authorized
*
* @exception IllegalArgumentException if conn is not
* a connection to this RemoteDevice; if
* conn was not created using one of the schemes
* btspp, btl2cap, or
* btgoep; or if conn is a notifier
* used by a server to wait for a client connection, since the
* notifier is not a connection to this RemoteDevice.
*
* @exception IOException if conn is closed
*/
public boolean isAuthorized(javax.microedition.io.Connection conn) throws IOException {
if (NotImplementedError.enabled) {
throw new NotImplementedIOException();
}
return false;
}
/**
* Determines if data exchanges with this RemoteDevice
* are currently being encrypted.
*
* Encryption may have been previously turned on by this or another
* application. Encryption applies to an ACL link
* between devices and not on a specific L2CAP, RFCOMM, or OBEX connection.
* Therefore, if encrypt() is performed with the
* on parameter set to true when an L2CAP
* connection is made to device A, then isEncrypted() may
* return true when tested as part of making an RFCOMM
* connection to device A.
*
* @return true if data exchanges with this
* RemoteDevice are being encrypted; false
* if they are not being encrypted, or there are no open connections
* between the local device and this RemoteDevice
*/
public boolean isEncrypted() {
return RemoteDeviceHelper.isEncrypted(this);
}
}