1# Native Child Process Development (C/C++) 2 3>**NOTE** 4> 5> The initial APIs of this module are supported since API version 12. They depend on [IPC Kit](../ipc/ipc-capi-development-guideline.md). 6 7## When to Use 8 9This topic describes how to create a native child process in the main process and establish an IPC channel between the main process and child process. It makes multi-process programming at the native layer easier. 10 11## Available APIs 12 13| Name | Description | 14| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | 15| int [OH_Ability_CreateNativeChildProcess](../reference/apis-ability-kit/c-apis-ability-childprocess.md#oh_ability_createnativechildprocess) (const char *libName, [OH_Ability_OnNativeChildProcessStarted](../reference/apis-ability-kit/c-apis-ability-childprocess.md#oh_ability_onnativechildprocessstarted) onProcessStarted) | Creates a child process, loads a specified dynamic link library, and returns the startup result asynchronously through a callback parameter. An independent thread is used to execute the callback function. When implementing the callback function, pay attention to thread synchronization issues and avoid performing time-consuming operations to prevent extended blocking.| 16 17> **NOTE** 18> 19> Currently, only 2-in-1 devices are supported, and only one native child process can be started for a process. 20 21## How to Develop 22 23This section describes how to use the C APIs provided by Ability Kit to create a native child process and establish an IPC channel between the main process and child process based on an existing native application development project. 24 25**Dynamic Link Libraries** 26 27```txt 28libipc_capi.so 29libchild_process.so 30``` 31 32**Header Files** 33 34```c++ 35#include <IPCKit/ipc_kit.h> 36#include <AbilityKit/native_child_process.h> 37``` 38 39### 1. Child Process - Implementing Necessary Export Functions 40 41In the child process, implement and export the functions **NativeChildProcess_OnConnect** and **NativeChildProcess_MainProc**. (It is assumed that the code file is named **ChildProcessSample.cpp**.) The **OHIPCRemoteStub** object returned by **NativeChildProcess_OnConnect** is responsible for IPC of the main process. For details, see [IPC Development (C/C++)](../ipc/ipc-capi-development-guideline.md). After the child process is started, **NativeChildProcess_OnConnect** is invoked to obtain an IPC stub object, and then **NativeChildProcess_MainProc** is called to transfer the control right of the main thread. After the second function is returned, the child process exits. 42 43```c++ 44#include <IPCKit/ipc_kit.h> 45 46extern "C" { 47 48OHIPCRemoteStub* NativeChildProcess_OnConnect() 49{ 50 // ipcRemoteStub points to the IPC stub object implemented by the child process. The object is used to receive and respond to IPC messages from the main process. 51 // The child process controls its lifecycle according to the service logic. 52 return ipcRemoteStub; 53} 54 55void NativeChildProcess_MainProc() 56{ 57 // Equivalent to the Main function of the child process. It implements the service logic of the child process. 58 // ... 59 // After the function is returned, the child process exits. 60} 61 62} // extern "C" 63``` 64 65### 2. Child Process - Compiled as a Dynamic Link Library 66 67Modify the **CMakeList.txt** file, compile the file into a dynamic link library (named **libchildprocesssample.so** in this example), and add the dependency of the IPC dynamic link library. 68 69```txt 70add_library(childprocesssample SHARED 71 # Source code file that implements the necessary export functions 72 ChildProcessSample.cpp 73 74 # Other source code files 75 # ... 76) 77 78target_link_libraries(childprocesssample PUBLIC 79 # Add the dependency of the IPC dynamic link library. 80 libipc_capi.so 81 82 # Dependencies of other dynamic link libraries 83 # ... 84) 85``` 86 87### 3. Main Process - Implementing the Child Process Startup Result Callback 88 89```c++ 90#include <IPCKit/ipc_kit.h> 91 92static void OnNativeChildProcessStarted(int errCode, OHIPCRemoteProxy *remoteProxy) 93{ 94 if (errCode != NCP_NO_ERROR) { 95 // Exception handling when the child process is not started normally. 96 // ... 97 return; 98 } 99 100 // Save the remoteProxy object for IPC with the child process based on the APIs provided by IPC Kit. 101 // You are advised to transfer time-consuming operations to an independent thread to avoid blocking the callback thread for a long time. 102 // When the IPC object is no longer needed, call OH_IPCRemoteProxy_Destroy to release it. 103 // ... 104} 105``` 106 107The second parameter **OHIPCRemoteProxy** in the callback function is used to establish an IPC channel with the **OHIPCRemoteStub** object returned by the **NativeChildProcess_OnConnect** method implemented by the child process. For details, see [IPC Development (C/C++)](../ipc/ipc-capi-development-guideline.md). When the **OHIPCRemoteProxy** object is no longer needed, call [OH_IPCRemoteProxy_Destory](../reference/apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) to release it. 108 109### 4. Main Process - Starting the Native Child Process 110 111Call the API to start the native child process. Note that the return value **NCP_NO_ERROR** only indicates that the native child process startup logic is successfully called. The actual startup result is asynchronously notified through the callback function specified in the second parameter. **A child process can be created only in the main process.** 112 113```c++ 114#include <AbilityKit/native_child_process.h> 115 116// The first parameter libchildprocesssample.so is the name of the dynamic link library that implements the necessary export functions of the child process. 117int32_t ret = OH_Ability_CreateNativeChildProcess("libchildprocesssample.so", OnNativeChildProcessStarted); 118if (ret != NCP_NO_ERROR) { 119 // Exception handling when the child process is not started normally. 120 // ... 121} 122``` 123 124### 5. Main Process - Adding Build Dependencies 125 126Modify the **CMaklist.txt** file to add the dependencies. The following assumes that the main process is implemented in the library file named **libmainprocesssample.so**. (The implementation of the main process and child processes can be compiled to the same dynamic link library file.) 127 128```txt 129target_link_libraries(mainprocesssample PUBLIC 130 # Add dependencies of the IPC and ability dynamic link library. 131 libipc_capi.so 132 libchild_process.so 133 134 # Dependencies of other dynamic link libraries 135 # ... 136) 137``` 138