BluetoothDisplayDeviceProperty - функция выводит стандартное окно свойств устройства Bluetooth.

Объявление функции:

function BluetoothEnableDiscovery(
 hwndParent : HWND;
 var pbtdi : PBLUETOOTH_DEVICE_INFO): BOOL; stdcall; 

Важно: В оригинале (см. примечание выше) функция выглядит вот так:

function BluetoothEnableDiscovery(
 hwndParent : HWND;
 pbtdi : PBLUETOOTH_DEVICE_INFO): BOOL; stdcall; 

Это не верно, так как в документации Microsoft указано, что параметр pbtdi должен передаваться как указатель (что подразумевает запись PBLUETOOTH_DEVICE_INFO), но как я писал выше, этот тип ошибочен. Он не является указателем. Я изменил функцию так, как показано выше (так она и должна быть, если не менять определение типа). Параметры:

hwndParent	Handle родительского окна, которому будет принадлежать диалог свойств. Может быть 0, тогда родительским выбирается окно Desktop.
pbtdi	Указатель на структуру BLUETOOTH_DEVICE_INFO в которой содержится адрес требуемого устройства.

Возвращаемые значения:

• TRUE - если вызов успешен
• FALSE - в противном случае (код ошибки можно узнать вызовом функции GetLastError).

Выбор устройства

Рассмотрим, как вызвать окно диалога выбора устройства.

Добавим в наш проект на Panel еще одну кнопку TButton и установите ее свойства как в таблице:

Напишем вот такой обработчик события OnClick у этой кнопки:

procedure TfmMain.btSelectClick(Sender: TObject);
var
 ASelParams: BLUETOOTH_SELECT_DEVICE_PARAMS;
 ASelParamsSize: dword;
begin
 ASelParamsSize := SizeOf(BLUETOOTH_SELECT_DEVICE_PARAMS);
 FillChar(ASelParams, ASelParamsSize, 0);
 with ASelParams do
 begin
 dwSize := ASelParamsSize;
 hwndParent := Handle;
 fShowRemembered := True;
 fAddNewDeviceWizard := True;
 end;

 BluetoothSelectDevices(@ASelParams);
 BluetoothSelectDevicesFree(@ASelParams);
end 

В этой части кода две новые функции.

BluetoothSelectDevices - функция разрешает/запрещает обнаружение локального радиомодуля Bluetooth.

Объявление функции:

function BluetoothSelectDevices(
 pbtsdp : PBLUETOOTH_SELECT_DEVICE_PARAMS): BOOL; stdcall; 

Параметры:

pbtsdp

Описание смотрите ниже в описании структуры.

Возвращаемые значения:

Если функция вернула TRUE, то пользователь выбрал устройства. Pbtsdp^.pDevices будет указывать на корректные данные. После вызова необходимо проверить флаги fAuthenticated и fRemembered, что бы удостовериться в корректности данных. Для освобождения памяти используйте функцию BluetoothSelectDevicesFree, только если функция вернет TRUE.

Вернет FALSE если вызов прошел не удачно. Используйте GetLastError для получения дополнительных сведений. Возможные ошибки:

ERROR_CANCELLED	Пользователь отменил выбор устройства.
ERROR_INVALID_PARAMETER	Параметр pbsdp равен nil.
ERROR_REVISION_MISMATCH	Структура, переданная в pbsdp неизвестного или неверного размера.
Другие ошибки Win32

BLUETOOTH_SELECT_DEVICE_PARAMS

Объявление:

BLUETOOTH_SELECT_DEVICE_PARAMS = record
 dwSize : DWORD;
 cNumOfClasses : ULONG;
 prgClassOfDevices : PBlueToothCodPairs;
 pszInfo : LPWSTR;
 hwndParent : HWND;
 fForceAuthentication : BOOL;
 fShowAuthenticated : BOOL;
 fShowRemembered : BOOL;
 fShowUnknown : BOOL;
 fAddNewDeviceWizard : BOOL;
 fSkipServicesPage : BOOL;
 pfnDeviceCallback : PFN_DEVICE_CALLBACK;
 pvParam : Pointer;
 cNumDevices : DWORD;
 pDevices : __PBLUETOOTH_DEVICE_INFO;
end; 

Члены:

dwSize	Должен быть равен размеру структуры (dwSize := SizeOf(BLUETOOTH_RADIO_INFO))
cNumOfClasses	Входной параметр. Количество записей в массиве prgClassOfDevice. Если 0, то ищутся все устройства.
prgClassOfDevices	Входной параметр. Массив COD (классов устройств), которые необходимо искать.
pszInfo	Входной параметр. Если не nil, то задает текст заголовка окна выбора устройства.
hwndParent	Входной параметр. Handle родительского окна для диалога выбора устройства. Если 0, то родителем будет Desktop.
fForceAuthentication	Входной параметр. Если TRUE, то требует принудительной авторизации устройств.
fShowAuthenticated	Входной параметр. Если TRUE, то авторизованные устройства будут доступны для выбора.
fShowRemembered	Входной параметр. Если TRUE, то запомненные устройства будут доступны для выбора.
fShowUnknown	Входной параметр. Если TRUE, то неизвестные (неавторизованные и не запомненные) устройства будут доступны для выбора.
fAddNewDeviceWizard	Входной параметр. Если TRUE, то запускает мастер добавления нового устройства.
fSkipServicesPage	Входной параметр. Если TRUE, то пропускает страницу Сервисы в мастере.
pfnDeviceCallback	Входной параметр. Если не nil, то является указателем на функцию обратного вызова, которая вызывается для каждого найденного устройства. Если функция вернет TRUE, то устройства добавляется в список, если нет, то устройство игнорируется.
pvParam	Входной параметр. Его значение будет передано функции pfnDeviceCallback в качестве параметра pvParam.
cNumDevices	Как входной параметр – количество устройств, которое требуется вернуть. Если 0, то нет ограничений. Как выходной параметр – количество возвращенных устройств (выбранных).
pDevices	Выходной параметр. Указатель на массив структур BLUETOOTH_DEVICE_INFO. Для его освобождения используйте функцию BluetoothSelectDevicesFree. Важно: В оригинале этот параметр объявлен как PBLUETOOTH_DEVICE_INFO. По этому поводу здесь много комментариев.

BluetoothSelectDevicesFree - функция должна вызываться, только если вызов BluetoothSelectDevices был успешен. Эта функция освобождает память и ресурсы, задействованные функцией BluetoothSelectDevices в структуре BLUETOOTH_SELECT_DEVICE_PARAMS.

Объявление функции:

function BluetoothSelectDevices(
 pbtsdp : PBLUETOOTH_SELECT_DEVICE_PARAMS): BOOL; stdcall; 

Параметры:

pbtsdp

Описание смотрите выше в описании структуры.

Возвращаемые значения:

• TRUE - если вызов успешен,
• FALSE - нечего освобождать.

Управление сервисами

Для управления сервисами Microsoft Bluetooth API предоставляет функцию:

BluetoothSetServiceState - включает или выключает указанный сервис для устройства Bluetooth. Система проецирует сервис Bluetooth на соответствующий драйвер. При отключении сервиса – драйвер удаляется. При его включении – драйвер устанавливается. Если выполняется включение не поддерживаемого сервиса, то драйвер не будет установлен.

Объявление функции:

function BluetoothSetServiceState(
 hRadio : Thandle;
 var pbtdi : PBLUETOOTH_DEVICE_INFO;
 const pGuidService : TGUID;
 dwServiceFlags : DWORD): DWORD; stdcall; 

Параметры:

hRadio	Описатель радиомодуля.
pbtdi	Указатель на структуру BLUETOOTH_DEVICE_INFO.
pGuidService	GUID сервиса, который необходимо включить/выключить.
dwServiceFlags	Флаги управления сервисом: BLUETOOTH_SERVICE_DISABLE – отключает сервис; BLUETOOTH_SERVICE_ENABLE – включает сервис.

Возвращает ERROR_SUCCESS если вызов прошел успешно. Если вызов не удался вернет один из следующих кодов:

ERROR_INVALID_PARAMETER	Неверные флаги в dwServiceFlags
ERROR_SERVICE_DOES_NOT_EXIST	Указанный сервис не поддерживается
Другие ошибки Win32

Важно: В оригинале (см. примечание выше) функция выглядит вот так:

function BluetoothSetServiceState(
 hRadio : Thandle;
 pbtdi : PBLUETOOTH_DEVICE_INFO;
 const pGuidService : TGUID;
 dwServiceFlags : DWORD): DWORD; stdcall; 

Это не верно, так как в документации Microsoft указано, что параметр pbtdi должен передаваться как указатель (что подразумевает запись PBLUETOOTH_DEVICE_INFO), но как я писал выше, этот тип ошибочен. Он не является указателем. Я изменил функцию так, как показано выше (так она и должна быть, если не менять определение типа).

Как использовать функцию? Давайте добавим к ActionList еще одну TAction с такими свойствами:

И добавим на Panel еще одну кнопку TButton, установив у нее следующие свойства:

В обработчике события OnUpdate для acEnable напишем вот такой код:

 procedure TfmMain.acEnableUpdate(Sender: TObject);
 var
 SelectedNode: TTreeNode;
 SelectedItem: TListItem;
 begin
 SelectedNode := TreeView.Selected;
 SelectedItem := ListView.Selected;

 TAction(Sender).Enabled := Assigned(SelectedNode) and
 Assigned(SelectedItem) and
 (SelectedNode.ImageIndex = -2);
 end; 

А в обработчике OnExecute для acEnable вот такой код:

 procedure TfmMain.acEnableExecute(Sender: TObject);
 var
 GUID: TGUID;
 begin
 GUID := StringToGUID(ListView.Selected.Caption);
 BluetoothSetServiceState(TreeView.Selected.Parent.ImageIndex,
 BLUETOOTH_DEVICE_INFO(TreeView.Selected.Data^),
 GUID,
 BLUETOOTH_SERVICE_DISABLE);
 end; 

Важно: После нажатия на кнопку btEnable сервис будет удален из системы. Включить его можно будет через окно свойств устройства Bluetooth.

Как определять отключенные сервисы рассмотрим в серии про передачу данных через Bluetooth.

Удаление устройств

Для удаления устройств используется функция:

BluetoothRemoveDevice - функция удаляет авторизацию между компьютером и устройством Bluetooth. Так же очищает кэш-записи об этом устройстве.

Объявление функции:

function BluetoothRemoveDevice(
 var pAddress : BLUETOOTH_ADDRESS): DWORD; stdcall;

Параметры:

hAddress

Адрес устройства, которое удаляется.

Возвращаемые значения:

ERROR_SUCCESS	устройство удалено
ERROR_NOT_FOUND	устройство не найдено

Давайте попробуем. Добавим в ActionList TAction со следующими свойствами:

И на Panel кнопку TButton со свойствами:

В обработчике OnUpdate для acRemove напишем следующий код:

 procedure TfmMain.acRemoveUpdate(Sender: TObject);
 begin
 TAction(Sender).Enabled := acProperty.Enabled;
 end;

А для события OnExecute вот такой код:

 procedure TfmMain.acRemoveExecute(Sender: TObject);
 var
 Info: BLUETOOTH_DEVICE_INFO;
 Res: dword;
 begin
 Info := BLUETOOTH_DEVICE_INFO(ListView.Selected.Data^);
 Res := BluetoothRemoveDevice(Info.Address);
 if Res <> ERROR_SUCCESS then
 MessageDlg('Device not found', mtError, [mbOK], 0);
 TreeViewChange(TreeView, TreeView.Selected);
 end; 

Процедура выполняется достаточно долго, так что не думайте, что программа зависла.

Важно: Устройство удаляется из списка. Однако, если уже иметь адрес устройства, то можно получить о нем информацию.

Есть еще одно функция, которая связана с BluetoothRemoveDevice. Это:

BluetoothUpdateDeviceRecord - функция обновляет данные об устройстве в кэше.

Объявление функции:

function BluetoothUpdateDeviceRecord(
 var pbtdi : BLUETOOTH_DEVICE_INFO): DWORD; stdcall; 

Параметры:

pbtdu

Указатель на структуру BLUETOOTH_DEVICE_INFO. В ней должны быть заполнены поля: dwSize – размер структуры; Address – адрес устройства; szName – новое имя устройства.

Возвращаемые значения:

ERROR_SUCCESS	Функция выполнена успешно
ERROR_INVALID_PARAMETER	Указатель pbtdi=nil. (Для варианта в Delphi не реально, так как указатель мы получаем из структуры, передавая ее как var-параметр).
ERROR_REVISION_MISMATCH	Размер структуры в dwSize не правильный
Другие ошибки Win32

Попробуем использовать и ее. Схема стандартная: TAction к ActionList, TButton на Panel:

Код:

 procedure TfmMain.acUpdateUpdate(Sender: TObject);
 begin
 TAction(Sender).Enabled := acProperty.Enabled;
 end; 

 procedure TfmMain.acUpdateExecute(Sender: TObject);
 var
 Info: BLUETOOTH_DEVICE_INFO;
 Res: dword;
 NewName: string;
 begin
 if InputQuery('Имя устройства', 'Новое имя', NewName) then begin
 lstrcpyW(Info.szName, PWideChar(WideString(NewName)));
 Res := BluetoothUpdateDeviceRecord(Info);
 if Res <> ERROR_SUCCESS then RaiseLastOsError;
 TreeViewChange(TreeView, TreeView.Selected);
 end;
 end; 

Как видите, все просто.

И так, удалять устройства мы умеем. Давайте теперь научимся добавлять их. Для этого Bluetooth API предоставляет две функции:

BluetoothAuthenticateDevice - отправляет запрос на авторизацию удаленному устройству Bluetooth. Есть два режима авторизации: "Wizrd mode" и "Blind Mode".

"Wizard Mode" запускается, когда параметр pszPasskey = nil. В этом случае открывается окно "Мастера подключения". У пользователя будет запрошен пароль, который будет отправлен в запросе на авторизацию удаленному устройству. Пользователь будет оповещен системой об успешном или не успешном выполнении авторизации и получит возможность попытаться авторизировать устройства еще раз.

"Blind Mode" вызывается, когда pszPasskey <> nil. В этом случае пользователь не увидит никакого мастера. Вам необходимо программно запросить код авторизации (pszPasskey) и уведомить пользователя о результате.

Объявление функции:

function BluetoothAuthenticateDevice(
 hwndParent : HWND;
 hRadio : THandle;
 pbtdi : BLUETOOTH_DEVICE_INFO;
 pszPasskey : PWideChar;
 ulPasskeyLength : ULONG): DWORD; stdcall; 

Параметры:

hwndParent	Handle родительского окна. Если 0, то родительским окном станет окно Desktop.
hRadio	Handle локального радиомодуля. Если 0, то авторизация будет проведена на всех радиомодулях. Если хотя бы один пройдет авторизацию, функция выполнится успешно.
pbdti	Информация об устройстве, на котором необходимо авторизироваться.
pszPasskey	PIN для авторизации. Если nil, то вызывается мастер авторизации (описано выше). Важно: pszPasskey не NULL-терминированная строка!
ulPasskeyLength	Длина строки в байтах. Должна быть меньше либо равна BLUETOOTH_MAX_PASSKEY_SIZE * SizeOf(WCHAR).

Возвращаемые значения:

ERROR_SUCCESS	Функция выполнена успешно
ERROR_CANCELLED	Пользователь отменил процесс авторизации
ERROR_INVALID_PARAMETER	Структура pbtdi не верна
ERROR_NO_MORE_ITEMS	Устройство в pbtdi уже авторизированно
Другие ошибки Win32

Для "Blind Mode" соответствие кодов ошибок Bluetooth кодам ошибок Win32 приведено в таблице:

Аналогичная функция:

BluetoothAuthenticateMultipleDevices - позволяет авторизироваться сразу на нескольких устройствах при помощи одной копии "Мастера авторизации".

Объявление функции:

function BluetoothAuthenticateMultipleDevices(
 hwndParent : HWND;
 hRadio : THandle;
 cDevices : DWORD;
 rgpbtdi : __PBLUETOOTH_DEVICE_INFO): DWORD; stdcall; 

Параметры:

hwndParent	Handle родительского окна. Если 0, то родительским окном станет окно Desktop.
hRadio	Handle локального радиомодуля. Если 0, то авторизация будет проведена на всех радиомодулях. Если хотя бы один пройдет авторизацию, функция выполнится успешно.
cDevices	Количество элементов в массиве rgpbtdi.
rgpbtdi	Массив структур BLUETOOTH_DEVICE_INFO, в котором представлены устройства для авторизации.

Возвращаемые значения:

ERROR_SUCCESS	Функция выполнена успешно. Проверьте флаг fAuthenticated у каждого устройства, что бы знать, какие прошли авторизацию.
ERROR_CANCELLED	Пользователь отменил процесс авторизации. Проверьте флаг fAuthenticated у каждого устройства, что бы знать, какие прошли авторизацию.
ERROR_INVALID_PARAMETER	Один или несколько элементов массива rgpbtdi не верны.
ERROR_NO_MORE_ITEMS	Все устройства в массиве уже авторизированны.
Другие ошибки Win32

Важно: В оригинале функция выглядит вот так:

function BluetoothAuthenticateMultipleDevices(
 hwndParent : HWND;
 hRadio : THandle;
 cDevices : DWORD;
 pbtdi : PBLUETOOTH_DEVICE_INFO): DWORD; stdcall; 

Это не верно, так как в документации Microsoft указано, что параметр rgpbtdi должен передаваться как указатель (что подразумевает запись PBLUETOOTH_DEVICE_INFO), но как я писал выше, этот тип ошибочен. Он не является указателем. Я изменил функцию так, как показано выше. По поводу типа __PBLUETOOTH_DEVICE_INFO я писал выше.

Описывать с примером, как использовать эти функции не буду, так как они тривиальны (если вы прочитали все вышеизложенное). Остались последние три функции, которые мы не рассмотрели:

BluetoothRegisterForAuthentication - регистрирует функцию обратного вызова, которая будет вызываться на запрос устройства об авторизации. Если несколько приложений зарегистрировало такую функцию, то будет вызвана функция в последнем приложении.

Объявление функции:

function BluetoothRegisterForAuthentication(
 var pbtdi : PBLUETOOTH_DEVICE_INFO;
 var phRegHandle : HBLUETOOTH_AUTHENTICATION_REGISTRATION;
 pfnCallback : PFN_AUTHENTICATION_CALLBACK;
 pvParam : Pointer): DWORD; stdcall; 

Параметры:

pbtdi	Указатель на BLUETOOTH_DEVICE_INFO. Используется адрес устройства, для которого регистрируется функция. Обратите внимание на параметр. В оригинале он опять передается не как указатель.
phRegHandle	Указатель, куда будет возвращен Handle регистрации, которой потом используется в BluetoothUnregisterAuthentication.
pfnCallback	Функция обратного вызова.
pvParam	Опциональный параметр, который без изменения передается в функцию обратного вызова.

Возвращаемые значения:

ERROR_SUCCESS	Функция выполнена успешно.
ERROR_OUTOFMEMORY	Недостаточно памяти.
Другие ошибки Win32

BluetoothUnregisterAuthentication - удаляет функцию обратного вызова, зарегистрированную функцией BluetoothRegisterForAuthentication и закрывает Handle.

Объявление функции:

function BluetoothUnregisterAuthentication(
 hRegHandle : HBLUETOOTH_AUTHENTICATION_REGISTRATION): BOOL; stdcall; 

Параметры:

hRegHandle

Handle регистрации, полученный функцией BluetoothRegisterForAuthentication.

Возвращаемые значения:

Вернет TRUE, если вызов успешен и FALSE в случае неудачи. Используйте GetLastError для получения дополнительной информации.

BluetoothSendAuthenticationResponse - эта функция должна вызываться из функции обратного вызова при запросе авторизации удаленным устройством для передачи PIN.

Объявление функции:

function BluetoothSendAuthenticationResponse(
 hRadio : THandle;
 pbtdi : PBLUETOOTH_DEVICE_INFO;
 pszPasskey : LPWSTR): DWORD; stdcall;

Параметры:

hRadio	Handle радиомодуля, для которого проводим авторизацию. Если 0, то пытаемся на всех.
pbtdi	Указатель на BLUETOOTH_DEVICE_INFO с данными об устройстве, от которого поступил запрос на авторизацию. Может быть тот же указатель, который передан в функцию обратного вызова.
pszPasskey	Указатель на UNICODE строку, в которой содержится ключ авторизации (PIN).

Возвращаемые значения:

ERROR_SUCCESS	Функция выполнена успешно.
ERROR_CANCELLED	Устройство отвергло авторизационный код (PIN). Так же, возможно, имеются проблемы со связью
E_FAIL	Устройство вернуло ошибку авторизации.
Другие ошибки Win32

И, наконец, функция обратного вызова:

PFN_AUTHENTICATION_CALLBACK

Описание этой функции дано выше. Здесь приведу лишь определеннее.

Объявление функции:

PFN_AUTHENTICATION_CALLBACK =
 function(pvParam : Pointer;
 pDevice : PBLUETOOTH_DEVICE_INFO): BOOL; stdcall; 

Параметры:

pvParam	Указатель на параметр, который мы передали в BluetoothRegisterForAuthentication.
pDevice	Указатель на BLUETOOTH_DEVICE_INFO с данными об устройстве, от которого поступил запрос на авторизацию.

Заключение

На этот раз все. Мы рассмотрели все функции Bluetooth API от Microsoft. Также мы научились управлять устройствами и радиомодулями Bluetooth, проводить авторизацию и получать информацию об этих устройствах.

Но актуальным остается вопрос, который мне многие задают. Как же все-таки передавать данные между устройствами Bluetooth?

Ответ на этот вопрос читайте в следующей серии статей "Передача данных через Bluetooth".

Конечно, можно было бы всю эту информацию уместить в эти статьи, но объем ее не сравним с предоставленным здесь. Так что наберитесь терпения. Я постараюсь надолго не задерживать с выходом новой серии.

Я буду рад любым замечаниям и пожеланиям по данной теме.

P.S. Внимательно относитесь к сторонним библиотекам. Как видите, в JWALIB оказалось много ошибок, которые порой загоняют в тупик. Я минут 20 смотрел на Access Violation, пока не понял, в чем дело.

Внимание! Запрещается перепечатка данной статьи или ее части без согласования с автором. Если вы хотите разместить эту статью на своем сайте или издать в печатном виде, свяжитесь с автором.