本頁面由 Cloud Translation API 翻譯而成。

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)`	`WEAVE_ERROR` 根據事件記錄通訊協定寫入事件標頭和資料的輔助函式。
`CancelShutdownInProgress(void)`	`void` 將 mShutdownInProgress 旗標設為 false。
`CheckShouldRunWDM(void)`	`bool` 依據未排定上傳的事件緩衝區中的位元組數，決定是否卸載事件。
`FetchEventsSince(nl::Weave::TLV::TLVWriter & ioWriter, ImportanceType inImportance, event_id_t & ioEventID)`	`WEAVE_ERROR` 這個函式可用於擷取指定重要性事件 (從指定事件 ID 開始) 的函式。
`GetBytesWritten(void) const`	`uint32_t` 取得此記錄自執行個體化以來寫入的位元組總數 (涵蓋所有事件重要性)。
`GetEventReader(nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance)`	`WEAVE_ERROR` 一種輔助方法，可用於檢查記憶體內記錄緩衝區。
`GetFirstEventID(ImportanceType inImportance)`	`event_id_t` 擷取目前儲存特定重要性等級的第一個事件 ID。
`GetLastEventID(ImportanceType inImportance)`	`event_id_t` 擷取特定重要性等級的最新 ID。
`IsShutdownInProgress(void)`	`bool` 檢查 mShutdownInProgress 旗標。
`IsValid(void)`	`bool` IsValid 會傳回 LoggingManagement 執行個體是否有效。
`LoadEvents(TLVReader & reader)`	`WEAVE_ERROR` 載入先前保留的 Weave 事件。
`LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void inAppData, const EventOptions inOptions)`	`event_id_t` 透過回呼記錄事件，並提供選項。
`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)`	`WEAVE_ERROR` 用於註冊一組外部儲存事件的公用 API。
`RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, event_id_t *outLastEventID)`	`WEAVE_ERROR` 用於註冊一組外部儲存事件的公用 API。
`RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, event_id_t *outLastEventID)`	`WEAVE_ERROR` 用於註冊一組外部儲存事件的公用 API。
`ScheduleFlushIfNeeded(bool inFlushRequested)`	`WEAVE_ERROR` 安排記錄檔卸載工作。
`SerializeEvents(TLVWriter & writer)`	`WEAVE_ERROR` 將所有重要類型的 Weave 事件序列化。
`SetBDXUploader(LogBDXUpload *inUploader)`	`void`
`SetExchangeManager(nl::Weave::WeaveExchangeManager *inMgr)`	`WEAVE_ERROR` 設定要與這個記錄子系統搭配使用的 WeaveExchangeManager。
`SetLoggingEndpoint(event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition)`	`WEAVE_ERROR`
`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)`	`LoggingManagement &`

公用函式

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：說明時間戳記和與這個事件相關的其他標記。

CancelShutdownInProgress

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。

傳回值

`WEAVE_END_OF_TLV`	函式已在指定重要性等級達到可用記錄項目的結尾
`WEAVE_ERROR_NO_MEMORY`	函式已耗盡 ioWriter 中的空間，因此記錄中可用的更多事件。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	函式已耗盡 ioWriter 中的空間，因此記錄中可用的更多事件。

GetBytesWritten

uint32_t GetBytesWritten(
  void
) const

取得此記錄自執行個體化以來寫入的位元組總數 (涵蓋所有事件重要性)。

詳細說明
傳回	寫入記錄的位元組數。

GetEventReader

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

一種輔助方法，可用於檢查記憶體內記錄緩衝區。

詳細說明

參數

`[in,out] ioReader`	讀取器的參照，會使用事件記錄中的備份儲存空間初始化
`[in] inImportance`	讀者的重要性。請注意，在本案例中，起始重要性比較有點直觀：除了專屬緩衝區之外，更重要的事件也會共用較少重要事件的緩衝區。因此，在傳入「Debug」重要性時，讀取器會掃遍最少的資料。

傳回

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

IsShutdownInProgress

bool IsShutdownInProgress(
  void
)

檢查 mShutdownInProgress 旗標。

IsValid

bool IsValid(
  void
)

IsValid 會傳回 LoggingManagement 執行個體是否有效。

詳細說明

傳回值

`true`	該執行個體有效 (使用適當的支援儲存庫初始化)
`false`	其他情況

LoadEvents

WEAVE_ERROR LoadEvents(
  TLVReader & reader
)

載入先前保留的 Weave 事件。

LogEvent

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

透過回呼記錄事件，並提供選項。

這個函式會記錄以 EventWriterFunct 表示的事件，以及應用程式專屬的 appData 背景資訊。這個函式會寫入事件中繼資料，並呼叫 inEventWriter 參照 nl::Weave::TLV::TLVWriter 參照和 inAppData 結構定義，讓使用者程式碼直接將事件資料發至事件記錄檔。由於事件資料會直接序列化到目標緩衝區，因此這種形式的事件記錄功能可將記憶體用量降到最低。事件資料「必須」包含要解讀的結構定義標記 (由 inProfileID 和 inEventType 識別)。系統會忽略第一個元素的標記；事件記錄系統會用 eventData 代碼取代該標記。

如果結構定義重要性超過 LoggingConfiguration 中指定的記錄門檻，系統就會記錄事件。如果事件的重要性不符合目前的門檻，系統會捨棄該事件，且函式會傳回 0 做為產生的事件 ID。

這個叫用變數允許呼叫端設定任何 EventOptions 組合：

時間戳記，如果 0 預設為呼叫當下的目前時間，
事件來源 (事件來源和特徵 ID) 的「根」區段；如果為 NULL，則會預設為目前的裝置。事件會標示為與進行通話的裝置相關，
用來分組事件 ID 的相關事件 ID；當相關事件 ID 為 0 時，系統會將該事件標示為與任何其他事件無關；
緊急狀況；預設為非緊急。

詳細說明

參數

`[in] inSchema`	結構定義會定義這個事件的重要性、設定檔 ID 和結構類型。
`[in] inEventWriter`	叫用此回呼，以便實際將事件資料序列化
`[in] inAppData`	回呼的應用程式結構定義。
`[in] inOptions`	事件中繼資料的選項。可以是空值。

傳回

event_id_t 事件 ID (如果事件寫入記錄中)，則事件 ID 為 0。

LoggingManagement

 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

 LoggingManagement(
  void
)

LoggingManagement 預設建構函式。

主要提供為讓編譯器滿意。

詳細說明
傳回	LoggingManagement

MarkShutdownInProgress

void MarkShutdownInProgress(
  void
)

將 mShutdownInProgress 標記設為 true。

NotifyEventsDelivered

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 結構的指標為空值，否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。

如要進一步瞭解回呼必須實作的內容，請參閱 FetchExternalEventsFunct 文件。

詳細說明

參數

`[in] inImportance`	重要性等級
`[in] inFetchCallback`	用於註冊以擷取外部事件的回呼
`[in] inNotifyCallback`	註冊傳送通知的回呼
`[in] inEvictedCallback`	用於註冊移除通知的回呼
`[in] inNumEvents`	這個組合中的事件數量
`[out] outLastEventID`	指標指向 event_id_t；成功註冊外部事件時，函式會儲存對應外部事件區塊的最後一個事件 ID 的事件 ID。參數可以是空值。

傳回值

`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。

