Qt for HarmonyOS/user development guide/how to start uiless child process

English 中文

Introduction

The HarmonyOS platform supports a multi-process architecture, and Qt provides developers with the ability to create UI-less child processes and pass startup parameters via the startNoUiChildProcess API. This guide details the usage, deployment steps of this feature, and provides complete code examples.

Functional Architecture Overview

When using Qt's child process functionality on HarmonyOS, the following architectural principles can be referenced:

Main Application Process
- Responsible for UI interaction and user interface
- Calls child process APIs via the QtOhosExtras module
- Passes startup parameters to child processes
Child Process (UI-less)
- Receives startup parameters passed from the main process
- Executes background tasks and data processing
- Runs independently without relying on the main process UI

Core Features

The child process functionality of Qt for HarmonyOS has the following characteristics:

Multi-parameter Passing Support: Applications can customize and pass multiple startup parameters, with parameter types being basic types.
Differentiated Startup Capability: Supports passing different startup parameters when launching different child processes.
UI-less Background Processing: Child processes are dedicated to background task processing and do not occupy UI resources.
Automatic Parameter Forwarding: Startup parameters are automatically forwarded to the main() function of the child process.

API Details

startNoUiChildProcess Function

This function is the core child process startup API provided by Qt for HarmonyOS:

static void QtOhosExtras::QOhosAppContext::startNoUiChildProcess(
    QString libraryName,
    QStringList args
);

Parameter Details

Parameter	Type	Description
libraryName	QString	Dynamic library name of the child process (e.g., "libChildApp.so")
args	QStringList	List of parameters to be passed to the child process

Functional Mechanism

This function is implemented based on HarmonyOS's Child Process Manager API, with the following characteristics:

Asynchronous Startup: Child process startup is an asynchronous operation and does not block the main process.
Parameter Forwarding: Passed parameters are forwarded to the main() function of the child process as command-line arguments.
Process Isolation: Child processes run independently with memory space isolated from the main process.
Lifecycle Management: Child processes need to manage their own lifecycles.

Manual Development Steps

1. Preparation

First, ensure you have:

Qt for HarmonyOS development environment
HarmonyOS application project directory
Basic understanding of multi-process architecture

2. Create Project Structure

A typical child process application needs to include both the main application and the child process parts. It is recommended to organize them according to the following structure:

YourProject/
├── MainApp/                # Main application (responsible for UI interaction)
│   ├── main.cpp
│   ├── mainwindow.cpp
│   ├── mainwindow.h
│   ├── mainwindow.ui
│   └── MainApp.pro
└── BackgroundTask/         # Child process application (background task processing)
    ├── main.cpp
    └── BackgroundTask.pro

3. Child Process Implementation Details

Basic Child Process Framework

The core task of a child process is to receive and process startup parameters passed from the main process. Below is a complete child process implementation:

BackgroundTask/main.cpp:

#include <QCoreApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);

    qDebug() << "Child process started";
    qDebug() << "Total arguments:" << argc;

    // Process passed parameters
    for (int i = 0; i < argc; ++i) {
        qDebug() << "Argument" << i << ":" << argv[i];
    }

    // Execute different business logic based on parameters
    if (argc > 1) {
        QString command = QString::fromLocal8Bit(argv[1]);
        if (command == "task1") {
            qDebug() << "Executing task 1";
            // Execute task 1 logic
        } else if (command == "task2") {
            qDebug() << "Executing task 2";
            // Execute task 2 logic
        }
    }

    return app.exec();
}

4. Main Application Implementation Details

A. Interface Header File Definition

MainApp/mainwindow.h:

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>

QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }
QT_END_NAMESPACE

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

private slots:
    void startChildProcess1();
    void startChildProcess2();

private:
    Ui::MainWindow *ui;
};

#endif // MAINWINDOW_H

B. Core Function Implementation

MainApp/mainwindow.cpp:

#include "mainwindow.h"
#include "ui_mainwindow.h"
#include <QtOhosExtras/QtOhosExtras>
#include <QStringList>

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
    , ui(new Ui::MainWindow)
{
    ui->setupUi(this);
}

MainWindow::~MainWindow()
{
    delete ui;
}

void MainWindow::startChildProcess1()
{
    // Start child process and pass parameters
    QtOhosExtras::QOhosAppContext::startNoUiChildProcess(
        "libBackgroundTask.so",
        QStringList{
            "task1",           // Task type
            "param1",          // Parameter 1
            "param2",          // Parameter 2
            "priority_high"    // Priority
        });

    ui->statusLabel->setText("Child Process 1 Started!");
}

void MainWindow::startChildProcess2()
{
    // Start another child process instance with different parameters
    QtOhosExtras::QOhosAppContext::startNoUiChildProcess(
        "libBackgroundTask.so",
        QStringList{
            "task2",           // Different task type
            "config.json",     // Configuration file
            "debug_mode"       // Debug mode
        });

    ui->statusLabel->setText("Child Process 2 Started!");
}

C. Main Application Project Configuration

MainApp/MainApp.pro:

QT += core gui widgets ohosextras

SOURCES += \
    main.cpp \
    mainwindow.cpp

HEADERS += \
    mainwindow.h

FORMS += \
    mainwindow.ui

Manual Compilation and Deployment

1. Compile Child Process Dynamic Library

# Enter child process directory
cd BackgroundTask

# Generate Makefile
qmake BackgroundTask.pro

# Compile to generate .so file
make

# Verify generated file
ls -la libBackgroundTask.so

2. Manually Deploy Dynamic Library Files

When deploying child process dynamic libraries on HarmonyOS, you need to follow a specific directory structure:

# Create target directory (if not exists)
mkdir -p entry/libs/arm64-v8a

# Copy dynamic library to specified location
cp BackgroundTask/libBackgroundTask.so entry/libs/arm64-v8a/

# Verify deployment
ls -la entry/libs/arm64-v8a/libBackgroundTask.so

3. Compile Main Application

# Compile main application
cd MainApp
qmake MainApp.pro
make

Complete Deployment Checklist

ohostemplateforqtapplication/
├── entry/
│   └── libs/
│       └── arm64-v8a/
│           ├── libBackgroundTask.so  # Child process dynamic library
│           └── ... # Other Qt-related library files
├── MainApp/
└── BackgroundTask/

Testing and Verification Methods

1. Functional Testing

Start Main Application: Run the compiled main application program.
Trigger Child Process: Click the start button on the interface.
Observe Status Feedback: Check the status prompt information on the application interface.

2. Process Status Verification

Confirm successful process creation in the following ways:

Task Manager Check

In the device's task manager, you should see:

Main Process:
```
com.yourpackage.name
```
Child Process:
```
com.yourpackage.name:QChildProcess0
```

Complete Test Case

Below is a complete test process based on the

testUiLessProcess

reference example:

Compile child process

cd testUiLessProcess/TestConsoleApp && qmake TestConsoleApp.pro && make

Deploy dynamic library

cp libTestConsoleApp.so ../ohostemplateforqtapplication/entry/libs/arm64-v8a/

Compile and run main application

cd ../mainWindowApp && qmake mainWindowApp.pro && make && ./mainWindowApp

Perform test operations
- Click the "Start Child Process" button.
- Observe the prompt "Start UI less Child Process Successfully!".
Verify results
- Check processes in the task manager.

Related Resources

Official Documentation

HarmonyOS Child Process Manager API - Underlying API Reference