Condividi tramite

Metodo IMMDevice::Activate (mmdeviceapi.h)

  • Articolo

Il metodo Activate crea un oggetto COM con l'interfaccia specificata.

Sintassi

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

Parametri

[in] iid

Identificatore dell'interfaccia. Questo parametro è un riferimento a un GUID che identifica l'interfaccia che il chiamante richiede l'attivazione. Il chiamante userà questa interfaccia per comunicare con l'oggetto COM. Impostare questo parametro su uno degli identificatori di interfaccia seguenti:

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

Per altre informazioni, vedere Osservazioni.

[in] dwClsCtx

Contesto di esecuzione in cui verrà eseguito il codice che gestisce l'oggetto appena creato. Il chiamante può limitare il contesto impostando questo parametro sul OR bit per bit di uno o più valori di enumerazione CLSCTX. In alternativa, il client può evitare di imporre restrizioni di contesto specificando CLSCTX_ALL. Per altre informazioni su CLSCTX, vedere la documentazione di Windows SDK.

[in] pActivationParams

Impostare su NULL per attivare un IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManagero interfaccia IDeviceTopology in un dispositivo endpoint audio. A partire da Windows 10 Build 20348, i chiamanti che attivano un IAudioClient possono impostare pActivationParams a un puntatore a un AUDIOCLIENT_ACTIVATION_PARAMS per configurare un client audio in modalità loopback con un filtro di processo.

Quando si attiva un IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCaptureo interfaccia IDirectSoundCapture8 nel dispositivo, il chiamante può specificare un puntatore a una struttura PROPVARIANT che contiene informazioni sull'inizializzazione del flusso. Per altre informazioni, vedere Osservazioni.

[out] ppInterface

Puntatore a una variabile puntatore in cui il metodo scrive l'indirizzo dell'interfaccia specificata dal parametro iid. Tramite questo metodo, il chiamante ottiene un riferimento contato all'interfaccia. Il chiamante è responsabile del rilascio dell'interfaccia, quando non è più necessario, chiamando il metodo Release dell'interfaccia. Se la chiamata Activate ha esito negativo, *ppInterface è NULL.

Valore restituito

Se il metodo ha esito positivo, restituisce S_OK. Se ha esito negativo, i possibili codici restituiti includono, ma non sono limitati, i valori illustrati nella tabella seguente.

Codice restituito Descrizione
E_NOINTERFACE
 L'oggetto non supporta il tipo di interfaccia richiesto.
E_POINTER
 Il parametro ppInterface è NULL.
E_INVALIDARG
 Il parametro pActivationParams deve essere NULL per l'interfaccia specificata; o pActivationParams punta a dati non validi.
E_OUTOFMEMORY
 Memoria insufficiente.
AUDCLNT_E_DEVICE_INVALIDATED
 L'utente ha rimosso il dispositivo endpoint audio o il dispositivo adattatore a cui si connette il dispositivo endpoint.

Osservazioni

Questo metodo crea un oggetto COM con un'interfaccia specificata dal parametro iid . Il metodo è simile alla funzione CoCreateInstance di Windows , ad eccezione del fatto che il chiamante non fornisce un CLSID come parametro. Per altre informazioni su CoCreateInstance, vedere la documentazione di Windows SDK.

Un client può chiamare il metodo activate dell'interfaccia IMMDevice per un particolare dispositivo endpoint audio per ottenere un riferimento contato a un'interfaccia nel dispositivo. Il metodo può attivare le interfacce seguenti:

Per ottenere l'ID di interfaccia per un'interfaccia, usare l'operatore __uuidof. Ad esempio, l'ID interfaccia di IAudioCaptureClient viene definito come segue: 

const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Per informazioni sull'operatore __uuidof, vedere la documentazione di Windows SDK. Per informazioni su IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8e IMFTrustedOutput vedere la documentazione di Windows SDK.

Il parametro pActivationParams deve essere NULL per una chiamata Activate per creare un IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManagero interfaccia IDeviceTopology per un dispositivo endpoint audio. A partire da Windows 10 Build 20348, i chiamanti che attivano un IAudioClient possono impostare pActivationParams a un puntatore a un AUDIOCLIENT_ACTIVATION_PARAMS per configurare un client audio in modalità loopback con un filtro di processo.

