QNearFieldTarget Class

The QNearFieldTarget class provides an interface for communicating with a target device. More...

Header: #include <QNearFieldTarget>
qmake: QT += nfc
Since: Qt 5.2
Inherits: QObject

This class was introduced in Qt 5.2.

Public Types

class RequestId
enum AccessMethod { UnknownAccess, NdefAccess, TagTypeSpecificAccess, LlcpAccess }
flags AccessMethods
enum Error { NoError, UnknownError, UnsupportedError, TargetOutOfRangeError, NoResponseError, …, CommandError }
enum Type { ProprietaryTag, NfcTagType1, NfcTagType2, NfcTagType3, NfcTagType4, MifareTag }

Public Functions

QNearFieldTarget(QObject *parent = nullptr)
virtual ~QNearFieldTarget()
virtual QNearFieldTarget::AccessMethods accessMethods() const = 0
bool disconnect()
virtual bool hasNdefMessage()
bool isProcessingCommand() const
bool keepConnection() const
int maxCommandLength() const
virtual QNearFieldTarget::RequestId readNdefMessages()
QVariant requestResponse(const QNearFieldTarget::RequestId &id)
virtual QNearFieldTarget::RequestId sendCommand(const QByteArray &command)
virtual QNearFieldTarget::RequestId sendCommands(const QList<QByteArray> &commands)
bool setKeepConnection(bool isPersistent)
void setResponseForRequest(const QNearFieldTarget::RequestId &id, const QVariant &response, bool emitRequestCompleted = true)
virtual QNearFieldTarget::Type type() const = 0
virtual QByteArray uid() const = 0
virtual QUrl url() const
virtual bool waitForRequestCompleted(const QNearFieldTarget::RequestId &id, int msecs = 5000)
virtual QNearFieldTarget::RequestId writeNdefMessages(const QList<QNdefMessage> &messages)

Signals

void disconnected()
void error(QNearFieldTarget::Error error, const QNearFieldTarget::RequestId &id)
void ndefMessageRead(const QNdefMessage &message)
void ndefMessagesWritten()
void requestCompleted(const QNearFieldTarget::RequestId &id)

Protected Functions

virtual bool handleResponse(const QNearFieldTarget::RequestId &id, const QByteArray &response)
void reportError(QNearFieldTarget::Error error, const QNearFieldTarget::RequestId &id)
quint16 qNfcChecksum(const char *data, uint len)

Detailed Description

QNearFieldTarget provides a generic interface for communicating with an NFC target device. Both NFC Forum devices and NFC Forum Tag targets are supported by this class. All target specific classes subclass this class.

The type() function can be used to get the type of the target device. The uid() function returns the unique identifier of the target. The AccessMethods flags returns from the accessMethods() function can be tested to determine which access methods are supported by the target.

If the target supports NdefAccess, hasNdefMessage() can be called to test if the target has a stored NDEF message, readNdefMessages() and writeNdefMessages() functions can be used to get and set the NDEF message.

If the target supports TagTypeSpecificAccess, sendCommand() can be used to send a single proprietary command to the target and retrieve the response. sendCommands() can be used to send multiple proprietary commands to the target and retrieve all of the responses.

If the target supports LlcpAccess, the QLlcpSocket class can be used to connected to a service provided by the target.

Member Type Documentation

enum QNearFieldTarget::AccessMethod
flags QNearFieldTarget::AccessMethods

This enum describes the access methods a near field target supports.

ConstantValueDescription
QNearFieldTarget::UnknownAccess0x00The target supports an unknown access type.
QNearFieldTarget::NdefAccess0x01The target supports reading and writing NDEF messages using readNdefMessages() and writeNdefMessages().
QNearFieldTarget::TagTypeSpecificAccess0x02The target supports sending tag type specific commands using sendCommand() and sendCommands().
QNearFieldTarget::LlcpAccess0x04The target supports peer-to-peer LLCP communication.

The AccessMethods type is a typedef for QFlags<AccessMethod>. It stores an OR combination of AccessMethod values.

