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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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]	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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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.

bt_socket_l2cap_channel_connection_requested_cb() will be called when a L2CAP CoC connection is requested.

Since :: 7.0

Privilege Level:: public

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

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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed

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_SUPPORTED	Not supported
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_AGAIN	Resource temporarily unavailable

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_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_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized

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()

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_SUPPORTED	Not supported
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_INITIALIZED	Not initialized

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()

int bt_socket_unset_l2cap_channel_connection_requested_cb ( void )

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_SUPPORTED	Not supported
BT_ERROR_NOT_INITIALIZED	Not initialized

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()

int bt_socket_unset_l2cap_channel_connection_state_changed_cb ( void )

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_SUPPORTED	Not supported
BT_ERROR_NOT_INITIALIZED	Not initialized

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()

Required Header

Overview

Related Features

Asynchronous Operations

Callback(Event) Operations

Functions

Function Documentation