1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup ChildProcess 18 * @{ 19 * 20 * @brief Provides the APIs to manage child processes. 21 * 22 * @syscap SystemCapability.Ability.AbilityRuntime.Core 23 * @since 12 24 */ 25 26 /** 27 * @file native_child_process.h 28 * 29 * @brief Declares the APIs used to create a native child process and establish an IPC channel between the parent and 30 * child processes. 31 * 32 * @kit AbilityKit 33 * @library libchild_process.so 34 * @syscap SystemCapability.Ability.AbilityRuntime.Core 35 * @since 12 36 */ 37 38 #ifndef OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 39 #define OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 40 41 #include "IPCKit/ipc_cparcel.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Enumerates the error codes used by the native child process module. 49 * @since 12 50 */ 51 typedef enum Ability_NativeChildProcess_ErrCode { 52 /** 53 * @error Operation successful. 54 */ 55 NCP_NO_ERROR = 0, 56 57 /** 58 * @error Invalid parameter. 59 */ 60 NCP_ERR_INVALID_PARAM = 401, 61 62 /** 63 * @error Creating a native child process is not supported. 64 */ 65 NCP_ERR_NOT_SUPPORTED = 801, 66 67 /** 68 * @error Internal error. 69 */ 70 NCP_ERR_INTERNAL = 16000050, 71 72 /** 73 * @error A new child process cannot be created during the startup of another native child process. 74 * You can try again after the child process is started. 75 */ 76 NCP_ERR_BUSY = 16010001, 77 78 /** 79 * @error Starting the native child process times out. 80 */ 81 NCP_ERR_TIMEOUT = 16010002, 82 83 /** 84 * @error Server error. 85 */ 86 NCP_ERR_SERVICE_ERROR = 16010003, 87 88 /** 89 * @error The multi-process mode is disabled. A child process cannot be started. 90 */ 91 NCP_ERR_MULTI_PROCESS_DISABLED = 16010004, 92 93 /** 94 * @error A process cannot be created in a child process. 95 */ 96 NCP_ERR_ALREADY_IN_CHILD = 16010005, 97 98 /** 99 * @error The number of native child processes reaches the maximum. 100 */ 101 NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006, 102 103 /** 104 * @error The child process fails to load the dynamic library because the file does not exist 105 * or the corresponding method is not implemented or exported. 106 */ 107 NCP_ERR_LIB_LOADING_FAILED = 16010007, 108 109 /** 110 * @error The child process fails to call the OnConnect method of the dynamic library. 111 * An invalid IPC object pointer may be returned. 112 */ 113 NCP_ERR_CONNECTION_FAILED = 16010008, 114 115 /** 116 * @error The callback does not exist; it may not have been registered or has already been unregistered. 117 * @since 20 118 */ 119 NCP_ERR_CALLBACK_NOT_EXIST = 16010009, 120 } Ability_NativeChildProcess_ErrCode; 121 122 /** 123 * @brief Enumerates the isolation modes used by the native child process module. 124 * @since 13 125 */ 126 typedef enum NativeChildProcess_IsolationMode { 127 /** 128 * Normal isolation mode, parent process shares the same sandbox or internet with the child process. 129 */ 130 NCP_ISOLATION_MODE_NORMAL = 0, 131 132 /** 133 * Isolated mode, parent process does not share the same sandbox or internet with the child process. 134 */ 135 NCP_ISOLATION_MODE_ISOLATED = 1, 136 } NativeChildProcess_IsolationMode; 137 138 /** 139 * @brief Defines a struct for the child process configs. 140 * @since 20 141 */ 142 typedef struct Ability_ChildProcessConfigs Ability_ChildProcessConfigs; 143 144 /** 145 * @brief Creates a new child process configs object. 146 * The caller is responsible for destroying the returned object by calling 147 * {@link OH_Ability_DestroyChildProcessConfigs} to avoid memory leaks. 148 * @return Returns a pointer to the newly created {@link Ability_ChildProcessConfigs} object if successful. 149 * Returns nullptr if an internal error occurs or memory allocation fails. 150 * @since 20 151 */ 152 Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs(); 153 154 /** 155 * @brief Destroys a child process configs object and releases associated resources. 156 * 157 * @param configs Pointer to the child process configs object to be destroyed. 158 * After this call, the pointer becomes invalid and must not be used. 159 * Passing nullptr is allowed and will be ignored. 160 * @return Returns {@link NCP_NO_ERROR} if the operation is successful or if the input is nullptr. 161 * Returns {@link NCP_ERR_INVALID_PARAM} if the input parameters are invalid. 162 * @since 20 163 */ 164 Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs); 165 166 /** 167 * @brief Sets the isolation mode for the specified child process configs. 168 * The isolationMode only takes effect in {@link OH_Ability_StartNativeChildProcessWithConfigs}. 169 * 170 * @param configs Pointer to the child process configs object. Must not be nullptr. 171 * @param isolationMode The isolation mode to set. See {@link NativeChildProcess_IsolationMode} for details. 172 * @return Returns {@link NCP_NO_ERROR} if the isolation mode is set successfully. 173 * Returns {@link NCP_ERR_INVALID_PARAM} if the input parameters are invalid. 174 * @since 20 175 */ 176 Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode( 177 Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode); 178 179 /** 180 * @brief Sets the process name for the specified child process configs. 181 * 182 * @param configs Pointer to the child process configs object. Must not be nullptr. 183 * @param processName The process name to set. 184 * Must be a non-empty string containing only letters, digits, or underscores. 185 * Maximum length is 64 characters. 186 * The name ultimately assigned to the process is {bundleName}:{processName}. 187 * @return Returns {@link NCP_NO_ERROR} if the process name is set successfully. 188 * Returns {@link NCP_ERR_INVALID_PARAM} if the input parameters are invalid. 189 * @since 20 190 */ 191 Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs, 192 const char* processName); 193 194 /** 195 * @brief Defines a callback function for notifying the child process startup result. 196 * 197 * @param errCode Error code corresponding to the callback function. The following values are available: 198 * {@link NCP_NO_ERROR} if the child process is created successfully.\n 199 * {@link NCP_ERR_LIB_LOADING_FAILED} if loading the dynamic library file fails or the necessary export function 200 * is not implemented in the dynamic library.\n 201 * {@link NCP_ERR_CONNECTION_FAILED} if the OnConnect method implemented in the dynamic library does not return 202 * a valid IPC stub pointer.\n 203 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 204 * @param remoteProxy Pointer to the IPC object of the child process. If an exception occurs, the value may be nullptr. 205 * The object must be released by calling {@link OH_IPCRemoteProxy_Destory} when it is no longer needed. 206 * @see OH_Ability_CreateNativeChildProcess 207 * @see OH_IPCRemoteProxy_Destory 208 * @since 12 209 */ 210 typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy); 211 212 /** 213 * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result 214 * asynchronously through a callback parameter. 215 * The callback notification is an independent thread. When implementing the callback function, 216 * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. 217 * 218 * The dynamic library specified must implement and export the following functions:\n 219 * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect()\n 220 * 2. void NativeChildProcess_MainProc()\n 221 * 222 * The processing logic sequence is shown in the following pseudocode: \n 223 * Main process: \n 224 * 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)\n 225 * Child process: \n 226 * 2. dlopen(libName)\n 227 * 3. dlsym("NativeChildProcess_OnConnect")\n 228 * 4. dlsym("NativeChildProcess_MainProc")\n 229 * 5. ipcRemote = NativeChildProcess_OnConnect()\n 230 * 6. NativeChildProcess_MainProc()\n 231 * Main process: \n 232 * 7. onProcessStartedCallback(ipcRemote, errCode)\n 233 * Child process: \n 234 * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. \n 235 * 236 * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. 237 * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. 238 * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. 239 * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the 240 * callback function.\n 241 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n 242 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n 243 * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device.\n 244 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n 245 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n 246 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 247 * @see OH_Ability_OnNativeChildProcessStarted 248 * @since 12 249 */ 250 int OH_Ability_CreateNativeChildProcess(const char* libName, 251 OH_Ability_OnNativeChildProcessStarted onProcessStarted); 252 253 /** 254 * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result 255 * asynchronously through a callback parameter. 256 * The callback notification is an independent thread. When implementing the callback function, 257 * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. 258 * 259 * The dynamic library specified must implement and export the following functions: 260 * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 261 * 2. void NativeChildProcess_MainProc() 262 * 263 * The processing logic sequence is shown in the following pseudocode: 264 * Main process: 265 * 1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback) 266 * Child process: 267 * 2. dlopen(libName) 268 * 3. dlsym("NativeChildProcess_OnConnect") 269 * 4. dlsym("NativeChildProcess_MainProc") 270 * 5. ipcRemote = NativeChildProcess_OnConnect() 271 * 6. NativeChildProcess_MainProc() 272 * Main process: 273 * 7. onProcessStartedCallback(ipcRemote, errCode) 274 * Child process: 275 * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. 276 * 277 * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. 278 * @param configs Pointer to the child process configs object. The value cannot be nullptr. 279 * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. 280 * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. 281 * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the 282 * callback function. 283 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. 284 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. 285 * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device. 286 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. 287 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. 288 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 289 * @see OH_Ability_OnNativeChildProcessStarted 290 * @since 20 291 */ 292 Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName, 293 Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted); 294 295 /** 296 * @brief The info of the file descriptors passed to child process. 297 * @since 13 298 */ 299 typedef struct NativeChildProcess_Fd { 300 /** the key of the file descriptor. */ 301 char* fdName; 302 303 /** the value of the file descriptor. */ 304 int32_t fd; 305 306 /** the next pointer of the linked list. */ 307 struct NativeChildProcess_Fd* next; 308 } NativeChildProcess_Fd; 309 310 /** 311 * @brief The list of the info of the file descriptors passed to child process. 312 * @since 13 313 */ 314 typedef struct NativeChildProcess_FdList { 315 /** the head of the list. 316 * For details, see {@link NativeChildProcess_Fd}. 317 */ 318 struct NativeChildProcess_Fd* head; 319 } NativeChildProcess_FdList; 320 321 /** 322 * @brief The options used by the child process. 323 * @since 13 324 */ 325 typedef struct NativeChildProcess_Options { 326 /** the isolation mode used by the child process. 327 * For details, see {@link NativeChildProcess_IsolationMode}. 328 */ 329 NativeChildProcess_IsolationMode isolationMode; 330 331 /** reserved field for future extension purposes */ 332 int64_t reserved; 333 } NativeChildProcess_Options; 334 335 /** 336 * @brief The arguments passed to the child process. 337 * @since 13 338 */ 339 typedef struct NativeChildProcess_Args { 340 /** the entry parameter. */ 341 char* entryParams; 342 343 /** the list of the info of the file descriptors passed to child process. 344 * For details, see {@link NativeChildProcess_FdList}. 345 */ 346 struct NativeChildProcess_FdList fdList; 347 } NativeChildProcess_Args; 348 349 /** 350 * @brief Starts a child process, loads the specified dynamic library file. 351 * 352 * The dynamic library specified must implement a function with NativeChildProcess_Args as a 353 * pamameter(function name can be customized), and export the function, such as:\n 354 * 1. void Main(NativeChildProcess_Args args); 355 * 356 * The processing logic sequence is shown in the following pseudocode: \n 357 * Main process: \n 358 * 1. OH_Ability_StartNativeChildProcess(entryPoint, args, options)\n 359 * Child process: \n 360 * 2. dlopen(libName)\n 361 * 3. dlsym("Main")\n 362 * 4. Main(args)\n 363 * 5. The child process exits after the Main(args) function is returned \n 364 * 365 * @param entry Dynamic library and entry function loaded in child process, such as "libEntry.so:Main". 366 * The value cannot be nullptr. 367 * @param args The arguments passed to the child process. 368 * For details, see {@link NativeChildProcess_Args}. 369 * @param options The child process options. 370 * For details, see {@link NativeChildProcess_Options}. 371 * @param pid The started child process id. 372 * @return Returns {@link NCP_NO_ERROR} if the call is successful.\n 373 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n 374 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n 375 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n 376 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n 377 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 378 * @see OH_Ability_OnNativeChildProcessStarted 379 * @since 13 380 */ 381 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( 382 const char* entry, NativeChildProcess_Args args, 383 NativeChildProcess_Options options, int32_t *pid); 384 385 /** 386 * @brief Starts a child process, loads the specified dynamic library file. 387 * 388 * The dynamic library specified must implement a function with NativeChildProcess_Args as a 389 * pamameter(function name can be customized), and export the function, such as: 390 * 1. void Main(NativeChildProcess_Args args); 391 * 392 * The processing logic sequence is shown in the following pseudocode: 393 * Main process: 394 * 1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid) 395 * Child process: 396 * 2. dlopen(libName) 397 * 3. dlsym("Main") 398 * 4. Main(args) 399 * 5. The child process exits after the Main(args) function is returned 400 * 401 * @param entry Dynamic library and entry function loaded in child process, such as "libEntry.so:Main". 402 * The value cannot be nullptr. 403 * @param args The arguments passed to the child process. 404 * For details, see {@link NativeChildProcess_Args}. 405 * @param configs Pointer to the child process configs object. The value cannot be null. 406 * For details, see {@link Ability_ChildProcessConfigs}. 407 * @param pid The started child process id. 408 * @return Returns {@link NCP_NO_ERROR} if the call is successful. 409 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. 410 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. 411 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. 412 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. 413 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 414 * @since 20 415 */ 416 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs( 417 const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid); 418 419 /** 420 * @brief Child process get self NativeChildProcess_Args. 421 * 422 * @return Returns a pointer to the arguments passed to current child process.\n 423 * For details, see {@link NativeChildProcess_Args}. 424 * @since 17 425 */ 426 NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs(); 427 428 /** 429 * @brief Defines a callback function to handle the exit of a native child process. 430 * 431 * @param pid The pid of the exited native child process. 432 * @param signal The signal of the exited native child process. 433 * @since 20 434 */ 435 typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal); 436 437 /** 438 * @brief Register a native child process exit callback. 439 * Registering the same callback repeatedly will only keep one. 440 * 441 * @param onProcessExit Pointer to the callback function to handle the exit of a native child process. 442 * For details, see {@link OH_Ability_OnNativeChildProcessExit}. 443 * @return Returns {@link NCP_NO_ERROR} if the call is successful. 444 * Returns {@link NCP_ERR_INTERNAL} if internal error occurs. 445 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 446 * @since 20 447 */ 448 Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback( 449 OH_Ability_OnNativeChildProcessExit onProcessExit); 450 451 /** 452 * @brief Unregister a native child process exit callback. 453 * 454 * @param onProcessExit Pointer to the callback function to handle the exit of a native child process. 455 * For details, see {@link OH_Ability_OnNativeChildProcessExit}. 456 * @return Returns {@link NCP_NO_ERROR} if the call is successful. 457 * Returns {@link NCP_ERR_INTERNAL} if internal error occurs. 458 * Returns {@link NCP_ERR_CALLBACK_NOT_EXIST} if the callback is not exist. 459 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 460 * @since 20 461 */ 462 Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback( 463 OH_Ability_OnNativeChildProcessExit onProcessExit); 464 465 #ifdef __cplusplus 466 } // extern "C" 467 #endif 468 469 /** @} */ 470 #endif // OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 471