enum QNearFieldTarget::Error

This enum describes the error codes that a near field target reports.

ConstantValueDescription
QNearFieldTarget::NoError0No error has occurred.
QNearFieldTarget::UnknownError1An unidentified error occurred.
QNearFieldTarget::UnsupportedError2The requested operation is unsupported by this near field target.
QNearFieldTarget::TargetOutOfRangeError3The target is no longer within range.
QNearFieldTarget::NoResponseError4The target did not respond.
QNearFieldTarget::ChecksumMismatchError5The checksum has detected a corrupted response.
QNearFieldTarget::InvalidParametersError6Invalid parameters were passed to a tag type specific function.
QNearFieldTarget::NdefReadError7Failed to read NDEF messages from the target.
QNearFieldTarget::NdefWriteError8Failed to write NDEF messages to the target.
QNearFieldTarget::CommandError9Failed to send a command to the target.

enum QNearFieldTarget::Type

This enum describes the type of tag the target is detected as.

ConstantValueDescription
QNearFieldTarget::ProprietaryTag0An unidentified proprietary target tag.
QNearFieldTarget::NfcTagType11An NFC tag type 1 target.
QNearFieldTarget::NfcTagType22An NFC tag type 2 target.
QNearFieldTarget::NfcTagType33An NFC tag type 3 target.
QNearFieldTarget::NfcTagType44An NFC tag type 4 target.
QNearFieldTarget::MifareTag5A Mifare target.

Member Function Documentation

QNearFieldTarget::QNearFieldTarget(QObject *parent = nullptr)

Constructs a new near field target with parent.

[signal] void QNearFieldTarget::disconnected()

This signal is emitted when the near field target moves out of proximity.

[signal] void QNearFieldTarget::error(QNearFieldTarget::Error error, const QNearFieldTarget::RequestId &id)

This signal is emitted when an error occurs while processing request id. The error parameter describes the error.

[signal] void QNearFieldTarget::ndefMessageRead(const QNdefMessage &message)

This signal is emitted when a complete NDEF message has been read from the target.

See also readNdefMessages().

[signal] void QNearFieldTarget::ndefMessagesWritten()

This signal is emitted when NDEF messages have been successfully written to the target.

See also writeNdefMessages().

[signal] void QNearFieldTarget::requestCompleted(const QNearFieldTarget::RequestId &id)

This signal is emitted when a request id completes.

See also sendCommand().

[virtual] QNearFieldTarget::~QNearFieldTarget()

Destroys the near field target.

[pure virtual] QNearFieldTarget::AccessMethods QNearFieldTarget::accessMethods() const

Returns the access methods support by this near field target.

bool QNearFieldTarget::disconnect()

Closes the connection to the target.

Returns true only if an existing connection was successfully closed.

This function was introduced in Qt 5.9.

See also keepConnection() and setKeepConnection().

[virtual protected] bool QNearFieldTarget::handleResponse(const QNearFieldTarget::RequestId &id, const QByteArray &response)

Handles the response received for the request id. Returns true if the response is handled; otherwise returns false.

Classes reimplementing this virtual function should call the base class implementation to ensure that requests initiated by those classes are handled correctly.

The default implementation stores the response such that it can be retrieved by requestResponse().

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[virtual] bool QNearFieldTarget::hasNdefMessage()

Returns true if at least one NDEF message is stored on the near field target; otherwise returns false.

bool QNearFieldTarget::isProcessingCommand() const

Returns true if the target is processing commands; otherwise returns false.

bool QNearFieldTarget::keepConnection() const

Returns true if this feature is enabled.

This function was introduced in Qt 5.9.

See also setKeepConnection() and disconnect().

int QNearFieldTarget::maxCommandLength() const

Returns the maximum number of bytes that can be sent with sendCommand. 0 will be returned if the target does not support sending tag type specific commands.

This function was introduced in Qt 5.9.

See also sendCommand() and sendCommands().

