MdePkg/Include/Protocol/BluetoothAttribute.h

   1 /** @file
   2   EFI Bluetooth Attribute Protocol as defined in UEFI 2.7.
   3   This protocol provides service for Bluetooth ATT (Attribute Protocol) and GATT (Generic
   4   Attribute Profile) based protocol interfaces.
   5
   6   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9   @par Revision Reference:
  10   This Protocol is introduced in UEFI Specification 2.7
  11
  12 **/
  13
  14 #ifndef __EFI_BLUETOOTH_ATTRIBUTE_H__
  15 #define __EFI_BLUETOOTH_ATTRIBUTE_H__
  16
  17 #define EFI_BLUETOOTH_ATTRIBUTE_SERVICE_BINDING_PROTOCOL_GUID \
  18   { \
  19     0x5639867a, 0x8c8e, 0x408d, { 0xac, 0x2f, 0x4b, 0x61, 0xbd, 0xc0, 0xbb, 0xbb } \
  20   }
  21
  22 #define EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL_GUID \
  23   { \
  24     0x898890e9, 0x84b2, 0x4f3a, { 0x8c, 0x58, 0xd8, 0x57, 0x78, 0x13, 0xe0, 0xac } \
  25   }
  26
  27 typedef struct _EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL;
  28
  29 #pragma pack(1)
  30
  31 //
  32 // Bluetooth UUID
  33 //
  34 typedef struct {
  35   UINT8    Length;
  36   union {
  37     UINT16    Uuid16;
  38     UINT32    Uuid32;
  39     UINT8     Uuid128[16];
  40   } Data;
  41 } EFI_BLUETOOTH_UUID;
  42
  43 #define UUID_16BIT_TYPE_LEN   2
  44 #define UUID_32BIT_TYPE_LEN   4
  45 #define UUID_128BIT_TYPE_LEN  16
  46
  47 #define BLUETOOTH_IS_ATTRIBUTE_OF_TYPE(a, t)  ((a)->Type.Length == UUID_16BIT_TYPE_LEN && (a)->Type.Data.Uuid16 == (t))
  48
  49 //
  50 // Bluetooth Attribute Permission
  51 //
  52 typedef union {
  53   struct {
  54     UINT16    Readable            : 1;
  55     UINT16    ReadEncryption      : 1;
  56     UINT16    ReadAuthentication  : 1;
  57     UINT16    ReadAuthorization   : 1;
  58     UINT16    ReadKeySize         : 5;
  59     UINT16    Reserved1           : 7;
  60     UINT16    Writeable           : 1;
  61     UINT16    WriteEncryption     : 1;
  62     UINT16    WriteAuthentication : 1;
  63     UINT16    WriteAuthorization  : 1;
  64     UINT16    WriteKeySize        : 5;
  65     UINT16    Reserved2           : 7;
  66   } Permission;
  67   UINT32    Data32;
  68 } EFI_BLUETOOTH_ATTRIBUTE_PERMISSION;
  69
  70 typedef struct {
  71   EFI_BLUETOOTH_UUID                    Type;
  72   UINT16                                Length;
  73   UINT16                                AttributeHandle;
  74   EFI_BLUETOOTH_ATTRIBUTE_PERMISSION    AttributePermission;
  75 } EFI_BLUETOOTH_ATTRIBUTE_HEADER;
  76
  77 typedef struct {
  78   EFI_BLUETOOTH_ATTRIBUTE_HEADER    Header;
  79   UINT16                            EndGroupHandle;
  80   EFI_BLUETOOTH_UUID                ServiceUuid;
  81 } EFI_BLUETOOTH_GATT_PRIMARY_SERVICE_INFO;
  82
  83 typedef struct {
  84   EFI_BLUETOOTH_ATTRIBUTE_HEADER    Header;
  85   UINT16                            StartGroupHandle;
  86   UINT16                            EndGroupHandle;
  87   EFI_BLUETOOTH_UUID                ServiceUuid;
  88 } EFI_BLUETOOTH_GATT_INCLUDE_SERVICE_INFO;
  89
  90 typedef struct {
  91   EFI_BLUETOOTH_ATTRIBUTE_HEADER    Header;
  92   UINT8                             CharacteristicProperties;
  93   UINT16                            CharacteristicValueHandle;
  94   EFI_BLUETOOTH_UUID                CharacteristicUuid;
  95 } EFI_BLUETOOTH_GATT_CHARACTERISTIC_INFO;
  96
  97 typedef struct {
  98   EFI_BLUETOOTH_ATTRIBUTE_HEADER    Header;
  99   EFI_BLUETOOTH_UUID                CharacteristicDescriptorUuid;
 100 } EFI_BLUETOOTH_GATT_CHARACTERISTIC_DESCRIPTOR_INFO;
 101
 102 #pragma pack()
 103
 104 typedef struct {
 105   UINT16    AttributeHandle;
 106 } EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION;
 107
 108 typedef struct {
 109   UINT16    AttributeHandle;
 110 } EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION;
 111
 112 typedef struct {
 113   UINT32    Version;
 114   UINT8     AttributeOpCode;
 115   union {
 116     EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_NOTIFICATION    Notification;
 117     EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER_INDICATION      Indication;
 118   } Parameter;
 119 } EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER;
 120
 121 typedef struct {
 122   UINT32                  Version;
 123   BLUETOOTH_LE_ADDRESS    BD_ADDR;
 124   BLUETOOTH_LE_ADDRESS    DirectAddress;
 125   UINT8                   RSSI;
 126   UINTN                   AdvertisementDataSize;
 127   VOID                    *AdvertisementData;
 128 } EFI_BLUETOOTH_LE_DEVICE_INFO;
 129
 130 /**
 131   The callback function to send request.
 132
 133   @param[in]  This                Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
 134   @param[in]  Data                Data received. The first byte is the attribute opcode, followed by opcode specific
 135                                   fields. See Bluetooth specification, Vol 3, Part F, Attribute Protocol. It might be a
 136                                   normal RESPONSE message, or ERROR RESPONSE messag
 137   @param[in]  DataLength          The length of Data in bytes.
 138   @param[in]  Context             The context passed from the callback registration request.
 139
 140   @retval EFI_SUCCESS   The callback function complete successfully.
 141
 142 **/
 143 typedef
 144 EFI_STATUS
 145 (EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION)(
 146   IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL *This,
 147   IN VOID                             *Data,
 148   IN UINTN                            DataLength,
 149   IN VOID                             *Context
 150   );
 151
 152 /**
 153   Send a "REQUEST" or "COMMAND" message to remote server and receive a "RESPONSE" message
 154   for "REQUEST" from remote server according to Bluetooth attribute protocol data unit(PDU).
 155
 156   @param[in]  This              Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
 157   @param[in]  Data              Data of a REQUEST or COMMAND message. The first byte is the attribute PDU
 158                                 related opcode, followed by opcode specific fields. See Bluetooth specification,
 159                                 Vol 3, Part F, Attribute Protocol.
 160   @param[in]  DataLength        The length of Data in bytes.
 161   @param[in]  Callback          Callback function to notify the RESPONSE is received to the caller, with the
 162                                 response buffer. Caller must check the response buffer content to know if the
 163                                 request action is success or fail. It may be NULL if the data is a COMMAND.
 164   @param[in]  Context           Data passed into Callback function. It is optional parameter and may be NULL.
 165
 166   @retval EFI_SUCCESS           The request is sent successfully.
 167   @retval EFI_INVALID_PARAMETER One or more parameters are invalid due to following conditions:
 168                                 - The Buffer is NULL.
 169                                 - The BufferLength is 0.
 170                                 - The opcode in Buffer is not a valid OPCODE according to Bluetooth specification.
 171                                 - The Callback is NULL.
 172   @retval EFI_DEVICE_ERROR      Sending the request failed due to the host controller or the device error.
 173   @retval EFI_NOT_READY         A GATT operation is already underway for this device.
 174   @retval EFI_UNSUPPORTED       The attribute does not support the corresponding operation.
 175
 176 **/
 177 typedef
 178 EFI_STATUS
 179 (EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST)(
 180   IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL            *This,
 181   IN VOID                                        *Data,
 182   IN UINTN                                       DataLength,
 183   IN EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION   Callback,
 184   IN VOID                                        *Context
 185   );
 186
 187 /**
 188   Register or unregister a server initiated message, such as NOTIFICATION or INDICATION, on a
 189   characteristic value on remote server.
 190
 191   @param[in]  This              Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
 192   @param[in]  CallbackParameter The parameter of the callback.
 193   @param[in]  Callback          Callback function for server initiated attribute protocol. NULL callback
 194                                 function means unregister the server initiated callback.
 195   @param[in]  Context           Data passed into Callback function. It is optional parameter and may be NULL.
 196
 197   @retval EFI_SUCCESS           The callback function is registered or unregistered successfully
 198   @retval EFI_INVALID_PARAMETER The attribute opcode is not server initiated message opcode. See
 199                                 Bluetooth specification, Vol 3, Part F, Attribute Protocol.
 200   @retval EFI_ALREADY_STARTED   A callback function is already registered on the same attribute
 201                                 opcode and attribute handle, when the Callback is not NULL.
 202   @retval EFI_NOT_STARTED       A callback function is not registered on the same attribute opcode
 203                                 and attribute handle, when the Callback is NULL.
 204   @retval EFI_NOT_READY         A GATT operation is already underway for this device.
 205   @retval EFI_UNSUPPORTED       The attribute does not support notification.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION)(
 211   IN  EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL           *This,
 212   IN  EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_PARAMETER *CallbackParameter,
 213   IN  EFI_BLUETOOTH_ATTRIBUTE_CALLBACK_FUNCTION  Callback,
 214   IN  VOID                                       *Context
 215   );
 216
 217 /**
 218   Get Bluetooth discovered service information.
 219
 220   @param[in]  This              Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
 221   @param[out] ServiceInfoSize   A pointer to the size, in bytes, of the ServiceInfo buffer.
 222   @param[out] ServiceInfo       A pointer to a callee allocated buffer that returns Bluetooth
 223                                 discovered service information. Callee allocates this buffer by
 224                                 using EFI Boot Service AllocatePool().
 225
 226   @retval EFI_SUCCESS           The Bluetooth discovered service information is returned successfully.
 227   @retval EFI_DEVICE_ERROR      A hardware error occurred trying to retrieve the Bluetooth discovered
 228                                 service information.
 229
 230 **/
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO)(
 234   IN EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL      *This,
 235   OUT UINTN                                *ServiceInfoSize,
 236   OUT VOID                                 **ServiceInfo
 237   );
 238
 239 /**
 240   Get Bluetooth device information.
 241
 242   @param[in]  This              Pointer to the EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL instance.
 243   @param[out] DeviceInfoSize    A pointer to the size, in bytes, of the DeviceInfo buffer.
 244   @param[out] DeviceInfo        A pointer to a callee allocated buffer that returns Bluetooth
 245                                 device information. Callee allocates this buffer by using EFI Boot
 246                                 Service AllocatePool(). If this device is Bluetooth classic
 247                                 device, EFI_BLUETOOTH_DEVICE_INFO should be used. If
 248                                 this device is Bluetooth LE device, EFI_BLUETOOTH_LE_DEVICE_INFO
 249                                 should be used.
 250
 251   @retval EFI_SUCCESS           The Bluetooth device information is returned successfully.
 252   @retval EFI_DEVICE_ERROR      A hardware error occurred trying to retrieve the Bluetooth device
 253                                 information
 254
 255 **/
 256 typedef
 257 EFI_STATUS
 258 (EFIAPI *EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO)(
 259   IN  EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL  *This,
 260   OUT UINTN                             *DeviceInfoSize,
 261   OUT VOID                              **DeviceInfo
 262   );
 263
 264 struct _EFI_BLUETOOTH_ATTRIBUTE_PROTOCOL {
 265   EFI_BLUETOOTH_ATTRIBUTE_SEND_REQUEST                        SendRequest;
 266   EFI_BLUETOOTH_ATTRIBUTE_REGISTER_FOR_SERVER_NOTIFICATION    RegisterForServerNotification;
 267   EFI_BLUETOOTH_ATTRIBUTE_GET_SERVICE_INFO                    GetServiceInfo;
 268   EFI_BLUETOOTH_ATTRIBUTE_GET_DEVICE_INFO                     GetDeviceInfo;
 269 };
 270
 271 extern EFI_GUID  gEfiBluetoothAttributeProtocolGuid;
 272 extern EFI_GUID  gEfiBluetoothAttributeServiceBindingProtocolGuid;
 273
 274 #endif