com.webos.service.connectionmanager

API Summary

This API is used by webOS apps and services to manage wired and wireless network connections. 

Overview of the API

(click to expand)

About com.webos.service.connectionmanager API:
​​The connectionmanager API provides methods to get and set the overall network connection status including setting IPv4/IPv6 and DNS parameters.
This API can be used for both wired and wireless interfaces.

About webos-connman-adapter daemon:

webos-connman-adapter is a daemon which acts as an interface between a daemon for managing internet connections called connman, and the rest of the webOS world. The reason we need this wrapper daemon is because connman communicates via dbus whereas the webOS apps/services require luna-service2(LS2) for interprocess communication. So, internally webos-connman-adapter communicates to connman via dbus but provides the LS2 interface to all the webOS apps/services so that they can get all the network related information as well as manage the connections.


Open All


findProxyForURL

Description

Provides the proxy server that was used to reach the target URL.

Parameters

Name

Required

Type

Description

url Required String

The complete URL to be checked for proxy access.

host Required String

The hostname component of a URL for convenience

Call Returns

Name

Required

Type

Description

proxy Required String

The proxy address for the target URL.

For example, "PROXY <proxy1>:1080". 

For directly connected sites, the value "DIRECT" is returned.

returnValue Required String

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.
errorCode Optional String

The error code for the failed operation.

errorText Optional String

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

Error References

Error Code

Error Text

Error Description

205 Error in finding proxy for url

Error in finding the proxy for the provided URL and host.

Example

Example 1: Example for direct call.

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/findProxyForURL

'{

    "url":"http://webosose.org",

    "host":"webosose.org"

}'

Example 2: Example for call through a proxy.

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/findProxyForURL

'{

    "url":"http://www.webos.com",

    "host":"www.webos.com"

}'
 


getinfo

Description

This method is used to get the MAC addresses for the Wi-Fi and wired interfaces.

When subscribed, getInfo periodically checks for any changes in interface MAC addresses and notifies subscribers when changes are detected. The check interval is 1 second.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Subscribe to be notified of changes in interfaces. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

Default value: false

Call Returns

Name

Required

Type

Description

wifiInfoOptionalObject: wifiInfo

Information about the Wi-Fi interface.

wiredInfoOptionalObject: wiredInfo

Information about the wired interface. 

returnValueRequiredBoolean

Indicates the status of 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
subscribedRequiredBoolean

Indicates if subscribed to get notified.

  • true - Subscribed for changes
  • false - Not subscribed
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Subscription Returns

Name

Required

Type

Description

wifiInfoOptionalObject: wifiInfo

Information about the Wi-Fi interface.

wiredInfoOptionalObject: wiredInfo

Information about the wired interface. 

subscribedRequiredBoolean

Always true in case of subscription response.

returnValueRequiredBoolean

Always true in case of subscription response

Error References

Error Code

Error Text

Error Description

1Unknown error

This message implies that there was an internal error when parsing the JSON object being prepared as a response (extremely unlikely).

Example

Example response for a successful call:

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/getinfo {}

{

"wifiInfo": {

"macAddress": "2C:54:CF:E9:BD:BF"

},

"returnValue": true

}


getStatus

Description

Provides the current status of the Wi-Fi and wired network connections on the system.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean

Subscribe to this method to get notified on changes to the status of the network connection. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

Default value: false

Call Returns

Name

Required

Type

Description

isInternetConnectionAvailable Required Boolean

Indicates if internet connection is available. Possible values are:

  • true - Internet connection available
  • false - Internet connection is unavailable
wifi Required Object: wifi

Information about the Wi-Fi connection.

wired Required Object: wired

Information about the wired connection.

offlineMode Optional String

Indicates if the system is offline. Possible values are:

  • enabled - System is offline
  • disabled - System is online
subscribed Required Boolean

Indicates if subscribed to get notified on changes to the status of the network connection. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed
returnValue Required Boolean

Indicates the status of 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.
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

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

