<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qlowenergycharacteristic.cpp -->
<title>QLowEnergyCharacteristic Class | Qt Bluetooth 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtbluetooth-index.html">Qt Bluetooth</a></td><td ><a href="qtbluetooth-module.html">C++ Classes</a></td><td >QLowEnergyCharacteristic</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtbluetooth-index.html">Qt 5.12.6 Reference Documentation</a></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="#protected-variables">Protected Variables</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QLowEnergyCharacteristic Class</h1>
<!-- $$$QLowEnergyCharacteristic-brief -->
<p>The <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> class stores information about a Bluetooth Low Energy service characteristic. <a href="#details">More...</a></p>
<!-- @@@QLowEnergyCharacteristic -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QLowEnergyCharacteristic></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></table></div><ul>
<li><a href="qlowenergycharacteristic-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="qlowenergycharacteristic.html#PropertyType-enum">PropertyType</a></b> { Unknown, Broadcasting, Read, WriteNoResponse, ..., ExtendedProperty }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> flags </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#PropertyType-enum">PropertyTypes</a></b></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="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic-1">QLowEnergyCharacteristic</a></b>(const QLowEnergyCharacteristic &<i>other</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#dtor.QLowEnergyCharacteristic">~QLowEnergyCharacteristic</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyDescriptor </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#descriptor">descriptor</a></b>(const QBluetoothUuid &<i>uuid</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QList<QLowEnergyDescriptor> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#descriptors">descriptors</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyHandle </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#handle">handle</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#isValid">isValid</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#name">name</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyCharacteristic::PropertyTypes </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#properties">properties</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QBluetoothUuid </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#uuid">uuid</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QByteArray </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#value">value</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#operator-not-eq">operator!=</a></b>(const QLowEnergyCharacteristic &<i>other</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyCharacteristic &</td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#operator-eq">operator=</a></b>(const QLowEnergyCharacteristic &<i>other</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#operator-eq-eq">operator==</a></b>(const QLowEnergyCharacteristic &<i>other</i>) const</td></tr>
</table></div>
<a name="protected-variables"></a>
<h2 id="protected-variables">Protected Variables</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> QSharedPointer<QLowEnergyServicePrivate> </td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#d_ptr-var">d_ptr</a></b></td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QLowEnergyCharacteristicPrivate *</td><td class="memItemRight bottomAlign"><b><a href="qlowenergycharacteristic.html#data-var">data</a></b></td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QLowEnergyCharacteristic-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> class stores information about a Bluetooth Low Energy service characteristic.</p>
<p><a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> provides information about a Bluetooth Low Energy service characteristic's <a href="qlowenergycharacteristic.html#name">name</a>(), <a href="qlowenergycharacteristic.html#uuid">uuid</a>(), <a href="qlowenergycharacteristic.html#value">value</a>(), <a href="qlowenergycharacteristic.html#properties">properties</a>(), <a href="qlowenergycharacteristic.html#handle">handle</a>() and <a href="qlowenergycharacteristic.html#descriptors">descriptors</a>(). To obtain the characteristic's specification and information, it is necessary to connect to the device using the <a href="qlowenergyservice.html">QLowEnergyService</a> and <a href="qlowenergycontroller.html">QLowEnergyController</a> classes.</p>
<p>The characteristic value may be written via the <a href="qlowenergyservice.html">QLowEnergyService</a> instance that manages the service to which this characteristic belongs. The <a href="qlowenergyservice.html#writeCharacteristic">QLowEnergyService::writeCharacteristic</a>() function writes the new value. The <a href="qlowenergyservice.html#characteristicWritten">QLowEnergyService::characteristicWritten</a>() signal is emitted upon success. The <a href="qlowenergycharacteristic.html#value">value</a>() of this object is automatically updated accordingly.</p>
<p>Characteristics may contain none, one or more descriptors. They can be individually retrieved using the <a href="qlowenergycharacteristic.html#descriptor">descriptor</a>() function. The <a href="qlowenergycharacteristic.html#descriptors">descriptors</a>() function returns all descriptors as a list. The general purpose of a descriptor is to add contextual information to the characteristic. For example, the descriptor might provide format or range information specifying how the characteristic's value is to be interpreted.</p>
</div>
<p><b>See also </b><a href="qlowenergyservice.html">QLowEnergyService</a> and <a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a>.</p>
<!-- @@@QLowEnergyCharacteristic -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$PropertyType$$$Unknown$$$Broadcasting$$$Read$$$WriteNoResponse$$$Write$$$Notify$$$Indicate$$$WriteSigned$$$ExtendedProperty -->
<h3 class="flags" id="PropertyType-enum"><a name="PropertyType-enum"></a>enum QLowEnergyCharacteristic::<span class="name">PropertyType</span><br/>flags QLowEnergyCharacteristic::<span class="name">PropertyTypes</span></h3>
<p>This enum describes the properties of a characteristic.</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>QLowEnergyCharacteristic::Unknown</code></td><td class="topAlign tblval"><code>0x00</code></td><td class="topAlign">The type is not known.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::Broadcasting</code></td><td class="topAlign tblval"><code>0x01</code></td><td class="topAlign">Allow for the broadcasting of Generic Attributes (GATT) characteristic values.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::Read</code></td><td class="topAlign tblval"><code>0x02</code></td><td class="topAlign">Allow the characteristic values to be read.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::WriteNoResponse</code></td><td class="topAlign tblval"><code>0x04</code></td><td class="topAlign">Allow characteristic values without responses to be written.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::Write</code></td><td class="topAlign tblval"><code>0x08</code></td><td class="topAlign">Allow for characteristic values to be written.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::Notify</code></td><td class="topAlign tblval"><code>0x10</code></td><td class="topAlign">Permits notification of characteristic values.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::Indicate</code></td><td class="topAlign tblval"><code>0x20</code></td><td class="topAlign">Permits indications of characteristic values.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::WriteSigned</code></td><td class="topAlign tblval"><code>0x40</code></td><td class="topAlign">Permits signed writes of the GATT characteristic values.</td></tr>
<tr><td class="topAlign"><code>QLowEnergyCharacteristic::ExtendedProperty</code></td><td class="topAlign tblval"><code>0x80</code></td><td class="topAlign">Additional characteristic properties are defined in the characteristic's extended properties descriptor.</td></tr>
</table></div>
<p>The PropertyTypes type is a typedef for <a href="">QFlags</a><PropertyType>. It stores an OR combination of PropertyType values.</p>
<p><b>See also </b><a href="qlowenergycharacteristic.html#properties">properties</a>().</p>
<!-- @@@PropertyType -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QLowEnergyCharacteristic[overload1]$$$QLowEnergyCharacteristic -->
<h3 class="fn" id="QLowEnergyCharacteristic"><a name="QLowEnergyCharacteristic"></a>QLowEnergyCharacteristic::<span class="name">QLowEnergyCharacteristic</span>()</h3>
<p>Construct a new <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a>. A default-constructed instance of this class is always invalid.</p>
<p><b>See also </b><a href="qlowenergycharacteristic.html#isValid">isValid</a>().</p>
<!-- @@@QLowEnergyCharacteristic -->
<!-- $$$QLowEnergyCharacteristic$$$QLowEnergyCharacteristicconstQLowEnergyCharacteristic& -->
<h3 class="fn" id="QLowEnergyCharacteristic-1"><a name="QLowEnergyCharacteristic-1"></a>QLowEnergyCharacteristic::<span class="name">QLowEnergyCharacteristic</span>(const <span class="type"><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></span> &<i>other</i>)</h3>
<p>Construct a new <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> that is a copy of <i>other</i>.</p>
<p>The two copies continue to share the same underlying data which does not detach upon write.</p>
<!-- @@@QLowEnergyCharacteristic -->
<!-- $$$~QLowEnergyCharacteristic[overload1]$$$~QLowEnergyCharacteristic -->
<h3 class="fn" id="dtor.QLowEnergyCharacteristic"><a name="dtor.QLowEnergyCharacteristic"></a>QLowEnergyCharacteristic::<span class="name">~QLowEnergyCharacteristic</span>()</h3>
<p>Destroys the <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> object.</p>
<!-- @@@~QLowEnergyCharacteristic -->
<!-- $$$descriptor[overload1]$$$descriptorconstQBluetoothUuid& -->
<h3 class="fn" id="descriptor"><a name="descriptor"></a><span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span> QLowEnergyCharacteristic::<span class="name">descriptor</span>(const <span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span> &<i>uuid</i>) const</h3>
<p>Returns the descriptor for <i>uuid</i> or an invalid <code>QLowEnergyDescriptor</code> instance.</p>
<p><b>See also </b><a href="qlowenergycharacteristic.html#descriptors">descriptors</a>().</p>
<!-- @@@descriptor -->
<!-- $$$descriptors[overload1]$$$descriptors -->
<h3 class="fn" id="descriptors"><a name="descriptors"></a><span class="type">QList</span><<span class="type"><a href="qlowenergydescriptor.html">QLowEnergyDescriptor</a></span>> QLowEnergyCharacteristic::<span class="name">descriptors</span>() const</h3>
<p>Returns the list of descriptors belonging to this characteristic; otherwise an empty list.</p>
<p><b>See also </b><a href="qlowenergycharacteristic.html#descriptor">descriptor</a>().</p>
<!-- @@@descriptors -->
<!-- $$$handle[overload1]$$$handle -->
<h3 class="fn" id="handle"><a name="handle"></a><span class="type"><a href="qbluetooth.html#QLowEnergyHandle-typedef">QLowEnergyHandle</a></span> QLowEnergyCharacteristic::<span class="name">handle</span>() const</h3>
<p>Returns the handle of the characteristic's value attribute; or <code>0</code> if the handle cannot be accessed on the platform or if the characteristic is invalid.</p>
<p><b>Note: </b>On macOS and iOS handles can differ from 0, but these values have no special meaning outside of internal/private API.</p><!-- @@@handle -->
<!-- $$$isValid[overload1]$$$isValid -->
<h3 class="fn" id="isValid"><a name="isValid"></a><span class="type">bool</span> QLowEnergyCharacteristic::<span class="name">isValid</span>() const</h3>
<p>Returns <code>true</code> if the <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> object is valid, otherwise returns <code>false</code>.</p>
<p>An invalid characteristic object is not associated with any service (default-constructed) or the associated service is no longer valid due to a disconnect from the underlying Bluetooth Low Energy device, for example. Once the object is invalid it cannot become valid anymore.</p>
<p><b>Note: </b>If a <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> instance turns invalid due to a disconnect from the underlying device, the information encapsulated by the current instance remains as it was at the time of the disconnect. Therefore it can be retrieved after the disconnect event.</p><!-- @@@isValid -->
<!-- $$$name[overload1]$$$name -->
<h3 class="fn" id="name"><a name="name"></a><span class="type">QString</span> QLowEnergyCharacteristic::<span class="name">name</span>() const</h3>
<p>Returns the human-readable name of the characteristic.</p>
<p>The name is based on the characteristic's <a href="qlowenergycharacteristic.html#uuid">uuid</a>() which must have been standardized. The complete list of characteristic types can be found under <a href="https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx">Bluetooth.org Characteristics</a>.</p>
<p>The returned string is empty if the <a href="qlowenergycharacteristic.html#uuid">uuid</a>() is unknown.</p>
<p><b>See also </b><a href="qbluetoothuuid.html#characteristicToString">QBluetoothUuid::characteristicToString</a>().</p>
<!-- @@@name -->
<!-- $$$properties[overload1]$$$properties -->
<h3 class="fn" id="properties"><a name="properties"></a><span class="type"><a href="qlowenergycharacteristic.html#PropertyType-enum">QLowEnergyCharacteristic::PropertyTypes</a></span> QLowEnergyCharacteristic::<span class="name">properties</span>() const</h3>
<p>Returns the properties of the characteristic.</p>
<p>The properties define the access permissions for the characteristic.</p>
<!-- @@@properties -->
<!-- $$$uuid[overload1]$$$uuid -->
<h3 class="fn" id="uuid"><a name="uuid"></a><span class="type"><a href="qbluetoothuuid.html">QBluetoothUuid</a></span> QLowEnergyCharacteristic::<span class="name">uuid</span>() const</h3>
<p>Returns the UUID of the characteristic if <a href="qlowenergycharacteristic.html#isValid">isValid</a>() returns <code>true</code>; otherwise a null UUID.</p>
<!-- @@@uuid -->
<!-- $$$value[overload1]$$$value -->
<h3 class="fn" id="value"><a name="value"></a><span class="type">QByteArray</span> QLowEnergyCharacteristic::<span class="name">value</span>() const</h3>
<p>Returns the cached value of the characteristic.</p>
<p>If the characteristic's <a href="qlowenergycharacteristic.html#properties">properties</a>() permit writing of new values, the value can be updated using <a href="qlowenergyservice.html#writeCharacteristic">QLowEnergyService::writeCharacteristic</a>().</p>
<p>The cache is updated during the associated service's <a href="qlowenergyservice.html#discoverDetails">detail discovery</a>, a successful <a href="qlowenergyservice.html#readCharacteristic">read</a>/<a href="qlowenergyservice.html#writeCharacteristic">write</a> operation or when an update notification is received.</p>
<p>The returned QByteArray always remains empty if the characteristic does not have the <a href="qlowenergycharacteristic.html#PropertyType-enum">read permission</a>. In such cases only the <a href="qlowenergyservice.html#characteristicChanged">QLowEnergyService::characteristicChanged</a>() or <a href="qlowenergyservice.html#characteristicWritten">QLowEnergyService::characteristicWritten</a>() may provice information about the value of this characteristic.</p>
<!-- @@@value -->
<!-- $$$operator!=[overload1]$$$operator!=constQLowEnergyCharacteristic& -->
<h3 class="fn" id="operator-not-eq"><a name="operator-not-eq"></a><span class="type">bool</span> QLowEnergyCharacteristic::<span class="name">operator!=</span>(const <span class="type"><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></span> &<i>other</i>) const</h3>
<p>Returns <code>true</code> if <i>other</i> is not equal to this <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a>; otherwise <code>false</code>.</p>
<p>Two QLowEnergyCharcteristic instances are considered to be equal if they refer to the same characteristic on the same remote Bluetooth Low Energy device or both instances have been default-constructed.</p>
<!-- @@@operator!= -->
<!-- $$$operator=[overload1]$$$operator=constQLowEnergyCharacteristic& -->
<h3 class="fn" id="operator-eq"><a name="operator-eq"></a><span class="type"><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></span> &QLowEnergyCharacteristic::<span class="name">operator=</span>(const <span class="type"><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></span> &<i>other</i>)</h3>
<p>Makes a copy of <i>other</i> and assigns it to this <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> object. The two copies continue to share the same service and controller details.</p>
<!-- @@@operator= -->
<!-- $$$operator==[overload1]$$$operator==constQLowEnergyCharacteristic& -->
<h3 class="fn" id="operator-eq-eq"><a name="operator-eq-eq"></a><span class="type">bool</span> QLowEnergyCharacteristic::<span class="name">operator==</span>(const <span class="type"><a href="qlowenergycharacteristic.html#QLowEnergyCharacteristic">QLowEnergyCharacteristic</a></span> &<i>other</i>) const</h3>
<p>Returns <code>true</code> if <i>other</i> is equal to this <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a>; otherwise <code>false</code>.</p>
<p>Two <a href="qlowenergycharacteristic.html">QLowEnergyCharacteristic</a> instances are considered to be equal if they refer to the same characteristic on the same remote Bluetooth Low Energy device or both instances have been default-constructed.</p>
<!-- @@@operator== -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 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>
