TeamTalk 5 C-API DLL  Version 5.14A
Client Initialization

This section explains how to instantiate a new client instance and query its current state. More...

Typedefs

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...
 
typedef VOID TTInstance
 Pointer to a TeamTalk client instance created by TT_InitTeamTalk. More...
 

Enumerations

enum  ClientFlag {
  CLIENT_CLOSED = 0x00000000 , CLIENT_SNDINPUT_READY = 0x00000001 , CLIENT_SNDOUTPUT_READY = 0x00000002 , CLIENT_SNDINOUTPUT_DUPLEX = 0x00000004 ,
  CLIENT_SNDINPUT_VOICEACTIVATED = 0x00000008 , CLIENT_SNDINPUT_VOICEACTIVE = 0x00000010 , CLIENT_SNDOUTPUT_MUTE = 0x00000020 , CLIENT_SNDOUTPUT_AUTO3DPOSITION = 0x00000040 ,
  CLIENT_VIDEOCAPTURE_READY = 0x00000080 , CLIENT_TX_VOICE = 0x00000100 , CLIENT_TX_VIDEOCAPTURE = 0x00000200 , CLIENT_TX_DESKTOP = 0x00000400 ,
  CLIENT_DESKTOP_ACTIVE = 0x00000800 , CLIENT_MUX_AUDIOFILE = 0x00001000 , CLIENT_CONNECTING = 0x00002000 , CLIENT_CONNECTED = 0x00004000 ,
  CLIENT_CONNECTION = CLIENT_CONNECTING | CLIENT_CONNECTED , CLIENT_AUTHORIZED = 0x00008000 , CLIENT_STREAM_AUDIO = 0x00010000 , CLIENT_STREAM_VIDEO = 0x00020000
}
 Flags used to describe the the client instance current state. More...
 

Functions

TEAMTALKDLL_API const TTCHARTT_GetVersion (void)
 Get the DLL's version number. More...
 
TEAMTALKDLL_API TTInstanceTT_InitTeamTalk (IN HWND hWnd, IN UINT32 uMsg)
 Create a new TeamTalk client instance where events are posted to a HWND. More...
 
TEAMTALKDLL_API TTBOOL 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 (void)
 Create a new TeamTalk client instance where events are 'polled' using TT_GetMessage. More...
 
TEAMTALKDLL_API TTBOOL TT_CloseTeamTalk (IN TTInstance *lpTTInstance)
 Close the TeamTalk client instance and release its resources. More...
 
TEAMTALKDLL_API TTBOOL TT_GetMessage (IN TTInstance *lpTTInstance, OUT TTMessage *pMsg, IN const INT32 *pnWaitMs)
 Poll for events in the client instance. More...
 
TEAMTALKDLL_API TTBOOL TT_PumpMessage (IN TTInstance *lpTTInstance, ClientEvent nClientEvent, INT32 nIdentifier)
 Cause client instance event thread to schedule an update event. More...
 
TEAMTALKDLL_API ClientFlags TT_GetFlags (IN TTInstance *lpTTInstance)
 Get a bitmask describing the client's current state. More...
 
TEAMTALKDLL_API TTBOOL TT_SetLicenseInformation (IN const TTCHAR szRegName[TT_STRLEN], IN const TTCHAR szRegKey[TT_STRLEN])
 Set license information to disable trial mode. More...
 

Detailed Description

This section explains how to instantiate a new client instance and query its current state.

TT_InitTeamTalkPoll() will instantiate a new client instance where events are polled using TT_GetMessage(). The events are defined in ClientEvent. On Windows TT_InitTeamTalk() can also be used which takes as parameter a HWND that will have a message posted whenever an event in the client instance takes place.

When a new client instance is created a user application can call to TT_GetFlags to query the client instance's current state. Initially the client instance's state will be CLIENT_CLOSED. This means that no operation has been performed on the client.

Typedef Documentation

◆ ClientFlag

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.

◆ ClientFlags

typedef UINT32 ClientFlags

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

Definition at line 4149 of file TeamTalk.h.

◆ TTInstance

typedef VOID TTInstance

Pointer to a TeamTalk client instance created by TT_InitTeamTalk.

