/usr/share/qt5/doc/qtbluetooth/qlowenergyservice.html is in qtconnectivity5-doc-html 5.7.1~20161021-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qlowenergyservice.cpp -->
<title>QLowEnergyService Class | Qt Bluetooth 5.7</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
window.onload = function(){document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");};
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.7</td><td ><a href="qtbluetooth-index.html">Qt Bluetooth</a></td><td ><a href="qtbluetooth-module.html">C++ Classes</a></td><td >QLowEnergyService</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.7.1 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#signals">Signals</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#service-structure">Service Structure</a></li>
<li class="level2"><a href="#service-interaction">Service Interaction</a></li>
<li class="level2"><a href="#service-data-sharing">Service Data Sharing</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QLowEnergyService Class</h1>
<!-- $$$QLowEnergyService-brief -->
<p>The <a href="qlowenergyservice.html">QLowEnergyService</a> class represents an individual service on a Bluetooth Low Energy Device. <a href="#details">More...</a></p>
<!-- @@@QLowEnergyService -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QLowEnergyService></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += bluetooth</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.4</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <a href="../qtcore/qobject.html">QObject</a></td></tr></table></div><ul>
<li><a href="qlowenergyservice-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#ServiceError-enum">ServiceError</a></b> { NoError, OperationError, CharacteristicReadError, CharacteristicWriteError, ..., UnknownError }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#ServiceState-enum">ServiceState</a></b> { InvalidService, DiscoveryRequired, DiscoveringServices, ServiceDiscovered, LocalService }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#ServiceType-enum">ServiceType</a></b> { PrimaryService, IncludedService }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> flags </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#ServiceType-enum">ServiceTypes</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#WriteMode-enum">WriteMode</a></b> { WriteWithResponse, WriteWithoutResponse, WriteSigned }</td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#dtor.QLowEnergyService">~QLowEnergyService</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyCharacteristic </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#characteristic">characteristic</a></b>(const QBluetoothUuid &<i>uuid</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QList<QLowEnergyCharacteristic> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#characteristics">characteristics</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#contains">contains</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#contains-1">contains</a></b>(const QLowEnergyDescriptor &<i>descriptor</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#discoverDetails">discoverDetails</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> ServiceError </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#error">error</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QList<QBluetoothUuid> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#includedServices">includedServices</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#readCharacteristic">readCharacteristic</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#readDescriptor">readDescriptor</a></b>(const QLowEnergyDescriptor &<i>descriptor</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#serviceName">serviceName</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QBluetoothUuid </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#serviceUuid">serviceUuid</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyService::ServiceState </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#state">state</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyService::ServiceTypes </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#type">type</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>, const QByteArray &<i>newValue</i>, WriteMode <i>mode</i> = WriteWithResponse)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#writeDescriptor">writeDescriptor</a></b>(const QLowEnergyDescriptor &<i>descriptor</i>, const QByteArray &<i>newValue</i>)</td></tr>
</table></div>
<ul>
<li class="fn">31 public functions inherited from <a href="../qtcore/qobject.html#public-functions">QObject</a></li>
</ul>
<a name="signals"></a>
<h2 id="signals">Signals</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#characteristicChanged">characteristicChanged</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>, const QByteArray &<i>newValue</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#characteristicRead">characteristicRead</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>, const QByteArray &<i>value</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#characteristicWritten">characteristicWritten</a></b>(const QLowEnergyCharacteristic &<i>characteristic</i>, const QByteArray &<i>newValue</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#descriptorRead">descriptorRead</a></b>(const QLowEnergyDescriptor &<i>descriptor</i>, const QByteArray &<i>value</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#descriptorWritten">descriptorWritten</a></b>(const QLowEnergyDescriptor &<i>descriptor</i>, const QByteArray &<i>newValue</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#error-1">error</a></b>(QLowEnergyService::ServiceError <i>newError</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlowenergyservice.html#stateChanged">stateChanged</a></b>(QLowEnergyService::ServiceState <i>newState</i>)</td></tr>
</table></div>
<ul>
<li class="fn">2 signals inherited from <a href="../qtcore/qobject.html#signals">QObject</a></li>
</ul>
<h3>Additional Inherited Members</h3>
<ul>
<li class="fn">1 property inherited from <a href="../qtcore/qobject.html#properties">QObject</a></li>
<li class="fn">1 public slot inherited from <a href="../qtcore/qobject.html#public-slots">QObject</a></li>
<li class="fn">1 public variable inherited from <a href="../qtcore/qobject.html#public-variables">QObject</a></li>
<li class="fn">10 static public members inherited from <a href="../qtcore/qobject.html#static-public-members">QObject</a></li>
<li class="fn">9 protected functions inherited from <a href="../qtcore/qobject.html#protected-functions">QObject</a></li>
<li class="fn">2 protected variables inherited from <a href="../qtcore/qobject.html#protected-variables">QObject</a></li>
</ul>
<a name="details"></a>
<!-- $$$QLowEnergyService-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qlowenergyservice.html">QLowEnergyService</a> class represents an individual service on a Bluetooth Low Energy Device.</p>
<p><a href="qlowenergyservice.html">QLowEnergyService</a> provides access to the details of Bluetooth Low Energy services. The class facilitates the discovery and publification of service details, permits reading and writing of the contained data and notifies about data changes.</p>
<a name="service-structure"></a>
<h3 >Service Structure</h3>
<p>A Bluetooth Low Energy peripheral device can contain multiple services. In turn each service may include further services. This class represents a single service of the peripheral device and is created via <a href="qlowenergycontroller.html#createServiceObject">QLowEnergyController::createServiceObject</a>(). The <a href="qlowenergyservice.html#type">type</a>() indicates whether this service is a primary (top-level) service or whether the service is part of another service. Each service may contain one or more characteristics and each characteristic may contain descriptors. The resulting structure may look like the following diagram:</p>
<p class="centerAlign"><img src="images/peripheral-structure.png" alt="Structure of a generic peripheral" /></p><p>A characteristic is the principle information carrier. It has a <a href="qlowenergycharacteristic.html#value">value()</a> and <a href="qlowenergycharacteristic.html#value">properties()</a> describing the access permissions for the value. The general purpose of the contained descriptor is to further define the nature of the characteristic. For example, it might specify how the value is meant to be interpreted or whether it can notify the value consumer about value changes.</p>
<a name="service-interaction"></a>
<h3 >Service Interaction</h3>
<p>Once a service object was created for the first time, its details are yet to be discovered. This is indicated by its current <a href="qlowenergyservice.html#state">state</a>() being <a href="qlowenergyservice.html#ServiceState-enum">DiscoveryRequired</a>. It is only possible to retrieve the <a href="qlowenergyservice.html#serviceUuid">serviceUuid</a>() and <a href="qlowenergyservice.html#serviceName">serviceName</a>().</p>
<p>The discovery of its included services, characteristics and descriptors is triggered when calling <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>(). During the discovery the <a href="qlowenergyservice.html#state">state</a>() transitions from <a href="qlowenergyservice.html#ServiceState-enum">DiscoveryRequired</a> via <a href="qlowenergyservice.html#ServiceState-enum">DiscoveringServices</a> to its final <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state. This transition is advertised via the <a href="qlowenergyservice.html#stateChanged">stateChanged</a>() signal. Once the details are known, all of the contained characteristics, descriptors and included services are known and can be read or written.</p>
<p>The values of characteristics and descriptors can be retrieved via <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> and <a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a>, respectively. However, direct reading or writing of these attributes requires the service object. The <a href="qlowenergyservice.html#readCharacteristic">readCharacteristic</a>() function attempts to re-read the value of a characteristic. Although the initial service discovery may have obtained a value already this call may be required in cases where the characteristic value constantly changes without any notifications being provided. An example might be a time characteristic that provides a continuous value. If the read attempt is successful, the <a href="qlowenergyservice.html#characteristicRead">characteristicRead</a>() signal is emitted. A failure to read the value triggers the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicReadError</a>. The <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>() function attempts to write a new value to the given characteristic. If the write attempt is successful, the <a href="qlowenergyservice.html#characteristicWritten">characteristicWritten</a>() signal is emitted. A failure to write triggers the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a>. Reading and writing of descriptors follows the same pattern.</p>
<p>Every attempt is made to read or write the value of a descriptor or characteristic on the hardware. This means that meta information such as <a href="qlowenergycharacteristic.html#properties">QLowEnergyCharacteristic::properties</a>() is generally ignored when reading and writing. As an example, it is possible to call <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>() despite the characteristic being read-only based on its meta data description. The resulting write request is forwarded to the connected device and it is up to the device to respond to the potentially invalid request. In this case the result is the emission of the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a> in response to the returned device error. This behavior simplifies interaction with devices which report wrong meta information. If it was not possible to forward the request to the remote device the <a href="qlowenergyservice.html#ServiceError-enum">OperationError</a> is set. A potential reason could be that the to-be-written characteristic object does not even belong the current service. In summary, the two types of errors permit a quick distinction of local and remote error cases.</p>
<p>All requests are serialised based on First-In First-Out principle. For example, issuing a second write request, before the previous write request has finished, is delayed until the first write request has finished.</p>
<p><b>Note: </b>Currently, it is not possible to send signed write or reliable write requests.</p><a name="notifications"></a><p>In some cases the peripheral generates value updates which the central is interested in receiving. In order for a characteristic to support such notifications it must have the <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::Notify</a> or <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::Indicate</a> property and a descriptor of type <a href="qbluetoothuuid.html#DescriptorType-enum">QBluetoothUuid::ClientCharacteristicConfiguration</a>. Provided those conditions are fulfilled notifications can be enabled as shown in the following code segment:</p>
<pre class="cpp">
<span class="comment">//PreCondition: service details already discovered</span>
<span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> batteryLevel <span class="operator">=</span> service<span class="operator">-</span><span class="operator">></span>characteristic(
<span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span><span class="operator">::</span>BatteryLevel);
<span class="keyword">if</span> (<span class="operator">!</span>batteryLevel<span class="operator">.</span>isValid())
<span class="keyword">return</span>;
<span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> notification <span class="operator">=</span> batteryLevel<span class="operator">.</span>descriptor(
<span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span><span class="operator">::</span>ClientCharacteristicConfiguration);
<span class="keyword">if</span> (<span class="operator">!</span>notification<span class="operator">.</span>isValid())
<span class="keyword">return</span>;
<span class="comment">// establish hook into notifications</span>
connect(service<span class="operator">,</span> SIGNAL(characteristicChanged(<span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span><span class="operator">,</span><span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(characteristicChanged(<span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span><span class="operator">,</span><span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span>)));
<span class="comment">// enable notification</span>
service<span class="operator">-</span><span class="operator">></span>writeDescriptor(notification<span class="operator">,</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span><span class="operator">::</span>fromHex(<span class="string">"0100"</span>));
<span class="comment">// disable notification</span>
<span class="comment">//service->writeDescriptor(notification, QByteArray::fromHex("0000"));</span>
<span class="comment">// wait until descriptorWritten() signal is emitted</span>
<span class="comment">// to confirm successful write</span>
</pre>
<p>The example shows a battery level characteristic which updates the central on every value change. The notifications are provided via the <a href="qlowenergyservice.html#characteristicChanged">characteristicChanged</a>() signal. More details about this mechanism are provided by the <a href="https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml">Bluetooth Specification</a>.</p>
<a name="service-data-sharing"></a>
<h3 >Service Data Sharing</h3>
<p>Each <a href="qlowenergyservice.html">QLowEnergyService</a> instance shares its internal states and information with other <a href="qlowenergyservice.html">QLowEnergyService</a> instance of the same service. If one instance initiates the discovery of the service details, all remaining instances automatically follow. Therefore the following snippet always works:</p>
<pre class="cpp">
<span class="type">QLowEnergyService</span> <span class="operator">*</span>first<span class="operator">,</span> <span class="operator">*</span>second;
<span class="type"><a href="qlowenergycontroller.html">QLowEnergyController</a></span> control(remoteDevice);
control<span class="operator">.</span>connectToDevice();
<span class="comment">// waiting for connection</span>
first <span class="operator">=</span> control<span class="operator">.</span>createServiceObject(<span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span><span class="operator">::</span>BatteryService);
second <span class="operator">=</span> control<span class="operator">.</span>createServiceObject(<span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span><span class="operator">::</span>BatteryService);
Q_ASSERT(first<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> <span class="type">QLowEnergyService</span><span class="operator">::</span>DiscoveryRequired);
Q_ASSERT(first<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> second<span class="operator">-</span><span class="operator">></span>state());
first<span class="operator">-</span><span class="operator">></span>discoverDetails();
Q_ASSERT(first<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> <span class="type">QLowEnergyService</span><span class="operator">::</span>DiscoveringServices);
Q_ASSERT(first<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> second<span class="operator">-</span><span class="operator">></span>state());
</pre>
<p>Other operations such as calls to <a href="qlowenergyservice.html#readCharacteristic">readCharacteristic</a>(), <a href="qlowenergyservice.html#readDescriptor">readDescriptor</a>(), <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>(), <a href="qlowenergyservice.html#writeDescriptor">writeDescriptor</a>() or the invalidation of the service due to the related <a href="qlowenergycontroller.html">QLowEnergyController</a> disconnecting from the device are shared the same way.</p>
</div>
<p><b>See also </b><a href="qlowenergycontroller.html">QLowEnergyController</a>, <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a>, and <a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a>.</p>
<!-- @@@QLowEnergyService -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$ServiceError$$$NoError$$$OperationError$$$CharacteristicWriteError$$$DescriptorWriteError$$$UnknownError$$$CharacteristicReadError$$$DescriptorReadError -->
<h3 class="fn" id="ServiceError-enum"><a name="ServiceError-enum"></a>enum QLowEnergyService::<span class="name">ServiceError</span></h3>
<p>This enum describes all possible error conditions during the service's existence. The <a href="qlowenergyservice.html#error">error</a>() function returns the last occurred error.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QLowEnergyService::NoError</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">No error has occurred.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::OperationError</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">An operation was attempted while the service was not ready. An example might be the attempt to write to the service while it was not yet in the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> <a href="qlowenergyservice.html#state">state</a>() or the service is invalid due to a loss of connection to the peripheral device.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::CharacteristicReadError</code></td><td class="topAlign tblval"><code>5</code></td><td class="topAlign">An attempt to read a characteristic value failed. For example, it might be triggered in response to a call to <a href="qlowenergyservice.html#readCharacteristic">readCharacteristic</a>(). This value was introduced by Qt 5.5.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::CharacteristicWriteError</code></td><td class="topAlign tblval"><code>2</code></td><td class="topAlign">An attempt to write a new value to a characteristic failed. For example, it might be triggered when attempting to write to a read-only characteristic.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::DescriptorReadError</code></td><td class="topAlign tblval"><code>6</code></td><td class="topAlign">An attempt to read a descriptor value failed. For example, it might be triggered in response to a call to <a href="qlowenergyservice.html#readDescriptor">readDescriptor</a>(). This value was introduced by Qt 5.5.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::DescriptorWriteError</code></td><td class="topAlign tblval"><code>3</code></td><td class="topAlign">An attempt to write a new value to a descriptor failed. For example, it might be triggered when attempting to write to a read-only descriptor.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::UnknownError</code></td><td class="topAlign tblval"><code>4</code></td><td class="topAlign">An unknown error occurred when interacting with the service. This value was introduced by Qt 5.5.</td></tr>
</table></div>
<!-- @@@ServiceError -->
<!-- $$$ServiceState$$$InvalidService$$$DiscoveryRequired$$$DiscoveringServices$$$ServiceDiscovered$$$LocalService -->
<h3 class="fn" id="ServiceState-enum"><a name="ServiceState-enum"></a>enum QLowEnergyService::<span class="name">ServiceState</span></h3>
<p>This enum describes the <a href="qlowenergyservice.html#state">state</a>() of the service object.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QLowEnergyService::InvalidService</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">A service can become invalid when it looses the connection to the underlying device. Even though the connection may be lost it retains its last information. An invalid service cannot become valid anymore even if the connection to the device is re-established.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::DiscoveryRequired</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">The service details are yet to be discovered by calling <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>(). The only reliable pieces of information are its <a href="qlowenergyservice.html#serviceUuid">serviceUuid</a>() and <a href="qlowenergyservice.html#serviceName">serviceName</a>().</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::DiscoveringServices</code></td><td class="topAlign tblval"><code>2</code></td><td class="topAlign">The service details are being discovered.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::ServiceDiscovered</code></td><td class="topAlign tblval"><code>3</code></td><td class="topAlign">The service details have been discovered.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::LocalService</code></td><td class="topAlign tblval"><code>4</code></td><td class="topAlign">The service is associated with a controller object in the <a href="qlowenergycontroller.html#Role-enum">peripheral role</a>. Such service objects do not change their state. This value was introduced by Qt 5.7.</td></tr>
</table></div>
<!-- @@@ServiceState -->
<!-- $$$ServiceType$$$PrimaryService$$$IncludedService -->
<h3 class="flags" id="ServiceType-enum"><a name="ServiceType-enum"></a>enum QLowEnergyService::<span class="name">ServiceType</span><br/>flags QLowEnergyService::<span class="name">ServiceTypes</span></h3>
<p>This enum describes the type of the service.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QLowEnergyService::PrimaryService</code></td><td class="topAlign tblval"><code>0x0001</code></td><td class="topAlign">The service is a top-level/primary service. If this type flag is not set, the service is considered to be a secondary service. Each service may be included by another service which is indicated by IncludedService.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::IncludedService</code></td><td class="topAlign tblval"><code>0x0002</code></td><td class="topAlign">The service is included by another service. On some platforms, this flag cannot be determined until the service that includes the current service was discovered.</td></tr>
</table></div>
<p>The ServiceTypes type is a typedef for <a href="../qtcore/qflags.html">QFlags</a><ServiceType>. It stores an OR combination of ServiceType values.</p>
<!-- @@@ServiceType -->
<!-- $$$WriteMode$$$WriteWithResponse$$$WriteWithoutResponse$$$WriteSigned -->
<h3 class="fn" id="WriteMode-enum"><a name="WriteMode-enum"></a>enum QLowEnergyService::<span class="name">WriteMode</span></h3>
<p>This enum describes the mode to be used when writing a characteristic value. The characteristic advertises its supported write modes via its <a href="qlowenergycharacteristic.html#properties">properties</a>.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QLowEnergyService::WriteWithResponse</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">If a characteristic is written using this mode, the peripheral shall send a write confirmation. If the operation is successful, the confirmation is emitted via the <a href="qlowenergyservice.html#characteristicWritten">characteristicWritten</a>() signal. Otherwise the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a> is emitted. A characteristic must have set the <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::Write</a> property to support this write mode.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::WriteWithoutResponse</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">If a characteristic is written using this mode, the remote peripheral shall not send a write confirmation. The operation's success cannot be determined and the payload must not be longer than 20 bytes. A characteristic must have set the <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::WriteNoResponse</a> property to support this write mode. Its adavantage is a quicker write operation as it may happen in between other device interactions.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyService::WriteSigned</code></td><td class="topAlign tblval"><code>2</code></td><td class="topAlign">If a characteristic is written using this mode, the remote peripheral shall not send a write confirmation. The operation's success cannot be determined and the payload must not be longer than 8 bytes. A bond must exist between the two devices and the link must not be encrypted. A characteristic must have set the <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::WriteSigned</a> property to support this write mode. This value was introduced in Qt 5.7 and is currently only supported on Android and on Linux with BlueZ 5 and a kernel version 3.7 or newer.</td></tr>
</table></div>
<!-- @@@WriteMode -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$~QLowEnergyService[overload1]$$$~QLowEnergyService -->
<h3 class="fn" id="dtor.QLowEnergyService"><a name="dtor.QLowEnergyService"></a>QLowEnergyService::<span class="name">~QLowEnergyService</span>()</h3>
<p>Destroys the <a href="qlowenergyservice.html">QLowEnergyService</a> instance.</p>
<!-- @@@~QLowEnergyService -->
<!-- $$$characteristic[overload1]$$$characteristicconstQBluetoothUuid& -->
<h3 class="fn" id="characteristic"><a name="characteristic"></a><span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> QLowEnergyService::<span class="name">characteristic</span>(const <span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span> &<i>uuid</i>) const</h3>
<p>Returns the matching characteristic for <i>uuid</i>; otherwise an invalid characteristic.</p>
<p>The returned characteristic is invalid if this service instance's <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>() was not yet called or there are no characteristics with a matching <i>uuid</i>.</p>
<p><b>See also </b><a href="qlowenergyservice.html#characteristics">characteristics</a>().</p>
<!-- @@@characteristic -->
<!-- $$$characteristicChanged[overload1]$$$characteristicChangedconstQLowEnergyCharacteristic&constQByteArray& -->
<h3 class="fn" id="characteristicChanged"><a name="characteristicChanged"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">characteristicChanged</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>newValue</i>)</h3>
<p>If the associated controller object is in the <a href="qlowenergycontroller.html#Role-enum">central</a> role, this signal is emitted when the value of <i>characteristic</i> is changed by an event on the peripheral. In that case, the signal emission implies that change notifications must have been activated via the characteristic's <a href="qbluetoothuuid.html#DescriptorType-enum">ClientCharacteristicConfiguration</a> descriptor prior to the change event on the peripheral. More details on how this might be done can be found further <a href="qlowenergyservice.html#notifications">above</a>.</p>
<p>If the controller is in the <a href="qlowenergycontroller.html#Role-enum">peripheral</a> role, that is, the service object was created via <a href="qlowenergycontroller.html#addService">QLowEnergyController::addService</a>, the signal is emitted when a GATT client has written the value of the characteristic using a write request or command.</p>
<p>The <i>newValue</i> parameter contains the updated value of the <i>characteristic</i>.</p>
<!-- @@@characteristicChanged -->
<!-- $$$characteristicRead[overload1]$$$characteristicReadconstQLowEnergyCharacteristic&constQByteArray& -->
<h3 class="fn" id="characteristicRead"><a name="characteristicRead"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">characteristicRead</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>value</i>)</h3>
<p>This signal is emitted when the read request for <i>characteristic</i> successfully returned its <i>value</i>. The signal might be triggered by calling characteristicRead(). If the read operation is not successful, the <a href="qlowenergyservice.html#error">error</a>() signal is emitted using the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicReadError</a> flag.</p>
<p>This function was introduced in Qt 5.5.</p>
<p><b>See also </b><a href="qlowenergyservice.html#readCharacteristic">readCharacteristic</a>().</p>
<!-- @@@characteristicRead -->
<!-- $$$characteristicWritten[overload1]$$$characteristicWrittenconstQLowEnergyCharacteristic&constQByteArray& -->
<h3 class="fn" id="characteristicWritten"><a name="characteristicWritten"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">characteristicWritten</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>newValue</i>)</h3>
<p>This signal is emitted when the value of <i>characteristic</i> is successfully changed to <i>newValue</i>. The change must have been triggered by calling <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>(). If the write operation is not successful, the <a href="qlowenergyservice.html#error">error</a>() signal is emitted using the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a> flag.</p>
<p>Since this signal is an indication of a successful write operation <i>newValue</i> generally matches the value that was passed to the associated <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>() call. However, it may happen that the two values differ from each other. This can occur in cases when the written value is used by the remote device to trigger an operation and it returns some other value via the written and/or change notification. Such cases are very specific to the target device. In any case, the reception of the written signal can still be considered as a sign that the target device received the to-be-written value.</p>
<p><b>Note: </b>If <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>() is called using the <a href="qlowenergyservice.html#WriteMode-enum">WriteWithoutResponse</a> mode, this signal and the <a href="qlowenergyservice.html#error">error</a>() are never emitted.</p><p><b>See also </b><a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>().</p>
<!-- @@@characteristicWritten -->
<!-- $$$characteristics[overload1]$$$characteristics -->
<h3 class="fn" id="characteristics"><a name="characteristics"></a><span class="type"><a href="../qtcore/qlist.html">QList</a></span><<span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span>> QLowEnergyService::<span class="name">characteristics</span>() const</h3>
<p>Returns all characteristics associated with this <code>QLowEnergyService</code> instance.</p>
<p>The returned list is empty if this service instance's <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>() was not yet called or there are no known characteristics.</p>
<p><b>See also </b><a href="qlowenergyservice.html#characteristic">characteristic</a>(), <a href="qlowenergyservice.html#state">state</a>(), and <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>().</p>
<!-- @@@characteristics -->
<!-- $$$contains[overload1]$$$containsconstQLowEnergyCharacteristic& -->
<h3 class="fn" id="contains"><a name="contains"></a><span class="type">bool</span> QLowEnergyService::<span class="name">contains</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>) const</h3>
<p>Returns <code>true</code> if <i>characteristic</i> belongs to this service; otherwise <code>false</code>.</p>
<p>A characteristic belongs to a service if <a href="qlowenergyservice.html#characteristics">characteristics</a>() contains the <i>characteristic</i>.</p>
<!-- @@@contains -->
<!-- $$$contains$$$containsconstQLowEnergyDescriptor& -->
<h3 class="fn" id="contains-1"><a name="contains-1"></a><span class="type">bool</span> QLowEnergyService::<span class="name">contains</span>(const <span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> &<i>descriptor</i>) const</h3>
<p>Returns <code>true</code> if <i>descriptor</i> belongs to this service; otherwise <code>false</code>.</p>
<!-- @@@contains -->
<!-- $$$descriptorRead[overload1]$$$descriptorReadconstQLowEnergyDescriptor&constQByteArray& -->
<h3 class="fn" id="descriptorRead"><a name="descriptorRead"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">descriptorRead</span>(const <span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> &<i>descriptor</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>value</i>)</h3>
<p>This signal is emitted when the read request for <i>descriptor</i> successfully returned its <i>value</i>. The signal might be triggered by calling descriptorRead(). If the read operation is not successful, the <a href="qlowenergyservice.html#error">error</a>() signal is emitted using the <a href="qlowenergyservice.html#ServiceError-enum">DescriptorReadError</a> flag.</p>
<p>This function was introduced in Qt 5.5.</p>
<p><b>See also </b><a href="qlowenergyservice.html#readDescriptor">readDescriptor</a>().</p>
<!-- @@@descriptorRead -->
<!-- $$$descriptorWritten[overload1]$$$descriptorWrittenconstQLowEnergyDescriptor&constQByteArray& -->
<h3 class="fn" id="descriptorWritten"><a name="descriptorWritten"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">descriptorWritten</span>(const <span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> &<i>descriptor</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>newValue</i>)</h3>
<p>This signal is emitted when the value of <i>descriptor</i> is successfully changed to <i>newValue</i>. If the associated controller object is in the <a href="qlowenergycontroller.html#Role-enum">central</a> role, the change must have been caused by calling <a href="qlowenergyservice.html#writeDescriptor">writeDescriptor</a>(). Otherwise, the signal is the result of a write request or command from a GATT client to the respective descriptor.</p>
<p><b>See also </b><a href="qlowenergyservice.html#writeDescriptor">writeDescriptor</a>().</p>
<!-- @@@descriptorWritten -->
<!-- $$$discoverDetails[overload1]$$$discoverDetails -->
<h3 class="fn" id="discoverDetails"><a name="discoverDetails"></a><span class="type">void</span> QLowEnergyService::<span class="name">discoverDetails</span>()</h3>
<p>Initiates the discovery of the services, characteristics and descriptors contained by the service. The discovery process is indicated via the <a href="qlowenergyservice.html#stateChanged">stateChanged</a>() signal.</p>
<p><b>See also </b><a href="qlowenergyservice.html#state">state</a>().</p>
<!-- @@@discoverDetails -->
<!-- $$$error[overload1]$$$error -->
<h3 class="fn" id="error"><a name="error"></a><span class="type"><a href="qlowenergyservice.html#ServiceError-enum">ServiceError</a></span> QLowEnergyService::<span class="name">error</span>() const</h3>
<p>Returns the last occurred error or <a href="qlowenergyservice.html#ServiceError-enum">NoError</a>.</p>
<!-- @@@error -->
<!-- $$$error$$$errorQLowEnergyService::ServiceError -->
<h3 class="fn" id="error-1"><a name="error-1"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">error</span>(<span class="type"><a href="qlowenergyservice.html#ServiceError-enum">QLowEnergyService::ServiceError</a></span> <i>newError</i>)</h3>
<p>This signal is emitted when an error occurrs. The <i>newError</i> parameter describes the error that occurred.</p>
<p><b>Note:</b> Signal <i>error</i> is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:<pre class="cpp">
connect(lowEnergyService<span class="operator">,</span> <span class="keyword">static_cast</span><span class="operator"><</span><span class="type">void</span>(<span class="type">QLowEnergyService</span><span class="operator">::</span><span class="operator">*</span>)(<span class="type">QLowEnergyService</span><span class="operator">::</span>ServiceError)<span class="operator">></span>(<span class="operator">&</span><span class="type">QLowEnergyService</span><span class="operator">::</span>error)<span class="operator">,</span>
<span class="operator">[</span><span class="operator">=</span><span class="operator">]</span>(<span class="type">QLowEnergyService</span><span class="operator">::</span>ServiceError newError){ <span class="comment">/* ... */</span> });
</pre>
<!-- @@@error -->
<!-- $$$includedServices[overload1]$$$includedServices -->
<h3 class="fn" id="includedServices"><a name="includedServices"></a><span class="type"><a href="../qtcore/qlist.html">QList</a></span><<span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span>> QLowEnergyService::<span class="name">includedServices</span>() const</h3>
<p>Returns the UUIDs of all services which are included by the current service.</p>
<p>The returned list is empty if this service instance's <a href="qlowenergyservice.html#discoverDetails">discoverDetails</a>() was not yet called or there are no known characteristics.</p>
<p>It is possible that an included service contains yet another service. Such second level includes have to be obtained via their relevant first level <a href="qlowenergyservice.html">QLowEnergyService</a> instance. Technically, this could create a circular dependency.</p>
<p><a href="qlowenergycontroller.html#createServiceObject">QLowEnergyController::createServiceObject</a>() should be used to obtain service instances for each of the UUIDs.</p>
<p><b>See also </b><a href="qlowenergycontroller.html#createServiceObject">createServiceObject</a>().</p>
<!-- @@@includedServices -->
<!-- $$$readCharacteristic[overload1]$$$readCharacteristicconstQLowEnergyCharacteristic& -->
<h3 class="fn" id="readCharacteristic"><a name="readCharacteristic"></a><span class="type">void</span> QLowEnergyService::<span class="name">readCharacteristic</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>)</h3>
<p>Reads the value of <i>characteristic</i>. If the operation is successful, the <a href="qlowenergyservice.html#characteristicRead">characteristicRead</a>() signal is emitted; otherwise the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicReadError</a> is set. In general, a <i>characteristic</i> is readable, if its <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::Read</a> property is set.</p>
<p>All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple requests at the same time. The queue does not eliminate duplicated read requests for the same characteristic.</p>
<p>A characteristic can only be read if the service is in the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state and belongs to the service. If one of these conditions is not true the <a href="qlowenergyservice.html#ServiceError-enum">QLowEnergyService::OperationError</a> is set.</p>
<p><b>Note: </b>Calling this function despite <a href="qlowenergycharacteristic.html#properties">QLowEnergyCharacteristic::properties</a>() reporting a non-readable property always attempts to read the characteristic's value on the hardware. If the hardware returns with an error the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicReadError</a> is set.</p><p>This function was introduced in Qt 5.5.</p>
<p><b>See also </b><a href="qlowenergyservice.html#characteristicRead">characteristicRead</a>() and <a href="qlowenergyservice.html#writeCharacteristic">writeCharacteristic</a>().</p>
<!-- @@@readCharacteristic -->
<!-- $$$readDescriptor[overload1]$$$readDescriptorconstQLowEnergyDescriptor& -->
<h3 class="fn" id="readDescriptor"><a name="readDescriptor"></a><span class="type">void</span> QLowEnergyService::<span class="name">readDescriptor</span>(const <span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> &<i>descriptor</i>)</h3>
<p>Reads the value of <i>descriptor</i>. If the operation is successful, the <a href="qlowenergyservice.html#descriptorRead">descriptorRead</a>() signal is emitted; otherwise the <a href="qlowenergyservice.html#ServiceError-enum">DescriptorReadError</a> is set.</p>
<p>All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple requests at the same time. The queue does not eliminate duplicated read requests for the same descriptor.</p>
<p>A descriptor can only be read if the service is in the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state and the descriptor belongs to the service. If one of these conditions is not true the <a href="qlowenergyservice.html#ServiceError-enum">QLowEnergyService::OperationError</a> is set.</p>
<p>This function was introduced in Qt 5.5.</p>
<p><b>See also </b><a href="qlowenergyservice.html#descriptorRead">descriptorRead</a>() and <a href="qlowenergyservice.html#writeDescriptor">writeDescriptor</a>().</p>
<!-- @@@readDescriptor -->
<!-- $$$serviceName[overload1]$$$serviceName -->
<h3 class="fn" id="serviceName"><a name="serviceName"></a><span class="type"><a href="../qtcore/qstring.html">QString</a></span> QLowEnergyService::<span class="name">serviceName</span>() const</h3>
<p>Returns the name of the service; otherwise an empty string.</p>
<p>The returned name can only be retrieved if <a href="qlowenergyservice.html#serviceUuid">serviceUuid</a>() is a <a href="https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx">well-known UUID</a>.</p>
<!-- @@@serviceName -->
<!-- $$$serviceUuid[overload1]$$$serviceUuid -->
<h3 class="fn" id="serviceUuid"><a name="serviceUuid"></a><span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span> QLowEnergyService::<span class="name">serviceUuid</span>() const</h3>
<p>Returns the UUID of the service; otherwise a null UUID.</p>
<!-- @@@serviceUuid -->
<!-- $$$state[overload1]$$$state -->
<h3 class="fn" id="state"><a name="state"></a><span class="type"><a href="qlowenergyservice.html#ServiceState-enum">QLowEnergyService::ServiceState</a></span> QLowEnergyService::<span class="name">state</span>() const</h3>
<p>Returns the current state of the service.</p>
<p>If the device's service was instantiated for the first time, the object's state is <a href="qlowenergyservice.html#ServiceState-enum">DiscoveryRequired</a>. The state of all service objects which point to the same service on the peripheral device are always equal. This is caused by the shared nature of the internal object data. Therefore any service object instance created after the first one has a state equal to already existing instances.</p>
<p>A service becomes invalid if the <a href="qlowenergycontroller.html">QLowEnergyController</a> disconnects from the remote device. An invalid service retains its internal state at the time of the disconnect event. This implies that once the service details are discovered they can even be retrieved from an invalid service. This permits scenarios where the device connection is established, the service details are retrieved and the device immediately disconnected to permit the next device to connect to the peripheral device.</p>
<p>However, under normal circumstances the connection should remain to avoid repeated discovery of services and their details. The discovery may take a while and the client can subscribe to ongoing change notifications.</p>
<p><b>See also </b><a href="qlowenergyservice.html#stateChanged">stateChanged</a>().</p>
<!-- @@@state -->
<!-- $$$stateChanged[overload1]$$$stateChangedQLowEnergyService::ServiceState -->
<h3 class="fn" id="stateChanged"><a name="stateChanged"></a><code>[signal] </code><span class="type">void</span> QLowEnergyService::<span class="name">stateChanged</span>(<span class="type"><a href="qlowenergyservice.html#ServiceState-enum">QLowEnergyService::ServiceState</a></span> <i>newState</i>)</h3>
<p>This signal is emitted when the service's state changes. The <i>newState</i> can also be retrieved via <a href="qlowenergyservice.html#state">state</a>().</p>
<p><b>See also </b><a href="qlowenergyservice.html#state">state</a>().</p>
<!-- @@@stateChanged -->
<!-- $$$type[overload1]$$$type -->
<h3 class="fn" id="type"><a name="type"></a><span class="type"><a href="qlowenergyservice.html#ServiceType-enum">QLowEnergyService::ServiceTypes</a></span> QLowEnergyService::<span class="name">type</span>() const</h3>
<p>Returns the type of the service.</p>
<p><b>Note: </b>The type attribute cannot be relied upon until the service has reached the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state. This field is initialised with <a href="qlowenergyservice.html#ServiceType-enum">PrimaryService</a>.</p><p><b>Note: </b>On Android, it is not possible to determine whether a service is a primary or secondary service. Therefore all services have the <a href="qlowenergyservice.html#ServiceType-enum">PrimaryService</a> flag set.</p><!-- @@@type -->
<!-- $$$writeCharacteristic[overload1]$$$writeCharacteristicconstQLowEnergyCharacteristic&constQByteArray&WriteMode -->
<h3 class="fn" id="writeCharacteristic"><a name="writeCharacteristic"></a><span class="type">void</span> QLowEnergyService::<span class="name">writeCharacteristic</span>(const <span class="type"><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a></span> &<i>characteristic</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>newValue</i>, <span class="type"><a href="qlowenergyservice.html#WriteMode-enum">WriteMode</a></span> <i>mode</i> = WriteWithResponse)</h3>
<p>Writes <i>newValue</i> as value for the <i>characteristic</i>. The exact semantics depend on the role that the associated controller object is in.</p>
<p><b>Central role</b></p>
<p>The call results in a write request or command to a remote peripheral. If the operation is successful, the <a href="qlowenergyservice.html#characteristicWritten">characteristicWritten</a>() signal is emitted; otherwise the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a> is set.</p>
<p>The <i>mode</i> parameter determines whether the remote device should send a write confirmation. The to-be-written <i>characteristic</i> must support the relevant write mode. The characteristic's supported write modes are indicated by its <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::Write</a> and <a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::WriteNoResponse</a> properties.</p>
<p>All descriptor and characteristic write requests towards the same remote device are serialised. A queue is employed when issuing multiple write requests at the same time. The queue does not eliminate duplicated write requests for the same characteristic. For example, if the same descriptor is set to the value A and immediately afterwards to B, the two write request are executed in the given order.</p>
<p><b>Note: </b>Currently, it is not possible to use signed or reliable writes as defined by the Bluetooth specification.</p><p>A characteristic can only be written if this service is in the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state and belongs to the service. If one of these conditions is not true the <a href="qlowenergyservice.html#ServiceError-enum">QLowEnergyService::OperationError</a> is set.</p>
<p><b>Note: </b>Calling this function despite <a href="qlowenergycharacteristic.html#properties">QLowEnergyCharacteristic::properties</a>() reporting a non-writable property always attempts to write to the hardware. Similarly, a <a href="qlowenergyservice.html#WriteMode-enum">WriteWithoutResponse</a> is sent to the hardware too although the characteristic may only support <a href="qlowenergyservice.html#WriteMode-enum">WriteWithResponse</a>. If the hardware returns with an error the <a href="qlowenergyservice.html#ServiceError-enum">CharacteristicWriteError</a> is set.</p><p><b>Peripheral role</b></p>
<p>The call results in the value of the characteristic getting updated in the local database.</p>
<p>If a client is currently connected and it has enabled notifications or indications for the characteristic, the respective information will be sent. If a device has enabled notifications or indications for the characteristic and that device is currently not connected, but a bond exists between it and the local device, then the notification or indication will be sent on the next reconnection.</p>
<p>If there is a constraint on the length of the characteristic value and <i>newValue</i> does not adhere to that constraint, the behavior is unspecified.</p>
<p><b>Note: </b>The <i>mode</i> argument is ignored in peripheral mode.</p><p><b>See also </b><a href="qlowenergyservice.html#characteristicWritten">QLowEnergyService::characteristicWritten</a>() and <a href="qlowenergyservice.html#readCharacteristic">QLowEnergyService::readCharacteristic</a>().</p>
<!-- @@@writeCharacteristic -->
<!-- $$$writeDescriptor[overload1]$$$writeDescriptorconstQLowEnergyDescriptor&constQByteArray& -->
<h3 class="fn" id="writeDescriptor"><a name="writeDescriptor"></a><span class="type">void</span> QLowEnergyService::<span class="name">writeDescriptor</span>(const <span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> &<i>descriptor</i>, const <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> &<i>newValue</i>)</h3>
<p>Writes <i>newValue</i> as value for <i>descriptor</i>. The exact semantics depend on the role that the associated controller object is in.</p>
<p><b>Central role</b></p>
<p>A call to this function results in a write request to the remote device. If the operation is successful, the <a href="qlowenergyservice.html#descriptorWritten">descriptorWritten</a>() signal is emitted; otherwise the <a href="qlowenergyservice.html#ServiceError-enum">DescriptorWriteError</a> is emitted.</p>
<p>All descriptor and characteristic requests towards the same remote device are serialised. A queue is employed when issuing multiple write requests at the same time. The queue does not eliminate duplicated write requests for the same descriptor. For example, if the same descriptor is set to the value A and immediately afterwards to B, the two write request are executed in the given order.</p>
<p>A descriptor can only be written if this service is in the <a href="qlowenergyservice.html#ServiceState-enum">ServiceDiscovered</a> state, belongs to the service. If one of these conditions is not true the <a href="qlowenergyservice.html#ServiceError-enum">QLowEnergyService::OperationError</a> is set.</p>
<p><b>Peripheral Role</b></p>
<p>The value is written to the local service database. If the contents of <i>newValue</i> are not valid for <i>descriptor</i>, the behavior is unspecified.</p>
<p><b>See also </b><a href="qlowenergyservice.html#descriptorWritten">descriptorWritten</a>() and <a href="qlowenergyservice.html#readDescriptor">readDescriptor</a>().</p>
<!-- @@@writeDescriptor -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2016 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|