nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine

#include <src/lib/profiles/data-management/Current/TraitData.h>

The schema engine takes schema information associated with a particular trait and provides facilities to parse and translate that into a form usable by the WDM machinery.

Summary

This includes converting from PathHandles to WDM paths (and vice versa), methods to interpret/query the schema itself and methods to help read/write out data to/from TLV given a handle.

The schema itself is stored in tabular form, sufficiently described to allow for generic parsing/composition of WDM paths/data for any given trait. These tables are what will be the eventual output of 'code-gen' (The term itself being somewhat misleading given the absence of any generated code :P)

Public static attributes
kHandleTableOffset = 2
const uint32_t

Public attributes
mSchema
const Schema

Public functions
FindLowestCommonAncestor(PropertyPathHandle aHandle1, PropertyPathHandle aHandle2, PropertyPathHandle *aHandle1BranchChild, PropertyPathHandle *aHandle2BranchChild) const
Given two property handles, calculate the lowest handle that serves as a parent to both of these handles.
GetChildHandle(PropertyPathHandle aParentHandle, uint8_t aContextTag) const
GetDepth(PropertyPathHandle aHandle) const
int32_t
Calculate the depth in the schema tree for a given handle.
GetDictionaryItemHandle(PropertyPathHandle aParentHandle, uint16_t aDictionaryKey) const
GetFirstChild(PropertyPathHandle aParentHandle) const
Returns the first child handle associated with a particular parent.
GetHighestForwardVersion(SchemaVersion aVersion) const
SchemaVersion
Given a provided data schema version, this will return the highest forward compatible schema version.
GetLowestCompatibleVersion(SchemaVersion aVersion) const
SchemaVersion
Given a provided data schema version, this will return the minimum compatible schema version.
GetMap(PropertyPathHandle aHandle) const
const PropertyInfo *
Returns a pointer to the PropertyInfo structure describing a particular path handle.
GetMaxVersion() const
SchemaVersion
GetMinVersion() const
SchemaVersion
GetNextChild(PropertyPathHandle aParentId, PropertyPathHandle aChildHandle) const
Given a handle to an existing child, returns the next child handle associated with a particular parent.
GetParent(PropertyPathHandle aHandle) const
Returns the parent handle of a given child path handle.
GetProfileId(void) const
uint32_t
Returns the profile id of the associated trait.
GetRelativePathTags(const PropertyPathHandle aCandidateHandle, uint64_t *aTags, const uint32_t aTagsSize, uint32_t & aNumTags) const
Converts a PropertyPathHandle to an array of context tags.
GetTag(PropertyPathHandle aHandle) const
uint64_t
Returns the tag associated with a path handle.
GetVersionIntersection(SchemaVersionRange & aVersion, SchemaVersionRange & aIntersection) const
bool
Given a version range, this function checks to see if there is a compatibility intersection between that and what is supported by schema that is backing this schema engine.
IsDictionary(PropertyPathHandle aHandle) const
bool
Returns true if the handle is a dictionary (and not in a dictionary - see method below).
IsEphemeral(PropertyPathHandle aHandle) const
bool
IsInDictionary(PropertyPathHandle aHandle, PropertyPathHandle & aDictionaryItemHandle) const
bool
Returns true if the handle is inside a dictionary (a dictionary element).
IsLeaf(PropertyPathHandle aPropertyHandle) const
bool
Returns true if the handle refers to a leaf node in the schema tree.
IsNullable(PropertyPathHandle aHandle) const
bool
IsOptional(PropertyPathHandle aHandle) const
bool
IsParent(PropertyPathHandle aChildHandle, PropertyPathHandle aParentHandle) const
bool
Checks if a given handle is a child of another handle.
MapHandleToPath(PropertyPathHandle aHandle, nl::Weave::TLV::TLVWriter & aPathWriter) const
Convert the path handle to a TLV path.
MapPathToHandle(nl::Weave::TLV::TLVReader & aPathReader, PropertyPathHandle & aHandle) const
Given a reader positioned at the root of a WDM path element, read out the relevant tags and provide the equivalent path handle.
MapPathToHandle(const char *aPathString, PropertyPathHandle & aHandle) const
Given the a string representation of a WDM path read out the relevant tags and provide the equivalent path handle.
MatchesProfileId(uint32_t aProfileId) const
bool
Returns true if the passed in profileId matches that stored in the schema.
RetrieveData(PropertyPathHandle aHandle, uint64_t aTagToWrite, nl::Weave::TLV::TLVWriter & aWriter, IGetDataDelegate *aDelegate, IDirtyPathCut *apDirtyPathCut) const
Given a path handle and a writer position on the corresponding data element, retrieve leaf data from the source and write it into the buffer pointed to by the writer in a schema compliant manner.
RetrieveUpdatableDictionaryData(PropertyPathHandle aHandle, uint64_t aTagToWrite, nl::Weave::TLV::TLVWriter & aWriter, IGetDataDelegate *aDelegate, PropertyPathHandle & aPropertyPathHandleOfDictItemToStartFrom) const
StoreData(PropertyPathHandle aHandle, nl::Weave::TLV::TLVReader & aReader, ISetDataDelegate *aDelegate, IPathFilter *aPathFilter) const
Given a path handle and a reader positioned on the corresponding data element, process the data buffer pointed to by the reader and store it into the sink by invoking the SetLeafData call whenever a leaf data item is encountered.

