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.hue.internal.handler;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.openhab.binding.hue.internal.api.dto.clip1.ConfigUpdate;
  18 import org.openhab.binding.hue.internal.api.dto.clip1.FullGroup;
  19 import org.openhab.binding.hue.internal.api.dto.clip1.FullLight;
  20 import org.openhab.binding.hue.internal.api.dto.clip1.FullSensor;
  21 import org.openhab.binding.hue.internal.api.dto.clip1.StateUpdate;
  22 import org.openhab.binding.hue.internal.discovery.HueDeviceDiscoveryService;
  23
  24 /**
  25  * Access to the Hue system for light handlers.
  26  *
  27  * @author Simon Kaufmann - initial contribution and API
  28  * @author Samuel Leisering - Added support for sensor API
  29  * @author Christoph Weitkamp - Added support for sensor API
  30  * @author Laurent Garnier - Added support for groups
  31  */
  32 @NonNullByDefault
  33 public interface HueClient {
  34
  35     /**
  36      * Register {@link HueDeviceDiscoveryService} to bridge handler
  37      *
  38      * @param listener the discovery service
  39      * @return {@code true} if the new discovery service is accepted
  40      */
  41     boolean registerDiscoveryListener(HueDeviceDiscoveryService listener);
  42
  43     /**
  44      * Unregister {@link HueDeviceDiscoveryService} from bridge handler
  45      *
  46      * @return {@code true} if the discovery service was removed
  47      */
  48     boolean unregisterDiscoveryListener();
  49
  50     /**
  51      * Register a light status listener.
  52      *
  53      * @param lightStatusListener the light status listener
  54      * @return {@code true} if the collection of listeners has changed as a result of this call
  55      */
  56     boolean registerLightStatusListener(LightStatusListener lightStatusListener);
  57
  58     /**
  59      * Unregister a light status listener.
  60      *
  61      * @param lightStatusListener the light status listener
  62      * @return {@code true} if the collection of listeners has changed as a result of this call
  63      */
  64     boolean unregisterLightStatusListener(LightStatusListener lightStatusListener);
  65
  66     /**
  67      * Register a sensor status listener.
  68      *
  69      * @param sensorStatusListener the sensor status listener
  70      * @return {@code true} if the collection of listeners has changed as a result of this call
  71      */
  72     boolean registerSensorStatusListener(SensorStatusListener sensorStatusListener);
  73
  74     /**
  75      * Unregister a sensor status listener.
  76      *
  77      * @param sensorStatusListener the sensor status listener
  78      * @return {@code true} if the collection of listeners has changed as a result of this call
  79      */
  80     boolean unregisterSensorStatusListener(SensorStatusListener sensorStatusListener);
  81
  82     /**
  83      * Register a group status listener.
  84      *
  85      * @param groupStatusListener the group status listener
  86      * @return {@code true} if the collection of listeners has changed as a result of this call
  87      */
  88     boolean registerGroupStatusListener(GroupStatusListener groupStatusListener);
  89
  90     /**
  91      * Unregister a group status listener.
  92      *
  93      * @param groupStatusListener the group status listener
  94      * @return {@code true} if the collection of listeners has changed as a result of this call
  95      */
  96     boolean unregisterGroupStatusListener(GroupStatusListener groupStatusListener);
  97
  98     /**
  99      * Get the light by its ID.
 100      *
 101      * @param lightId the light ID
 102      * @return the full light representation or {@code null} if it could not be found
 103      */
 104     @Nullable
 105     FullLight getLightById(String lightId);
 106
 107     /**
 108      * Get the sensor by its ID.
 109      *
 110      * @param sensorId the sensor ID
 111      * @return the full sensor representation or {@code null} if it could not be found
 112      */
 113     @Nullable
 114     FullSensor getSensorById(String sensorId);
 115
 116     /**
 117      * Get the group by its ID.
 118      *
 119      * @param groupId the group ID
 120      * @return the full group representation or {@code null} if it could not be found
 121      */
 122     @Nullable
 123     FullGroup getGroupById(String groupId);
 124
 125     /**
 126      * Updates the given light.
 127      *
 128      * @param listener the light status listener to block it for state updates
 129      * @param light the light to be updated
 130      * @param stateUpdate the state update
 131      * @param fadeTime the status listener will be blocked for this duration after command
 132      */
 133     void updateLightState(LightStatusListener listener, FullLight light, StateUpdate stateUpdate, long fadeTime);
 134
 135     /**
 136      * Updates the given sensors config.
 137      *
 138      * @param sensor the light to be updated
 139      * @param configUpdate the config update
 140      */
 141     void updateSensorConfig(FullSensor sensor, ConfigUpdate configUpdate);
 142
 143     /**
 144      * Updates the given sensor.
 145      *
 146      * @param sensor the sensor to be updated
 147      * @param stateUpdate the state update
 148      */
 149     void updateSensorState(FullSensor sensor, StateUpdate stateUpdate);
 150
 151     /**
 152      * Updates the given group.
 153      *
 154      * @param group the group to be updated
 155      * @param stateUpdate the state update
 156      */
 157     void updateGroupState(FullGroup group, StateUpdate stateUpdate, long fadeTime);
 158
 159     /**
 160      * Recall scene to all lights that belong to the scene.
 161      *
 162      * @param id the ID of the scene to be recalled
 163      */
 164     void recallScene(String id);
 165 }