using System; using System.Runtime.InteropServices; using Vanara.InteropServices; using static Vanara.PInvoke.Ole32; using static Vanara.PInvoke.PropSys; namespace Vanara.PInvoke { /// Functions, structures and constants from Windows Core Audio Api. public static partial class CoreAudio { /// System Effects are disabled. public const uint ENDPOINT_SYSFX_DISABLED = 0x00000001; /// System Effects are enabled. public const uint ENDPOINT_SYSFX_ENABLED = 0x00000000; /// The DEVICE_STATE_XXX constants indicate the current state of an audio endpoint device. /// /// /// The IMMDeviceEnumerator::EnumAudioEndpoints, IMMDevice::GetState, and /// IMMNotificationClient::OnDeviceStateChanged methods use the DEVICE_STATE_XXX constants. These methods enable clients to /// obtain information about endpoint devices that are in any of the states represented by the DEVICE_STATE_XXX constants. /// /// /// However, a client can open a stream (for example, by obtaining an IAudioClient interface for the device) only on a device /// that is in the DEVICE_STATE_ACTIVE state. /// /// /// The Windows multimedia control panel, Mmsys.cpl, displays the audio endpoint devices in the system. Disabling a device in /// Mmsys.cpl hides the device from the device-discovery mechanisms in higher-level audio APIs, but it does not invalidate any /// stream objects that a client might have instantiated before the device was disabled. For example, if a stream is playing on the /// device when the user disables it in Mmsys.cpl, the stream continues to play uninterrupted. /// /// In contrast, disabling a device in Device Manager effectively removes the device from the system. /// To use Mmsys.cpl to view the rendering devices, open a Command Prompt window and enter the following command: /// control mmsys.cpl,,0 /// To view the capture devices, enter the following command: /// control mmsys.cpl,,1 /// /// Alternatively, you can view the rendering devices or the capture devices in Mmsys.cpl by right-clicking the speaker icon in the /// notification area, which is located on the right side of the taskbar, and selecting Playback Devices or Recording Devices. /// /// /// Mmsys.cpl always displays endpoint devices that are in the DEVICE_STATE_ACTIVE state. In addition, it can be configured to /// display disabled and disconnected devices. /// /// /// To view endpoint devices that are in the DEVICE_STATE_DISABLED and DEVICE_STATE_NOTPRESENT states, right-click in the Mmsys.cpl /// window and select the Show Disabled Devices option. /// /// /// To view endpoint devices that are in the DEVICE_STATE_UNPLUGGED state, right-click in the Mmsys.cpl window and select the /// Show Disconnected Devices option. /// /// /// To view only endpoint devices that are in the DEVICE_STATE_ACTIVE state, deselect both the Show Disabled Devices and /// Show Disconnected Devices options. /// /// /// To enable or disable an endpoint device in Mmsys.cpl, click Playback or Recording, depending on whether the device /// is a playback or recording device. Next, select the device and click Properties. In the Properties window, next to /// Device usage, select either Use this device (enable) or Don't use this device (disable). /// /// // https://docs.microsoft.com/en-us/windows/win32/coreaudio/device-state-xxx-constants [PInvokeData("mmdeviceapi.h", MSDNShortId = "d03f2fbc-313a-42cf-902a-fd9f6dce2a35")] [Flags] public enum DEVICE_STATE { /// /// The audio endpoint device is active. That is, the audio adapter that connects to the endpoint device is present and enabled. /// In addition, if the endpoint device plugs into a jack on the adapter, then the endpoint device is plugged in. /// DEVICE_STATE_ACTIVE = 0x00000001, /// /// The audio endpoint device is disabled. The user has disabled the device in the Windows multimedia control panel, Mmsys.cpl. /// For more information, see Remarks. /// DEVICE_STATE_DISABLED = 0x00000002, /// /// The audio endpoint device is not present because the audio adapter that connects to the endpoint device has been removed /// from the system, or the user has disabled the adapter device in Device Manager. /// DEVICE_STATE_NOTPRESENT = 0x00000004, /// /// The audio endpoint device is unplugged. The audio adapter that contains the jack for the endpoint device is present and /// enabled, but the endpoint device is not plugged into the jack. Only a device with jack-presence detection can be in this /// state. For more information about jack-presence detection, see Audio Endpoint Devices. /// DEVICE_STATE_UNPLUGGED = 0x00000008, /// Includes audio endpoint devices in all states active, disabled, not present, and unplugged. DEVICE_STATEMASK_ALL = 0x0000000f, } /// /// The EDataFlow enumeration defines constants that indicate the direction in which audio data flows between an audio /// endpoint device and an application. /// /// /// The IMMDeviceEnumerator::GetDefaultAudioEndpoint, IMMDeviceEnumerator::EnumAudioEndpoints, IMMEndpoint::GetDataFlow, and /// IMMNotificationClient::OnDefaultDeviceChanged methods use the constants defined in the EDataFlow enumeration. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/ne-mmdeviceapi-edataflow typedef enum // __MIDL___MIDL_itf_mmdeviceapi_0000_0000_0001 { eRender, eCapture, eAll, EDataFlow_enum_count } EDataFlow; [PInvokeData("mmdeviceapi.h", MSDNShortId = "d79315aa-d753-4674-84c2-9ba601f36f57")] public enum EDataFlow { /// /// Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream. /// eRender, /// Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application. eCapture, /// /// Audio rendering or capture stream. Audio data can flow either from the application to the audio endpoint device, or from the /// audio endpoint device to the application. /// eAll, /// The number of members in the EDataFlow enumeration (not counting the EDataFlow_enum_count member). EDataFlow_enum_count, } /// /// The EndpointFormFactor enumeration defines constants that indicate the general physical attributes of an audio endpoint device. /// /// /// The constants in this enumeration are the values that can be assigned to the PKEY_AudioEndpoint_FormFactor property. /// /// In digital pass-through mode, a digital interface transports blocks of non-PCM data through a connection without modifying them /// and without attempting to interpret their contents. For more information about digital pass-through mode, see the following documentation: /// /// /// /// The descriptions of the WAVE_FORMAT_WMA_SPDIF and WAVE_FORMAT_DOLBY_AC3_SPDIF wave-format tags in the Windows DDK documentation. /// /// /// /// The white paper titled "Audio Driver Support for the WMA Pro-over-S/PDIF Format" at the Audio Device Technologies for Windows website. /// /// /// /// /// For information about obtaining a description of the audio jack or connector through which an audio endpoint device connects to /// an audio adapter, see IKsJackDescription::GetJackDescription and IKsJackDescription2::GetJackDescription2. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/ne-mmdeviceapi-endpointformfactor typedef enum // __MIDL___MIDL_itf_mmdeviceapi_0000_0000_0003 { RemoteNetworkDevice, Speakers, LineLevel, Headphones, Microphone, Headset, // Handset, UnknownDigitalPassthrough, SPDIF, DigitalAudioDisplayDevice, UnknownFormFactor, EndpointFormFactor_enum_count } EndpointFormFactor; [PInvokeData("mmdeviceapi.h", MSDNShortId = "3fd3782b-c0fc-4d75-8627-d898e7fae436")] public enum EndpointFormFactor { /// An audio endpoint device that the user accesses remotely through a network. RemoteNetworkDevice, /// A set of speakers. Speakers, /// /// An audio endpoint device that sends a line-level analog signal to a line-input jack on an audio adapter or that receives a /// line-level analog signal from a line-output jack on the adapter. /// LineLevel, /// A set of headphones. Headphones, /// A microphone. Microphone, /// An earphone or a pair of earphones with an attached mouthpiece for two-way communication. Headset, /// The part of a telephone that is held in the hand and that contains a speaker and a microphone for two-way communication. Handset, /// /// An audio endpoint device that connects to an audio adapter through a connector for a digital interface of unknown type that /// transmits non-PCM data in digital pass-through mode. For more information, see Remarks. /// UnknownDigitalPassthrough, /// /// An audio endpoint device that connects to an audio adapter through a Sony/Philips Digital Interface (S/PDIF) connector. /// SPDIF, /// /// An audio endpoint device that connects to an audio adapter through a High-Definition Multimedia Interface (HDMI) connector /// or a display port.In Windows Vista, this value was named HDMI. /// DigitalAudioDisplayDevice, /// An audio endpoint device with unknown physical attributes. UnknownFormFactor, /// Windows 7: Maximum number of endpoint form factors. EndpointFormFactor_enum_count, } /// /// The ERole enumeration defines constants that indicate the role that the system has assigned to an audio endpoint device. /// /// /// /// The IMMDeviceEnumerator::GetDefaultAudioEndpoint and IMMNotificationClient::OnDefaultDeviceChanged methods use the constants /// defined in the ERole enumeration. /// /// For more information, see Device Roles. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/ne-mmdeviceapi-erole typedef enum // __MIDL___MIDL_itf_mmdeviceapi_0000_0000_0002 { eConsole, eMultimedia, eCommunications, ERole_enum_count } ERole; [PInvokeData("mmdeviceapi.h", MSDNShortId = "0d0d3174-8489-4951-858c-024d58477ae0")] public enum ERole { /// Games, system notification sounds, and voice commands. eConsole, /// Music, movies, narration, and live music recording. eMultimedia, /// Voice communications (talking to another person). eCommunications, /// The number of members in the ERole enumeration (not counting the ERole_enum_count member). ERole_enum_count, } /// /// Represents an asynchronous operation activating a WASAPI interface and provides a method to retrieve the results of the activation. /// /// When to implement: Implemented by Windows and returned from the function ActivateAudioInterfaceAsync. // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-iactivateaudiointerfaceasyncoperation [PInvokeData("mmdeviceapi.h", MSDNShortId = "43b25a67-d9a8-4749-a654-c7310039c553")] [ComImport, Guid("72A22D78-CDE4-431D-B8CC-843A71199B6D"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IActivateAudioInterfaceAsyncOperation { /// /// Gets the results of an asynchronous activation of a WASAPI interface initiated by an application calling the /// ActivateAudioInterfaceAsync function. /// /// /// /// /// The function returns an HRESULT. Possible values include, but are not limited to, those in the following table. /// /// /// Return code /// Description /// /// /// E_ILLEGAL_METHOD_CALL /// The method was called before the asynchronous operation was complete. /// /// /// /// /// /// An application calls this method after Windows calls the ActivateCompleted method of the application’s /// IActivateAudioInterfaceCompletionHandler interface. /// /// /// The result code returned through activateResult may depend on the requested interface. For additional information, see /// IMMDevice::Activate. A result code of E_ACCESSDENIED might indicate that the user has not given consent to access the /// device in a manner required by the requested WASAPI interface. /// /// The returned activatedInterface may be NULL if activateResult is not a success code. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-iactivateaudiointerfaceasyncoperation-getactivateresult // HRESULT GetActivateResult( HRESULT *activateResult, IUnknown **activatedInterface ); [PreserveSig] HRESULT GetActivateResult(out HRESULT activateResult, [MarshalAs(UnmanagedType.IUnknown)] out object activatedInterface); } /// Provides a callback to indicate that activation of a WASAPI interface is complete. /// /// When to implement: An application implements this interface if it calls the ActivateAudioInterfaceAsync function. /// The implementation must be agile (aggregating a free-threaded marshaler). /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-iactivateaudiointerfacecompletionhandler [PInvokeData("mmdeviceapi.h", MSDNShortId = "04ff7cbb-fd33-40d9-9c11-4f716c6423b0")] [ComImport, Guid("41D949AB-9862-444A-80F6-C261334DA5EB"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IActivateAudioInterfaceCompletionHandler { /// Indicates that activation of a WASAPI interface is complete and results are available. /// /// An interface representing the asynchronous operation of activating the requested WASAPI interface /// /// /// An application implements this method if it calls the ActivateAudioInterfaceAsync function. When Windows calls this method, /// the results of the activation are available. The application can then retrieve the results by calling the GetActivateResult /// method of the IActivateAudioInterfaceAsyncOperation interface, passed through the activateOperation parameter. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-iactivateaudiointerfacecompletionhandler-activatecompleted // HRESULT ActivateCompleted( IActivateAudioInterfaceAsyncOperation *activateOperation ); void ActivateCompleted(IActivateAudioInterfaceAsyncOperation activateOperation); } /// /// /// The IMMDevice interface encapsulates the generic features of a multimedia device resource. In the current implementation /// of the MMDevice API, the only type of device resource that an IMMDevice interface can represent is an audio endpoint device. /// /// A client can obtain an IMMDevice interface from one of the following methods: /// /// /// IMMDeviceCollection::Item /// /// /// IMMDeviceEnumerator::GetDefaultAudioEndpoint /// /// /// IMMDeviceEnumerator::GetDevice /// /// /// For more information, see IMMDeviceCollection Interface. /// /// After obtaining the IMMDevice interface of an audio endpoint device, a client can obtain an interface that encapsulates /// the endpoint-specific features of the device by calling the IMMDevice::QueryInterface method with parameter iid set to /// REFIID IID_IMMEndpoint. For more information, see IMMEndpoint Interface. /// /// For code examples that use the IMMDevice interface, see the following topics: /// /// /// Device Properties /// /// /// Rendering a Stream /// /// /// Device Roles for Legacy Windows Multimedia Applications /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immdevice [PInvokeData("mmdeviceapi.h", MSDNShortId = "12b05e7e-81b2-49fd-bb9f-d5ad3315c580")] [ComImport, Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IMMDevice { /// The Activate method creates a COM object with the specified interface. /// /// /// The interface identifier. This parameter is a reference to a GUID that identifies the interface that the caller requests be /// activated. The caller will use this interface to communicate with the COM object. Set this parameter to one of the following /// interface identifiers: /// /// 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 /// For more information, see Remarks. /// /// /// The execution context in which the code that manages the newly created object will run. The caller can restrict the context /// by setting this parameter to the bitwise OR of one or more CLSCTX enumeration values. Alternatively, the /// client can avoid imposing any context restrictions by specifying CLSCTX_ALL. For more information about CLSCTX, see /// the Windows SDK documentation. /// /// /// Set to NULL to activate an IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or /// IDeviceTopology interface on an audio endpoint device. When activating an IBaseFilter, IDirectSound, /// IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 interface on the device, the caller can /// specify a pointer to a PROPVARIANT structure that contains stream-initialization information. For more information, /// see Remarks. /// /// /// Pointer to a pointer variable into which the method writes the address of the interface specified by parameter iid. Through /// this method, the caller obtains a counted reference to the interface. The caller is responsible for releasing the interface, /// when it is no longer needed, by calling the interface's Release method. If the Activate call fails, /// *ppInterface is NULL. /// /// /// /// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values /// shown in the following table. /// /// /// /// Return code /// Description /// /// /// E_NOINTERFACE /// The object does not support the requested interface type. /// /// /// E_POINTER /// Parameter ppInterface is NULL. /// /// /// E_INVALIDARG /// The pActivationParams parameter must be NULL for the specified interface; or pActivationParams points to invalid data. /// /// /// E_OUTOFMEMORY /// Out of memory. /// /// /// AUDCLNT_E_DEVICE_INVALIDATED /// The user has removed either the audio endpoint device or the adapter device that the endpoint device connects to. /// /// /// /// /// /// This method creates a COM object with an interface that is specified by the iid parameter. The method is similar to the /// Windows CoCreateInstance function, except that the caller does not supply a CLSID as a parameter. For more /// information about CoCreateInstance, see the Windows SDK documentation. /// /// /// A client can call the Activate method of the IMMDevice interface for a particular audio endpoint device to /// obtain a counted reference to an interface on that device. The method can activate the following interfaces: /// /// /// /// IAudioClient /// /// /// IAudioEndpointVolume /// /// /// IAudioMeterInformation /// /// /// IAudioSessionManager /// /// /// IAudioSessionManager2 /// /// /// IBaseFilter /// /// /// IDeviceTopology /// /// /// IDirectSound /// /// /// IDirectSound8 /// /// /// IDirectSoundCapture /// /// /// IDirectSoundCapture8 /// /// /// IMFTrustedOutput /// /// /// /// To obtain the interface ID for an interface, use the __uuidof operator. For example, the interface ID of /// IAudioCaptureClient is defined as follows: /// /// /// For information about the __uuidof operator, see the Windows SDK documentation. For information about /// IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8, and /// IMFTrustedOutput see the Windows SDK documentation. /// /// /// The pActivationParams parameter should be NULL for an Activate call to create an IAudioClient, /// IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or IDeviceTopology interface /// for an audio endpoint device. /// /// /// For an Activate call to create an IBaseFilter, IDirectSound, IDirectSound8, /// IDirectSoundCapture, or IDirectSoundCapture8 interface, the caller can, as an option, specify a non- /// NULL value for pActivationParams. In this case, pActivationParams points to a PROPVARIANT structure that /// contains stream-initialization information. Set the vt member of the structure to VT_BLOB. Set the /// blob.pBlobData member to point to a DIRECTX_AUDIO_ACTIVATION_PARAMS structure that contains an audio session GUID and /// stream-initialization flags. Set the blob.cbSize member to sizeof( DIRECTX_AUDIO_ACTIVATION_PARAMS). /// For a code example, see Device Roles for DirectShow Applications. For more information about PROPVARIANT, see the /// Windows SDK documentation. /// /// /// An IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 /// interface instance that is created by the Activate method encapsulates a stream on the audio endpoint device. During /// the Activate call, the DirectSound system module creates the stream by calling the IAudioClient::Initialize method. /// If pActivationParams is non- NULL, DirectSound supplies the audio session GUID and stream-initialization flags from /// the DIRECTX_AUDIO_ACTIVATION_PARAMS structure as input parameters to the Initialize call. If pActivationParams /// is NULL, DirectSound sets the Initialize method's AudioSessionGuid and StreamFlags parameters to their /// respective default values, NULL and 0. These values instruct the method to assign the stream to the process-specific /// session that is identified by the session GUID value GUID_NULL. /// /// /// Activate can activate an IDirectSound or IDirectSound8 interface only on a rendering endpoint device. /// It can activate an IDirectSoundCapture or IDirectSoundCapture8 interface only on a capture endpoint device. An /// Activate call to activate an IDirectSound or IDirectSoundCapture8 interface on a capture device or an /// IDirectSoundCapture or IDirectSoundCapture8 interface on a rendering device fails and returns error code E_NOINTERFACE. /// /// /// In Windows 7, a client can call IMMDevice::Activate and specify, IID_IMFTrustedOutput, to create an output /// trust authorities (OTA) object and retrieve a pointer to the object's IMFTrustedOutput interface. OTAs can operate inside or /// outside the Media Foundation's protected media path (PMP) and send content outside the Media Foundation pipeline. If the /// caller is outside PMP, then the OTA may not operate in the PMP, and the protection settings are less robust. For information /// about using protected objects for audio and example code, see Protected User Mode Audio (PUMA). /// /// /// For general information about protected objects and IMFTrustedOutput, see "Protected Media Path" in Media Foundation documentation. /// /// /// Note When using the ISpatialAudioClient interfaces on an Xbox One Development Kit (XDK) title, you must first call /// EnableSpatialAudio before calling IMMDeviceEnumerator::EnumAudioEndpoints or /// IMMDeviceEnumerator::GetDefaultAudioEndpoint. Failure to do so will result in an E_NOINTERFACE error being returned from the /// call to Activate. EnableSpatialAudio is only available for XDK titles, and does not need to be called for Universal /// Windows Platform apps running on Xbox One, nor for any non-Xbox One devices. /// /// For code examples that call the Activate method, see the following topics: /// /// /// Rendering a Stream /// /// /// Device Topologies /// /// /// Using the IKsControl Interface to Access Audio Properties /// /// /// Audio Events for Legacy Audio Applications /// /// /// Render Spatial Sound Using Spatial Audio Objects /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-activate HRESULT Activate( REFIID // iid, DWORD dwClsCtx, PROPVARIANT *pActivationParams, void **ppInterface ); [PreserveSig] HRESULT Activate([In] in Guid iid, [In] CLSCTX dwClsCtx, [In, Optional] PROPVARIANT pActivationParams, [MarshalAs(UnmanagedType.IUnknown)] out object ppInterface); /// The OpenPropertyStore method retrieves an interface to the device's property store. /// /// /// The storage-access mode. This parameter specifies whether to open the property store in read mode, write mode, or read/write /// mode. Set this parameter to one of the following STGM constants: /// /// STGM_READ /// STGM_WRITE /// STGM_READWRITE /// /// The method permits a client running as an administrator to open a store for read-only, write-only, or read/write access. A /// client that is not running as an administrator is restricted to read-only access. For more information about STGM constants, /// see the Windows SDK documentation. /// /// /// /// Pointer to a pointer variable into which the method writes the address of the IPropertyStore interface of the /// device's property store. Through this method, the caller obtains a counted reference to the interface. The caller is /// responsible for releasing the interface, when it is no longer needed, by calling the interface's Release method. If /// the OpenPropertyStore call fails, *ppProperties is NULL. For more information about IPropertyStore, see /// the Windows SDK documentation. /// /// /// /// In general, the properties in the device's property store are read-only for clients that do not perform administrative, /// system, or service functions. /// /// For code examples that call the OpenPropertyStore method, see the following topics: /// /// /// Device Properties /// /// /// Device Roles for DirectSound Applications /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-openpropertystore HRESULT // OpenPropertyStore( DWORD stgmAccess, IPropertyStore **ppProperties ); IPropertyStore OpenPropertyStore(STGM stgmAccess); /// The GetId method retrieves an endpoint ID string that identifies the audio endpoint device. /// /// Pointer to a pointer variable into which the method writes the address of a null-terminated, wide-character string /// containing the endpoint device ID. The method allocates the storage for the string. The caller is responsible for freeing /// the storage, when it is no longer needed, by calling the CoTaskMemFree function. If the GetId call fails, /// *ppstrId is NULL. For information about CoTaskMemFree, see the Windows SDK documentation. /// /// /// /// The endpoint ID string obtained from this method identifies the audio endpoint device that is represented by the /// IMMDevice interface instance. A client can use the endpoint ID string to create an instance of the audio endpoint /// device at a later time or in a different process by calling the IMMDeviceEnumerator::GetDevice method. Clients should treat /// the contents of the endpoint ID string as opaque. That is, clients should not attempt to parse the contents of the string to /// obtain information about the device. The reason is that the string format is undefined and might change from one /// implementation of the MMDevice API system module to the next. /// /// For code examples that call the GetId method, see the following topics: /// /// /// Device Properties /// /// /// Device Roles for Legacy Windows Multimedia Applications /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-getid HRESULT GetId( LPWSTR *ppstrId ); SafeCoTaskMemString GetId(); /// The GetState method retrieves the current device state. /// /// /// Pointer to a DWORD variable into which the method writes the current state of the device. The device-state value is /// one of the following DEVICE_STATE_XXX constants: /// /// DEVICE_STATE_ACTIVE /// DEVICE_STATE_DISABLED /// DEVICE_STATE_NOTPRESENT /// DEVICE_STATE_UNPLUGGED /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevice-getstate HRESULT GetState( DWORD // *pdwState ); DEVICE_STATE GetState(); } /// The Activate method creates a COM object with the specified interface. /// /// Can be one of the following interfaces: /// /// /// IAudioClient /// /// /// IAudioEndpointVolume /// /// /// IAudioMeterInformation /// /// /// IAudioSessionManager /// /// /// IAudioSessionManager2 /// /// /// IBaseFilter /// /// /// IDeviceTopology /// /// /// IDirectSound /// /// /// IDirectSound8 /// /// /// IDirectSoundCapture /// /// /// IDirectSoundCapture8 /// /// /// IMFTrustedOutput /// /// /// /// The instance. /// /// The execution context in which the code that manages the newly created object will run. The caller can restrict the context by /// setting this parameter to the bitwise OR of one or more CLSCTX enumeration values. Alternatively, the client can /// avoid imposing any context restrictions by specifying CLSCTX_ALL. For more information about CLSCTX, see the Windows SDK documentation. /// /// /// Set to NULL to activate an IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or /// IDeviceTopology interface on an audio endpoint device. When activating an IBaseFilter, IDirectSound, /// IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 interface on the device, the caller can specify /// a pointer to a PROPVARIANT structure that contains stream-initialization information. For more information, see Remarks. /// /// /// The interface specified by . Through this method, the caller obtains a counted reference to the /// interface. The caller is responsible for releasing the interface, when it is no longer needed, by calling the interface's /// Release method. If the Activate call fails, this value is NULL. /// /// /// /// This method creates a COM object with an interface that is specified by the iid parameter. The method is similar to the Windows /// CoCreateInstance function, except that the caller does not supply a CLSID as a parameter. For more information about /// CoCreateInstance, see the Windows SDK documentation. /// /// /// A client can call the Activate method of the IMMDevice interface for a particular audio endpoint device to obtain /// a counted reference to an interface on that device. The method can activate the following interfaces: /// /// /// To obtain the interface ID for an interface, use the __uuidof operator. For example, the interface ID of /// IAudioCaptureClient is defined as follows: /// /// /// For information about the __uuidof operator, see the Windows SDK documentation. For information about IBaseFilter, /// IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8, and IMFTrustedOutput /// see the Windows SDK documentation. /// /// /// The pActivationParams parameter should be NULL for an Activate call to create an IAudioClient, /// IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or IDeviceTopology interface for /// an audio endpoint device. /// /// /// For an Activate call to create an IBaseFilter, IDirectSound, IDirectSound8, /// IDirectSoundCapture, or IDirectSoundCapture8 interface, the caller can, as an option, specify a non- NULL /// value for pActivationParams. In this case, pActivationParams points to a PROPVARIANT structure that contains /// stream-initialization information. Set the vt member of the structure to VT_BLOB. Set the blob.pBlobData member to /// point to a DIRECTX_AUDIO_ACTIVATION_PARAMS structure that contains an audio session GUID and stream-initialization flags. Set /// the blob.cbSize member to sizeof( DIRECTX_AUDIO_ACTIVATION_PARAMS). For a code example, see Device Roles /// for DirectShow Applications. For more information about PROPVARIANT, see the Windows SDK documentation. /// /// /// An IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 /// interface instance that is created by the Activate method encapsulates a stream on the audio endpoint device. During the /// Activate call, the DirectSound system module creates the stream by calling the IAudioClient::Initialize method. If /// pActivationParams is non- NULL, DirectSound supplies the audio session GUID and stream-initialization flags from the /// DIRECTX_AUDIO_ACTIVATION_PARAMS structure as input parameters to the Initialize call. If pActivationParams is /// NULL, DirectSound sets the Initialize method's AudioSessionGuid and StreamFlags parameters to their respective /// default values, NULL and 0. These values instruct the method to assign the stream to the process-specific session that is /// identified by the session GUID value GUID_NULL. /// /// /// Activate can activate an IDirectSound or IDirectSound8 interface only on a rendering endpoint device. It /// can activate an IDirectSoundCapture or IDirectSoundCapture8 interface only on a capture endpoint device. An /// Activate call to activate an IDirectSound or IDirectSoundCapture8 interface on a capture device or an /// IDirectSoundCapture or IDirectSoundCapture8 interface on a rendering device fails and returns error code E_NOINTERFACE. /// /// /// In Windows 7, a client can call IMMDevice::Activate and specify, IID_IMFTrustedOutput, to create an output trust /// authorities (OTA) object and retrieve a pointer to the object's IMFTrustedOutput interface. OTAs can operate inside or outside /// the Media Foundation's protected media path (PMP) and send content outside the Media Foundation pipeline. If the caller is /// outside PMP, then the OTA may not operate in the PMP, and the protection settings are less robust. For information about using /// protected objects for audio and example code, see Protected User Mode Audio (PUMA). /// /// For general information about protected objects and IMFTrustedOutput, see "Protected Media Path" in Media Foundation documentation. /// /// Note When using the ISpatialAudioClient interfaces on an Xbox One Development Kit (XDK) title, you must first call /// EnableSpatialAudio before calling IMMDeviceEnumerator::EnumAudioEndpoints or /// IMMDeviceEnumerator::GetDefaultAudioEndpoint. Failure to do so will result in an E_NOINTERFACE error being returned from the /// call to Activate. EnableSpatialAudio is only available for XDK titles, and does not need to be called for Universal /// Windows Platform apps running on Xbox One, nor for any non-Xbox One devices. /// /// For code examples that call the Activate method, see the following topics: /// /// /// Rendering a Stream /// /// /// Device Topologies /// /// /// Using the IKsControl Interface to Access Audio Properties /// /// /// Audio Events for Legacy Audio Applications /// /// /// Render Spatial Sound Using Spatial Audio Objects /// /// /// public static T Activate(this IMMDevice device, [In] CLSCTX dwClsCtx = CLSCTX.CLSCTX_ALL, [In] PROPVARIANT pActivationParams = null) where T : class { device.Activate(typeof(T).GUID, dwClsCtx, pActivationParams, out var intf).ThrowIfFailed(); return intf as T; } /// /// /// The IMMDeviceCollection interface represents a collection of multimedia device resources. In the current implementation, /// the only device resources that the MMDevice API can create collections of are audio endpoint devices. /// /// /// A client can obtain a reference to an IMMDeviceCollection interface instance by calling the /// IMMDeviceEnumerator::EnumAudioEndpoints method. This method creates a collection of endpoint objects, each of which represents /// an audio endpoint device in the system. Each endpoint object in the collection supports the IMMDevice and IMMEndpoint /// interfaces. For more information, see IMMDeviceEnumerator Interface. /// /// For a code example that uses the IMMDeviceCollection interface, see Device Properties. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immdevicecollection [PInvokeData("mmdeviceapi.h", MSDNShortId = "4769b0a6-a319-4605-8742-5e7c285679cf")] [ComImport, Guid("0BD7A1BE-7A1A-44DB-8397-CC5392387B5E"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IMMDeviceCollection { /// The GetCount method retrieves a count of the devices in the device collection. /// Pointer to a UINT variable into which the method writes the number of devices in the device collection. /// For a code example that calls the GetCount method, see Device Properties. // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevicecollection-getcount HRESULT GetCount( // UINT *pcDevices ); uint GetCount(); /// The Item method retrieves a pointer to the specified item in the device collection. /// The device number. If the collection contains n devices, the devices are numbered 0 to n– 1. /// /// Pointer to a pointer variable into which the method writes the address of the IMMDevice interface of the specified item in /// the device collection. Through this method, the caller obtains a counted reference to the interface. The caller is /// responsible for releasing the interface, when it is no longer needed, by calling the interface's Release method. If /// the Item call fails, *ppDevice is NULL. /// /// /// /// If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values /// shown in the following table. /// /// /// /// Return code /// Description /// /// /// E_POINTER /// Parameter ppDevice is NULL. /// /// /// E_INVALIDARG /// Parameter nDevice is not a valid device number. /// /// /// /// /// /// This method retrieves a pointer to the IMMDevice interface of the specified item in the device collection. Each item /// in the collection is an endpoint object that represents an audio endpoint device. The caller selects a device from the /// device collection by specifying the device number. For a collection of n devices, valid device numbers range from 0 to n– 1. /// To obtain a count of the devices in a collection, call the IMMDeviceCollection::GetCount method. /// /// For a code example that calls the Item method, see Device Properties. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdevicecollection-item HRESULT Item( UINT // nDevice, IMMDevice **ppDevice ); [PreserveSig] HRESULT Item([In] uint nDevice, out IMMDevice ppDevice); } /// /// /// The IMMDeviceEnumerator interface provides methods for enumerating multimedia device resources. In the current /// implementation of the MMDevice API, the only device resources that this interface can enumerate are audio endpoint devices. A /// client obtains a reference to an IMMDeviceEnumerator interface by calling the CoCreateInstance function, as /// described previously (see MMDevice API). /// /// /// The device resources enumerated by the methods in the IMMDeviceEnumerator interface are represented as collections of /// objects with IMMDevice interfaces. A collection has an IMMDeviceCollection interface. The /// IMMDeviceEnumerator::EnumAudioEndpoints method creates a device collection. /// /// /// To obtain a pointer to the IMMDevice interface of an item in a device collection, the client calls the /// IMMDeviceCollection::Item method. /// /// For code examples that use the IMMDeviceEnumerator interface, see the following topics: /// /// /// Device Properties /// /// /// Rendering a Stream /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immdeviceenumerator [PInvokeData("mmdeviceapi.h", MSDNShortId = "1abdeac1-c156-40b8-8b8c-5ddb51e410aa")] [ComImport, Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(MMDeviceEnumerator))] public interface IMMDeviceEnumerator { /// /// The EnumAudioEndpoints method generates a collection of audio endpoint devices that meet the specified criteria. /// /// /// /// The data-flow direction for the endpoint devices in the collection. The caller should set this parameter to one of the /// following EDataFlow enumeration values: /// /// eRender /// eCapture /// eAll /// If the caller specifies eAll, the method includes both rendering and capture endpoints in the collection. /// /// /// /// The state or states of the endpoints that are to be included in the collection. The caller should set this parameter to the /// bitwise OR of one or more of the following DEVICE_STATE_XXX constants: /// /// DEVICE_STATE_ACTIVE /// DEVICE_STATE_DISABLED /// DEVICE_STATE_NOTPRESENT /// DEVICE_STATE_UNPLUGGED /// /// For example, if the caller sets the dwStateMask parameter to DEVICE_STATE_ACTIVE | DEVICE_STATE_UNPLUGGED, the method /// includes endpoints that are either active or unplugged from their jacks, but excludes endpoints that are on audio adapters /// that have been disabled or are not present. To include all endpoints, regardless of state, set dwStateMask = DEVICE_STATEMASK_ALL. /// /// /// /// Pointer to a pointer variable into which the method writes the address of the IMMDeviceCollection interface of the /// device-collection object. Through this method, the caller obtains a counted reference to the interface. The caller is /// responsible for releasing the interface, when it is no longer needed, by calling the interface's Release method. If /// the EnumAudioEndpoints call fails, *ppDevices is NULL. /// /// /// /// For example, the following call enumerates all audio-rendering endpoint devices that are currently active (present and not disabled): /// /// /// In the preceding code fragment, variable hr is of type HRESULT, pDevEnum is a pointer to an /// IMMDeviceEnumerator interface, and pEndpoints is a pointer to an IMMDeviceCollection interface. /// /// Examples /// For a code example that calls the EnumAudioEndpoints method, see Device Properties. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-enumaudioendpoints HRESULT // EnumAudioEndpoints( EDataFlow dataFlow, DWORD dwStateMask, IMMDeviceCollection **ppDevices ); IMMDeviceCollection EnumAudioEndpoints([In] EDataFlow dataFlow, [In] DEVICE_STATE dwStateMask); /// /// The GetDefaultAudioEndpoint method retrieves the default audio endpoint for the specified data-flow direction and role. /// /// /// /// The data-flow direction for the endpoint device. The caller should set this parameter to one of the following two EDataFlow /// enumeration values: /// /// eRender /// eCapture /// The data-flow direction for a rendering device is eRender. The data-flow direction for a capture device is eCapture. /// /// /// The role of the endpoint device. The caller should set this parameter to one of the following ERole enumeration values: /// eConsole /// eMultimedia /// eCommunications /// For more information, see Remarks. /// /// /// Pointer to a pointer variable into which the method writes the address of the IMMDevice interface of the endpoint object for /// the default audio endpoint device. Through this method, the caller obtains a counted reference to the interface. The caller /// is responsible for releasing the interface, when it is no longer needed, by calling the interface's Release method. /// If the GetDefaultAudioEndpoint call fails, *ppDevice is NULL. /// /// /// Note /// /// In Windows Vista, the MMDevice API supports device roles but the system-supplied user interface programs do not. The user /// interface in Windows Vista enables the user to select a default audio device for rendering and a default audio device for /// capture. When the user changes the default rendering or capture device, the system assigns all three device roles (eConsole, /// eMultimedia, and eCommunications) to that device. Thus, GetDefaultAudioEndpoint always selects the default rendering /// or capture device, regardless of which role is indicated by the role parameter. In a future version of Windows, the user /// interface might enable the user to assign individual roles to different devices. In that case, the selection of a rendering /// or capture device by GetDefaultAudioEndpoint might depend on the role parameter. Thus, the behavior of an audio /// application developed to run in Windows Vista might change when run in a future version of Windows. For more information, /// see Device Roles in Windows Vista. /// /// /// This method retrieves the default endpoint device for the specified data-flow direction (rendering or capture) and role. For /// example, a client can get the default console playback device by making the following call: /// /// /// In the preceding code fragment, variable hr is of type HRESULT, pDevEnum is a pointer to an /// IMMDeviceEnumerator interface, and pDeviceOut is a pointer to an IMMDevice interface. /// /// /// A Windows system might contain some combination of audio endpoint devices such as desktop speakers, high-fidelity /// headphones, desktop microphones, headsets with speaker and microphones, and high-fidelity multichannel speakers. The user /// can assign appropriate roles to the devices. For example, an application that manages voice communications streams can call /// GetDefaultAudioEndpoint to identify the designated rendering and capture devices for that role. /// /// /// If only a single rendering or capture device is available, the system always assigns all three rendering or capture roles to /// that device. If the method fails to find a rendering or capture device for the specified role, this means that no rendering /// or capture device is available at all. If no device is available, the method sets *ppEndpoint = NULL and returns ERROR_NOT_FOUND. /// /// For code examples that call the GetDefaultAudioEndpoint method, see the following topics: /// /// /// Rendering a Stream /// /// /// Audio Events for Legacy Audio Applications /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-getdefaultaudioendpoint // HRESULT GetDefaultAudioEndpoint( EDataFlow dataFlow, ERole role, IMMDevice **ppEndpoint ); IMMDevice GetDefaultAudioEndpoint([In] EDataFlow dataFlow, [In] ERole role); /// The GetDevice method retrieves an audio endpoint device that is identified by an endpoint ID string. /// /// Pointer to a string containing the endpoint ID. The caller typically obtains this string from the IMMDevice::GetId method or /// from one of the methods in the IMMNotificationClient interface. /// /// /// Pointer to a pointer variable into which the method writes the address of the IMMDevice interface for the specified device. /// Through this method, the caller obtains a counted reference to the interface. The caller is responsible for releasing the /// interface, when it is no longer needed, by calling the interface's Release method. If the GetDevice call /// fails, *ppDevice is NULL. /// /// /// /// If two programs are running in two different processes and both need to access the same audio endpoint device, one program /// cannot simply pass the device's IMMDevice interface to the other program. However, the programs can access the same /// device by following these steps: /// /// /// /// /// The first program calls the IMMDevice::GetId method in the first process to obtain the endpoint ID string that /// identifies the device. /// /// /// /// The first program passes the endpoint ID string across the process boundary to the second program. /// /// /// /// To obtain a reference to the device's IMMDevice interface in the second process, the second program calls /// GetDevice with the endpoint ID string. /// /// /// /// For more information about the GetDevice method, see the following topics: /// /// /// Endpoint ID Strings /// /// /// Audio Events for Legacy Audio Applications /// /// /// For code examples that use the GetDevice method, see the following topics: /// /// /// Device Properties /// /// /// Device Events /// /// /// Using the IKsControl Interface to Access Audio Properties /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-getdevice HRESULT // GetDevice( LPCWSTR pwstrId, IMMDevice **ppDevice ); IMMDevice GetDevice([In, MarshalAs(UnmanagedType.LPWStr)] string pwstrId); /// The RegisterEndpointNotificationCallback method registers a client's notification callback interface. /// Pointer to the IMMNotificationClient interface that the client is registering for notification callbacks. /// /// /// This method registers an IMMNotificationClient interface to be called by the system when the roles, state, existence, or /// properties of an endpoint device change. The caller implements the IMMNotificationClient interface. /// /// /// When notifications are no longer needed, the client can call the IMMDeviceEnumerator::UnregisterEndpointNotificationCallback /// method to terminate the notifications. /// /// /// The client must ensure that the IMMNotificationClient object is not released after the /// RegisterEndpointNotificationCallback call and before calling UnregisterEndpointNotificationCallback. These methods do /// not call the client's IMMNotificationClient::AddRef and IMMNotificationClient::Release implementations. The /// client is responsible for maintaining the reference count of the IMMNotificationClient object. The client must /// increment the count if the RegisterEndpointNotificationCallback call succeeds and release the final reference only /// after calling UnregisterEndpointNotificationCallback or implement some other mechanism to ensure that the object is /// not deleted before UnregisterEndpointNotificationCallback is called. Otherwise, the application leaks the resources /// held by the IMMNotificationClient and any other object that is implemented in the same container. /// /// /// For more information about the AddRef and Release methods, see the discussion of the IUnknown interface /// in the Windows SDK documentation. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-registerendpointnotificationcallback // HRESULT RegisterEndpointNotificationCallback( IMMNotificationClient *pClient ); void RegisterEndpointNotificationCallback([In] IMMNotificationClient pClient); /// /// The UnregisterEndpointNotificationCallback method deletes the registration of a notification interface that the /// client registered in a previous call to the IMMDeviceEnumerator::RegisterEndpointNotificationCallback method. /// /// /// Pointer to the client's IMMNotificationClient interface. The client passed this same interface pointer to the device /// enumerator in a previous call to the IMMDeviceEnumerator::RegisterEndpointNotificationCallback method. For more information, /// see Remarks. /// /// /// /// The client must ensure that the IMMNotificationClient object is not released after the RegisterEndpointNotificationCallback /// call and before calling UnregisterEndpointNotificationCallback. These methods do not call the client's /// IMMNotificationClient::AddRef and IMMNotificationClient::Release implementations. The client is responsible /// for maintaining the reference count of the IMMNotificationClient object. The client must increment the count if the /// RegisterEndpointNotificationCallback call succeeds and release the final reference only after calling /// UnregisterEndpointNotificationCallback or implement some other mechanism to ensure that the object is not deleted /// before UnregisterEndpointNotificationCallback is called. Otherwise, the application leaks the resources held by the /// IMMNotificationClient and any other object that is implemented in the same container. /// /// /// For more information about the AddRef and Release methods, see the discussion of the IUnknown interface /// in the Windows SDK documentation. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immdeviceenumerator-unregisterendpointnotificationcallback // HRESULT UnregisterEndpointNotificationCallback( IMMNotificationClient *pClient ); void UnregisterEndpointNotificationCallback([In] IMMNotificationClient pClient); } /// /// /// The IMMEndpoint interface represents an audio endpoint device. A client obtains a reference to an IMMEndpoint /// interface instance by following these steps: /// /// /// /// /// By using one of the techniques described in IMMDevice Interface, obtain a reference to the IMMDevice interface of an /// audio endpoint device. /// /// /// /// Call the IMMDevice::QueryInterface method with parameter iid set to REFIID IID_IMMEndpoint. /// /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immendpoint [PInvokeData("mmdeviceapi.h", MSDNShortId = "293de8eb-204a-4c18-807c-b1405db85b12")] [ComImport, Guid("1BE09788-6894-4089-8586-9A2A6C265AC5"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] public interface IMMEndpoint { /// /// The GetDataFlow method indicates whether the audio endpoint device is a rendering device or a capture device. /// /// /// /// Pointer to a variable into which the method writes the data-flow direction of the endpoint device. The direction is /// indicated by one of the following EDataFlow enumeration constants: /// /// eRender /// eCapture /// The data-flow direction for a rendering device is eRender. The data-flow direction for a capture device is eCapture. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immendpoint-getdataflow HRESULT GetDataFlow( // EDataFlow *pDataFlow ); EDataFlow GetDataFlow(); } /// /// /// The IMMNotificationClient interface provides notifications when an audio endpoint device is added or removed, when the /// state or properties of an endpoint device change, or when there is a change in the default role assigned to an endpoint device. /// Unlike the other interfaces in this section, which are implemented by the MMDevice API system component, an MMDevice API client /// implements the IMMNotificationClient interface. To receive notifications, the client passes a pointer to its /// IMMNotificationClient interface instance as a parameter to the IMMDeviceEnumerator::RegisterEndpointNotificationCallback method. /// /// /// After registering its IMMNotificationClient interface, the client receives event notifications in the form of callbacks /// through the methods of the interface. /// /// /// Each method in the IMMNotificationClient interface receives, as one of its input parameters, an endpoint ID string that /// identifies the audio endpoint device that is the subject of the notification. The string uniquely identifies the device with /// respect to all of the other audio endpoint devices in the system. The methods in the IMMNotificationClient interface /// implementation should treat this string as opaque. That is, none of the methods should attempt to parse the contents of the /// string to obtain information about the device. The reason is that the string format is undefined and might change from one /// implementation of the MMDevice API system module to the next. /// /// /// A client can use the endpoint ID string that it receives as an input parameter in a call to an IMMNotificationClient /// method in two ways: /// /// /// /// /// The client can create an instance of the device that the endpoint ID string identifies. The client does this by calling the /// IMMDeviceEnumerator::GetDevice method and supplying the endpoint ID string as an input parameter. /// /// /// /// /// The client can compare the endpoint ID string with the endpoint ID string of an existing device instance. To obtain the second /// endpoint ID string, the client calls the IMMDevice::GetId method of the device instance. If the two strings match, they identify /// the same device. /// /// /// /// /// In implementing the IMMNotificationClient interface, the client should observe these rules to avoid deadlocks and /// undefined behavior: /// /// /// /// /// The methods of the interface must be nonblocking. The client should never wait on a synchronization object during an event callback. /// /// /// /// /// To avoid dead locks, the client should never call IMMDeviceEnumerator::RegisterEndpointNotificationCallback or /// IMMDeviceEnumerator::UnregisterEndpointNotificationCallback in its implementation of IMMNotificationClient methods. /// /// /// /// The client should never release the final reference on an MMDevice API object during an event callback. /// /// /// For a code example that implements the IMMNotificationClient interface, see Device Events. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immnotificationclient [ComImport, Guid("7991EEC9-7E89-4D85-8390-6C703CEC60C0"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] [PInvokeData("mmdeviceapi.h")] public interface IMMNotificationClient { /// The OnDeviceStateChanged method indicates that the state of an audio endpoint device has changed. /// /// Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, /// wide-character string containing the endpoint ID. The string remains valid for the duration of the call. /// /// /// /// Specifies the new state of the endpoint device. The value of this parameter is one of the following DEVICE_STATE_XXX constants: /// /// DEVICE_STATE_ACTIVE /// DEVICE_STATE_DISABLED /// DEVICE_STATE_NOTPRESENT /// DEVICE_STATE_UNPLUGGED /// /// If the method succeeds, it returns S_OK. If it fails, it returns an error code. /// For a code example that implements the OnDeviceStateChanged method, see Device Events. // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immnotificationclient-ondevicestatechanged // HRESULT OnDeviceStateChanged( LPCWSTR pwstrDeviceId, DWORD dwNewState ); [PreserveSig] HRESULT OnDeviceStateChanged([In, MarshalAs(UnmanagedType.LPWStr)] string pwstrDeviceId, [In] DEVICE_STATE dwNewState); /// The OnDeviceAdded method indicates that a new audio endpoint device has been added. /// /// Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, /// wide-character string containing the endpoint ID. The string remains valid for the duration of the call. /// /// If the method succeeds, it returns S_OK. If it fails, it returns an error code. /// For a code example that implements the OnDeviceAdded method, see Device Events. // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immnotificationclient-ondeviceadded HRESULT // OnDeviceAdded( LPCWSTR pwstrDeviceId ); [PreserveSig] HRESULT OnDeviceAdded([In, MarshalAs(UnmanagedType.LPWStr)] string pwstrDeviceId); /// The OnDeviceRemoved method indicates that an audio endpoint device has been removed. /// /// Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, /// wide-character string containing the endpoint ID. The string remains valid for the duration of the call. /// /// If the method succeeds, it returns S_OK. If it fails, it returns an error code. /// For a code example that implements the OnDeviceRemoved method, see Device Events. // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immnotificationclient-ondeviceremoved HRESULT // OnDeviceRemoved( LPCWSTR pwstrDeviceId ); [PreserveSig] HRESULT OnDeviceRemoved([In, MarshalAs(UnmanagedType.LPWStr)] string pwstrDeviceId); /// /// The OnDefaultDeviceChanged method notifies the client that the default audio endpoint device for a particular device /// role has changed. /// /// /// /// The data-flow direction of the endpoint device. This parameter is set to one of the following EDataFlow enumeration values: /// /// eRender /// eCapture /// The data-flow direction for a rendering device is eRender. The data-flow direction for a capture device is eCapture. /// /// /// The device role of the audio endpoint device. This parameter is set to one of the following ERole enumeration values: /// eConsole /// eMultimedia /// eCommunications /// /// /// Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, /// wide-character string containing the endpoint ID. The string remains valid for the duration of the call. If the user has /// removed or disabled the default device for a particular role, and no other device is available to assume that role, then /// pwstrDefaultDevice is NULL. /// /// If the method succeeds, it returns S_OK. If it fails, it returns an error code. /// /// /// The three input parameters specify the data-flow direction, device role, and endpoint ID string of the new default audio /// endpoint device. /// /// /// In Windows Vista, the MMDevice API supports device roles but the system-supplied user interface programs do not. The user /// interface in Windows Vista enables the user to select a default audio device for rendering and a default audio device for /// capture. When the user changes the default rendering or capture device, the system assigns all three device roles (eConsole, /// eMultimedia, and eCommunications) to the new device. Thus, when the user changes the default rendering or capture device, /// the system calls the client's OnDefaultDeviceChanged method three times—once for each of the three device roles. /// /// /// In a future version of Windows, the user interface might enable the user to assign individual roles to different devices. In /// that case, if the user changes the assignment of only one or two device roles to a new rendering or capture device, the /// system will call the client's OnDefaultDeviceChanged method only once or twice (that is, one call per changed role). /// Depending on how the OnDefaultDeviceChanged method responds to role changes, the behavior of an audio application /// developed to run in Windows Vista might change when run in a future version of Windows. For more information, see Device /// Roles in Windows Vista. /// /// For a code example that implements the OnDefaultDeviceChanged method, see Device Events. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immnotificationclient-ondefaultdevicechanged // HRESULT OnDefaultDeviceChanged( EDataFlow flow, ERole role, LPCWSTR pwstrDefaultDeviceId ); [PreserveSig] HRESULT OnDefaultDeviceChanged([In] EDataFlow flow, [In] ERole role, [In, MarshalAs(UnmanagedType.LPWStr)] string pwstrDefaultDeviceId); /// /// The OnPropertyValueChanged method indicates that the value of a property belonging to an audio endpoint device has changed. /// /// /// Pointer to the endpoint ID string that identifies the audio endpoint device. This parameter points to a null-terminated, /// wide-character string that contains the endpoint ID. The string remains valid for the duration of the call. /// /// /// A PROPERTYKEY structure that specifies the property. The structure contains the property-set GUID and an index identifying a /// property within the set. The structure is passed by value. It remains valid for the duration of the call. For more /// information about PROPERTYKEY, see the Windows SDK documentation. /// /// If the method succeeds, it returns S_OK. If it fails, it returns an error code. /// /// /// A call to the IPropertyStore::SetValue method that successfully changes the value of a property of an audio endpoint device /// generates a call to OnPropertyValueChanged. For more information about IPropertyStore::SetValue, see the /// Windows SDK documentation. /// /// /// A client can use the key parameter to retrieve the new property value. For a code example that uses a property key to /// retrieve a property value from the property store of an endpoint device, see Device Properties. /// /// For a code example that implements the OnPropertyValueChanged method, see Device Events. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-immnotificationclient-onpropertyvaluechanged // HRESULT OnPropertyValueChanged( LPCWSTR pwstrDeviceId, const PROPERTYKEY key ); [PreserveSig] HRESULT OnPropertyValueChanged([In, MarshalAs(UnmanagedType.LPWStr)] string pwstrDeviceId, [In] PROPERTYKEY key); } /// Enables Windows Store apps to access preexisting Component Object Model (COM) interfaces in the WASAPI family. /// /// /// A device interface ID for an audio device. This is normally retrieved from a DeviceInformation object or one of the methods of /// the MediaDevice class. /// /// /// The GUIDs DEVINTERFACE_AUDIO_CAPTURE and DEVINTERFACE_AUDIO_RENDER represent the default audio capture and render device /// respectively. Call StringFromIID to convert either of these GUIDs to an LPCWSTR to use for this argument. /// /// /// The IID of a COM interface in the WASAPI family, such as IAudioClient. /// /// Interface-specific activation parameters. For more information, see the pActivationParams parameter in IMMDevice::Activate. /// /// /// An interface implemented by the caller that is called by Windows when the result of the activation procedure is available. /// /// /// Returns an IActivateAudioInterfaceAsyncOperation interface that represents the asynchronous operation of activating the /// requested WASAPI interface. /// /// /// The function returns an HRESULT. Possible values include, but are not limited to, those in the following table. /// /// /// Return code /// Description /// /// /// S_OK /// The underlying object and asynchronous operation were created successfully. /// /// /// E_ILLEGAL_METHOD_CALL /// /// This error may result if the function is called from an incorrect COM apartment, or if the passed /// IActivateAudioInterfaceCompletionHandler is not implemented on an agile object (aggregating a free-threaded marshaler). /// /// /// /// /// /// /// This function enables Windows Store apps to activate certain WASAPI COM interfaces after using Windows Runtime APIs in the /// Windows.Devices and Windows.Media.Devices namespaces to select an audio device. /// /// /// For many implementations, an application must call this function from the main UI thread to activate a COM interface in the /// WASAPI family so that the system can show a dialog to the user. The application passes an /// IActivateAudioInterfaceCompletionHandler callback COM interface through completionHandler. Windows calls a method in the /// application’s IActivateAudioInterfaceCompletionHandler interface from a worker thread in the COM Multi-threaded Apartment /// (MTA) when the activation results are available. The application can then call a method in the /// IActivateAudioInterfaceAsyncOperation interface to retrieve the result code and the requested WASAPI interface. There are /// some activations that are explicitly safe and therefore don't require that this function be called from the main UI thread. /// These explicitly safe activations include: /// /// /// /// /// Calling ActivateAudioInterfaceAsync with a deviceInterfacePath that specifies an audio render device and an riid that /// specifies the IAudioClient interface. /// /// /// /// /// Calling ActivateAudioInterfaceAsync with a deviceInterfacePath that specifies an audio render device and an riid that /// specifies the IAudioEndpointVolume interface. /// /// /// /// Calling ActivateAudioInterfaceAsync from a session 0 service. For more information, see Services. /// /// /// /// Windows holds a reference to the application's IActivateAudioInterfaceCompletionHandler interface until the operation is /// complete and the application releases the IActivateAudioInterfaceAsyncOperation interface. /// /// /// Important Applications must not free the object implementing the IActivateAudioInterfaceCompletionHandler until /// the completion handler callback has executed. /// /// /// Depending on which WASAPI interface is activated, this function may display a consent prompt the first time it is called. For /// example, when the application calls this function to activate IAudioClient to access a microphone, the purpose of the consent /// prompt is to get the user's permission for the app to access the microphone. For more information about the consent prompt, see /// Guidelines for devices that access personal data. /// /// /// ActivateAudioInterfaceAsync must be called on the main UI thread so that the consent prompt can be shown. If the consent /// prompt can’t be shown, the user can’t grant device access to the app. /// /// /// ActivateAudioInterfaceAsync must be called on a thread in a COM Single-Threaded Apartment (STA). The completionHandler /// that is passed into ActivateAudioInterfaceAsync needs to implement IAgileObject to ensure that there is no deadlock when /// the completionHandler is called from the MTA. Otherwise, an E_ILLEGAL_METHOD_CALL will occur. /// /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/nf-mmdeviceapi-activateaudiointerfaceasync HRESULT // ActivateAudioInterfaceAsync( LPCWSTR deviceInterfacePath, REFIID riid, PROPVARIANT *activationParams, // IActivateAudioInterfaceCompletionHandler *completionHandler, IActivateAudioInterfaceAsyncOperation **activationOperation ); [DllImport("mmdevapi.dll", SetLastError = false, ExactSpelling = true)] [PInvokeData("mmdeviceapi.h", MSDNShortId = "7BAFD9DB-DCD7-4093-A24B-9A8556C6C45B")] public static extern HRESULT ActivateAudioInterfaceAsync([MarshalAs(UnmanagedType.LPWStr)] string deviceInterfacePath, in Guid riid, [In, Optional] PROPVARIANT activationParams, [MarshalAs(UnmanagedType.IUnknown)] IActivateAudioInterfaceCompletionHandler completionHandler, [MarshalAs(UnmanagedType.IUnknown)] out IActivateAudioInterfaceAsyncOperation activationOperation); /// The DIRECTX_AUDIO_ACTIVATION_PARAMS structure specifies the initialization parameters for a DirectSound stream. /// /// /// This structure is used by the IMMDevice::Activate method. When activating an IDirectSound, IDirectSoundCapture, or /// IBaseFilter interface on an audio endpoint device, the DIRECTX_AUDIO_ACTIVATION_PARAMS structure specifies the /// session GUID and stream-initialization flags for the audio stream that the DirectSound module creates and encapsulates in the /// interface instance. During the Activate call, DirectSound calls the IAudioClient::Initialize method and specifies the /// session GUID and stream-initialization flags from the DIRECTX_AUDIO_ACTIVATION_PARAMS structure as input parameters. /// /// /// For more information about IDirectSound, IDirectSoundCapture, and IBaseFilter, see the Windows SDK documentation. /// /// For a code example that uses the DIRECTX_AUDIO_ACTIVATION_PARAMS structure, see Device Roles for DirectShow Applications. /// // https://docs.microsoft.com/en-us/windows/win32/api/mmdeviceapi/ns-mmdeviceapi-directx_audio_activation_params typedef struct // tagDIRECTX_AUDIO_ACTIVATION_PARAMS { DWORD cbDirectXAudioActivationParams; GUID guidAudioSession; DWORD dwAudioStreamFlags; } // DIRECTX_AUDIO_ACTIVATION_PARAMS, *PDIRECTX_AUDIO_ACTIVATION_PARAMS; [PInvokeData("mmdeviceapi.h", MSDNShortId = "d8d16c1c-5306-42a7-885b-4e1c5ee7634d")] [StructLayout(LayoutKind.Sequential)] public struct DIRECTX_AUDIO_ACTIVATION_PARAMS { /// The size, in bytes, of the DIRECTX_AUDIO_ACTIVATION_PARAMS structure. Set this member to sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). public uint cbDirectXAudioActivationParams; /// /// Session GUID. This member is a GUID value that identifies the audio session that the stream belongs to. If the GUID /// identifies a session that has been previously opened, the method adds the stream to that session. If the GUID does not /// identify an existing session, the method opens a new session and adds the stream to that session. The stream remains a /// member of the same session for its lifetime. /// public Guid guidAudioSession; /// /// /// Stream-initialization flags. This member specifies whether the stream belongs to a cross-process session or to a session /// that is specific to the current process. Set this member to 0 or to the following AUDCLNT_STREAMFLAGS_XXX constant: /// /// AUDCLNT_STREAMFLAGS_CROSSPROCESS /// public uint dwAudioStreamFlags; } /// CoClass for . [ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E"), ClassInterface(ClassInterfaceType.None)] [PInvokeData("mmdeviceapi.h")] public class MMDeviceEnumerator { } /// The DEVINTERFACE_XXX GUIDs are used to represent the GUIDs for device interfaces. // https://docs.microsoft.com/en-us/windows/win32/coreaudio/devinterface-xxx-guids [PInvokeData("mmdeviceapi.h", MSDNShortId = "2503463B-D7C6-4C82-8421-424D79FD1C2A")] public static class AudioGuids { /// /// Specifies the query string used to enumerate all audio capture devices on the system. This value is returned by MediaDevice::GetAudioCaptureSelector. /// Passing this value to ActivateAudioInterfaceAsync activates the requested interface on the default audio capture device. /// public static readonly Guid DEVINTERFACE_AUDIO_CAPTURE = new Guid(0x2eef81be, 0x33fa, 0x4800, 0x96, 0x70, 0x1c, 0xd4, 0x74, 0x97, 0x2c, 0x3f); /// /// Specifies the query string used to enumerate all audio render devices on the system. This value is returned by MediaDevice::GetAudioRenderSelector. /// Passing this value to ActivateAudioInterfaceAsync activates the requested interface on the default audio render device. /// public static readonly Guid DEVINTERFACE_AUDIO_RENDER = new Guid(0xe6327cad, 0xdcec, 0x4949, 0xae, 0x8a, 0x99, 0x1e, 0x97, 0x6a, 0x79, 0xd2); /// /// Specifies the query string used to enumerate all MidiInPort objects on the system. This value is returned by MidiInPort::GetDeviceSelector. /// public static readonly Guid DEVINTERFACE_MIDI_INPUT = new Guid(0x504be32c, 0xccf6, 0x4d2c, 0xb7, 0x3f, 0x6f, 0x8b, 0x37, 0x47, 0xe2, 0x2b); /// /// Specifies the query string used to enumerate all MidiOutPort objects on the system. This value is returned by MidiOutPort::GetDeviceSelector. /// public static readonly Guid DEVINTERFACE_MIDI_OUTPUT = new Guid(0x6dc23320, 0xab33, 0x4ce4, 0x80, 0xd4, 0xbb, 0xb3, 0xeb, 0xbf, 0x28, 0x14); } /// Core Audio SDK includes several properties of audio endpoint devices. For more information, see Audio Endpoint Properties. [PInvokeData("mmdeviceapi.h")] public static class AudioPropertyKeys { /// /// /// The PKEY_AudioEndpoint_Association property associates a kernel-streaming (KS) pin category with an audio endpoint /// device. The .inf file that installs an audio adapter assigns a pin category to each KS pin in the adapter. A KS pin on an /// adapter device represents the point at which an audio stream enters or leaves the device. A pin category is a GUID that /// specifies the type of function performed by a KS pin. For example, header file Ksmedia.h defines pin-category GUID /// KSNODETYPE_MICROPHONE to indicate a KS pin that connects to a microphone, and KSNODETYPE_HEADPHONES to indicate a KS pin /// that connects to headphones. For more information, see the description of pin category properties in the Windows DDK documentation. /// /// The vt member of the PROPVARIANT structure is set to VT_LPWSTR. /// /// The pwszVal member of the PROPVARIANT structure points to a null-terminated, wide-character string that /// contains a KS pin category GUID. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_Association = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 2); /// /// /// The PKEY_AudioEndpoint_ControlPanelPageProvider property specifies the CLSID of the registered provider of the /// device-properties extension for the audio endpoint device. The extension supplies the audio endpoint properties that are /// displayed in the device-properties page of the Windows multimedia control panel, Mmsys.cpl. For more information about /// Mmsys.cpl, see the Windows DDK documentation. /// /// The vt member of the PROPVARIANT structure is set to VT_LPWSTR. /// /// The pwszVal member of the PROPVARIANT structure points to a null-terminated, wide-character string that /// contains a GUID that identifies the provider of the control-panel extension. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_ControlPanelPageProvider = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 1); /// /// /// In Windows 10 Version 1605 and later, the PKEY_AudioEndpoint_Default_VolumeInDb property key configures the default /// volume (in dB) for the software volume node. The driver developer should provide the default dB value that they would like /// to set. /// /// /// If an audio driver is not implementing hardware volume node for an endpoint, the OS inserts a software volume node to /// control volume on that endpoint. There are situations, where the default volume value is too low. This INF key provides the /// user a better experience when appropriate gain or attenuation is applied to audio signal. /// /// /// /// /// IHVs and OEMs can override the default software volume value for an endpoint by setting /// PKEY_AudioEndpoint_Default_VolumeInDb on a topology filter using the driver INF file. The value specified by the key is in /// dB units. /// /// This key will be used for both render and capture endpoints. /// This key is ignored if the endpoint has implemented a hardware volume node. /// /// Any value can be set, but the OS will make sure that the value it is within the min and max value settings. For example, if /// the specified value is greater than max volume value, OS will set the default value to the max volume value. /// /// /// The data is stored as a 16.16 fixed point value. The upper 16 bits are used for the whole number of the value and the lower /// 16 bits are used for the fractional portion of the value. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_Default_VolumeInDb = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 9); /// /// /// The PKEY_AudioEndpoint_Disable_SysFx property specifies whether system effects are enabled in the shared-mode stream /// that flows to or from the audio endpoint device. /// /// /// System effects are implemented as audio processing objects (APOs) that can be inserted into an audio stream. APOs are /// software modules that perform audio processing functions such as volume control and format conversion. Disabling the system /// effects for an endpoint device enables the associated stream to pass through the APOs unmodified. /// /// /// For more information about system effects in Windows Vista, see the white papers titled "Custom Audio Effects in Windows /// Vista" and "Reusing Windows Vista Audio System Effects" at the Audio Device Technologies for Windows website. /// /// /// This property applies only to the local-effects and global-effects APOs that were installed by the .inf file that installed /// the audio adapter to which the endpoint device is connected. In addition, this property affects only the target endpoint /// device—it has no effect on the system effects for any other endpoint devices, even if they connect to the same adapter. /// /// The vt member of the PROPVARIANT structure is set to VT_UI4. /// /// The ulVal member of the PROPVARIANT structure is set to ENDPOINT_SYSFX_ENABLED if system effects are /// enabled or to ENDPOINT_SYSFX_DISABLED if they are disabled. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_Disable_SysFx = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 5); /// /// /// The PKEY_AudioEndpoint_FormFactor property specifies the form factor of the audio endpoint device. The form factor /// indicates the physical attributes of the audio endpoint device that the user manipulates. /// /// The vt member of the PROPVARIANT structure is set to VT_UI4. /// /// The uintVal member of the PROPVARIANT structure contains an enumeration value that is cast to type UINT. It is /// set to one of the following EndpointFormFactor enumeration values: /// /// /// /// RemoteNetworkDevice /// /// /// Speakers /// /// /// LineLevel /// /// /// Headphones /// /// /// Microphone /// /// /// Headset /// /// /// Handset /// /// /// UnknownDigitalPassthrough /// /// /// SPDIF /// /// /// HDMI /// /// /// UnknownFormFactor /// /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_FormFactor = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 0); /// /// /// The PKEY_AudioEndpoint_FullRangeSpeakers property specifies the channel-configuration mask for the full-range /// speakers that are connected to the audio endpoint device. The mask indicates the physical configuration of the full-range /// speakers and specifies the assignment of channels to those speakers. /// /// The vt member of the PROPVARIANT structure is set to VT_UI4. /// /// The uintVal member of the PROPVARIANT structure contains a channel-configuration mask that is cast to type UINT. /// /// /// A full-range speaker is capable of playing sounds over the full range from bass to treble. Typically, larger speakers are /// full range but smaller speakers are significantly less capable of playing bass sounds. In Windows Vista, the audio engine /// uses this property to manage bass levels in the audio output stream that is played by the audio endpoint device. /// /// /// The channel-configuration mask for this property is in the same format as the channel-configuration mask for the /// PKEY_AudioEndpoint_PhysicalSpeakers property. For more information about channel-configuration masks, see the following: /// /// /// /// The description of the KSPROPERTY_AUDIO_CHANNEL_CONFIG property in the Windows DDK documentation. /// /// /// /// The white paper titled "Audio Driver Support for Home Theater Speaker Configurations" at the Audio Device Technologies for /// Windows website. /// /// /// /// /// The system obtains the channel-configuration mask for the PKEY_AudioEndpoint_FullRangeSpeakers property from the user. The /// user enters this information through the Windows multimedia control panel, Mmsys.cpl. For more information about Mmsys.cpl, /// see the Windows DDK documentation. /// /// /// The channel-configuration mask for the PKEY_AudioEndpoint_FullRangeSpeakers property of an audio endpoint device is a subset /// of the channel-configuration mask for the PKEY_AudioEndpoint_PhysicalSpeakers property of the same device. /// /// /// For example, if an audio endpoint device drives a set of 5.1 surround-sound speakers, then the channel-configuration mask /// for the PKEY_AudioEndpoint_PhysicalSpeakers property is KSAUDIO_SPEAKER_5POINT1. This mask indicates the presence of /// front-left, front-right, front-center, side-left, and side-right speakers—plus a subwoofer. If the front-left and /// front-right speakers are large enough to produce bass sounds but the smaller front-center and side speakers are not, then /// the channel-configuration mask for the PKEY_AudioEndpoint_FullRangeSpeakers property is KSAUDIO_SPEAKER_STEREO, which /// indicates only the front-left and front-right speakers. Channel-configuration masks KSAUDIO_SPEAKER_5POINT1 and /// KSAUDIO_SPEAKER_STEREO are defined in header file Ksmedia.h. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_FullRangeSpeakers = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 6); /// /// /// The PKEY_AudioEndpoint_GUID property supplies the DirectSound device identifier that corresponds to the audio /// endpoint device. The property value is a GUID that the client can supply as the device identifier to the /// DirectSoundCreate or DirectSoundCaptureCreate function in the DirectSound API. This value uniquely identifies /// the audio endpoint device across all audio endpoint devices in the system. For more information about DirectSound, see the /// DirectX SDK documentation. /// /// The vt member of the PROPVARIANT structure is set to VT_LPWSTR. /// /// The pwszVal member of the PROPVARIANT structure points to a null-terminated, wide-character string that /// contains a GUID that identifies the audio endpoint device in DirectSound. /// /// /// As explained previously, the MMDevice API supports device roles. Although DirectSound does not directly support device /// roles, a DirectSound client can use the PKEY_AudioEndpoint_GUID property to select a DirectSound rendering or capture device /// based on its device role. /// /// /// For example, a DirectSound application performs the following steps to create a DirectSound device that corresponds to the /// rendering endpoint device that the user has assigned the eMultimedia role to: /// /// /// /// /// Call the IMMDeviceEnumerator::GetDefaultAudioEndpoint method to get the IMMDevice interface of the rendering /// endpoint device that has the eMultimedia role. /// /// /// /// /// Call the IMMDevice::OpenPropertyStore method to obtain the IPropertyStore interface of the eMultimedia device. /// For more information about IPropertyStore, see the Windows SDK documentation. /// /// /// /// Call the IPropertyStore::GetValue method to obtain the PKEY_AudioEndpoint_GUID property value. /// /// /// Convert the property value from a GUID in string format to a 16-byte GUID structure. /// /// /// Call the DirectSoundCreate function with the GUID to create the device with the eMultimedia role. /// /// /// /// Note that the 16-byte GUID generated in step 4 matches the device GUID that identifies the device during DirectSound device /// enumeration. The DirectSoundEnumerate function enumerates rendering endpoint devices, and the /// DirectSoundCaptureEnumerate function enumerates capture endpoint devices. In either case, the device GUID is the /// first parameter passed to the enumeration callback function. For more information about DirectSound enumeration, see the /// DirectX SDK documentation. /// /// For a code example that uses the PKEY_AudioEndpoint_GUID property, see Device Roles for DirectSound Applications. /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_GUID = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 4); /// /// /// The PKEY_AudioEndpoint_JackSubType property contains an output category GUID for an audio endpoint device. The header /// file Ksmedia.h defines the GUIDs; each GUID specifies the type of connection. These GUIDs also have associated pin /// categories. For example, header file Ksmedia.h defines the GUID KSNODETYPE_DISPLAYPORT_INTERFACE for a display port /// that connects with the KS pin defined by the GUID PINNAME_DISPLAYPORT_OUT. /// /// For more information, see the description of pin category properties in the Windows DDK documentation. /// The vt member of the PROPVARIANT structure is set to VT_LPWSTR. /// /// The pwszVal member of the PROPVARIANT structure points to a null-terminated, wide-character string that /// contains a category GUID. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_JackSubType = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 8); /// /// /// The PKEY_AudioEndpoint_PhysicalSpeakers property specifies the channel-configuration mask for the audio endpoint /// device. The mask indicates the physical configuration of a set of speakers and specifies the assignment of channels to /// speakers. For more information about channel-configuration masks, see the following: /// /// /// /// The description of the KSPROPERTY_AUDIO_CHANNEL_CONFIG property in the Windows DDK documentation. /// /// /// /// The white paper titled "Audio Driver Support for Home Theater Speaker Configurations" at the Audio Device Technologies for /// Windows website. /// /// /// /// The vt member of the PROPVARIANT structure is set to VT_UI4. /// /// The uintVal member of the PROPVARIANT structure contains a channel-configuration mask that is cast to type UINT. /// /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_PhysicalSpeakers = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 3); /// /// /// The PKEY_AudioEndpoint_Supports_EventDriven_Mode property indicates whether the endpoint supports the event-driven mode. /// /// The vt member of the PROPVARIANT structure is set to VT_UI4. /// /// The uintVal member of the PROPVARIANT structure is a DWORD that indicates if the endpoint supports the /// event-driven mode. /// /// /// /// This property value is populated by an audio OEM in an .inf file to indicate that the HDAudio hardware supports event driven /// mode as per the WHQL requirement. /// public static readonly PROPERTYKEY PKEY_AudioEndpoint_Supports_EventDriven_Mode = new PROPERTYKEY(new Guid(0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e), 7); /// public static readonly PROPERTYKEY PKEY_AudioEndpointLogo_IconEffects = new PROPERTYKEY(new Guid(0xf1ab780d, 0x2010, 0x4ed3, 0xa3, 0xa6, 0x8b, 0x87, 0xf0, 0xf0, 0xc4, 0x76), 0); /// public static readonly PROPERTYKEY PKEY_AudioEndpointLogo_IconPath = new PROPERTYKEY(new Guid(0xf1ab780d, 0x2010, 0x4ed3, 0xa3, 0xa6, 0x8b, 0x87, 0xf0, 0xf0, 0xc4, 0x76), 1); /// public static readonly PROPERTYKEY PKEY_AudioEndpointSettings_LaunchContract = new PROPERTYKEY(new Guid(0x14242002, 0x0320, 0x4de4, 0x95, 0x55, 0xa7, 0xd8, 0x2b, 0x73, 0xc2, 0x86), 1); /// public static readonly PROPERTYKEY PKEY_AudioEndpointSettings_MenuText = new PROPERTYKEY(new Guid(0x14242002, 0x0320, 0x4de4, 0x95, 0x55, 0xa7, 0xd8, 0x2b, 0x73, 0xc2, 0x86), 0); /// /// /// The PKEY_AudioEngine_DeviceFormat property specifies the device format, which is the format that the user has /// selected for the stream that flows between the audio engine and the audio endpoint device when the device operates in shared /// mode. This format might not be the best default format for an exclusive-mode application to use. Typically, an /// exclusive-mode application finds a suitable device format by making some number of calls to the /// IAudioClient::IsFormatSupported method. For more information, see Device Formats. /// /// The vt member of the PROPVARIANT structure is set to VT_BLOB. /// /// The blob member of the PROPVARIANT structure is a structure of type BLOB that contains two members. /// Member blob.cbSize is a DWORD that specifies the number of bytes in the format description. Member /// blob.pBlobData points to a WAVEFORMATEX structure that contains the format description. For more information /// about BLOB, see the Windows SDK documentation. For more information about WAVEFORMATEX, see the Windows DDK documentation. /// /// public static readonly PROPERTYKEY PKEY_AudioEngine_DeviceFormat = new PROPERTYKEY(new Guid(0xf19f064d, 0x82c, 0x4e27, 0xbc, 0x73, 0x68, 0x82, 0xa1, 0xbb, 0x8e, 0x4c), 0); /// /// /// The PKEY_AudioEngine_OEMFormat property specifies the default format of the device that is used for rendering or capturing a /// stream. The values are populated by the OEM in an .inf file. /// /// The vt member of the PROPVARIANT structure is set to VT_BLOB. /// /// The blob member of the PROPVARIANT structure is a structure of type BLOB that contains two members. /// Member blob.cbSize is a DWORD that specifies the number of bytes in the format description. Member /// blob.pBlobData points to a WAVEFORMATEX structure that contains the format description. For more information /// about BLOB, see the Windows SDK documentation. For more information about WAVEFORMATEX, see the Windows DDK documentation. /// /// public static readonly PROPERTYKEY PKEY_AudioEngine_OEMFormat = new PROPERTYKEY(new Guid(0xe4870e26, 0x3cc5, 0x4cd2, 0xba, 0x46, 0xca, 0xa, 0x9a, 0x70, 0xed, 0x4), 3); } } }