nl::Weave::Profiles::DataManagement_Current

This namespace includes all interfaces within Weave for the Weave Data Management (WDM) profile that are currently supported for production use.

Summary

Enumerations

@124 enum
@78{
  kTag_CurrentImportance = 1,
  kTag_ImportanceExpiration,
  kTag_MinimumLogUploadInterval,
  kTag_MaximumLogUploadInterval,
  kTag_LoggingDestination,
  kTag_TraitLoggingImportance
}
enum
Logging Settings tags.
@79 enum
Tags for logging capabilities.
@80 enum
Tags for event metadata.
@81 enum
Profile definitions for the debug trait.
@82 enum
Event types for the Nest Debug trait.
@83 enum
Tags for the kNestDebug_StringLogEntryEvent.
@84 enum
Tags for the kNestDebug_TokenizedLogEntryEvent.
@85 enum
The WDM profile message types.
@86 enum
WDM-specific status codes.
ImportanceType{
  ProductionCritical = 1,
  Production,
  Info,
  Debug
}
enum
The importance of the log entry.
LoggingManagementStates enum
TimestampType enum
The validity and type of timestamp included in EventOptions.

Typedefs

DataVersion typedef
uint16_t
EventProcessor typedef
void *
EventWriterFunct)(nl::Weave::TLV::TLVWriter &ioWriter, uint8_t inDataTag, void *appData) typedef
A function that supplies eventData element for the event logging subsystem.
FetchExternalEventsFunct)(EventLoadOutContext *aContext) typedef
A function prototype for platform callbacks fetching event data.
ImportanceType typedef
The importance of the log entry.
IteratorCallback)(void *aTraitInstance, TraitDataHandle aHandle, void *aContext) typedef
void(*
Trait handle iterator.
LoggingBufferHandler)(void *inAppState, PacketBuffer *inBuffer) typedef
NotifyExternalEventsDeliveredFunct)(ExternalEvents *inEv, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID) typedef
void(*
A function prototype for a callback invoked when external events are delivered to the remote subscriber.
PropertyDictionaryKey typedef
uint16_t
PropertyPathHandle typedef
uint32_t
A PropertyPathHandle is a unique 32-bit numerical hash of a WDM path relative to the root of a trait instance.
PropertySchemaHandle typedef
uint16_t
SchemaVersion typedef
uint16_t
SingleResourceSinkTraitCatalog typedef
SingleResourceSourceTraitCatalog typedef
TimestampType typedef
The validity and type of timestamp included in EventOptions.
TraitDataHandle typedef
uint16_t
duration_t nl::Weave::Profiles::DataManagement_Current::duration_t
uint32_t
Type used to describe the duration, in milliseconds.
event_id_t nl::Weave::Profiles::DataManagement_Current::event_id_t
uint32_t
The type of event ID.
timestamp_t nl::Weave::Profiles::DataManagement_Current::timestamp_t
uint32_t
Type used to describe the timestamp in milliseconds.
utc_timestamp_t nl::Weave::Profiles::DataManagement_Current::utc_timestamp_t
uint64_t
Type used to describe the UTC timestamp in milliseconds.

Variables

sInstance
sLogFileName = "topazlog"[]
char

Functions

BdxErrorHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer, WEAVE_ERROR aErrorCode)
void
BdxGetBlockHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer, uint64_t *aLength, uint8_t **aDataBlock, bool *aIsLastBlock)
void
BdxRejectHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer, nl::Weave::Profiles::StatusReporting::StatusReport *aReport)
void
BdxSendAcceptHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer, nl::Weave::Profiles::BulkDataTransfer::SendAccept *aSendAcceptMsg)
BdxXferDoneHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer)
void
BdxXferErrorHandler(nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer, nl::Weave::Profiles::StatusReporting::StatusReport *aXferError)
void
CreatePropertyPathHandle(PropertySchemaHandle aPropertyPathSchemaId, PropertyDictionaryKey aPropertyPathDictionaryKey)
EventWriterTLVCopy(TLVWriter & ioWriter, uint8_t inDataTag, void *appData)
A helper function that translates an already serialized eventdata element into the event buffer.
GetPropertyDictionaryKey(PropertyPathHandle aHandle)
PropertyDictionaryKey
GetPropertySchemaHandle(PropertyPathHandle aHandle)
PropertySchemaHandle
IsNullPropertyPathHandle(PropertyPathHandle aHandle)
bool
IsRootPropertyPathHandle(PropertyPathHandle aHandle)
bool
LogEvent(const EventSchema & inSchema, nl::Weave::TLV::TLVReader & inData)
Log an event from a pre-serialized form.
LogEvent(const EventSchema & inSchema, nl::Weave::TLV::TLVReader & inData, const EventOptions *inOptions)
Log an event from a pre-serialized form, with additional options.
LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData)
Log an event via a callback.
LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
Log an event via a callback, with options.
LogFreeform(ImportanceType inImportance, const char *inFormat, ...)
LogFreeform emits a freeform string to the default event stream.
LookForElementWithTag(const nl::Weave::TLV::TLVReader & aSrcReader, const uint64_t aTagInApiForm, nl::Weave::TLV::TLVReader *apDstReader)
PlainTextWriter(TLVWriter & ioWriter, uint8_t inDataTag, void *appData)
A helper function for emitting a freeform text as a debug event.
PlainTextWriter(::nl::Weave::TLV::TLVWriter & ioWriter, uint8_t inDataTag, void *appData)
A helper function for emitting a freeform text as a debug event.

