TeamTalk 4 C-API DLL  Version 4.5A
Client Event Handling

When events occur in the client instance, like e.g. if a new user joins a channel, the client instance queues a message which the user application must retrieve. More...

Classes

struct  TTMessage
 A struct containing the properties of an event. More...
 

Typedefs

typedef enum ClientEvent ClientEvent
 TeamTalk client event messages. On Windows these messages are posted to the HWND which was provided to TT_InitTeamTalk. More...
 
typedef struct TTMessage TTMessage
 A struct containing the properties of an event. More...
 

Enumerations

enum  ClientEvent {
  WM_TEAMTALK_CON_SUCCESS, WM_TEAMTALK_CON_FAILED, WM_TEAMTALK_CON_LOST, WM_TEAMTALK_CON_P2P,
  WM_TEAMTALK_CMD_PROCESSING, WM_TEAMTALK_CMD_MYSELF_LOGGEDIN, WM_TEAMTALK_CMD_MYSELF_LOGGEDOUT, WM_TEAMTALK_CMD_MYSELF_JOINED,
  WM_TEAMTALK_CMD_MYSELF_LEFT, WM_TEAMTALK_CMD_MYSELF_KICKED, WM_TEAMTALK_CMD_USER_LOGGEDIN, WM_TEAMTALK_CMD_USER_LOGGEDOUT,
  WM_TEAMTALK_CMD_USER_UPDATE, WM_TEAMTALK_CMD_USER_JOINED, WM_TEAMTALK_CMD_USER_LEFT, WM_TEAMTALK_CMD_USER_TEXTMSG,
  WM_TEAMTALK_CMD_CHANNEL_NEW, WM_TEAMTALK_CMD_CHANNEL_UPDATE, WM_TEAMTALK_CMD_CHANNEL_REMOVE, WM_TEAMTALK_CMD_SERVER_UPDATE,
  WM_TEAMTALK_CMD_FILE_NEW, WM_TEAMTALK_CMD_FILE_REMOVE, WM_TEAMTALK_CMD_ERROR, WM_TEAMTALK_CMD_SUCCESS,
  WM_TEAMTALK_USER_TALKING, WM_TEAMTALK_USER_VIDEOFRAME, WM_TEAMTALK_USER_AUDIOFILE, WM_TEAMTALK_INTERNAL_ERROR,
  WM_TEAMTALK_VOICE_ACTIVATION, WM_TEAMTALK_STREAM_AUDIOFILE_USER, WM_TEAMTALK_STREAM_AUDIOFILE_CHANNEL, WM_TEAMTALK_HOTKEY,
  WM_TEAMTALK_HOTKEY_TEST, WM_TEAMTALK_FILETRANSFER, WM_TEAMTALK_USER_AUDIOBLOCK, WM_TEAMTALK_USER_DESKTOPWINDOW,
  WM_TEAMTALK_DESKTOPWINDOW_TRANSFER, WM_TEAMTALK_USER_DESKTOPCURSOR, WM_TEAMTALK_CON_MAX_PAYLOAD_UPDATED, WM_TEAMTALK_STREAM_MEDIAFILE_CHANNEL
}
 TeamTalk client event messages. On Windows these messages are posted to the HWND which was provided to TT_InitTeamTalk. More...
 

Detailed Description

When events occur in the client instance, like e.g. if a new user joins a channel, the client instance queues a message which the user application must retrieve.

If TT_InitTeamTalk is used with a HWND then the events are sent to the user application with WinAPI's PostMessage(...) function and is retrieved through GetMessage(...).

If a HWND is not used then events can instead be retrieved through TT_GetMessage.

Note that when an event occurs the TeamTalk client instance doesn't wait for the user application to process the event. So if e.g. a user sends a text-message and immediately after disconnects from the server, then the text-message cannot be retrieved since the user is no longer available when the user application starts processing the new text-message event. This is, of course, annoying when designing the user application, but the reason for this design choice it that the client instance is a realtime component which cannot wait for the UI to process data, since audio playback and recording would then be halted.

The section Client Programming Guide gives a good idea of how events are processed in a user application.

Typedef Documentation

typedef enum ClientEvent ClientEvent

TeamTalk client event messages. On Windows these messages are posted to the HWND which was provided to TT_InitTeamTalk.

typedef struct TTMessage TTMessage

A struct containing the properties of an event.

The event can be retrieved by called TT_GetMessage. This struct is only required on non-Windows systems.

Section Client Event Handling explains event handling in the local client instance.

See Also
TT_GetMessage

Enumeration Type Documentation

TeamTalk client event messages. On Windows these messages are posted to the HWND which was provided to TT_InitTeamTalk.

Enumerator
WM_TEAMTALK_CON_SUCCESS 

Connected successfully to the server.

This event is posted if TT_Connect was successful.

TT_DoLogin can now be called in order to logon to the server.

Parameters
wParamIgnored
lParamIgnored
See Also
TT_Connect
TT_DoLogin
WM_TEAMTALK_CON_FAILED 

Failed to connect to server.

This event is posted if TT_Connect fails. Ensure to call TT_Disconnect before calling TT_Connect again.

Parameters
wParamIgnored
lParamIgnored
See Also
TT_Connect
WM_TEAMTALK_CON_LOST 

Connection to server has been lost.

The server is not responding to requests from the local client instance and the connection has been dropped. To change when the client instance should regard the server as unavailable call TT_SetServerTimeout.

TT_GetStatistics can be used to check when data was last received from the server.

Ensure to call TT_Disconnect before calling TT_Connect again.

Parameters
wParamIgnored
lParamIgnored
See Also
TT_Connect
WM_TEAMTALK_CON_P2P 

Peer to peer (p2p) status changed.

Audio and video packets can be sent to the user without forwarding through the server. This is done by enabling P2P network using TT_EnablePeerToPeer. Once the client instance joins a new channel it will try and create a peer to peer connection to each user in the channel. The client instance will try to create a peer to peer connection for 5 seconds.

Read section Forward Through Server Transmission Mode and section Peer to Peer Transmission Mode on the different ways of transmitting data.

Parameters
wParamUser ID
lParamTRUE if P2P connection was successful, FALSE if P2P connection failed.
See Also
USERRIGHT_FORWARD_AUDIO
USERRIGHT_FORWARD_VIDEO
WM_TEAMTALK_CMD_PROCESSING 

A command issued by TT_Do* methods is being processed.

Read section Client/Server Command Processing on how to use command processing in the user application.

Parameters
wParamCommand ID being processed (returned by TT_Do* commands)
lParamIs 0 if command ID started processing and 1 if the command has finished processing.
WM_TEAMTALK_CMD_MYSELF_LOGGEDIN 

The client instance successfully logged on to server.

The call to TT_DoLogin was successful and all channels on the server will be posted in the event WM_TEAMTALK_CMD_CHANNEL_NEW immediately following this event. If USERRIGHT_VIEW_ALL_USERS is enabled the client instance will also receive the events WM_TEAMTALK_CMD_USER_LOGGEDIN and WM_TEAMTALK_CMD_USER_JOINED for every user on the server.

Parameters
wParamThe client instance's user ID, i.e. what can now be retrieved through TT_GetMyUserID.
lParamIgnored
See Also
TT_DoLogin
WM_TEAMTALK_CMD_MYSELF_LOGGEDOUT 

The client instance logged out of a server.

A response to TT_DoLogout.

Parameters
wParamIgnored
lParamIgnored
See Also
TT_DoLogout
WM_TEAMTALK_CMD_MYSELF_JOINED 

The client instance has joined a new channel.

Result of command TT_DoJoinChannel or TT_DoJoinChannelByID. Can also be a result of an administrator calling TT_DoMoveUser.

If USERRIGHT_VIEW_ALL_USERS is disabled the client instance will afterwards receive the WM_TEAMTALK_CMD_USER_JOINED event for each of the users in the channel.

Parameters
wParamChannel's ID
lParamIgnored
See Also
WM_TEAMTALK_CMD_MYSELF_LEFT
WM_TEAMTALK_CMD_MYSELF_LEFT 

The client instance left a channel.

The WPARAM contains the channel ID.

Parameters
wParamChannel's ID
lParamIgnored
See Also
TT_DoLeaveChannel
WM_TEAMTALK_CMD_MYSELF_JOINED
WM_TEAMTALK_CMD_MYSELF_KICKED 

The client instance was kicked from a channel.

Parameters
wParamUser ID of the kicker.
lParamIgnored
WM_TEAMTALK_CMD_USER_LOGGEDIN 

A new user logged on to the server.

Use TT_GetUser to get the properties of the user.

Parameters
wParamThe user's ID.
lParamUnused
See Also
TT_DoLogin
TT_GetUser To retrieve user.
WM_TEAMTALK_CMD_USER_LOGGEDOUT
WM_TEAMTALK_CMD_USER_LOGGEDOUT 

A client logged out of the server.

This event is called when a user logs out with TT_DoLogout or disconnects with TT_Disconnect.

Parameters
wParamThe user's ID.
lParamUnused
See Also
TT_DoLogout
TT_Disconnect
WM_TEAMTALK_CMD_USER_LOGGEDIN
WM_TEAMTALK_CMD_USER_UPDATE 

User changed properties.

Use TT_GetUser to see the new properties.

Parameters
wParamUser's ID
lParamChannel ID. 0 for no channel.
See Also
TT_GetUser To retrieve user.
WM_TEAMTALK_CMD_USER_JOINED 

A user has joined a channel.

Parameters
wParamUser's ID.
lParamChannel ID.
See Also
TT_GetUser To retrieve user.
WM_TEAMTALK_CMD_USER_LEFT 

User has left a channel.

Parameters
wParamUser's ID.
lParamChannel ID.
WM_TEAMTALK_CMD_USER_TEXTMSG 

A user has sent a text-message.

Parameters
wParamThe user's user ID.
lParamThe message's ID.
See Also
TT_GetTextMessage To retrieve text message.
TT_GetUser To retrieve user.
TT_DoTextMessage() To send text message.
WM_TEAMTALK_CMD_CHANNEL_NEW 

A new channel has been created.

Parameters
wParamChannel's ID
lParamIgnored
See Also
TT_GetChannel To retrieve channel.
WM_TEAMTALK_CMD_CHANNEL_UPDATE 

A channel's properties has been updated.

wParam Channel's ID lParam Ignored

See Also
TT_GetChannel To retrieve channel.
WM_TEAMTALK_CMD_CHANNEL_REMOVE 

A channel has been removed.

Note that calling the TT_GetChannel with the channel ID will fail because the channel is no longer there.

Parameters
wParamChannel's ID
lParamIgnored
WM_TEAMTALK_CMD_SERVER_UPDATE 

Server has updated its settings (server name, MOTD, etc.)

Use TT_GetServerProperties to get the new server properties.

Parameters
wParamIgnored
lParamIgnored
WM_TEAMTALK_CMD_FILE_NEW 

A new file is added to a channel.

Use TT_GetChannelFileInfo to get information about the file.

Parameters
wParamFile ID.
lParamChannel ID.
See Also
TT_GetChannelFileInfo To retrieve file.
WM_TEAMTALK_CMD_FILE_REMOVE 

A file has been removed from a channel.

Parameters
wParamFile ID.
lParamChannel ID.
WM_TEAMTALK_CMD_ERROR 

The server rejected a command issued by the local client instance.

To figure out which command failed use the command ID returned by the TT_Do* command. Section Client/Server Command Processing explains how to use command ID.

Parameters
wParamError number
lParamThe command ID returned from the TT_Do* commands.
See Also
TT_GetErrorMessage
WM_TEAMTALK_CMD_SUCCESS 

The server successfully processed a command issued by the local client instance.

To figure out which command succeeded use the command ID returned by the TT_Do* command. Section Client/Server Command Processing explains how to use command ID.

Parameters
wParamThe command ID returned from the TT_Do* commands.
lParam0.
WM_TEAMTALK_USER_TALKING 

A user is talking.

Playback using the sound output device has started for a user.

Parameters
wParamUser's ID.
lParamTRUE if talking otherwise FALSE.
See Also
TT_GetUser To retrieve user.
TT_IsTransmitting To see if 'myself' is transmitting.
TT_SetUserStoppedTalkingDelay
WM_TEAMTALK_USER_VIDEOFRAME 

A new video frame was received from a user.

Use TT_GetUserVideoFrame to display the image.

Parameters
wParamUser's ID.
lParamNumber of video frames currently in queue for display. The client uses a cyclic buffer for video frame in order to prevent resources from being drained. Therefore the WM_TEAMTALK_USER_VIDEOFRAME event might be posted more times than there actually are frames available. So use the frame count to ensure the lastest frame is always displayed.
WM_TEAMTALK_USER_AUDIOFILE 

An audio file recording has changed status.

TT_SetUserAudioFolder makes the client instance store all audio from a user to a specified folder. Every time an audio file is being processed this event is posted.

Parameters
wParamThe user's ID.
lParamThe status of the audio file. Based on AudioFileStatus.
WM_TEAMTALK_INTERNAL_ERROR 

A sound device failed to initialize.

This can e.g. happen if a new user joins a channel and there is no sound output channels available. nMaxOutputChannels of SoundDevice struct tells how many streams can be active simultaneously.

Parameters
wParamAn error number based on ClientError. The value will be of the type INTERR_*.
See Also
WM_TEAMTALK_CMD_MYSELF_JOINED If sound input device fails it will be when joining a new channel.
TT_GetSoundOutputDevices
SoundDevice
WM_TEAMTALK_VOICE_ACTIVATION 

