Tizen Native API
7.0
|
Bluetooth L2CAP 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_l2cap_channel_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_l2cap_channel()), and start listening and accepting incoming connections (bt_socket_listen_and_accept_l2cap_channel()). If you want to connect to specific device and use it's services (client role), you have to start connection with bt_socket_connect_l2cap_channel() and wait for connection.
After connection has been established (information is passed to your program with bt_socket_l2cap_channel_connection_state_changed_cb() function call), you can exchange data by calling bt_socket_send_data_l2cap_channel().
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_l2cap_channel() and unregister callback functions (with using bt_socket_unset_data_received_cb(), bt_socket_unset_l2cap_channel_connection_state_changed_cb()).
Related Features
This API is related with the following features:
- http://tizen.org/feature/network.bluetooth.le.coc
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_l2cap_channel() bt_socket_connect_l2cap_channel() | bt_socket_l2cap_channel_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_l2cap_channel_connection_state_changed_cb() | bt_socket_unset_l2cap_channel_connection_state_changed_cb() | bt_socket_l2cap_channel_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_l2cap_channel (int psm, int *socket_fd) |
Registers a L2CAP Connection-oriented Channel (CoC) server socket with a specific protocol/service multiplexer (PSM) value. | |
int | bt_socket_destroy_l2cap_channel (int socket_fd) |
Removes the L2CAP Connection-oriented Channel (CoC) server socket which was created using bt_socket_create_l2cap_channel(). | |
int | bt_socket_listen_and_accept_l2cap_channel (int socket_fd, int max_pending_connections) |
Starts listening on passed L2CAP_LE socket and accepts connection requests. | |
int | bt_socket_get_l2cap_psm (int socket_fd, int *psm) |
Gets the assigned PSM for the listening L2CAP Connection-oriented Channel (CoC) server socket. | |
int | bt_socket_connect_l2cap_channel (const char *remote_address, int psm) |
Connects to a specific L2CAP CoC socket on a remote Bluetooth device PSM, asynchronously. | |
int | bt_socket_disconnect_l2cap_channel (int socket_fd) |
Disconnects the L2CAP CoC connection with the given file descriptor of connected socket. | |
int | bt_socket_send_data_l2cap_channel (int socket_fd, const char *data, int length) |
Sends data to the connected device. | |
int | bt_socket_set_l2cap_channel_connection_requested_cb (bt_socket_connection_requested_cb callback, void *user_data) |
Registers a callback function that will be invoked when a L2CAP CoC connection is requested. | |
int | bt_socket_unset_l2cap_channel_connection_requested_cb (void) |
Unregisters the L2CAP CoC connection requested callback. | |
int | bt_socket_set_l2cap_channel_connection_state_changed_cb (bt_socket_l2cap_channel_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_l2cap_channel_connection_state_changed_cb (void) |
Unregisters the L2CAP CoC connection state changed callback. | |
int | bt_socket_listen_l2cap_channel (int socket_fd, int max_pending_connections) |
Starts listening on passed L2CAP Connection-oriented Channel (CoC) socket. | |
int | bt_socket_accept_l2cap_channel (int requested_socket_fd) |
Accepts a connection request. | |
int | bt_socket_reject_l2cap_channel (int socket_fd) |
Rejects a connection request. |
Function Documentation
int bt_socket_accept_l2cap_channel | ( | int | requested_socket_fd | ) |
Accepts a connection request.
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] requested_socket_fd The file descriptor of socket on which a connection is requested
- 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 connection is requested by bt_socket_l2cap_channel_connection_requested_cb().
- See also:
- bt_socket_create_l2cap_channel()
- bt_socket_l2cap_channel_connection_requested_cb()
- bt_socket_listen_l2cap_channel()
- bt_socket_reject_l2cap_channel()
int bt_socket_connect_l2cap_channel | ( | const char * | remote_address, |
int | psm | ||
) |
Connects to a specific L2CAP CoC socket on a remote Bluetooth device PSM, asynchronously.
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Remarks:
- A connection can be disconnected by bt_socket_disconnect_l2cap_channel().
- Parameters:
-
[in] remote_address The address of the remote Bluetooth device [in] psm The dynamic PSM of a 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 scannable with bt_adapter_le_start_scan().
- Postcondition:
- This function invokes bt_socket_l2cap_channel_connection_state_changed_cb().
int bt_socket_create_l2cap_channel | ( | int | psm, |
int * | socket_fd | ||
) |
Registers a L2CAP Connection-oriented Channel (CoC) server socket with a specific protocol/service multiplexer (PSM) value.
If 0 is passed, the system will assign a dynamic PSM value when bt_socket_listen_and_accept_l2cap_channel() is called. This psm value can be read from the bt_socket_get_l2cap_psm().
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Remarks:
- A socket can be destroyed by bt_socket_destroy_l2cap_channel().
- Parameters:
-
[in] psm The dynamic PSM value to start server [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_l2cap_channel | ( | int | socket_fd | ) |
Removes the L2CAP Connection-oriented Channel (CoC) server socket which was created using bt_socket_create_l2cap_channel().
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Remarks:
- If callback function bt_socket_l2cap_channel_connection_state_changed_cb() is set and the remote Bluetooth device is connected, then bt_socket_l2cap_channel_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_l2cap_channel()) 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_l2cap_channel().
- Postcondition:
- If callback function bt_socket_l2cap_channel_connection_state_changed_cb() is set and the remote Bluetooth device is connected, then bt_socket_l2cap_channel_connection_state_changed_cb() will be called.
int bt_socket_disconnect_l2cap_channel | ( | int | socket_fd | ) |
Disconnects the L2CAP CoC connection with the given file descriptor of connected socket.
- Since :
- 7.0
- 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_l2cap_channel_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_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 connection must be established.
int bt_socket_get_l2cap_psm | ( | int | socket_fd, |
int * | psm | ||
) |
Gets the assigned PSM for the listening L2CAP Connection-oriented Channel (CoC) server socket.
It is used to get the system assigned PSM value especially when bt_socket_create_l2cap_channel() is called with psm value 0.
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] socket_fd The file descriptor of connected socket which was received using bt_socket_l2cap_channel_connection_state_changed_cb() [out] psm The assigned dynamic PSM value for the listening L2CAP CoC server socket
- 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 bt_socket_listen_and_accept_l2cap_channel() must be called.
int bt_socket_listen_and_accept_l2cap_channel | ( | int | socket_fd, |
int | max_pending_connections | ||
) |
Starts listening on passed L2CAP_LE socket and accepts connection requests.
Pop-up is shown automatically when a L2CAP CoC connection is requested. bt_socket_l2cap_channel_connection_state_changed_cb() will be called with BT_SOCKET_CONNECTED if the user click "yes" and connection is finished successfully.
- Since :
- 7.0
- 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_l2cap_channel().
- Postcondition:
- If callback function bt_socket_l2cap_channel_connection_state_changed_cb() is set, then bt_socket_l2cap_channel_connection_state_changed_cb() will be called when the remote Bluetooth device is connected.
int bt_socket_listen_l2cap_channel | ( | int | socket_fd, |
int | max_pending_connections | ||
) |
Starts listening on passed L2CAP Connection-oriented Channel (CoC) socket.
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
bt_socket_l2cap_channel_connection_requested_cb() will be called when a L2CAP CoC connection is requested.
- Parameters:
-
[in] socket_fd The file descriptor socket on which start to listen [in] max_pending_connections The 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_l2cap_channel().
- Postcondition:
- This function invokes bt_socket_l2cap_channel_connection_state_changed_cb().
- See also:
- bt_socket_create_l2cap_channel()
- bt_socket_set_l2cap_channel_connection_requested_cb()
- bt_socket_unset_l2cap_channel_connection_requested_cb()
- bt_socket_l2cap_channel_connection_requested_cb()
int bt_socket_reject_l2cap_channel | ( | int | socket_fd | ) |
Rejects a connection request.
- Since :
- 7.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/bluetooth
- Parameters:
-
[in] socket_fd The file descriptor of socket on which a connection is requested
- 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 connection is requested by bt_socket_l2cap_channel_connection_requested_cb().
- See also:
- bt_socket_create_l2cap_channel()
- bt_socket_l2cap_channel_connection_requested_cb()
- bt_socket_listen_l2cap_channel()
- bt_socket_accept_l2cap_channel()
int bt_socket_send_data_l2cap_channel | ( | int | socket_fd, |
const char * | data, | ||
int | length | ||
) |
Sends data to the connected device.
- Since :
- 7.0
- 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_l2cap_channel_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_INVALID_PARAMETER Invalid parameter BT_ERROR_NOT_ENABLED Not enabled
- Exceptions:
-
BT_ERROR_PERMISSION_DENIED Permission denied BT_ERROR_AGAIN Resource temporarily unavailable
- Return values:
-
BT_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The connection must be established.
int bt_socket_set_l2cap_channel_connection_requested_cb | ( | bt_socket_connection_requested_cb | callback, |
void * | user_data | ||
) |
Registers a callback function that will be invoked when a L2CAP CoC connection is requested.
- Since :
- 7.0
- 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_l2cap_channel_connection_state_changed_cb | ( | bt_socket_l2cap_channel_connection_state_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function that will be invoked when the connection state changes.
- Since :
- 7.0
- 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_l2cap_channel_connection_state_changed_cb() will be invoked.
Unregisters the L2CAP CoC connection requested callback.
- Since :
- 7.0
- 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().
Unregisters the L2CAP CoC connection state changed callback.
- Since :
- 7.0
- 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().