裝置屬性 （核心音訊 API）
在列舉 音訊端點裝置的過程中，用戶端應用程式可以詢問其裝置屬性的端點物件。 裝置屬性會在 MMDevice API 實作 IPropertyStore 介面中公開。 鑒於端點物件的 IMMDevice 介面參考，用戶端可以藉由呼叫 IMMDevice：：OpenPropertyStore 方法來取得端點物件屬性存放區的參考。
用戶端可以讀取這些屬性，但不應該加以設定。 屬性值會儲存為 PROPVARIANT 結構。
端點管理員會設定端點的基本裝置屬性。 端點管理員是負責偵測音訊端點裝置是否存在的 Windows 元件。
下列清單中的每個 PKEY_Xxx 屬性標識碼都是 propertyKEY 類型的常數 PROPERTYKEY，定義於頭檔 Functiondiscoverykeys_devpkey.h中。 所有音訊端點裝置都有這些裝置屬性。
| 財產 | 描述 |
|---|---|
| PKEY_DeviceInterface_FriendlyName | 端點裝置所連接的音訊配接器的易記名稱（例如，“XYZ 音訊配接器”）。 |
| PKEY_Device_DeviceDesc | 端點裝置的裝置描述（例如「說話者」）。 |
| PKEY_Device_FriendlyName | 端點裝置的易記名稱（例如「喇叭（XYZ 音訊配接器）」。 |
| PKEY_Device_InstanceId | 儲存裝置實例標識碼音訊端點。 您也可以透過 IMMDevice：：GetId 方法來取得此值。 如您要此屬性的詳細資訊，請參閱 端點識別子字串 和 DEVPKEY_Device_InstanceId。 |
| PKEY_Device_ContainerId | 儲存實作音頻端點的 PnP 裝置 容器標識碼。 如需此屬性的詳細資訊，請參閱 DEVPKEY_Device_ContainerId。 |
某些音訊端點裝置可能有其他屬性未出現在上述清單中。 如需其他屬性的詳細資訊，請參閱 音訊端點屬性。
如需 PROPERTYKEY的詳細資訊，請參閱 Windows 屬性系統檔案。
下列程式代碼範例會列印系統中所有音訊轉譯端點裝置的顯示名稱：
//-----------------------------------------------------------
// This function enumerates all active (plugged in) audio
// rendering endpoint devices. It prints the friendly name
// and endpoint ID string of each endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres) \
if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk) \
if ((punk) != NULL) \
{ (punk)->Release(); (punk) = NULL; }
const CLSID CLSID_MMDeviceEnumerator = __uuidof(MMDeviceEnumerator);
const IID IID_IMMDeviceEnumerator = __uuidof(IMMDeviceEnumerator);
void PrintEndpointNames()
{
HRESULT hr = S_OK;
IMMDeviceEnumerator *pEnumerator = NULL;
IMMDeviceCollection *pCollection = NULL;
IMMDevice *pEndpoint = NULL;
IPropertyStore *pProps = NULL;
LPWSTR pwszID = NULL;
hr = CoCreateInstance(
CLSID_MMDeviceEnumerator, NULL,
CLSCTX_ALL, IID_IMMDeviceEnumerator,
(void**)&pEnumerator);
EXIT_ON_ERROR(hr)
hr = pEnumerator->EnumAudioEndpoints(
eRender, DEVICE_STATE_ACTIVE,
&pCollection);
EXIT_ON_ERROR(hr)
UINT count;
hr = pCollection->GetCount(&count);
EXIT_ON_ERROR(hr)
if (count == 0)
{
printf("No endpoints found.\n");
}
// Each loop prints the name of an endpoint device.
for (ULONG i = 0; i < count; i++)
{
// Get pointer to endpoint number i.
hr = pCollection->Item(i, &pEndpoint);
EXIT_ON_ERROR(hr)
// Get the endpoint ID string.
hr = pEndpoint->GetId(&pwszID);
EXIT_ON_ERROR(hr)
hr = pEndpoint->OpenPropertyStore(
STGM_READ, &pProps);
EXIT_ON_ERROR(hr)
PROPVARIANT varName;
// Initialize container for property value.
PropVariantInit(&varName);
// Get the endpoint's friendly-name property.
hr = pProps->GetValue(
PKEY_Device_FriendlyName, &varName);
EXIT_ON_ERROR(hr)
// GetValue succeeds and returns S_OK if PKEY_Device_FriendlyName is not found.
// In this case vartName.vt is set to VT_EMPTY.
if (varName.vt != VT_EMPTY)
{
// Print endpoint friendly name and endpoint ID.
printf("Endpoint %d: \"%S\" (%S)\n",
i, varName.pwszVal, pwszID);
}
CoTaskMemFree(pwszID);
pwszID = NULL;
PropVariantClear(&varName);
SAFE_RELEASE(pProps)
SAFE_RELEASE(pEndpoint)
}
SAFE_RELEASE(pEnumerator)
SAFE_RELEASE(pCollection)
return;
Exit:
printf("Error!\n");
CoTaskMemFree(pwszID);
SAFE_RELEASE(pEnumerator)
SAFE_RELEASE(pCollection)
SAFE_RELEASE(pEndpoint)
SAFE_RELEASE(pProps)
}
上述程式代碼範例中的 FAILED 巨集定義於頭檔 Winerror.h 中。
在上述程式代碼範例中，PrintEndpointNames 函式中 迴圈本文的會呼叫 IMMDevice：：GetId 方法，以取得 IMMDevice 介面實例所代表音頻端點裝置的 端點標識符 字符串。 字串會唯一識別系統中所有其他音訊端點裝置的裝置。 用戶端可以使用端點標識符字串，在稍後或呼叫 IMMDeviceEnumerator：：GetDevice 方法來建立音訊端點裝置的實例。 用戶端應將端點標識符字串的內容視為不透明。 也就是說，客戶端不應該嘗試剖析字串的內容，以取得裝置的相關信息。 原因是字串格式未定義，而且可能會從MMDevice API的其中一個實作變更為下一個。
上述程式代碼範例中 PrintEndpointNames 函式取得的易記裝置名稱和端點標識符字串，與 DirectSound 在裝置列舉期間提供的易記裝置名稱和端點標識符字元串相同。 如需詳細資訊，請參閱 舊版音訊應用程式的音訊事件。
在上述程式代碼範例中，PrintEndpointNames 函式會呼叫 CoCreateInstance 函式，為系統中的音訊端點裝置建立列舉值。 除非先前呼叫 CoInitialize 或 CoInitializeEx 函式來初始化 COM 連結庫，否則呼叫 coCreateInstance 呼叫 將會失敗。 如需 CoCreateInstance、CoInitialize和 CoInitializeEx的詳細資訊，請參閱 Windows SDK 檔。
如需 IMMDeviceEnumerator、IMMDeviceCollection和 IMMDevice 介面的詳細資訊，請參閱 MMDevice API。