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

resolvehostname

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

Parameters

Name

Required

Type

Description

hostnameRequiredString

Indicates the hostname to be resolved.

The hostname must start with "www." and must end with one of the following:

  • .org
  • .com 
  • .net 
  • .gov
  • .edu
  • .jp
  • .int
  • .mil

Example: www.lge.com

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorText" field for details.
resolvedIpAddressOptionalString array

Indicates the list of resolved IP addresses.

errorTextOptionalString

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

NoneInvalid 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".

NoneError in resolving hostname

Error in the actual system call to resolve hostname.

NoneUnknown error

Error in parsing response json object.

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/resolvehostname '{
   "hostname":"www.lge.com"
}'

Response:

{
   "resolvedIpAddresses":[
      "172.229.208.172"
   ],
   "returnValue":true
}

ping

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

hostnameRequiredString

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

ifNameOptionalString

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

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

ipaddressOptionalString

Indicates the IP address requested for ping.

timeOptionalNumber

Indicates the time taken for the ping response.

hostnameOptionalString

Indicates the hostname or network address used for ping.

bytesOptionalNumber

Indicates the number of bytes - Ping packet size.

ttlOptionalNumber

Indicates the time to live.

Error Codes Reference

Error Code

Error Text

Error Description

NonePing failed: poor network

The number of packets received during the ping was less than the number of packets sent.

NonePing failed: unknown host

Ping failed because it could not recognize the host.

NonePing failed: network unreachable

Ping failed because it could not reach the host, most likely due to no internet connection.

NoneUnknown error

Error in the actual system call to ping.

Example

# 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

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

hostnameRequiredString

Indicates the hostname or the network address to ping.

Note: It must be a valid IPv6 address. 

Example: ac78::cgff:baff:eghh:hh05

ifNameOptionalString

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

returnValueRequiredBoolean

Indicates the status of operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" of this method for details.

ipaddressOptionalString

Indicates the IP address of the system that is pinged. 

timeOptionalNumber

Indicates the time taken for the ping response in milliseconds. 

hostnameOptionalString

Indicates the hostname or network address that is pinged.

bytesOptionalNumber

Indicates the ping packet size in bytes.

ttlOptionalNumber

Indicates the time to live.

Error Codes Reference

Error Code

Error Text

Error Description

NonePing failed: poor network

The number of packets received during the ping was less than the number of packets sent.

NonePing failed: unknown host

Ping failed because it could not recognize the host.

NonePing failed: network unreachable

Ping failed because it could not reach the host, most likely due to no internet connection.

NoneUnknown error

Error in the actual system call to ping.

Example

# 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
}

checkhttp

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

hostUrlRequiredstring

Indicates the URL on which to test the http connection.

The URL must start with "www." and must end with one of the following:

  • .org
  • .com 
  • .net 
  • .gov
  • .edu
  • .jp
  • .int
  • .mil

Example: www.lge.com

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorText" field for details.
errorrTextOptionalString

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

NoneInvalid 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".

NoneError in http connection

Error in testing the http connection.

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/checkhttp '{
   "hostUrl":"www.lge.com"
}'

Response:

{  
   "returnValue":true
}

arping

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 iputils.

Parameters

Name

Required

Type

Description

ifNameRequiredstring

Indicates the network interface to use for the arping command.

Example: eth0

ipAddressRequiredstring

Indicates the IP address for which the mac address needs to be resolved

Example: 192.168.1.100

Call Returns

Name

Required

Type

Description

returnValueRequiredboolean

Indicates the status of operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
foundMacAddressOptionalString

Indicates any MAC address if found for the IP address.

errorTextOptionalString

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

Nonearping failed: unreachable network

The network is unreachable, possibly due to no internet connection or the network interface is down.

Nonearping failed: mac address not found

The mac address for the given ipAddress was not found.

NoneUnknown error

Error in the actual system call for arping or error in parsing response json object.

Example

# 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"
}

sethostname

Description

Sets a new hostname for the system.

The implementation uses a call to sethostname() in glibc.

Parameters

Name

Required

Type

Description

hostnameRequiredString

Indicates the new hostname for the system.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation.

Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorText" field for details.
errorTextOptionalString

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

NoneError in setting /etc/hostname

Error in saving the new hostname in the /etc/hostname file.

NoneError in calling sethostname

Error in the actual system call sethostname().

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/sethostname '{
   "hostname":"nnnn6"
}'

Response:

{  
   "returnValue":true
}

gethostname

Description

Gets the hostname for the system.

The implementation uses a call to gethostname() in glibc.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Indicates if subscribe to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed

Default: false

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation.

Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorText" field for details.
hostnameRequiredString

Indicates the current hostname of the system.

errorTextOptionalString

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

returnValueRequiredBoolean

Indicates the status of operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
hostnameRequiredString

Indicates the current hostname of the system.

Error Codes Reference

Error Code

Error Text

Error Description

NoneError in calling gethostname

Error in calling the actual system call gethostname().

NoneUnknown error

Error in parsing the response json object.

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/gethostname '{}'

Response:

{  
   "hostname":"nnnn6",
   "returnValue":true
}

createVlan

Description

Creates a VLAN for the provided index and interface.

Parameters

Name

Required

Type

Description

indexRequiredString

VLAN ID, range 1 ~ 4094

interfaceRequiredObject: interface

Interface details to create VLAN tag

methodOptionalString

"dhcp" or "manual"

addressOptionalString

Sets a new IP address.

Note: Only when 'method' is specified as 'manual'.

netmaskOptionalString

Sets a new netmask.

Note: Only when 'method' is specified as 'manual'.

gatewayOptionalString

Sets a new gateway IP address.

Note: Only when 'method' is specified as 'manual'.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Error Codes Reference

Error Code

Error Text

Error Description

105Invalid Method

This message implies that there was an error because passed method does not exist.

106Invalid IP address

This message implies that there was an error because passed address parameters does not have a valid data.

107Invalid Netmask

This message implies that there was an error because passed netmask parameters does not have a valid data.

108Invalid Gateway

This message implies that there was an error because passed gateway parameters does not have a valid data.

109VLAN Index already Exist

This message implies that there is aready a VLAN Tag with the same index requested to create.

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/createVlan '{
   "interface":{
      "name":"eth0"
   },
   "index":9
}'

Response:

{
    "returnValue": true
}

deleteVlan

Description

Provided VLAN index will be deleted for the provided interface, if present.

Parameters

Name

Required

Type

Description

indexRequiredString

VLAN ID, range 1 ~ 4094

interfaceRequiredObject: interface

Interface details to delete VLAN tag

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Error Codes Reference

Error Code

Error Text

Error Description

110VLAN Index does not Exist

This message implies that there is no VLAN tag present for passed index.

Example

# luna-send -n 1 -f luna://com.webos.service.nettools/deleteVlan '{
   "interface":{
      "name":"eth0"
   },
   "index":9
}'

Response:

{
    "returnValue": true
}

Objects

interface

Provides the name of interface

Sample example for "interface" object :

{
         "name":"eth0"
}

Name

Required

Type

Description

nameRequiredString

Name of the interface

API Error Codes Reference

Error Code

Error Text

Error Description

101Unknown error

This message implies that there was an error to perform the operation.

102Could 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.

103Invalid VLAN Index

This message implies that there was an error because passed index parameters does not have a valid data.

104Invalid Interface

This message implies that there was an error because passed interface does not exist.

Contents