Qt for HarmonyOS/user development guide/application continuation guild

English 中文

Introduction

This document is intended for Qt developers and explains how to implement **Application Continuation** (migrating application state across devices) on HarmonyOS. The QtOhosExtras module has encapsulated HarmonyOS workflows such as onContinue/onNewWant. Developers only need to use Qt interfaces to initiate migration requests, package data, and restore state on the target device.

Capabilities and Modules

• Capabilities: Migrate the current application state between devices, supporting ContinueQuickStart (fast pre-warming) and source device retention/exit.
• Module: qtohosextras
  • Core Classes: QOhosAbilityContext, QOhosOnContinueContext, QOhosWantInfo
  • Utility Function: QtOhosExtras::tryGetOnContinueData
• Data Channel: Data <100KB is carried via Want parameters (Base64-encoded QByteArray, with the key __io_qt_on_continue_migration_data). Support for transferring larger data is not yet implemented in Qt and will be provided in future versions.

Workflow

1. Source device receives a migration request (continueRequestReceived) → Serializes business state → Approves/rejects the request → Decides whether to exit on the source device as needed.
2. Target device receives the Want via cold launch or newWantInfoReceived → Restores state using tryGetOnContinueData().
3. Optional: Configure ContinueQuickStart pre-warming; dynamically enable/disable migration capability; control source device retention or exit.

Core API Overview

API	Description
QOhosAbilityContext::continueRequestReceived	Signal emitted on the source device when a migration request is received
QOhosOnContinueContext	Provides approve/reject/version mismatch responses, and controls whether the source device exits
QOhosAbilityContext::newWantInfoReceived	Signal emitted on the target device when a new Want is received (warm start)
QOhosWantInfo::launchReason()	Gets the launch reason: StartAbility / PrepareContinuation / Continuation
QtOhosExtras::tryGetOnContinueData(const QOhosWant &want)	Extracts migration data (returns QSharedPointer<QByteArray>)
QOhosAbilityContext::setContinuationActive(bool)	Dynamically enables or disables the migration capability
QOhosOnContinueContext::setExitAppOnSourceDeviceAfterMigration(bool)	Controls whether the source device exits after successful migration

Source Device Implementation (Initiate Migration)

1. Listen for migration requests: Connect the continueRequestReceived signal.
2. Verify version and business conditions: Check ctx->sourceApplicationVersionCode().
3. Serialize state and respond:
   • Approve: Call setAgreeResponse(serialized) (data must be <100KB).
   • Version mismatch: Call setMismatchResponse().
   • Reject: Call setRejectResponse().
4. Retain or exit the source device: Call setExitAppOnSourceDeviceAfterMigration(false) (default is true, meaning exit).
5. Dynamic toggle: Call setContinuationActive(bool) based on business logic.

Example (Approve migration and retain source device):

auto ability = QOhosAbilityContext::getInstanceForMainWindow(window.windowHandle());
QObject::connect(ability.get(), &QOhosUiAbilityContext::continueRequestReceived,
    [](auto ctx) {
        auto appVersion = QOhosAppContext::instance()->getBundleInfo()->versionCode();
        if (ctx->sourceApplicationVersionCode() == appVersion) {
            QByteArray payload = /* serialize state (<100KB) */;
            ctx->setAgreeResponse(payload);
            ctx->setExitAppOnSourceDeviceAfterMigration(false); // Retain source device
        } else {
            ctx->setMismatchResponse();
        }
    });

Target Device Implementation (Receive and Restore)

1. Cold launch retrieval:

   auto wantInfo = QOhosAppContext::getAppLaunchWantInfo();
   

2. Runtime retrieval: Listen to the QOhosAbilityContext::newWantInfoReceived signal.
3. Scenario distinction: Check if launchReason() is Continuation.
4. Extract data: Use QtOhosExtras::tryGetOnContinueData.
5. Restore UI: Deserialize the data to restore business state.

Example (Handle cold start and warm start):

// 1. Cold start handling
if (auto launchInfo = QOhosAppContext::getAppLaunchWantInfo()) {
    auto data = QtOhosExtras::tryGetOnContinueData(launchInfo->want());
    if (data) { /* Deserialize and restore state */ }
}

// 2. Warm start handling (app running in background)
auto ability = QOhosAbilityContext::getInstanceForMainWindow(window.windowHandle());
QObject::connect(ability.get(), &QOhosUiAbilityContext::newWantInfoReceived,
    [](const QSharedPointer<QOhosWantInfo> &info) {
        if (info->launchReason() == QOhosWantInfo::LaunchReason::Continuation) {
            auto data = QtOhosExtras::tryGetOnContinueData(info->want());
            if (data) { /* Deserialize and restore state */ }
        }
    });

ContinueQuickStart

• Applicable Scenarios: When you want the target device to first launch a placeholder UI, then refresh content after data transfer completes.
• Configuration: Append _ContinueQuickStart to the continueType field of the target Ability in module.json5.
• Workflow: The system first triggers PrepareContinuation (pre-warming), then triggers Continuation (carrying data).

Example (Distinguish pre-warming from formal data):

QObject::connect(ability.get(), &QOhosUiAbilityContext::newWantInfoReceived,
    [](const QSharedPointer<QOhosWantInfo> &info) {
        switch (info->launchReason()) {
        case QOhosWantInfo::LaunchReason::PrepareContinuation:
            // Perform lightweight initialization or show a loading placeholder
            break;
        case QOhosWantInfo::LaunchReason::Continuation:
            auto data = QtOhosExtras::tryGetOnContinueData(info->want());
            if (data) { /* Restore full business state */ }
            break;
        default:
            break;
        }
    });

Notes

• Explicit Response: A migration request is rejected by default if not responded to. Be sure to handle it explicitly in the callback.
• Thread Safety: Callbacks run on the Qt main thread; avoid time-consuming synchronous operations that block the UI.
• Data Limit: Only data <100KB is currently supported. Migration may fail if this limit is exceeded.
• Forward Compatibility: It is recommended to include a version number in migration data, so the target device can handle continuation data from older source versions.

References

• Sample Code: qtohosextras/examples/qtohosextras/applicationcontinuation/main.cpp
• Source Implementation: qtohosextras/src/ohosextras/qohosabilitycontext.cpp
• External Link: HarmonyOS Official Application Continuation Guide