BluetoothAuthenticateDevice 函式 (bluetoothapis.h)

發行項
02/23/2024

BluetoothAuthenticateDevice 函式會將驗證要求傳送至遠端藍牙裝置。

注意針對 Windows Vista SP2 和 Windows 7 進行開發時，建議使用 BluetoothAuthenticateDeviceEx 。

語法

DWORD BluetoothAuthenticateDevice(
  HWND                  hwndParent,
  HANDLE                hRadio,
  BLUETOOTH_DEVICE_INFO *pbtbi,
  PWSTR                 pszPasskey,
  ULONG                 ulPasskeyLength
);

參數

hwndParent

要成為驗證精靈父系的視窗。如果設定為 NULL，精靈會從桌面移除。

hRadio

有效的本機無線電句柄或 NULL。如果 為 NULL，則會在所有本機無線電上嘗試驗證;如果有任何無線電成功，函式調用就會成功。

pbtbi

類型為 BLUETOOTH_DEVICE_INFO 的結構，其中包含要驗證的藍牙裝置記錄。

pszPasskey

個人標識碼 (PIN) 用於裝置驗證。如果設定為 NULL，則會顯示使用者介面，而且用戶必須遵循使用者介面中提供的驗證程式。如果 pszPasskey 不是 NULL，則不會顯示任何使用者介面。如果傳遞機碼不是 NULL，它必須是 NULL 終止的字串。如需詳細資訊，請參閱＜備註＞一節。

ulPasskeyLength

pszPasskey 的大小，以字元為單位。 pszPasskey 的大小必須小於或等於 BLUETOOTH_MAX_PASSKEY_SIZE。

傳回值

在成功完成時 傳回ERROR_SUCCESS 。

下表列出常見的錯誤。

傳回碼	Description
ERROR_CANCELLED	使用者已取消作業。
ERROR_INVALID_PARAMETER	pbtdi 參數中的裝置結構無效。
ERROR_NO_MORE_ITEMS	pbtdi 所指向的裝置已標示為已驗證。

備註

某些遠端藍牙裝置只能接受數值複雜金鑰。無法識別哪些裝置只會事先接受數值複雜密鑰。

藍牙驗證程式有兩種模式：精靈模式和透明模式。

當 pszPasskey 設定為 NULL，且啟動藍牙聯機精靈時，就會啟動精靈模式。系統會提示使用者在精靈中輸入傳遞密鑰作為步驟，之後就會傳送驗證要求。使用者介面會顯示驗證嘗試成功或失敗，並讓用戶有機會重新嘗試失敗的驗證。

當 pszPasskey 不是 NULL 時，就會啟動透明模式。在透明模式中，驗證要求會傳送至遠端藍牙裝置，而不會顯示任何使用者介面。在透明模式中，藍牙狀態代碼會對應至 Win32 錯誤碼;下表列出此對應資訊。

藍牙狀態代碼	Win32 錯誤碼
BTH_ERROR_SUCCESS	ERROR_SUCCESS
BTH_ERROR_NO_CONNECTION	ERROR_DEVICE_NOT_CONNECTED
BTH_ERROR_PAGE_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_HARDWARE_FAILURE	ERROR_GEN_FAILURE
BTH_ERROR_AUTHENTICATION_FAILURE	ERROR_NOT_AUTHENTICATED
BTH_ERROR_MEMORY_FULL	ERROR_NOT_ENOUGH_MEMORY
BTH_ERROR_CONNECTION_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_LMP_RESPONSE_TIMEOUT	WAIT_TIMEOUT
BTH_ERROR_MAX_NUMBER_OF_CONNECTIONS	ERROR_REQ_NOT_ACCEP
BTH_ERROR_PAIRING_NOT_ALLOWED	ERROR_ACCESS_DENIED
BTH_ERROR_UNSPECIFIED_ERROR	ERROR_NOT_READY
BTH_ERROR_LOCAL_HOST_TERMINATED_CONNECTION	ERROR_VC_DISCONNECTED

規格需求

需求	值
最低支援的用戶端	Windows Vista、Windows XP 與 SP2 [僅限傳統型應用程式]
最低支援的伺服器	都不支援
目標平台	Windows
標頭	bluetoothapis.h (包括 Bthsdpdef.h、BluetoothAPIs.h)
程式庫	Bthprops.lib
Dll	bthprops.cpl