#include <mw/xqnfcshare.h>
Link against: xqnfcshare.lib
class XQNfcShare : public QObject, public QObject |
The XQNfcShare class provides NFC-based services for obtaining Bluetooth device information, pairing and file sharing.
Public Slots | |
---|---|
void | cancel() |
void | easySetup() |
void | easySetupAndPair() |
void | share() |
void | shareFile(const QString &) |
void | shareFiles(const QStringList &) |
Public Signals | |
---|---|
void | busy(bool) |
void | easySetupCompleted() |
void | easySetupStarted() |
void | error(XQNfcShare::Error) |
void | shareCompleted() |
void | shareStarted() |
Inherited Attributes | |
---|---|
QObject::objectName | |
QObject::staticQtMetaObject |
Inherited Functions | |
---|---|
QObject::QObject(QObjectPrivate &,QObject *) | |
QObject::blockSignals(bool) | |
QObject::childEvent(QChildEvent *) | |
QObject::children()const | |
QObject::connect(const QObject *,const QMetaMethod &,const QObject *,const QMetaMethod &,Qt::ConnectionType) | |
QObject::connect(const QObject *,const char *,const QObject *,const char *,Qt::ConnectionType) | |
QObject::connect(const QObject *,const char *,const char *,Qt::ConnectionType)const | |
QObject::connectNotify(const char *) | |
QObject::customEvent(QEvent *) | |
QObject::deleteLater | |
QObject::destroyed | |
QObject::disconnect(const QObject *,const QMetaMethod &,const QObject *,const QMetaMethod &) | |
QObject::disconnect(const QObject *,const char *) | |
QObject::disconnect(const QObject *,const char *,const QObject *,const char *) | |
QObject::disconnect(const char *,const QObject *,const char *) | |
QObject::disconnectNotify(const char *) | |
QObject::dumpObjectInfo() | |
QObject::dumpObjectTree() | |
QObject::dynamicPropertyNames()const | |
QObject::event(QEvent *) | |
QObject::eventFilter(QObject *,QEvent *) | |
QObject::findChild(const QString &)const | |
QObject::findChildren(const QRegExp &)const | |
QObject::findChildren(const QString &)const | |
QObject::inherits(const char *)const | |
QObject::installEventFilter(QObject *) | |
QObject::isWidgetType()const | |
QObject::killTimer(int) | |
QObject::moveToThread(QThread *) | |
QObject::objectName()const | |
QObject::parent()const | |
QObject::property(const char *)const | |
QObject::receivers(const char *)const | |
QObject::registerUserData() | |
QObject::removeEventFilter(QObject *) | |
QObject::sender()const | |
QObject::senderSignalIndex()const | |
QObject::setObjectName(const QString &) | |
QObject::setParent(QObject *) | |
QObject::setProperty(const char *,const QVariant &) | |
QObject::setUserData(uint,QObjectUserData *) | |
QObject::signalsBlocked()const | |
QObject::startTimer(int) | |
QObject::thread()const | |
QObject::timerEvent(QTimerEvent *) | |
QObject::userData(uint)const | |
QObject::~QObject() |
An instance of this class can be used for two distinct services: easy setup and file sharing. Both of these services depend on the presence of NFC (Near Field Communication) hardware and compatible software on both this device and the device that is the target of these services.
Easy setup is used to easily obtain a target Bluetooth device's name, address and class. The user's device (i.e. the device using an instance of XQNfcShare) can optionally be paired with the target device (i.e. the device whose information XQNfcShare returned). File sharing is used to send one or more files from one NFC-enabled device to another. NFC is used to establish a connection between the two devices and to select a bearer (e.g. Bluetooth) for the actual file transmission.
As all of the services provided by this class are based on NFC, they all expect near field contact to take place to perform the requested service. For example after calling share() the source device (i.e. the device running the application using the XQNfcShare class) should be brought to close proximity with the target device (another device supporting NFC) for the file sharing to actually begin.
Only one operation can be in progress at any one time. The isBusy() function is used to test whether the XQNfcShare instance is currently processing a service request. It is not an error to call the service functions if isBusy() returns true, but they will have no effect.
While the the easy setup and file sharing services are provided as one API, they do not depend on each other. Both services can be used in isolation. There is, for example, no need to perform easy setup before attempting to share files. Using the easy setup or file sharing services provided by XQNfcShare does not require any additional software on the the target device (i.e. the device whose Bluetooth information is queried, or to which files are to be transferred) as the counterpart of the XQNfcShare API is built into Symbian^3 Anna and later releases.
See also: shareFile(), see shareFiles(), easySetup(), easySetupAndPair(), isBusy(), error(), XQNfcShare::Error
void | busy | ( | bool | busy | ) | [signal] |
Emitted whenever an operation is begins or ends.
This signal is emitted when any of the share(), easySetup() or easySetupAndPair() operations begins or ends. The busy(true) signal is emitted as soon as the function is called. Similarly busy(false) is emitted as soon as any operation completes (regardless of whether it completed successfully or not) to indicate that the XQNfcShare instance is idle and ready to receive another request.
The busy(true) signal does not indicate that any activity is taking place. For any of the operations to proceed near field contact needs to happen. The busy(true) signal merely indicates that the service request has been received and the XQNfcShare instance is reserved and not ready to start another operation.
For each operation there is a more accurate "started" signal. For instance easySetup() emits a more timely easySetupStarted() signal when the two devices have actually been brought into close proximity with one another and the exchange of information is started.
See also: share(), easySetup(), easySetupAndPair(), isBusy()
Parameters | |
---|---|
busy | true is the XQNfcShare instance started an operation, false if an operation has just been completed. |
void | cancel | ( | ) | [slot] |
Cancels an ongoing easy setup or file sharing operation.
Calling this function cancels any operation that this instance of XQNfcShare is currently processing. This function has no effect if none of the easy setup or file sharing functions have been called yet, or the operations have already been completed (i.e. isBusy() returns false).
See also: share(), easySetup(), easySetupAndPair(), isBusy()
void | easySetup | ( | ) | [slot] |
Obtains bearer information for establishing a connection between this device and the target device.
This is an asynchronous operation which completes when either this device is touched together with another NFC-enabled device and bearer information is successfully exchanged, or when this operation is cancelled by calling cancel().
On successful completion, the easySetupCompleted() signal is emitted. It is safe to access the newly acquired bearer type specific target device details (i.e. XQNfcShare::bluetoothDeviceName, XQNfcShare::bluetoothDeviceAddress and XQNfcShare::bluetoothDeviceClass for a Bluetooth bearer) after receiving this signal.
It is possible for the easy setup operation to end in an error, in which case the error(Error) signal is emitted. Note that easySetupCompleted() is only emitted if the operation completes without errors. Also note that calling cancel() causes the error(Error) signal to be emitted with an error parameter value of XQNfcShare::Error.
The following code snippet shows a simple QObject derived class declaration that is used to handle the easy setup operation in the usage example below:
#ifndef MYEASYSETUPCLASS_H #define MYEASYSETUPCLASS_H #include <QtCore/QObject> #include <xqnfcshare.h> class MyEasySetupClass : public QObject { Q_OBJECT public: explicit MyEasySetupClass(QObject *parent = 0); virtual ~MyEasySetupClass(); public slots: void startEasySetup(); void cancelEasySetup(); private slots: void handleNfcEasySetupStarted(); void handleNfcEasySetupCompleted(); void handleNfcBusy(bool busy); void handleNfcError(XQNfcShare::Error error); private: XQNfcShare *m_nfcShare; }; #endif // MYEASYSETUPCLASS_H
The following code snippet shows how to create a new XQNfcShare instance and how establish the signal-slot connections to receive easy setup state change notifications. The easy setup process is started when the slot void MyEasySetupClass::startEasySetup() gets called:
#include "myeasysetupclass.h" void MyEasySetupClass::MyEasySetupClass(QObject *parent) : QObject(parent) { // Construct a new instance. m_nfcShare = new XQNfcShare(this); // Connect signals for receiving state change notifications. connect(m_nfcShare, SIGNAL(easySetupStarted()), SLOT(handleNfcEasySetupStarted())); connect(m_nfcShare, SIGNAL(easySetupCompleted()), SLOT(handleNfcEasySetupCompleted())); connect(m_nfcShare, SIGNAL(busy(bool)), SLOT(handleNfcBusy(bool))); connect(m_nfcShare, SIGNAL(error(XQNfcShare::Error)), SLOT(handleNfcError(XQNfcShare::Error))); } } MyEasySetupClass::~MyEasySetupClass() { // No need to delete the XQNfcShare instance here, as we are its parent object. } void MyEasySetupClass::startEasySetup() { // Start easy setup to obtain Bluetooth information for a target device. // This call has no effect if the XQNfcShare instance is already busy. m_nfcShare->easySetup(); } void MyEasySetupClass::cancelEasySetup() { // Cancel the easy setup in case no near field contact has taken place yet. // If the XQNfcShare instance is busy, the current operation will be // cancelled and the error() signal will be emitted with a parameter // value of XQNfcShare::Cancelled, otherwise this call has no effect m_nfcShare->cancel(); } void MyEasySetupClass::handleNfcEasySetupStarted() { // The device has actually been brought into contact with a target // device and the exchange of bearer information has begun. This signal // is merely informational, there is no need to do anything here. } void MyEasySetupClass::handleNfcEasySetupCompleted() { // Easy setup has been completed successfully, the bearer type (here we're // only interested in the Bluetooth bearer type) specific properties are // now available and valid. The newly acquired target device information // could be e.g. displayed on the user interface, or used to open a // Bluetooth connection using the Qt Mobility connectivity classes. if (m_nfcShare->bearerType() == XQNfcShare::Bluetooth) { QString bluetoothDeviceName = m_nfcShare->bluetoothDeviceName(); QString bluetoothDeviceAddress = m_nfcShare->bluetoothDeviceAddress(); quint32 bluetoothDeviceClass = m_nfcShare->bluetoothDeviceClass(); } } void MyEasySetupClass::handleNfcBusy(bool busy) { if (busy) { // XQNfcShare has been activated. The busy property changes to true // as soon as the easySetup() function is called - no near field // contact has taken place yet. You can use the easySetupStarted() // signal to know exactly when NFC kicks in. } else { // XQNfcShare has been deactivated. The busy() signal is emitted with // a value of false whether or not the requested operation completed // successfully. } } void MyEasySetupClass::handleNfcError(XQNfcShare::Error error) { switch (error) { case XQNfcShare::Cancelled: // Easy setup has been cancelled before it was completed. break; default: // The easy setup attempt ended in an error. break; } }
Calling easySetup() currently always results in a Bluetooth bearer being selected. There is no way to specify a preferred bearer, such as wireless LAN, the bearer selection is an implementation detail that cannot be parameterized.
See also: easySetupCompleted(), error(Error), XQNfcShare::Error
void | easySetupAndPair | ( | ) | [slot] |
Obtains bearer information for establishing a connection between this device and the target device and creates a Bluetooth Out-Of-Band (OOB) pairing between the two.
This is an asynchronous operation which completes when either this device is touched together with another NFC-enabled device and the bearer information exchange and pairing is successfully completed, or when this operation is cancelled by calling cancel().
Easy setup with OOB pairing works identically to normal easy setup except that after obtaining the target device information an additional step is performed to form a Bluetooth pairing between the two devices. The usage of easySetupAndPair() is identical to the code snippet shown in the documentation for easySetup(), except in the void MyEasySetupClass::startEasySetup() slot you would call m_nfcShare->easySetupAndPair() instead of m_nfcShare->easySetup(). The required signal-slot connections and sequence of operation is otherwise exactly the same.
Calling easySetupAndPair() currently always results in a Bluetooth bearer being selected. There is no way to specify a preferred bearer, such as a wireless LAN, the bearer selection is an implementation detail that cannot be parameterized.
See also: easySetup(), easySetupCompleted(), error(Error), XQNfcShare::Error
void | easySetupCompleted | ( | ) | [signal] |
Emitted when an easy setup operation completes.
This signal is emitted when the setup operation started by calling either easySetup() or easySetupAndPair() completes and new bearer information is available.
After this signal is emitted, the newly selected bearer type is stored as the value of the bearerType() property. Bearer type values other than XQNfcShare::NoBearer indicate a valid bearer and properties associated with the selected bearer type are also usable. See bearerType() for details.
If errors occur during the easy setup operation, the signal is error(Error) is emitted instead of this signal.
See also: easySetup(), easySetupAndPair(), easySetupStarted(), bearerType(), error(Error)
void | easySetupStarted | ( | ) | [signal] |
Emitted when exchange of bearer information starts.
This signal is emitted when the either of the functions easySetup() or easySetupAndPair() has been called, this device has had near field contact with the target device and the exchange of bearer information has begun.
See also: easySetup(), easySetupAndPair(), easySetupCompleted()
void | error | ( | XQNfcShare::Error | error | ) | [signal] |
Emitted when any operation terminates abnormally.
This signal is emitted when any of the share(), easySetup() or easySetupAndPair() operations encounter an error condition. While technically not an error, calling cancel() when any operation is ongoing causes the error(Error) signal to be emitted with an error parameter value of XQNfcShare::Cancelled.
If an error occurs the signals shareCompleted() or easySetupCompleted() normally emitted on operation completion are not emitted.
See also: XQNfcShare::Error
Parameters | |
---|---|
error | An XQNfcShare::Error enumeration value describing the cause of the error condition. |
void | share | ( | ) | [slot] |
Requests notification when a target device comes into near field contact and is ready to receive one or more files.
File sharing happens in two stages. Before the actual file transmission can be started, near field contact must first take place so that a bearer channel may be selected.
As soon as this function is called, the busy(true) signal is emitted to indicate that this XQNfcShare instance is active. Note that this does not mean that any sharing is taking place yet. Calling share() merely indicates that the caller is interested in sharing one or more files. At this point there is need to state which files will be sent, because no near field contact has taken place yet and there is no one to receive the files.
When there is a potential receiver for the files to be shared, the shareStarted() signal is emitted. When this signal is emitted, the two devices have been brought to close proximity with one another, and a bearer channel for the transmission has been successfully negotiated.
At this point one or more files may be transmitted by calling either shareFile() or shareFiles(). After either of these is called, the actual file transfer is performed. Once the files have been transferred successfully, the shareCompleted() signal is emitted. If errors occur at any point in the transmission, the error(Error) signal is emitted with an error parameter value describing the problem.
Whether or not the sharing completed successfully, the busy(false) signal is always emitted to indicate that the XQNfcShare instance is ready to receive another service request.
The following code snippet shows a simple QObject derived class declaration that is used to handle the file sharing operation in usage example below:
#ifndef MYFILESHARECLASS_H #define MYFILESHARECLASS_H #include <QtCore/QObject> #include <xqnfcshare.h> class MyFileShareClass : public QObject { Q_OBJECT public: explicit MyFileShareClass(QObject *parent = 0); virtual ~MyFileShareClass(); public slots: void startShareFile(); void cancelShareFile(); private slots: void handleNfcShareFileStarted(); void handleNfcShareFileCompleted(); void handleNfcBusy(bool busy); void handleNfcError(XQNfcShare::Error error); private: XQNfcShare *m_nfcShare; }; #endif // MYFILESHARECLASS_H
The following code snippet shows how to create a new XQNfcShare instance and how establish the signal-slot connections to receive file sharing state change notifications. The file transfer is started when the slot void MyFileShareClass::startShareFile() gets called:
#include "myefileshareclass.h" void MyFileShareClass::MyFileShareClass(QObject *parent) : QObject(parent) { // Construct a new instance. m_nfcShare = new XQNfcShare(this); // Connect signals for receiving state change notifications. connect(m_nfcShare, SIGNAL(shareStarted()), SLOT(handleNfcShareFileStarted())); connect(m_nfcShare, SIGNAL(shareCompleted()), SLOT(handleNfcShareFileCompleted())); connect(m_nfcShare, SIGNAL(busy(bool)), SLOT(handleNfcBusy(bool))); connect(m_nfcShare, SIGNAL(error(NfcShare::Error)), SLOT(handleNfcError(NfcShare::Error))); } } MyFileShareClass::~MyFileShareClass() { // No need to delete the XQNfcShare instance here, as we are its parent object. } void MyFileShareClass::startShareFile() { // Start sharing a file. No transmission will take place until the two // devices come into near field contact. Here we test to see if the // XQNfcShare instance is already busy to avoid doing any processing of // our own if it is. Usually this is not needed, as the share() call // has no effect if XQNfcShare is already doing something. if (!m_nfcShare->isBusy()) { m_nfcShare->share(); } } void MyFileShareClass::cancelShareFile() { // Cancel the sharing in case no near field contact has taken place yet. // If the XQNfcShare instance is busy, the current operation will be // cancelled and the error() signal will be emitted with a parameter // value of XQNfcShare::Cancelled, otherwise this call has no effect. m_nfcShare->cancel(); } void MyFileShareClass::handleNfcShareFileStarted() { // The device has actually been brought into contact with a target // device and file transmission is ready to begin. We can now pass in // the path of the file to be transmitted. const QString fileName("E:/Images/image0001.jpg"); m_nfcShare->shareFile(fileName); } void MyFileShareClass::handleNfcShareFileCompleted() { // File sharing has been completed successfully. Unlike in the easy setup // example, there are no values to retrieve here. Getting this signal // simply means that the transmission was error free and everything is OK. } void MyFileShareClass::handleNfcBusy(bool busy) { if (busy) { // XQNfcShare has been activated. The busy property changes to true // as soon as the shareFile() function is called - no near field // contact has taken place yet. You can use the shareStarted() signal // to know exactly when NFC kicks in. } else { // XQNfcShare has been deactivated. The busy() signal is emitted with // a value of false whether or not the requested operation completed // successfully. } } void MyFileShareClass::handleNfcError(XQNfcShare::Error error) { switch (error) { case XQNfcShare::NfcNotAvailable: // NFC hardware is not available or is not powered on. break; case XQNfcShare::DeviceNotAvailable: // Device is not available. This error may occur for example if the device // is in offline mode and Bluetooth could not be enabled or the active // connection is interrupted. break; case XQNfcShare::ConnectionDenied: // The transmission has been terminated abruptly. This may happen for // example if the target device moves out of transmission range. break; case XQNfcShare::Cancelled: // The file sharing operation has been cancelled. break; case XQNfcShare::SystemError: // Some other system speicif error has taken place. break; default: break; } }
See also: shareStarted(), shareCompleted(), error(Error)
void | shareCompleted | ( | ) | [signal] |
Emitted when a file transmission operation completes.
This signal is emitted when the transmission of one or more files started by calling one of the functions shareFile() or shareFiles() completes successfully.
If errors occur during the transmission, the signal is error(Error) is emitted instead of this signal.
See also: share(), shareStarted(), shareFile(), shareFiles(), error(Error)
void | shareFile | ( | const QString & | fileName | ) | [slot] |
Transfers a single file to the target device.
This function should be called from a slot connected to the shareStarted() signal to transfer a single file to the target device.
The share() function must have been called prior to calling shareFile(), or shareFile() will have no effect. Similarly, if shareFile() is called after share() but before the shareStarted() signal has been emitted, the call will have no effect.
shareFile() may fail if there are errors trying to read the file, or if the file fails DRM checks, i.e. it is protected and not forwardable.
As a rule of thumb, the file should not be opened manually before supplying the file to shareFile(). The file transmission will fail if the file is already open for writing of any kind, or for exclusive reading.
See also: share(), shareFiles(), shareStarted(), shareCompleted(), error(Error)
Parameters | |
---|---|
fileName | The absolute path of the file to transfer. |
void | shareFiles | ( | const QStringList & | fileNames | ) | [slot] |
Transfers multiple files to the target device.
This function should be called from a slot connected to the shareStarted() signal to transfer multiples file to the target device. The behaviour of this function is identical to the shareFile() function for sending one file, except that more than one file may be transferred with a single call. See the documentation of share() for a description of behaviour that is common to all sharing operations.
The share() function must have been called prior to calling shareFiles(), or shareFiles() will have no effect. Similarly, if shareFiles() is called after share() but before the shareStarted() signal has been emitted, the call will have no effect.
The usage of shareFiles() is identical to the shareFile() code snippet shown in the documentation for share(), except in the void MyFileShareClass::handleNfcShareFileStarted() slot you would call m_nfcShare->shareFiles() instead of m_nfcShare->shareFile(). The required signal-slot connections and sequence of operation is otherwise exactly the same.
There are circumstances under which all files that are supplied as parameters may not get transferred. This is the case for example if some of the supplied files are protected by DRM - only the files that can be sent are actually transmitted.
See also: share(), shareFile(), shareStarted(), shareCompleted(), error(Error)
Parameters | |
---|---|
fileNames | The absolute paths of the files to transfer. |
void | shareStarted | ( | ) | [signal] |
Emitted when a target device comes into near field contact and is ready to receive one or more files.
This signal is emitted when the share() function has been called, this device has had near field contact with the target device and a bearer channel for file transmission has been successfully negotiated.
See also: share(), shareFile(), shareFiles(), shareCompleted()