Classes

nl::Weave::Profiles::DataManagement_Current::BuilderBase

Base class for WDM message encoders.

nl::Weave::Profiles::DataManagement_Current::CircularEventReader

A TLVReader backed by CircularEventBuffer.

nl::Weave::Profiles::DataManagement_Current::Command
nl::Weave::Profiles::DataManagement_Current::IDirtyPathCut
nl::Weave::Profiles::DataManagement_Current::IPathFilter
nl::Weave::Profiles::DataManagement_Current::IWeaveClientLock

Interface that is to be implemented by app to serialize access to key WDM data structures.

nl::Weave::Profiles::DataManagement_Current::IWeavePublisherLock

Interface that is to be implemented by app to serialize access to key WDM data structures.

nl::Weave::Profiles::DataManagement_Current::ListBuilderBase

Base class for WDM message encoders, specialized in TLV array elements like Data Lists and Version Lists.

nl::Weave::Profiles::DataManagement_Current::ListParserBase

Base class for WDM message parsers, specialized in TLV array elements like Data Lists and Version Lists.

nl::Weave::Profiles::DataManagement_Current::LogBDXUpload
nl::Weave::Profiles::DataManagement_Current::LoggingConfiguration

LoggingConfiguration encapsulates the configurable component of the Weave Event Logging subsystem.

nl::Weave::Profiles::DataManagement_Current::LoggingManagement

A class for managing the in memory event logs.

nl::Weave::Profiles::DataManagement_Current::NotificationEngine
nl::Weave::Profiles::DataManagement_Current::ParserBase

Base class for WDM message parsers.

nl::Weave::Profiles::DataManagement_Current::SingleResourceTraitCatalog
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient
nl::Weave::Profiles::DataManagement_Current::SubscriptionEngine

This is a singleton hosting all WDM Next subscriptions, both client and publisher sides.

nl::Weave::Profiles::DataManagement_Current::SubscriptionHandler
nl::Weave::Profiles::DataManagement_Current::TraitCatalogBase
nl::Weave::Profiles::DataManagement_Current::TraitDataSink
nl::Weave::Profiles::DataManagement_Current::TraitDataSource
nl::Weave::Profiles::DataManagement_Current::TraitSchemaEngine

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.

nl::Weave::Profiles::DataManagement_Current::UpdateClient
nl::Weave::Profiles::DataManagement_Current::UpdateDictionaryDirtyPathCut

Utility class to put the dictionary back to pending queue when process the property path that has dictionary child.

nl::Weave::Profiles::DataManagement_Current::UpdateDirtyPathFilter

Utility class to filter path when handling notification.

nl::Weave::Profiles::DataManagement_Current::ViewClient

Structs

nl::Weave::Profiles::DataManagement_Current::CircularEventBuffer

Internal event buffer, built around the nl::Weave::TLV::WeaveCircularTLVBuffer.

nl::Weave::Profiles::DataManagement_Current::ConstSchemaVersionRange
nl::Weave::Profiles::DataManagement_Current::CopyAndAdjustDeltaTimeContext

Internal structure for traversing event list.

nl::Weave::Profiles::DataManagement_Current::DebugLogContext
nl::Weave::Profiles::DataManagement_Current::DetailedRootSection

