TeamTalk 4 C-API 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 TT_Do*-functions, are sent on TCP whereas audio and video are sent on UDP. More...

Classes

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

Typedefs

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

Functions

TEAMTALKDLL_API BOOL TT_Connect (IN TTInstance *lpTTInstance, IN const TTCHAR *szHostAddress, IN INT32 nTcpPort, IN INT32 nUdpPort, IN INT32 nLocalTcpPort, IN INT32 nLocalUdpPort)
 Connect to a server. More...
 
TEAMTALKDLL_API BOOL TT_ConnectEx (IN TTInstance *lpTTInstance, IN const TTCHAR *szHostAddress, IN INT32 nTcpPort, IN INT32 nUdpPort, IN const TTCHAR *szBindIPAddr, IN INT32 nLocalTcpPort, IN INT32 nLocalUdpPort)
 Bind to specific IP-address priot to connecting to server. More...
 
TEAMTALKDLL_API BOOL TT_ConnectNonEncrypted (IN TTInstance *lpTTInstance, IN const TTCHAR *szHostAddress, IN INT32 nTcpPort, IN INT32 nUdpPort, IN const TTCHAR *szBindIPAddr, IN INT32 nLocalTcpPort, IN INT32 nLocalUdpPort)
 Connect to non-encrypted TeamTalk server. More...
 
TEAMTALKDLL_API BOOL TT_Disconnect (IN TTInstance *lpTTInstance)
 Disconnect from the server. More...
 
TEAMTALKDLL_API BOOL TT_QueryMaxPayload (IN TTInstance *lpTTInstance, IN INT32 nUserID)
 Query the maximum size of UDP data packets to the user or server. More...
 
TEAMTALKDLL_API BOOL TT_SetKeepAliveInterval (IN TTInstance *lpTTInstance, IN INT32 nTcpPingIntervalSec, IN INT32 nUdpPingIntervalSec)
 Set how often the client should ping the server on its TCP and UDP connection. More...
 
TEAMTALKDLL_API BOOL TT_GetKeepAliveInterval (IN TTInstance *lpTTInstance, OUT INT32 *lpnTcpPingIntervalSec, OUT INT32 *lpnUdpPingIntervalSec)
 Gets how often the client is sending keep-alive information to the server. More...
 
TEAMTALKDLL_API BOOL TT_SetServerTimeout (IN TTInstance *lpTTInstance, IN INT32 nTimeoutSec)
 Set server timeout for the client instance. More...
 
TEAMTALKDLL_API INT32 TT_GetServerTimeout (IN TTInstance *lpTTInstance)
 Get the server timeout for the client instance. More...
 
TEAMTALKDLL_API BOOL TT_EnablePeerToPeer (IN TTInstance *lpTTInstance, IN TransmitTypes mask, IN BOOL bEnable)
 Enable/disable peer to peer data transmission. More...
 
TEAMTALKDLL_API BOOL TT_GetStatistics (IN TTInstance *lpTTInstance, OUT ClientStatistics *lpStats)
 Retrieve client statistics of bandwidth usage and response times. More...
 
