Merge branch 'dev' into btle

Conflicts:
	src/bluetooth/qbluetoothuuid.cpp
	tests/bttestui/btlocaldevice.cpp

Change-Id: Id16ab93ec61361950669da7eb232769c5dc4644f

13 files changed, 169 insertions, 70 deletions

diff --git a/src/nfc/doc/snippets/doc_src_qtnfc.cpp b/src/nfc/doc/snippets/doc_src_qtnfc.cpp
index b7b0dfc4..62aa65e2 100644
--- a/src/nfc/doc/snippets/doc_src_qtnfc.cpp
+++ b/src/nfc/doc/snippets/doc_src_qtnfc.cpp
@@ -38,11 +38,35 @@
 **
 ****************************************************************************/
 
+#include <QtCore/QObject>
 //! [include]
 #include <QtNfc/QNearFieldManager>
 //! [include]
+#include <QtNfc/QNdefMessage>
 
 //! [namespace]
 QT_USE_NAMESPACE
 //! [namespace]
 
+class MyClass : public QObject
+{
+    Q_OBJECT
+public:
+    MyClass() : QObject()
+    {
+//formatting adjusted to improve usage in docs
+//! [handleNdefMessage]
+QNearFieldManager *manager = new QNearFieldManager(this);
+manager->registerNdefMessageHandler(this,
+            SLOT(handleNdefMessage(QNdefMessage,QNearFieldTarget*)));
+//! [handleNdefMessage]
+    }
+
+public Q_SLOTS:
+    void handleNdefMessage(QNdefMessage,QNearFieldTarget*)
+    {
+    }
+};
+
+#include "doc_src_qtnfc.moc"
+
diff --git a/src/nfc/doc/snippets/doc_src_qtnfc.pro b/src/nfc/doc/snippets/doc_src_qtnfc.pro
deleted file mode 100644
index 5730e227..00000000
--- a/src/nfc/doc/snippets/doc_src_qtnfc.pro
+++ /dev/null
@@ -1,51 +0,0 @@
-#****************************************************************************
-#*
-#* Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
-#* Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
-#* Contact: http://www.qt-project.org/legal
-#*
-#* This file is part of the documentation of the Qt Toolkit.
-#*
-#* $QT_BEGIN_LICENSE:BSD$
-#* You may use this file under the terms of the BSD license as follows:
-#*
-#* "Redistribution and use in source and binary forms, with or without
-#* modification, are permitted provided that the following conditions are
-#* met:
-#*   * Redistributions of source code must retain the above copyright
-#*     notice, this list of conditions and the following disclaimer.
-#*   * Redistributions in binary form must reproduce the above copyright
-#*     notice, this list of conditions and the following disclaimer in
-#*     the documentation and/or other materials provided with the
-#*     distribution.
-#*   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
-#*     of its contributors may be used to endorse or promote products derived
-#*     from this software without specific prior written permission.
-#*
-#*
-#* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-#* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-#* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-#* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-#* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-#* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-#* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-#* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-#* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-#* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-#* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-#*
-#* $QT_END_LICENSE$
-#*
-#***************************************************************************/
-
-#! [project modification]
-QT += nfc
-#! [project modification]
-
-SOURCES += main.cpp \
-           doc_src_qtnfc.cpp \
-           nfc.cpp \
-           foorecord.cpp
-
-HEADERS += foorecord.h
diff --git a/src/nfc/doc/snippets/doc_src_qtnfc.qml b/src/nfc/doc/snippets/doc_src_qtnfc.qml
index 6c4d892d..427c24c6 100644
--- a/src/nfc/doc/snippets/doc_src_qtnfc.qml
+++ b/src/nfc/doc/snippets/doc_src_qtnfc.qml
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -42,4 +43,13 @@
 import QtNfc 5.2
 //! [import]
 
