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     public 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     public 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     public 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     public 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     public 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     public @Nullable Application getClock();
 141
 142     /**
 143      * Get the built-in countdown timer application. This application counts
 144      * time down to zero when it sets off a beeper until it is reset. The
 145      * countdown can also be paused.
 146      *
 147      * @return the countdown app
 148      */
 149     public @Nullable Application getCountdown();
 150
 151     /**
 152      * Get the built-in radio application. The radio can play streams from the
 153      * Internet. The streams are set up in a list and can be navigated using
 154      * 'next' and 'previous' actions. The music can be started and stopped.
 155      *
 156      * @return the radio app
 157      */
 158     public @Nullable Application getRadio();
 159
 160     /**
 161      * Get the built-in stopwatch application. The stopwatch counts time
 162      * forwards and can be started, paused, and reset.
 163      *
 164      * @return the stopwatch app
 165      */
 166     public @Nullable Application getStopwatch();
 167
 168     /**
 169      * Get the built-in weather application. This application displays the
 170      * current weather conditions. It can also display the forecast for today
 171      * and tomorrow.
 172      *
 173      * @return the weather app
 174      */
 175     public @Nullable Application getWeather();
 176
 177     /**
 178      * Get any of the built-in applications.
 179      *
 180      * @param coreApp
 181      *            the app to retrieve
 182      * @return the requested app
 183      */
 184     public @Nullable Application getApplication(CoreApplication coreApp);
 185
 186     /**
 187      * Get any application installed on the device.
 188      *
 189      * @param name
 190      *            the name of the app to retrieve
 191      * @return the requested app
 192      * @throws ApplicationNotFoundException
 193      *             if the requested app is not found on the device
 194      */
 195     public @Nullable Application getApplication(@Nullable String name) throws ApplicationNotFoundException;
 196
 197     /**
 198      * Display the given built-in application on the device.
 199      *
 200      * @param coreApp
 201      *            the app to activate
 202      */
 203     public void activateApplication(CoreApplication coreApp);
 204
 205     /**
 206      * Display the first instance (widget) of the given application on the
 207      * device.
 208      *
 209      * @param app
 210      *            the app to activate
 211      * @throws ApplicationActivationException
 212      *             if the app fails to activate
 213      */
 214     public void activateApplication(Application app) throws ApplicationActivationException;
 215
 216     /**
 217      * Display the given widget on the device. A widget is simply an instance of
 218      * an application. Some applications can be installed more than once (e.g.
 219      * the {@link CoreApps#weather() weather} app) and each instance is assigned
 220      * a widget.
 221      *
 222      * @param widget
 223      *            the application instance (widget) to activate
 224      * @throws ApplicationActivationException
 225      *             if the app fails to activate
 226      */
 227     public void activateWidget(Widget widget) throws ApplicationActivationException;
 228
 229     /**
 230      * Perform the given action on the first instance (widget) of the
 231      * corresponding built-in application. The widget will activate
 232      * automatically before carrying out the action.
 233      *
 234      * @param coreAction
 235      *            the action to perform
 236      */
 237     public void doAction(CoreAction coreAction);
 238
 239     /**
 240      * Perform the given action on the first instance (widget) of the given
 241      * application. The widget will activate automatically before carrying out
 242      * the action.
 243      *
 244      * @param app
 245      *            the app which understands the requested action
 246      * @param action
 247      *            the action to perform
 248      * @throws ApplicationActionException
 249      *             if the action cannot be performed
 250      */
 251     public void doAction(Application app, UpdateAction action) throws ApplicationActionException;
 252
 253     /**
 254      * Perform the given core action on the given widget. A widget is simply an
 255      * instance of an application. Some applications can be installed more than
 256      * once (e.g. the {@link CoreApps#weather() weather} app) and each instance
 257      * is assigned a widget. The widget will activate automatically before
 258      * carrying out the action.
 259      *
 260      * @param widget
 261      *            the widget which understands the requested core action
 262      * @param action
 263      *            the action to perform
 264      * @throws ApplicationActionException
 265      *             if the action cannot be performed
 266      */
 267     public void doAction(@Nullable Widget widget, CoreAction action) throws ApplicationActionException;
 268
 269     /**
 270      * Perform the given action on the given widget. A widget is simply an
 271      * instance of an application. Some applications can be installed more than
 272      * once (e.g. the {@link CoreApps#weather() weather} app) and each instance
 273      * is assigned a widget. The widget will activate automatically before
 274      * carrying out the action.
 275      *
 276      * @param widget
 277      *            the widget which understands the requested action
 278      * @param action
 279      *            the action to perform
 280      * @throws ApplicationActionException
 281      *             if the action cannot be performed
 282      */
 283     public void doAction(Widget widget, UpdateAction action) throws ApplicationActionException;
 284
 285     /**
 286      * Set the display brightness. The {@link #setBrightnessMode(BrightnessMode)
 287      * brightness mode} will also be set to {@link BrightnessMode#MANUAL}.
 288      *
 289      * @param brightness
 290      *            the brightness value to set (must be between 0 and 100,
 291      *            inclusive)
 292      * @return the updated state of the display
 293      * @throws UpdateException
 294      *             if the update failed
 295      */
 296     public Display setBrightness(int brightness) throws UpdateException;
 297
 298     /**
 299      * Set the brightness mode on the display. {@link BrightnessMode#MANUAL}
 300      * will immediately respect the current brightness value while
 301      * {@link BrightnessMode#AUTO} will ignore the brightness value and set the
 302      * brightness based on ambient light intensity.
 303      *
 304      * @param mode
 305      *            the mode to set
 306      * @return the updated state of the display
 307      * @throws UpdateException
 308      *             if the update failed
 309      */
 310     public Display setBrightnessMode(BrightnessMode mode) throws UpdateException;
 311
 312     /**
 313      * Set the speaker volume on the device.
 314      *
 315      * @param volume
 316      *            the volume to set (must be between 0 and 100, inclusive)
 317      * @return the update audio state
 318      * @throws UpdateException
 319      *             if the update failed
 320      */
 321     public Audio setVolume(int volume) throws UpdateException;
 322
 323     /**
 324      * Mute the device's speakers. The current volume will be stored so that
 325      * {@link #unmute()} will restored it. If the volume is currently at zero,
 326      * no action will be taken.
 327      *
 328      * @return the update audio state
 329      * @throws UpdateException
 330      *             if the update failed
 331      */
 332     public Audio mute() throws UpdateException;
 333
 334     /**
 335      * Restore the volume prior to {@link #mute()}. If the volume has not been
 336      * muted previously and the volume is currently zero, it will be set to 50%.
 337      *
 338      * @return the update audio state
 339      * @throws UpdateException
 340      *             if the update failed
 341      */
 342     public Audio unmute() throws UpdateException;
 343
 344     /**
 345      * Set the active state of the Bluetooth radio on the device.
 346      *
 347      * @param active
 348      *            <code>true</code> to activate Bluetooth; <code>false</code> to
 349      *            deactive it
 350      * @return the updated state of Bluetooth on the device
 351      * @throws UpdateException
 352      *             if the update failed
 353      */
 354     public Bluetooth setBluetoothActive(boolean active) throws UpdateException;
 355
 356     /**
 357      * Set the device name as seen via Bluetooth connectivity.
 358      *
 359      * @param name
 360      *            the name to display on other devices
 361      * @return the updated state of Bluetooth on the device
 362      * @throws UpdateException
 363      *             if the update failed
 364      */
 365     public Bluetooth setBluetoothName(String name) throws UpdateException;
 366
 367     /**
 368      * Get the local API for more advanced interactions as well device inquiry.
 369      *
 370      * @return the local API
 371      */
 372     public LaMetricTimeLocal getLocalApi();
 373
 374     /**
 375      * Get the cloud API for interacting with LaMetric's services.
 376      *
 377      * @return the cloud API
 378      */
 379     public LaMetricTimeCloud getCloudApi();
 380
 381     /**
 382      * Create an instance of this API. For greater control over the
 383      * configuration, see {@link #create(Configuration, ClientBuilder)},
 384      * {@link #create(LocalConfiguration, CloudConfiguration)}, and
 385      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 386      *
 387      * @param config
 388      *            the configuration parameters that the new instance will use
 389      * @return the API instance
 390      */
 391     public static LaMetricTime create(Configuration config) {
 392         return new LaMetricTimeImpl(config);
 393     }
 394
 395     /**
 396      * Create an instance of this API. For greater control over the
 397      * configuration, see
 398      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 399      *
 400      * @param config
 401      *            the configuration parameters that the new instance will use
 402      * @param clientBuilder
 403      *            the builder that will be used to create clients for
 404      *            communicating with the device and cloud services
 405      * @return the API instance
 406      */
 407     public static LaMetricTime create(Configuration config, ClientBuilder clientBuilder) {
 408         return new LaMetricTimeImpl(config, clientBuilder);
 409     }
 410
 411     /**
 412      * Create an instance of this API specifying detailed configuration for both
 413      * the local and cloud APIs. See also
 414      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 415      *
 416      * @param localConfig
 417      *            the local API configuration for the new instance
 418      * @param cloudConfig
 419      *            the cloud API configuration for the new instance
 420      * @return the API instance
 421      */
 422     public static LaMetricTime create(LocalConfiguration localConfig, CloudConfiguration cloudConfig) {
 423         return new LaMetricTimeImpl(localConfig, cloudConfig);
 424     }
 425
 426     /**
 427      * Create an instance of this API specifying detailed configuration for both
 428      * the local and cloud APIs as well as the generic client.
 429      *
 430      * @param localConfig
 431      *            the local API configuration for the new instance
 432      * @param cloudConfig
 433      *            the cloud API configuration for the new instance
 434      * @param clientBuilder
 435      *            the builder that will be used to create clients for
 436      *            communicating with the device and cloud services
 437      * @return the API instance
 438      */
 439     public static LaMetricTime create(LocalConfiguration localConfig, CloudConfiguration cloudConfig,
 440             ClientBuilder clientBuilder) {
 441         return new LaMetricTimeImpl(localConfig, cloudConfig, clientBuilder);
 442     }
 443 }