mirror/MuditaOS
1
0
Fork 0
mirror of https://github.com/mudita/MuditaOS.git synced 2026-07-04 05:06:58 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
f7c8af86c858cd03142f62d582ef6461ba2168db
MuditaOS/module-bluetooth/lib/Bluetopia/profiles/PASS/source/PASSAPI.h

452 lines
24 KiB
C
Raw Blame History

/*
* 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
Reference in New Issue View Git Blame Copy Permalink