TeamTalk 4 .NET DLL  Version 4.5A
Client/Server Connectivity

To communicate with a server the TeamTalk client creates both a TCP and UDP connection to the server. Commands, i.e. the BearWare.TeamTalk4.Do*-functions, are sent on TCP whereas audio and video are sent on UDP. More...

Classes

struct  BearWare.ClientStatistics
 Statistics of bandwidth usage and ping times in the local client instance. More...
 

Functions

bool BearWare.TeamTalk4.Connect (string szHostAddress, int nTcpPort, int nUdpPort, int nLocalTcpPort, int nLocalUdpPort)
 Connect to a server. More...
 
bool BearWare.TeamTalk4.ConnectEx (string szHostAddress, int nTcpPort, int nUdpPort, string szBindIPAddr, int nLocalTcpPort, int nLocalUdpPort)
 Bind to specific IP-address priot to connecting to server. More...
 
bool BearWare.TeamTalk4.ConnectNonEncrypted (string szHostAddress, int nTcpPort, int nUdpPort, string szBindIPAddr, int nLocalTcpPort, int nLocalUdpPort)
 Connect to non-encrypted TeamTalk server. More...
 
bool BearWare.TeamTalk4.Disconnect ()
 Disconnect from the server. More...
 
bool BearWare.TeamTalk4.QueryMaxPayload (int nUserID)
 Query the maximum size of UDP data packets to the user or server. More...
 
bool BearWare.TeamTalk4.SetKeepAliveInterval (int nTcpPingIntervalSec, int nUdpPingIntervalSec)
 Set how often the client should ping the server on its TCP and UDP connection. More...
 
bool BearWare.TeamTalk4.GetKeepAliveInterval (out int lpnTcpPingIntervalSec, out int lpnUdpPingIntervalSec)
 Gets how often the client is sending keep-alive information to the server. More...
 
bool BearWare.TeamTalk4.SetServerTimeout (int nTimeoutSec)
 Set server timeout for the client instance. More...
 
int BearWare.TeamTalk4.GetServerTimeout ()
 Get the server timeout for the client instance. More...
 
bool BearWare.TeamTalk4.EnablePeerToPeer (TransmitType mask, bool bEnable)
 Enable/disable peer to peer data transmission. More...
 
bool BearWare.TeamTalk4.GetStatistics (out ClientStatistics lpStats)
 Retrieve client statistics of bandwidth usage and response times. More...
 
int BearWare.TeamTalk4.GetPacketSize (AudioCodec lpCodec)
 Get the number of bytes in a packet with the specified audio codec. More...
 

Detailed Description

To communicate with a server the TeamTalk client creates both a TCP and UDP connection to the server. Commands, i.e. the BearWare.TeamTalk4.Do*-functions, are sent on TCP whereas audio and video are sent on UDP.

To connect to a server the user application must call TeamTalk4.Connect(). Once connected the event TeamTalk4.OnConnectSuccess() is posted to the user application and the TeamTalk4.DoLogin() command can be issued. Always ensure to call TeamTalk4.Disconnect() before attempting to create a new connection with TeamTalk4.Connect().

When the client instance has joined a channel and wants to transmit audio or video data to other users this can be done in two ways depending on how the user application configures the client. One way is forward through server and the other is peer to peer mode which are explained in the following two sections.

Forward Through Server Transmission Mode

By default the client instance is sending its audio and video packets to the server and the server will then broadcast the packets to the other users on behalf of the client. In other words the client puts the bandwidth load onto the server. This approach has its advantages and disadvantages. Since most internet connections nowadays have limited upstream they cannot broadcast audio and video packets to numerous users at the same time, so therefore the default behaviour of the TeamTalk client is to have the server do the broadcasting. This means that the server must have sufficient bandwidth available to handle data transmission from and to all the connected users. One disadvantage by having the server forward the audio and video packets is that it doubles latency, since the client doesn't send directly to other clients.

If the server should not allow clients to forward audio and video packets the uUserRights member of BearWare.ServerProperties must disable UserRight USERRIGHT_FORWARD_AUDIO and UserRight USERRIGHT_FORWARD_VIDEO. Doing so means that clients connecting must use peer to peer connections in order to communicate. Note that the client doesn't automatically switch to peer to peer mode, but relies on the user application to call TeamTalk4.EnablePeerToPeer().

Peer to Peer Transmission Mode

By calling TeamTalk4.EnablePeerToPeer() the client instance will attempt to create peer to peer connections to all users it's communicating with. This reduces latency since the client will then broadcast the audio and video packets itself, so they do not have to be forwarded through the server.

The event TeamTalk4.OnConnectionP2P() is posted to the user application if a peer to peer connection either fails or succeeds. If a peer to peer connection fails the client will send through the server to that user given that the server allows it, i.e. if UserRight USERRIGHT_FORWARD_AUDIO or UserRight USERRIGHT_FORWARD_VIDEO is enabled.

If the server does not allow users to forward audio and video packets and the peer to peer connection to a user fails, then that user will be unavailable for audio and video data. So beware of this when configuring the server and client.

Function Documentation

bool BearWare.TeamTalk4.Connect ( string  szHostAddress,
int  nTcpPort,
int  nUdpPort,
int  nLocalTcpPort,
int  nLocalUdpPort 
)

Connect to a server.

This is a non-blocking call (but may block due to DNS lookup) so the user application must wait for the event OnConnectSuccess to be posted once the connection has been established or OnConnectFailed if connection could not be established. If the connection could not be establish ensure to call Disconnect to close open connections in the client instance before trying again.

Once connected call DoLogin to log on to the server.

