Tizen Native API
5.5
|
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
- 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
- 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.
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] 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().
Enumeration Type Documentation
enum bt_socket_role_e |
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().
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.
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.
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.
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.
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 BT_ERROR_INVALID_PARAMETER Invalid parameter
- Exceptions:
-
BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_AGAIN Resource temporarily unavailable
- Precondition:
- The connection must be established.
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.
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.
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.
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().
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().
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().