The structure that provides a full resolution of the trait instance.

nl::Weave::Profiles::DataManagement_Current::EventEnvelopeContext

Internal structure for traversing events.

nl::Weave::Profiles::DataManagement_Current::EventLoadOutContext

Structure for copying event lists on output.

nl::Weave::Profiles::DataManagement_Current::EventOptions

The structure that provides options for the different event fields.

nl::Weave::Profiles::DataManagement_Current::EventSchema

The structure that defines a schema for event metadata.

nl::Weave::Profiles::DataManagement_Current::ExternalEvents

Structure for tracking platform-stored events.

nl::Weave::Profiles::DataManagement_Current::ReclaimEventCtx
nl::Weave::Profiles::DataManagement_Current::ResourceIdentifier

This structure provides a way to represent the identity of a resource either by way of the NodeId of the device, or a UUID.

nl::Weave::Profiles::DataManagement_Current::SchemaVersionRange
nl::Weave::Profiles::DataManagement_Current::TraitPath
nl::Weave::Profiles::DataManagement_Current::VersionedTraitPath

Unions

nl::Weave::Profiles::DataManagement_Current::Timestamp

The union that provides an application set system or UTC timestamp.

Namespaces

nl::Weave::Profiles::DataManagement_Current::BaseMessageWithSubscribeId
nl::Weave::Profiles::DataManagement_Current::CustomCommand

WDM Custom Command definition.

nl::Weave::Profiles::DataManagement_Current::CustomCommandResponse

WDM Custom Command Response definition.

nl::Weave::Profiles::DataManagement_Current::DataElement

WDM Data Element definition.

nl::Weave::Profiles::DataManagement_Current::DataList
nl::Weave::Profiles::DataManagement_Current::Event
nl::Weave::Profiles::DataManagement_Current::EventList
nl::Weave::Profiles::DataManagement_Current::NotificationRequest
nl::Weave::Profiles::DataManagement_Current::Path

WDM Path definition.

nl::Weave::Profiles::DataManagement_Current::PathList

WDM Path List definition.

nl::Weave::Profiles::DataManagement_Current::Platform
nl::Weave::Profiles::DataManagement_Current::RejectionRecord
nl::Weave::Profiles::DataManagement_Current::RejectionRecordList
nl::Weave::Profiles::DataManagement_Current::StatusElement

WDM Status Element definition.

nl::Weave::Profiles::DataManagement_Current::StatusList
nl::Weave::Profiles::DataManagement_Current::SubscribeCancelRequest
nl::Weave::Profiles::DataManagement_Current::SubscribeConfirmRequest
nl::Weave::Profiles::DataManagement_Current::SubscribeRequest
nl::Weave::Profiles::DataManagement_Current::SubscribeResponse
nl::Weave::Profiles::DataManagement_Current::UpdateRequest

WDM Update Request Request definition.

nl::Weave::Profiles::DataManagement_Current::UpdateResponse
nl::Weave::Profiles::DataManagement_Current::VersionList
nl::Weave::Profiles::DataManagement_Current::ViewRequest
nl::Weave::Profiles::DataManagement_Current::ViewResponse

Enumerations

@124

 @124

@78

 @78

Logging Settings tags.

Properties
kTag_CurrentImportance

Current logging importance, the value is of type ImportanceType.

kTag_ImportanceExpiration

Time, in UTC seconds when the current elevated logging settings revert to the default values.

kTag_LoggingDestination

A URL denoting the destination of the log upload.

kTag_MaximumLogUploadInterval

Maximal duration, in seconds, between automatically triggered log upload attempts.

kTag_MinimumLogUploadInterval

Minimal duration, in seconds, between automatically triggered log upload attempts.

kTag_TraitLoggingImportance

An optional array selectively mapping chosen profiles onto the higher logging levels.

Each element in array takes a form (profile,path,loggingimportance) to selectively elevate the logging from a subset of the system. The elevated profile logging priority is only of significance when the logging priority exceeds that of the currentImportance and is the subject to the same expiration time as the currentImportance.

@79

 @79

Tags for logging capabilities.

@80

 @80

Tags for event metadata.

For complete semantics of the tag values, see the Event Design Specification.

@81

 @81

Profile definitions for the debug trait.

@82

 @82

Event types for the Nest Debug trait.

@83

 @83

Tags for the kNestDebug_StringLogEntryEvent.

@84

 @84

