Tizen Native API
Bluetooth Socket

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:

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)
 Register 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)
 Register 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)
 Register 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
Parameters:
[in]socket_fdThe file descriptor of socket on which a connection is requested
[in]remote_addressThe address of remote device
[in]user_dataThe 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
Parameters:
[in]resultThe result of connection state changing
[in]connection_stateThe connection state
[in]connectionThe connection information which is established or disconnected
[in]user_dataThe 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
Parameters:
[in]dataThe received data from the remote device
[in]user_dataThe 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

Enumerations of Bluetooth socket connection state.

Since :
2.3
Enumerator:
BT_SOCKET_CONNECTED 

RFCOMM is connected

BT_SOCKET_DISCONNECTED 

RFCOMM is disconnected

Enumerations of connected Bluetooth device event role.

Since :
2.3
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_addressThe address of the remote Bluetooth device
[in]service_uuidThe UUID of service provided by the remote Bluetooth device
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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_uuidThe UUID of service to provide
[out]socket_fdThe file descriptor of socket to listen
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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_fdThe 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_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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_fdThe 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_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth

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.

Parameters:
[in]socket_fdThe file descriptor of socket on which start to listen
[in]max_pending_connectionsThe maximum number of pending connections
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot 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_fdThe file descriptor of connected socket which was received using bt_socket_connection_state_changed_cb()
[in]dataThe data to be sent
[in]lengthThe length of data to be sent
Returns:
the number of bytes written (zero indicates nothing was written).
Return values:
Onerror, -1 is returned, and errno is set appropriately. See write 2 man page.
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot supported
Exceptions:
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_AGAINResource 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()

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

Since :
2.3
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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()

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

Since :
2.3
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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 
)

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

Since :
2.3
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot 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()

Unregisters the callback function.

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot 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()

Unregisters the callback function.

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot 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()

Unregisters the callback function.

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot 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()