KsAllocateDefaultClockEx function (ks.h)

Article
02/22/2024

The KsAllocateDefaultClockEx function allocates and initializes the default clock structure.

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

Parameters

[out] DefaultClock

Specifies the caller-allocated shared default clock structure. The current time is set to zero and the state is set to KSSTATE_STOP. Upon successful completion of this routine, the structure indicated by this pointer will contain a reference to the default clock. The data returned should be treated as opaque and reserved for system use.

[in, optional] Context

Optionally contains the context of the alternate time facilities. This must be set if a timer or correlated time function is used.

[in, optional] SetTimer

Optionally contains a pointer to a driver-defined KStrSetTimer function to use to generate DPC timer callbacks based on a Presentation Time. If this is set, the function will be used to set timers based on deltas to the current Presentation Time in order to generate event notifications. If you supply a KStrSetTimer function to set timers, you must also supply a corresponding KStrCancelTimer function. Pass NULL in this parameter if the default KeSetTimerEx function is to be used to approximate the next notification time. This parameter would normally be set only if a KStrCorrelatedTime function was also being used. The KStrSetTimer function must have the same characteristics as KeSetTimerEx.

[in, optional] CancelTimer

Optionally contains a pointer to a driver-defined KStrCancelTimer function to use to cancel outstanding timer callbacks. If you supply a KStrCancelTimer function to cancel timers, you must also supply a corresponding KStrSetTimer function. Pass NULL in this parameter if the default KeCancelTimer function is to be used to cancel timers. The KStrCancelTimer function must have the same characteristics as KeCancelTimer.

[in, optional] CorrelatedTime

Optionally contains a pointer to a driver-defined KStrCorrelatedTime function to retrieve both the Presentation and Physical Time in a correlated manner. This allows the clock owner to completely determine the current time. Pass NULL if the default KeQueryPerformanceCounter function is to be used to regulate time progression.

[in, optional] Resolution

Optionally contains an alternate Granularity and/or Error factor for the clock. This can only be used only if an alternate timer or correlated time function are being provided. An alternate Granularity may be specified if an alternate correlated time is being used, else the structure element must be zero. An alternate Error may be specified if an alternate timer is being used, else the structure element must be zero.

[in] Flags

Reserved, set to zero.

Return value

The KsAllocateDefaultClockEx function returns STATUS_SUCCESS if successful, or a memory error if unsuccessful.

Remarks

The internal DefaultClock.ReferenceCount element is initialized to one by the KsAllocateDefaultClock function. The element is incremented and decremented as each notification DPC is queued and completed. When the structure is to be freed, the element is used to determine if the owner of the clock should free the structure or if a pending DPC should free it asynchronously.

Requirements

Requirement	Value
Target Platform	Universal
Header	ks.h (include Ks.h)
Library	Ks.lib
IRQL	PASSIVE_LEVEL