mirror/MuditaOS
1
0
Fork 0
mirror of https://github.com/mudita/MuditaOS.git synced 2026-06-15 03:55:03 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
41b6df457c3c674b40539ea4e36b202bb49f6bc3
MuditaOS/module-bluetooth/lib/Bluetopia/include/BSCAPI.h
pholat 530ffee55e Bluetopia library added as it is
2019-10-14 15:32:06 +02:00

828 lines
46 KiB
C
Raw Blame History

/*
* Copyright 2000 - 2014 Stonestreet One.
* All Rights Reserved.
* Author: Damon Lange
*** MODIFICATION HISTORY ****************************************************
*
* mm/dd/yy F. Lastname Description of Modification
* -------- ----------- ------------------------------------------------
* 09/11/00 D. Lange Initial creation.
* 09/18/08 T. Thomas Updates for BT 2.1
****************************************************************************
*/
/**
* @file BSCAPI.h
*
* @brief Stonestreet One Bluetooth Stack Controller API Type Definitions,
* Constants, and Prototypes. To use any of the following API's,
* include the following declaration in your application.
*
* @code
* #include "SS1BTPS.h"
* @endcode
* ============================================================================
*/
#ifndef __BSCAPIH__
#define __BSCAPIH__
#include "BTPSKRNL.h" /*! BTPS Kernel Prototypes/Constants. */
#include "BTAPITyp.h" /*! Bluetooth API Type Definitions. */
#include "BTTypes.h" /*! Bluetooth Type Definitions/Constants. */
#include "HCITypes.h" /*! Bluetooth HCI Type Definitions/Constants. */
#include "BTPSCFG.h" /*! BTPS Configuration Constants. */
/*! The following definitions, represent BIT Flags that can be used
* with the BSC_Initialize() function. These Bit Flags can be used
* to inform the Bluetooth Stack Controller of various Requested
* options.
*/
#define BSC_INITIALIZE_FLAG_NO_L2CAP 0x00000001L
#define BSC_INITIALIZE_FLAG_NO_SCO 0x00000002L
#define BSC_INITIALIZE_FLAG_NO_SDP 0x00000004L
#define BSC_INITIALIZE_FLAG_NO_RFCOMM 0x00000008L
#define BSC_INITIALIZE_FLAG_NO_GAP 0x00001000L
#define BSC_INITIALIZE_FLAG_NO_SPP 0x00002000L
#define BSC_INITIALIZE_FLAG_NO_GOEP 0x00004000L
#define BSC_INITIALIZE_FLAG_NO_OTP 0x00008000L
/*! The following type represents the defined List Entry Keys that
* can be searched on using the Generic List Entry routines that are
* present in this file.
*/
typedef enum
{
ekNone,
ekBoolean_t,
ekByte_t,
ekWord_t,
ekDWord_t,
ekBD_ADDR_t,
ekEntryPointer,
ekUnsignedInteger
} BSC_Generic_List_Entry_Key_t;
/*! The following constants are used with @brief The following functions:
* - BSC_EnableFeature()
* - BSC_DisableFeature()
* - BSC_QueryActiveFeatures()
* \note This functionality is not normally supported by default
* (i.e. a custom stack build is required to enable this
* functionality).
*/
#define BSC_FEATURE_BLUETOOTH_LOW_ENERGY 0x00000001
#define BSC_FEATURE_ANT_PLUS 0x00000002
#define BSC_FEATURE_WIDE_BAND_SPEECH 0x00000004
#define BSC_FEATURE_A3DP_SOURCE 0x00000008
#define BSC_FEATURE_A3DP_SINK 0x00000010
/*! The following defines the valid Result Values that can be returned
* in the Result field of the Authentication Request Event.
*/
#define BSC_AUTHENTICATION_REQUEST_RESULT_SUCCESS 0x00
#define BSC_AUTHENTICATION_REQUEST_RESULT_IN_PROGRESS 0x01
#define BSC_AUTHENTICATION_REQUEST_RESULT_REFUSED 0x02
#define BSC_AUTHENTICATION_REQUEST_RESULT_FAILURE 0x03
/*! The following enumerated type represents the BSC Event Reason
* (and valid Data) and is used with the BSC Event Callback.
*/
typedef enum
{
etAuthenticationRequest /*!< Event that signals that an authentication request has been received. */
} BSC_Event_Type_t;
/*! The following structure defines the Authentication Request Event
* data.
*/
typedef struct _tagBSC_Authentication_Request_t
{
BD_ADDR_t BD_ADDR;
Byte_t *Result;
} BSC_Authentication_Request_t;
#define BSC_AUTHENTICATION_REQUEST_SIZE (sizeof(BSC_Authentication_Request_t))
/*! The following structure represents the container structure that
* holds all BSC Event Data Data.
*/
typedef struct _tagBSC_Event_Data_t
{
BSC_Event_Type_t Event_Type;
DWord_t Event_Data_Length;
union
{
BSC_Authentication_Request_t *BSC_Authentication_Request;
} Event_Data;
} BSC_Event_Data_t;
#define BSC_EVENT_DATA_SIZE (sizeof(BSC_Event_Data_t))
/*! The following declared type represents the Prototype Function for
* an Bluetooth Stack Timer Callback. This function will be called
* whenever an installed Timer has expired (installed via the
* BSC_StartTimer() function).
* @param BluetoothStackID Which device stack this packet is from.
* @param TimerID Timer Identifier of the timer that has expired.
* This value will be the same as the value returned from a successful call
* to the BSC_StartTimer function.
* @param CallbackParameter User-defined parameter (e.g., tag value) that
* was defined in the timer callback registration.
* 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 reentrant). 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 no other Timer and/or Stack Callbacks will be
* issued while function call is outstanding).
* \note This function MUST NOT Block and wait for events that
* can only be satisfied by Receiving other Stack Events.
* A Deadlock WILL occur because NO Stack Event Callbacks
* will be issued while this function is currently
* outstanding.
*/
typedef void (BTPSAPI *BSC_Timer_Callback_t)(unsigned int BluetoothStackID, unsigned int TimerID, unsigned long CallbackParameter);
/*! The following declared type represents the Prototype Function for
* an Bluetooth Stack Debug Data Callback. This function will be
* called whenever a complete HCI Packet has been sent or received by
* the Bluetooth Device that was opened with the Bluetooth Protocol
* Stack.
* @param BluetoothStackID Which device stack this
* packet is from.
* @param Packetsent TRUE if HCI packet was sent, FALSE
* if it was received.
* @param HCIPacket Pointer to packet contents
* @param CallbackParameter User-defined parameter
* (e.g., tag value) that was defined in the callback registration.
* This function passes to the caller the HCI Packet that
* was received and the Debug Callback Parameter that was specified
* when this Callback was installed. The caller is free to use the
* contents of the HCI Packet ONLY in the context of this callback.
* 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 reentrant). 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 Packet Processing
* (Sending/Receiving) will be suspended while function call is
* outstanding).
* \note THIS FUNCTION MUST NOT CALL ANY BLUETOOTH STACK
* FUNCTIONS ! FAILURE TO FOLLOW THIS GUIDELINE WILL
* RESULT IN POTENTIAL DEADLOCKS AND/OR ERRATIC
* BEHAVIOR !
* The Debug Callback is a VERY LOW LEVEL Callback and as
* such, does NOT allow the Bluetooth Stack to be
* re-entrant !
*/
typedef void (BTPSAPI *BSC_Debug_Callback_t)(unsigned int BluetoothStackID, Boolean_t PacketSent, HCI_Packet_t *HCIPacket, unsigned long CallbackParameter);
/*! The following declared type represents the Prototype Function for
* a Bluetooth Stack Cleanup Function Callback. This function will
* be called once, whenever a call is made to shutdown the Bluetooth
* stack. This function is called from within the context of the
* BSC_Shutdown function. 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 reentrant).
* @param BluetoothStackID The first parameter specifies the Bluetooth Stack identifier obtained
* from the successful BSC_Initialize function return.
* @param CallbackParameter The second parameter is a User defined value that will passed to the
* Callback Parameter when it is called.
*/
typedef void (BTPSAPI *BSC_Cleanup_Callback_t)(unsigned int BluetoothStackID, unsigned long CallbackParameter);
/*! The following declared type represents the Prototype Function for
* the BSC Event Receive Data Callback. This function will be called
* whenever a Callback has been registered for the specified BSC
* Action that is associated with the specified Bluetooth Stack ID.
* @param BluetoothStackID Bluetooth Stack ID of the Bluetooth Stack
* that generated the event.
* @param BSC_Event_Data Pointer to the BSC Event Data of the
* specified event.
* @param CallbackParameter User-defined parameter
* (e.g., tag value) that was defined in the callback registration.
* This function passes to the caller the Bluetooth Stack ID, the BSC
* Event Data of the specified Event, and the BSC Event Callback
* Parameter that was specified when this Callback was installed.
* The caller is free to use the contents of the BSC 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
* reentrant). 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
* other BSC Events 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 other BSC Events. A
* Deadlock WILL occur because NO BSC Event Callbacks will
* be issued while this function is currently outstanding.
*/
typedef void (BTPSAPI *BSC_Event_Callback_t)(unsigned int BluetoothStackID, BSC_Event_Data_t *BSC_Event_Data, unsigned long CallbackParameter);
/*! The following declared type represents the Prototype Function for
* the BSC Asynchronous Callback. This function will be called once
* for each call to BSC_ScheduleAsynchronousCallback.
* @param BluetoothStackID Bluetooth Stack ID of the Bluetooth Stack
* that issued the call to BSC_ScheduleAsynchronousCallback.
* @param CallbackParameter User-defined parameter (e.g., tag value)
* that was defined in the callback registration.
* 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.
* \note The caller should keep the processing of these
* Callbacks small because other Events will not be able
* to be called while one is being serviced.
*/
typedef void (BTPSAPI *BSC_AsynchronousCallbackFunction_t)(unsigned int BluetoothStackID, unsigned long CallbackParameter);
/*! @brief The following function is responsible for Initializing a Bluetooth
* Protocol Stack for the specified Bluetooth Device (using the
* specified HCI Transport). This function *MUST* be called (and
* complete successfully) before any function in this module can be
* called. @param HCI_DriverInformation The first parameter specifies the Bluetooth HCI Driver
* Transport Information to use when opening the Bluetooth Device
* and @param Flags The second parameter specifies Flags that are to be used to
* alter the base Bluetooth Protocol Stack Functionality. The HCI
* Driver Information parameter is NOT optional and must specify a
* valid Bluetooth HCI Driver transport provided by this Protocol
* Stack Implementation. The flags parameter should be zero unless
* altered functionality is required. @return Upon successfuly completion,
* this function will return a positive, non-zero, return value.
* This value will be used as input to functions provided by the
* Bluetooth Protocol Stack that require a Bluetooth Protocol Stack
* ID (functions that operate directly on a Bluetooth Device). If
* this function fails, the return value will be a negative return
* code which specifies the error (see error codes defined
* elsewhere). Once this function completes the specified Bluetooth
* Protocol Stack ID will remain valid for the specified Bluetooth
* Device until the Bluetooth Stack is Closed via a call to the
* BSC_Shutdown() function.
* \note The Bit Mask values for the Flags Parameter are defined
* at the top of this file.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_Initialize(HCI_DriverInformation_t *HCI_DriverInformation, unsigned long Flags);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_Initialize_t)(HCI_DriverInformation_t *HCI_DriverInformation, unsigned long Flags);
#endif
/*! @brief The following function is responsible for Closing the Bluetooth
* Protocol Stack that was opened for the Bluetooth Device specified
* via a successful call to the BSC_Initialize() function.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth Protocol
* Stack via a call to BSC_Initialize. Once this function
* completes, the Bluetooth Device that was opened (and the Bluetooth
* Protocol Stack that is associated with the Device) cannot be
* accessed again until the Device (and a corresponding Bluetooth
* Protocol Stack is Re-Opened by calling the BSC_Initialize()
* function.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_Shutdown(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_Shutdown_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is a Debugging function that allows the
* caller to register a Debugging Callback that will be called EACH
* Time a HCI Packet is Sent or Received. Because this Function will
* be called every time a Packet is Sent or Received, this function
* should only be used when debugging is required because of the
* Performance Penalty that is present when using this mechanism.
* @param BluetoothStackID The first parameter is obtained by a successful call to the
* BSC_Initialize() function. @param BSC_DebugCallback The second parameter is a pointer
* to a function that is to be called when an HCI Packet (of any
* type) is Sent OR Received on the specified Bluetooth Protocol
* Stack (specified by the first parameter). @param CallbackParameter
* This is a User defined value that will passed to the Callback
* Parameter when it is called. @return The return value of this function
* will be a non-zero, non-negative value on success or a negative
* return code if there was a failure. Once a Debug Callback
* has been installed, it can ONLY be removed via a call to the
* BSC_UnRegisterDebugCallback() function.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_RegisterDebugCallback(unsigned int BluetoothStackID, BSC_Debug_Callback_t BSC_DebugCallback, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_RegisterDebugCallback_t)(unsigned int BluetoothStackID, BSC_Debug_Callback_t BSC_DebugCallback, unsigned long CallbackParameter);
#endif
/*! @brief The following function is responsible for Removing a previously
* installed Debug Callback for the specified Bluetooth Protocol
* Stack (specified by the specified BluetoothStackID parameter).
* After this function has completed, the caller will no longer be
* Notified via the Debug Callback Function when a debug event
* occurs.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_UnRegisterDebugCallback(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_UnRegisterDebugCallback_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is provided to allows the caller to
* register an Event Callback that will be called when an upper layer
* module requires a specific function that is provided by another
* layer. @param BluetoothStackID The first parameter is obtained by a successful call to
* the BSC_Initialize() function. @param BSC_EventCallback The second parameter is a pointer
* to a function that is to be called when an BSC Event is
* dispatched. @param CallbackParameter This parameter is a User defined
* value that will passed to the Callback Function when it is
* called. @return The return value of this function will be a non-zero,
* non-negative value on success or a negative return code if there
* was a failure. Once an Event Callback has been installed, it can
* ONLY be removed via a call to the BSC_UnRegisterEventCallback()
* function.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_RegisterEventCallback(unsigned int BluetoothStackID, BSC_Event_Callback_t BSC_EventCallback, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_RegisterEventCallback_t)(unsigned int BluetoothStackID, BSC_Event_Callback_t BSC_EventCallback, unsigned long CallbackParameter);
#endif
/*! @brief The following function is responsible for Removing a previously
* installed EVent Callback for the specified Bluetooth Protocol
* Stack (specified by the specified BluetoothStackID parameter).
* @param BluetoothStackID The first parameter is obtained by a successful call to
* the BSC_Initialize() function.
* After this function has completed, the caller will no longer be
* Notified via the Event Callback Function when a BSC event occurs.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_UnRegisterEventCallback(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_UnRegisterEventCallback_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is a low-level primitive that allows the
* caller the ability to 'Lock' the Bluetooth Protocol Stack so that
* no other thread has access to the specified Bluetooth Protocol
* Stack. This functionality is provided to allow the programmer the
* means to guard against the Bluetooth Protocol Stack calling a
* Bluetooth Event Callback and potentially leading to a Thread
* Problem if Mutexes/Semaphores are being used. This function is
* completely safe to be called in any context (except Debug
* Callbacks).
* @param BluetoothStackID The first parameter is obtained by a successful call to
* the BSC_Initialize() function.
* @return This function returns zero if the specified Bluetooth Protocol
* Stack was successfully 'Locked' or a negative return error code if
* an error occurred. Once the Bluetooth Stack is successfully
* Locked it *MUST* be unlocked manually by calling the
* BSC_UnLockBluetoothStack() function. Failure to call the UnLock
* function after successfully locking the Bluetooth Protocol Stack
* will result in the Bluetooth Stack to quit responding.
* \note This function is NOT required to be called before
* calling Bluetooth Protocol Stack functions!
* \note This function is provided for applications that need
* require the Bluetooth Protocol Stack to force all
* Resource protection. In many cases (almost all) this
* function (and it's counterpart, the
* the BSC_UnLockBluetoothStack() function) will not need
* to be used. This function SHOULD BE USED WITH EXTREME
* CAUTION!
* \note Multiple calls to this function are possible, however
* there *MUST* be a corresponding call to the
* BSC_UnLockBluetoothStack() function for each successful
* call that is made to this function. Failure to call the
* BSC_UnLockBluetoothStack() function the same amount of
* times will yield the Bluetooth Stack un-usable.
* \note The programmer using this function can guard against the
* case of being interrupted by the Bluetooth Protocol Stack
* while issuing more than one Bluetooth Protocol Stack
* operation. This allows the caller some guarantee that
* the stack will not cause a non-reentrant operation on
* data structures that might need to be protected. This
* function allows the caller to use the same protection
* that the Bluetooth Protocol Stack uses to avoid potential
* dead-lock conditions.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_LockBluetoothStack(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_LockBluetoothStack_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is provided to allow the programmer a
* mechanism for releasing an existing 'Lock' that was acquired on
* the specified Bluetooth Protocol Stack.
* @param BluetoothStackID The first parameter is obtained by a successful call to
* the BSC_Initialize() function.
* The Bluetooth Protocol Stack is considered 'Locked' if the the caller called the
* BSC_LockBluetoothStack() function (and it was successful). Please
* see the BSC_LockBluetoothStack() function for more information.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_UnLockBluetoothStack(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_UnLockBluetoothStack_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is provided to allow a mechanism to start
* a Timer of the specified Time out (in Milliseconds and NOT zero),
* and call the specified Timer Callback function when the timer
* expires.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize
* @param Timeout Timeout value (in milliseconds)
* @param BSC_TimerCallback Pointer to a user-supplied callback function
* which is defined as above in the BSC callback section.
* @param CallbackParameter A user-defined parameter (e.g., a tag value)
* that will be passed back to the user in the callback function when the timer expires.
* @return This function returns the
* Timer ID of the newly created Timer if successful (positive AND
* NON-zero). This Timer ID can be used when calling BSC_StopTimer()
* function if the specified Timer has not expired. The Timer ID's
* are always greater than zero. If the Timer was not able to be
* started, a negative return error code is returned.
* \note All Timers supported by this module are one-shot timers
* only. This means that after the Timer expires and the
* the caller is notified, no other Timeout will occur.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_StartTimer(unsigned int BluetoothStackID, unsigned long Timeout, BSC_Timer_Callback_t BSC_TimerCallback, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_StartTimer_t)(unsigned int BluetoothStackID, unsigned long Timeout, BSC_Timer_Callback_t BSC_TimerCallback, unsigned long CallbackParameter);
#endif
/*! @brief The following function is provided to allow a mechanism for
* stopping a Timer that was previously started with the
* BSC_StartTimer() function.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize
* @param TimerID Timer indentifier of the timer that is to be stopped.
* This value must be a successful return value from the BSC_StartTimer function.
* @return This function returns zero if successful, or a negative return error
* code if there was error stopping the specified Timer.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_StopTimer(unsigned int BluetoothStackID, unsigned int TimerID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_StopTimer_t)(unsigned int BluetoothStackID, unsigned int TimerID);
#endif
/*! @brief The following function is provided to allow a mechanism for any
* layer to request that a connected device be authenticated.
* @param BluetoothStackID Unique identifier assigned
* to this Bluetooth Protocol Stack via a call to BSC_Initialize
* @param BD_ADDR Bluetooth device address of device
* that is to be authenticated
* @param Result Variable that is to receive the status
* result from the request.
* @return This function returns zero if successful, or a negative return error code if the
* Authentication process was not started.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_AuthenticateDevice(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Byte_t *Result);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_AuthenticateDevice_t)(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Byte_t *Result);
#endif
/*! @brief The following function is provided to allow a mechanism for any
* layer request the stack controller to enable an individual feature
* of the Bluetooth Protocol Stack.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize.
* @param Feature Feature to enable.
* @return This function returns zero if
* successful or a negative return error code if there was an error.
* \note This functionality is not normally supported by default
* (i.e. a custom stack build is required to enable this
* functionality).
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_EnableFeature(unsigned int BluetoothStackID, unsigned long Feature);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_EnableFeature_t)(unsigned int BluetoothStackID, unsigned long Feature);
#endif
/*! @brief The following function is provided to allow a mechanism for any
* layer request the stack controller to disable an individual
* feature of the Bluetooth Protocol Stack.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize.
* @param Feature Feature to disable.
* @return This function returns
* zero if successful or a negative return error code if there was an
* error.
* \note This functionality is not normally supported by default
* (i.e. a custom stack build is required to enable this
* functionality).
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_DisableFeature(unsigned int BluetoothStackID, unsigned long Feature);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_DisableFeature_t)(unsigned int BluetoothStackID, unsigned long Feature);
#endif
/*! @brief The following function is provided to allow a mechanism for any
* layer query the stack controller to determine if an individual
* feature of the Bluetooth Protocol Stack is currently active.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth Protocol Stack via a call to BSC_Initialize.
* @param Feature Pointer to a buffer that will contain the features that are currently enabled/active.
* @return This function returns zero if successful or a negative return error
* code if there was an error.
* \note This functionality is not normally supported by default
* (i.e. a custom stack build is required to enable this
* functionality).
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_QueryActiveFeatures(unsigned int BluetoothStackID, unsigned long *Feature);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_QueryActiveFeatures_t)(unsigned int BluetoothStackID, unsigned long *Feature);
#endif
/*! @brief The following function is provided as a mechanism to determine if
* the specified Bluetooth Protocol Stack is "Idle". "Idle" in this
* case means that there is no pending processing. This is useful
* in single threaded operating environments to be able to allow the
* processor to sleep for power savings.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize
@return This function returns
* BOOLEAN TRUE if the stack is currently idle or FALSE if the
* specified Bluetooth stack is either currently processing data or
* has pending data to process.
* \note This function is only applicable for single threaded
* operating environments. On multi-threaded operating
* environments this function always returns TRUE.
*/
BTPSAPI_DECLARATION Boolean_t BTPSAPI BSC_QueryStackIdle(unsigned int BluetoothStackID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef Boolean_t (BTPSAPI *PFN_BSC_QueryStackIdle_t)(unsigned int BluetoothStackID);
#endif
/*! @brief The following function is provided as a mechanism for scheduling
* an Asynchronous Callback. This function will be scheduled to be
* Dispatched (called back) from another Thread.
* @param BluetoothStackID Unique identifier assigned to this Bluetooth
* Protocol Stack via a call to BSC_Initialize
* @param AsynchronousCallbackFunction The callback function.
* @param CallbackParameter A user-defined parameter (e.g., a tag value)
* that will be passed back to the user in the callback function when it is called.
* @return This function returns a non-zero value if successful or zero if
* the callback was not able to be scheduled.
* \note Once an Asynchronous Callback is scheduled it cannot be
* removed.
*/
BTPSAPI_DECLARATION int BTPSAPI BSC_ScheduleAsynchronousCallback(unsigned int BluetoothStackID, BSC_AsynchronousCallbackFunction_t AsynchronousCallbackFunction, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_BSC_ScheduleAsynchronousCallback_t)(unsigned int BluetoothStackID, BSC_AsynchronousCallbackFunction_t AsynchronousCallbackFunction, unsigned long CallbackParameter);
#endif
/*! @brief The following function is an internal function that exists to
* acquire a global lock that can be used to search lists that are
* maintained by modules (for resource tracking). This Lock CANNOT
* be held while holding or acquiring any other lock. This
* functionality is provided to allow a mechanism on smaller
* (embedded) systems so that individual modules (such as the HCI
* Drivers) to do not have to waste resources for Mutexes to protect
* their internal lists.
* @return BOOLEAN value, TRUE if the list lock was obtained successfully,
* FALSE if the lock was unable to be obtained (or an error occurred).
* \note The caller *MUST* call BSC_ReleaseListLock() when
* finished to release the lock.
*/
BTPSAPI_DECLARATION Boolean_t BTPSAPI BSC_AcquireListLock(void);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef Boolean_t (BTPSAPI *PFN_BSC_AcquireListLock_t)(void);
#endif
/*! @brief The following function is provided to allow a mechansim for the
* caller to release the List Lock (previously acquired via a
* successful call to the BSC_AcquireListLock() function).
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_ReleaseListLock(void);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_ReleaseListLock_t)(void);
#endif
/*! @brief The following function is a utility function that adds the actual
* specified List Entry to the specified Generic List Entry List.
* @param GenericListEntryKey Key value type that is used to search for
* duplicates (see notes above).
* @param ListEntryKeyOffset Offset (specified in bytes) from the
* beginning of the list entry where the list entry key is located
* @param ListEntryNextPointerOffset Offset (specified in bytes)
* from the beginning of the list entry where the list entry next pointer is located
* @param ListHead Pointer to the location that holds a pointer to
* the first entry in the list (the value at this location can be NULL for
* an empty list, but this parameter cannot be NULL)
* @param ListEntryToAdd Pointer to the actual list entry that is
* to be added to the specified list (note that the offsets specified in the
* prior parameters are applied to this address to resolve the correct locations)
* @return This function returns a BOOLEAN TRUE value if
* successful or BOOLEAN FALSE if the specified entry could not be
* added to the list.
* \note Valid values must be specified for the following
* parameters (or the function will fail):
* - ListHead - parameter cannot be NULL, but the value
* that it points to can be NULL.
* - ListEntryToAdd - parameter cannot be NULL, and it
* must point to the List Entry Data that is to be
* added (of size ListEntrySize).
* \note If the GenericListEntryKey value is anything other than
* ekNone, then this function does not insert duplicate
* entries into the list. An item is considered a duplicate
* if the Key value of the entry being added matches any
* Key value of an entry already in the list. When this
* parameter is ANYTHING OTHER THAN ekNone, then the
* following parameters must be specified:
* - ListEntryKeyOffset - specifies the byte offset of
* the Generic List Entry Key Element (in each
* individual List Entry).
* \note In all cases, the ListEntryNextPointerOffset parameter
* MUST specify the byte offset of the element that
* represents a pointer to the next element that is present
* in the list (for each individual List Entry).
*/
BTPSAPI_DECLARATION Boolean_t BTPSAPI BSC_AddGenericListEntry_Actual(BSC_Generic_List_Entry_Key_t GenericListEntryKey, unsigned int ListEntryKeyOffset, unsigned ListEntryNextPointerOffset, void **ListHead, void *ListEntryToAdd);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef Boolean_t (BTPSAPI *PFN_BSC_AddGenericListEntry_Actual_t)(BSC_Generic_List_Entry_Key_t GenericListEntryKey, unsigned int ListEntryKeyOffset, unsigned ListEntryNextPointerOffset, void **ListHead, void *ListEntryToAdd);
#endif
/*! @brief The following function is a utility function that adds the
* specified List Entry to the specified Generic List Entry List.
* @param ListEntrySizeToAllocate Entire size (in bytes) of the entry
* to allocate. Note that this is note the size of the list entry itself.
* This value must be AT-LEAST the size of ListEntrySize, but can be specified larger.
* This allows the ability to allocate extra space immediately after the list entry.
* @param GenericListEntryKey Key value type that is used to search for
* duplicates (see notes above).
* @param ListEntryKeyOffset Offset (specified in bytes) from the beginning
* of the list entry where the list entry key is located
* @param ListEntrySize Specifies the size (in bytes) of the list entry size.
* This size is used to copy the specified list entry information (final parameter)
* to the newly allocated list entry.
* @param ListEntryNextPointerOffset Offset (specified in bytes) from the
* beginning of the list entry where the list entry next pointer is located
* @param ListHead Pointer to the location that holds a pointer to the first
* entry in the list (the value at this location can be NULL for an empty list,
* but this parameter cannot be NULL)
* @param ListEntryToAdd Pointer to the actual list entry that is to be added
* to the specified list (note that the offsets specified in the prior parameters
* are applied to this address to resolve the correct locations).
* @return This function returns
* a pointer to the element that was added to the list (if
* successful) or NULL if the specified entry could not be added to
* the list.
* \note Valid values must be specified for the following
* parameters (or the function will fail):
* - ListEntrySizeToAllocate - cannot be zero and MUST
* be greater than or equal to the ListEntrySize
* parameter.
* - ListEntrySize - cannot be zero and MUST be less
* than or equal to the ListEntrySizeToAllocate
* parameter.
* - ListHead - parameter cannot be NULL, but the value
* that it points to can be NULL.
* - ListEntryToAdd - parameter cannot be NULL, and it
* must point to the List Entry Data that is to be
* added (of size ListEntrySize).
* \note If the GenericListEntryKey value is anything other than
* ekNone, then this function does not insert duplicate
* entries into the list. An item is considered a duplicate
* if the Key value of the entry being added matches any
* Key value of an entry already in the list. When this
* parameter is ANYTHING OTHER THAN ekNone, then the
* following parameters must be specified:
* - ListEntryKeyOffset - specifies the byte offset of
* the Generic List Entry Key Element (in each
* individual List Entry).
* \note In all cases, the ListEntryNextPointerOffset parameter
* MUST specify the byte offset of the element that
* represents a pointer to the next element that is present
* in the list (for each individual List Entry).
*/
BTPSAPI_DECLARATION void *BTPSAPI BSC_AddGenericListEntry(unsigned int ListEntrySizeToAllocate, BSC_Generic_List_Entry_Key_t GenericListEntryKey, unsigned int ListEntryKeyOffset, unsigned int ListEntrySize, unsigned ListEntryNextPointerOffset, void **ListHead, void *ListEntryToAdd);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void *(BTPSAPI *PFN_BSC_AddGenericListEntry_t)(unsigned int ListEntrySizeToAllocate, BSC_Generic_List_Entry_Key_t GenericListEntryKey, unsigned int ListEntryKeyOffset, unsigned int ListEntrySize, unsigned ListEntryNextPointerOffset, void **ListHead, void *ListEntryToAdd);
#endif
/*! @brief The following function is a utility function that exists to search
* for an individual Generic List Entry that is present in the
* specified Generic List Entry List.
* @param GenericListEntryKey Key value type that is used
* to search the entries.
* @param GenericListEntryKeyValue Pointer to the key value that
* is to matched for the search. The actual data type that this value points
* to depends upon the value of the previous parameter. \note This value CANNOT be NULL.
* @param ListEntryKeyOffset Offset (specified in bytes)
* from the beginning of each list entry where the list entry key is located
* @param ListEntryNextPointerOffset Offset (specified
* in bytes) from the beginning of each list entry where the list entry next
* pointer is located
* @param ListHead Pointer to the location that holds a
* pointer to the first entry in the list (the value at this location can be
* NULL for an empty list, but this parameter cannot be NULL)
* @return This function returns
* a pointer to the specified List Entry Element (if it was found
* in the specified list) or NULL if the element could not be found
* in the list.
*/
BTPSAPI_DECLARATION void *BTPSAPI BSC_SearchGenericListEntry(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryKeyOffset, unsigned ListEntryNextPointerOffset, void **ListHead);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void *(BTPSAPI *PFN_BSC_SearchGenericListEntry_t)(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryKeyOffset, unsigned ListEntryNextPointerOffset, void **ListHead);
#endif
/*! @brief The following function is a utility function that exists to search
* the list for the next Generic List Entry.
* @param GenericListEntryKey Key value type that is used to search the entries.
* @param GenericListEntryKeyValue Pointer to the key value that is to matched for the search.
* The actual data type that this value points to depends upon the value of the
* previous parameter. Note that this value CANNOT be NULL.
* @param ListEntryNextPointerOffset Offset (specified in bytes) from the beginning
* of each list entry where the list entry next pointer is located
* @param ListHead Pointer to the location that holds a pointer to the first entry
* in the list (the value at this location can be NULL for an empty list,
* but this parameter cannot be NULL)
* @return This function returns a pointer to the specified List Entry Element (if it was
* found in the specified list) or NULL if the element could not be
* found in the list.
*/
BTPSAPI_DECLARATION void *BTPSAPI BSC_GetNextGenericListEntry(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryNextPointerOffset, void **ListHead);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void *(BTPSAPI *PFN_BSC_GetNextGenericListEntry_t)(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryNextPointerOffset, void **ListHead);
#endif
/*! @brief The following function is a utility function that exists to search
* for an individual Generic List Entry that is present in the
* specified Generic List Entry List and remove it from the specified
* list.
* @param GenericListEntryKey Key value type that is used to search the entries.
* @param GenericListEntryKeyValue Pointer to the key value that is to matched
* for the search. The actual data type that this value points to depends
* upon the value of the previous parameter. Note that this value CANNOT be NULL.
* @param ListEntryKeyOffset Offset (specified in bytes) from the
* beginning of each list entry where the list entry key is located
* @param ListEntryNextPointerOffset Offset (specified in bytes)
* from the beginning of each list entry where the list entry next pointer is located
* @param ListHead Pointer to the location that holds a pointer
* to the first entry in the list (the value at this location can be
* NULL for an empty list, but this parameter cannot be NULL)
* @return This function returns a pointer to the specified List
* Entry Element (if it was found and removed from the specified
* list) or NULL if the element could not be found in the list.
* \note This function does not free the resources of the element
* that was deleted from the List, it only removes it from
* the list and returns a pointer to the element. The
* Next Pointer element of the returned element will have
* it's value set to NULL.
* \note It is the callers responsibility to free the memory that
* is occuppied by the specified list (when finished) by
* calling the BSC_FreeGenericListEntryMemory() function.
*/
BTPSAPI_DECLARATION void *BTPSAPI BSC_DeleteGenericListEntry(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryKeyOffset, unsigned int ListEntryNextPointerOffset, void **ListHead);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void *(BTPSAPI *PFN_BSC_DeleteGenericListEntry_t)(BSC_Generic_List_Entry_Key_t GenericListEntryKey, void *GenericListEntryKeyValue, unsigned int ListEntryKeyOffset, unsigned int ListEntryNextPointerOffset, void **ListHead);
#endif
/*! @brief This function frees the specified Generic List Entry ember. No
* check is done on this entry other than making sure it NOT NULL.
* @param EntryToFree Pointer to the the actual opaque list entry memory that is be freed.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_FreeGenericListEntryMemory(void *EntryToFree);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_FreeGenericListEntryMemory_t)(void *EntryToFree);
#endif
/*! @brief The following function deletes (and free's all memory) every
* element of the specified Generic List Entry List. Upon return of
* this function, the Head Pointer is set to NULL.
* @param ListHead Pointer to the location that holds a pointer to the first entry
* in the list (the value at this location can be NULL for an empty list, but this
* parameter cannot be NULL)
* @param ListEntryNextPointerOffset Offset (specified in bytes) from the beginning
* of each list entry where the list entry next pointer is located.
*/
BTPSAPI_DECLARATION void BTPSAPI BSC_FreeGenericListEntryList(void **ListHead, unsigned int ListEntryNextPointerOffset);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef void (BTPSAPI *PFN_BSC_FreeGenericListEntryList_t)(void **ListHead, unsigned int ListEntryNextPointerOffset);
#endif
#endif
Reference in New Issue View Git Blame Copy Permalink