CommunicationsClient

Client for remote communications services.

Communications services are services than run on one or more remote devices. These can be accessed by creating a CommunicationsClient object and telling it what service it should connect to. A listener object should also be provided which will be called when a connection is established to a service and when it is lost. When a connection is established a proxy object is provided, that can be used to access the service.

All remote services are defined using a Protobuf file. Kotlin code will be automatically generated from this file.

The specified communicationsClientContext provides the client with a Context, a lifecycleOwner and a CommunicationsServiceClientFactory. The CommunicationsServiceClientFactory provides the meta-data to the client to know which service to connect to. This factory is service specific and is automatically generated from the Protobuf definition for that service.

Multiple devices can be connected. All or none of which can provide a particular service. An instance of a service on a particular device is referred to by a unique ServiceProviderId. A ServiceProviderId is always unique to a particular connection to a service. If a service would go down on a device and it would come back up on that same device it will get a new unique ServiceProviderId.

When a device that supports a particular service is connected, the client will call CommunicationsClientListener.onServiceConnected on the specified communicationsClientListener object. It will provide a ServiceProviderId and the proxy object. The ServiceProviderId is a unique ID of the connection with the service provider and the proxy object can be directly used to make calls into the remote service.

When connection is lost to a service the client will call CommunicationsClientListener.onServiceDisconnected on the communicationsClientListener and provide its ServiceProviderId.

Example

private val communicationsClientContext = CommunicationsClientContext(
  iviServiceHostContext.context, lifecycleOwner, MessagingService.ClientFactory()
)

private val communicationsServiceClientListener = object : CommunicationsClientListener {
  override fun onServiceConnected(
    serviceProviderUuid: ServiceProviderId,
    proxy: CommunicationsServiceBase
  ) {
    // Do something with `proxy`.
  }

  override fun onServiceDisconnected(serviceProviderId: ServiceProviderId) {
    // From now on the proxy object for the `serviceProvideId` is not usable anymore.
  }
}

val communicationsClient = CommunicationsClient(
  communicationsClientContext, communicationsServiceClientListener
)