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 la sezione 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 sull'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'interfaccia IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager o IDeviceTopology in un dispositivo endpoint audio. Quando si attiva un'interfaccia IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture o IDirectSoundCapture8 nel dispositivo, il chiamante può specificare un puntatore a una struttura PROPVARIANT che contiene informazioni di inizializzazione di flusso. Per altre informazioni, vedere la sezione 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 conteggiato all'interfaccia. Il chiamante è responsabile del rilascio dell'interfaccia, quando non è più necessario, chiamando il metodo Release dell'interfaccia. Se la chiamata Attiva ha esito negativo, *ppInterface è NULL.

Valore restituito

Se il metodo ha esito positivo, viene restituito S_OK. Se ha esito negativo, i codici restituiti possibili includono, ma non sono limitati a, i valori visualizzati 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 dell'endpoint audio o il dispositivo adattatore a cui si connette il dispositivo endpoint.

Commenti

Questo metodo crea un oggetto COM con un'interfaccia specificata dal parametro iid . Il metodo è simile alla funzione Windows CoCreateInstance , 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 determinato dispositivo endpoint audio per ottenere un riferimento conteggiato a un'interfaccia nel dispositivo. Il metodo può attivare le interfacce seguenti:

Per ottenere l'ID interfaccia per un'interfaccia, usare l'operatore __uuidof . Ad esempio, l'ID interfaccia di IAudioCaptureClient è 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, IDirectSoundCapture8 e FMTrustedOutput, vedere la documentazione di Windows SDK.

Il parametro pActivationParams deve essere NULL per una chiamata Attiva per creare un'interfaccia IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager o IDeviceTopology per un dispositivo endpoint audio.

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

Un'istanza dell'interfaccia IBaseFilter, IDirectSound8, IDirectSoundCapture o IDirectSoundCapture8 creata dal metodo Activate incapsula un flusso nel dispositivo endpoint audio. Durante la chiamata Attiva , 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 Inizializza . Se pActivationParams è NULL, DirectSound imposta i parametri AudioSessionGuid e StreamFlags del metodo Initialize 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.

L'attivazione può attivare un'interfaccia 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'interfaccia IDirectSound o IDirectSoundCapture8 in un dispositivo di acquisizione o in un'interfaccia IDirectSoundCapture8 in un dispositivo di rendering ha esito negativo e restituisce il codice di errore E_NOINTERFACE.

In Windows 7 un client può chiamare IMMDevice::Attiva e specificare, IID_IMFTrustedOutput, per creare un oggetto OTA (Output Trust Authority) e recuperare un puntatore all'interfaccia FMTrustedOutput dell'oggetto. Gli OTA possono operare all'interno o all'esterno del percorso multimediale protetto di Media Foundation (PMP) e inviare contenuto 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 (PUMA).

Per informazioni generali sugli oggetti protetti e FMTrustedOutput, vedere "Percorso multimediale protetto" nella documentazione di Media Foundation.

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

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione mmdeviceapi.h

Vedi anche

Interfaccia IAudioClient

Interfaccia IAudioEndpointVolume

Interfaccia IAudioMeterInformation

Interfaccia IAudioSessionManager

Interfaccia IDeviceTopology

Interfaccia IMMDevice