chromeos/ash/components/dbus/shill/README.md
The Shill D-Bus clients are a critical component of the Chrome OS network stack that facilitate communication between applications and system components with Shill via D-Bus. These clients provide a high-level API that enables interaction with the following Shill services:
All of the clients used to interact with these Shill services are instantiated as singletons, and all usage of their interfaces must happen on the same thread that was used to instantiate the client.
For more information about Shill, the connection manager for ChromeOS, see the official README.md.
ChromeOS interacts with Shill services through their corresponding Shill D-Bus
clients. To initialize all Shill D-Bus clients, the
shill_clients::Initialize()
function is used. This function is called from the
ash::InitializeDBus()
function during the Ash/Chrome UI early
initialization
stage as there are many other components that depend on Shill clients. The
shill_clients::Initialize() function sets up a single global instance of each
Shill D-Bus client which are accessible by public static functions provided by
each client individually, e.g. ShillManagerClient::Get(). Similarly,
the
shill_clients::InitializeFakes()
function is also provided which initializes the global singleton instance with fake
implementations. This function is mostly used for unit tests or ChromeOS-Linux
build. Finally, during Ash/Chrome UI shutdown, the
ash::ShutdownDBus()
function is called, and the
shill_clients::Shutdown()
function is used to bring down all the Shill D-Bus clients.
The ShillManagerClient
class provides the interface for interacting with the Shill manager service
interface which is the top-level singleton exposed by Shill that provides
global system properties. It enables Chrome to:
For detailed documentation on the Shill Manager D-Bus API, please refer to manager-api.txt.
The ShillDeviceClient class provides an interface for performing operations on different device types. Devices are how Shill represents network interface that is used for different technologies (Cellular, WiFi, Ethernet, etc) within the platform layer. It maintains a map of ShillClientHelpers for each device type and through those helpers, makes calls to the corresponding dbus proxy objects. It enables Chrome to:
For detailed documentation on the Shill Device DBus API, please refer to device-api.txt
The ShillIPConfigClient
class provides an interface for interacting with the Shill IPConfig interface
which is the top-level singleton exposed by Shill that provides Layer 3
configuration. It enables Chrome to:
For detailed documentation on the Shill IPConfig DBus API, please refer to ipconfig-api.txt.
The ShillProfileClient
class provides an interface for interacting with the Shill profile interface
which is the top-level singleton exposed by Shill that provides Layer 3
configuration. It enables Chrome to:
For detailed documentation on the Shill Profile DBus API, please refer to profile-api.txt.
The
ShillServiceClient
class provides the interface for interacting with the Shill service service.
Services are how Shill represents network configurations and connections through
an associated device within the Platform layer and can be thought of the source
of truth for these network configurations
and connections on ChromeOS devices. While Chrome, i.e. the Software layer,
generally relies on the read-only
NetworkState
class for network properties, the NetworkState class is effectively just a
cache of a Shill service.
The ShillServiceClient class provides a thorough interface for interacting
with Shill services:
For detailed documentation on the Shill Service D-Bus API, please refer to service-api.txt.
Each of the clients discussed provides a testing interface that can be used to
effectively configure Shill to be in a specific, custom state during testing.
These testing interfaces are declared within the corresponding client class and
can be used within tests in multiple ways. For example, the
NetworkTestHelperBase
class can be used within tests which will initialize the entire network stack,
including the test interfaces for each of the clients.
The
ShillManagerClient::TestInterface
class supports a wide variety of functionality that is very useful when testing:
The ShillManagerClient::TestInterface interface is implemented by
FakeShillManagerClient.
The ShillDeviceClient::TestInterface provides various functions that help during testing:
The ShillDeviceClient::TestInterface interface is implemented by FakeShillDeviceClient
The
ShillIPConfigClient::TestInterface
class supports adding fake IPConfig entries during testing. This interface is
implemented by
FakeShillIPConfigClient.
The ShillProfileClient::TestInterface
allows you to add fake profile entries for ChromeOS unit testing
purposes. This interface is implemented in the FakeShillProfileClient.
The
ShillServiceClient::TestInterface
class provides a number of different APIs for interacting with services:
The ShillServiceClient::TestInterface interface is implemented by
FakeShillServiceClient.