/* * 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