//**@@@*@@@**************************************************** // // Microsoft Windows // Copyright (C) Microsoft Corporation. All rights reserved. // //**@@@*@@@**************************************************** // // FileName: MMDeviceAPI.idl // // Abstract: Audio Device and Endpoint API // Provides Enumeration, Activation and IPropertyStore for Audio Endpoint Devices. // // Author: MitchR // // Created: 2004/8/24 // -------------------------------------------------------------------------------- import "unknwn.idl"; import "propsys.idl"; cpp_quote("#define E_NOTFOUND HRESULT_FROM_WIN32(ERROR_NOT_FOUND)") cpp_quote("#define E_UNSUPPORTED_TYPE HRESULT_FROM_WIN32(ERROR_UNSUPPORTED_TYPE)") cpp_quote("#define DEVICE_STATE_ACTIVE 0x00000001") cpp_quote("#define DEVICE_STATE_DISABLED 0x00000002") cpp_quote("#define DEVICE_STATE_NOTPRESENT 0x00000004") cpp_quote("#define DEVICE_STATE_UNPLUGGED 0x00000008") cpp_quote("#define DEVICE_STATEMASK_ALL 0x0000000f") // public property keys cpp_quote("#ifdef DEFINE_PROPERTYKEY") cpp_quote("#undef DEFINE_PROPERTYKEY") cpp_quote("#endif") cpp_quote("#ifdef INITGUID") cpp_quote("#define DEFINE_PROPERTYKEY(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8, pid) EXTERN_C const PROPERTYKEY name = { { l, w1, w2, { b1, b2, b3, b4, b5, b6, b7, b8 } }, pid }") cpp_quote("#else") cpp_quote("#define DEFINE_PROPERTYKEY(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8, pid) EXTERN_C const PROPERTYKEY name") cpp_quote("#endif // INITGUID") // PKEY_AudioEndpoint_xxx // GUID for PKEY_AudioEndpoint_XXX (public): 1da5d803-d492-4edd-8c23-e0c0ffee7f0e // PKEY_AudioEndpoint_FormFactor: AudioEndpointFormFactor (cast to UINT) of an Audio Endpoint IMMDevice // vartype = VT_UI4 cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_FormFactor, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 0); ") // PKEY_AudioEndpoint_ControlPanelPageProvider: mmsys.cpl device properties page extensions. Used in device interface, devnode and endpoint propertystores // vartype = VT_LPWSTR -- A UUID cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_ControlPanelPageProvider, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 1); ") // PKEY_AudioEndpoint_Association: ks pin category to associate with an "endpoint target" property store in an inf file // vartype = VT_LPWSTR (stringized GUID) cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_Association, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 2);") // PKEY_AudioEndpoint_PhysicalSpeakers: the channel configuration of speakers that are physically present in a users system // vartype = VT_UI4 cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_PhysicalSpeakers, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 3);") // PKEY_AudioEndpoint_GUID: A GUID associated with this audio endpoint, unique across all audio endpoints. This GUID can be used as the device identifier in the DirectSound APIs. // vartype = VT_LPWSTR (stringized GUID) cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_GUID, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 4);") // PKEY_Endpoint_Disable_SysFx: Boolean that when TRUE enables SysFx for the endpoint // vartype = VT_UI4 cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_Disable_SysFx, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 5);") // System Effects enable/disable flags: cpp_quote("#define ENDPOINT_SYSFX_ENABLED 0x00000000 // System Effects are enabled.") cpp_quote("#define ENDPOINT_SYSFX_DISABLED 0x00000001 // System Effects are disabled.") // PKEY_AudioEndpoint_FullRangeSpeakers: the channel configuration of speakers that are FullRangely present in a users system // vartype = VT_UI4 cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_FullRangeSpeakers, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 6);") // PKEY_AudioEndpoint_Supports_EventDriven_Mode: INF supplied property that indicates endpoint supports event-driven mode // vartype = VT_UI4 cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_Supports_EventDriven_Mode, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 7);") // PKEY_AudioEndpoint_JackSubType: KS Category ID (GUID) of an Audio Endpoint // vartype = VT_LPWSTR (stringized GUID) cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEndpoint_JackSubType, 0x1da5d803, 0xd492, 0x4edd, 0x8c, 0x23, 0xe0, 0xc0, 0xff, 0xee, 0x7f, 0x0e, 8);") // PKEY_AudioEngine_xxx // GUID for PKEY_AudioEngine_xxx (public): {F19F064D-082C-4e27-BC73-6882A1BB8E4C} // PKEY_AudioEngine_DeviceFormat: The format device format (can be PCM integer) // vartype = VT_BLOB cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEngine_DeviceFormat, 0xf19f064d, 0x82c, 0x4e27, 0xbc, 0x73, 0x68, 0x82, 0xa1, 0xbb, 0x8e, 0x4c, 0); ") // PKEY_AudioEngine_* Index 0, 1, and 2 are in endpointkeys.h // PKEY_AudioEngine_OEMFormat: Specifies the default format that // is used for rendering/capturing. Populated by OEM INF file. // vartype = VT_BLOB cpp_quote("DEFINE_PROPERTYKEY(PKEY_AudioEngine_OEMFormat, 0xe4870e26, 0x3cc5, 0x4cd2, 0xba, 0x46, 0xca, 0xa, 0x9a, 0x70, 0xed, 0x4, 3); ") // PKEY_AudioEngine_* Index 4, 5, and 6 are in endpointkeys.h // PKEY_AudioEngine_* index 7 is in endpointkeys.h // ---------------------------------------------------------------------- // Public Structures // ---------------------------------------------------------------------- typedef struct tagDIRECTX_AUDIO_ACTIVATION_PARAMS { DWORD cbDirectXAudioActivationParams; GUID guidAudioSession; DWORD dwAudioStreamFlags; } DIRECTX_AUDIO_ACTIVATION_PARAMS, *PDIRECTX_AUDIO_ACTIVATION_PARAMS; // ---------------------------------------------------------------------- // Types // ---------------------------------------------------------------------- typedef enum { eRender, eCapture, eAll, EDataFlow_enum_count } EDataFlow; typedef enum { eConsole, eMultimedia, eCommunications, ERole_enum_count } ERole; typedef enum { RemoteNetworkDevice, // = 0 Speakers, LineLevel, Headphones, Microphone, Headset, Handset, UnknownDigitalPassthrough, SPDIF, DigitalAudioDisplayDevice, UnknownFormFactor, EndpointFormFactor_enum_count } EndpointFormFactor; cpp_quote("#define HDMI DigitalAudioDisplayDevice") // ---------------------------------------------------------------------- // Interfaces // ---------------------------------------------------------------------- // ---------------------------------------------------------------------- // IMMNotificationClient // // Description: // This interface is implemented by a client who wishes to be notified of changes // to Endpoint devices on the system. [ object, local, uuid(7991EEC9-7E89-4D85-8390-6C703CEC60C0), nonextensible, helpstring("Interface implemented by objects that want to be notified of MMDevice events"), pointer_default(unique) ] interface IMMNotificationClient : IUnknown { //------------------------------------------------------------------------- // Description: // Called by the MMDeviceEnumerator object when the state of an Endpoint device changes // // Parameters: // pwstrDeviceId - [in] The ID of the Endpoint device whose state has changed // dwNewState - [in] The new state of the device // // Return values: // ignored // [id(1), helpstring("method OnDeviceStateChanged")] HRESULT OnDeviceStateChanged([in, annotation("__in")] LPCWSTR pwstrDeviceId, [in, annotation("__in")]DWORD dwNewState); //------------------------------------------------------------------------- // Description: // Called by the MMDeviceEnumerator object when a new Endpoint device is added to the system // // Parameters: // pwstrDeviceId - [in] The ID of the new Endpoint device // // Remarks: // Clients should check the state of the Endpoint before using it. It is generally more useful // to monitor state changes than Endpoint additions and removals // // Return values: // ignored // [id(2), helpstring("method OnDeviceAdded")] HRESULT OnDeviceAdded([in, annotation("__in")] LPCWSTR pwstrDeviceId); //------------------------------------------------------------------------- // Description: // Called by the MMDeviceEnumerator object when an Endpoint device is removed from the system // // Parameters: // pwstrDeviceId - [in] The ID of the Endpoint device that was removed // // Remarks: // It is generally more useful to monitor state changes than Endpoint additions and removals // // Return values: // ignored // [id(3), helpstring("method OnDeviceRemoved")] HRESULT OnDeviceRemoved([in, annotation("__in")] LPCWSTR pwstrDeviceId); //------------------------------------------------------------------------- // Description: // Called by the MMDeviceEnumerator object when the default Endpoint device for a given role changes // // Parameters: // flow - [in] The dataflow direction // role - [in] The role // pwstrDefaultDeviceId - [in] The ID of the Endpoint device that is now the default for the specified role // // Return values: // ignored // [id(4), helpstring("method OnDefaultDeviceChanged")] HRESULT OnDefaultDeviceChanged([in, annotation("__in")] EDataFlow flow, [in, annotation("__in")] ERole role, [in, annotation("__in")] LPCWSTR pwstrDefaultDeviceId); //------------------------------------------------------------------------- // Description: // Called by the MMDeviceEnumerator object when a value in an Endpoint device property store changes // // Parameters: // pwstrDeviceId - [in] The ID of the Endpoint whose Property has changed // key - [in] The Property that was modified // // Return values: // ignored // [id(5), helpstring("method OnPropertyValueChanged")] HRESULT OnPropertyValueChanged([in, annotation("__in")] LPCWSTR pwstrDeviceId, [in, annotation("__in")]const PROPERTYKEY key); }; // ---------------------------------------------------------------------- // IMMDevice // // Description: // Base interface for Device objects supported by MMDeviceAPI. // QueryInterface on an IMMDevice should succeed for one and only one of the following: // IMMEndpoint // IPnpInterface // IPnpDevnode // [ object, local, uuid(D666063F-1587-4E43-81F1-B948E807363F), nonextensible, helpstring("MMDevice Interface"), pointer_default(unique) ] interface IMMDevice : IUnknown { //------------------------------------------------------------------------- // Description: // Creates an object with the specified interface appropriate for this device. // // Parameters: // iid - [in] The requested interface // dwClsCtx - [in] The requested CLSCTX if the object is a COM object // pActivationParams - [in] Object specific context (usually NULL) // ppInterface - [out] Address of a pointer to receive the new object interface // // Remarks: // The caller is responsible for releasing *ppInterface using IUnknown::Release() // // Return values: // S_OK if successful // E_NOINTERFACE if the specified interface is not supported for this device type // If activation is supported for the requested interface, any initialization // errors returned by the component being activated will be propagated. // See documentation for the activated interface for more information. // [id(1), helpstring("method Activate")] HRESULT Activate([in, annotation("__in")] REFIID iid, [in, annotation("__in")] DWORD dwClsCtx, [in,unique, annotation("__in_opt")] PROPVARIANT* pActivationParams, [out,iid_is(iid), annotation("__out")] void** ppInterface); //------------------------------------------------------------------------- // Description: // Opens a PropertyStore for this object // // Parameters: // stgmAccess - [in] Access flags (e.g. STGM_READ, STGM_WRITE, or STGM_READWRITE) // ppProperties - [out] Address of a pointer to receive the PropertyStore interface // // Remarks: // The caller is responsible for releasing *ppProperties using IUnknown::Release() // // Return values: // S_OK if successful // [id(2), helpstring("method OpenPropertyStore")] HRESULT OpenPropertyStore([in, annotation("__in")] DWORD stgmAccess, [out, annotation("__out")] IPropertyStore** ppProperties); //------------------------------------------------------------------------- // Description: // Returns the ID of the device as an allocated string // // Parameters: // pstrId - [out] The ID of this Device // // Remarks: // The caller is responsible for freeing *pstrId using CoTaskMemFree // // Return values: // S_OK if successful // [id(3), helpstring("method GetId")] HRESULT GetId([out,annotation("__deref_out")] LPWSTR* ppstrId); //------------------------------------------------------------------------- // Description: // Retrieves the current state of the device // // Parameters: // pdwState - [out] Address of a DWORD that is set to the current state of the device // // Remarks: // On return *pdwState will be one of the DEVICE_STATE_xxx flags // // Return values: // S_OK if successful // [id(4), helpstring("method GetState")] HRESULT GetState([out, annotation("__out")] DWORD* pdwState); }; // ---------------------------------------------------------------------- // IMMDeviceCollection // // Description: // Provides methods for accessing and enumerating a collection of IMMDevice objects // [ object, local, uuid(0BD7A1BE-7A1A-44DB-8397-CC5392387B5E), nonextensible, helpstring("Interface for accessing a collection of IMMDevice objects"), pointer_default(unique) ] interface IMMDeviceCollection : IUnknown { //------------------------------------------------------------------------- // Description: // Returns the number of devices in the collection // // Parameters: // pcDevices - [out] Address of a UINT that will receive the count // // Return values: // S_OK if successful // [id(1), helpstring("method GetCount")] HRESULT GetCount([out, annotation("__out")] UINT* pcDevices); //------------------------------------------------------------------------- // Description: // Gets the device at the specified index in the collection // // Parameters: // nDevice - [in] The index // ppDevice - [out] Address of an IMMDevice pointer that will receive the device // // Remarks: // The caller is responsible for releasing *ppDevice using IUnknown::Release() // // Return values: // S_OK if successful // [id(2), helpstring("method Item")] HRESULT Item([in, annotation("__in")]UINT nDevice, [out, annotation("__out")] IMMDevice** ppDevice); }; // ---------------------------------------------------------------------- // IMMEndpoint // // Description: // Provides additional methods beyond IMMDevice for Endpoint device objects // [ object, local, uuid(1BE09788-6894-4089-8586-9A2A6C265AC5), nonextensible, helpstring("Extension to IMMDevice for Audio Endpoint devices"), pointer_default(unique) ] interface IMMEndpoint : IUnknown { //------------------------------------------------------------------------- // Description: // Gets the dataflow of the Endpoint device // // Parameters: // pDataFlow - [out] Address of an EDataFlow that will receive the current dataflow direction // // Remarks: // // Return values: // S_OK if successful // [id(1), helpstring("method GetDataFlow")] HRESULT GetDataFlow([out, annotation("__out")] EDataFlow* pDataFlow); }; // ---------------------------------------------------------------------- // IMMDeviceEnumerator // // Description: // Provides methods for enumerating IMMDevice objects and for registering notifications // about Endpoint devices // [ object, local, uuid(A95664D2-9614-4F35-A746-DE8DB63617E6), nonextensible, helpstring("MMDevice Enumerator Interface"), pointer_default(unique) ] interface IMMDeviceEnumerator : IUnknown { //------------------------------------------------------------------------- // Description: // Enumerates Endpoint devices // // Parameters: // dataFlow - [in] The dataflow direction of Endpoint devices to enumerate // dwStateMask - [in] The allowed states to filter by. Typically, this is DEVICE_STATE_ACTIVE // ppDevices - [out] Address of a pointer that will receive the device collection // // Remarks: // The caller is responsible for releasing *ppDevices using IUnknown::Release() // // Return values: // S_OK if successful // [id(1), helpstring("method EnumAudioEndpoints")] HRESULT EnumAudioEndpoints([in, annotation("__in")] EDataFlow dataFlow, [in, annotation("__in")] DWORD dwStateMask, [out, annotation("__out")] IMMDeviceCollection** ppDevices); //------------------------------------------------------------------------- // Description: // Returns the default Endpoint device for the specified role // // Parameters: // dataFlow - [in] The dataflow direction of Endpoint devices to enumerate // role - [in] The role // ppEndpoints - [out] Address of a pointer that will receive the default Endpoint device // // Remarks: // The caller is responsible for releasing *ppEndpoint using IUnknown::Release() // // Return values: // S_OK if successful // [id(2), helpstring("method GetDefaultAudioEndpoint")] HRESULT GetDefaultAudioEndpoint([in, annotation("__in")] EDataFlow dataFlow, [in, annotation("__in")] ERole role, [out, annotation("__out")] IMMDevice** ppEndpoint); //------------------------------------------------------------------------- // Description: // Gets the device with the specified ID. Use QueryInterface to determine // if it is an Endpoint, Pnp Devnode or Pnp Interface. // // Parameters: // pwstrId - [in] The ID of the device to retrieve // ppDevice - [out] Address of a pointer that will receive the device // // Remarks: // The caller is responsible for releasing *ppDevice using IUnknown::Release() // // Return values: // S_OK if successful // [id(3), helpstring("method GetDevice")] HRESULT GetDevice([in, annotation("__in")]LPCWSTR pwstrId, [out, annotation("__out")] IMMDevice** ppDevice); //------------------------------------------------------------------------- // Description: // Registers the specified client to receive Endpoint device notifications // // Parameters: // pClient - [in] Pointer to an IMMNotificationClient interface on an object implemented by the client // // Remarks: // The client is responsible for ensuring that the specified object is valid until calling UnregisterEndpointNotificationCallback // // Return values: // S_OK if successful // [id(4), helpstring("method RegisterEndpointNotificationCallback")] HRESULT RegisterEndpointNotificationCallback([in, annotation("__in")] IMMNotificationClient* pClient); //------------------------------------------------------------------------- // Description: // Unregisters a client that was registered in a previous call to RegisterEndpointNotificationCallback // // Parameters: // pClient - [in] The client to unregister // // Return values: // S_OK if successful // [id(5), helpstring("method UnregisterEndpointNotificationCallback")] HRESULT UnregisterEndpointNotificationCallback([in, annotation("__in")] IMMNotificationClient* pClient); }; // ---------------------------------------------------------------------- // IMMDeviceActivator // // Description: // Interface provided by an object that can be activated on a device. i.e Components that // provide interfaces produced by IMMDevice::Activate must support this interface. // cpp_quote("/* IMMDeviceActivator is reserved for system use */") [ object, local, uuid(3B0D0EA4-D0A9-4B0E-935B-09516746FAC0), nonextensible, helpstring("Interface implemented by objects that can be activated on an IMMDevice object"), pointer_default(unique) ] interface IMMDeviceActivator : IUnknown { //------------------------------------------------------------------------- // Description: // Creates an object that implements the specified interface on behalf of the specified device // // Parameters: // iid - [in] The specified interface // pDevice - [in] The specified device // pActivationParams - [in] Component specific data. This is supplied by clients in a call to IMMDevice::Activate // ppInterface - [out] Address of a pointer that will receive the specified interface // // Remarks: // The caller is responsible for releasing *ppInterface using IUnknown::Release() // // Return values: // S_OK if successful // [id(1), helpstring("method Activate")] HRESULT Activate([in, annotation("__in")] REFIID iid, [in, annotation("__in")] IMMDevice* pDevice, [in, annotation("__in_opt")] PROPVARIANT* pActivationParams, [out,iid_is(iid), annotation("__out")] void** ppInterface); }; cpp_quote("/* IMMDeviceActivator is reserved for system use */") // ---------------------------------------------------------------------- // Structures // ---------------------------------------------------------------------- // This structure is passed to the Control Panel Endpoint Extension property // page via IShellPropSheetExt::AddPages typedef struct { LPARAM AddPageParam; IMMDevice* pEndpoint; IMMDevice* pPnpInterface; IMMDevice* pPnpDevnode; } AudioExtensionParams; // ---------------------------------------------------------------------- // [ uuid(2FDAAFA3-7523-4F66-9957-9D5E7FE698F6), version(1.0), helpstring("MM Device API 1.0 Type Library") ] library MMDeviceAPILib { //------------------------------------------------------------------------- // MMDeviceEnumerator coclass [ uuid(BCDE0395-E52F-467C-8E3D-C4579291692E), ] coclass MMDeviceEnumerator { [default] interface IMMDeviceEnumerator; }; };