CreateChannel Method

Creates a new channel.

Syntax

public fun createChannel(peerIP: String?, peerPort: Int): String?

Remarks

This method creates a new channel that the component can use to communicate more efficiently with the peer identified by PeerIP and PeerPort. If a channel with the given IP address and port already exists, it is refreshed. This method returns the Id of new/refreshed channel.

Channels expire after 10 minutes unless they are refreshed by calling this method again with the same values (this time limit is dictated by the TURN specification and cannot be changed). Sending data over a channel does not affect its expiration time; the channel must be explicitly refreshed using this method.

A successful call to this method will also create a permission for the given PeerIP (or, if one already exists, refresh it). Keep in mind that permissions only have a lifetime of 5 minutes; i.e., they must be refreshed more often than channels (either explicitly, using the CreatePermission method; or implicitly, using this method). If the permission for a given PeerIP expires, the server will stop relaying data over all channels associated with that PeerIP.

About Data Relaying

There are two mechanisms for sending data between a TURN client (e.g., this component) and a TURN server: indications and channels.

• Indications work by encapsulating the data within a STUN packet, which allows them to be sent at anytime without any further configuration. Use the SendData method to send data in an indication.
• Channels must be created ahead-of-time, but allow for more efficient data transfer between the client and server by sending data packets with minimal overhead. Use the SendChannelData method to send data over a channel.

In both cases, the server will only relay data to/from a peer if there is an active permission for the peer's IP address.

About Permissions

To prevent unwanted messages, TURN servers will only relay packets between a TURN client (e.g., this component) and a peer if there is an active permission for the peer's IP address. This restriction applies to packets flowing in both the peer-to-client direction and the client-to-peer direction, and applies regardless of whether the packets are delivered in an indication or on a channel. Essentially, permissions are a "peer whitelist" mechanism.

The component automatically tracks active permissions, adding and removing items to and from the Permissions collection as they are created and expired. The TURNPermission type's TTL field can be queried to determine the number of seconds remaining until that permission expires.

Refer to the CreatePermission method for more information.