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

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

用于管理内存事件日志的类。

摘要

构造函数和构造函数

LoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources)
LoggingManagement 构造函数。
LoggingManagement(void)
LoggingManagement 默认构造函数。

公共函数

BlitEvent(EventLoadOutContext *aContext, const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
根据事件日志记录协议写入事件标头和数据的帮助程序函数。
CancelShutdownInProgress(void)
void
将 mShutdownInProgress 标志设置为 false。
CheckShouldRunWDM(void)
bool
决定是否根据未安排上传的事件缓冲区中的字节数来分流事件。
FetchEventsSince(nl::Weave::TLV::TLVWriter & ioWriter, ImportanceType inImportance, event_id_t & ioEventID)
自指定事件 ID 以来检索指定重要事件的函数。
GetBytesWritten(void) const
uint32_t
获取自实例化以来写入此日志的字节总数(跨所有事件重要性)。
GetEventReader(nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance)
用于检查内存中日志缓冲区的辅助方法。
GetFirstEventID(ImportanceType inImportance)
获取当前针对特定重要程度存储的第一个事件 ID。
GetLastEventID(ImportanceType inImportance)
获取具有特定重要性级别的最新更新 ID。
IsShutdownInProgress(void)
bool
检查 mShutdownInProgress 标记。
IsValid(void)
bool
IsValid 返回 LoggingManagement 实例是否有效。
LoadEvents(TLVReader & reader)
加载之前保存的 Weave 事件。
LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
使用回调通过选项记录事件。
MarkShutdownInProgress(void)
void
将 mShutdownInProgress 标志设置为 true。
NotifyEventsDelivered(ImportanceType inImportance, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID)
void
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, NotifyExternalEventsEvictedFunct inEvictedCallback, size_t inNumEvents, event_id_t *outLastEventID)
用于注册一组外部存储事件的公共 API。
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, event_id_t *outLastEventID)
用于注册一组外部存储事件的公共 API。
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, event_id_t *outLastEventID)
用于注册一组外部存储事件的公共 API。
ScheduleFlushIfNeeded(bool inFlushRequested)
安排日志分流任务。
SerializeEvents(TLVWriter & writer)
序列化所有重要性类型的 Weave 事件。
SetBDXUploader(LogBDXUpload *inUploader)
void
SetExchangeManager(nl::Weave::WeaveExchangeManager *inMgr)
设置用于此日志记录子系统的 WeaveExchangeManager
SetLoggingEndpoint(event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition)
SkipEvent(EventLoadOutContext *aContext)
void
跳过写入与分配的事件 ID 对应的事件的辅助函数。
ThrottleLogger(void)
void
ThrottleLogger 将有效日志记录级别提高到生产级别。
UnregisterEventCallbackForImportance(ImportanceType inImportance, event_id_t inEventID)
void
用于取消注册一组外部存储的事件的公共 API。
UnthrottleLogger(void)
void
UnthrottleLogger 将有效日志记录级别恢复为配置的日志记录级别。

公共静态函数

CreateLoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources)
void
使用提供的资源创建 LoggingManagement 对象并初始化日志记录管理子系统。
DestroyLoggingManagement(void)
void
执行关停时所需的任何操作。
GetInstance(void)

公共函数

BlitEvent

WEAVE_ERROR BlitEvent(
  EventLoadOutContext *aContext,
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData,
  const EventOptions *inOptions
)

根据事件日志记录协议写入事件标头和数据的帮助程序函数。

详细信息
参数
[in,out] aContext
EventLoadOutContext,使用缓冲区的有状态信息进行初始化。BlitEvent 会使用此上下文更新和保留状态。
[in] inSchema
架构:定义此事件的重要程度、配置文件 ID 和结构类型。
[in] inEventWriter
为序列化事件数据而调用的回调函数。
[in] inAppData
回调的应用上下文。
[in] inOptions
EventOptions,用于描述与此事件相关的时间戳和其他代码。

取消关闭正在进行

void CancelShutdownInProgress(
  void
)

将 mShutdownInProgress 标志设置为 false。

