TI’s Bluetooth stack is implementation of the upper layers of the Bluetooth protocol stack. TI’s Bluetooth stack provides 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) describes all of the API's in detail.

Description

The following function is responsible for opening a Serial Port Server on the Local Device. This function opens the Serial Port Server on the specified RFCOMM Channel. This function returns zero if successful, or a negative return value if an error occurred.

Parameters

The command only requires one parameter. This parameter is the Port Number.

Command Call Examples

"OpenHFServer 4" Attempts to Open a Handsfree Server at Port Number #4.

"OpenHFServer 1" Attempts to Open a Handsfree Server at Port Number #1.

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Open_HandsFree_Server_Port(BluetoothStackID, TempParam->Params[0].intParam, HFRE_SUPPORTED_FEATURES, 0, NULL, HFRE_Event_Callback, (unsigned long)0)

API Prototype

int BTPSAPI HFRE_Open_HandsFree_Server_Port(unsigned int BluetoothStackID, unsigned int ServerPort, unsigned long SupportedFeaturesMask, unsigned int NumberAdditionalIndicators, char *AdditionalSupportedIndicators[], HFRE_Event_Callback_t EventCallback, unsigned long CallbackParameter)

Description of API

The following function is responsible for Opening a Hands-Free Server on the specified Bluetooth SPP Serial Port. This function accepts as input the Bluetooth Stack ID of the Bluetooth Stack Instance to use for the Hands-Free Server, the Local Serial Port Server Number to use, a bit mask that specifies the features in which the Hands-Free unit supports, the Number of Additional Indicators, a list of Additional Indicators to Support, and the HFRE Event Callback function (and parameter) to associate with the specified Hands-Free Port. The ServerPort parameter *MUST* be between SPP_PORT_NUMBER_MINIMUM and SPP_PORT_NUMBER_MAXIMUM. This function returns a positive, non-zero, value if successful or a negative return error code if an error occurs. A successful return code will be a HFRE Port ID that can be used to reference the Opened HFRE Port in ALL other functions in this module except for the HFRE_Register_Audio_Gateway_SDP_Record() function which is specific to an Audio Gateway Server NOT a Hands-Free Server. Once a Server HFRE Port is opened, it can only be Un-Registered via a call to the HFRE_Close_Server_Port() function (passing the return value from this function). The HFRE_Close_Port() function can be used to Disconnect a Client from the Server Port (if one is connected, it will NOT Un-Register the Server Port however).

Description

The following function is responsible for closing a Serial Port Server that was previously opened via a successful call to the OpenServer() function. This function returns zero if successful or a negative return error code if there was an error.

Parameters

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

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Close_Server_Port(BluetoothStackID, HFServerPortID)

API Prototype

int BTPSAPI HFRE_Close_Server_Port(unsigned int BluetoothStackID, unsigned int HFREPortID)

Description of API

The following function is responsible for Un-Registering a HFRE Port Server (which was Registered by a successful call to either the HFRE_Open_HandsFree_Server_Port() or the HFRE_Open_Audio_Gateway_Server_Port() function). This functionaccepts as input the Bluetooth Stack ID of the Bluetooth Protocol Stack that the HFRE Port specified by the Second Parameter is valid for. This function returns zero if successful, or a negative return error code if an error occurred (see BTERRORS.H). Note that this function does NOT delete any SDP Service Record Handles.

Description

The following function is responsible for setting up or releasing an audio connection. This function returns zero on successful execution and a negative value on all errors.

Parameters

The Manage Audio command requires only one parameter to which is is an integer value that represents the ManageAudio mode. This value must be specified as 0 (for Release) or 1 (for Setup)

Command Call Examples

"ManageAudio 0" Attempts to Release the Audio Connection.

"ManageAudio 1" Attempts to Setup the Audio Connection.

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Setup_Audio_Connection(BluetoothStackID, HFServerPortID)

or HFRE_Release_Audio_Connection(BluetoothStackID, HFServerPortID)

API Prototype

int BTPSAPI HFRE_Setup_Audio_Connection(unsigned int BluetoothStackID, unsigned int HFREPortID)

or int BTPSAPI HFRE_Release_Audio_Connection(unsigned int BluetoothStackID, unsigned int HFREPortID)