-Item { }
+Item {
+//! [QML register for messages]
+    NearField {
+        filter: [ NdefFilter { type: "U"; typeNameFormat: NdefRecord.NfcRtd; minimum: 1; maximum: 1 } ]
+        orderMatch: false
+
+        onMessageRecordsChanged: displayMessage()
+    }
+//! [QML register for messages]
+}
diff --git a/src/nfc/doc/snippets/snippets.pro b/src/nfc/doc/snippets/snippets.pro
new file mode 100644
index 00000000..437782e4
--- /dev/null
+++ b/src/nfc/doc/snippets/snippets.pro
@@ -0,0 +1,13 @@
+TEMPLATE = app
+TARGET = nfc_cppsnippet
+QT = core
+#! [project modification]
+QT += nfc
+#! [project modification]
+
+SOURCES += main.cpp \
+           doc_src_qtnfc.cpp \
+           nfc.cpp \
+           foorecord.cpp
+
+HEADERS += foorecord.h
diff --git a/src/nfc/doc/src/nfc-cpp.qdoc b/src/nfc/doc/src/nfc-cpp.qdoc
index 4df93e69..cbb07e0c 100644
--- a/src/nfc/doc/src/nfc-cpp.qdoc
+++ b/src/nfc/doc/src/nfc-cpp.qdoc
@@ -38,6 +38,6 @@ The \l{Qt NFC} C++ API enables an application to access NFC Forum Tags.
 To use the C++ library in your application, add the following configuration
 option to your \c .pro file:
 
-\snippet doc_src_qtnfc.pro project modification
+\snippet snippets.pro project modification
 */
 
diff --git a/src/nfc/doc/src/nfc-index.qdoc b/src/nfc/doc/src/nfc-index.qdoc
index 2ec40891..2944a6ab 100644
--- a/src/nfc/doc/src/nfc-index.qdoc
+++ b/src/nfc/doc/src/nfc-index.qdoc
@@ -38,12 +38,14 @@ The NFC API provides APIs for interacting with NFC Forum Tags and NFC Forum Devi
 target detection and loss, registering NDEF message handlers, reading and writing NDEF messages
 on NFC Forum Tags and sending tag specific commands.
 
+Currently the API is supported on BlackBerry 10.
+
 \section1 Getting started
 
 To use the C++ library in your application, add the following configuration
 option to your \c .pro file:
 
-\snippet doc_src_qtnfc.pro project modification
+\snippet snippets.pro project modification
 
 To use the classes of the module in your application you need the following
 import statement in your \c .qml file:
diff --git a/src/nfc/doc/src/nfc-overview.qdoc b/src/nfc/doc/src/nfc-overview.qdoc
index b7d029bb..b068dfb5 100644
--- a/src/nfc/doc/src/nfc-overview.qdoc
+++ b/src/nfc/doc/src/nfc-overview.qdoc
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -36,14 +37,114 @@
 With the Qt NFC API typical use cases are:
 
 \list
-    \li Detect NFC tags entering and leaving the communication range.
-    \li Read and write NDEF message on NFC Forum Tags.
-    \li Register an NDEF message handler for a particular content type.
+    \li Detecting NFC tags.
+    \li Reading and writing NDEF messages.
+    \li Registering NDEF message handlers.
+    \li Sharing files and messages.
 \endlist
 
-The following sections describe how to use Qt NFC C++ classes for the above use cases.
+The following sections describe how to use Qt NFC C++ classes and QML types for the above use cases.
 