CheckShouldRunWDM

bool CheckShouldRunWDM(
  void
)

决定是否根据未安排上传的事件缓冲区中的字节数来分流事件。

函数的行为通过 WEAVE_CONFIG_EVENT_LOGGING_BYTE_THRESHOLD 常量进行控制。如果系统自上次 WDM 通知发送以来写入的字节数超过了该上限,该函数就会指示应触发 NotificationEngine

详细信息
返回值
true
事件应分流
false
否则

FetchEventsSince

WEAVE_ERROR FetchEventsSince(
  nl::Weave::TLV::TLVWriter & ioWriter,
  ImportanceType inImportance,
  event_id_t & ioEventID
)

自指定事件 ID 以来检索指定重要事件的函数。

如果有一个 nl::Weave::TLV::TLVWriter、重要性类型和事件 ID,该函数将提取自指定事件以来指定的重要性。相应函数会继续抓取事件,直到 nl::Weave::TLV::TLVWriter 或日志中的空间耗尽为止。函数将在事件边界上终止写入事件。

详细信息
参数
[in] ioWriter
用于存储事件的写入者
[in] inImportance
要提取的事件的重要性
[in,out] ioEventID
输入时,事件 ID 正好在我们要获取的 ID 之前。完成后,上次提取的事件的 ID。
返回值
WEAVE_END_OF_TLV
该函数已达到指定重要性级别的可用日志条目末尾
WEAVE_ERROR_NO_MEMORY
该函数在 ioWriter 中耗尽了,日志中还有更多事件可用。
WEAVE_ERROR_BUFFER_TOO_SMALL
该函数在 ioWriter 中耗尽了,日志中还有更多事件可用。

GetBytes 写入

uint32_t GetBytesWritten(
  void
) const 

获取自实例化以来写入此日志的字节总数(跨所有事件重要性)。

详细信息
返回值
写入日志的字节数。

GetEventReader 类中的方法

WEAVE_ERROR GetEventReader(
  nl::Weave::TLV::TLVReader & ioReader,
  ImportanceType inImportance
)

用于检查内存中日志缓冲区的辅助方法。

详细信息
参数
[in,out] ioReader
对读取器的引用(将通过事件日志中的后备存储空间进行初始化)
[in] inImportance
读者的起始重要性。请注意,在这种情况下,起始重要性有点直观:更重要的事件与专用事件共享的缓冲区不那么重要。因此,当传递调试重要性时,读取器将遍历最少的数据。
返回值
WEAVE_NO_ERROR,无条件。

GetFirstEventID 类

event_id_t GetFirstEventID(
  ImportanceType inImportance
)

获取当前针对特定重要程度存储的第一个事件 ID。

详细信息
参数
inImportance
重要性级别
返回值
event_id_t:当前存储的事件重要性 ID

GetLastEventID

event_id_t GetLastEventID(
  ImportanceType inImportance
)

获取具有特定重要性级别的最新更新 ID。

详细信息
参数
inImportance
重要性级别
返回值
event_id_t - 与事件重要性相匹配的最新事件 ID

正在关闭

bool IsShutdownInProgress(
  void
)

检查 mShutdownInProgress 标记。

有效

bool IsValid(
  void
)

IsValid 返回 LoggingManagement 实例是否有效。

详细信息
返回值
true
实例有效(使用相应的后备存储区进行了初始化)
false
否则

加载事件数

WEAVE_ERROR LoadEvents(
  TLVReader & reader
)

加载之前保存的 Weave 事件。

日志事件

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

使用回调通过选项记录事件。

该函数会记录以 EventWriterFunct 表示的事件和特定于应用的 appData 上下文。该函数会写入事件元数据并使用 nl::Weave::TLV::TLVWriter 引用和 inAppData 上下文调用 inEventWriter,以便用户代码可以直接将事件数据发送到事件日志。这种形式的事件日志记录可最大限度地减少内存消耗,因为事件数据会直接序列化到目标缓冲区。事件数据必须包含要在由 inProfileIDinEventType 标识的架构内解读的上下文标记。第一个元素的代码将被忽略;事件日志记录系统将将其替换为 eventData 代码。

