Bluetooth Socket API provides functions for managing connections to other devices and exchanging data.

Required Header

#include <bluetooth.h>

Overview

This set of functions is used for exchanging data between two bluetooth devices, our device can have both roles as server (service provider) and client (service user). Depending on the role, there is difference in creating a connection. After that, processes of exchanging data and disconnection are same.

To start communication, you should first register for bt_socket_set_connection_state_changed_cb() and bt_socket_set_data_received_cb(). Next step depends on the role of your application.
If you want to be server role, application should create socket (bt_socket_create_rfcomm()), and start listening and accepting incoming connections (bt_socket_listen_and_accept_rfcomm()). If you want to connect to specific device and use it's services (client role), you have to start connection with bt_socket_connect_rfcomm() and wait for connection.
After connection has been established (information is passed to your program with bt_socket_connection_state_changed_cb() function call), you can exchange data by calling bt_socket_send_data().
If you receive data from remote device, bt_socket_data_received_cb() functions will be called. When you finish exchanging data, you should disconnect connection with bt_socket_disconnect_rfcomm() and unregister callback functions (with using bt_socket_unset_data_received_cb(), bt_socket_unset_connection_state_changed_cb()).

Related Features

This API is related with the following features:

http://tizen.org/feature/network.bluetooth

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information,thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Asynchronous Operations

FUNCTION	CALLBACK	DESCRIPTION
bt_socket_listen_and_accept_rfcomm() bt_socket_connect_rfcomm()	bt_socket_connection_state_changed_cb()	Used to connect a device.

Callback(Event) Operations

REGISTER	UNREGISTER	CALLBACK	DESCRIPTION
bt_socket_set_data_received_cb()	bt_socket_unset_data_received_cb()	bt_socket_data_received_cb()	Used to be notified of received data.
bt_socket_set_connection_state_changed_cb()	bt_socket_unset_connection_state_changed_cb()	bt_socket_connection_state_changed_cb()	Used to be notified when the state of connection changes.

Please refer Bluetooth Tutorial if you want to get more detailed usages and information of this api.

Functions
int	bt_socket_create_rfcomm (const char service_uuid, int socket_fd)
	Registers a RFCOMM server socket with a specific UUID.
int	bt_socket_destroy_rfcomm (int socket_fd)
	Removes the RFCOMM server socket which was created using bt_socket_create_rfcomm().
int	bt_socket_listen_and_accept_rfcomm (int socket_fd, int max_pending_connections)
	Starts listening on passed RFCOMM socket and accepts connection requests.
int	bt_socket_connect_rfcomm (const char remote_address, const char service_uuid)
	Connects to a specific RFCOMM based service on a remote Bluetooth device UUID, asynchronously.
int	bt_socket_disconnect_rfcomm (int socket_fd)
	Disconnects the RFCOMM connection with the given file descriptor of connected socket.
int	bt_socket_send_data (int socket_fd, const char *data, int length)
	Sends data to the connected device.
int	bt_socket_set_data_received_cb (bt_socket_data_received_cb callback, void *user_data)
	Registers a callback function that will be invoked when you receive data.
int	bt_socket_unset_data_received_cb (void)
	Unregisters the callback function.
int	bt_socket_set_connection_requested_cb (bt_socket_connection_requested_cb callback, void *user_data)
	Registers a callback function that will be invoked when a RFCOMM connection is requested.
int	bt_socket_unset_connection_requested_cb (void)
	Unregisters the callback function.
int	bt_socket_set_connection_state_changed_cb (bt_socket_connection_state_changed_cb callback, void *user_data)
	Registers a callback function that will be invoked when the connection state changes.
int	bt_socket_unset_connection_state_changed_cb (void)
	Unregisters the callback function.
Typedefs
typedef void(*	bt_socket_data_received_cb )(bt_socket_received_data_s data, void user_data)
	Called when you receive data.
typedef void(*	bt_socket_connection_state_changed_cb )(int result, bt_socket_connection_state_e connection_state, bt_socket_connection_s connection, void user_data)
	Called when the socket connection state changes.
typedef void(*	bt_socket_connection_requested_cb )(int socket_fd, const char remote_address, void user_data)
	Called when a RFCOMM connection is requested.

Typedef Documentation

typedef void(* bt_socket_connection_requested_cb)(int socket_fd, const char *remote_address, void *user_data)

Called when a RFCOMM connection is requested.

Since :: 2.3.1

Parameters:

[in]	socket_fd	The file descriptor of socket on which a connection is requested
[in]	remote_address	The address of remote device
[in]	user_data	The user data passed from the callback registration function

Precondition:: If you register this callback function by bt_socket_set_connection_requested_cb(), bt_socket_connection_requested_cb() will be invoked.

typedef void(* bt_socket_connection_state_changed_cb)(int result, bt_socket_connection_state_e connection_state, bt_socket_connection_s *connection, void *user_data)

Called when the socket connection state changes.

Since :: 2.3.1

Parameters:

[in]	result	The result of connection state changing
[in]	connection_state	The connection state
[in]	connection	The connection information which is established or disconnected
[in]	user_data	The user data passed from the callback registration function

Precondition:: Either bt_socket_connect_rfcomm() will invoke this function. In addition, bt_socket_connection_state_changed_cb() will be invoked when the socket connection state is changed.

See also:: bt_socket_listen_and_accept_rfcomm(); bt_socket_connect_rfcomm(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

typedef void(* bt_socket_data_received_cb)(bt_socket_received_data_s *data, void *user_data)

Called when you receive data.

Since :: 2.3.1

Parameters:

[in]	data	The received data from the remote device
[in]	user_data	The user data passed from the callback registration function

Precondition:: When the connected remote Bluetooth device invokes bt_socket_send_data(), this function will be invoked if you register this function using bt_socket_set_data_received_cb().

See also:: bt_socket_set_data_received_cb(); bt_socket_unset_data_received_cb(); bt_socket_send_data()

Enumeration Type Documentation

enum bt_socket_connection_state_e

Enumerations of Bluetooth socket connection state.

Since :: 2.3.1

Enumerator:

BT_SOCKET_CONNECTED	RFCOMM is connected
BT_SOCKET_DISCONNECTED	RFCOMM is disconnected

enum bt_socket_role_e

Enumerations of connected Bluetooth device event role.

Since :: 2.3.1

Enumerator:

BT_SOCKET_UNKNOWN	Unknown role
BT_SOCKET_SERVER	Server role
BT_SOCKET_CLIENT	Client role

Function Documentation

int bt_socket_connect_rfcomm	(	const char *	remote_address,
		const char *	service_uuid
	)

Connects to a specific RFCOMM based service on a remote Bluetooth device UUID, asynchronously.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Remarks:: A connection can be disconnected by bt_socket_disconnect_rfcomm().

Parameters:

[in]	remote_address	The address of the remote Bluetooth device
[in]	service_uuid	The UUID of service provided by the remote Bluetooth device

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.; The remote device must be discoverable with bt_adapter_start_device_discovery().; The bond with the remote device must be created with bt_device_create_bond().

Postcondition:: This function invokes bt_socket_connection_state_changed_cb().

See also:: bt_device_create_bond(); bt_adapter_start_device_discovery(); bt_device_start_service_search(); bt_socket_disconnect_rfcomm(); bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_create_rfcomm	(	const char *	service_uuid,
		int *	socket_fd
	)

Registers a RFCOMM server socket with a specific UUID.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Remarks:: A socket can be destroyed by bt_socket_destroy_rfcomm().

Parameters:

[in]	service_uuid	The UUID of service to provide
[out]	socket_fd	The file descriptor of socket to listen

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The state of local Bluetooth must be BT_ADAPTER_ENABLED.

See also:: bt_socket_listen_and_accept_rfcomm(); bt_socket_destroy_rfcomm()

int bt_socket_destroy_rfcomm ( int socket_fd )

Removes the RFCOMM server socket which was created using bt_socket_create_rfcomm().

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Remarks:: If callback function bt_socket_connection_state_changed_cb() is set and the remote Bluetooth device is connected, then bt_socket_connection_state_changed_cb() will be called when this function is finished successfully.

Parameters:

[in] socket_fd The file descriptor of socket (which was created using bt_socket_create_rfcomm()) to destroy

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The socket must be created with bt_socket_create_rfcomm().

Postcondition:: If callback function bt_socket_connection_state_changed_cb() is set and the remote Bluetooth device is connected, then bt_socket_connection_state_changed_cb() will be called.

See also:: bt_socket_create_rfcomm(); bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_disconnect_rfcomm ( int socket_fd )

Disconnects the RFCOMM connection with the given file descriptor of connected socket.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in] socket_fd The file descriptor of socket to close which was received using bt_socket_connection_state_changed_cb()

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The connection must be established.