Subscription Returns

Name

Required

Type

Description

isInternetConnectionAvailable Required Boolean

Indicates if internet connection is available. Possible values are:

  • true - Internet connection available
  • false - Internet connection is unavailable
wifi Required Object: wifi

Information about the Wi-Fi connection.

wired Required Object: wired

Information about the wired connection.

returnValue Required Boolean

Value is always true (since subscription is only displayed on successful operations).

subscribed Required Boolean

Indicates if subscribed to get notified on changes to the status of the network connection. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed

Error References

Error Code

Error Text

Error Description

1 Unknown error

Error when parsing the response JSON object.

4 Connman manager is not available

Error because webos-connman-adapter was unable to communicate with the connman daemon.

Example

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/getStatus {}
{
    "returnValue": true,
    "offlineMode": "disabled",
    "wired": {
        "netmask": "255.255.255.0",
        "dns1": "192.168.0.102",
        "ipAddress": "192.168.0.10",
        "proxyinfo": {
            "method": "direct"
        },
        "onInternet": "no",
        "method": "fixed",
        "state": "connected",
        "gateway": "192.168.0.1",
        "interfaceName": "eth0",
        "plugged": true
    },
    "wifi": {
        "state": "disconnected"
    },
    "subscribed": false,
    "isInternetConnectionAvailable": false
}


setdns

Description

The setdns method changes the DNS servers for the network. If a SSID value is not provided in the request then the modifications are applied to the wired connection.

Parameters

Name

Required

Type

Description

dnsRequiredString array

The dns array contains the IP addresses of the DNS servers that need to be changed. 

ssidOptionalString

The ssid parameter contains the SSID of the Wi-Fi connection to be modified.

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 "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error References

Error Code

Error Text

Error Description

1Unknown error

This message implies that there was an error in setting the dns for the given network.

3Invalid parameters

This message implies that there was an error because one or more invalid ip addresses were passed in the dns parameter.

4Connection service unavailable

This message implies that there was an error because webos-connman-adapter was not able to talk to the connman daemon.

136No connected network

This message implies that there was an error because no network was found with the provided ssid.

Example

Example response for a successful call:

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setdns '{"dns":["192.45.67.128"]}'

{

    "returnValue": true

}


setipv4

Description

The setipv4 method is used to modify the parameters of an IPv4 connection (wired or Wi-Fi). If a SSID value is not provided in the request, the modifications are applied to the wired connection only.

Note: At least one of the following parameters must be provided: method, address, netmask or gateway.

Parameters

Name

Required

Type

Description

method Optional String

The method parameter specifies the way the IPv4 parameter should be changed. The allowed values are: 

  • dhcp 
  • manual
address Optional String

If specified, sets a new IP address.

netmask Optional String

If specified, sets a new netmask.

gateway Optional String

If specified, sets a new gateway IP address.

ssid Optional String

The ssid parameter specifies the Wi-Fi connection to modify. If absent, the wired connection is changed.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of 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
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

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

Error References

Error Code

Error Text

Error Description

1 Unknown error

This message implies that there was an error in setting ipv4 parameters for the given network.

3 Invalid parameters

This message implies that there was an error because of an invalid ip address value in the address, netmask or gateway parameters.

4 Connman service unavailable

This message implies that there was an error because webos-connman-adapter was not able to talk to the connman daemon.

102 Network not found

This message implies that there was an error because the network with the given ssid was not found.

Example

Example responses for a successful call:

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setipv4

'{

"ssid": "MyTestAP",

"method": "manual",

"address": "192.168.1.42",

"netmask": "255.255.255.0",

"gateway": "192.168.1.1"

}'

{

"returnValue": true

}

 

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setipv4 '{"ssid": "MyTestAP", "method": "dhcp"}'

{

"returnValue": true

}


setipv6

Description

The setipv6 method modifies the parameters of an IPv6 connection (wired or Wi-Fi). If a SSID value is not provided in the request then the modifications are applied to the wired connection only.

