/*****< basapi.h >*************************************************************/
/*      Copyright 2012 - 2014 Stonestreet One.                                */
/*      All Rights Reserved.                                                  */
/*                                                                            */
/*  BASAPI - Stonestreet One Bluetooth Battery Service (GATT based)           */
/*           API Type Definitions, Constants, and Prototypes.                 */
/*                                                                            */
/*  Author:  Zahid Khan                                                       */
/*                                                                            */
/*** MODIFICATION HISTORY *****************************************************/
/*                                                                            */
/*   mm/dd/yy  F. Lastname    Description of Modification                     */
/*   --------  -----------    ------------------------------------------------*/
/*   06/22/12  Z. Khan        Initial creation.                               */
/******************************************************************************/
#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,
   etBAS_Server_Client_Configuration_Update,
   etBAS_Server_Read_Battery_Level_Request
} 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.  This function passes to   */
   /* the caller the Bluetooth Stack ID, the BAS Event Data that        */
   /* occurred and 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.                                                   */

   /* The following function is responsible for opening a BAS Server.   */
   /* The first parameter is the Bluetooth Stack ID on which to open the*/
   /* server.  The second parameter is the Callback function to call    */
   /* when an event occurs on this Server Port.  The third parameter is */
   /* a user-defined callback parameter that will be passed to the      */
   /* callback function with each event.  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.  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

   /* The following function is responsible for opening a BAS Server.   */
   /* The first parameter is the Bluetooth Stack ID on which to open the*/
   /* server.  The second parameter is the Callback function to call    */
   /* when an event occurs on this Server Port.  The third parameter is */
   /* a user-defined callback parameter that will be passed to the      */
   /* callback function with each event.  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.  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.  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_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

   /* The following function is responsible for closing a previous BAS  */
   /* Server.  The first parameter is the Bluetooth Stack ID on which to*/
   /* close the server.  The second parameter is the InstanceID that was*/
   /* returned from a successful call to BAS_Initialize_Service().      */
   /* 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

   /* 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().  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

   /* The following function is responsible for responding to a BAS Read*/
   /* Battery Level Request.  The first parameter is the Bluetooth      */
   /* Stack ID of the Bluetooth Device.  The second parameter is the    */
   /* Transaction ID of the request.  The final parameter contains the  */
   /* Battery Level to send to the remote device.  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

   /* The following function is responsible for responding to a BAS Read*/
   /* Battery Level Request when an error occured.  The first parameter */
   /* is the Bluetooth Stack ID of the Bluetooth Device. The second     */
   /* parameter is the Transaction ID of the request.The final parameter*/
   /* contains the Error which occured during the Read operation.  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

   /* The following function is responsible for getting the presentation*/
   /* format of Device battery level on the specified BAS Instance.     */
   /* The first parameter is the Bluetooth Stack ID of the Bluetooth    */
   /* Device.The second parameter is the InstanceID returned from a     */
   /* successful call to BAS_Initialize_Server().The final parameter is */
   /* a pointer to store the Battery Level presentation format of the   */
   /* specified BAS Instance.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

   /* The following function is responsible for setting the presentation*/
   /* format of Device battery level on the specified BAS Instance.     */
   /* The first parameter is the Bluetooth Stack ID of the Bluetooth    */
   /* Device.The second parameter is the InstanceID returned from a     */
   /* successful call to BAS_Initialize_Server().The final parameter is */
   /* Battery Level presentation format to be set on the specified      */
   /* BAS Instance.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

   /* The following function is responsible for responding to a BAS Read*/
   /* Client Configuration Request.  The first parameter is the         */
   /* Bluetooth Stack ID of the Bluetooth Device.  The second parameter */
   /* is the InstanceID returned from a successful call to              */
   /* BAS_Initialize_Server().  The third is the Transaction ID of the  */
   /* request.  The final parameter contains the Client Configuration to*/
   /* send to the remote device.  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

   /* The following function is responsible for sending a Battery Level */
   /* Status notification to a specified remote device.  The first      */
   /* parameter is the Bluetooth Stack ID of the Bluetooth Device.  The */
   /* second parameter is the InstanceID returned from a successful call*/
   /* to BAS_Initialize_Server().  The third parameter is the           */
   /* ConnectionID of the remote device to send the notification to.    */
   /* The final parameter contains the Battery Level to send to the     */
   /* remote device. 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                                                    */

   /* The following function is responsible for parsing a value received*/
   /* from a remote BAS Server interpreting it as characteristic        */
   /* persentation format of Battery Level. The first parameter is the  */
   /* length of the value returned by the remote BAS Server. The second */
   /* parameter is a pointer to the data returned by the remote BAS     */
   /* Server.The final parameter is a pointer to store the parsed       */
   /* Battery Level Presentation Format. 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
