Improve QBluetoothTransferManager documentation

Change-Id: I918bd3b4134504d5bfc3e160adeb97187186df3d
Reviewed-by: Timur Pocheptsov <Timur.Pocheptsov@digia.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Reviewed-by: Mitch Curtis <mitch.curtis@digia.com>

3 files changed, 29 insertions, 8 deletions

diff --git a/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp b/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
index 70e1f629..d8e5b23f 100644
--- a/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
+++ b/src/bluetooth/doc/snippets/doc_src_qtbluetooth.cpp
@@ -75,6 +75,7 @@ public slots:
     void deviceDiscovered(const QBluetoothDeviceInfo &device);
     void serviceDiscovered(const QBluetoothServiceInfo &service);
     void transferFinished(QBluetoothTransferReply* reply);
+    void error(QBluetoothTransferReply::TransferError errorType);
     void characteristicChanged(const QLowEnergyCharacteristic& ,const QByteArray&);
 };
 
@@ -162,10 +163,16 @@ QFile *file = new QFile("testfile.txt");
 
 // Ask the transfer manager to send it
 QBluetoothTransferReply *reply = transferManager->put(request, file);
-
-// Connect to the reply's signals to be informed about the status and do cleanups when done
-QObject::connect(reply, SIGNAL(finished(QBluetoothTransferReply*)),
-                 this, SLOT(transferFinished(QBluetoothTransferReply*)));
+if (reply->error() == QBluetoothTransferReply::NoError) {
+
+    // Connect to the reply's signals to be informed about the status and do cleanups when done
+    QObject::connect(reply, SIGNAL(finished(QBluetoothTransferReply*)),
+                     this, SLOT(transferFinished(QBluetoothTransferReply*)));
+    QObject::connect(reply, SIGNAL(error(QBluetoothTransferReply::TransferError)),
+                     this, SLOT(error(QBluetoothTransferReply::TransferError)));
+} else {
+    qWarning() << "Cannot push testfile.txt:" << reply->errorString();
+}
 //! [sendfile]
 }
 
@@ -173,6 +180,10 @@ void MyClass::transferFinished(QBluetoothTransferReply* /*reply*/)
 {
 }
 
+void MyClass::error(QBluetoothTransferReply::TransferError /*errorType*/)
+{
+}
+
 void MyClass::characteristicChanged(const QLowEnergyCharacteristic &, const QByteArray &)
 {
 }
diff --git a/src/bluetooth/doc/src/bluetooth-overview.qdoc b/src/bluetooth/doc/src/bluetooth-overview.qdoc
index 81d6270a..1aa0d28d 100644
--- a/src/bluetooth/doc/src/bluetooth-overview.qdoc
+++ b/src/bluetooth/doc/src/bluetooth-overview.qdoc
@@ -75,8 +75,8 @@
 
     Once the desired device was found, there are two main use cases provided by Qt Bluetooth. The
     simpler one is to send files via the Obex Object Push Profile (OPP). As the name describes, this
-    profile can only push files from one device to another, but not pull files or browse the remote
-    file system. Because of this limitation, this profile does not require the two devices to be
+    profile can push files from one device to another. Currently it is not possible to pull files
+    or browse the remote file system. The profile does not require the two devices to be
     paired before exchanging data. To push files to remote devices, create a
     QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in
     the request by calling its \l {QBluetoothTransferManager::put()}{put()} function.
diff --git a/src/bluetooth/qbluetoothtransfermanager.cpp b/src/bluetooth/qbluetoothtransfermanager.cpp
index 0754fb9a..56e59f48 100644
--- a/src/bluetooth/qbluetoothtransfermanager.cpp
+++ b/src/bluetooth/qbluetoothtransfermanager.cpp
@@ -51,7 +51,10 @@ QT_BEGIN_NAMESPACE
 
     \since 5.2
 
-    QBluetoothTransferManager uses OBEX to send put commands to remote devices.
+    QBluetoothTransferManager uses OBEX to send put commands to remote devices. A typical
+    OBEX transfer is initialized as follows:
+
+    \snippet doc_src_qtbluetooth.cpp sendfile
 
     Note that this API is not currently supported on Android.
 */
@@ -60,7 +63,14 @@ QT_BEGIN_NAMESPACE
     \fn QBluetoothTransferReply *QBluetoothTransferManager::put(const QBluetoothTransferRequest &request, QIODevice *data)
 
     Sends the contents of \a data to the remote device identified by \a request, and returns a new
-    QBluetoothTransferReply that can be used to track the request's progress.
+    QBluetoothTransferReply that can be used to track the request's progress. \a data must remain valid
+    until the \l finished() signal is emitted.
+
+    The returned \l QBluetoothTransferReply object must be immediately checked for its
+    \l {QBluetoothTransferReply::error()}{error()} state. This is required in case
+    this function detects an error during the initialization of the
+    \l QBluetoothTransferReply. In such cases \l {QBluetoothTransferReply::isFinished()} returns
+    \c true as well.
 
     If the platform does not support the Object Push profile, this function will return \c 0.
 */