TeamTalk 4 C-API DLL  Version 4.5A
Client Initialization

The first thing a user application must to is call TT_InitTeamTalk which will return a TTInstance-pointer which is a new client instance. More...

Typedefs

typedef VOID TTInstance
 Pointer to a TeamTalk client instance created by TT_InitTeamTalk. More...
 
typedef enum ClientFlag ClientFlag
 Flags used to describe the the client instance current state. More...
 
typedef UINT32 ClientFlags
 A bitmask based on ClientFlag describing the local client instance's current state. More...
 

Enumerations

enum  ClientFlag {
  CLIENT_CLOSED = 0x00000000, CLIENT_SNDINPUT_READY = 0x00000001, CLIENT_SNDOUTPUT_READY = 0x00000002, CLIENT_VIDEO_READY = 0x00000004,
  CLIENT_DESKTOP_ACTIVE = 0x00000008, CLIENT_SNDINPUT_VOICEACTIVATED = 0x00000010, CLIENT_SNDINPUT_DENOISING = 0x00000020, CLIENT_SNDINPUT_AGC = 0x00000040,
  CLIENT_SNDOUTPUT_MUTE = 0x00000080, CLIENT_SNDOUTPUT_AUTO3DPOSITION = 0x00000100, CLIENT_SNDINPUT_AEC = 0x00000200, CLIENT_SNDINOUTPUT_DUPLEX = 0x00000400,
  CLIENT_TX_AUDIO = 0x00001000, CLIENT_TX_VIDEO = 0x00002000, CLIENT_MUX_AUDIOFILE = 0x00004000, CLIENT_TX_DESKTOP = 0x00008000,
  CLIENT_CONNECTING = 0x00010000, CLIENT_CONNECTED = 0x00020000, CLIENT_CONNECTION = CLIENT_CONNECTING | CLIENT_CONNECTED, CLIENT_AUTHORIZED = 0x00040000,
  CLIENT_P2P_AUDIO = 0x00100000, CLIENT_P2P_VIDEO = 0x00200000, CLIENT_P2P = CLIENT_P2P_AUDIO | CLIENT_P2P_VIDEO, CLIENT_STREAM_AUDIO = 0x00400000,
  CLIENT_STREAM_VIDEO = 0x00800000
}
 Flags used to describe the the client instance current state. More...
 

Functions

TEAMTALKDLL_API const TTCHARTT_GetVersion ()
 Get the DLL's version number. More...
 
TEAMTALKDLL_API TTInstanceTT_InitTeamTalk (IN HWND hWnd)
 Create a new TeamTalk client instance where events are posted to a HWND. More...
 
TEAMTALKDLL_API BOOL TT_SwapTeamTalkHWND (IN TTInstance *lpTTInstance, IN HWND hWnd)
 Replace the HWND passed as parameter to TT_InitTeamTalk with this HWND. More...
 
TEAMTALKDLL_API TTInstanceTT_InitTeamTalkPoll ()
 Create a new TeamTalk client instance where events are 'polled' using TT_GetMessage. More...
 
TEAMTALKDLL_API BOOL TT_CloseTeamTalk (IN TTInstance *lpTTInstance)
 Close the TeamTalk client instance and release its resources. More...
 
TEAMTALKDLL_API BOOL TT_GetMessage (IN TTInstance *lpTTInstance, OUT TTMessage *pMsg, IN const INT32 *pnWaitMs)
 Poll for events in the client instance. More...
 
TEAMTALKDLL_API ClientFlags TT_GetFlags (IN TTInstance *lpTTInstance)
 Get a bitmask describing the client's current state. More...
 
TEAMTALKDLL_API BOOL TT_SetLicenseInformation (IN const TTCHAR szRegName[TT_STRLEN], IN INT64 nRegKey)
 Set license information to disable trial mode. More...
 

Detailed Description

The first thing a user application must to is call TT_InitTeamTalk which will return a TTInstance-pointer which is a new client instance.

TT_InitTeamTalk takes as parameter a HWND which will have messages posted whenever an event in the client instance takes place. These are the events defined in ClientEvent. If the end-user application is console-based the function TT_InitTeamTalkPoll can be used where events are processed using TT_GetMessage.

When a new client instance is created a call to TT_GetFlags will show that the client initially is in state CLIENT_CLOSED. This means that no operation has been performed on the client.

Querying TT_GetFlags call can be used by a user application as a state-machine to show which actions are currently possible for the user application. The ClientFlag enumeration shows the information which can be retrived though TT_GetFlags.

Typedef Documentation

typedef VOID TTInstance

Pointer to a TeamTalk client instance created by TT_InitTeamTalk.

See Also
TT_CloseTeamTalk
typedef enum ClientFlag ClientFlag

Flags used to describe the the client instance current state.

The client's state is a bitmask of the flags in ClientFlag.

The state of the client instance can be retrieved by calling TT_GetFlags. This enables the user application to display the possible options to the end user. If e.g. the flag CLIENT_AUTHORIZED is not set it will not be possible to perform any other commands except TT_DoLogin. Doing so will make the server return an error message to the client.

typedef UINT32 ClientFlags

A bitmask based on ClientFlag describing the local client instance's current state.

Enumeration Type Documentation

enum ClientFlag

Flags used to describe the the client instance current state.

The client's state is a bitmask of the flags in ClientFlag.

The state of the client instance can be retrieved by calling TT_GetFlags. This enables the user application to display the possible options to the end user. If e.g. the flag CLIENT_AUTHORIZED is not set it will not be possible to perform any other commands except TT_DoLogin. Doing so will make the server return an error message to the client.

Enumerator
CLIENT_CLOSED 

The client instance (TTInstance) is in closed state, i.e. TT_InitTeamTalk has return a valid instance ready for use but no operations has been performed on it.

CLIENT_SNDINPUT_READY 

If set the client instance's sound input device has been initialized, i.e. TT_InitSoundInputDevice has been called successfully.

CLIENT_SNDOUTPUT_READY 

If set the client instance's sound output device has been initialized, i.e. TT_InitSoundOutputDevice has been called successfully.

CLIENT_VIDEO_READY 

If set the client instance's video device has been initialized, i.e. TT_InitVideoCaptureDevice has been called successfuly.

CLIENT_DESKTOP_ACTIVE 

If set the client instance current have an active desktop session, i.e. TT_SendDesktopWindow() has been called. Call TT_CloseDesktopWindow() to close the desktop session.

CLIENT_SNDINPUT_VOICEACTIVATED 

If set the client instance will start transmitting audio if the sound level is above the voice activation level. The event WM_TEAMTALK_VOICE_ACTIVATION is posted when voice activation initiates transmission.

See Also
TT_SetVoiceActivationLevel
TT_EnableVoiceActivation
CLIENT_SNDINPUT_DENOISING 

If set the client instance will try to remove noise from recorded audio.

See Also
TT_EnableDenoising
CLIENT_SNDINPUT_AGC 

If set the client instance is using automatic gain control.

See Also
TT_EnableAGC
CLIENT_SNDOUTPUT_MUTE 

If set the client instance has muted all users.

See Also
TT_SetSoundOutputMute
CLIENT_SNDOUTPUT_AUTO3DPOSITION 

If set the client instance will auto position users in a 180 degree circle using 3D-sound. This option is only available with SOUNDSYSTEM_DSOUND.

See Also
TT_SetUserPosition
TT_Enable3DSoundPositioning
CLIENT_SNDINPUT_AEC 

If set the client instance will try to eliminate echo from speakers. To enable echo cancellation first make the client run on sound duplex mode by calling TT_InitSoundDuplexDevices() and afterwards call TT_EnableEchoCancellation().

CLIENT_SNDINOUTPUT_DUPLEX 

If set the client instance is running in sound duplex mode where multiple audio output streams are mixed into a single stream. This option must be enabled to support echo cancellation (CLIENT_SNDINPUT_AEC). Call TT_InitSoundDuplexDevices() to enable duplex mode.

CLIENT_TX_AUDIO 

If set the client instance is currently transmitting audio.

See Also
TT_EnableTransmission
CLIENT_TX_VIDEO 

If set the client instance is currently transmitting video.

See Also
TT_EnableTransmission
CLIENT_MUX_AUDIOFILE 

If set the client instance is currently muxing audio streams into a single file. This is enabled by calling TT_StartRecordingMuxedAudioFile().

CLIENT_TX_DESKTOP 

If set the client instance is currently transmitting a desktop window. A desktop window update is issued by calling TT_SendDesktopWindow(). The event WM_TEAMTALK_DESKTOPWINDOW_TRANSFER is triggered when a desktop window transmission completes.

CLIENT_CONNECTING 

If set the client instance is currently try to connect to a server, i.e. TT_Connect has been called.

CLIENT_CONNECTED 

If set the client instance is connected to a server, i.e. WM_TEAMTALK_CON_SUCCESS event has been issued after doing a TT_Connect. Valid commands in this state: TT_DoLogin.

CLIENT_CONNECTION 

Helper for CLIENT_CONNECTING and CLIENT_CONNECTED to see if TT_Disconnect should be called.

CLIENT_AUTHORIZED 

If set the client instance is logged on to a server, i.e. got WM_TEAMTALK_CMD_MYSELF_LOGGEDIN event after issueing TT_DoLogin.

CLIENT_P2P_AUDIO 

If set the client instance will try and connect to other users using peer to peer connections. Audio will be broadcast to users instead of forwarded through server (thereby increasing the bandwith usage). Note that if USERRIGHT_FORWARD_AUDIO is disabled and no peer to peer connection could be established, i.e. event WM_TEAMTALK_CON_P2P was posted with failure, then data cannot be transferred to a user.

CLIENT_P2P_VIDEO 

If set the client instance will try and connect to other users using peer to peer connections. Video will be broadcast to users instead of forwarded through server (thereby increasing the bandwith usage). Note that if USERRIGHT_FORWARD_VIDEO is disabled and no peer to peer connection could be established, i.e. event WM_TEAMTALK_CON_P2P was posted with failure, then data cannot be transferred to a user.

CLIENT_P2P 

Helper for CLIENT_P2P_AUDIO and CLIENT_P2P_VIDEO to see if the client instance is currently attempting P2P connections.

CLIENT_STREAM_AUDIO 

If set the client is currently streaming the audio of a media file. When streaming a video file the CLIENT_STREAM_VIDEO flag is also typically set.

See Also
TT_StartStreamingMediaFileToChannel()
CLIENT_STREAM_VIDEO 

If set the client is currently streaming the video of a media file. When streaming a video file the CLIENT_STREAM_AUDIO flag is also typically set.

See Also
TT_StartStreamingMediaFileToChannel()

Function Documentation

TEAMTALKDLL_API const TTCHAR* TT_GetVersion ( )

Get the DLL's version number.

TEAMTALKDLL_API TTInstance* TT_InitTeamTalk ( IN HWND  hWnd)

Create a new TeamTalk client instance where events are posted to a HWND.

This function must be invoked before any other of the TT_* functions can be called. Call TT_CloseTeamTalk to shutdown the TeamTalk client and release its resources.

Parameters
hWndThe window handle which will receive the events defined in ClientEvent.
Returns
A pointer to a new client instance. NULL if a failure occured.
See Also
TT_CloseTeamTalk
TEAMTALKDLL_API BOOL TT_SwapTeamTalkHWND ( IN TTInstance lpTTInstance,
IN HWND  hWnd 
)

Replace the HWND passed as parameter to TT_InitTeamTalk with this HWND.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
hWndThe new HWND which should receive event messages.
TEAMTALKDLL_API TTInstance* TT_InitTeamTalkPoll ( )

Create a new TeamTalk client instance where events are 'polled' using TT_GetMessage.

This 'polled' method can be used by application which doesn't have a HWND, e.g. console applications.

This function must be invoked before any other of the TT_* functions can be called. Call TT_CloseTeamTalk to shutdown the TeamTalk client and release its resources.

Returns
A pointer to a new client instance. NULL if a failure occured.
See Also
TT_CloseTeamTalk
TEAMTALKDLL_API BOOL TT_CloseTeamTalk ( IN TTInstance lpTTInstance)

Close the TeamTalk client instance and release its resources.

It is adviced to call this before closing the main application to ensure a proper shutdown.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
See Also
TT_InitTeamTalk
TEAMTALKDLL_API BOOL TT_GetMessage ( IN TTInstance lpTTInstance,
OUT TTMessage pMsg,
IN const INT32 *  pnWaitMs 
)

Poll for events in the client instance.

On Windows a each client instance can send its events to a HWND but events can also be polled using a timer using TT_GetMessage.

Parameters
lpTTInstancePointer to client instance created by
pMsgPointer to a TTMessage instance which will hold the events that has occured.
pnWaitMsThe amount of time to wait for the event. If NULL or -1 the function will block forever or until the next event occurs.
Returns
Returns TRUE if an event has occured otherwise FALSE.
See Also
TT_InitTeamTalkPolled
ClientEvent
TEAMTALKDLL_API ClientFlags TT_GetFlags ( IN TTInstance lpTTInstance)

Get a bitmask describing the client's current state.

Checks whether the client is connecting, connected, authorized, etc. The current state can be checked by and'ing the returned bitmask which is based on ClientFlag.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
Returns
A bitmask describing the current state (based on ClientFlag).
See Also
ClientFlag
TEAMTALKDLL_API BOOL TT_SetLicenseInformation ( IN const TTCHAR  szRegName[TT_STRLEN],
IN INT64  nRegKey 
)

Set license information to disable trial mode.

This function must be called before TT_InitTeamTalk.

Parameters
szRegNameThe registration name provided by BearWare.dk.
nRegKeyThe registration key provided by BearWare.dk.
Returns
True if the provided registration is acceptable.