UMSKT
/
xpmgr
mirror of https://github.com/UMSKT/xpmgr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
xpmgr/BuildTools/Include/mmdeviceapi.idl

601 lines
23 KiB
Plaintext
Raw Blame History

//**@@@*@@@****************************************************
//
// 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
// <other> 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;
};
};
Reference in New Issue View Git Blame Copy Permalink