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.
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.
bool BearWare::TeamTalk4.Disconnect ()
 Disconnect from the server.
bool BearWare::TeamTalk4.QueryMaxPayload (int nUserID)
 Query the maximum size of UDP data packets to the user or server.
bool BearWare::TeamTalk4.SetKeepAliveInterval (int nTcpPingIntervalSec, int nUdpPingIntervalSec)
 Set how often the client should ping the server on its TCP and UDP connection.
bool BearWare::TeamTalk4.GetKeepAliveInterval (out int lpnTcpPingIntervalSec, out int lpnUdpPingIntervalSec)
 Gets how often the client is sending keep-alive information to the server.
bool BearWare::TeamTalk4.SetServerTimeout (int nTimeoutSec)
 Set server timeout for the client instance.
int BearWare::TeamTalk4.GetServerTimeout ()
 Get the server timeout for the client instance.
bool BearWare::TeamTalk4.EnablePeerToPeer (TransmitType mask, bool bEnable)
 Enable/disable peer to peer data transmission.
bool BearWare::TeamTalk4.GetStatistics (out ClientStatistics lpStats)
 Retrieve client statistics of bandwidth usage and response times.
int BearWare::TeamTalk4.GetPacketSize (AudioCodec lpCodec)
 Get the number of bytes in a packet with the specified audio codec.

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 
) [inherited]

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:
szHostAddress The IP-address or hostname of the server.
nTcpPort The host port of the server (TCP).
nUdpPort The audio/video port of the server (UDP).
nLocalTcpPort The local TCP port which should be used. Setting it to 0 makes OS select a port number (recommended).
nLocalUdpPort The 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 
) [inherited]

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:
szHostAddress The IP-address or hostname of the server.
nTcpPort The host port of the server (TCP).
nUdpPort The audio/video port of the server (UDP).
szBindIPAddr The IP-address to bind to on the local interface in dotted decimal format, e.g. 192.168.1.10.
nLocalTcpPort The local TCP port which should be used. Setting it to 0 makes OS select a port number (recommended).
nLocalUdpPort The local UDP port which should be used. Setting it to 0 makes OS select a port number (recommended).
See also:
Connect
bool BearWare.TeamTalk4.Disconnect (  )  [inherited]

Disconnect from the server.

This will clear the flag ClientFlag.CLIENT_CONNECTED and ClientFlag.CLIENT_CONNECTING.

bool BearWare.TeamTalk4.QueryMaxPayload ( int  nUserID  )  [inherited]

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:
nUserID The 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 
) [inherited]

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:
nTcpPingIntervalSec Seconds between issuing the ping-command. Passing 0 will make the client instance use default settings.
nUdpPingIntervalSec Seconds 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 
) [inherited]

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

Parameters:
lpnTcpPingIntervalSec The number of seconds between issuing the 'ping' command.
lpnUdpPingIntervalSec The number of seconds between sending UDP keepalive packets.
See also:
TeamTalk4.SetKeepAliveInterval
bool BearWare.TeamTalk4.SetServerTimeout ( int  nTimeoutSec  )  [inherited]

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:
nTimeoutSec Seconds before dropping connection if server hasn't replied. Passing 0 will use default (180 seconds).
int BearWare.TeamTalk4.GetServerTimeout (  )  [inherited]

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 
) [inherited]

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  )  [inherited]

Retrieve client statistics of bandwidth usage and response times.

See also:
BearWare.ClientStatistics
int BearWare.TeamTalk4.GetPacketSize ( AudioCodec  lpCodec  )  [inherited]

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:
lpCodec The codec settings to test for packet size
See also:
BearWare.AudioCodec
Generated on Sun Mar 18 17:16:14 2012 for TeamTalk 4 .NET DLL by  doxygen 1.6.3