phoneGetIcon 函式 (tapi.h)

發行項
03/02/2024

phoneGetIcon 函式可讓應用程式擷取服務電話裝置特定 (或可向用戶顯示的提供者特定) 圖示。

語法

LONG phoneGetIcon(
  DWORD   dwDeviceID,
  LPCSTR  lpszDeviceClass,
  LPHICON lphIcon
);

參數

dwDeviceID

要求圖示的手機裝置標識碼。

lpszDeviceClass

識別裝置類別名稱之 Null 終止字串的指標。此裝置類別可讓應用程式選取適用於該裝置類別的特定子圖示。此參數是選擇性的，而且可以保留 NULL 或空白，在此情況下，會選取與手機裝置相關聯的最高層級圖示，而不是選取指定的媒體串流裝置。

lphIcon

傳回圖示句柄的記憶體位置指標。

傳回值

如果要求成功或發生錯誤，則傳回零。可能的傳回值為：

PHONEERR_BADDEVICEID、PHONEERR_RESOURCEUNAVAIL、PHONEERR_INVALPOINTER、PHONEERR_OPERATIONFAILED、PHONEERR_INVALDEVICECLASS、PHONEERR_UNINITIALIZED、PHONEERR_NOMEM、PHONEERR_NODEVICE。

備註

phoneGetIcon 函式會使提供者將 lphIcon) 中的句 (柄傳回至與指定電話相關聯的 LoadIcon) 取得的圖示資源 (。圖示句柄適用於與提供者相關聯的資源;如果應用程式想要在卸除提供者之後參考圖示，則應用程式必須使用 CopyIcon ，只要應用程式已開啟手機，就不太可能發生此情況。

lpszDeviceClass 參數可讓提供者根據呼叫端所參考的服務類型傳回不同的圖示。允許的字串與 phoneGetID 相同。例如，如果手機支援 Comm API，將「COMM」當做 lpszDeviceClass 傳遞，會導致提供者傳回與服務提供者的 Comm 裝置功能相關的圖示。參數「tapi/phone」、“或 NULL 可用來要求電話服務的圖示。

對於使用 TAPI 版本早於 2.0 的應用程式，如果提供者未傳回圖示， (因為指定的裝置類別無效，或提供者不支援圖示) ，TAPI 會取代一般 Telephony phone 裝置圖示。對於使用 TAPI 2.0 版或更新版本的應用程式，只有在 lpszDeviceClass 參數為 “tapi/phone”、“” 或 NULL 時，TAPI 才會取代默認手機圖示。對於任何其他裝置類別，如果指定的裝置類別無效，或提供者不支援類別的圖示， phoneGetIcon 會傳回PHONEERR_INVALDEVICECLASS。