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