//**@@@*@@@****************************************************
//
// 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;
    };
};


