функция обратного вызова EVT_ACX_STREAM_SET_RENDER_PACKET (acxstreams.h)

Статья
03/10/2023

Событие EvtAcxStreamSetRenderPacket сообщает драйверу, какой пакет был только что освобожден клиентом.

Если сбои отсутствуют, этот пакет должен быть (CurrentRenderPacket + 1), где CurrentRenderPacket — это пакет, из которого в данный момент выполняется потоковая передача драйвера. Драйвер должен продолжать увеличивать Значение CurrentRenderPacket по мере отрисовки пакетов, а не изменять его CurrentRenderPacket в соответствии с этим значением. Свойство будет включать индекс пакета (на основе 0) и, при необходимости, флаг EOS со смещением в байтах конца потока в текущем пакете.

Синтаксис

EVT_ACX_STREAM_SET_RENDER_PACKET EvtAcxStreamSetRenderPacket;

NTSTATUS EvtAcxStreamSetRenderPacket(
  ACXSTREAM Stream,
  ULONG Packet,
  ULONG Flags,
  ULONG EosPacketLength
)
{...}

Параметры

Stream

Объект ACXSTREAM представляет звуковой поток, созданный каналом. Дополнительные сведения см. в разделе ACX — сводка по объектам ACX.

Packet

Номер пакета, записанного ОС в буфер WaveRT. В зависимости от значений, предоставленных драйвером для AcxRtStreamNotifyPacketComplete, число пакета может пропускать значения.

Flags

Флаги могут быть 0 или AcxStreamSetRenderPacketEndOfStream, указывающие, что пакет является последним пакетом в потоке.

EosPacketLength

Длина пакета EOS, если acxStreamSetRenderPacketEndOfStream указан в разделе Флаги. Ноль является допустимым значением. Если acxStreamSetRenderPacketEndOfStream не указан в разделе Флаги, этот параметр следует игнорировать. EosPacketLength измеряется в байтах.

Возвращаемое значение

Возвращает значение STATUS_SUCCESS , если вызов был успешным. В противном случае возвращается соответствующий код ошибки. Дополнительные сведения см. в разделе Использование значений NTSTATUS.

STATUS_DATA_LATE_ERROR — драйвер возвращает эту ошибку, если ОС передает номер пакета, который уже передан или передается в данный момент. В этом случае произошло сбой. Драйвер может при необходимости использовать некоторые данные из пакета или продолжить воспроизведение данных, ранее записанных на этот номер пакета.

STATUS_DATA_OVERRUN — драйвер возвращает эту ошибку, если ОС передает пакет с номером, превышающим значение, которое может быть сохранено в буфере WaveRT. В этом случае произошло сбой. При необходимости драйвер может игнорировать данные в пакете.

STATUS_INVALID_DEVICE_STATE — драйвер возвращает эту ошибку, если ОС вызывает эту подпрограмму после установки флага AcxStreamSetRenderPacketEndOfStream.

STATUS_INVALID_PARAMETER — драйвер возвращает эту ошибку, если он считает какой-либо другой параметр недопустимым, кроме конкретных случаев для других состояний ошибки. Сюда входят все значения флагов, которые не определены выше.

После того как ОС вызовет эту подпрограмму, драйвер может при необходимости использовать предоставленные сведения для оптимизации передачи оборудования. Например, драйвер может оптимизировать передачу DMA или запрограммировать оборудование, чтобы остановить передачу в конце указанного пакета, если ОС не вызовет эту подпрограмму снова, чтобы сообщить драйверу о другом пакете. Это может смягчить звуковые последствия недостаточного потока, например, ввести звуковой разрыв, а не повторять циклический буфер. Однако драйвер по-прежнему обязан увеличить свой внутренний счетчик пакетов и сообщить о событиях уведомлений в номинальном режиме реального времени.

В зависимости от возможностей оборудования, если указан флаг AcxStreamSetRenderPacketEndOfStream, драйвер может заполнить часть буфера WaveRT, следующую за пакетом EOS, в случае, если оборудование передает данные за пределы позиции EOS.

Клиент начинается с предварительной смены буфера. Когда клиент вызывает ReleaseBuffer, это преобразуется в вызов в AudioKSE, который вызовет уровень ACX, который вызывает EvtAcxStreamSetRenderPacket для активного ACXSTREAM. Свойство будет включать индекс пакета (на основе 0) и, при необходимости, флаг EOS со смещением в байтах конца потока в текущем пакете.   

Пример

Ниже приведен пример использования.

    //
    // Init RT streaming callbacks.
    //
    ACX_RT_STREAM_CALLBACKS rtCallbacks;
    ACX_RT_STREAM_CALLBACKS_INIT(&rtCallbacks);

    rtCallbacks.EvtAcxStreamSetRenderPacket = EvtStreamSetRenderPacket;

    status = AcxStreamInitAssignAcxRtStreamCallbacks(StreamInit, &rtCallbacks);

#pragma code_seg("PAGE")
NTSTATUS
EvtStreamSetRenderPacket(
    _In_ ACXSTREAM Stream,
    _In_ ULONG     Packet,
    _In_ ULONG     Flags,
    _In_ ULONG     EosPacketLength
    )
{
    PSTREAM_CONTEXT ctx;
    NTSTATUS        status = STATUS_SUCCESS;

    PAGED_CODE();

    ctx = GetStreamContext(Stream);

    currentPacket = (ULONG)InterlockedCompareExchange((LONG*)&ctx->m_CurrentPacket, -1, -1);

    if (Packet <= currentPacket)
    {
        status = STATUS_DATA_LATE_ERROR;
    }
    else if (Packet > currentPacket + 1)
    {
        status = STATUS_DATA_OVERRUN;
    }

    return status;
}

Требования ACX

Минимальная версия ACX: 1.0

Дополнительные сведения о версиях ACX см. в статье Обзор версий ACX.

Требования

Требование	Значение
Заголовок	acxstreams.h
IRQL	PASSIVE_LEVEL

См. также раздел

Заголовок acxstreams.h