git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.bluetooth;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.openhab.core.common.registry.Identifiable;
  18 import org.openhab.core.thing.ThingUID;
  19
  20 /**
  21  * The {@link BluetoothAdapter} class defines the standard adapter API that must be implemented by bridge handlers,
  22  * which are then required to be registered as a BluetoothAdapter OSGi service.
  23  * <p>
  24  * <b>Scanning</b>
  25  * The API assumes that the adapter is "always" scanning to enable beacons to be received.
  26  * The bridge must decide to enable and disable scanning as it needs. This design choice avoids interaction between
  27  * higher layers where a binding may want to enable scanning while another needs to disable scanning for a specific
  28  * function (e.g. to connect to a device). The bridge should disable scanning only for the period that is needed.
  29  *
  30  * @author Chris Jackson - Initial contribution
  31  * @author Kai Kreuzer - renamed it, made it identifiable and added listener support
  32  */
  33 @NonNullByDefault
  34 public interface BluetoothAdapter extends Identifiable<ThingUID> {
  35
  36     /**
  37      * Adds a {@link BluetoothDiscoveryListener} to the adapter
  38      *
  39      * @param listener the listener to add
  40      */
  41     void addDiscoveryListener(BluetoothDiscoveryListener listener);
  42
  43     /**
  44      * Removes a {@link BluetoothDiscoveryListener} from the adapter
  45      *
  46      * @param listener the listener to remove
  47      */
  48     void removeDiscoveryListener(@Nullable BluetoothDiscoveryListener listener);
  49
  50     /**
  51      * Starts an active scan on the Bluetooth interface.
  52      */
  53     void scanStart();
  54
  55     /**
  56      * Stops an active scan on the Bluetooth interface
  57      */
  58     void scanStop();
  59
  60     /**
  61      * Gets the {@link BluetoothAddress} of the adapter
  62      *
  63      * @return the {@link BluetoothAddress} of the adapter
  64      * @throws IllegalStateException if the adapter is not initialized
  65      */
  66     @Nullable
  67     BluetoothAddress getAddress();
  68
  69     /**
  70      * Gets the {@link BluetoothDevice} given the {@link BluetoothAddress}.
  71      * A {@link BluetoothDevice} will always be returned for a valid hardware address, even if this adapter has never
  72      * seen that device.
  73      *
  74      * @param address the {@link BluetoothAddress} to retrieve
  75      * @return the {@link BluetoothDevice}
  76      */
  77     BluetoothDevice getDevice(BluetoothAddress address);
  78
  79     /**
  80      * Gets the location of this adapter, as specified in Thing.getLocation()
  81      *
  82      * @return the location of this adapter
  83      */
  84     @Nullable
  85     String getLocation();
  86
  87     /**
  88      * Gets the label for this adapter, as specified in Thing.getLabel()
  89      *
  90      * @return the location of this adapter
  91      */
  92     @Nullable
  93     String getLabel();
  94
  95     /**
  96      * Checks if this adapter has a device with the given {@link BluetoothAddress}.
  97      *
  98      * @param address the {@link BluetoothAddress} to check for
  99      * @return true if this adapter has a {@link BluetoothDevice} with that address
 100      */
 101     boolean hasHandlerForDevice(BluetoothAddress address);
 102 }