LocalDevice.java - bluecove

‹r2530

r2997

Source path: svn/ trunk/ bluecove/ src/ main/ java/ javax/ bluetooth/ LocalDevice.java

493
494

/**
 *  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$
 */
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 <code>LocalDevice</code> 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.
 * <P>
 * 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 <code>getLocalDevice()</code> 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 <code>LocalDevice</code> object for the local Bluetooth
     * device. Multiple calls to this method will return the same object. This
     * method will never return <code>null</code>.
     * 
     * @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 <code>true</code> if the local Bluetooth device is powered on,
     *         <code>false</code> 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
     * <code>null</code>.
     * 
     * @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; <code>null</code> if the name could
     *         not be retrieved
     */
    public String getFriendlyName() {
        return this.bluetoothStack.getLocalDeviceName();
    }

    /**
     * Retrieves the <code>DeviceClass</code> object that represents the service
     * classes, major device class, and minor device class of the local device.
     * This method will return <code>null</code> 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 <code>null</code> 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 <code>mode</code> 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
     * ( <code>DiscoveryAgent.GIAC</code>) and LIAC (
     * <code>DiscoveryAgent.LIAC</code>) 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 <A
     * HREF="http://www.bluetooth.org/assigned-numbers/baseband.htm">
     * http://www.bluetooth.org/assigned-numbers/baseband.htm</A>. If
     * <code>DiscoveryAgent.GIAC</code> or <code>DiscoveryAgent.LIAC</code> 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
     * <code>DiscoveryAgent.NOT_DISCOVERABLE</code> 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.
     * <P>
     * According to the Bluetooth Specification, a device should only be limited
     * discoverable ( <code>DiscoveryAgent.LIAC</code>) 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
     *            <code>DiscoveryAgent.GIAC</code>,
     *            <code>DiscoveryAgent.LIAC</code>,
     *            <code>DiscoveryAgent.NOT_DISCOVERABLE</code> and any value in
     *            the range 0x9E8B00 to 0x9E8B3F
     * 
     * @return <code>true</code> if the request succeeded, otherwise
     *         <code>false</code> if the request failed because the BCC denied
     *         the request; <code>false</code> if the Bluetooth system does not
     *         support the access mode specified in <code>mode</code>
     * 
     * @exception IllegalArgumentException
     *                if the <code>mode</code> is not
     *                <code>DiscoveryAgent.GIAC</code>,
     *                <code>DiscoveryAgent.LIAC</code> ,
     *                <code>DiscoveryAgent.NOT_DISCOVERABLE</code>, 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:
     * <TABLE>
     * <TR>
     * <TH>Property Name</TH>
     * <TH>Description</TH>
     * </TR>
     * <TR>
     * <TD>bluetooth.api.version</TD>
     * <TD>The version of the Java API for Bluetooth wireless technology that is
     * supported. For this version it will be set to "1.1.1".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.master.switch</TD>
     * <TD>Is master/slave switch allowed? Valid values are either "true" or
     * "false".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.sd.attr.retrievable.max</TD>
     * <TD>Maximum number of service attributes to be retrieved per service
     * record. The string will be in Base 10 digits.</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.connected.devices.max</TD>
     * <TD>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.</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.l2cap.receiveMTU.max</TD>
     * <TD>The maximum ReceiveMTU size in bytes supported in L2CAP. The string
     * will be in Base 10 digits, e.g. "32".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.sd.trans.max</TD>
     * <TD>Maximum number of concurrent service discovery transactions. The
     * string will be in Base 10 digits.</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.connected.inquiry.scan</TD>
     * <TD>Is Inquiry scanning allowed during connection? Valid values are
     * either "true" or "false".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.connected.page.scan</TD>
     * <TD>Is Page scanning allowed during connection? Valid values are either
     * "true" or "false".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.connected.inquiry</TD>
     * <TD>Is Inquiry allowed during a connection? Valid values are either
     * "true" or "false".</TD>
     * </TR>
     * <TR>
     * <TD>bluetooth.connected.page</TD>
     * <TD>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".</TD>
     * </TR>
     * </TABLE>
     * 
     * @see com.intel.bluetooth.BlueCoveLocalDeviceProperties
     * 
     * @param property
     *            the property to retrieve as defined in this class.
     * 
     * @return the value of the property specified; <code>null</code> if the
     *         <code>property</code> 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_FEATURE_RSSI.equals(property)) {
                return BlueCoveImpl.instance().getLocalDeviceFeature(BluetoothStack.FEATURE_RSSI);
            } 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
     * <code>DiscoveryAgent.GIAC</code>, <code>DiscoveryAgent.LIAC</code>,
     * <code>DiscoveryAgent.NOT_DISCOVERABLE</code>, 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 <code>null</code>. 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 <code>btspp</code>,
     * <code>btl2cap</code>, or <code>btgoep</code> notifier. In the case of a
     * run-before-connect service, the service record returned by
     * <code>getRecord()</code> was created by the same call to
     * <code>Connector.open()</code> that created the <code>notifier</code>.
     * 
     * <p>
     * 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 <code>ServiceRecord</code> returned by
     * <code>getRecord()</code> was created by the same call to
     * <code>Connector.open()</code> that created the notifier.
     * <p>
     * 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 <code>getRecord()</code> method must return a
     * <code>ServiceRecord</code> 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 <code>ServiceRecord</code> returned by <code>getRecord()</code>.
     * 
     * <p>
     * Two invocations of this method with the same <code>notifier</code>
     * 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 <code>ServiceRecord</code> associated with
     *         <code>notifier</code>
     * 
     * @exception IllegalArgumentException
     *                if <code>notifier</code> is closed, or if
     *                <code>notifier</code> does not implement one of the
     *                following interfaces:
     *                <code>javax.microedition.io.StreamConnectionNotifier</code>
     *                , <code>javax.bluetooth.L2CapConnectionNotifier</code>, or
     *                <code>javax.obex.SessionNotifier</code>. This exception is
     *                also thrown if <code>notifier</code> is not a Bluetooth
     *                notifier, e.g., a <code>StreamConnectionNotifier</code>
     *                created with a scheme other than <code>btspp</code>.
     * 
     * @exception NullPointerException
     *                if <code>notifier</code> is <code>null</code>
     * 
     */
    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
     * <code>ServiceRecord</code> parameter. Updating is possible only if
     * <code>srvRecord</code> was obtained using the <code>getRecord()</code>
     * method. The service record in the SDDB is modified to have the same
     * service attributes with the same contents as <code>srvRecord</code>.
     * 
     * <p>
     * 
     * If <code>srvRecord</code> was obtained from the SDDB of a remote device
     * using the service search methods, updating is not possible and this
     * method will throw an <code>IllegalArgumentException</code>.
     * 
     * <P>
     * 
     * If the <code>srvRecord</code> parameter is a <code>btspp</code> service
     * record, then before the SDDB is changed the following checks are
     * performed. If any of these checks fail, then an
     * <code>IllegalArgumentException</code> is thrown.
     * 
     * <UL>
     * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
     * attributes for a <code>btspp</code> service record, must be present in
     * <code>srvRecord</code>.
     * <LI>L2CAP and RFCOMM must be in the ProtocolDescriptorList.
     * <LI><code>srvRecord</code> must not have changed the RFCOMM server
     * channel number from the channel number that is currently in the SDDB
     * version of this service record.
     * </UL>
     * 
     * <P>
     * 
     * If the <code>srvRecord</code> parameter is a <code>btl2cap</code> service
     * record, then before the SDDB is changed the following checks are
     * performed. If any of these checks fail, then an
     * <code>IllegalArgumentException</code> is thrown.
     * <UL>
     * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
     * attributes for a <code>btl2cap</code> service record, must be present in
     * <code>srvRecord</code>.
     * <LI>L2CAP must be in the ProtocolDescriptorList.
     * <LI><code>srvRecord</code> must not have changed the PSM value from the
     * PSM value that is currently in the SDDB version of this service record.
     * </UL>
     * 
     * <P>
     * 
     * If the <code>srvRecord</code> parameter is a <code>btgoep</code> service
     * record, then before the SDDB is changed the following checks are
     * performed. If any of these checks fail, then an
     * <code>IllegalArgumentException</code> is thrown.
     * <UL>
     * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
     * attributes for a <code>btgoep</code> service record, must be present in
     * <code>srvRecord</code>.
     * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList.
     * <LI><code>srvRecord</code> must not have changed the RFCOMM server
     * channel number from the channel number that is currently in the SDDB
     * version of this service record.
     * </UL>
     * 
     * <p>
     * 
     * <code>updateRecord()</code> is not required to ensure that
     * <code>srvRecord</code> is a completely valid service record. It is the
     * responsibility of the application to ensure that <code>srvRecord</code>
     * follows all of the applicable syntactic and semantic rules for service
     * record correctness.
     * 
     * <P>
     * 
     * If there is currently no SDDB version of the <code>srvRecord</code>
     * 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 <code>srvRecord</code> is <code>null</code>
     * 
     * @exception IllegalArgumentException
     *                if the structure of the <code>srvRecord</code> 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);
    }

Show details Hide details

Change log

r2736 by skarzhevskyy on Feb 12, 2009 Diff

Adding property bluecove.feature.rssi

Go to:

Project members, sign in to write a code review

Older revisions

r2530 by skarzhevskyy on Dec 09, 2008 Diff

sync package javax.bluetooth javadocs
with JSR-82 1.1.1

r2525 by skarzhevskyy on Dec 08, 2008 Diff

Cleanup references to "bluetooth.*"
properties

r2523 by skarzhevskyy on Dec 08, 2008 Diff

Started TCK for JSR 82 1.1.1

All revisions of this file

File info

Size: 22092 bytes, 494 lines

View raw file

File properties

svn:mime-type: text/plain
svn:eol-style: native
svn:keywords: Date Author Id Revision