IMMDevice::Activate 메서드(mmdeviceapi.h)

아티클
03/15/2023

Activate 메서드는 지정된 인터페이스를 사용하여 COM 개체를 만듭니다.

구문

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

매개 변수

[in] iid

인터페이스 식별자입니다. 이 매개 변수는 호출자 요청이 활성화될 인터페이스를 식별하는 GUID에 대한 참조입니다. 호출자는 이 인터페이스를 사용하여 COM 개체와 통신합니다. 이 매개 변수를 다음 인터페이스 식별자 중 하나로 설정합니다.

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

자세한 내용은 설명 부분을 참조하세요.

[in] dwClsCtx

새로 만든 개체를 관리하는 코드가 실행되는 실행 컨텍스트입니다. 호출자는 이 매개 변수를 하나 이상의 CLSCTX 열거형 값의 비트 OR로 설정하여 컨텍스트를 제한할 수 있습니다. 또는 클라이언트는 CLSCTX_ALL 지정하여 컨텍스트 제한을 부과하지 않을 수 있습니다. CLSCTX에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

[in] pActivationParams

오디오 엔드포인트 디바이스에서 IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager 또는 IDeviceTopology 인터페이스를 활성화하려면 NULL로 설정합니다. 디바이스 에서 IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture 또는 IDirectSoundCapture8 인터페이스를 활성화할 때 호출자는 스트림 초기화 정보를 포함하는 PROPVARIANT 구조체에 대한 포인터를 지정할 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[out] ppInterface

메서드가 매개 변수 iid로 지정된 인터페이스의 주소를 쓰는 포인터 변수에 대한 포인터입니다. 이 메서드를 통해 호출자는 인터페이스에 대해 계산된 참조를 가져옵니다. 호출자는 인터페이스의 Release 메서드를 호출하여 더 이상 필요하지 않은 경우 인터페이스를 해제 할 책임이 있습니다. 활성화 호출이 실패하면 *ppInterface는 NULL입니다.

반환 값

메서드가 성공하면 S_OK가 반환되고, 실패할 경우 가능한 반환 코드에는 다음 표에 표시된 값이 포함되지만 이에 국한되지는 않습니다.

반환 코드	설명
E_NOINTERFACE	개체는 요청된 인터페이스 형식을 지원하지 않습니다.
E_POINTER	매개 변수 ppInterface 는 NULL입니다.
E_INVALIDARG	pActivationParams 매개 변수는 지정된 인터페이스에 대해 NULL이어야 합니다. 또는 pActivationParams는 잘못된 데이터를 가리킵니다.
E_OUTOFMEMORY	메모리가 부족합니다.
AUDCLNT_E_DEVICE_INVALIDATED	사용자가 엔드포인트 디바이스가 연결하는 오디오 엔드포인트 디바이스 또는 어댑터 디바이스를 제거했습니다.

설명

이 메서드는 iid 매개 변수로 지정된 인터페이스를 사용하여 COM 개체를 만듭니다. 메서드는 호출자가 CLSID를 매개 변수로 제공하지 않는다는 점을 제외하고 Windows CoCreateInstance 함수와 유사합니다. CoCreateInstance에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

클라이언트는 특정 오디오 엔드포인트 디바이스에 대한 IMMDevice 인터페이스의 Activate 메서드를 호출하여 해당 디바이스의 인터페이스에 대한 계산된 참조를 가져올 수 있습니다. 메서드는 다음 인터페이스를 활성화할 수 있습니다.

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

인터페이스에 대한 인터페이스 ID를 가져오려면 __uuidof 연산자를 사용합니다. 예를 들어 IAudioCaptureClient 의 인터페이스 ID는 다음과 같이 정의됩니다.


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

__uuidof 연산자에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요. IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8 및 IMFTrustedOutput에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

오디오 엔드포인트 디바이스에 대한 IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager 또는 IDeviceTopology 인터페이스를 만들려면 활성화 호출에 대해 pActivationParams 매개 변수가 NULL이어야 합니다.

IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture 또는 IDirectSoundCapture8 인터페이스를 만드는 Activate 호출의 경우 호출자는 옵션으로 pActivationParams에 NULL이 아닌 값을 지정할 수 있습니다. 이 경우 pActivationParams는 스트림 초기화 정보가 포함된 PROPVARIANT 구조를 가리킵니다. 구조체의 vt 멤버를 VT_BLOB 설정합니다. blob.pBlobData 멤버를 오디오 세션 GUID 및 스트림 초기화 플래그가 포함된 DIRECTX_AUDIO_ACTIVATION_PARAMS 구조를 가리키도록 설정합니다. blob.cbSize 멤버를 sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS)로 설정합니다. 코드 예제는 DirectShow 애플리케이션에 대한 디바이스 역할을 참조하세요. PROPVARIANT에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

Activate 메서드에서 만든 IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture 또는 IDirectSoundCapture8 인터페이스 instance 오디오 엔드포인트 디바이스의 스트림을 캡슐화합니다. 활성화 호출 중에 DirectSound 시스템 모듈은 IAudioClient::Initialize 메서드를 호출하여 스트림을 만듭니다. pActivationParams가 NULL이 아닌 경우 DirectSound는 DIRECTX_AUDIO_ACTIVATION_PARAMS 구조의 오디오 세션 GUID 및 스트림 초기화 플래그를 초기화 호출에 대한 입력 매개 변수로 제공합니다. pActivationParams가 NULL인 경우 DirectSound는 Initialize 메서드의 AudioSessionGuid 및 StreamFlags 매개 변수를 각각의 기본값인 NULL 및 0으로 설정합니다. 이러한 값은 GUID_NULL 세션 GUID 값으로 식별되는 프로세스별 세션에 스트림을 할당하도록 메서드에 지시합니다.

활성화 는 렌더링 엔드포인트 디바이스에서만 IDirectSound 또는 IDirectSound8 인터페이스를 활성화할 수 있습니다. 캡처 엔드포인트 디바이스에서만 IDirectSoundCapture 또는 IDirectSoundCapture8 인터페이스를 활성화할 수 있습니다. 캡처 디바이스에서 IDirectSound 또는 IDirectSoundCapture8 인터페이스를 활성화하기 위한 활성화 호출 또는 렌더링 디바이스에서 IDirectSoundCapture 또는 IDirectSoundCapture8 인터페이스가 실패하고 오류 코드 E_NOINTERFACE 반환합니다.

Windows 7에서 클라이언트는 IMMDevice::Activate 를 호출하고 IID_IMFTrustedOutput 지정하여 OTA(출력 신뢰 기관) 개체를 만들고 개체의 IMFTrustedOutput 인터페이스에 대한 포인터를 검색할 수 있습니다. OTA는 Media Foundation의 PMP(보호된 미디어 경로) 내부 또는 외부에서 작동하고 Media Foundation 파이프라인 외부에 콘텐츠를 보낼 수 있습니다. 호출자가 PMP 외부에 있는 경우 OTA는 PMP에서 작동하지 않을 수 있으며 보호 설정은 덜 강력합니다. 오디오 및 예제 코드에 보호된 개체를 사용하는 방법에 대한 자세한 내용은 PUMA(보호된 사용자 모드 오디오)를 참조하세요.

보호된 개체 및 IMFTrustedOutput에 대한 일반적인 내용은 Media Foundation 설명서의 "보호된 미디어 경로"를 참조하세요.

참고 Xbox One 개발 키트(XDK) 타이틀에서 ISpatialAudioClient 인터페이스를 사용하는 경우 먼저 IMMDeviceEnumerator::EnumAudioEndpoints 또는 IMMDeviceEnumerator::GetDefaultAudioEndpoint를 호출하기 전에 EnableSpatialAudio를 호출해야 합니다. 이렇게 하지 않으면 활성화 호출에서 E_NOINTERFACE 오류가 반환됩니다. EnableSpatialAudio는 XDK 타이틀에만 사용할 수 있으며 Xbox One에서 실행되는 유니버설 Windows 플랫폼 앱이나 Xbox One 이외의 장치에 대해 호출할 필요가 없습니다.

Activate 메서드를 호출하는 코드 예제는 다음 topics 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	mmdeviceapi.h