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_H 17 #define LIBABCKIT_METADATA_H 18 19 #ifndef __cplusplus 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 #else 24 #include <cstddef> 25 #include <cstdint> 26 #endif /* __cplusplus */ 27 28 #include "./declarations.h" 29 #include "./api_version.h" 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif /* __cplusplus */ 34 35 /* 36 * This enum is a part of the public API, returned by `ModuleGetTarget`. 37 */ 38 enum AbckitTarget { 39 /* 40 * For cases when user does not have needed language extension. 41 */ 42 ABCKIT_TARGET_UNKNOWN, 43 /* 44 * For `.abc` files obtained from mainline pipeline from `.ets` files. 45 */ 46 ABCKIT_TARGET_ARK_TS_V1, 47 /* 48 * Reserved for future versions. 49 */ 50 ABCKIT_TARGET_ARK_TS_V2, 51 /* 52 * Reserved for future versions. 53 */ 54 ABCKIT_TARGET_TS, 55 /* 56 * For `.abc` files obtained from `.js` files. 57 */ 58 ABCKIT_TARGET_JS, 59 /* 60 * Reserved for future versions. 61 */ 62 ABCKIT_TARGET_NATIVE, 63 /* 64 * NOTE: Extend for other module types. 65 */ 66 }; 67 68 enum AbckitTypeId { 69 ABCKIT_TYPE_ID_INVALID, 70 ABCKIT_TYPE_ID_VOID, 71 ABCKIT_TYPE_ID_U1, 72 ABCKIT_TYPE_ID_I8, 73 ABCKIT_TYPE_ID_U8, 74 ABCKIT_TYPE_ID_I16, 75 ABCKIT_TYPE_ID_U16, 76 ABCKIT_TYPE_ID_I32, 77 ABCKIT_TYPE_ID_U32, 78 ABCKIT_TYPE_ID_F32, 79 ABCKIT_TYPE_ID_F64, 80 ABCKIT_TYPE_ID_I64, 81 ABCKIT_TYPE_ID_U64, 82 ABCKIT_TYPE_ID_STRING, 83 ABCKIT_TYPE_ID_ANY, 84 ABCKIT_TYPE_ID_REFERENCE, 85 ABCKIT_TYPE_ID_LITERALARRAY 86 }; 87 88 /* NOTE: (knazarov) may need to prune this enum in order to only expose user-friendly literal types */ 89 enum AbckitLiteralTag { 90 /* common */ 91 ABCKIT_LITERAL_TAG_INVALID, 92 ABCKIT_LITERAL_TAG_TAGVALUE, 93 ABCKIT_LITERAL_TAG_BOOL, 94 ABCKIT_LITERAL_TAG_BYTE, 95 ABCKIT_LITERAL_TAG_SHORT, 96 ABCKIT_LITERAL_TAG_INTEGER, 97 ABCKIT_LITERAL_TAG_LONG, 98 ABCKIT_LITERAL_TAG_FLOAT, 99 ABCKIT_LITERAL_TAG_DOUBLE, 100 ABCKIT_LITERAL_TAG_STRING, 101 ABCKIT_LITERAL_TAG_METHOD, 102 ABCKIT_LITERAL_TAG_GENERATORMETHOD, 103 ABCKIT_LITERAL_TAG_ACCESSOR, 104 ABCKIT_LITERAL_TAG_METHODAFFILIATE, 105 ABCKIT_LITERAL_TAG_ARRAY_U1, 106 ABCKIT_LITERAL_TAG_ARRAY_U8, 107 ABCKIT_LITERAL_TAG_ARRAY_I8, 108 ABCKIT_LITERAL_TAG_ARRAY_U16, 109 ABCKIT_LITERAL_TAG_ARRAY_I16, 110 ABCKIT_LITERAL_TAG_ARRAY_U32, 111 ABCKIT_LITERAL_TAG_ARRAY_I32, 112 ABCKIT_LITERAL_TAG_ARRAY_U64, 113 ABCKIT_LITERAL_TAG_ARRAY_I64, 114 ABCKIT_LITERAL_TAG_ARRAY_F32, 115 ABCKIT_LITERAL_TAG_ARRAY_F64, 116 ABCKIT_LITERAL_TAG_ARRAY_STRING, 117 ABCKIT_LITERAL_TAG_ASYNCGENERATORMETHOD, 118 ABCKIT_LITERAL_TAG_NULLVALUE, 119 120 /* static */ 121 ABCKIT_LITERAL_TAG_BIGINT, 122 ABCKIT_LITERAL_TAG_ASYNCMETHOD, 123 124 /* dynamic */ 125 ABCKIT_LITERAL_TAG_LITERALBUFFERINDEX, 126 ABCKIT_LITERAL_TAG_LITERALARRAY, 127 ABCKIT_LITERAL_TAG_BUILTINTYPEINDEX, 128 ABCKIT_LITERAL_TAG_GETTER, 129 ABCKIT_LITERAL_TAG_SETTER 130 }; 131 132 enum { ABCKIT_VERSION_SIZE = 4 }; 133 134 /** 135 * @brief Struct that holds the pointers to the non-modifying API for core Abckit types. 136 */ 137 struct AbckitInspectApi { 138 /* ======================================== 139 * Language-independent abstractions 140 * ======================================== */ 141 142 /* ======================================== 143 * File 144 * ======================================== */ 145 146 /** 147 * @brief Read version of provided binary file. 148 * @return Version of the binary file. 149 * @param [ in ] file - Binary file to read version from. 150 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 151 */ 152 AbckitFileVersion (*fileGetVersion)(AbckitFile *file); 153 154 /** 155 * @brief Enumerates modules that are defined in binary file `file`, invoking callback `cb` for each of such 156 * modules. 157 * @return `false` if was early exited. Otherwise - `true`. 158 * @param [ in ] file - Binary file to enumerate local modules in. 159 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 160 * it is invoked. 161 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 162 * should continue. 163 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 164 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 165 */ 166 bool (*fileEnumerateModules)(AbckitFile *file, void *data, bool (*cb)(AbckitCoreModule *module, void *data)); 167 168 /** 169 * @brief Enumerates modules that are defined in other binary file, but are referenced in binary file `file`, 170 * invoking callback `cb` for each of such modules. 171 * @return `false` if was early exited. Otherwise - `true`. 172 * @param [ in ] file - Binary file to enumerate external modules in. 173 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 174 * it is invoked. 175 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 176 * should continue. 177 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 178 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 179 */ 180 bool (*fileEnumerateExternalModules)(AbckitFile *file, void *data, 181 bool (*cb)(AbckitCoreModule *module, void *data)); 182 183 /* ======================================== 184 * String 185 * ======================================== */ 186 187 /** 188 * @brief Converts value of type `AbckitString` to C-style null-terminated string. Returned pointer should not be 189 * used to write to the memory. 190 * @return C-style string that corresponds to the `value`. 191 * @param [ in ] value - Value of type `AbckitString` that needs to be converted. 192 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 193 */ 194 const char *(*abckitStringToString)(AbckitString *value); 195 196 /* ======================================== 197 * Type 198 * ======================================== */ 199 200 /** 201 * @brief Returns type id for the given value of type `AbckitType`. 202 * @return Type id of the `t` argument. 203 * @param [ in ] t - Type to be inspected. 204 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `t` is NULL. 205 */ 206 enum AbckitTypeId (*typeGetTypeId)(AbckitType *t); 207 208 /** 209 * @brief Returns instance of the `AbckitCoreClass` that the type `t` is reference to. 210 * @return Pointer to the `AbckitCoreClass` that `t` references. 211 * @param [ in ] t - Type to be inspected. 212 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `t` is NULL. 213 */ 214 AbckitCoreClass *(*typeGetReferenceClass)(AbckitType *t); 215 216 /* ======================================== 217 * Value 218 * ======================================== */ 219 220 /** 221 * @brief Returns binary file that the given `value` is a part of. 222 * @return Pointer to the file that contains given `value`. 223 * @param [ in ] value - Value item to be inspected. 224 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 225 */ 226 AbckitFile *(*valueGetFile)(AbckitValue *value); 227 228 /** 229 * @brief Returns type that given `value` has. 230 * @return Pointer to the `AbckitType` that corresponds to provided `value`. 231 * @param [ in ] value - Value item to be inspected. 232 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 233 */ 234 AbckitType *(*valueGetType)(AbckitValue *value); 235 236 /** 237 * @brief Returns boolean value that given `value` holds. 238 * @return Boolean value that is stored in the `value`. 239 * @param [ in ] value - Value item to be inspected. 240 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 241 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` type id differs from `ABCKIT_TYPE_ID_U1`. 242 */ 243 bool (*valueGetU1)(AbckitValue *value); 244 245 /** 246 * @brief Returns double value that given `value` holds. 247 * @return Double value that is stored in the `value`. 248 * @param [ in ] value - Value item to be inspected. 249 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 250 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` type id differs from `ABCKIT_TYPE_ID_F64`. 251 */ 252 double (*valueGetDouble)(AbckitValue *value); 253 254 /** 255 * @brief Returns string value that given `value` holds. 256 * @return Pointer to the `AbckitString` value that is stored in the `value`. 257 * @param [ in ] value - Value item to be inspected. 258 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 259 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` type id differs from `ABCKIT_TYPE_ID_STRING`. 260 * @note Allocates 261 */ 262 AbckitString *(*valueGetString)(AbckitValue *value); 263 264 /** 265 * @brief Returns literal array that given `value` holds. 266 * @return Pointer to the `AbckitLiteralArray`. 267 * @param [ in ] value - Value item to be inspected. 268 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 269 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` type id differs from `ABCKIT_TYPE_ID_LITERALARRAY`. 270 */ 271 AbckitLiteralArray *(*arrayValueGetLiteralArray)(AbckitValue *value); 272 273 /* ======================================== 274 * Literal 275 * ======================================== */ 276 277 /** 278 * @brief Returns binary file that the given `lit` is a part of. 279 * @return Pointer to the `AbckitFile`. 280 * @param [ in ] lit - Literal to be inspected. 281 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 282 */ 283 AbckitFile *(*literalGetFile)(AbckitLiteral *lit); 284 285 /** 286 * @brief Returns type tag that the given `lit` has. 287 * @return Tag of the literal `lit`. 288 * @param [ in ] lit - Literal to be inspected. 289 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 290 */ 291 enum AbckitLiteralTag (*literalGetTag)(AbckitLiteral *lit); 292 293 /** 294 * @brief Returns boolean value for `lit`. 295 * @return Boolean value of the `lit` literal. 296 * @param [ in ] lit - Literal to be inspected. 297 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 298 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_BOOL`. 299 */ 300 bool (*literalGetBool)(AbckitLiteral *lit); 301 302 /** 303 * @brief Returns byte value for `lit`. 304 * @return Byte value of the `lit` literal. 305 * @param [ in ] lit - Literal to be inspected. 306 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 307 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_BYTE`, 308 * `ABCKIT_LITERAL_TAG_NULLVALUE`, `ABCKIT_LITERAL_TAG_TAGVALUE` or `ABCKIT_LITERAL_TAG_ACCESSOR`. 309 */ 310 uint8_t (*literalGetU8)(AbckitLiteral *lit); 311 /** 312 * @brief Returns short value for `lit`. 313 * @return Short value of the `lit` literal. 314 * @param [ in ] lit - Literal to be inspected. 315 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 316 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_SHORT`. 317 */ 318 uint16_t (*literalGetU16)(AbckitLiteral *lit); 319 320 /** 321 * @brief Returns method affiliate value for `lit`. 322 * @return uint16_t containing method affiliate оffset that is stored in the `lit` literal. 323 * @param [ in ] lit - Literal to be inspected. 324 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 325 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from 326 * `ABCKIT_LITERAL_TAG_METHODAFFILIATE`. 327 */ 328 uint16_t (*literalGetMethodAffiliate)(AbckitLiteral *lit); 329 330 /** 331 * @brief Returns integer value for `lit`. 332 * @return uint32_t value for `lit` literal. 333 * @param [ in ] lit - Literal to be inspected. 334 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 335 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_INTEGER`. 336 */ 337 uint32_t (*literalGetU32)(AbckitLiteral *lit); 338 339 /** 340 * @brief Returns long value that is sotred in `lit` literal. 341 * @return uint64_t value for `lit` literal. 342 * @param [ in ] lit - Literal to be inspected. 343 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 344 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_LONG`. 345 */ 346 uint64_t (*literalGetU64)(AbckitLiteral *lit); 347 348 /** 349 * @brief Returns float value that is sotred in `lit` literal. 350 * @return float value for `lit` literal. 351 * @param [ in ] lit - Literal to be inspected. 352 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 353 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_FLOAT`. 354 */ 355 float (*literalGetFloat)(AbckitLiteral *lit); 356 357 /** 358 * @brief Returns double value that is sotred in `lit` literal. 359 * @return double value for `lit` literal. 360 * @param [ in ] lit - Literal to be inspected. 361 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 362 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_DOUBLE`. 363 */ 364 double (*literalGetDouble)(AbckitLiteral *lit); 365 366 /** 367 * @brief Returns literal array that is stored insode literal `lit`. 368 * @return Pointer to the `AbckitLiteralArray` that holds the literal array. 369 * @param [ in ] lit - Literal to be inspected. 370 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 371 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_LITERALARRAY`. 372 */ 373 AbckitLiteralArray *(*literalGetLiteralArray)(AbckitLiteral *lit); 374 375 /** 376 * @brief Returns string value for `lit`. 377 * @return Pointer to the `AbckitString` that holds the string value of the `lit` literal. 378 * @param [ in ] lit - Literal to be inspected. 379 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 380 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_STRING`. 381 * @note Allocates 382 */ 383 AbckitString *(*literalGetString)(AbckitLiteral *lit); 384 385 /** 386 * @brief Returns method descriptor that is stored in `lit` literal. 387 * @return Pointer to the `AbckitString` that holds the string value of the `lit` literal. 388 * @param [ in ] lit - Literal to be inspected. 389 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `lit` is NULL. 390 * @note Set `ABCKIT_STATUS_WRONG_LITERAL_TYPE` error if `lit` tag differs from `ABCKIT_LITERAL_TAG_STRING`. 391 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for literal emitted not for target 392 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`. 393 * @note Allocates 394 */ 395 AbckitString *(*literalGetMethod)(AbckitLiteral *lit); 396 397 /* ======================================== 398 * LiteralArray 399 * ======================================== */ 400 401 /** 402 * @brief Enumerates elements of the literal array `litArr`, invoking callback `cb` for each of it's 403 * elements. 404 * @return `false` if was early exited. Otherwise - `true`. 405 * @param [ in ] litArr - Literal array to enumerate elements in. 406 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 407 * it is invoked. 408 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 409 * should continue. 410 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `litArr` is NULL. 411 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 412 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for literal emitted not for target 413 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`.. 414 */ 415 bool (*literalArrayEnumerateElements)(AbckitLiteralArray *litArr, void *data, 416 bool (*cb)(AbckitFile *file, AbckitLiteral *lit, void *data)); 417 418 /* ======================================== 419 * Language-dependent abstractions 420 * ======================================== */ 421 422 /* ======================================== 423 * Module 424 * ======================================== */ 425 426 /** 427 * @brief Returns binary file that the given module `m` is a part of. 428 * @return Pointer to the `AbckitFile` that contains given module `m`. 429 * @param [ in ] m - Module to be inspected. 430 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 431 */ 432 AbckitFile *(*moduleGetFile)(AbckitCoreModule *m); 433 434 /** 435 * @brief Returns the target that the given module `m` was compiled for. 436 * @return Target of the current module. 437 * @param [ in ] m - Module to be inspected. 438 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 439 */ 440 enum AbckitTarget (*moduleGetTarget)(AbckitCoreModule *m); 441 442 /** 443 * @brief Returns the name of the given module `m`. 444 * @return Pointer to the `AbckitString` that contains the name of the module. 445 * @param [ in ] m - Module to be inspected. 446 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 447 * @note Allocates 448 */ 449 AbckitString *(*moduleGetName)(AbckitCoreModule *m); 450 451 /** 452 * @brief Tells if module is defined in the same binary or externally in another binary. 453 * @return Returns `true` if given module `m` is defined in another binary and `false` if defined locally. 454 * @param [ in ] m - Module to be inspected. 455 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 456 */ 457 bool (*moduleIsExternal)(AbckitCoreModule *m); 458 459 /** 460 * @brief Enumerates imports of the module `m`, invoking callback `cb` for each import. 461 * @return `false` if was early exited. Otherwise - `true`. 462 * @param [ in ] m - Module to be inspected. 463 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 464 * it is invoked. 465 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 466 * should continue. 467 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 468 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 469 */ 470 bool (*moduleEnumerateImports)(AbckitCoreModule *m, void *data, 471 bool (*cb)(AbckitCoreImportDescriptor *i, void *data)); 472 473 /** 474 * @brief Enumerates exports of the module `m`, invoking callback `cb` for each export. 475 * @return `false` if was early exited. Otherwise - `true`. 476 * @param [ in ] m - Module to be inspected. 477 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 478 * it is invoked. 479 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 480 * should continue. 481 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 482 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 483 */ 484 bool (*moduleEnumerateExports)(AbckitCoreModule *m, void *data, 485 bool (*cb)(AbckitCoreExportDescriptor *i, void *data)); 486 487 /** 488 * @brief Enumerates namespaces of the module `m`, invoking callback `cb` for each namespace. 489 * @return `false` if was early exited. Otherwise - `true`. 490 * @param [ in ] m - Module to be inspected. 491 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 492 * it is invoked. 493 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 494 * should continue. 495 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 496 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 497 */ 498 bool (*moduleEnumerateNamespaces)(AbckitCoreModule *m, void *data, bool (*cb)(AbckitCoreNamespace *n, void *data)); 499 500 /** 501 * @brief Enumerates classes of the module `m`, invoking callback `cb` for each class. 502 * @return `false` if was early exited. Otherwise - `true`. 503 * @param [ in ] m - Module to be inspected. 504 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 505 * it is invoked. 506 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 507 * should continue. 508 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 509 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 510 */ 511 bool (*moduleEnumerateClasses)(AbckitCoreModule *m, void *data, bool (*cb)(AbckitCoreClass *klass, void *data)); 512 513 /** 514 * @brief Enumerates top level functions of the module `m`, invoking callback `cb` for each top level function. 515 * @return `false` if was early exited. Otherwise - `true`. 516 * @param [ in ] m - Module to be inspected. 517 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 518 * it is invoked. 519 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 520 * should continue. 521 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 522 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 523 */ 524 bool (*moduleEnumerateTopLevelFunctions)(AbckitCoreModule *m, void *data, 525 bool (*cb)(AbckitCoreFunction *function, void *data)); 526 527 /** 528 * @brief Enumerates anonymous functions of the module `m`, invoking callback `cb` for each anonymous function. 529 * @return`false` if was early exited. Otherwise - `true`. 530 * @param [ in ] m - Module to be inspected. 531 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 532 * it is invoked. 533 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 534 * should continue. 535 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 536 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 537 */ 538 bool (*moduleEnumerateAnonymousFunctions)(AbckitCoreModule *m, void *data, 539 bool (*cb)(AbckitCoreFunction *function, void *data)); 540 541 /** 542 * @brief Enumerates annotation interfaces of the module `m`, invoking callback `cb` for each annotation interface. 543 * @return `false` if was early exited. Otherwise - `true`. 544 * @param [ in ] m - Module to be inspected. 545 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 546 * it is invoked. 547 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 548 * should continue. 549 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `m` is NULL. 550 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 551 */ 552 bool (*moduleEnumerateAnnotationInterfaces)(AbckitCoreModule *m, void *data, 553 bool (*cb)(AbckitCoreAnnotationInterface *ai, void *data)); 554 555 /* ======================================== 556 * Namespace 557 * ======================================== */ 558 559 /** 560 * @brief Returns name of the namespace `n`. 561 * @return Pointer to the `AbckitString` containig the name of the namespace. 562 * @param [ in ] n - Namespace to be inspected. 563 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `n` is NULL. 564 * @note Allocates 565 */ 566 AbckitString *(*namespaceGetName)(AbckitCoreNamespace *n); 567 568 /** 569 * @brief Returns parent namespace for namespace `n`. 570 * @return Pointer to the `AbckitCoreNamespace` or NULL if `n` has no parent namespace. 571 * @param [ in ] n - Namespace to be inspected. 572 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `n` is NULL. 573 */ 574 AbckitCoreNamespace *(*namespaceGetParentNamespace)(AbckitCoreNamespace *n); 575 576 /** 577 * @brief Enumerates namespaces defined inside of the namespace `n`, invoking callback `cb` for each inner 578 * namespace. 579 * @return `false` if was early exited. Otherwise - `true`. 580 * @param [ in ] n - Namespace to be inspected. 581 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 582 * it is invoked. 583 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 584 * should continue. 585 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `n` is NULL. 586 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 587 */ 588 bool (*namespaceEnumerateNamespaces)(AbckitCoreNamespace *n, void *data, 589 bool (*cb)(AbckitCoreNamespace *klass, void *data)); 590 591 /** 592 * @brief Enumerates classes of the namespace `n`, invoking callback `cb` for each class. 593 * @return `false` if was early exited. Otherwise - `true`. 594 * @param [ in ] n - Namespace to be inspected. 595 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 596 * it is invoked. 597 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 598 * should continue. 599 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `n` is NULL. 600 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 601 */ 602 bool (*namespaceEnumerateClasses)(AbckitCoreNamespace *n, void *data, 603 bool (*cb)(AbckitCoreClass *klass, void *data)); 604 605 /** 606 * @brief Enumerates top level functions of the namespace `n`, invoking callback `cb` for each top level function. 607 * @return `false` if was early exited. Otherwise - `true`. 608 * @param [ in ] n - Namespace to be inspected. 609 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 610 * it is invoked. 611 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 612 * should continue. 613 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `n` is NULL. 614 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 615 */ 616 bool (*namespaceEnumerateTopLevelFunctions)(AbckitCoreNamespace *n, void *data, 617 bool (*cb)(AbckitCoreFunction *function, void *data)); 618 619 /* ======================================== 620 * ImportDescriptor 621 * ======================================== */ 622 623 /** 624 * @brief Returns binary file that the given import descriptor `i` is a part of. 625 * @return Pointer to the `AbckitFile` that the import `i` is a part of. 626 * @param [ in ] i - Import descriptor to be inspected. 627 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `i` is NULL. 628 */ 629 AbckitFile *(*importDescriptorGetFile)(AbckitCoreImportDescriptor *i); 630 631 /** 632 * @brief Returns importing module for import descriptor `i`. 633 * @return Pointer to the `AbckitCoreModule` that holds the module that the import `i` is a part of. 634 * @param [ in ] i - Import descriptor to be inspected. 635 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `i` is NULL. 636 */ 637 AbckitCoreModule *(*importDescriptorGetImportingModule)(AbckitCoreImportDescriptor *i); 638 639 /** 640 * @brief Returns imported module for import descriptor `i`. 641 * @return Pointer to the `AbckitCoreModule` that holds the module that the import `i` imports from. 642 * @param [ in ] i - Import descriptor to be inspected. 643 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `i` is NULL. 644 */ 645 AbckitCoreModule *(*importDescriptorGetImportedModule)(AbckitCoreImportDescriptor *i); 646 647 /** 648 * @brief Returns name of the import descriptor `i`. 649 * @return Pointer to the `AbckitString` that holds the name of the imported entity. 650 * @param [ in ] i - Import descriptor to be inspected. 651 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `i` is NULL. 652 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for import descriptor `i` emitted not for target 653 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`. 654 * @note Allocates 655 */ 656 AbckitString *(*importDescriptorGetName)(AbckitCoreImportDescriptor *i); 657 658 /** 659 * @brief Returns alias for import descriptor `i`. 660 * @return Pointer to the `AbckitString` that holds the alias of the imported entity. 661 * @param [ in ] i - Import descriptor to be inspected. 662 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `i` is NULL. 663 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for import descriptor `i` emitted not for target 664 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`. 665 * @note Allocates 666 */ 667 AbckitString *(*importDescriptorGetAlias)(AbckitCoreImportDescriptor *i); 668 669 /* ======================================== 670 * ExportDescriptor 671 * ======================================== */ 672 673 /** 674 * @brief Returns binary file that the given export descriptor `e` is a part of. 675 * @return Pointer to the `AbckitFile` that the export `e` is a part of. 676 * @param [ in ] e- Export descriptor to be inspected. 677 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `e` is NULL. 678 */ 679 AbckitFile *(*exportDescriptorGetFile)(AbckitCoreExportDescriptor *e); 680 681 /** 682 * @brief Returns exporting module for export descriptor `e`. 683 * @return Pointer to the `AbckitCoreModule` that holds the module that the export `e` is a part of. 684 * @param [ in ] e- Export descriptor to be inspected. 685 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `e` is NULL. 686 */ 687 AbckitCoreModule *(*exportDescriptorGetExportingModule)(AbckitCoreExportDescriptor *e); 688 689 /** 690 * @brief Returns exporting module for export descriptor `e`. 691 * @return Pointer to the `AbckitCoreModule` that holds the module that the export `e` exports from. For local 692 * entity export equals to the exporting module. For re-exports may be different. 693 * @param [ in ] e- Export descriptor to be inspected. 694 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `e` is NULL. 695 */ 696 AbckitCoreModule *(*exportDescriptorGetExportedModule)(AbckitCoreExportDescriptor *e); 697 698 /** 699 * @brief Returns name for export descriptor `e`. 700 * @return Pointer to the `AbckitString` that holds the name of the exported entity. 701 * @param [ in ] e- Export descriptor to be inspected. 702 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `e` is NULL. 703 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for export descriptor `i` emitted not for target 704 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`. 705 * @note Allocates 706 */ 707 AbckitString *(*exportDescriptorGetName)(AbckitCoreExportDescriptor *e); 708 709 /** 710 * @brief Returns alias for export descriptor `e`. 711 * @return Pointer to the `AbckitString` that holds the alias of the exported entity. 712 * @param [ in ] e- Export descriptor to be inspected. 713 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `e` is NULL. 714 * @note Set `ABCKIT_STATUS_UNSUPPORTED` error if invoked for export descriptor `i` emitted not for target 715 * `ABCKIT_TARGET_ARK_TS_V1` or `ABCKIT_TARGET_JS`. 716 * @note Allocates 717 */ 718 AbckitString *(*exportDescriptorGetAlias)(AbckitCoreExportDescriptor *e); 719 720 /* ======================================== 721 * Class 722 * ======================================== */ 723 724 /** 725 * @brief Returns binary file that the given class `klass` is a part of. 726 * @return Pointer to the `AbckitFile`. 727 * @param [ in ] klass - Class to be inspected. 728 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 729 */ 730 AbckitFile *(*classGetFile)(AbckitCoreClass *klass); 731 732 /** 733 * @brief Returns module for class `klass`. 734 * @return Pointer to the `AbckitCoreModule`. 735 * @param [ in ] klass - Class to be inspected. 736 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 737 */ 738 AbckitCoreModule *(*classGetModule)(AbckitCoreClass *klass); 739 740 /** 741 * @brief Returns name for class `klass`. 742 * @return Pointer to the `AbckitString`. 743 * @param [ in ] klass - Class to be inspected. 744 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 745 * @note Allocates 746 */ 747 AbckitString *(*classGetName)(AbckitCoreClass *klass); 748 749 /** 750 * @brief Returns parent function for class `klass`. 751 * @return Pointer to the `AbckitCoreFunction`. 752 * @param [ in ] klass - Class to be inspected. 753 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 754 */ 755 AbckitCoreFunction *(*classGetParentFunction)(AbckitCoreClass *klass); 756 757 /** 758 * @brief Returns parent namespace for class `klass`. 759 * @return Pointer to the `AbckitCoreNamespace`. 760 * @param [ in ] klass - Class to be inspected. 761 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 762 */ 763 AbckitCoreNamespace *(*classGetParentNamespace)(AbckitCoreClass *klass); 764 765 /** 766 * @brief Enumerates methods of class `klass`, invoking callback `cb` for each method. 767 * @return `false` if was early exited. Otherwise - `true`. 768 * @param [ in ] klass - Class to be inspected. 769 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 770 * it is invoked. 771 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 772 * should continue. 773 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 774 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 775 */ 776 bool (*classEnumerateMethods)(AbckitCoreClass *klass, void *data, 777 bool (*cb)(AbckitCoreFunction *method, void *data)); 778 779 /** 780 * @brief Enumerates annotations of class `klass`, invoking callback `cb` for each annotation. 781 * @return false` if was early exited. Otherwise - `true`. 782 * @param [ in ] klass - Class to be inspected. 783 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 784 * it is invoked. 785 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 786 * should continue. 787 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 788 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 789 */ 790 bool (*classEnumerateAnnotations)(AbckitCoreClass *klass, void *data, 791 bool (*cb)(AbckitCoreAnnotation *anno, void *data)); 792 793 /* ======================================== 794 * Function 795 * ======================================== */ 796 797 /** 798 * @brief Returns binary file that the given function `function` is a part of. 799 * @return Pointer to the `AbckitFile`. 800 * @param [ in ] function - Function to be inspected. 801 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 802 */ 803 AbckitFile *(*functionGetFile)(AbckitCoreFunction *function); 804 805 /** 806 * @brief Returns module for function `function`. 807 * @return Pointer to the `AbckitCoreModule`. 808 * @param [ in ] function - Function to be inspected. 809 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 810 */ 811 AbckitCoreModule *(*functionGetModule)(AbckitCoreFunction *function); 812 813 /** 814 * @brief Returns name for function `function`. 815 * @return Pointer to the `AbckitString`. 816 * @param [ in ] function - Function to be inspected. 817 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 818 * @note Allocates 819 */ 820 AbckitString *(*functionGetName)(AbckitCoreFunction *function); 821 822 /** 823 * @brief Returns parent function for function `function`. 824 * @return Pointer to the `AbckitCoreClass`. 825 * @param [ in ] function - Function to be inspected. 826 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 827 */ 828 AbckitCoreFunction *(*functionGetParentFunction)(AbckitCoreFunction *function); 829 830 /** 831 * @brief Returns parent class for function `function`. 832 * @return Pointer to the `AbckitCoreClass`. 833 * @param [ in ] function - Function to be inspected. 834 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 835 */ 836 AbckitCoreClass *(*functionGetParentClass)(AbckitCoreFunction *function); 837 838 /** 839 * @brief Returns parent namespace for function `function`. 840 * @return Pointer to the `AbckitCoreNamespace`. 841 * @param [ in ] function - Function to be inspected. 842 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 843 */ 844 AbckitCoreNamespace *(*functionGetParentNamespace)(AbckitCoreFunction *function); 845 846 /** 847 * @brief Enumerates nested functions of function `func`, invoking callback `cb` for each nested function. 848 * @return `false` if was early exited. Otherwise - `true`. 849 * @param [ in ] func - Function to be inspected. 850 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 851 * it is invoked. 852 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 853 * should continue. 854 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `func` is NULL. 855 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 856 */ 857 bool (*functionEnumerateNestedFunctions)(AbckitCoreFunction *func, void *data, 858 bool (*cb)(AbckitCoreFunction *nestedFunc, void *data)); 859 860 /** 861 * @brief Enumerates nested classes of function `func`, invoking callback `cb` for each nested class. 862 * @return false` if was early exited. Otherwise - `true`. 863 * @param [ in ] func - Function to be inspected. 864 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 865 * it is invoked. 866 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 867 * should continue. 868 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `func` is NULL. 869 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 870 */ 871 bool (*functionEnumerateNestedClasses)(AbckitCoreFunction *func, void *data, 872 bool (*cb)(AbckitCoreClass *nestedClass, void *data)); 873 874 /** 875 * @brief Enumerates annotations of function `func`, invoking callback `cb` for each annotation. 876 * @return `false` if was early exited. Otherwise - `true`. 877 * @param [ in ] func - Function to be inspected. 878 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 879 * it is invoked. 880 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 881 * should continue. 882 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `func` is NULL. 883 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 884 */ 885 bool (*functionEnumerateAnnotations)(AbckitCoreFunction *func, void *data, 886 bool (*cb)(AbckitCoreAnnotation *anno, void *data)); 887 888 /** 889 * @brief Creates graph from function `function`. 890 * @return Pointer to the `AbckitGraph`. 891 * @param [ in ] function - Function to be inspected. 892 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 893 * @note Allocates 894 */ 895 AbckitGraph *(*createGraphFromFunction)(AbckitCoreFunction *function); 896 897 /** 898 * @brief Tells if function `function` is static. 899 * @return Returns `true` if given function `function` is static and `false` otherwise. 900 * @param [ in ] function - Function to be inspected. 901 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 902 */ 903 bool (*functionIsStatic)(AbckitCoreFunction *function); 904 905 /** 906 * @brief Tells if function `function` is constructor. 907 * @return Returns `true` if given function `function` is constructor and `false` otherwise. 908 * @param [ in ] function - Function to be inspected. 909 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 910 */ 911 bool (*functionIsCtor)(AbckitCoreFunction *function); 912 913 /** 914 * @brief Tells if function `function` is anonymous. 915 * @return Returns `true` if given function `function` is anonymous and `false` otherwise. 916 * @param [ in ] function - Function to be inspected. 917 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 918 */ 919 bool (*functionIsAnonymous)(AbckitCoreFunction *function); 920 921 /* ======================================== 922 * Annotation 923 * ======================================== */ 924 925 /** 926 * @brief Returns binary file that the given annotation `anno` is a part of. 927 * @return Pointer to the `AbckitFile`. 928 * @param [ in ] anno - Annotation to be inspected. 929 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `anno` is NULL. 930 */ 931 AbckitFile *(*annotationGetFile)(AbckitCoreAnnotation *anno); 932 933 /** 934 * @brief Returns interface for annotation `anno`. 935 * @return Pointer to the `AbckitCoreAnnotationInterface`. 936 * @param [ in ] anno - Annotation to be inspected. 937 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `anno` is NULL. 938 */ 939 AbckitCoreAnnotationInterface *(*annotationGetInterface)(AbckitCoreAnnotation *anno); 940 941 /** 942 * @brief Enumerates elements of the annotation `anno`, invoking the callback for each element. 943 * @return `false` if was early exited. Otherwise - `true`. 944 * @param [ in ] anno - Annotation to be inspected. 945 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 946 * it is invoked. 947 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 948 * should continue. 949 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `anno` is NULL. 950 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 951 */ 952 bool (*annotationEnumerateElements)(AbckitCoreAnnotation *anno, void *data, 953 bool (*cb)(AbckitCoreAnnotationElement *ae, void *data)); 954 955 /* ======================================== 956 * AnnotationElement 957 * ======================================== */ 958 959 /** 960 * @brief Returns binary file that the given annotation element `ae` is a part of. 961 * @return Pointer to the `AbckitFile`. 962 * @param [ in ] ae - Annotation element to be inspected. 963 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ae` is NULL. 964 */ 965 AbckitFile *(*annotationElementGetFile)(AbckitCoreAnnotationElement *ae); 966 967 /** 968 * @brief Returns annotation for annotation element `ae`. 969 * @return Pointer to the `AbckitCoreAnnotation`. 970 * @param [ in ] ae - Annotation element to be inspected. 971 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ae` is NULL. 972 */ 973 AbckitCoreAnnotation *(*annotationElementGetAnnotation)(AbckitCoreAnnotationElement *ae); 974 975 /** 976 * @brief Returns name for annotation element `ae`. 977 * @return Pointer to the `AbckitString`. 978 * @param [ in ] ae - Annotation element to be inspected. 979 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ae` is NULL. 980 * @note Allocates 981 */ 982 AbckitString *(*annotationElementGetName)(AbckitCoreAnnotationElement *ae); 983 984 /** 985 * @brief Returns value for annotation element `ae`. 986 * @return Pointer to the `AbckitValue`. 987 * @param [ in ] ae - Annotation element to be inspected. 988 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ae` is NULL. 989 */ 990 AbckitValue *(*annotationElementGetValue)(AbckitCoreAnnotationElement *ae); 991 992 /* ======================================== 993 * AnnotationInterface 994 * ======================================== */ 995 996 /** 997 * @brief Returns binary file that the given annotation interface `ai` is a part of. 998 * @return Pointer to the `AbckitFile`. 999 * @param [ in ] ai - Annotation interface to be inspected. 1000 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ai` is NULL. 1001 */ 1002 AbckitFile *(*annotationInterfaceGetFile)(AbckitCoreAnnotationInterface *ai); 1003 1004 /** 1005 * @brief Returns module for annotation interface `ai`. 1006 * @return Pointer to the `AbckitCoreModule`. 1007 * @param [ in ] ai - Annotation interface to be inspected. 1008 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ai` is NULL. 1009 */ 1010 AbckitCoreModule *(*annotationInterfaceGetModule)(AbckitCoreAnnotationInterface *ai); 1011 1012 /** 1013 * @brief Returns name for annotation interface `ai`. 1014 * @return Pointer to the `AbckitString`. 1015 * @param [ in ] ai - Annotation interface to be inspected. 1016 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ai` is NULL. 1017 * @note Allocates 1018 */ 1019 AbckitString *(*annotationInterfaceGetName)(AbckitCoreAnnotationInterface *ai); 1020 1021 /** 1022 * @brief Enumerates fields of annotation interface `ai`, invoking callback `cb` for each field. 1023 * @return `false` if was early exited. Otherwise - `true`. 1024 * @param [ in ] ai - Annotation interface to be inspected. 1025 * @param [ in, out ] data - Pointer to the user-defined data that will be passed to the callback `cb` each time 1026 * it is invoked. 1027 * @param [ in ] cb - Callback that will be invoked. Should return `false` on early exit and `true` when iterations 1028 * should continue. 1029 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `ai` is NULL. 1030 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `cb` is NULL. 1031 */ 1032 bool (*annotationInterfaceEnumerateFields)(AbckitCoreAnnotationInterface *ai, void *data, 1033 1034 bool (*cb)(AbckitCoreAnnotationInterfaceField *fld, void *data)); 1035 1036 /* ======================================== 1037 * AnnotationInterfaceField 1038 * ======================================== */ 1039 1040 /** 1041 * @brief Returns binary file that the given interface field `fld` is a part of. 1042 * @return Pointer to the `AbckitFile`. 1043 * @param [ in ] fld - Annotation interface field to be inspected. 1044 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `fld` is NULL. 1045 */ 1046 AbckitFile *(*annotationInterfaceFieldGetFile)(AbckitCoreAnnotationInterfaceField *fld); 1047 1048 /** 1049 * @brief Returns interface for interface field `fld`. 1050 * @return Pointer to the `AbckitCoreAnnotationInterface`. 1051 * @param [ in ] fld - Annotation interface field to be inspected. 1052 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `fld` is NULL. 1053 */ 1054 AbckitCoreAnnotationInterface *(*annotationInterfaceFieldGetInterface)(AbckitCoreAnnotationInterfaceField *fld); 1055 1056 /** 1057 * @brief Returns name for interface field `fld`. 1058 * @return Pointer to the `AbckitString`. 1059 * @param [ in ] fld - Annotation interface field to be inspected. 1060 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `fld` is NULL. 1061 * @note Allocates 1062 */ 1063 AbckitString *(*annotationInterfaceFieldGetName)(AbckitCoreAnnotationInterfaceField *fld); 1064 1065 /** 1066 * @brief Returns type for interface field `fld`. 1067 * @return Pointer to the `AbckitType`. 1068 * @param [ in ] fld - Annotation interface field to be inspected. 1069 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `fld` is NULL. 1070 */ 1071 AbckitType *(*annotationInterfaceFieldGetType)(AbckitCoreAnnotationInterfaceField *fld); 1072 1073 /** 1074 * @brief Returns default value for interface field `fld`. 1075 * @return Pointer to the `AbckitValue`. 1076 * @param [ in ] fld - Annotation interface field to be inspected. 1077 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `fld` is NULL. 1078 */ 1079 AbckitValue *(*annotationInterfaceFieldGetDefaultValue)(AbckitCoreAnnotationInterfaceField *fld); 1080 }; 1081 1082 /** 1083 * @brief Instantiates non-modifying API for core Abckit types. 1084 * @return Instance of the `AbckitInspectApi` struct with valid function pointers. 1085 * @param [ in ] version - Version of the API to instantiate. 1086 * @note Set `ABCKIT_STATUS_UNKNOWN_API_VERSION` error if `version` value is not in the `AbckitApiVersion` enum. 1087 */ 1088 struct AbckitInspectApi const *AbckitGetInspectApiImpl(enum AbckitApiVersion version); 1089 1090 /** 1091 * @brief Struct that holds the pointers to the modifying API for core Abckit types. 1092 */ 1093 struct AbckitModifyApi { 1094 /* ======================================== 1095 * Function 1096 * ======================================== */ 1097 1098 /** 1099 * @brief Sets graph for function `function`. 1100 * @return None. 1101 * @param [ in ] function - Function to be modified. 1102 * @param [ in ] graph - Graph to be set. 1103 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 1104 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `graph` is NULL. 1105 * @note Set `ABCKIT_STATUS_WRONG_CTX` error if corresponding `AbckitFile`s owning `function` and `graph` are 1106 * differ. 1107 * @note Allocates 1108 */ 1109 void (*functionSetGraph)(AbckitCoreFunction *function, AbckitGraph *graph); 1110 1111 /* ======================================== 1112 * Type 1113 * ======================================== */ 1114 1115 /** 1116 * @brief Creates type according to type id `id`. 1117 * @return Pointer to the `AbckitType`. 1118 * @param [ in ] file - Binary file to be modified. 1119 * @param [ in ] `id` - Type id corresponding to the type being created. 1120 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1121 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `id` is `ABCKIT_TYPE_ID_INVALID`. 1122 * @note Allocates 1123 */ 1124 AbckitType *(*createType)(AbckitFile *file, enum AbckitTypeId id); 1125 1126 /** 1127 * @brief Creates reference type according to class `klass`. 1128 * @return Pointer to the `AbckitType`. 1129 * @param [ in ] file - Binary file to be modified. 1130 * @param [ in ] klass - Class from which the type is created. 1131 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1132 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `klass` is NULL. 1133 * @note Allocates 1134 */ 1135 AbckitType *(*createReferenceType)(AbckitFile *file, AbckitCoreClass *klass); 1136 1137 /* ======================================== 1138 * Value 1139 * ======================================== */ 1140 1141 /** 1142 * @brief Creates value item `AbckitValue` containing the given boolean value `value`. 1143 * @return Pointer to the `AbckitValue`. 1144 * @param [ in ] file - Binary file to be modified. 1145 * @param [ in ] value - Boolean value from which value item is created. 1146 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1147 * @note Allocates 1148 */ 1149 AbckitValue *(*createValueU1)(AbckitFile *file, bool value); 1150 1151 /** 1152 * @brief Creates value item containing the given double value `value`. 1153 * @return Pointer to the `AbckitValue`. 1154 * @param [ in ] file - Binary file to be modified. 1155 * @param [ in ] value - Double value from which value item is created. 1156 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1157 * @note Allocates 1158 */ 1159 AbckitValue *(*createValueDouble)(AbckitFile *file, double value); 1160 1161 /** 1162 * @brief Creates value item containing the given C-style null-terminated string `value`. 1163 * @return Pointer to the `AbckitValue`. 1164 * @param [ in ] file - Binary file to be modified. 1165 * @param [ in ] value - C-style null-terminated string from which value item is created. 1166 * @param [ in ] len - length of `value`. 1167 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1168 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 1169 * @note Allocates 1170 */ 1171 AbckitValue *(*createValueString)(AbckitFile *file, const char *value, size_t len); 1172 1173 /** 1174 * @brief Creates literal array value item with size `size` from the given value items array `value`. 1175 * @return Pointer to the `AbckitValue`. 1176 * @param [ in ] file - Binary file to be modified. 1177 * @param [ in ] value - Value items from which literal array item is created. 1178 * @param [ in ] size - Size of the literal array value item to be created. 1179 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1180 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 1181 * @note Allocates 1182 */ 1183 AbckitValue *(*createLiteralArrayValue)(AbckitFile *file, AbckitValue **value, size_t size); 1184 1185 /* ======================================== 1186 * String 1187 * ======================================== */ 1188 1189 /** 1190 * @brief Creates string item containing the given C-style null-terminated string `value`. 1191 * @return Pointer to the `AbckitString`. 1192 * @param [ in ] file - Binary file to be modified. 1193 * @param [ in ] value - C-style null-terminated string to be set. 1194 * @param [ in ] len - length of `value`. 1195 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1196 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 1197 * @note Allocates 1198 */ 1199 AbckitString *(*createString)(AbckitFile *file, const char *value, size_t len); 1200 1201 /* ======================================== 1202 * LiteralArray 1203 * ======================================== */ 1204 1205 /** 1206 * @brief Creates literal array with size `size` from the given literals array `value`. 1207 * @return Pointer to the `AbckitLiteralArray`. 1208 * @param [ in ] file - Binary file to be modified. 1209 * @param [ in ] value - Literals from which literal array is created. 1210 * @param [ in ] size - Size of the literal array to be created. 1211 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1212 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 1213 * @note Allocates 1214 */ 1215 AbckitLiteralArray *(*createLiteralArray)(AbckitFile *file, AbckitLiteral **value, size_t size); 1216 1217 /* ======================================== 1218 * Literal 1219 * ======================================== */ 1220 1221 /** 1222 * @brief Creates literal containing the given boolean value `value`. 1223 * @return Pointer to the `AbckitLiteral`. 1224 * @param [ in ] file - Binary file to be modified. 1225 * @param [ in ] value - Boolean value that will be stored in the literal to be created. 1226 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1227 * @note Allocates 1228 */ 1229 AbckitLiteral *(*createLiteralBool)(AbckitFile *file, bool value); 1230 1231 /** 1232 * @brief Creates literal containing the given byte value `value`. 1233 * @return Pointer to the `AbckitLiteral`. 1234 * @param [ in ] file - Binary file to be modified. 1235 * @param [ in ] value - Byte value that will be stored in the literal to be created. 1236 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1237 * @note Allocates 1238 */ 1239 AbckitLiteral *(*createLiteralU8)(AbckitFile *file, uint8_t value); 1240 1241 /** 1242 * @brief Creates literal containing the given short value `value`. 1243 * @return Pointer to the `AbckitLiteral`. 1244 * @param [ in ] file - Binary file to be modified. 1245 * @param [ in ] value - Short value that will be stored in the literal to be created. 1246 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1247 * @note Allocates 1248 */ 1249 AbckitLiteral *(*createLiteralU16)(AbckitFile *file, uint16_t value); 1250 1251 /** 1252 * @brief Creates literal containing the given оffset of method affiliate `value`. 1253 * @return Pointer to the `AbckitLiteral`. 1254 * @param [ in ] file - Binary file to be modified. 1255 * @param [ in ] value - Offset of method affiliate. 1256 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1257 * @note Allocates 1258 */ 1259 AbckitLiteral *(*createLiteralMethodAffiliate)(AbckitFile *file, uint16_t value); 1260 1261 /** 1262 * @brief Creates literal containing the given integer value `value`. 1263 * @return Pointer to the `AbckitLiteral`. 1264 * @param [ in ] file - Binary file to be modified. 1265 * @param [ in ] value - Integer value that will be stored in the literal to be created. 1266 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1267 * @note Allocates 1268 */ 1269 AbckitLiteral *(*createLiteralU32)(AbckitFile *file, uint32_t value); 1270 1271 /** 1272 * @brief Creates literal containing the given long value `value`. 1273 * @return Pointer to the `AbckitLiteral`. 1274 * @param [ in ] file - Binary file to be modified. 1275 * @param [ in ] value - Long value that will be stored in the literal to be created. 1276 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1277 * @note Allocates 1278 */ 1279 AbckitLiteral *(*createLiteralU64)(AbckitFile *file, uint64_t value); 1280 1281 /** 1282 * @brief Creates literal containing the given float value `value`. 1283 * @return Pointer to the `AbckitLiteral`. 1284 * @param [ in ] file - Binary file to be modified. 1285 * @param [ in ] value - Float value that will be stored in the literal to be created. 1286 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1287 * @note Allocates 1288 */ 1289 AbckitLiteral *(*createLiteralFloat)(AbckitFile *file, float value); 1290 1291 /** 1292 * @brief Creates literal containing the given double value `value`. 1293 * @return Pointer to the `AbckitLiteral`. 1294 * @param [ in ] file - Binary file to be modified. 1295 * @param [ in ] value - Double value that will be stored in the literal to be created. 1296 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1297 * @note Allocates 1298 */ 1299 AbckitLiteral *(*createLiteralDouble)(AbckitFile *file, double value); 1300 1301 /** 1302 * @brief Creates literal containing the given literal array `litarr`. 1303 * @return Pointer to the `AbckitLiteral`. 1304 * @param [ in ] file - Binary file to be modified. 1305 * @param [ in ] litarr - Literal array that will be stored in the literal to be created. 1306 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1307 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `litarr` is NULL. 1308 * @note Allocates 1309 */ 1310 AbckitLiteral *(*createLiteralLiteralArray)(AbckitFile *file, AbckitLiteralArray *litarr); 1311 1312 /** 1313 * @brief Creates literal containing the given C-style null-terminated string `value`. 1314 * @return Pointer to the `AbckitLiteral`. 1315 * @param [ in ] file - Binary file to be modified. 1316 * @param [ in ] value - C-style null-terminated string that will be stored in the literal to be created. 1317 * @param [ in ] len - length of `value`. 1318 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1319 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `value` is NULL. 1320 * @note Allocates 1321 */ 1322 AbckitLiteral *(*createLiteralString)(AbckitFile *file, const char *value, size_t len); 1323 1324 /** 1325 * @brief Creates literal containing the given function `function`. 1326 * @return Pointer to the `AbckitLiteral`. 1327 * @param [ in ] file - Binary file to be modified. 1328 * @param [ in ] function - Function that will be stored in the literal to be created. 1329 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `file` is NULL. 1330 * @note Set `ABCKIT_STATUS_BAD_ARGUMENT` error if `function` is NULL. 1331 * @note Allocates 1332 */ 1333 AbckitLiteral *(*createLiteralMethod)(AbckitFile *file, AbckitCoreFunction *function); 1334 }; 1335 1336 /** 1337 * @brief Instantiates modifying API for core Abckit types. 1338 * @return Instance of the `AbckitModifyApi` struct with valid function pointers. 1339 * @param [ in ] version - Version of the API to instantiate. 1340 * @note Set `ABCKIT_STATUS_UNKNOWN_API_VERSION` error if `version` value is not in the `AbckitApiVersion` enum. 1341 */ 1342 struct AbckitModifyApi const *AbckitGetModifyApiImpl(enum AbckitApiVersion version); 1343 1344 #ifdef __cplusplus 1345 } 1346 #endif /* __cplusplus */ 1347 1348 #endif /* !LIBABCKIT_METADATA_H */ 1349