/*****< passapi.h >************************************************************/
/*      Copyright 2011 - 2014 Stonestreet One.                                */
/*      All Rights Reserved.                                                  */
/*                                                                            */
/*  PASSAPI - Stonestreet One Bluetooth Phone Alert Status Service (GATT      */
/*            based) API Type Definitions, Constants, and Prototypes.         */
/*                                                                            */
/*  Author:  Tim Cook                                                         */
/*                                                                            */
/*** MODIFICATION HISTORY *****************************************************/
/*                                                                            */
/*   mm/dd/yy  F. Lastname    Description of Modification                     */
/*   --------  -----------    ------------------------------------------------*/
/*   09/22/11  T. Cook        Initial creation.                               */
/******************************************************************************/
#ifndef __PASSAPIH__
#define __PASSAPIH__

#include "SS1BTPS.h"        /* Bluetooth Stack API Prototypes/Constants.      */
#include "SS1BTGAT.h"       /* Bluetooth Stack GATT API Prototypes/Constants. */
#include "PASSType.h"       /* Phone Alert Status 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 PASS_ERROR_INVALID_PARAMETER                     (-1000)
#define PASS_ERROR_INVALID_BLUETOOTH_STACK_ID            (-1001)
#define PASS_ERROR_INSUFFICIENT_RESOURCES                (-1002)
#define PASS_ERROR_SERVICE_ALREADY_REGISTERED            (-1003)
#define PASS_ERROR_INVALID_INSTANCE_ID                   (-1004)
#define PASS_ERROR_MALFORMATTED_DATA                     (-1005)
#define PASS_ERROR_UNKNOWN_ERROR                         (-1006)

   /* The following structure defines the format of the Alert Status    */
   /* characteristic value.                                             */
typedef struct _tagPASS_Alert_Status_t
{
   Boolean_t RingerStateActive;
   Boolean_t VibrateStateActive;
   Boolean_t DisplayStateActive;
} PASS_Alert_Status_t;

#define PASS_ALERT_STATUS_DATA_SIZE                      (sizeof(PASS_Alert_Status_t))

   /* The following define the valid Ringer Setting characteristic      */
   /* values.                                                           */
typedef enum
{
   rsSilent = PASS_RINGER_SETTING_RINGER_SILENT,
   rsNormal = PASS_RINGER_SETTING_RINGER_NORMAL
} PASS_Ringer_Setting_t;

   /* The following define the commands that may be received in the     */
   /* etPASS_Server_Ringer_Control_Command event and that may be written*/
   /* using the PASS_Write_Ringer_Control_Command() function.           */
typedef enum
{
   rcSilent       = PASS_RINGER_CONTROL_COMMAND_SILENT_MODE,
   rcMuteOnce     = PASS_RINGER_CONTROL_COMMAND_MUTE_ONCE,
   rcCancelSilent = PASS_RINGER_CONTROL_COMMAND_CANCEL_SILENT_MODE
} PASS_Ringer_Control_Command_t;

   /* The following define the valid Read Request types that a server   */
   /* may receive in a etPASS_Server_Read_Client_Configuration_Request  */
   /* or etPASS_Server_Client_Configuration_Update event.  This is also */
   /* used by the PASS_Send_Notification to denote the characteristic   */
   /* value to notify.                                                  */
   /* * 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
{
   rrAlertStatus,
   rrRingerSetting
} PASS_Characteristic_Type_t;

   /* The following enumeration covers all the events generated by the  */
   /* PASS Service.  These are used to determine the type of each event */
   /* generated, and to ensure the proper union element is accessed for */
   /* the PASS_Event_Data_t structure.                                  */
typedef enum
{
   etPASS_Server_Read_Client_Configuration_Request,
   etPASS_Server_Client_Configuration_Update,
   etPASS_Server_Ringer_Control_Command_Indication
} PASS_Event_Type_t;

   /* The following structure contains the Handles that will need to be */
   /* cached by a PASS client in order to only do service discovery     */
   /* once.                                                             */
typedef struct _tagPASS_Client_Information_t
{
   Word_t Alert_Status;
   Word_t Alert_Status_Client_Configuration;
   Word_t Ringer_Setting;
   Word_t Ringer_Setting_Client_Configuration;
   Word_t Ringer_Control_Point;
} PASS_Client_Information_t;

#define PASS_CLIENT_INFORMATION_DATA_SIZE                (sizeof(PASS_Client_Information_t))

   /* The following structure contains all of the per Client data that  */
   /* will need to be stored by a PASS Server.                          */
typedef struct _tagPASS_Server_Information_t
{
   Boolean_t Alert_Status_Client_Configuration;
   Boolean_t Ringer_Setting_Client_Configuration;
} PASS_Server_Information_t;

#define PASS_SERVER_INFORMATION_DATA_SIZE                (sizeof(PASS_Server_Information_t))

   /* The following PASS Service Event is dispatched to a PASS Server   */
   /* when a PASS 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                  */
   /* PASS_Client_Configuration_Read_Response() API function.           */
typedef struct _tagPASS_Read_Client_Configuration_Data_t
{
   unsigned int               InstanceID;
   unsigned int               ConnectionID;
   unsigned int               TransactionID;
   GATT_Connection_Type_t     ConnectionType;
   BD_ADDR_t                  RemoteDevice;
   PASS_Characteristic_Type_t ClientConfigurationType;
} PASS_Read_Client_Configuration_Data_t;

#define PASS_READ_CLIENT_CONFIGURATION_DATA_SIZE         (sizeof(PASS_Read_Client_Configuration_Data_t))

   /* The following PASS Service Event is dispatched to a PASS Server   */
   /* when a PASS Client has written a Client Configuration descriptor. */
   /* The ConnectionID, ConnectionType, and RemoteDevice specifiy the   */
   /* Client that is making the update.  The DescriptorType specifies   */
   /* the Descriptor that the Client is writing.                        */
typedef struct _tagPASS_Client_Configuration_Update_Data_t
{
   unsigned int               InstanceID;
   unsigned int               ConnectionID;
   GATT_Connection_Type_t     ConnectionType;
   BD_ADDR_t                  RemoteDevice;
   PASS_Characteristic_Type_t ClientConfigurationType;
   Boolean_t                  NotificationsEnabled;
} PASS_Client_Configuration_Update_Data_t;

#define PASS_CLIENT_CONFIGURATION_UPDATE_DATA_SIZE       (sizeof(PASS_Client_Configuration_Update_Data_t))

   /* The following PASS Service Event is dispatched to a PASS Server   */
   /* when a PASS Client is attempting to write a command to the Ringer */
   /* Control point characteristic.  The ConnectionID, ConnectionType,  */
   /* and RemoteDevice specifiy the Client that is making the request.  */
   /* The Command specifies the command that the Client is attempting to*/
   /* write.                                                            */
typedef struct _tagPASS_Ringer_Control_Command_Data_t
{
   unsigned int                  InstanceID;
   unsigned int                  ConnectionID;
   GATT_Connection_Type_t        ConnectionType;
   BD_ADDR_t                     RemoteDevice;
   PASS_Ringer_Control_Command_t Command;
} PASS_Ringer_Control_Command_Data_t;

#define PASS_RINGER_CONTROL_COMMAND_DATA_SIZE            (sizeof(PASS_Ringer_Control_Command_Data_t))

   /* The following structure represents the container structure for    */
   /* holding all PASS Service 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 _tagPASS_Event_Data_t
{
   PASS_Event_Type_t Event_Data_Type;
   Word_t            Event_Data_Size;
   union
   {
      PASS_Read_Client_Configuration_Data_t   *PASS_Read_Client_Configuration_Data;
      PASS_Client_Configuration_Update_Data_t *PASS_Client_Configuration_Update_Data;
      PASS_Ringer_Control_Command_Data_t      *PASS_Ringer_Control_Command_Data;
   } Event_Data;
} PASS_Event_Data_t;

#define PASS_EVENT_DATA_SIZE                             (sizeof(PASS_Event_Data_t))

   /* The following declared type represents the Prototype Function for */
   /* a PASS Service Event Receive Data Callback.  This function will be*/
   /* called whenever an PASS Service Event occurs that is associated   */
   /* with the specified Bluetooth Stack ID.  This function passes to   */
   /* the caller the Bluetooth Stack ID, the PASS Event Data that       */
   /* occurred and the PASS Service Event Callback Parameter that was   */
   /* specified when this Callback was installed.  The caller is free to*/
   /* use the contents of the PASS Service 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 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 PASS Service 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 PASS Service Event  */
   /*            Packets.  A Deadlock WILL occur because NO PASS Event  */
   /*            Callbacks will be issued while this function is        */
   /*            currently outstanding.                                 */
typedef void (BTPSAPI *PASS_Event_Callback_t)(unsigned int BluetoothStackID, PASS_Event_Data_t *PASS_Event_Data, unsigned long CallbackParameter);

   /* PASS Server API.                                                  */

   /* The following function is responsible for opening a PASS 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 PASS       */
   /* 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 PASS 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 PASS_Initialize_Service(unsigned int BluetoothStackID, PASS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Initialize_Service_t)(unsigned int BluetoothStackID, PASS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);
#endif

   /* The following function is responsible for opening a PASS 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 PASS       */
   /* 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 PASS 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 PASS_Initialize_Service_Handle_Range(unsigned int BluetoothStackID, PASS_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_PASS_Initialize_Service_Handle_Range_t)(unsigned int BluetoothStackID, PASS_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 previously    */
   /* PASS 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                       */
   /* PASS_Initialize_Service().  This function returns a zero if       */
   /* successful or a negative return error code if an error occurs.    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Cleanup_Service(unsigned int BluetoothStackID, unsigned int InstanceID);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_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 PASS Service that is         */
   /* registered with a call to PASS_Initialize_Service().  This        */
   /* function returns the non-zero number of attributes that are       */
   /* contained in a PASS Server or zero on failure.                    */
BTPSAPI_DECLARATION unsigned int BTPSAPI PASS_Query_Number_Attributes(void);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef unsigned int (BTPSAPI *PFN_PASS_Query_Number_Attributes_t)(void);
#endif

   /* The following function is responsible for setting the Alert Status*/
   /* characteristic on the specified PASS 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 PASS_Initialize_Server().  The final parameter is the Alert    */
   /* Status to set as the current Alert Status for the specified PASS  */
   /* Instance.  This function returns a zero if successful or a        */
   /* negative return error code if an error occurs.                    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Set_Alert_Status(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Alert_Status_t AlertStatus);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Set_Alert_Status_t)(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Alert_Status_t AlertStatus);
#endif

   /* The following function is responsible for querying the current    */
   /* Alert Status characteristic value on the specified PASS 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 PASS_Initialize_Server().  The final parameter */
   /* is a pointer to a structure to return the current Alert Status for*/
   /* the specified PASS Instance.  This function returns a zero if     */
   /* successful or a negative return error code if an error occurs.    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Query_Alert_Status(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Alert_Status_t *AlertStatus);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Query_Alert_Status_t)(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Alert_Status_t *AlertStatus);
#endif

   /* The following function is responsible for setting the Ringer      */
   /* Setting characteristic on the specified PASS 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 PASS_Initialize_Server().  The final parameter is the Ringer   */
   /* Setting to set as the current Ringer Setting for the specified    */
   /* PASS Instance.  This function returns a zero if successful or a   */
   /* negative return error code if an error occurs.                    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Set_Ringer_Setting(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Ringer_Setting_t RingerSetting);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Set_Ringer_Setting_t)(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Ringer_Setting_t RingerSetting);
#endif

   /* The following function is responsible for querying the current    */
   /* Ringer Setting characteristic value on the specified PASS         */
   /* 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 PASS_Initialize_Server().  The final    */
   /* parameter is a pointer to store the current Ringer Setting for the*/
   /* specified PASS Instance.  This function returns a zero if         */
   /* successful or a negative return error code if an error occurs.    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Query_Ringer_Setting(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Ringer_Setting_t *RingerSetting);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Query_Ringer_Setting_t)(unsigned int BluetoothStackID, unsigned int InstanceID, PASS_Ringer_Setting_t *RingerSetting);
#endif

   /* The following function is responsible for responding to a 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              */
   /* PASS_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 PASS_Read_Client_Configuration_Response(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int TransactionID, Boolean_t NotificationsEnabled);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Read_Client_Configuration_Response_t)(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int TransactionID, Boolean_t NotificationsEnabled);
#endif

   /* The following function is responsible for sending a notification  */
   /* of a specified characteristic 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 PASS_Initialize_Server().  The third parameter is the     */
   /* ConnectionID of the remote device to send the notification to.    */
   /* The final parameter specifies the characteristic to notify.  This */
   /* function returns a zero if successful or a negative return error  */
   /* code if an error occurs.                                          */
BTPSAPI_DECLARATION int BTPSAPI PASS_Send_Notification(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, PASS_Characteristic_Type_t CharacteristicType);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Send_Notification_t)(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, PASS_Characteristic_Type_t CharacteristicType);
#endif

   /* PASS Client API.                                                  */

   /* The following function is responsible for parsing a value received*/
   /* from a remote PASS Server interpreting it as the Alert Status     */
   /* characteristic.  The first parameter is the length of the value   */
   /* returned by the remote PASS Server.  The second parameter is a    */
   /* pointer to the data returned by the remote PASS Server.  The final*/
   /* parameter is a pointer to store the parsed Alert Status value.    */
   /* This function returns a zero if successful or a negative return   */
   /* error code if an error occurs.                                    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Decode_Alert_Status(unsigned int ValueLength, Byte_t *Value, PASS_Alert_Status_t *AlertStatusResult);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Decode_Alert_Status_t)(unsigned int ValueLength, Byte_t *Value, PASS_Alert_Status_t *AlertStatusResult);
#endif

   /* The following function is responsible for parsing a value received*/
   /* from a remote PASS Server interpreting it as the Ringer Setting   */
   /* characteristic.  The first parameter is the length of the value   */
   /* returned by the remote PASS Server.  The second parameter is a    */
   /* pointer to the data returned by the remote PASS Server.  The final*/
   /* parameter is a pointer to store the parsed Ringer Setting value.  */
   /* This function returns a zero if successful or a negative return   */
   /* error code if an error occurs.                                    */
BTPSAPI_DECLARATION int BTPSAPI PASS_Decode_Ringer_Setting(unsigned int ValueLength, Byte_t *Value, PASS_Ringer_Setting_t *RingerSetting);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Decode_Ringer_Setting_t)(unsigned int ValueLength, Byte_t *Value, PASS_Ringer_Setting_t *RingerSetting);
#endif

   /* The following function is responsible for formatting a Ringer     */
   /* Control Point command.  This formatted value can be then written  */
   /* to a remote PASS Server.  The first parameter is the command to   */
   /* format.  The final two parameters are the buffer length and the   */
   /* buffer to format the command into.  The BufferLength must be large*/
   /* enough to hold the formatted command.  This function returns the  */
   /* number of bytes formatted into Buffer if successful or a negative */
   /* error code.                                                       */
BTPSAPI_DECLARATION int BTPSAPI PASS_Format_Ringer_Control_Command(PASS_Ringer_Control_Command_t RingerControlCommand, unsigned int BufferLength, Byte_t *Buffer);

#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
   typedef int (BTPSAPI *PFN_PASS_Format_Ringer_Control_Command_t)(PASS_Ringer_Control_Command_t RingerControlCommand, unsigned int BufferLength, Byte_t *Buffer);
#endif

#endif
