Funzione ActivateAudioInterfaceAsync (mmdeviceapi.h)

Consente alle app di Windows Store di accedere alle interfacce COM (Component Object Model) preesistenti nella famiglia 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. Questa operazione viene in genere recuperata da un oggetto DeviceInformation o da 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 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 TBD, è possibile 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 che viene chiamata da Windows quando è disponibile il risultato della procedura di attivazione.

activationOperation

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

Valore restituito

La funzione restituisce un valore HRESULT. I valori possibili includono, ma non sono limitati a, quelli indicati 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 L'oggetto IActivateAudioInterfaceCompletionHandler passato non viene implementato in un oggetto Agile (aggregando un marshalling a thread libero).

Commenti

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

Per molte implementazioni, un'applicazione deve chiamare questa funzione dal thread principale dell'interfaccia utente per attivare un'interfaccia COM nella famiglia WASAPI in modo che il sistema possa visualizzare una finestra di dialogo all'utente. L'applicazione passa un'interfaccia COM di callback IActivateAudioInterfaceCompletionHandler tramite completionHandler. Windows chiama un metodo nell'interfaccia IActivateAudioInterfaceCompletionHandler dell'applicazione 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:

  • Chiamata di ActivateAudioInterfaceAsync con un deviceInterfacePath che specifica un dispositivo di rendering audio e un riid che specifica l'interfaccia IAudioClient .
  • Chiamata di ActivateAudioInterfaceAsync con un deviceInterfacePath che specifica un dispositivo di rendering audio e un riid che specifica l'interfaccia IAudioEndpointVolume .
  • Chiamata di ActivateAudioInterfaceAsync da un servizio di sessione 0. Per altre informazioni, vedere Servizi.
Windows contiene un riferimento all'interfaccia IActivateAudioInterfaceCompletionHandler dell'applicazione fino al completamento dell'operazione e l'applicazione rilascia l'interfaccia IActivateAudioInterfaceAsyncOperation .
Importante  

Le applicazioni non devono liberare l'oggetto che implementa IActivateAudioInterfaceCompletionHandler fino all'esecuzione del callback del gestore di completamento.

 
A seconda dell'interfaccia WASAPI attivata, 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'app ad accedere al microfono. Per altre informazioni sulla richiesta di consenso, vedere Linee guida per i dispositivi che accedono ai dati personali.

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 garantire che non vi sia alcun deadlock quando viene chiamato completionHandler dall'MTA. In caso contrario, si verificherà un E_ILLEGAL_METHOD_CALL .

Requisiti

   
Client minimo supportato Windows 8 [app desktop | App UWP]
Server minimo supportato Windows Server 2012 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione mmdeviceapi.h (include Mmdevapi.idl)
Libreria Mmdevapi.lib
DLL Mmdevapi.dll
IRQL No

Vedere anche

Funzioni audio di base

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler