NativeModule: callAsync() method
The callAsync() method calls one of this module's async methods and returns a Promise. JS keeps running while the native side works.
Syntax
callAsync(method, ...args)Parameters
method
The method name, a string. It must be in methods.async. A non-string is converted to a string first.
args
Arguments passed to the native side, any number of them. Each must be a value that can be passed.
Return value
A Promise.
- It fulfills with the value given by the native side, or
nullwhen the native side gives none. - It rejects when the native side reports an error; for the reason, see Errors from native code.
- It rejects with a
TypeErrorwhen the native side returns a value that can't be passed. - When the native side drops the call without delivering a result or reporting an error, it rejects, and the
messagecontainsfinished without calling resolve or reject. The Promise never stays pending forever. - When the native side delivers a result twice, the first one counts.
Even when the native side delivers the result right away, the Promise fulfills only after the currently running JS finishes.
Exceptions
TypeError
The following cases throw immediately instead of returning a Promise, and the native method isn't called:
- No method name:
callAsync: a method name is required. - The module has no such method:
callAsync: native module "example" has no method "nope"; sync methods: …; async methods: …. - The method is sync:
callAsync: "add" is a sync method of native module "example"; use call("add", …) instead. - An argument contains a value that can't be passed; the message is written the same way as in
call().
Description
For large binary data (several hundred KB or more), have the native side return it directly as an async method's return value: in that case it isn't encoded and is copied only once. In every other case (binary data in arguments, sync method return values, event data, binary data nested in arrays and objects), each chunk is encoded once and decoded once, which gets slower as the data grows. The actual timing is not measured.
Examples
Calling an async method
const example = application.nativeModules.get('example');
example.callAsync('echoLater', 'hello', 500).then((value) => {
console.log(value);
});
console.log('callAsync returned');Result: Prints callAsync returned first, then hello about half a second later.
Native error
const example = application.nativeModules.get('example');
example.callAsync('failLater', 'Offline', 'no network').catch((err) => {
const e = /** @type {NativeModuleError} */ (err);
console.log(e.name, e.message, 'code' in e);
});Result: Prints Offline no network false. The native side gave no error code, so there's no code.
Corresponding iOS API
There's no corresponding system API. For how the native side registers async methods, see Writing your own native module.
See also
call(): calls sync methods- Errors from native code