ut_kvp: A Flexible Key‐Value Pair Framework

Key Value Pair

The ut_kvp module is a versatile component within the RDK Central project. It offers a structured way to represent and manage data using a simple key-value pair (KVP) paradigm. This framework is particularly valuable in scenarios where you need to:

• Store Configuration Data: Easily define and access configuration settings for your application or system.
• Pass Parameters: Efficiently pass data between different components or functions.
• Manage Structured Data: Represent hierarchical or complex data structures in a readable format.

Repo:ut-control

Key Concepts

• Key-Value Pairs (KVPs): The fundamental building block of the framework. A KVP associates a key (a string identifier) with a corresponding value (which can be a string, number, boolean, or array).
• YAML/JSON Input: ut_kvp natively supports loading KVP data from YAML or JSON files, making it easy to define and maintain your KVP structures in a human-readable format.
• C API: The framework provides a C API (ut_kvp.h) for creating, manipulating, and accessing KVPs within your C/C++ applications.

YAML/JSON Input Format

You can represent your KVP data using either YAML or JSON format:

YAML Example

database:
  host: localhost
  port: 5432
  username: myuser
  password: mypassword
logging:
  level: debug

JSON Example

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "username": "myuser",
    "password": "mypassword"
  },
  "logging": {
    "level": "debug"
  }
}

How to Use ut_kvp

1. Define Your KVP Structure: Create a YAML or JSON file to represent your KVP data.
2. Parse the Input: Use the ut_kvp API functions to load and parse your YAML/JSON file. This will populate the internal KVP data structure.
3. Access KVP Values: Use the API functions to retrieve the values associated with specific keys.
4. Modify KVP Values (Optional): If needed, you can update the values of existing keys or add new KVPs.

Code Example (C)

#include "ut_kvp.h"

ut_kvp_instance_t *pKVPInstance;
ut_kvp_status_t status;

pKVPInstance = ut_kvp_createInstance();
assert( pKVPInstance!=NULL );

// ... (load and parse YAML/JSON file)
status =  ut_kvp_open(pKVPInstance, "filenameToLoad.yaml/json");
assert( status != UT_KVP_STATUS_OK );

// Access values
const char* host = ut_kvp_get_string("database/host"); 
int port = ut_kvp_get_int("database/port"); 
 
// ... (use the values in your application)
// ...

// ... (destroy the instance)
ut_kvp_destroyInstance( pKVPInstance );

Benefits of ut_kvp

• Flexibility: Supports various data types and hierarchical structures.
• Ease of Use: Simple and intuitive API for working with KVPs.
• Human-Readable Input: YAML/JSON formats are easy to read and modify.
• Configuration Management: Ideal for storing and managing application configurations.
• Data Exchange: Can be used to pass structured data between components.

ut_kvp: Support for Includes in YAML Files

The ut_kvp module has been enhanced internally to support including external YAML files, providing a way to modularize and reuse configuration data.

Key Features:

• Local File Inclusion: Reference YAML files within your project's directory structure using the !include <file:xxx> directive.
• Remote File Inclusion: Fetch YAML files from URLs using the !include <https://...> directive.
• Unlimited Nesting: Include as many files as needed, and those files can include other files, forming a hierarchical structure.

For more detailed information see ut_kvp: Support for Includes in YAML files