Tags for the kNestDebug_TokenizedLogEntryEvent.

@85

 @85

The WDM profile message types.

These values are called out in the data management specification.

@86

 @86

WDM-specific status codes.

ImportanceType

 ImportanceType

The importance of the log entry.

Importance is used as a way to filter events before they are actually emitted into the log. After the event is in the log, we make no further provisions to expunge it from the log. The importance level serves to prioritize event storage. If an event of high importance is added to a full buffer, events are dropped in order of importance (and age) to accomodate it. As such, importance levels only have relative value. If a system is using only one importance level, events are dropped only in order of age, like a ring buffer.

Properties
Debug

Debug importance denotes log entries of interest to the developers of the system and is used primarily in the development phase.

Debug importance logs are not accounted for in the bandwidth or power budgets of the constrained devices; as a result, they must be used only over a limited time span in production systems.

Info

Info importance denotes log entries that provide extra insight and diagnostics into the running system.

Info logging level may be used over an extended period of time in a production system, or may be used as the default log level in a field trial. On the constrained devices, the entries logged with Info level must be accounted for in the bandwidth and memory budget, but not in the power budget.

Production

Production importance denotes the log entries that are used in the ongoing monitoring and maintenance of the Nest ecosystem.

On constrained devices, entries logged with Production importance must be accounted for in the power and memory budget, as it is expected that they are always logged and offloaded from the device.

ProductionCritical

Production Critical importance denotes events whose loss would directly impact customer-facing features.

Applications may use loss of Production Critical events to indicate system failure. On constrained devices, entries logged with Production Critical importance must be accounted for in the power and memory budget, as it is expected that they are always logged and offloaded from the device.

LoggingManagementStates

 LoggingManagementStates

TimestampType

 TimestampType

The validity and type of timestamp included in EventOptions.

Typedefs

DataVersion

uint16_t DataVersion

EventProcessor

void * EventProcessor

EventWriterFunct

WEAVE_ERROR(* EventWriterFunct)(nl::Weave::TLV::TLVWriter &ioWriter, uint8_t inDataTag, void *appData)

A function that supplies eventData element for the event logging subsystem.

Functions of this type are expected to provide the eventData element for the event logging subsystem. The functions of this type are called after the event subsystem has generated all required event metadata. The function is called with a nl::Weave::TLV::TLVWriter object into which it will emit a single TLV element tagged kTag_EventData; the value of that element MUST be a structure containing the event data. The event data itself must be structured using context tags.

Details
Parameters
[in,out] ioWriter
A reference to the nl::Weave::TLV::TLVWriter object to be used for event data serialization.
[in] inDataTag
A context tag for the TLV we're writing out.
[in] appData
A pointer to an application specific context.
Return Values
WEAVE_NO_ERROR
On success.
other
An appropriate error signaling to the caller that the serialization of event data could not be completed. Errors from calls to the ioWriter should be propagated without remapping. If the function returns any type of error, the event generation is aborted, and the event is not written to the log.
See also:
PlainTextWriter
EventWriterTLVCopy

FetchExternalEventsFunct

WEAVE_ERROR(* FetchExternalEventsFunct)(EventLoadOutContext *aContext)

A function prototype for platform callbacks fetching event data.

Similar to FetchEventsSince, this fetch function returns all events from EventLoadOutContext.mStartingEventID through ExternalEvents.mLastEventID.

The context pointer is of type FetchExternalEventsContext. This includes the EventLoadOutContext, with some helper variables for the format of the TLV. It also includes a pointer to the ExternalEvents struct created on registration of the callback. This specifies the event ID range for the callback.

On returning from the function, EventLoadOutContext.mCurrentEventID should reflect the first event ID that has not been successfully written to the TLV buffer. The platform must write the events header and data to the TLV writer in the correct format, specified by the EventLogging protocol. The platform must also maintain uniqueness of events and timestamps.

All TLV errors should be propagated to higher levels. For instance, running out of space in the buffer will trigger a sent message, followed by another call to the callback with whichever event ID remains.

Details
Return Values
WEAVE_ERROR_NO_MEMORY
If no space to write events.
WEAVE_ERROR_BUFFER_TOO_SMALL
If no space to write events.
WEAVE_NO_ERROR
On success.
WEAVE_END_OF_TLV
On success.

ImportanceType

enum nl::Weave::Profiles::DataManagement_Current::ImportanceType ImportanceType

