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

   1 /**
   2  * Copyright 2017-2018 Gregory Moyer and contributors.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package org.openhab.binding.lametrictime.api;
  17
  18 import javax.ws.rs.client.ClientBuilder;
  19
  20 import org.openhab.binding.lametrictime.api.cloud.CloudConfiguration;
  21 import org.openhab.binding.lametrictime.api.cloud.LaMetricTimeCloud;
  22 import org.openhab.binding.lametrictime.api.impl.LaMetricTimeImpl;
  23 import org.openhab.binding.lametrictime.api.local.ApplicationActionException;
  24 import org.openhab.binding.lametrictime.api.local.ApplicationActivationException;
  25 import org.openhab.binding.lametrictime.api.local.ApplicationNotFoundException;
  26 import org.openhab.binding.lametrictime.api.local.LaMetricTimeLocal;
  27 import org.openhab.binding.lametrictime.api.local.LocalConfiguration;
  28 import org.openhab.binding.lametrictime.api.local.NotificationCreationException;
  29 import org.openhab.binding.lametrictime.api.local.UpdateException;
  30 import org.openhab.binding.lametrictime.api.local.model.Application;
  31 import org.openhab.binding.lametrictime.api.local.model.Audio;
  32 import org.openhab.binding.lametrictime.api.local.model.Bluetooth;
  33 import org.openhab.binding.lametrictime.api.local.model.Display;
  34 import org.openhab.binding.lametrictime.api.local.model.UpdateAction;
  35 import org.openhab.binding.lametrictime.api.local.model.Widget;
  36 import org.openhab.binding.lametrictime.api.model.CoreAction;
  37 import org.openhab.binding.lametrictime.api.model.CoreApplication;
  38 import org.openhab.binding.lametrictime.api.model.CoreApps;
  39 import org.openhab.binding.lametrictime.api.model.Icon;
  40 import org.openhab.binding.lametrictime.api.model.enums.BrightnessMode;
  41 import org.openhab.binding.lametrictime.api.model.enums.Priority;
  42 import org.openhab.binding.lametrictime.api.model.enums.Sound;
  43
  44 public interface LaMetricTime
  45 {
  46     /**
  47      * Get the version identifier reported by the device.
  48      *
  49      * @return the version
  50      */
  51     public String getVersion();
  52
  53     /**
  54      * Send a low priority message to the device.
  55      *
  56      * @param message
  57      *            the text to display
  58      * @return the identifier of the newly created notification
  59      * @throws NotificationCreationException
  60      *             if there is a communication error or malformed data
  61      */
  62     public String notifyInfo(String message) throws NotificationCreationException;
  63
  64     /**
  65      * Send a medium priority message to the device.
  66      *
  67      * @param message
  68      *            the text to display
  69      * @return the identifier of the newly created notification
  70      * @throws NotificationCreationException
  71      *             if there is a communication error or malformed data
  72      */
  73     public String notifyWarning(String message) throws NotificationCreationException;
  74
  75     /**
  76      * Send an urgent message to the device. The notification will not be
  77      * automatically removed. The user will be required to dismiss this
  78      * notification or it must be deleted through he API.
  79      *
  80      * @param message
  81      *            the text to display
  82      * @return the identifier of the newly created notification
  83      * @throws NotificationCreationException
  84      *             if there is a communication error or malformed data
  85      */
  86     public String notifyCritical(String message) throws NotificationCreationException;
  87
  88     /**
  89      * Send a notification to the device.
  90      *
  91      * Priority is important. It defines the urgency of this notification as
  92      * related to others in the queue and the current state of the device.
  93      * <ol>
  94      * <li>{@link Priority#INFO}: lowest priority; not shown when the
  95      * screensaver is active; waits for its turn in the queue
  96      * <li>{@link Priority#WARNING}: middle priority; not shown when the
  97      * screensaver is active; preempts {@link Priority#INFO}
  98      * <li>{@link Priority#CRITICAL}: highest priority; shown even when the
  99      * screensaver is active; preempts all other notifications (to be used
 100      * sparingly)
 101      * </ol>
 102      *
 103      * @param message
 104      *            the text to display
 105      * @param priority
 106      *            the urgency of this notification; defaults to
 107      *            {@link Priority#INFO}
 108      * @param icon
 109      *            the icon to display next to the message; can be
 110      *            <code>null</code>
 111      * @param sound
 112      *            the sound to play when the notification is displayed; can be
 113      *            <code>null</code>
 114      * @param messageRepeat
 115      *            the number of times the message should be displayed before
 116      *            being removed (use <code>0</code> to leave the notification on
 117      *            the device until it is dismissed by the user or deleted
 118      *            through the API)
 119      * @param soundRepeat
 120      *            the number of times to repeat the sound (use <code>0</code> to
 121      *            keep the sound looping until the notification is dismissed by
 122      *            the user or deleted through the API)
 123      * @return the identifier of the newly created notification
 124      * @throws NotificationCreationException
 125      *             if there is a communication error or malformed data
 126      */
 127     public String notify(String message,
 128                          Priority priority,
 129                          Icon icon,
 130                          Sound sound,
 131                          int messageRepeat,
 132                          int soundRepeat) 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 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 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 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 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 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 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 Application getApplication(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(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     {
 393         return new LaMetricTimeImpl(config);
 394     }
 395
 396     /**
 397      * Create an instance of this API. For greater control over the
 398      * configuration, see
 399      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 400      *
 401      * @param config
 402      *            the configuration parameters that the new instance will use
 403      * @param clientBuilder
 404      *            the builder that will be used to create clients for
 405      *            communicating with the device and cloud services
 406      * @return the API instance
 407      */
 408     public static LaMetricTime create(Configuration config, ClientBuilder clientBuilder)
 409     {
 410         return new LaMetricTimeImpl(config, clientBuilder);
 411     }
 412
 413     /**
 414      * Create an instance of this API specifying detailed configuration for both
 415      * the local and cloud APIs. See also
 416      * {@link #create(LocalConfiguration, CloudConfiguration, ClientBuilder)}.
 417      *
 418      * @param localConfig
 419      *            the local API configuration for the new instance
 420      * @param cloudConfig
 421      *            the cloud API configuration for the new instance
 422      * @return the API instance
 423      */
 424     public static LaMetricTime create(LocalConfiguration localConfig,
 425                                       CloudConfiguration cloudConfig)
 426     {
 427         return new LaMetricTimeImpl(localConfig, cloudConfig);
 428     }
 429
 430     /**
 431      * Create an instance of this API specifying detailed configuration for both
 432      * the local and cloud APIs as well as the generic client.
 433      *
 434      * @param localConfig
 435      *            the local API configuration for the new instance
 436      * @param cloudConfig
 437      *            the cloud API configuration for the new instance
 438      * @param clientBuilder
 439      *            the builder that will be used to create clients for
 440      *            communicating with the device and cloud services
 441      * @return the API instance
 442      */
 443     public static LaMetricTime create(LocalConfiguration localConfig,
 444                                       CloudConfiguration cloudConfig,
 445                                       ClientBuilder clientBuilder)
 446     {
 447         return new LaMetricTimeImpl(localConfig, cloudConfig, clientBuilder);
 448     }
 449 }