MÉTHODE IMMDevice ::Activate (mmdeviceapi.h)

Article
02/29/2024

La méthode Activate crée un objet COM avec l’interface spécifiée.

Syntaxe

HRESULT Activate(
  [in]  REFIID      iid,
  [in]  DWORD       dwClsCtx,
  [in]  PROPVARIANT *pActivationParams,
  [out] void        **ppInterface
);

Paramètres

[in] iid

Identificateur de l’interface. Ce paramètre est une référence à un GUID qui identifie l’interface que l’appelant demande à activer. L’appelant utilise cette interface pour communiquer avec l’objet COM. Définissez ce paramètre sur l’un des identificateurs d’interface suivants :

IID_IAudioClient

IID_IAudioEndpointVolume

IID_IAudioMeterInformation

IID_IAudioSessionManager

IID_IAudioSessionManager2

IID_IBaseFilter

IID_IDeviceTopology

IID_IDirectSound

IID_IDirectSound8

IID_IDirectSoundCapture

IID_IDirectSoundCapture8

IID_IMFTrustedOutput

IID_ISpatialAudioClient

IID_ISpatialAudioMetadataClient

Pour plus d'informations, consultez la section Notes.

[in] dwClsCtx

Contexte d’exécution dans lequel le code qui gère l’objet nouvellement créé s’exécutera. L’appelant peut restreindre le contexte en définissant ce paramètre sur le bit OR d’une ou de plusieurs valeurs d’énumération CLSCTX . Le client peut également éviter d’imposer des restrictions de contexte en spécifiant CLSCTX_ALL. Pour plus d’informations sur CLSCTX, consultez la documentation SDK Windows.

[in] pActivationParams

Définissez sur NULL pour activer une interface IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager ou IDeviceTopology sur un appareil de point de terminaison audio. Lors de l’activation d’une interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 sur l’appareil, l’appelant peut spécifier un pointeur vers une structure PROPVARIANT qui contient des informations d’initialisation de flux. Pour plus d'informations, consultez la section Notes.

[out] ppInterface

Pointeur vers une variable pointeur dans laquelle la méthode écrit l’adresse de l’interface spécifiée par le paramètre iid. Grâce à cette méthode, l’appelant obtient une référence comptabilisée à l’interface. L’appelant est chargé de libérer l’interface, quand elle n’est plus nécessaire, en appelant la méthode Release de l’interface. Si l’appel Activer échoue, *ppInterface a la valeur NULL.

Valeur retournée

Si la méthode réussit, retourne S_OK. En cas d’échec, les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.

Code de retour	Description
E_NOINTERFACE	L’objet ne prend pas en charge le type d’interface demandé.
E_POINTER	Le paramètre ppInterface a la valeur NULL.
E_INVALIDARG	Le paramètre pActivationParams doit être NULL pour l’interface spécifiée ; ou pActivationParams pointe vers des données non valides.
E_OUTOFMEMORY	Mémoire insuffisante.
AUDCLNT_E_DEVICE_INVALIDATED	L’utilisateur a supprimé le périphérique de point de terminaison audio ou l’appareil adaptateur auquel il se connecte.

Remarques

Cette méthode crée un objet COM avec une interface spécifiée par le paramètre iid . La méthode est similaire à la fonction Windows CoCreateInstance , sauf que l’appelant ne fournit pas de CLSID en tant que paramètre. Pour plus d’informations sur CoCreateInstance, consultez la documentation SDK Windows.

Un client peut appeler la méthode Activate de l’interface IMMDevice pour un périphérique de point de terminaison audio particulier afin d’obtenir une référence comptabilisée à une interface sur cet appareil. La méthode peut activer les interfaces suivantes :

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
IBaseFilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
IMFTrustedOutput

Pour obtenir l’ID d’interface d’une interface, utilisez l’opérateur __uuidof . Par exemple, l’ID d’interface de IAudioCaptureClient est défini comme suit :


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Pour plus d’informations sur l’opérateur __uuidof, consultez la documentation SDK Windows. Pour plus d’informations sur IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8 et IMFTrustedOutput, consultez la documentation SDK Windows.