Parameters
szHostAddressThe IP-address or hostname of the server.
nTcpPortThe host port of the server (TCP).
nUdpPortThe audio/video port of the server (UDP).
nLocalTcpPortThe local TCP port which should be used. Setting it to 0 makes OS select a port number (recommended).
nLocalUdpPortThe local UDP port which should be used. Setting it to 0 makes OS select a port number (recommended).
See Also
OnConnectSuccess
OnConnectFailed
TeamTalk4.DoLogin
bool BearWare.TeamTalk4.ConnectEx ( string  szHostAddress,
int  nTcpPort,
int  nUdpPort,
string  szBindIPAddr,
int  nLocalTcpPort,
int  nLocalUdpPort 
)

Bind to specific IP-address priot to connecting to server.

Same as Connect() except that this also allows which IP-address to bind to on the local interface.

Parameters
szHostAddressThe IP-address or hostname of the server.
nTcpPortThe host port of the server (TCP).
nUdpPortThe audio/video port of the server (UDP).
szBindIPAddrThe IP-address to bind to on the local interface in dotted decimal format, e.g. 192.168.1.10.
nLocalTcpPortThe local TCP port which should be used. Setting it to 0 makes OS select a port number (recommended).
nLocalUdpPortThe local UDP port which should be used. Setting it to 0 makes OS select a port number (recommended).
See Also
Connect
bool BearWare.TeamTalk4.ConnectNonEncrypted ( string  szHostAddress,
int  nTcpPort,
int  nUdpPort,
string  szBindIPAddr,
int  nLocalTcpPort,
int  nLocalUdpPort 
)

Connect to non-encrypted TeamTalk server.

This function is only useful in the Professional edition of the TeamTalk SDK. It enabled the encrypted TeamTalk client to connect to non-encrypted TeamTalk servers. The default behaviour of TeamTalk4.Connect() and TeamTalk4.ConnectEx() in the Professional SDK is to connect to encrypted servers.

bool BearWare.TeamTalk4.Disconnect ( )

Disconnect from the server.

This will clear the flag ClientFlag CLIENT_CONNECTED and ClientFlag CLIENT_CONNECTING.

bool BearWare.TeamTalk4.QueryMaxPayload ( int  nUserID)

Query the maximum size of UDP data packets to the user or server.

The TeamTalk4.OnMaxPayloadUpdate() event is posted when the query has finished.

Parameters
nUserIDThe ID of the user to query or 0 for querying server. Currently only nUserID = 0 is supported.
bool BearWare.TeamTalk4.SetKeepAliveInterval ( int  nTcpPingIntervalSec,
int  nUdpPingIntervalSec 
)

Set how often the client should ping the server on its TCP and UDP connection.

Ensure that both the TCP or the UDP ping interval is less than the server's user-timeout specified by nUserTimeout in BearWare.ServerProperties. UDP keep-alive packets also updates the ping-time to the server in nUdpPingTimeMs of BearWare.ClientStatistics.

Parameters
nTcpPingIntervalSecSeconds between issuing the ping-command. Passing 0 will make the client instance use default settings.
nUdpPingIntervalSecSeconds between sending UDP keepalive packets to the server (and p2p users). Passing 0 will make the client instance use default settings.
See Also
BearWare.ServerProperties
bool BearWare.TeamTalk4.GetKeepAliveInterval ( out int  lpnTcpPingIntervalSec,
out int  lpnUdpPingIntervalSec 
)

Gets how often the client is sending keep-alive information to the server.

Parameters
lpnTcpPingIntervalSecThe number of seconds between issuing the 'ping' command.
lpnUdpPingIntervalSecThe number of seconds between sending UDP keepalive packets.
See Also
TeamTalk4.SetKeepAliveInterval
bool BearWare.TeamTalk4.SetServerTimeout ( int  nTimeoutSec)

Set server timeout for the client instance.

Set the number of seconds the client should allow the server not to respond to keepalive requests

Parameters
nTimeoutSecSeconds before dropping connection if server hasn't replied. Passing 0 will use default (180 seconds).
int BearWare.TeamTalk4.GetServerTimeout ( )

Get the server timeout for the client instance.

Get the number of seconds the client should allow the server not to respond to keepalive requests

Returns
The number of seconds. On error -1.
bool BearWare.TeamTalk4.EnablePeerToPeer ( TransmitType  mask,
bool  bEnable 
)

Enable/disable peer to peer data transmission.

Peer to peer data transmission will reduce data transmission time, since packets will not be forwarded through the server. This, however, increases the bandwidth usage for clients since a separate data packet will be sent to each user in a channel, instead of just sending a single packet to the server which would then broadcast the packet.

Note that peer to peer data transmission is very unreliable and will only work with simple NAT-devices. Once a peer to peer connection succeeds or fails the event OnConnectionP2P is posted.

If the client instance is unable to connect with peer to peer to a user it will try and forward the data packet through the server if UserRight USERRIGHT_FORWARD_AUDIO or UserRight USERRIGHT_FORWARD_VIDEO are enabled.

See Also
TeamTalk4.GetServerProperties
BearWare.UserRights
bool BearWare.TeamTalk4.GetStatistics ( out ClientStatistics  lpStats)

Retrieve client statistics of bandwidth usage and response times.

See Also
BearWare.ClientStatistics
int BearWare.TeamTalk4.GetPacketSize ( AudioCodec  lpCodec)

Get the number of bytes in a packet with the specified audio codec.

Note that this is only an estimate which doesn't include headers of underlying protocols.

Parameters
lpCodecThe codec settings to test for packet size
See Also
BearWare.AudioCodec