Description of API

This function is responsible for Setting Up an Audio Connection between the Local and Remote Device. This function may be used by either an Audio Gateway or a Hands-Free unit for which a valid Service Level Connection Exists. This function accepts as its input parameters the Bluetooth Stack ID for which the HFRE Port ID is valid as well as the HFRE Port ID. This function returns zero if successful or a negative return error code if there was an error.

(or) This function is responsible for Releasing an Audio Connection which was previously established by the Remote Device or by a call to the HFRE_Setup_Audio_Connection() function. This function may be used by either an Audio Gateway or a Hands-Free unit. This function accepts as its input parameters the Bluetooth Stack ID for which the HFRE Port ID is valid as well as the HFRE Port ID. This function returns zero if successful or a negative return error code if there was an error.

Description

The following function is responsible for sending the command to Anwser an Incoming Call on the Remote Audio Gateway. This function returns zero on successful execution and a negative value on all errors.

Parameters

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

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Answer_Incoming_Call(BluetoothStackID, HFServerPortID)

API Prototype

int BTPSAPI HFRE_Answer_Incoming_Call(unsigned int BluetoothStackID, unsigned int HFREPortID)

Description of API

This function is responsible for sending the command to Answer an Incoming call on a Remote Audio Gateway. This function may only be performed by Hands-Free units for which a valid Service Level Connection exists. This function accepts as its input parameters the Bluetooth Stack ID for which the HFRE Port ID is valid as well as the HFRE Port ID. This function return zero if successful or a negative return error code if there was an error.

Description

The following function is responsible for sending the command to HangUp ongoing calls or reject incoming calls on the Remote Audio Gateway. This function returns zero on successful execution and a negative value on all errors.

Parameters

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

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Hang_Up_Call(BluetoothStackID, HFServerPortID)

API Prototype

int BTPSAPI HFRE_Hang_Up_Call(unsigned int BluetoothStackID, unsigned int HFREPortID)

Description of API

This function is responsible for sending a Hang-Up Command to the Remote Audio Gateway. This function may be used to Reject an incoming call, or to terminate an ongoing call. This function may only be performed by Hands-Free units for which a valid Service Level Connection exists. This function accepts as its input parameters the Bluetooth Stack ID for which the HFRE Port ID is valid as well as the HFRE Port ID. This function returns zero if successful or a negative return error code if there was an error.

Description

The following function is responsible for closing any open HFP ports. This function returns zero on successful execution and a negative value on all errors.

Parameters

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

Possible Return Values

(0) A3DP Endpoint opened successfully

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-4) FUNCTION_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHFRE_ERROR_INVALID_PARAMETER

(-1001) BTHFRE_ERROR_NOT_INITIALIZED

(-1002) BTHFRE_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1003) BTHFRE_ERROR_LIBRARY_INITIALIZATION_ERROR

(-1004) BTHFRE_ERROR_INSUFFICIENT_RESOURCES

(-1005) BTHFRE_ERROR_INVALID_OPERATION

(-1006) BTHFRE_ERROR_INVALID_CODEC_ID

API Call

HFRE_Close_Port(BluetoothStackID, HFServerPortID)

API Prototype

int BTPSAPI HFRE_Close_Port(unsigned int BluetoothStackID, unsigned int HFREPortID)

Description of API

The following function exists to close a HFRE Port that was previously opened by any of the following mechanisms:

- Successful call to HFRE_Open_Remote_HandsFree_Port() function.

- Successful call to HFRE_Open_Remote_Audio_Gateway_Port() function.

- Incoming open request (Hands-Free or Audio Gateway) which the server was opened with either the HFRE_Open_HandsFree_Server_Port() or the HFRE_Open_Audio_Gateway_Server_Port() functions.

This function accepts as input the Bluetooth Stack ID of the Bluetooth Stack which the Open HFRE Port resides and the HFRE Port ID (return value from one of the above mentioned Open functions) of the Port to Close. This function returns zero if successful, or a negative return value if there was an error. This function does NOT Un-Register a HFRE Server Port from the system, it ONLY disconnects any connection that is currently active on the Server Port. The HFRE_Close_Server_Port()function can be used to Un-Register the HFRE Server Port.