Funzione ActivateAudioInterfaceAsync (mmdeviceapi.h)

Consente alle app di Windows Store di accedere alle interfacce COM (Component Object Model) preesistenti nella famiglia di WASAPI.

Sintassi

HRESULT ActivateAudioInterfaceAsync(
  [in] LPCWSTR                                  deviceInterfacePath,
  [in] REFIID                                   riid,
  [in] PROPVARIANT                              *activationParams,
  [in] IActivateAudioInterfaceCompletionHandler *completionHandler,
       IActivateAudioInterfaceAsyncOperation    **activationOperation
);

Parametri

[in] deviceInterfacePath

ID dell'interfaccia del dispositivo per un dispositivo audio. Questo viene in genere recuperato da un oggetto DeviceInformation o uno dei metodi della classe MediaDevice.

I GUID DEVINTERFACE_AUDIO_CAPTURE e DEVINTERFACE_AUDIO_RENDER rappresentano rispettivamente l'acquisizione audio predefinita e il dispositivo di rendering. Chiamare StringFromIID per convertire uno di questi GUID in un LPCWSTR da usare per questo argomento.

Specificare AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK per attivare l'interfaccia audio per l'acquisizione del loopback del processo. Per il codice di esempio che illustra lo scenario di acquisizione del loopback del processo, vedere l'esempio di acquisizione dell'API loopback dell'applicazione.

[in] riid

IID di un'interfaccia COM nella famiglia di WASAPI, ad esempio IAudioClient.

[in] activationParams

Parametri di attivazione specifici dell'interfaccia. Per altre informazioni, vedere il parametro pActivationParams in IMMDevice::Activate.

A partire da Windows 10 Build 20438, puoi specificare AUDIOCLIENT_ACTIVATION_PARAMS per attivare l'interfaccia per includere o escludere flussi audio associati a un ID processo specificato.

[in] completionHandler

Interfaccia implementata dal chiamante chiamata da Windows quando il risultato della procedura di attivazione è disponibile.

activationOperation

Restituisce un'interfaccia IActivateAudioInterfaceAsyncOperation che rappresenta l'operazione asincrona di attivazione dell'interfaccia WASAPI richiesta .

Valore restituito

La funzione restituisce un HRESULT. I valori possibili includono, ma non solo, quelli nella tabella seguente.

Codice restituito	Descrizione
S_OK	L'oggetto sottostante e l'operazione asincrona sono stati creati correttamente.
E_ILLEGAL_METHOD_CALL	Nelle versioni di Windows precedenti a Windows 10, questo errore può determinare se la funzione viene chiamata da un apartment COM non corretto o se il IActivateAudioInterfaceCompletionHandler non viene implementato in un oggetto Agile (aggregando un marshalling a thread libero).

Osservazioni

Questa funzione consente alle app di Windows Store di attivare determinate interfacce WASAPI COM dopo aver usato le API Windows Runtime nel Windows.Devices e spazi dei nomi Windows.Media.Devices per selezionare un dispositivo audio.

Per molte implementazioni, un'applicazione deve chiamare questa funzione dal thread dell'interfaccia utente principale per attivare un'interfaccia COM nella famiglia di WASAPI in modo che il sistema possa visualizzare un dialogo all'utente. L'applicazione passa un'interfaccia COM IActivateAudioInterfaceCompletionHandler callback tramite completionHandler. Windows chiama un metodo nel IActivateAudioInterfaceCompletionHandler'interfaccia da un thread di lavoro in COM Multithread Apartment (MTA) quando i risultati dell'attivazione sono disponibili. L'applicazione può quindi chiamare un metodo nell'interfaccia IActivateAudioInterfaceAsyncOperation per recuperare il codice del risultato e l'interfaccia WASAPI richiesta. Esistono alcune attivazioni che sono esplicitamente sicure e pertanto non richiedono che questa funzione venga chiamata dal thread principale dell'interfaccia utente. Queste attivazioni in modo esplicito sicuro includono:

• Chiamando ActivateAudioInterfaceAsync con un deviceInterfacePath che specifica un dispositivo di rendering audio e un riid che specifica l'interfaccia IAudioClient .
• Chiamando ActivateAudioInterfaceAsync con un deviceInterfacePath che specifica un dispositivo di rendering audio e un riid che specifica l'interfaccia IAudioEndpointVolume.
• Chiamata ActivateAudioInterfaceAsync da un servizio sessione 0. Per altre informazioni, vedere Services.

Windows contiene un riferimento all'interfaccia IActivateAudioInterfaceCompletionHandler fino al completamento dell'operazione e l'applicazione rilascia l'interfaccia IActivateAudioInterfaceAsyncOperation. A seconda della 'interfaccia WASAPI, questa funzione può visualizzare una richiesta di consenso la prima volta che viene chiamata. Ad esempio, quando l'applicazione chiama questa funzione per attivare IAudioClient per accedere a un microfono, lo scopo della richiesta di consenso è ottenere l'autorizzazione dell'utente per l'accesso al microfono. Per altre informazioni sulla richiesta di consenso, vedere linee guida per i dispositivi che accedono ai dati personali.

il ActivateAudioInterfaceAsync deve essere chiamato nel thread principale dell'interfaccia utente in modo che sia possibile visualizzare la richiesta di consenso. Se non è possibile visualizzare la richiesta di consenso, l'utente non può concedere l'accesso del dispositivo all'app.

Nelle versioni di Windows precedenti a Windows 10, ActivateAudioInterfaceAsync deve essere chiamato su un thread in un com Single-Threaded Apartment (STA), quando si apre un dispositivo per l'acquisizione audio. Il completionHandler passato in ActivateAudioInterfaceAsync deve implementare IAgileObject per assicurarsi che non sia presente alcun deadlock quando viene chiamato completionHandler dall'MTA. In caso contrario, si verificherà un E_ILLEGAL_METHOD_CALL.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8 [app desktop | App UWP]
server minimo supportato	Windows Server 2012 [app desktop | App UWP]
piattaforma di destinazione	Finestre
intestazione	mmdeviceapi.h (include Mmdevapi.idl)
libreria	Mmdevapi.lib
dll	Mmdevapi.dll
IRQL	No

Vedere anche

funzioni audio di base

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler