# com.innovaphone.devices

The com.innovaphone.devices api enables apps to find and configure specific devices.

## consumeApi

The client consumeApi function is used to access the Api:

    var devicesApi = start.consumeApi("com.innovaphone.devices");
    devicesApi.onmessage.attach(onmessage); // onmessage is called for responses from the API

## Messages

GetGateways
GetAppPlatforms
GetPhones
GetDects
GetDevice
GetDevicePhones
RemoveDevicePhone
HttpGet
GetProvisioningCode

### GetGateways

Retrieves all gateways and IPVAs.

    devicesApi.send({ mt: "GetGateways" });

#### Parameters

string hwIds | A comma separated list of hardware IDs (e.g. "009033010101,009033010102") (optional).
boolean justFxs | If true, just returns devices with FXS support (optional).

### GetGatewaysResult

The result message for the GetGateways request. This also contains App Platforms with an installed App IP which may have an active PBX. The uri already contains the path to this App IP.

#### Parameters

array gateways | An array of device objects.
boolean last | If true, no more GetGatewaysResult messages are to be expected, otherwise more will follow with further devices.
string error | An error string if an error happened (optional).

#### Device object

number id | A unique ID for this device.
string hwId | The hardware ID.
string name | The name of the device, if configured.
number domainId | The domain ID.
string product | The product name, e.g. IP811.
string version | The software and hardware version, e.g. 13r1 dvl [13.A110/13A146/200]
string type | The hardware type (possible types are GW,VA,PHONE,DECT,APP_PLATFORM).
boolean pbxActive | If true, the PBX is enabled on this device.
boolean online | If true, this device is currently online.
boolean hasLeaseLicenses | If true, this device has rental licenses.
boolean rented | If true, this device is a rented device.
boolean rentalWant | If true, this device shall be rented (this flag is set on provisioning a rental device).
boolean rentalStarted | If true, this device is actually rented.
string uri | The URI under which this device is accessible during the current session.
JSON array ethIfs | A JSON array which contains JSON objects describing the network interfaces (see example below).
string appIpPath | The webserver path of an installed App IP. This property can just exist on the APP_PLATFORM device type.
boolean appIpOnline | If true, the App IP is online, otherwise offline (e.g. stopped). This property can just exist on the APP_PLATFORM device type.

##### Example

    {
        "mt":"GetGatewaysResult",
        "last":true,
        "gateways":[
            {
                "id":1,
                "hwId":"0090334100be",
                "name":"Kari2",
                "domainId":2,
                "product":"IP811",
                "version":"13r1 dvl [13.A110/13A146/200]",
                "type":"GW",
                "pbxActive":true,
                "online":true,
                "uri":"http://172.16.14.38/devices/passthrough/0090334100be/fa0550ed-e360-41fb-9714-b212f10ef20c/",
                "ethIfs": [{"if":"ETH0","ipv4":"172.16.14.35","ipv6":"fec0:9033:0:230:290:33ff:fe41:a"},{"if":"ETH1","ipv6":"fe80::290:33ff:fe41:80be"}]
            }
        ]
    }

### GetAppPlatforms

Retrieves all App Platforms.

    devicesApi.send({ mt: "GetAppPlatforms" });

#### Parameters

string hwIds | A comma separated list of hardware IDs (e.g. "029033010101,029033010102") (optional).

### GetAppPlatformsResult

The result message for the GetAppPlatforms request.

#### Parameters

array appPlatforms | An array of device objects.
boolean last | If true, no more GetAppPlatformsResult messages are to be expected, otherwise more will follow with further devices.
string error | An error string if an error happened (optional).

### GetPhones

Retrieves all phones.

    devicesApi.send({ mt: "GetPhones" });

#### Parameters

string hwIds | A comma separated list of hardware IDs (e.g. "029033010101,029033010102") (optional).

### GetPhonesResult

The result message for the GetPhones request.

#### Parameters

array phones | An array of device objects.
boolean last | If true, no more GetPhonesResult messages are to be expected, otherwise more will follow with further devices.
string error | An error string if an error happened (optional).

### GetDects

Retrieves all phones.

    devicesApi.send({ mt: "GetDects" });

#### Parameters

string hwIds | A comma separated list of hardware IDs (e.g. "029033010101,029033010102") (optional).

### GetDectsResult

The result message for the GetDects request.

#### Parameters

array dects | An array of device objects.
boolean last | If true, no more GetDectsResult messages are to be expected, otherwise more will follow with further devices.
string error | An error string if an error happened (optional).

### GetDevice

Retrieves a specific device.

    devicesApi.send({ mt: "GetDevice", hwId: "009033010101" });

#### Parameters

string hwId | A hardware ID.

### GetDeviceResult

The result message for the GetDevice request.

#### Parameters

object device | A device object.
string error | An error string if an error happened (optional).

### GetDevicePhones

Retrieves the provisioned phones of an FXS device.

    devicesApi.send({ mt: "GetDevicePhones", hwId: "009033010101" });

#### Parameters

string hwId | A hardware ID.

### GetDevicePhonesResult

The result message for the GetDevicePhones request.

#### Parameters

array phones | An array of strings, while each string is a provisioned FXS interface.
string error | An error string if an error happened (optional).

### RemoveDevicePhone

Removes a provisioned FXS phone from a gateway.

    devicesApi.send({ mt: "RemoveDevicePhone", hwId: "009033010101", id: "TEL1" });

#### Parameters

string hwId | A hardware ID.
string id | The id/name of the interface retrieved in the array of the GetDevicePhonesResult message.

### RemoveDevicePhoneResult

The result message for the RemoveDevicePhone request.

#### Parameters

string error | An error string if an error happened (optional).

### HttpGet

Executes an HTTP GET request and returns the result.

    devicesApi.send({ mt: "HttpGet", "uri": device.uri + "log.txt" });

#### Parameters

string uri | The absolute URI starting with the uri retrieved inside the device object.

### HttpGetResult

The result message for the HttpGet request.

#### Parameters

### GetProvisioningCode

Gets a provisioning code from Devices to provision a new device.

    devicesApi.send({ mt: "GetProvisioningCode", sip: "maxmuster", category: "Phones" });

#### Parameters

string sip | Will be used for the device name in Devices. (optional)
string category | A name of a provisioning category.
string description | Will be used for the device description in Devices. (optional)
boolean administrative | If true, the provisioned device will get the domain password as administrative password if the domain checkword to set these passwords is checked. (optional, default false)

### GetProvisioningCodeResult

The result message for the GetProvisioningCode request.

#### Parameters

string code | The provisioning code.
string url | The URL which will be used for the sysclient.
string error | An error string if an error happened (optional).

### DeviceProvisioned

This message will be triggered if the device has been actually provisioned. Just works if the websocket session used to create the provisioning code is still active.

#### Parameters

string gateway | The device.
string error | An error string if an error happened (optional).