[virtual] QNearFieldTarget::RequestId QNearFieldTarget::readNdefMessages()

Starts reading NDEF messages stored on the near field target. Returns a request id which can be used to track the completion status of the request. An invalid request id will be returned if the target does not support reading NDEF messages.

An ndefMessageRead() signal will be emitted for each NDEF message. The requestCompleted() signal will be emitted was all NDEF messages have been read. The error() signal is emitted if an error occurs.

[protected] void QNearFieldTarget::reportError(QNearFieldTarget::Error error, const QNearFieldTarget::RequestId &id)

Reports the error for the request id by appending the signal emission to the event queue.

This function was introduced in Qt 5.12.

QVariant QNearFieldTarget::requestResponse(const QNearFieldTarget::RequestId &id)

Returns the decoded response for request id. If the request is unknown or has not yet been completed an invalid QVariant is returned.

[virtual] QNearFieldTarget::RequestId QNearFieldTarget::sendCommand(const QByteArray &command)

Sends command to the near field target. Returns a request id which can be used to track the completion status of the request. An invalid request id will be returned if the target does not support sending tag type specific commands.

The requestCompleted() signal will be emitted on successful completion of the request; otherwise the error() signal will be emitted.

Once the request completes successfully the response can be retrieved from the requestResponse() function. The response of this request will be a QByteArray.

See also requestCompleted() and waitForRequestCompleted().

[virtual] QNearFieldTarget::RequestId QNearFieldTarget::sendCommands(const QList<QByteArray> &commands)

Sends multiple commands to the near field target. Returns a request id which can be used to track the completion status of the request. An invalid request id will be returned if the target does not support sending tag type specific commands.

If all commands complete successfully the requestCompleted() signal will be emitted; otherwise the error() signal will be emitted. If a command fails succeeding commands from this call will not be processed.

Once the request completes the response for successfully completed requests can be retrieved from the requestResponse() function. The response of this request will be a QList<QByteArray>.

See also requestCompleted() and waitForRequestCompleted().

bool QNearFieldTarget::setKeepConnection(bool isPersistent)

Preserves the connection to the target device after processing a command or reading/writing NDEF messages if isPersistent is true. By default, this behavior is not enabled.

Returns true if enabling this feature was successful. A possible reason for a failure is the lack of support on the used platform.

Enabling this feature requires to use the disconnect() function too, to close the connection manually and enable communication with the target from a different instance. Disabling this feature will also close an open connection.

This function was introduced in Qt 5.9.

See also keepConnection() and disconnect().

void QNearFieldTarget::setResponseForRequest(const QNearFieldTarget::RequestId &id, const QVariant &response, bool emitRequestCompleted = true)

Sets the decoded response for request id to response. If emitRequestCompleted is true the requestCompleted() signal will be emitted for id; otherwise no signal will be emitted.

See also requestResponse().

[pure virtual] QNearFieldTarget::Type QNearFieldTarget::type() const

Returns the type of tag type of this near field target.

[pure virtual] QByteArray QNearFieldTarget::uid() const

Returns the UID of the near field target.

[virtual] QUrl QNearFieldTarget::url() const

Returns the URL of the near field target.

[virtual] bool QNearFieldTarget::waitForRequestCompleted(const QNearFieldTarget::RequestId &id, int msecs = 5000)

Waits up to msecs milliseconds for the request id to complete. Returns true if the request completes successfully and the requestCompeted() signal is emitted; otherwise returns false.

[virtual] QNearFieldTarget::RequestId QNearFieldTarget::writeNdefMessages(const QList<QNdefMessage> &messages)

Writes the NDEF messages in messages to the target. Returns a request id which can be used to track the completion status of the request. An invalid request id will be returned if the target does not support reading NDEF messages.

The ndefMessagesWritten() signal will be emitted when the write operation completes successfully; otherwise the error() signal is emitted.

Related Non-Members

quint16 qNfcChecksum(const char *data, uint len)

Returns the NFC checksum of the first len bytes of data.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. 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.