Le paramètre pActivationParams doit être NULL pour qu’un appel Activate crée une interface IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager ou IDeviceTopology pour un appareil de point de terminaison audio.

Pour qu’un appel Activate crée une interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 , l’appelant peut, en option, spécifier une valeur non NULL pour pActivationParams. Dans ce cas, pActivationParams pointe vers une structure PROPVARIANT qui contient des informations d’initialisation de flux. Définissez le membre vt de la structure sur VT_BLOB. Définissez le membre blob.pBlobData pour qu’il pointe vers une structure DIRECTX_AUDIO_ACTIVATION_PARAMS qui contient un GUID de session audio et des indicateurs d’initialisation de flux. Définissez le membre blob.cbSize sur sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Pour obtenir un exemple de code, consultez Rôles d’appareil pour les applications DirectShow. Pour plus d’informations sur PROPVARIANT, consultez la documentation SDK Windows.

Une interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 instance créée par la méthode Activate encapsule un flux sur le périphérique de point de terminaison audio. Pendant l’appel Activer , le module système DirectSound crée le flux en appelant la méthode IAudioClient ::Initialize . Si pActivationParams n’a pas la valeur NULL, DirectSound fournit le GUID de session audio et les indicateurs d’initialisation de flux de la structure DIRECTX_AUDIO_ACTIVATION_PARAMS en tant que paramètres d’entrée à l’appel Initialize . Si pActivationParams a la valeur NULL, DirectSound définit les paramètres AudioSessionGuid et StreamFlags de la méthode Initialize sur leurs valeurs par défaut respectives, NULL et 0. Ces valeurs indiquent à la méthode d’affecter le flux à la session spécifique au processus identifiée par la valeur GUID de session GUID_NULL.

Activate peut activer une interface IDirectSound ou IDirectSound8 uniquement sur un appareil de point de terminaison de rendu. Il peut activer une interface IDirectSoundCapture ou IDirectSoundCapture8 uniquement sur un appareil de point de terminaison de capture. Un appel Activate pour activer une interface IDirectSound ou IDirectSoundCapture8 sur un appareil de capture ou une interface IDirectSoundCapture ou IDirectSoundCapture8 sur un périphérique de rendu échoue et retourne le code d’erreur E_NOINTERFACE.

Dans Windows 7, un client peut appeler IMMDevice ::Activate et spécifier, IID_IMFTrustedOutput, pour créer un objet OTA (Output Trust Authorities) et récupérer un pointeur vers l’interface IMFTrustedOutput de l’objet. Les otAs peuvent fonctionner à l’intérieur ou à l’extérieur du chemin d’accès multimédia protégé (PMP) de Media Foundation et envoyer du contenu en dehors du pipeline Media Foundation. Si l’appelant est en dehors du PMP, l’OTA peut ne pas fonctionner dans le PMP et les paramètres de protection sont moins robustes. Pour plus d’informations sur l’utilisation d’objets protégés pour l’audio et un exemple de code, consultez Audio en mode utilisateur protégé (PUMA).

Pour obtenir des informations générales sur les objets protégés et IMFTrustedOutput, consultez « Protected Media Path » dans la documentation Media Foundation.

Note Lorsque vous utilisez les interfaces ISpatialAudioClient sur un titre XDK (Xbox One Development Kit), vous devez d’abord appeler EnableSpatialAudio avant d’appeler IMMDeviceEnumerator ::EnumAudioEndpoints ou IMMDeviceEnumerator ::GetDefaultAudioEndpoint. Si vous ne le faites pas, une erreur E_NOINTERFACE est retournée à partir de l’appel à Activer. EnableSpatialAudio est disponible uniquement pour les titres XDK et n’a pas besoin d’être appelé pour plateforme Windows universelle applications s’exécutant sur Xbox One, ni pour les appareils non Xbox One.

Pour obtenir des exemples de code qui appellent la méthode Activate , consultez les rubriques suivantes :

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	mmdeviceapi.h