Note
This API has been available since API level 13.
This API has been available since API level 13.
com.webos.service.nettools
API Summary
Provides a selection of standard network tools.
Overview of the API
Provides a set of standard network utility tools for applications so that they don't have to deal directly with low level network system tools.
These tools may be easier for an application developer to use than trying to directly call the system tools, since then the application does not have to rely on a particular shell command being present. However the set of tools provided is quite limited.
The implementation of these tools either calls through to standard system utilities or to standard libc functions.
It is expected that the user have a solid understanding of networking before attempting to use these tools.
These APIs may be called by any application which has sufficient permissions to call private APIs.
Note: The set of URLs accepted by the relevant methods is very restricted, please refer to the detailed description for each method for the allowable set.
Where appropriate, IPv4 and IPv6 support is provided.
Methods
arping
ACG: nettools.operation
- Added:
API level 13
Description
Performs an ARP request to resolve IP address to mac address which can then be used to detect IP address conflicts.
The implementation uses a call to the system arping utility: "arping -c 1 -f -I ifName ipaddress".
arping is part of the iputils package available from http://www.skbuff.net/iputils/.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| ifName | Required | String | Indicates the network interface to use for the arping command. Example: eth0 |
| ipAddress | Required | String | Indicates the IP address for which the mac address needs to be resolved Example: 192.168.1.100 |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| foundMacAddress | Optional | String | Indicates any MAC address if found for the IP address. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | arping failed: unreachable network | The network is unreachable, possibly due to no internet connection or the network interface is down. |
| None | arping failed: mac address not found | The mac address for the given ipAddress was not found. |
| None | Unknown error | Error in the actual system call for arping or error in parsing response json object. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/arping '{
"ifName":"eth0",
"ipAddress":"10.195.248.213"
}'
Response:
{
"returnValue":true,
"foundMacAddress":"B8:CA:3A:81:A2:5B"
}
checkhttp
ACG: nettools.operation
- Added:
API level 13
Description
Creates a TCP socket and checks if it can successfully connect to the hostURL using the standard http port (port 80).
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| hostUrl | Required | String | Indicates the URL on which to test the http connection. The URL must start with "www." and must end with one of the following:
Example: www.lge.com |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorrText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Invalid hostUrl | The hostUrl does not conform to the supported URL format, i.e it must start with "www." and end with ".org" or ".com" or ".net" or ".gov" or ".edu" or ".jp" or ".int" or ".mil". |
| None | Error in http connection | Error in testing the http connection. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/checkhttp '{
"hostUrl":"www.lge.com"
}'
Response:
{
"returnValue":true
}
createVlan
ACG: nettools.management
- Added:
API level 13
Description
Creates a VLAN for the provided index and interface.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| index | Required | String | VLAN ID, range 1 ~ 4094. |
| interface | Required | Object: interface | Interface details to create VLAN tag. |
| method | Optional | String | "dhcp" or "manual" |
| address | Optional | String | Sets a new IP address. Note: Only when 'method' is specified as 'manual'. |
| netmask | Optional | String | Sets a new netmask. Note: Only when 'method' is specified as 'manual'. |
| gateway | Optional | String | Sets a new gateway IP address. Note: Only when 'method' is specified as 'manual'. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 105 | Invalid Method | This message implies that there was an error because passed method does not exist. |
| 106 | Invalid IP address | This message implies that there was an error because passed address parameters does not have a valid data. |
| 107 | Invalid Netmask | This message implies that there was an error because passed netmask parameters does not have a valid data. |
| 108 | Invalid Gateway | This message implies that there was an error because passed gateway parameters does not have a valid data. |
| 109 | VLAN Index already Exist | This message implies that there is aready a VLAN Tag with the same index requested to create. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/createVlan '{
"interface":{
"name":"eth0"
},
"index":9
}'
Response:
{
"returnValue": true
}
deleteVlan
ACG: nettools.management
- Added:
API level 13
Description
Provided VLAN index will be deleted for the provided interface, if present.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| index | Required | String | VLAN ID, range 1 ~ 4094. |
| interface | Required | Object: interface | Interface details to delete VLAN tag |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 110 | VLAN Index does not Exist | This message implies that there is no VLAN tag present for passed index. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/deleteVlan '{
"interface":{
"name":"eth0"
},
"index":9
}'
Response:
{
"returnValue": true
}
gethostname
ACG: nettools.operation
- Added:
API level 13
Description
Gets the hostname for the system.
The implementation uses a call to gethostname() in glibc.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| subscribe | Optional | Boolean | Indicates if subscribe to get the notifications. Possible values are:
Default: false |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| hostname | Required | String | Indicates the current hostname of the system. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| hostname | Required | String | Indicates the current hostname of the system. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Error in calling gethostname | Error in calling the actual system call gethostname(). |
| None | Unknown error | Error in parsing the response json object. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/gethostname '{}'
Response:
{
"hostname":"nnnn6",
"returnValue":true
}
ping
ACG: nettools.operation
- Added:
API level 13
Description
"Ping" an IPv4 network address or hostname to determine if it is reachable. The maximum wait time is 5 seconds.
The implementation uses a call to the system ping command: "ping -c 1 -w 5 hostname ifName".
Note: To ping an IPv6 address, use the ping6() method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| hostname | Required | String | Indicates the hostname or network address to ping. Network address must be IPv4, IPv6 is not supported. Example: www.lge.com or 10.10.1.1 |
| ifName | Optional | String | Interface on which to issue the ping. Example: eth0 Note: If unspecified it will use the interface with the default gateway. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
| ipaddress | Optional | String | Indicates the IP address requested for ping. |
| time | Optional | Number | Indicates the time taken for the ping response. |
| hostname | Optional | String | Indicates the hostname or network address used for ping. |
| bytes | Optional | Number | Indicates the number of bytes - Ping packet size. |
| ttl | Optional | Number | Indicates the time to live. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Ping failed: poor network | The number of packets received during the ping was less than the number of packets sent. |
| None | Ping failed: unknown host | Ping failed because it could not recognize the host. |
| None | Ping failed: network unreachable | Ping failed because it could not reach the host, most likely due to no internet connection. |
| None | Unknown error | Error in the actual system call to ping. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/ping '{
"hostname":"127.0.0.1",
"ifName":"lo"
}'
Response:
{
"ipaddress": "127.0.0.1",
"time": 0.102,
"hostname": "127.0.0.1",
"returnValue": true,
"bytes": 64,
"ttl": 64
}
ping6
ACG: nettools.operation
- Added:
API level 13
Description
Pings an IPv6 network address or host name to determine if it is reachable. The maximum amount of time the ping waits for a reply is 5 seconds.
Internally, the implementation uses a call to the system ping command: "ping6 -c 1 -w 5 hostname ifName".
Note: To ping an IPv4 address, use the ping() method.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| hostname | Required | String | Indicates the hostname or the network address to ping. Note: It must be a valid IPv6 address. Example: ac78::cgff:baff:eghh:hh05 |
| ifName | Optional | String | Indicates the interface through which the ping is to be issued. Example: eth0 Note: By default, the ping is issued on the default gateway. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" of this method for details. |
| ipaddress | Optional | String | Indicates the IP address of the system that is pinged. |
| time | Optional | Number | Indicates the time taken for the ping response in milliseconds. |
| hostname | Optional | String | Indicates the hostname or network address that is pinged. |
| bytes | Optional | Number | Indicates the ping packet size in bytes. |
| ttl | Optional | Number | Indicates the time to live. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Ping failed: poor network | The number of packets received during the ping was less than the number of packets sent. |
| None | Ping failed: unknown host | Ping failed because it could not recognize the host. |
| None | Ping failed: network unreachable | Ping failed because it could not reach the host, most likely due to no internet connection. |
| None | Unknown error | Error in the actual system call to ping. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/ping6 '{
"hostname":"fe80::a8bb:ccff:fedd:ee01"
}'
Response:
{
"ipaddress":"fe80::a8bb:ccff:fedd:ee01",
"time":0.102,
"hostname":"fe80::a8bb:ccff:fedd:ee01",
"returnValue":true,
"bytes":64,
"ttl":64
}
resolvehostname
ACG: nettools.operation
- Added:
API level 13
Description
Performs a DNS request to resolve hostname to list all IP addresses that it maps to. This will return IPv4 or IPv6 addresses depending upon what the network interface supports.
The implementation uses a call to the POSIX.1-2001 getaddrinfo() function, please refer to RFC 2553 (https://www.ietf.org/rfc/rfc2553.txt).
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| hostname | Required | String | Indicates the hostname to be resolved. The hostname must start with "www." and must end with one of the following:
Example: www.lge.com |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| resolvedIpAddress | Optional | String array | Indicates the list of resolved IP addresses. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Invalid hostname | If the hostname does not conform to the supported URL format, i.e it must start with "www." and end with ".org" or ".com" or ".net" or ".gov" or ".edu" or ".jp" or ".int" or ".mil". |
| None | Error in resolving hostname | Error in the actual system call to resolve hostname. |
| None | Unknown error | Error in parsing response json object. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/resolvehostname '{
"hostname":"www.lge.com"
}'
Response:
{
"resolvedIpAddresses":[
"172.229.208.172"
],
"returnValue":true
}
sethostname
ACG: nettools.management
- Added:
API level 13
Description
Sets a new hostname for the system.
The implementation uses a call to sethostname() in glibc.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| hostname | Required | String | Indicates the new hostname for the system. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| None | Error in setting /etc/hostname | Error in saving the new hostname in the /etc/hostname file. |
| None | Error in calling sethostname | Error in the actual system call sethostname(). |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.nettools/sethostname '{
"hostname":"nnnn6"
}'
Response:
{
"returnValue":true
}
Objects
interface
Provides the name of interface
Sample example for "interface" object :
{
"name":"eth0"
}
Name | Required | Type | Description |
|---|---|---|---|
| name | Required | String | Name of the interface |
API Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 101 | Unknown error | This message implies that there was an error to perform the operation. |
| 102 | Could not validate json message against schema | This message implies that there was an error because parameters passed to a method were not following the schema format. |
| 103 | Invalid VLAN Index | This message implies that there was an error because passed index parameters does not have a valid data. |
| 104 | Invalid Interface | This message implies that there was an error because passed interface does not exist. |