fonction waveOutOpen (mmeapi.h)

Article
08/24/2023

La fonction waveOutOpen ouvre le périphérique de sortie audio de forme d’onde donné pour la lecture.

Syntaxe

MMRESULT waveOutOpen(
  LPHWAVEOUT      phwo,
  UINT            uDeviceID,
  LPCWAVEFORMATEX pwfx,
  DWORD_PTR       dwCallback,
  DWORD_PTR       dwInstance,
  DWORD           fdwOpen
);

Paramètres

phwo

Pointeur vers une mémoire tampon qui reçoit un handle identifiant le périphérique de sortie audio de forme d’onde ouverte. Utilisez le handle pour identifier l’appareil lors de l’appel d’autres fonctions de sortie audio de forme d’onde. Ce paramètre peut être NULL si l’indicateur WAVE_FORMAT_QUERY est spécifié pour fdwOpen.

uDeviceID

Identificateur du périphérique de sortie audio de forme d’onde à ouvrir. Il peut s’agir d’un identificateur d’appareil ou d’une poignée d’un périphérique d’entrée audio de forme d’onde ouverte. Vous pouvez également utiliser l’indicateur suivant au lieu d’un identificateur d’appareil :

Valeur	Signification
WAVE_MAPPER	La fonction sélectionne un périphérique de sortie audio de forme d’onde capable de lire le format donné.

pwfx

Pointeur vers une structure WAVEFORMATEX qui identifie le format des données audio de forme d’onde à envoyer à l’appareil. Vous pouvez libérer cette structure immédiatement après l’avoir passée à waveOutOpen.

dwCallback

Spécifie le mécanisme de rappel. La valeur doit être l'une des suivantes :

Pointeur vers une fonction de rappel. Pour la signature de la fonction, consultez waveOutProc.
Handle d'une fenêtre.
Identificateur de thread.
Handle d’un événement.
Valeur NULL.

Le paramètre fdwOpen spécifie la façon dont le paramètre dwCallback est interprété. Pour plus d'informations, consultez la section Notes.

dwInstance

Les données instance l’utilisateur transmises au mécanisme de rappel. Ce paramètre n’est pas utilisé avec le mécanisme de rappel de fenêtre.

fdwOpen

Indicateurs d’ouverture de l’appareil. Les valeurs suivantes sont définies.

Valeur	Signification
CALLBACK_EVENT	Le paramètre dwCallback est un handle d’événement.
CALLBACK_FUNCTION	Le paramètre dwCallback est une adresse de procédure de rappel.
CALLBACK_NULL	Aucun mécanisme de rappel. Il s'agit du paramètre par défaut.
CALLBACK_THREAD	Le paramètre dwCallback est un identificateur de thread.
CALLBACK_WINDOW	Le paramètre dwCallback est un handle de fenêtre.
WAVE_ALLOWSYNC	Si cet indicateur est spécifié, un périphérique audio de forme d’onde synchrone peut être ouvert. Si cet indicateur n’est pas spécifié lors de l’ouverture d’un pilote synchrone, l’appareil ne peut pas s’ouvrir.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Si cet indicateur est spécifié et que le paramètre uDeviceID est WAVE_MAPPER, la fonction ouvre le périphérique de communication par défaut. Cet indicateur s’applique uniquement lorsque uDeviceID est égal à WAVE_MAPPER. Note Nécessite Windows 7
WAVE_FORMAT_DIRECT	Si cet indicateur est spécifié, le pilote ACM n’effectue pas de conversions sur les données audio.
WAVE_FORMAT_QUERY	Si cet indicateur est spécifié, waveOutOpen interroge l’appareil pour déterminer s’il prend en charge le format donné, mais qu’il n’est pas réellement ouvert.
WAVE_MAPPED	Si cet indicateur est spécifié, le paramètre uDeviceID spécifie un périphérique audio de forme d’onde à mapper par le mappeur d’ondes.

Valeur retournée

Retourne MMSYSERR_NOERROR en cas de réussite ou une erreur dans le cas contraire. Les valeurs d’erreur possibles sont les suivantes.

Code de retour	Description
MMSYSERR_ALLOCATED	La ressource spécifiée est déjà allouée.
MMSYSERR_BADDEVICEID	L’identificateur d’appareil spécifié est hors de portée.
MMSYSERR_NODRIVER	Aucun pilote de périphérique n’est présent.
MMSYSERR_NOMEM	Impossible d’allouer ou de verrouiller la mémoire.
WAVERR_BADFORMAT	Tentative d’ouverture avec un format audio de forme d’onde non pris en charge.
WAVERR_SYNC	L’appareil est synchrone, mais waveOutOpen a été appelé sans utiliser l’indicateur WAVE_ALLOWSYNC .

Notes

Utilisez la fonction waveOutGetNumDevs pour déterminer le nombre d’appareils de sortie audio de forme d’onde présents dans le système. Si la valeur spécifiée par le paramètre uDeviceID est un identificateur d’appareil, elle peut varier de zéro à un inférieur au nombre d’appareils présents. La constante WAVE_MAPPER peut également être utilisée comme identificateur d’appareil.

La structure pointée par pwfx peut être étendue pour inclure des informations spécifiques au type pour certains formats de données. Par exemple, pour les données PCM, un UINT supplémentaire est ajouté pour spécifier le nombre de bits par exemple. Dans ce cas, utilisez la structure PCMWAVEFORMAT . Pour tous les autres formats audio de forme d’onde, utilisez la structure WAVEFORMATEX pour spécifier la longueur des données supplémentaires.

Si vous choisissez de faire en sorte qu’une fenêtre ou un thread reçoive des informations de rappel, les messages suivants sont envoyés à la fonction de procédure de fenêtre pour indiquer la progression de la sortie audio de forme d’onde : MM_WOM_OPEN, MM_WOM_CLOSE et MM_WOM_DONE.

Mécanisme de rappel

Les paramètres dwCallback et fdwOpen spécifient la façon dont l’application est informée de la progression de la sortie audio de forme d’onde.

Si fdwOpen contient l’indicateur CALLBACK_FUNCTION , dwCallback est un pointeur vers une fonction de rappel. Pour la signature de la fonction, consultez waveOutProc. Le paramètre uMsg du rappel indique la progression de la sortie audio :

Si fdwOpen contient l’indicateur CALLBACK_WINDOW , dwCallback est un handle d’une fenêtre. La fenêtre reçoit les messages suivants, indiquant la progression :

Si fdwOpen contient l’indicateur CALLBACK_THREAD , dwCallback est un identificateur de thread. Le thread reçoit les messages répertoriés précédemment pour CALLBACK_WINDOW.

Si fdwOpen contient l’indicateur CALLBACK_EVENT , dwCallback est un handle pour un événement. L’événement est signalé chaque fois que l’état de la mémoire tampon de forme d’onde change. L’application peut utiliser WaitForSingleObject ou WaitForMultipleObjects pour attendre l’événement. Lorsque l’événement est signalé, vous pouvez obtenir l’état actuel de la mémoire tampon de forme d’onde en vérifiant le membre dwFlags de la structure WAVEHDR . (Voir waveOutPrepareHeader.)

Si fdwOpen contient l’indicateur CALLBACK_NULL , dwCallback doit avoir la valeur NULL. Dans ce cas, aucun mécanisme de rappel n’est utilisé.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	mmeapi.h (inclure Windows.h)
Bibliothèque	Winmm.lib
DLL	Winmm.dll