# Master : Master service call

This module is the EdgerOS master service module.

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

var master = require('master');

# Support

The following shows master module APIs available for each permissions.

# Master Object

# master.log(file, callback)

• file {String} Local file name.
• callback {Function} Callback function.
  • error {Error} Log copy error message, no error is undefined.
  • file {String} The argument file in when calling this function.

Each application can inform the EdgerOS operating system of the desired log mode through a description file (desc.json). They include: 'file', 'console', 'null'(fast mode), 'file' mode means that all console output of the application will be saved in the system log file, 'console' mode means directly observe the application output through the EdgerOS IDE plug-in, and 'null' mode means no log will be saved. When the application selects the 'file' mode, the system will record the latest log output within 64 - 256KB. The system can call master.log() function to notify EdgerOS to copy the log to the file specified by file. EdgerOS will copy the current application log in append form. At this file, EdgerOS will erase the original log files after success, ensuring that the logs copied by each application request are not duplicated.

# Example

master.log('log.log', function(error) {
  if (error) {
    console.error('Get log error:', error.message);
  }
});

When the application crashes, you can use this log to analyze uncaught exceptions.

# master.find(eapid, callback)

• eapid {String} EdgerOS App package ID (Bundle ID: eg. 'com.acoinfo.app').
• callback {Function} Query callback function.
  • error {Error} Error information when an error occurs.
  • vendor {Object} App vendor information.
    • id {String} Vendor ID.
    • name {String} Vendor name.
  • version {Array} App version, typical format: [x.y.z].

This method can be used to query whether the specified application is installed in current EdgerOS system. The EdgerOS application package ID is the application unique bundle name. This method is mostly used to share information with other known applications.

# Example

/* Use master to search App ID */
master.find('com.acoinfo.app', function(error, vendor, version) {
  if (error) {
    // App does not exist
  } else {
    console.log(vendor.id, version);
  }
});

iosched.forever();

# master.cloud(callback)

• callback {Function} Callback function.
  • error {Error} Error information when an error occurs.
  • dock {Boolean} Whether to connect with EdgerOS Cloud.

This method can detect whether the current machine is connected to the cloud, or it can be used to detect whether the current device has an Internet connection.

# Example

var master = require('master');

master.cloud(function(error, conn) {
  if (error) {
    console.error('Detect error:', error.message);
  } else {
    console.info('Internet connect:', conn ? true : false);
  }
});

# master.startup(callback)

• callback {Function} Callback function.
  • error {Error} Error information when an error occurs.
  • startup {Boolean} Whether current App is auto startup.

Get whether current App is auto startup when EdgerOS boot on.

# Example

var master = require('master');

master.startup(function(error, startup) {
  if (error) {
    console.error('error:', error.message);
  } else {
    console.info('Auto startup:', startup ? true : false);
  }
});

# master.machine(callback)

• callback {Function} Callback function.
  • error {Error} Error information when an error occurs.
  • mname {String} Machine name set by the administrator.
  • machine {Object} Machine information.

This method can get information about the currently running machine. This information contains the following members:

• product {Object} Basic product info.
• vendor {Object} Machine vendor information.
• version {Array} EdgerOS version [x.x.x].

Get current machine information.

# Example

var master = require('master');

console.inspectEnable = true;

master.machine(function(error, mname, machine) {
  if (error) {
    console.error('error:', error.message);
  } else {
    console.log(mname, machine);
  }
});

# master.wallpaper(acoid, chunkOrPath[, callback[, option]])

• acoid {String} User ID.
• chunkOrPath {Buffer} | {String} Wallpaper bitmap buffer or picture file path.
• callback {Function} Callback function to get whether the wallpaper set successfully.
  • error {Error} Operation error, success is undefined.
• option {Object} Set options.