See also:: bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_listen_and_accept_rfcomm	(	int	socket_fd,
		int	max_pending_connections
	)

Starts listening on passed RFCOMM socket and accepts connection requests.

Pop-up is shown automatically when a RFCOMM connection is requested. bt_socket_connection_state_changed_cb() will be called with BT_SOCKET_CONNECTED if you click "yes" and connection is finished successfully.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Parameters:

[in]	socket_fd	The file descriptor of socket on which start to listen
[in]	max_pending_connections	The maximum number of pending connections

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The socket must be created with bt_socket_create_rfcomm().

Postcondition:: If callback function bt_socket_connection_state_changed_cb() is set, then bt_socket_connection_state_changed_cb() will be called when the remote Bluetooth device is connected.

See also:: bt_socket_create_rfcomm(); bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_send_data	(	int	socket_fd,
		const char *	data,
		int	length
	)

Sends data to the connected device.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/bluetooth

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.

Parameters:

[in]	socket_fd	The file descriptor of connected socket which was received using bt_socket_connection_state_changed_cb()
[in]	data	The data to be sent
[in]	length	The length of data to be sent

Returns:: The number of bytes written (zero indicates nothing was written)

Return values:

On	error, `-1` is returned, and errno is set appropriately. See write 2 man page.
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not supported

Exceptions:

BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_AGAIN	Resource temporarily unavailable

Precondition:: The connection must be established.

See also:: bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_set_connection_requested_cb	(	bt_socket_connection_requested_cb	callback,
		void *	user_data
	)

Registers a callback function that will be invoked when a RFCOMM connection is requested.

Since :: 2.3

Parameters:

[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

Postcondition:: bt_socket_connection_requested_cb() will be invoked.

See also:: bt_initialize(); bt_socket_unset_connection_requested_cb()

int bt_socket_set_connection_state_changed_cb	(	bt_socket_connection_state_changed_cb	callback,
		void *	user_data
	)

Registers a callback function that will be invoked when the connection state changes.

Since :: 2.3

Parameters:

[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

Postcondition:: bt_socket_connection_state_changed_cb() will be invoked.

See also:: bt_initialize(); bt_socket_connection_state_changed_cb(); bt_socket_unset_connection_state_changed_cb()

int bt_socket_set_data_received_cb	(	bt_socket_data_received_cb	callback,
		void *	user_data
	)

Registers a callback function that will be invoked when you receive data.

Since :: 2.3

Parameters:

[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

Postcondition:: bt_socket_data_received_cb() will be invoked.

See also:: bt_initialize(); bt_socket_data_received_cb(); bt_socket_set_data_received_cb(); bt_socket_unset_data_received_cb()

int bt_socket_unset_connection_requested_cb ( void )

Unregisters the callback function.

Since :: 2.3

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize(); bt_socket_set_connection_requested_cb(); bt_socket_connection_requested_cb()

int bt_socket_unset_connection_state_changed_cb ( void )

Unregisters the callback function.

Since :: 2.3

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize(); bt_socket_connection_state_changed_cb(); bt_socket_set_connection_state_changed_cb()

int bt_socket_unset_data_received_cb ( void )

Unregisters the callback function.

Since :: 2.3

Returns:: 0 on success, otherwise a negative error value

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: The Bluetooth service must be initialized with bt_initialize().

See also:: bt_initialize(); bt_socket_data_received_cb(); bt_socket_set_data_received_cb()

Required Header

Overview

Related Features

Asynchronous Operations

Callback(Event) Operations

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation