/usr/share/qt5/doc/qtnfc/qtnfc-overview.html is in qtconnectivity5-doc-html 5.9.5-0ubuntu1.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- nfc-overview.qdoc -->
<title>Qt NFC Overview | Qt NFC 5.9</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.9</td><td ><a href="qtnfc-index.html">Qt NFC</a></td><td >Qt NFC Overview</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 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="#c-overview">C++ Overview</a></li>
<li class="level2"><a href="#detecting-nfc-tags">Detecting NFC Tags</a></li>
<li class="level2"><a href="#reading-and-writing-ndef-messages">Reading and Writing NDEF Messages</a></li>
<li class="level2"><a href="#registering-ndef-message-handlers">Registering NDEF Message Handlers</a></li>
<li class="level2"><a href="#sharing-files-and-messages">Sharing Files and Messages</a></li>
<li class="level1"><a href="#qml-overview">QML Overview</a></li>
<li class="level2"><a href="#reading-ndef-messages">Reading NDEF Messages</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt NFC Overview</h1>
<span class="subtitle"></span>
<!-- $$$qtnfc-overview.html-description -->
<div class="descr"> <a name="details"></a>
<p>With the Qt NFC API typical use cases are:</p>
<ul>
<li>Detecting NFC tags.</li>
<li>Reading and writing NDEF messages.</li>
<li>Registering NDEF message handlers.</li>
<li>Sharing files and messages.</li>
</ul>
<p>The following sections describe how to use Qt NFC C++ classes and QML types for the above use cases.</p>
<p><b>Note: </b>On Android, Qt Nfc only works in foreground applications. Android services are not supported which is due to API limitations on the Android side.</p><a name="c-overview"></a>
<h2 id="c-overview">C++ Overview</h2>
<p>The C++ API provides access to the full feature set of the Qt NFC API. This section introduces the major features available to developers.</p>
<a name="detecting-nfc-tags"></a>
<h3 >Detecting NFC Tags</h3>
<p>The <a href="qnearfieldmanager.html">QNearFieldManager</a> class is responsible for the detection of new NFC tags coming into range of the device. The <a href="qnearfieldmanager.html#targetDetected">QNearFieldManager::targetDetected</a>() and <a href="qnearfieldmanager.html#targetLost">QNearFieldManager::targetLost</a>() signals are emitted when a tag comes into or leaves the range. The passed <a href="qnearfieldtarget.html">QNearFieldTarget</a> parameter acts as primary interaction point for each detected tag. The detection does not actually start though until <a href="qnearfieldmanager.html#startTargetDetection">QNearFieldManager::startTargetDetection</a>() has been called.</p>
<pre class="cpp">
m_manager <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qnearfieldmanager.html">QNearFieldManager</a></span>(<span class="keyword">this</span>);
connect(m_manager<span class="operator">,</span> SIGNAL(targetDetected(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">*</span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(targetDetected(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">*</span>)));
connect(m_manager<span class="operator">,</span> SIGNAL(targetLost(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">*</span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(targetLost(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">*</span>)));
m_manager<span class="operator">-</span><span class="operator">></span>startTargetDetection();
</pre>
<p>Finally the detection can be stopped:</p>
<pre class="cpp">
m_manager<span class="operator">-</span><span class="operator">></span>stopTargetDetection();
</pre>
<p>Although each <a href="qnearfieldtarget.html">QNearFieldTarget</a> instance is owned by its related <a href="qnearfieldmanager.html">QNearFieldManager</a> instance it can be beneficial to manually delete each instance. Otherwise they would continue to exist until the <a href="qnearfieldmanager.html">QNearFieldManager</a> instance is deleted. The best way to do that would be in response to the <a href="qnearfieldmanager.html#targetLost">QNearFieldManager::targetLost</a>() signal:</p>
<pre class="cpp">
<span class="type">void</span> MainWindow<span class="operator">::</span>targetLost(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span> <span class="operator">*</span>target)
{
target<span class="operator">-</span><span class="operator">></span>deleteLater();
}
</pre>
<p><b>Note: </b>The target object should only be deleted via deleteLater() if it is deleted inside the slot.</p><a name="reading-and-writing-ndef-messages"></a>
<h3 >Reading and Writing NDEF Messages</h3>
<p>The <a href="qnearfieldtarget.html">QNearFieldTarget</a> instance returned by <a href="qnearfieldmanager.html#targetDetected">QNearFieldManager::targetDetected</a>() signal is used to interact with the tag. Reading and writing a message is an asynchronous operation. The <a href="qnearfieldtarget-requestid.html">QNearFieldTarget::RequestId</a> class associates individual operations and their results.</p>
<pre class="cpp">
<span class="type">void</span> MainWindow<span class="operator">::</span>targetDetected(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span> <span class="operator">*</span>target)
{
<span class="keyword">switch</span> (m_touchAction) {
<span class="keyword">case</span> NoAction:
<span class="keyword">break</span>;
<span class="keyword">case</span> ReadNdef:
connect(target<span class="operator">,</span> SIGNAL(ndefMessageRead(<span class="type"><a href="qndefmessage.html">QNdefMessage</a></span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(ndefMessageRead(<span class="type"><a href="qndefmessage.html">QNdefMessage</a></span>)));
connect(target<span class="operator">,</span> SIGNAL(error(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>Error<span class="operator">,</span><span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>RequestId))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(targetError(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>Error<span class="operator">,</span><span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>RequestId)));
m_request <span class="operator">=</span> target<span class="operator">-</span><span class="operator">></span>readNdefMessages();
<span class="keyword">if</span> (<span class="operator">!</span>m_request<span class="operator">.</span>isValid()) <span class="comment">// cannot read messages</span>
targetError(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>NdefReadError<span class="operator">,</span> m_request);
<span class="keyword">break</span>;
<span class="keyword">case</span> WriteNdef:
connect(target<span class="operator">,</span> SIGNAL(ndefMessagesWritten())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(ndefMessageWritten()));
connect(target<span class="operator">,</span> SIGNAL(error(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>Error<span class="operator">,</span><span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>RequestId))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(targetError(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>Error<span class="operator">,</span><span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>RequestId)));
m_request <span class="operator">=</span> target<span class="operator">-</span><span class="operator">></span>writeNdefMessages(<span class="type"><a href="../qtcore/qlist.html">QList</a></span><span class="operator"><</span><span class="type"><a href="qndefmessage.html">QNdefMessage</a></span><span class="operator">></span>() <span class="operator"><</span><span class="operator"><</span> ndefMessage());
<span class="keyword">if</span> (<span class="operator">!</span>m_request<span class="operator">.</span>isValid()) <span class="comment">// cannot write messages</span>
targetError(<span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">::</span>NdefWriteError<span class="operator">,</span> m_request);
<span class="keyword">break</span>;
}
}
</pre>
<p>Once the <a href="qnearfieldtarget.html#readNdefMessages">QNearFieldTarget::readNdefMessages</a>() request was successfully processed, the <a href="qnearfieldtarget.html#ndefMessageRead">QNearFieldTarget::ndefMessageRead</a>() signal is emitted. Each returned <a href="qndefmessage.html">QNdefMessage</a> may consist of zero or more <a href="qndefrecord.html">QNdefRecord</a> entries, which can be identified by their type. For more information about processing of records, see the <a href="qndefrecord.html">QNdefRecord</a> class documentation. As the above code demonstrates, writing of NDEF messages is triggered via <a href="qnearfieldtarget.html#writeNdefMessages">QNearFieldTarget::writeNdefMessages</a>(). The successful completion of the write operation is indicated by the emission of the <a href="qnearfieldtarget.html#ndefMessagesWritten">QNearFieldTarget::ndefMessagesWritten</a>() signal. Any type of error during read or write is indicated via <a href="qnearfieldtarget.html#error">QNearFieldTarget::error</a>().</p>
<a name="registering-ndef-message-handlers"></a>
<h3 >Registering NDEF Message Handlers</h3>
<p>The above described method (of reading NDEF messages) directly connects to the platform's NFC infrastructure. However on some platforms (in particular mobile platforms) this may not actually trigger the target slot if the application is currently running in the background. This is not desirable in cases where an application wants to be activated if the platform detects a tag of particular type. For this purpose the Qt NFC API provides the possibility to register an NDEF message handler. The handler is called by the operating system, when the detected NDEF message matches the given filter criteria. Depending on the platform it may even be possible to start the application that registered the handler.</p>
<p><b>Note: </b>This feature is not available on all platforms and, in addition to the code snippets below, may require further platform specific setup.</p><pre class="cpp">
manager <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qnearfieldmanager.html">QNearFieldManager</a></span>(<span class="keyword">this</span>);
<span class="keyword">if</span> (<span class="operator">!</span>manager<span class="operator">-</span><span class="operator">></span>isAvailable()) {
<a href="../qtcore/qtglobal.html#qWarning">qWarning</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"NFC not available"</span>;
<span class="keyword">return</span>;
}
<span class="type"><a href="qndeffilter.html">QNdefFilter</a></span> filter;
filter<span class="operator">.</span>setOrderMatch(<span class="keyword">false</span>);
filter<span class="operator">.</span>appendRecord<span class="operator"><</span><span class="type"><a href="qndefnfctextrecord.html">QNdefNfcTextRecord</a></span><span class="operator">></span>(<span class="number">1</span><span class="operator">,</span> UINT_MAX);
filter<span class="operator">.</span>appendRecord<span class="operator"><</span><span class="type"><a href="qndefnfcurirecord.html">QNdefNfcUriRecord</a></span><span class="operator">></span>();
<span class="comment">// type parameter cannot specify substring so filter for "image/" below</span>
filter<span class="operator">.</span>appendRecord(<span class="type"><a href="qndefrecord.html">QNdefRecord</a></span><span class="operator">::</span>Mime<span class="operator">,</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span>()<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">1</span>);
<span class="type">int</span> result <span class="operator">=</span> manager<span class="operator">-</span><span class="operator">></span>registerNdefMessageHandler(filter<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span>
SLOT(handleMessage(<span class="type"><a href="qndefmessage.html">QNdefMessage</a></span><span class="operator">,</span><span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span><span class="operator">*</span>)));
</pre>
<p>For comparison an application that uses an empty NDEF filter (match all behavior) in combination with <a href="qnearfieldmanager.html#registerNdefMessageHandler">QNearFieldManager::registerNdefMessageHandler</a>() would behave similarly to another application that uses <a href="qnearfieldtarget.html#readNdefMessages">QNearFieldTarget::readNdefMessages</a>() while being in the forground. For more information about registration details of NDEF message handlers, see the <a href="qnearfieldmanager.html#automatically-launching-ndef-message-handlers">QNearFieldManager</a> class description.</p>
<p>The content of <code>handleMessage()</code> may look like the snippet below. Any incoming NDEF message of type <code>text</code> or <code>uri</code> will be processed:</p>
<pre class="cpp">
<span class="type">void</span> AnnotatedUrl<span class="operator">::</span>handleMessage(<span class="keyword">const</span> <span class="type"><a href="qndefmessage.html">QNdefMessage</a></span> <span class="operator">&</span>message<span class="operator">,</span> <span class="type"><a href="qnearfieldtarget.html">QNearFieldTarget</a></span> <span class="operator">*</span>target)
{
foreach (<span class="keyword">const</span> <span class="type"><a href="qndefrecord.html">QNdefRecord</a></span> <span class="operator">&</span>record<span class="operator">,</span> message) {
<span class="keyword">if</span> (record<span class="operator">.</span>isRecordType<span class="operator"><</span><span class="type"><a href="qndefnfctextrecord.html">QNdefNfcTextRecord</a></span><span class="operator">></span>()) {
<span class="type"><a href="qndefnfctextrecord.html">QNdefNfcTextRecord</a></span> textRecord(record);
title <span class="operator">=</span> textRecord<span class="operator">.</span>text();
<span class="type"><a href="../qtcore/qlocale.html">QLocale</a></span> locale(textRecord<span class="operator">.</span>locale());
} <span class="keyword">else</span> <span class="keyword">if</span> (record<span class="operator">.</span>isRecordType<span class="operator"><</span><span class="type"><a href="qndefnfcurirecord.html">QNdefNfcUriRecord</a></span><span class="operator">></span>()) {
<span class="type"><a href="qndefnfcurirecord.html">QNdefNfcUriRecord</a></span> uriRecord(record);
url <span class="operator">=</span> uriRecord<span class="operator">.</span>uri();
}
}
<span class="keyword">emit</span> annotatedUrl(url<span class="operator">,</span> title<span class="operator">,</span> pixmap);
}
</pre>
<a name="sharing-files-and-messages"></a>
<h3 >Sharing Files and Messages</h3>
<p>Since Qt 5.3, Qt NFC provides a generic NFC share feature. If both devices support the same protocol, the feature can be used to share files or NDEF messages. The advantage is that the two involved partners can quickly establish a connection via NFC but transfer the data through, for example, Bluetooth or Wifi. Effectively, this combines the low configuration effort of NFC with high data rate communication bearers which usually require a much more complex setup.</p>
<p><b>Note: </b>The API does not make any guarantees about the actual communication bearer used during the transfer. The bearer is chosen based on the device's capabilities and the properties of the to-be-shared data.</p><p><a href="qnearfieldsharemanager.html">QNearFieldShareManager</a> and <a href="qnearfieldsharetarget.html">QNearFieldShareTarget</a> are responsible for accessing the NFC share feature.</p>
<a name="qml-overview"></a>
<h2 id="qml-overview">QML Overview</h2>
<p>The QML API only supports a very small subset of the Qt NFC feature set. This section outlines the available QML features.</p>
<a name="reading-ndef-messages"></a>
<h3 >Reading NDEF Messages</h3>
<p>The user can specify NDEF filters and use those filters to register for the automatic reception of NDEF messages which match those filters. The <a href="qml-qtnfc-nearfield.html#messageRecords-prop">NearField::messageRecords</a> property contains the list of NDEF records of the last NDEF message read matching the given filters.</p>
<pre class="qml">
<span class="type"><a href="qml-qtnfc-nearfield.html">NearField</a></span> {
<span class="name">filter</span>: [ <span class="type"><a href="qml-qtnfc-ndeffilter.html">NdefFilter</a></span> { <span class="name">type</span>: <span class="string">"U"</span>; <span class="name">typeNameFormat</span>: <span class="name">NdefRecord</span>.<span class="name">NfcRtd</span>; <span class="name">minimum</span>: <span class="number">1</span>; <span class="name">maximum</span>: <span class="number">1</span> } ]
<span class="name">orderMatch</span>: <span class="number">false</span>
<span class="name">onMessageRecordsChanged</span>: <span class="name">displayMessage</span>()
}
</pre>
<p>If no filter is set, the message handler will match all incoming NDEF messages.</p>
</div>
<!-- @@@qtnfc-overview.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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>
|