GATT_DB - GATT Database Interface and Definitions

Overview

---

Files
file	gatt_database.h
file	gatt_db_app_interface.h

Data Structures
struct	gattDbAttribute_t

Macros
#define	gGattDbInvalidHandleIndex_d
#define	gGattDbInvalidHandle_d

Enumerations
enum	gattCharacteristicPropertiesBitFields_t {   gGattCharPropNone_c, gGattCharPropBroadcast_c, gGattCharPropRead_c, gGattCharPropWriteWithoutRsp_c,   gGattCharPropWrite_c, gGattCharPropNotify_c, gGattCharPropIndicate_c, gGattCharPropAuthSignedWrites_c,   gGattCharPropExtendedProperties_c }
enum	gattAttributePermissionsBitFields_t {   gPermissionNone_c, gPermissionFlagReadable_c, gPermissionFlagReadWithEncryption_c, gPermissionFlagReadWithAuthentication_c,   gPermissionFlagReadWithAuthorization_c, gPermissionFlagWritable_c, gPermissionFlagWriteWithEncryption_c, gPermissionFlagWriteWithAuthentication_c,   gPermissionFlagWriteWithAuthorization_c }
enum	gattDbAccessType_t { gAccessRead_c, gAccessWrite_c, gAccessNotify_c }

Functions
uint16_t	GattDb_GetIndexOfHandle (uint16_t handle)
bleResult_t	GattDb_Init ()
bleResult_t	GattDb_WriteAttribute (uint16_t handle, uint16_t valueLength, uint8_t *aValue)
bleResult_t	GattDb_ReadAttribute (uint16_t handle, uint16_t maxBytes, uint8_t *aOutValue, uint16_t *pOutValueLength)
bleResult_t	GattDb_FindServiceHandle (uint16_t startHandle, bleUuidType_t serviceUuidType, bleUuid_t *pServiceUuid, uint16_t *pOutServiceHandle)
bleResult_t	GattDb_FindCharValueHandleInService (uint16_t serviceHandle, bleUuidType_t characteristicUuidType, bleUuid_t *pCharacteristicUuid, uint16_t *pOutCharValueHandle)
bleResult_t	GattDb_FindCccdHandleForCharValueHandle (uint16_t charValueHandle, uint16_t *pOutCccdHandle)
bleResult_t	GattDb_FindDescriptorHandleForCharValueHandle (uint16_t charValueHandle, bleUuidType_t descriptorUuidType, bleUuid_t *pDescriptorUuid, uint16_t *pOutDescriptorHandle)

Variables
uint16_t	gGattDbAttributeCount_c
gattDbAttribute_t *	gattDatabase

---

Data Structure Documentation

gattDbAttribute_t

struct gattDbAttribute_t

Attribute structure.

Data Fields
uint16_t	handle	The attribute handle - cannot be 0x0000. The attribute handles need not be consecutive, but must be strictly increasing.
uint16_t	permissions	Attribute permissions as defined by the ATT.
uint32_t	uuid	The UUID should be read according to the gattDbAttribute_t.uuidType member: for 2-byte and 4-byte UUIDs, this contains the value of the UUID; for 16-byte UUIDs, this is a pointer to the allocated 16-byte array containing the UUID.
uint8_t *	pValue	A pointer to allocated value array.
uint16_t	valueLength	The size of the value array.
uint16_t	uuidType: 2	Identifies the length of the UUID; values interpreted according to the bleUuidType_t enumeration.
uint16_t	maxVariableValueLength: 10	The maximum length of the attribute value array; if this is set to 0, then the attribute's length is fixed and cannot be changed.

Macro Definition Documentation

gGattDbInvalidHandleIndex_d

#define gGattDbInvalidHandleIndex_d

Special value returned by GattDb_GetIndexOfHandle to signal that an invalid attribute handle was given as parameter.

gGattDbInvalidHandle_d

#define gGattDbInvalidHandle_d

Special value used to mark an invalid attribute handle.