只要訂閱者嘗試擷取範圍內的事件 ID 任意次數，直到取消註冊為止，系統就會呼叫回呼。

如果外部供應器想要在事件傳送至訂閱者時收到通知，則應使用此函式的變化版本，但如果外部事件物件遭到撤銷，就不應該使用該函式變化版本。事件傳送時，外部供應器會收到通知，以及接收者的節點 ID 和最終傳送給該收件者的事件 ID。請注意，系統可能會多次通知外部供應者使用相同的事件 ID。處理常式沒有特定的限制，具體而言，處理常式可能會取消註冊外部事件 ID。

失敗時，ExternalEvents 結構的指標為空值，否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。

如要進一步瞭解回呼必須實作的內容，請參閱 FetchExternalEventsFunct 文件。

詳細說明

參數

`[in] inImportance`	重要性等級
`[in] inCallback`	用於註冊以擷取外部事件的回呼
`[in] inNotifyCallback`	註冊傳送通知的回呼
`[in] inNumEvents`	這個組合中的事件數量
`[out] outLastEventID`	指標指向 event_id_t；成功註冊外部事件時，函式會儲存對應外部事件區塊的最後一個事件 ID 的事件 ID。參數可以是空值。

傳回值

`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。

只要訂閱者嘗試擷取範圍內的事件 ID 任意次數，直到取消註冊為止，系統就會呼叫回呼。

當外部供應器需要通知，或外部事件物件遭到清除時，都應使用此函式的變體。

失敗時，ExternalEvents 結構的指標為空值，否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。

如要進一步瞭解回呼必須實作的內容，請參閱 FetchExternalEventsFunct 文件。

詳細說明

參數

`[in] inImportance`	重要性等級
`[in] inCallback`	用於註冊以擷取外部事件的回呼
`[in] inNumEvents`	這個組合中的事件數量
`[out] outLastEventID`	指標指向 event_id_t；成功註冊外部事件時，函式會儲存對應外部事件區塊的最後一個事件 ID 的事件 ID。參數可以是空值。

傳回值

`WEAVE_ERROR_NO_MEMORY`	如果沒有可用的回呼運算單元。
`WEAVE_ERROR_INVALID_ARGUMENT`	空值函式回呼或沒有要註冊的事件。
`WEAVE_NO_ERROR`	成功時。

ScheduleFlushIfNeeded

WEAVE_ERROR ScheduleFlushIfNeeded(
  bool inFlushRequested
)

安排記錄檔卸載工作。

函式會決定是否安排工作卸載程序，如果是，則會排定在 Weave 執行緒上以非同步方式執行 LoggingFlushHandler。

安排清除時間取決於三個因素：

清除緩衝區的明確要求

事件緩衝區的狀態，以及尚未與事件用戶端同步處理的資料量

是否有待處理的要求清除要求事件。

排程清除的明確要求會透過輸入參數傳遞。

系統通常會在事件緩衝區包含足夠資料時安排自動清除作業，以利開始新的卸載。視卸載策略而定，可能也會將其他觸發事件 (例如卸載之間的最短和最長時間) 納入考量。

事件記錄的待處理狀態會以 mUploadRequested 變數表示。這個函式可以由多個執行緒呼叫，因此 mUploadRequested 必須自動讀取及設定，以免在通知送出前排定冗餘的 LoggingFlushHandler。

詳細說明

參數

inRequestFlush

布林值，表示無論內部緩衝區管理政策為何，系統是否應安排清除作業。

傳回值

`WEAVE_ERROR_INCORRECT_STATE`	LoggingManagement 模組未完全初始化。
`WEAVE_NO_ERROR`	成功時。

SerializeEvents

WEAVE_ERROR SerializeEvents(
  TLVWriter & writer
)

將所有重要類型的 Weave 事件序列化。

將 WeaveCircularTLVBuffer 中的事件和相關狀態序列化到提供的緩衝區。

這個方法適合在睡眠時未保留 RAM 的裝置使用，讓裝置可以在入睡前保留事件，從而避免事件遺失

SetBDXUploader

void SetBDXUploader(
  LogBDXUpload *inUploader
)

SetExchangeManager

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

設定要與這個記錄子系統搭配使用的 WeaveExchangeManager。

在某些平台上，這可能需要與上述 CreateLoggingManagement() 不同。

詳細說明

參數

[in] inMgr

要與這個記錄子系統搭配使用的 WeaveExchangeManager

SetLoggingEndpoint

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 傳送給訂閱者。

其用途是一次提供一組事件。如果必須使用相同函式註冊一組新事件，則必須先取消註冊回呼，然後重新註冊。這表示系統已無法擷取原始事件組合。

這個函式會無條件成功執行。如果回呼從未註冊或已取消註冊，則屬於免人工管理。

詳細說明

參數

`[in] inImportance`	重要性等級
`[in] inEventID`	與外部事件區塊中任何要取消註冊的事件對應的事件 ID。

UnthrottleLogger

void UnthrottleLogger(
  void
)

UnthrottleLogger 會將有效記錄層級還原至設定的記錄層級。

公開的靜態函式

CreateLoggingManagement

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

建立 LoggingManagement 物件，並使用提供的資源初始化記錄管理子系統。

詳細說明

參數

`[in] inMgr`	要與這個記錄子系統搭配使用的 WeaveExchangeManager
`[in] inNumBuffers`	inLogStorageResources 陣列中的元素數量
`[in] inLogStorageResources`	各重要性等級的 LogStorageResources 陣列。

DestroyLoggingManagement

void DestroyLoggingManagement(
  void
)

執行關機所需的動作。

GetInstance

LoggingManagement & GetInstance(
  void
)

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

摘要

建構函式和解構函式

公用函式

公開的靜態函式

公用函式

BlitEvent

CancelShutdownInProgress

CheckShouldRunWDM

FetchEventsSince

GetBytesWritten

GetEventReader

GetFirstEventID

GetLastEventID

IsShutdownInProgress

IsValid

LoadEvents

LogEvent

LoggingManagement

LoggingManagement

MarkShutdownInProgress

NotifyEventsDelivered

RegisterEventCallbackForImportance

RegisterEventCallbackForImportance

RegisterEventCallbackForImportance

ScheduleFlushIfNeeded

SerializeEvents

SetBDXUploader

SetExchangeManager

SetLoggingEndpoint

SkipEvent

ThrottleLogger

UnregisterEventCallbackForImportance

UnthrottleLogger

公開的靜態函式

CreateLoggingManagement

DestroyLoggingManagement

GetInstance