Back to Qt.io
Contact Us Blog Download Qt

C

QAndroidBroadcastReceiver Class

Allows receiving broadcasts with custom Intent Filters. (Technical Preview). More...

Header: #include <QAndroidBroadcastReceiver>
CMake: find_package(Qt6 REQUIRED COMPONENTS AndroidAutomotiveBase)
target_link_libraries(mytarget PRIVATE Qt6::AndroidAutomotiveBase)
Since: QtAndroidAutomotive 6.5
Inherits: QObject

Public Types

ExtraToVariantFunc

Public Functions

QAndroidBroadcastReceiver(QObject *parent = nullptr)
QAndroidBroadcastReceiver(QAndroidIntentFilter *filter, QObject *parent = nullptr)
bool hasConverter(const QString &javaTypename) const
QAndroidIntentFilter *intentFilter() const
void registerConverter(const QString &javaTypename, QAndroidBroadcastReceiver::ExtraToVariantFunc func)
bool running()
void setIntentFilter(QAndroidIntentFilter *filter)
bool unregisterConverter(const QString &javaTypename)

Public Slots

bool start()
bool stop()

Signals

void intentFilterChanged()
void jniObjectReceived(const QJniObject &intent)
void received(const QAndroidIntentInfo &intent)

Static Public Members

bool hasGlobalConverter(const QString &javaTypename)
void registerGlobalConverter(const QString &javaTypename, QAndroidBroadcastReceiver::ExtraToVariantFunc func)
bool removeGlobalConverter(const QString &javaTypename)

Detailed Description

This class will automatically use QAndroidBroadcastReceiver::ExtraToVariantFunc functions to convert extras received within intents.

Here is a basic example of filtering for a specific action via QAndroidIntentFilter usage and parsing the extras:

QAndroidIntentFilter filter{ "org.qt.io.example.action.ACTION_DATE" };
QAndroidBroadcastReceiver receiver(&filter);
QObject::connect(&receiver,
                 &QAndroidBroadcastReceiver::received,
                 [] (const QAndroidIntentInfo &intent) {
    const auto dateVariant = intent.extras().value("date");
    qDebug()<<dateVariant;
    if (dateVariant.metaType().id() == qMetaTypeId<QDate>()) {
        QDate date = dateVariant.toDate();
        qDebug() << "Received date: " << date;
    }
});

So that the user does not need to provide a custom conversion function for all basic types, the API has some conversions handled internally. These default conversions can also be overridden by using registerConverter and registerGlobalConverter.

  • Bundle, see note about Bundle conversions.
  • jstring
  • jboolean
  • jbyte
  • jchar
  • jshort
  • jint
  • jlong
  • jfloat
  • jdouble

Note: Bundles are iterated over and each value is converted by using available converters, including user-provided local and global converters.

Member Type Documentation

QAndroidBroadcastReceiver::ExtraToVariantFunc

This is a typedef for std::function<QVariant(const QStringList &, const QJniObject &)>, which is a special function that is used to convert data from Java types to QVariants.

These functions are used whenever a new broadcast is received, to convert extras data from Java types to QVariant. Users may register custom conversion functions of this type via registerConverter(), which takes another argument that defines what Java type the conversion function will be used to convert.

For example, users may register a global custom conversion function for dates, which will be called by all QAndroidBroadcastReceiver instances to get a valid QDate out of a Android Bundle that contains fields year, month and day:

QAndroidBroadcastReceiver::ExtraToVariantFunc dateReceiverConverter = [] (
        const QStringList &keys,
        const QJniObject &bundle) {
    if (!keys.size() || keys.last() != "date")
        return QVariant();

    const auto yearKey = QJniObject::fromString("year");
    const auto yearString = yearKey.object<jstring>();
    const auto hasYear = bundle.callMethod<jboolean>("containsKey", yearString);

    const auto monthKey = QJniObject::fromString("month");
    const auto monthString = monthKey.object<jstring>();
    const auto hasMonth = bundle.callMethod<jboolean>("containsKey", monthString);

    const auto dayKey = QJniObject::fromString("day");
    const auto dayString = dayKey.object<jstring>();
    const auto hasDay = bundle.callMethod<jboolean>("containsKey", dayString);

    if (hasYear && hasMonth && hasDay) {
        const auto year = bundle.callMethod<jint>("getInt", yearString, 1970);
        const auto month = bundle.callMethod<jint>("getInt", monthString, 1);
        const auto day = bundle.callMethod<jint>("getInt", dayString, 1);
        QDate date(year, month, day);
        return QVariant::fromValue(date);
    }
    return QVariant();
};
QAndroidBroadcastReceiver::registerGlobalConverter("android.os.Bundle",
                                                   dateReceiverConverter);

If the conversion function returns an invalid QVariant, the result will be ignored and the data will be processed internally by QAndroidBroadcastReceiver.

When a new intent is received, this type of function may be called to read the received extras data in the intent to a QVariant.

The function will receive a QStringList argument. This argument will be the path of keys from the root of the extras object to the value currently being converted. This key may be used to detect data that the user wants to handle in some specific way.

The function will also receive a QJniObject argument which will contain the data to be converted. This data can either be the entire extras bundle or one of the objects within that bundle, depending on what data type the function has been registered for.

See also registerConverter() and registerGlobalConverter().

Member Function Documentation

[explicit] QAndroidBroadcastReceiver::QAndroidBroadcastReceiver(QObject *parent = nullptr)

Constructs a QAndroidBroadcastReceiver with the given parent.

[explicit] QAndroidBroadcastReceiver::QAndroidBroadcastReceiver(QAndroidIntentFilter *filter, QObject *parent = nullptr)

Constructs a QAndroidBroadcastReceiver object with the given parent and sets the given QAndroidIntentFilter filter as the active intent filter.

See also setIntentFilter().

[invokable] bool QAndroidBroadcastReceiver::hasConverter(const QString &javaTypename) const

Returns true if a local converter for Java type javaTypename has been registered, false if not.

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

See also registerConverter() and unregisterConverter().

[static] bool QAndroidBroadcastReceiver::hasGlobalConverter(const QString &javaTypename)

Returns true if a global converter for Java type javaTypename has been registered, false if not.

See also registerGlobalConverter() and removeGlobalConverter().

[invokable] QAndroidIntentFilter *QAndroidBroadcastReceiver::intentFilter() const

Returns the current intent filter.

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

See also setIntentFilter().

[signal] void QAndroidBroadcastReceiver::intentFilterChanged()

This signal is fired when a new intent filter has been set for this receiver.

[signal] void QAndroidBroadcastReceiver::jniObjectReceived(const QJniObject &intent)

This signal is fired when a new intent has been received. The intent will contain the QJniObject representation of that intent.

This signal can be used instead of QAndroidBroadcastReceiver::received if the user wants direct access to the QJniObject that wraps the underlying Android Intent.

[signal] void QAndroidBroadcastReceiver::received(const QAndroidIntentInfo &intent)

This signal is fired when a new intent has been received. The intent contains the QAndroidIntentInfo representation of that intent.

void QAndroidBroadcastReceiver::registerConverter(const QString &javaTypename, QAndroidBroadcastReceiver::ExtraToVariantFunc func)

Registers a new local converter func that will be used for Java types with name javaTypename.

A local converter is a QAndroidBroadcastReceiver::ExtraToVariantFunc function that is only usable from this instance of QAndroidBroadcastReceiver.

Note: Each type with this name may only have one registered local converter.

See also unregisterConverter() and hasConverter().

[static] void QAndroidBroadcastReceiver::registerGlobalConverter(const QString &javaTypename, QAndroidBroadcastReceiver::ExtraToVariantFunc func)

Registers a new global converter func that will be called when a broadcast is received and has an extra of type javaTypename.

A global converter is a QAndroidBroadcastReceiver::ExtraToVariantFunc function that is used by all instances of QAndroidBroadcastReceiver.

Note: Each type with this name may only have one registered global converter.

See also removeGlobalConverter() and hasGlobalConverter().

[static] bool QAndroidBroadcastReceiver::removeGlobalConverter(const QString &javaTypename)

Removes the global converter for the Java type with name javaTypename.

Returns true if the converter existed and was removed, false otherwise.

See also registerGlobalConverter() and hasGlobalConverter().

bool QAndroidBroadcastReceiver::running()

Returns true if the receiver has been started, false if not.

See also start() and stop().

void QAndroidBroadcastReceiver::setIntentFilter(QAndroidIntentFilter *filter)

Sets current intent filter to filter, taking ownership of the filter in the process.

See also intentFilter().

[slot] bool QAndroidBroadcastReceiver::start()

Starts the receiver. Once running, it will become active and start receiving broadcasts until stopped.

Returns true if the receiver was successfully started, false otherwise.

See also stop() and running().

[slot] bool QAndroidBroadcastReceiver::stop()

Stops the receiver. This receiver will not receive broadcasts again until started.

Returns true if the receiver was running and is now stopped, false otherwise.

See also start() and running().

bool QAndroidBroadcastReceiver::unregisterConverter(const QString &javaTypename)

Removes local converter for the Java type with name javaTypename.

Returns true if converter existed and was removed, false otherwise.

See also registerConverter() and hasConverter().

Available under certain Qt licenses.
Find out more.