1378 lines
60 KiB
C
1378 lines
60 KiB
C
/**
|
||
@headerfile: gatt.h
|
||
$Date:
|
||
$Revision:
|
||
|
||
@mainpage BLE GATT API
|
||
|
||
Description: This file contains Generic Attribute Profile (GATT)
|
||
definitions and prototypes.<BR><BR>
|
||
|
||
SDK_LICENSE
|
||
|
||
*/
|
||
|
||
#ifndef GATT_H
|
||
#define GATT_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C"
|
||
{
|
||
#endif
|
||
|
||
/*********************************************************************
|
||
INCLUDES
|
||
*/
|
||
#include "bcomdef.h"
|
||
#include "OSAL.h"
|
||
|
||
#include "att.h"
|
||
|
||
/*********************************************************************
|
||
CONSTANTS
|
||
*/
|
||
|
||
/** @defgroup GATT_PERMIT_BITMAPS_DEFINES GATT Attribute Access Permissions Bit Fields
|
||
@{
|
||
*/
|
||
|
||
#define GATT_PERMIT_READ 0x01 //!< Attribute is Readable
|
||
#define GATT_PERMIT_WRITE 0x02 //!< Attribute is Writable
|
||
#define GATT_PERMIT_AUTHEN_READ 0x04 //!< Read requires Authentication
|
||
#define GATT_PERMIT_AUTHEN_WRITE 0x08 //!< Write requires Authentication
|
||
#define GATT_PERMIT_AUTHOR_READ 0x10 //!< Read requires Authorization
|
||
#define GATT_PERMIT_AUTHOR_WRITE 0x20 //!< Write requires Authorization
|
||
#define GATT_PERMIT_ENCRYPT_READ 0x40 //!< Read requires Encryption
|
||
#define GATT_PERMIT_ENCRYPT_WRITE 0x80 //!< Write requires Encryption
|
||
|
||
/** @} End GATT_PERMIT_BITMAPS_DEFINES */
|
||
|
||
|
||
/** @defgroup GATT_NUM_PREPARE_WRITES_DEFINES GATT Maximum Number of Prepare Writes
|
||
@{
|
||
*/
|
||
#define PREPARE_QUEUE_STATIC
|
||
#if !defined( GATT_MAX_NUM_PREPARE_WRITES )
|
||
#define GATT_MAX_NUM_PREPARE_WRITES 1//20 //!< GATT Maximum number of attributes that Attribute Server can prepare for writing per Attribute Client
|
||
#endif
|
||
|
||
/** @} End GATT_NUM_PREPARE_WRITES_DEFINES */
|
||
|
||
|
||
/** @defgroup GATT_ENCRYPT_KEY_SIZE_DEFINES GATT Encryption Key Size
|
||
@{
|
||
*/
|
||
|
||
#define GATT_ENCRYPT_KEY_SIZE 16 //!< GATT Encryption Key Size used for encrypting a link
|
||
|
||
/** @} End GATT_ENCRYPT_KEY_SIZE_DEFINES */
|
||
|
||
|
||
/** @defgroup GATT_MAX_ATTR_SIZE_DEFINES GATT Maximum Attribute Value Length
|
||
@{
|
||
*/
|
||
|
||
#define GATT_MAX_ATTR_SIZE 512 //!< GATT Maximum length of an attribute value
|
||
|
||
/** @} End GATT_MAX_ATTR_SIZE_DEFINES */
|
||
|
||
// GATT Maximum number of connections (including loopback)
|
||
#ifndef GATT_MAX_NUM_CONN
|
||
#define GATT_MAX_NUM_CONN ( MAX_NUM_LL_CONN + 1 )
|
||
#endif
|
||
|
||
// GATT Base Method
|
||
#define GATT_BASE_METHOD 0x40
|
||
|
||
// Attribute handle defintions
|
||
#define GATT_INVALID_HANDLE 0x0000 // Invalid attribute handle
|
||
#define GATT_MIN_HANDLE 0x0001 // Minimum attribute handle
|
||
#define GATT_MAX_HANDLE 0xFFFF // Maximum attribute handle
|
||
|
||
/*********************************************************************
|
||
VARIABLES
|
||
*/
|
||
|
||
/*********************************************************************
|
||
MACROS
|
||
*/
|
||
|
||
// Attribute Access Permissions
|
||
#define gattPermitRead( a ) ( (a) & GATT_PERMIT_READ )
|
||
#define gattPermitWrite( a ) ( (a) & GATT_PERMIT_WRITE )
|
||
#define gattPermitAuthenRead( a ) ( (a) & GATT_PERMIT_AUTHEN_READ )
|
||
#define gattPermitAuthenWrite( a ) ( (a) & GATT_PERMIT_AUTHEN_WRITE )
|
||
#define gattPermitAuthorRead( a ) ( (a) & GATT_PERMIT_AUTHOR_READ )
|
||
#define gattPermitAuthorWrite( a ) ( (a) & GATT_PERMIT_AUTHOR_WRITE )
|
||
#define gattPermitEncryptRead( a ) ( (a) & GATT_PERMIT_ENCRYPT_READ )
|
||
#define gattPermitEncryptWrite( a ) ( (a) & GATT_PERMIT_ENCRYPT_WRITE )
|
||
|
||
// Check for different UUID types
|
||
#define gattPrimaryServiceType( t ) ( ATT_CompareUUID( primaryServiceUUID, ATT_BT_UUID_SIZE, \
|
||
(t).uuid, (t).len ) )
|
||
#define gattSecondaryServiceType( t ) ( ATT_CompareUUID( secondaryServiceUUID, ATT_BT_UUID_SIZE, \
|
||
(t).uuid, (t).len ) )
|
||
#define gattCharacterType( t ) ( ATT_CompareUUID( characterUUID, ATT_BT_UUID_SIZE, \
|
||
(t).uuid, (t).len ) )
|
||
#define gattIncludeType( t ) ( ATT_CompareUUID( includeUUID, ATT_BT_UUID_SIZE, \
|
||
(t).uuid, (t).len ) )
|
||
#define gattServiceType( t ) ( gattPrimaryServiceType( (t) ) || \
|
||
gattSecondaryServiceType( (t) ) )
|
||
|
||
/*********************************************************************
|
||
TYPEDEFS
|
||
*/
|
||
|
||
/**
|
||
GATT Read By Type Request format.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint8 discCharsByUUID; //!< Whether this is a GATT Discover Characteristics by UUID sub-procedure
|
||
attReadByTypeReq_t req; //!< Read By Type Request
|
||
} gattReadByTypeReq_t;
|
||
|
||
/**
|
||
GATT Prepare Write Request format.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint16 handle; //!< Handle of the attribute to be written (must be first field)
|
||
uint16 offset; //!< Offset of the first octet to be written
|
||
uint8 len; //!< Length of value
|
||
uint8* pValue; //!< Part of the value of the attribute to be written (must be allocated)
|
||
} gattPrepareWriteReq_t;
|
||
|
||
/**
|
||
GATT Write Long Request format. Do not change the order of the members.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint8 reliable; //!< Whether reliable writes requested (always FALSE for Write Long)
|
||
gattPrepareWriteReq_t req; //!< GATT Prepare Write Request
|
||
uint16 lastOffset; //!< Offset of last Prepare Write Request sent
|
||
} gattWriteLongReq_t;
|
||
|
||
/**
|
||
GATT Reliable Writes Request format. Do not change the order of the members.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint8 reliable; //!< Whether reliable writes requested (always TRUE for Reliable Writes)
|
||
attPrepareWriteReq_t* pReqs; //!< Arrary of Prepare Write Requests (must be allocated)
|
||
uint8 numReqs; //!< Number of Prepare Write Requests
|
||
uint8 index; //!< Index of last Prepare Write Request sent
|
||
uint8 flags; //!< 0x00 - cancel all prepared writes.
|
||
//!< 0x01 - immediately write all pending prepared values.
|
||
} gattReliableWritesReq_t;
|
||
|
||
/**
|
||
GATT Message format. It's a union of all attribute protocol/profile messages
|
||
used between the attribute protocol/profile and upper layer application.
|
||
*/
|
||
typedef union
|
||
{
|
||
// Request messages
|
||
attExchangeMTUReq_t exchangeMTUReq; //!< ATT Exchange MTU Request
|
||
attFindInfoReq_t findInfoReq; //!< ATT Find Information Request
|
||
attFindByTypeValueReq_t findByTypeValueReq; //!< ATT Find By Type Vaue Request
|
||
attReadByTypeReq_t readByTypeReq; //!< ATT Read By Type Request
|
||
attReadReq_t readReq; //!< ATT Read Request
|
||
attReadBlobReq_t readBlobReq; //!< ATT Read Blob Request
|
||
attReadMultiReq_t readMultiReq; //!< ATT Read Multiple Request
|
||
attReadByGrpTypeReq_t readByGrpTypeReq; //!< ATT Read By Group Type Request
|
||
attWriteReq_t writeReq; //!< ATT Write Request
|
||
attPrepareWriteReq_t prepareWriteReq; //!< ATT Prepare Write Request
|
||
attExecuteWriteReq_t executeWriteReq; //!< ATT Execute Write Request
|
||
gattReadByTypeReq_t gattReadByTypeReq; //!< GATT Read By Type Request
|
||
gattWriteLongReq_t gattWriteLongReq; //!< GATT Long Write Request
|
||
gattReliableWritesReq_t gattReliableWritesReq; //!< GATT Reliable Writes Request
|
||
|
||
// Response messages
|
||
attErrorRsp_t errorRsp; //!< ATT Error Response
|
||
attExchangeMTURsp_t exchangeMTURsp; //!< ATT Exchange MTU Response
|
||
attFindInfoRsp_t findInfoRsp; //!< ATT Find Information Response
|
||
attFindByTypeValueRsp_t findByTypeValueRsp; //!< ATT Find By Type Vaue Response
|
||
attReadByTypeRsp_t readByTypeRsp; //!< ATT Read By Type Response
|
||
attReadRsp_t readRsp; //!< ATT Read Response
|
||
attReadBlobRsp_t readBlobRsp; //!< ATT Read Blob Response
|
||
attReadMultiRsp_t readMultiRsp; //!< ATT Read Multiple Response
|
||
attReadByGrpTypeRsp_t readByGrpTypeRsp; //!< ATT Read By Group Type Response
|
||
attPrepareWriteRsp_t prepareWriteRsp; //!< ATT Prepare Write Response
|
||
|
||
// Indication and Notification messages
|
||
attHandleValueNoti_t handleValueNoti; //!< ATT Handle Value Notification
|
||
attHandleValueInd_t handleValueInd; //!< ATT Handle Value Indication
|
||
} gattMsg_t;
|
||
|
||
/**
|
||
GATT OSAL GATT_MSG_EVENT message format. This message is used to forward an
|
||
incoming attribute protocol/profile message up to upper layer application.
|
||
*/
|
||
typedef struct
|
||
{
|
||
osal_event_hdr_t hdr; //!< GATT_MSG_EVENT and status
|
||
uint16 connHandle; //!< Connection message was received on
|
||
uint8 method; //!< Type of message
|
||
gattMsg_t msg; //!< Attribute protocol/profile message
|
||
} gattMsgEvent_t;
|
||
|
||
/**
|
||
GATT Attribute Type format.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint8 len; //!< Length of UUID
|
||
const uint8* uuid; //!< Pointer to UUID
|
||
} gattAttrType_t;
|
||
|
||
/**
|
||
GATT Attribute format.
|
||
*/
|
||
typedef struct attAttribute_t
|
||
{
|
||
gattAttrType_t type; //!< Attribute type (2 or 16 octet UUIDs)
|
||
uint8 permissions; //!< Attribute permissions
|
||
uint16 handle; //!< Attribute handle - assigned internally by attribute server
|
||
uint8* const pValue; //!< Attribute value - encoding of the octet array is defined in
|
||
//!< the applicable profile. The maximum length of an attribute
|
||
//!< value shall be 512 octets.
|
||
} gattAttribute_t;
|
||
|
||
/**
|
||
GATT Service format.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint16 numAttrs; //!< Number of attributes in attrs
|
||
|
||
/** Array of attribute records.
|
||
NOTE: The list must start with a Service attribute followed by
|
||
all attributes associated with this Service attribute.
|
||
*/
|
||
gattAttribute_t* attrs;
|
||
} gattService_t;
|
||
|
||
/*********************************************************************
|
||
VARIABLES
|
||
*/
|
||
|
||
/*********************************************************************
|
||
API FUNCTIONS
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
GATT Client Public APIs
|
||
*/
|
||
|
||
/**
|
||
@defgroup GATT_CLIENT_API GATT Client API Functions
|
||
|
||
@{
|
||
*/
|
||
|
||
/**
|
||
@brief Initialize the Generic Attribute Profile Client.
|
||
|
||
@return SUCCESS
|
||
*/
|
||
extern bStatus_t GATT_InitClient( void );
|
||
|
||
/**
|
||
@brief Register to receive incoming ATT Indications or Notifications
|
||
of attribute values.
|
||
|
||
@param taskId ? task to forward indications or notifications to
|
||
|
||
@return void
|
||
*/
|
||
extern void GATT_RegisterForInd( uint8 taskId );
|
||
|
||
/**
|
||
@brief The Prepare Write Request is used to request the server to
|
||
prepare to write the value of an attribute.
|
||
|
||
Note: This function is needed only for GATT testing.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_PrepareWriteReq( uint16 connHandle, attPrepareWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief The Execute Write Request is used to request the server to
|
||
write or cancel the write of all the prepared values currently
|
||
held in the prepare queue from this client.
|
||
|
||
Note: This function is needed only for GATT testing.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ExecuteWriteReq( uint16 connHandle, attExecuteWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@}
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
GATT Server Public APIs
|
||
*/
|
||
|
||
/**
|
||
@defgroup GATT_SERVER_API GATT Server API Functions
|
||
|
||
@{
|
||
*/
|
||
|
||
/**
|
||
@brief Initialize the Generic Attribute Profile Server.
|
||
|
||
@return SUCCESS
|
||
*/
|
||
extern bStatus_t GATT_InitServer( void );
|
||
|
||
/**
|
||
@brief Register a service attribute list with the GATT Server. A service
|
||
is composed of characteristics or references to other services.
|
||
Each characteristic contains a value and may contain optional
|
||
information about the value. There are two types of services:
|
||
primary service and secondary service.
|
||
|
||
A service definition begins with a service declaration and ends
|
||
before the next service declaration or the maximum Attribute Handle.
|
||
|
||
A characteristic definition begins with a characteristic declaration
|
||
and ends before the next characteristic or service declaration or
|
||
maximum Attribute Handle.
|
||
|
||
The attribute server will only keep a pointer to the attribute
|
||
list, so the calling application will have to maintain the code
|
||
and RAM associated with this list.
|
||
|
||
@param pService - pointer to service attribute list to be registered
|
||
|
||
@return SUCCESS: Service registered successfully.<BR>
|
||
INVALIDPARAMETER: Invalid service field.<BR>
|
||
FAILURE: Not enough attribute handles available.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
*/
|
||
extern bStatus_t GATT_RegisterService( gattService_t* pService );
|
||
|
||
/**
|
||
@brief Deregister a service attribute list with the GATT Server.
|
||
|
||
NOTE: It's the caller's responsibility to free the service attribute
|
||
list returned from this API.
|
||
|
||
@param handle - handle of service to be deregistered
|
||
@param pService - pointer to deregistered service (to be returned)
|
||
|
||
@return SUCCESS: Service deregistered successfully.<BR>
|
||
FAILURE: Service not found.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DeregisterService( uint16 handle, gattService_t* pService );
|
||
|
||
/**
|
||
@brief Register to receive incoming ATT Requests.
|
||
|
||
@param taskId ? task to forward requests to
|
||
|
||
@return void
|
||
*/
|
||
extern void GATT_RegisterForReq( uint8 taskId );
|
||
|
||
/**
|
||
@brief Verify the permissions of an attribute for reading.
|
||
|
||
@param connHandle - connection to use
|
||
@param permissions - attribute permissions
|
||
|
||
@return SUCCESS: Attribute can be read.<BR>
|
||
ATT_ERR_READ_NOT_PERMITTED: Attribute cannot be read.<BR>
|
||
ATT_ERR_INSUFFICIENT_AUTHEN: Attribute requires authentication.<BR>
|
||
ATT_ERR_INSUFFICIENT_KEY_SIZE: Key Size used for encrypting is insufficient.<BR>
|
||
ATT_ERR_INSUFFICIENT_ENCRYPT: Attribute requires encryption.<BR>
|
||
*/
|
||
extern bStatus_t GATT_VerifyReadPermissions( uint16 connHandle, uint8 permissions );
|
||
|
||
/**
|
||
@brief Verify the permissions of an attribute for writing.
|
||
|
||
@param connHandle - connection to use
|
||
@param permissions - attribute permissions
|
||
@param pReq - pointer to write request
|
||
|
||
@return SUCCESS: Attribute can be written.<BR>
|
||
ATT_ERR_READ_NOT_PERMITTED: Attribute cannot be written.<BR>
|
||
ATT_ERR_INSUFFICIENT_AUTHEN: Attribute requires authentication.<BR>
|
||
ATT_ERR_INSUFFICIENT_KEY_SIZE: Key Size used for encrypting is insufficient.<BR>
|
||
ATT_ERR_INSUFFICIENT_ENCRYPT: Attribute requires encryption.<BR>
|
||
*/
|
||
extern bStatus_t GATT_VerifyWritePermissions( uint16 connHandle, uint8 permissions, attWriteReq_t* pReq );
|
||
|
||
/**
|
||
@brief Send out a Service Changed Indication.
|
||
|
||
@param connHandle - connection to use
|
||
@param taskId - task to be notified of confirmation
|
||
|
||
@return SUCCESS: Indication was sent successfully.<BR>
|
||
FAILURE: Service Changed attribute not found.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A confirmation is pending with this client.<BR>
|
||
*/
|
||
extern uint8 GATT_ServiceChangedInd( uint16 connHandle, uint8 taskId );
|
||
|
||
/**
|
||
@brief Find the attribute record for a given handle and UUID.
|
||
|
||
@param startHandle - first handle to look for
|
||
@param endHandle - last handle to look for
|
||
@param pUUID - pointer to UUID to look for
|
||
@param len - length of UUID
|
||
@param pHandle - handle of owner of attribute (to be returned)
|
||
|
||
@return Pointer to attribute record. NULL, otherwise.
|
||
*/
|
||
extern gattAttribute_t* GATT_FindHandleUUID( uint16 startHandle, uint16 endHandle, const uint8* pUUID,
|
||
uint16 len, uint16* pHandle );
|
||
/**
|
||
@brief Find the attribute record for a given handle
|
||
|
||
@param handle - handle to look for
|
||
@param pHandle - handle of owner of attribute (to be returned)
|
||
|
||
@return Pointer to attribute record. NULL, otherwise.
|
||
*/
|
||
extern gattAttribute_t* GATT_FindHandle( uint16 handle, uint16* pHandle );
|
||
|
||
/**
|
||
@brief Find the next attribute of the same type for a given attribute.
|
||
|
||
@param pAttr - pointer to attribute to find a next for
|
||
@param endHandle - last handle to look for
|
||
@param service - handle of owner service
|
||
@param pLastHandle - handle of last attribute (to be returned)
|
||
|
||
@return Pointer to next attribute record. NULL, otherwise.
|
||
*/
|
||
extern gattAttribute_t* GATT_FindNextAttr( gattAttribute_t* pAttr, uint16 endHandle,
|
||
uint16 service, uint16* pLastHandle );
|
||
/**
|
||
@brief Get the number of attributes for a given service
|
||
|
||
@param handle - service handle to look for
|
||
|
||
@return Number of attributes. 0, otherwise.
|
||
*/
|
||
extern uint16 GATT_ServiceNumAttrs( uint16 handle );
|
||
|
||
/**
|
||
@}
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
GATT Server Sub-Procedure APIs
|
||
*/
|
||
|
||
/**
|
||
@defgroup GATT_SERVER_SUB_PROCEDURE_API GATT Server Sub-Procedure API Functions
|
||
|
||
@{
|
||
*/
|
||
|
||
/**
|
||
@brief This sub-procedure is used when a server is configured to
|
||
indicate a characteristic value to a client and expects an
|
||
attribute protocol layer acknowledgement that the indication
|
||
was successfully received.
|
||
|
||
The ATT Handle Value Indication is used in this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be ATT_HANDLE_VALUE_CFM.
|
||
|
||
Note: This sub-procedure is complete when ATT_HANDLE_VALUE_CFM
|
||
(with SUCCESS or bleTimeout status) is received by the
|
||
calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pInd - pointer to indication to be sent
|
||
@param authenticated - whether an authenticated link is required
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Indication was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A confirmation is pending with this client.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_Indication( uint16 connHandle, attHandleValueInd_t* pInd,
|
||
uint8 authenticated, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used when a server is configured to
|
||
notify a characteristic value to a client without expecting
|
||
any attribute protocol layer acknowledgement that the
|
||
notification was successfully received.
|
||
|
||
The ATT Handle Value Notification is used in this sub-procedure.
|
||
|
||
Note: A notification may be sent at any time and does not
|
||
invoke a confirmation.
|
||
|
||
No confirmation will be sent to the calling application task for
|
||
this sub-procedure.
|
||
|
||
@param connHandle - connection to use
|
||
@param pNoti - pointer to notification to be sent
|
||
@param authenticated - whether an authenticated link is required
|
||
|
||
@return SUCCESS: Notification was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_Notification( uint16 connHandle, attHandleValueNoti_t* pNoti,
|
||
uint8 authenticated );
|
||
/**
|
||
@}
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
GATT Client Sub-Procedure APIs
|
||
*/
|
||
|
||
/**
|
||
@defgroup GATT_CLIENT_SUB_PROCEDURE_API GATT Client Sub-Procedure API Functions
|
||
|
||
@{
|
||
*/
|
||
|
||
/**
|
||
@brief This sub-procedure is used by the client to set the ATT_MTU
|
||
to the maximum possible value that can be supported by both
|
||
devices when the client supports a value greater than the
|
||
default ATT_MTU for the Attribute Protocol. This sub-procedure
|
||
shall only be initiated once during a connection.
|
||
|
||
The ATT Exchange MTU Request is used by this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_EXCHANGE_MTU_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_EXCHANGE_MTU_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ExchangeMTU( uint16 connHandle, attExchangeMTUReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used by a client to discover all
|
||
the primary services on a server.
|
||
|
||
The ATT Read By Group Type Request is used with the Attribute
|
||
Type parameter set to the UUID for "Primary Service". The
|
||
Starting Handle is set to 0x0001 and the Ending Handle is
|
||
set to 0xFFFF.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BY_GRP_TYPE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BY_GRP_TYPE_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application
|
||
task.
|
||
|
||
@param connHandle - connection to use
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DiscAllPrimaryServices( uint16 connHandle, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used by a client to discover a specific
|
||
primary service on a server when only the Service UUID is
|
||
known. The primary specific service may exist multiple times
|
||
on a server. The primary service being discovered is identified
|
||
by the service UUID.
|
||
|
||
The ATT Find By Type Value Request is used with the Attribute
|
||
Type parameter set to the UUID for "Primary Service" and the
|
||
Attribute Value set to the 16-bit Bluetooth UUID or 128-bit
|
||
UUID for the specific primary service. The Starting Handle shall
|
||
be set to 0x0001 and the Ending Handle shall be set to 0xFFFF.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_FIND_BY_TYPE_VALUE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_FIND_BY_TYPE_VALUE_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pValue - pointer to value to look for
|
||
@param len - length of value
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DiscPrimaryServiceByUUID( uint16 connHandle, uint8* pValue,
|
||
uint8 len, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used by a client to find include
|
||
service declarations within a service definition on a
|
||
server. The service specified is identified by the service
|
||
handle range.
|
||
|
||
The ATT Read By Type Request is used with the Attribute
|
||
Type parameter set to the UUID for "Included Service". The
|
||
Starting Handle is set to starting handle of the specified
|
||
service and the Ending Handle is set to the ending handle
|
||
of the specified service.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BY_TYPE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param startHandle - starting handle
|
||
@param endHandle - end handle
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_FindIncludedServices( uint16 connHandle, uint16 startHandle,
|
||
uint16 endHandle, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used by a client to find all the
|
||
characteristic declarations within a service definition on
|
||
a server when only the service handle range is known. The
|
||
service specified is identified by the service handle range.
|
||
|
||
The ATT Read By Type Request is used with the Attribute Type
|
||
parameter set to the UUID for "Characteristic". The Starting
|
||
Handle is set to starting handle of the specified service and
|
||
the Ending Handle is set to the ending handle of the specified
|
||
service.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BY_TYPE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param startHandle - starting handle
|
||
@param endHandle - end handle
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DiscAllChars( uint16 connHandle, uint16 startHandle,
|
||
uint16 endHandle, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used by a client to discover service
|
||
characteristics on a server when only the service handle
|
||
ranges are known and the characteristic UUID is known.
|
||
The specific service may exist multiple times on a server.
|
||
The characteristic being discovered is identified by the
|
||
characteristic UUID.
|
||
|
||
The ATT Read By Type Request is used with the Attribute Type
|
||
is set to the UUID for "Characteristic" and the Starting
|
||
Handle and Ending Handle parameters is set to the service
|
||
handle range.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BY_TYPE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DiscCharsByUUID( uint16 connHandle, attReadByTypeReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used by a client to find all the
|
||
characteristic descriptor<6F>s Attribute Handles and Attribute
|
||
Types within a characteristic definition when only the
|
||
characteristic handle range is known. The characteristic
|
||
specified is identified by the characteristic handle range.
|
||
|
||
The ATT Find Information Request is used with the Starting
|
||
Handle set to starting handle of the specified characteristic
|
||
and the Ending Handle set to the ending handle of the specified
|
||
characteristic. The UUID Filter parameter is NULL (zero length).
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_FIND_INFO_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_FIND_INFO_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param startHandle - starting handle
|
||
@param endHandle - end handle
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_DiscAllCharDescs( uint16 connHandle, uint16 startHandle,
|
||
uint16 endHandle, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used to read a Characteristic Value
|
||
from a server when the client knows the Characteristic Value
|
||
Handle. The ATT Read Request is used with the Attribute Handle
|
||
parameter set to the Characteristic Value Handle. The Read
|
||
Response returns the Characteristic Value in the Attribute
|
||
Value parameter.
|
||
|
||
The Read Response only contains a Characteristic Value that
|
||
is less than or equal to (ATT_MTU ? 1) octets in length. If
|
||
the Characteristic Value is greater than (ATT_MTU ? 1) octets
|
||
in length, the Read Long Characteristic Value procedure may
|
||
be used if the rest of the Characteristic Value is required.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_READ_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadCharValue( uint16 connHandle, attReadReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to read a Characteristic Value
|
||
from a server when the client only knows the characteristic
|
||
UUID and does not know the handle of the characteristic.
|
||
|
||
The ATT Read By Type Request is used to perform the sub-procedure.
|
||
The Attribute Type is set to the known characteristic UUID and
|
||
the Starting Handle and Ending Handle parameters shall be set
|
||
to the range over which this read is to be performed. This is
|
||
typically the handle range for the service in which the
|
||
characteristic belongs.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT messages.
|
||
The type of the message will be either ATT_READ_BY_TYPE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadUsingCharUUID( uint16 connHandle, attReadByTypeReq_t* pReq, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used to read a Characteristic Value from
|
||
a server when the client knows the Characteristic Value Handle
|
||
and the length of the Characteristic Value is longer than can
|
||
be sent in a single Read Response Attribute Protocol message.
|
||
|
||
The ATT Read Blob Request is used in this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BLOB_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BLOB_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadLongCharValue( uint16 connHandle, attReadBlobReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to read multiple Characteristic Values
|
||
from a server when the client knows the Characteristic Value
|
||
Handles. The Attribute Protocol Read Multiple Requests is used
|
||
with the Set Of Handles parameter set to the Characteristic Value
|
||
Handles. The Read Multiple Response returns the Characteristic
|
||
Values in the Set Of Values parameter.
|
||
|
||
The ATT Read Multiple Request is used in this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_READ_MULTI_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_MULTI_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadMultiCharValues( uint16 connHandle, attReadMultiReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a Characteristic Value
|
||
to a server when the client knows the Characteristic Value
|
||
Handle and the client does not need an acknowledgement that
|
||
the write was successfully performed. This sub-procedure
|
||
only writes the first (ATT_MTU ? 3) octets of a Characteristic
|
||
Value. This sub-procedure can not be used to write a long
|
||
characteristic; instead the Write Long Characteristic Values
|
||
sub-procedure should be used.
|
||
|
||
The ATT Write Command is used for this sub-procedure. The
|
||
Attribute Handle parameter shall be set to the Characteristic
|
||
Value Handle. The Attribute Value parameter shall be set to
|
||
the new Characteristic Value.
|
||
|
||
No response will be sent to the calling application task for this
|
||
sub-procedure. If the Characteristic Value write request is the
|
||
wrong size, or has an invalid value as defined by the profile,
|
||
then the write will not succeed and no error will be generated
|
||
by the server.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to command to be sent
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_WriteNoRsp( uint16 connHandle, attWriteReq_t* pReq );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a Characteristic Value
|
||
to a server when the client knows the Characteristic Value
|
||
Handle and the ATT Bearer is not encrypted. This sub-procedure
|
||
shall only be used if the Characteristic Properties authenticated
|
||
bit is enabled and the client and server device share a bond as
|
||
defined in the GAP.
|
||
|
||
This sub-procedure only writes the first (ATT_MTU ? 15) octets
|
||
of an Attribute Value. This sub-procedure cannot be used to
|
||
write a long Attribute.
|
||
|
||
The ATT Write Command is used for this sub-procedure. The
|
||
Attribute Handle parameter shall be set to the Characteristic
|
||
Value Handle. The Attribute Value parameter shall be set to
|
||
the new Characteristic Value authenticated by signing the
|
||
value, as defined in the Security Manager.
|
||
|
||
No response will be sent to the calling application task for this
|
||
sub-procedure. If the authenticated Characteristic Value that is
|
||
written is the wrong size, or has an invalid value as defined by
|
||
the profile, or the signed value does not authenticate the client,
|
||
then the write will not succeed and no error will be generated by
|
||
the server.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to command to be sent
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleLinkEncrypted: Connection is already encrypted.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_SignedWriteNoRsp( uint16 connHandle, attWriteReq_t* pReq );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a characteristic value
|
||
to a server when the client knows the characteristic value
|
||
handle. This sub-procedure only writes the first (ATT_MTU-3)
|
||
octets of a characteristic value. This sub-procedure can not
|
||
be used to write a long attribute; instead the Write Long
|
||
Characteristic Values sub-procedure should be used.
|
||
|
||
The ATT Write Request is used in this sub-procedure. The
|
||
Attribute Handle parameter shall be set to the Characteristic
|
||
Value Handle. The Attribute Value parameter shall be set to
|
||
the new characteristic.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_WRITE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_WRITE_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_WriteCharValue( uint16 connHandle, attWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a Characteristic Value to
|
||
a server when the client knows the Characteristic Value Handle
|
||
but the length of the Characteristic Value is longer than can
|
||
be sent in a single Write Request Attribute Protocol message.
|
||
|
||
The ATT Prepare Write Request and Execute Write Request are
|
||
used to perform this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_PREPARE_WRITE_RSP,
|
||
ATT_EXECUTE_WRITE_RSP or ATT_ERROR_RSP (if an error occurred on
|
||
the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP
|
||
(with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS
|
||
or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status)
|
||
is received by the calling application task.
|
||
|
||
Note: The 'pReq->pValue' pointer will be freed when the sub-procedure
|
||
is complete.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_WriteLongCharValue( uint16 connHandle, gattPrepareWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a Characteristic Value to
|
||
a server when the client knows the Characteristic Value Handle,
|
||
and assurance is required that the correct Characteristic Value
|
||
is going to be written by transferring the Characteristic Value
|
||
to be written in both directions before the write is performed.
|
||
This sub-procedure can also be used when multiple values must
|
||
be written, in order, in a single operation.
|
||
|
||
The sub-procedure has two phases, the first phase prepares the
|
||
characteristic values to be written. Once this is complete,
|
||
the second phase performs the execution of all of the prepared
|
||
characteristic value writes on the server from this client.
|
||
|
||
In the first phase, the ATT Prepare Write Request is used.
|
||
In the second phase, the attribute protocol Execute Write
|
||
Request is used.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_PREPARE_WRITE_RSP,
|
||
ATT_EXECUTE_WRITE_RSP or ATT_ERROR_RSP (if an error occurred on
|
||
the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP
|
||
(with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS
|
||
or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status)
|
||
is received by the calling application task.
|
||
|
||
Note: The 'pReqs' pointer will be freed when the sub-procedure is
|
||
complete.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReqs - pointer to requests to be sent (must be allocated)
|
||
@param numReqs - number of requests in pReq
|
||
@param flags - execute write request flags
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReliableWrites( uint16 connHandle, attPrepareWriteReq_t* pReqs,
|
||
uint8 numReqs, uint8 flags, uint8 taskId );
|
||
/**
|
||
@brief This sub-procedure is used to read a characteristic descriptor
|
||
from a server when the client knows the characteristic descriptor
|
||
declaration<6F>s Attribute handle.
|
||
|
||
The ATT Read Request is used for this sub-procedure. The Read
|
||
Request is used with the Attribute Handle parameter set to the
|
||
characteristic descriptor handle. The Read Response returns the
|
||
characteristic descriptor value in the Attribute Value parameter.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_READ_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadCharDesc( uint16 connHandle, attReadReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to read a characteristic descriptor
|
||
from a server when the client knows the characteristic descriptor
|
||
declaration<6F>s Attribute handle and the length of the characteristic
|
||
descriptor declaration is longer than can be sent in a single Read
|
||
Response attribute protocol message.
|
||
|
||
The ATT Read Blob Request is used to perform this sub-procedure.
|
||
The Attribute Handle parameter shall be set to the characteristic
|
||
descriptor handle. The Value Offset parameter shall be the offset
|
||
within the characteristic descriptor to be read.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_READ_BLOB_RSP or
|
||
ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_READ_BLOB_RSP
|
||
(with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP
|
||
(with SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_ReadLongCharDesc( uint16 connHandle, attReadBlobReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a characteristic
|
||
descriptor value to a server when the client knows the
|
||
characteristic descriptor handle.
|
||
|
||
The ATT Write Request is used for this sub-procedure. The
|
||
Attribute Handle parameter shall be set to the characteristic
|
||
descriptor handle. The Attribute Value parameter shall be
|
||
set to the new characteristic descriptor value.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive an OSAL GATT_MSG_EVENT message.
|
||
The type of the message will be either ATT_WRITE_RSP
|
||
or ATT_ERROR_RSP (if an error occurred on the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_WRITE_RSP
|
||
(with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with
|
||
SUCCESS status) is received by the calling application task.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.<BR>
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_WriteCharDesc( uint16 connHandle, attWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@brief This sub-procedure is used to write a Characteristic Value to
|
||
a server when the client knows the Characteristic Value Handle
|
||
but the length of the Characteristic Value is longer than can
|
||
be sent in a single Write Request Attribute Protocol message.
|
||
|
||
The ATT Prepare Write Request and Execute Write Request are
|
||
used to perform this sub-procedure.
|
||
|
||
If the return status from this function is SUCCESS, the calling
|
||
application task will receive multiple OSAL GATT_MSG_EVENT messages.
|
||
The type of the messages will be either ATT_PREPARE_WRITE_RSP,
|
||
ATT_EXECUTE_WRITE_RSP or ATT_ERROR_RSP (if an error occurred on
|
||
the server).
|
||
|
||
Note: This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP
|
||
(with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS
|
||
or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status)
|
||
is received by the calling application task.
|
||
|
||
Note: The 'pReq->pValue' pointer will be freed when the sub-procedure
|
||
is complete.
|
||
|
||
@param connHandle - connection to use
|
||
@param pReq - pointer to request to be sent
|
||
@param taskId - task to be notified of response
|
||
|
||
@return SUCCESS: Request was sent successfully.<BR>
|
||
INVALIDPARAMETER: Invalid connection handle or request field.v
|
||
MSG_BUFFER_NOT_AVAIL: No HCI buffer is available.<BR>
|
||
bleNotConnected: Connection is down.<BR>
|
||
blePending: A response is pending with this server.<BR>
|
||
bleMemAllocError: Memory allocation error occurred.<BR>
|
||
bleTimeout: Previous transaction timed out.<BR>
|
||
*/
|
||
extern bStatus_t GATT_WriteLongCharDesc( uint16 connHandle, gattPrepareWriteReq_t* pReq, uint8 taskId );
|
||
|
||
/**
|
||
@}
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
GATT Flow Control APIs
|
||
*/
|
||
|
||
/**
|
||
@defgroup GATT_FLOW_CTRL_API GATT Flow Control API Functions
|
||
|
||
@{
|
||
*/
|
||
|
||
/**
|
||
@brief This API is used by the Application to turn flow control on
|
||
or off for GATT messages sent from the Host to the Application.
|
||
|
||
Note: If the flow control is enabled then the Application must
|
||
call the GATT_AppCompletedMsg() API when it completes
|
||
processing an incoming GATT message.
|
||
|
||
@param flowCtrlMode ? flow control mode: TRUE or FALSE
|
||
|
||
@return void
|
||
*/
|
||
extern void GATT_SetHostToAppFlowCtrl( uint16 hostBufSize,uint8 flowCtrlMode );
|
||
|
||
/**
|
||
@brief This API is used by the Application to notify GATT that
|
||
the processing of a message has been completed.
|
||
|
||
@param pMsg ? pointer to the processed GATT message
|
||
|
||
@return void
|
||
*/
|
||
extern void GATT_AppCompletedMsg( gattMsgEvent_t* pMsg );
|
||
|
||
/**
|
||
@}
|
||
*/
|
||
|
||
/* -------------------------------------------------------------------
|
||
Internal API - This function is only called from GATT Qualification modules.
|
||
*/
|
||
|
||
/**
|
||
@internal
|
||
|
||
@brief Set the next available attribute handle.
|
||
|
||
@param handle - next attribute handle.
|
||
|
||
@return none
|
||
*/
|
||
extern void GATT_SetNextHandle( uint16 handle );
|
||
|
||
/* -------------------------------------------------------------------
|
||
TASK API - These functions must only be called by OSAL.
|
||
*/
|
||
|
||
/**
|
||
@internal
|
||
|
||
@brief GATT Task initialization function.
|
||
|
||
@param taskId - GATT task ID.
|
||
|
||
@return void
|
||
*/
|
||
extern void GATT_Init( uint8 taskId );
|
||
|
||
/**
|
||
@internal
|
||
|
||
@brief GATT Task event processing function.
|
||
|
||
@param taskId - GATT task ID
|
||
@param events - GATT events.
|
||
|
||
@return events not processed
|
||
*/
|
||
extern uint16 GATT_ProcessEvent( uint8 taskId, uint16 events );
|
||
|
||
/*********************************************************************
|
||
*********************************************************************/
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* GATT_H */
|