Metodo IMiniportWavePci::NewStream (portcls.h)

Articolo
08/07/2023

Il NewStream metodo crea una nuova istanza di un flusso logico associato a un canale fisico specificato.

Sintassi

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

Parametri

[out] Stream

Puntatore di output per il nuovo flusso. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive un puntatore nell'interfaccia IMiniportWavePciStream dell'oggetto flusso. Il chiamante specifica un puntatore non NULL valido per questo parametro.

[in, optional] OuterUnknown

Puntatore all'interfaccia IUnknown di un oggetto che deve aggregare l'oggetto flusso. Questo parametro è facoltativo e, Se l'aggregazione non è obbligatoria, il chiamante specifica questo parametro come NULL.

[in] PoolType

Specifica il tipo di pool di memoria da cui deve essere allocata l'archiviazione per l'oggetto canale DMA. Questo parametro sarà uno dei tipi di pool non di paging definiti nell'enumerazione POOL_TYPE .

[in] PortStream

Puntatore all'interfaccia IPortWavePciStream dell'oggetto flusso del driver di porta.

[in] Pin

Specifica un ID pin che identifica il pin da aprire. Se il descrittore di filtro del driver WavePci miniport specifica un totale di n pin factory nel filtro, i valori validi per il parametro Pin sono compresi nell'intervallo da 0 a n-1.

[in] Capture

Specifica se creare un flusso di acquisizione o un flusso di rendering. Questo parametro è TRUE per un canale di acquisizione (input) e FALSE per un canale di riproduzione (output).

[in] DataFormat

Puntatore a una struttura KSDATAFORMAT che specifica il formato di dati del flusso.

[out] DmaChannel

Puntatore di output per il canale DMA. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive un puntatore nell'oggetto IDmaChannel del flusso. Il chiamante specifica un puntatore non NULL valido per questo parametro.

[out] ServiceGroup

Puntatore di output per il gruppo di servizi. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive un puntatore nell'interfaccia IServiceGroup dell'oggetto gruppo di servizi del flusso. Si tratta del gruppo di servizi che viene registrato per la notifica di interruzione. Il chiamante specifica un puntatore non NULL valido per questo parametro.

Valore restituito

NewStream restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, il metodo restituisce un codice di errore appropriato.

Commenti

Il NewStream metodo imposta lo stato iniziale del flusso su KSSTATE_STOP e la relativa posizione iniziale su zero. Vedere IMiniportWavePciStream::SetState e IMiniportWavePciStream::GetPosition.

Il parametro DataFormat , che specifica il formato di dati del flusso, punta a una delle versioni estese specifiche dell'audio seguenti della struttura KSDATAFORMAT :

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

Se il driver miniport non fornisce un puntatore al gruppo di servizi , ovvero se la chiamata restituisce NULL tramite il puntatore ServiceGroup, il driver della porta imposta il proprio timer periodico per l'elaborazione NewStream della posizione del flusso e degli eventi di clock. Il periodo per questo timer è attualmente di 20 millisecondi, ma il periodo potrebbe cambiare nelle implementazioni future.

I parametri Stream, OuterUnknown, PortStream e ServiceGroup seguono le convenzioni di conteggio dei riferimenti per gli oggetti COM.

Si noti che NewStream non segue le consuete convenzioni di conteggio dei riferimenti nella gestione del puntatore restituito tramite il parametro DmaChannel OUT. Al termine dell'utilizzo dei riferimenti ricevuti tramite NewStream altri parametri OUT del metodo, Stream e ServiceGroup, il driver di porta li rilascia, come previsto. Al contrario, il driver di porta non usa mai il puntatore DmaChannel ricevuto dalla NewStream chiamata e non chiama mai Release sull'oggetto DmaChannel .

Il driver audio di esempio ac97 in Microsoft Windows Driver Kit (WDK) riflette questo comportamento. L'implementazione di questo esempio del IMiniportWavePci::NewStream metodo chiama AddRef nei riferimenti Stream e ServiceGroup che restituisce ma non il riferimento DmaChannel. Questo comportamento viene mantenuto per motivi di compatibilità con le versioni precedenti.

Si noti che i NewStream metodi per gli altri tipi di porta (WaveCyclic, in particolare) seguono le consuete convenzioni di conteggio dei riferimenti per tutti i relativi parametri OUT.