nl::Weave::TLV

Definitions for working with data encoded in Weave TLV format.

Summary

Weave TLV is a generalized encoding method for simple structured data. It shares many properties with the commonly used JSON serialization format while being considerably more compact over the wire.

Enumerations
@71 enum
@73 enum
@74{
  AnonymousTag = kSpecialTagMarker | 0x00000000FFFFFFFFULL
} 		enum
@75 enum
TLVCommonProfiles{
  kProfileIdNotSpecified = 0xFFFFFFFF
} 		enum
TLVElementType enum
TLVFieldSize enum
TLVTagControl enum
TLVTagFields enum
TLVType enum
An enumeration identifying the type of a TLV element.

Variables
kWeaveTLVCopyChunkSize = 16
const size_t
Copies a TLV element from a reader object into the writer.
sTagSizes = { 0, 1, 2, 4, 2, 4, 6, 8 }[]
const uint8_t

Functions
CommonTag(uint32_t tagNum)
uint64_t
Generates the API representation of a common profile TLV tag.
ContextTag(uint8_t tagNum)
uint64_t
Generates the API representation for of context-specific TLV tag.
GetTLVFieldSize(uint8_t type)
TLVFieldSize
IsContextTag(uint64_t tag)
bool
Returns true if the supplied tag is a context-specific tag.
IsProfileTag(uint64_t tag)
bool
Returns true of the supplied tag is a profile-specific tag.
IsSpecialTag(uint64_t tag)
bool
IsValidTLVType(uint8_t type)
bool
Returns true if the specified TLV type is valid.
ProfileIdFromTag(uint64_t tag)
uint32_t
Returns the profile id from a TLV tag.
ProfileNumFromTag(uint64_t tag)
uint16_t
Returns the profile number from a TLV tag.
ProfileTag(uint32_t profileId, uint32_t tagNum)
uint64_t
Generates the API representation of a profile-specific TLV tag from a profile id and tag number.
ProfileTag(uint16_t vendorId, uint16_t profileNum, uint32_t tagNum)
uint64_t
Generates the API representation of a profile-specific TLV tag from a vendor id, profile number and tag number.
TLVFieldSizeToBytes(TLVFieldSize fieldSize)
uint8_t
TLVTypeHasLength(uint8_t type)
bool
Returns true if the specified TLV type implies the presence of an associated length field.
TLVTypeHasValue(uint8_t type)
bool
Returns true if the specified TLV type implies the presence of an associated value field.
TLVTypeIsContainer(uint8_t type)
bool
Returns true if the specified TLV type is a container.
TLVTypeIsString(uint8_t type)
bool
Returns true if the specified TLV type is a UTF8 or byte string.
TagNumFromTag(uint64_t tag)
uint32_t
Returns the tag number from a TLV tag.
VendorIdFromTag(uint64_t tag)
uint16_t
Returns the vendor id from a TLV tag.

Classes
nl::Weave::TLV::CircularTLVReader
nl::Weave::TLV::CircularTLVWriter
nl::Weave::TLV::TLVReader

Provides a memory efficient parser for data encoded in Weave TLV format.

nl::Weave::TLV::TLVUpdater

Provides a unified Reader/Writer interface for editing/adding/deleting elements in TLV encoding.

nl::Weave::TLV::TLVWriter

Provides a memory efficient encoder for writing data in Weave TLV format.

nl::Weave::TLV::WeaveCircularTLVBuffer

WeaveCircularTLVBuffer provides circular storage for the nl::Weave::TLV::TLVWriter and nl::Weave::TLVTLVReader.

Namespaces
nl::Weave::TLV::Debug

This namespace includes types and interfaces for debugging and logging Weave TLV.

nl::Weave::TLV::Utilities

This namespace includes types and utility interfaces for managing and working with Weave TLV.

Enumerations

@71

 @71

@73

 @73

@74

 @74
Properties
AnonymousTag

A value signifying a TLV element that has no tag (i.e.

an anonymous element).

@75

 @75

TLVCommonProfiles

 TLVCommonProfiles
Properties
kProfileIdNotSpecified

Used to indicate the absence of a profile id in a variable or member.

This is essentially the same as kWeaveProfile_NotSpecified defined in WeaveProfiles.h

TLVElementType

 TLVElementType

TLVFieldSize

 TLVFieldSize

TLVTagControl

 TLVTagControl

TLVTagFields

 TLVTagFields

TLVType

 TLVType

An enumeration identifying the type of a TLV element.

Variables

kWeaveTLVCopyChunkSize

const size_t kWeaveTLVCopyChunkSize = 16

Copies a TLV element from a reader object into the writer.

The CopyElement() method encodes a new TLV element whose type and value are taken from a TLVReader object. When the method is called, the supplied reader object is expected to be positioned on the source TLV element. The newly encoded element will have the same type and contents as the input container, however the tag will be set to the specified argument. If the supplied element is a TLV container (structure, array or path), the entire contents of the container will be copied.

