KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION

The KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION property specifies a driver-allocated cyclic buffer for audio data and identifies event notification requirements.

The following table summarizes the features of this property.

Usage Summary Table

Get	Set	Target	Property descriptor type	Property value type
Yes	No	Pin	KSRTAUDIO_BUFFER_PROPERTY_WITH_NOTIFICATION	KSRTAUDIO_BUFFER

The property descriptor (instance data) consists of a KSRTAUDIO_BUFFER_PROPERTY_WITH_NOTIFICATION structure that contains a KSPROPERTY structure along with other members. The client writes its requested buffer size into the structure. The client must specify the base address as NULL unless a specific base address is needed.

This property is used when you want DMA-driven event notification. Based on the NotificationCount member, registered events are signaled once (at the end) or twice (at the mid-point and the end) per cycle through the cyclic buffer. Events are registered using KSPROPERTY_RTAUDIO_REGISTER_NOTIFICATION_EVENT after successfully calling KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION.

The property value (operation data) is a structure of type KSRTAUDIO_BUFFER. The driver fills this structure with the actual buffer size, base address, and memory barrier flag for the cyclic buffer that it has allocated.

Return Value

A KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate failure status code. The following table shows some of the possible failure status codes.

Status code	Meaning
STATUS_UNSUCCESSFUL	A cyclic buffer with the specified combination of buffer attributes cannot be allocated.
STATUS_INSUFFICIENT_RESOURCES	Memory for the buffer cannot be allocated.
STATUS_DEVICE_NOT_READY	The device is not ready.

Remarks

The base address is the virtual memory address at the start of the cyclic buffer. The client can directly access the buffer at this address. The buffer is contiguous in virtual memory. The driver determines whether the buffer is contiguous in physical memory.

The client sets the base address in the property descriptor to NULL. The driver sets the base address in the property value to the virtual address of the allocated audio buffer.

Typically, audio hardware requires that either the audio buffer begins and ends on sample boundaries or it meets other types of hardware-dependent alignment constraints. If sufficient memory is available, the actual size of the buffer is the requested size rounded (up or down) to the nearest sample or other hardware-constrained boundary. Otherwise, the actual size can be less than the requested size.

If a KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION property request succeeds, the property value, which is a structure of type KSRTAUDIO_BUFFER, contains the address and size of the driver-allocated buffer.

Closing the pin automatically frees the buffer that was allocated through this property.

Requirements

Version	Available in Windows Vista and later Windows operating systems.
Header	Ksmedia.h

See also

KSPROPERTY

KSRTAUDIO_BUFFER

KSRTAUDIO_BUFFER_PROPERTY_WITH_NOTIFICATION

KSPROPERTY_RTAUDIO_REGISTER_NOTIFICATION_EVENT