IMiniportWavePci::NewStream-Methode (portcls.h)

Artikel
02/27/2024

Die NewStream -Methode erstellt eine neue instance eines logischen Datenstroms, der einem angegebenen physischen Kanal zugeordnet ist.

Syntax

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

Parameter

[out] Stream

Ausgabezeiger für den neuen Stream. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die Methode einen Zeiger auf die IMiniportWavePciStream-Schnittstelle des Streamobjekts schreibt. Der Aufrufer gibt einen gültigen Nicht-NULL-Zeiger für diesen Parameter an.

[in, optional] OuterUnknown

Zeiger auf die IUnknown-Schnittstelle eines Objekts, das das Streamobjekt aggregieren muss. Dieser Parameter ist optional. Wenn die Aggregation nicht erforderlich ist, gibt der Aufrufer diesen Parameter als NULL an.

[in] PoolType

Gibt den Typ des Speicherpools an, aus dem der Speicher für das DMA-Kanalobjekt zugeordnet werden soll. Dieser Parameter ist einer der nicht auslagerten Pooltypen, die in der POOL_TYPE-Enumeration definiert sind.

[in] PortStream

Zeiger auf die IPortWavePciStream-Schnittstelle des Streamobjekts des Porttreibers.

[in] Pin

Gibt eine Pin-ID an, die den zu öffnenden Pin identifiziert. Wenn der Filterdeskriptor des WavePci-Miniporttreibers insgesamt n Pin-Fabriken für den Filter angibt, liegen die gültigen Werte für den Parameter Pin im Bereich von 0 bis n-1.

[in] Capture

Gibt an, ob ein Aufzeichnungsstream oder ein Renderdatenstrom erstellt werden soll. Dieser Parameter ist TRUE für einen Erfassungskanal (Eingabekanal) und FALSE für einen Wiedergabekanal (Ausgabekanal).

[in] DataFormat

Zeiger auf eine KSDATAFORMAT-Struktur , die das Datenformat des Datenstroms angibt.

[out] DmaChannel

Ausgabezeiger für den DMA-Kanal. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die Methode einen Zeiger auf das IDmaChannel-Objekt des Datenstroms schreibt. Der Aufrufer gibt einen gültigen Nicht-NULL-Zeiger für diesen Parameter an.

[out] ServiceGroup

Ausgabezeiger für die Dienstgruppe. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die Methode einen Zeiger auf die IServiceGroup-Schnittstelle des Dienstgruppenobjekts des Streams schreibt. Dies ist die Dienstgruppe, die für Unterbrechungsbenachrichtigungen registriert wird. Der Aufrufer gibt einen gültigen Nicht-NULL-Zeiger für diesen Parameter an.

Rückgabewert

NewStream gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Andernfalls gibt die Methode einen entsprechenden Fehlercode zurück.

Hinweise

Die NewStream -Methode legt den Anfangszustand des Datenstroms auf KSSTATE_STOP und seine Anfangsposition auf 0 (Null) fest. (Siehe IMiniportWavePciStream::SetState und IMiniportWavePciStream::GetPosition.)

Der DataFormat-Parameter , der das Datenformat des Datenstroms angibt, verweist auf eine der folgenden audiospezifischen, erweiterten Versionen der KSDATAFORMAT-Struktur :

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

Wenn der Miniporttreiber keinen Dienstgruppenzeiger bereitstellt (d. h. wenn der NewStream Aufruf NULL über den ServiceGroup-Zeiger ausgibt), richtet der Porttreiber stattdessen einen eigenen periodischen Timer für die Verarbeitung von Datenstrompositions- und Uhrereignissen ein. Der Zeitraum für diesen Timer beträgt derzeit 20 Millisekunden, aber der Zeitraum kann sich in zukünftigen Implementierungen ändern.

Die Parameter Stream, OuterUnknown, PortStream und ServiceGroup folgen den Referenzzählungskonventionen für COM-Objekte.

Beachten Sie, dass NewStream bei der Behandlung des Zeigers, den er über den DmaChannel OUT-Parameter ausgibt, nicht den üblichen Referenzzählungskonventionen folgt. Wenn der Porttreiber die Verweise verwendet, die er über die anderen OUT-Parameter der NewStream Methode empfängt, Stream und ServiceGroup, gibt er diese wie erwartet frei. Im Gegensatz dazu verwendet der Porttreiber nie den DmaChannel-Zeiger , den NewStream er vom Aufruf empfängt, und ruft nie Release für das DmaChannel-Objekt auf.

Der ac97-Beispiel-Audiotreiber im Microsoft Windows Driver Kit (WDK) spiegelt dieses Verhalten wider. Die Implementierung der IMiniportWavePci::NewStream Methode dieses Beispiels ruft AddRef für die Stream- und ServiceGroup-Verweise auf, die ausgegeben werden, aber nicht für den DmaChannel-Verweis. Dieses Verhalten wird aus Gründen der Abwärtskompatibilität beibehalten.

Beachten Sie, dass die NewStream Methoden für die anderen Porttypen (insbesondere WaveCyclic) den üblichen Referenzzählungskonventionen für alle out-Parameter folgen.