Details
Parameters
[in] tag
The TLV tag to be encoded with the container, or AnonymousTag if the container should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] reader
A reference to a TLVReader object identifying a pre-encoded TLV element whose type and value should be copied.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the supplied reader is not positioned on an element.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding associated with the supplied reader ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the supplied reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the supplied reader encountered a TLV tag in an invalid context, or if the supplied tag is invalid or inappropriate in the context in which the new container is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer() function associated with the reader object.

sTagSizes

const uint8_t sTagSizes[] = { 0, 1, 2, 4, 2, 4, 6, 8 }

Functions

CommonTag

uint64_t CommonTag(
  uint32_t tagNum
)

Generates the API representation of a common profile TLV tag.

Details
Parameters
[in] tagNum
The common profile tag number assigned to the tag.
Returns
A 64-bit integer representing the tag.

ContextTag

uint64_t ContextTag(
  uint8_t tagNum
)

Generates the API representation for of context-specific TLV tag.

Details
Parameters
[in] tagNum
The context-specific tag number assigned to the tag.
Returns
A 64-bit integer representing the tag.

GetTLVFieldSize

TLVFieldSize GetTLVFieldSize(
  uint8_t type
)

IsContextTag

bool IsContextTag(
  uint64_t tag
)

Returns true if the supplied tag is a context-specific tag.

IsProfileTag

bool IsProfileTag(
  uint64_t tag
)

Returns true of the supplied tag is a profile-specific tag.

IsSpecialTag

bool IsSpecialTag(
  uint64_t tag
)

IsValidTLVType

bool IsValidTLVType(
  uint8_t type
)

Returns true if the specified TLV type is valid.

Details
Returns
true if the specified TLV type is valid; otherwise false.

ProfileIdFromTag

uint32_t ProfileIdFromTag(
  uint64_t tag
)

Returns the profile id from a TLV tag.

Details
Parameters
[in] tag
The API representation of a profile-specific TLV tag.
Returns
The profile id.

ProfileNumFromTag

uint16_t ProfileNumFromTag(
  uint64_t tag
)

Returns the profile number from a TLV tag.

Details
Parameters
[in] tag
The API representation of a profile-specific TLV tag.
Returns
The associated profile number.

ProfileTag

uint64_t ProfileTag(
  uint32_t profileId,
  uint32_t tagNum
)

Generates the API representation of a profile-specific TLV tag from a profile id and tag number.

Details
Parameters
[in] profileId
The id of the profile within which the tag is defined.
[in] tagNum
The profile-specific tag number assigned to the tag.
Returns
A 64-bit integer representing the tag.

ProfileTag

uint64_t ProfileTag(
  uint16_t vendorId,
  uint16_t profileNum,
  uint32_t tagNum
)

Generates the API representation of a profile-specific TLV tag from a vendor id, profile number and tag number.

Details
Parameters
[in] vendorId
The id of the vendor that defined the tag.
[in] profileNum
The vendor assigned number for the profile within which the tag is defined.
[in] tagNum
The profile-specific tag number assigned to the tag.
Returns
A 64-bit integer representing the tag.

TLVFieldSizeToBytes

uint8_t TLVFieldSizeToBytes(
  TLVFieldSize fieldSize
)

TLVTypeHasLength

bool TLVTypeHasLength(
  uint8_t type
)

Returns true if the specified TLV type implies the presence of an associated length field.

Details
Returns
true if the specified TLV type implies the presence of an associated length field; otherwise false.

TLVTypeHasValue

bool TLVTypeHasValue(
  uint8_t type
)

Returns true if the specified TLV type implies the presence of an associated value field.

Details
Returns
true if the specified TLV type implies the presence of an associated value field; otherwise false.

TLVTypeIsContainer

bool TLVTypeIsContainer(
  uint8_t type
)

Returns true if the specified TLV type is a container.

Details
Returns
true if the specified TLV type is a container; otherwise false.

TLVTypeIsString

bool TLVTypeIsString(
  uint8_t type
)

Returns true if the specified TLV type is a UTF8 or byte string.

Details
Returns
true if the specified TLV type is a UTF8 or byte string; otherwise false.

TagNumFromTag

uint32_t TagNumFromTag(
  uint64_t tag
)

Returns the tag number from a TLV tag.

Details
Parameters
[in] tag
The API representation of a profile-specific or context-specific TLV tag.
Returns
The associated tag number.
See also:
IsProfileTag() and IsContextTag()

VendorIdFromTag

uint16_t VendorIdFromTag(
  uint64_t tag
)

Returns the vendor id from a TLV tag.

Details
Parameters
[in] tag
The API representation of a profile-specific TLV tag.
Returns
The associated vendor id.