mirror of
https://github.com/mudita/MuditaOS.git
synced 2026-07-04 05:06:58 -04:00
245 lines
12 KiB
C
245 lines
12 KiB
C
/*
|
|
* Copyright 2012 - 2014 Stonestreet One.
|
|
* All Rights Reserved.
|
|
* Author: Ajay Parashar
|
|
*** MODIFICATION HISTORY ****************************************************
|
|
*
|
|
* mm/dd/yy F. Lastname Description of Modification
|
|
* -------- ----------- ------------------------------------------------
|
|
* 06/25/12 A. Parashar Initial creation.
|
|
****************************************************************************
|
|
*/
|
|
|
|
/**
|
|
* @file LLSAPI.h
|
|
*
|
|
* @brief Stonestreet One Bluetooth Link Loss Service (GATT
|
|
* based) API Type Definitions, Constants, and Prototypes.
|
|
* The Link Loss Service programming interface defines the protocols
|
|
* and procedures to be used to implement Link Loss Service capabilities.
|
|
* To use any of the following API's,
|
|
* include the following declaration in your application.
|
|
* @code
|
|
* #include "SS1BTLLS.h"
|
|
* @endcode
|
|
*/
|
|
#ifndef __LLSAPIH__
|
|
#define __LLSAPIH__
|
|
|
|
#include "SS1BTPS.h" /*! Bluetooth Stack API Prototypes/Constants. */
|
|
#include "SS1BTGAT.h" /*! Bluetooth Stack GATT API Prototypes/Constants. */
|
|
#include "LLSTypes.h" /*! Link Loss Notification Service Types */
|
|
|
|
/*! 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 LLS_ERROR_INVALID_PARAMETER (-1000)
|
|
#define LLS_ERROR_INVALID_BLUETOOTH_STACK_ID (-1001)
|
|
#define LLS_ERROR_INSUFFICIENT_RESOURCES (-1002)
|
|
#define LLS_ERROR_SERVICE_ALREADY_REGISTERED (-1003)
|
|
#define LLS_ERROR_INVALID_INSTANCE_ID (-1004)
|
|
#define LLS_ERROR_MALFORMATTED_DATA (-1005)
|
|
#define LLS_ERROR_UNKNOWN_ERROR (-1006)
|
|
|
|
/*! The following structure contains the Handles that will need to be
|
|
* cached by a LLS client in order to only do service discovery once.
|
|
*/
|
|
typedef struct _tagLLS_Client_Information_t
|
|
{
|
|
Word_t Alert_Level;
|
|
} LLS_Client_Information_t;
|
|
|
|
#define LLS_CLIENT_INFORMATION_DATA_SIZE (sizeof( LLS_Client_Information_t))
|
|
|
|
/*! The following structure contains the Handles that will need to be
|
|
* cached by a LLS Server in order to only do service discovery once.
|
|
*/
|
|
typedef struct _tagLLS_Server_Information_t
|
|
{
|
|
Word_t Alert_Level;
|
|
} LLS_Server_Information_t;
|
|
|
|
#define LLS_SERVER_INFORMATION_DATA_SIZE (sizeof( LLS_Server_Information_t))
|
|
|
|
/*! The following enumeration covers all the events generated by the
|
|
* LLS Profile. These are used to determine the type of each event
|
|
* generated, and to ensure the proper union element is accessed for
|
|
* the LLS_Event_Data_t structure.
|
|
*/
|
|
typedef enum
|
|
{
|
|
etLLS_Alert_Level_Update /*!< Dispatched when a LLS Client requests to update Alert Level to a registered LLS Server. */
|
|
} LLS_Event_Type_t;
|
|
|
|
/*! The following LLS Profile Event is dispatched to a LLS Server when
|
|
* a LLS Client is attempting to write the Alert Level
|
|
* characteristic. The ConnectionID, ConnectionType, and
|
|
* RemoteDevice specifiy the Client that is making the update. The
|
|
* final member is the new Alert Level.
|
|
*/
|
|
typedef struct _tagLLS_Alert_Level_Update_Data_t
|
|
{
|
|
unsigned int InstanceID;
|
|
unsigned int ConnectionID;
|
|
GATT_Connection_Type_t ConnectionType;
|
|
BD_ADDR_t RemoteDevice;
|
|
Byte_t AlertLevel;
|
|
} LLS_Alert_Level_Update_Data_t;
|
|
|
|
#define LLS_ALERT_LEVEL_UPDATE_DATA_SIZE (sizeof(LLS_Alert_Level_Update_Data_t))
|
|
|
|
/*! The following structure represents the container structure for
|
|
* holding all LLS 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 _tagLLS_Event_Data_t
|
|
{
|
|
LLS_Event_Type_t Event_Data_Type;
|
|
Word_t Event_Data_Size;
|
|
union
|
|
{
|
|
LLS_Alert_Level_Update_Data_t *LLS_Alert_Level_Update_Data;
|
|
} Event_Data;
|
|
} LLS_Event_Data_t;
|
|
|
|
#define LLS_EVENT_DATA_SIZE (sizeof(LLS_Event_Data_t))
|
|
|
|
/*! The following declared type represents the Prototype Function for
|
|
* a LLS Profile Event Receive Data Callback. This function will be
|
|
* called whenever an LLS Profile Event occurs that is associated
|
|
* with the specified Bluetooth Stack ID. @param BluetoothStackID This function passes to
|
|
* the caller the Bluetooth Stack ID. @param LLS_Event_Data The LLS Event Data that
|
|
* occurred. @param CallbackParameter The LLS Profile Event Callback Parameter that was
|
|
* specified when this Callback was installed. The caller is free to
|
|
* use the contents of the LLS 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 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 LLS 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 LLS Profile Event
|
|
* Packets. A Deadlock WILL occur because NO LLS Event
|
|
* Callbacks will be issued while this function is
|
|
* currently outstanding.
|
|
*/
|
|
typedef void (BTPSAPI *LLS_Event_Callback_t)(unsigned int BluetoothStackID, LLS_Event_Data_t *LLS_Event_Data, unsigned long CallbackParameter);
|
|
|
|
/*! LLS Server API. */
|
|
|
|
/*! @brief The following function is responsible for opening a LLS 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 LLS
|
|
* 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 LLS 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 LLS_Initialize_Service(unsigned int BluetoothStackID, LLS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef int (BTPSAPI *PFN_LLS_Initialize_Service_t)(unsigned int BluetoothStackID, LLS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID);
|
|
#endif
|
|
|
|
/*! @brief The following function is responsible for opening a LLS 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 LLS
|
|
* 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 LLS 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 LLS_Initialize_Service_Handle_Range(unsigned int BluetoothStackID, LLS_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_LLS_Initialize_Service_Handle_Range_t)(unsigned int BluetoothStackID, LLS_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
|
|
* opened LLS 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 successfully call to
|
|
* LLS_Initialize_Service(). @return This function returns a zero if
|
|
* successful or a negative return error code if an error occurs.
|
|
*/
|
|
BTPSAPI_DECLARATION int BTPSAPI LLS_Cleanup_Service(unsigned int BluetoothStackID, unsigned int InstanceID);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef int (BTPSAPI *PFN_LLS_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 LLS Service that is
|
|
* registered with a call to LLS_Initialize_Service().
|
|
* @return This function returns the non-zero number of attributes that are contained in a
|
|
* LLS Server or zero on failure.
|
|
*/
|
|
BTPSAPI_DECLARATION unsigned int BTPSAPI LLS_Query_Number_Attributes(void);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef unsigned int (BTPSAPI *PFN_LLS_Query_Number_Attributes_t)(void);
|
|
#endif
|
|
|
|
/*! @brief The following function is responsible for setting the Alert Level
|
|
* on the specified LLS Instance. @param BluetoothStackID The first parameter is
|
|
* Bluetooth Stack ID of the Bluetooth Device. @param InstanceID The second parameter
|
|
* is the InstanceID returned from a successful call to
|
|
* LLS_Initialize_Server(). @param Alert_Level The final parameter is the
|
|
* to set for the specified LLS Instance. @return This function returns
|
|
* a zero if successful or a negative return error code if an error
|
|
* occurs.
|
|
*/
|
|
BTPSAPI_DECLARATION int BTPSAPI LLS_Set_Alert_Level(unsigned int BluetoothStackID, unsigned int InstanceID, Byte_t Alert_Level);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef int (BTPSAPI *PFN_LLS_Set_Alert_Level_t)(unsigned int BluetoothStackID, unsigned int InstanceID, Byte_t Alert_Level);
|
|
#endif
|
|
|
|
/*! @brief The following function is responsible for querying the Alert Level
|
|
* on the specified LLS Instance.@param BluetoothStackID The first parameter is
|
|
* Bluetooth Stack ID of Bluetooth Device. @param InstanceID The second parameter is
|
|
* InstanceID returned from a successful call LLS_Initialize_Server
|
|
* @param Alert_Level The final parameter is a pointer to return the Alert Level
|
|
* specified LLS Instance. @return This function returns a zero if successful
|
|
* or a negative return error code if an error occurs.
|
|
*/
|
|
BTPSAPI_DECLARATION int BTPSAPI LLS_Query_Alert_Level(unsigned int BluetoothStackID, unsigned int InstanceID, Byte_t *Alert_Level);
|
|
|
|
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
|
|
typedef int (BTPSAPI *PFN_LLS_Query_Alert_Level_t)(unsigned int BluetoothStackID, unsigned int InstanceID, Byte_t *Alert_Level);
|
|
#endif
|
|
|
|
#endif
|