transactions.html
7.43 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>hueplusplus: Transactions</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">hueplusplus
 <span id="projectnumber">1.0.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Transactions </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><ul><li class="level2"><a href="#autotoc_md28">Using a transaction for lights</a><ul><li class="level3"><a href="#autotoc_md29">Advanced usage</a></li>
</ul>
</li>
<li class="level2"><a href="#autotoc_md30">Using a transaction for groups</a></li>
<li class="level2"><a href="#autotoc_md31">Creating Actions</a></li>
</ul>
</ul>
</div>
<div class="textblock"><p>Often, you want to change more than one property on a light at the same time, for example brightness and color. This is done using transactions (<a class="el" href="classhueplusplus_1_1_state_transaction.html">StateTransaction</a>). </p><div class="fragment"><div class="line"> light.<a class="code" href="classhueplusplus_1_1_light.html#a37d025adaf1791ac0ba904fa52a5bfb5">transaction</a>().<a class="code" href="classhueplusplus_1_1_state_transaction.html#a1627d0ca2714a6c24e5e1c7b9647bd70">setOn</a>(<span class="keyword">true</span>).<a class="code" href="classhueplusplus_1_1_state_transaction.html#a3502aed5c5b47f058133358959c171e5">setBrightness</a>(29).<a class="code" href="classhueplusplus_1_1_state_transaction.html#a6861e2c1cdbf0e95b14b81869a5eb7de">setColorHue</a>(3000).<a class="code" href="classhueplusplus_1_1_state_transaction.html#aa436b81cd742568d6230e841826cd044">setColorSaturation</a>(128).<a class="code" href="classhueplusplus_1_1_state_transaction.html#aeb7dae7c01fdffad9e224e5393f83b85">commit</a>();</div></div><!-- fragment --><p> The request is reduced to only the variables that need to be changed based on the current state. For example, if the light is already on, that part of the transaction is ignored.</p>
<p><b>Important:</b> 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.</p>
<p>Another way to use the transaction is by storing it and building up the calls separately. </p><div class="fragment"><div class="line"> <a class="code" href="classhueplusplus_1_1_state_transaction.html">hueplusplus::StateTransaction</a> t = light.<a class="code" href="classhueplusplus_1_1_light.html#a37d025adaf1791ac0ba904fa52a5bfb5">transaction</a>();</div><div class="line"> <span class="keywordflow">if</span> (shouldTurnOn)</div><div class="line"> t.<a class="code" href="classhueplusplus_1_1_state_transaction.html#a1627d0ca2714a6c24e5e1c7b9647bd70">setOn</a>(<span class="keyword">true</span>);</div><div class="line"> t.<a class="code" href="classhueplusplus_1_1_state_transaction.html#aeb7dae7c01fdffad9e224e5393f83b85">commit</a>();</div></div><!-- fragment --><p> In this case, it is especially important that the light and the state of the light <b>MUST NOT</b> invalidate. That means</p><ul>
<li>the light variable has to live longer than the transaction</li>
<li>especially no non-const method calls on the light while the transaction is open, or committing other transactions</li>
</ul>
<p>In general, this method is easier to screw up and should only be used when really necessary.</p>
<p>The same principles of transactions for lights also apply for groups. The main difference is that for groups, there are no checks of the current state. Even if all lights in the group are already on, the request to turn on all lights on the group is still sent. </p><div class="fragment"><div class="line"> group.<a class="code" href="classhueplusplus_1_1_group.html#a0cbbc12721df742db97eb824a9356384">transaction</a>().<a class="code" href="classhueplusplus_1_1_state_transaction.html#a1627d0ca2714a6c24e5e1c7b9647bd70">setOn</a>(<span class="keyword">true</span>).<a class="code" href="classhueplusplus_1_1_state_transaction.html#a3502aed5c5b47f058133358959c171e5">setBrightness</a>(64).<a class="code" href="classhueplusplus_1_1_state_transaction.html#aeb7dae7c01fdffad9e224e5393f83b85">commit</a>();</div></div><!-- fragment --><p>In a <a class="el" href="classhueplusplus_1_1_schedule.html">Schedule</a> or <a class="el" href="classhueplusplus_1_1_rule.html">Rule</a>, the bridge can set the state of lights and groups. To configure this, a transaction can be saved for later instead of committing it directly. </p><div class="fragment"><div class="line"> <a class="code" href="classhueplusplus_1_1_action.html">hueplusplus::Action</a> action = light.<a class="code" href="classhueplusplus_1_1_light.html#a37d025adaf1791ac0ba904fa52a5bfb5">transaction</a>().<a class="code" href="classhueplusplus_1_1_state_transaction.html#a1627d0ca2714a6c24e5e1c7b9647bd70">setOn</a>(<span class="keyword">true</span>).<a class="code" href="classhueplusplus_1_1_state_transaction.html#a3502aed5c5b47f058133358959c171e5">setBrightness</a>(254).<a class="code" href="classhueplusplus_1_1_state_transaction.html#a44db927471c11bab402e9a295014adff">toAction</a>();</div><div class="line"> schedule.setCommand(action);</div></div><!-- fragment --></div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>