ChildProcess

概述

提供子进程的管理能力，支持创建Native子进程并在父子进程间建立IPC通道，用于实现多进程应用开发。

创建的子进程不支持UI界面，也不支持Context相关的接口调用。通过此模块和childProcessManager（非SELF_FORK模式）启动的子进程总数最大为512个。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

起始版本：12

汇总

文件

类型定义

枚举

函数

说明：

当前仅支持2in1设备。 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。

类型定义说明

OH_Ability_OnNativeChildProcessStarted

typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy)

描述

通知子进程启动结果的回调函数。

起始版本：12

参数：

参见：

OH_Ability_CreateNativeChildProcess

OH_IPCRemoteProxy_Destroy

OH_Ability_OnNativeChildProcessExit

typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal)

描述

感知Native子进程退出的回调函数。

起始版本：20

参数：

参见：

OH_Ability_RegisterNativeChildProcessExitCallback

OH_Ability_UnregisterNativeChildProcessExitCallback

NativeChildProcess_Fd

typedef struct NativeChildProcess_Fd {
    char* fdName;
    int32_t fd;
    struct NativeChildProcess_Fd* next;
} NativeChildProcess_Fd;

描述

子进程文件描述记录。

起始版本：13

参数：

NativeChildProcess_FdList

typedef struct NativeChildProcess_FdList {
    struct NativeChildProcess_Fd* head;
} NativeChildProcess_FdList;

描述

子进程文件描述记录链表。文件描述符记录个数不能超过16个。

起始版本：13

参数：

NativeChildProcess_Args

typedef struct NativeChildProcess_Args {
    char* entryParams;
    struct NativeChildProcess_FdList fdList;
} NativeChildProcess_Args;

描述

启动子进程的入参。

起始版本：13

参数：

NativeChildProcess_Options

typedef struct NativeChildProcess_Options {
    NativeChildProcess_IsolationMode isolationMode;
    int64_t reserved;
} NativeChildProcess_Options;

描述

启动子进程的配置选项。

起始版本：13

参数：

Ability_ChildProcessConfigs

描述

启动子进程的配置信息，包括子进程的进程名、以及数据沙箱与网络环境的共享模式。

起始版本：20

枚举类型说明

Ability_NativeChildProcess_ErrCode

enum Ability_NativeChildProcess_ErrCode

描述

定义Native子进程模块错误码。

起始版本：12

NativeChildProcess_IsolationMode

enum NativeChildProcess_IsolationMode

描述

定义Native子进程数据沙箱和网络环境的共享模式。

起始版本：13

函数说明

OH_Ability_CreateNativeChildProcess

int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted)

描述：

创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。

参数所指定的动态库必须实现并导出下列函数：

1. OHIPCRemoteStub* NativeChildProcess_OnConnect()
2. void NativeChildProcess_MainProc()

处理逻辑顺序如下列伪代码所示：

主进程：
1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)

子进程 ：
2. dlopen(libName)
3. dlsym("NativeChildProcess_OnConnect")
4. dlsym("NativeChildProcess_MainProc")
5. ipcRemote = NativeChildProcess_OnConnect()
6. NativeChildProcess_MainProc()

主进程 ：
7. onProcessStartedCallback(ipcRemote, errCode)

子进程 ：
8. 在NativeChildProcess_MainProc()函数返回后子进程退出。

说明：

当前仅支持2in1设备。 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。

起始版本：12

参数：

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_StartNativeChildProcess

Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(
    const char* entry, NativeChildProcess_Args args,
    NativeChildProcess_Options options, int32_t *pid)

描述：

启动Native子进程，加载参数中指定的动态链接库文件并调用入口函数。支持传参到子进程。子进程中不支持创建ArkTS基础运行时环境。

参数所指定的动态库必须实现参数为NativeChildProcess_Args入口函数并导出。详见Native子进程开发指导（C/C++）- 创建支持参数传递的子进程。

说明：

当前仅支持2in1、tablet设备。

起始版本：13

参数：

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_GetCurrentChildProcessArgs

NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs();

描述：

通过OH_Ability_StartNativeChildProcess启动子进程后，子进程能够在任意so和任意子线程中获取启动参数NativeChildProcess_Args。

说明：

当前仅支持2in1、tablet设备。

起始版本：17

返回：

执行成功返回指向NativeChildProcess_Args对象的指针，失败返回nullptr。

OH_Ability_RegisterNativeChildProcessExitCallback

Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback(
    OH_Ability_OnNativeChildProcessExit onProcessExit)

描述：

注册Native子进程异常退出回调函数，当通过OH_Ability_StartNativeChildProcess和@ohos.app.ability.childProcessManager的startNativeChildProcess启动的子进程异常退出时，调用入口参数的回调函数。当重复注册同一个回调函数时，子进程退出时只会执行一次回调函数。

参数必须实现OH_Ability_OnNativeChildProcessExit入口函数。详见注册Native子进程退出回调。

起始版本：20

参数：

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_UnregisterNativeChildProcessExitCallback

Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback(
    OH_Ability_OnNativeChildProcessExit onProcessExit)