Note: At least one of the following parameters must be provided: method, address, prefixLength or gateway.

Parameters

Name

Required

Type

Description

addressOptionalString

If specified, sets a new IP address.

gatewayOptionalString

If specified, sets a new gateway IP address.

methodRequiredString

The method parameter specifies the way the IPv4 parameter should be changed. The allowed values are: 

  • auto 
  • manual
prefixLengthOptionalNumber (int32_t)

If specified, sets the prefixLength for the IPv6 address.

ssidOptionalString

The ssid parameter specifies the Wi-Fi connection to modify. If absent, the wired connection is changed.

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 "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error References

Error Code

Error Text

Error Description

1Unknown error

This message implies that there was an error in setting ipv6 parameters for the network with the given ssid.

3Invalid parameters

This message implies that there was an error because of an invalid ip address value in address or gateway.

4Connman service unavailable

This message implies that there was an error because webos-connman-adapter was not able to communicate with the connman daemon.

102Network not found

This message implies that there was an error because a network with the given ssid was not found.

Example

Example responses for successful calls:

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setipv6

'{

"ssid": "MyTestAP",

"method": "manual",

"address": "2001:db8:85a3:8d3:1319:8a2e:370:7348"

}'

{

"returnValue": true

}

 

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setipv6 '{"ssid": "MyTestAP", "method": "auto"}'

{

"returnValue": true

}


setProxy

Description

Specifies the proxy server for the network.

Parameters

Name

Required

Type

Description

method Required String

The method to get the actual system configuration for proxy servers. Possible values are:

  • direct - Direct access. No proxy information required to be specified.
  • auto - Automatically configure the proxy. Uses the "url" parameter.
  • manual - Manually configure the proxy information. Uses the "servers" parameter and optionally the "excludes" parameter.
url Optional String

Automatic proxy configuration URL. If no URL is specified, DHCP/WPAD auto-discover will be tried.

If DHCP/WPAD auto-discover methods also fail, then method will be set to "direct".

Note: Used when method is set to "auto".

servers Optional String array

List of proxy URIs. An URI without a protocol will be interpreted as the generic proxy URI.

Note: Used when method is set to "manual".

excludes Optional String array

List of hosts which can be accessed directly. 

Note: Used when method is set to "manual".

ssid Optional String

The SSID of the Wi-Fi connection for which the proxy must be set. If no value is provided, the proxy is applied to the wired connection.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of 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.
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

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

Error References

Error Code

Error Text

Error Description

1 Unknown Error

Error in setting the proxy.

3 Invalid parameters

Error because the "servers" parameter is mandatory if the method is "manual".

4 Connman service unavailable

Error because webos-connman-adapter was not able to communicate with the connman daemon.

136 No connected network

Error because no network was found with the provided SSID.

Example

Example responses for a successful call:

luna-send -n 1 -f luna://com.webos.service.connectionmanager/setProxy '{"method":"direct"}'
{
    "returnValue": true
}

luna-send -n 1 -f luna://com.webos.service.connectionmanager/setProxy '{"method": "auto", "url":"http://webosose.org/proxy.pac"}'
{
    "returnValue": true
}

luna-send -n 1 -f luna://com.webos.service.connectionmanager/setProxy '{"method":"manual", "servers":["10.10.10.10:8080"], "excludes" : ["webosose.org"]}'

{
    "returnValue": true
}


setstate

Description

The setstate method enables or disables the state of either or both the Wi-Fi and wired connections on the system.

While all parameters are optional, at least one parameter is required, or the method will return error.

Parameters

Name

Required

Type

Description

wifiOptionalString

Set it to enabled to enable Wi-Fi.

Set it to disabled to disable Wi-Fi.

Any other value will result in an error.

wiredOptionalString

Set it to enabled to enable wired.

Set it to disabled to disable wired.

Any other value will lead to an error.

offlineModeOptionalString

Set it to enabled to enable offline mode.

Set it to disabled to disable offline mode.

Any other value will lead to an error.

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 "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error References

Error Code

Error Text

Error Description

3Invalid parameters

This message implies that there was an error occurs when either the wifi or wired parameters have a value other than enabled or disabled.

4Connman service unavailable

This message implies that there was an error because webos-connman-adapter was not able to talk to the connman daemon.

Example

Example response for a successful call:

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setstate '{"wifi":"enabled"} '

{

"returnValue": true

}


setTechnologyState

Description

This method will let the user enable or disable the available connection interfaces which can be:

  • Wired (ethernet)
  • Wi-Fi

If a technology is not available on the device, an error will be returned.

The current status of the connection interfaces are reported through the getStatus method. Only one of the listed properties is allowed to be specified.

Parameters

Name

Required

Type

Description

enabledOptionalString array

List of technologies to enable. The array can contain: wifi, ethernet.

disabledOptionalString array

List of technologies to disable. The array can contain: wifi, ethernet.

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 "errorCode" and "errorText" fields for details
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error References

Error Code

Error Text

Error Description

4Connman service unavailable

This message implies that there was an error because webos-connman-adapter was not able to communicate with the connman daemon.

163Failed to enable/disable one or more technologies

This message implies that there was an error because the service failed while trying to enable or disable any of the specified technologies.

The most common cause is that the technology is not available on the device.

Note: Getting this error does not mean that no technology changed its state. The list is processed in order and if the last one for example failed to get enabled/disabled, all of the others would have correctly been processed and switched to their state according to the request.

181Not supported

This message implies that technology exists, but enabling or disabling it is not supported on this platform.
Note: Getting this error does not mean that no technology changed its state. 
The list is processed in order and if the last one for example failed to get enabled/disabled, all of the others would have correctly been processed and switched to their state according to the request.

Example

# luna-send -n 1 -f luna://com.webos.service.connectionmanager/setTechnologyState '{"enabled":["wifi"]}'

{

    "returnValue": true

}


Objects

wifi

The wifi object provides details on the status of the Wi-Fi connection. If the Wi-Fi connection is available then all the fields of this object will contain relevant information. If the Wi-Fi connection is not available then the state field of this object will be set to disconnected, and is the only value that is returned to the calling app.

An example object would look like this:

{
    "netmask": "255.255.255.0",
    "dns1": "192.168.1.1",
    "ipAddress": "192.168.1.61",
    "onInternet": "yes",
    "method": "dhcp",
    "ssid": "TestAP",
    "state": "connected",
    "gateway": "192.168.1.1",
    "interfaceName": "wlan0",
    "proxyInfo" :
    {
        "servers": ["10.10.10.10:80"],
        "method": "manual",
        "excludes": ["webosose.org"]
    }
}

Name

Required

Type

Description

dns Optional String array

List of IP Addreses of the DNS servers for this Wi-Fi connection.

gateway Optional String

The IP address of the network gateway.

interfaceName Optional String

Name of the Wi-Fi Interface name in use. For example, wlan0.

ipAddress Optional String

The IP address associated with the Wi-Fi connection.

method Optional String

If the IP address was assigned using the manual mode, method will contain Manual.

If the IP Address was assigned through DHCP, method will contain dhcp.

netmask Optional String

The net mask value for the Wi-Fi connection.

onInternet Optional String

The captive portal technique forces an HTTP client on a network to see a special web page (usually for authentication purposes) before using the Internet normally. Captive portals are used at most Wi-Fi hotspots.The onInternet will contain one of the following values:

  • yes - indicating the Wi-Fi connection is connected to the Internet.
  • no - indicating the Wi-Fi connection is not connected to the Internet.
ssid Optional String

The SSID of the connected service (if known).

state Required String

If the W-iFi connection is available it will be set to connected.

If the Wi-Fi connection is not available, it will be set to disconnected .

proxyInfo Optional Object: proxyInfo

The actual system configuration of Proxy servers.

wifiInfo

This object contains the MAC address for the WI-Fi interface.

