This is a HOWTO for people like me. People who know absolutely nothing about C++ but are cocky enough to do their BlackBerry 10 apps in Cascades anyway. So you've got your Cascades app, you've done some cool stuff in QML but then you want to add BBM Invite functionality. Ouch. Gonna need to dive into some C++. It was quite a struggle for me to get BBM Invite to work so I want to make sure it isn't for YOU. Big thanks go to Jerome Carty for helping me tie all this stuff together and Daraius G for sending me some useful code. So without further ado, here goes:

1: Add the four files attached to this email to your project:

1: InviteToDownload.hpp

/*
* Copyright (c) 2012 Jason I. Carter
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/


#ifndef INVITETODOWNLOAD_HPP_
#define INVITETODOWNLOAD_HPP_

#include <QtCore/QObject>

namespace bb {namespace platform {namespace bbm {class Context; class MessageService;}}}

/**
 * @brief A class that encapsulates the sending of the 'Invite to Download' message.
 */
class InviteToDownload: public QObject
{
Q_OBJECT


public:
	// Creates a new 'invite to download' object.
	InviteToDownload(bb::platform::bbm::Context *context);
	~InviteToDownload();

	// This method is invoked to open the invitation dialog
	Q_INVOKABLE void sendInvite();

private:
	// The service object to send BBM messages
	bb::platform::bbm::MessageService * m_messageService;
	bb::platform::bbm::Context* m_context;

};

#endif /* INVITETODOWNLOAD_HPP_ */

View Raw Code →


2: InviteToDownload.cpp

/*
 * Copyright (c) 2012 Jason I. Carter
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include "InviteToDownload.hpp"

#include <bb/platform/bbm/MessageService>
#include <bb/system/SystemToast>
#include <bps/netstatus.h>

using namespace bb::system;

InviteToDownload::InviteToDownload(bb::platform::bbm::Context *context) :
		m_messageService(0), m_context(context) {
}

InviteToDownload::~InviteToDownload() {
	delete m_messageService;
}

void InviteToDownload::sendInvite() {
	bool is_available;
	netstatus_get_availability(&is_available);

	if (is_available) {

		if (!m_messageService) {
			// Instantiate the MessageService.
			m_messageService = new bb::platform::bbm::MessageService(m_context,
					this);
		}

		// Trigger the invite to download process.
		m_messageService->sendDownloadInvitation();
	} else {
		SystemToast *toast = new SystemToast(this);
		toast->setBody("No network connection available.");
		toast->show();
	}
}

View Raw Code →


3: RegistrationHandler.hpp

View Raw Code →


/* Copyright (c) 2012 Research In Motion Limited.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef REGISTRATIONHANDLER_HPP
#define REGISTRATIONHANDLER_HPP

#include <bb/platform/bbm/Context>
#include <bb/platform/bbm/RegistrationState>
#include <bb/system/SystemUiResult>

#include <QtCore/QObject>
#include <QUuid>

/**
 * @brief A class that encapsulates the registration at the BBM Social Platform.
 */
//! [0]
class RegistrationHandler : public QObject
{
    Q_OBJECT

    // Flag indicating whether the application is successfully registered
    // with BBM.
    Q_PROPERTY(bool allowed READ isAllowed NOTIFY stateChanged)

    // The status message describing the registration process.
    Q_PROPERTY(QString statusMessage READ statusMessage NOTIFY stateChanged)

    // Flag indicating whether registration failed due to a temporary error.
    // This allows the user to re-try registration.
    Q_PROPERTY(bool temporaryError READ isTemporaryError NOTIFY stateChanged)

public:
    // Enumerates the possible registration progress states.
    struct BbmRegistrationProgress
    {
        enum Type {
            // Registration has not started and has never been attempted since
            // the application started.
            NotStarted = 0,
            // Registration has started.
            Started,
            // Registration is in progress.
            Pending,
            // Registration is done. Use isRegistered() or
            // Context::isAccessAllowed() to check if the application is
            // registered successfully.
            Finished
        };
    };

    /**
     * Creates a new registration handler.
     *
     * @param uuid The unique ID of the application
     * @param parent The parent object
     */
    RegistrationHandler(const QUuid &uuid, QObject *parent = 0);

    /**
     * Returns the BBM context that is associated with this application.
     */
    bb::platform::bbm::Context& context()
    { return m_context; }

    /**
     * Returns the registration progress.
     * @see BbmRegistrationProgress::Type
     */
    BbmRegistrationProgress::Type progress() const
    { return m_progress; }

public Q_SLOTS:
    /**
     * This method is called to trigger the registration with the BBM Social
     * Platform. Check the progress prior to calling this function to ensure
     * that another registration is not in progress.
     */
    void registerApplication();

Q_SIGNALS:
    // The change notification signal of the properties.
    void stateChanged();

private Q_SLOTS:
    // This slot is invoked whenever the registration status is changed.
    // This will initiate, continue, or finish registration based on the status.
    // @param state is the registration state
    void processRegistrationStatus(const bb::platform::bbm::RegistrationState::Type state);

    // This slot is invoked when the uuid is invalid or NULL.
    // This will cause the application to exit with error code -1
    // @param value is the system ui result indicating which button was pressed
    void dialogFinished(bb::system::SystemUiResult::Type value);

private:
    // Return true if registration has completed successfully.
    bool isAllowed() const
    { return m_isAllowed; }

    // Return true if registration failed due to a temporary error.
    bool isTemporaryError() const
    { return m_temporaryError; }

    // Return the message that describes the registration state.
    const QString& statusMessage() const
    { return m_statusMessage; }

    // Registration finished. This method updates m_registered, m_statusMessage,
    // and m_progress. It emits a stateChanged() signal.
    void registrationFinished();

    // BBM Social Platform Context used to gain access to BBM functionality.
    bb::platform::bbm::Context m_context;

    // A flag that indicates whether registration completed successfully.
    bool m_isAllowed;

    // Registration progress. Use this to check if you have already attempted
    // registration, if registration has finished, or it's still in progress.
    BbmRegistrationProgress::Type m_progress;

    // A flag that indicates whether registration failed due to a temporary
    // error.
    bool m_temporaryError;

    // A status message that describes the current state of registration.
    QString m_statusMessage;
};
//! [0]

#endif

View Raw Code →


4: RegistrationHandler.cpp