See also
TT_CloseTeamTalk

Definition at line 4155 of file TeamTalk.h.

Enumeration Type Documentation

◆ ClientFlag

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_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 (see TT_SetSoundInputPreprocess()). Call TT_InitSoundDuplexDevices() to enable duplex mode.

CLIENT_SNDINPUT_VOICEACTIVATED 

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

See also
TT_SetVoiceActivationLevel
TT_EnableVoiceActivation
CLIENT_SNDINPUT_VOICEACTIVE 

If set GetSoundInputLevel() is higher than the voice activation level. To enable voice transmission if voice level is higher than actication level also enable CLIENT_SNDINPUT_VOICEACTIVATED.

See also
TT_SetVoiceActivationLevel()
TT_EnableVoiceActivation()
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_VIDEOCAPTURE_READY 

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

CLIENT_TX_VOICE 

If set the client instance is currently transmitting audio.

See also
TT_EnableVoiceTransmission()
CLIENT_TX_VIDEOCAPTURE 

If set the client instance is currently transmitting video.

See also
TT_StartVideoCaptureTransmission()
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 CLIENTEVENT_DESKTOPWINDOW_TRANSFER is triggered when a desktop window transmission completes.

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_MUX_AUDIOFILE 

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

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. CLIENTEVENT_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 CLIENTEVENT_CMD_MYSELF_LOGGEDIN event after issueing TT_DoLogin.

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()

Definition at line 4050 of file TeamTalk.h.

Function Documentation

◆ TT_GetVersion()

TEAMTALKDLL_API const TTCHAR* TT_GetVersion ( void  )

Get the DLL's version number.

◆ TT_InitTeamTalk()

TEAMTALKDLL_API TTInstance* TT_InitTeamTalk ( IN HWND  hWnd,
IN UINT32  uMsg 
)

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.
uMsgThe message ID which will be passed to hWnd when a new event can be retrieved by TT_GetMessage().
Returns
A pointer to a new client instance. NULL if a failure occured.
See also
TT_CloseTeamTalk

◆ TT_SwapTeamTalkHWND()

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

◆ TT_InitTeamTalkPoll()

TEAMTALKDLL_API TTInstance* TT_InitTeamTalkPoll ( void  )

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

◆ TT_CloseTeamTalk()

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

◆ TT_GetMessage()

TEAMTALKDLL_API TTBOOL TT_GetMessage ( IN TTInstance lpTTInstance,
OUT TTMessage pMsg,
IN const INT32 *  pnWaitMs 
)

Poll for events in the client instance.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
pMsgPointer to a TTMessage instance which will hold the event 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

◆ TT_PumpMessage()

TEAMTALKDLL_API TTBOOL TT_PumpMessage ( IN TTInstance lpTTInstance,
ClientEvent  nClientEvent,
INT32  nIdentifier 
)

Cause client instance event thread to schedule an update event.

Normally all events of type TTMessage received from TT_GetMessage() are due to a state change in the client instance. The state change (ClientEvent) is submitted by the client instance's internal thread. In some cases it's, however, convenient to make the internal thread submit the latest properties of an object. One example is after having changed the volume of a User. Then your local copy of User will no longer contain the latest nVolumeVoice.

Calling TT_PumpMessage() will make the client instance's internal thread queue an update of User so the latest properties of the user can be retrieved from TT_GetMessage().

It's also possible to simply use TT_GetUser() but the problem with this approach is that this call is from a separate thread and therefore doesn't take the event queue into account.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nClientEventThe event which should be queued. Currently only CLIENTEVENT_USER_STATECHANGE is supported.
nIdentifierThe ID of the object to retrieve. Currently only nUserID is supported.
Returns
Returns TRUE if the event has been scheduled.

◆ TT_GetFlags()

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

◆ TT_SetLicenseInformation()

TEAMTALKDLL_API TTBOOL TT_SetLicenseInformation ( IN const TTCHAR  szRegName[TT_STRLEN],
IN const TTCHAR  szRegKey[TT_STRLEN] 
)

Set license information to disable trial mode.

This function must be called before TT_InitTeamTalk.

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