TeamTalk 4 C-API DLL
Version 4.5A
|
The following sections gives a step-by-step tour of building a user application which uses the TeamTalk 4 C-API DLL to transmit audio and video. In order for the user application to interact with other clients a TeamTalk server must first be set up. Section Server Setup Guide explains how to do this.
The job of the TeamTalk server is to keep track of connected users and provide user autentication. Once a client is connected and has been authenticated the client is presented with a tree structure where each node is a so-called channel which the client can join and from there interact with the other users who are in the same channel.
The following six steps explains how to build a TeamTalk client:
A new client instance is created by calling TT_InitTeamTalk which will return a TTInstance pointer to the new client instance. On Windows the window handle (HWND) of the user application must be provided as parameter to the function. This HWND will receive the client events described in section Client Event Handling. When the user application quits ensure to call TT_CloseTeamTalk so the client instance can close down properly.
Once a new client instance has been created its current state can always be retrieved by calling the function TT_GetFlags which will return a bitmask describing the client's current state. Initially after creating the client instance a call to TT_GetFlags will return a bitmask with the value CLIENT_CLOSED since no operations have been performed on the client.
Before connecting to a server it is a good idea to setup the user's sound and video devices. Sound devices are initialized using the TT_InitSoundInputDevice and TT_InitSoundOutputDevice functions. The video capture device is initialized using TT_InitVideoCaptureDevice. Initializing the video capture device can be quite tricky because there's many properties which needs to be configured. Look at the SDK sample applications to get an idea of how it's done.
Once sound and video devices has been initialized the function TT_GetFlags will return a mask containing CLIENT_SNDINPUT_READY, CLIENT_SNDOUTPUT_READY and CLIENT_VIDEO_READY.
By calling TT_Connect will make the client connect to the server running on the IP-address and port numbers specified as parameters to the function. After this call the TT_GetFlags function will have the CLIENT_CONNECTING bit set.
If the TT_Connect call fails the WM_TEAMTALK_CON_FAILED event will be posted to the HWND and the CLIENT_CONNECTING bit will be cleared.
If the TT_Connect is successful the WM_TEAMTALK_CON_SUCCESS event will be posted to the HWND of the user application and the CLIENT_CONNECTED bit will be set and CLIENT_CONNECTING will be cleared.
Once connected the user application can call TT_DoLogin to log on to the server. All functions with the prefix TT_Do* are client to server commands (see Client/Server Commands). The TT_DoLogin requires that the user application provides a server password, account username and account password. A server may allow anonymous users (see USERRIGHT_GUEST_LOGIN) to log on in which case the account username and password can be left blank.
If the server rejects the login the WM_TEAMTALK_CMD_ERROR event is posted along with an error code (see ClientError).
If the server accepts the login information the WM_TEAMTALK_CMD_MYSELF_LOGGEDIN event is posted to the HWND and the the client instance will have the CLIENT_AUTHORIZED flag set.
For every channel on the server a WM_TEAMTALK_CMD_CHANNEL_NEW event will be posted and a WM_TEAMTALK_CMD_USER_LOGGEDIN will be posted for every user. The WM_TEAMTALK_CMD_USER_JOINED event tells if the specified user in the event is in a channel.
Now that the client is connected and authorized it is possible to join a channel on the server. This is done by either calling the function TT_DoJoinChannel to create a new channel or by calling TT_DoJoinChannelByID to join an existing channel.
If using the TT_DoJoinChannelByID command to join a channel the ID of the channel must be retrieved and also the password needed to join the channel. The ID of a channel is posted in the WM_TEAMTALK_CMD_CHANNEL_NEW event and the password must be known by the user.
If the call to TT_DoJoinChannelByID is successful the event WM_TEAMTALK_CMD_MYSELF_JOINED is posted and if the server rejected the command to join the WM_TEAMTALK_CMD_ERROR event is posted.
Having joined a channel now enables the client instance to start transmitting audio and video to the other users in the channel by calling TT_EnableTransmission.
When the other users in the channel starts receiving audio they will receive the WM_TEAMTALK_USER_TALKING event. If video is also being transmitted the event WM_TEAMTALK_USER_VIDEOFRAME will be posted for every video frame which is received.