diff options
| author | Gabriel Schulhof <gabriel.schulhof@intel.com> | 2021-02-11 19:29:55 -0800 |
|---|---|---|
| committer | Richard Lau <rlau@redhat.com> | 2021-03-17 20:59:08 +0000 |
| commit | f5692093d3aab880afd2fe8c994ebdec0dedcae6 (patch) | |
| tree | 6ae2779a89f8db5339444f98dcc76f52141816fa /doc | |
| parent | 86f34ee18c36e2fcd3c057abc86704523ec940c8 (diff) | |
| download | node-new-f5692093d3aab880afd2fe8c994ebdec0dedcae6.tar.gz | |
node-api: allow retrieval of add-on file name
Unlike JS-only modules, native add-ons are always associated with a
dynamic shared object from which they are loaded. Being able to
retrieve its absolute path is important to native-only add-ons, i.e.
add-ons that are not themselves being loaded from a JS-only module
located in the same package as the native add-on itself.
Currently, the file name is obtained at environment construction time
from the JS `module.filename`. Nevertheless, the presence of `module`
is not required, because the file name could also be passed in via a
private property added onto `exports` from the `process.dlopen`
binding.
As an attempt at future-proofing, the file name is provided as a URL,
i.e. prefixed with the `file://` protocol.
Fixes: https://github.com/nodejs/node-addon-api/issues/449
PR-URL: https://github.com/nodejs/node/pull/37195
Backport-PR-URL: https://github.com/nodejs/node/pull/37328
Co-authored-by: Michael Dawson <mdawson@devrus.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/n-api.md | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 1f3c90de3d..600738db45 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5791,6 +5791,31 @@ idempotent. This API may only be called from the main thread. +## Miscellaneous utilities + +## node_api_get_module_file_name + +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +```c +NAPI_EXTERN napi_status +node_api_get_module_file_name(napi_env env, const char** result); + +``` + +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: A URL containing the absolute path of the + location from which the add-on was loaded. For a file on the local + file system it will start with `file://`. The string is null-terminated and + owned by `env` and must thus not be modified or freed. + +`result` may be an empty string if the add-on loading process fails to establish +the add-on's file name during loading. + [ABI Stability]: https://nodejs.org/en/docs/guides/abi-stability/ [AppVeyor]: https://www.appveyor.com [C++ Addons]: addons.html |