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.
	StateTransaction (const StateTransaction &)=delete
	Deleted copy constructor, do not store StateTransaction in a variable.
	StateTransaction (StateTransaction &&)=default
bool	commit (bool trimRequest=true)
	Commit transaction and make request.
Action	toAction ()
	Create an Action from the transaction.
StateTransaction &	setOn (bool on)
	Turn light on or off.
StateTransaction &	setBrightness (uint8_t brightness)
	Set light brightness.
StateTransaction &	setColorHue (uint16_t hue)
	Set light hue.
StateTransaction &	setColorSaturation (uint8_t saturation)
	Set light saturation.
StateTransaction &	setColor (const HueSaturation &hueSat)
	Set light color in hue and saturation.
StateTransaction &	setColor (const XY &xy)
	Set light color in xy space (without brightness).
StateTransaction &	setColor (const XYBrightness &xy)
	Set light color and brightness in xy space.
StateTransaction &	setColorTemperature (unsigned int mired)
	Set light color temperature.
StateTransaction &	setColorLoop (bool on)
	Enables or disables color loop.
StateTransaction &	incrementBrightness (int increment)
	Increment/Decrement brightness.
StateTransaction &	incrementSaturation (int increment)
	Increment/Decrement saturaction.
StateTransaction &	incrementHue (int increment)
	Increment/Decrement hue.
StateTransaction &	incrementColorTemperature (int increment)
	Increment/Decrement color temperature.
StateTransaction &	incrementColorXY (float xInc, float yInc)
	Increment/Decrement color xy.
StateTransaction &	setTransition (uint16_t transition)
	Set transition time for the request.
StateTransaction &	alert ()
	Trigger an alert.
StateTransaction &	longAlert ()
	Trigger a long alert (15s).
StateTransaction &	stopAlert ()
	Stop an ongoing long alert.

Protected Member Functions
void	trimRequest ()
	Remove parts from request that are already set in state.

Protected Attributes
const HueCommandAPI &	commands
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.

light.transaction().setOn(true).setBrightness(29).setColorHue(3000).setColorSaturation(128).commit();

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.

hueplusplus::StateTransaction t = light.transaction();
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

the light variable has to live longer than the transaction
especially no non-const method calls on the light while the transaction is open, or committing other transactions

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

commands	HueCommandAPI for making requests
path	Path to which the final PUT request is made (without username)
currentState	Optional, 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

trimRequest Optional. 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_error	when system or socket operations fail
HueException	when response contains no body
HueAPIResponseException	when response contains an error
nlohmann::json::parse_error	when response could not be parsed

◆ incrementBrightness()

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

Increment/Decrement brightness.

Parameters

increment Brightness 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

increment Color 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

xInc	x color coordinate change from -0.5 to 0.5.
yInc	y 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

increment Hue 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

increment Saturation 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

brightness Brightness 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

hueSat Color 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

xy	x 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

xy	x,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

hue	Color 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

on	true 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

saturation Color 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

mired Color 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

on	true 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

transition Transition 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:

include/hueplusplus/StateTransaction.h
src/StateTransaction.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Advanced usage

Constructor & Destructor Documentation

◆ StateTransaction() [1/3]

◆ StateTransaction() [2/3]

◆ StateTransaction() [3/3]

Member Function Documentation

◆ alert()

◆ commit()

◆ incrementBrightness()

◆ incrementColorTemperature()

◆ incrementColorXY()

◆ incrementHue()

◆ incrementSaturation()

◆ longAlert()

◆ setBrightness()

◆ setColor() [1/3]

◆ setColor() [2/3]

◆ setColor() [3/3]

◆ setColorHue()

◆ setColorLoop()

◆ setColorSaturation()

◆ setColorTemperature()

◆ setOn()

◆ setTransition()

◆ stopAlert()

◆ toAction()

◆ trimRequest()

Member Data Documentation

◆ commands

◆ path

◆ request

◆ state