hueplusplus  1.0.0
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
hueplusplus::StateTransaction Class Reference

Transaction class which can be used for either light or group state. More...

#include <hueplusplus/StateTransaction.h>

+ Collaboration diagram for hueplusplus::StateTransaction:

Public Member Functions

 StateTransaction (const HueCommandAPI &commands, const std::string &path, nlohmann::json *currentState)
 Creates a StateTransaction to a group or light state. More...
 
 StateTransaction (const StateTransaction &)=delete
 Deleted copy constructor, do not store StateTransaction in a variable. More...
 
 StateTransaction (StateTransaction &&)=default
 
bool commit (bool trimRequest=true)
 Commit transaction and make request. More...
 
Action toAction ()
 Create an Action from the transaction. More...
 
StateTransactionsetOn (bool on)
 Turn light on or off. More...
 
StateTransactionsetBrightness (uint8_t brightness)
 Set light brightness. More...
 
StateTransactionsetColorHue (uint16_t hue)
 Set light hue. More...
 
StateTransactionsetColorSaturation (uint8_t saturation)
 Set light saturation. More...
 
StateTransactionsetColor (const HueSaturation &hueSat)
 Set light color in hue and saturation. More...
 
StateTransactionsetColor (const XY &xy)
 Set light color in xy space (without brightness). More...
 
StateTransactionsetColor (const XYBrightness &xy)
 Set light color and brightness in xy space. More...
 
StateTransactionsetColorTemperature (unsigned int mired)
 Set light color temperature. More...
 
StateTransactionsetColorLoop (bool on)
 Enables or disables color loop. More...
 
StateTransactionincrementBrightness (int increment)
 Increment/Decrement brightness. More...
 
StateTransactionincrementSaturation (int increment)
 Increment/Decrement saturaction. More...
 
StateTransactionincrementHue (int increment)
 Increment/Decrement hue. More...
 
StateTransactionincrementColorTemperature (int increment)
 Increment/Decrement color temperature. More...
 
StateTransactionincrementColorXY (float xInc, float yInc)
 Increment/Decrement color xy. More...
 
StateTransactionsetTransition (uint16_t transition)
 Set transition time for the request. More...
 
StateTransactionalert ()
 Trigger an alert. More...
 
StateTransactionlongAlert ()
 Trigger a long alert (15s). More...
 
StateTransactionstopAlert ()
 Stop an ongoing long alert. More...
 

Protected Member Functions

void trimRequest ()
 Remove parts from request that are already set in state. More...
 

Protected Attributes

const HueCommandAPIcommands
 
std::string path
 
nlohmann::json * state
 
nlohmann::json request
 

Detailed Description

Transaction class which can be used for either light or group state.

This is intended to be used in-line, all calls are chained until a commit() call.

Note
The transaction has an internal reference to the light state. You must not cause a refresh of the state between creating and committing the transaction (e.g. non-const getters/setters), because that invalidates the reference.

Advanced usage

Another way to use the transaction is by storing it and building up the calls separately.

if(shouldTurnOn)
t.setOn(true);
t.commit();

In this case, it is especially important that the light and the state of the light MUST NOT invalidate. That means

In general, this method is easier to screw up and should only be used when really necessary.

Constructor & Destructor Documentation

◆ StateTransaction() [1/3]

hueplusplus::StateTransaction::StateTransaction ( const HueCommandAPI commands,
const std::string &  path,
nlohmann::json *  currentState 
)

Creates a StateTransaction to a group or light state.

Parameters
commandsHueCommandAPI for making requests
pathPath to which the final PUT request is made (without username)
currentStateOptional, the current state to check whether changes are needed. Pass nullptr to always include all requests (for groups, because individual lights might be different).

◆ StateTransaction() [2/3]

hueplusplus::StateTransaction::StateTransaction ( const StateTransaction )
delete

Deleted copy constructor, do not store StateTransaction in a variable.

◆ StateTransaction() [3/3]

hueplusplus::StateTransaction::StateTransaction ( StateTransaction &&  )
default

Member Function Documentation

◆ alert()

StateTransaction & hueplusplus::StateTransaction::alert ( )

Trigger an alert.

The light performs one breathe cycle.

Returns
This transaction for chaining calls

◆ commit()

bool hueplusplus::StateTransaction::commit ( bool  trimRequest = true)

Commit transaction and make request.

Parameters
trimRequestOptional. When true, request parameters that are unneccessary based on the current state are removed. This reduces load on the bridge. On the other hand, an outdated state might cause requests to be dropped unexpectedly. Has no effect on groups.
Returns
true on success or when no change was requested.
Note
After changing the state of a Light or Group, refresh() must be called if the updated values are needed immediately.
Exceptions
std::system_errorwhen system or socket operations fail
HueExceptionwhen response contains no body
HueAPIResponseExceptionwhen response contains an error
nlohmann::json::parse_errorwhen response could not be parsed

