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 LIBABCKIT_METADATA_JS_H 17 #define LIBABCKIT_METADATA_JS_H 18 19 #ifndef __cplusplus 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 #else 24 #include <cstdbool> 25 #include <cstddef> 26 #include <cstdint> 27 #endif /* __cplusplus */ 28 29 #include "../../declarations.h" 30 #include "../../api_version.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif /* __cplusplus */ 35 36 /** 37 * @brief Struct that holds the pointers to the non-modifying API for Js-specific Abckit types. 38 */ 39 struct AbckitJsInspectApi { 40 /* ======================================== 41 * Language-independent abstractions 42 * ======================================== */ 43 44 /* ======================================== 45 * File 46 * ======================================== */ 47 48 /* ======================================== 49 * String 50 * ======================================== */ 51 52 /* ======================================== 53 * Type 54 * ======================================== */ 55 56 /* ======================================== 57 * Value 58 * ======================================== */ 59 60 /* ======================================== 61 * Literal 62 * ======================================== */ 63 64 /* ======================================== 65 * LiteralArray 66 * ======================================== */ 67 68 /* ======================================== 69 * Language-dependent abstractions 70 * ======================================== */ 71 72 /* ======================================== 73 * Module 74 * ======================================== */ 75 76 /** 77 * @brief Convert an instance of type `AbckitJsModule` to the instance of type `AbckitCoreModule`, which can be used 78 * to invoke the corresponding APIs. The original pointer can still be used after the conversion. 79 * @return Pointer to the language-independent representation of the `m`. 80 * @param [ in ] m - Module to convert. 81 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 82 */ 83 AbckitCoreModule *(*jsModuleToCoreModule)(AbckitJsModule *m); 84 85 /** 86 * @brief Convert an instance of type `AbckitCoreModule` to the instance of type `AbckitJsModule`, which can be used 87 * to invoke the corresponding APIs. The original pointer can still be used after the conversion. 88 * @return Pointer to the language-dependent representation of the `m`. 89 * @param [ in ] m - Module to convert. 90 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 91 * @note Set `ABCKIT_STATUS_WRONG_TARGET` error if `m` is does not have `ABCKIT_TARGET_JS` target. 92 */ 93 AbckitJsModule *(*coreModuleToJsModule)(AbckitCoreModule *m); 94 95 /* ======================================== 96 * ImportDescriptor 97 * ======================================== */ 98 99 /** 100 * @brief Convert an instance of type `AbckitJsImportDescriptor` to the instance of type 101 * `AbckitCoreImportDescriptor`, which can be used to invoke the corresponding APIs. The original pointer can still 102 * be used after the conversion. 103 * @return Pointer to the language-independent representation of the `id`. 104 * @param [ in ] id - Import descriptor to convert. 105 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `id` is NULL. 106 */ 107 AbckitCoreImportDescriptor *(*jsImportDescriptorToCoreImportDescriptor)(AbckitJsImportDescriptor *id); 108 109 /** 110 * @brief Convert an instance of type `AbckitCoreImportDescriptor` to the instance of type 111 * `AbckitJsImportDescriptor`, which can be used to invoke the corresponding APIs. The original pointer can still be 112 * used after the conversion. 113 * @return Pointer to the language-dependent representation of the `id`. 114 * @param [ in ] id - Import descriptor to convert. 115 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `id` is NULL. 116 * @note Set `ABCKIT_STATUS_WRONG_TARGET` error if `id` is does not have `ABCKIT_TARGET_JS` target. 117 */ 118 AbckitJsImportDescriptor *(*coreImportDescriptorToJsImportDescriptor)(AbckitCoreImportDescriptor *id); 119 120 /* ======================================== 121 * ExportDescriptor 122 * ======================================== */ 123 124 /** 125 * @brief Convert an instance of type `AbckitJsExportDescriptor` to the instance of type 126 * `AbckitCoreExportDescriptor`, which can be used to invoke the corresponding APIs. The original pointer can still 127 * be used after the conversion. 128 * @return Pointer to the language-independent representation of the `ed`. 129 * @param [ in ] ed - Export descriptor to convert. 130 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ed` is NULL. 131 */ 132 AbckitCoreExportDescriptor *(*jsExportDescriptorToCoreExportDescriptor)(AbckitJsExportDescriptor *ed); 133 134 /** 135 * @brief Convert an instance of type `AbckitCoreExportDescriptor` to the instance of type 136 * `AbckitJsExportDescriptor`, which can be used to invoke the corresponding APIs. The original pointer can still be 137 * used after the conversion. 138 * @return Pointer to the language-dependent representation of the `ed`. 139 * @param [ in ] ed - Export descriptor to convert. 140 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ed` is NULL. 141 * @note Set `ABCKIT_STATUS_WRONG_TARGET` error if `ed` is does not have `ABCKIT_TARGET_JS` target. 142 */ 143 AbckitJsExportDescriptor *(*coreExportDescriptorToJsExportDescriptor)(AbckitCoreExportDescriptor *ed); 144 145 /* ======================================== 146 * Class 147 * ======================================== */ 148 149 /** 150 * @brief Convert an instance of type `AbckitJsClass` to the instance of type `AbckitCoreClass`, which can be used 151 * to invoke the corresponding APIs. The original pointer can still be used after the conversion. 152 * @return Pointer to the language-independent representation of the `c`. 153 * @param [ in ] c - Class to convert. 154 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `c` is NULL. 155 */ 156 AbckitCoreClass *(*jsClassToCoreClass)(AbckitJsClass *c); 157 158 /** 159 * @brief Convert an instance of type `AbckitCoreClass` to the instance of type `AbckitJsClass`, which can be used 160 * to invoke the corresponding APIs. The original pointer can still be used after the conversion. 161 * @return Pointer to the language-dependent representation of the `c`. 162 * @param [ in ] c - Class to convert. 163 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `c` is NULL. 164 * @note Set `ABCKIT_STATUS_WRONG_TARGET` error if `c` is does not have `ABCKIT_TARGET_JS` target. 165 */ 166 AbckitJsClass *(*coreClassToJsClass)(AbckitCoreClass *c); 167 168 /* ======================================== 169 * Function 170 * ======================================== */ 171 172 /** 173 * @brief Convert an instance of type `AbckitJsFunction` to the instance of type `AbckitCoreFunction`, which can be 174 * used to invoke the corresponding APIs. The original pointer can still be used after the conversion. 175 * @return Pointer to the language-independent representation of the `f`. 176 * @param [ in ] f - Function to convert. 177 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `f` is NULL. 178 */ 179 AbckitCoreFunction *(*jsFunctionToCoreFunction)(AbckitJsFunction *f); 180 181 /** 182 * @brief Convert an instance of type `AbckitCoreFunction` to the instance of type `AbckitJsFunction`, which can be 183 * used to invoke the corresponding APIs. The original pointer can still be used after the conversion. 184 * @return Pointer to the language-dependent representation of the `f`. 185 * @param [ in ] f - Function to convert. 186 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `f` is NULL. 187 * @note Set `ABCKIT_STATUS_WRONG_TARGET` error if `f` is does not have `ABCKIT_TARGET_JS` target. 188 */ 189 AbckitJsFunction *(*coreFunctionToJsFunction)(AbckitCoreFunction *f); 190 191 /* ======================================== 192 * Annotation 193 * ======================================== */ 194 195 /* ======================================== 196 * AnnotationElement 197 * ======================================== */ 198 199 /* ======================================== 200 * AnnotationInterface 201 * ======================================== */ 202 203 /* ======================================== 204 * AnnotationInterfaceField 205 * ======================================== */ 206 }; 207 208 /** 209 * @brief Struct that is used to create new imports. 210 */ 211 struct AbckitJsImportFromDynamicModuleCreateParams { 212 /** 213 * @brief Import name. For namespace imports equals to "*". For default imports equals to "default". For regular 214 * imports is the same as in user code. 215 */ 216 const char *name; 217 /** 218 * @brief Alias name for the import. For namespace imports is the same as in user code. For delault import is the 219 * same as the default import name in user code. For regular imports is the same as in user code. 220 */ 221 const char *alias; 222 }; 223 224 /** 225 * @brief Struct that is used to create new exports. 226 */ 227 struct AbckitJsDynamicModuleExportCreateParams { 228 /** 229 * @brief Name of the entity that should be exported. For star exports equals to "*". For indirect exports is the 230 * same as in user code. For local exports is the same as in user code. 231 */ 232 const char *name; 233 /** 234 * @brief Alias under which entity should be exported. For star exports equals nullptr. For indirect exports is the 235 * same as in user code. For local exports is the same as in user code. 236 */ 237 const char *alias; 238 }; 239 240 /** 241 * @brief Struct that is used to create new external modules. 242 */ 243 struct AbckitJsExternalModuleCreateParams { 244 /** 245 * @brief Name of the external module. 246 */ 247 const char *name; 248 }; 249 250 /** 251 * @brief Struct that holds the pointers to the modifying API for Js-specific Abckit types. 252 */ 253 struct AbckitJsModifyApi { 254 /* ======================================== 255 * File 256 * ======================================== */ 257 258 /** 259 * @brief Creates an external Js module and adds it to the file `file`. 260 * @return Pointer to the created module. 261 * @param [ in ] file - Binary file to add the external module to. 262 * @param [ in ] params - Data that is used to create the external module. 263 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 264 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `params` is NULL. 265 * @note Allocates 266 */ 267 AbckitJsModule *(*fileAddExternalModule)(AbckitFile *file, const struct AbckitJsExternalModuleCreateParams *params); 268 269 /* ======================================== 270 * Module 271 * ======================================== */ 272 273 /** 274 * @brief Adds import from one Js module to another Js module. 275 * @return Pointer to the newly created import descriptor. 276 * @param [ in ] importing - Importing module. 277 * @param [ in ] imported - The module the `importing` module imports from. 278 * @param [ in ] params - Data that is used to create the import. 279 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `importing` is NULL. 280 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `imported` is NULL. 281 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `params` is NULL. 282 * @note Allocates 283 */ 284 AbckitJsImportDescriptor *(*moduleAddImportFromJsToJs)( 285 AbckitJsModule *importing, AbckitJsModule *imported, 286 const struct AbckitJsImportFromDynamicModuleCreateParams *params); 287 288 /** 289 * @brief Removes import `id` from module `m`. 290 * @return None. 291 * @param [ in ] m - The module to remove the import `id` from. 292 * @param [ in ] id - Import to remove from the module `m`. 293 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 294 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `id` is NULL. 295 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if module `m` does not have the import descriptor `id`. 296 */ 297 void (*moduleRemoveImport)(AbckitJsModule *m, AbckitJsImportDescriptor *id); 298 299 /** 300 * @brief Adds export to the Js module. 301 * @return Pointer to the newly created export descriptor. 302 * @param [ in ] exporting - The module to add export to. 303 * @param [ in ] exported - The module the entity is exported from. In case of local export is the same as 304 * `exporting`. 305 * @param [ in ] params - Data that is used to create the export. 306 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `exporting` is NULL. 307 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `exported` is NULL. 308 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `params` is NULL. 309 * @note Allocates 310 */ 311 AbckitJsExportDescriptor *(*moduleAddExportFromJsToJs)( 312 AbckitJsModule *exporting, AbckitJsModule *exported, 313 const struct AbckitJsDynamicModuleExportCreateParams *params); 314 315 /** 316 * @brief Removes export `ed` from module `m`. 317 * @return None. 318 * @param [ in ] m - Module to remove the export `ed` from. 319 * @param [ in ] ed - Export to remove from the module `m`. 320 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 321 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ed` is NULL. 322 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if module `m` does not have the export descriptor `ed`. 323 */ 324 void (*moduleRemoveExport)(AbckitJsModule *m, AbckitJsExportDescriptor *ed); 325 326 /* ======================================== 327 * Class 328 * ======================================== */ 329 330 /* ======================================== 331 * AnnotationInterface 332 * ======================================== */ 333 334 /* ======================================== 335 * Function 336 * ======================================== */ 337 338 /* ======================================== 339 * Annotation 340 * ======================================== */ 341 342 /* ======================================== 343 * Type 344 * ======================================== */ 345 346 /* ======================================== 347 * Value 348 * ======================================== */ 349 350 /* ======================================== 351 * String 352 * ======================================== */ 353 354 /* ======================================== 355 * LiteralArray 356 * ======================================== */ 357 358 /* ======================================== 359 * Literal 360 * ======================================== */ 361 }; 362 363 /** 364 * @brief Instantiates non-modifying API for Js-specific Abckit types. 365 * @return Instance of the `AbckitApi` struct with valid function pointers. 366 * @param [ in ] version - Version of the API to instantiate. 367 * @note Set `ABCKIT_STATUS_UNKNOWN_API_VERSION` error if `version` value is not in the `AbckitApiVersion` enum. 368 */ 369 struct AbckitJsInspectApi const *AbckitGetJsInspectApiImpl(enum AbckitApiVersion version); 370 371 /** 372 * @brief Instantiates modifying API for Js-specific Abckit types. 373 * @return Instance of the `AbckitApi` struct with valid function pointers. 374 * @param [ in ] version - Version of the API to instantiate. 375 * @note Set `ABCKIT_STATUS_UNKNOWN_API_VERSION` error if `version` value is not in the `AbckitApiVersion` enum. 376 */ 377 struct AbckitJsModifyApi const *AbckitGetJsModifyApiImpl(enum AbckitApiVersion version); 378 379 #ifdef __cplusplus 380 } 381 #endif /* __cplusplus */ 382 383 #endif /* !LIBABCKIT_METADATA_JS_H */ 384