Cordova bridge

Methods available in the Cordova layer

These methods can be called from the Cordova javascript code directly:

• nodejs.start
• nodejs.startWithScript
• nodejs.channel.on
• nodejs.channel.post
• nodejs.channel.setListener
• nodejs.channel.send

Note

nodejs.channel.setListener(callback) is equivalent to nodejs.channel.on('message',callback) and nodejs.channel.send(msg) is equivalent to nodejs.channel.post('message',msg). They are maintained for backward compatibility purposes.

nodejs.start(scriptFileName, callback [, options])

Param	Type
scriptFileName	string
callback	function
options	StartupOptions

Starts the nodejs-mobile runtime thread with a file inside the nodejs-project directory.

nodejs.startWithScript(scriptBody, callback [, options])

Param	Type
scriptBody	string
callback	function
options	StartupOptions

Starts the nodejs-mobile runtime thread with a script body.

nodejs.channel.on(event, callback)

Param	Type
event	string
callback	function

Registers a callback for user-defined events raised from the nodejs-mobile side.

nodejs.channel.post(event, message)

Param	Type
event	string
message	any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse

Raises a user-defined event on the nodejs-mobile side.

nodejs.channel.setListener(listenerCallback)

Param	Type
listenerCallback	function

Registers a callback for 'message' events raised from the nodejs-mobile side. It is an alias for nodejs.channel.on('message', listenerCallback);.

nodejs.channel.send(message)

Param	Type
message	any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse

Raises a 'message' event on the nodejs-mobile side. It is an alias for nodejs.channel.post('message', message);.

StartupOptions: object

Name	Type	Default	Description
redirectOutputToLogcat	boolean	true	Allows to disable the redirection of the Node stdout/stderr to the Android logcat

Note

Note: the stdout/stderr redirection is applied to the whole application, the side effect is that some undesired/duplicated output may appear in the logcat. For example, the Chromium console output I/chromium: [INFO:CONSOLE(xx)] is also sent to stderr and will show up in logcat has well, with the NODEJS-MOBILE log tag.

Methods available in the Node layer

The following methods can be called from the Node javascript code through the cordova-bridge module:

  var cordova = require('cordova-bridge');

• cordova.channel.on
• cordova.channel.post
• cordova.channel.send
• cordova.app.on
• cordova.app.datadir

Note

cordova.channel.send(msg) is equivalent to cordova.channel.post('message',msg). It is maintained for backward compatibility purposes.

cordova.channel.on(event, callback)

Param	Type
event	string
callback	function

Registers a callback for user-defined events raised from the cordova side.

Note

To receive messages from nodejs.channel.send, use:

js cordova.channel.on('message', listenerCallback);

cordova.channel.post(event, message)

Param	Type
event	string
message	any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse

Raises a user-defined event on the cordova side.

cordova.channel.send(message)

Param	Type
message	any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse

Raises a 'message' event on the cordova side. It is an alias for cordova.channel.post('message', message);.

cordova.app.on(event, callback)

Param	Type
event	string
callback	function

Registers callbacks for App events. Currently supports the 'pause' and 'resume' events, which are raised automatically when the app switches to the background/foreground.

cordova.app.on('pause', (pauseLock) => {
  console.log('[node] app paused.');
  pauseLock.release();
});
cordova.app.on('resume', () => {
  console.log('[node] app resumed.');
});

The 'pause' event is raised when the application switches to the background. On iOS, the system will wait for the 'pause' event handlers to return before finally suspending the application. For the purpose of letting the iOS application know when it can safely suspend after going to the background, a pauseLock argument is passed to each 'pause' listener, so that release() can be called on it to signal that listener has finished doing all the work it needed to do. The application will only suspend after all the locks have been released (or iOS forces it to).

cordova.app.on('pause', (pauseLock) => {
  server.close( () => {
    // App will only suspend after the server stops listening for connections and current connections are closed.
    pauseLock.release();
  });
});

Warning

On iOS, the application will eventually be suspended, so the pause event should be used to run the clean up operations as quickly as possible and let the application suspend after that. Make sure to call pauseLock.release() in each 'pause' event listener, or your Application will keep running in the background for as long as iOS will allow it.

cordova.app.datadir()

Returns a writable path used for persistent data storage in the application. Its value corresponds to NSDocumentDirectory on iOS and FilesDir on Android.

Channel callback: function(arg)

Name	Type
arg	any JS type that can be serialized with JSON.stringify and deserialized with JSON.parse

The messages sent through the channel can be of any type that can be correctly serialized with JSON.stringify on one side and deserialized with JSON.parse on the other side, as it is what the channel does internally. This means that passing JS dates through the channel will convert them to strings and functions will be removed from their containing objects. In line with The JSON Data Interchange Syntax Standard, the channel supports sending messages that are composed of these JS types: Boolean, Number, String, Object, Array.

Notes about other node APIs

os.tmpdir()

On iOS, os.tmpdir() returns a temporary directory, since iOS sets the TMPDIR environment variable of the application to the equivalent of calling NSTemporaryDirectory.

The Android OS doesn't define a temporary directory for the system or application, so the plugin sets the TMPDIR environment variable to the value of the application context's CacheDir value.