如果架构重要性超过 LoggingConfiguration 中指定的日志记录阈值,则记录该事件。如果事件的重要程度未达到当前阈值,则会丢弃该函数,并返回一个 0 作为生成的事件 ID。

调用的以下变体允许调用方设置 EventOptions 的任意组合:

  • 时间戳(当 0 默认为调用点的当前时间时),
  • 事件根源(事件源和特征 ID);如果值为 NULL,则默认使用当前设备;事件被标记为与发起调用的设备相关;
  • 用于为事件 ID 分组的相关事件 ID;如果相关事件 ID 为 0,则会将该事件标记为与任何其他事件都无关;
  • 紧急;默认为非紧急。

详细信息
参数
[in] inSchema
架构:定义此事件的重要程度、配置文件 ID 和结构类型。
[in] inEventWriter
要在实际序列化事件数据时调用的回调函数
[in] inAppData
回调的应用上下文。
[in] inOptions
事件元数据的选项。可以为 NULL。
返回值
event_id_t 事件写入到日志中的事件 ID,否则为 0。

日志记录管理

 LoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  const LogStorageResources *const inLogStorageResources
)

LoggingManagement 构造函数。

使用 LogStorageResources 数组初始化 LoggingManagement。该数组必须为每个有效重要性级别提供一个资源,该数组的元素必须按递增递增重要性数值(并按重要性递减);该数组中的第一个元素对应于为最关键事件分配的资源,最后一个元素对应于最不重要的事件。

详细信息
参数
[in] inMgr
WeaveExchangeManager 与此日志记录子系统结合使用
[in] inNumBuffers
inLogStorageResources 数组中的元素数量
[in] inLogStorageResources
每个重要性级别的 LogStorageResources 数组。

日志记录管理

 LoggingManagement(
  void
)

LoggingManagement 默认构造函数。

提供此参数的主要目的是让编译器满意。

详细信息
返回值

MarkShutdownInProgress

void MarkShutdownInProgress(
  void
)

将 mShutdownInProgress 标志设置为 true。

已传送通知事件数

void NotifyEventsDelivered(
  ImportanceType inImportance,
  event_id_t inLastDeliveredEventID,
  uint64_t inRecipientNodeID
)

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  NotifyExternalEventsEvictedFunct inEvictedCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用于注册一组外部存储事件的公共 API。

注册 FetchExternalEventsFunct 形式的回调。此 API 要求平台知道注册时的事件数量。进行内部工作时,此数字也需要保持不变。由于此 API 不允许平台注册特定的事件 ID,因此会阻止平台持续存储事件(至少具有唯一事件 ID)。

每当订阅者尝试提取取任意范围内的事件 ID 直至取消注册为止,系统就会调用此回调函数。

当外部提供程序想在事件已传送给订阅者以及外部事件对象被逐出时收到通知时,应使用此函数的变体。

发送事件时,外部提供程序会通知接收者,还会告知接收者的节点 ID 以及传送给接收者的最后事件 ID。请注意,外部提供商可能会多次收到同一事件 ID 的通知。处理程序没有任何特定限制,具体而言,处理程序可能会取消注册外部事件 ID。

如果将外部事件对象从日志缓冲区中逐出,则外部提供程序将与外部事件对象的副本一起收到通知。

失败时,指向 ExternalEvents 结构的指针将为 NULL,否则将使用分配给回调的开始和结束事件 ID 进行填充。此指针应该用于取消注册这组事件。

如需详细了解回调必须实现什么,请参阅 FetchExternalEventsFunct 文档。

详细信息
参数
[in] inImportance
重要性级别
[in] inFetchCallback
用于提取外部事件的注册回调
[in] inNotifyCallback
注册以接收递送通知的回调
[in] inEvictedCallback
用于注册逐出通知的回调
[in] inNumEvents
此组中的事件数
[out] outLastEventID
指向 event_id_t 的指针;在成功注册外部事件后,该函数将存储与外部事件块的最后一个事件 ID 对应的事件 ID。该参数可以为 NULL。
返回值
WEAVE_ERROR_NO_MEMORY
如果没有可用的回调槽位。
WEAVE_ERROR_INVALID_ARGUMENT
空函数回调或没有要注册的事件。
WEAVE_NO_ERROR
成功时。

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用于注册一组外部存储事件的公共 API。

