IviServiceHostConfig

Defines the implementation and the IVI service interfaces of an IVI service host.

While building an IVI application, the IVI service host implementation can be included in the build, which is the default, but it is also possible for it to reside in another Android application.

IVI service host implementation included in the build

To include the IVI service host implementation in the build, its definition needs to reference the service host builder class. The serviceHostBuilderName, implementationModule and subPackageName properties are used to refer to the builder class of the service host. The builder class is expected to be defined with the fully qualified class name: <package-of-implementationModule>[.<subPackageName>].<ServiceHostBuilderName>.

The builder class needs to implement the IviServiceHostBuilder interface and must have a constructor without parameters.

Example

A builder class in a module with the name "platform_framework_functionaltest_ipc_exampleserviceplugin":

package com.tomtom.ivi.platform.framework.functionaltest.ipc.exampleserviceplugin

...

class ExampleServiceHostBuilder : IviServiceHostBuilder() {
    override fun build(iviServiceHostContext: IviServiceHostContext) =
        SimpleIviServiceHost(
            listOf(
                TestExampleService(iviServiceHostContext),
                ...
            )
        )
}

This corresponds to the following IviServiceHostConfig:

IviServiceHostConfig(
    serviceHostBuilderName = "ExampleServiceHostBuilder",
    implementationModule = ModuleReference(
        groupName = "com.tomtom.ivi.platform"
        moduleName = "platform_framework_functionaltest_ipc_exampleserviceplugin"
        packageName = "com.tomtom.ivi.platform.framework.functionaltest.ipc.exampleserviceplugin"
    )
    ...
)

The ModuleReference class is open for extension. If some parts of the module reference parameters can be derived, define and use a subclass to simplify the configuration. For instance, an IviPlatformModuleReference, subclass of ModuleReference, can derive the package name from the module name for all TomTom Digital Cockpit platform modules.

As such the above example can be simplified to:

IviServiceHostConfig(
    serviceHostBuilderName = "ExampleServiceHostBuilder",
    implementationModule = IviPlatformModuleReference(
        "platform_framework_functionaltest_ipc_exampleserviceplugin"
    )
    ...
)

Reference to an IVI service host in an external Android application

To allow an IVI application to connect to an IVI service host in another Android application, the external application must export the service and the IVI application must be configured with an IVI service host which references the external IVI service host. To reference the external service host, the package name of the external Android application is required.

An existing IviServiceHostConfig can be transformed to an external IVI service host references by using toExternal.

Example

IviServiceHostConfig(
    serviceHostBuilderName = "ExampleServiceHostBuilder",
    ...
).toExternal("com.example.another.application")

Service host interfaces

The service interface implemented by the service host needs to be configured to allow the service host to be registered. A service host needs to have at least one interface.

Example

val exampleServiceHost = IviServiceHostConfig(
    serviceHostBuilderName = "ExampleServiceHostBuilder",
    ...
    interfaces = listOf(
        IviServiceInterfaceConfig(
            serviceName = "ExampleService",
            serviceApiModule = IviPlatformModuleReference(
                "platform_framework_functionaltest_ipc_exampleserviceapi"
            )
        ),
        ...
    ),
    ...
)

This defines that the ExampleServiceHostBuilder builds a host that implements the com.tomtom.ivi.platform.framework.functionaltest.ipc.exampleserviceapi.ExampleService interface. The package name here is derived from the module name.

To register a discoverable service interface (a service interface annotated with the IviDiscoverableService annotation), the IviServiceInterfaceConfig.serviceId needs to be defined.

Dependencies

A service host implementation can require other IVI service interfaces to be registered. The dependencies property can be used to define those interface. This allows misconfiguration to be detected at build time.

This configuration is unavailable (null) if an external IVI service host is referenced.

Optional tags

A host config can have one or more tags. The tags can be used to selectively configure the deployment of hosts based on the tag. See IviServiceHostMatcher.

Parameters