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.lametrictime.internal.api;
  14
  15 import javax.ws.rs.client.ClientBuilder;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.openhab.binding.lametrictime.internal.api.cloud.CloudConfiguration;
  20 import org.openhab.binding.lametrictime.internal.api.cloud.LaMetricTimeCloud;
  21 import org.openhab.binding.lametrictime.internal.api.dto.CoreAction;
  22 import org.openhab.binding.lametrictime.internal.api.dto.CoreApplication;
  23 import org.openhab.binding.lametrictime.internal.api.dto.CoreApps;
  24 import org.openhab.binding.lametrictime.internal.api.dto.Icon;
  25 import org.openhab.binding.lametrictime.internal.api.dto.enums.BrightnessMode;
  26 import org.openhab.binding.lametrictime.internal.api.dto.enums.Priority;
  27 import org.openhab.binding.lametrictime.internal.api.dto.enums.Sound;
  28 import org.openhab.binding.lametrictime.internal.api.impl.LaMetricTimeImpl;
  29 import org.openhab.binding.lametrictime.internal.api.local.ApplicationActionException;
  30 import org.openhab.binding.lametrictime.internal.api.local.ApplicationActivationException;
  31 import org.openhab.binding.lametrictime.internal.api.local.ApplicationNotFoundException;
  32 import org.openhab.binding.lametrictime.internal.api.local.LaMetricTimeLocal;
  33 import org.openhab.binding.lametrictime.internal.api.local.LocalConfiguration;
  34 import org.openhab.binding.lametrictime.internal.api.local.NotificationCreationException;
  35 import org.openhab.binding.lametrictime.internal.api.local.UpdateException;
  36 import org.openhab.binding.lametrictime.internal.api.local.dto.Application;
  37 import org.openhab.binding.lametrictime.internal.api.local.dto.Audio;
  38 import org.openhab.binding.lametrictime.internal.api.local.dto.Bluetooth;
  39 import org.openhab.binding.lametrictime.internal.api.local.dto.Display;
  40 import org.openhab.binding.lametrictime.internal.api.local.dto.UpdateAction;
  41 import org.openhab.binding.lametrictime.internal.api.local.dto.Widget;
  42
  43 /**
  44  * Interface for LaMetric Time devices.
  45  *
  46  * @author Gregory Moyer - Initial contribution
  47  */
  48 @NonNullByDefault
  49 public interface LaMetricTime {
  50     /**
  51      * Get the version identifier reported by the device.
  52      *
  53      * @return the version
  54      */
  55     String getVersion();
  56
  57     /**
  58      * Send a low priority message to the device.
  59      *
  60      * @param message
  61      *            the text to display
  62      * @return the identifier of the newly created notification
  63      * @throws NotificationCreationException
  64      *             if there is a communication error or malformed data
  65      */
  66     String notifyInfo(String message) throws NotificationCreationException;
  67
  68     /**
  69      * Send a medium priority message to the device.
  70      *
  71      * @param message
  72      *            the text to display
  73      * @return the identifier of the newly created notification
  74      * @throws NotificationCreationException
  75      *             if there is a communication error or malformed data
  76      */
  77     String notifyWarning(String message) throws NotificationCreationException;
  78
  79     /**
  80      * Send an urgent message to the device. The notification will not be
  81      * automatically removed. The user will be required to dismiss this
  82      * notification or it must be deleted through he API.
  83      *
  84      * @param message
  85      *            the text to display
  86      * @return the identifier of the newly created notification
  87      * @throws NotificationCreationException
  88      *             if there is a communication error or malformed data
  89      */
  90     String notifyCritical(String message) throws NotificationCreationException;
  91
  92     /**
  93      * Send a notification to the device.
  94      *
  95      * Priority is important. It defines the urgency of this notification as
  96      * related to others in the queue and the current state of the device.
  97      * <ol>
  98      * <li>{@link Priority#INFO}: lowest priority; not shown when the
  99      * screensaver is active; waits for its turn in the queue
 100      * <li>{@link Priority#WARNING}: middle priority; not shown when the
 101      * screensaver is active; preempts {@link Priority#INFO}
 102      * <li>{@link Priority#CRITICAL}: highest priority; shown even when the
 103      * screensaver is active; preempts all other notifications (to be used
 104      * sparingly)
 105      * </ol>
 106      *
 107      * @param message
 108      *            the text to display
 109      * @param priority
 110      *            the urgency of this notification; defaults to
 111      *            {@link Priority#INFO}
 112      * @param icon
 113      *            the icon to display next to the message; can be
 114      *            <code>null</code>
 115      * @param sound
 116      *            the sound to play when the notification is displayed; can be
 117      *            <code>null</code>
 118      * @param messageRepeat
 119      *            the number of times the message should be displayed before
 120      *            being removed (use <code>0</code> to leave the notification on
 121      *            the device until it is dismissed by the user or deleted
 122      *            through the API)
 123      * @param soundRepeat
 124      *            the number of times to repeat the sound (use <code>0</code> to
 125      *            keep the sound looping until the notification is dismissed by
 126      *            the user or deleted through the API)
 127      * @return the identifier of the newly created notification
 128      * @throws NotificationCreationException
 129      *             if there is a communication error or malformed data
 130      */
 131     String notify(String message, Priority priority, Icon icon, Sound sound, int messageRepeat, int soundRepeat)
 132             throws NotificationCreationException;
 133
 134     /**
 135      * Get the built-in clock application. This applications displays the time
 136      * and date. It also provides an alarm feature.
 137      *
 138      * @return the clock app
 139      */
 140     @Nullable
 141     Application getClock();
 142
 143     /**
 144      * Get the built-in countdown timer application. This application counts
 145      * time down to zero when it sets off a beeper until it is reset. The
 146      * countdown can also be paused.
 147      *
 148      * @return the countdown app
 149      */
 150     @Nullable
 151     Application getCountdown();
 152
 153     /**
 154      * Get the built-in radio application. The radio can play streams from the
 155      * Internet. The streams are set up in a list and can be navigated using
 156      * 'next' and 'previous' actions. The music can be started and stopped.
 157      *
 158      * @return the radio app
 159      */
 160     @Nullable
 161     Application getRadio();
 162
 163     /**
 164      * Get the built-in stopwatch application. The stopwatch counts time
 165      * forwards and can be started, paused, and reset.
 166      *
 167      * @return the stopwatch app
 168      */
 169     @Nullable
 170     Application getStopwatch();
 171
 172     /**
 173      * Get the built-in weather application. This application displays the
 174      * current weather conditions. It can also display the forecast for today
 175      * and tomorrow.
 176      *
 177      * @return the weather app
 178      */
 179     @Nullable
 180     Application getWeather();
 181
 182     /**
 183      * Get any of the built-in applications.
 184      *
 185      * @param coreApp
 186      *            the app to retrieve
 187      * @return the requested app
 188      */
 189     @Nullable
 190     Application getApplication(CoreApplication coreApp);
 191
 192     /**
 193      * Get any application installed on the device.
 194      *
 195      * @param name
 196      *            the name of the app to retrieve
 197      * @return the requested app
 198      * @throws ApplicationNotFoundException
 199      *             if the requested app is not found on the device
 200      */
 201     @Nullable
 202     Application getApplication(@Nullable String name) throws ApplicationNotFoundException;
 203
 204     /**
 205      * Display the given built-in application on the device.
 206      *
 207      * @param coreApp
 208      *            the app to activate
 209      */
 210     void activateApplication(CoreApplication coreApp);
 211
 212     /**
 213      * Display the first instance (widget) of the given application on the
 214      * device.
 215      *
 216      * @param app
 217      *            the app to activate
 218      * @throws ApplicationActivationException
 219      *             if the app fails to activate
 220      */
 221     void activateApplication(Application app) throws ApplicationActivationException;
 222
 223     /**
 224      * Display the given widget on the device. A widget is simply an instance of
 225      * an application. Some applications can be installed more than once (e.g.
 226      * the {@link CoreApps#weather() weather} app) and each instance is assigned
 227      * a widget.
 228      *
 229      * @param widget
 230      *            the application instance (widget) to activate
 231      * @throws ApplicationActivationException
 232      *             if the app fails to activate
 233      */
 234     void activateWidget(Widget widget) throws ApplicationActivationException;
 235
 236     /**
 237      * Perform the given action on the first instance (widget) of the
 238      * corresponding built-in application. The widget will activate
 239      * automatically before carrying out the action.
 240      *
 241      * @param coreAction
 242      *            the action to perform
 243      */
 244     void doAction(CoreAction coreAction);
 245
 246     /**
 247      * Perform the given action on the first instance (widget) of the given
 248      * application. The widget will activate automatically before carrying out
 249      * the action.
 250      *
 251      * @param app
 252      *            the app which understands the requested action
 253      * @param action
 254      *            the action to perform
 255      * @throws ApplicationActionException
 256      *             if the action cannot be performed
 257      */
 258     void doAction(Application app, UpdateAction action) throws ApplicationActionException;
 259
 260     /**
 261      * Perform the given core action on the given widget. A widget is simply an
 262      * instance of an application. Some applications can be installed more than
 263      * once (e.g. the {@link CoreApps#weather() weather} app) and each instance
 264      * is assigned a widget. The widget will activate automatically before
 265      * carrying out the action.
 266      *
 267      * @param widget
 268      *            the widget which understands the requested core action
 269      * @param action
 270      *            the action to perform
 271      * @throws ApplicationActionException
 272      *             if the action cannot be performed
 273      */
 274     void doAction(@Nullable Widget widget, CoreAction action) throws ApplicationActionException;
 275
 276     /**
 277      * Perform the given action on the given widget. A widget is simply an
 278      * instance of an application. Some applications can be installed more than
 279      * once (e.g. the {@link CoreApps#weather() weather} app) and each instance
 280      * is assigned a widget. The widget will activate automatically before
 281      * carrying out the action.
 282      *
 283      * @param widget
 284      *            the widget which understands the requested action
 285      * @param action
 286      *            the action to perform
 287      * @throws ApplicationActionException
 288      *             if the action cannot be performed
 289      */
 290     void doAction(Widget widget, UpdateAction action) throws ApplicationActionException;
 291
 292     /**
 293      * Set the display brightness. The {@link #setBrightnessMode(BrightnessMode)
 294      * brightness mode} will also be set to {@link BrightnessMode#MANUAL}.
 295      *
 296      * @param brightness
 297      *            the brightness value to set (must be between 0 and 100,
 298      *            inclusive)
 299      * @return the updated state of the display
 300      * @throws UpdateException
 301      *             if the update failed
 302      */
 303     Display setBrightness(int brightness) throws UpdateException;
 304
 305     /**
 306      * Set the brightness mode on the display. {@link BrightnessMode#MANUAL}
 307      * will immediately respect the current brightness value while
 308      * {@link BrightnessMode#AUTO} will ignore the brightness value and set the
 309      * brightness based on ambient light intensity.
 310      *
 311      * @param mode
 312      *            the mode to set
 313      * @return the updated state of the display
 314      * @throws UpdateException
 315      *             if the update failed
 316      */
 317     Display setBrightnessMode(BrightnessMode mode) throws UpdateException;
 318
 319     /**
 320      * Set the speaker volume on the device.
 321      *
 322      * @param volume
 323      *            the volume to set (must be between 0 and 100, inclusive)
 324      * @return the update audio state
 325      * @throws UpdateException
 326      *             if the update failed
 327      */
 328     Audio setVolume(int volume) throws UpdateException;
 329
 330     /**
 331      * Mute the device's speakers. The current volume will be stored so that
 332      * {@link #unmute()} will restored it. If the volume is currently at zero,
 333      * no action will be taken.
 334      *
 335      * @return the update audio state
 336      * @throws UpdateException
 337      *             if the update failed
 338      */
 339     Audio mute() throws UpdateException;
 340
 341     /**
 342      * Restore the volume prior to {@link #mute()}. If the volume has not been
 343      * muted previously and the volume is currently zero, it will be set to 50%.
 344      *
 345      * @return the update audio state
 346      * @throws UpdateException
 347      *             if the update failed
 348      */
 349     Audio unmute() throws UpdateException;
 350
 351     /**
 352      * Set the active state of the Bluetooth radio on the device.
 353      *
 354      * @param active
 355      *            <code>true</code> to activate Bluetooth; <code>false</code> to
 356      *            deactive it
 357      * @return the updated state of Bluetooth on the device
 358      * @throws UpdateException
 359      *             if the update failed
 360      */
 361     Bluetooth setBluetoothActive(boolean active) throws UpdateException;
 362
 363     /**
 364      * Set the device name as seen via Bluetooth connectivity.
 365      *
 366      * @param name
 367      *            the name to display on other devices
 368      * @return the updated state of Bluetooth on the device
 369      * @throws UpdateException
 370      *             if the update failed
 371      */
 372     Bluetooth setBluetoothName(String name) throws UpdateException;
 373
 374     /**
 375      * Get the local API for more advanced interactions as well device inquiry.
 376      *
 377      * @return the local API
 378      */
 379     LaMetricTimeLocal getLocalApi();
 380
 381     /**
 382      * Get the cloud API for interacting with LaMetric's services.
 383      *
 384      * @return the cloud API
 385      */
 386     LaMetricTimeCloud getCloudApi();
 387
 388     /**
 389      * Create an instance of this API. For greater control over the
 390      * configuration, see {@link #create(Configuration, ClientBuilder)},
 391      * {@link #create(LocalConfiguration, CloudConfiguration)}, and
 392      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 393      *
 394      * @param config
 395      *            the configuration parameters that the new instance will use
 396      * @return the API instance
 397      */
 398     static LaMetricTime create(Configuration config) {
 399         return new LaMetricTimeImpl(config);
 400     }
 401
 402     /**
 403      * Create an instance of this API. For greater control over the
 404      * configuration, see
 405      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 406      *
 407      * @param config
 408      *            the configuration parameters that the new instance will use
 409      * @param clientBuilder
 410      *            the builder that will be used to create clients for
 411      *            communicating with the device and cloud services
 412      * @return the API instance
 413      */
 414     static LaMetricTime create(Configuration config, ClientBuilder clientBuilder) {
 415         return new LaMetricTimeImpl(config, clientBuilder);
 416     }
 417
 418     /**
 419      * Create an instance of this API specifying detailed configuration for both
 420      * the local and cloud APIs. See also
 421      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 422      *
 423      * @param localConfig
 424      *            the local API configuration for the new instance
 425      * @param cloudConfig
 426      *            the cloud API configuration for the new instance
 427      * @return the API instance
 428      */
 429     static LaMetricTime create(LocalConfiguration localConfig, CloudConfiguration cloudConfig) {
 430         return new LaMetricTimeImpl(localConfig, cloudConfig);
 431     }
 432
 433     /**
 434      * Create an instance of this API specifying detailed configuration for both
 435      * the local and cloud APIs as well as the generic client.
 436      *
 437      * @param localConfig
 438      *            the local API configuration for the new instance
 439      * @param cloudConfig
 440      *            the cloud API configuration for the new instance
 441      * @param clientBuilder
 442      *            the builder that will be used to create clients for
 443      *            communicating with the device and cloud services
 444      * @return the API instance
 445      */
 446     static LaMetricTime create(LocalConfiguration localConfig, CloudConfiguration cloudConfig,
 447             ClientBuilder clientBuilder) {
 448         return new LaMetricTimeImpl(localConfig, cloudConfig, clientBuilder);
 449     }
 450 }