The DotStack SPP API is a simple API for communicating over a Bluetooth link using the Bluetooth Serial Port Profile. More...

Modules
	SPP Configuration
	This module describes parameters used to configure SPP layer.

	RFCOMM Configuration
	This module describes parameters used to configure RFCOMM layer.

Data Structures
struct	bt_spp_port_t
	Serial port structure. More...

struct	bt_spp_port_t::_bt_spp_port_flags_t

Typedefs
typedef void(*	bt_spp_state_callback_fp) (bt_spp_port_t port, bt_spp_port_event_e evt, void param)
	Serial port state callback. More...

typedef void(*	bt_spp_send_callback_fp) (bt_spp_port_t port, bt_ulong bytes_sent, bt_spp_send_status_e status, void param)
	Serial port send callback. More...

typedef void(*	bt_spp_receive_callback_fp) (bt_spp_port_t port, bt_int bytes_received, void param)
	Serial port receive callback. More...

Enumerations
enum	bt_spp_port_state_e { SPP_PORT_STATE_FREE, SPP_PORT_STATE_DISCONNECTED, SPP_PORT_STATE_DISCONNECTING, SPP_PORT_STATE_CONNECTING, SPP_PORT_STATE_CONNECTED }
	Serial port state. More...

enum	bt_spp_port_event_e { SPP_PORT_EVENT_CONNECTED = 1, SPP_PORT_EVENT_DISCONNECTED, SPP_PORT_EVENT_CONNECTION_FAILED, SPP_PORT_EVENT_SEND_PROGRESS, SPP_PORT_EVENT_REMOTE_MODEM_STATUS_CHANGED, SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGED, SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGE_FAILED, SPP_PORT_EVENT_REMOTE_AFC_ON, SPP_PORT_EVENT_REMOTE_AFC_OFF }
	Serial port event. More...

enum	bt_spp_send_status_e { SPP_SEND_STATUS_SUCCESS = 0, SPP_SEND_STATUS_TIMEOUT, SPP_SEND_STATUS_NOT_ENOUGH_RESOURCES, SPP_SEND_STATUS_CANCELED, SPP_SEND_STATUS_INTERRUPTED }
	Send operation status. More...

Functions
void	bt_spp_init (void)
	Initialize the SPP module. More...

bt_spp_port_t *	bt_spp_allocate (bt_l2cap_mgr_t l2cap_mgr, bt_spp_state_callback_fp callback, void callback_param)
	Allocate a serial port. More...

void	bt_spp_set_port_options (bt_spp_port_t *port, bt_uint options)
	Set port options. More...

void	bt_spp_clr_port_options (bt_spp_port_t *port, bt_uint options)
	Clear port options. More...

bt_bool	bt_spp_listen (bt_spp_port_t *port, bt_byte channel)
	Listen for incoming connections. More...

bt_bool	bt_spp_cancel_listen (bt_spp_port_t *port, bt_byte server_channel)
	Stop listening for incoming connections. More...

bt_bool	bt_spp_connect (bt_spp_port_t port, bt_bdaddr_t remote_addr, bt_byte channel)
	Connect to a remote device. More...

bt_bool	bt_spp_cancel_connect (bt_spp_port_t *port)
	Cancel connection establishment. More...

void	bt_spp_disconnect (bt_spp_port_t *port)
	Disconnect from the remote device. More...

bt_bool	bt_spp_deallocate (bt_spp_port_t *port)
	Deallocate serial port. More...

bt_bool	bt_spp_send (bt_spp_port_t port, const void data, bt_ulong data_len, bt_spp_send_callback_fp callback)
	Send data. More...

bt_bool	bt_spp_receive (bt_spp_port_t port, void buffer, bt_int buffer_len, bt_spp_receive_callback_fp callback)
	Receive data. More...

void	bt_spp_cancel_send (bt_spp_port_t *port)
	Cancel send data. More...

void	bt_spp_cancel_receive (bt_spp_port_t *port)
	Cancel receive data. More...

bt_int	bt_spp_get_frame_length (bt_spp_port_t *port)
	Get frame length. More...

bt_hci_conn_state_t *	bt_spp_get_hci_connection (const bt_spp_port_t *port)
	Get SPP port's ACL connection. More...

bt_bdaddr_t *	bt_spp_get_remote_address (const bt_spp_port_t *port)
	Get the address of the remote device this device is connected to. More...

bt_byte	bt_spp_get_local_modem_status (const bt_spp_port_t *port)
	Get local device's TS 07.10 control signals. More...

bt_byte	bt_spp_set_local_modem_status (bt_spp_port_t *port, bt_byte ms)
	Set local device's TS 07.10 control signals. More...

bt_byte	bt_spp_get_remote_modem_status (const bt_spp_port_t *port)
	Get remote device's TS 07.10 control signals. More...

bt_byte	bt_spp_set_dtr (bt_spp_port_t *port, bt_bool on)
	Set local device's RS-232 DTR signal. More...

bt_byte	bt_spp_set_rts (bt_spp_port_t *port, bt_bool on)
	Set local device's RS-232 RTS signal. More...

bt_bool	bt_spp_afc_on (const bt_spp_port_t *port)
	Enable aggregate flow. More...

bt_bool	bt_spp_afc_off (const bt_spp_port_t *port)
	Disable aggregate flow. More...

Port options
#define	SPP_PORT_OPTION_SECURE 0x0001
	Underlying ACL connection has to be authenticated, i.e., paiting is required.

#define	SPP_PORT_OPTION_ENCRYPTED 0x0002
	Underlying ACL connection has to be encrypted.

#define	SPP_PORT_OPTION_MASTER 0x0004
	The role of the underlying ACL connection has to be set to Master if possible.

Detailed Description

The DotStack SPP API is a simple API for communicating over a Bluetooth link using the Bluetooth Serial Port Profile.

Here are the steps for using this API:

Call the bt_spp_init() function.
Allocate a serial port structure with bt_spp_allocate(). One of the parameters to this function is a pointer to a callback function. That callback function will be called by the stack whenever the state of the serial port changes.
To connect to a remote device call bt_spp_connect(). The stack will notify when the connection is established by calling the state callback function.
To wait for a connection from a remote device call bt_spp_listen(). The stack will notify when the connection is established by calling the state callback function.
When the port is connected you can send data with bt_spp_send() and receive data with bt_spp_receive().
To terminate the connection call bt_spp_disconnect().
When you are finished using the port deallocate it with bt_spp_deallocate().

Typedef Documentation

typedef void(* bt_spp_receive_callback_fp) (bt_spp_port_t *port, bt_int bytes_received, void *param)

Serial port receive callback.

This callback function is called when a receive operation initiated by bt_spp_receive() completes.

Parameters

port	Serial port on which the receive operation completed.
bytes_received	Number of received bytes.
param	Callback parameter that was specified when bt_spp_allocate() was called.

typedef void(* bt_spp_send_callback_fp) (bt_spp_port_t *port, bt_ulong bytes_sent, bt_spp_send_status_e status, void *param)

Serial port send callback.

This callback function is called when a send operation initiated by bt_spp_send() completes.

Parameters

port	Serial port on which the send operation completed.
bytes_sent	Number of bytes sent. This parameter is just a convenience as it always specifies the same number of bytes that was passed to bt_spp_send();
status	Completion status. It is one of the values defined in the bt_spp_send_status_e enumeration.
param	Callback parameter that was specified when bt_spp_allocate() was called.

typedef void(* bt_spp_state_callback_fp) (bt_spp_port_t *port, bt_spp_port_event_e evt, void *param)

Serial port state callback.

This callback function is called whenever the state of a serial port is changed.

Parameters

port	Serial port which state has changed.
evt	Event describing the nature of state change. It is one of the values defined in the bt_spp_port_event_e enumeration.
param	Callback parameter that was specified when bt_spp_allocate() was called.

Enumeration Type Documentation

enum bt_spp_port_event_e

Serial port event.

Values of this enumeration represent serial port events. Events are reported to the application through a callback function. The callback function is specified when the port is allocated using bt_spp_allocate().

Enumerator
SPP_PORT_EVENT_CONNECTED	Connection with a remote device was successfully established. This event is reported independent of which side (local or remote) initiated the connection.
SPP_PORT_EVENT_DISCONNECTED	Connection with the remote device was terminated. This event is reported independent of which side (local or remote) initiated termination of the connection.
SPP_PORT_EVENT_CONNECTION_FAILED	Connection to a remote device failed. This event is reported when an attempt to establish a connection using bt_spp_connect() has failed.
SPP_PORT_EVENT_SEND_PROGRESS	Send operation progress. This event is reported periodically during sending data over the serial port connection. It can be used by the application to track send operation progress.
SPP_PORT_EVENT_REMOTE_MODEM_STATUS_CHANGED	Remote modem status. This event is reported when a remote device notifies the local device about the status of its V.24 control signals. The actual value of the signals can be obtained by calling bt_spp_get_remote_modem_status(const bt_spp_port_t* port)
SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGED	Local modem status. This event is reported when the local device has successfully sent the state of its V.24 signals to the remote party.
SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGE_FAILED	Local modem status. This event is reported when the local device failed to send the state of its V.24 signals to the remote party.
SPP_PORT_EVENT_REMOTE_AFC_ON	Aggregate flow control is ON. This event is reported when the local device has successfully enabled aggregate flow.
SPP_PORT_EVENT_REMOTE_AFC_OFF	Aggregate flow control is ON. This event is reported when the local device has successfully disabled aggregate flow.

