Jump to content

Qt for HarmonyOS/user development guide/application continuation guild

From Qt Wiki

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

Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_HarmonyOS/user_development_guide/application_continuation_guild&oldid=45545"