Méthode IMiniportDMus ::NewStream (dmusicks.h)

Article
08/11/2023

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

Syntaxe

NTSTATUS NewStream(
  [out]          PMXF             *MXF,
  [in, optional] PUNKNOWN         OuterUnknown,
  [in]           POOL_TYPE        PoolType,
  [in]           ULONG            PinID,
  [in]           DMUS_STREAM_TYPE StreamType,
  [in]           PKSDATAFORMAT    DataFormat,
  [out]          PSERVICEGROUP    *ServiceGroup,
  [in]           PAllocatorMXF    AllocatorMXF,
  [in]           PMASTERCLOCK     MasterClock,
  [out]          PULONGLONG       SchedulePreFetch
);

Paramètres

[out] MXF

Pointeur de sortie pour le nouveau flux. Ce paramètre pointe vers une variable pointeur allouée par l’appelant dans laquelle la méthode écrit un pointeur vers l’interface IMXF de l’objet de flux.

[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 défini sur l’une des valeurs d’énumération POOL_TYPE .

[in] PinID

Spécifie l’ID d’épingle. Ce paramètre identifie l’épingle à ouvrir. Si la méthode IMiniport ::GetDescription du pilote miniport DMus génère un descripteur de filtre qui spécifie un total de n fabriques de broches sur le filtre, les ID de broche valides se trouvent entre 0 et n-1.

[in] StreamType

Spécifie le type de flux de données à créer. Ce paramètre est défini sur l’une des valeurs d’énumération DMUS_STREAM_TYPE suivantes :

DMUS_STREAM_MIDI_RENDER

Spécifie un flux de sortie (lecture) MIDI.

DMUS_STREAM_MIDI_CAPTURE

Spécifie un flux d’entrée MIDI.

DMUS_STREAM_WAVE_SINK

Spécifie un flux de sortie d’onde.

Pour plus d'informations, consultez la section Notes qui suit.

[in] DataFormat

Pointeur vers une structure KSDATAFORMAT de streaming du noyau spécifiant le format de données à utiliser pour cette instance

[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.

[in] AllocatorMXF

Pointeur vers un objet IAllocatorMXF . Il s’agit de l’allocateur de mémoire du pilote de port, qui est nécessaire pour recycler DMUS_KERNEL_EVENT structures.

[in] MasterClock

Pointeur vers un objet IMasterClock . Cette horloge master passe un wrapper pour l’horloge KS au pilote miniport. Le pointeur master-horloge est nécessaire pour effectuer la synchronisation avec l’heure de référence.

[out] SchedulePreFetch

Pointeur de sortie pour l’heure de planification-prérécupération. Ce paramètre est un pointeur vers une variable ULONGLONG allouée par l’appelant dans laquelle la méthode écrit une valeur de temps qui spécifie la distance à suivre pour rechercher des événements. L’heure est spécifiée en unités de 100 nanosecondes. Le pilote de port est chargé de séquencer tous les événements qui dépassent la durée spécifiée ici par le pilote miniport.

Valeur retournée

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

Remarques

Notez que le pilote de port crée l’objet IAllocatorMXF que la NewStream méthode entre par le biais du paramètre pAllocatorMXF , mais que le pilote miniport crée l’objet IMXF que la méthode génère via le paramètre ppMXF . Pour plus d’informations sur IMXF et IAllocatorMXF, consultez Transport MIDI.

La signification du paramètre StreamType de la IMiniportDMus::NewStream méthode est similaire à celle du paramètre Capture de la méthode IMiniportMidi ::NewStream :

Lors de la création d’un flux sur une broche MIDI, le paramètre Capture de la méthode IMiniportMidi ::NewStream indique si la broche doit servir de récepteur pour un flux de rendu MIDI (Capture = FALSE) ou comme source d’un flux de capture MIDI (Capture = TRUE).
De même, lors de la création d’un flux sur une broche MIDI ou DirectMusic, le paramètre StreamType de la IMiniportDMus::NewStream méthode peut indiquer si la broche doit servir de récepteur pour un flux de rendu MIDI (StreamType = DMUS_STREAM_MIDI_RENDER) ou comme source d’un flux de capture MIDI (StreamType = DMUS_STREAM_MIDI_CAPTURE).

Toutefois, une épingle sur un filtre DirectMusic peut prendre en charge une troisième option qui n’est pas disponible avec un filtre MIDI. Une broche peut servir de source d’un flux de sortie d’onde (StreamType = DMUS_STREAM_WAVE_SINK). Le pilote de port DMus implémente le récepteur d’ondes pour ce flux. Après avoir créé le flux de sortie d’onde, le pilote de port DMus interroge l’objet de flux (que le pilote de port obtient via le paramètre de sortie ppMXF de la IMiniportDMus::NewStream méthode) pour son interface ISynthSinkDMus. Le récepteur d’ondes du pilote de port appelle la méthode Render sur cette interface pour extraire les données d’onde du synthétiseur logiciel. Pour plus d’informations, consultez A Wave Sink for Kernel-Mode Software Synthétiseurs.

Les paramètres ppMXF, pOuterUnknown, ppServiceGroup, pAllocatorMXF et pMasterClock suivent les conventions de comptage de références pour les objets COM.