注册 FetchExternalEventsFunct 形式的回调。此 API 要求平台知道注册时的事件数量。进行内部工作时,此数字也需要保持不变。由于此 API 不允许平台注册特定的事件 ID,因此会阻止平台持续存储事件(至少具有唯一事件 ID)。

每当订阅者尝试提取取任意范围内的事件 ID 直至取消注册为止,系统就会调用此回调函数。

当外部提供程序想要在将事件传送给订阅者时收到通知,但不应使用外部事件对象逐出时,应使用此函数的变体。发送事件时,外部提供程序会通知接收者,还会告知接收者的节点 ID 以及传送给接收者的最后事件 ID。请注意,外部提供商可能会多次收到同一事件 ID 的通知。处理程序没有任何特定限制,具体而言,处理程序可能会取消注册外部事件 ID。

失败时,指向 ExternalEvents 结构的指针将为 NULL,否则将使用分配给回调的开始和结束事件 ID 进行填充。此指针应该用于取消注册这组事件。

如需详细了解回调必须实现什么,请参阅 FetchExternalEventsFunct 文档。

详细信息
参数
[in] inImportance
重要性级别
[in] inCallback
用于提取外部事件的注册回调
[in] inNotifyCallback
注册以接收递送通知的回调
[in] inNumEvents
此组中的事件数
[out] outLastEventID
指向 event_id_t 的指针;在成功注册外部事件后,该函数将存储与外部事件块的最后一个事件 ID 对应的事件 ID。该参数可以为 NULL。
返回值
WEAVE_ERROR_NO_MEMORY
如果没有可用的回调槽位。
WEAVE_ERROR_INVALID_ARGUMENT
空函数回调或没有要注册的事件。
WEAVE_NO_ERROR
成功时。

RegisterEventCallbackForImportance

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用于注册一组外部存储事件的公共 API。

注册 FetchExternalEventsFunct 形式的回调。此 API 要求平台知道注册时的事件数量。进行内部工作时,此数字也需要保持不变。由于此 API 不允许平台注册特定的事件 ID,因此会阻止平台持续存储事件(至少具有唯一事件 ID)。

每当订阅者尝试提取取任意范围内的事件 ID 直至取消注册为止,系统就会调用此回调函数。

当外部提供程序既已传送外部事件也要求外部事件对象被逐出时,应使用该函数的此变体。

失败时,指向 ExternalEvents 结构的指针将为 NULL,否则将使用分配给回调的开始和结束事件 ID 进行填充。此指针应该用于取消注册这组事件。

如需详细了解回调必须实现什么,请参阅 FetchExternalEventsFunct 文档。

详细信息
参数
[in] inImportance
重要性级别
[in] inCallback
用于提取外部事件的注册回调
[in] inNumEvents
此组中的事件数
[out] outLastEventID
指向 event_id_t 的指针;在成功注册外部事件后,该函数将存储与外部事件块的最后一个事件 ID 对应的事件 ID。该参数可以为 NULL。
返回值
WEAVE_ERROR_NO_MEMORY
如果没有可用的回调槽位。
WEAVE_ERROR_INVALID_ARGUMENT
空函数回调或没有要注册的事件。
WEAVE_NO_ERROR
成功时。

时间安排 FlushIfNeeded

WEAVE_ERROR ScheduleFlushIfNeeded(
  bool inFlushRequested
)

安排日志分流任务。

该函数决定是否安排任务分流进程,如果是,它会安排 LoggingFlushHandler 在 Weave 线程上异步运行。

是否安排定期刷新取决于三个因素:

刷新缓冲区的显式请求

事件缓冲区的状态以及尚未与事件使用方同步的数据量

是否已存在待处理的请求清空请求事件。

通过输入参数传递明确安排刷新的请求。

