This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
BlueSoleilBlueSoleilTMTM
Bluetooth API for WindowsReference Manual
Nov 1st, 2004
IVT CORPORATION
5/F, Fa Zhan PlazaNo. 12, Shang Di Xin Xi Zhong Road,
Contents1 Introduction..........................................................................................................................12 System Requirements..........................................................................................................13 Development Guide.............................................................................................................14 Data Structure Reference....................................................................................................2
1 IntroductionThis document describes APIs exported by IVT BlueSoleil™ for Windows. These APIs are available after BlueSoleil is installed on a computer with MS Windows. With these APIs, applications can perform standard Bluetooth operations, including inquiring surrounding Bluetooth devices, authenticating a remote Bluetooth device, connecting to a service on a Bluetooth device, starting/stopping a service of BlueSoleil, etc.NOTE: These APIs are tested under Microsoft Visual C++ 6.0 currently.
2 System RequirementsTo develop software based on BlueSoleil Bluetooth APIs, following hardware and software are required:
Windows 98 SE / ME / 2000 / XP BlueSoleil version 1.6.0 or above A Bluetooth radio device (Bluetooth USB dongle or CF cards) compatible with
BlueSoleil
3 Development GuideFour files are provided for developers to compile, link and run applications: a DLL file btfunc.dll, a library file btfunc.lib and two header file bt_ui.h, bt_def.h.
btfunc.dllThis is the Bluetooth APIs implementation. It is installed to Windows system directory when BlueSoleil is installed.
btfunc.lib This is the Bluetooth API function address library. It can be linked with developer’s program.
bt_ui.h This is the header file that defines constants, structures and API prototypes.
bt_def.h This is a header file that contains constants for Class of Device and other Bluetooth definitions.
IMPORTANT NOTES:1. For future upgrade, an API version is assigned to "bt_ui.h" and "btfunc.lib"
when they are formally released. The latest revision number of this document is the API version to the concomitant “bt_ui.h” and ”btfunc.lib”.
2. As new APIs may be added or API behaviors may be changed in future, it is strongly recommended that user application uses LoadLibrary(“btfunc.dll”) and GetProcAddress() to locate API addresses dynamically and calls BT_GetVersion() to make sure the installed BlueSoleil supports the APIs that user application requires; User application should always uses the “btfunc.dll” that installed to Windows system directory by BlueSoleil
installation, the “btfunc.dll” that comes along with this document is only for development convenience purpose.
3. Make sure to call BT_InitializeLibrary and get a TRUE return value before calling any other APIs except BT_IsBlueSoleilStarted, BT_IsBluetoothReady and BT_GetVersion.
4. Make sure to call BT_UninitializeLibrary to free resources before user application exits.
5. Bytes order of parameters, including Bluetooth Device Address, Bluetooth Device Class, pin code and link key, is in the order of what they are normally returned from HCI event.
6. When BlueSoleil is started/stopped, a global system event object ("Global\\BluesoleilStarted") is set/rest; and a global system event ("Global\\BluesoleilStopping") is reset/set. When Bluetooth is started/stopped, a global system event object ("Global\\BluesoleilBluetoothStarted") is set/reset. User applications can detect the running status of BlueSoleil by monitoring on these events, but it is recommended that user applications use BT_IsBlueSoleilStarted and BT_IsBluetoothReady instead. If these events are used, they must be created as manual-reset and user applications should not set/reset these events.
8. When a connection is established (by BT_ConnectService or other APIs), it may be released because user releases it from the remote device or from BlueSoleil's UI, or because Bluetooth hardware does not function. Client applications should register callbacks for appropriate events to monitor the status of connection, and re-connect to the remote device when necessary.
4 Data Structure Reference
4.1 BLUETOOTH_DEVICE_INFO
The BLUETOOTH_DEVICE_INFO structure provides information about a Bluetooth device.
Specifies which item is to be set for a desktop shortcut. This parameter can be any combination of the following values:Value MeaningDUN_SET_USER_NAME Set DUN dial up user name by szUserName.DUN_SET_PASSWORD Set DUN dial up user password by password.DUN_SET_DIAL_NUMBER Set DUN dial up number by dialNumber
If applications do not want to create a desktop shortcut, wShortcutFlags must be set to DUN_SET_NONE.
bAutoDialSpecifies whether to dial automatically without prompting the user to enter additional dial up information.
szUserNameDUN dial up user name.
passwordDUN dial up user password.
dialNumberDUN dial up number.
4.5 OPP_CLIENT_PARAM
The OPP_CLIENT_PARAM contains OPP profile connection parameters for function BT_ConnectService (with service class CLS_OBEX_OBJ_PUSH).
Specifies which command is to be executed when connected to the OPP service. This parameter can be one of the following values:Value MeaningOPP_COMMAND_PUSH Push a file to the remote deviceOPP_COMMAND_PULL Pull the owner card from the remote device
szObjectPathSpecifies the object’s full path. This parameter is ignored if wCmdFlags is OPP_COMMAND_PULL.
4.6 SYNC_CLIENT_PARAM
The SYNC_CLIENT_PARAM contains SYNC profile connection parameters for function BT_ConnectService (with service class CLS_IRMC_SYNC).
Indicates whether to show a synchronization dialog and let user control the synchronization operation. If bShowSyncDlg is FALSE, the synchronization dialog will not be shown and the object types specified by ucSyncType will be automatically be synchronized when connected to the service.
ucSyncTypeSpecifies which object type is to be synchronized when connected to the SYNC service, in case bShowSyncDlg is set to FALSE. This parameter can be any combination of the following values:
Value MeaningSYNC_VCARD vCard format objectsSYNC_VCAL vCal format objectsSYNC_VNOTE vNote format objectsSYNC_VMESSAGE vMsg format objects
4.7 GENERAL_SERVICE_INFO
The GENERAL_SERVICE_INFO structure contains information about a general service. Typically this structure is used by BT_BrowseServices and BT_SearchServices.
A NULL-terminated string specifying the name of the service.
4.8 SPPEX_SERVICE_INFO
The SPPEX_SERVICE_INFO structure contains information about an extended serial port service, which has a 128bits-GUID. This structure is used by BT_SearchSPPExService, BT_ConnectSPPExService, BT_DisconnectSPPExService, BT_StartSPPExService and BT_StopSPPExService.
RemarksThis function MUST be called and the return value MUST be TRUE before any other functions (except BT_IsBlueSoleilStarted, BT_IsBluetoothReady and BT_GetVersion.) can be called.This function checks whether BlueSoleil is started and Bluetooth is working; if not, it will try to launch BlueSoleil and wait up to 30 seconds until BlueSoleil is started and Bluetooth is working.Each successful calling to BT_InitializeLibrary must be balanced by a corresponding call to BT_UninitializeLibrary after subsequent Bluetooth function calls are finished.This function is highly recommended to be called only once for successful initialization in an application.
5.2 BT_UninitializeLibrary
This function un-initializes the context created by BT_InitializeLibrary.
void BT_UninitializeLibrary ();
ParametersNone.
Return ValuesNone.
RemarksAn application must call BT_UninitializeLibrary once for each successful call it has made to BT_InitializeLibrary.
[in] The time (in seconds) to wait before function returns if Bluetooth is not started
Return ValuesTURE if Bluetooth is started; otherwise FALSE.
RemarksNormally, Bluetooth is started when local Bluetooth device is inserted to user’s computer. Bluetooth is stopped when local Bluetooth device is removed.
5.5 BT_StartBluetooth
This function starts the Buletooth stack of BlueSoleil. Normally this function is called when the Bluetooth stack is shutdown deliberately by calling BT_StopBluetooth(), and later needs to be re-started.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_FAIL if the function fails for other reasons.
RemarksBlueSoleil automatically shutdowns it’s Bluetooth stack when it detects that Bluetooth device does not function properly.
5.6 BT_StopBluetooth
This function stops the Buletooth stack of BlueSoleil. Normally this function is called to make the Bluetooth device available for other applications.
DWORD BT_StopBluetooth(BOOL bSwitch2HidMode);
ParametersbSwitch2HidMode
[in] Specifies whether to switch Bluetooth device from HCI mode to HID mode.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksWhen BlueSoleil detects that a Bluetooth device is plug, BlueSoleil will restarts its Bluetooth stack automatically.
5.7 BT_GetLocalDeviceInfo
This function gets information about local Bluetooth radio device.
[in] Specifies what information should be output. This parameter can be any combination of the following values:Value MeaningMASK_DEVICE_NAME Get the device name.MASK_DEVICE_CLASS Get the device class.MASK_DEVICE_ADDRESS Get the device address.
MASK_LPM_VERSIONGet LPM version, manufacture number and LPM sub version.
pDevInfo[in/out] Pointer to a structure of type BLUETOOTH_DEVICE_INFO _EX .
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.8 BT_SetLocalDeviceInfo
This function gets information about local device.
[in] Specifies what information should be set. This parameter can be any combination of the following values:Value MeaningMASK_DEVICE_NAME Set the device name.MASK_DEVICE_CLASS Set the device class.
[in/out] Pointer to a structure of type BLUETOOTH_DEVICE_INFO.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.9 BT_GetRemoteDeviceInfo
This function gets information of a specified remote Bluetooth device.
[in] Specifies what information should be output. This parameter can be any combination of the following values:Value MeaningMASK_DEVICE_NAME Get the device name.MASK_DEVICE_CLASS Get the device class.MASK_PAIR_STATUS Get the pairing status with the device.MASK_CONNECT_STATUS Get the connection status with the device.
MASK_LPM_VERSION
Get LPM version, LPM sub version, and manufacture number. These values are available only when the remote device is connected.
MASK_GET_DATA_COUNT
Get the sent/received data count between local device and the remote device. This value is available only when the remote device is connected.
MASK_CLOCK_OFFSETGet clock offset of the device. This value is available only when the remote device is connected.
MASK_SIGNAL_STRENGTH Get the signal strength of the device. This
value is available only when the remote device is connected.
pDevInfo[in/out] Pointer to a structure of type BLUETOOTH_DEVICE_INFO _EX , member address must be initialized to specify the remote device.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correct.BTSTATUS_DEVICE_NOT_EXIST the specified device is not found in BlueSoleil’s database.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksIf BT_GetRemoteDeviceInfo fails to get any one of the specified items, BTSTATUS_FAIL is returned. The remote device is required to be connected with BlueSoleil for getting ucLmpVersion, wManuName, wLmpSubversion, wClockOffset, dwDataRecvBytes dwDataSentBytes and cSignalStrength.
Normally content of device name is from BlueSoleil’s history database. If device name is empty, BlueSoleil tries to get the device name from remote device.
5.10BT_SetRemoteDeviceInfo
This function adds a device’s information to BlueSoleil’s database. If the device address specified already exists, BlueSoleil modifies the corresponding information.
[in] Specifies what information should be set. This parameter can be any combination of the following values:Value MeaningMASK_DEVICE_NAME Set the device name.MASK_DEVICE_CLASS Set the device class.
MASK_CLOCK_OFFSETSet clock offset of the device, used for setting up ACL connection.
pDevInfo[in/out] Pointer to a structure of type BLUETOOTH_DEVICE_INFO _EX , member address must be initialized.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.11BT_PairDevice
This function starts pairing with a remote device.
[in] Pointer to a structure of type BLUETOOTH_DEVICE_INFO containing the record of the Bluetooth device to be paired.
wPinCodeLen[in] Specifies the length of the buffer pointed by lpPinCode. If bShowPincode is TRUE, wPinCodeLen must be greater then 0. If wPinCodeLen is 0 and BlueSoleil is not paired with the device yet, BT_PairDevice invokes BlueSoleil’s pair mechanism, prompts the user to enter a pin code, or uses the default pin code if set.
lpPinCode[in] Pointer to a buffer containing the pin code. lpPinCode can be set to NULL if wPinCodeLen is 0.
bKeepOldKeyOnFail[in] Specifies whether to keep the old stored link key (if there is any) if pairing with the device fails. If bKeepOldkeyOnFail is FALSE, Delete Stored Link Key HCI command will be issued before the pair procedure; If bKeepOldkeyOnFail is TRUE, BT_PairDevice will:
i) Search for the link key in BlueSoleil’s database;ii) If the link key can not be found in BlueSoleil’s database, issue Read Stored Link Key HCI command to retrieve the link key;iii) If the link key is successfully retrieved in step i) or ii), store it;iv) Issue Delete Stored Link Key HCI command and start the pair procedure;v) On fail of the pair procedure, if a link key is available in step iii), issue Write Stored Link Key HCI command to restore the link key.
bShowPincode[in] Specifies whether to show the pin code (specified by lpPinCode) using BlueSoleil’s GUI. If bShowPincode is TRUE, wPinCodeLen must be greater then 0.
Return ValuesBTSTATUS_SUCCESS if BlueSoleil successfully pairs with the device;BTSTATUS_ALREADY_PAIRED if BlueSoleil is already paired with the device and bKeepOldKeyOnFail is FALSE;BTSTATUS_AUTHENTICATE_FAILED if authentication fails.BTSTATUS_BT_BUSY if the remote device is connected, or Bluetooth is busy.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correct BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
Remarks
To get extended error information for BTSTATUS_FAIL, register a callback function for EVENT_ERROR. Not all failures of BTSTATUS_FAIL generate an error event.
5.12BT_UnpairDevice
This function removes the pair relationship with a remote device.
[in] Pointer to a 6-bytes buffer containing the device address.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.13BT_ConnectService
This function connects to a service on the remote device,
[in] Pointer to a structure of type BLUETOOTH_DEVICE_INFO containing the record of the Bluetooth device.
pServiceInfo[in] Pointer to a structure of type GENERAL_SERVICE_INFO containing the service information. BlueSoleil searches services specified by member dwServiceClass, if member dwServiceHandle is NULL, BlueSoleil connects to the first service if any is found, otherwise BlueSoleil connects to the service that matches dwServiceHandle.
lpParam[in,out] Pointer to a buffer containing additional connecting parameters. The structure of buffer depends on wServiceClass member of GENERAL_SERVICE_INFO pointed by pServiceInfo. Not every service class has a connecting parameter data structure, for those that do not have corresponding parameter data structures, lpParam must be set to NULL.Service Class Buffer StuctureCLS_SERIAL_PORT SPP_CLIENT_PARAM [out]CLS_DIALUP_NET DUN_CLIENT_PARAM [in]/NULL
dwConnectionHandle[out] Pointer to a variable that receives the connection handle if BT_ConnectService returns successfully. To disconnect from the service, applications should call BT_DisconnectService with this handle as the input parameter.
Return ValuesBTSTATUS_SUCCESS if BlueSoleil successfully connects to the service on the device.BTSTATUS_CONNECTION_EXIST if the connection to the service is already established.BTSTATUS_SERVICE_NOT_EXIST if the specified service can not be found or the remote device can not be connected.BTSTATUS_BT_BUSY if Bluetooth is busy with browsing services or connecting to a device.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if fails for any other reasons.
RemarksBT_ConnectService returns after the connection process is completed, during the process, connection status or other events will be notified if callback functions for these events are registered.
To get extended error information for BTSTATUS_FAIL, register a callback function for EVENT_ERROR. Not all failures of BTSTATUS_FAIL generate an error event.
CLS_DIALUP_NET:If lpParam is NULL, BlueSoleil makes the Bluetooth connection only and does not dail up. User application is responsible to do dial up operations on the COM port associated with the connection. To get the COM port associated with the connection, call BT_GetConnectInfo.
5.14BT_DisconnectService
This function disconnects from a service on a remote device.
[in] Specifies the handle of the connection output by BT_ConnectService or reported by callback.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_CONNECTION_NOT_EXIST if the connection does not exist or is released.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksFor incoming connections that are initiated by remote device, BT_DisconnectService only supports PAN profile.
5.15BT_InquireDevices
This function inquires nearby Bluetooth devices or gets paired devices from BlueSoleil’s history records.
[in] Specifies the inquiry mode:Value MeaningINQUIRY_GENERAL Inquires using general-discovery modeINQUIRY_LIMITED Inquires using limited-discovery mode
INQUIRY_PAIREDGets paired devices from history list without performing Bluetooth inquiry.
INQUIRY_GENERAL_REFRESH Inquires using general-discovery mode, clears devices in memory before performing the inquiry.
ucInqTimeLen[in] Maximum amount of time before the inquiry is halted.Range: 0x01 – 0x30Time = N * 1.28 secRange: 1.28 – 61.44 Sec.
lpDevsListLength[in,out] Pointer to a variable that specifies the length of the buffer pointed by lpDevsList, after the function returns, the variable receives the length of data copied to the buffer.If value (*lpDevsListLength) is zero, the function returns immediately after Bluetooth inquiry is started, inquiry results will be reported if callback function for EVENT_INQUIRY_DEVICE_REPORT is registered.
lpDevsList[out] Pointer to a BLUETOOTH_DEVICE_INFO array buffer that receives the device information. This parameter can be NULL if (*lpDevsListLength) is zero..
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is error.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksIf value (*lpDevsListLength) is not zero, the function is synchronous, when it returns successfully, the number of BLUETOOTH_DEVICE_INFO in the lpDevsList buffer can be calculated by expression: (*lpDevsListLength)/sizeof(BLUETOOTH_DEVICE_INFO).
If a callback function for EVENT_INQUIRY_DEVICE_REPORT is registered, inquiry results will be reported regardless of value (*lpDevsListLength).
5.16BT_CancelInquiry
This function cancels the ongoing inquiry of device and query of device names.
BTSTATUS_SUCCESS if the function succeeds.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksIf BT_InquireDevices is called in synchronous mode, calling BT_CancelInquiry from a thread separate from the one waiting for BT_InquireDevices will cancel the inquiry and make BT_InquireDevices return immediately.
5.17BT_BrowseServices
This function browses all services or searches a specified service on a remote device.
[in] Pointer to a structure of type BLUETOOTH_DEVICE_INFO containing the record of the device.
bBrowseAllServices[in] Specifies whether to browse all services supported by the device.
lpServiceClassListLength[in/out] Pointer to a variable that specifies the length (in bytes) of the buffer pointed by lpSeriveClassList, after the function returns, this variable contains the length of data copied to the buffer.
pSeriveClassList[in/out] Pointer to a GENERAL_ SERVICE_INFO array buffer that receives the services found on the device. If bBrowseAllServices is FALSE, the first element of the array specifies the service class to search, and the variable pointed by lpServiceClassListLength must not be less than 1*sizeof(GENERAL_ SERVICE_INFO).
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_SERVICE_NOT_EXIST if no service is found.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.
BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksWhen the function returns successfully, the number of class in the lpServiceClassList buffer can be calculated by expression:(*lpServiceClassListLength)/sizeof(GENERAL_ SERVICE_INFO).
To get extended error information for BTSTATUS_FAIL, register a callback function for EVENT_ERROR. Not all failures of BTSTATUS_FAIL generate an error event.
5.18BT_GetConnectInfo
This function gets the information related to a connection handle.
[in] Handle to the connection. By registering a callback function for EVENT_CONNECTION_STATUS, connection handles are reported to applications when connections are established.
lpIsOutgoing[out] Pointer to a variable that receives the value specifying the connection direction. lpIsOutgoing can NOT be NULL.
lpServiceClass[out] Pointer to a variable that receives the service class related to the connection. lpServiceClass can NOT be NULL.
lpRemoteBdAddr[out] Pointer to a 6-bytes buffer receives the remote device address related to connection. lpRemoteBdAddr can NOT be NULL.
lpConnInfoLen[in/out] Pointer to a variable that specifies the length (in bytes) of the buffer pointed by lpConnInfo, after the function returns, this variable contains the length of data copied to the buffer. lpConnInfoLen can NOT be NULL.
lpConnInfo[out] Pointer to a data buffer that receives the additional information to the connection handle. The structure of the data buffer depends on the service class related to the connection:Service Class Buffer StuctureCLS_SERIAL_PORT SPP_CONNECT_INFO(SPP_CLIENT_PARAM)CLS_DIALUP_NET SPP_CONNECT_INFO(SPP_CLIENT_PARAM)CLS_FAX SPP_CONNECT_INFO(SPP_CLIENT_PARAM)
lpConnInfo can be NULL if *lpConnInfoLen is 0.Return Values
BTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.19BT_StartSPPExService
This function starts a specific SPP service which has a 128bits-GUID.
[in/out] Pointer to a structure of type SPPEX_SERVICE_INFO, serviceClassUuid128 member must be initialized, after the function returns successfully, dwSDAPRecordHandle member contains the handle to the SDAP record of the service, ucServiceChannel member contains the service channel.
lpServerHandle[out] Pointer to a variable that receives the server handle if BT_StartSPPExService succeeds. In order to stop the service, applications should call BT_StopSPPExService taking the output lpServerHandle as an input parameter.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.
BTSTATUS_PARAMETER_ERROR if parameter(s) is error.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksTo be notified when a remote device connects to the started SPP service, register a callback function for EVENT_SPPEX_CONNECTION_STATUS.
5.20BT_StopSPPExService
This function stops a specific SPP service which has a 128bits-GUID.
[in] Handle to the service output by BT_StartSPPExService.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is error.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.21BT_SearchSPPExServices
This function searches extended SPP services which have a 128bits-GUID on a remote device..
[in] Pointer to a structure of type BLUETOOTH_DEVICE_INFO containing the record of the device.
lpServiceClassListLength[in/out] Pointer to a variable that specifies the length (in bytes) of the buffer pointed by lpSeriveClassList, and must be greater than 1*sizeof(SPPEX_ SERVICE_INFO). After the function returns, this variable contains the length of data copied to the buffer.
pSeriveClassList[in/out] lpSeriveClassList is a pointer to a SPPEX_ SERVICE_INFO array buffer that receives the services found on the device. The array must have at least one element and the first element specifies the 128bits-GUID to search.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_SERVICE_NOT_EXIST if the service is not found.BTSTATUS_PARAMETER_ERROR if parameter(s) is error.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksWhen the function returns successfully, the number of class in the lpServiceClassList buffer can be calculated by expression:(*lpServiceClassListLength)/sizeof(SPPEX_ SERVICE_INFO).
To get extended error information for BTSTATUS_FAIL, Register a callback function for EVENT_ERROR. Not all failures of BTSTATUS_FAIL generate an error event
5.22BT_ConnectSPPExService
This function connects to a RFCOMM-based service with 128bits-GUID on a remote device.
pServiceInfo[in/out] Pointer to a structure of type SPPEX_SERVICE_INFO, serviceClassUuid128 member must be initialized. BlueSoleil connects to the first service if any is found. After the function returns successfully, dwSDAPRecordHandle member contains the handle to the SDAP record of the service, szServiceName member contains the name of the service, ucServiceChannel member contains the service channel, ucComIndex contains the COM port number associated with the connection.
lpConnectionHandle[out] Pointer to a variable that receives the connection handle if BT_ConnectSPPExService succeeds. To disconnect from the service, call BT_DisconnectSPPExService with the output lpConnectionHandle as an input parameter.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksTo get extended error information for BTSTATUS_FAIL, Register a callback function for EVENT_ERROR. Not all failures of BTSTATUS_FAIL generate an error event.
5.23BT_DisconnectSPPExService
This function disconnects from a specific SPP service which has a 128bits-GUID.
[in] The connection handle output by BT_ConnectSPPExService.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_CONNECTION_NOT_EXIST if the connection does not exist or is released.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.
lpBdAddr[in] Pointer to a 6-bytes buffer containing the address of the remote device associated with the connection.
ucStatus[in] Indicates the current connection status:
Value MeaningSTATUS_INCOMING_CONNECT An incoming connection is established.STATUS_INCOMING_DISCONNECT An incoming connection is released.STATUS_OUTCOMING_CONNECT An outgoing connection is established.STATUS_OUTCOMING_DISCONNECT An outgoing connection is released.
pDevInfo[in] Pointer to a structure of type BLUETOOTH_DEVICE_INFO containing the record of the device. Content of member szName is from BlueSoleil’s history database. If member address and classOfDevice contain all zeros, it indicates that the inquiry completes, though BlueSoleil may continue to query device names.
RemarksA device with the same device address may be reported more than one 1 time, client applications are expected to filter duplicated devices.
[in] The handle to the specific SPP service. By comparing to the handle returned by BT_StartSPPExService, dwServerHandle can be used to retrieve related service information, e.g. COM port associated to the service.
lpBdAddr[in] Pointer to a 6-bytes buffer containing the address of the remote device associated with the connection. The address is invalid if ucStatus is STATUS_INCOMING_DISCONNECT.
ucStatus[in] Connection status:
Value MeaningSTATUS_INCOMING_CONNECT An incoming connection is established.STATUS_INCOMING_DISCONNECT An incoming connection is released.
ucStatus[in] Indicates the current status of Bluetooth, this parameter is one of the following value:
Value MeaningSTATUS_BLUETOOTH_STARTED Bluetooth is started.STATUS_BLUETOOTH_STOPED Bluetooth is stoped.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_FAIL if the function fails for other reasons.
RemarksIf BlueSoleil exits, all registered events will be discarded, the associated callbacks will not work after BlueSoleil is restarted. To keep callbacks working, an application must call BT_UninitializeLibrary when it detects BlueSoleil exits, and call BT_InitializeLibrary and BT_RegisterCallback again after BlueSoleil is restarted.
It is recommended that, the Bluetooth APIs defined in this document should not be called in the users’ callback functions registered by BT_RegisterCallback to prevent any potential deadlock in codes.
5.25BT_UnregisterCallback
This function un-registers an application-defined callback function for a Bluetooth event.
[in] Specifies which event applications want to remove from previous register by BT_RegisterCallback.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_FAIL if the function fails for other reasons.
RemarksNone.
5.26BT_GetVersion
This function returns the version number of current API series.
DWORD BT_GetVersion();
ParametersNone.
Return ValuesA DWORD value that contains the major and minor version numbers of the current API series.
RemarksThe low order word contains the version number of the current API series. The low-order byte of this word specifies the major version number. The high-order byte specifies the minor version (revision) number.
Pointer to a variable that receives t version number.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_FAIL if the function fails for other reasons.
RemarksIf this function returns successfully, the low order word of (*lpBtSpecVersion) contains the version number. The low-order byte of this word specifies the major version number. The high-order byte specifies the minor version number.
5.28BT_EnumConnections
This function enumerates all active connections in BlueSoleil.
[in/out] Pointer to a variable containing the size (in bytes) of the buffer pointed to by pBuffer. On return, the variable receives the length of data copied to the buffer.
lpBuffer[out] Pointer to a GENERAL_CONNECT_INFO array buffer that receives the active connection information.
Return ValuesBTSTATUS_SUCCESS if the function succeeds.
BTSTATUS_PARAMETER_ERROR if parameter(s) is (/are) not correctBTSTATUS_SYSTEM_ERROR if system error(s) occurs.BTSTATUS_BT_NOT_READY if Bluetooth is not started.BTSTATUS_FAIL if the function fails for other reasons.
RemarksWhen the function returns successfully, the number of handles in the lpBuffer buffer can be calculated by expression:(*lpBufferLen)/sizeof(GENERAL_CONNECT_INFO).
To get extended information for a connection handle, call BT_GetConnectInfo.