26. Network Protocols — Bluetooth¶
26.1. EFI Bluetooth Host Controller Protocol¶
26.1.1. EFI_BLUETOOTH_HC_PROTOCOL¶
Summary
This protocol abstracts the Bluetooth host controller layer.message transmit and receive.
GUID
#define EFI_BLUETOOTH_HC_PROTOCOL_GUID \
{ 0xb3930571, 0xbeba, 0x4fc5,
{ 0x92, 0x3, 0x94, 0x27, 0x24, 0x2e, 0x6a, 0x43 }}
Protocol Interface Structure
typedef struct _EFI_BLUETOOTH_HC_PROTOCOL {
EFI_BLUETOOTH_HC_SEND_COMMAND SendCommand;
EFI_BLUETOOTH_HC_RECEIVE_EVENT ReceiveEvent;
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT AsyncReceiveEvent;
EFI_BLUETOOTH_HC_SEND_ACL_DATA SendACLData;
EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA ReceiveACLData;
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA AsyncReceiveACLData;
EFI_BLUETOOTH_HC_SEND_SCO_DATA SendSCOData;
EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA ReceiveSCOData;
EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA AsyncReceiveSCOData;
} EFI_BLUETOOTH_HC_PROTOCOL;
Parameters
- SendCommand
Send HCI command packet. See the SendCommand() function description.
- ReceiveEvent
Receive HCI event packets. See the ReceiveEvent() function description.
- AsyncReceiveEvent
Non-blocking receive HCI event packets. See the AsyncReceiveEvent() function description.
- SendACLData
Send HCI ACL (asynchronous connection-oriented) data packets. See the SendACLData() function description.
- ReceiveACLData
Receive HCI ACL data packets. See the ReceiveACLData() function description.
- AsyncReceiveACLData
Non-blocking receive HCI ACL data packets. See the AsyncReceiveACLData() function description.
- SendSCOData
Send HCI synchronous (SCO and eSCO) data packets. See the SendSCOData() function description.
- ReceiveSCOData
Receive HCI synchronous data packets. See the ReceiveSCOData() function description.
- AsyncReceiveSCOData
Non-blocking receive HCI synchronous data packets. See the AsyncReceiveSCOData() function description.
Description
The EFI_BLUETOOTH_HC_PROTOCOL is used to transmit or receive HCI layer data packets. For detail of different HCI packet (command, event, ACL, SCO), please refer to Bluetooth specification.
26.1.2. BLUETOOTH_HC_PROTOCOL.SendCommand()¶
Summary
Send HCI command packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_COMMAND)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
IN VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be transmitted to Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The SendCommand() function sends HCI command packet. Buffer holds the whole HCI command packet, including OpCode, OCF, OGF, parameter length, and parameters. When this function is returned, it just means the HCI command packet is sent, it does not mean the command is success or complete. Caller might need to wait a command status event to know the command status, or wait a command complete event to know if the command is completed. (see in Bluetooth specification, HCI Command Packet for more detail).
Status Codes Returned
EFI_SUCCESS |
The HCI command packet is sent successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
BufferSize is NULL.
* BufferSize is 0.
Buffer is NULL.
|
EFI_TIMEOUT |
Sending HCI command packet fail due to timeout. |
EFI_DEVICE_ERROR |
Sending HCI command packet fail due to host controller or device error. |
26.1.3. BLUETOOTH_HC_PROTOCOL.ReceiveEvent()¶
Summary
Receive HCI event packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_EVENT)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
OUT VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be received from Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The ReceiveEvent() function receives HCI event packet. Buffer holds the whole HCI event packet, including EventCode, parameter length, and parameters. (See in Bluetooth specification, HCI Event Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI event packet is received successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Receiving HCI event packet fail due to timeout. |
EFI_DEVICE_ERROR |
Receiving HCI event packet fail due to host controller or device error. |
26.1.4. BLUETOOTH_HC_PROTOCOL.AsyncReceiveEvent()¶
Summary
Receive HCI event packet in non-blocking way.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_EVENT) (
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN BOOLEAN IsNewTransfer,
IN UINTN PollingInterval,
IN UINTN DataLength,
IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- IsNewTransfer
If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
- PollingInterval
Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- DataLength
Specifies the length, in bytes, of the data to be received.
- Callback
The callback function. This function is called if the asynchronous transfer is completed.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The AsyncReceiveEvent() function receives HCI event packet in non-blocking way. Data in Callback function holds the whole HCI event packet, including EventCode, parameter length, and parameters. (See in Bluetooth specification, HCI Event Packet for more detail.)
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK) (
IN VOID *Data,
IN UINTN DataLength,
IN VOID *Context
);
- Data
Data received via asynchronous transfer.
- DataLength
The length of Data in bytes, received via asynchronous transfer.
- Context
Context passed from asynchronous transfer request.
Status Codes Returned
EFI_SUCCESS |
The HCI asynchronous receive request is submitted successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataLength is 0.
• If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
|
26.1.5. BLUETOOTH_HC_PROTOCOL.SendACLData()¶
Summary
Send HCI ACL data packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_ACL_DATA)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
IN VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be transmitted to Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The SendACLData() function sends HCI ACL data packet. Buffer holds the whole HCI ACL data packet, including Handle, PB flag, BC flag, data length, and data. (See in Bluetooth specification, HCI ACL Data Packet for more detail.)
The SendACLData() function and ReceiveACLData() function just send and receive data payload from application layer. In order to protect the payload data, the Bluetooth bus is required to call HCI_Set_Connection_Encryption command to enable hardware based encryption after authentication completed, according to pairing mode and host capability.
Status Codes Returned
EFI_SUCCESS |
The HCI ACL data packet is sent successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Sending HCI ACL data packet fail due to timeout. |
EFI_DEVICE_ERROR |
Sending HCI ACL data packet fail due to host controller or device error. |
26.1.6. BLUETOOTH_HC_PROTOCOL.ReceiveACLData()¶
Summary
Receive HCI ACL data packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_ACL_DATA)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
OUT VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be received from Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The ReceiveACLData() function receives HCI ACL data packet. Buffer holds the whole HCI ACL data packet, including Handle, PB flag, BC flag, data length, and data. (See in Bluetooth specification, HCI ACL Data Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI ACL data packet is received successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Receiving HCI ACL data packet fail due to timeout. |
EFI_DEVICE_ERROR |
Receiving HCI ACL data packet fail due to host controller or device error. |
26.1.7. BLUETOOTH_HC_PROTOCOL.AsyncReceiveACLData()¶
Summary
Receive HCI ACL data packet in non-blocking way.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_ACL_DATA) (
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN BOOLEAN IsNewTransfer,
IN UINTN PollingInterval,
IN UINTN DataLength,
IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- IsNewTransfer
- If TRUE, a new transfer will be submitted.If FALSE, the request is deleted.
- PollingInterval
Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- DataLength
Specifies the length, in bytes, of the data to be received.
- Callback
The callback function. This function is called if the asynchronous transfer is completed.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The AsyncReceiveACLData() function receives HCI ACL data packet in non-blocking way. Data in Callback holds the whole HCI ACL data packet, including Handle, PB flag, BC flag, data length, and data. (See in Bluetooth specification, HCI ACL Data Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI asynchronous receive request is submitted successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataLength is 0.
• If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
|
26.1.8. BLUETOOTH_HC_PROTOCOL.SendSCOData()¶
Summary
Send HCI SCO data packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_SEND_SCO_DATA)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
IN VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be transmitted to Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The SendSCOData() function sends HCI SCO data packet. Buffer holds the whole HCI SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data. (See in Bluetooth specification, HCI Synchronous Data Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI SCO data packet is sent successfully. |
EFI_UNSUPPORTED |
The implementation does not support HCI SCO transfer. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Sending HCI SCO data packet fail due to timeout. |
EFI_DEVICE_ERROR |
Sending HCI SCO data packet fail due to host controller or device error. |
26.1.9. BLUETOOTH_HC_PROTOCOL.ReceiveSCOData()¶
Summary
Receive HCI SCO data packet.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_RECEIVE_SCO_DATA)(
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN OUT UINTN *BufferSize,
OUT VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be received from Bluetooth host controller.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The ReceiveSCOData() function receives HCI SCO data packet. Buffer holds the whole HCI SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data. (See in Bluetooth specification, HCI Synchronous Data Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI SCO data packet is received successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Receiving HCI SCO data packet fail due to timeout. |
EFI_DEVICE_ERROR |
Receiving HCI SCO data packet fail due to host controller or device error. |
26.1.10. BLUETOOTH_HC_PROTOCOL.AsyncReceiveSCOData()¶
Summary
Receive HCI SCO data packet in non-blocking way.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_HC_ASYNC_RECEIVE_SCO_DATA) (
IN EFI_BLUETOOTH_HC_PROTOCOL *This,
IN BOOLEAN IsNewTransfer,
IN UINTN PollingInterval,
IN UINTN DataLength,
IN EFI_BLUETOOTH_HC_ASYNC_FUNC_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_HC_PROTOCOL instance.
- IsNewTransfer
If TRUE, a new transfer will be submitted. If FALSE, the request is deleted.
- PollingInterval
Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- DataLength
Specifies the length, in bytes, of the data to be received.
- Callback
The callback function. This function is called if the asynchronous transfer is completed.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The AsyncReceiveSCOData() function receives HCI SCO data packet in non-blocking way. Data in Callback holds the whole HCI SCO data packet, including ConnectionHandle, PacketStatus flag, data length, and data. (See in Bluetooth specification, HCI SCO Data Packet for more detail.)
Status Codes Returned
EFI_SUCCESS |
The HCI asynchronous receive request is submitted successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataLength is 0.
• If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
|
26.2. EFI Bluetooth Bus Protocol¶
26.2.1. EFI_BLUETOOTH_IO_SERVICE_BINDING_PROTOCOL¶
Summary
The EFI Bluetooth IO Service Binding Protocol is used to locate EFI Bluetooth IO Protocol drivers to create and destroy child of the driver to communicate with other Bluetooth device by using Bluetooth IO protocol.
GUID
#define EFI_BLUETOOTH_IO_SERVICE_BINDING_PROTOCOL_GUID \
{ 0x388278d3, 0x7b85, 0x42f0,\
{ 0xab, 0xa9, 0xfb, 0x4b, 0xfd, 0x69, 0xf5, 0xab }
Description
The Bluetooth IO consumer need locate EFI_BLUETOOTH_IO_SERVICE_BINDING_PROTOCOL and call CreateChild() to create a new child of EFI_BLUETOOTH_IO_PROTOCOL instance. Then use EFI_BLUETOOTH_IO_PROTOCOL for Bluetooth communication. After use, the Bluetooth IO consumer need call DestroyChild() to destroy it.
26.2.2. EFI_BLUETOOTH_IO_PROTOCOL¶
Summary
This protocol provides service for Bluetooth L2CAP (Logical Link Control and Adaptation Protocol) and SDP (Service Discovery Protocol).
GUID
#define EFI_BLUETOOTH_IO_PROTOCOL_GUID \
{ 0x467313de, 0x4e30, 0x43f1,\
{ 0x94, 0x3e, 0x32, 0x3f, 0x89, 0x84, 0x5d, 0xb5 }}
Protocol Interface Structure
typedef struct _EFI_BLUETOOTH_IO_PROTOCOL {
EFI_BLUETOOTH_IO_GET_DEVICE_INFO GetDeviceInfo;
EFI_BLUETOOTH_IO_GET_SDP_INFO GetSdpInfo;
EFI_BLUETOOTH_IO_L2CAP_RAW_SEND L2CapRawSend;
EFI_BLUETOOTH_IO_L2CAP_RAW_RECEIVE L2CapRawReceive;
EFI_BLUETOOTH_IO_L2CAP_RAW_ASYNC_RECEIVE\ L2CapRawAsyncReceive;
EFI_BLUETOOTH_IO_L2CAP_SEND L2CapSend;
EFI_BLUETOOTH_IO_L2CAP_RECEIVE L2CapReceive;
EFI_BLUETOOTH_IO_L2CAP_ASYNC_RECEIVE L2CapAsyncReceive;
EFI_BLUETOOTH_IO_L2CAP_CONNECT L2CapConnect;
EFI_BLUETOOTH_IO_L2CAP_DISCONNECT L2CapDisconnect;
EFI_BLUETOOTH_IO_L2CAP_REGISTER_SERVICE\ L2CapRegisterService;
}
EFI_BLUETOOTH_IO_PROTOCOL;
Parameters
- GetDeviceInfo
Get Bluetooth device Information. See theGetDeviceInfo()* function description.
- GetSdpInfo
Get Bluetooth device SDP information. See the GetSdpInfo() function description.
- L2CapRawSend
Send L2CAP message (including L2CAP header). See the L2CapRawSend() function description.
- L2CapRawReceive
Receive L2CAP message (including L2CAP header). See the L2CapRawReceive() function description.
- L2CapRawAsyncReceive
Non-blocking receive L2CAP message (including L2CAP header). See the L2CapRawAsyncReceive() function description.
- L2CapSend
Send L2CAP message (excluding L2CAP header) to a specific channel. See the L2CapSend() function description.
- L2CapReceive
Receive L2CAP message (excluding L2CAP header) from a specific channel. See the L2CapRawReceive() function description.
- L2CapAsyncReceive
Non-blocking receive L2CAP message (excluding L2CAP header) from a specific channel. See the L2CapRawAsyncReceive() function description.
- L2CapConnect
Do L2CAP connection. See the L2CapConnect() function description.
- L2CapDisconnect
Do L2CAP disconnection. See the L2CapDisconnect() function description.
- L2CapRegisterService
Register L2CAP callback function for special channel. See the L2CapRegisterService() function description.
Description
The EFI_BLUETOOTH_IO_PROTOCOL provides services in L2CAP protocol and SDP protocol. For detail of L2CAP packet format, and SDP service, please refer to Bluetooth specification.
26.2.3. BLUETOOTH_IO_PROTOCOL.GetDeviceInfo¶
Summary
Get Bluetooth device information.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_GET_DEVICE_INFO)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
OUT UINTN *DeviceInfoSize,
OUT VOID **DeviceInfo
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- DeviceInfoSize
A pointer to the size, in bytes, of the DeviceInfo buffer.
- DeviceInfo
A pointer to a callee allocated buffer that returns Bluetooth device information. Callee allocates this buffer by using EFI Boot Service AllocatePool().
Description
The GetDeviceInfo() function returns Bluetooth device information. The size of DeviceInfo structure should never be assumed and the value of DeviceInfoSize is the only valid way to know the size of DeviceInfo.
Related Definitions
typedef struct {
UINT32 Version;
BLUETOOTH_ADDRESS BD_ADDR;
UINT8 PageScanRepetitionMode;
BLUETOOTH_CLASS_OF_DEVICE ClassOfDevice;
UINT16 ClockOffset;
UINT8 RSSI;
UINT8 ExtendedInquiryResponse [240];
} EFI_BLUETOOTH_DEVICE_INFO;
- Version
The version of the structure. A value of zero represents the EFI_BLUETOOTH_DEVICE_INFO structure as defined here. Future version of this specification may extend this data structure in a backward compatible way and increase the value of Version.
- BD_ADDR
48bit Bluetooth device address.
- PageScanRepetitionMode*
Bluetooth PageScanRepetitionMode. See Bluetooth specification for detail.
- ClassOfDevice
Bluetooth ClassOfDevice. See Bluetooth specification for detail.
- ClockOffset
Bluetooth CloseOffset. See Bluetooth specification for detail.
- RSSI
Bluetooth RSSI. See Bluetooth specification for detail.
- ExtendedInquiryResponse
Bluetooth ExtendedInquiryResponse. See Bluetooth specification for detail.
typedef struct {
UINT8 Address [6];
} BLUETOOTH_ADDRESS;
typedef struct {
UINT8 FormatType:2;
UINT8 MinorDeviceClass:6;
UINT16 MajorDeviceClass:5;
UINT16 MajorServiceClass:11;
} BLUETOOTH_CLASS_OF_DEVICE;
Status Codes Returned
EFI_SUCCESS |
The Bluetooth device information is returned successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to retrieve the Bluetooth device information. |
26.2.4. BLUETOOTH_IO_PROTOCOL.GetSdpInfo¶
Summary
Get Bluetooth SDP information.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_GET_SDP_INFO)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
OUT UINTN *SdpInfoSize,
OUT VOID **SdpInfo
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- SdpInfoSize
A pointer to the size, in bytes, of the SdpInfo buffer.
- SdpInfo
A pointer to a callee allocated buffer that returns Bluetooth SDP information. Callee allocates this buffer by using EFI Boot Service AllocatePool().
Description
The GetSdpInfo() function returns Bluetooth SDP information. The size of SdpInfo structure should never be assumed and the value of SdpInfoSize is the only valid way to know the size of SdpInfo.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth SDP information is returned successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to retrieve the Bluetooth SDP information. |
26.2.5. BLUETOOTH_IO_PROTOCOL.L2CapRawSend¶
Summary
Send L2CAP message (including L2CAP header).
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_SEND)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN OUT UINTN *BufferSize,
IN VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
EFI iSCSI Initiator Name Protocol sends L2CAP layer message (including L2CAP header). Buffer holds the whole L2CAP message, including Length, ChannelID, and information payload. (See the Bluetooth specification, L2CAP Data Packet Format for more details.)
Status Codes Returned
EFI_SUCCESS |
The L2CAP message is sent successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Sending L2CAP message fail due to timeout. |
EFI_DEVICE_ERROR |
Sending L2CAP message fail due to host controller or device error. |
26.2.6. BLUETOOTH_IO_PROTOCOL.L2CapRawReceive¶
Summary
Receive L2CAP message (including L2CAP header).
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_RECEIVE)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN OUT UINTN *BufferSize,
OUT VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be received from Bluetooth L2CAP layer.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The L2CapRawReceive() function receives L2CAP layer message (including L2CAP header). Buffer holds the whole L2CAP message, including Length, ChannelID, and information payload. (See in Bluetooth specification, L2CAP Data Packet Format for more detail.)
Status Codes Returned
EFI_SUCCESS |
The L2CAP message is received successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Receiving L2CAP message fail due to timeout. |
EFI_DEVICE_ERROR |
Receiving L2CAP message fail due to host controller or device error. |
26.2.7. BLUETOOTH_IO_PROTOCOL.L2CapRawAsyncReceive¶
Summary
Receive L2CAP message (including L2CAP header) in non-blocking way.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RAW_ASYNC_RECEIVE)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN BOOLEAN IsNewTransfer,
IN UINTN PollingInterval,
IN UINTN DataLength,
IN EFI_BLUETOOTH_IO_ASYNC_FUNC_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- IsNewTransfer
- If TRUE, a new transfer will be submitted.If FALSE, the request is deleted.
- PollingInterval
Indicates the periodic rate, in milliseconds, that the transfer is to be executed.
- DataLength
Specifies the length, in bytes, of the data to be received.
- Callback
The callback function. This function is called if the asynchronous transfer is completed.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The L2CapRawAsyncReceive() function receives L2CAP layer message (including L2CAP header) in non-blocking way. Data in Callback function holds the whole L2CAP message, including Length, ChannelID, and information payload. (See in Bluetooth specification, L2CAP Data Packet Format for more detail.)
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_ASYNC_FUNC_CALLBACK) (
IN UINT16 ChannelID,
IN VOID *Data,
IN UINTN DataLength,
IN VOID *Context
);
- ChannelID
Bluetooth L2CAP message channel ID.
- Data
Data received via asynchronous transfer.
- DataLength
The length of Data in bytes, received via asynchronous transfer.
- Context
Context passed from asynchronous transfer request.
Status Codes Returned
EFI_SUCCESS |
The L2CAP asynchronous receive request is submitted successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataLength is 0.
• If IsNewTransfer is TRUE, and an asynchronous receive request already exists.
|
26.2.8. BLUETOOTH_IO_PROTOCOL.L2CapSend¶
Summary
Send L2CAP message (excluding L2CAP header) to a specific channel.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_SEND)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN EFI_HANDLE Handle,
IN OUT UINTN *BufferSize,
IN VOID *Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- Handle
A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to send.
- BufferSize
On input, indicates the size, in bytes, of the data buffer specified by Buffer. On output, indicates the amount of data actually transferred.
- Buffer
A pointer to the buffer of data that will be transmitted to Bluetooth L2CAP layer.
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The L2CapSend() function sends L2CAP layer message (excluding L2CAP header) to Bluetooth channel indicated by Handle. Buffer only holds information payload. (See in Bluetooth specification, L2CAP Data Packet Format for more detail.)
Status Codes Returned
EFI_SUCCESS |
The L2CAP message is sent successfully. |
EFI_NOT_FOUND |
Handle is invalid or not found. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Sending L2CAP message fail due to timeout. |
EFI_DEVICE_ERROR |
Sending L2CAP message fail due to host controller or device error. |
26.2.9. BLUETOOTH_IO_PROTOCOL.L2CapReceive¶
Summary
Receive L2CAP message (excluding L2CAP header) from a specific channel.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_RECEIVE)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN EFI_HANDLE Handle,
OUT UINTN *BufferSize,
OUT VOID **Buffer,
IN UINTN Timeout
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- Handle
A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive.
- BufferSize
Indicates the size, in bytes, of the data buffer specified by Buffer.
- Buffer
A pointer to the buffer of data that will be received from Bluetooth L2CAP layer. Callee allocates this buffer by using EFI Boot Service AllocatePool().
- Timeout
Indicating the transfer should be completed within this time frame. The units are in milliseconds. If Timeout is 0, then the caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
Description
The L2CapReceive() function receives L2CAP layer message (excluding L2CAP header) from Bluetooth channel indicated by Handle. Buffer only holds information payload. (See in Bluetooth specification, L2CAP Data Packet Format for more detail.)
Status Codes Returned
EFI_SUCCESS |
The L2CAP message is received successfully. |
EFI_NOT_FOUND |
Handle is invalid or not found. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• BufferSize is NULL.
• * BufferSize is 0.
• Buffer is NULL.
|
EFI_TIMEOUT |
Receiving L2CAP message fail due to timeout. |
EFI_DEVICE_ERROR |
Receiving L2CAP message fail due to host controller or device error. |
26.2.10. BLUETOOTH_IO_PROTOCOL.L2CapAsyncReceive¶
Summary
Receive L2CAP message (including L2CAP header) in non-blocking way from a specific channel.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_ASYNC_RECEIVE)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN EFI_HANDLE Handle,
IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback,
IN VOID *Context
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- Handle
A handle created by EFI_BLUETOOTH_IO_PROTOCOL.L2CapConnect indicates which channel to receive.
- Callback
The callback function. This function is called if the asynchronous transfer is completed.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The L2CapAsyncReceive() function receives L2CAP layer message (excluding L2CAP header) in non-blocking way from Bluetooth channel indicated by Handle. Data in Callback function only holds information payload. (See in Bluetooth specification, L2CAP Data Packet Format for more detail.)
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK) (
IN VOID *Data,
IN UINTN DataLength,
IN VOID *Context
);
- Data
Data received via asynchronous transfer.
- DataLength
The length of Data in bytes, received via asynchronous transfer.
- Context
Context passed from asynchronous transfer request.
Status Codes Returned
EFI_SUCCESS |
The L2CAP asynchronous receive request is submitted successfully. |
EFI_NOT_FOUND |
Handle is invalid or not found. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataLength is 0.
• If an asynchronous receive request already exists on same Handle.
|
26.2.11. BLUETOOTH_IO_PROTOCOL.L2CapConnect¶
Summary
Do L2CAP connection.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_CONNECT)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
OUT EFI_HANDLE *Handle,
IN UINT16 Psm,
IN UINT16 Mtu,
IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- Handle
A handle to indicate this L2CAP connection.
- Psm
Bluetooth PSM. See Bluetooth specification for detail.
- Mtu
Bluetooth MTU. See Bluetooth specification for detail.
- Callback
The callback function. This function is called whenever there is message received in this channel.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The L2CapConnect() function does all necessary steps for Bluetooth L2CAP layer connection in blocking way. It might take long time. Once this function is returned Handle is created to indicate the connection.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth L2CAP layer connection is created successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• Handle is NULL.
|
EFI_DEVICE_ERROR |
A hardware error occurred trying to do Bluetooth L2CAP connection. |
26.2.12. BLUETOOTH_IO_PROTOCOL.L2CapDisconnect¶
Summary
Do L2CAP disconnection.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_DISCONNECT)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
IN EFI_HANDLE Handle
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
- Handle
A handle to indicate this L2CAP connection.
Description
The L2CapDisconnect() function does all necessary steps for Bluetooth L2CAP layer disconnection in blocking way. It might take long time. Once this function is returned Handle is no longer valid.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth L2CAP layer disconnection is created successfully. |
EFI_NOT_FOUND |
Handle is invalid or not found. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to do Bluetooth L2CAP disconnection. |
26.2.13. BLUETOOTH_IO_PROTOCOL.L2CapRegisterService¶
Summary
Register L2CAP callback function for special channel.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_IO_L2CAP_REGISTER_SERVICE)(
IN EFI_BLUETOOTH_IO_PROTOCOL *This,
OUT EFI_HANDLE *Handle,
IN UINT16 Psm,
IN UINT16 Mtu,
IN EFI_BLUETOOTH_IO_CHANNEL_SERVICE_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_IO_PROTOCOL instance.
Handle
- Psm
Bluetooth PSM. See Bluetooth specification for detail.
- Mtu
Bluetooth MTU. See Bluetooth specification for detail.
- Callback
The callback function. This function is called whenever there is message received in this channel. NULL means unregister.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The L2CapRegisterService() function registers L2CAP callback function for a special channel. Once this function is returned Handle is created to indicate the connection.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth L2CAP callback function is registered successfully. |
EFI_ALREADY_STARTED |
The callback function already exists when register. |
EFI_NOT_FOUND |
The callback function does not exist when unregister. |
26.3. EFI Bluetooth Configuration Protocol¶
26.3.1. EFI_BLUETOOTH_CONFIG_PROTOCOL¶
Summary
This protocol abstracts user interface configuration for Bluetooth device.
GUID
#define EFI_BLUETOOTH_CONFIG_PROTOCOL_GUID \
{ 0x62960cf3, 0x40ff, 0x4263,\
{ 0xa7, 0x7c, 0xdf, 0xde, 0xbd, 0x19, 0x1b, 0x4b }}
Protocol Interface Structure
typedef struct _EFI_BLUETOOTH_CONFIG_PROTOCOL {
EFI_BLUETOOTH_CONFIG_INIT Init;
EFI_BLUETOOTH_CONFIG_SCAN Scan;
EFI_BLUETOOTH_CONFIG_CONNECT Connect;
EFI_BLUETOOTH_CONFIG_DISCONNECT Disconnect;
EFI_BLUETOOTH_CONFIG_GET_DATA GetData;
EFI_BLUETOOTH_CONFIG_SET_DATA SetData;
EFI_BLUETOOTH_CONFIG_GET_REMOTE_DATA GetRemoteData;
EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK RegisterPinCallback;
EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK RegisterGetLinkKeyCallback;
EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK RegisterSetLinkKeyCallback;
EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK RegisterLinkConnectCompleteCallback;
} EFI_BLUETOOTH_CONFIG_PROTOCOL;
Parameters
- Init
Initialize Bluetooth host controller and local device. See the Init() function description.
- Scan
Scan Bluetooth device. See the Scan() function description.
- Connect
Connect one Bluetooth device. See the Connect() function description.
- Disconnect
Disconnect one Bluetooth device. See the Disconnect() function description.
- GetData
Get Bluetooth configuration data. See the GetData() function description.
- SetData
Set Bluetooth configuration data. See the SetData() function description.
- GetRemoteData
Get remote Bluetooth device data. See the GetRemoteData() function description.
- RegisterPinCallback
Register PIN callback function. See the RegisterPinCallback() function description.
- RegisterGetLinkKeyCallback
Register get link key callback function. See the RegisterGetLinkKeyCallback() function description.
- RegisterSetLinkKeyCallback
Register set link key callback function. See the RegisterSetLinkKeyCallback() function description.
- RegisterLinkConnectCompleteCallback
Register link connect complete callback function. See the RegisterLinkConnectCompleteCallback() function description.
Description
The EFI_BLUETOOTH_CONFIG_PROTOCOL abstracts the Bluetooth configuration. User can use Bluetooth configuration to interactive with Bluetooth bus driver.
26.3.2. BLUETOOTH_CONFIG_PROTOCOL.Init¶
Summary
Initialize Bluetooth host controller and local device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_INIT)(
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
Description
The Init() function initializes Bluetooth host controller and local device.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth host controller and local device is initialized successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to initialize the Bluetooth host controller and local device. |
26.3.3. BLUETOOTH_CONFIG_PROTOCOL.Scan¶
Summary
Scan Bluetooth device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_SCAN)(
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN BOOLEAN ReScan,
IN UINT8 ScanType,
IN EFI_BLUETOOTH_CONFIG_SCAN_CALLBACK_FUNCTION Callback
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- ReScan
If TRUE, a new scan request is submitted no matter there is scan result before. If FALSE and there is scan result, the previous scan result is returned and no scan request is submitted.
- ScanType
Bluetooth scan type, Inquiry and/or Page. See Bluetooth specification for detail.
- Callback
The callback function. This function is called if a Bluetooth device is found during scan process.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The Scan() function scans Bluetooth device. When this function is returned, it just means scan request is submitted. It does not mean scan process is started or finished. Whenever there is a Bluetooth device is found, the Callback function will be called. Callback function might be called before this function returns or after this function returns.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_SCAN_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN EFI_BLUETOOTH_SCAN_CALLBACK_INFORMATION *CallbackInfo
);
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Context
Context passed from scan request.
- CallbackInfo
Data related to scan result. NULL CallbackInfo means scan complete.
typedef
typedef struct{
BLUETOOTH_ADDRESS BDAddr;
UINT8 RemoteDeviceState;
BLUETOOTH_CLASS_OF_DEVICE ClassOfDevice;
UINT8 RemoteDeviceName[BLUETOOTH_HCI_COMMAND_LOCAL_READABLE_NAME_MAX_SIZE];
} EFI_BLUETOOTH_SCAN_CALLBACK_INFORMATION;
#define BLUETOOTH_HCI_COMMAND_LOCAL_READABLE_NAME_MAX_SIZE 248
Status Codes Returned
EFI_SUCCESS |
The Bluetooth scan request is submitted. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to scan the Bluetooth device. |
26.3.4. BLUETOOTH_CONFIG_PROTOCOL.Connect¶
Summary
Connect a Bluetooth device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_CONNECT)(
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN BLUETOOTH_ADDRESS *BD_ADDR
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- BD_ADDR
The address of Bluetooth device to be connected.
Description
The Connect() function connects a Bluetooth device. When this function is returned successfully, a new EFI_BLUETOOTH_IO_PROTOCOL is created.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth device is connected successfully. |
EFI_ALREADY_STARTED |
The Bluetooth device is already connected. |
EFI_NOT_FOUND |
The Bluetooth device is not found. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to connect the Bluetooth device. |
26.3.5. BLUETOOTH_CONFIG_PROTOCOL.Disconnect¶
Summary
Disconnect a Bluetooth device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_DISCONNECT)(
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN BLUETOOTH_ADDRESS *BD_ADDR,
IN UINT8 *Reason
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- BD_ADDR
The address of Bluetooth device to be connected.
- Reason
Bluetooth disconnect reason. See Bluetooth specification for detail.
Description
The Disconnect() function disconnects a Bluetooth device. When this function is returned successfully, the EFI_BLUETOOTH_IO_PROTOCOL associated with this device is destroyed and all services associated are stopped.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth device is disconnected successfully. |
EFI_NOT_STARTED |
The Bluetooth device is not connected. |
EFI_NOT_FOUND |
The Bluetooth device is not found. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to disconnect the Bluetooth device. |
26.3.6. BLUETOOTH_CONFIG_PROTOCOL.GetData¶
Summary
Get Bluetooth configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_GET_DATA) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN OUT UINTN *DataSize,
IN OUT VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- DataSize
On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually returned.
- Data
A pointer to the buffer of data that will be returned.
Description
The GetData() function returns Bluetooth configuration data. For remote Bluetooth device configuration data, please use GetRemoteData() function with valid BD_ADDR.
Related Definitions
typedef enum {
EfiBluetoothConfigDataTypeDeviceName, /* Relevant for LE*/
EfiBluetoothConfigDataTypeClassOfDevice,
EfiBluetoothConfigDataTypeRemoteDeviceState, /* Relevant for LE*/
EfiBluetoothConfigDataTypeSdpInfo,
EfiBluetoothConfigDataTypeBDADDR, /* Relevant for LE*/
EfiBluetoothConfigDataTypeDiscoverable, /* Relevant for LE*/
EfiBluetoothConfigDataTypeControllerStoredPairedDeviceList,
EfiBluetoothConfigDataTypeAvailableDeviceList,
EfiBluetoothConfigDataTypeRandomAddress, /* Relevant for LE*/
EfiBluetoothConfigDataTypeRSSI, /* Relevant for LE*/
EfiBluetoothConfigDataTypeAdvertisementData, /* Relevant for LE*/
EfiBluetoothConfigDataTypeIoCapability, /* Relevant for LE*/
EfiBluetoothConfigDataTypeOOBDataFlag, /* Relevant for LE*/
EfiBluetoothConfigDataTypeKeyType, /* Relevant for LE*/
EfiBluetoothConfigDataTypeEncKeySize, /* Relevant for LE*/
EfiBluetoothConfigDataTypeMax,
} EFI_BLUETOOTH_CONFIG_DATA_TYPE;
EfiBluetoothConfigDataTypeAdvertisementDataReport Advertisement report. Data structure is UNIT8[].
- EfiBluetoothConfigDataTypeKeyType
KeyType of Authentication Requirements flag of local device as UINT8, indicating requested security properties. See Bluetooth specification 3.H.3.5.1. BIT0: MITM, BIT1: SC.
- EfiBluetoothConfigDataTypeDeviceName
Local/Remote Bluetooth device name. Data structure is zero terminated CHAR8[].
- EfiBluetoothConfigDataTypeClassOfDevice
nLocal/Remote Bluetooth device ClassOfDevice. Data structure is BLUETOOTH_CLASS_OF_DEVICE.
- EfiBluetoothConfigDataTypeRemoteDeviceState
Remove Bluetooth device state. Data structure is EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_TYPE.
- EfiBluetoothConfigDataTypeSdpInfo
Local/Remote Bluetooth device SDP information. Data structure is UINT8[].
- EfiBluetoothConfigDataTypeBDADDR
Local Bluetooth device address. Data structure is BLUETOOTH_ADDRESS.
- EfiBluetoothConfigDataTypeDiscoverable
Local Bluetooth discoverable state. Data structure is UINT8. (Page scan and/or Inquiry scan)
- EfiBluetoothConfigDataTypeControllerStoredPairedDeviceList
Local Bluetooth controller stored paired device list. Data structure is BLUETOOTH_ADDRESS[].
- EfiBluetoothConfigDataTypeAvailableDeviceList
Local available device list. Data structure is BLUETOOTH_ADDRESS[].
typedef EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_TYPE UINT32;
#define EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_CONNECTED 0x1
#define EFI_BLUETOOTH_CONFIG_REMOTE_DEVICE_STATE_PAIRED 0x2
#define BLUETOOTH_HCI_LINK_KEY_SIZE 16
Status Codes Returned
EFI_SUCCESS |
The Bluetooth configuration data is returned successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is NULL.
• * DataSize is not 0 and Data is NULL
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_NOT_FOUND |
The DataType is not found. |
EFI_BUFFER_TOO_SMALL |
The buffer is too small to hold the buffer. DataSize has been updated with the size needed to complete the request. |
26.3.7. BLUETOOTH_CONFIG_PROTOCOL.SetData¶
Summary
Set Bluetooth configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_SET_DATA) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN UINTN DataSize,
IN VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- DataSize
Indicates the size, in bytes, of the data buffer specified by Data.
- Data
A pointer to the buffer of data that will be set.
Description
The SetData() function sets local Bluetooth device configuration data. Not all DataType can be set.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth configuration data is set successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is 0.
• Data is NULL.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_WRITE_PROTECTED |
Cannot set configuration data. |
26.3.8. BLUETOOTH_CONFIG_PROTOCOL.GetRemoteData¶
Summary
Get remove Bluetooth device configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_GET_REMOTE_DATA) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN BLUETOOTH_ADDRESS *BDAddr,
IN OUT UINTN *DataSize,
IN OUT VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- BDAddr
Remote Bluetooth device address.
- DataSize
On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually returned.
- Data
A pointer to the buffer of data that will be returned.
Description
The GetRemoteData() function returns remote Bluetooth device configuration data.
Status Codes Returned
EFI_SUCCESS |
The remote Bluetooth device configuration data is returned successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is NULL.
• * DataSize is not 0 and Data is NULL
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_NOT_FOUND |
The DataType is not found. |
EFI_BUFFER_TOO_SMALL |
The buffer is too small to hold the buffer. DataSize has been updated with the size needed to complete the request. |
26.3.9. BLUETOOTH_CONFIG_PROTOCOL.RegisterPinCallback¶
Summary
Register PIN callback function.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK_FUNCTION *Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Callback
The callback function. NULL means unregister.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The RegisterPinCallback() function registers Bluetooth PIN callback function. The Bluetooth configuration driver must call RegisterPinCallback() to register a callback function. During pairing, Bluetooth bus driver must trigger this callback function, and Bluetooth configuration driver must handle callback function according to CallbackType during pairing. Both Legacy pairing and SSP (secure simple pairing) are required to be supported. See EFI_BLUETOOTH_PIN_CALLBACK_TYPE below for detail of each pairing mode.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_PIN_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL * *This,
IN VOID * *Context,
IN EFI_BLUETOOTH_PIN_CALLBACK_TYPE *CallbackType,
IN VOID * *InputBuffer,
IN UINTN *InputBufferSize,
OUT VOID ** *OutputBuffer,
OUT UINTN * *OutputBufferSize
);
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Context
Context passed from registration.
CallbackType* Callback type in EFI_BLUETOOTH_PIN_CALLBACK_TYPE.
- InBuffer
A pointer to the buffer of data that is input from callback caller.
- InputBufferSize
Indicates the size, in bytes, of the data buffer specified by InBuffer.
- OutputBuffer
A pointer to the buffer of data that will be output from callback callee. Callee allocates this buffer by using EFI Boot Service AllocatePool().
- OutputBufferSize*
Indicates the size, in bytes, of the data buffer specified by OutputBuffer.
typedef enum {
EfiBluetoothCallbackTypeUserPasskeyNotification,
EfiBluetoothCallbackTypeUserConfirmationRequest,
EfiBluetoothCallbackTypeOOBDataRequest,
EfiBluetoothCallbackTypePinCodeRequest,
EfiBluetoothCallbackTypeMax,
} EFI_BLUETOOTH_PIN_CALLBACK_TYPE;
- EfiBluetoothCallbackTypeUserPasskeyNotification
For SSP - passkey entry. Input buffer is Passkey (4 bytes). No output buffer. See Bluetooth HCI command for detail.
- EfiBluetoothCallbackTypeUserConfirmationRequest
For SSP - just work and numeric comparison. Input buffer is numeric value (4 bytes). Output buffer is BOOLEAN (1 byte). See Bluetooth HCI command for detail.
- EfiBluetoothCallbackTypeOOBDataRequest
For SSP - OOB. See Bluetooth HCI command for detail.
- EfiBluetoothCallbackTypePinCodeRequest
For legacy paring. No input buffer. Output buffer is PIN code (<= 16 bytes). See Bluetooth HCI command for detail.
Status Codes Returned
EFI_SUCCESS |
The PIN callback function is registered successfully. |
26.3.10. BLUETOOTH_CONFIG_PROTOCOL.RegisterGetLinkKeyCallback¶
Summary
Register get link key callback function.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK_FUNCTION Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Callback
The callback function. NULL means unregister.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The RegisterGetLinkKeyCallback() function registers Bluetooth get link key callback function. The Bluetooth configuration driver may call RegisterGetLinkKeyCallback() to register a callback function. When Bluetooth bus driver get Link_Key_Request_Event, Bluetooth bus driver must trigger this callback function if it is registered. Then the callback function in Bluetooth configuration driver must pass link key to Bluetooth bus driver. When the callback function is returned Bluetooth bus driver gets link key and must send HCI_Link_Key_Request_Reply to remote device. If this GetLinkKey callback function is not registered or Bluetooth configuration driver fails to return a valid link key, the Bluetooth bus driver must send HCI_Link_Key_Request_Negative_Reply to remote device. The original link key is passed by Bluetooth bus driver to Bluetooth configuration driver by using EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK_FUNCTION . The Bluetooth configuration driver need save link key to a non-volatile safe place. (See Bluetooth specification, HCI_Link_Key_Request_Reply)
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK_FUNCTION)
(
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN BLUETOOTH_ADDRESS *BDAddr,
OUT UINT8 LinkKey[BLUETOOTH_HCI_LINK_KEY_SIZE]
);
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Context
Context passed from registration.
- CallbackType
Callback type in EFI_BLUETOOTH_PIN_CALLBACK_TYPE.
- BDAddr
A pointer to Bluetooth device address.
- LinkKey
A pointer to the buffer of link key.
Status Codes Returned
EFI_SUCCESS |
The link key callback function is registered successfully. |
26.3.11. BLUETOOTH_CONFIG_PROTOCOL.RegisterSetLinkKeyCallback¶
Summary
Register set link key callback function.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK_FUNCTION *Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Callback
The callback function. NULL means unregister.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The RegisterSetLinkKeyCallback() function registers Bluetooth link key callback function. The Bluetooth configuration driver may call RegisterSetLinkKeyCallback() to register a callback function to get link key from Bluetooth bus driver. When Bluetooth bus driver gets Link_Key_Notification_Event, Bluetooth bus driver must call this callback function if it is registered. Then the callback function in Bluetooth configuration driver must save link key to a safe place. This link key will be used by EFI_BLUETOOTH_CONFIG_REGISTER_GET_LINK_KEY_CALLBACK_FUNCTION later. (See Bluetooth specification, Link_Key_Notification_Event)
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_SET_LINK_KEY_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN BLUETOOTH_ADDRESS *BDAddr,
IN UINT8 LinkKey[BLUETOOTH_HCI_LINK_KEY_SIZE]
);
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Context
Context passed from registration.
- CallbackType
Callback type in EFI_BLUETOOTH_PIN_CALLBACK_TYPE.
- BDAddr
A pointer to Bluetooth device address.
- LinkKey
A pointer to the buffer of link key.
Status Codes Returned
EFI_SUCCESS |
The link key callback function is registered successfully. |
26.3.12. BLUETOOTH_CONFIG_PROTOCOL.RegisterLinkConnectCompleteCallback¶
Summary
Register link connect complete callback function.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK_FUNCTION Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Callback
The callback function. NULL means unregister. to CallbackType defined by EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The RegisterLinkConnectCompleteCallback() function registers Bluetooth link connect complete callback function. The Bluetooth Configuration driver may call RegisterLinkConnectCompleteCallback() to register a callback function. During pairing, Bluetooth bus driver must trigger this callback function to report device state, if it is registered. Then Bluetooth Configuration driver will get information on device connection, according
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE CallbackType,
IN BLUETOOTH_ADDRESS *BDAddr,
IN VOID *InputBuffer,
IN UINTN InputBufferSize
);
- This
Pointer to the EFI_BLUETOOTH_CONFIG_PROTOCOL instance.
- Context
Context passed from registration.
- CallbackType
Callback type in EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE.
- BDAddr
A pointer to Bluetooth device address.
- InputBuffer
A pointer to the buffer of data that is input from callback caller.
- InputBufferSize
Indicates the size, in bytes, of the data buffer specified by InputBuffer.
typedef enum {
EfiBluetoothConnCallbackTypeDisconnected,
EfiBluetoothConnCallbackTypeConnected,
EfiBluetoothConnCallbackTypeAuthenticated,
EfiBluetoothConnCallbackTypeEncrypted,
} EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE;
- EfiBluetoothConnCallbackTypeDisconnected
This callback is called when Bluetooth receive Disconnection_Complete event. Input buffer is Event Parameters of Disconnection_Complete Event defined in Bluetooth specification.
- EfiBluetoothConnCallbackTypeConnected
This callback is called when Bluetooth receive Connection_Complete event. Input buffer is Event Parameters of Connection_Complete Event defined in Bluetooth specification.
- EfiBluetoothConnCallbackTypeAuthenticated
This callback is called when Bluetooth receive Authentication_Complete event. Input buffer is Event Parameters of Authentication_Complete Event defined in Bluetooth specification.
- EfiBluetoothConnCallbackTypeEncrypted
This callback is called when Bluetooth receive Encryption_Change event. Input buffer is Event Parameters of Encryption_Change Event defined in Bluetooth specification.
Status Codes Returned
EFI_SUCCESS |
The link connect complete callback function is registered successfully. |
26.4. EFI Bluetooth Attribute Protocol¶
26.4.1. EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL¶
Summary
This protocol provides service for Bluetooth ATT (Attribute Protocol) and GATT (Generic Attribute Profile) based protocol interfaces.
GUID
#define EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL_GUID \
{ 0x898890e9, 0x84b2, 0x4f3a, { 0x8c, 0x58, 0xd8, 0x57, 0x78, 0x13, 0xe0, 0xac }}
Protocol Interface Structure
,, code-block:
typedef struct _EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL {
EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST SendRequest;
EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION RegisterForServerNotification;
EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO GetServiceInfo;
EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO GetDeviceInfo;
} EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL;
Parameters
- SendRequest
Send a “REQUEST” or “COMMAND” message to remote server and receive a “RESPONSE” message for “REQUEST” from remote server according to Bluetooth attribute protocol data unit (PDU). See the SendRequest() function description.
- RegisterForServerNotification
Register or unregister a server initiated PDU, such as “NOTIFICATION” or “INDICATION” on a characteristic value on remote server. See the RegisterForServerInitiatedMessage() function description.
- GetServiceInfo
Get discovered service data information from connected remote device. See GetServiceInfo() function description.
- GetDeviceInfo
Get the device information. See GetDeviceInfo() function description.
Description
The EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL provides services in ATT protocol and GATT profile. For detail of ATT protocol, and GATT profile, please refer to Bluetooth specification.
26.4.2. BLUETOOTH_ATTRIBUTE_PROTOCOL.SendRequest¶
Summary
Send a “REQUEST” or “COMMAND” message to remote server and receive a “RESPONSE” message for “REQUEST” from remote server according to Bluetooth attribute protocol data unit (PDU).
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST)(
IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
IN VOID *Data,
IN UINTN DataLength,
IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
- Data
Data of a REQUEST or COMMAND message. The first byte is the attribute PDU related opcode, followed by opcode specific fields. See Bluetooth specification, Vol 3, Part F, Attribute Protocol.
- DataLength
The length of Data in bytes.
- Callback
Callback function to notify the RESPONSE is received to the caller, with the response buffer. Caller must check the response buffer content to know if the request action is success or fail. It may be NULL if the data is a COMMAND.
- Context
Data passed into Callback function. It is optional parameter and may be NULL.
Description
The SendRequest() function sends a “REQUEST” or “COMMAND” message to remote server and receive a “RESPONSE” message for “REQUEST” from remote server according to Bluetooth attribute protocol data unit (PDU). In most cases, this interface is used to read attributes from remote device, or write attributes to remote device.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
IN VOID *Data,
IN UINTN DataLength,
IN VOID *Context
);
- This
Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
- Data
Data received. The first byte is the attribute opcode, followed by opcode specific fields. See Bluetooth specification, Vol 3, Part F, Attribute Protocol. It might be a normal RESPONSE message, or ERROR RESPONSE message.
- DataLength
The length of* Data in bytes.
- Context
The context passed from the callback registration request.*
Status Codes Returned
EFI_SUCCESS |
The request is sent successfully. |
EFI_INVALID_PARAMETER |
One or more parameters are invalid due to following conditions:
• The Buffer is NULL.
• The BufferLength is 0.
• The opcode in Buffer is not a valid OPCODE according to Bluetooth specification.
• The Callback is NULL.
|
EFI_DEVICE_ERROR |
Sending the request failed due to the host controller or the device error. |
EFI_NOT_READY |
A GATT operation is already underway for this device |
EFI_UNSUPPORTED |
The attribute does not support the corresponding operation |
26.4.3. BLUETOOTH_ATTRIBUTE_PROTOCOL.RegisterForServerNotification¶
Summary Register or unregister a server initiated message, such as NOTIFICATION or INDICATION, on a characteristic value on remote server.
Prototype
code-block:
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION)
(
IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER *CallbackParameter,
IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
- CallbackParameter
The parameter of the callback.
- Callback
Callback function for server initiated attribute protocol. NULL callback function means unregister the server initiated callback.
- Context
Data passed into Callback function. It is optional parameter and may be NULL.
Description
The RegisterForServerNotification() function can be issued to request Bluetooth to register or unregister a server initiated message, such as notification or indication, on a characteristic value on remote server. It can only be done if the characteristic supports that operation.
Related Definitions
typedef struct {
UINT16 AttributeHandle;
} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION;
typedef struct {
UINT16 AttributeHandle;
} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION;
typedef struct {
UINT32 Version;
UINT8 AttributeOpCode;
union {
EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION Notification;
EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION Indication;
} Parameter;
} EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER;
- Version
The version of the structure. A value of zero represents the EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER structure as defined here. Future version of this specification may extend this data structure in a backward compatible way and increase the value of Version.
- AttributeOpCode
The attribute opcode for server initiated attribute protocol. See Bluetooth specification, Vol 3, Part F, Attribute Protocol.
- AttributeHandle
The attribute handle for notification or indication.
Status Codes Returned
EFI_SUCCESS |
The callback function is registered or unregistered successfully |
EFI_INVALID_PARAMETER |
The attribute opcode is not server initiated message opcode. See Bluetooth specification, Vol 3, Part F, Attribute Protocol. |
EFI_ALREADY_STARTED |
A callback function is already registered on the same attribute opcode and attribute handle, when the Callback is not NULL. |
EFI_NOT_STARTED |
A callback function is not registered on the same attribute opcode and attribute handle, when the Callback is NULL. |
EFI_NOT_READY |
A GATT operation is already underway for this device |
EFI_UNSUPPORTED |
The attribute does not support notification |
26.4.4. BLUETOOTH_ATTRIBUTE_PROTOCOL.GetServiceInfo¶
Summary
Get Bluetooth discovered service information.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO)(
IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
OUT UINTN *ServiceInfoSize,
OUT VOID **ServiceInfo
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
- ServiceInfoSize
A pointer to the size, in bytes, of the ServiceInfo buffer.
- ServiceInfo
A pointer to a callee allocated buffer that returns Bluetooth discovered service information. Callee allocates this buffer by using EFI Boot Service AllocatePool().
Description
The GetServiceInfo() function returns Bluetooth discovered service information. The size of ServiceInfo structure should never be assumed and the value of ServiceInfoSize is the only valid way to know the size of ServiceInfo. The ServiceInfo buffer is a list Bluetooth service information structures defined below.
Related Definitions
typedef struct {
UINT8 Length;
union {
UINT16 Uuid16;
UINT32 Uuid32;
UINT8 Uuid128[16];
} Data;
} EFI_BLUETOOTH_UUID;
- Length
The length of Bluetooth UUID data. The valid value is 2, 4, or 16.
- Uuid16
The 16-bit Bluetooth UUID data.
- Uuid32
The 32-bit Bluetooth UUID data.
- Uuid128
The 128-bit Bluetooth UUID data.
typedef struct {
EFI_BLUETOOTH_UUID Type;
UINT16 Length;
UINT16 AttributeHandle;
EFI_BLUETOOTH_ATTRIBUTE_PERMISSION AttributePermission;
} EFI_BLUETOOTH_ATTRIBUTE_HEADER;
- Type
The type of this structure. It must be EFI_BLUETOOTH_UUID. See Bluetooth GATT definition. Primary Service is 0x2800. Secondary Service is 0x2801. Include Service is 0x2802. Characteristic is 0x2803. Characteristic Descriptor is 0x2900.
- Length
The length of this structure.
- AttributeHandle
The handle of the service declaration. See Bluetooth specification.
- AttributePermission
The permission of the attribute. This field is only valid for the attribute of the local device. This field should be ignored for the attribute of the remote device.
//
// Bluetooth Attribute Permission
//
typedef union {
struct {
UINT16 Readable : 1;
UINT16 ReadEncryption : 1;
UINT16 ReadAuthentication : 1;
UINT16 ReadAuthorization : 1;
UINT16 ReadKeySize : 5;
UINT16 Reserved1 : 7;
UINT16 Writeable : 1;
UINT16 WriteEncryption : 1;
UINT16 WriteAuthentication : 1;
UINT16 WriteAuthorization : 1;
UINT16 WriteKeySize : 5;
UINT16 Reserved2 : 7;
} Permission;
UINT32 Data32;
} EFI_BLUETOOTH_ATTRIBUTE_PERMISSION;
- Readable
The attribute is readable.
- ReadEncryption
The encryption is required on read.
- ReadAuthentication
The authentication is required on read.
- ReadAuthorization
The authorization is required on read.
- ReadKeySize
The size of key in bytes on read.
- Writeable
The attribute is writeable.
- WriteEncryption
The encryption is required on write.
- WriteAuthentication
The authentication is required on write.
- WriteAuthorization
The authorization is required on write.
- WriteKeySize
The size of key in bytes on write.
typedef struct {
EFI_BLUETOOTH_ATTRIBUTE_HEADER Header;
UINT16 EndGroupHandle;
EFI_BLUETOOTH_UUID ServiceUuid;
} EFI_BLUETOOTH_GATT_PRIMARY_SERVICE_INFO;
- EndGroupHandle
The handle of the last attribute within the service definition. See Bluetooth specification.
- Header
The header of this structure.
typedef struct {
EFI_BLUETOOTH_ATTRIBUTE_HEADER Header;
UINT16 StartGroupHandle;
UINT16 EndGroupHandle;
EFI_BLUETOOTH_UUID ServiceUuid;
} EFI_BLUETOOTH_GATT_INCLUDE_SERVICE_INFO;
- Header
The header of this structure.
typedef struct {
EFI_BLUETOOTH_ATTRIBUTE_HEADER Header;
UINT8 CharacteristicProperties;
UINT16 CharacteristicValueHandle;
EFI_BLUETOOTH_UUID CharacteristicUuid;
} EFI_BLUETOOTH_GATT_CHARACTERISTIC_INFO;
- Header
The header of this structure.
typedef struct {
EFI_BLUETOOTH_ATTRIBUTE_HEADER Header;
EFI_BLUETOOTH_UUID CharacteristicDescriptorUuid;
} EFI_BLUETOOTH_GATT_CHARACTERISTIC_DESCRIPTOR_INFO;
- Header
The header of this structure.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth discovered service information is returned successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to retrieve the Bluetooth discovered service information. |
26.4.5. BLUETOOTH_ATTRIBUTE_PROTOCOL.GetDeviceInfo¶
Summary
Get Bluetooth device information.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO)(
IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
OUT UINTN *DeviceInfoSize,
OUT VOID **DeviceInfo
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
- DeviceInfoSize
A pointer to the size, in bytes, of the DeviceInfo buffer.
- DeviceInfo
A pointer to a callee allocated buffer that returns Bluetooth device information. Callee allocates this buffer by using EFI Boot Service AllocatePool(). If this device is Bluetooth classic device, EFI_BLUETOOTH_DEVICE_INFO should be used. If this device is Bluetooth LE device, EFI_BLUETOOTH_LE_DEVICE_INFO should be used.
Description
The GetDeviceInfo() function returns Bluetooth device information. The size of DeviceInfo structure should never be assumed and the value of DeviceInfoSize is the only valid way to know the size of DeviceInfo.
Related Definitions
typedef struct {
UINT8 Address[6];
UINT8 Type;
} BLUETOOTH_LE_ADDRESS;
typedef struct {
UINT32 Version;
BLUETOOTH_LE_ADDRESS BD_ADDR;
BLUETOOTH_LE_ADDRESS DirectAddress;
UINT8 RSSI;
UINTN AdvertismentDataSize;
VOID *AdvertismentData;
} EFI_BLUETOOTH_LE_DEVICE_INFO;
- Version
The version of the structure. A value of zero represents th* e EFI_BLUETOOTH_LE_DEVICE_INFO structure as defined here. Future version of this specification may extend this data structure in a backward compatible way and increase the value of Version.
- BD_ADDR
48bit Bluetooth device address and 1byte address type.
- DirectAddress
48bit random device address and 1byte address type.
- RSSI
Bluetooth RSSI. See Bluetooth specification for detail.
- AdvertisementDataSize
The size of AdvertisementData in bytes.
- AdvertisementData
Bluetooth LE advertisement data. See Bluetooth specification for detail.
Status Codes Returned
EFI_SUCCESS |
The Bluetooth device information is returned successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to retrieve the Bluetooth device information. |
26.4.6. EFI_BLUETOOTH_ATTRIBUTE_SERVICE_BINDING_PROTOCOL¶
Summary
The EFI Bluetooth ATTRIBUTE Service Binding Protocol is used to locate EFI Bluetooth ATTRIBUTE Protocol drivers to create and destroy child of the driver to communicate with other Bluetooth device by using Bluetooth ATTRIBUTE protocol.
GUID
#define EFI_BLUETOOTH_ATTRIBUTE_SERVICE_BINDING_PROTOCOL_GUID \
{ \
0x5639867a, 0x8c8e, 0x408d, 0xac, 0x2f, 0x4b, 0x61, 0xbd, 0xc0, 0xbb, 0xbb \
}
Description
The Bluetooth ATTRIBUTE consumer need locate EFI_BLUETOOTH_ATTRIBUTE_SERVICE_BINDING_PROTOCOL and call CreateChild() to create a new child of EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance. Then use EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL for Bluetooth communication. After use, the Bluetooth ATTRIBUTE consumer need call DestroyChild() to destroy it.
26.5. EFI Bluetooth LE Configuration Protocol¶
26.5.1. EFI_BLUETOOTH_LE_CONFIG_PROTOCOL¶
Summary
This protocol abstracts user interface configuration for BluetoothLe device.
GUID
#define EFI_BLUETOOTH_LE_CONFIG_PROTOCOL_GUID \
{ 0x8f76da58, 0x1f99, 0x4275, { 0xa4, 0xec, 0x47, 0x56, 0x51, 0x5b, 0x1c, 0xe8 }}
Protocol Interface Structure
typedef struct _EFI_BLUETOOTH_LE_CONFIG_PROTOCOL {
EFI_BLUETOOTH_LE_CONFIG_INIT Init;
EFI_BLUETOOTH_LE_CONFIG_SCAN Scan;
EFI_BLUETOOTH_LE_CONFIG_CONNECT Connect;
EFI_BLUETOOTH_LE_CONFIG_DISCONNECT Disconnect;
EFI_BLUETOOTH_LE_CONFIG_GET_DATA GetData;
EFI_BLUETOOTH_LE_CONFIG_SET_DATA SetData;
EFI_BLUETOOTH_LE_CONFIG_GET_REMOTE_DATA GetRemoteData;
EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_AUTH_CALLBACK RegisterSmpAuthCallback;
EFI_BLUETOOTH_LE_CONFIG_SEND_SMP_AUTH_DATA SendSmpAuthData;
EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_GET_DATA_CALLBACK RegisterSmpGetDataCallback;
EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_SET_DATA_CALLBACK RegisterSmpSetDataCallback;
EFI_BLUETOOTH_LE_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK
RegisterLinkConnectCompleteCallback;
} EFI_BLUETOOTH_LE_CONFIG_PROTOCOL;
Parameters
- Init
Initialize BluetoothLE host controller and local device. See the Init() function description.
- Scan
Scan BluetoothLE device. See the Scan() function description.
- Connect
Connect one BluetoothLE device. See the Connect() function description.
- Disconnect
Disconnect one BluetoothLE device. See the Disconnect() function description.
- GetData
Get BluetoothLE configuration data. See the GetData() function description.
- SetData
Set BluetoothLE configuration data. See the SetData() function description.
- GetRemoteData
Get remote BluetoothLE device data. See the GetRemoteData() function description.
- RegisterSmpAuthCallback
Register Security Manager Callback function. This function will be called from Bluetooth BUS driver whenever user interaction is required for security protocol authorization/authentication. See the RegisterSmpAuthCallback() function description.
- SendSmpAuthData
Send user input (Authentication/Authorization) such as passkey, confirmation (yes/no) in response to pairing request. See the SendSmpAuthData() function description.
- RegisterSmpGetDataCallback
Register a callback function to get SMP related data. See the RegisterSmpGetDataCallback() function description.
- RegisterSmpSetDataCallback
Register a callback function to set SMP related data. See the RegisterSmpGetDataCallback() function description.
- RegisterLinkConnectCompleteCallback
Register link connect complete callback function. See the RegisterLinkConnectCompleteCallback() function description.
Description
The EFI_BLUETOOTH_LE_CONFIG_PROTOCOL abstracts the BluetoothLE configuration. User can use BluetoothLE configuration to interactive with BluetoothLE bus driver.
26.5.2. BLUETOOTH_LE_CONFIG_PROTOCOL.Init¶
Summary
Initialize BluetoothLE host controller and local device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_INIT)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
Description
The Init() function initializes BluetoothLE host controller and local device.
Status Codes Returned
EFI_SUCCESS |
The BluetoothLE host controller and local device is initialized successfully. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to initialize the BluetoothLE host controller and local device. |
26.5.3. BLUETOOTH_LE_CONFIG_PROTOCOL.Scan¶
Summary
Scan BluetoothLE device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SCAN)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN BOOLEAN ReScan,
IN UIN32 Timeout;
IN EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER *ScanParameter, OPTIONAL
IN EFI_BLUETOOTH_LE_CONFIG_SCAN_CALLBACK_FUNCTION Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- ReScan
If TRUE, a new scan request is submitted no matter there is scan result before. If FALSE and there is scan result, the previous scan result is returned and no scan request is submitted.
- Timeout
Duration in milliseconds for which to scan.
- ScanParameter
If it is not NULL, the ScanParameter is used to perform a scan by the BluetoothLE bus driver. If it is NULL, the default parameter is used.
- Callback
The callback function. This function is called if a BluetoothLE device is found during scan process.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The Scan() function scans BluetoothLE device. When this function is returned, it just means scan request is submitted. It does not mean scan process is started or finished. Whenever there is a BluetoothLE device is found, the Callback function will be called. Callback function might be called before this function returns or after this function returns.
Related Definitions
typedef struct {
// Scan parameter
UINT32 Version;
UINT8 ScanType;
UINT16 ScanInterval;
UINT16 ScanWindow;
UINT8 ScanningFilterPolicy;
// Scan result filter
UINT8 AdvertisementFlagFilter;
} EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER;
- Version
The version of the structure. A value of zero represents the EFI_BLUETOOTH_LE_CONFIG_SCAN_PARAMETER structure as defined here. Future version of this specification may extend this data structure in a backward compatible way and increase the value of Version.
- ScanType
Passive scanning or active scanning. See Bluetooth specification.
- ScanInterval
Recommended scan interval to be used while performing scan.
- ScanWindow
Recommended scan window to be used while performing a scan.
- ScanningFilterPolicy
Recommended scanning filter policy to be used while performing a scan.
- AdvertisementFlagFilter
This is one byte flag to serve as a filter to remove unneeded scan result. For example, set BIT0 means scan in LE Limited Discoverable Mode. Set BIT1 means scan in LE General Discoverable Mode. See Supplement to Bluetooth Core Specification.
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SCAN_CALLBACK_FUNCTION) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN EFI_BLUETOOTH_LE_SCAN_CALLBACK_INFORMATION *CallbackInfo
);
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Context
Context passed from scan request.
- CallbackInfo
Data related to scan result. NULL CallbackInfo means scan complete.
typedef struct{
BLUETOOTH_LE_ADDRESS BDAddr;
BLUETOOTH_LE_ADDRESS DirectAddress;
UINT8 RemoteDeviceState;
INT8 RSSI;
UINTN AdvertisementDataSize;
VOID *AdvertisementData;
} EFI_BLUETOOTH_LE_SCAN_CALLBACK_INFORMATION;
Status Codes Returned
EFI_SUCCESS |
The Bluetooth scan request is submitted. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to scan the Bluetooth device. |
26.5.4. BLUETOOTH_LE_CONFIG_PROTOCOL.Connect¶
Summary
Connect a BluetoothLE device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_CONNECT)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN BOOLEAN AutoReconnect,
IN BOOLEAN DoBonding;
IN EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER *ConnectParameter, OPTIONAL
IN BLUETOOTH_LE_ADDRESS *BD_ADDR
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- AutoReconnect
If TRUE. the BluetoothLE host controller needs to do an auto reconnect. If FALSE, the BluetoothLE host controller does not do an auto reconnect.
- DoBonding
If TRUE, the BluetoothLE host controller needs to do a bonding. If FALSE, the BluetoothLE host controller does not do a bonding.
- ConnectParameter
If it is not NULL, the ConnectParameter is used to perform a scan by the BluetoothLE bus driver. If it is NULL, the default parameter is used.
- BD_ADDR
The address of the BluetoothLE device to be connected.
Description
The Connect() function connects a Bluetooth device. When this function is returned successfully, a new EFI_BLUETOOTH_IO_PROTOCOL is created.
Related Definitions
typedef struct {
UINT32 Version;
UINT16 ScanInterval;
UINT16 ScanWindow;
UINT16 ConnIntervalMin;
UINT16 ConnIntervalMax;
UINT16 ConnLatency;
UINT16 SupervisionTimeout;
} EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER;
- Version
The version of the structure. A value of zero represents the EFI_BLUETOOTH_LE_CONFIG_CONNECT_PARAMETER structure as defined here. Future version of this specification may extend this data structure in a backward compatible way and increase the value of Version.
- ScanInterval
Recommended scan interval to be used while performing scan before connect.
- ScanWindow
Recommended scan window to be used while performing a connection.
- ConnIntervalMin
Minimum allowed connection interval. Shall be less than or equal to ConnIntervalMax.
- ConnIntervalMax
Maximum allowed connection interval. Shall be greater than or equal to ConnIntervalMin.
- ConnLatency
Slave latency for the connection in number of connection events.
- SupervisionTimeout
Link supervision timeout for the connection.
Status Codes Returned
EFI_SUCCESS |
The BluetoothLE device is connected successfully. |
EFI_ALREADY_STARTED |
The BluetoothLE device is already connected. |
EFI_NOT_FOUND |
The BluetoothLE device is not found. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to connect the BluetoothLE device. |
26.5.5. BLUETOOTH_LE_CONFIG_PROTOCOL.Disconnect¶
Summary
Disconnect a BluetoothLE device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_DISCONNECT)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN BLUETOOTH_LE_ADDRESS *BD_ADDR,
IN UINT8 Reason
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- BD_ADDR
The address of BluetoothLE device to be connected.
- Reason
BluetoothLE disconnect reason. See Bluetooth specification for detail.
Description
The Disconnect() function disconnects a BluetoothLE device. When this function is returned successfully, the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL associated with this device is destroyed and all services associated are stopped.
Status Codes Returned
EFI_SUCCESS |
The BluetoothLE device is disconnected successfully. |
EFI_NOT_STARTED |
The BluetoothLE device is not connected. |
EFI_NOT_FOUND |
The BluetoothLE device is not found. |
EFI_DEVICE_ERROR |
A hardware error occurred trying to disconnect the BluetoothLE device. |
26.5.6. BLUETOOTH_LE_CONFIG_PROTOCOL.GetData¶
Summary
Get BluetoothLE configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_GET_DATA) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN OUT UINTN *DataSize,
IN OUT VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- DataSize
On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually returned.
- Data
A pointer to the buffer of data that will be returned.
Description
The GetData() function returns BluetoothLE configuration data. For remote BluetoothLE device configuration data, please use GetRemoteData() function with valid BD_ADDR.
Status Codes Returned
EFI_SUCCESS |
The BluetoothLE configuration data is returned successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is NULL.
• * DataSize is 0.
• Data is NULL.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_NOT_FOUND |
The DataType is not found. |
EFI_BUFFER_TOO_SMALL |
The buffer is too small to hold the buffer. |
26.5.7. BLUETOOTH_LE_CONFIG_PROTOCOL.SetData¶
Summary
Set BluetoothLE configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_SET_DATA) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN UINTN DataSize,
IN VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- DataSize
Indicates the size, in bytes, of the data buffer specified by Data.
- Data
A pointer to the buffer of data that will be set.
Description
The SetData() function sets local BluetoothLE device configuration data. Not all DataType can be set.
Status Codes Returned
EFI_SUCCESS |
The BluetoothLE configuration data is set successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is 0.
• Data is NULL.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_WRITE_PROTECTED |
Cannot set configuration data. |
26.5.8. BLUETOOTH_LE_CONFIG_PROTOCOL.GetRemoteData¶
Summary
Get remove BluetoothLE device configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_GET_REMOTE_DATA) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_CONFIG_DATA_TYPE DataType,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN OUT UINTN *DataSize,
IN OUT VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- DataType
Configuration data type.
- BDAddr
Remote BluetoothLE device address.
- DataSize
On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually returned.
- Data
A pointer to the buffer of data that will be returned.
Description
The GetRemoteData() function returns remote BluetoothLE device configuration data.
Status Codes Returned
EFI_SUCCESS |
The remote BluetoothLE device configuration data is returned successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• DataSize is NULL.
• * DataSize is 0.
• Data is NULL.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_NOT_FOUND |
The DataType is not found. |
EFI_BUFFER_TOO_SMALL |
The buffer is too small to hold the buffer. |
26.5.9. BLUETOOTH_LE_CONFIG_PROTOCOL.RegisterSmpAuthCallback¶
Summary
Register Security Manager Protocol callback function for user authentication/authorization.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_REGISTER_SMP_AUTH_CALLBACK)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_LE_SMP_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Callback
Callback function for user authentication/authorization.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
Description
The RegisterSmpAuthCallback() function register Security Manager Protocol callback function for user authentication/authorization.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_SMP_CALLBACK) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE EventDataType,
IN UINTN DataSize,
IN VOID *Data
);
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
- BDAddr
Remote BluetoothLE device address.
- EventDataType
Event data type in EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE.
- DataSize
Indicates the size, in bytes, of the data buffer specified by Data.
- Data
A pointer to the buffer of data.
typedef enum {
EfiBlutoothSmpAuthorizationRequestEvent,
EfiBlutoothSmpPasskeyReadyEvent,
EfiBlutoothSmpPasskeyRequestEvent,
EfiBlutoothSmpOOBDataRequestEvent,
EfiBlutoothSmpNumericComparisonEvent,
} EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE;
- EfiBlutoothSmpAuthorizationRequestEvent
It indicates an authorization request. No data is associated with the callback input. In the output data, the application should return the authorization value. The data structure is BOOLEAN. TRUE means YES. FALSE means NO.
- EfiBlutoothSmpPasskeyReadyEvent
It indicates that a passkey has been generated locally by the driver, and the same passkey should be entered at the remote device. The callback input data is the passkey of type UINT32, to be displayed by the application. No output data should be returned.
- EfiBlutoothSmpPasskeyRequestEvent
It indicates that the driver is requesting for the passkey has been generated at the remote device. No data is associated with the callback input. The output data is the passkey of type UINT32, to be entered by the user.
- EfiBlutoothSmpOOBDataRequestEvent
It indicates that the driver is requesting for the passkey that has been pre-shared out-of-band with the remote device. No data is associated with the callback input. The output data is the stored OOB data of type UINT8[16].
- EfiBlutoothSmpNumericComparisonEvent
In indicates that a number have been generated locally by the bus driver, and also at the remote device, and the bus driver wants to know if the two numbers match. The callback input data is the number of type UINT32. The output data is confirmation value of type BOOLEAN. TRUE means comparison pass. FALSE means comparison fail.
Status Codes Returned
EFI_SUCCESS |
The SMP callback function is registered successfully. |
EFI_ALREADY_STARTED |
A callback function is already registered on the same attribute opcode and attribute handle, when the Callback is not NULL. |
EFI_NOT_STARTED |
A callback function is not registered on the same attribute opcode and attribute handle, when the Callback is NULL. |
26.5.10. BLUETOOTH_LE_CONFIG_PROTOCOL.SendSmpAuthData¶
Summary
Send user authentication/authorization to remote device.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_SEND_SMP_AUTH_DATA)(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE EventDataType,
IN UINTN DataSize,
IN VOID *Data
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- BDAddr
Remote BluetoothLE device address.
- EventDataType
Event data type in EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE.
- DataSize
The size of Data in bytes, of the data buffer specified by Data.
- Data
A pointer to the buffer of data that will be sent. The data format depends on the type of SMP event data being responded to. See EFI_BLUETOOTH_LE_SMP_EVENT_DATA_TYPE.
Description
The SendSmpAuthData() function sends user authentication/authorization to remote device. It should be used to send these information after the caller gets the request data from the callback function by RegisterSmpAuthCallback ().
Status Codes Returned
EFI_SUCCESS |
The SMP authorization data is sent successfully. |
EFI_NOT_READY |
SMP is not in the correct state to receive the auth data |
26.5.11. BLUETOOTH_LE_CONFIG_PROTOCOL.RegisterSmpGetDataCallback¶
Summary
Register a callback function to get SMP related data.
Prototype
typedef
EFI_STATUS
(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_GET_DATA_CALLBACK )(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_LE_CONFIG_SMP_GET_DATA_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Callback
Callback function for SMP get data.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
Description
The RegisterSmpGetDataCallback() function registers a callback function to get SMP related data.
Related Definitions
typedef
EFI_STATUS
(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_SMP_GET_DATA_CALLBACK) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN EFI_BLUETOOTH_LE_SMP_DATA_TYPE DataType,
IN OUT UINTN *DataSize,
OUT VOID *Data
);
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
- BDAddr
Remote BluetoothLE device address. For Local device setting, it should be NULL.
- DataType
Data type in EFI_BLUETOOTH_LE_SMP_DATA_TYPE.
- DataSize
On input, indicates the size, in bytes, of the data buffer specified by Data. On output, indicates the amount of data actually returned.
- Data
A pointer to the buffer of data that will be returned.
typedef enum {
// For local device only
EfiBluetoothSmpLocalIR, /* If Key hierarchy is supported */
EfiBluetoothSmpLocalER, /* If Key hierarchy is supported */
EfiBluetoothSmpLocalDHK, /* If Key hierarchy is supported. OPTIONAL */
// For peer specific
EfiBluetoothSmpKeysDistributed = 0x1000,
EfiBluetoothSmpKeySize,
EfiBluetoothSmpKeyType,
EfiBluetoothSmpPeerLTK,
EfiBluetoothSmpPeerIRK,
EfiBluetoothSmpPeerCSRK,
EfiBluetoothSmpPeerRand,
EfiBluetoothSmpPeerEDIV,
EfiBluetoothSmpPeerSignCounter,
EfiBluetoothSmpLocalLTK, /* If Key hierarchy not supported */
EfiBluetoothSmpLocalIRK, /* If Key hierarchy not supported */
EfiBluetoothSmpLocalCSRK, /* If Key hierarchy not supported */
EfiBluetoothSmpLocalSignCounter,
EfiBluetoothSmpLocalDIV,
EfiBluetoothSmpPeerAddressList,
EfiBluetoothSmpMax,
} EFI_BLUETOOTH_LE_SMP_DATA_TYPE;
- EfiBlutoothSmpLocalIR
It is a 128-bit Identity Root (IR) key to generate IRK. Data structure is UINT8[16]. See Bluetooth specification. This is only required when Bluetooth key hierarchy is supported. This type is for the local device only.
- EfiBlutoothSmpLocalER
It is a 128-bit Encryption Root (ER) key to generate LTK and CSRK. Data structure is UINT8[16]. See Bluetooth specification. This is only required when Bluetooth key hierarchy is supported. This type is for the local device only.
- EfiBlutoothSmpLocalDHK
It is a 128-bit Diversifier Hiding Key (DHK) to generate EDIV. Data structure is UINT8[16].See Bluetooth specification. This is only required when Bluetooth key hierarchy is supported. This type is for the local device only.
- EfiBlutoothSmpKeysDistributed
It is LE Key Distribution Format. Data structure is UINT8. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpKeySize
It indicates the size of keys in bytes. It is the negotiated key size between local device and peer device. Data structure is UINTN. This is the peer device specific information.
- EfiBlutoothSmpKeyType
Indicates support for MITM/Secure connection. It is the negotiated Authentication Requirements between local device and peer device. See Bluetooth Spec 3.H.3.5.1. Data structure is UINT8. BIT0: MITM, BIT1: SC. This is the peer device specific information.
- EfiBlutoothSmpPeerLTK
It is a 128-bit Long-Term Key (LTK) to generate the contributory session key for an encrypted connection. Data structure is UINT8[16]. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpPeerIRK
It is a 128-bit Identity Resolving Key (IRK) to generate and resolve random addresses. Data structure is UINT8[16]. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpPeerCSRK
It is a 128-bit Connection-Signature Resolving Key (CSRK) to sign data and verify signatures on the receiving device. Data structure is UINT8[16]. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpPeerRand
It is a 64-bit Random number (Rand) to identify the LTK distributed during LE legacy pairing. Data structure is UINT64. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpPeerEDIV
It is a 16-bit Encrypted Diversifier (EDIV) to identify the LTK distributed during LE legacy pairing. Data structure is UINT16. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpPeerSignCounter
It is a 32-bit Sign Counter to assist MAC generation. Data structure is UINT32. See Bluetooth specification. This is the peer device specific information.
- EfiBlutoothSmpLocakLTK
It is a 128-bit Long-Term Key (LTK) to generate the contributory session key for an encrypted connection. Data structure is UINT8[16]. See Bluetooth specification. This is only required when Bluetooth key hierarchy is not supported. This is the peer specific local device information.
- EfiBlutoothSmpLocalIRK
It is a 128-bit Identity Resolving Key (IRK) to generate and resolve random addresses. Data structure is UINT8[16]. See Bluetooth specification. This is only required when Bluetooth key hierarchy is not supported. This is the peer specific local device information.
- EfiBlutoothSmpLocalCSRK
It is a 128-bit Connection-Signature Resolving Key (CSRK) to sign data and verify signatures on the receiving device. Data structure is UINT8[16]. See Bluetooth specification. This is only required when Bluetooth key hierarchy is not supported. This is the peer specific local device information.
- EfiBlutoothSmpLocalSignCounter
It is a 32-bit Sign Counter to assist MAC generation. Data structure is UINT32. See Bluetooth specification. This is the peer specific local device information.
- EfiBlutoothSmpLocalDIV
It is a 16-bit Diversifier (DIV) to be used as index to recover LTK. Data structure is UINT16. See Bluetooth specification. This is the peer specific local device information.
- EfiBluetoothSmpPeerAddressList
A list of Bluetooth peer addresses that have been connected before. The data structure is BLUETOOTH_LE_ADDRESS[]. The data size must be a multiple of sizeof(BLUETOOTH_LE_ADDRESS).
Status Codes Returned
EFI_SUCCESS |
The SMP get data callback function is registered successfully. |
EFI_ALREADY_STARTED |
A callback function is already registered on the same attribute opcode and attribute handle, when the Callback is not NULL. |
EFI_NOT_STARTED |
A callback function is not registered on the same attribute opcode and attribute handle, when the Callback is NULL. |
26.5.12. BLUETOOTH_LE_CONFIG_PROTOCOL.RegisterSmpSetDataCallback¶
Summary
Register a callback function to set SMP related data.
Prototype
typedef
EFI_STATUS
(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_REGISTER_SMP_SET_DATA_CALLBACK )(
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_LE_CONFIG_SMP_SET_DATA_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Callback
Callback function for SMP set data.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
Description
The RegisterSmpSetDataCallback() function registers a callback function to set SMP related data.
Related Definitions
typedef
EFI_STATUS
(EFIAPI * EFI_BLUETOOTH_LE_CONFIG_SMP_SET_DATA_CALLBACK) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN EFI_BLUETOOTH_LE_SMP_DATA_TYPE Type,
IN UINTN DataSize,
IN VOID *Data
);
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Context
Data passed into callback function. This is optional parameter and may be NULL.
- BDAddr
Remote BluetoothLE device address.
- DataType
Data type in EFI_BLUETOOTH_LE_SMP_DATA_TYPE.
- DataSize
Indicates the size, in bytes, of the data buffer specified by Data.
- Data
A pointer to the buffer of data.
Status Codes Returned
EFI_SUCCESS |
The SMP get data callback function is registered successfully. |
EFI_ALREADY_STARTED |
A callback function is already registered on the same attribute opcode and attribute handle, when the Callback is not NULL. |
EFI_NOT_STARTED |
A callback function is not registered on the same attribute opcode and attribute handle, when the Callback is NULL. |
26.5.13. BLUETOOTH_LE_CONFIG_PROTOCOL.RegisterLinkConnectCompleteCallback¶
Summary
Register link connect complete callback function.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_REGISTER_CONNECT_COMPLETE_CALLBACK) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN EFI_BLUETOOTH_LE_CONFIG_CONNECT_COMPLETE_CALLBACK Callback,
IN VOID *Context
);
Parameters
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Callback
The callback function. NULL means unregister.
- Context
Data passed into Callback function. This is optional parameter and may be NULL.
Description
The RegisterLinkConnectCompleteCallback() function registers Bluetooth link connect complete callback function. The Bluetooth Configuration driver may call RegisterLinkConnectCompleteCallback() to register a callback function. During pairing, Bluetooth bus driver must trigger this callback function to report device state, if it is registered. Then Bluetooth Configuration driver will get information on device connection, according to CallbackType defined by EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_BLUETOOTH_LE_CONFIG_CONNECT_COMPLETE_CALLBACK) (
IN EFI_BLUETOOTH_LE_CONFIG_PROTOCOL *This,
IN VOID *Context,
IN EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE CallbackType,
IN BLUETOOTH_LE_ADDRESS *BDAddr,
IN VOID *InputBuffer,
IN UINTN InputBufferSize
);
- This
Pointer to the EFI_BLUETOOTH_LE_CONFIG_PROTOCOL instance.
- Context
Context passed from registration.
- CallbackType
Callback type in EFI_BLUETOOTH_CONNECT_COMPLETE_CALLBACK_TYPE.
- BDAddr
A pointer to BluetoothLE device address.
- InputBuffer
A pointer to the buffer of data that is input from callback caller.
- InputBufferSize
Indicates the size, in bytes, of the data buffer specified by InputBuffer.
Status Codes Returned
EFI_SUCCESS |
The link connect complete callback function is registered successfully. |
EFI_ALREADY_STARTED |
A callback function is already registered on the same attribute opcode and attribute handle, when the Callback is not NULL. |
EFI_NOT_STARTED |
A callback function is not registered on the same attribute opcode and attribute handle, when the Callback is NULL. |