Classes
nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine::IGetDataDelegate
nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine::ISetDataDelegate

Structs
nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine::PropertyInfo
nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine::Schema

The main schema structure that houses the schema information.

Public static attributes

kHandleTableOffset

const uint32_t kHandleTableOffset = 2

Public attributes

mSchema

const Schema mSchema

Public functions

FindLowestCommonAncestor

PropertyPathHandle FindLowestCommonAncestor(
  PropertyPathHandle aHandle1,
  PropertyPathHandle aHandle2,
  PropertyPathHandle *aHandle1BranchChild,
  PropertyPathHandle *aHandle2BranchChild
) const

Given two property handles, calculate the lowest handle that serves as a parent to both of these handles.

Additionally, return the two child branches that contain each of the two handles (even if they are the same).

Details
Return Values
PropertyPathHandle
Handle to the lowest parent.

GetChildHandle

PropertyPathHandle GetChildHandle(
  PropertyPathHandle aParentHandle,
  uint8_t aContextTag
) const

GetDepth

int32_t GetDepth(
  PropertyPathHandle aHandle
) const

Calculate the depth in the schema tree for a given handle.

Details
Return Values
int32_t
The depth in the tree

GetDictionaryItemHandle

PropertyPathHandle GetDictionaryItemHandle(
  PropertyPathHandle aParentHandle,
  uint16_t aDictionaryKey
) const

GetFirstChild

PropertyPathHandle GetFirstChild(
  PropertyPathHandle aParentHandle
) const

Returns the first child handle associated with a particular parent.

Details
Return Values
PropertyPathHandle
Handle of the first child.

GetHighestForwardVersion

SchemaVersion GetHighestForwardVersion(
  SchemaVersion aVersion
) const

Given a provided data schema version, this will return the highest forward compatible schema version.

GetLowestCompatibleVersion

SchemaVersion GetLowestCompatibleVersion(
  SchemaVersion aVersion
) const

Given a provided data schema version, this will return the minimum compatible schema version.

GetMap

const PropertyInfo * GetMap(
  PropertyPathHandle aHandle
) const

Returns a pointer to the PropertyInfo structure describing a particular path handle.

Details
Return Values
PropertyInfo*

GetMaxVersion

SchemaVersion GetMaxVersion() const

GetMinVersion

SchemaVersion GetMinVersion() const

GetNextChild

PropertyPathHandle GetNextChild(
  PropertyPathHandle aParentId,
  PropertyPathHandle aChildHandle
) const

Given a handle to an existing child, returns the next child handle associated with a particular parent.

Details
Return Values
PropertyPathHandle
Handle of the next child.

GetParent

PropertyPathHandle GetParent(
  PropertyPathHandle aHandle
) const

Returns the parent handle of a given child path handle.

Dictionary keys in the handle are preserved in the case where the parent handle is also a dictionary element.

Details
Return Values
PropertyPathHandle
Handle of the parent.

GetProfileId

uint32_t GetProfileId(
  void
) const

Returns the profile id of the associated trait.

Details
Return Values
Trait
profile id

GetRelativePathTags

WEAVE_ERROR GetRelativePathTags(
  const PropertyPathHandle aCandidateHandle,
  uint64_t *aTags,
  const uint32_t aTagsSize,
  uint32_t & aNumTags
) const

Converts a PropertyPathHandle to an array of context tags.

Details
Parameters
[in] aCandidateHandle
The PropertyPathHandle to be converted.
[in] aTags
Pointer to the output array.
[in] aTagsSize
Size of the aTags array, in number of elements.
[out] aNumTags
The number of tags written to aTags
Returns
WEAVE_NO_ERROR in case of success; WEAVE_ERROR_NO_MEMORY if aTags is too small to store the full path.

GetTag

uint64_t GetTag(
  PropertyPathHandle aHandle
) const

Returns the tag associated with a path handle.

If it's a dictionary element, this function returns the ProfileTag. Otherwise, it returns context tags.