TEAMTALKDLL_API INT32 TT_GetPacketSize (IN const 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 TT_Do*-functions, are sent on TCP whereas audio and video are sent on UDP.

To connect to a server the user application must call TT_Connect. Once connected the event WM_TEAMTALK_CON_SUCCESS is posted to the user application and the TT_DoLogin command can be issued. Always ensure to call TT_Disconnect before attempting to create a new connection with TT_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 ServerProperties must disable USERRIGHT_FORWARD_AUDIO and 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 TT_EnablePeerToPeer.

Peer to Peer Transmission Mode

By calling TT_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 WM_TEAMTALK_CON_P2P 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_FORWARD_AUDIO or 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.

Typedef Documentation

Statistics of bandwidth usage and ping times in the local client instance.

See Also
TT_GetStatistics

Function Documentation

TEAMTALKDLL_API BOOL TT_Connect ( IN TTInstance lpTTInstance,
IN const TTCHAR szHostAddress,
IN INT32  nTcpPort,
IN INT32  nUdpPort,
IN INT32  nLocalTcpPort,
IN INT32  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 WM_TEAMTALK_CON_SUCCESS to be posted once the connection has been established or WM_TEAMTALK_CON_FAILED if connection could not be established. If the connection could not be establish ensure to call TT_Disconnect to close open connections in the client instance before trying again.

Once connected call TT_DoLogin to log on to the server.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
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
WM_TEAMTALK_CON_SUCCESS
WM_TEAMTALK_CON_FAILED
TT_DoLogin
TEAMTALKDLL_API BOOL TT_ConnectEx ( IN TTInstance lpTTInstance,
IN const TTCHAR szHostAddress,
IN INT32  nTcpPort,
IN INT32  nUdpPort,
IN const TTCHAR szBindIPAddr,
IN INT32  nLocalTcpPort,
IN INT32  nLocalUdpPort 
)

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

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

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
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
TT_Connect
TEAMTALKDLL_API BOOL TT_ConnectNonEncrypted ( IN TTInstance lpTTInstance,
IN const TTCHAR szHostAddress,
IN INT32  nTcpPort,
IN INT32  nUdpPort,
IN const TTCHAR szBindIPAddr,
IN INT32  nLocalTcpPort,
IN INT32  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 TT_Connect() and TT_ConnectEx() in the Professional SDK is to connect to encrypted servers.

TEAMTALKDLL_API BOOL TT_Disconnect ( IN TTInstance lpTTInstance)

Disconnect from the server.

This will clear the flag CLIENT_CONNECTED and CLIENT_CONNECTING.

Use TT_CloseTeamTalk to release all resources allocated by the client instance.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
TEAMTALKDLL_API BOOL TT_QueryMaxPayload ( IN TTInstance lpTTInstance,
IN INT32  nUserID 
)

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

The WM_TEAMTALK_CON_MAX_PAYLOAD_UPDATED event is posted when the query has finished.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe ID of the user to query or 0 for querying server. Currently only nUserID = 0 is supported.
TEAMTALKDLL_API BOOL TT_SetKeepAliveInterval ( IN TTInstance lpTTInstance,
IN INT32  nTcpPingIntervalSec,
IN INT32  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 ServerProperties. UDP keep-alive packets also updates the ping-time to the server in nUdpPingTimeMs of ClientStatistics.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
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
ServerProperties
TEAMTALKDLL_API BOOL TT_GetKeepAliveInterval ( IN TTInstance lpTTInstance,
OUT INT32 *  lpnTcpPingIntervalSec,
OUT INT32 *  lpnUdpPingIntervalSec 
)

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

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpnTcpPingIntervalSecThe number of seconds between issuing the 'ping' command.
lpnUdpPingIntervalSecThe number of seconds between sending UDP keepalive packets.
See Also
TT_SetKeepAliveInterval
TEAMTALKDLL_API BOOL TT_SetServerTimeout ( IN TTInstance lpTTInstance,
IN INT32  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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nTimeoutSecSeconds before dropping connection if server hasn't replied. Passing 0 will use default (180 seconds).
TEAMTALKDLL_API INT32 TT_GetServerTimeout ( IN TTInstance lpTTInstance)

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

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
Returns
The number of seconds. On error -1.
TEAMTALKDLL_API BOOL TT_EnablePeerToPeer ( IN TTInstance lpTTInstance,
IN TransmitTypes  mask,
IN 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 WM_TEAMTALK_CON_P2P 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_FORWARD_AUDIO or USERRIGHT_FORWARD_VIDEO are enabled.

See Also
TT_GetServerProperties
UserRights
TEAMTALKDLL_API BOOL TT_GetStatistics ( IN TTInstance lpTTInstance,
OUT ClientStatistics lpStats 
)

Retrieve client statistics of bandwidth usage and response times.

See Also
ClientStatistics
TEAMTALKDLL_API INT32 TT_GetPacketSize ( IN const 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
AudioCodec