# SharedPipe : Shared data pipeline between apps

This module provides pipeline communication between EdgerOS applications. This module cooperates with the notify.share back-end message sharing function and the Web-SDK edger.app.open front-end message sharing function to fully realize any data exchange between EdgerOS Apps. This module is valid on EdgerOS 2.0.1 and above.

User can use the following code to import the SharedPipe module.

var SharedPipe = require('sharedpipe');

Any app can receive data from other apps, but the sender must have the permission.share permission. For details, please refer to permission.

# Support

The following shows SharedPipe module APIs available for each permissions.

# SharedPipe Class

# new SharedPipe()

• Returns: {Object} SharedPipe object.

Create SharedPipe object for transmit and receive data with other apps. One task can only create one SharedPipe object, duplicate creation will throw trigger an exception.

# Example

var shpipe = new SharedPipe();

# SharedPipe Object

# shpipe.listen(enable[, callback])

• enable {Boolean} Whether the current object is enabled to receive data.
• callback {Function} Callback.
  • error {Error} Whether the operation was successful.

shpipe.listen(true) can enable the current object to accept data receive. One SharedPipe object can be created in each task of an App, but only one object can be used to receive data. The last task that calls this function will be selected by the system to be receiver.

# Example

var shpipe = new SharedPipe();

shpipe.listen(true); // Become to a receiver
shpipe.listen(false); // Transmit only

# shpipe.transmit(dest, opt, callback[, timeout])

• dest {String} Destination app bundle ID.
• opt {Object} Transmit options.
• callback {Function} Callback.
  • error {Error} If an error occurs, specify the error information.
  • writable {Writable} Writable stream object, target is destination app.
• timeout {Integer} The timeout for waiting for the destination app to confirm receipt, the minimum cannot be less than 3000ms. The default is 30000ms.

Initiate a transmission request to the specified destination app, opt contains various options of the request, which can be defined by the app itself.

# Example

var shpipe = new SharedPipe();
var fname = 'test.txt';
var rdable = fs.createReadStream(fname);

shpipe.transmit('com.example.app', {
  file: fname, size: fs.size(fname)
}, function(error, wrable) {
  if (error) {
    console.error(error);
    rdable.destroy();
  } else {
    rdable.pipe(wrable);
    rdable.on('error', error => wrable.destroy(error));
    wrable.on('finish', () => {
      console.log('Transmit success!');
    });
  }
});

# SharedPipe Events

The SharedPipe object inherits from the EventEmitter class. The following events are thrown in some specific situations.

# accept

• src {String} Indicates the request transmit app bundle ID.
• opt {Object} Transmit options.
• confirm {Function} Confirm function.
  • accept {Boolean} Whether accept this transmit request.
  • receive {Function} Receive function.
    • error {Error} If an error occurs, specify the error information.
    • readable {Readable} Readable stream for receiving data.
  • alive {Integer} The maximum timeout to wait for the peer to send data. default: 30000ms. Optional.

When the current object is enabled as a listener, when other apps send data to the current app, this event will be generated, and the developer can choose to allow or denied the data transmission request according to the relevant information.

# Example

var shpipe = new SharedPipe();

shpipe.on('accept', function(src, opt, confirm) {
  if (!opt || opt.size > 1024) {
    confirm(false); // denied
  } else {
    confirm(true, function(error, rdable) {
      if (error) {
        return console.error(error);
      }
      var wrable = fs.createWriteStream(opt.file);
      rdable.pipe(wrable);
      rdable.on('error', error => wrable.destroy(error));
      wrable.on('finish', () => {
        console.log('Received success!');
      });
    }); // allow
  }
});