Client-side use

You can refactor conditionally compiled code to read values dynamically from the HAL interface. For example:

#ifdef TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS
// some code fragment
#endif

Framework code can then call an appropriate utility function defined in <configstore/Utils.h> depending on its type.

ConfigStore example

This example shows reading TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS, defined in ConfigStore HAL as forceHwcForVirtualDisplays() with return type OptionalBool:

#include <configstore/Utils.h>
using namespace android::hardware::configstore;
using namespace android::hardware::configstore::V1_0;

static bool vsyncPhaseOffsetNs = getBool<ISurfaceFlingerConfigs,
        ISurfaceFlingerConfigs::forceHwcForVirtualDisplays>(false);

The utility function (getBool in the example above) contacts the configstore service to get the handle for the proxy of the interface function, then retrieves the value by invoking the handle via HIDL/hwbinder.

Utility functions

Type	Function (template parameters omitted)
`OptionalBool`	`bool getBool(const bool defValue)`
`OptionalInt32`	`int32_t getInt32(const int32_t defValue)`
`OptionalUInt32`	`uint32_t getUInt32(const uint32_t defValue)`
`OptionalInt64`	`int64_t getInt64(const int64_t defValue)`
`OptionalUInt64`	`uint64_t getUInt64(const uint64_t defValue)`
`OptionalString`	`std::string getString(const std::string &defValue)`

defValue is a default value returned when the HAL implementation doesn't specify a value for the configuration item. Each function takes two template parameters:

I is the interface class name.
Func is the member function pointer for getting the configuration item.

Because the configuration value is read-only and doesn't change, the utility function internally caches the configuration value. Subsequent calls are serviced more efficiently using the cached value in the same linking unit.

Use configstore-utils

The ConfigStore HAL is designed to be forward compatible for minor version upgrades, meaning that when the HAL is revised and some framework code uses the newly introduced items, the ConfigStore service with an older minor version in /vendor can still be used.

For forward compatibility, ensure that your implementation adheres to the following guidelines:

New items use the default value when only the old version's service is available. Example:

service = V1_1::IConfig::getService(); // null if V1_0 is installed
value = DEFAULT_VALUE;
  if(service) {
    value = service->v1_1API(DEFAULT_VALUE);
  }

The client uses the first interface that included the ConfigStore item. Example:

V1_1::IConfig::getService()->v1_0API(); // NOT ALLOWED

V1_0::IConfig::getService()->v1_0API(); // OK

The new version's service can be retrieved for old version's interface. In the following example, if the installed version is v1_1, the v1_1 service must be returned for getService():
```
V1_0::IConfig::getService()->v1_0API();
```
Note: The current AOSP implementation satisfies this requirement.

When the access functions in the configstore-utils library are used for accessing the ConfigStore item, #1 is guaranteed by the implementation and #2 is guaranteed by compiler errors. For these reasons, we strongly recommend using configstore-utils wherever possible.