Tizen Native API  7.0
Data Channel

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

Callback(Event) Operations

The callback mechanism is used to notify the application about significant webrtc data channel events.

REGISTER UNREGISTER CALLBACK DESCRIPTION
webrtc_set_data_channel_cb() webrtc_unset_data_channel_cb() webrtc_data_channel_cb() This callback is used to notify that a data channel is created to the connection by the remote peer
webrtc_data_channel_set_open_cb() webrtc_data_channel_unset_open_cb() webrtc_data_channel_open_cb() This callback is used to notify that the data channel is opened
webrtc_data_channel_set_message_cb() webrtc_data_channel_unset_message_cb() webrtc_data_channel_message_cb() This callback is used to notify that a message is received from the data channel
webrtc_data_channel_set_error_cb() webrtc_data_channel_unset_error_cb() webrtc_data_channel_error_cb() This callback is used to notify that an error occurs from the data channel
webrtc_data_channel_set_close_cb() webrtc_data_channel_unset_close_cb() webrtc_data_channel_close_cb() This callback is used to notify that the data channel is closed
webrtc_data_channel_set_buffered_amount_low_cb() webrtc_data_channel_unset_buffered_amount_low_cb() webrtc_data_channel_buffered_amount_low_cb() This callback is used to notify that the number of bytes of data currently queued to be sent over the data channel falls below the threshold

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.
int webrtc_data_channel_get_buffered_amount (webrtc_data_channel_h channel, unsigned int *buffered_amount)
 Gets the number of bytes of data currently queued to be sent over the data channel.
int webrtc_data_channel_set_buffered_amount_low_cb (webrtc_data_channel_h channel, unsigned int threshold, webrtc_data_channel_buffered_amount_low_cb callback, void *user_data)
 Sets the threshold at which the buffered amount is considered low and callback function.
int webrtc_data_channel_get_buffered_amount_low_threshold (webrtc_data_channel_h channel, unsigned int *threshold)
 Gets the threshold at which the buffered amount is considered low.
int webrtc_data_channel_unset_buffered_amount_low_cb (webrtc_data_channel_h channel)
 Unsets the data channel buffered amount low callback function.

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 void(* webrtc_data_channel_buffered_amount_low_cb )(webrtc_data_channel_h channel, void *user_data)
 Called when the number of bytes of data currently queued to be sent over the data channel falls below the threshold.

Typedef Documentation

typedef void* webrtc_bytes_data_h

WebRTC bytes data handle type.

Since :
6.5
typedef void(* webrtc_data_channel_buffered_amount_low_cb)(webrtc_data_channel_h channel, void *user_data)

Called when the number of bytes of data currently queued to be sent over the data channel falls below the threshold.

Since :
7.0
Remarks:
The channel is the same object for which the callback was set.
The channel should not be released.
Parameters:
[in]channelWebRTC data channel handle
[in]user_dataThe user data passed from the callback registration function
See also:
webrtc_create_data_channel()
webrtc_destroy_data_channel()
webrtc_data_channel_set_buffered_amount_low_cb()
webrtc_data_channel_unset_buffered_amount_low_cb()
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]webrtcWebRTC handle
[in]channelWebRTC data channel handle
[in]user_dataThe 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]channelWebRTC data channel handle
[in]user_dataThe 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]channelWebRTC data channel handle
[in]errorThe error code
[in]user_dataThe 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]channelWebRTC data channel handle
[in]typeThe data type
[in]messageThe message from the remote peer
[in]user_dataThe 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]channelWebRTC data channel handle
[in]user_dataThe 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

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]webrtcWebRTC handle
[in]labelName for the channel
[in]optionsConfiguration options for creating the data channel (optional, this can be NULL)
[out]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
WEBRTC_ERROR_INVALID_STATEInvalid state
Precondition:
webrtc state must be set to WEBRTC_STATE_IDLE.
See also:
webrtc_destroy_data_channel()
int webrtc_data_channel_get_buffered_amount ( webrtc_data_channel_h  channel,
unsigned int *  buffered_amount 
)

Gets the number of bytes of data currently queued to be sent over the data channel.

Since :
7.0
Parameters:
[in]channelData channel handle
[out]buffered_amountThe number of bytes of data
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_create_data_channel()
int webrtc_data_channel_get_buffered_amount_low_threshold ( webrtc_data_channel_h  channel,
unsigned int *  threshold 
)

Gets the threshold at which the buffered amount is considered low.

Since :
7.0
Remarks:
The default value is 0.
Parameters:
[in]channelData channel handle
[out]thresholdThe threshold
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_buffered_amount_low_cb()
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]channelData channel handle
[out]labelThe channel label
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid 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]channelData channel handle
[in]dataByte data to send
[in]sizeSize of the data
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
WEBRTC_ERROR_INVALID_STATEInvalid 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]channelData channel handle
[in]stringString data to send
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
WEBRTC_ERROR_INVALID_STATEInvalid 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_buffered_amount_low_cb ( webrtc_data_channel_h  channel,
unsigned int  threshold,
webrtc_data_channel_buffered_amount_low_cb  callback,
void *  user_data 
)

Sets the threshold at which the buffered amount is considered low and callback function.

Since :
7.0
Remarks:
The registered callback will be invoked in an internal thread of the webrtc.
Callback function will be invoked when the number of bytes currently queued falls below the threshold.
Parameters:
[in]channelData channel handle
[in]thresholdThe threshold
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
Postcondition:
webrtc_data_channel_buffered_amount_low_cb() will be invoked.
See also:
webrtc_data_channel_buffered_amount_low_cb()
webrtc_data_channel_get_buffered_amount_low_threshold()
webrtc_data_channel_unset_buffered_amount_low_cb()
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]channelData channel handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid 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]channelData channel handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
webrtc_data_channel_error_cb() will be invoked.
See also:
webrtc_data_channel_unset_error_cb()
webrtc_data_channel_error_cb()

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]channelData channel handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid 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]channelData channel handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
webrtc_data_channel_open_cb() will be invoked.
See also:
webrtc_data_channel_unset_open_cb()
webrtc_data_channel_open_cb()

Unsets the data channel buffered amount low callback function.

Since :
7.0
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_buffered_amount_low_cb()

Unsets the data channel close callback function.

Since :
6.5
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_close_cb()

Unsets the data channel error callback function.

Since :
6.5
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_error_cb()

Unsets the data channel message callback function.

Since :
6.5
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_message_cb()

Unsets the data channel open callback function.

Since :
6.5
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
See also:
webrtc_data_channel_set_open_cb()

Destroys the data channel.

Since :
6.5
Parameters:
[in]channelData channel handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid 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]bytesBytes data handle
[out]dataData pointer
[out]sizeSize of the data
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid 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]webrtcWebRTC handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_STATEInvalid 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()

Unsets the data channel callback function.

Since :
6.5
Parameters:
[in]webrtcWebRTC handle
Returns:
0 on success, otherwise a negative error value
Return values:
WEBRTC_ERROR_NONESuccessful
WEBRTC_ERROR_INVALID_PARAMETERInvalid parameter
WEBRTC_ERROR_INVALID_OPERATIONInvalid operation
WEBRTC_ERROR_INVALID_STATEInvalid state
Precondition:
webrtc state must be set to WEBRTC_STATE_IDLE.
See also:
webrtc_set_data_channel_cb()