MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

NDEF Message Push Library

Introduction

This library provides a Qt-based API to push NFC (Near Field Communication) messages to other devices. NDEFPusher (NFC Data Exchange Format) class provides the interface.

List of classes the NDEF Message Push Library provides:

Name Content
NDEFPusher Provides interface to push NDEF messages

Getting started

Install NDEF Message Push Library development package libndefpush-dev and qt-mobility development packages to your development environment.

Use pkgconfig to link against the NDEF Message Push Library in qt project file.

CONFIG += link_pkgconfig
PKGCONFIG += libndefpush-1.0

Examples

The following example shows how to push a simple Ndef message containing an url record to other device.

The example application creates instance of NDEFPusher class and connects to signals provided by it to get notified about availability of the push service and status of the push request.

NDEFPusher pusher;

// This signal gets triggered when the Push service becomes available
// or when it is available and its status was ecplicitly requested
// by NDEFPusher::requestPushService() method.
connect(&pusher, SIGNAL(pushServiceAvailable()),
        this, SLOT(pushServiceAvailable()));

// This signal gets triggered when the Push service becomes unavailable
// or when it is unavailable and its status was ecplicitly requested
// by NDEFPusher::requestPushService() method.
connect(&pusher, SIGNAL(pushServiceUnavailable()),
        this, SLOT(pushServiceUnavailable()));

// This signal gets triggered when the push request completes
connect(&pusher, SIGNAL(pushComplete(unsigned int, enum NDEFPusher::RequestStatus)), 
        this, SLOT(pushComplete(unsigned int, enum NDEFPusher::RequestStatus)));

// Connect also to NDEFPusher::pushProgress() signal if progress
// of the push requests needs to be monitored

The next step is to request Ndef push service.

// Request push service
pusher.requestPushService();

When the push service is available NDEFPusher::pushServiceAvailable() signal gets triggered. It is now possible to make the Ndef push request.

// Create Ndef URL record
QUrl url("www.nokia.com");
QtMobility::QNdefNfcUriRecord record;
record.setUri(url);

// Create Ndef message with the URL record
QtMobility::QNdefMessage message = QtMobility::QNdefMessage(record);

// Request NFC push for the Ndef message
pusher.push(message, push_request_id);

When the message has been pushed NDEFPusher::pushComplete() signal gets triggered. The Ndef message gets pushed to the target device when nfc touch happens with the target.

Note: The message gets pushed only when the application that has requested the push is on foreground. It is not possible to implement backround process to push Ndef messages.

Full source code of the example below.

qt_uri_push.pro

TEMPLATE = app

SOURCES += main.cpp NDEFUriPusher.cpp

HEADERS += NDEFUriPusher.h

CONFIG += link_pkgconfig
PKGCONFIG += libndefpush-1.0

main.cpp

#include "NDEFUriPusher.h"

#include <QApplication>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    NDEFUriPusher pusher;

    pusher.setWindowTitle("Simple NDEF push example");
    pusher.showFullScreen();

    return app.exec();
}

NDEFUriPusher.h

#include <QWidget>
#include <QLabel>
#include <NDEFPusher.h>

class NDEFUriPusher : public QWidget 
{
    Q_OBJECT;

public:
    NDEFUriPusher(QWidget *parent = 0);

    ~NDEFUriPusher();

private slots:

    void pushServiceAvailable();

    void pushServiceUnavailable();

    void pushComplete(unsigned int id, enum NDEFPusher::RequestStatus status);

private:
    
    NDEFPusher pusher;

    unsigned int push_request_id;

    QLabel* label;
};

NDEFUriPusher.cpp

#include <QUrl>
#include <QString>
#include <QNdefMessage>
#include <QNdefNfcUriRecord>

#include "NDEFUriPusher.h"

NDEFUriPusher::NDEFUriPusher(QWidget *parent)
    : QWidget(parent), push_request_id(0)
{
    label = new QLabel(QString("Requesting push service..."), this);
    label->setGeometry(rect());

    // This signal gets triggered when the Push service becomes available
    // or when it is available and its status was ecplicitly requested
    // by NDEFPusher::requestPushService() method.
    connect(&pusher, SIGNAL(pushServiceAvailable()),
            this, SLOT(pushServiceAvailable()));

    // This signal gets triggered when the Push service becomes unavailable
    // or when it is unavailable and its status was ecplicitly requested
    // by NDEFPusher::requestPushService() method.
    connect(&pusher, SIGNAL(pushServiceUnavailable()),
            this, SLOT(pushServiceUnavailable()));

    // This signal gets triggered when the push request completes
    connect(&pusher, SIGNAL(pushComplete(unsigned int, enum NDEFPusher::RequestStatus)), 
            this, SLOT(pushComplete(unsigned int, enum NDEFPusher::RequestStatus)));

    // Connect also to NDEFPusher::pushProgress() signal if progress
    // of the push requests needs to be monitored

    // Request push service
    pusher.requestPushService();
}

NDEFUriPusher::~NDEFUriPusher()
{
    pusher.cancelPush(push_request_id);
}

void NDEFUriPusher::pushServiceAvailable()
{
    // Push service is available.
    // Let's now create a ndef message and request
    // NFC push for it.

    // Create Ndef URL record
    QUrl url("www.nokia.com");
    QtMobility::QNdefNfcUriRecord record;
    record.setUri(url);

    // Create Ndef message with the URL record
    QtMobility::QNdefMessage message = QtMobility::QNdefMessage(record);

    // Request NFC push for the Ndef message
    if (pusher.push(message, push_request_id))
        label->setText(QString("Push request done. Please touch the target device to complete the push."));
    else
        label->setText(QString("Push request failed"));
}

void NDEFUriPusher::pushServiceUnavailable()
{
    // Push service unavailable, cannot create a push request.
    push_request_id = 0;
    label->setText(QString("Push service unavailable."));
}

void NDEFUriPusher::pushComplete(unsigned int id, enum NDEFPusher::RequestStatus status)
{
    Q_UNUSED(id);
    push_request_id = 0;

    // The push request has been completed.

    if(status ==  NDEFPusher::REQUEST_OK )
        label->setText(QString("Push request succeeded!"));
    else
        label->setText(QString("Push request failed!"));
}

Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved.
MeeGo 1.2 Harmattan API