enum bt_spp_port_state_e

Serial port state.

Values of this enumeration represent states of the serial port.

Enumerator
SPP_PORT_STATE_FREE	Used internally to mark a port structure as available for allocation. The application should never encounter a port in this state.
SPP_PORT_STATE_DISCONNECTED	Port is not connected.
SPP_PORT_STATE_DISCONNECTING	Disconnecting from remote device.
SPP_PORT_STATE_CONNECTING	Connecting to a remote device.
SPP_PORT_STATE_CONNECTED	Port is connected to a remote device.

enum bt_spp_send_status_e

Send operation status.

Enumerator
SPP_SEND_STATUS_SUCCESS	The operation completed successfully.
SPP_SEND_STATUS_TIMEOUT	The operation timed out.
SPP_SEND_STATUS_NOT_ENOUGH_RESOURCES	There was not enough resources to complete the operation.
SPP_SEND_STATUS_CANCELED	The operation was canceled.
SPP_SEND_STATUS_INTERRUPTED	The operation was interrupted because the connection closed.

Function Documentation

bt_bool bt_spp_afc_off ( const bt_spp_port_t * port )

Disable aggregate flow.

If the FCoff command has been successfully sent to a remote device SPP_PORT_EVENT_REMOTE_AFC_OFF event is generated. When aggregate flow is disabled the remote device cannot send data to the local device.

Parameters

port	Serial port.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_spp_afc_on ( const bt_spp_port_t * port )

Enable aggregate flow.

If the FCon command has been successfully sent to a remote device SPP_PORT_EVENT_REMOTE_AFC_ON event is generated. When aggregate flow is enabled the remote device can send data to the local device.

Parameters

port	Serial port.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_spp_port_t* bt_spp_allocate	(	bt_l2cap_mgr_t *	l2cap_mgr,
		bt_spp_state_callback_fp	callback,
		void *	callback_param
	)

Allocate a serial port.

The returned serial port is initially in the SPP_PORT_STATE_DISCONNECTED state. To establish a connection with a remote device, call bt_spp_connect(). To listen for incoming connections from other devices, call bt_spp_listen(). The callback parameter must specify a callback function that will be used to notify about serial port events and state changes. When the port is not needed any more it must be deallocated by bt_spp_deallocate(). The maximum number of serial ports that can be allocated simultaneously is specified by the SPP_MAX_PORTS configuration parameter.

Parameters

l2cap_mgr	L2CAP manager.
callback	Pointer to a callback function used to notify about serial port events. Cannot be NULL.
callback_param	An arbitrary pointer that is passed as a parameter to the callback function.

Returns: A pointer to the ::bt_spp_port_t structure. Returns NULL if the maximum number of ports has been already allocated or the callback parameter is NULL.

bt_bool bt_spp_cancel_connect ( bt_spp_port_t * port )

Cancel connection establishment.

If port is in SPP_PORT_STATE_CONNECTING state this function will try terminate corresponding ACL connection.

Parameters

port	Serial port.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_spp_cancel_listen	(	bt_spp_port_t *	port,
		bt_byte	server_channel
	)

Stop listening for incoming connections.

This function stops the port to accept incoming connections on a given server channel.

Parameters

port	Serial port.
channel	The RFCOMM server channel to accept connections on.

Returns: TRUE if successful, FALSE otherwise.

void bt_spp_cancel_receive ( bt_spp_port_t * port )

Cancel receive data.

If a receive operation is currently in progress this function will cancel it. After calling this function the receive callback specified in bt_spp_receive() will not be called.

If there is no receive operation in progress calling this function has no effect.

Parameters

port	Serial port.

void bt_spp_cancel_send ( bt_spp_port_t * port )

Cancel send data.

If a send operation is currently in progress this function will try to cancel it. When the operation is canceled the send callback function will be called with the SPP_SEND_STATUS_CANCELED status.

If this function is called but the active send operation completes successfuly before the stack can actually cancel it the call back function will still be called with the SPP_SEND_STATUS_CANCELED status.

If there is no send operation in progess calling this function has no effect.

