Метод IMiniportWavePci::NewStream (portcls.h)

Статья
08/07/2023

Метод NewStream создает новый экземпляр логического потока, связанного с указанным физическим каналом.

Синтаксис

NTSTATUS NewStream(
  [out]          PMINIPORTWAVEPCISTREAM *Stream,
  [in, optional] PUNKNOWN               OuterUnknown,
  [in]           POOL_TYPE              PoolType,
  [in]           PPORTWAVEPCISTREAM     PortStream,
  [in]           ULONG                  Pin,
  [in]           BOOLEAN                Capture,
  [in]           PKSDATAFORMAT          DataFormat,
  [out]          PDMACHANNEL            *DmaChannel,
  [out]          PSERVICEGROUP          *ServiceGroup
);

Параметры

[out] Stream

Выходной указатель для нового потока. Этот параметр указывает на переменную указателя, выделенную вызывающим объектом, в которую метод записывает указатель на интерфейс IMiniportWavePciStream объекта потока. Вызывающий объект указывает допустимый указатель, отличный от NULL для этого параметра.

[in, optional] OuterUnknown

Указатель на интерфейс IUnknown объекта, который должен агрегировать объект потока. Этот параметр является необязательным. Если агрегирование не требуется, вызывающий объект задает этот параметр как NULL.

[in] PoolType

Указывает тип пула памяти, из которого должно быть выделено хранилище для объекта DMA-канала. Этот параметр будет одним из типов непагированных пулов, определенных в перечислении POOL_TYPE .

[in] PortStream

Указатель на интерфейс IPortWavePciStream объекта потока драйвера порта.

[in] Pin

Указывает идентификатор пин-кода, определяющий открываемую булавку. Если дескриптор фильтра драйвера miniport WavePci указывает в общей сложности n фабрик контактов на фильтре, то допустимые значения параметра Pin находятся в диапазоне от 0 до n–1.

[in] Capture

Указывает, следует ли создавать поток захвата или поток отрисовки. Этот параметр имеет значение TRUE для канала записи (входных данных) и FALSE для канала воспроизведения (вывода).

[in] DataFormat

Указатель на структуру KSDATAFORMAT , задающую формат данных потока.

[out] DmaChannel

Выходной указатель для канала DMA. Этот параметр указывает на выделенную вызывающим элементом переменную указателя, в которую метод записывает указатель на объект IDmaChannel потока. Вызывающий объект указывает допустимый указатель, отличный от NULL для этого параметра.

[out] ServiceGroup

Выходной указатель для группы служб. Этот параметр указывает на выделенную вызывающей переменной указателя, в которую метод записывает указатель на интерфейс IServiceGroup объекта группы служб потока. Это группа служб, которая регистрируется для уведомления об прерывании. Вызывающий объект указывает допустимый указатель, отличный от NULL для этого параметра.

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

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

Если драйвер мини-порта не предоставляет указатель на группу служб (т. е. если NewStream вызов выводит значение NULL через указатель ServiceGroup ), драйвер порта настраивает собственный периодический таймер для обработки событий положения потока и событий часов. Период для этого таймера в настоящее время составляет 20 миллисекунда, но в будущих реализациях этот период может измениться.

Параметры Stream, OuterUnknown, PortStream и ServiceGroup следуют соглашениям о подсчете ссылок для COM-объектов.

Обратите внимание, что NewStream не соответствует обычным соглашениям о подсчете ссылок при обработке указателя, который выводится с помощью параметра DmaChannel OUT. Когда драйвер порта завершает работу с использованием ссылок, получаемых через NewStream другие параметры OUT метода, Stream и ServiceGroup, он освобождает их, как и ожидалось. В отличие от этого, драйвер порта никогда не использует указатель DmaChannel , который он получает от NewStream вызова, и никогда не вызывает Release для объекта DmaChannel .

Пример аудиодрайва ac97 в комплекте драйверов Microsoft Windows (WDK) отражает это поведение. Реализация IMiniportWavePci::NewStream метода в этом примере вызывает Метод AddRef для Stream и ссылки ServiceGroup, которые он выводит, но не ссылки DmaChannel. Это поведение сохраняется для обеспечения обратной совместимости.

Обратите внимание, что NewStream методы для других типов портов (в частности, WaveCyclic) следуют обычным соглашениям о подсчете ссылок для всех их параметров OUT.