/* Copyright (c) 2012 Research In Motion Limited.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include "RegistrationHandler.hpp"

#include <bb/cascades/AbstractPane>
#include <bb/cascades/Application>
#include <bb/cascades/QmlDocument>
#include <bb/system/SystemDialog>

#include <bb/platform/bbm/Context>
#include <bb/platform/bbm/RegistrationState>

using namespace bb::cascades;
using namespace bb::platform::bbm;
using namespace bb::system;

//! [0]
RegistrationHandler::RegistrationHandler(const QUuid &uuid, QObject *parent)
    : QObject(parent)
    , m_context(uuid)
    , m_isAllowed(false)
    , m_progress(BbmRegistrationProgress::NotStarted)
    , m_temporaryError(false)
    , m_statusMessage(tr("Please wait while the application connects to BBM."))
{
    if (uuid.isNull()) {
    	SystemDialog *uuidDialog = new SystemDialog("OK");
    	uuidDialog->setTitle("UUID Error");
        uuidDialog->setBody("Invalid/Empty UUID, please set correctly in main.cpp");
        connect(uuidDialog, SIGNAL(finished(bb::system::SystemUiResult::Type)), this, SLOT(dialogFinished(bb::system::SystemUiResult::Type)));
        uuidDialog->show();
        return;
    }
    connect(&m_context,
            SIGNAL(registrationStateUpdated(
                   bb::platform::bbm::RegistrationState::Type)),
            this,
            SLOT(processRegistrationStatus(
                 bb::platform::bbm::RegistrationState::Type)));
    RegistrationHandler::registerApplication();
}
//! [0]


//! [1]
void RegistrationHandler::registerApplication()
{
    m_progress = BbmRegistrationProgress::Started;
    processRegistrationStatus(m_context.registrationState());
}
//! [1]

//! [2]
void RegistrationHandler::processRegistrationStatus(const RegistrationState::Type state)
{
    // Based on the state, decide whether we need to register. If we already
    // registered successfully once (i.e. on a previous application run), then
    // we will not call requestRegisterApplication() again.
    qDebug() << "Received a BBM Social Platform registration access state="
        << state;
    switch(m_progress)
    {
    case BbmRegistrationProgress::Pending:
        if (state != RegistrationState::Pending) {
            registrationFinished();
            return;
        }
        // Otherwise, ignore since registration is still in progress.
        break;

    case BbmRegistrationProgress::Started:
        if (m_context.isAccessAllowed()) {
            // Access is allowed, the application is registered.
            registrationFinished();
            return;
        }
        if (m_context.registrationState() == RegistrationState::Unknown) {
            // Status is not yet known. Wait for an event that will deliver the
            // status.
            qDebug() << "BBM Social Platform access state is UNKNOWN; waiting "
                "for the initial status";
            return;
        }
        // Start registration.
        if (m_context.requestRegisterApplication()) {
            // Registration started. The user will see a dialog informing them
            // that your application is connecting to BBM.
            m_progress = BbmRegistrationProgress::Pending;
            qDebug() << "BBM Social Platform registration started";
            qDebug() << "Verify you are using a valid UUID";
            return;
        }
        // Could not start registration. No dialogs were shown.
        qDebug() << "BBM Social Platform registration could not be started";
        registrationFinished();
        break;

    case BbmRegistrationProgress::Finished:
        if (m_context.isAccessAllowed() != m_isAllowed) {
            // Access to the BBM Social Platform has changed.
            registrationFinished();
        }
        break;

    default:
        qDebug() << "Ignoring BBM Social Platform access state=" << state
            << "when progress=" << m_progress;
        break;
    }
}
//![2]

//! [3]
void RegistrationHandler::registrationFinished()
{
    // Finish registration and use the state to decide which message to show
    // the user.
    m_progress = BbmRegistrationProgress::Finished;
    switch (m_context.registrationState()) {
    case RegistrationState::Allowed:
        m_statusMessage = tr("Application connected to BBM.  Press Continue.");
        m_temporaryError = false;
        break;

// This error code is not yet available in the NDK.
//    case RegistrationState::BbmDisabled:
//        m_statusMessage = tr("Cannot connect to BBM. BBM is not setup. "
//                             "Open BBM to set it up and try again.");
//        m_temporaryError = false;
//        break;

    case RegistrationState::BlockedByRIM:
        m_statusMessage = tr("Disconnected by RIM. RIM is preventing this "
                             "application from connecting to BBM.");
        m_temporaryError = false;
        break;

    case RegistrationState::BlockedByUser:
        m_statusMessage = tr("Disconnected. Go to Settings -> Security and "
                             "Privacy -> Application Permissions and "
                             "connect this application to BBM.");
        m_temporaryError = false;
        break;

    case RegistrationState::InvalidUuid:
        // You should be resolving this error at development time.
        m_statusMessage = tr("Invalid UUID. Report this error to the "
                             "vendor.");
        m_temporaryError = true;
        break;

    case RegistrationState::MaxAppsReached:
        m_statusMessage = tr("Too many applications are connected to BBM. "
                             "Uninstall one or more applications and try "
                             "again.");
        m_temporaryError = false;
        break;

    case RegistrationState::Expired:
    case RegistrationState::MaxDownloadsReached:
        m_statusMessage = tr("Cannot connect to BBM. Download this "
                             "application from AppWorld to keep using it.");
        m_temporaryError = false;
        break;

    case RegistrationState::NoDataConnection:
        m_statusMessage = tr("Check your Internet connection and try again.");
        m_temporaryError = true;
        break;

    case RegistrationState::Pending:
        // The user will never see this. The BBM Social Platform already
        // displays a "Connecting" dialog.
        m_statusMessage = tr("Connecting to BBM. Please wait.");
        m_temporaryError = false;
        break;

    case RegistrationState::Unknown:
        m_statusMessage = tr("Determining the status. Please wait.");
        m_temporaryError = false;
        break;

    case RegistrationState::Unregistered:
    case RegistrationState::UnexpectedError:
    case RegistrationState::TemporaryError:
    case RegistrationState::CancelledByUser:
    default:
        // If new error codes are added, treat them as temporary errors.
        m_statusMessage = tr("Would you like to connect the application to "
                             "BBM?");
        m_temporaryError = true;
        break;
    }

    if (m_context.isAccessAllowed()) {
        m_isAllowed = true;
    } else {
        m_isAllowed = false;
    }
    qDebug() << "Finished BBM Social Platform registration, success="
        << m_isAllowed << "temporaryError=" << m_temporaryError;
    emit stateChanged();
}
//! [3]

void RegistrationHandler::dialogFinished(bb::system::SystemUiResult::Type value) {
	Application::exit(-1);
}

View Raw Code →


2: In your project's .pro file, add these two lines:

LIBS += -lbbplatformbbm
LIBS += -lbbsystem

View Raw Code →


3: In YourApp.hpp add:

#include "RegistrationHandler.hpp"
#include "InviteToDownload.hpp"

View Raw Code →


and under the public bit:

private:
    RegistrationHandler *registrationHandler;
    InviteToDownload *inviteToDownload;

View Raw Code →


4: In YourApp.cpp add:

#include "RegistrationHandler.hpp"
#include "InviteToDownload.hpp"

View Raw Code →


and in the constructor:

// replace YOUR_GUID with a guid from http://www.guidgenerator.com/

const QUuid uuid(QLatin1String("YOUR_GUID"));

// Register with BBM.
registrationHandler = new RegistrationHandler(uuid, app);
inviteToDownload = new InviteToDownload(&registrationHandler->context());

QmlDocument *qml = QmlDocument::create("asset:///main.qml").parent(this);
qml->setContextProperty("inviteToDownload", inviteToDownload);

View Raw Code →


5: In your QML you can now use:

inviteToDownload.sendInvite();

View Raw Code →


Use it for example in an onClicked() handler on a button you have defined somewhere to activate the BBM Invite functionality.

I hope this HOWTO is useful for some people who aren't blessed with C++ skills (yet).

Enjoy!