Loading...
Searching...
No Matches
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:
[legend]

## 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();
hueplusplus::StateTransaction
Transaction class which can be used for either light or group state.
Definition StateTransaction.h:62
hueplusplus::StateTransaction::setOn
StateTransaction & setOn(bool on)
Turn light on or off.
Definition StateTransaction.cpp:91
hueplusplus::StateTransaction::commit
bool commit(bool trimRequest=true)
Commit transaction and make request.
Definition StateTransaction.cpp:36

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