Attribute handles are strictly positive.

Enumeration Type Documentation

gattCharacteristicPropertiesBitFields_t

enum gattCharacteristicPropertiesBitFields_t

Bit fields for Characteristic properties.

Enumerator
gGattCharPropNone_c	No Properties selected.
gGattCharPropBroadcast_c	Characteristic can be broadcast.
gGattCharPropRead_c	Characteristic can be read.
gGattCharPropWriteWithoutRsp_c	Characteristic can be written without response.
gGattCharPropWrite_c	Characteristic can be written with response.
gGattCharPropNotify_c	Characteristic can be notified.
gGattCharPropIndicate_c	Characteristic can be indicated.
gGattCharPropAuthSignedWrites_c	Characteristic can be written with signed data.
gGattCharPropExtendedProperties_c	Extended Characteristic properties.

gattAttributePermissionsBitFields_t

enum gattAttributePermissionsBitFields_t

Bit fields for attribute permissions.

Enumerator
gPermissionNone_c	No permissions selected.
gPermissionFlagReadable_c	Attribute can be read.
gPermissionFlagReadWithEncryption_c	Attribute may be read only if link is encrypted.
gPermissionFlagReadWithAuthentication_c	Attribute may be read only by authenticated peers.
gPermissionFlagReadWithAuthorization_c	Attribute may be read only by authorized peers.
gPermissionFlagWritable_c	Attribute can be written.
gPermissionFlagWriteWithEncryption_c	Attribute may be written only if link is encrypted.
gPermissionFlagWriteWithAuthentication_c	Attribute may be written only by authenticated peers.
gPermissionFlagWriteWithAuthorization_c	Attribute may be written only by authorized peers.

gattDbAccessType_t

enum gattDbAccessType_t

Attribute access type.

Function Documentation

GattDb_GetIndexOfHandle()

uint16_t GattDb_GetIndexOfHandle

(

uint16_t

handle

)

---

Returns the database index for a given attribute handle.

Parameters

[in]

handle

The attribute handle.

Returns

The index of the given attribute in the database or gGattDbInvalidHandleIndex_d.

GattDb_Init()

bleResult_t GattDb_Init

(

)

---

Initializes the GATT database at runtime.

Remarks

This function should be called only once at device start-up. In the current stack implementation, it is called internally by Ble_HostInitialize.

This function executes synchronously.

Returns

gBleSuccess_c or error.

GattDb_WriteAttribute()

bleResult_t GattDb_WriteAttribute	(	uint16_t	handle,
		uint16_t	valueLength,
		uint8_t *	aValue
	)

Writes an attribute from the application level.

This function can be called by the application code to modify an attribute in the database. It should only be used by the application to modify a Characteristic's value based on the application logic (e.g., external sensor readings).

Parameters

[in]	handle	The handle of the attribute to be written.
[in]	valueLength	The number of bytes to be written.
[in]	aValue	The source buffer containing the value to be written.

Returns

gBleSuccess_c or error.

Remarks

This function executes synchronously.

GattDb_ReadAttribute()

bleResult_t GattDb_ReadAttribute	(	uint16_t	handle,
		uint16_t	maxBytes,
		uint8_t *	aOutValue,
		uint16_t *	pOutValueLength
	)

Reads an attribute from the application level.

This function can be called by the application code to read an attribute in the database.

Parameters

[in]	handle	The handle of the attribute to be read.
[in]	maxBytes	The maximum number of bytes to be received.
[out]	aOutValue	The pre-allocated buffer ready to receive the bytes.
[out]	pOutValueLength	The actual number of bytes received.

Returns

gBleSuccess_c or error.

Remarks

This function executes synchronously.

GattDb_FindServiceHandle()

bleResult_t GattDb_FindServiceHandle	(	uint16_t	startHandle,
		bleUuidType_t	serviceUuidType,
		bleUuid_t *	pServiceUuid,
		uint16_t *	pOutServiceHandle
	)

Finds the handle of a Service Declaration with a given UUID inside the database.

Parameters

[in]	startHandle	The handle to start the search. Should be 0x0001 on the first call.
[in]	serviceUuidType	Service UUID type.
[in]	pServiceUuid	Service UUID.
[out]	pOutServiceHandle	Pointer to the service declaration handle to be written.

Returns

gBleSuccess_c or error.

Return values

gBleSuccess_c	Service Declaration found, handle written in pOutCharValueHandle.
gGattDbInvalidHandle_c	Invalid Start Handle.
gGattDbServiceNotFound_c	Service with given UUID not found.

Remarks

This function executes synchronously.

The startHandle should be set to 0x0001 when this function is called for the first time. If multiple Services with the same UUID are expected, then after the first successful call the function may be called again with the startHandle equal to the found service handle plus one.

GattDb_FindCharValueHandleInService()

bleResult_t GattDb_FindCharValueHandleInService	(	uint16_t	serviceHandle,
		bleUuidType_t	characteristicUuidType,
		bleUuid_t *	pCharacteristicUuid,
		uint16_t *	pOutCharValueHandle
	)

Finds the handle of a Characteristic Value with a given UUID inside a Service.

The Service is input by its declaration handle.

Parameters

[in]	serviceHandle	The handle of the Service declaration.
[in]	characteristicUuidType	Characteristic UUID type.
[in]	pCharacteristicUuid	Characteristic UUID.
[out]	pOutCharValueHandle	Pointer to the characteristic value handle to be written.

Returns

gBleSuccess_c or error.

Return values

gBleSuccess_c	Characteristic Value found, handle written in pOutCharValueHandle.
gGattDbInvalidHandle_c	Handle not found or not a Service declaration.
gGattDbCharacteristicNotFound_c	Characteristic Value with given UUID not found.

Remarks

This function executes synchronously.

GattDb_FindCccdHandleForCharValueHandle()

bleResult_t GattDb_FindCccdHandleForCharValueHandle	(	uint16_t	charValueHandle,
		uint16_t *	pOutCccdHandle
	)

Finds the handle of a Characteristic's CCCD given the Characteristic's Value handle.

Parameters

[in]	charValueHandle	The handle of the Service declaration.
[out]	pOutCccdHandle	Pointer to the CCCD handle to be written.

Returns

gBleSuccess_c or error.

Return values

gBleSuccess_c	CCCD found, handle written in pOutCccdHandle.
gGattDbInvalidHandle_c	Invalid Characteristic Value handle.
gGattDbCccdNotFound_c	CCCD not found for this Characteristic.

Remarks

This function executes synchronously.

GattDb_FindDescriptorHandleForCharValueHandle()

bleResult_t GattDb_FindDescriptorHandleForCharValueHandle	(	uint16_t	charValueHandle,
		bleUuidType_t	descriptorUuidType,
		bleUuid_t *	pDescriptorUuid,
		uint16_t *	pOutDescriptorHandle
	)

Finds the handle of a Characteristic Descriptor given the Characteristic's Value handle and Descriptor's UUID.

Parameters

[in]	charValueHandle	The handle of the Service declaration.
[in]	descriptorUuidType	Descriptor's UUID type.
[in]	pDescriptorUuid	Descriptor's UUID.
[out]	pOutDescriptorHandle	Pointer to the Descriptor handle to be written.

Returns

gBleSuccess_c or error.

Return values

gBleSuccess_c	Descriptor found, handle written in pOutDescriptorHandle.
gGattDbInvalidHandle_c	Invalid Characteristic Value handle.
gGattDbDescriptorNotFound_c	Descriptor not found for this Characteristic.

Remarks

This function executes synchronously.

Variable Documentation

gGattDbAttributeCount_c

uint16_t gGattDbAttributeCount_c

The number of attributes in the GATT Database.

gattDatabase

gattDbAttribute_t* gattDatabase

Reference to the GATT database.