Tizen Native API  7.0
Bluetooth L2CAP Socket

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

Callback(Event) Operations


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_fdThe file descriptor of socket on which a connection is requested
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 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_addressThe address of the remote Bluetooth device
[in]psmThe dynamic PSM of a 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 scannable with bt_adapter_le_start_scan().
Postcondition:
This function invokes bt_socket_l2cap_channel_connection_state_changed_cb().
See also:
bt_adapter_le_start_scan()
bt_socket_disconnect_l2cap_channel()
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_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]psmThe dynamic PSM value to start server
[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_l2cap_channel()
bt_socket_destroy_l2cap_channel()
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_fdThe 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_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_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.
See also:
bt_socket_create_l2cap_channel()
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_l2cap_channel_connection_state_changed_cb()
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_fdThe 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_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 connection must be established.
See also:
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_l2cap_channel_connection_state_changed_cb()
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_fdThe file descriptor of connected socket which was received using bt_socket_l2cap_channel_connection_state_changed_cb()
[out]psmThe assigned dynamic PSM value for the listening L2CAP CoC server socket
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 bt_socket_listen_and_accept_l2cap_channel() must be called.
See also:
bt_socket_create_l2cap_channel()
bt_socket_listen_and_accept_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.

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_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_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.
See also:
bt_socket_create_l2cap_channel()
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_l2cap_channel_connection_state_changed_cb()
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_fdThe file descriptor socket on which start to listen
[in]max_pending_connectionsThe 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_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_fdThe file descriptor of socket on which a connection is requested
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 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_fdThe file descriptor of connected socket which was received using bt_socket_l2cap_channel_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_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
Exceptions:
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_AGAINResource temporarily unavailable
Return values:
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The connection must be established.
See also:
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_l2cap_channel_connection_state_changed_cb()

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

Since :
7.0
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_l2cap_channel_connection_requested_cb()

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

Since :
7.0
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_l2cap_channel_connection_state_changed_cb() will be invoked.
See also:
bt_initialize()
bt_socket_l2cap_channel_connection_state_changed_cb()
bt_socket_unset_l2cap_channel_connection_state_changed_cb()

Unregisters the L2CAP CoC connection requested callback.

Since :
7.0
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_l2cap_channel_connection_requested_cb()
bt_socket_connection_requested_cb()

Unregisters the L2CAP CoC connection state changed callback.

Since :
7.0
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_l2cap_channel_connection_state_changed_cb()
bt_socket_set_l2cap_channel_connection_state_changed_cb()