Set the EdgerOS wallpaper, please make sure you have the wallpaper permission. Supported image formats include png, jpeg, the maximum image size does not exceed 4096 x 4096, and the size does not exceed 6 MBytes. If acoid is 'default' or undefined, it means setting the global default wallpaper.

option can contain the following members:

• priority {String} Wallpaper display priority: 'personal' or 'default'.

The option.priority indicates priority of surface wallpaper display, 'personal' indicates that personal wallpaper is displayed first, and 'default' indicates that global default wallpaper is displayed first.

Currently, this API does not allow unprivileged apps to set the global default wallpaper.

# Example

var master = require('master');

// req is http request
master.wallpaper(req.eos.user.acoid, './wallpaper.png', function(error) {
  if (error) {
    console.error('Wallpaper setting failed:', error.message);
  } else {
    console.log('Wallpaper set successfully!');
  }
});

// Or:
var chunk = fs.readFile('./wallpaper.png');

// req is http request
master.wallpaper(req.eos.user.acoid, chunk, function(error) {
  if (error) {
    console.error('Wallpaper setting failed:', error.message);
  } else {
    console.log('Wallpaper set successfully!');
  }
}, {
  priority: 'personal' /* Personal wallpaper is displayed first */
});

# master.traffic()

• Returns: {Object} Network traffic usage of current App.

Get the network traffic usage of the current App. The returned value object contains the following properties:

• generic {Object} Generic data.

  • send {Integer} Number of bytes sent over the network.
  • recv {Integer} Number of bytes received by the network.

• multimedia {Object} Multimedia data.

  • send {Integer} Number of bytes sent over the network.
  • recv {Integer} Number of bytes received by the network.

These statistics are the values from the start of the App to the current moment. This function is valid in EdgerOS 2.2.1 and above.

# master.alarmAdd(time, topic, msg[, callback][, extra])

• time {Date} | {Integer} | {String} Some time in the future.
• topic {String} Topic that generates a message when the alarm expires.
• msg {String} The content of the message when the alarm expires.
• callback {Function} Callback function to get whether the alarm was created successfully.
  • error {Error} Operation error, success is undefined.
  • alarmid {Integer} Alarm ID, greater than 0 is valid.
• extra {Object} Extra Information. (EdgerOS 1.4.0 or later)

Create an alarm. Regardless of whether the application is closed or not, a preset push message will be generated when the alarm expires. time is a UTC time, You have to guarantee that it is sometime in the future.

extra can have the following members:

• accounts {Array} EdgerOS acoid array, specify the list of members to receive.

# Example

var master = require('master');

var now  = new Date();
var time = new Date(now.getTime() + 60 * 1000);

// Push this message after 1 minute, regardless of whether this application is closed.
master.alarmAdd(time, 'Test', 'This is message');

# master.alarmDelete(start[, end[, callback]])

• start {Date} | {Integer} | {String} Start time.
• end {Date} | {Integer} | {String} End time. default: all future time from start.
• callback {Function} Callback function to get whether the alarm was deleted successfully.
  • error {Error} Operation error, success is undefined.

Delete the timer for the current app installation that expires in a future time period.

# Example

var master = require('master');

// Delete all alarms created by the current app.
master.alarmDelete(new Date());

# master.alarmDeleteById(alarmid[, callback])

• alarmid {Integer} Alarm ID, greater than 0 is valid.
• callback {Function} Callback function to get whether the alarm was deleted successfully.
  • error {Error} Operation error, success is undefined.

Delete alarm with specified alarmid.

# Example

master.alarmAdd(..., function(error, alarmid) {
  if (error == undefined) {
    master.alarmDeleteById(alarmid);
  }
});

# Master Events

The master object will emit specific events in some situations.

# state

This event will be generated when the application state changes, such as switching from the foreground to the background, returning to the foreground from the background, etc.

# Example

var master = require('master');

master.on('state', function(state) {
  if (state.foreground) {
    console.log('Foreground!');
  } else {
    console.log('Background!');
  }
});