-\section1 Detect NFC tags entering and leaving communication range.
-\section1 Read and write an NDEF message on NFC Forum Tags.
-\section1 Register an NDEF message handler for a particular content type.
+\section1 C++ Overview
+
+The C++ API provides access to the full feature set of the Qt NFC API. This section introduces the
+major features available to developers.
+
+\section2 Detecting NFC Tags
+
+The \l QNearFieldManager class is responsible for the detection of new NFC tags coming
+into range of the device. The \l QNearFieldManager::targetDetected() and
+\l QNearFieldManager::targetLost() signals are emitted when
+a tag comes into or leaves the range. The passed \l QNearFieldTarget parameter acts
+as primary interaction point for each detected tag. The detection does not actually start though until
+\l QNearFieldManager::startTargetDetection() has been called.
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager init
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager start detection
+
+Finally the detection can be stopped:
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager stop detection
+
+Although each \l QNearFieldTarget instance is owned by its related \l QNearFieldManager
+instance it can be beneficial to manually delete each instance. Otherwise they would continue to
+exist until the \l QNearFieldManager instance is deleted. The best way to do that would be in response
+to the \l QNearFieldManager::targetLost() signal:
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldTarget lost
+
+\note The target object should only be deleted via deleteLater() if it is deleted inside the slot.
+
+\section2 Reading and Writing NDEF Messages
+
+The \l QNearFieldTarget instance returned by \l QNearFieldManager::targetDetected() signal
+is used to interact with the tag. Reading and writing a message is an asynchronous operation.
+The \l QNearFieldTarget::RequestId class associates individual operations and their results.
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldTarget detected
+
+Once the \l QNearFieldTarget::readNdefMessages() request was successfully processed, the
+\l QNearFieldTarget::ndefMessageRead() signal is emitted. Each returned \l QNdefMessage
+may consist of zero or more \l QNdefRecord entries, which can be identified by their type.
+For more information about processing of records, see the \l QNdefRecord class documentation.
+As the above code demonstrates, writing of NDEF messages is triggered via
+\l QNearFieldTarget::writeNdefMessages(). The successful completion of the write operation
+is indicated by the emission of the \l QNearFieldTarget::ndefMessagesWritten() signal. Any
+type of error during read or write is indicated via \l QNearFieldTarget::error().
+
+\section2 Registering NDEF Message Handlers
+
+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.
+
+\note This feature is not available on all platforms and, in addition to the code snippets below,
+may require further platform specific setup.
+
+\snippet annotatedurl/main.cpp QNearFieldManager register handler
+
+For comparison an application that uses an empty NDEF filter (match all behavior) in combination with
+\l QNearFieldManager::registerNdefMessageHandler() would behave similarly to another application that uses
+\l QNearFieldTarget::readNdefMessages() while being in the forground. For more information about
+registration details of NDEF message handlers, see the
+\l {QNearFieldManager#automatically-launching-ndef-message-handlers}{QNearFieldManager} class description.
+
+The content of \c handleMessage() may look like the snippet below. Any incoming NDEF message of type
+\c text or \c uri will be processed:
+
+\snippet annotatedurl/annotatedurl.cpp handleMessage 1
+\snippet annotatedurl/annotatedurl.cpp handleMessage 2
+\snippet annotatedurl/annotatedurl.cpp handleMessage 3
+\snippet annotatedurl/annotatedurl.cpp handleMessage 4
+
+\section2 Sharing Files and Messages
+
+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.
+
+\note 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.
+
+\l QNearFieldShareManager and \l QNearFieldShareTarget are responsible for accessing the NFC share feature.
+
+\section1 QML Overview
+
+The QML API only supports a very small subset of the Qt NFC feature set. This section outlines the available QML features.
+
+\section2 Reading NDEF Messages
+
+The user can specify NDEF filters and use those filters to register for the automatic reception of NDEF
+messages which match those filters. The \l NearField::messageRecords property contains the list of NDEF records
+of the last NDEF message read matching the given filters.
+
+\snippet doc_src_qtnfc.qml QML register for messages
+
+If no filter is set, the message handler will match all incoming NDEF messages.
 */
diff --git a/src/nfc/qnearfieldmanager.cpp b/src/nfc/qnearfieldmanager.cpp
index f2fafdce..88656a6e 100644
--- a/src/nfc/qnearfieldmanager.cpp
+++ b/src/nfc/qnearfieldmanager.cpp
@@ -103,11 +103,7 @@ QT_BEGIN_NAMESPACE
     If the application has been registered as an NDEF message handler, the application only needs
     to call the registerNdefMessageHandler() function:
 
-    \code
-        QNearFieldManager *manager = new QNearFieldManager;
-        manager->registerNdefMessageHandler(this,
-                                            SLOT(handleNdefMessage(QNdefMessage,QNearFieldTarget)));
-    \endcode
+    \snippet doc_src_qtnfc.cpp handleNdefMessage
 
     On BlackBerry the registration for NDEF message handlers is done over the
     \l{https://developer.blackberry.com/native/documentation/core/invocation_framework.html}{Invocation Framework}.
diff --git a/src/nfc/qnearfieldmanager_qnx.cpp b/src/nfc/qnearfieldmanager_qnx.cpp
index b09a6ed4..14dfc755 100644
--- a/src/nfc/qnearfieldmanager_qnx.cpp
+++ b/src/nfc/qnearfieldmanager_qnx.cpp
@@ -139,13 +139,13 @@ bool QNearFieldManagerPrivateImpl::unregisterNdefMessageHandler(int handlerId)
 void QNearFieldManagerPrivateImpl::requestAccess(QNearFieldManager::TargetAccessModes accessModes)
 {
     Q_UNUSED(accessModes);
-    //Do nothing, because we dont have access modes for the target
+    //Do nothing, because we don't have access modes for the target
 }
 
 void QNearFieldManagerPrivateImpl::releaseAccess(QNearFieldManager::TargetAccessModes accessModes)
 {
     Q_UNUSED(accessModes);
-    //Do nothing, because we dont have access modes for the target
+    //Do nothing, because we don't have access modes for the target
 }
 
 void QNearFieldManagerPrivateImpl::handleMessage(const QNdefMessage &message, QNearFieldTarget *target)
diff --git a/src/nfc/qnearfieldsharemanager.cpp b/src/nfc/qnearfieldsharemanager.cpp
index b3e736b6..43b1634b 100644
--- a/src/nfc/qnearfieldsharemanager.cpp
+++ b/src/nfc/qnearfieldsharemanager.cpp
@@ -58,6 +58,7 @@ QT_BEGIN_NAMESPACE
 
     \ingroup connectivity-nfc
     \inmodule QtNfc
+    \since 5.3
 
     Applications can share NDEF data or file content using NFC technology by tapping two NFC-enabled devices
     together. The QNearFieldShareManager provides a high level entry point to access this functionality.
diff --git a/src/nfc/qnearfieldsharetarget.cpp b/src/nfc/qnearfieldsharetarget.cpp
index 9ac66c5c..606090b5 100644
--- a/src/nfc/qnearfieldsharetarget.cpp
+++ b/src/nfc/qnearfieldsharetarget.cpp
@@ -58,9 +58,12 @@ QT_BEGIN_NAMESPACE
 
     \ingroup connectivity-nfc
     \inmodule QtNfc
+    \since 5.3
 
     The QNearFieldShareTarget class can be used for sharing NDEF message or files to a remote
     NFC enabled device supporting the same protocol.
+
+    \sa QNearFieldShareManager
 */
 
 /*!
diff --git a/src/nfc/qnearfieldtagtype3.cpp b/src/nfc/qnearfieldtagtype3.cpp
index b8cc89fe..8668dda4 100644
--- a/src/nfc/qnearfieldtagtype3.cpp
+++ b/src/nfc/qnearfieldtagtype3.cpp
@@ -109,7 +109,7 @@ QNearFieldTarget::RequestId QNearFieldTagType3::serviceData(quint16 serviceCode)
 }
 
 /*!
-    Writes \a data to the the service specified by \a serviceCode. Returns a request id which can
+    Writes \a data to the service specified by \a serviceCode. Returns a request id which can
     be used to track the completion status of the request.
 
     Once the request completes the response can be retrieved from the requestResponse() function.
diff --git a/src/nfc/qnearfieldtarget_qnx_p.h b/src/nfc/qnearfieldtarget_qnx_p.h
index 789d8de5..faff94e2 100644
--- a/src/nfc/qnearfieldtarget_qnx_p.h
+++ b/src/nfc/qnearfieldtarget_qnx_p.h
@@ -147,7 +147,7 @@ public:
             if (!isSupported) {
                 nfc_tag_supports_tag_type (m_target,TAG_TYPE_ISO_15693_3, &isSupported);
                 tagType = TAG_TYPE_ISO_15693_3;
-                //We dont support this tag
+                //We don't support this tag
                 if (!isSupported) {
                     Q_EMIT QNearFieldTarget::error(QNearFieldTarget::UnsupportedError, QNearFieldTarget::RequestId());
                     return QNearFieldTarget::RequestId();