The importance of the log entry.

Importance is used as a way to filter events before they are actually emitted into the log. After the event is in the log, we make no further provisions to expunge it from the log. The importance level serves to prioritize event storage. If an event of high importance is added to a full buffer, events are dropped in order of importance (and age) to accomodate it. As such, importance levels only have relative value. If a system is using only one importance level, events are dropped only in order of age, like a ring buffer.

IteratorCallback

void(* IteratorCallback)(void *aTraitInstance, TraitDataHandle aHandle, void *aContext)

Trait handle iterator.

LoggingBufferHandler

WEAVE_ERROR(* LoggingBufferHandler)(void *inAppState, PacketBuffer *inBuffer)

NotifyExternalEventsDeliveredFunct

void(* NotifyExternalEventsDeliveredFunct)(ExternalEvents *inEv, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID)

A function prototype for a callback invoked when external events are delivered to the remote subscriber.

When the external events are delivered to a remote subscriber, the engine will provide a notification to the external event provider. The callback contains the event of the last ID that was delivered, and the ID of the subscriber that received the event.

Details
Parameters
[in] inLastDeliveredEventID
ID of the last event delivered to the subscriber.
[in] inRecipientNodeID
Weave node ID of the recipient

PropertyDictionaryKey

uint16_t PropertyDictionaryKey

PropertyPathHandle

uint32_t PropertyPathHandle

A PropertyPathHandle is a unique 32-bit numerical hash of a WDM path relative to the root of a trait instance.

It has two parts to it:

  • A lower 16-bit number that maps to the static portion of the schema.
  • Where the lower 16-bits refer to a path within a dictionary element, an upper 16-bit number is present that represents the dictionary key associated with that element. If the lower 16-bits refer to a non dictionary element, then the upper 16-bits should be 0.

Some characteristics:

  • Every trait has its own property path handle space.
  • Every unique WDM sub-path path will have a similarly unique PropertyPathHandle.
  • PropertyPathHandles are auto-generated (done by hand for now) by a trait compiler from IDL and is represented as an enumerant list in the corresponding trait's header file.
  • With this construct, application logic never has to deal with WDM paths directly. Rather, their interactions with WDM are conducted exclusively through these handles.
  • There are two reserved values for path handles that have specific meaning:
    • 0 indicates a 'NULL' handle
    • 1 indicates a handle that points to the root of the trait instance.

PropertySchemaHandle

uint16_t PropertySchemaHandle

SchemaVersion

uint16_t SchemaVersion

SingleResourceSinkTraitCatalog

SingleResourceTraitCatalog< TraitDataSink > SingleResourceSinkTraitCatalog

SingleResourceSourceTraitCatalog

SingleResourceTraitCatalog< TraitDataSource > SingleResourceSourceTraitCatalog

TimestampType

enum nl::Weave::Profiles::DataManagement_Current::TimestampType TimestampType

The validity and type of timestamp included in EventOptions.

TraitDataHandle

uint16_t TraitDataHandle

duration_t

uint32_t duration_t

Type used to describe the duration, in milliseconds.

event_id_t

uint32_t event_id_t

The type of event ID.

timestamp_t

uint32_t timestamp_t

Type used to describe the timestamp in milliseconds.

utc_timestamp_t

uint64_t utc_timestamp_t

Type used to describe the UTC timestamp in milliseconds.

Variables

sInstance

LoggingManagement sInstance

sLogFileName

char sLogFileName[] = "topazlog"

Functions

BdxErrorHandler

void BdxErrorHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer,
  WEAVE_ERROR aErrorCode
)

BdxGetBlockHandler

void BdxGetBlockHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer,
  uint64_t *aLength,
  uint8_t **aDataBlock,
  bool *aIsLastBlock
)

BdxRejectHandler

void BdxRejectHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer,
  nl::Weave::Profiles::StatusReporting::StatusReport *aReport
)

BdxSendAcceptHandler

WEAVE_ERROR BdxSendAcceptHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer,
  nl::Weave::Profiles::BulkDataTransfer::SendAccept *aSendAcceptMsg
)

BdxXferDoneHandler

void BdxXferDoneHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer
)

BdxXferErrorHandler

void BdxXferErrorHandler(
  nl::Weave::Profiles::BulkDataTransfer::BDXTransfer *aXfer,
  nl::Weave::Profiles::StatusReporting::StatusReport *aXferError
)

