javax.bluetooth.LocalDevice Maven / Gradle / Ivy
Show all versions of bluecove Show documentation
/**
* 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: LocalDevice.java 2530 2008-12-09 18:52:53Z skarzhevskyy $
*/
package javax.bluetooth;
import java.util.Hashtable;
import javax.microedition.io.Connection;
import com.intel.bluetooth.BlueCoveImpl;
import com.intel.bluetooth.BlueCoveLocalDeviceProperties;
import com.intel.bluetooth.BluetoothConnectionNotifierServiceRecordAccess;
import com.intel.bluetooth.BluetoothConsts;
import com.intel.bluetooth.BluetoothStack;
import com.intel.bluetooth.RemoteDeviceHelper;
import com.intel.bluetooth.ServiceRecordsRegistry;
import com.intel.bluetooth.UtilsJavaSE;
/**
* 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.
*/
public class LocalDevice {
private static Hashtable localDevices = new Hashtable();
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(BluetoothStack stack) throws BluetoothStateException {
this.bluetoothStack = stack;
discoveryAgent = new DiscoveryAgent(this.bluetoothStack);
addressStr = RemoteDeviceHelper.formatBluetoothAddress(this.bluetoothStack.getLocalDeviceBluetoothAddress());
}
private static synchronized LocalDevice getLocalDeviceInstance() throws BluetoothStateException {
BluetoothStack stack = BlueCoveImpl.instance().getBluetoothStack();
LocalDevice localDevice = (LocalDevice) localDevices.get(stack);
if (localDevice == null) {
localDevice = new LocalDevice(stack);
localDevices.put(stack, 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();
}
/**
* 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;
}
}
/**
* 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 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.1.1".
*
*
* 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".
*
*
*
* @see com.intel.bluetooth.BlueCoveLocalDeviceProperties
*
* @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 (BluetoothConsts.PROPERTY_BLUETOOTH_API_VERSION.equals(property)) {
return BlueCoveImpl.BLUETOOTH_API_VERSION;
} else if (BluetoothConsts.PROPERTY_OBEX_API_VERSION.equals(property)) {
return BlueCoveImpl.OBEX_API_VERSION;
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_BLUECOVE_VERSION.equals(property)) {
return BlueCoveImpl.version;
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_STACK.equals(property)) {
return BlueCoveImpl.instance().getBluetoothStack().getStackID();
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_FEATURE_L2CAP.equals(property)) {
return BlueCoveImpl.instance().getLocalDeviceFeature(BluetoothStack.FEATURE_L2CAP);
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_FEATURE_SERVICE_ATTRIBUTES.equals(property)) {
return BlueCoveImpl.instance().getLocalDeviceFeature(BluetoothStack.FEATURE_SERVICE_ATTRIBUTES);
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_FEATURE_SET_DEVICE_SERVICE_CLASSES.equals(property)) {
return BlueCoveImpl.instance().getLocalDeviceFeature(BluetoothStack.FEATURE_SET_DEVICE_SERVICE_CLASSES);
} else if (BlueCoveLocalDeviceProperties.LOCAL_DEVICE_PROPERTY_OPEN_CONNECTIONS.equals(property)) {
return String.valueOf(RemoteDeviceHelper.openConnections());
}
return BlueCoveImpl.instance().getBluetoothStack().getLocalDeviceProperty(property);
} catch (BluetoothStateException e) {
throw (RuntimeException) UtilsJavaSE.initCause(new RuntimeException(e.getMessage()), e);
}
}
/**
* 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 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);
}
}