Voice activation has triggered transmission.

Parameters
wParamTRUE if enabled, FALSE if disabled.
lParamUnused
See Also
TT_SetVoiceActivationLevel
CLIENT_SNDINPUT_VOICEACTIVATION
TT_EnableTransmission
WM_TEAMTALK_STREAM_AUDIOFILE_USER 

An audio file being streamed to a user is processing.

This event is called as a result of TT_StartStreamingAudioFileToUser.

Parameters
wParamUser's ID of where the audio file is streamed to.
lParamThe status of the audio file. Based on AudioFileStatus
See Also
TT_StartStreamingAudioFileToUser
WM_TEAMTALK_STREAM_AUDIOFILE_CHANNEL 

Audio file being stream to a channel is processing.

This event is called as a result of TT_StartStreamingAudioFileToChannel.

Parameters
wParamChannel's ID of where the audio file is being streamed to.
lParamThe status of the audio file. Based on AudioFileStatus.
See Also
TT_StartStreamingAudioFileToChannel
WM_TEAMTALK_HOTKEY 

A hotkey has been acticated or deactivated.

Parameters
wParamThe hotkey ID passed to TT_HotKey_Register
lParamis TRUE when hotkey is active and FALSE when it becomes inactive.
See Also
TT_HotKey_Register
TT_HotKey_Unregister
WM_TEAMTALK_HOTKEY_TEST 

A button was pressed or released on the user's keyboard or mouse.

When TT_HotKey_InstallTestHook is called a hook is installed in Windows which intercepts all keyboard and mouse presses. Every time a key or mouse is pressed or released this event is posted.

Use TT_HotKey_GetKeyString to get a key description of the pressed key.

Parameters
wParamThe virtual key code. Look here for a list of virtual key codes: http://msdn.microsoft.com/en-us/library/ms645540(VS.85).aspx
lParamTRUE when key is down and FALSE when released.
See Also
TT_HotKey_InstallTestHook
WM_TEAMTALK_FILETRANSFER 

A file transfer is processing.

Use TT_GetFileTransferInfo to get information about the file transfer. Ensure to check if the file transfer is completed, because the file transfer instance will be removed from the client instance when the user application reads the FileTransfer object and it has completed the transfer.

Parameters
wParamTransfer ID
lParamThe FileTransfer's status described by FileTransferStatus.
See Also
TT_GetFileTransferInfo To retrieve FileTransfer.
WM_TEAMTALK_USER_AUDIOBLOCK 

A new audio block can be extracted.

This event is only generated if TT_EnableAudioBlockEvent() is first called.

Call TT_AcquireUserAudioBlock() to extract the AudioBlock.

Parameters
wParamThe user ID.
lParamUnused.
WM_TEAMTALK_USER_DESKTOPWINDOW 

A new or updated desktop window has been received from a user.

Use TT_GetUserDesktopWindow() to retrieve the bitmap of the desktop window.

Parameters
wParamThe user's ID.
lParamThe ID of the desktop window's session. If this ID changes it means the user has started a new session. If the session ID becomes 0 it means the desktop session has been closed by the user.
See Also
TT_SendDesktopWindow()
WM_TEAMTALK_DESKTOPWINDOW_TRANSFER 

Used for tracking when a desktop window has been transmitted to the server.

When the transmission has completed the flag CLIENT_TX_DESKTOP will be cleared from the local client instance.

Parameters
wParamThe desktop session's ID. If the desktop session ID becomes 0 it means the desktop session has been closed and/or cancelled.
lParamThe number of bytes remaining before transmission of last desktop window completes. When remaining bytes is 0 TT_SendDesktopWindow() can be called again.
WM_TEAMTALK_USER_DESKTOPCURSOR 

A user has sent the position of the mouse cursor.

Use TT_SendDesktopCursorPosition() to send the position of the mouse cursor.

Parameters
wParamThe user ID of the owner of the mouse cursor.
lParamThe owner of the desktop session the mouse cursor is pointing to.
WM_TEAMTALK_CON_MAX_PAYLOAD_UPDATED 

The maximum size of the payload put into UDP packets has been updated.

Parameters
wParamThe user's ID. 0 means server's maximum payload size.
lParamThe maximum size in bytes of the payload data which is put in UDP packets. 0 means the max payload query failed.
See Also
TT_QueryMaxPayload()
WM_TEAMTALK_STREAM_MEDIAFILE_CHANNEL 

Media file being streamed to a channel is processing.

This event is called as a result of TT_StartStreamingMediaFileToChannel().

Parameters
wParamUnused.
lParamThe status of the audio file. Based on AudioFileStatus.