Parameters

port	Serial port.

void bt_spp_clr_port_options	(	bt_spp_port_t *	port,
		bt_uint	options
	)

Clear port options.

This function clears port's options. The function should be called before port has been connected.

Parameters

port	Serial port.
options	Serial port options to clear. This can be a combination of the following values: SPP_PORT_OPTION_SECURE SPP_PORT_OPTION_ENCRYPTED SPP_PORT_OPTION_MASTER

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_spp_connect	(	bt_spp_port_t *	port,
		bt_bdaddr_t *	remote_addr,
		bt_byte	channel
	)

Connect to a remote device.

This function initiates a connection to a remote device. When the connection is successfully established the port's callback is called with the SPP_PORT_EVENT_CONNECTED event. If connection fails the callback is called with the SPP_PORT_EVENT_CONNECTION_FAILED event.

The port must be in SPP_PORT_STATE_DISCONNECTED state. Otherwise, the function will fail.

Parameters

port	Serial port.
remote_addr	Bluetooth address of the remote device.
channel	RFCOMM server channel on which the connection is to be established.

Returns: TRUE if successful, FALSE otherwise.

bt_bool bt_spp_deallocate ( bt_spp_port_t * port )

Deallocate serial port.

This function deallocates the specified port structure and other resources associated with it.

The port must be in SPP_PORT_STATE_DISCONNECTED state. Otherwise, the function will fail.

If the function completes successfully the application must not try to access any fields in the structure and must not use it with any other SPP functions. Also, it becomes available for subsequent allocation by bt_spp_port_allocate().

Parameters

port	Serial port structure to deallocate.

Returns: TRUE if successful, FALSE otherwise.

void bt_spp_disconnect ( bt_spp_port_t * port )

Disconnect from the remote device.

This function initiates the disconnection process. When it is complete the the port's callback is called with the SPP_PORT_EVENT_DISCONNECTED event.

If the port is already in the disconnected state the function does nothing and the callback is not called.

Parameters

port	Serial port.

bt_int bt_spp_get_frame_length ( bt_spp_port_t * port )

Get frame length.

This function returns the RFCOMM frame length used by the RFCOMM protocol. The frame length depends on configuration of DotStack and configuration of the Bluetooth stack running on the remote device. In order to achieve maximum throughput over the serial port connection the application should send and receive data in chunks that are multiple of this frame length.

Returns: RFCOMM frame length in bytes.

bt_hci_conn_state_t* bt_spp_get_hci_connection ( const bt_spp_port_t * port )

Get SPP port's ACL connection.

This function returns a pinter to the structure that describes the ACL connection this port is on.

Returns: Pointer to ACL connection description if the port is connected, NULL otherwise.

bt_byte bt_spp_get_local_modem_status ( const bt_spp_port_t * port )

Get local device's TS 07.10 control signals.

This function returns current state of the local device's TS 07.10 controls signals. The signals are defined as a mask of the following constants: SPP_RS232_DSR SPP_RS232_RTS SPP_RS232_RI SPP_RS232_DCD

Parameters

port	Serial port.

Returns: local device's TS 07.10 control signals.

bt_bdaddr_t* bt_spp_get_remote_address ( const bt_spp_port_t * port )

Get the address of the remote device this device is connected to.

Parameters

port	Serial port.

Returns

A pointer to bt_bdaddr structure that contains the address of the remote device.

bt_byte bt_spp_get_remote_modem_status ( const bt_spp_port_t * port )

Get remote device's TS 07.10 control signals.

This function returns current state of the remote device's V.24 controls signals. The signals are defined as a mask of the following constants: SPP_RS232_DTR SPP_RS232_CTS SPP_RS232_RI SPP_RS232_DCD

Parameters

port	Serial port.

Returns: remote device's TS 07.10 control signals.

void bt_spp_init ( void )

Initialize the SPP module.

This function initializes all internal variables of the SPP module. It must be called prior to using any other functions in this module.

bt_bool bt_spp_listen	(	bt_spp_port_t *	port,
		bt_byte	channel
	)

Listen for incoming connections.

This function registers the port to accept incoming connections from remote devices on a particular RFCOMM server channel. The specified server channel should be listed in the SDP database. Otherwise, remote devices will not be able to find out which server channel to use.

When a remote device successfully establishes a connection on the specified port the port's callback is called with the SPP_PORT_EVENT_CONNECTED event.

The port must be in SPP_PORT_STATE_DISCONNECTED state. Otherwise, the function will fail.

Parameters

port	Serial port.
channel	The RFCOMM server channel on which to listen for connections.

Returns: TRUE if successful, FALSE otherwise.

bt_bool bt_spp_receive	(	bt_spp_port_t *	port,
		void *	buffer,
		bt_int	buffer_len,
		bt_spp_receive_callback_fp	callback
	)

Receive data.

This function receives data from the serial port connection. The caller must provide a buffer and a callback function. Whenever the port receives data they are copied to the provided buffer and the callback function is called. The callback function is passed the length of received data and the same callback parameter that was specified when the port was allocated with bt_spp_allocate(). This function does not wait until the buffer is filled out completely. Any amount of received data will complete the operation.

The port must be in SPP_PORT_STATE_CONNECTED state. Otherwise, the function will fail. Also, the function will fail if a previously started receive operation is still in progress.

Parameters

port	Serial port.
data	Pointer to the data to be sent.
data_len	Length of the data.
callback	Send callback function.

Returns: TRUE if successful, FALSE otherwise.

bt_bool bt_spp_send	(	bt_spp_port_t *	port,
		const void *	data,
		bt_ulong	data_len,
		bt_spp_send_callback_fp	callback
	)

Send data.

This function starts sending data over the serial port connection. Along with the data the caller must provide a callback function that is called when all data has been sent. Also, during execution of this operation the port's state callback function is called periodically with the SPP_PORT_EVENT_SEND_PROGRESS event.

The port must be in SPP_PORT_STATE_CONNECTED state. Otherwise, the function will fail. Also, the function will fail if a previously started send operation is still in progress.

The callback function is passed the same callback parameter that was specified when the port was allocated with bt_spp_allocate().

Parameters

port	Serial port.
data	Pointer to the data to be sent.
data_len	Length of the data.
callback	Send callback function.

Returns: TRUE if successful, FALSE otherwise.

bt_byte bt_spp_set_dtr	(	bt_spp_port_t *	port,
		bt_bool	on
	)

Set local device's RS-232 DTR signal.

Changes the state of local device's RS-232 DTR signal and notifies the remote device of the change. This signal corresponds to the TS 07.10's RFCOMM_MODEM_STATUS_RTC signal.

If there are resources to send a command to the remote device this command will return TRUE.

If the remote party has been successfully notified SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGED event will be reported. If the command could not be send to the remote party for any reason other than lack of resources SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGE_FAILED will be reported.

If the status cannot be changed because there is no resources to send a command to the remote device this function will return FALSE and no events will be reported.

Parameters

port	Serial port.
on	Value indicating weather to set or clear the signal.

Returns: TRUE if successful, FALSE otherwise.

bt_byte bt_spp_set_local_modem_status	(	bt_spp_port_t *	port,
		bt_byte	ms
	)

Set local device's TS 07.10 control signals.

Changes the state of local device's TS 07.10 control signals and notifies the remote device of the change.

If there are resources to send a command to the remote device this command will return TRUE.

If the remote party has been successfully notified SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGED event will be reported. If the command could not be send to the remote party for any reason other than lack of resources SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGE_FAILED will be reported.

If the status cannot be changed because there is no resources to send a command to the remote device this function will return FALSE and no events will be reported.

Parameters

port	Serial port.
ms	Signals mask.

Returns: TRUE if successful, FALSE otherwise.

void bt_spp_set_port_options	(	bt_spp_port_t *	port,
		bt_uint	options
	)

Set port options.

This function sets port's options. The function should be called before port has been connected.

Parameters

port	Serial port.
options	Serial port options. This can be a combination of the following values: SPP_PORT_OPTION_SECURE SPP_PORT_OPTION_ENCRYPTED SPP_PORT_OPTION_MASTER

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_byte bt_spp_set_rts	(	bt_spp_port_t *	port,
		bt_bool	on
	)

Set local device's RS-232 RTS signal.

Changes the state of local device's RS-232 DTR signal and notifies the remote device of the change. This signal corresponds to the TS 07.10's RFCOMM_MODEM_STATUS_RTR signal.

If there are resources to send a command to the remote device this command will return TRUE.

If the remote party has been successfully notified SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGED event will be reported. If the command could not be send to the remote party for any reason other than lack of resources SPP_PORT_EVENT_LOCAL_MODEM_STATUS_CHANGE_FAILED will be reported.

If the status cannot be changed because there is no resources to send a command to the remote device this function will return FALSE and no events will be reported.

Parameters

port	Serial port.
on	Value indicating weather to set or clear the signal.

Returns: TRUE if successful, FALSE otherwise.

Modules

Data Structures

Typedefs

Enumerations

Functions

Port options

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation