Tizen Native API
7.0
|
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.
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] channel WebRTC data channel handle [in] user_data The user data passed from the callback registration function
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
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
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
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
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
Enumeration Type Documentation
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 istrue
.
'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_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] channel Data channel handle [out] buffered_amount The number of bytes of 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
- 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] channel Data channel handle [out] threshold The threshold
- 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
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.
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.
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] channel Data channel handle [in] threshold The threshold [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_OPERATION Invalid operation
- Postcondition:
- webrtc_data_channel_buffered_amount_low_cb() will be invoked.
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.
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.
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.
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.
Unsets the data channel buffered amount low callback function.
- Since :
- 7.0
- 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
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.
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()