javax.bluetooth.LocalDevice 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: LocalDevice.java 1335 2007-12-07 17:15:54Z skarzhevskyy $
*/
package javax.bluetooth;
import javax.microedition.io.Connection;
import com.intel.bluetooth.BlueCoveImpl;
import com.intel.bluetooth.BluetoothConnectionNotifierServiceRecordAccess;
import com.intel.bluetooth.BluetoothStack;
import com.intel.bluetooth.RemoteDeviceHelper;
import com.intel.bluetooth.ServiceRecordsRegistry;
/**
* The LocalDevice class defines the basic functions of the Bluetooth manager. The Bluetooth manager
* provides the lowest level of interface possible into the Bluetooth stack. It provides access to and control of the
* local Bluetooth device.
*
* This class produces a singleton object.
*
* @version 1.0 February 11, 2002
* @version 1.1 September 2, 2005
*/
public class LocalDevice {
private static LocalDevice localDevice;
private BluetoothStack bluetoothStack;
private DiscoveryAgent discoveryAgent;
private String addressStr;
/**
* The default constructor is hidden so that no one can create a new instance of the LocalDevice. To get the
* LocalDevice object for this device, use the getLocalDevice() static method in this class.
*
* @see #getLocalDevice
*/
private LocalDevice() throws BluetoothStateException {
this.bluetoothStack = BlueCoveImpl.instance().getBluetoothStack();
discoveryAgent = new DiscoveryAgent(this.bluetoothStack);
addressStr = RemoteDeviceHelper.getBluetoothAddress(this.bluetoothStack.getLocalDeviceBluetoothAddress());
}
private static synchronized LocalDevice getLocalDeviceInstance() throws BluetoothStateException {
if (localDevice == null) {
localDevice = new LocalDevice();
}
return localDevice;
}
/**
* Retrieves the LocalDevice object for the local Bluetooth device. Multiple calls to this method
* will return the same object. This method will never return null.
*
* @return an object that represents the local Bluetooth device
*
* @exception BluetoothStateException
* if the Bluetooth system could not be initialized
*/
public static LocalDevice getLocalDevice() throws BluetoothStateException {
return getLocalDeviceInstance();
}
/**
* Returns the discovery agent for this device. Multiple calls to this method will return the same object. This
* method will never return null.
*
* @return the discovery agent for the local device
*
*/
public DiscoveryAgent getDiscoveryAgent() {
return discoveryAgent;
}
/**
* Retrieves the name of the local device. The Bluetooth specification calls this name the "Bluetooth device name"
* or the "user-friendly name".
*
* @return the name of the local device; null if the name could not be retrieved
*/
public String getFriendlyName() {
return this.bluetoothStack.getLocalDeviceName();
}
/**
* Retrieves the DeviceClass object that represents the service classes, major device class, and
* minor device class of the local device. This method will return null if the service classes, major
* device class, or minor device class could not be determined.
*
* @return the service classes, major device class, and minor device class of the local device, or null
* if the service classes, major device class or minor device class could not be determined
*
*/
public DeviceClass getDeviceClass() {
return this.bluetoothStack.getLocalDeviceClass();
}
/**
* Sets the discoverable mode of the device. The mode may be any number in the range 0x9E8B00 to
* 0x9E8B3F as defined by the Bluetooth Assigned Numbers Document. When this specification was defined, only GIAC (DiscoveryAgent.GIAC)
* and LIAC (DiscoveryAgent.LIAC) were defined, but Bluetooth profiles may add additional access
* codes in the future. To determine what values may be used, check the Bluetooth Assigned Numbers document at
* http://www.bluetooth.org/assigned-numbers/baseband.htm. If DiscoveryAgent.GIAC or
* DiscoveryAgent.LIAC are provided, then this method will attempt to put the device into general or
* limited discoverable mode, respectively. To take a device out of discoverable mode, provide the
* DiscoveryAgent.NOT_DISCOVERABLE flag. The BCC decides if the request will be granted. In addition
* to the BCC, the Bluetooth system could effect the discoverability of a device.
*
* According to the Bluetooth Specification, a device should only be limited discoverable (DiscoveryAgent.LIAC)
* for 1 minute. This is handled by the implementation of the API. After the minute is up, the device will revert
* back to the previous discoverable mode.
*
* @see DiscoveryAgent#GIAC
* @see DiscoveryAgent#LIAC
* @see DiscoveryAgent#NOT_DISCOVERABLE
*
* @param mode
* the mode the device should be in; valid modes are DiscoveryAgent.GIAC,
* DiscoveryAgent.LIAC, DiscoveryAgent.NOT_DISCOVERABLE and any value in
* the range 0x9E8B00 to 0x9E8B3F
*
* @return true if the request succeeded, otherwise false if the request failed
* because the BCC denied the request; false if the Bluetooth system does not support the
* access mode specified in mode
*
* @exception IllegalArgumentException
* if the mode is not DiscoveryAgent.GIAC,
* DiscoveryAgent.LIAC, DiscoveryAgent.NOT_DISCOVERABLE, or in the
* range 0x9E8B00 to 0x9E8B3F
*
* @exception BluetoothStateException
* if the Bluetooth system is in a state that does not allow the discoverable mode to be changed
*
*/
public boolean setDiscoverable(int mode) throws BluetoothStateException {
if ((mode != DiscoveryAgent.GIAC) && (mode != DiscoveryAgent.LIAC) && (mode != DiscoveryAgent.NOT_DISCOVERABLE)
&& (mode < 0x9E8B00 || mode > 0x9E8B3F)) {
throw new IllegalArgumentException("Invalid discoverable mode");
}
return this.bluetoothStack.setLocalDeviceDiscoverable(mode);
}
/**
* Retrieves the power state of the local Bluetooth device.
*
* @since 1.1
* @return true if the local Bluetooth device is powered on, false if the local
* Bluetooth device is off.
*/
public static boolean isPowerOn() {
try {
return BlueCoveImpl.instance().getBluetoothStack().isLocalDevicePowerOn();
} catch (BluetoothStateException e) {
return false;
}
}
/**
* Retrieves the local device's discoverable mode. The return value will be DiscoveryAgent.GIAC,
* DiscoveryAgent.LIAC, DiscoveryAgent.NOT_DISCOVERABLE, or a value in the range
* 0x9E8B00 to 0x9E8B3F.
*
* @see DiscoveryAgent#GIAC
* @see DiscoveryAgent#LIAC
* @see DiscoveryAgent#NOT_DISCOVERABLE
*
* @return the discoverable mode the device is presently in
*/
public int getDiscoverable() {
return this.bluetoothStack.getLocalDeviceDiscoverable();
}
/**
* Retrieves Bluetooth system properties. The following properties must be supported, but additional values are
* allowed:
*
* Property Name
* Description
*
*
* bluetooth.api.version
* The version of the Java API for Bluetooth wireless technology that is supported. For this version it will be
* set to "1.0".
*
*
* bluetooth.master.switch
* Is master/slave switch allowed? Valid values are either "true" or "false".
*
*
* bluetooth.sd.attr.retrievable.max
* Maximum number of service attributes to be retrieved per service record. The string will be in Base 10
* digits.
*
*
* bluetooth.connected.devices.max
* The maximum number of connected devices supported. This number may be greater than 7 if the implementation
* handles parked connections. The string will be in Base 10 digits.
*
*
* bluetooth.l2cap.receiveMTU.max
* The maximum ReceiveMTU size in bytes supported in L2CAP. The string will be in Base 10 digits, e.g. "32".
*
*
* bluetooth.sd.trans.max
* Maximum number of concurrent service discovery transactions. The string will be in Base 10 digits.
*
*
* bluetooth.connected.inquiry.scan
* Is Inquiry scanning allowed during connection? Valid values are either "true" or "false".
*
*
* bluetooth.connected.page.scan
* Is Page scanning allowed during connection? Valid values are either "true" or "false".
*
*
* bluetooth.connected.inquiry
* Is Inquiry allowed during a connection? Valid values are either "true" or "false".
*
*
* bluetooth.connected.page
* Is paging allowed during a connection? In other words, can a connection be established to one device if it
* is already connected to another device. Valid values are either "true" or "false".
*
*
*
* BlueCove specific properties.
*
* Property Name
* Description
*
*
* bluecove
* The version of BlueCove implementation
*
*
* bluecove.stack
* The Bluetooth Stack: "winsock", "widcomm" or "bluesoleil"
*
*
*
* @param property
* the property to retrieve as defined in this class.
*
* @return the value of the property specified; null if the property is not defined
*/
public static String getProperty(String property) {
try {
if ("bluetooth.api.version".equals(property)) {
return "1.1";
} else if ("bluecove".equals(property)) {
return BlueCoveImpl.version;
} else if ("bluecove.stack".equals(property)) {
return BlueCoveImpl.instance().getBluetoothStack().getStackID();
} else if ("bluecove.connections".equals(property)) {
return String.valueOf(RemoteDeviceHelper.openConnections());
}
return BlueCoveImpl.instance().getBluetoothStack().getLocalDeviceProperty(property);
} catch (BluetoothStateException e) {
throw new RuntimeException(e.getMessage());
}
}
/**
* Retrieves the Bluetooth address of the local device. The Bluetooth address will never be null.
* The Bluetooth address will be 12 characters long. Valid characters are 0-9 and A-F.
*
* @return the Bluetooth address of the local device
*/
public String getBluetoothAddress() {
return addressStr;
}
/**
* Gets the service record corresponding to a btspp, btl2cap, or btgoep
* notifier. In the case of a run-before-connect service, the service record returned by getRecord()
* was created by the same call to Connector.open() that created the notifier.
*
*
* If a connect-anytime server application does not already have a service record in the SDDB, either because a
* service record for this service was never added to the SDDB or because the service record was added and then
* removed, then the ServiceRecord returned by getRecord() was created by the same
* call to Connector.open() that created the notifier.
*
* In the case of a connect-anytime service, there may be a service record in the SDDB corresponding to this service
* prior to application startup. In this case, the getRecord() method must return a
* ServiceRecord whose contents match those of the corresponding service record in the SDDB. If a
* connect-anytime server application made changes previously to its service record in the SDDB (for example, during
* a previous execution of the server), and that service record is still in the SDDB, then those changes must be
* reflected in the ServiceRecord returned by getRecord().
*
*
* Two invocations of this method with the same notifier argument return objects that describe the
* same service attributes, but the return values may be different object references.
*
* @param notifier
* a connection that waits for clients to connect to a Bluetooth service
*
* @return the ServiceRecord associated with notifier
*
* @exception IllegalArgumentException
* if notifier is closed, or if notifier does not implement one of the
* following interfaces: javax.microedition.io.StreamConnectionNotifier,
* javax.bluetooth.L2CapConnectionNotifier, or
* javax.obex.SessionNotifier. This exception is also thrown if notifier
* is not a Bluetooth notifier, e.g., a StreamConnectionNotifier created with a scheme
* other than btspp.
*
* @exception NullPointerException
* if notifier is null
*
*/
public ServiceRecord getRecord(Connection notifier) {
if (notifier == null) {
throw new NullPointerException("notifier is null");
}
if (!(notifier instanceof BluetoothConnectionNotifierServiceRecordAccess)) {
throw new IllegalArgumentException("connection is not a Bluetooth notifier");
}
return ((BluetoothConnectionNotifierServiceRecordAccess) notifier).getServiceRecord();
}
/**
* Updates the service record in the local SDDB that corresponds to the ServiceRecord parameter.
* Updating is possible only if srvRecord was obtained using the getRecord() method.
* The service record in the SDDB is modified to have the same service attributes with the same contents as
* srvRecord.
*
*
*
* If srvRecord was obtained from the SDDB of a remote device using the service search methods,
* updating is not possible and this method will throw an IllegalArgumentException.
*
*
*
* If the srvRecord parameter is a btspp service record, then before the SDDB is
* changed the following checks are performed. If any of these checks fail, then an
* IllegalArgumentException is thrown.
*
*
* - ServiceClassIDList and ProtocolDescriptorList, the mandatory service attributes for a
btspp
* service record, must be present in srvRecord.
* - L2CAP and RFCOMM must be in the ProtocolDescriptorList.
*
srvRecord must not have changed the RFCOMM server channel number from the channel number that
* is currently in the SDDB version of this service record.
*
*
*
*
* If the srvRecord parameter is a btl2cap service record, then before the SDDB is
* changed the following checks are performed. If any of these checks fail, then an
* IllegalArgumentException is thrown.
*
* - ServiceClassIDList and ProtocolDescriptorList, the mandatory service attributes for a
btl2cap
* service record, must be present in srvRecord.
* - L2CAP must be in the ProtocolDescriptorList.
*
srvRecord must not have changed the PSM value from the PSM value that is currently in the
* SDDB version of this service record.
*
*
*
*
* If the srvRecord parameter is a btgoep service record, then before the SDDB is
* changed the following checks are performed. If any of these checks fail, then an
* IllegalArgumentException is thrown.
*
* - ServiceClassIDList and ProtocolDescriptorList, the mandatory service attributes for a
btgoep
* service record, must be present in srvRecord.
* - L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList.
*
srvRecord must not have changed the RFCOMM server channel number from the channel number that
* is currently in the SDDB version of this service record.
*
*
*
*
* updateRecord() is not required to ensure that srvRecord is a completely valid
* service record. It is the responsibility of the application to ensure that srvRecord follows all
* of the applicable syntactic and semantic rules for service record correctness.
*
*
*
* If there is currently no SDDB version of the srvRecord service record, then this method will do
* nothing.
*
* @param srvRecord
* the new contents to use for the service record in the SDDB
*
* @exception NullPointerException
* if srvRecord is null
*
* @exception IllegalArgumentException
* if the structure of the srvRecord is missing any mandatory service attributes, or
* if an attempt has been made to change any of the values described as fixed.
*
* @exception ServiceRegistrationException
* if the local SDDB could not be updated successfully due to insufficient disk space, database
* locks, etc.
*
*/
public void updateRecord(ServiceRecord srvRecord) throws ServiceRegistrationException {
if (srvRecord == null) {
throw new NullPointerException("Service Record is null");
}
ServiceRecordsRegistry.updateServiceRecord(srvRecord);
}
}