通常,当事件缓冲区包含的数据足以开始新的分流时,系统就会安排自动刷新。根据分流策略,可能还考虑了其他触发器,例如分流的最短和最长间隔。

事件日志的待处理状态由 mUploadRequested 变量指示。由于可被多个线程调用,因此 mUploadRequested 必须以原子方式进行读取和设置,以免在发送通知之前调度冗余的 LoggingFlushHandler

详细信息
参数
inRequestFlush
指示是否应安排刷新(无论内部缓冲区管理政策为何)的布尔值。
返回值
WEAVE_ERROR_INCORRECT_STATE
LoggingManagement 模块未完全初始化。
WEAVE_NO_ERROR
成功时。

序列化事件

WEAVE_ERROR SerializeEvents(
  TLVWriter & writer
)

序列化所有重要性类型的 Weave 事件。

将 WeaveCircularTLVBuffer 中的事件和相关状态序列化到提供的缓冲区中。

该方法适用于没有在休眠时保留 RAM 的设备,从而可让它们在进入休眠状态之前保留事件,从而防止丢失事件

SetBDXUploader

void SetBDXUploader(
  LogBDXUpload *inUploader
)

设置交换管理器

WEAVE_ERROR SetExchangeManager(
  nl::Weave::WeaveExchangeManager *inMgr
)

设置用于此日志记录子系统的 WeaveExchangeManager

在某些平台上,这可能需要与上述 CreateLoggingManagement() 分开进行。

详细信息
参数
[in] inMgr
WeaveExchangeManager 与此日志记录子系统结合使用

设置 LoggingEndpoint

WEAVE_ERROR SetLoggingEndpoint(
  event_id_t *inEventEndpoints,
  size_t inNumImportanceLevels,
  size_t & outLoggingPosition
)

SkipEvent

void SkipEvent(
  EventLoadOutContext *aContext
)

跳过写入与分配的事件 ID 对应的事件的辅助函数。

详细信息
参数
[in,out] aContext
EventLoadOutContext,使用缓冲区的有状态信息进行初始化。BlitEvent 会使用此上下文更新和保留状态。

ThrottleLogger

void ThrottleLogger(
  void
)

ThrottleLogger 将有效日志记录级别提高到生产级别。

UnregisterEventCallbackForImportance

void UnregisterEventCallbackForImportance(
  ImportanceType inImportance,
  event_id_t inEventID
)

用于取消注册一组外部存储的事件的公共 API。

取消注册回调将阻止 LoggingManagement 针对一组事件调用回调。LoggingManagement 不会再将这些事件 ID 发送给订阅者。

intent 旨在供一个函数一次提供一组事件。如果需要使用同一函数注册一组新事件,则应先取消回调,然后重新注册。这意味着系统无法再提取原始事件组。

此函数可成功无条件地执行。如果该回调从未注册或已被取消注册,则属于空操作。

详细信息
参数
[in] inImportance
重要性级别
[in] inEventID
与要取消注册的外部事件块中的任何事件相对应的事件 ID。

UnthrottleLogger

void UnthrottleLogger(
  void
)

UnthrottleLogger 将有效日志记录级别恢复为配置的日志记录级别。

公共静态函数

创建日志记录

void CreateLoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  const LogStorageResources *const inLogStorageResources
)

使用提供的资源创建 LoggingManagement 对象并初始化日志记录管理子系统。

使用 LogStorageResources 数组初始化 LoggingManagement。该数组必须为每个有效重要性级别提供一个资源,该数组的元素必须按递增递增重要性数值(并按重要性递减);该数组中的第一个元素对应于为最关键事件分配的资源,最后一个元素对应于最不重要的事件。

详细信息
参数
[in] inMgr
WeaveExchangeManager 与此日志记录子系统结合使用
[in] inNumBuffers
inLogStorageResources 数组中的元素数量
[in] inLogStorageResources
每个重要性级别的 LogStorageResources 数组。

销毁日志记录管理

void DestroyLoggingManagement(
  void
)

执行关停时所需的任何操作。

GetInstance

LoggingManagement & GetInstance(
  void
)