The Data Channel API provides functions to manage data channels.

Required Header

#include <webrtc.h>

Overview

The WebRTC Data Channel API allows you to:

create/destroy the data channel
send/receive bytes or string data to/from the data channel
get notified various states of the data channel

Functions
int	webrtc_set_data_channel_cb (webrtc_h webrtc, webrtc_data_channel_cb callback, void *user_data)
	Sets a data channel callback function to be invoked when the data channel is created to the connection by the remote peer.
int	webrtc_unset_data_channel_cb (webrtc_h webrtc)
	Unsets the data channel callback function.
int	webrtc_create_data_channel (webrtc_h webrtc, const char label, bundle options, webrtc_data_channel_h *channel)
	Creates a new data channel which is linked with the remote peer.
int	webrtc_destroy_data_channel (webrtc_data_channel_h channel)
	Destroys the data channel.
int	webrtc_data_channel_set_open_cb (webrtc_data_channel_h channel, webrtc_data_channel_open_cb callback, void *user_data)
	Sets a data channel open callback function to be invoked when the data channel's underlying data transport is established.
int	webrtc_data_channel_unset_open_cb (webrtc_data_channel_h channel)
	Unsets the data channel open callback function.
int	webrtc_data_channel_set_message_cb (webrtc_data_channel_h channel, webrtc_data_channel_message_cb callback, void *user_data)
	Sets a data channel message callback function to be invoked when a message is received from the remote peer.
int	webrtc_data_channel_unset_message_cb (webrtc_data_channel_h channel)
	Unsets the data channel message callback function.
int	webrtc_data_channel_set_error_cb (webrtc_data_channel_h channel, webrtc_data_channel_error_cb callback, void *user_data)
	Sets a data channel error callback function to be invoked when an error occurs on the data channel.
int	webrtc_data_channel_unset_error_cb (webrtc_data_channel_h channel)
	Unsets the data channel error callback function.
int	webrtc_data_channel_set_close_cb (webrtc_data_channel_h channel, webrtc_data_channel_close_cb callback, void *user_data)
	Sets a data channel close callback function to be invoked when the data channel has closed down.
int	webrtc_data_channel_unset_close_cb (webrtc_data_channel_h channel)
	Unsets the data channel close callback function.
int	webrtc_data_channel_send_string (webrtc_data_channel_h channel, const char *string)
	Sends a string data across the data channel to the remote peer.
int	webrtc_data_channel_send_bytes (webrtc_data_channel_h channel, const char *data, unsigned int size)
	Sends byte data across the data channel to the remote peer.
int	webrtc_data_channel_get_label (webrtc_data_channel_h channel, char **label)
	Gets the channel label.
int	webrtc_get_data (webrtc_bytes_data_h bytes, const char *data, unsigned long size)
	Gets data pointer and its size.
Typedefs
typedef void *	webrtc_data_channel_h
	WebRTC data channel handle type.
typedef void *	webrtc_bytes_data_h
	WebRTC bytes data handle type.
typedef void(*	webrtc_data_channel_cb )(webrtc_h webrtc, webrtc_data_channel_h channel, void *user_data)
	Called when the data channel is created to the connection by the remote peer.
typedef void(*	webrtc_data_channel_open_cb )(webrtc_data_channel_h channel, void *user_data)
	Called when the data channel's underlying data transport is established.
typedef void(*	webrtc_data_channel_message_cb )(webrtc_data_channel_h channel, webrtc_data_channel_type_e type, void message, void user_data)
	Called when a message is received from other peer via the data channel.
typedef void(*	webrtc_data_channel_error_cb )(webrtc_data_channel_h channel, webrtc_error_e error, void *user_data)
	Called when an error occurs on the data channel.
typedef void(*	webrtc_data_channel_close_cb )(webrtc_data_channel_h channel, void *user_data)
	Called when the data channel has closed down.

Typedef Documentation

typedef void* webrtc_bytes_data_h

WebRTC bytes data handle type.

Since :: 6.5

typedef void(* webrtc_data_channel_cb)(webrtc_h webrtc, webrtc_data_channel_h channel, void *user_data)

Called when the data channel is created to the connection by the remote peer.

Since :: 6.5

Remarks:: The webrtc is the same object for which the callback was set.
The webrtc should not be released.
The channel should not be released.

Parameters:

[in]	webrtc	WebRTC handle
[in]	channel	WebRTC data channel handle
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_data_channel_set_open_cb(); webrtc_data_channel_unset_open_cb(); webrtc_data_channel_set_message_cb(); webrtc_data_channel_unset_message_cb(); webrtc_data_channel_set_error_cb(); webrtc_data_channel_unset_error_cb(); webrtc_data_channel_set_close_cb(); webrtc_data_channel_unset_close_cb()

typedef void(* webrtc_data_channel_close_cb)(webrtc_data_channel_h channel, void *user_data)

Called when the data channel has closed down.

Since :: 6.5

Remarks:: The channel is the same object for which the callback was set.
The channel should not be released.

Parameters:

