Méthode IMiniportWavePci ::NewStream (portcls.h)

Article
02/26/2024

La NewStream méthode crée une nouvelle instance d’un flux logique associé à un canal physique spécifié.

Syntaxe

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

Paramètres

[out] Stream

Pointeur de sortie pour le nouveau flux. Ce paramètre pointe vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit un pointeur vers l’interface IMiniportWavePciStream de l’objet de flux. L’appelant spécifie un pointeur non NULL valide pour ce paramètre.

[in, optional] OuterUnknown

Pointeur vers l’interface IUnknown d’un objet qui doit agréger l’objet de flux. Ce paramètre est facultatif. Si l’agrégation n’est pas requise, l’appelant spécifie ce paramètre comme NULL.

[in] PoolType

Spécifie le type de pool de mémoire à partir duquel le stockage de l’objet de canal DMA doit être alloué. Ce paramètre est l’un des types de pool non paginés définis dans l’énumération POOL_TYPE .

[in] PortStream

Pointeur vers l’interface IPortWavePciStream de l’objet stream du pilote de port.

[in] Pin

Spécifie un ID d’épingle identifiant la broche à ouvrir. Si le descripteur de filtre du pilote de miniport WavePci spécifie un total de n fabriques de broches sur le filtre, les valeurs valides pour le paramètre Pin sont comprises entre 0 et n-1.

[in] Capture

Spécifie s’il faut créer un flux de capture ou un flux de rendu. Ce paramètre est TRUE pour un canal de capture (entrée) et FALSE pour un canal de lecture (sortie).

[in] DataFormat

Pointeur vers une structure KSDATAFORMAT qui spécifie le format de données du flux.

[out] DmaChannel

Pointeur de sortie pour le canal DMA. Ce paramètre pointe vers une variable pointeur allouée par l’appelant dans laquelle la méthode écrit un pointeur vers l’objet IDmaChannel du flux. L’appelant spécifie un pointeur non NULL valide pour ce paramètre.

[out] ServiceGroup

Pointeur de sortie pour le groupe de services. Ce paramètre pointe vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit un pointeur vers l’interface IServiceGroup de l’objet de groupe de services du flux. Il s’agit du groupe de services qui est inscrit pour la notification d’interruption. L’appelant spécifie un pointeur non NULL valide pour ce paramètre.

Valeur retournée

NewStream retourne STATUS_SUCCESS si l’appel a réussi. Sinon, la méthode retourne un code d’erreur approprié.

Remarques

La NewStream méthode définit l’état initial du flux sur KSSTATE_STOP et sa position initiale sur zéro. (Voir IMiniportWavePciStream ::SetState et IMiniportWavePciStream ::GetPosition.)

Le paramètre DataFormat , qui spécifie le format de données du flux, pointe vers l’une des versions étendues spécifiques à l’audio suivantes de la structure KSDATAFORMAT :

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

Si le pilote miniport ne fournit pas de pointeur de groupe de services (autrement dit, si l’appel NewStream sort NULL via le pointeur ServiceGroup ), le pilote de port configure son propre minuteur périodique à la place pour traiter les événements de position et d’horloge du flux. La période de ce minuteur est actuellement de 20 millisecondes, mais la période peut changer dans les implémentations ultérieures.

Les paramètres Stream, OuterUnknown, PortStream et ServiceGroup suivent les conventions de comptage des références pour les objets COM.

Notez que NewStream ne suit pas les conventions de comptage de références habituelles dans sa gestion du pointeur qu’il génère via le paramètre DmaChannel OUT. Lorsque le pilote de port a fini d’utiliser les références qu’il reçoit via les autres paramètres OUT de la NewStream méthode, Stream et ServiceGroup, il les libère, comme prévu. En revanche, le pilote de port n’utilise jamais le pointeur DmaChannel qu’il reçoit de l’appel NewStream et n’appelle jamais Release sur l’objet DmaChannel .

L’exemple de pilote audio ac97 dans le Kit de pilotes Microsoft Windows (WDK) reflète ce comportement. L’implémentation de cet exemple de la IMiniportWavePci::NewStream méthode appelle AddRef sur les références Stream et ServiceGroup qu’elle génère, mais pas la référence DmaChannel. Ce comportement est conservé pour des raisons de compatibilité descendante.

Notez que les NewStream méthodes pour les autres types de ports (WaveCyclique, en particulier) suivent les conventions de comptage de références habituelles pour tous leurs paramètres OUT.