Per una chiamata a Activate per creare un IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCaptureo interfaccia IDirectSoundCapture8, Il chiamante può, come opzione, specificare un valore NULL nonper pActivationParams. In questo caso, pActivationParams punta a una struttura PROPVARIANT che contiene informazioni sull'inizializzazione del flusso. Impostare il membro vt della struttura su VT_BLOB. Impostare il membro blob.pBlobData in modo che punti a una struttura DIRECTX_AUDIO_ACTIVATION_PARAMS che contiene un GUID sessione audio e flag di inizializzazione del flusso. Impostare il membro blob.cbSize su sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Per un esempio di codice, vedere Ruoli dispositivo per DirectShow Applications. Per altre informazioni su PROPVARIANT, vedere la documentazione di Windows SDK.

Un IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCaptureo istanza dell'interfaccia IDirectSoundCapture8 creata dal metodo activate incapsula un flusso nel dispositivo endpoint audio. Durante la chiamata di Activate, il modulo di sistema DirectSound crea il flusso chiamando il metodo IAudioClient::Initialize. Se pActivationParams non èNULL, DirectSound fornisce il GUID della sessione audio e i flag di inizializzazione di flusso dalla struttura DIRECTX_AUDIO_ACTIVATION_PARAMS come parametri di input alla chiamata Initialize. Se pActivationParams è NULL, DirectSound imposta i parametri InitializeAudioSessionGuid e StreamFlags sui rispettivi valori predefiniti, NULL e 0. Questi valori indicano al metodo di assegnare il flusso alla sessione specifica del processo identificata dal valore GUID della sessione GUID_NULL.

Activate può attivare un'interfaccia di IDirectSound o IDirectSound8 solo in un dispositivo endpoint di rendering. Può attivare un'interfaccia IDirectSoundCapture o IDirectSoundCapture8 solo in un dispositivo endpoint di acquisizione. Una chiamata attiva per attivare un IDirectSound o interfaccia di IDirectSoundCapture8 in un dispositivo di acquisizione o in un IDirectSoundCapture o interfaccia IDirectSoundCapture8 in un dispositivo di rendering non riesce e restituisce il codice di errore E_NOINTERFACE.

In Windows 7 un client può chiamare IMMDevice::Activate e specificare, IID_IMFTrustedOutput, per creare un oggetto OTA (Output Trust Authorities) e recuperare un puntatore all'interfaccia IMFTrustedOutput dell'oggetto. Gli OTA possono operare all'interno o all'esterno del percorso multimediale protetto di Media Foundation (PMP) e inviare contenuti all'esterno della pipeline di Media Foundation. Se il chiamante è esterno a PMP, l'OTA potrebbe non funzionare nel PMP e le impostazioni di protezione sono meno affidabili. Per informazioni sull'uso di oggetti protetti per l'audio e il codice di esempio, vedere AUDIO in modalità utente protetta (MDF).

Per informazioni generali sugli oggetti protetti e IMFTrustedOutput, vedere "Protected Media Path" nella documentazione di Media Foundation.

Nota Quando si utilizzano le interfacce ISpatialAudioClient in un titolo di Xbox One Development Kit (XDK), è necessario chiamare EnableSpatialAudio prima di chiamare IMMDeviceEnumerator::EnumAudioEndpoints o IMMDeviceEnumerator::GetDefaultAudioEndpoint. In caso contrario, verrà generato un errore E_NOINTERFACE restituito dalla chiamata a Activate. EnableSpatialAudio è disponibile solo per i titoli XDK e non deve essere chiamato per le app della piattaforma UWP (Universal Windows Platform) in esecuzione su Xbox One, né per i dispositivi non Xbox One.
 
Per esempi di codice che chiamano il metodo Activate , vedere gli argomenti seguenti:

Fabbisogno

Requisito Valore
client minimo supportato Windows Vista [solo app desktop]
server minimo supportato Windows Server 2008 [solo app desktop]
piattaforma di destinazione Finestre
intestazione mmdeviceapi.h

Vedere anche

interfaccia IAudioClient

Interfaccia IAudioEndpointVolume

Interfaccia IAudioMeterInformation

Interfaccia IAudioSessionManager

interfaccia IDeviceTopology

interfaccia IMMDevice