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