[in]	channel	WebRTC data channel handle
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_create_data_channel(); webrtc_destroy_data_channel(); webrtc_data_channel_set_close_cb(); webrtc_data_channel_unset_close_cb()

typedef void(* webrtc_data_channel_error_cb)(webrtc_data_channel_h channel, webrtc_error_e error, void *user_data)

Called when an error occurs on the data channel.

The following error codes can be received:
WEBRTC_ERROR_INVALID_OPERATION
WEBRTC_ERROR_STREAM_FAILED
WEBRTC_ERROR_RESOURCE_FAILED

Since :: 6.5

Remarks:: The channel is the same object for which the callback was set.
The channel should not be released.

Parameters:

[in]	channel	WebRTC data channel handle
[in]	error	The error code
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_create_data_channel(); webrtc_destroy_data_channel(); webrtc_data_channel_set_error_cb(); webrtc_data_channel_unset_error_cb()

typedef void* webrtc_data_channel_h

WebRTC data channel handle type.

Since :: 6.5

typedef void(* webrtc_data_channel_message_cb)(webrtc_data_channel_h channel, webrtc_data_channel_type_e type, void *message, void *user_data)

Called when a message is received from other peer via the data channel.

Since :: 6.5

Remarks:: The channel is the same object for which the callback was set.
The channel should not be released.
When type is WEBRTC_DATA_CHANNEL_TYPE_STRING, message should be casted to char pointer.
When type is WEBRTC_DATA_CHANNEL_TYPE_BYTES, message should be casted to webrtc_bytes_data_h. In this case, webrtc_get_data() can be used to get the data and its size inside of this callback.
The message should not be released.

Parameters:

[in]	channel	WebRTC data channel handle
[in]	type	The data type
[in]	message	The message from the remote peer
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_create_data_channel(); webrtc_destroy_data_channel(); webrtc_data_channel_set_message_cb(); webrtc_data_channel_unset_message_cb(); webrtc_get_data()

typedef void(* webrtc_data_channel_open_cb)(webrtc_data_channel_h channel, void *user_data)

Called when the data channel's underlying data transport is established.

Since :: 6.5

Remarks:: The channel is the same object for which the callback was set.
The channel should not be released.

Parameters:

[in]	channel	WebRTC data channel handle
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_create_data_channel(); webrtc_destroy_data_channel(); webrtc_data_channel_set_open_cb(); webrtc_data_channel_unset_open_cb()

Enumeration Type Documentation

enum webrtc_data_channel_type_e

Enumeration for WebRTC data channel type.

Since :: 6.5

Enumerator:

WEBRTC_DATA_CHANNEL_TYPE_STRING	String data
WEBRTC_DATA_CHANNEL_TYPE_BYTES	Bytes data

Function Documentation

int webrtc_create_data_channel	(	webrtc_h	webrtc,
		const char *	label,
		bundle *	options,
		webrtc_data_channel_h *	channel
	)

Creates a new data channel which is linked with the remote peer.

Since :: 6.5

Remarks:: The channel should be released using webrtc_destroy().
The options dictionary is similar format as the RTCDataChannelInit members outlined https://www.w3.org/TR/webrtc/#dom-rtcdatachannelinit.
The following attributes can be set to options by using bundle API:
'ordered' of type bool : Whether the channel will send data with guaranteed ordering. The default value is true.
'max-packet-lifetime' of type int : The time in milliseconds to attempt transmitting unacknowledged data. -1 for unset. The default value is -1.
'max-retransmits' of type int : The number of times data will be attempted to be transmitted without acknowledgement before dropping. The default value is -1.
'protocol' of type string : The subprotocol used by this channel. The default value is NULL.
'id' of type int : Override the default identifier selection of this channel. The default value is -1.
'priority' of type int : The priority to use for this channel(1:very low, 2:low, 3:medium, 4:high). The default value is 2.

Parameters:

[in]	webrtc	WebRTC handle
[in]	label	Name for the channel
[in]	options	Configuration options for creating the data channel (optional, this can be NULL)
[out]	channel	Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_destroy_data_channel()

int webrtc_data_channel_get_label	(	webrtc_data_channel_h	channel,
		char **	label
	)

Gets the channel label.

Since :: 6.5

Remarks:: The label should be released using free().

Parameters:

[in]	channel	Data channel handle
[out]	label	The channel label

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_create_data_channel()

int webrtc_data_channel_send_bytes	(	webrtc_data_channel_h	channel,
		const char *	data,
		unsigned int	size
	)

Sends byte data across the data channel to the remote peer.

Since :: 6.5

Parameters:

[in]	channel	Data channel handle
[in]	data	Byte data to send
[in]	size	Size of the data

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: channel should be opened before calling this function.

Postcondition:: webrtc_data_channel_error_cb() will be invoked if this function fails.

See also:: webrtc_data_channel_open_cb(); webrtc_data_channel_send_string()

int webrtc_data_channel_send_string	(	webrtc_data_channel_h	channel,
		const char *	string
	)

Sends a string data across the data channel to the remote peer.

Since :: 6.5

Parameters:

[in]	channel	Data channel handle
[in]	string	String data to send

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: channel should be opened before calling this function.

Postcondition:: webrtc_data_channel_error_cb() will be invoked if this function fails.

See also:: webrtc_data_channel_open_cb(); webrtc_data_channel_send_bytes()

int webrtc_data_channel_set_close_cb	(	webrtc_data_channel_h	channel,
		webrtc_data_channel_close_cb	callback,
		void *	user_data
	)

Sets a data channel close callback function to be invoked when the data channel has closed down.

Since :: 6.5

Remarks:: The registered callback will be invoked in an internal thread of the webrtc.

Parameters:

[in]	channel	Data channel handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

Postcondition:: webrtc_data_channel_close_cb() will be invoked.

See also:: webrtc_data_channel_unset_close_cb(); webrtc_data_channel_close_cb()

int webrtc_data_channel_set_error_cb	(	webrtc_data_channel_h	channel,
		webrtc_data_channel_error_cb	callback,
		void *	user_data
	)

Sets a data channel error callback function to be invoked when an error occurs on the data channel.

Since :: 6.5

Remarks:: The registered callback will be invoked in an internal thread of the webrtc.

Parameters:

[in]	channel	Data channel handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

Postcondition:: webrtc_data_channel_error_cb() will be invoked.

See also:: webrtc_data_channel_unset_error_cb(); webrtc_data_channel_error_cb()

int webrtc_data_channel_set_message_cb	(	webrtc_data_channel_h	channel,
		webrtc_data_channel_message_cb	callback,
		void *	user_data
	)

Sets a data channel message callback function to be invoked when a message is received from the remote peer.

Since :: 6.5

Remarks:: The registered callback will be invoked in an internal thread of the webrtc.

Parameters:

[in]	channel	Data channel handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

Postcondition:: webrtc_data_channel_message_cb() will be invoked.

See also:: webrtc_data_channel_unset_message_cb(); webrtc_data_channel_message_cb()

int webrtc_data_channel_set_open_cb	(	webrtc_data_channel_h	channel,
		webrtc_data_channel_open_cb	callback,
		void *	user_data
	)

Sets a data channel open callback function to be invoked when the data channel's underlying data transport is established.

Since :: 6.5

Remarks:: The registered callback will be invoked in an internal thread of the webrtc.

Parameters:

[in]	channel	Data channel handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

Postcondition:: webrtc_data_channel_open_cb() will be invoked.

See also:: webrtc_data_channel_unset_open_cb(); webrtc_data_channel_open_cb()

int webrtc_data_channel_unset_close_cb ( webrtc_data_channel_h channel )

Unsets the data channel close callback function.

Since :: 6.5

Parameters:

[in] channel Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_data_channel_set_close_cb()

int webrtc_data_channel_unset_error_cb ( webrtc_data_channel_h channel )

Unsets the data channel error callback function.

Since :: 6.5

Parameters:

[in] channel Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_data_channel_set_error_cb()

int webrtc_data_channel_unset_message_cb ( webrtc_data_channel_h channel )

Unsets the data channel message callback function.

Since :: 6.5

Parameters:

[in] channel Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_data_channel_set_message_cb()

int webrtc_data_channel_unset_open_cb ( webrtc_data_channel_h channel )

Unsets the data channel open callback function.

Since :: 6.5

Parameters:

[in] channel Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_data_channel_set_open_cb()

int webrtc_destroy_data_channel ( webrtc_data_channel_h channel )

Destroys the data channel.

Since :: 6.5

Parameters:

[in] channel Data channel handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: webrtc_create_data_channel()

int webrtc_get_data	(	webrtc_bytes_data_h	bytes,
		const char **	data,
		unsigned long *	size
	)

Gets data pointer and its size.

Since :: 6.5

Remarks:: This function must be called inside of the webrtc_data_channel_message_cb().
bytes and data are managed by the platform and will be released when after the webrtc_data_channel_message_cb() is ended.

Parameters:

[in]	bytes	Bytes data handle
[out]	data	Data pointer
[out]	size	Size of the data

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: webrtc_data_channel_message_cb()

int webrtc_set_data_channel_cb	(	webrtc_h	webrtc,
		webrtc_data_channel_cb	callback,
		void *	user_data
	)

Sets a data channel callback function to be invoked when the data channel is created to the connection by the remote peer.

Since :: 6.5

Remarks:: The registered callback will be invoked in an internal thread of the webrtc.

Parameters:

[in]	webrtc	WebRTC handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: webrtc state must be set to WEBRTC_STATE_IDLE.

Postcondition:: webrtc_data_channel_cb() will be invoked.

See also:: webrtc_unset_data_channel_cb(); webrtc_data_channel_cb()

int webrtc_unset_data_channel_cb ( webrtc_h webrtc )

Unsets the data channel callback function.

Since :: 6.5

Parameters:

[in] webrtc WebRTC handle

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_set_data_channel_cb()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation