MuditaOS/module-bluetooth/lib/Bluetopia/profiles/PASS/include/PASSAPI.h

/*
 * Copyright 2011 - 2014 Stonestreet One.
 * All Rights Reserved.
 * Author:  Tim Cook
 *** MODIFICATION HISTORY ****************************************************
 *
 *   mm/dd/yy  F. Lastname    Description of Modification
 *   --------  -----------    ------------------------------------------------
 *   09/22/11  T. Cook        Initial creation.
 ****************************************************************************
 */

/**
 *  @file PASSAPI.h
 *
 *  @brief Stonestreet One Bluetooth Phone Alert Status 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 "SS1BTPAS.h"
 *  @endcode
 *
 *  The Phone Alert Status Service, PASS, programming interface defines the protocols and procedures to be used to implement PASS capabilities for both Server and Client services.
 *  ============================================================================
 */
#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,  /*!< Dispatched to a PASS Server when a PASS Client is attempting to read a descriptor. */
   etPASS_Server_Client_Configuration_Update,  /*!< Dispatched to a PASS Server when a PASS Client has written a Client Configuration descriptor. */
   etPASS_Server_Ringer_Control_Command_Indication  /*!< Dispatched to a PASS Server when a PASS Client is attempting to write a command to the Ringer Control point characteristic. */
} 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. @param BluetoothStackID This function passes to
    * the caller the Bluetooth Stack ID. @param PASS_Event_Data The PASS Event Data that
    * occurred. @param CallbackParameter 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);

   /*!
    * @brief PASS Server API. The following function is responsible for opening a PASS 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 PASS
    * 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 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

   /*! @brief The following function is responsible for opening a PASS 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 PASS
    * 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 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

   /*! @brief The following function is responsible for closing a previously
    * PASS 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
    * PASS_Initialize_Service(). @return 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

   /*! @brief 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().
    * @return 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

   /*! @brief The following function is responsible for setting the Alert Status
    * characteristic on the specified PASS 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 PASS_Initialize_Server().  @param AlertStatus The final parameter is the Alert
    * Status to set as the current Alert Status for the specified PASS
    * Instance. @return 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

   /*! @brief The following function is responsible for querying the current
    * Alert Status characteristic value on the specified PASS 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 PASS_Initialize_Server(). @param AlertStatus The final parameter
    * is a pointer to a structure to return the current Alert Status for
    * the specified PASS Instance. @return 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

   /*! @brief The following function is responsible for setting the Ringer
    * Setting characteristic on the specified PASS instance.
    *n@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 PASS_Initialize_Server().  @param RingerSetting The final parameter is the Ringer
    * Setting to set as the current Ringer Setting for the specified
    * PASS Instance. @return 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

   /*! @brief The following function is responsible for querying the current
    * Ringer Setting characteristic value on the specified PASS
    * 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 PASS_Initialize_Server().
    * @param RingerSetting The final parameter is a pointer to store the current Ringer Setting for the
    * specified PASS Instance. @return 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

   /*! @brief The following function is responsible for responding to a 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
    * PASS_Initialize_Server(). @param TransactionID The third parameter is the Transaction ID of the
    * request. @param NotificationsEnabled 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 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

   /*! @brief The following function is responsible for sending a notification
    * of a specified characteristic 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 PASS_Initialize_Server().  @param ConnectionID The third parameter is the
    * ConnectionID of the remote device to send the notification to.
    * @param CharacteristicType The final parameter specifies the characteristic to notify.
    * @return 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.
    * @brief The following function is responsible for parsing a value received
    * from a remote PASS Server interpreting it as the Alert Status
    * characteristic.  @param ValueLength The first parameter is the length of the value
    * returned by the remote PASS Server.  @param Value The second parameter is a
    * pointer to the data returned by the remote PASS Server.
    * @param AlertStatusResult The final parameter is a pointer to store the parsed Alert Status value.
    * @return 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

   /*! @brief The following function is responsible for parsing a value received
    * from a remote PASS Server interpreting it as the Ringer Setting
    * characteristic. @param ValueLength The first parameter is the length of the value
    * returned by the remote PASS Server. @param Value The second parameter is a
    * pointer to the data returned by the remote PASS Server.
    * @param RingerSetting The final parameter is a pointer to store the parsed Ringer Setting value.
    * @return 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

   /*! @brief The following function is responsible for formatting a Ringer
    * Control Point command.  This formatted value can be then written
    * to a remote PASS Server. @param RingerControlCommand The first parameter is the command to
    * format.
    * @param BufferLength The second parameter is the buffer length.
    * @param Buffer The final parameter is a pointer to the buffer to format the command into.
    * \note The BufferLength must be large enough to hold the formatted command.
    * @return 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