◆ incrementBrightness()

StateTransaction & hueplusplus::StateTransaction::incrementBrightness ( int  increment)

Increment/Decrement brightness.

Parameters
incrementBrightness change from -254 to 254.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have brightness control.

◆ incrementColorTemperature()

StateTransaction & hueplusplus::StateTransaction::incrementColorTemperature ( int  increment)

Increment/Decrement color temperature.

Parameters
incrementColor temperature change in mired from -65535 to 65535.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have color temperature control.

◆ incrementColorXY()

StateTransaction & hueplusplus::StateTransaction::incrementColorXY ( float  xInc,
float  yInc 
)

Increment/Decrement color xy.

Parameters
xIncx color coordinate change from -0.5 to 0.5.
yIncy color coordinate change from -0.5 to 0.5.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.

◆ incrementHue()

StateTransaction & hueplusplus::StateTransaction::incrementHue ( int  increment)

Increment/Decrement hue.

Parameters
incrementHue change from -65535 to 65535.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.

◆ incrementSaturation()

StateTransaction & hueplusplus::StateTransaction::incrementSaturation ( int  increment)

Increment/Decrement saturaction.

Parameters
incrementSaturation change from -254 to 254.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.

◆ longAlert()

StateTransaction & hueplusplus::StateTransaction::longAlert ( )

Trigger a long alert (15s).

Returns
This transaction for chaining calls

◆ setBrightness()

StateTransaction & hueplusplus::StateTransaction::setBrightness ( uint8_t  brightness)

Set light brightness.

Parameters
brightnessBrightness from 0 = off to 254 = fully lit.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have brightness control.
Brightness 0 will also turn off the light if nothing else is specified, any other value will also turn on the light.

◆ setColor() [1/3]

StateTransaction & hueplusplus::StateTransaction::setColor ( const HueSaturation hueSat)

Set light color in hue and saturation.

Parameters
hueSatColor in hue and saturation
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColor() [2/3]

StateTransaction & hueplusplus::StateTransaction::setColor ( const XY xy)

Set light color in xy space (without brightness).

Parameters
xyx and y coordinates in CIE color space
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColor() [3/3]

StateTransaction & hueplusplus::StateTransaction::setColor ( const XYBrightness xy)

Set light color and brightness in xy space.

Parameters
xyx,y and brightness in CIE color space
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColorHue()

StateTransaction & hueplusplus::StateTransaction::setColorHue ( uint16_t  hue)

Set light hue.

Parameters
hueColor hue from 0 to 65535
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColorLoop()

StateTransaction & hueplusplus::StateTransaction::setColorLoop ( bool  on)

Enables or disables color loop.

Parameters
ontrue to enable, false to disable color loop.
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColorSaturation()

StateTransaction & hueplusplus::StateTransaction::setColorSaturation ( uint8_t  saturation)

Set light saturation.

Parameters
saturationColor saturation from 0 to 254
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have rgb color control.
Will also turn on the light if nothing else is specified

◆ setColorTemperature()

StateTransaction & hueplusplus::StateTransaction::setColorTemperature ( unsigned int  mired)

Set light color temperature.

Parameters
miredColor temperature in mired from 153 to 500
Returns
This transaction for chaining calls
Note
If this transaction is for a light, the light needs to have color temperature control.
Will also turn on the light if nothing else is specified

◆ setOn()

StateTransaction & hueplusplus::StateTransaction::setOn ( bool  on)

Turn light on or off.

Parameters
ontrue for on, false for off
Returns
This transaction for chaining calls

◆ setTransition()

StateTransaction & hueplusplus::StateTransaction::setTransition ( uint16_t  transition)

Set transition time for the request.

Parameters
transitionTransition time in 100ms, default for any request is 400ms.
Returns
This transaction for chaining calls
Note
The transition only applies to the current request. A request without any changes only containing a transition is pointless and is not sent.

◆ stopAlert()

StateTransaction & hueplusplus::StateTransaction::stopAlert ( )

Stop an ongoing long alert.

Returns
This transaction for chaining calls

◆ toAction()

Action hueplusplus::StateTransaction::toAction ( )

Create an Action from the transaction.

Returns
An Action that can be used to execute this transaction on a Schedule or Rule.

◆ trimRequest()

void hueplusplus::StateTransaction::trimRequest ( )
protected

Remove parts from request that are already set in state.

Member Data Documentation

◆ commands

const HueCommandAPI& hueplusplus::StateTransaction::commands
protected

◆ path

std::string hueplusplus::StateTransaction::path
protected

◆ request

nlohmann::json hueplusplus::StateTransaction::request
protected

◆ state

nlohmann::json* hueplusplus::StateTransaction::state
protected

The documentation for this class was generated from the following files: