TeamTalk 5 C-API DLL Version 5.19A

Classes | Typedefs | Functions
Client/Server Connectivity

This section explains how to connect to a server and how the client should transmit voice and video data. More...

## Classes

struct | EncryptionContext
| Configure peer verification for encrypted connection. More...
struct | ClientKeepAlive
| Control timers for sending keep alive information to the server. More...
struct | ClientStatistics
| Statistics of bandwidth usage and ping times in the local client instance. More...
struct | JitterConfig
| Configuration parameters for the Jitter Buffer. More...

## Typedefs

typedef struct EncryptionContext | EncryptionContext
| Configure peer verification for encrypted connection. More...
typedef struct ClientKeepAlive | ClientKeepAlive
| Control timers for sending keep alive information to the server. More...
typedef struct ClientStatistics | ClientStatistics
| Statistics of bandwidth usage and ping times in the local client instance. More...
typedef struct JitterConfig | JitterConfig
| Configuration parameters for the Jitter Buffer. More...

## Functions

TEAMTALKDLL_API TTBOOL | TT_SetEncryptionContext (IN TTInstance *lpTTInstance, const EncryptionContext *lpEncryptionContext)
| Setup encryption properties prior to TT_Connect(). More...
TEAMTALKDLL_API TTBOOL | TT_Connect (IN TTInstance *lpTTInstance, IN const TTCHAR *szHostAddress, IN INT32 nTcpPort, IN INT32 nUdpPort, IN INT32 nLocalTcpPort, IN INT32 nLocalUdpPort, IN TTBOOL bEncrypted)
| Connect to a server. More...
TEAMTALKDLL_API TTBOOL | TT_ConnectSysID (IN TTInstance *lpTTInstance, IN const TTCHAR *szHostAddress, IN INT32 nTcpPort, IN INT32 nUdpPort, IN INT32 nLocalTcpPort, IN INT32 nLocalUdpPort, IN TTBOOL bEncrypted, IN const TTCHAR *szSystemID)
| Same as TT_Connect() but the option of providing a unique system-ID. More...
TEAMTALKDLL_API TTBOOL | 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, IN TTBOOL bEncrypted)
| Bind to specific IP-address prior to connecting to server. More...
TEAMTALKDLL_API TTBOOL | TT_Disconnect (IN TTInstance *lpTTInstance)
| Disconnect from the server. More...
TEAMTALKDLL_API TTBOOL | TT_QueryMaxPayload (IN TTInstance *lpTTInstance, IN INT32 nUserID)
| Query the maximum size of UDP data packets to the user or server. More...
TEAMTALKDLL_API TTBOOL | TT_GetClientStatistics (IN TTInstance *lpTTInstance, OUT ClientStatistics *lpClientStatistics)
| Retrieve client statistics of bandwidth usage and response times. More...
TEAMTALKDLL_API TTBOOL | TT_SetClientKeepAlive (IN TTInstance *lpTTInstance, IN const ClientKeepAlive *lpClientKeepAlive)
| Update the client instance's default keep alive settings. More...
TEAMTALKDLL_API TTBOOL | TT_GetClientKeepAlive (IN TTInstance *lpTTInstance, OUT ClientKeepAlive *lpClientKeepAlive)
| Get the client instance's current keep alive settings. More...

## Detailed Description

This section explains how to connect to a server and how the client should transmit voice and video data.

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 CLIENTEVENT_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 by calling TT_EnableTransmission().

# Forward Through Server Transmission Mode

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 users nowadays have limited upstream they cannot broadcast audio and video packets to numerous users at the same time, so therefore the TeamTalk client makes 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 UserAccount must disable USERRIGHT_TRANSMIT_VOICE and USERRIGHT_TRANSMIT_VIDEOCAPTURE.

## Typedef Documentation

## ◆ EncryptionContext

typedef struct EncryptionContext EncryptionContext

Configure peer verification for encrypted connection.

Client and server can verify that the remote end is using a valid cerficate that has been issued by the same certification authority.

Call TT_SetEncryptionContext() to set up peer verification.

## ◆ ClientKeepAlive

typedef struct ClientKeepAlive ClientKeepAlive

Control timers for sending keep alive information to the server.

See also
  TT_DoPing()

## ◆ ClientStatistics

typedef struct ClientStatistics ClientStatistics

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

See also
  TT_GetClientStatistics

## ◆ JitterConfig

typedef struct JitterConfig JitterConfig

Configuration parameters for the Jitter Buffer.

See also
  TT_SetUserJitterControl()

## Function Documentation

## ◆ TT_SetEncryptionContext()

TEAMTALKDLL_API TTBOOL TT_SetEncryptionContext | ( | IN TTInstance * | lpTTInstance,
|  | const EncryptionContext * | lpEncryptionContext
| ) |  |

Setup encryption properties prior to TT_Connect().

If the server does peer verification then client must specify certificate file and private key file.

Do not set encryption context unless server requires clients to do so.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpEncryptionContext | Encryption properties for peer verification.

## ◆ TT_Connect()

TEAMTALKDLL_API TTBOOL TT_Connect | ( | IN TTInstance * | lpTTInstance,
|  | IN const TTCHAR * | szHostAddress,
|  | IN INT32 | nTcpPort,
|  | IN INT32 | nUdpPort,
|  | IN INT32 | nLocalTcpPort,
|  | IN INT32 | nLocalUdpPort,
|  | IN TTBOOL | bEncrypted
| ) |  |

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 CLIENTEVENT_CON_SUCCESS to be posted once the connection has been established or CLIENTEVENT_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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  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).
  bEncrypted | Whether the server requires an encrypted connection. As of TeamTalk v5.5 and onwards encryption is available in both TeamTalk SDK Standard and Professional Edition.

Returns
  Returns TRUE if connection process was initiated.

See also
  CLIENTEVENT_CON_SUCCESS
  CLIENTEVENT_CON_FAILED
  TT_DoLogin

## ◆ TT_ConnectSysID()

TEAMTALKDLL_API TTBOOL TT_ConnectSysID | ( | IN TTInstance * | lpTTInstance,
|  | IN const TTCHAR * | szHostAddress,
|  | IN INT32 | nTcpPort,
|  | IN INT32 | nUdpPort,
|  | IN INT32 | nLocalTcpPort,
|  | IN INT32 | nLocalUdpPort,
|  | IN TTBOOL | bEncrypted,
|  | IN const TTCHAR * | szSystemID
| ) |  |

Same as TT_Connect() but the option of providing a unique system-ID.

The system-ID is set in the TeamTalk server API using TTS_StartServerSysID(). If a client tries to connect with a different system-ID that client will receive the error CMDERR_INCOMPATIBLE_PROTOCOLS when trying to log in.

Requires TeamTalk version 5.1.3.4506.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  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).
  bEncrypted | Whether the server requires an encrypted connection. As of TeamTalk v5.5 and onwards encryption is available in both TeamTalk SDK Standard and Professional Edition.
  szSystemID | The identification of the conferencing system. The default value is "teamtalk". See TTS_StartServerSysID()

Returns
  Returns TRUE if connection process was initiated.

## ◆ TT_ConnectEx()

TEAMTALKDLL_API TTBOOL 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,
|  | IN TTBOOL | bEncrypted
| ) |  |

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

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

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  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).
  bEncrypted | Whether the server requires an encrypted connection. As of TeamTalk v5.5 and onwards encryption is available in both TeamTalk SDK Standard and Professional Edition.

See also
  TT_Connect

## ◆ TT_Disconnect()

TEAMTALKDLL_API TTBOOL 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

## ◆ TT_QueryMaxPayload()

TEAMTALKDLL_API TTBOOL TT_QueryMaxPayload | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID
| ) |  |

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

The CLIENTEVENT_CON_MAX_PAYLOAD_UPDATED event is posted when the query has finished.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the user to query or 0 for querying server. Currently only `nUserID` = 0 is supported.

## ◆ TT_GetClientStatistics()

TEAMTALKDLL_API TTBOOL TT_GetClientStatistics | ( | IN TTInstance * | lpTTInstance,
|  | OUT ClientStatistics * | lpClientStatistics
| ) |  |

Retrieve client statistics of bandwidth usage and response times.

See also
  ClientStatistics

## ◆ TT_SetClientKeepAlive()

TEAMTALKDLL_API TTBOOL TT_SetClientKeepAlive | ( | IN TTInstance * | lpTTInstance,
|  | IN const ClientKeepAlive * | lpClientKeepAlive
| ) |  |

Update the client instance's default keep alive settings.

It is generally discouraged to change the client instance's keep alive settings unless the network has special requirements.

After calling TT_SetClientKeepAlive() it is recommended doing a TT_DoPing() since all TCP and UDP keep alive timers will be restarted.

See also
  TT_DoPing()
  TT_GetClientKeepAlive()
  TT_GetClientStatistics()

## ◆ TT_GetClientKeepAlive()

TEAMTALKDLL_API TTBOOL TT_GetClientKeepAlive | ( | IN TTInstance * | lpTTInstance,
|  | OUT ClientKeepAlive * | lpClientKeepAlive
| ) |  |

Get the client instance's current keep alive settings.

See also
  TT_DoPing()
  TT_SetClientKeepAlive()
  TT_GetClientStatistics()