Qt for HarmonyOS/user development guide/how to pass args to main guide

English 中文

Qt for HarmonyOS: Developer Guide for Passing Arguments to Qt main()

This document explains how to pass startup arguments to the main(int argc, char *argv[]) function of a Qt for HarmonyOS application, and how to inject arguments via Want or hdc shell aa start.

Note

hdc shell aa ... is for debugging and verification only. It is not recommended as an official product feature entry point.

1. Qt-side Argument Assembly Rules

The Qt OHOS platform plugin reads arguments from the startup configuration or the startup Want, and assembles them into the argv array passed to main().

Assembly Rules (Key Points):

• argv[0]: The path to the application shared library loaded by Qt (e.g., .../libs/arm64/lib<app>.so).
• argv[1...]: String argument list from appArgs.
  • If using fixed arguments in the project (appArgs in QAbilityStage.ets): Passed directly as argv[1...]. No placeholder is reserved for want.uri.
  • If passing arguments via Want (io.qt.appArgs / io.qt.appArgsJson): By default, want.uri is inserted as argv[1] first, even if the uri is empty.
    • You can disable this placeholder by setting want.parameters["io.qt.useUriAsArg"] = false (see examples below).

2. Method 1: Fixed Arguments in the Project

Set appArgs (a string array) in the AbilityStage startup configuration of the Qt HarmonyOS project template. Qt will pass these arguments directly to main(). This path takes precedence over Want parameters; when enabled, no want.uri placeholder is inserted.

Example (ohostemplateforqtapplication/entry/src/main/ets/qabilitystage/QAbilityStage.ets):

private static appArgs = ["val1", "val2"];

3. Method 2: Arguments via Want

For Want parameters to take effect, you must explicitly construct a Want on the ETS side and call context.startAbility(...) to launch QAbility (or launch externally using hdc shell aa start). The project template only includes the system-triggered startup flow by default. If you wish to trigger and pass arguments within the project, you must add a startAbility call in the entry Ability or page.

Example (in a scope where UIAbilityContext is available):

import Want from '@ohos.app.ability.Want';

const want: Want = {
bundleName: '<bundlename>',
abilityName: 'QAbility',
parameters: {
"io.qt.useUriAsArg": false,
"io.qt.appArgs": ["val1", "val2"]
// Alternatively "io.qt.appArgsJson": '["val1","val2"]'
}
};

this.context.startAbility(want);

Qt reads the following keys under want.parameters (effective only when no fixed arguments are set in the project):

3.1 io.qt.appArgs: Array<string> (N-API Napi::Array)

Requirement: The value must be of "array type", and all array elements must be strings. Otherwise, Qt will perform type checking and terminate the process with an exception (manifesting as a crash on startup).

Correct data format for Want.parameters in JS/TS:

{
parameters: {
"io.qt.useUriAsArg": false,
"io.qt.appArgs": ["val1", "val2"]
}
}

3.2 io.qt.appArgsJson: string (JSON array string)

Use this key when external tools can only pass string values (e.g., hdc shell aa start --ps).

Example value (note this is string content, not an array type):

["val1","val2"]

3.3 Debugging Example with hdc shell aa start

Since the value of the io.qt.appArgsJson key must be a valid JSON string (containing double quotes), pay attention to escaping rules on different operating system terminals to prevent double quotes from being stripped by the shell.

macOS / Linux (zsh or bash)

On macOS, the simplest method is to wrap the entire JSON string in single quotes '.

Recommended Command:

hdc shell aa start -a QAbility -b <bundlename> --ps io.qt.appArgsJson '["val1","val2"]'

Windows (CMD)

Windows CMD does not support single-quoted wrapping. You must use double quotes and escape internal double quotes.

Recommended Command (using backslashes):

hdc shell aa start -a QAbility -b <bundlename> --ps io.qt.appArgsJson \"[\"val1\",\"val2\"]\"

Debugging Key Points Summary

1. Argument Placeholder: When passing arguments via Want, want.uri occupies argv[1] by default. Your custom arguments usually start from argv[2].
2. Disable URI Placeholder: If you want custom arguments to start from argv[1], explicitly pass the boolean parameter io.qt.useUriAsArg:

hdc shell aa start -a QAbility -b <bundlename> --pb io.qt.useUriAsArg false --ps io.qt.appArgsJson '["val1","val2"]'

Error Diagnosis: If the application crashes with the error input is not valid JSON string, it is usually because double quotes were lost during transmission (resulting in [val1,val2]). Please recheck the escaping.

4. Example of Receiving Arguments in the Application (main.cpp)

#include <QApplication>
#include <QMainWindow>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    QMainWindow mainwindow;
    qDebug() << QString("argc=%1").arg(argc);

    for (int i = 0; i < argc; ++i) {
        qDebug() << QString("argv[%1]=%2").arg(i).arg(argv[i] ? argv[i] : "(null)");
    }

    mainwindow.show();
    return a.exec();
}