Details
Return Values
uint64_t

GetVersionIntersection

bool GetVersionIntersection(
  SchemaVersionRange & aVersion,
  SchemaVersionRange & aIntersection
) const

Given a version range, this function checks to see if there is a compatibility intersection between that and what is supported by schema that is backing this schema engine.

If there is an intersection, the function will return true and update the aIntersection argument passed in to reflect that results of that intersection test.

IsDictionary

bool IsDictionary(
  PropertyPathHandle aHandle
) const

Returns true if the handle is a dictionary (and not in a dictionary - see method below).

Details
Return Values
bool

IsEphemeral

bool IsEphemeral(
  PropertyPathHandle aHandle
) const

IsInDictionary

bool IsInDictionary(
  PropertyPathHandle aHandle,
  PropertyPathHandle & aDictionaryItemHandle
) const

Returns true if the handle is inside a dictionary (a dictionary element).

A user passed in handle (aDictionaryItemHandle) is updated to point to the top-most dictionary element handle within the dictionary.

Details
Return Values
bool

IsLeaf

bool IsLeaf(
  PropertyPathHandle aPropertyHandle
) const

Returns true if the handle refers to a leaf node in the schema tree.

Details
Return Values
bool

IsNullable

bool IsNullable(
  PropertyPathHandle aHandle
) const

IsOptional

bool IsOptional(
  PropertyPathHandle aHandle
) const

IsParent

bool IsParent(
  PropertyPathHandle aChildHandle,
  PropertyPathHandle aParentHandle
) const

Checks if a given handle is a child of another handle.

This can be an in-direct parent.

Details
Return Values
bool

MapHandleToPath

WEAVE_ERROR MapHandleToPath(
  PropertyPathHandle aHandle,
  nl::Weave::TLV::TLVWriter & aPathWriter
) const

Convert the path handle to a TLV path.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
Was unable to convert the handle to a TLV path

MapPathToHandle

WEAVE_ERROR MapPathToHandle(
  nl::Weave::TLV::TLVReader & aPathReader,
  PropertyPathHandle & aHandle
) const

Given a reader positioned at the root of a WDM path element, read out the relevant tags and provide the equivalent path handle.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_TLV_TAG_NOT_FOUND
If a matching handle could not be found due to a malformed/incorrectly specified path.

MapPathToHandle

WEAVE_ERROR MapPathToHandle(
  const char *aPathString,
  PropertyPathHandle & aHandle
) const

Given the a string representation of a WDM path read out the relevant tags and provide the equivalent path handle.

The WDM path is represented as a string using the following rules:

  • tags are separated with /
  • the path MUST begin with a leading / and MUST NOT contain a trailing slash
  • numerical tags in the WDM path MUST be encoded using the standard C library for integer to string encoding, i.e. decimal encoding (default) MUST NOT contain a leading 0, a hexadecimal encoding MUST begin with 0x, and octal encoding MUST contain a leading 0.

Details
Return Values
WEAVE_NO_ERROR
On success.
WEAVE_ERROR_TLV_TAG_NOT_FOUND
If a matching handle could not be found.
WEAVE_ERROR_INVALID_ARGUMENT
If a path string is malformed

MatchesProfileId

bool MatchesProfileId(
  uint32_t aProfileId
) const

Returns true if the passed in profileId matches that stored in the schema.

Details
Return Values
bool

RetrieveData

WEAVE_ERROR RetrieveData(
  PropertyPathHandle aHandle,
  uint64_t aTagToWrite,
  nl::Weave::TLV::TLVWriter & aWriter,
  IGetDataDelegate *aDelegate,
  IDirtyPathCut *apDirtyPathCut
) const

Given a path handle and a writer position on the corresponding data element, retrieve leaf data from the source and write it into the buffer pointed to by the writer in a schema compliant manner.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
Encountered errors writing out the data.

RetrieveUpdatableDictionaryData

WEAVE_ERROR RetrieveUpdatableDictionaryData(
  PropertyPathHandle aHandle,
  uint64_t aTagToWrite,
  nl::Weave::TLV::TLVWriter & aWriter,
  IGetDataDelegate *aDelegate,
  PropertyPathHandle & aPropertyPathHandleOfDictItemToStartFrom
) const

StoreData

WEAVE_ERROR StoreData(
  PropertyPathHandle aHandle,
  nl::Weave::TLV::TLVReader & aReader,
  ISetDataDelegate *aDelegate,
  IPathFilter *aPathFilter
) const

Given a path handle and a reader positioned on the corresponding data element, process the data buffer pointed to by the reader and store it into the sink by invoking the SetLeafData call whenever a leaf data item is encountered.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
Encountered errors parsing/processing the data.