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 #ifndef OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 17 #define OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 18 19 #include "ipc_cparcel.h" 20 21 /** 22 * @addtogroup ChildProcess 23 * @{ 24 * 25 * @brief Provides the APIs to manage child processes. 26 * 27 * @syscap SystemCapability.Ability.AbilityRuntime.Core 28 * @since 12 29 */ 30 31 /** 32 * @file native_child_process.h 33 * 34 * @brief Declares the APIs used to create a native child process and establish an IPC channel between the parent and 35 * child processes. 36 * 37 * @kit AbilityKit 38 * @library libchild_process.so 39 * @syscap SystemCapability.Ability.AbilityRuntime.Core 40 * @since 12 41 */ 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 */ 118 NCP_ERR_CALLBACK_NOT_EXIST = 16010009, 119 } Ability_NativeChildProcess_ErrCode; 120 121 /** 122 * @brief Enumerates the isolation modes used by the native child process module. 123 * @since 13 124 */ 125 typedef enum NativeChildProcess_IsolationMode { 126 /** 127 * Normal isolation mode, parent process shares the same sandbox or internet with the child process. 128 */ 129 NCP_ISOLATION_MODE_NORMAL = 0, 130 131 /** 132 * Isolated mode, parent process does not share the same sandbox or internet with the child process. 133 */ 134 NCP_ISOLATION_MODE_ISOLATED = 1, 135 } NativeChildProcess_IsolationMode; 136 137 /** 138 * @brief Defines a struct for the child process configs. 139 * @since 20 140 */ 141 typedef struct Ability_ChildProcessConfigs Ability_ChildProcessConfigs; 142 143 /** 144 * @brief Creates a new child process configs object. 145 * The caller is responsible for destroying the returned object by calling 146 * {@link OH_Ability_DestroyChildProcessConfigs} to avoid memory leaks. 147 * @return Returns a pointer to the newly created {@link Ability_ChildProcessConfigs} object if successful. 148 * Returns nullptr if an internal error occurs or memory allocation fails. 149 * @since 20 150 */ 151 Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs(); 152 153 /** 154 * @brief Destroys a child process configs object and releases associated rescources. 155 * 156 * @param configs Pointer to the child process configs object to be destroyed. 157 * After this call, the pointer becomes invalid and must not be used. 158 * Passing nullptr is allowed and will be ignored. 159 * @return Returns {@link NCP_NO_ERROR} if the operation is successful or if the input is nullptr. 160 * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. 161 * @since 20 162 */ 163 Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs); 164 165 /** 166 * @brief Sets the isolation mode for the specified child process configs. 167 * The isolationMode only takes effect in {@link OH_Ability_StartNativeChildProcessWithConfigs}. 168 * 169 * @param configs Pointer to the child process configs object. Must not be nullptr. 170 * @param isolationMode The isolation mode to set. See {@link NativeChildProcess_IsolationMode} for details. 171 * @return Returns {@link NCP_NO_ERROR} if the isolation mode is set successful. 172 * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. 173 * @since 20 174 */ 175 Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode( 176 Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode); 177 178 /** 179 * @brief Sets the process name for the specified child process configs. 180 * 181 * @param configs Pointer to the child process configs object. Must not be nullptr. 182 * @param processName The process name to set. 183 * Must be a non-empty string containing only letters, digits, or underscores. 184 * Maximum length is 64 characters. 185 * The name ultimately assigned to the process is {bundleName}:{processName}. 186 * @return Returns {@link NCP_NO_ERROR} if the process name is set successful. 187 * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. 188 * @since 20 189 */ 190 Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs, 191 const char* processName); 192 193 /** 194 * @brief Defines a callback function for notifying the child process startup result. 195 * 196 * @param errCode Error code corresponding to the callback function. The following values are available: 197 * {@link NCP_NO_ERROR} if the child process is created successfully.\n 198 * {@link NCP_ERR_LIB_LOADING_FAILED} if loading the dynamic library file fails or the necessary export function 199 * is not implemented in the dynamic library.\n 200 * {@link NCP_ERR_CONNECTION_FAILED} if the OnConnect method implemented in the dynamic library does not return 201 * a valid IPC stub pointer.\n 202 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 203 * @param remoteProxy Pointer to the IPC object of the child process. If an exception occurs, the value may be nullptr. 204 * The object must be released by calling {@link OH_IPCRemoteProxy_Destory} when it is no longer needed. 205 * @see OH_Ability_CreateNativeChildProcess 206 * @see OH_IPCRemoteProxy_Destory 207 * @since 12 208 */ 209 typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy); 210 211 /** 212 * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result 213 * asynchronously through a callback parameter. 214 * The callback notification is an independent thread. When implementing the callback function, 215 * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. 216 * 217 * The dynamic library specified must implement and export the following functions:\n 218 * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect()\n 219 * 2. void NativeChildProcess_MainProc()\n 220 * 221 * The processing logic sequence is shown in the following pseudocode: \n 222 * Main process: \n 223 * 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)\n 224 * Child process: \n 225 * 2. dlopen(libName)\n 226 * 3. dlsym("NativeChildProcess_OnConnect")\n 227 * 4. dlsym("NativeChildProcess_MainProc")\n 228 * 5. ipcRemote = NativeChildProcess_OnConnect()\n 229 * 6. NativeChildProcess_MainProc()\n 230 * Main process: \n 231 * 7. onProcessStartedCallback(ipcRemote, errCode)\n 232 * Child process: \n 233 * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. \n 234 * 235 * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. 236 * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. 237 * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. 238 * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the 239 * callback function.\n 240 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n 241 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n 242 * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device.\n 243 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n 244 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n 245 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 246 * @see OH_Ability_OnNativeChildProcessStarted 247 * @since 12 248 */ 249 int OH_Ability_CreateNativeChildProcess(const char* libName, 250 OH_Ability_OnNativeChildProcessStarted onProcessStarted); 251 252 /** 253 * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result 254 * asynchronously through a callback parameter. 255 * The callback notification is an independent thread. When implementing the callback function, 256 * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. 257 * 258 * The dynamic library specified must implement and export the following functions: 259 * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 260 * 2. void NativeChildProcess_MainProc() 261 * 262 * The processing logic sequence is shown in the following pseudocode: 263 * Main process: 264 * 1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback) 265 * Child process: 266 * 2. dlopen(libName) 267 * 3. dlsym("NativeChildProcess_OnConnect") 268 * 4. dlsym("NativeChildProcess_MainProc") 269 * 5. ipcRemote = NativeChildProcess_OnConnect() 270 * 6. NativeChildProcess_MainProc() 271 * Main process: 272 * 7. onProcessStartedCallback(ipcRemote, errCode) 273 * Child process: 274 * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. 275 * 276 * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. 277 * @param configs Pointer to the child process configs object. The value cannot be nullptr. 278 * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. 279 * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. 280 * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the 281 * callback function. 282 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. 283 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. 284 * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device. 285 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. 286 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. 287 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 288 * @see OH_Ability_OnNativeChildProcessStarted 289 * @since 20 290 */ 291 Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName, 292 Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted); 293 294 /** 295 * @brief The info of the file descriptors passed to child process. 296 * @since 13 297 */ 298 typedef struct NativeChildProcess_Fd { 299 /** the key of the file descriptor. */ 300 char* fdName; 301 302 /** the value of the file descriptor. */ 303 int32_t fd; 304 305 /** the next pointer of the linked list. */ 306 struct NativeChildProcess_Fd* next; 307 } NativeChildProcess_Fd; 308 309 /** 310 * @brief The list of the info of the file descriptors passed to child process. 311 * @since 13 312 */ 313 typedef struct NativeChildProcess_FdList { 314 /** the head of the list. 315 * For details, see {@link NativeChildProcess_Fd}. 316 */ 317 struct NativeChildProcess_Fd* head; 318 } NativeChildProcess_FdList; 319 320 /** 321 * @brief The options used by the child process. 322 * @since 13 323 */ 324 typedef struct NativeChildProcess_Options { 325 /** the isolation mode used by the child process. 326 * For details, see {@link NativeChildProcess_IsolationMode}. 327 */ 328 NativeChildProcess_IsolationMode isolationMode; 329 330 /** reserved field for future extension purposes */ 331 int64_t reserved; 332 } NativeChildProcess_Options; 333 334 /** 335 * @brief The arguments passed to the child process. 336 * @since 13 337 */ 338 typedef struct NativeChildProcess_Args { 339 /** the entry parameter. */ 340 char* entryParams; 341 342 /** the list of the info of the file descriptors passed to child process. 343 * For details, see {@link NativeChildProcess_FdList}. 344 */ 345 struct NativeChildProcess_FdList fdList; 346 } NativeChildProcess_Args; 347 348 /** 349 * @brief Starts a child process, loads the specified dynamic library file. 350 * 351 * The dynamic library specified must implement a function with NativeChildProcess_Args as a 352 * pamameter(function name can be customized), and export the function, such as:\n 353 * 1. void Main(NativeChildProcess_Args args); 354 * 355 * The processing logic sequence is shown in the following pseudocode: \n 356 * Main process: \n 357 * 1. OH_Ability_StartNativeChildProcess(entryPoint, args, options)\n 358 * Child process: \n 359 * 2. dlopen(libName)\n 360 * 3. dlsym("Main")\n 361 * 4. Main(args)\n 362 * 5. The child process exits after the Main(args) function is returned \n 363 * 364 * @param entry Dynamic library and entry function loaded in child process, such as "libEntry.so:Main". 365 * The value cannot be nullptr. 366 * @param args The arguments passed to the child process. 367 * For details, see {@link NativeChildProcess_Args}. 368 * @param options The child process options. 369 * For details, see {@link NativeChildProcess_Options}. 370 * @param pid The started child process id. 371 * @return Returns {@link NCP_NO_ERROR} if the call is successful.\n 372 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n 373 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n 374 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n 375 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n 376 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 377 * @see OH_Ability_OnNativeChildProcessStarted 378 * @since 13 379 */ 380 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( 381 const char* entry, NativeChildProcess_Args args, 382 NativeChildProcess_Options options, int32_t *pid); 383 384 /** 385 * @brief Starts a child process, loads the specified dynamic library file. 386 * 387 * The dynamic library specified must implement a function with NativeChildProcess_Args as a 388 * pamameter(function name can be customized), and export the function, such as: 389 * 1. void Main(NativeChildProcess_Args args); 390 * 391 * The processing logic sequence is shown in the following pseudocode: 392 * Main process: 393 * 1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid) 394 * Child process: 395 * 2. dlopen(libName) 396 * 3. dlsym("Main") 397 * 4. Main(args) 398 * 5. The child process exits after the Main(args) function is returned 399 * 400 * @param entry Dynamic library and entry function loaded in child process, such as "libEntry.so:Main". 401 * The value cannot be nullptr. 402 * @param args The arguments passed to the child process. 403 * For details, see {@link NativeChildProcess_Args}. 404 * @param configs Pointer to the child process configs object. The value cannot be null. 405 * For details, see {@link Ability_ChildProcessConfigs}. 406 * @param pid The started child process id. 407 * @return Returns {@link NCP_NO_ERROR} if the call is successful. 408 * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. 409 * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. 410 * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. 411 * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. 412 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 413 * @since 20 414 */ 415 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs( 416 const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid); 417 418 /** 419 * @brief Child process get self NativeChildProcess_Args. 420 * 421 * @return Returns a pointer to the arguments passed to current child process.\n 422 * For details, see {@link NativeChildProcess_Args}. 423 * @since 17 424 */ 425 NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs(); 426 427 /** 428 * @brief Define a callback function to handle the exit of a native child process. 429 * 430 * @param pid The pid of the exited native child process. 431 * @param signal The signal of the exited native child process. 432 * @since 20 433 */ 434 typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal); 435 436 /** 437 * @brief Register a native child process exit callback. 438 * Registering the same callback repeatedly will only keep one. 439 * 440 * @param onProcessExit Pointer to the callback function to handle the exit of a native child process. 441 * For details, see {@link OH_Ability_OnNativeChildProcessExit}. 442 * @return Returns {@link NCP_NO_ERROR} if the call is successful. 443 * Returns {@link NCP_ERR_INVALID_PARAM} if the param is invalid. 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_INVALID_PARAM} if the param is invalid. 458 * Returns {@link NCP_ERR_INTERNAL} if internal error occurs. 459 * Returns {@link NCP_ERR_CALLBACK_NOT_EXIST} if the callback is not exist. 460 * For details, see {@link Ability_NativeChildProcess_ErrCode}. 461 * @since 20 462 */ 463 Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback( 464 OH_Ability_OnNativeChildProcessExit onProcessExit); 465 466 #ifdef __cplusplus 467 } // extern "C" 468 #endif 469 470 /** @} */ 471 #endif // OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H 472