KsAllocateDefaultClockEx-Funktion (ks.h)

Artikel
08/07/2023

Die KsAllocateDefaultClockEx-Funktion weist die Standarduhrstruktur zu und initialisiert sie.

Syntax

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
);

Parameter

[out] DefaultClock

Gibt die vom Aufrufer zugewiesene, freigegebene Standarduhrstruktur an. Die aktuelle Zeit wird auf 0 festgelegt, und der Zustand wird auf KSSTATE_STOP festgelegt. Nach erfolgreichem Abschluss dieser Routine enthält die durch diesen Zeiger angegebene Struktur einen Verweis auf die Standarduhr. Die zurückgegebenen Daten sollten als undurchsichtig behandelt und für die Systemverwendung reserviert werden.

[in, optional] Context

Enthält optional den Kontext der alternativen Zeitfunktionen. Dies muss festgelegt werden, wenn ein Timer oder eine korrelierte Zeitfunktion verwendet wird.

[in, optional] SetTimer

Enthält optional einen Zeiger auf eine vom Treiber definierte KStrSetTimer-Funktion , die zum Generieren von DPC-Timer-Rückrufen basierend auf einer Präsentationszeit verwendet werden soll. Wenn dies festgelegt ist, wird die Funktion verwendet, um Timer basierend auf Deltas auf die aktuelle Präsentationszeit festzulegen, um Ereignisbenachrichtigungen zu generieren. Wenn Sie eine KStrSetTimer-Funktion zum Festlegen von Timern bereitstellen, müssen Sie auch eine entsprechende KStrCancelTimer-Funktion bereitstellen. Übergeben Sie NULL in diesem Parameter, wenn die KeSetTimerEx-Standardfunktion verwendet werden soll, um die nächste Benachrichtigungszeit anzunähern. Dieser Parameter wird normalerweise nur festgelegt, wenn auch eine KStrCorrelatedTime-Funktion verwendet wird. Die KStrSetTimer-Funktion muss dieselben Eigenschaften wie KeSetTimerEx aufweisen.

[in, optional] CancelTimer

Enthält optional einen Zeiger auf eine vom Treiber definierte KStrCancelTimer-Funktion , mit der ausstehende Timerrückrufe abgebrochen werden können. Wenn Sie eine KStrCancelTimer-Funktion zum Abbrechen von Timern bereitstellen, müssen Sie auch eine entsprechende KStrSetTimer-Funktion bereitstellen. Übergeben Sie NULL in diesem Parameter, wenn die Standardfunktion KeCancelTimer zum Abbrechen von Timern verwendet werden soll. Die KStrCancelTimer-Funktion muss dieselben Eigenschaften wie KeCancelTimer aufweisen.

[in, optional] CorrelatedTime

Enthält optional einen Zeiger auf eine vom Treiber definierte KStrCorrelatedTime-Funktion , um sowohl die Präsentation als auch die physische Zeit in korrelierter Weise abzurufen. Dadurch kann der Besitzer der Uhr die aktuelle Zeit vollständig bestimmen. Übergeben Sie NULL , wenn die Standardfunktion KeQueryPerformanceCounter verwendet werden soll, um den Zeitverlauf zu regulieren.

[in, optional] Resolution

Enthält optional einen alternativen Granularitäts- und/oder Fehlerfaktor für die Uhr. Dies kann nur verwendet werden, wenn ein alternativer Timer oder eine korrelierte Zeitfunktion bereitgestellt wird. Eine alternative Granularität kann angegeben werden, wenn eine alternative korrelierte Zeit verwendet wird, andernfalls muss das Strukturelement 0 sein. Ein alternativer Fehler kann angegeben werden, wenn ein alternativer Timer verwendet wird, andernfalls muss das Strukturelement 0 sein.

[in] Flags

Reserviert, auf Null festgelegt.

Rückgabewert

Die KsAllocateDefaultClockEx-Funktion gibt bei erfolgreicher Ausführung STATUS_SUCCESS oder bei Erfolg einen Speicherfehler zurück.

Hinweise

Das interne DefaultClock.ReferenceCount-Element wird von der KsAllocateDefaultClock-Funktion als eines initialisiert. Das Element wird inkrementiert und dekrementiert, wenn jede Benachrichtigungs-DPC in die Warteschlange gestellt und abgeschlossen wird. Wenn die Struktur freigegeben werden soll, wird das -Element verwendet, um zu bestimmen, ob der Besitzer der Uhr die Struktur freigeben soll oder ob ein ausstehender DPC sie asynchron freigeben soll.