An example object would like this:

{
  "macAddress": "aa:bb:cc:dd:ee"
}

Name

Required

Type

Description

macAddress Required String

MAC address of the Wi-Fi interface.

wired

The wired object provides details on the status of the wired connections.

If the wired connection is available then all the fields of this object contain the relevant information. If the wired connection is not available then the state field of this object will be set to disconnected and is the only value that is returned to the calling app.

An example would look like:

{
    "netmask": "255.255.255.0",
    "dns1": "192.168.100.10",
    "dns2": "8.8.8.8",
    "ipAddress": "192.168.100.204",
    "dns3": "8.8.4.4",
    "onInternet": "yes",
    "method": "dhcp",
    "state": "connected",
    "gateway": "192.168.100.1",
    "interfaceName": "eth0",
    "plugged": true,
    "proxyInfo" :
    {
        "servers": ["10.10.10.10:80"],
        "method": "manual",
        "excludes": ["webosose.org"]
    }          
}

Name

Required

Type

Description

dns Optional String array

List of IP Addreses of the DNS servers for this wired connection.

gateway Optional String

The IP address of the network gateway.

interfaceName Optional String

Name of the wired Interface name in use. For example, eth0.

ipAddress Optional String

The IP address associated with the wired connection.

method Optional String

If the IP address was assigned using the manual mode, method will contain Manual.

If the IP Address was assigned through DHCP, method will contain dhcp.

netmask Optional String

The net mask value for the wired connection.

plugged Required Boolean

If Ethernet cable is plugged, plugged will contain true.

If Ethernet cable is unplugged, plugged will contain false.

onInternet Optional String

The captive portal technique forces an HTTP client on a network to see a special web page (usually for authentication purposes) before using the Internet normally. Captive portals are used at most Wi-Fi hotspots.The onInternet will contain one of the following values:

  • yes - indicating the Wired connection is connected to the Internet.
  • no - indicating the Wired connection is not connected to the Internet.
state Required String

If the wired connection is available it will be set to connected.

If the wired connection is not available, it will be set to disconnected .

proxyInfo Optional Object: proxyInfo

The actual system configuration of Proxy servers.

wiredInfo

The object containing the MAC address of the wired interface.

An example would look like:

{
  "macAddress": "aa:bb:cc:dd:ee"
}

Name

Required

Type

Description

macAddress Required String MAC address of wired interface

ipInfo

The object containing IP configuration information.

An example would look like:

{
    "subnet": "255.255.255.0",
    "dns": [ "192.168.100.10" ],
    "address": "192.168.100.204",
    "gateway": "192.168.100.1",
    "interface": "eth0"
}

Name

Required

Type

Description

interface Required String

Network interface to which this configuration is to be applied.

address Optional String

Address used for the configuration.

subnet Required String

Subnet mask.

gateway Required String

Address of the network gateway.

dns Required String array

List of DNS servers used for this IP configuration.

proxyInfo

This object contains the actual system configuration for proxy servers.

Sample "proxyInfo" object:

{
    "servers": ["10.10.10.10:80"],
    "method": "manual",
    "excludes": ["webosose.org"]
}

Name

Required

Type

Description

method Required String

The method to get the actual system configuration for proxy servers. Possible values are:

  • direct - Direct access. No proxy information required to be specified.
  • auto - Automatically configure the proxy. Uses the "url" parameter.
  • manual - Manually configure the proxy information. Uses the "servers" parameter and optionally the "excludes" parameter.
url Optional String

Automatic proxy configuration URL. If no URL is specified, DHCP/WPAD auto-discover will be tried.

If DHCP/WPAD auto-discover methods also fail, then method will be set to "direct".

Note: Used when method is set to "auto".

servers Optional String array

List of proxy URIs. An URI without a protocol will be interpreted as the generic proxy URI.

Note: Used when method is set to "manual".

excludes Optional String array

List of hosts which can be accessed directly. 

Note: Used when method is set to "manual".


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.