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 the opened port number (1-31) if successful, or a negative return value if an error occurred.

Parameters

None.

Possible Return Values

(1-32) HSP port opened successfully

(-8) INVALID_STACK_ID_ERROR

(-9) UNABLE_TO_REGISTER_SERVER

(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

(-1000) BTHDSET_ERROR_INVALID_PARAMETER

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1004) BTHDSET_ERROR_INSUFFICIENT_RESOURCES

API Call

HDSET_Open_Audio_Gateway_Server_Port(BluetoothStackID, LOCAL_SERVER_CHANNEL_ID, HDSET_Event_Callback, (unsigned long)0)

API Prototype

int BTPSAPI HDSET_Open_Audio_Gateway_Server_Port(unsigned int BluetoothStackID, unsigned int ServerPort, HDSET_Event_Callback_t EventCallback, unsigned long CallbackParameter)

Description of API

The following function is responsible for Opening an Audio Gateway 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 Audio Gateway Server, the Local Serial Port Server Number to use, and the HDSET Event Callback function (and parameter) to associate with the specified Headset 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 HDSET Port ID that can be used to reference the Opened HDSET Port in ALL other functions in this module except for the HDSET_Register_Headset_SDP_Record() function which is specific to a Headset Server NOT an Audio Gateway. Once a Server HDSET Port is opened, it can only be Un-Registered via a call to the HDSET_Close_Server_Port() function (passing the return value from this function). The HDSET_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. If the last Server is closed, the function also unregisters the SDP record. 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.

Possible Return Values

(0) HSP Server closed successfully

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000)

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

API Call

HDSET_Close_Server_Port(BluetoothStackID, HDSServerID)

API Prototype

int BTPSAPI HDSET_Close_Server_Port(unsigned int BluetoothStackID, unsigned int HDSETPortID)

Description of API

The following function is responsible for Un-Registering a HDSET Port Server (which was Registered by a successful call to either the HDSET_Open_Headset_Server_Port() or the HDSET_Open_Audio_Gateway_Server_Port() function). This function accepts as input the Bluetooth Stack ID of the Bluetooth Protocol Stack that the HDSET 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 issuing a Press Button Command for a Headset (either Accept or End a Call). This function returns zero if successful or a negative return error code if an error occurs.

Parameters

It is not necessary to include parameters when using this command.

Possible Return Values

(0) command sent successfully

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1005) BTHDSET_ERROR_INVALID_OPERATION

API Call

HDSET_Send_Button_Press(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID))

API Prototype

int BTPSAPI HDSET_Send_Button_Press(unsigned int BluetoothStackID, unsigned int HDSETPortID)

Description of API

The following function is responsible for sending a Button Press to a remote Audio Gateway. This function accepts the Bluetooth Stack ID of the Bluetooth Stack which has received the HDSET Connection Request and the HDSET Port ID of the Headset to send the request on. This function returns a zero if successful, or a negative return error code if there was an error

Description

The following function is responsible for sending a Speaker gain (Volume) Change Command to the Remote Connection. This function returns zero if successful or a negative return error code if an error occurs.

Parameters

One Parameter - Number Between 0-15

Possible Return Values

(0) command sent successfully

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHDSET_ERROR_INVALID_PARAMETER

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1005) BTHDSET_ERROR_INVALID_OPERATION

API Call

HDSET_Set_Speaker_Gain(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID), TempParam->Params[0].intParam)

API Prototype

int BTPSAPI HDSET_Set_Speaker_Gain(unsigned int BluetoothStackID, unsigned int HDSETPortID, unsigned int SpeakerGain)

Description of API

The following function is provided to allow the local entity a mechanism of notifying the Remote entity (either Headset OR Audio Gateway) that the Speaker Gain has changed. This function accepts as input the Bluetooth Stack ID of the Bluetooth Stack which the HDSET Port ID (second parameter) is valid for, the HDSET Port ID, and the new Speaker Gain Setting. This function returns zero if successful or a negative return error code if there was an error. The Speaker Gain Parameter *MUST* be between the values of HDSET_SPEAKER_GAIN_MINIMUM and HDSET_SPEAKER_GAIN_MAXIMUM.

Description

The following function is responsible for sending a Change Microphone Gain Command to the Remote Connection. This function returns zero if successful or a negative return error code if an error occurs.

Parameters

One Parameter - Number Between 0-15

Possible Return Values

(0) Command sent successfully

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000) BTHDSET_ERROR_INVALID_PARAMETER

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1005) BTHDSET_ERROR_INVALID_OPERATION

API Call

HDSET_Set_Microphone_Gain(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID), TempParam->Params[0].intParam)

API Prototype

int BTPSAPI HDSET_Set_Microphone_Gain(unsigned int BluetoothStackID, unsigned int HDSETPortID, unsigned int MicrophoneGain)

Description of API

The following function is provided to allow the local entity a mechanism of notifying the Remote entity (either Headset OR Audio Gateway) that the Microphone Gain has changed. This function accepts as input the Bluetooth Stack ID of the Bluetooth Stack which the HDSET Port ID (second parameter) is valid for, the HDSET Port ID, and the new Microphone Gain Setting. This function returns zero if successful or a negative return error code if there was an error. The Microphone Gain Parameter *MUST* be between the values of HDSET_MICROPHONE_GAIN_MINIMUM and HDSET_MICROPHONE_GAIN_MAXIMUM.

Description

