mirror/MuditaOS
1
0
Fork 0
mirror of https://github.com/mudita/MuditaOS.git synced 2026-07-04 13:17:08 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
f7c8af86c858cd03142f62d582ef6461ba2168db
MuditaOS/module-bluetooth/lib/Bluetopia/profiles/BAS/include/BASAPI.h

409 lines
22 KiB
C
Raw Blame History

/*
* Copyright 2012 - 2014 Stonestreet One.
* All Rights Reserved.
* Author: Zahid Khan
*** MODIFICATION HISTORY ****************************************************
*
* mm/dd/yy F. Lastname Description of Modification
* -------- ----------- ------------------------------------------------
* 06/22/12 Z. Khan Initial creation.
****************************************************************************
*/
/**
* @file BASAPI.h
*
* @brief Stonestreet One Bluetooth Battery Service (GATT based)
* API Type Definitions, Constants, and Prototypes.
* To use any of the following API's,
* include the following declaration in your application.
* @code
* #include "SS1BTBAS.h"
* @endcode
*
* The Battery Service programming interface defines the protocols and procedures to be used to implement Battery Service capabilities.
* ============================================================================
*/
#ifndef __BASAPIH__
#define __BASAPIH__
#include "SS1BTPS.h" /*! Bluetooth Stack API Prototypes/Constants. */
#include "SS1BTGAT.h" /*! Bluetooth Stack GATT API Prototypes/Constants. */
#include "BASTypes.h" /*! Battery Service Types/Constants */
/*! Error Return Codes.
* Error Codes that are smaller than these (less than -1000) are
* related to the Bluetooth Protocol Stack itself (see BTERRORS.H).
*/
#define BAS_ERROR_INVALID_PARAMETER (-1000)
#define BAS_ERROR_INVALID_BLUETOOTH_STACK_ID (-1001)
#define BAS_ERROR_INSUFFICIENT_RESOURCES (-1002)
#define BAS_ERROR_SERVICE_ALREADY_REGISTERED (-1003)
#define BAS_ERROR_INVALID_INSTANCE_ID (-1004)
#define BAS_ERROR_MALFORMATTED_DATA (-1005)
#define BAS_ERROR_MAXIMUM_NUMBER_OF_INSTANCES_REACHED (-1006)
#define BAS_ERROR_UNKNOWN_ERROR (-1007)
/*! The Characteristic Presentation Format descriptor defines the
* format of the Characteristic Value.
* The Format field determines how a single value contained in the
* Characteristic Value is formatted.
* The Exponent field is used with interger data types to determine
* how the Characteristic Value is further formatted.
* The actual value = Characteristic Value * 10^Exponent.
* Unit specifies Unit of this attribute UUID
* The Name Space field is used to indentify the organization that
* is responsible for defining the enumerations for the description
* field.
* The Description is an enumerated value from the organization
* identified by the Name Space field.
*/
typedef struct _tagBAS_Presentation_Format_Data_t
{
Byte_t Format;
Byte_t Exponent;
Word_t Unit;
Byte_t NameSpace;
Word_t Description;
} BAS_Presentation_Format_Data_t;
#define BAS_PRESENTATION_FORMAT_DATA_SIZE (sizeof(BAS_Presentation_Format_Data_t))
/*! The following define the valid Read Request types that a server
* may receive in a etBAS_Server_Read_Client_Configuration_Request or
* etBAS_Server_Client_Configuration_Update event.
* \note For each event it is up to the application to return (or
* write) the correct Client Configuration descriptor based
* on this value.
*/
typedef enum _tagBAS_Characteristic_Type_t
{
ctBatteryLevel
} BAS_Characteristic_Type_t;
/*! The following enumeration covers all the events generated by the
* BAS Profile. These are used to determine the type of each event
* generated, and to ensure the proper union element is accessed for
* the BAS_Event_Data_t structure.
*/
typedef enum _tagBAS_Event_Type_t
{
etBAS_Server_Read_Client_Configuration_Request, /*!< Dispatched when a BAS Client requests read client configuration to a registered BAS Server. */
etBAS_Server_Client_Configuration_Update, /*!< Dispatched when a BAS Client requests to update client configuration to a registered BAS Server. */
etBAS_Server_Read_Battery_Level_Request /*!< Dispatched when a BAS Client requests read battery level to a registered BAS Server. */
} BAS_Event_Type_t;
/*! The following structure contains the Handles that will need to be
* cached by a BAS client in order to only do service discovery once.
*/
typedef struct _tagBAS_Client_Information_t
{
Word_t Battery_Level;
Word_t Battery_Level_Client_Configuration;
Word_t Battery_Level_Presentation_Format;
} BAS_Client_Information_t;
#define BAS_CLIENT_INFORMATION_DATA_SIZE (sizeof(BAS_Client_Information_t))
/*! The following structure contains all of the per Client data that
* will need to be stored by a BAS Server.
*/
typedef struct _tagBAS_Server_Information_t
{
Word_t Battery_Level_Client_Configuration;
} BAS_Server_Information_t;
#define BAS_SERVER_INFORMATION_DATA_SIZE (sizeof(BAS_Server_Information_t))
/*! The following BAS Profile Event is dispatched to a BAS Server when
* a BAS Client is attempting to read a descriptor. The
* ConnectionID, ConnectionType, and RemoteDevice specifiy the Client
* that is making the request. The DescriptorType specifies the
* Descriptor that the Client is attempting to read. The
* TransactionID specifies the TransactionID of the request, this can
* be used when responding to the request using the
* BAS_Client_Configuration_Read_Response() API function.
*/
typedef struct _tagBAS_Read_Client_Configuration_Data_t
{
unsigned int InstanceID;
unsigned int ConnectionID;
unsigned int TransactionID;
GATT_Connection_Type_t ConnectionType;
BD_ADDR_t RemoteDevice;
BAS_Characteristic_Type_t ClientConfigurationType;
} BAS_Read_Client_Configuration_Data_t;
#define BAS_READ_CLIENT_CONFIGURATION_DATA_SIZE (sizeof(BAS_Read_Client_Configuration_Data_t))
/*! The following BAS Profile Event is dispatched to a BAS Server when
* a BAS Client has written a Client Configuration descriptor. The
* ConnectionID, ConnectionType, and RemoteDevice specifiy the Client
* that is making the update. The ClientConfigurationType specifies
* the Descriptor that the Client is writing. The final member is
* the new Client Configuration for the specified characteristic.
*/
typedef struct _tagBAS_Client_Configuration_Update_Data_t
{
unsigned int InstanceID;
unsigned int ConnectionID;
GATT_Connection_Type_t ConnectionType;
BD_ADDR_t RemoteDevice;
BAS_Characteristic_Type_t ClientConfigurationType;
Boolean_t Notify;
} BAS_Client_Configuration_Update_Data_t;
#define BAS_CLIENT_CONFIGURATION_UPDATE_DATA_SIZE (sizeof(BAS_Client_Configuration_Update_Data_t))
/*! The following BAS Profile Event is dispatched to a BAS Server when
* a BAS Client is attempting to read the battery level. The
* ConnectionID and ConnectionType specifiy the Client that is making
* the request. The TransactionID specifies the TransactionID of the
* request, this can be used when responding to the request using
* the BAS_Battery_Level_Read_Request_Response() and
* BAS_Battery_Level_Read_Request_Error_Response API functions.
*/
typedef struct _tagBAS_Read_Battery_Level_Data_t
{
unsigned int InstanceID;
unsigned int ConnectionID;
unsigned int TransactionID;
GATT_Connection_Type_t ConnectionType;
BD_ADDR_t RemoteDevice;
} BAS_Read_Battery_Level_Data_t;
#define BAS_READ_BATTERY_LEVEL_DATA_SIZE (sizeof(BAS_Read_Battery_Level_Data_t))
/*! The following structure represents the container structure for
* holding all BAS Profile Event Data. This structure is received
* for each event generated. The Event_Data_Type member is used to
* determine the appropriate union member element to access the
* contained data. The Event_Data_Size member contains the total
* size of the data contained in this event.
*/
typedef struct _tagBAS_Event_Data_t
{
BAS_Event_Type_t Event_Data_Type;
Word_t Event_Data_Size;
union
{
BAS_Read_Client_Configuration_Data_t *BAS_Read_Client_Configuration_Data;
BAS_Client_Configuration_Update_Data_t *BAS_Client_Configuration_Update_Data;
BAS_Read_Battery_Level_Data_t *BAS_Read_Battery_Level_Data;
} Event_Data;
} BAS_Event_Data_t;
#define BAS_EVENT_DATA_SIZE (sizeof(BAS_Event_Data_t))
/*! The following declared type represents the Prototype Function for
* a BAS Profile Event Receive Data Callback. This function will be
* called whenever an BAS Profile Event occurs that is associated
* with the specified Bluetooth Stack ID. @param BluetoothStackID This function passes to
* the caller the Bluetooth Stack ID. @param BAS_Event_Data The BAS Event Data that
* occurred. @param CallbackParameter The BAS Profile Event Callback Parameter that was
* specified when this Callback was installed. The caller is free to
* use the contents of the BAS Profile Event Data ONLY in the context
* of this callback. If the caller requires the Data for a longer
* period of time, then the callback function MUST copy the data into
* another Data Buffer This function is guaranteed NOT to be invoked
* more than once simultaneously for the specified installed callback
* (i.e. this function DOES NOT have to be re-entrant).It needs to be
* noted however, that if the same Callback is installed more than
* once, then the callbacks will be called serially. Because of
* this, the processing in this function should be as efficient as
* possible. It should also be noted that this function is called in
* the Thread Context of a Thread that the User does NOT own.
* Therefore, processing in this function should be as efficient as
* possible (this argument holds anyway because another BAS Profile
* Event will not be processed while this function call is
* outstanding).
* \note This function MUST NOT Block and wait for events that
* can only be satisfied by Receiving BAS Profile Event
* Packets. A Deadlock WILL occur because NO BAS Event
* Callbacks will be issued while this function is
* currently outstanding.
*/
typedef void (BTPSAPI *BAS_Event_Callback_t)(unsigned int BluetoothStackID, BAS_Event_Data_t *BAS_Event_Data, unsigned long CallbackParameter);
/*! BAS Server API. */
/*! @brief The following function is responsible for opening a BAS Server.
* @param BluetoothStackID The first parameter is the Bluetooth Stack ID on which to open the
* server. @param EventCallback The second parameter is the Callback function to call
* when an event occurs on this Server Port. @param CallbackParameter The third parameter is
* a user-defined callback parameter that will be passed to the
* callback function with each event. @param ServiceID The final parameter is a
* pointer to store the GATT Service ID of the registered BAS
* service. This can be used to include the service registered by
* this call. @return This function returns the positive, non-zero, Instance
* ID or a negative error code.
* \note Only 1 BAS Server may be open at a time, per Bluetooth
* Stack ID.
* \note All Client Requests will be dispatch to the EventCallback
* function that is specified by the second parameter to
* this function.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Initialize_Service(unsigned int BluetoothStackID, BAS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Initialize_Service_t)(unsigned int BluetoothStackID, BAS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);
#endif
/*! @brief The following function is responsible for opening a BAS Server.
* @param BluetoothStackID The first parameter is the Bluetooth Stack ID on which to open the
* server. @param EventCallback The second parameter is the Callback function to call
* when an event occurs on this Server Port. @param CallbackParameter The third parameter is
* a user-defined callback parameter that will be passed to the
* callback function with each event. @param ServiceID The fourth parameter is a
* pointer to store the GATT Service ID of the registered BAS
* service. This can be used to include the service registered by
* this call. @param ServiceHandleRange The final parameter is a pointer, that on input can be
* used to control the location of the service in the GATT database,
* and on ouput to store the service handle range.
* @return This function returns the positive, non-zero, Instance ID or a negative error
* code.
* \note Only 1 BAS Server may be open at a time, per Bluetooth
* Stack ID.
* \note All Client Requests will be dispatch to the EventCallback
* function that is specified by ghe second parameter to
* this function.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Initialize_Service_Handle_Range(unsigned int BluetoothStackID, BAS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID, GATT_Attribute_Handle_Group_t *ServiceHandleRange);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Initialize_Service_Handle_Range_t)(unsigned int BluetoothStackID, BAS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID, GATT_Attribute_Handle_Group_t *ServiceHandleRange);
#endif
/*! @brief The following function is responsible for closing a previous BAS
* Server. @param BluetoothStackID The first parameter is the Bluetooth Stack ID on which to
* close the server. @param InstanceID The second parameter is the InstanceID that was
* returned from a successful call to BAS_Initialize_Service().
* @return This function returns a zero if successful or a negative return
* error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Cleanup_Service(unsigned int BluetoothStackID, unsigned int InstanceID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Cleanup_Service_t)(unsigned int BluetoothStackID, unsigned int InstanceID);
#endif
/*! @brief The following function is responsible for querying the number of
* attributes that are contained in the BAS Service that is
* registered with a call to BAS_Initialize_Service().
* @return This function returns the non-zero number of attributes that are contained in a
* BAS Server or zero on failure.
*/
BTPSAPI_DECLARATION unsigned int BTPSAPI BAS_Query_Number_Attributes(void);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef unsigned int (BTPSAPI *PFN_BAS_Query_Number_Attributes_t)(void);
#endif
/*! @brief The following function is responsible for responding to a BAS Read
* Battery Level Request. @param BluetoothStackID The first parameter is the Bluetooth
* Stack ID of the Bluetooth Device. @param TransactionID The second parameter is the
* Transaction ID of the request. @param BatteryLevel The final parameter contains the
* Battery Level to send to the remote device. @return This function returns
* a zero if successful or a negative return error code if an error
* occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Battery_Level_Read_Request_Response(unsigned int BluetoothStackID, unsigned int TransactionID, Byte_t BatteryLevel);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Battery_Level_Read_Request_Response_t)(unsigned int BluetoothStackID, unsigned int TransactionID, Byte_t BatteryLevel);
#endif
/*! @brief The following function is responsible for responding to a BAS Read
* Battery Level Request when an error occured. @param BluetoothStackID The first parameter
* is the Bluetooth Stack ID of the Bluetooth Device.
* @param TransactionID The second parameter is the Transaction
* ID of the request. @param ErrorCode The final parameter
* contains the Error which occured during the Read operation.
* @return This function returns a zero if successful or a negative return error
* code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Battery_Level_Read_Request_Error_Response(unsigned int BluetoothStackID, unsigned int TransactionID, Byte_t ErrorCode);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Battery_Level_Read_Request_Error_Response_t)(unsigned int BluetoothStackID, unsigned int TransactionID, Byte_t ErrorCode);
#endif
/*! @brief The following function is responsible for getting the presentation
* format of Device battery level on the specified BAS Instance.
* @param BluetoothStackID The first parameter is the Bluetooth Stack ID of the Bluetooth
* Device.@param InstanceID The second parameter is the InstanceID returned from a
* successful call to BAS_Initialize_Server(). @param CharacteristicPresentationFormat The final parameter is
* a pointer to store the Battery Level presentation format of the
* specified BAS Instance. @return This function returns zero if successful or
* a negative return error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Query_Characteristic_Presentation_Format(unsigned int BluetoothStackID, unsigned int InstanceID, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Query_Characteristic_Presentation_Format_t)(unsigned int BluetoothStackID, unsigned int InstanceID, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#endif
/*! @brief The following function is responsible for setting the presentation
* format of Device battery level on the specified BAS Instance.
* @param BluetoothStackID The first parameter is the Bluetooth Stack ID of the Bluetooth
* Device.@param InstanceID The second parameter is the InstanceID returned from a
* successful call to BAS_Initialize_Server(). @param CharacteristicPresentationFormat The final parameter is
* Battery Level presentation format to be set on the specified
* BAS Instance. @return This function returns zero if successful or
* a negative return error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Set_Characteristic_Presentation_Format(unsigned int BluetoothStackID, unsigned int InstanceID, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Set_Characteristic_Presentation_Format_t)(unsigned int BluetoothStackID, unsigned int InstanceID, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#endif
/*! @brief The following function is responsible for responding to a BAS Read
* Client Configuration Request. @param BluetoothStackID The first parameter is the
* Bluetooth Stack ID of the Bluetooth Device. @param InstanceID The second parameter
* is the InstanceID returned from a successful call to
* BAS_Initialize_Server(). @param TransactionID The third parameter is the Transaction ID of the
* request. @param Client_Configuration The final parameter contains the Client Configuration to
* send to the remote device. @return This function returns a zero if
* successful or a negative return error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Read_Client_Configuration_Response(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int TransactionID, Word_t Client_Configuration);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Read_Client_Configuration_Response_t)(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int TransactionID, Word_t Client_Configuration);
#endif
/*! @brief The following function is responsible for sending a Battery Level
* Status notification to a specified remote device.
* @param BluetoothStackID The first parameter is the Bluetooth Stack ID of the Bluetooth Device.
* @param InstanceID The second parameter is the InstanceID returned from a successful call
* to BAS_Initialize_Server(). @param ConnectionID The third parameter is the
* ConnectionID of the remote device to send the notification to.
* @param BatteryLevel The final parameter contains the Battery Level to send to the
* remote device. @return This function returns a zero if successful or a
* negative return error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Notify_Battery_Level(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, Byte_t BatteryLevel);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Notify_Battery_Level_t)(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, Byte_t BatteryLevel);
#endif
/*! BAS Client API */
/*! @brief The following function is responsible for parsing a value received
* from a remote BAS Server interpreting it as characteristic
* persentation format of Battery Level. @param ValueLength The first parameter is the
* length of the value returned by the remote BAS Server.
* @param Value The second parameter is a pointer to the data returned by the remote BAS
* Server. @param CharacteristicPresentationFormat The final parameter is a pointer to store the parsed
* Battery Level Presentation Format. @return This function returns a zero
* if successful or a negative return error code if an error occurs.
*/
BTPSAPI_DECLARATION int BTPSAPI BAS_Decode_Characteristic_Presentation_Format(unsigned int ValueLength, Byte_t *Value, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BAS_Decode_Characteristic_Presentation_Format_t)(unsigned int ValueLength, Byte_t *Value, BAS_Presentation_Format_Data_t *CharacteristicPresentationFormat);
#endif
#endif
Reference in New Issue View Git Blame Copy Permalink