TI’s Bluetooth stack is implementation of the upper layers of the Bluetooth protocol stack. TI’s Bluetooth stackprovides a robust and flexible software development tool that implements the Bluetooth Protocols and Profiles above the Host Controller Interface (HCI). TI’s Bluetooth stack's Application Programming Interface (API) provides access to the upper-layer protocols and profiles and can interface directly with the Bluetooth chips.

This page describes the various commands that a user of the application can use. Each command is a wrapper over a TI’s Bluetooth stack API which gets invoked with the parameters selected by the user. This is a subset of the APIs available to the user. TI’s Bluetooth stack API documentation (TI_Bluetooth_Stack_Version-Number\Documentation or for STM32F4, TI_Bluetooth_Stack_Version-Number\RTOS_VERSION\Documentation) describes all of the API's in detail.

Description

RegisterANS is responsible for registering a ANP Service.

Parameters

It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values

(0) Successfully registered ANP service

(-4) Function_Error

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1001)ANS_ERROR_INSUFFICIENT_RESOURCES

(-1002)ANS_ERROR_SERVICE_ALREADY_REGISTERED

API Call

ANS_Initialize_Service(BluetoothStackID, ANS_EventCallback, NULL, &ANSInstanceID)

API Prototype

int BTPSAPI ANS_Initialize_Service(unsigned int BluetoothStackID, ANS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID)

Description of API

This function is responsible for opening a ANS Server.The first parameter is the Bluetooth Stack ID on which to open the Server. The second parameter is the Callback function to call when an event occurs on this Server Port. The third parameter is a user-defined callback parameter that will be passed to the callback function with each event. The final parameter is a pointer to store the GATT Service ID of the registered ANS service. This can be used to include the service registered by this call. This function returns the positive, non-zero, Instance ID or a negative error code.

Description

UnRegisterANS is responsible for unregistering a ANP Service.

Parameters

It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values

(0)Successfully unregistered ANP service

(-4) Function_Error

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Cleanup_Service(BluetoothStackID, ANSInstanceID)

API Prototype

int BTPSAPI ANS_Cleanup_Service(unsigned int BluetoothStackID, unsigned int InstanceID)

Description of API

The following function is responsible for closing a previously opened ANS Server. The first parameter is the Bluetooth Stack ID on which to close the Server. The second parameter is the InstanceID that was returned from a successfull call to ANS_Initialize_Service(). This function returns a zero if successful or a negative return error code if an error occurs.

Description

DiscoverANS is responsible for performing a ANP Service Discovery Operation. This function will return zero on successful execution and a negative value on errors.

Parameters

It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values

(0)Successfully unregistered ANP service

(-4) Function_Error

API Call

GDIS_Service_Discovery_Start(BluetoothStackID, ConnectionID, (sizeof(UUID)/sizeof(GATT_UUID_t)), UUID, GDIS_Event_Callback, sdANS)

API Prototype

int BTPSAPI GDIS_Service_Discovery_Start(unsigned int BluetoothStackID, unsigned int ConnectionID, unsigned int NumberOfUUID, GATT_UUID_t *UUIDList, GDIS_Event_Callback_t ServiceDiscoveryCallback, unsigned long ServiceDiscoveryCallbackParameter)

Description of API

The GDIS_Service_Discover_Start is in an application module called GDIS that is provided to allow an easy way to perform GATT service discovery. This module can and should be modified for the customers use. This function is called to start a service discovery operation by the GDIS module.

Description

ConfigureRemoteANS is responsible for configure a ANP Service on a remote device. This function will return zero on successful execution and a negative value on errors.

Parameters

There are two parameters for this command, they are [New Alert Notify (0 = disable, 1 = enable)] and [Unread Alert Status Notify (0 = disable, 1 = enable)].

Possible Return Values

(0) CCCD Configuration Success

(-4) FUNCTION_ERROR

(-6) BTPS_ERROR_INVALID_PARAMETER

Description

NotifyNewAlerts is responsible for performing a New Alert notification to a connected remote device. This function will return zero on successful execution and a negative value on errors.

Parameters

[BitMask (0xXXXX)]

Category(bit values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Sending New Alert Notification for 'category'... Success

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

NotifyUnreadAlerts is responsible for performing an Unread Alert notification to a connected remote device. This function will return zero on successful execution and a negative value on errors.

Parameters

[BitMask (0xXXXX)]

Category(bit values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Sending Unread Alert Notification for 'category'... Success

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

GetNewAlertStatus is responsible for reading the New Alert Status for a specified category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Get New Alert Status request sent

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scNewAlert, &SupportedCategories))

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

SetNewAlertStatus is responsible for writing the New Alert Status for a specified category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category] [Num Alerts] [Alert String (Optional)]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Set New Alert Status success

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scNewAlert, &SupportedCategories)

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

GetUnreadAlertStatus is responsible for reading the Unread Alert Status for a specified category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Get Unread Alert Status request sent

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scUnreadAlertStatus, &SupportedCategories)

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

SetUnreadAlertStatus is responsible for writing the Unread Alert Status for a specified category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category][NUM VALUES]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Set Unread Alert Status success

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scUnreadAlertStatus, &SupportedCategories)

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

GetSupportedNewAlertCategories is responsible for reading the Supported New Alert Category. It can be executed by a Server or a Client with an open connection to a remote Server. If executed as a Client, a GATT read request will be generated, and the results will be returned as a response in the GATT Client event callback. This function will return zero on successful execution and a negative value on errors.

Parameters

It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values

(0) Get Supported New Alert Category Request sent, Transaction ID = %u

(-4) FUNCTION_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scNewAlert, &SupportedCategories)

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

SetSupportedNewAlertCategories is responsible for writing the Supported New Alert Category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[BitMask (0xXXXX)]

Category(bit values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Supported New Alert Category successfully set

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Set_Supported_Categories(BluetoothStackID, ANSInstanceID, scNewAlert, SupportedCategories)

API Prototype

int BTPSAPI ANS_Set_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to set the Supported Categories for. The final parameter is the Supported Categories bit mask to set as the supported categories for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

GetSupportedUnreadAlertCategories is responsible for reading the Supported Unread Alert Category. It can be executed by a Server or a Client with an open connection to a remote Server. If executed as a Client, a GATT read request will be generated, and the results will be returned as a response in the GATT Client event callback. This function will return zero on successful execution and a negative value on errors.

Parameters

It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values

(0) Get Supported Unread Alert Category Request sent, Transaction ID = %u

(-4) FUNCTION_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Query_Supported_Categories(BluetoothStackID, ANSInstanceID, scUnreadAlertStatus, &SupportedCategories)

API Prototype

int BTPSAPI ANS_Query_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t *SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to query the Supported Categories for. The final parameter is a pointer to store the Supported Categories bit mask for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

SetSupportedUnreadAlertCategories is responsible for writing the Supported Unread Alert Category. It can be executed only by a Server. This function will return zero on successful execution and a negative value on errors.

Parameters

[BitMask (0xXXXX)]

Category(bit values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message

Possible Return Values

(0) Supported Unread Alert Category successfully set

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1000) ANS_ERROR_INVALID_PARAMETER

(-1003) ANS_ERROR_INVALID_INSTANCE_ID

API Call

ANS_Set_Supported_Categories(BluetoothStackID, ANSInstanceID, scUnreadAlertStatus, SupportedCategories)

API Prototype

int BTPSAPI ANS_Set_Supported_Categories(unsigned int BluetoothStackID, unsigned int InstanceID, ANS_Supported_Categories_Type_t SupportedCategoryType, Word_t SupportedCategoriesMask)

Description of API

The following function is responsible for setting the Alert Notification Supported Categories for the specified Category Type on the specified ANS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to ANS_Initialize_Server(). The next parameter specifies the Category to set the Supported Categories for. The final parameter is the Supported Categories bit mask to set as the supported categories for the specified ANS Instance. This function returns a zero if successful or a negative return error code if an error occurs.

Description

EnableNewAlertNotifications is responsible for writing the Enable New Incoming Alert Notifications command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Enable New Alert Notifications command request sent.

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

DisableNewAlertNotifications is responsible for writing the Disable New Incoming Alert Notifications command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Disable New Alert Notifications command request sent

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

EnableUnreadAlertNotifications is responsible for writing the Enable Unread Category Status Notifications command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Enable Unread Category Notifications command request sent

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

DisableUnreadAlertNotifications is responsible for writing the Disable Unread Category Status Notifications command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Disable Unread Category Notifications command request sent

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

NotifyImmediatelyNewAlerts is responsible for writing the Notify New Incoming Alert Immediately command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Notify New Alert Immediately command request sent

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

Description

NotifyImmediatelyUnreadAlerts is responsible for writing the Notify New Unread Category Status Immediately command to a remote Server Control Point. It can be executed only by a Client. This function will return zero on successful execution and a negative value on errors.

Parameters

[Category]

Category(numeric values): 0 = Simple Alert, 1 = E-Mail, 2 = News, 3 = Call, 4 = Missed Call, 5 = SMS MMS, 6 = Voice Mail, 7 = Schedule, 8 = High Priority Alert, 9 = Instant Message, 10 = All Categories

Possible Return Values

(0) Notify Unread Category Immediately command request sent

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR