Test API to handle a cache

Overview

// typedefs

typedef te_errno (*tapi_cache_cb)(
    const char *oid,
    void *opaque
    );

// global functions

te_errno tapi_cache_register(const char* method, const char* area, tapi_cache_cb cb_func);
te_errno tapi_cache_actualize(const char* method, void* opaque, const char* area_ptrn, ...);
te_errno te_errno tapi_cache_invalidate(const char* method, const char* area_ptrn, ...);
te_errno te_errno te_errno tapi_cache_add(cfg_val_type type, const void* value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno tapi_cache_add_string(const char* value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno tapi_cache_add_int(int value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_add_addr(const struct sockaddr* addr, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_del(const char* area_ptrn, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_find(cfg_handle_cb_func cb_func, void* opaque, const char* area_ptrn, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get(cfg_val_type* type, void* value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_string(char** value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_int(int* value, const char* area_inst, ...);
te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_addr(struct sockaddr** addr, const char* area_inst, ...);

// macros

#define TAPI_CACHE_ALL
#define TAPI_CACHE_ROOT_INST
#define TAPI_CACHE_ROOT_OID

Detailed Documentation

Generic API to operate the Configurator subtree /volatile/cache. Configurator subtree (doc/cm/cm_volatile.xml).

Synopsis

Test API is intended to manage data which could be obtained with different ways. The main idea is to reduce a number of expensive read operations of data which are changed rarely, and keep the cache up to date independently on what way is used to obtain data.

Terminology

area - Subtree handled by same actualization callbacks set. For example, there are two areas in /volatile/cache/foo/bar : foo and foo/bar Note, it is not mandatory to register callbacks for each area

method - The way to gather data to be cached. Do not mistake it with callback functions! For example, crm, cwmp, etc. It MUST be a leaf of Configurator tree. For example, /volatile:/cache:/foo:FOO/bar:BAR/baz:crm

Example

To use this feature, you need to register cache node and its children in Configurator

Lets assume for instance, we need to operate wifi/ssid/path cache area

<?xml version="1.0"?>
<history>
  <register>
    <object oid="/volatile"
        access="read_create" type="none" volatile="true"/>
    <object oid="/volatile/cache"
        access="read_create" type="none"/>
    <object oid="/volatile/cache/wifi"
        access="read_create" type="none"/>
    <object oid="/volatile/cache/wifi/ssid"
        access="read_create" type="none"/>
    <object oid="/volatile/cache/wifi/ssid/path"
        access="read_create" type="string"/>
  </register>

  <add>
    <instance oid="/volatile:"/>
    <instance oid="/volatile:/cache:"/>
  </add>
</history>

Example of usage in the test

#include "tapi_cache.h"
...

CHECK_RC(tapi_cache_register("crm", "wifi", wifi_crm_cb));
CHECK_RC(tapi_cache_register("cwmp", "wifi", wifi_cwmp_cb));

CHECK_RC(tapi_cache_actualize("crm", &wifi_crm_opaque, "wifi:%s", band));
CHECK_RC(tapi_cache_actualize("cwmp", &wifi_cwmp_opaque, "wifi:*"));
...

# Get all SSIDs of band 5G from the cache
struct {
    char *ssid[];
} ap;
CHECK_RC(tapi_cache_find(get_ssids, &ap, "wlan:5G/ssid:*"));

# Get a CRM path to the first 5G SSID from the cache
char *crm_path;
CHECK_RC(tapi_cache_get_string(&crm_path,
                               "wifi:5G/ssid:%s/path:crm", ap.ssid[0]));

# Get a CWMP path to the first 5G SSID from the cache
char *cwmp_path;
CHECK_RC(tapi_cache_get_string(&cwmp_path,
                               "wifi:5G/ssid:%s/path:cwmp", ap.ssid[0]));
...

# Add a new 5G SSID "test" via CRM:
crm_path = some_tapi_add_ssid_via_crm(...);
# Register this newly added SSID to cache
CHECK_RC(tapi_cache_add_string(crm_path, "wifi:5G/ssid:test/path:crm"));
...

CHECK_RC(tapi_cache_invalidate(NULL, "wifi:*"));

Typedefs

typedef te_errno (*tapi_cache_cb)(
    const char *oid,
    void *opaque
    )

Type of callback function which can be called by tapi_cache_actualize() and registered by tapi_cache_register()

Parameters:

oid	Object instance identifier (root of subtree to be actualized)
opaque	Opaque data containing arguments of certain callback

Returns:

Status code

Global Functions

te_errno tapi_cache_register(const char* method, const char* area, tapi_cache_cb cb_func)

Register a callback function for particular cache actualization method of certain area

Parameters:

method	Method
area	Area
cb_func	Callback function

Returns:

Status code

te_errno tapi_cache_actualize(const char* method, void* opaque, const char* area_ptrn, ...)

Actualize certain cache area instances. It calls a suitable function registered with tapi_cache_register() to gather data required to fill the cache area with particular method

It invalidates the area instances of certain method before actualization. Also it is possible to call the function on parent instance which does not have registered callback but whose children have ones. Caution: keep in mind in this case it can call different callbacks with the same opaque. For instance, if we had the following areas with registered callbacks: foo/bar, foo/bar/baz, qux, the function on area instance TAPI_CACHE_ALL would invoke callbacks of foo/bar and qux

Parameters:

method	Method
opaque	Opaque argument to pass to the callback function registered with tapi_cache_register()
area_ptrn	Format string of area instance, can contain wildcards to actualize several instances of area. For example, “foo:*”, “foo:FOO”, or TAPI_CACHE_ALL
…	Format string arguments
0	Instance has been actualized completely
TE_ECHILD	Some of subareas have not been actualized due to they do not have actualization callbacks
TE_ENOENT	Instance has not been actualized completely
Any-other	Other errors which should be handled as critical

Returns:

Status code

See also:

tapi_cache_invalidate

te_errno te_errno tapi_cache_invalidate(const char* method, const char* area_ptrn, ...)

Invalidate certain cache area instances.

Parameters:

method	Method, can be `NULL` to invalidate all instances indepenently on actualization method
area_ptrn	Format string of area instance, can contain wildcards to invalidate several instances of area. For example, “foo:*”, or “foo:FOO”
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_actualize

te_errno te_errno te_errno tapi_cache_add(cfg_val_type type, const void* value, const char* area_inst, ...)

Add a new instance to cache area, add parent instances (with value CFG_VAL(NONE, NULL)) as needed

It is important for proper work of acrialize and invalidate actions to follow agreement that leaf is a method

Parameters:

type	Value type
value	Value to add
area_inst	Format string of area instance to add. For example, “foo:%s/bar:%s/baz:METHOD”, it is allowed to use “foo:%s/bar:%s” if further a leaf instance of method will be added according to agreement
…	Format string arguments

Returns:

Status code

te_errno te_errno te_errno te_errno tapi_cache_add_string(const char* value, const char* area_inst, ...)

Add a new string instance to cache area

Parameters:

value	String value to add
area_inst	Format string of area instance to add
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_add

te_errno te_errno te_errno te_errno te_errno tapi_cache_add_int(int value, const char* area_inst, ...)

Add a new integer instance to cache area

Parameters:

value	Integer value to add
area_inst	Format string of area instance to add
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_add

te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_add_addr(const struct sockaddr* addr, const char* area_inst, ...)

Add a new network address instance to cache area

Parameters:

addr	Network address to add
area_inst	Format string of area instance to add
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_add

te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_del(const char* area_ptrn, ...)

Delete instance(s) of cache area by pattern

Prefer tapi_cache_invalidate() to this function since this one knows nothing about methods and, hence, ignores them. It simply removes area instances of all methods.

Parameters:

area_ptrn	Format string of area instance, can contain wildcards to delete several instances of area. For example, “foo:*”, or “foo:FOO”
…	Format string arguments

Returns:

Status code

te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_find(cfg_handle_cb_func cb_func, void* opaque, const char* area_ptrn, ...)

Find all area instances matching a pattern and call cb_func for each of found items

Parameters:

cb_func	Pointer to callback function
opaque	Opaque argument to pass to `cb_func`
area_ptrn	Format string of area instance, can contain wildcards to find several instances of area. For example, “foo:*”, or “foo:FOO”
…	Format string arguments

Returns:

Status code

See also:

cfg_find_pattern_iter_fmt

te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get(cfg_val_type* type, void* value, const char* area_inst, ...)

Get a value of certain instance of cache area

Parameters:

type	Value type location, may be `NULL`. If it is CVT_UNSPECIFIED, it will be updated with obtained value type
value	Value location
area_inst	Area instance format string
…	Format string arguments

Returns:

Status code

te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_string(char** value, const char* area_inst, ...)

Get a string value of certain instance of cache area

Return value should be freed with free(3) when it is no longer needed

Parameters:

value	Pointer to value location
area_inst	Area instance format string
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_get

te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_int(int* value, const char* area_inst, ...)

Get an integer value of certain instance of cache area

Parameters:

value	Value location
area_inst	Area instance format string
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_get

te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno te_errno tapi_cache_get_addr(struct sockaddr** addr, const char* area_inst, ...)

Get a network address value of certain instance of cache area

Return value should be freed with free(3) when it is no longer needed

Parameters:

addr	Pointer to address location
area_inst	Area instance format string
…	Format string arguments

Returns:

Status code

See also:

tapi_cache_get

Macros

#define TAPI_CACHE_ALL

Cache instance pointing to all cache data (cache root). Useful if you need to actualize all cache instances at once

#define TAPI_CACHE_ROOT_INST

Cache area configurator root instance

#define TAPI_CACHE_ROOT_OID

Cache area configurator root object