CreatePropertyPathHandle

PropertyPathHandle CreatePropertyPathHandle(
  PropertySchemaHandle aPropertyPathSchemaId,
  PropertyDictionaryKey aPropertyPathDictionaryKey
)

EventWriterTLVCopy

WEAVE_ERROR EventWriterTLVCopy(
  TLVWriter & ioWriter,
  uint8_t inDataTag,
  void *appData
)

A helper function that translates an already serialized eventdata element into the event buffer.

Details
Parameters
[in,out] ioWriter
The writer to use for writing out the event
[in] inDataTag
A context tag for the TLV we're copying out. Unused here, but required by the typedef for EventWriterFunct.
[in] appData
A pointer to the TLVReader that holds serialized event data.
Return Values
WEAVE_NO_ERROR
On success.
other
Other errors that mey be returned from the ioWriter.

GetPropertyDictionaryKey

PropertyDictionaryKey GetPropertyDictionaryKey(
  PropertyPathHandle aHandle
)

GetPropertySchemaHandle

PropertySchemaHandle GetPropertySchemaHandle(
  PropertyPathHandle aHandle
)

IsNullPropertyPathHandle

bool IsNullPropertyPathHandle(
  PropertyPathHandle aHandle
)

IsRootPropertyPathHandle

bool IsRootPropertyPathHandle(
  PropertyPathHandle aHandle
)

LogEvent

event_id_t LogEvent(
  const EventSchema & inSchema,
  nl::Weave::TLV::TLVReader & inData
)

Log an event from a pre-serialized form.

The function logs an event represented as a nl::Weave::TLV::TLVReader. This implies that the event data representation is already serialized in the storage underlying the nl::Weave::TLV::TLVReader. The nl::Weave::TLV::TLVReader is expected to contain at least a single data element, that element must be a structure. The first element read out of the reader is treated as event data and stored in the event log. The event data MUST contain context tags to be interpreted within the schema identified by inProfileID and inEventType. The tag of the first element will be ignored; the event logging system will replace it with the eventData tag.

The event is logged if its inImportance exceeds the logging threshold specified in the LoggingConfiguration. If the event's importance does not meet the current threshold, it is dropped and the function returns a 0 as the resulting event ID.

This variant of the invocation implicitly specifies all the default event options:

  • the event is timestamped with the current time at the point of the call,
  • the event is marked as relating to the device that is making the call,
  • the event is standalone, not relating to any other events,
  • the event is marked as non-urgent,

Details
Parameters
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inData
The TLV reader containing the event data as the first element.
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LogEvent

event_id_t LogEvent(
  const EventSchema & inSchema,
  nl::Weave::TLV::TLVReader & inData,
  const EventOptions *inOptions
)

Log an event from a pre-serialized form, with additional options.

The function logs an event represented as a nl::Weave::TLV::TLVReader. This implies that the event data representation is already serialized in the storage underlying the nl::Weave::TLV::TLVReader. The nl::Weave::TLV::TLVReader is expected to contain at least a single data element, that element must be a structure. The first element read out of the reader is treated as event data and stored in the event log. The event data MUST contain context tags to be interpreted within the schema identified by inProfileID and inEventType. The tag of the first element will be ignored; the event logging system will replace it with the eventData tag.

The event is logged if its inImportance exceeds the logging threshold specified in the LoggingConfiguration. If the event's importance does not meet the current threshold, it is dropped and the function returns a 0 as the resulting event ID.

This variant of the invocation permits the caller to set any combination of EventOptions:

  • timestamp, when 0 defaults to the current time at the point of the call,
  • "root" section of the event source (event source and trait ID); if NULL, it defaults to the current device. the event is marked as relating to the device that is making the call,
  • a related event ID for grouping event IDs; when the related event ID is 0, the event is marked as not relating to any other events,
  • urgency; by default non-urgent.

Details
Parameters
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inData
The TLV reader containing the event data as the first element. Must not be NULL
[in] inOptions
The options for the event metadata. May be NULL.
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LogEvent

event_id_t LogEvent(
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData
)

Log an event via a callback.

The function logs an event represented as an EventWriterFunct and an app-specific appData context. The function writes the event metadata and calls the inEventWriter with an nl::Weave::TLV::TLVWriter reference and inAppData context so that the user code can emit the event data directly into the event log. This form of event logging minimizes memory consumption, as event data is serialized directly into the target buffer. The event data MUST contain context tags to be interpreted within the schema identified by inProfileID and inEventType. The tag of the first element will be ignored; the event logging system will replace it with the eventData tag.

