KsAllocateDefaultClockEx 函式 (ks.h)

發行項
02/26/2024

KsAllocateDefaultClockEx 函式會配置並初始化預設時鐘結構。

語法

KSDDKAPI NTSTATUS KsAllocateDefaultClockEx(
  [out]          PKSDEFAULTCLOCK     *DefaultClock,
  [in, optional] PVOID               Context,
  [in, optional] PFNKSSETTIMER       SetTimer,
  [in, optional] PFNKSCANCELTIMER    CancelTimer,
  [in, optional] PFNKSCORRELATEDTIME CorrelatedTime,
  [in, optional] const KSRESOLUTION  *Resolution,
  [in]           ULONG               Flags
);

參數

[out] DefaultClock

指定呼叫端配置的共享預設時鐘結構。目前的時間會設定為零，而狀態會設定為 KSSTATE_STOP。成功完成此例程時，這個指標所指示的結構將會包含預設時鐘的參考。傳回的數據應該視為不透明，並保留供系統使用。

[in, optional] Context

選擇性地包含替代時間設施的內容。如果使用定時器或相互關聯的時間函式，則必須設定此設定。

[in, optional] SetTimer

選擇性地包含驅動程式定義 KStrSetTimer 函式的指標，用來根據簡報時間產生 DPC 定時器回呼。如果已設定，函式會用來根據目前簡報時間的差異來設定定時器，以產生事件通知。如果您提供 KStrSetTimer 函 式來設定定時器，您也必須提供對應的 KStrCancelTimer 函式。如果要使用預設 KeSetTimerEx 函式來估計下一個通知時間，請在此參數中傳遞 NULL。只有在也使用 KStrCorrelatedTime 函式時，才會設定此參數。 KStrSetTimer 函式必須具有與 KeSetTimerEx 相同的特性。

[in, optional] CancelTimer

選擇性地包含驅動程式定義 KStrCancelTimer 函式的指標，用來取消未完成的定時器回呼。如果您提供 KStrCancelTimer 函式來取消定時器，您也必須提供對應的 KStrSetTimer 函式。如果要使用預設 KeCancelTimer 函式來取消定時器，請在此參數中傳遞 NULL。 KStrCancelTimer 函式必須與 KeCancelTimer 具有相同的特性。

[in, optional] CorrelatedTime

選擇性地包含驅動程式定義 KStrCorrelatedTime 函式的指標，以相互關聯的方式擷取 Presentation 和 Physical Time。這可讓時鐘擁有者完全判斷目前的時間。如果要使用預設 KeQueryPerformanceCounter 函式來規範時間進展，則傳遞 NULL。

[in, optional] Resolution

選擇性地包含時鐘的替代數據粒度和/或錯誤因數。只有在提供替代定時器或相互關聯的時間函式時，才能使用此功能。如果使用替代相互關聯的時間，可能會指定替代的粒度，否則結構項目必須是零。如果使用替代定時器，可能會指定替代 Error，否則結構項目必須是零。

[in] Flags

保留，設定為零。

傳回值

如果成功， KsAllocateDefaultClockEx 函 式會傳回STATUS_SUCCESS，否則會傳回記憶體錯誤。

備註

內部 DefaultClock.ReferenceCount 元素是由 KsAllocateDefaultClock 函式初始化為一個。元素會遞增並遞減，因為每個通知 DPC 都會排入佇列並完成。當結構要釋放時，會使用元素來判斷時鐘的擁有者是否應該釋放結構，或擱置的 DPC 是否應該以異步方式釋放它。