描述：

解注册Native子进程异常退出回调函数。

参数必须实现OH_Ability_OnNativeChildProcessExit入口函数。详见解注册Native子进程退出回调。

起始版本：20

参数：

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_CreateChildProcessConfigs

Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs();

描述：

创建一个子进程配置信息对象。创建对象成功后需要通过调用OH_Ability_DestroyChildProcessConfigs来销毁对象从而避免内存泄漏。

起始版本：20

返回：

返回一个指向Ability_ChildProcessConfigs对象的指针 - 子进程配置信息对象创建成功。
返回nullptr - 发生内部错误或者内存分配失败。

OH_Ability_DestroyChildProcessConfigs

Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs);

描述

销毁一个子进程配置信息对象，并释放其内存，在调用该接口后，要避免继续使用已销毁的configs对象。

起始版本：20

参数：

返回：

NCP_NO_ERROR - 对象销毁成功。

NCP_ERR_INVALID_PARAM - 传入参数为nullptr。

错误码详见Ability_NativeChildProcess_ErrCode。

OH_Ability_ChildProcessConfigs_SetIsolationMode

Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode(
    Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode);

描述

设置子进程配置信息对象的数据沙箱与网络环境的共享模式。该设置仅当调用OH_Ability_StartNativeChildProcessWithConfigs接口时生效。

起始版本：20

参数：

返回：

NCP_NO_ERROR - 执行成功。

NCP_ERR_INVALID_PARAM - 传入参数configs为nullptr。

错误码详见Ability_NativeChildProcess_ErrCode。

OH_Ability_ChildProcessConfigs_SetProcessName

Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs, const char* processName);

描述

设置子进程配置信息对象中的进程名称。

起始版本：20

参数：

返回：

NCP_NO_ERROR - 执行成功。

NCP_ERR_INVALID_PARAM - 传入参数configs为nullptr，或者processName包含除字母、数字、下划线以外的字符。

错误码详见Ability_NativeChildProcess_ErrCode。

OH_Ability_CreateNativeChildProcessWithConfigs

 Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName,
    Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted);

描述

根据传入的子进程配置信息创建子进程，并加载参数中指定的动态链接库文件。子进程的启动结果通过回调参数异步通知调用方。该回调在独立线程中执行，需要确保线程同步，且不能执行高耗时操作避免长时间阻塞。

参数所指定的动态库必须实现并导出下列函数：

1. OHIPCRemoteStub* NativeChildProcess_OnConnect()
2. void NativeChildProcess_MainProc()

处理逻辑顺序如下列伪代码所示：

主进程：
1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback)

子进程 ：
2. dlopen(libName)
3. dlsym("NativeChildProcess_OnConnect")
4. dlsym("NativeChildProcess_MainProc")
5. ipcRemote = NativeChildProcess_OnConnect()
6. NativeChildProcess_MainProc()

主进程 ：
7. onProcessStartedCallback(ipcRemote, errCode)

子进程 ：
8. 在NativeChildProcess_MainProc()函数返回后子进程退出。

说明：

当前仅支持2in1、tablet设备。

起始版本：20

参数：

返回：

NCP_NO_ERROR - 执行成功。

NCP_ERR_INVALID_PARAM - 传入参数无效。

NCP_ERR_NOT_SUPPORTED - 当前设备不支持创建Native子进程。

NCP_ERR_MULTI_PROCESS_DISABLED - 当前设备已关闭多进程模式，不允许启动子进程。

NCP_ERR_ALREADY_IN_CHILD - 不允许在子进程中再次创建子进程。

NCP_ERR_MAX_CHILD_PROCESSES_REACHED - 超过最大Native子进程数量限制。

错误码详见Ability_NativeChildProcess_ErrCode。

OH_Ability_StartNativeChildProcessWithConfigs

 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs(
    const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid);

描述：

根据参数中子进程配置信息启动Native子进程，加载参数中指定的动态链接库文件并调用入口函数。支持传参到子进程。

参数所指定的动态库必须实现参数为NativeChildProcess_Args的入口函数并导出，详见Native子进程开发指导（C/C++）- 创建支持参数传递的子进程。示例如下：

1. void Main(NativeChildProcess_Args args);

处理逻辑顺序如下列伪代码所示：

主进程：
1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid)

子进程：
2. dlopen(libName)
3. dlsym("Main")
4. Main(args)
5. 子进程在函数Main(args)返回后退出

说明：

当前仅支持2in1、tablet设备。

起始版本：20

参数：

返回：

NCP_NO_ERROR - 执行成功。

NCP_ERR_INVALID_PARAM - 传入参数无效。

NCP_ERR_NOT_SUPPORTED - 当前设备不支持创建Native子进程。

NCP_ERR_ALREADY_IN_CHILD - 不允许在子进程中再次创建子进程。

NCP_ERR_MAX_CHILD_PROCESSES_REACHED - 超过最大Native子进程数量限制。

错误码详见Ability_NativeChildProcess_ErrCode。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h