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

Статья
08/06/2024

Событие 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. В зависимости от значений, предоставленных драйвером для AcxRtRtStreamNotifyPacketComplete, номер пакета может пропускать значения.

Flags

Флаги могут быть 0 или KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM = 0x200, указывающие, что пакет является последним пакетом в потоке, и EosPacketLength является допустимой длиной в байтах для пакета. Дополнительные сведения см. в разделе OptionsFlags в KSSTREAM_HEADER структуре (ks.h).

EosPacketLength

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

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

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

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

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

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

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

Замечания

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

В зависимости от возможностей оборудования, если указан флаг KSSTREAM_HEADER_OPTIONSF_ENDOFSTREAM, драйвер может замолчать часть буфера 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

Поделиться через