TeamTalk 5 C-API DLL: Client Initialization

TeamTalk 5 C-API DLL Version 5.18A

Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
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.
typedef UINT32 | ClientFlags
| A bitmask based on ClientFlag describing the local client instance's current state.
typedef VOID | TTInstance
| Pointer to a TeamTalk client instance created by TT_InitTeamTalk.

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

## 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 4155 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 4161 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 4056 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

  hWnd | The window handle which will receive the events defined in ClientEvent.
  uMsg | The 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  hWnd | The 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

  lpTTInstance | Pointer 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  pMsg | Pointer to a TTMessage instance which will hold the event that has occured.
  pnWaitMs | The 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

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nClientEvent | The event which should be queued. Currently only CLIENTEVENT_USER_STATECHANGE is supported.
  nIdentifier | The 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

  lpTTInstance | Pointer 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

  szRegName | The registration name provided by BearWare.dk.
  szRegKey | The registration key provided by BearWare.dk.

Returns
  True if the provided registration is acceptable.