The following function is responsible for initiating a connection with a Remote Headset or Audio Gateway Server. This function returns zero if successful and a negative value if an error occurred.

Parameters

Two Parameters, First one is the Inquiry index, the Second is the RFCOMM Server Port.

Possible Return Values

(0) Command sent successfully

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

(-1000) BTHDSET_ERROR_INVALID_PARAMETER

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1004) BTHDSET_ERROR_INSUFFICIENT_RESOURCES

API Call

HDSET_Open_Remote_Headset_Port(BluetoothStackID, InquiryResultList[(TempParam->Params[0].intParam - 1)], TempParam->Params[1].intParam, FALSE, HDSET_Event_Callback, (unsigned long)0)

API Prototype

int BTPSAPI HDSET_Open_Remote_Headset_Port(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, unsigned int RemoteServerPort, Boolean_t SupportInBandRinging, HDSET_Event_Callback_t EventCallback, unsigned long CallbackParameter)

Description of API

The following function is responsible for Opening a Remote Headset Port on the specified Remote Device. This function accepts the Bluetooth Stack ID of the Bluetooth Stack which is to open the HDSET Connection as the first parameter. The second parameter specifies the Board Address (NON NULL) of the Remote Bluetooth Device to connect with. The next parameter specifies whether or not the Local Audio Gateway (the entity that is connecting to the Remote Headset) supports In Band Ringing or not (TRUE if supported). The final two parameters specify the HDSET Event Callback function, and callback parameter, respectively, of the HDSET Event Callback that is to process any further interaction with the specified Remote Port (Opening Status, Close Status, etc). This function returns a non-zero, positive, value if successful, or a negative return error code if this function is unsuccessful. If this function is successful, the return value will represent the HDSET Port ID that can be passed to all other functions that require it. Once a Remote Headset opened, it can only be closed via a call to the HDSET_Close_Port() function (passing the return value from this function).

Description

The following function is responsible for terminating a connection with a Remote Headset or Audio Gateway Server. This function returns zero if successful and a negative value if an error occurred.

Parameters

It is not necessary to include parameters when using this command.

Possible Return Values

(0) HSP Server closed successfully

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-1000)

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

API Call

HDSET_Close_Port(BluetoothStackID, HDSClientID

API Prototype

int BTPSAPI HDSET_Close_Port(unsigned int BluetoothStackID, unsigned int HDSETPortID)

Description of API

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

• Successful call to HDSET_Open_Remote_Headset_Port() function.
• Successful call to HDSET_Open_Remote_Audio_Gateway_Port() function.
• Incoming call request (Headset or Audio Gateway) which the Server was opened with either the HDSET_Open_Headset_Server_Port() or the HDSET_Open_Audio_Gateway_Server_Port() functions.

This function accepts as input the Bluetooth Stack ID of the Bluetooth Stack which the Open HDSET Port resides and the HDSET 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 HDSET Server Port from the system, it ONLY disconnects any connection that is currently active on the Server Port. The HDSET_Close_Server_Port() function can be used to Un-Register the HDSET Server Port. .

Description

The following function is responsible for sending a Ring Indication to the Remote connected Headset. This function returns zero if successful or a negative return error code if an error occurs.

Parameters

It is not necessary to include parameters when using this command.

Possible Return Values

(0) command sent successfully

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1005) BTHDSET_ERROR_INVALID_OPERATION

API Call

HDSET_Ring_Indication(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID))

API Prototype

int BTPSAPI HDSET_Ring_Indication(unsigned int BluetoothStackID, unsigned int HDSETPortID)

Description of API

The following function is responsible for Sending a Ring Indication to the remote side. The function accepts the Bluetooth Stack ID of the Bluetooth Stack which has received the HDSET Connection Request and the HDSET Port ID for which the Connection has been established. This function returns a zero if successful, or a negative return error code if there was an error. .

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 for 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 from Server with port index 1.

"ManageAudio 1" Attempts to Setup the Audio Connection with Server port index 2.

Possible Return Values

(0) command sent successfully

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

(-1000) BTHDSET_ERROR_INVALID_PARAMETER

(-1001) BTHDSET_ERROR_NOT_INITIALIZED

(-1002) BTHDSET_ERROR_INVALID_BLUETOOTH_STACK_ID

(-1005) BTHDSET_ERROR_INVALID_OPERATION

API Call

HDSET_Setup_Audio_Connection(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID), FALSE)

or HDSET_Release_Audio_Connection(BluetoothStackID, ((ServerConnected)?HDSServerID:HDSClientID))

API Prototype

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

or int BTPSAPI HDSET_Release_Audio_Connection(unsigned int BluetoothStackID, unsigned int HDSETPortID)

Description of API

This function is responsible for Setting Up an Audio Connection between the Local Audio Gateway and Remote Headset Device. This function may ONLY be used by an Audio Gateway. This function accepts as its input parameters the Bluetooth Stack ID for which the HDSET Port ID is valid as well as the HDSET Port ID (of the Audio Gateway). The final parameter specifies whether this is In-Band ringing (TRUE) or not (FALSE). If In-Band Ringing is specified then the remote Headset is required to accept the call. 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 local Audio Gateway or by a call to the HDSET_Setup_Audio_Connection() function. This function may ONLY be used by an Audio Gateway. This function accepts as its input parameters the Bluetooth Stack ID for which the HDSET Port ID is valid as well as the HDSET Port ID. This function returns zero if successful or a negative return error code if there was an error.