KsAllocateDefaultClockEx, fonction (ks.h)

Article
08/07/2023

La fonction KsAllocateDefaultClockEx alloue et initialise la structure d’horloge par défaut.

Syntaxe

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

Paramètres

[out] DefaultClock

Spécifie la structure d’horloge partagée par défaut allouée à l’appelant. L’heure actuelle est définie sur zéro et l’état est défini sur KSSTATE_STOP. Une fois cette routine terminée, la structure indiquée par ce pointeur contient une référence à l’horloge par défaut. Les données retournées doivent être traitées comme opaques et réservées à une utilisation système.

[in, optional] Context

Contient éventuellement le contexte des autres installations d’heure. Cela doit être défini si un minuteur ou une fonction d’heure corrélée est utilisé.

[in, optional] SetTimer

Contient éventuellement un pointeur vers une fonction KStrSetTimer définie par le pilote à utiliser pour générer des rappels du minuteur DPC en fonction d’une heure de présentation. Si cette valeur est définie, la fonction sera utilisée pour définir des minuteurs basés sur des deltas sur l’heure de présentation actuelle afin de générer des notifications d’événements. Si vous fournissez une fonction KStrSetTimer pour définir des minuteurs, vous devez également fournir une fonction KStrCancelTimer correspondante. Passez la valeur NULL dans ce paramètre si la fonction KeSetTimerEx par défaut doit être utilisée pour approximativement l’heure de notification suivante. Ce paramètre n’est normalement défini que si une fonction KStrCorrelatedTime est également utilisée. La fonction KStrSetTimer doit avoir les mêmes caractéristiques que KeSetTimerEx.

[in, optional] CancelTimer

Contient éventuellement un pointeur vers une fonction KStrCancelTimer définie par le pilote à utiliser pour annuler les rappels du minuteur en attente. Si vous fournissez une fonction KStrCancelTimer pour annuler les minuteurs, vous devez également fournir une fonction KStrSetTimer correspondante. Passez la valeur NULL dans ce paramètre si la fonction KeCancelTimer par défaut doit être utilisée pour annuler les minuteurs. La fonction KStrCancelTimer doit avoir les mêmes caractéristiques que KeCancelTimer.

[in, optional] CorrelatedTime

Contient éventuellement un pointeur vers une fonction KStrCorrelatedTime définie par le pilote pour récupérer la présentation et l’heure physique de manière corrélée. Cela permet au propriétaire de l’horloge de déterminer complètement l’heure actuelle. Passez la valeur NULL si la fonction KeQueryPerformanceCounter par défaut doit être utilisée pour réguler la progression du temps.

[in, optional] Resolution

Contient éventuellement un autre facteur de granularité et/ou d’erreur pour l’horloge. Cela ne peut être utilisé que si un minuteur de remplacement ou une fonction d’heure corrélée est fourni. Une autre granularité peut être spécifiée si une autre heure corrélée est utilisée, sinon l’élément de structure doit être égal à zéro. Une autre erreur peut être spécifiée si un minuteur de remplacement est utilisé, sinon l’élément structure doit être égal à zéro.

[in] Flags

Réservé, défini sur zéro.

Valeur retournée

La fonction KsAllocateDefaultClockEx retourne STATUS_SUCCESS en cas de réussite ou une erreur de mémoire en cas d’échec.

Remarques

L’élément DefaultClock.ReferenceCount interne est initialisé en un par la fonction KsAllocateDefaultClock . L’élément est incrémenté et décrémenté à mesure que chaque DPC de notification est mis en file d’attente et terminé. Lorsque la structure doit être libérée, l’élément est utilisé pour déterminer si le propriétaire de l’horloge doit libérer la structure ou si un DPC en attente doit la libérer de manière asynchrone.