Node-ios-devices NPM

JavaScript library, designed to facilitate communication with iOS devices. The library’s interface is Promise-based.

Quick overview

In order to use node-ios-devices, just add a reference to it in your package.json by executing

$ npm install --save --save-exact node-ios-devices

In your project. Now you are ready to use node-ios-devices in your project:

const { DeviceMan } = require("node-ios-devices");
(async () => {
  const deviceman = new DeviceMan();
  deviceman.addDeviceFoundListener(function (connectedDevice) {
    console.log("Device FOUND!", connectedDevice);
  });
  deviceman.run();
  // Get devices list
  const { response: devices } = await deviceman.list();
  for (const device of devices) {
    try {
      // create device connection
      const deviceConnection = deviceman.createDeviceConnection(device);

      // Get files
      const { response: files } = await deviceConnection.files([
        {
          appId: "com.viettel.ttnd.vietteldiscovery",
          path: "/Documents",
        },
      ]);
      console.log(device.deviceId, JSON.stringify(files, null, 2));
    } catch (_error) {
      console.error(_error);
    }
  }
  deviceman.destroy();
}).call();

Building

The node-ios-devices package can be built on either Windows (requires Visual Studio) or macOS (requires Xcode). In order to build the application one should simply open the .sln or .xcodeproj file with the respective tool and click build. Whenever building in release configuration, the result binary will end up in bin/<platform-name>/<architecture>, relative to the root of this repository. For example bin/win/x64/ or bin/mac/x64/. The JavaScript counterpart of the C++ code expects the binaries to be present in those exact locations, so one would have to build at least once prior to using the application.

Releasing

When you want to release a new version, you should build the binaries for macOS and Windows. To do this, please follow the steps below:

On Windows machine, open NodeIOSDevices.sln file with Visual Studio.
Select Release configuration and x64 architecture.
Build the application.
Now switch the architecture to x86.
Build the application again.
After that open the <repo dir>\bin\win - you will find two dirs there - ia32 and x64.
Open both of the directories and delete all files except the node-ios-devices.exe file.
Copy the win dir to your Mac machine.
Open the repository on macOS
With Xcode open the NodeIOSDevices.xcodeproj
Build the product in Release mode (Cmd + Shift + B on my side).
Open the <repo dir>/bin/mac directory and check if you have x64 dir there with a single binary file in it.
Inside <repo dir>/bin/ put the win directory that you've copied from your Windows machine.
At the root of the repository execute npm pack - this will produce a new .tgz file.
Publish the .tgz file in npm.

Inter-process Communication

This application consists of two separate layers - one C++ and one Node.js. The C++ layer implements the application's business logic, whereas the Node.js layer exists simply for alleviation. Whenever the Node.js part is used, it launches the C++ binary and initiates communication with it. This communication consists of requests to the binary via the stdin pipe and responses from the binary via the stdout pipe. Currently the stderr pipe is only used for debugging purposes.

The nature of this way of communication imposes some quirks:

All request messages are marked with an unique identifier which is also present in the response messages. This way the Node.js layer can distinguish between different messages and match a request with it's response counterpart
All messages are printed in binary on the stdout (and the stderr) pipe. Each message is prefixed with a 4 byte header, containing the length of the succeeding message. These 4-byte prefixes appear as peculiar symbols in the console whenever one decides to launch the binary directly. This is necessary as the messages have variable length and in addition it alleviates printing from the C++ code as the strings we want to print might contain NULL characters which would otherwise terminate printing.

API Reference

In order to use the application directly one can either launch the binary, either directly or from within an IDE, or use the JavaScript API. Whenever using this library make sure that there is at least one actual iOS device attached to the system. This library has no functionality whatsoever without actual devices.

C++ Binary

Upon launching the binary it will report all devices currently attached in the following form:

{
  "deviceColor": "1",
  "deviceId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "deviceName": "iPhone",
  "event": "deviceFound",
  "productType": "iPhone9,4",
  "productVersion": "11.0.3",
  "status": "Connected"
}

After that the binary is ready to accept requests via its standart input. Currently each passed message must be on one line, ending with a new line (Enter key) in order for it to be parsed correctly. Each message contains the name of the method, which you'd like to invoke, an identification string and the method's arguments. Messages are processed asynchronously, hence multiple messages can be passed at once. Example messages for the different opperations can be found below:

List applications

{
  "methods": [
    {
      "name": "apps"
    }
  ]
}

Install application

{
  "methods": [
    {
      "name": "install",
      "args": [
        "D:\\\apps\\\app.ipa"
      ]
    }
  ]
}

Uninstall application

{
  "methods": [
    {
      "name": "uninstall",
      "args": [
        "com.sample.MyApp"
      ]
    }
  ]
}

List files in an application

{
  "methods": [
    {
      "name": "files",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "path": "/Documents"
        }
      ]
    }
  ]
}

Upload a file from the local file system to the device

{
  "methods": [
    {
      "name": "uploadFile",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "source": "D:\\\MyStorage\\\app.js",
          "destination": "/Library/app.js"
        }
      ]
    }
  ]
}

Delete a file from the device

{
  "methods": [
    {
      "name": "deleteFile",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "destination": "/Library/app.js"
        }
      ]
    }
  ]
}

Retrieve the contents of a file from the device

{
  "methods": [
    {
      "name": "readFile",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "path": "/Library/app.js"
        }
      ]
    }
  ]
}

Download a file from the device to the local system

{
  "methods": [
    {
      "name": "downloadFile",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "source": "/Library/logs/app.js",
          "destination": "D:\\\MyStorage\\\app.js"
        }
      ]
    }
  ]
}

Make folder inside the device

{
  "methods": [
    {
      "name": "createDirectory",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "path": "/Library/MyStorage"
        }
      ]
    }
  ]
}

Download folder from the device to the local system

{
  "methods": [
    {
      "name": "downloadDirectory",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "source": "/Library",
          "destination": "D:\\\Downloads\\MyStorage"
        }
      ]
    }
  ]
}

Delete folder inside device

{
  "methods": [
    {
      "name": "deleteDirectory",
      "args": [
        {
          "appId": "com.sample.MyApp",
          "path": "/Library/MyStorage"
        }
      ]
    }
  ]
}

Start printing the device log for a device

{
  "methods": [
    {
      "name": "log"
    }
  ]
}

Post a notification to a device. (As if it was dispatched via NSNotificationCenter). This call is non-blocking.

Post

{
  "methods": [
    {
      "name": "postNotification",
      "args": [
        {
          "commandType": "PostNotification",
          "notificationName": "com.sample.MyApp:NativeScript.Debug.AttachAvailabilityQuery"
        }
      ]
    }
  ]
}

Observe

{
  "methods": [
    {
      "name": "postNotification",
      "args": [
        {
          "commandType": "ObserveNotification",
          "notificationName": "com.sample.MyApp:NativeScript.Debug.AttachAvailable"
        }
      ]
    }
  ]
}

Post a notification to a device and await its response. This call is blocking.

{
  "methods": [
    {
      "name": "awaitNotificationResponse",
      "args": [
        {
          "socket": 10,
          "timeout": 9,
          "responseCommandType": "RelayNotification",
          "responsePropertyName": "Name"
        }
      ]
    }
  ]
}

Start an application.

{
  "methods": [
    {
      "name": "start",
      "args": [
        {
          "appId": "com.sample.MyApp"
        }
      ]
    }
  ]
}

Stop a running application.

{
  "methods": [
    {
      "name": "stop",
      "args": [
        {
          "appId": "com.sample.MyApp"
        }
      ]
    }
  ]
}

JavaScript interface

A detailed definition of all the methods can be found here

Additional information

Upon launching the node-ios-devices binary it will immediately start a detached thread with a run loop so that it can proactively detect attaching and detaching of devices.
All requests to the binary are executed in separate threads
Error understanding: Whenever an error is raised, for example:

{
  "deviceId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "error": {
    "code": -402653081,
    "deviceId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "message": "Could not install application"
  },
  "id": "1"
}

How does one go about deciphering the error code?

First off you'd need to convert the code to hex (this can easily be done with a calculator application for example). So -402653081 becomes FFFFFFFFE8000067 or E8000067 if we disregard the sign. Using this hex code you can look the error up in this header file. In this example we can see that this is a kAMDAPIInternalError, hence an internal error.