The event is logged if its inImportance exceeds the logging threshold specified in the LoggingConfiguration. If the event's importance does not meet the current threshold, it is dropped and the function returns a 0 as the resulting event ID.

This variant of the invocation implicitly specifies all the default event options:

  • the event is timestamped with the current time at the point of the call,
  • the event is marked as relating to the device that is making the call,
  • the event is standalone, not relating to any other events,
  • the event is marked as non-urgent,

Details
Parameters
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inEventWriter
The callback to invoke to actually serialize the event data
[in] inAppData
Application context for the callback.
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LogEvent

event_id_t LogEvent(
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData,
  const EventOptions *inOptions
)

Log an event via a callback, with options.

The function logs an event represented as an EventWriterFunct and an app-specific appData context. The function writes the event metadata and calls the inEventWriter with an nl::Weave::TLV::TLVWriter reference and inAppData context so that the user code can emit the event data directly into the event log. This form of event logging minimizes memory consumption, as event data is serialized directly into the target buffer. The event data MUST contain context tags to be interpreted within the schema identified by inProfileID and inEventType. The tag of the first element will be ignored; the event logging system will replace it with the eventData tag.

The event is logged if its inImportance exceeds the logging threshold specified in the LoggingConfiguration. If the event's importance does not meet the current threshold, it is dropped and the function returns a 0 as the resulting event ID.

This variant of the invocation permits the caller to set any combination of EventOptions:

  • timestamp, when 0 defaults to the current time at the point of the call,
  • "root" section of the event source (event source and trait ID); if NULL, it defaults to the current device. the event is marked as relating to the device that is making the call,
  • a related event ID for grouping event IDs; when the related event ID is 0, the event is marked as not relating to any other events,
  • urgency; by default non-urgent.

Details
Parameters
[in] inSchema
Schema defining importance, profile ID, and structure type of this event.
[in] inEventWriter
The callback to invoke to actually serialize the event data
[in] inAppData
Application context for the callback.
[in] inOptions
The options for the event metadata. May be NULL.
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LogFreeform

event_id_t LogFreeform(
  ImportanceType inImportance,
  const char *inFormat,
  ...
)

LogFreeform emits a freeform string to the default event stream.

The string will be encapsulated in an debug event structure, structurally identical to other logged strings. The event profile ID will be that of a Nest Debug event, and the event type will be kNestDebug_StringLogEntryEvent.

Details
Parameters
[in] inImportance
Importance of the log entry; if the importance falls below the current importance, the event is not actually logged
[in] inFormat
printf-compliant format string, followed by arguments to be formatted
Returns
event_id_t The event ID if the event was written to the log, 0 otherwise.

LookForElementWithTag

WEAVE_ERROR LookForElementWithTag(
  const nl::Weave::TLV::TLVReader & aSrcReader,
  const uint64_t aTagInApiForm,
  nl::Weave::TLV::TLVReader *apDstReader
)

PlainTextWriter

WEAVE_ERROR PlainTextWriter(
  TLVWriter & ioWriter,
  uint8_t inDataTag,
  void *appData
)

A helper function for emitting a freeform text as a debug event.

The debug event is a structure with a logregion and a freeform text.

Details
Parameters
[in,out] ioWriter
The writer to use for writing out the event
[in] appData
A pointer to the DebugLogContext, a structure that holds a string format, arguments, and a log region
[in] inDataTag
A context tag for the TLV we're writing out. Unused here, but required by the typedef for EventWriterFunct.
Return Values
WEAVE_NO_ERROR
On success.
other
Other errors that mey be returned from the ioWriter.

PlainTextWriter

WEAVE_ERROR PlainTextWriter(
  ::nl::Weave::TLV::TLVWriter & ioWriter,
  uint8_t inDataTag,
  void *appData
)

A helper function for emitting a freeform text as a debug event.

The debug event is a structure with a logregion and a freeform text.

Details
Parameters
[in,out] ioWriter
The writer to use for writing out the event
[in] inDataTag
The tag to emit
[in] appData
A pointer to the DebugLogContext, a structure that holds a string format, arguments, and a log region
Return Values
WEAVE_NO_ERROR
On success.
other
Other errors that may be returned from the ioWriter.