From 2d513bbcab73a4466a09e051d688718130dc01bd Mon Sep 17 00:00:00 2001 From: Umiko Date: Sun, 18 May 2025 09:05:19 +0700 Subject: [PATCH] fixed sdk downloader. --- TeamTalk_DLL/TeamTalk.h | 8015 ++++++++++++++++++++++++++++++++++++ TeamTalk_DLL/TeamTalk5.lib | Bin 0 -> 49470 bytes tools/ttsdk_downloader.py | 92 +- 3 files changed, 8068 insertions(+), 39 deletions(-) create mode 100644 TeamTalk_DLL/TeamTalk.h create mode 100644 TeamTalk_DLL/TeamTalk5.lib diff --git a/TeamTalk_DLL/TeamTalk.h b/TeamTalk_DLL/TeamTalk.h new file mode 100644 index 0000000..3ab7cd0 --- /dev/null +++ b/TeamTalk_DLL/TeamTalk.h @@ -0,0 +1,8015 @@ +#if !defined(TEAMTALKDLL_H) +#define TEAMTALKDLL_H + +/* + * BearWare.dk TeamTalk 5 SDK. + * + * Copyright 2005-2022, BearWare.dk. + * + * Read the License.txt file included with the TeamTalk 5 SDK for + * terms of use. + */ + +/** + * @brief Ensure the header and DLL are exactly the same version. To + * get the version of the loaded DLL call TT_GetVersion(). A remote + * client's version can be seen in the @a szVersion member of the + * #User-struct. */ + +#define TEAMTALK_VERSION "5.12.0.5106" + + +#if defined(WIN32) + +#ifdef TEAMTALKDLL_EXPORTS +#define TEAMTALKDLL_API __declspec(dllexport) +#else +#define TEAMTALKDLL_API __declspec(dllimport) +#endif + +#else + +#define TEAMTALKDLL_API + +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + + /* OS specific types. */ +#if !defined(TEAMTALK_TYPES) + +#define TEAMTALK_TYPES 1 + +#if defined(WIN32) + /* If you get a compiler error here you probably forgot to include + * before this file. */ + + /** @brief TeamTalk uses Unicode on Windows. @see TT_STRLEN */ + typedef WCHAR TTCHAR; + typedef int TTBOOL; +#else + typedef char TTCHAR; + typedef int TTBOOL; + typedef unsigned short UINT16; + typedef int INT32; + typedef long long INT64; + typedef unsigned int UINT32; + typedef void VOID; + +/** Windows has macros which tell whether a parameter is used as input + * or output so these are just defined as nothing. */ + +#define IN +#define OUT + +#ifndef TRUE +#define TRUE 1 +#endif + +#ifndef FALSE +#define FALSE 0 +#endif + +#endif + + /** @def TT_STRLEN + * + * If a string is passed to the client instance is longer than + * TT_STRLEN it will be truncated. + * + * On Windows the client instance converts unicode characters to + * UTF-8 before transmission, so be aware of non-ASCII characters + * if communicating with the TeamTalk server from another + * applications than the TeamTalk client. */ +#define TT_STRLEN 512 + + /** @def TT_USERID_MAX + * The highest user ID */ +#define TT_USERID_MAX 0xFFF + + /** @def TT_CHANNELID_MAX + * The highest channel ID. Also used for #TT_CLASSROOM_FREEFORALL */ +#define TT_CHANNELID_MAX 0xFFF + + /** @ingroup videocapture + * @def TT_VIDEOFORMATS_MAX + * The maximum number of video formats which will be queried for a + * #VideoCaptureDevice. */ +#define TT_VIDEOFORMATS_MAX 1024 + + /** @ingroup channels + * @def TT_TRANSMITUSERS_MAX + * The maximum number of users allowed to transmit when a + * #Channel is configured with #CHANNEL_CLASSROOM. */ +#define TT_TRANSMITUSERS_MAX 128 + + /** @ingroup channels + * @def TT_CLASSROOM_FREEFORALL + * If a #Channel is configured with #CHANNEL_CLASSROOM then only + * users certain user IDs are allowed to transmit. If, however, @c + * TT_CLASSROOM_FREEFORALL is put in @c transmitUsers then + * everyone in the channel are allowed to transmit. */ +#define TT_CLASSROOM_FREEFORALL 0xFFF + + /** @ingroup channels + * User ID index in @c transmitUsers of #Channel */ +#define TT_CLASSROOM_USERID_INDEX 0 + + /** @ingroup channels + * #StreamTypes index in @c transmitUsers of #Channel */ +#define TT_CLASSROOM_STREAMTYPE_INDEX 1 + + /** @ingroup channels + * @def TT_TRANSMITUSERS_FREEFORALL + * Same as #TT_CLASSROOM_FREEFORALL */ +#define TT_TRANSMITUSERS_FREEFORALL 0xFFF + + /** @ingroup channels + * @def TT_TRANSMITUSERS_USERID_INDEX + * Same as #TT_CLASSROOM_USERID_INDEX */ +#define TT_TRANSMITUSERS_USERID_INDEX 0 + + /** @ingroup channels + * @def TT_TRANSMITUSERS_STREAMTYPE_INDEX + * Same as #TT_CLASSROOM_STREAMTYPE_INDEX */ +#define TT_TRANSMITUSERS_STREAMTYPE_INDEX 1 + + /** @ingroup channels + * @def TT_CHANNELS_OPERATOR_MAX + * The maximum number of channels where a user can automatically become + * channel operator. + * @see #UserAccount */ +#define TT_CHANNELS_OPERATOR_MAX 16 + + /** @ingroup channels + * @def TT_TRANSMITQUEUE_MAX + * The maximum number of users in a #Channel's transmit queue when channel + * is configured with #CHANNEL_SOLO_TRANSMIT */ +#define TT_TRANSMITQUEUE_MAX 16 + + /** @ingroup sounddevices + * The maximum number of sample rates supported by a #SoundDevice. */ +#define TT_SAMPLERATES_MAX 16 + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_MAX + * + * The maximum number #DesktopInput instances which can be sent by + * TT_SendDesktopInput(). */ +#define TT_DESKTOPINPUT_MAX 16 + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_KEYCODE_IGNORE + * + * If @c uKeyCode in #DesktopInput is set to + * #TT_DESKTOPINPUT_KEYCODE_IGNORE it means no key (or mouse button) + * was pressed in the desktop input event and + * TT_DesktopInput_Execute() will ignore the value. */ +#define TT_DESKTOPINPUT_KEYCODE_IGNORE 0xFFFFFFFF + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_MOUSEPOS_IGNORE + * + * If @c uMousePosX or @c uMousePosY in #DesktopInput are set to + * #TT_DESKTOPINPUT_MOUSEPOS_IGNORE it means the mouse position is + * ignored when calling TT_DesktopInput_Execute(). */ +#define TT_DESKTOPINPUT_MOUSEPOS_IGNORE 0xFFFF + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN + * + * If @c uKeyCode of #DesktopInput is set to + * #TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN then TT_DesktopInput_Execute() + * will see the key-code as a left mouse button click. */ +#define TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN 0x1000 + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN + * + * If @c uKeyCode of #DesktopInput is set to + * #TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN then TT_DesktopInput_Execute() + * will see the key-code as a right mouse button click. */ +#define TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN 0x1001 + +/** @ingroup desktopshare + * @def TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN + * + * If @c uKeyCode of #DesktopInput is set to + * #TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN then TT_DesktopInput_Execute() + * will see the key-code as a middle mouse button click. */ +#define TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN 0x1002 + +/** @ingroup mediastream + * @def TT_MEDIAPLAYBACK_OFFSET_IGNORE + * + * Specify this value as uOffsetMSec in #MediaFilePlayback when + * calling TT_InitLocalPlayback() and TT_UpdateLocalPlayback() to + * ignore rewind or forward. + */ +#define TT_MEDIAPLAYBACK_OFFSET_IGNORE 0xFFFFFFFF + +#endif /* TEAMTALK_TYPES */ + + /** @addtogroup transmission + * @{ */ + + /** @brief The types of streams which are available for + * transmission. */ + typedef enum StreamType + { + /** @brief No stream. */ + STREAMTYPE_NONE = 0x00000000, + /** @brief Voice stream type which is audio recorded from a + * sound input device. @see TT_InitSoundInputDevice() */ + STREAMTYPE_VOICE = 0x00000001, + /** @brief Video capture stream type which is video recorded + * from a webcam. @see TT_InitVideoCaptureDevice() */ + STREAMTYPE_VIDEOCAPTURE = 0x00000002, + /** @brief Audio stream type from a media file which is being + * streamed. @see TT_StartStreamingMediaFileToChannel() */ + STREAMTYPE_MEDIAFILE_AUDIO = 0x00000004, + /** @brief Video stream type from a media file which is being + * streamed. @see TT_StartStreamingMediaFileToChannel() */ + STREAMTYPE_MEDIAFILE_VIDEO = 0x00000008, + /** @brief Desktop window stream type which is a window (or + * bitmap) being transmitted. @see TT_SendDesktopWindow() */ + STREAMTYPE_DESKTOP = 0x00000010, + /** @brief Desktop input stream type which is keyboard or + * mouse input being transmitted. @see + * TT_SendDesktopInput() */ + STREAMTYPE_DESKTOPINPUT = 0x00000020, + /** @brief Shortcut to allow both audio and video media files. */ + STREAMTYPE_MEDIAFILE = STREAMTYPE_MEDIAFILE_AUDIO | + STREAMTYPE_MEDIAFILE_VIDEO, + /** @brief Channel text messages as stream type. + * + * A channel text message is not a stream but is only included + * as a stream type in order to be able to block messages + * using @c transmitUsers in #Channel struct. + * + * @see TT_DoUpdateChannel() + * @see CHANNEL_CLASSROOM. */ + STREAMTYPE_CHANNELMSG = 0x00000040, + /** @brief Stream type for audio of local playback. + * + * TT_EnableAudioBlockEvent() can be used to intercept audio + * from a local media playback. + * @see TT_InitLocalPlayback() */ + STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO = 0x00000080, + + /** @brief Shortcut to allow voice, media files, desktop, + * webcamera and channel messages. */ + STREAMTYPE_CLASSROOM_ALL = STREAMTYPE_VOICE | + STREAMTYPE_VIDEOCAPTURE | + STREAMTYPE_DESKTOP | + STREAMTYPE_MEDIAFILE | + STREAMTYPE_CHANNELMSG, + } StreamType; + + /** @brief Mask of #StreamType. */ + typedef UINT32 StreamTypes; + + /** @} */ + + /** @addtogroup sounddevices + * @{ */ + + /** + * @brief The supported sound systems. + * + * @see SoundDevice + * @see TT_InitSoundInputDevice() + * @see TT_InitSoundOutputDevice() + * @see TT_InitSoundDuplexDevices() */ + typedef enum SoundSystem + { + /** @brief Sound system denoting invalid or not found. */ + SOUNDSYSTEM_NONE = 0, + /** @brief Windows legacy audio system. Should be used on Windows Mobile. */ + SOUNDSYSTEM_WINMM = 1, + /** @brief DirectSound audio system. Should be used on Windows. */ + SOUNDSYSTEM_DSOUND = 2, + /** + * @brief Advanced Linux Sound Architecture (ALSA). Should be used on Linux. + * + * Often ALSA sound devices only support a limited number of + * sample rates so TeamTalk internally use software filters to + * resample the audio to the sample rate used by the selected + * audio codecs. */ + SOUNDSYSTEM_ALSA = 3, + /** @brief Core Audio. Should be used on MacOS. */ + SOUNDSYSTEM_COREAUDIO = 4, + /** @brief Windows Audio Session API (WASAPI). Should be used + * on Windows Vista/7/8/10. + * + * WASAPI audio devices typically only support a single sample + * rate so internally TeamTalk uses software filters to + * resample audio to the sample rate used by the selected + * audio codecs. + * + * Check @c supportedSampleRates and @c nDefaultSampleRate of + * #SoundDevice to see which sample rates are supported. */ + SOUNDSYSTEM_WASAPI = 5, + /** @brief Android sound API. + * + * The OpenSL ES sound API requires Android 4.1 or later. + * + * Duplex mode is not supported by OpenSL ES @see + * TT_InitSoundDuplexDevices() */ + SOUNDSYSTEM_OPENSLES_ANDROID = 7, + /** @brief iOS sound API. + * + * The following sound devices will appear when calling + * TT_GetSoundDevices(). Sound device ID + * #TT_SOUNDDEVICE_ID_REMOTEIO will be AudioUnit subtype + * Remote I/O Unit and sound device ID + * #TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO will be AudioUnit + * subtype Voice-Processing I/O Unit. + * + * Note that iOS only supports one active Voice-Processing I/O + * Unit, i.e. only one #TTInstance can use the + * Voice-Processing I/O Unit. + * + * Add libraries @c AVFoundation.framework and + * @c AudioToolbox.framework. + * + * Duplex mode is not supported by AudioUnit iOS sound API. + * @see TT_SOUNDDEVICE_ID_REMOTEIO + * @see TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO */ + SOUNDSYSTEM_AUDIOUNIT = 8, + /** @brief Same as #SOUNDSYSTEM_AUDIOUNIT. */ + SOUNDSYSTEM_AUDIOUNIT_IOS = SOUNDSYSTEM_AUDIOUNIT, + } SoundSystem; + + /** + * @brief Features available on a sound device. + * Checkout @c uSoundDeviceFeatures on #SoundDevice. + * */ + typedef enum SoundDeviceFeature + { + /** @brief No sound device features are available on this + * sound device. */ + SOUNDDEVICEFEATURE_NONE = 0x0000, + /** @brief The #SoundDevice can enable Acoustic + * Echo Canceler (AEC). + * Enable AEC use property @c bEnableAEC on + * #SoundDeviceEffects. + * @see TT_SetSoundDeviceEffects() */ + SOUNDDEVICEFEATURE_AEC = 0x0001, + /** @brief The #SoundDevice can enable Automatic + * Gain Control (AGC). + * Enable AGC use property @c bEnableAGC on + * #SoundDeviceEffects. + * @see TT_SetSoundDeviceEffects() */ + SOUNDDEVICEFEATURE_AGC = 0x0002, + /** @brief The #SoundDevice can enable denoising. + * Enable denoising use property @c bEnableDenoising on + * #SoundDeviceEffects. + * @see TT_SetSoundDeviceEffects() */ + SOUNDDEVICEFEATURE_DENOISE = 0x0004, + /** @brief The #SoundDevice can position user in 3D. + * @see TT_SetUserPosition() */ + SOUNDDEVICEFEATURE_3DPOSITION = 0x0008, + /** @brief The #SoundDevice can run in duplex mode. + * @see TT_InitSoundDuplexDevices() */ + SOUNDDEVICEFEATURE_DUPLEXMODE = 0x0010, + /** @brief The #SoundDevice is the default communication device. + * This feature is only supported on SOUNDSYSTEM_WASAPI. */ + SOUNDDEVICEFEATURE_DEFAULTCOMDEVICE = 0x0020, + } SoundDeviceFeature; + + /** @brief A bitmask of available #SoundDeviceFeature. + * Checkout @c uSoundDeviceFeatures on #SoundDevice. */ + typedef UINT32 SoundDeviceFeatures; + + /** + * @brief A struct containing the properties of a sound device + * for either playback or recording. + * + * Use @a nDeviceID to pass to #TT_InitSoundInputDevice or + * #TT_InitSoundOutputDevice. + * + * Note that the @a nDeviceID may change if the user application + * is restarted and a new sound device is added or removed from + * the computer. + * + * @see TT_GetSoundDevices */ + typedef struct SoundDevice + { + /** @brief The ID of the sound device. Used for passing to + * #TT_InitSoundInputDevice and + * #TT_InitSoundOutputDevice. Note that @a nDeviceID might change + * if USB sound devices are plugged in or unplugged, therefore + * use @a szDeviceID to ensure proper device is used. */ + INT32 nDeviceID; + /** @brief The sound system used by the sound device */ + SoundSystem nSoundSystem; + /** @brief The name of the sound device */ + TTCHAR szDeviceName[TT_STRLEN]; + /** @brief An identifier uniquely identifying the sound device + * even when new sound devices are being added and removed. In + * DirectSound, WASAPI and WinMM it would be the GUID of the sound + * device. Note that it may not always be available. */ + TTCHAR szDeviceID[TT_STRLEN]; + /** + * @brief A Windows specific ID to the sound device. + * + * For DirectSound and WinMM this is the ID of the device used + * in Win32's waveInGetDevCaps and waveOutGetDevCaps. + * Value will be -1 if no ID could be found This ID can also + * be used to find the corresponding mixer on Windows passing + * it as @a nWaveDeviceID. Note that this ID applies both to + * DirectSound and WinMM. + * + * For WASAPI this ID is the index of + * IMMDeviceEnumerator::EnumAudioEndpoints() + * + * @see TT_Mixer_GetWaveInName + * @see TT_Mixer_GetWaveOutName + * @see TT_Mixer_GetMixerCount */ + INT32 nWaveDeviceID; + /** @brief Whether the sound device supports 3D-sound + * effects. @deprecated Use #SOUNDDEVICEFEATURE_3DPOSITION. */ + TTBOOL bSupports3D; + /** @brief The maximum number of input channels. */ + INT32 nMaxInputChannels; + /** @brief The maximum number of output channels. */ + INT32 nMaxOutputChannels; + /** @brief Supported sample rates by device for recording. A + * zero value terminates the list of supported sample rates or + * its maximum size of #TT_SAMPLERATES_MAX. */ + INT32 inputSampleRates[TT_SAMPLERATES_MAX]; + /** @brief Supported sample rates by device for playback. A + * zero value terminates the list of supported sample rates or + * its maximum size of #TT_SAMPLERATES_MAX. */ + INT32 outputSampleRates[TT_SAMPLERATES_MAX]; + /** @brief The default sample rate for the sound device. */ + INT32 nDefaultSampleRate; + /** @brief Additional features available for this sound + * device. The sound device features can be used to enable + * additional features on the sound device. + * @see SoundDeviceFeature + * @see TT_SetSoundDeviceEffects() */ + SoundDeviceFeatures uSoundDeviceFeatures; + } SoundDevice; + + /** + * @brief Set up audio effects supported by the sound device. + * + * The effects supported by a sound device are listed in the @c + * uSoundDeviceFeatures property of #SoundDevice. + * + * To apply audio effects on a sound device call + * TT_SetSoundDeviceEffects() */ + typedef struct SoundDeviceEffects + { + /** + * @brief Enable Automatic Gain Control. + * + * This effect can be enabled on a #SoundDevice that has + * #SOUNDDEVICEFEATURE_AGC flag in @c uSoundDeviceFeatures. + * + * Supported platforms: + * - Windows + * - Automatic gain control is per #TTInstance. + * - #TTInstance must initialize sound devices using + * TT_InitSoundDuplexDevices() + * - Android + * - Automatic gain control will be applied on all active + * #TTInstance. + * @see SOUNDDEVICEFEATURE_AGC */ + TTBOOL bEnableAGC; + /** + * @brief Enable noise suppression. + * + * This effect can be enabled on a #SoundDevice that has + * #SOUNDDEVICEFEATURE_DENOISE flag in @c + * uSoundDeviceFeatures. + * + * Supported platforms: + * - Windows + * - Noise suppression is per #TTInstance. + * - #TTInstance must initialize sound devices using + * TT_InitSoundDuplexDevices() + * - Android + * - Noise suppression will be applied on all active + * #TTInstance. + * @see SOUNDDEVICEFEATURE_DENOISE */ + TTBOOL bEnableDenoise; + /** + * @brief Enable echo cancellation. + * + * This effect can be enabled on a #SoundDevice that has + * #SOUNDDEVICEFEATURE_AEC flag in @c uSoundDeviceFeatures. + * + * Supported platforms: + * - Windows + * - Echo cancellation is per #TTInstance. + * - #TTInstance must initialize sound devices using + * TT_InitSoundDuplexDevices() + * - Android + * - Echo cancellation will be applied on all active + * #TTInstance. + * @see SOUNDDEVICEFEATURE_AEC */ + TTBOOL bEnableEchoCancellation; + } SoundDeviceEffects; + +/** + * @brief Flag/bit in @c nDeviceID telling if the #SoundDevice is a + * shared version of an existing sound device. + * + * On Android the recording device can only be used by one TeamTalk + * instance. As a workaround for this issue a shared recording device + * has been introduced. Internally TeamTalk initializes + * #TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT which then resample and + * distribute the audio data to multiple TeamTalk instances. + * + * The shared audio device on Android will show up as + * (TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT | TT_SOUNDDEVICE_ID_SHARED_FLAG), + * i.e. 2048. + */ +#define TT_SOUNDDEVICE_ID_SHARED_FLAG 0x00000800 + +/** @brief Extract sound device ID of @c nDeviceID in #SoundDevice by + * and'ing this value. + * + * let PhysicalDeviceID = (SoundDevice.nDeviceID & TT_SOUNDDEVICE_ID_MASK). */ +#define TT_SOUNDDEVICE_ID_MASK 0x000007FF + +/** @brief Sound device ID for iOS AudioUnit subtype Remote I/O + * Unit. @see SOUNDSYSTEM_AUDIOUNIT */ +#define TT_SOUNDDEVICE_ID_REMOTEIO 0 + +/** @brief Sound device ID for iOS AudioUnit subtype Voice-Processing + * I/O Unit. + * + * This sound device ID include the flag + * #TT_SOUNDDEVICE_ID_SHARED_FLAG since multiple streams cannot be + * recorded/played on the device. @see SOUNDSYSTEM_AUDIOUNIT */ +#define TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO (1 | TT_SOUNDDEVICE_ID_SHARED_FLAG) + +/** @brief Sound device ID for Android OpenSL ES default audio + * device. @see SOUNDSYSTEM_OPENSLES_ANDROID */ +#define TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT 0 + +/** @brief Sound device ID for Android OpenSL ES voice communication + * mode. This device uses the OpenSL ES' AndroidConfiguration @c + * SL_ANDROID_RECORDING_PRESET_VOICE_COMMUNICATION @see + * SOUNDSYSTEM_OPENSLES_ANDROID */ +#define TT_SOUNDDEVICE_ID_OPENSLES_VOICECOM 1 + +/** @brief Sound device ID for virtual TeamTalk sound device. + * + * This is a sound device which decodes received audio packets but + * does not send the decoded audio to a real sound device. When used + * for recording the virtual sound device injects silence. + * + * In duplex mode the virtual TeamTalk sound device can only be used + * as input/output device. @see SOUNDSYSTEM_NONE */ +#define TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL 1978 + + /** + * @brief An enum encapsulation the minimum, maximum and default sound + * levels for input and output sound devices. */ + typedef enum SoundLevel + { + /** + * @brief The maximum value of recorded audio. + * @see TT_GetSoundInputLevel + * @see TT_SetVoiceActivationLevel + * @see TT_GetVoiceActivationLevel */ + SOUND_VU_MAX = 100, + /** + * @brief The minimum value of recorded audio. + * @see TT_GetSoundInputLevel + * @see TT_SetVoiceActivationLevel + * @see TT_GetVoiceActivationLevel */ + SOUND_VU_MIN = 0, + /** + * @brief The maximum volume. + * + * @see TT_SetSoundOutputVolume + * @see TT_GetSoundOutputVolume + * @see TT_SetUserVolume + * @see SOUND_VOLUME_DEFAULT */ + SOUND_VOLUME_MAX = 32000, + /** + * @brief The default volume. Use this whenever possible since + * it requires the least amount of CPU usage. + * + * @see TT_SetSoundOutputVolume + * @see TT_GetSoundOutputVolume + * @see TT_SetUserVolume */ + SOUND_VOLUME_DEFAULT = 1000, + /** + * @brief The minimum volume. + * @see TT_SetSoundOutputVolume + * @see TT_GetSoundOutputVolume + * @see TT_SetUserVolume */ + SOUND_VOLUME_MIN = 0, + /** + * @brief The maximum gain level. + * + * A gain level of 32000 gains the volume by a factor 32. A gain + * level of #SOUND_GAIN_DEFAULT means no gain. + * + * @see TT_SetSoundInputGainLevel + * @see TT_GetSoundInputGainLevel */ + SOUND_GAIN_MAX = 32000, + /** + * @brief The default gain level. + * + * A gain level of 1000 means no gain. Check #SOUND_GAIN_MAX + * and #SOUND_GAIN_MIN to see how to increase and lower gain + * level. + * + * @see TT_SetSoundInputGainLevel + * @see TT_GetSoundInputGainLevel */ + SOUND_GAIN_DEFAULT = 1000, + /** + * @brief The minimum gain level (since it's zero it means + * silence). + * + * A gain level of 100 is 1/10 of the default volume. + * + * @see TT_SetSoundInputGainLevel + * @see TT_GetSoundInputGainLevel */ + SOUND_GAIN_MIN = 0 + } SoundLevel; + + /** + * @brief An audio block containing the raw audio from a user who + * was talking. + * + * To enable audio blocks first call TT_EnableAudioBlockEvent() + * then whenever new audio is played the event + * #CLIENTEVENT_USER_AUDIOBLOCK is generated. Use + * TT_AcquireUserAudioBlock() to retrieve the audio block. + * + * Note that each user is limited to 128 kbytes of audio data. + * + * @see TT_EnableAudioBlockEvent() + * @see TT_AcquireUserAudioBlock() + * @see TT_ReleaseUserAudioBlock() */ + typedef struct AudioBlock + { + /** @brief The ID of the stream. The stream id changes every time + * the user enables a new transmission using TT_EnableTransmission() + * or through voice activation. */ + INT32 nStreamID; + /** @brief The sample rate of the raw audio. */ + INT32 nSampleRate; + /** @brief The number of channels used (1 for mono, 2 for stereo). */ + INT32 nChannels; + /** @brief The raw audio in 16-bit integer format array. The + * size of the array in bytes is @c sizeof(short) * @c + * nSamples * @c nChannels. */ + VOID* lpRawAudio; + /** @brief The number of samples in the raw audio array. */ + INT32 nSamples; + /** @brief The index of the first sample in @c lpRawAudio. Its + * value will be a multiple of @c nSamples. The sample index + * can be used to detect overflows of the internal + * buffer. When a user initially starts talking the @c + * nSampleIndex will be 0 and while the user is talking @c + * nSampleIndex will be greater than 0. When the user stops + * talking @c nSampleIndex will be reset to 0 again. */ + UINT32 uSampleIndex; + /** @brief The stream types used to generate the AudioBlock's + * raw audio. + * + * When retrieving audio that has been mixed together from + * multiple sources it can be useful to know what stream types + * were mixed together to generate the AudioBlock. + * + * If 'uStreamTypes' is STREAMTYPE_NONE it means that silence + * was inserted. Silence is inserted if no audio was available + * for mixing or the duration from last audio packet was + * received and until @c nStoppedDelayVoice of #User has + * expired. @see TT_MUXED_USERID */ + StreamTypes uStreamTypes; + } AudioBlock; + +/** + * @brief User ID passed to TT_EnableAudioBlockEvent() in order to + * receive #AudioBlock directly from sound input device after joining + * a channel. + * + * When this user ID is passed then the #AudioBlock received will be + * prior to audio preprocessing (#AudioPreprocessor). + * + * Note, however, that #CLIENTEVENT_USER_AUDIOBLOCK will not be + * triggered until the #TTInstance is in a channel. This is because + * the sound input device is not started until it knows the + * #AudioCodec's sample rate, number of channels and transmit + * interval. */ +#define TT_LOCAL_USERID 0 + +/** + * @brief User ID passed to TT_EnableAudioBlockEvent() in order to + * receive #AudioBlock when voice transmission is activated. + * + * Either through TT_EnableVoiceActivation() or + * TT_EnableVoiceTransmission(). + */ +#define TT_LOCAL_TX_USERID 0x1002 + +/** + * @brief User ID used to identify muxed audio that has been mixed + * into a single stream. + * + * This user ID is passed to TT_EnableAudioBlockEvent() in order to + * receive #AudioBlock of audio that is played by the #TTInstance. */ +#define TT_MUXED_USERID 0x1001 /* TT_USERID_MAX + 2 */ + + /** @} */ + + /** @addtogroup mediastream + * @{ */ + + /** + * @brief Status of media file being written to disk. + * @see CLIENTEVENT_USER_RECORD_MEDIAFILE */ + typedef enum MediaFileStatus + { + MFS_CLOSED = 0, + /** @brief Error while processing media file. */ + MFS_ERROR = 1, + /** @brief Started processing media file. */ + MFS_STARTED = 2, + /** @brief Finished processing media file. */ + MFS_FINISHED = 3, + /** @brief Aborted processing of media file. */ + MFS_ABORTED = 4, + /** @brief Paused processing of media file. */ + MFS_PAUSED = 5, + /** @brief Playing media file with updated @c uElapsedMSec of + * #MediaFileInfo. */ + MFS_PLAYING = 6 + } MediaFileStatus; + + /** + * @brief Media file formats supported for muxed audio recordings. + * @see TT_StartRecordingMuxedAudioFile() */ + typedef enum AudioFileFormat + { + /** @brief Used to denote nothing selected. */ + AFF_NONE = 0, + /** @brief Store audio in the same format as the #Channel's + * configured audio codec. + * + * Audio is stored in OGG format. OGG format is supported by + * https://www.xiph.org/ogg and can be played using VLC media player + * http://www.videolan.org + * + * Requires TeamTalk version 5.2.0.4730. + * @see TT_SetUserMediaStorageDir() + * @see TT_StartRecordingMuxedAudioFile() */ + AFF_CHANNELCODEC_FORMAT = 1, + /** @brief Store in PCM 16-bit wave format. */ + AFF_WAVE_FORMAT = 2, + /** @brief Store in MP3-format. */ + AFF_MP3_16KBIT_FORMAT = 3, + /** @see #AFF_MP3_16KBIT_FORMAT */ + AFF_MP3_32KBIT_FORMAT = 4, + /** @see #AFF_MP3_16KBIT_FORMAT */ + AFF_MP3_64KBIT_FORMAT = 5, + /** @see #AFF_MP3_16KBIT_FORMAT */ + AFF_MP3_128KBIT_FORMAT = 6, + /** @see #AFF_MP3_16KBIT_FORMAT */ + AFF_MP3_256KBIT_FORMAT = 7, + } AudioFileFormat; + + /** + * @brief Struct describing the audio format used by a + * media file. + * + * @see TT_GetMediaFileInfo() + * @see MediaFileInfo + */ + typedef struct AudioFormat + { + /** @brief The audio file format, e.g. wave or MP3. */ + AudioFileFormat nAudioFmt; + /** @brief Sample rate of media file. */ + INT32 nSampleRate; + /** @brief Channels used by media file, mono = 1, stereo = 2. */ + INT32 nChannels; + } AudioFormat; + + /** @} */ + + /** @addtogroup videocapture + * @{ */ + + /** + * @brief The picture format used by a capture device. + * + * @see VideoFormat + * @see VideoCaptureDevice */ + typedef enum FourCC + { + /** @brief Internal use to denote no supported formats. */ + FOURCC_NONE = 0, + /** @brief Prefered image format with the lowest bandwidth + * usage. A 640x480 pixel image takes up 460.800 bytes. */ + FOURCC_I420 = 100, + /** @brief Image format where a 640x480 pixel images takes up + * 614.400 bytes. */ + FOURCC_YUY2 = 101, + /** @brief The image format with the highest bandwidth + * usage. A 640x480 pixel images takes up 1.228.880 bytes. */ + FOURCC_RGB32 = 102 + } FourCC; + + /** + * @brief A struct containing the properties of a video capture + * format. + * + * A struct for holding a supported video capture format by a + * #VideoCaptureDevice. */ + typedef struct VideoFormat + { + /** @brief The width in pixels of the video device supported + * video format. */ + INT32 nWidth; + /** @brief The height in pixels of the video device supported + * video format. */ + INT32 nHeight; + /** @brief The numerator of the video capture device's video + * format. Divinding @a nFPS_Numerator with @a + * nFPS_Denominator gives the frame-rate. */ + INT32 nFPS_Numerator; + /** @brief The denominator of the video capture device's video + * format. Divinding @a nFPS_Numerator with @a + * nFPS_Denominator gives the frame-rate.*/ + INT32 nFPS_Denominator; + /** @brief Picture format for capturing. */ + FourCC picFourCC; + } VideoFormat; + + /** + * @brief A RGB32 image where the pixels can be accessed directly + * in an allocated @a frameBuffer. + * + * Use TT_AcquireUserVideoCaptureFrame() to acquire a user's image and + * remember to call TT_ReleaseUserVideoCaptureFrame() when the image has + * been processed so TeamTalk can release its resources. */ + typedef struct VideoFrame + { + /** @brief The width in pixels of the image contained in @a + * frameBuffer. */ + INT32 nWidth; + /** @brief The height in pixels of the image contained in @a + * imageBuffer. */ + INT32 nHeight; + /** @brief A unique identifier for the frames which are part of the + * same video sequence. If the stream ID changes it means the + * frames which are being received are part of a new video sequence + * and @a nWidth and @a nHeight may have changed. The @a nStreamID + * will always be a positive integer value.*/ + INT32 nStreamID; + /** @brief Whether the image acquired is a key-frame. If it is + * not a key-frame and there has been packet loss or a + * key-frame has not been acquired prior then the image may + * look blurred. */ + TTBOOL bKeyFrame; + /** @brief A buffer allocated internally by client instance. */ + VOID* frameBuffer; + /** @brief The size in bytes of the buffer allocate in @a + * frameBuffer. */ + INT32 nFrameBufferSize; + } VideoFrame; + + /** + * @brief A struct containing the properties of a video capture + * device. + * + * The information retrieved from the video capture device is used + * to initialize the video capture device using the + * #TT_InitVideoCaptureDevice function. + * + * @see TT_GetVideoCaptureDevices */ + typedef struct VideoCaptureDevice + { + /** @brief A string identifying the device. */ + TTCHAR szDeviceID[TT_STRLEN]; + /** @brief The name of the capture device. */ + TTCHAR szDeviceName[TT_STRLEN]; + /** @brief The name of the API used to capture video. + * + * The following video capture APIs are supported: + * - AVFoundation (Mac OS) + * - DirectShow (Windows) + * - V4L2 (Linux) + * + * Mac OS's QTkit video capture API was removed in TeamTalk + * 5.2 because Apple's AppStore will reject apps which have + * dependencies to it. + * + * V4L support was removed in TeamTalk 5.2. */ + TTCHAR szCaptureAPI[TT_STRLEN]; + /** @brief The supported capture formats. */ + VideoFormat videoFormats[TT_VIDEOFORMATS_MAX]; + /** @brief The number of capture formats available in @a + * videoFormats array. */ + INT32 nVideoFormatsCount; + } VideoCaptureDevice; + + /** @} */ + + /** @addtogroup desktopshare + * @{ */ + + /** + * @brief The bitmap format used for a #DesktopWindow. */ + typedef enum BitmapFormat + { + /** @brief Used to denote nothing selected. */ + BMP_NONE = 0, + /** @brief The bitmap is a 256-colored bitmap requiring a + * palette. The default 256 colored palette is the Netscape + * browser-safe palette. Use TT_Palette_GetColorTable() to + * access or change the palette. The maximum size of a + * 8-bit bitmap is 4095 blocks of 120 by 34 pixels. */ + BMP_RGB8_PALETTE = 1, + /** @brief The bitmap is a 16-bit colored bitmap. The maximum + * pixels. */ + BMP_RGB16_555 = 2, + /** @brief The bitmap is a 24-bit colored bitmap. The maximum + * size of a 24-bit bitmap is 4095 blocks of 85 by 16 + * pixels. */ + BMP_RGB24 = 3, + /** @brief The bitmap is a 32-bit colored bitmap. The maximum + * size of a 32-bit bitmap is 4095 blocks of 51 by 20 + * pixels. */ + BMP_RGB32 = 4 + } BitmapFormat; + + /** @brief The protocols supported for transferring a + * #DesktopWindow. + * + * So far only one, UDP-based, protocol is supported. */ + typedef enum DesktopProtocol + { + /** @brief Desktop protocol based on ZLIB for image + * compression and UDP for data transmission. */ + DESKTOPPROTOCOL_ZLIB_1 = 1 + } DesktopProtocol; + + /** + * @brief A struct containing the properties of a shared desktop window. + * + * The desktop window is a description of the bitmap which can be retrieved using + * TT_AcquireUserDesktopWindow() or the bitmap which should be transmitted using + * TT_SendDesktopWindow(). */ + typedef struct DesktopWindow + { + /** @brief The width in pixels of the bitmap. */ + INT32 nWidth; + /** @brief The height in pixels of the bitmap. */ + INT32 nHeight; + /** @brief The format of the bitmap. */ + BitmapFormat bmpFormat; + /** @brief The number of bytes for each scan-line in the + * bitmap. Zero means 4-byte aligned. */ + INT32 nBytesPerLine; + /** @brief The ID of the session which the bitmap belongs + * to. If the session ID changes it means the user has started + * a new session. This e.g. happens if the desktop session has + * been closed and restart or if the bitmap has been + * resized. Set @c nSessionID to 0 if the desktop window is + * used with TT_SendDesktopWindow(). */ + INT32 nSessionID; + /** @brief The desktop protocol used for transmitting the desktop window. */ + DesktopProtocol nProtocol; + /** @brief A buffer pointing to the bitmap data (often refered to as Scan0). */ + VOID* frameBuffer; + /** @brief The size in bytes of the buffer allocate in @a + * frameBuffer. Typically @c nBytesPerLine * @c nHeight. */ + INT32 nFrameBufferSize; + } DesktopWindow; + + /** + * @brief The state of a key (or mouse button), i.e. if it's + * pressed or released. @see DesktopInput */ + typedef enum DesktopKeyState + { + /** @brief The key is ignored. */ + DESKTOPKEYSTATE_NONE = 0x00000000, + /** @brief The key is pressed. */ + DESKTOPKEYSTATE_DOWN = 0x00000001, + /** @brief The key is released. */ + DESKTOPKEYSTATE_UP = 0x00000002, + } DesktopKeyState; + + /** @brief Mask of key states. */ + typedef UINT32 DesktopKeyStates; + + /** + * @brief A struct containing a mouse or keyboard event. + * + * The DesktopInput struct is used for desktop access where a + * remote user can control mouse or keybaord on a shared + * desktop. Check out section @ref desktopinput on how to use + * remote desktop access. */ + typedef struct DesktopInput + { + /** @brief The X coordinate of the mouse. If used with + * TT_DesktopInput_Execute() and the mouse position should be + * ignored then set to #TT_DESKTOPINPUT_MOUSEPOS_IGNORE. */ + UINT16 uMousePosX; + /** @brief The Y coordinate of the mouse. If used with + * TT_DesktopInput_Execute() and the mouse position should be + * ignored then set to #TT_DESKTOPINPUT_MOUSEPOS_IGNORE. */ + UINT16 uMousePosY; + /** @brief The key-code (or mouse button) pressed. If used + * with TT_DesktopInput_Execute() and no key (or mouse button) + * is pressed then set to #TT_DESKTOPINPUT_KEYCODE_IGNORE. + * Read section @ref transdesktopinput on issues with + * key-codes and keyboard settings. */ + UINT32 uKeyCode; + /** @brief The state of the key (or mouse button) pressed, + * i.e. if it's up or down. */ + DesktopKeyStates uKeyState; + } DesktopInput; + + /** @} */ + + /** @addtogroup codecs + * @{ */ + + /** @brief Speex audio codec settings for Constant Bitrate mode + * (CBR). + * + * @deprecated Use #OpusCodec. + * + * @see SpeexVBRCodec */ + typedef struct SpeexCodec + { + /** @brief Set to 0 for 8 KHz (narrow band), set to 1 for 16 KHz + * (wide band), set to 2 for 32 KHz (ultra-wide band). */ + INT32 nBandmode; + /** @brief A value from 1-10. As of DLL version 4.2 also 0 is + * supported.*/ + INT32 nQuality; + /** @brief Milliseconds of audio data before each + * transmission. + * + * Speex uses 20 msec frame sizes. Recommended is 40 msec. Min + * is 20, max is 500 msec. + * + * The #SoundSystem must be able to process audio packets at + * this interval. In most cases this makes less than 40 msec + * transmission interval unfeasible. */ + INT32 nTxIntervalMSec; + /** @brief Playback should be done in stereo. Doing so will + * disable 3d-positioning. + * + * @see TT_SetUserPosition() + * @see TT_SetUserStereo() */ + TTBOOL bStereoPlayback; + } SpeexCodec; + + /** @brief Speex audio codec settings for Variable Bitrate mode + * (VBR). + * + * @deprecated Use #OpusCodec. */ + typedef struct SpeexVBRCodec + { + /** @brief Set to 0 for 8 KHz (narrow band), set to 1 for 16 KHz + * (wide band), set to 2 for 32 KHz (ultra-wide band). */ + INT32 nBandmode; + /** @brief A value from 0-10. If @c nBitRate is non-zero it + * will override this value. */ + INT32 nQuality; + /** @brief The bitrate at which the audio codec should output + * encoded audio data. Dividing it by 8 gives roughly the + * number of bytes per second used for transmitting the + * encoded data. For limits check out #SPEEX_NB_MIN_BITRATE, + * #SPEEX_NB_MAX_BITRATE, #SPEEX_WB_MIN_BITRATE, + * #SPEEX_WB_MAX_BITRATE, #SPEEX_UWB_MIN_BITRATE and + * #SPEEX_UWB_MAX_BITRATE. Note that specifying @c nBitRate + * will override nQualityVBR. */ + INT32 nBitRate; + /** @brief The maximum bitrate at which the audio codec is + * allowed to output audio. Set to zero if it should be + * ignored. */ + INT32 nMaxBitRate; + /** @brief Enable/disable discontinuous transmission. When + * enabled Speex will ignore silence, so the bitrate will + * become very low. */ + TTBOOL bDTX; + /** @brief Milliseconds of audio data before each transmission. + * + * Speex uses 20 msec frame sizes. Recommended is 40 msec. Min + * is 20, max is 500 msec. + * + * The #SoundSystem must be able to process audio packets at + * this interval. In most cases this makes less than 40 msec + * transmission interval unfeasible. */ + INT32 nTxIntervalMSec; + /** @brief Playback should be done in stereo. Doing so will + * disable 3d-positioning. + * + * @see TT_SetUserPosition() + * @see TT_SetUserStereo() */ + TTBOOL bStereoPlayback; + } SpeexVBRCodec; + +/** @brief The minimum bitrate for Speex codec in 8 KHz mode. Bandmode + * = 0. */ +#define SPEEX_NB_MIN_BITRATE 2150 +/** @brief The maximum bitrate for Speex codec in 8 KHz mode. Bandmode + * = 0. */ +#define SPEEX_NB_MAX_BITRATE 24600 +/** @brief The minimum bitrate for Speex codec in 16 KHz + * mode. Bandmode = 1. */ +#define SPEEX_WB_MIN_BITRATE 3950 +/** @brief The maximum bitrate for Speex codec in 16 KHz + * mode. Bandmode = 1. */ +#define SPEEX_WB_MAX_BITRATE 42200 +/** @brief The minimum bitrate for Speex codec in 32 KHz + * mode. Bandmode = 2. */ +#define SPEEX_UWB_MIN_BITRATE 4150 +/** @brief The maximum bitrate for Speex codec in 32 KHz + * mode. Bandmode = 2. */ +#define SPEEX_UWB_MAX_BITRATE 44000 + + /** @brief OPUS audio codec settings. For detailed information + * about the OPUS codec check out http://www.opus-codec.org */ + typedef struct OpusCodec + { + /** @brief The sample rate to use. Sample rate must be + * 8000, 12000, 16000, 24000 or 48000 Hz. */ + INT32 nSampleRate; + /** @brief Mono = 1 or stereo = 2. */ + INT32 nChannels; + /** @brief Application of encoded audio, i.e. VoIP or music. + * @see OPUS_APPLICATION_VOIP + * @see OPUS_APPLICATION_AUDIO */ + INT32 nApplication; + /** @brief Complexity of encoding (affects CPU usage). + * Value from 0-10. */ + INT32 nComplexity; + /** @brief Forward error correction. + * Corrects errors if there's packetloss. */ + TTBOOL bFEC; + /** @brief Discontinuous transmission. + * Enables "null" packets during silence. */ + TTBOOL bDTX; + /** @brief Bitrate for encoded audio. Should be between + * #OPUS_MIN_BITRATE and #OPUS_MAX_BITRATE. */ + INT32 nBitRate; + /** @brief Enable variable bitrate. */ + TTBOOL bVBR; + /** @brief Enable constrained VBR. + * @c bVBR must be enabled to enable this. */ + TTBOOL bVBRConstraint; + /** @brief Duration of audio before each transmission. Minimum is 2 msec. + * Recommended is 40 msec. Maximum is 500 msec. + * + * The #SoundSystem must be able to process audio packets at + * this interval. In most cases this makes less than 40 msec + * transmission interval unfeasible. */ + INT32 nTxIntervalMSec; + /** @brief OPUS supports 2.5, 5, 10, 20, 40, 60, 80, 100 and 120 msec. + * If @c nFrameSizeMSec is 0 then @c nFrameSizeMSec will be same as + * @c nTxIntervalMSec. */ + INT32 nFrameSizeMSec; + } OpusCodec; + +/** @brief Audio encoding is for VoIP. This value should be set as + * nApplicaton in #OpusCodec. */ +#define OPUS_APPLICATION_VOIP 2048 +/** @brief Audio encoding is for music. This value should be set as + * nApplicaton in #OpusCodec. */ +#define OPUS_APPLICATION_AUDIO 2049 +/** @brief The minimum bitrate for OPUS codec. Checkout @c nBitRate of + * #OpusCodec. */ +#define OPUS_MIN_BITRATE 6000 +/** @brief The maximum bitrate for OPUS codec. Checkout @c nBitRate of + * #OpusCodec. */ +#define OPUS_MAX_BITRATE 510000 +/** @brief The minimum frame size for OPUS codec. Checkout @c nFrameSizeMSec + * of #OpusCodec. */ +#define OPUS_MIN_FRAMESIZE 2 /* Actually it's 2.5 */ +/** @brief The maximum frame size for OPUS codec. Checkout @c nFrameSizeMSec + * of #OpusCodec. */ +#define OPUS_MAX_FRAMESIZE 60 +/** @brief The real maximum frame size for OPUS codec. Checkout @c nFrameSizeMSec + * of #OpusCodec. Although OPUS states it only supports 2.5 - 60 msec, it actually + * support up to 120 msec. */ +#define OPUS_REALMAX_FRAMESIZE 120 + + /** @brief Speex DSP is used for specifying how recorded audio + * from a sound input device should be preprocessed before + * transmission. + * + * @deprecated Use #WebRTCAudioPreprocessor. + * + * Users' audio levels may be diffent due to how their microphone + * is configured in their OS. Automatic Gain Control (AGC) can be + * used to ensure all users in the same channel have the same + * audio level. + * + * Enable the preprocessing configuration by calling + * TT_SetSoundInputPreprocess(). + * + * When joining a #Channel and @c bEnableGainControl of + * #AudioConfig is enabled in the channel then enable sound input + * preprocessing by setting @c bEnableAGC to TRUE and @c + * nGainLevel of #SpeexDSP to the @c nGainLevel of + * #AudioConfig. */ + typedef struct SpeexDSP + { + /** @brief Whether to enable AGC with the settings specified + * @a nGainLevel, @a nMaxIncDBSec, @a nMaxDecDBSec and @a + * nMaxGainDB. + * + * Note that AGC is not supported on ARM (iOS and Android), + * since there's no fixed point implementation of AGC in + * SpeexDSP. */ + TTBOOL bEnableAGC; + /** @brief A value from 0 to 32768. Default is 8000. + * Value is ignored if @a bEnableAGC is FALSE. */ + INT32 nGainLevel; + /** @brief Used so volume should not be amplified too quickly + * (maximal gain increase in dB/second). Default is 12. + * * Value is ignored if @a bEnableAGC is FALSE. */ + INT32 nMaxIncDBSec; + /** @brief Used so volume should not be attenuated + * too quickly (maximal gain decrease in dB/second). + * Negative value! Default is -40. + * Value is ignored if @a bEnableAGC is FALSE. */ + INT32 nMaxDecDBSec; + /** @brief Ensure volume doesn't become too loud (maximal gain + * in dB). Default is 30. + * Value is ignored if @a bEnableAGC is FALSE. */ + INT32 nMaxGainDB; + /** @brief Whether clients who join the channel should automatically + * enable denoising. */ + TTBOOL bEnableDenoise; + /** @brief Maximum attenuation of the noise in dB. + * Negative value! Default value is -30. + * Value is ignored if @a bEnableDenoise is FALSE. */ + INT32 nMaxNoiseSuppressDB; + /** @brief Enable/disable acoustic echo cancellation (AEC). + * + * In order to enable echo cancellation mode the local client + * instance must first be set in sound duplex mode by calling + * TT_InitSoundDuplexDevices(). This is because the echo canceller + * must first mixed all audio streams into a single stream and + * have then run in synch with the input stream. After calling + * TT_InitSoundDuplexDevices() the flag #CLIENT_SNDINOUTPUT_DUPLEX + * will be set. + * + * For echo cancellation to work the sound input and output device + * must be the same sound card since the input and output stream + * must be completely synchronized. Also it is recommended to also + * enable denoising and AGC for better echo cancellation. */ + TTBOOL bEnableEchoCancellation; + /** @brief Set maximum attenuation of the residual echo in dB + * (negative number). Default is -40. + * Value is ignored if @a bEnableEchoCancellation is FALSE. */ + INT32 nEchoSuppress; + /** @brief Set maximum attenuation of the residual echo in dB + * when near end is active (negative number). Default is -15. + * Value is ignored if @a bEnableEchoCancellation is FALSE. */ + INT32 nEchoSuppressActive; + } SpeexDSP; + + /** @brief Use TeamTalk's internal audio preprocessor for gain + * audio. Same as used for TT_SetSoundInputGainLevel(). */ + typedef struct TTAudioPreprocessor + { + /** @brief Gain level between #SOUND_GAIN_MIN and + * #SOUND_GAIN_MAX. Default is #SOUND_GAIN_DEFAULT (no + * gain). */ + INT32 nGainLevel; + /** @brief Whether to mute left speaker in stereo playback. */ + TTBOOL bMuteLeftSpeaker; + /** @brief Whether to mute right speaker in stereo playback. */ + TTBOOL bMuteRightSpeaker; + } TTAudioPreprocessor; + + /** @brief WebRTC's audio preprocessor. + * + * Use WebRTC's audio preprocessor, https://webrtc.org + * + * Note that WebRTC's can only operate on 10 msec audio frame, so + * @c nTxIntervalMSec in #AudioCodec must a multiple of 10. + * + * #WebRTCAudioPreprocessor is recommended to + * TT_SetSoundDeviceEffects() on desktop platforms. + * + * Activate #WebRTCAudioPreprocessor by calling + * TT_SetSoundInputPreprocessEx(). */ + typedef struct WebRTCAudioPreprocessor + { + /** @brief Configuration of WebRTC pre-amplifier. */ + struct + { + /** @brief Enable pre-amplifier. Replacement for + * TT_SetSoundInputGainLevel() */ + TTBOOL bEnable; + /** @brief Gain factor. Default: 1. */ + float fFixedGainFactor; + } preamplifier; + /** @brief Configuration of WebRTC's echo canceller. See also + * TT_SetSoundDeviceEffects() */ + struct + { + /** @brief Enable WebRTC echo canceller. The WebRTC echo + * canceller requires sound input and output devices are + * initialized using TT_InitSoundDuplexDevices(). This is + * because both input and output device must use the same + * sample rate. */ + TTBOOL bEnable; + } echocanceller; + /** @brief Configuration of WebRTC's noise suppression. See + * also #SpeexDSP. */ + struct + { + /** @brief Enable WebRTC noise suppression. */ + TTBOOL bEnable; + /** @brief Noise suppression level. 0 = Low, 1 = Moderate, + * 2 = High, 3 = VeryHigh. Default: 1. */ + INT32 nLevel; + } noisesuppression; + /** @brief Configuration of WebRTC's voice detection. */ + struct + { + /** @brief Use WebRTC's voice detection to trigger + * #CLIENTEVENT_VOICE_ACTIVATION. + * + * TT_EnableVoiceActivation() must still be called to + * activate voice detection event + * #CLIENTEVENT_VOICE_ACTIVATION. + * + * Enabling WebRTC's voice detection invalidates use of + * TT_SetVoiceActivationLevel() */ + TTBOOL bEnable; + } voicedetection; + /** @brief Configuration of WebRTC's gain controller 2 for + * AGC. */ + struct + { + /** @brief Enable WebRTC's fixed digital gain. WebRTC's + * automatic gain control (AGC) */ + TTBOOL bEnable; + /** @brief Gain level for AGC. Only active when @c bEnable + * is true. */ + struct + { + /** @brief Gain level in dB. Range: 0 <= x < 50. Default: + * 0. */ + float fGainDB; + } fixeddigital; + /** @brief Configuration for fine tuning gain level. */ + struct + { + /* @brief Enable saturation protector where saturation + * margin is 2 dB. */ + TTBOOL bEnable; + /* Range: 0 <= x <= 100. Default: 20 dB */ + float fInitialSaturationMarginDB; + /* Range: 0 <= x <= 100. Default: 2 dB */ + float fExtraSaturationMarginDB; + /* Range: 0 < x < infinite. Default: 3 dB/sec */ + float fMaxGainChangeDBPerSecond; + /* Range: -infinite < x < 0. Default: -50 */ + float fMaxOutputNoiseLevelDBFS; + } adaptivedigital; + } gaincontroller2; + /** @brief Configuration of WebRTC's level estimater. */ + struct + { + /** @brief Enable level estimater. When enabled + * TT_GetSoundInputLevel() will return a value based on + * WebRTC's level estimater. A WebRTC level estimater + * value of 0 will result in #SOUND_VU_MAX and level + * estimater value of 127 will return #SOUND_VU_MIN. */ + TTBOOL bEnable; + } levelestimation; + } WebRTCAudioPreprocessor; + +/** @brief Max value for fGainDB in #WebRTCAudioPreprocessor's @c gaincontroller2 */ +#define WEBRTC_GAINCONTROLLER2_FIXEDGAIN_MAX 49.9f + + /** @brief The types of supported audio preprocessors. + * + * @see TT_InitLocalPlayback() */ + typedef enum AudioPreprocessorType + { + /** @brief Value for specifying that no audio preprocessing + * should occur. */ + NO_AUDIOPREPROCESSOR = 0, + /** @brief Use the #SpeexDSP audio preprocessor. */ + SPEEXDSP_AUDIOPREPROCESSOR = 1, + /** @brief Use TeamTalk's internal audio preprocessor #TTAudioPreprocessor. */ + TEAMTALK_AUDIOPREPROCESSOR = 2, + /** @brief Use WebRTC's audio preprocessor from + * #WebRTCAudioPreprocessor. https://webrtc.org */ + WEBRTC_AUDIOPREPROCESSOR = 3, + } AudioPreprocessorType; + + /** @brief Configure the audio preprocessor specified by @c nPreprocessor. */ + typedef struct AudioPreprocessor + { + /** @brief The audio preprocessor to use in the union of audio preprocessors. */ + AudioPreprocessorType nPreprocessor; + union + { + /** @brief Used when @c nPreprocessor is #SPEEXDSP_AUDIOPREPROCESSOR. */ + SpeexDSP speexdsp; + /** @brief Used when @c nPreprocessor is #TEAMTALK_AUDIOPREPROCESSOR. */ + TTAudioPreprocessor ttpreprocessor; + /** @brief Used when @c nPreprocessor is #WEBRTC_AUDIOPREPROCESSOR. */ + WebRTCAudioPreprocessor webrtc; + }; + } AudioPreprocessor; + + /** @brief WebM video codec settings. + * @see VideoCodec + * @see TT_InitVideoCaptureDevice + * @see TT_StartStreamingMediaFileToChannel() */ + typedef struct WebMVP8Codec + { + union + { + /** @brief Same as @c rc_target_bitrate */ + INT32 nRcTargetBitrate; + /** @brief Target bitrate in kbits/sec. This value must be + * greater than 0. + * + * Same as 'rc_target_bitrate' in 'vpx_codec_enc_cfg_t'. + * http://www.webmproject.org/docs/webm-sdk/ */ + UINT32 rc_target_bitrate; + }; + /** @brief Time that should be spent on encoding a frame. + * + * Same as 'deadline' parameter in 'vpx_codec_encode()'. + * http://www.webmproject.org/docs/webm-sdk/ + * + * Supported values are VPX_DL_REALTIME = 1, VPX_DL_GOOD_QUALITY = 1000000, + * and VPX_DL_BEST_QUALITY = 0. */ + UINT32 nEncodeDeadline; + } WebMVP8Codec; + +/** @brief @c nEncodeDeadline value for fastest encoding. + * @see WebMVP8Codec */ +#define WEBM_VPX_DL_REALTIME 1 +/** @brief @c nEncodeDeadline value for good encoding. + * @see WebMVP8Codec */ +#define WEBM_VPX_DL_GOOD_QUALITY 1000000 +/** @brief @c nEncodeDeadline value for best encoding. + * @see WebMVP8Codec */ +#define WEBM_VPX_DL_BEST_QUALITY 0 + + /** @brief The codecs supported. + * @see AudioCodec + * @see VideoCodec */ + typedef enum Codec + { + /** @brief No codec specified. */ + NO_CODEC = 0, + /** @brief Speex audio codec, http://www.speex.org @see + * SpeexCodec */ + SPEEX_CODEC = 1, + /** @brief Speex audio codec in VBR mode, http://www.speex.org + * @see SpeexVBRCodec */ + SPEEX_VBR_CODEC = 2, + /** @brief OPUS audio codec. @see OpusCodec */ + OPUS_CODEC = 3, + /** @brief WebM video codec. @see WebMVP8Codec */ + WEBM_VP8_CODEC = 128, + } Codec; + + /** @brief Struct used for specifying which audio codec a channel + * uses. */ + typedef struct AudioCodec + { + /** @brief Specifies whether the member @a speex, @a speex_vbr or + * @a opus holds the codec settings. */ + Codec nCodec; + union + { + /** @brief Speex codec settings if @a nCodec is + * #SPEEX_CODEC */ + SpeexCodec speex; + /** @brief Speex codec settings if @a nCodec is + * #SPEEX_VBR_CODEC */ + SpeexVBRCodec speex_vbr; + /** @brief Opus codec settings if @a nCodec is + * OPUS_CODEC */ + OpusCodec opus; + }; + } AudioCodec; + + /** @brief Audio configuration for clients in a channel. + * + * An audio configuration can be used to set common audio + * properties for all users in a channel. Checkout @c audiocfg of + * #Channel. + * + * The audio configuration only supports same audio level + * for all users by manually converting the values to the + * selected #AudioPreprocessor. + * + * @see TT_SetSoundInputPreprocessEx() + * @see TT_DoMakeChannel() + * @see TT_DoJoinChannel() */ + typedef struct AudioConfig + { + /** @brief Users should enable automatic gain control. */ + TTBOOL bEnableAGC; + /** @brief Reference gain level to be used by all users. */ + INT32 nGainLevel; + } AudioConfig; + + /** @brief Struct used for specifying the video codec to use. */ + typedef struct VideoCodec + { + /** @brief Specifies member holds the codec settings. So far + * there is only one video codec to choose from, namely @c + * webm_vp8. */ + Codec nCodec; + union + { + WebMVP8Codec webm_vp8; + }; + } VideoCodec; + /** @} */ + + /** @addtogroup mediastream + * @{ */ + + /** + * @brief Struct describing the audio and video format used by a + * media file. + * + * @see TT_GetMediaFile() */ + typedef struct MediaFileInfo + { + /** @brief Status of media file if it's being saved to + * disk. */ + MediaFileStatus nStatus; + /** @brief Name of file. */ + TTCHAR szFileName[TT_STRLEN]; + /** @brief The audio properties of the media file. */ + AudioFormat audioFmt; + /** @brief The video properties of the media file. */ + VideoFormat videoFmt; + /** @brief The duration of the media file in miliseconds. */ + UINT32 uDurationMSec; + /** @brief The elapsed time of the media file in miliseconds. */ + UINT32 uElapsedMSec; + } MediaFileInfo; + + /** + * @brief Properties for initializing or updating a file for media + * streaming. + * + * @see TT_InitLocalPlayback() + * @see TT_UpdateLocalPlayback() + * @see TT_StartStreamingMediaFileToChannelEx() + * @see TT_UpdateStreamingMediaFileToChannel() */ + typedef struct MediaFilePlayback + { + /** @brief Offset in milliseconds in the media file where to + * start playback. Pass #TT_MEDIAPLAYBACK_OFFSET_IGNORE to + * ignore this value when using TT_UpdateLocalPlayback() or + * TT_UpdateStreamingMediaFileToChannel(). @c uOffsetMSec + * must be less than @c uDurationMSec in #MediaFileInfo. */ + UINT32 uOffsetMSec; + /** @brief Start or pause media file playback. */ + TTBOOL bPaused; + /** @brief Option to activate audio preprocessor on local media file playback. */ + AudioPreprocessor audioPreprocessor; + } MediaFilePlayback; + + /** @brief The progress of the audio currently being processed as + * audio input. @see TT_InsertAudioBlock() */ + typedef struct AudioInputProgress + { + /** @brief The stream ID provided in the #AudioBlock. */ + INT32 nStreamID; + /** @brief The duration of the audio currently queued for + * transmission. */ + UINT32 uQueueMSec; + /** @brief The duration of the audio that has been + * transmitted. */ + UINT32 uElapsedMSec; + } AudioInputProgress; + + /** @} */ + + /** @addtogroup server + * @{ */ + + /** + * @brief The rights users have once they have logged on to the + * server. + * + * #ServerProperties holds the user rights in its \a uUserRights + * member variable and is retrieved by calling + * #TT_GetServerProperties once connected to the server. + * + * @see ServerProperties + * @see TT_GetServerProperties */ + typedef enum UserRight + { + /** @brief Users who log onto the server has none of the + * rights below. */ + USERRIGHT_NONE = 0x00000000, + /** @brief Allow multiple users to log on to the server with + * the same #UserAccount. @see TT_DoLogin() */ + USERRIGHT_MULTI_LOGIN = 0x00000001, + /** @brief User can see users in all other channels. */ + USERRIGHT_VIEW_ALL_USERS = 0x00000002, + /** @brief User is allowed to create temporary channels which + * disappear when last user leaves the channel. + * @see TT_DoJoinChannel() */ + USERRIGHT_CREATE_TEMPORARY_CHANNEL = 0x00000004, + /** @brief User is allowed to create permanent channels which + * are stored in the server's configuration file. + * @see TT_DoMakeChannel() */ + USERRIGHT_MODIFY_CHANNELS = 0x00000008, + /** @brief User can broadcast text message of type + * #MSGTYPE_BROADCAST to all users. */ + USERRIGHT_TEXTMESSAGE_BROADCAST = 0x00000010, + /** @brief User can kick users off the server. @see TT_DoKickUser() */ + USERRIGHT_KICK_USERS = 0x00000020, + /** @brief User can add and remove banned users. + * @see TT_DoBanUser() @see TT_DoListBans() */ + USERRIGHT_BAN_USERS = 0x00000040, + /** @brief User can move users from one channel to another. + * @see TT_DoMoveUser() */ + USERRIGHT_MOVE_USERS = 0x00000080, + /** @brief User can make other users channel operator. + * @see TT_DoChannelOp() */ + USERRIGHT_OPERATOR_ENABLE = 0x00000100, + /** @brief User can upload files to channels. @see TT_DoSendFile() */ + USERRIGHT_UPLOAD_FILES = 0x00000200, + /** @brief User can download files from channels. + * @see TT_DoRecvFile() */ + USERRIGHT_DOWNLOAD_FILES = 0x00000400, + /** @brief User can update server properties. + * @see TT_DoUpdateServer() */ + USERRIGHT_UPDATE_SERVERPROPERTIES = 0x00000800, + /** @brief Users are allowed to forward audio packets through + * server. TT_EnableVoiceTransmission() */ + USERRIGHT_TRANSMIT_VOICE = 0x00001000, + /** @brief User is allowed to forward video packets through + * server. TT_StartVideoCaptureTransmission() */ + USERRIGHT_TRANSMIT_VIDEOCAPTURE = 0x00002000, + /** @brief User is allowed to forward desktop packets through + * server. @see TT_SendDesktopWindow() */ + USERRIGHT_TRANSMIT_DESKTOP = 0x00004000, + /** @brief User is allowed to forward desktop input packets through + * server. @see TT_SendDesktopInput() */ + USERRIGHT_TRANSMIT_DESKTOPINPUT = 0x00008000, + /** @brief User is allowed to stream audio files to channel. + * @see TT_StartStreamingMediaFileToChannel() */ + USERRIGHT_TRANSMIT_MEDIAFILE_AUDIO = 0x00010000, + /** @brief User is allowed to stream video files to channel. + * @see TT_StartStreamingMediaFileToChannel() */ + USERRIGHT_TRANSMIT_MEDIAFILE_VIDEO = 0x00020000, + /** @brief User is allowed to stream media files to channel. + * @see TT_StartStreamingMediaFileToChannel() */ + USERRIGHT_TRANSMIT_MEDIAFILE = USERRIGHT_TRANSMIT_MEDIAFILE_VIDEO | USERRIGHT_TRANSMIT_MEDIAFILE_AUDIO, + /** @brief User's nick name is locked. + * TT_DoChangeNickname() cannot be used and TT_DoLogin() + * will ignore szNickname parameter. + * @see TT_DoLogin() + * @see TT_DoLoginEx() + * @see TT_DoChangeNickname() */ + USERRIGHT_LOCKED_NICKNAME = 0x00040000, + /** @brief User's status is locked. TT_DoChangeStatus() + * cannot be used. */ + USERRIGHT_LOCKED_STATUS = 0x00080000, + /** @brief User can record voice in all channels. Even channels + * with #CHANNEL_NO_RECORDING. */ + USERRIGHT_RECORD_VOICE = 0x00100000, + /** @brief User can see hidden channels, #CHANNEL_HIDDEN. */ + USERRIGHT_VIEW_HIDDEN_CHANNELS = 0x00200000 + } UserRight; + + /** + * @brief A bitmask based on #UserRight for holding the rights users + * have who log on the server. + * @see ServerProperties */ + typedef UINT32 UserRights; + + + /** + * @brief Events that are logged by the server, i.e. written to server's + * log file. + * + * @see ServerProperties + * @see TT_DoUpdateServer() */ + typedef enum ServerLogEvent + { + /** @brief Nothing is logged to file by server. */ + SERVERLOGEVENT_NONE = 0x00000000, + /** @brief User's IP-address is logged to file by serer. */ + SERVERLOGEVENT_USER_CONNECTED = 0x00000001, + /** @brief User disconnected from server is logged to file by the server. */ + SERVERLOGEVENT_USER_DISCONNECTED = 0x00000002, + /** @brief User logged in is logged to file by the server. */ + SERVERLOGEVENT_USER_LOGGEDIN = 0x00000004, + /** @brief User logged out is logged to file by the server. */ + SERVERLOGEVENT_USER_LOGGEDOUT = 0x00000008, + /** @brief User failed to log in is logged to file by the server.*/ + SERVERLOGEVENT_USER_LOGINFAILED = 0x00000010, + /** @brief User disconnected due to connection timeout is logged to file by the server. */ + SERVERLOGEVENT_USER_TIMEDOUT = 0x00000020, + /** @brief User was kicked is logged to file by the server. */ + SERVERLOGEVENT_USER_KICKED = 0x00000040, + /** @brief User was banned is logged to file by the server. */ + SERVERLOGEVENT_USER_BANNED = 0x00000080, + /** @brief User was removed from ban list is logged to file by the server. */ + SERVERLOGEVENT_USER_UNBANNED = 0x00000100, + /** @brief User's status is logged to file by the server. */ + SERVERLOGEVENT_USER_UPDATED = 0x00000200, + /** @brief User joined a channel is logged to file by the server. */ + SERVERLOGEVENT_USER_JOINEDCHANNEL = 0x00000400, + /** @brief User left a channel is logged to file by the server. */ + SERVERLOGEVENT_USER_LEFTCHANNEL = 0x00000800, + /** @brief User was moved to another channel is logged to file by the server. */ + SERVERLOGEVENT_USER_MOVED = 0x00001000, + /** @brief User's private text messages are logged to file by the server. */ + SERVERLOGEVENT_USER_TEXTMESSAGE_PRIVATE = 0x00002000, + /** @brief User's custom text messages are logged to file by the server. */ + SERVERLOGEVENT_USER_TEXTMESSAGE_CUSTOM = 0x00004000, + /** @brief User's channel text messages are logged to file by the server. */ + SERVERLOGEVENT_USER_TEXTMESSAGE_CHANNEL = 0x00008000, + /** @brief User's broadcast text messages are logged to file by the server. */ + SERVERLOGEVENT_USER_TEXTMESSAGE_BROADCAST = 0x00010000, + /** @brief User created new channel is logged to file by the server. */ + SERVERLOGEVENT_CHANNEL_CREATED = 0x00020000, + /** @brief User updated a channel is logged to file by the server. */ + SERVERLOGEVENT_CHANNEL_UPDATED = 0x00040000, + /** @brief User removed a channel is logged to file by the server. */ + SERVERLOGEVENT_CHANNEL_REMOVED = 0x00080000, + /** @brief User uploaded a file is logged to file by the server. */ + SERVERLOGEVENT_FILE_UPLOADED = 0x00100000, + /** @brief User downloaded a file is logged to file by the server. */ + SERVERLOGEVENT_FILE_DOWNLOADED = 0x00200000, + /** @brief User deleted a file is logged to file by the server. */ + SERVERLOGEVENT_FILE_DELETED = 0x00400000, + /** @brief User updated server's properties is logged to file by the server. */ + SERVERLOGEVENT_SERVER_UPDATED = 0x00800000, + /** @brief User saved server's configuration is logged to file by the server. */ + SERVERLOGEVENT_SERVER_SAVECONFIG = 0x01000000, + } ServerLogEvent; + + /** @brief Bitmask of #ServerLogEvent. + * @see ServerProperties */ + typedef UINT32 ServerLogEvents; + + /** + * @brief A struct containing the properties of the server's + * settings. + * + * The server properties is available after a successful call to + * #TT_DoLogin + * + * @see TT_DoUpdateServer + * @see TT_GetServerProperties + * @see TT_Login + * @see UserRight */ + typedef struct ServerProperties + { + /** @brief The server's name. */ + TTCHAR szServerName[TT_STRLEN]; + /** @brief The message of the day. Read-only property. Use @c szMOTDRaw + * to update this property.*/ + TTCHAR szMOTD[TT_STRLEN]; + /** @brief The message of the day including variables. The result of the + * szMOTDRaw string will be displayed in @c szMOTD. + * When updating the MOTD the variables %users% (number of users), + * %admins% (number + * of admins), %uptime% (hours, minutes and seconds the server has + * been online), %voicetx% (KBytes transmitted), %voicerx% (KBytes + * received) and %lastuser% (nickname of last user to log on to the + * server) as part of the MOTD. */ + TTCHAR szMOTDRaw[TT_STRLEN]; + /** @brief The maximum number of users allowed on the server. A user + * with admin account can ignore this. */ + INT32 nMaxUsers; + /** @brief The maximum number of logins with wrong password before + * banning user's IP-address. */ + INT32 nMaxLoginAttempts; + /** @brief The maximum number of users allowed to log in with the same + * IP-address. 0 means disabled. */ + INT32 nMaxLoginsPerIPAddress; + /** @brief The maximum number of bytes per second which the server + * will allow for voice packets. If this value is exceeded the server + * will start dropping audio packets. 0 = disabled. */ + INT32 nMaxVoiceTxPerSecond; + /** @brief The maximum number of bytes per second which the + * server will allow for video input packets. If this value is + * exceeded the server will start dropping video packets. 0 = + * disabled. */ + INT32 nMaxVideoCaptureTxPerSecond; + /** @brief The maximum number of bytes per second which the server + * will allow for media file packets. If this value is exceeded the server + * will start dropping media file packets. 0 = disabled. */ + INT32 nMaxMediaFileTxPerSecond; + /** @brief The maximum number of bytes per second which the server + * will allow for desktop packets. If this value is exceeded the server + * will start dropping desktop packets. 0 = disabled. */ + INT32 nMaxDesktopTxPerSecond; + /** @brief The amount of bytes per second which the server + * will allow for packet forwarding. If this value is exceeded the server + * will start dropping packets. 0 = disabled. */ + INT32 nMaxTotalTxPerSecond; + /** @brief Whether the server automatically saves changes */ + TTBOOL bAutoSave; + /** @brief The server's TCP port. */ + INT32 nTcpPort; + /** @brief The server's UDP port. */ + INT32 nUdpPort; + /** @brief The number of seconds before a user who hasn't + * responded to keepalives will be kicked off the server. */ + INT32 nUserTimeout; + /** @brief The server version. Read-only property. */ + TTCHAR szServerVersion[TT_STRLEN]; + /** @brief The version of the server's protocol. Read-only + * property. */ + TTCHAR szServerProtocolVersion[TT_STRLEN]; + /** @brief Number of msec before an IP-address can make + * another login attempt. If less than this amount then + * TT_DoLogin() will result in + * #CMDERR_MAX_LOGINS_PER_IPADDRESS_EXCEEDED. Zero means + * disabled. + * + * Also checkout @c nMaxLoginAttempts and @c + * nMaxLoginsPerIPAddress. */ + INT32 nLoginDelayMSec; + /** @brief A randomly generated 256 bit access token created + * by the server to identify the login session. + * + * The szAccessToken is available after receiving + * #CLIENTEVENT_CON_SUCCESS. + * + * Read-only property. */ + TTCHAR szAccessToken[TT_STRLEN]; + /** @brief The events that are logged on the server. + * + * @c uServerLogEvents is set after + * #CLIENTEVENT_CMD_SERVER_UPDATE during login. + * @see TT_DoLogin() */ + ServerLogEvents uServerLogEvents; + } ServerProperties; + + /** + * @brief A struct containing the server's statistics, + * i.e. bandwidth usage and user activity. + * + * Use TT_DoQueryServerStats() to query the server's statistics. */ + typedef struct ServerStatistics + { + /** @brief The number of bytes sent from the server to + * clients. */ + INT64 nTotalBytesTX; + /** @brief The number of bytes received by the server from + * clients. */ + INT64 nTotalBytesRX; + /** @brief The number of bytes in audio packets sent from the + * server to clients. */ + INT64 nVoiceBytesTX; + /** @brief The number of bytes in audio packets received by + * the server from clients. */ + INT64 nVoiceBytesRX; + /** @brief The number of bytes in video packets sent from the + * server to clients. */ + INT64 nVideoCaptureBytesTX; + /** @brief The number of bytes in video packets received by + * the server from clients. */ + INT64 nVideoCaptureBytesRX; + /** @brief The number of bytes in media file packets sent from the + * server to clients. */ + INT64 nMediaFileBytesTX; + /** @brief The number of bytes in media file packets received by + * the server from clients. */ + INT64 nMediaFileBytesRX; + /** @brief The number of bytes in desktop packets sent from the + * server to clients. */ + INT64 nDesktopBytesTX; + /** @brief The number of bytes in desktop packets received by + * the server from clients. */ + INT64 nDesktopBytesRX; + /** @brief The number of users who have logged on to the server. */ + INT32 nUsersServed; + /** @brief The highest numbers of users online. */ + INT32 nUsersPeak; + /** @brief The number of bytes for file transmission transmitted + * from the server. */ + INT64 nFilesTx; + /** @brief The number of bytes for file transmission received + * by the server. */ + INT64 nFilesRx; + /** @brief The server's uptime in msec. */ + INT64 nUptimeMSec; + } ServerStatistics; + + /** + * @brief Way to ban a user from either login or joining a + * channel. + * + * @see BannedUser */ + typedef enum BanType + { + /** @brief Ban type not set. */ + BANTYPE_NONE = 0x00, + /** @brief The ban applies to the channel specified in the @c + * szChannel of #BannedUser. Otherwise the ban applies to the + * entire server. */ + BANTYPE_CHANNEL = 0x01, + /** @brief Ban @c szIPAddress specified in #BannedUser. */ + BANTYPE_IPADDR = 0x02, + /** @brief Ban @c szUsername specified in #BannedUser. */ + BANTYPE_USERNAME = 0x04 + } BanType; + + /** @brief A mask of types of bans that apply. @see #BanType */ + typedef UINT32 BanTypes; + + /** + * @brief A struct containing the properties of a banned user. + * @see TT_DoListBans() + * @see TT_DoBanUserEx() */ + typedef struct BannedUser + { + /** @brief IP-address of banned user. */ + TTCHAR szIPAddress[TT_STRLEN]; + /** @brief Channel where user was located when banned. */ + TTCHAR szChannelPath[TT_STRLEN]; + /** @brief Date and time when user was banned. Read-only property. + * Date/time is converted local time. */ + TTCHAR szBanTime[TT_STRLEN]; + /** @brief Nickname of banned user. Read-only property. */ + TTCHAR szNickname[TT_STRLEN]; + /** @brief Username of banned user. */ + TTCHAR szUsername[TT_STRLEN]; + /** @brief The type of ban that applies to this banned user. */ + BanTypes uBanTypes; + } BannedUser; + + /** @ingroup users + * @brief The types of users supported. + * @see User @see UserAccount */ + typedef enum UserType + { + /** @brief Used internally to denote an unauthenticated + * user. */ + USERTYPE_NONE = 0x0, + /** @brief A default user who can join channels. */ + USERTYPE_DEFAULT = 0x01, + /** @brief A user with administrator privileges. */ + USERTYPE_ADMIN = 0x02 + } UserType; + + /** @ingroup users + * @brief A bitmask based on #UserType describing the user type. + * @see UserType */ + typedef UINT32 UserTypes; + + /** + * @brief Properties to prevent server abuse. + * + * The AbusePrevention-struct is part of #UserAccount and can be + * used to limit the number of commands a user can issue to the + * server. + * + * Requires TeamTalk version 5.2.3.4896. */ + typedef struct AbusePrevention + { + /** @brief Limit number of commands a user can send to the + * server. + * + * This can be used to prevent flooding where a user is + * sending several hundred text messages to another user. + * + * Values set like this: User can issue @c nCommandsLimit + * commands within duration @c nCommandsIntervalMSec. Put zeros to + * disable. @see CMDERR_COMMAND_FLOOD */ + INT32 nCommandsLimit; + /** @brief Commands within given interval. */ + INT32 nCommandsIntervalMSec; + } AbusePrevention; + + /** + * @brief A struct containing the properties of a user account. + * + * A registered user is one that has a user account on the server. + * + * @see TT_DoListUserAccounts + * @see TT_DoNewUserAccount + * @see TT_DoDeleteUserAccount */ + typedef struct UserAccount + { + /** @brief The account's username. */ + TTCHAR szUsername[TT_STRLEN]; + /** @brief The account's password. */ + TTCHAR szPassword[TT_STRLEN]; + /** @brief A bitmask of the type of user based on #UserType. */ + UserTypes uUserType; + /** @brief A bitmask based on #UserRight which specifies the rights + * the user have who logs onto the server. A user of type + * #USERTYPE_ADMIN by default has all rights. */ + UserRights uUserRights; + /** @brief A user data field which can be used for additional + * information. The @a nUserData field of the #User struct will + * contain this value when a user who logs in with this account. */ + INT32 nUserData; + /** @brief Additional notes about this user. */ + TTCHAR szNote[TT_STRLEN]; + /** @brief User should (manually) join this channel after login. + * If an initial channel is specified in the user's account then + * no password is required for the user to join the channel. + * @see TT_DoJoinChannel() */ + TTCHAR szInitChannel[TT_STRLEN]; + /** @brief Channels where this user will automatically become channel + * operator when joining. The channels must be of type #CHANNEL_PERMANENT. + * @see TT_DoChannelOp() */ + INT32 autoOperatorChannels[TT_CHANNELS_OPERATOR_MAX]; + /** @brief Bandwidth restriction for audio codecs created by + * this user. This value will hold the highest bitrate which + * is allowed for audio codecs. 0 = no limit. @see AudioCodec */ + INT32 nAudioCodecBpsLimit; + /** @brief Properties which can be set to prevent abuse of a + * server, e.g. limit number of commands issued. + * + * Requires TeamTalk version 5.2.3.4896. */ + AbusePrevention abusePrevent; + /** @brief Timestamp of last modification of user account. + * Date/time is converted local time. */ + TTCHAR szLastModified[TT_STRLEN]; + } UserAccount; + /** @} */ + + /** @addtogroup users + * @{ */ + + /** + * @brief A user by default accepts audio, video and text messages + * from all users. Using subscribtions can, however, change what + * the local client instance is willing to accept from other + * users. + * + * By calling #TT_DoSubscribe and #TT_DoUnsubscribe the local + * client instance can tell the server (and thereby remote users) + * what he is willing to accept from other users. + * + * To check what a user subscribes to check out the #User struct's + * @a uLocalSubscriptions. The subscriptions with the prefix + * @c SUBSCRIBE_INTERCEPT_* options can be used to spy on users and + * receive data from them even if one is not participating in the + * same channel as they are. + * + * @see TT_DoSubscribe + * @see TT_DoUnsubscribe */ + typedef enum Subscription + { + /** @brief No subscriptions. */ + SUBSCRIBE_NONE = 0x00000000, + /** @brief Subscribing to user text messages. + * @see #MSGTYPE_USER. */ + SUBSCRIBE_USER_MSG = 0x00000001, + /** @brief Subscribing to channel texxt messages. + * @see #MSGTYPE_CHANNEL. */ + SUBSCRIBE_CHANNEL_MSG = 0x00000002, + /** @brief Subscribing to broadcast text messsages. + * @see #MSGTYPE_BROADCAST.*/ + SUBSCRIBE_BROADCAST_MSG = 0x00000004, + /** @brief Subscribing to custom user messages. + * @see #MSGTYPE_CUSTOM. */ + SUBSCRIBE_CUSTOM_MSG = 0x00000008, + /** @brief Subscribing to #STREAMTYPE_VOICE. */ + SUBSCRIBE_VOICE = 0x00000010, + /** @brief Subscribing to #STREAMTYPE_VIDEOCAPTURE. */ + SUBSCRIBE_VIDEOCAPTURE = 0x00000020, + /** @brief Subscribing to #STREAMTYPE_DESKTOP. */ + SUBSCRIBE_DESKTOP = 0x00000040, + /** @brief Subscribing to #STREAMTYPE_DESKTOPINPUT. + * @see TT_GetUserDesktopInput() + * @see TT_SendDesktopInput() */ + SUBSCRIBE_DESKTOPINPUT = 0x00000080, + /** @brief Subscribing to #STREAMTYPE_MEDIAFILE_VIDEO and + * #STREAMTYPE_MEDIAFILE_AUDIO. */ + SUBSCRIBE_MEDIAFILE = 0x00000100, + /** @brief Intercept all user text messages sent by a + * user. Only user-type #USERTYPE_ADMIN can do this. */ + SUBSCRIBE_INTERCEPT_USER_MSG = 0x00010000, + /** @brief Intercept all channel messages sent by a user. Only + * user-type #USERTYPE_ADMIN can do this. */ + SUBSCRIBE_INTERCEPT_CHANNEL_MSG = 0x00020000, + /* unused SUBSCRIBE_INTERCEPT_BROADCAST_MSG = 0x00040000 */ + /** @brief Intercept all custom text messages sent by user. + * Only user-type #USERTYPE_ADMIN can do this. */ + SUBSCRIBE_INTERCEPT_CUSTOM_MSG = 0x00080000, + /** @brief Intercept all voice sent by a user. Only user-type + * #USERTYPE_ADMIN can do this. By enabling this subscription an + * administrator can listen to audio sent by users outside his + * own channel. */ + SUBSCRIBE_INTERCEPT_VOICE = 0x00100000, + /** @brief Intercept all video sent by a user. Only user-type + * #USERTYPE_ADMIN can do this. By enabling this subscription an + * administrator can receive video frames sent by users + * outside his own channel. */ + SUBSCRIBE_INTERCEPT_VIDEOCAPTURE = 0x00200000, + /** @brief Intercept all desktop data sent by a user. Only + * user-type #USERTYPE_ADMIN can do this. By enabling this + * subscription an administrator can views desktops + * sent by users outside his own channel. */ + SUBSCRIBE_INTERCEPT_DESKTOP = 0x00400000, + /* unused SUBSCRIBE_INTERCEPT_DESKTOPINPUT = 0x00800000, */ + /** @brief Intercept all media file data sent by a user. Only user-type + * #USERTYPE_ADMIN can do this. By enabling this subscription an + * administrator can listen to media files sent by users outside his + * own channel. */ + SUBSCRIBE_INTERCEPT_MEDIAFILE = 0x01000000, + } Subscription; + + /** + * @brief A bitmask based on #Subscription describing which + * subscriptions are enabled. + * @see Subscription */ + typedef UINT32 Subscriptions; + + /** @brief The possible states for a user. Used for #User's @a + * uUserState variable. */ + typedef enum UserState + { + /** @brief The user is in initial state. */ + USERSTATE_NONE = 0x0000000, + /** @brief If set the user is currently talking. If this flag + * changes the event #CLIENTEVENT_USER_STATECHANGE is + * posted. */ + USERSTATE_VOICE = 0x00000001, + /** @brief If set the user's voice is muted. @see TT_SetUserMute */ + USERSTATE_MUTE_VOICE = 0x00000002, + /** @brief If set the user's media file playback is muted. + * @see TT_SetUserMute */ + USERSTATE_MUTE_MEDIAFILE = 0x00000004, + /** @brief If set the user currently has an active desktop + * session. If this flag changes the event + * #CLIENTEVENT_USER_STATECHANGE is posted. @see + * TT_SendDesktopWindow(). */ + USERSTATE_DESKTOP = 0x00000008, + /** @brief If set the user currently has an active video + * stream. If this flag changes the event + * #CLIENTEVENT_USER_STATECHANGE is posted. @see + * CLIENTEVENT_USER_VIDEOCAPTURE. */ + USERSTATE_VIDEOCAPTURE = 0x00000010, + /** @brief If set the user currently streams an audio file. If + * user is streaming a video file with audio then this value + * is also set. If this flag changes the event + * #CLIENTEVENT_USER_STATECHANGE is posted. @see + * TT_StartStreamingMediaFile() */ + USERSTATE_MEDIAFILE_AUDIO = 0x00000020, + /** @brief If set the user currently streams a video file. If + * this flag changes the event #CLIENTEVENT_USER_STATECHANGE + * is posted. @see TT_StartStreamingMediaFile() */ + USERSTATE_MEDIAFILE_VIDEO = 0x00000040, + /** @brief If set user is streaming a media file. If this + * flag changes the event #CLIENTEVENT_USER_STATECHANGE is + * posted. @see TT_StartStreamingMediaFile() */ + USERSTATE_MEDIAFILE = USERSTATE_MEDIAFILE_AUDIO | + USERSTATE_MEDIAFILE_VIDEO + } UserState; + + /** @brief A bitmask based on #UserState indicating a #User's current + * state. */ + typedef UINT32 UserStates; + + /** + * @brief A struct containing the properties of a user. + * @see UserType + * @see TT_GetUser */ + typedef struct User + { + /** @brief The user's ID. A value from 1 - + * #TT_USERID_MAX. This property is set by the server and will + * not change after login. */ + INT32 nUserID; + /** @brief The @a szUsername of the user's #UserAccount. A + * user account is created by calling + * TT_DoNewUserAccount(). This property is set by the server + * and will not change after login. */ + TTCHAR szUsername[TT_STRLEN]; + /** @brief The @a nUserData of the user's #UserAccount. This + * field can be use to denote e.g. a database ID. This + * property is set by the server and will not change after + * login.*/ + INT32 nUserData; + /** @brief The @a uUserType of the user's #UserAccount. This + * property is set by the server and will not change after + * login. */ + UserTypes uUserType; + /** @brief The user's IP-address. This value is set by the server. */ + TTCHAR szIPAddress[TT_STRLEN]; + /** @brief The user's client version. This property is set by + * the server and will not change after login. Three octets + * are used for the version number. Third octet is major, + * second octet is minor and third octet is + * build. I.e. 0x00050201 is version 5.2.1. */ + UINT32 uVersion; + /** @brief The channel which the user is currently + * participating in. 0 if none. This value can change as a + * result of TT_DoJoinChannel() or TT_DoLeaveChannel(). Events + * #CLIENTEVENT_CMD_USER_JOINED and #CLIENTEVENT_CMD_USER_LEFT + * are posted when this value changes. */ + INT32 nChannelID; + /** @brief A bitmask of what the local user subscribes to from + * this user. Invoking TT_DoSubscribe() and TT_DoUnsubscribe() + * on the local client instance can change this value. Event + * #CLIENTEVENT_CMD_USER_UPDATE is posted if this value + * changes. */ + Subscriptions uLocalSubscriptions; + /** @brief A bitmask of what this user subscribes to from + * local client instance. Invoking TT_DoSubscribe() and + * TT_DoUnsubscribe() on the remote client instance can change + * this value. Event #CLIENTEVENT_CMD_USER_UPDATE is posted if + * this value changes. */ + Subscriptions uPeerSubscriptions; + /** @brief The user's nickname. Invoking + * TT_DoChangeNickname() changes this value. Event + * #CLIENTEVENT_CMD_USER_UPDATE is posted if this value + * changes. */ + TTCHAR szNickname[TT_STRLEN]; + /** @brief The user's current status mode. Invoke + * TT_DoChangeStatus() to change this value. Event + * #CLIENTEVENT_CMD_USER_UPDATE is posted if this value + * changes. */ + INT32 nStatusMode; + /** @brief The user's current status message. Invoke + * TT_DoChangeStatus() to change this value. Event + * #CLIENTEVENT_CMD_USER_UPDATE is posted if this value + * changes. */ + TTCHAR szStatusMsg[TT_STRLEN]; + /** @brief A bitmask of the user's current state, + * e.g. talking, muted, etc. */ + UserStates uUserState; + /** @brief Store audio received from this user to this + * folder. @see TT_SetUserMediaStorageDir */ + TTCHAR szMediaStorageDir[TT_STRLEN]; + /** @brief The user's voice volume level. Note that it's a virtual + * volume which is being set since the master volume affects + * the user volume. The value will be between + * #SOUND_VOLUME_MIN and #SOUND_VOLUME_MAX + * @see TT_SetUserVolume */ + INT32 nVolumeVoice; + /** @brief The user's voice volume level. Note that it's a virtual + * volume which is being set since the master volume affects + * the user volume. The value will be between + * #SOUND_VOLUME_MIN and #SOUND_VOLUME_MAX + * @see TT_SetUserVolume */ + INT32 nVolumeMediaFile; + /** @brief The delay of when a user should no longer be + * considered as talking. + * @see TT_SetUserStoppedTalkingDelay */ + INT32 nStoppedDelayVoice; + /** @brief The delay of when a user should no longer be + * considered playing audio of a media file. + * @see TT_SetUserStoppedTalkingDelay */ + INT32 nStoppedDelayMediaFile; + /** @brief User's position when using 3D-sound (DirectSound option). + * Index 0 is x-axis, index 1 is y-axis and index 2 is Z-axis. + * @see TT_SetUserPosition() + * @see SoundDevice */ + float soundPositionVoice[3]; + /** @brief User's position when using 3D-sound (DirectSound option). + * Index 0 is x-axis, index 1 is y-axis and index 2 is Z-axis. + * @see TT_SetUserPosition() + * @see SoundDevice */ + float soundPositionMediaFile[3]; + /** @brief Check what speaker a user is outputting to. + * If index 0 is TRUE then left speaker is playing. If index 1 is + * TRUE then right speaker is playing. + * @see TT_SetUserStereo */ + TTBOOL stereoPlaybackVoice[2]; + /** @brief Check what speaker a user is outputting to. + * If index 0 is TRUE then left speaker is playing. If index 1 is + * TRUE then right speaker is playing. + * @see TT_SetUserStereo */ + TTBOOL stereoPlaybackMediaFile[2]; + /** @brief The size of the buffer (in msec) to hold voice + * content. + * @see TT_SetUserAudioStreamBufferSize() */ + INT32 nBufferMSecVoice; + /** @brief The size of the buffer (in msec) to hold media file + * content. + * @see TT_SetUserAudioStreamBufferSize() */ + INT32 nBufferMSecMediaFile; + /** @brief the currently active adaptive jitter delay for + received voice streams for this user. + * @see TT_SetUserJitterControl */ + INT32 nActiveAdaptiveDelayMSec; + /** @brief The name of the client application which the user + * is using. This is the value passed as @c szClientName in + * TT_DoLoginEx() */ + TTCHAR szClientName[TT_STRLEN]; + } User; + + /** + * @brief Packet reception and data statistics for a user. + * + * @see TT_GetUserStatistics */ + typedef struct UserStatistics + { + /** @brief Number of voice packets received from user. */ + INT64 nVoicePacketsRecv; + /** @brief Number of voice packets lost from user. */ + INT64 nVoicePacketsLost; + /** @brief Number of video packets received from user. A video + * frame can consist of several video packets. */ + INT64 nVideoCapturePacketsRecv; + /** @brief Number of video frames received from user. */ + INT64 nVideoCaptureFramesRecv; + /** @brief Video frames which couldn't be shown because packets were + * lost. */ + INT64 nVideoCaptureFramesLost; + /** @brief Number of video frames dropped because user application + * didn't retrieve video frames in time. */ + INT64 nVideoCaptureFramesDropped; + /** @brief Number of media file audio packets received from user. */ + INT64 nMediaFileAudioPacketsRecv; + /** @brief Number of media file audio packets lost from user. */ + INT64 nMediaFileAudioPacketsLost; + /** @brief Number of media file video packets received from user. + * A video frame can consist of several video packets. */ + INT64 nMediaFileVideoPacketsRecv; + /** @brief Number of media file video frames received from user. */ + INT64 nMediaFileVideoFramesRecv; + /** @brief Media file video frames which couldn't be shown because + * packets were lost. */ + INT64 nMediaFileVideoFramesLost; + /** @brief Number of media file video frames dropped because user + * application didn't retrieve video frames in time. */ + INT64 nMediaFileVideoFramesDropped; + } UserStatistics; + + /** + * @brief Text message types. + * + * The types of messages which can be passed to #TT_DoTextMessage(). + * + * @see TextMessage + * @see TT_DoTextMessage + * @see CLIENTEVENT_CMD_USER_TEXTMSG */ + typedef enum TextMsgType + { + /** @brief An incomplete text message */ + MSGTYPE_NONE = 0, + /** @brief A User to user text message. A message of this + * type can be sent across channels. */ + MSGTYPE_USER = 1, + /** @brief A User to channel text message. Users of type + * #USERTYPE_DEFAULT can only send this text message to the + * channel they're participating in, whereas users of type + * #USERTYPE_ADMIN can send to any channel. */ + MSGTYPE_CHANNEL = 2, + /** @brief A broadcast message. Requires + * #USERRIGHT_TEXTMESSAGE_BROADCAST. */ + MSGTYPE_BROADCAST = 3, + /** @brief A custom user to user text message. Works the same + * way as #MSGTYPE_USER. */ + MSGTYPE_CUSTOM = 4 + } TextMsgType; + + /** + * @brief A struct containing the properties of a text message + * sent by a user. + * + * @see CLIENTEVENT_CMD_USER_TEXTMSG + * @see TT_DoTextMessage */ + typedef struct TextMessage + { + /** @brief The type of text message. */ + TextMsgType nMsgType; + /** @brief Will be set automatically on outgoing message. */ + INT32 nFromUserID; + /** @brief The originators username. */ + TTCHAR szFromUsername[TT_STRLEN]; + /** @brief Set to zero if channel message. */ + INT32 nToUserID; + /** @brief Set to zero if @a nMsgType is #MSGTYPE_USER or + * #MSGTYPE_BROADCAST. */ + INT32 nChannelID; + /** @brief The actual text message. The message can be + * multi-line (include EOL). */ + TTCHAR szMessage[TT_STRLEN]; + /** @brief Whether this text message is to be merged with next + * text message. */ + TTBOOL bMore; + } TextMessage; + /** @} */ + + /** @addtogroup channels + * @{ */ + + /** + * @brief The types of channels supported. @see Channel */ + typedef enum ChannelType + { + /** @brief A default channel is a channel which disappears + * after the last user leaves the channel. */ + CHANNEL_DEFAULT = 0x0000, + /** @brief A channel which persists even when the last user + * leaves the channel. */ + CHANNEL_PERMANENT = 0x0001, + /** @brief Only one user can transmit at a time. */ + CHANNEL_SOLO_TRANSMIT = 0x0002, + /** @brief Voice and video transmission in the channel is + * controlled by a channel operator. + * + * For a user to transmit audio or video to this type of + * channel the channel operator must add the user's ID to @c + * transmitUsers in the #Channel struct and call + * TT_DoUpdateChannel(). + * + * @see TT_IsChannelOperator + * @see #USERTYPE_ADMIN */ + CHANNEL_CLASSROOM = 0x0004, + /** @brief Only channel operators (and administrators) will receive + * audio/video/desktop transmissions. Default channel users + * will only see transmissions from operators and/or + * administrators. */ + CHANNEL_OPERATOR_RECVONLY = 0x0008, + /** @brief Don't allow voice transmission if it's trigged by + * voice activation. @see TT_EnableVoiceActivation() */ + CHANNEL_NO_VOICEACTIVATION = 0x0010, + /** @brief Don't allow recording to files in the channel. */ + CHANNEL_NO_RECORDING = 0x0020, + /** @brief Hidden channel which can only be seen with + * #USERRIGHT_VIEW_HIDDEN_CHANNELS. */ + CHANNEL_HIDDEN = 0x0040 + } ChannelType; + + /** + * @brief Bitmask of #ChannelType. */ + typedef UINT32 ChannelTypes; + + /** + * @brief A struct containing the properties of a channel. + * + * To change the properties of a channel call + * TT_DoUpdateChannel(). Note that @a audiocodec cannot be + * changed if the channel has users. + * + * @see TT_GetChannel + * @see ChannelType + * @see AudioCodec */ + typedef struct Channel + { + /** @brief Parent channel ID. 0 means no parent channel, + * i.e. it's the root channel. */ + INT32 nParentID; + /** @brief The channel's ID. A value from 1 - #TT_CHANNELID_MAX. */ + INT32 nChannelID; + /** @brief Name of the channel. */ + TTCHAR szName[TT_STRLEN]; + /** @brief Topic of the channel. */ + TTCHAR szTopic[TT_STRLEN]; + /** @brief Password to join the channel. When extracted through + * #TT_GetChannel the password will only be set for users of + * user-type #USERTYPE_ADMIN. */ + TTCHAR szPassword[TT_STRLEN]; + /** @brief Whether password is required to join channel. Read-only + * property. */ + TTBOOL bPassword; + /** @brief A bitmask of the type of channel based on #ChannelType. */ + ChannelTypes uChannelType; + /** @brief User specific data which will be stored on + * persistent storage on the server if the channel type is + * #CHANNEL_PERMANENT. */ + INT32 nUserData; + /** @brief Number of bytes available for file storage. */ + INT64 nDiskQuota; + /** @brief Password to become channel operator. @see + * TT_DoChannelOpEx() */ + TTCHAR szOpPassword[TT_STRLEN]; + /** @brief Max number of users in channel. */ + INT32 nMaxUsers; + /** @brief The audio codec used by users in the channel. */ + AudioCodec audiocodec; + /** @brief The audio configuration which users who join the channel + * should use. @see TT_SetSoundInputPreprocess() */ + AudioConfig audiocfg; + /** @brief List of users who can transmit in a channel. + * + * @c transmitUsers is a 2-dimensional array which specifies + * who can transmit to the channel. + * + * If @c uChannelType is set to #CHANNEL_CLASSROOM then only + * the users in @c transmitUsers are allowed to transmit. + * + * In TeamTalk v5.4 and onwards adding a user ID to @c + * transmitUsers will block the user from transmitting if the + * #ChannelType is not #CHANNEL_CLASSROOM. Basically the + * opposite effect of #CHANNEL_CLASSROOM. + * + * To specify user ID 46 can transmit voice to a + * #CHANNEL_CLASSROOM channel is done by assigning the + * following: + * + * @verbatim + * transmitUsers[0][0] = 46; + * transmitUsers[0][1] = STREAMTYPE_VOICE; + * @endverbatim + * + * To specify user ID 46 can transmit both voice and video + * capture to a #CHANNEL_CLASSROOM channel is done by + * assigning the following: + * + * @verbatim + * transmitUsers[0][0] = 46; + * transmitUsers[0][1] = STREAMTYPE_VOICE | STREAMTYPE_VIDEOCAPTURE; + * @endverbatim + * + * The transmission list is terminated by assigning user ID 0 + * to the end of the list, i.e.: + * + * @verbatim + * transmitUsers[0][0] = 0; + * transmitUsers[0][1] = STREAMTYPE_NONE; + * @endverbatim + * + * To allow all users of a #CHANNEL_CLASSROOM channel to + * transmit a specific #StreamType is done like this: + * + * @verbatim + * transmitUsers[0][0] = TT_CLASSROOM_FREEFORALL; + * transmitUsers[0][1] = STREAMTYPE_VOICE; + * @endverbatim + * + * Only channel operators are allowed to change the users who + * are allowed to transmit data to a channel. Call + * TT_DoUpdateChannel() to update the list of users who are + * allowed to transmit data to the channel. + * + * @see TT_IsChannelOperator + * @see TT_DoChannelOp + * @see TT_CLASSROOM_FREEFORALL */ + INT32 transmitUsers[TT_TRANSMITUSERS_MAX][2]; + /** @brief The users currently queued for voice or media file transmission. + * + * This property only applied when channel is configured with + * #CHANNEL_SOLO_TRANSMIT. Read-only property. */ + INT32 transmitUsersQueue[TT_TRANSMITQUEUE_MAX]; + /** @brief Delay for switching to next active voice user in + * @c transmitUsersQueue. + * + * In channels of type #CHANNEL_SOLO_TRANSMIT only one user can + * transmit voice. When user has stopped transmitting this value + * specifies the delay before switching to next user in + * @c transmitUsersQueue. Default value is 500 msec. */ + INT32 nTransmitUsersQueueDelayMSec; + } Channel; + + + /** @brief Status of a file transfer. @see FileTransfer */ + typedef enum FileTransferStatus + { + /** brief Invalid transfer. */ + FILETRANSFER_CLOSED = 0, + /** @brief Error during file transfer. */ + FILETRANSFER_ERROR = 1, + /** @brief File transfer active. */ + FILETRANSFER_ACTIVE = 2, + /** @brief File transfer finished. */ + FILETRANSFER_FINISHED = 3 + } FileTransferStatus; + + /** + * @brief A struct containing the properties of a file transfer. + * @see TT_GetFileTransferInfo */ + typedef struct FileTransfer + { + /** @brief Status of file transfer. */ + FileTransferStatus nStatus; + /** @brief The ID identifying the file transfer. */ + INT32 nTransferID; + /** @brief The channel where the file is/will be located. */ + INT32 nChannelID; + /** @brief The file path on local disk. */ + TTCHAR szLocalFilePath[TT_STRLEN]; + /** @brief The filename in the channel. */ + TTCHAR szRemoteFileName[TT_STRLEN]; + /** @brief The size of the file being transferred. */ + INT64 nFileSize; + /** @brief The number of bytes transferred so far. */ + INT64 nTransferred; + /** @brief TRUE if download and FALSE if upload. */ + TTBOOL bInbound; + } FileTransfer; + + + /** + * @brief A struct containing the properties of a file in a #Channel. + * @see TT_GetChannelFile */ + typedef struct RemoteFile + { + /** @brief The ID of the channel where the file is located. */ + INT32 nChannelID; + /** @brief The ID identifying the file. */ + INT32 nFileID; + /** @brief The name of the file. */ + TTCHAR szFileName[TT_STRLEN]; + /** @brief The size of the file. */ + INT64 nFileSize; + /** @brief Username of the person who uploaded the file. */ + TTCHAR szUsername[TT_STRLEN]; + /** @brief Time when file was uploaded. Date/time is converted + * local time. */ + TTCHAR szUploadTime[TT_STRLEN]; + } RemoteFile; + /** @} */ + + /** @ingroup connectivity + * @brief Configure peer verification for encrypted connection. + * + * Client and server can verify that the remote end is using a + * valid cerficate that has been issued by the same certification + * authority. + * + * Call TT_SetEncryptionContext() to set up peer verification. */ + typedef struct EncryptionContext + { + /** @brief Path to SSL certificate in PEM format. + * + * If server has enabled @c bVerifyPeer then the client + * (#TTInstance) must have specified its certificate and + * private key. */ + TTCHAR szCertificateFile[TT_STRLEN]; + /** @brief Path to certificate's private key. */ + TTCHAR szPrivateKeyFile[TT_STRLEN]; + /** @brief Path to Certificate Authority (CA) Certificate in + * PEM format. + * + * If there's multiple CA certificates use @c szCADir. */ + TTCHAR szCAFile[TT_STRLEN]; + /** @brief Path to directory containing Certificate Authority + * (CA) Certificates in PEM format. */ + TTCHAR szCADir[TT_STRLEN]; + /** @brief Verify that peer (client or server) uses a + * certificate that has been generated by the Certificate + * Authority contained in @c szCAFile or @c szCAdir. + * + * For additional information checkout OpenSSL's @c + * SSL_CTX_set_verify() with property @c SSL_VERIFY_PEER */ + TTBOOL bVerifyPeer; + /** @brief Whether to only verify client's certificate once + * during initial connection. + * + * Default value is TRUE. + * + * Only valid for server. + * + * For additional information checkout OpenSSL's + * SSL_CTX_set_verify() with property @c + * SSL_VERIFY_CLIENT_ONCE. */ + TTBOOL bVerifyClientOnce; + /** @brief Set limit to depth in the certificate chain during + * the verification procedure. + * + * Default value is 0. + * + * For additional information checkout OpenSSL's + * SSL_CTX_set_verify_depth() */ + INT32 nVerifyDepth; + } EncryptionContext; + + /** @ingroup connectivity + * @brief Control timers for sending keep alive information to the + * server. + * + * @see TT_DoPing() + */ + typedef struct ClientKeepAlive + { + /** @brief The duration before the #TTInstance should consider + * the client/server connection lost. + * + * This value must be greater than @c + * nTcpKeepAliveIntervalMSec and @c nUdpKeepAliveIntervalMSec. + * + * This timeout applies to both the TCP and UDP + * connection. I.e. @c nTcpServerSilenceSec or @c + * nUdpServerSilenceSec in #ClientStatistics should not exceed + * @c nConnectionLostMSec. */ + INT32 nConnectionLostMSec; + /** @brief Client instance's interval between automatically + * doing TT_DoPing() command. Read-only value. Will be half of + * #ServerProperties' @c nUserTimeout. */ + INT32 nTcpKeepAliveIntervalMSec; + /** @brief Client instance's interval between sending UDP keep + * alive packets. The UDP keep alive packets are used to + * ensure audio, video and desktop streams can be sent from + * the server to the client immediately. This value must be + * less than @c nConnectionLostMSec. */ + INT32 nUdpKeepAliveIntervalMSec; + /** @brief Client instance's interval for retransmitting UDP + * keep alive packets. If server hasn't responded to UDP keep + * alive sent at interval @c nUdpKeepAliveIntervalMSec then a + * new UDP keep alive will be sent at the rate specified by + * @c nUdpKeepAliveRTXMSec. */ + INT32 nUdpKeepAliveRTXMSec; + /** @brief Client instance's interval for retransmitting UDP + * connect packets. UDP connect packets are only sent when + * TT_Connect() is initially called. If the server doesn't + * respond to the client instance's initial UDP connect then a + * retransmission will be started at the rate of @c + * nUdpConnectRTXMSec. */ + INT32 nUdpConnectRTXMSec; + /** @brief The duration before the client instance should give + * up trying to connect to the server on UDP. When + * TT_Connect() manages to connect to the server's TCP port + * then the client will afterwards try to connect on server's + * UDP port. If the client cannot connect on UDP before the + * time specified by @c nUdpConnectTimeoutMSec then the client + * instance will report #CLIENTEVENT_CON_FAILED. */ + INT32 nUdpConnectTimeoutMSec; + } ClientKeepAlive; + + /** @ingroup connectivity + * @brief Statistics of bandwidth usage and ping times in the local + * client instance. + * @see TT_GetClientStatistics */ + typedef struct ClientStatistics + { + /** @brief Bytes sent on UDP. */ + INT64 nUdpBytesSent; + /** @brief Bytes received on UDP. */ + INT64 nUdpBytesRecv; + /** @brief Voice data sent (on UDP). */ + INT64 nVoiceBytesSent; + /** @brief Voice data received (on UDP). */ + INT64 nVoiceBytesRecv; + /** @brief Video data sent (on UDP). */ + INT64 nVideoCaptureBytesSent; + /** @brief Video data received (on UDP). */ + INT64 nVideoCaptureBytesRecv; + /** @brief Audio from media file data sent (on UDP). */ + INT64 nMediaFileAudioBytesSent; + /** @brief Audio from media file data received (on UDP). */ + INT64 nMediaFileAudioBytesRecv; + /** @brief Video from media file data sent (on UDP). */ + INT64 nMediaFileVideoBytesSent; + /** @brief Video from media file data received (on UDP). */ + INT64 nMediaFileVideoBytesRecv; + /** @brief Desktop data sent (on UDP). */ + INT64 nDesktopBytesSent; + /** @brief Desktop data received (on UDP). */ + INT64 nDesktopBytesRecv; + /** @brief Response time to server on UDP (based on ping/pong + * sent at a specified interval. Set to -1 if not currently + * available. */ + INT32 nUdpPingTimeMs; + /** @brief Response time to server on TCP (based on ping/pong + * sent at a specified interval. Set to -1 if not currently + * available. @see TT_DoPing() @see ClientKeepAlive */ + INT32 nTcpPingTimeMs; + /** @brief The number of seconds nothing has been received by + * the client on TCP. @see TT_DoPing() @see ClientKeepAlive */ + INT32 nTcpServerSilenceSec; + /** @brief The number of seconds nothing has been received by + * the client on UDP. @see ClientKeepAlive */ + INT32 nUdpServerSilenceSec; + /** @brief Delay of sound input device until the first audio + * frame is delivered (in msec). + * + * The time from when the sound input device is started and until the first + * audio frame is delived (not including the time of the initial audio frame). + * + * @c nSoundInputDeviceDelayMSec is only updated when #TTInstance is in + * a channel. @c nSoundInputDeviceDelayMSec will remain zero until the + * first audio frame is delived. + * + * @see TT_InitSoundInputDevice() */ + INT32 nSoundInputDeviceDelayMSec; + } ClientStatistics; + + /** @ingroup connectivity + * @brief Configuration parameters for the Jitter Buffer + * + * @see TT_SetUserJitterControl() + */ + typedef struct JitterConfig + { + /** @brief The fixed delay in milliseconds. Default = 0.*/ + INT32 nFixedDelayMSec; + /** @brief Turns adaptive jitter buffering ON/OFF. Default is OFF.*/ + TTBOOL bUseAdativeDejitter; + /** @brief A hard maximum delay on the adaptive delay. + Only valid when higher than zero. Default = 0.*/ + INT32 nMaxAdaptiveDelayMSec; + /** @brief The current adaptive delay. + When used with TT_SetUserJitterControl, this value is used as the + adaptive jitter delay starting at the next voice stream of the user. + Default = 0, meaning the value will not be used. + When returned via TT_GetUserJitterControl, it contains the currently + active adaptive jitter delay.*/ + INT32 nActiveAdaptiveDelayMSec; + } JitterConfig; + + /** @addtogroup errorhandling + * @{ */ + + /** + * @brief Errors which can occur either as a result of client + * commands or as a result of internal errors. + * + * Use #TT_GetErrorMessage to get a text-description of the + * error. */ + typedef enum ClientError + { + /** @brief Command indicating success. Only used internally. */ + CMDERR_SUCCESS = 0, + + /* COMMAND ERRORS 1000-1999 ARE DUE TO INVALID OR UNSUPPORTED + * COMMANDS */ + + /** @brief Command has syntax error. Only used internally. */ + CMDERR_SYNTAX_ERROR = 1000, + /** @brief The server doesn't support the issued command. + * + * This error may occur if the server is an older version than + * the client instance. */ + CMDERR_UNKNOWN_COMMAND = 1001, + /** @brief Command cannot be performed due to missing + * parameter. Only used internally. */ + CMDERR_MISSING_PARAMETER = 1002, + /** @brief The server uses a protocol which is incompatible + * with the client instance. */ + CMDERR_INCOMPATIBLE_PROTOCOLS = 1003, + /** @brief The server does not support the audio codec specified + * by the client. Introduced in version 4.1.0.1264. + * @see TT_DoMakeChannel + * @see TT_DoJoinChannel */ + CMDERR_UNKNOWN_AUDIOCODEC = 1004, + /** @brief Invalid username for #UserAccount. + * @see TT_DoNewUserAccount() */ + CMDERR_INVALID_USERNAME = 1005, + + /* COMMAND ERRORS 2000-2999 ARE DUE TO INSUFFICIENT RIGHTS */ + + /** @brief Invalid channel password. + * + * The #TT_DoJoinChannel or #TT_DoJoinChannelByID passed an + * invalid channel password. #TT_DoMakeChannel can also cause + * a this error if the password is longer than #TT_STRLEN. */ + CMDERR_INCORRECT_CHANNEL_PASSWORD = 2001, + /** @brief Invalid username or password for account. + * + * The #TT_DoLogin command was issued with invalid account + * properties. This error can also occur by + * #TT_DoNewUserAccount if username is empty. */ + CMDERR_INVALID_ACCOUNT = 2002, + /** @brief Login failed due to maximum number of users on + * server. + * + * #TT_DoLogin failed because the server does not allow any + * more users. */ + CMDERR_MAX_SERVER_USERS_EXCEEDED = 2003, + /** @brief Cannot join channel because it has maximum number + * of users. + * + * #TT_DoJoinChannel or #TT_DoJoinChannelByID failed because + * no more users are allowed in the channel. */ + CMDERR_MAX_CHANNEL_USERS_EXCEEDED = 2004, + /** @brief IP-address has been banned from server. + * + * #TT_DoLogin failed because the local client's IP-address + * has been banned on the server. */ + CMDERR_SERVER_BANNED = 2005, + /** @brief Command not authorized. + * + * The command cannot be performed because the client instance + * has insufficient rights. + * + * @see TT_DoDeleteFile + * @see TT_DoJoinChannel + * @see TT_DoJoinChannelByID + * @see TT_DoLeaveChannel + * @see TT_DoChannelOp + * @see TT_DoChannelOpEx + * @see TT_DoKickUser + * @see TT_DoUpdateChannel + * @see TT_DoChangeNickname + * @see TT_DoChangeStatus + * @see TT_DoTextMessage + * @see TT_DoSubscribe + * @see TT_DoUnsubscribe + * @see TT_DoMakeChannel + * @see TT_DoRemoveChannel + * @see TT_DoMoveUser + * @see TT_DoUpdateServer + * @see TT_DoSaveConfig + * @see TT_DoSendFile + * @see TT_DoRecvFile + * @see TT_DoBanUser + * @see TT_DoUnBanUser + * @see TT_DoListBans + * @see TT_DoListUserAccounts + * @see TT_DoNewUserAccount + * @see TT_DoDeleteUserAccount */ + CMDERR_NOT_AUTHORIZED = 2006, + /** @brief Cannot upload file because disk quota will be exceeded. + * + * #TT_DoSendFile was not allowed because there's not enough + * disk space available for upload. + * + * @see Channel */ + CMDERR_MAX_DISKUSAGE_EXCEEDED = 2008, + /** @brief Invalid password for becoming channel operator. + * + * The password specified in #TT_DoChannelOpEx is not correct. + * The operator password is the @a szOpPassword of the + * #Channel-struct. */ + CMDERR_INCORRECT_OP_PASSWORD = 2010, + + /** @brief The selected #AudioCodec exceeds what the server allows. + * + * A server can limit the vitrate of audio codecs if @c + * nAudioCodecBpsLimit of #ServerProperties is specified. */ + CMDERR_AUDIOCODEC_BITRATE_LIMIT_EXCEEDED = 2011, + + /** @brief The maximum number of logins allowed per IP-address has + * been exceeded. + * + * @see ServerProperties + * @see TT_DoLogin() */ + CMDERR_MAX_LOGINS_PER_IPADDRESS_EXCEEDED = 2012, + + /** @brief The maximum number of channels has been exceeded. + * @see TT_CHANNELID_MAX */ + CMDERR_MAX_CHANNELS_EXCEEDED = 2013, + + /** @brief Command flooding prevented by server. + * + * Commands are issued faster than allowed by the server. See + * #UserAccount @c commandsPerMSec. @see TT_CHANNELID_MAX */ + CMDERR_COMMAND_FLOOD = 2014, + + /** @brief Banned from joining a channel. + * + * @see TT_DoJoinChannel() + * @see TT_DoJoinChannelByID() + * @see TT_DoBanUser() */ + CMDERR_CHANNEL_BANNED = 2015, + + /* COMMAND ERRORS 3000-3999 ARE DUE TO INVALID STATE OF CLIENT INSTANCE */ + + /** @brief Client instance has not been authenticated. + * + * #TT_DoLogin has not been issued successfully or + * #TT_DoLogout could not be performed because client + * instance is already logged in.*/ + CMDERR_NOT_LOGGEDIN = 3000, + + /** @brief Already logged in. + * + * #TT_DoLogin cannot be performed twice. */ + CMDERR_ALREADY_LOGGEDIN = 3001, + /** @brief Cannot leave channel because not in channel. + * + * #TT_DoLeaveChannel failed because user is not in a channel. */ + CMDERR_NOT_IN_CHANNEL = 3002, + /** @brief Cannot join same channel twice. + * + * #TT_DoJoinChannel or #TT_DoJoinChannelByID failed because + * client instance is already in the specified channel. */ + CMDERR_ALREADY_IN_CHANNEL = 3003, + /** @brief Channel already exists. + * + * #TT_DoMakeChannel failed because channel already exists. */ + CMDERR_CHANNEL_ALREADY_EXISTS = 3004, + /** @brief Channel does not exist. + * + * Command failed because channel does not exists. + * @see TT_DoRemoveChannel + * @see TT_DoUpdateChannel + * @see TT_DoMakeChannel Due to invalid channel name + * @see TT_DoSendFile + * @see TT_DoRecvFile + * @see TT_DoDeleteFile + * @see TT_DoJoinChannel + * @see TT_DoJoinChannelByID + * @see TT_DoLeaveChannel + * @see TT_DoChannelOp + * @see TT_DoKickUser + * @see TT_DoBanUser + * @see TT_DoMoveUser + * @see TT_DoTextMessage */ + CMDERR_CHANNEL_NOT_FOUND = 3005, + /** @brief User not found. + * + * Command failed because user does not exists. + * @see TT_DoChannelOp + * @see TT_DoKickUser + * @see TT_DoBanUser + * @see TT_DoMoveUser + * @see TT_DoTextMessage + * @see TT_DoSubscribe + * @see TT_DoUnsubscribe */ + CMDERR_USER_NOT_FOUND = 3006, + /** @brief Banned IP-address does not exist. + * + * #TT_DoUnBanUser failed because there is no banned + * IP-address which matches what was specified. */ + CMDERR_BAN_NOT_FOUND = 3007, + /** @brief File transfer doesn't exists. + * + * TT_DoSendFile() or TT_DoRecvFile() failed because the server + * cannot process the file transfer. */ + CMDERR_FILETRANSFER_NOT_FOUND = 3008, + /** @brief Server failed to open file. + * + * TT_DoSendFile() or TT_DoRecvFile() failed because the server + * cannot open the specified file (possible file lock). */ + CMDERR_OPENFILE_FAILED = 3009, + /** @brief Cannot find user account. + * + * #TT_DoDeleteUserAccount failed because the specified user + * account does not exists. */ + CMDERR_ACCOUNT_NOT_FOUND = 3010, + /** @brief File does not exist. + * + * #TT_DoSendFile, #TT_DoRecvFile or #TT_DoDeleteFile failed + * because the server cannot find the specified file. */ + CMDERR_FILE_NOT_FOUND = 3011, + /** @brief File already exist. + * + * #TT_DoSendFile failed because the file already exists in + * the channel. */ + CMDERR_FILE_ALREADY_EXISTS = 3012, + /** @brief Server does not allow file transfers. + * + * #TT_DoSendFile or #TT_DoRecvFile failed because the server + * does not allow file transfers. */ + CMDERR_FILESHARING_DISABLED = 3013, + /** @brief Cannot process command since channel is not empty. + * + * @see TT_DoUpdateChannel #AudioCodec cannot be changed while + * there are users in a channel. */ + CMDERR_CHANNEL_HAS_USERS = 3015, + + /** @brief The login service is currently unavailable. + * + * Added in TeamTalk v5.3 to support web-logins. */ + CMDERR_LOGINSERVICE_UNAVAILABLE = 3016, + + /** @brief Cannot apply #CHANNEL_HIDDEN to #Channel's type. + * + * A hidden channel cannot contain subchannels or have it + * #CHANNEL_HIDDEN property toggled. */ + CMDERR_CHANNEL_CANNOT_BE_HIDDEN = 3017, + + /* ERRORS 10000-10999 ARE NOT COMMAND ERRORS BUT INSTEAD + * ERRORS IN THE CLIENT INSTANCE. */ + + /** @brief A sound input device failed. + * + * This can e.g. happen when joining a channel and the sound + * input device has been unplugged. + * + * Call #TT_CloseSoundInputDevice and TT_InitSoundInputDevice + * with a valid #SoundDevice to releave the problem. */ + INTERR_SNDINPUT_FAILURE = 10000, + /** @brief A sound output device failed. + * + * This can e.g. happen when joining a channel and the sound + * output device has been unplugged. Note that it can be posted + * multiple times if there's several users in the channel. + * + * Call #TT_CloseSoundOutputDevice and TT_InitSoundOutputDevice + * with a valid #SoundDevice to releave the problem. */ + INTERR_SNDOUTPUT_FAILURE = 10001, + /** @brief Audio codec used by channel failed to initialize. + * Ensure the settings specified in #AudioCodec are valid. + * @see TT_DoJoinChannel() */ + INTERR_AUDIOCODEC_INIT_FAILED = 10002, + /** @brief Same as #INTERR_AUDIOPREPROCESSOR_INIT_FAILED. */ + INTERR_SPEEXDSP_INIT_FAILED = 10003, + /** @brief #AudioPreprocessor failed to initialize. + * + * This error occurs when joining a channel and the + * #AudioPreprocessor is initialized. + * + * The settings specified by TT_SetSoundInputPreprocessEx() + * are invalid or unsupported. @see TT_DoJoinChannel() */ + INTERR_AUDIOPREPROCESSOR_INIT_FAILED = 10003, + /** @brief #TTMessage event queue overflowed. + * + * The message queue for events has overflowed because + * TT_GetMessage() has not drained the queue in time. The + * #TTMessage message queue will suspend event handling once + * the queue overflows and resumes event handling again when + * the message queue has been drained. */ + INTERR_TTMESSAGE_QUEUE_OVERFLOW = 10004, + /** @brief #SoundDeviceEffects failed to initialize. + * + * This error occurs when joining a channel and an effect in + * #SoundDeviceEffects failed to initialize. + * + * The effects are applied using TT_SetSoundDeviceEffects() */ + INTERR_SNDEFFECT_FAILURE = 10005, + } ClientError; + + /** @brief Struct containing an error message. */ + typedef struct ClientErrorMsg + { + /** @brief Error number based on #ClientError. */ + INT32 nErrorNo; + /** @brief Text message describing the error. */ + TTCHAR szErrorMsg[TT_STRLEN]; + } ClientErrorMsg; + /** @} */ + + /** @addtogroup events + * @{ */ + + /** + * @brief TeamTalk client event messages. + * + * Events are retrieved using TT_GetMessage(). */ + typedef enum ClientEvent + { + CLIENTEVENT_NONE = 0, + + /** + * @brief 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. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__NONE + * @see TT_Connect */ + CLIENTEVENT_CON_SUCCESS = CLIENTEVENT_NONE + 10, + /** + * @brief Failed to connect to server. + * + * This event is posted if #TT_Connect fails. Ensure to call + * #TT_Disconnect before calling #TT_Connect again. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__NONE + * @see TT_Connect */ + CLIENTEVENT_CON_FAILED = CLIENTEVENT_NONE + 20, + /** + * @brief Connection to server has been lost. + * + * The server is not responding to requests from the local + * client instance and the connection has been dropped. + * + * #TT_GetClientStatistics can be used to check when data was + * last received from the server. + * + * Ensure to call #TT_Disconnect before calling #TT_Connect + * again. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__NONE + * @see TT_Connect */ + CLIENTEVENT_CON_LOST = CLIENTEVENT_NONE + 30, + /** + * @brief The maximum size of the payload put into UDP packets + * has been updated. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Ignored + * - #TTMessage.ttType #__INT32 + * - #TTMessage.nPayloadSize Placed in union of #TTMessage. The + * maximum size in bytes of the payload data which is put in + * UDP packets. 0 means the max payload query failed. @see + * TT_QueryMaxPayload() */ + CLIENTEVENT_CON_MAX_PAYLOAD_UPDATED = CLIENTEVENT_NONE + 40, + /** + * @brief A command issued by @c TT_Do* methods is being + * processed. + * + * Read section @ref cmdprocessing on how to use command + * processing in the user application. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Command ID being processed (returned by + * TT_Do* commands) + * - #TTMessage.ttType #__TTBOOL + * - #TTMessage.bActive Placed in union of #TTMessage. Is TRUE if + * command ID started processing and FALSE if the command has + * finished processing. */ + CLIENTEVENT_CMD_PROCESSING = CLIENTEVENT_NONE + 200, + /** + * @brief 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 @ref cmdprocessing + * explains how to use command ID. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The command ID returned from the TT_Do* + * commands. + * - #TTMessage.ttType #__CLIENTERRORMSG + * - #TTMessage.clienterrormsg Placed in union of #TTMessage. Contains + * error description. */ + CLIENTEVENT_CMD_ERROR = CLIENTEVENT_NONE + 210, + /** + * @brief 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 @ref cmdprocessing + * explains how to use command ID. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The command ID returned from the TT_Do* + * commands. + * - #TTMessage.ttType #__NONE */ + CLIENTEVENT_CMD_SUCCESS = CLIENTEVENT_NONE + 220, + /** + * @brief 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 + * #CLIENTEVENT_CMD_CHANNEL_NEW immediately following this + * event. If #USERRIGHT_VIEW_ALL_USERS is enabled the client + * instance will also receive the events + * #CLIENTEVENT_CMD_USER_LOGGEDIN and + * #CLIENTEVENT_CMD_USER_JOINED for every user on the server. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The client instance's user ID, i.e. what can now + * be retrieved through TT_GetMyUserID(). + * - #TTMessage.ttType #__USERACCOUNT + * - #TTMessage.useraccount Placed in union of #TTMessage. + * @see TT_DoLogin */ + CLIENTEVENT_CMD_MYSELF_LOGGEDIN = CLIENTEVENT_NONE + 230, + /** + * @brief The client instance logged out of the server. + * + * A response to #TT_DoLogout. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__NONE + * @see TT_DoLogout */ + CLIENTEVENT_CMD_MYSELF_LOGGEDOUT = CLIENTEVENT_NONE + 240, + /** + * @brief The client instance was kicked from a channel. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource If greater than zero indicates local client + * instance was kicked from a channel. Otherwise kicked from + * server. + * - #TTMessage.ttType #__USER if kicked by a user otherwise #__NONE. + * - #TTMessage.user Placed in union of #TTMessage if @a ttType + * equals #__USER otherwise #__NONE. */ + CLIENTEVENT_CMD_MYSELF_KICKED = CLIENTEVENT_NONE + 250, + /** + * @brief A new user logged on to the server. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USER + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_DoLogin + * @see TT_GetUser To retrieve user. + * @see CLIENTEVENT_CMD_USER_LOGGEDOUT */ + CLIENTEVENT_CMD_USER_LOGGEDIN = CLIENTEVENT_NONE + 260, + /** + * @brief A client logged out of the server. + * + * This event is called when a user logs out with + * #TT_DoLogout or disconnects with #TT_Disconnect. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USER + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_DoLogout + * @see TT_Disconnect + * @see CLIENTEVENT_CMD_USER_LOGGEDIN */ + CLIENTEVENT_CMD_USER_LOGGEDOUT = CLIENTEVENT_NONE + 270, + /** + * @brief User changed properties. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USER + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_GetUser To retrieve user. */ + CLIENTEVENT_CMD_USER_UPDATE = CLIENTEVENT_NONE + 280, + /** + * @brief A user has joined a channel. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USER + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_GetUser To retrieve user. */ + CLIENTEVENT_CMD_USER_JOINED = CLIENTEVENT_NONE + 290, + /** + * @brief User has left a channel. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Channel ID of previous channel. + * - #TTMessage.ttType #__USER + * - #TTMessage.user Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_USER_LEFT = CLIENTEVENT_NONE + 300, + /** + * @brief A user has sent a text-message. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__TEXTMESSAGE + * - #TTMessage.textmessage Placed in union of #TTMessage. + * + * @see TT_GetUser To retrieve user. + * @see TT_DoTextMessage() to send text message. */ + CLIENTEVENT_CMD_USER_TEXTMSG = CLIENTEVENT_NONE + 310, + /** + * @brief A new channel has been created. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__CHANNEL + * - #TTMessage.channel Placed in union of #TTMessage. + * + * @see TT_GetChannel To retrieve channel. */ + CLIENTEVENT_CMD_CHANNEL_NEW = CLIENTEVENT_NONE + 320, + /** + * @brief A channel's properties has been updated. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__CHANNEL + * - #TTMessage.channel Placed in union of #TTMessage. + * + * @see TT_GetChannel To retrieve channel. */ + CLIENTEVENT_CMD_CHANNEL_UPDATE = CLIENTEVENT_NONE + 330, + /** + * @brief A channel has been removed. + * + * Note that calling the #TT_GetChannel with the channel ID + * will fail because the channel is no longer there. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__CHANNEL + * - #TTMessage.channel Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_CHANNEL_REMOVE = CLIENTEVENT_NONE + 340, + /** + * @brief Server has updated its settings (server name, MOTD, + * etc.) + * + * Get new settings in @c serverproperties of #TTMessage. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__SERVERPROPERTIES + * - #TTMessage.serverproperties Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_SERVER_UPDATE = CLIENTEVENT_NONE + 350, + /** + * @brief Server statistics available. + * + * This is a response to TT_DoServerStatistics() + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__SERVERSTATISTICS + * - #TTMessage.serverstatistics Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_SERVERSTATISTICS = CLIENTEVENT_NONE + 360, + /** + * @brief A new file is added to a channel. + * + * Use TT_GetChannelFile() to get information about the + * file. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__REMOTEFILE + * - #TTMessage.remotefile Placed in union of #TTMessage. + * + * @see TT_GetChannelFile To retrieve file. */ + CLIENTEVENT_CMD_FILE_NEW = CLIENTEVENT_NONE + 370, + /** + * @brief A file has been removed from a channel. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__REMOTEFILE + * - #TTMessage.remotefile Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_FILE_REMOVE = CLIENTEVENT_NONE + 380, + /** + * @brief A user account has been received from the server. + * + * This message is posted as a result of TT_DoListUserAccounts() + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USERACCOUNT + * - #TTMessage.useraccount Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_USERACCOUNT = CLIENTEVENT_NONE + 390, + /** + * @brief A banned user has been received from the server. + * + * This message is posted as a result of TT_DoListBans() + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__BANNEDUSER + * - #TTMessage.useraccount Placed in union of #TTMessage. */ + CLIENTEVENT_CMD_BANNEDUSER = CLIENTEVENT_NONE + 400, + /** + * @brief A user state has changed. + * + * The @a uUserState has changed for a user due to playback of + * an incoming stream. + * + * The user state changes if: + * - A user has started/stopped voice stream, + * i.e. #USERSTATE_VOICE + * - A user has started/stopped a video capture stream, + * i.e. #USERSTATE_VIDEOCAPTURE + * - A user has started/stopped a media file stream, i.e. + * i.e. #USERSTATE_MEDIAFILE_AUDIO or #USERSTATE_MEDIAFILE_VIDEO + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__USER. + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_SetUserStoppedTalkingDelay */ + CLIENTEVENT_USER_STATECHANGE = CLIENTEVENT_NONE + 500, + /** + * @brief A new video frame from a video capture device + * was received from a user. + * + * Use #TT_AcquireUserVideoCaptureFrame to display the video frame. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource User's ID. + * - #TTMessage.ttType #__INT32 + * - #TTMessage.nStreamID Placed in union of #TTMessage. The ID of + * the video stream currently active for this user. If stream + * ID becomes 0 it means the current stream has been + * closed. */ + CLIENTEVENT_USER_VIDEOCAPTURE = CLIENTEVENT_NONE + 510, + /** + * @brief A new video frame from a video media file + * was received from a user. + * + * Use TT_AcquireUserMediaVideoFrame() to display the video frame. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource User's ID. + * - #TTMessage.ttType #__INT32 + * - #TTMessage.nStreamID Placed in union of #TTMessage. The ID of + * the video stream currently active for this user. If stream + * ID becomes 0 it means the current stream has been + * closed. */ + CLIENTEVENT_USER_MEDIAFILE_VIDEO = CLIENTEVENT_NONE + 520, + /** + * @brief A new or updated desktop window has been received + * from a user. + * + * Use TT_AcquireUserDesktopWindow() to retrieve the bitmap of the + * desktop window. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The user's ID. + * - #TTMessage.ttType #__INT32 + * - #TTMessage.nStreamID Placed in union of #TTMessage. The 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 TT_SendDesktopWindow() */ + CLIENTEVENT_USER_DESKTOPWINDOW = CLIENTEVENT_NONE + 530, + /** + * @brief A user has sent the position of the mouse cursor. + * + * Use TT_SendDesktopCursorPosition() to send the position of + * the mouse cursor. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The user ID of the owner of the mouse cursor. + * - #TTMessage.ttType #__DESKTOPINPUT + * - #TTMessage.desktopinput Placed in union of #TTMessage. Contains + * the coordinates of the mouse cursor. */ + CLIENTEVENT_USER_DESKTOPCURSOR = CLIENTEVENT_NONE + 540, + /** + * @brief Desktop input (mouse or keyboard input) has been + * received from a user. + * + * Desktop input is used in combination with a shared desktop + * window, see @ref desktopshare. + * + * This event is generated if a remote user has called + * TT_SendDesktopInput(). In order for the local client + * instance to receive desktop input it must have enabled the + * subscription #SUBSCRIBE_DESKTOPINPUT. + * + * Due to different keyboard layout it might be a good idea + * to look into the key-translation function + * TT_DesktopInput_KeyTranslate(). + * + * See @ref rxdesktopinput for more information on receiving + * desktop input. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource User ID + * - #TTMessage.ttType #__DESKTOPINPUT + * - #TTMessage.desktopinput Placed in union of #TTMessage. */ + CLIENTEVENT_USER_DESKTOPINPUT = CLIENTEVENT_NONE + 550, + /** + * @brief A media file recording has changed status. + * + * #TT_SetUserMediaStorageDir 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. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The user's ID. + * - #TTMessage.ttType #__MEDIAFILEINFO + * - #TTMessage.mediafileinfo Placed in union of + * #TTMessage. Properties for the media file currently being + * recorded */ + CLIENTEVENT_USER_RECORD_MEDIAFILE = CLIENTEVENT_NONE + 560, + /** + * @brief A new audio block can be extracted. + * + * The #AudioBlock can either be of #STREAMTYPE_VOICE, + * STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO or + * #STREAMTYPE_MEDIAFILE_AUDIO. + * + * This event is only generated if TT_EnableAudioBlockEvent() + * is first called. + * + * Call TT_AcquireUserAudioBlock() to extract the #AudioBlock. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The user ID. @see TT_LOCAL_USERID + * @see TT_MUTEX_USERID + * - #TTMessage.ttType #__STREAMTYPE */ + CLIENTEVENT_USER_AUDIOBLOCK = CLIENTEVENT_NONE + 570, + /** + * @brief An internal error occurred in the client instance. + * + * This can e.g. happen if a new user joins a channel and + * a sound output device fails to start a new audio stream. + * + * For at list of internal error messages check out #ClientError + * with errors prefixed @c INTERR_* + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__CLIENTERRORMSG + * - #TTMessage.clienterrormsg Placed in union of #TTMessage. Contains + * information on what caused an error. */ + CLIENTEVENT_INTERNAL_ERROR = CLIENTEVENT_NONE + 1000, + /** + * @brief Voice activation has triggered transmission. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__TTBOOL + * - #TTMessage.bActive Placed in union of #TTMessage. TRUE if voice + * is being transmitted due to voice level high than + * activation level. + * + * @see TT_GetSoundInputLevel() + * @see TT_SetVoiceActivationLevel() + * @see CLIENT_SNDINPUT_VOICEACTIVATION + * @see TT_EnableTransmission */ + CLIENTEVENT_VOICE_ACTIVATION = CLIENTEVENT_NONE + 1010, + /** + * @brief A hotkey has been acticated or deactivated. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The hotkey ID passed to TT_HotKey_Register(). + * - #TTMessage.ttType #__TTBOOL + * - #TTMessage.bActive Placed in union of #TTMessage. TRUE when + * hotkey is active and FALSE when it becomes inactive. + * + * @see TT_HotKey_Register + * @see TT_HotKey_Unregister */ + CLIENTEVENT_HOTKEY = CLIENTEVENT_NONE + 1020, + /** + * @brief 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. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The virtual key code. Look here for a list of virtual + * key codes: http://msdn.microsoft.com/en-us/library/ms645540(VS.85).aspx + * - #TTMessage.ttType #__TTBOOL + * - #TTMessage.bActive Placed in union of #TTMessage. TRUE when key + * is down and FALSE when released. + * @see TT_HotKey_InstallTestHook */ + CLIENTEVENT_HOTKEY_TEST = CLIENTEVENT_NONE + 1030, + /** + * @brief 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. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__FILETRANSFER + * - #TTMessage.filetransfer Placed in union of #TTMessage. Properties + * and status information about the file transfer. + * + * @see TT_GetFileTransferInfo To retrieve #FileTransfer. */ + CLIENTEVENT_FILETRANSFER = CLIENTEVENT_NONE + 1040, + /** + * @brief 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. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource The desktop session's ID. If the desktop session ID + * becomes 0 it means the desktop session has been closed and/or + * cancelled. + * - #TTMessage.ttType #__INT32 + * - #TTMessage.nBytesRemain Placed in union of #TTMessage. The number of + * bytes remaining before transmission of last desktop window + * completes. When remaining bytes is 0 TT_SendDesktopWindow() + * can be called again. */ + CLIENTEVENT_DESKTOPWINDOW_TRANSFER = CLIENTEVENT_NONE + 1050, + /** + * @brief Media file being streamed to a channel is processing. + * + * This event is called as a result of + * TT_StartStreamingMediaFileToChannel() to monitor progress + * of streaming. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource 0 + * - #TTMessage.ttType #__MEDIAFILEINFO + * - #TTMessage.mediafileinfo Placed in union of #TTMessage. Contains + * properties and status information about the media file + * being streamed. */ + CLIENTEVENT_STREAM_MEDIAFILE = CLIENTEVENT_NONE + 1060, + /** + * @brief Media file played locally is processing. + * + * This event is called as a result of TT_InitLocalPlayback() + * to monitor progress of playback. + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Session ID returned by TT_InitLocalPlayback() + * - #TTMessage.ttType #__MEDIAFILEINFO + * - #TTMessage.mediafileinfo Placed in union of #TTMessage. Contains + * properties and status information about the media file + * being played. + */ + CLIENTEVENT_LOCAL_MEDIAFILE = CLIENTEVENT_NONE + 1070, + /** + * @brief Progress is audio being injected as + * #STREAMTYPE_VOICE. + * + * @c nStreamID of #AudioInputProgress is the stream ID + * provided in the #AudioBlock when calling + * TT_InsertAudioBlock(). + * + * When @c uElapsedMSec and @c uQueueMSec of + * #AudioInputProgress are zero then the stream ID (session) + * has ended. An audio input session has ended when an empty + * #AudioBlock has been inserted using TT_InsertAudioBlock(). + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Stream ID used for sending audio input. + * The stream ID will appear in #AudioBlock's @c nStreamID + * on the receiving side. + * - #TTMessage.ttType #__AUDIOINPUTPROGRESS + * - #TTMessage.audioinputprogress Placed in union of #TTMessage. + * Tells how much audio remains in queue. The queue should + * be refilled as long as the audio input should remain active. + */ + CLIENTEVENT_AUDIOINPUT = CLIENTEVENT_NONE + 1080, + /** + * @brief The first voice packet of a new voice stream + * has been received. + * + * This time of this event may differ significantly from the start + * of the voice playout that is notified via + * #CLIENTEVENT_USER_STATECHANGE due to jitter buffering. + * + * The time between #CLIENTEVENT_USER_FIRSTVOICESTREAMPACKET + * and #CLIENTEVENT_USER_STATECHANGE is the fixed jitter delay + * configuration plus the currently active adaptive jitter + * buffering in the nActiveAdaptiveDelayMSec member of the + * User struct + * + * Attribute values in #TTMessage: + * - #TTMessage.nSource Stream ID. This can be mapped to #AudioBlock. + * - #TTMessage.ttType #__USER. + * - #TTMessage.user Placed in union of #TTMessage. + * + * @see TT_SetUserJitterControl */ + CLIENTEVENT_USER_FIRSTVOICESTREAMPACKET = CLIENTEVENT_NONE + 1090, + } ClientEvent; + + /* List of structures used internally by TeamTalk. */ + typedef enum TTType + { + __NONE = 0, + __AUDIOCODEC = 1, + __BANNEDUSER = 2, + __VIDEOFORMAT = 3, + __OPUSCODEC = 4, + __CHANNEL = 5, + __CLIENTSTATISTICS = 6, + __REMOTEFILE = 7, + __FILETRANSFER = 8, + __MEDIAFILESTATUS = 9, + __SERVERPROPERTIES = 10, + __SERVERSTATISTICS = 11, + __SOUNDDEVICE = 12, + __SPEEXCODEC = 13, + __TEXTMESSAGE = 14, + __WEBMVP8CODEC = 15, + __TTMESSAGE = 16, + __USER = 17, + __USERACCOUNT = 18, + __USERSTATISTICS = 19, + __VIDEOCAPTUREDEVICE = 20, + __VIDEOCODEC = 21, + __AUDIOCONFIG = 22, + __SPEEXVBRCODEC = 23, + __VIDEOFRAME = 24, + __AUDIOBLOCK = 25, + __AUDIOFORMAT = 26, + __MEDIAFILEINFO = 27, + __CLIENTERRORMSG = 28, + __TTBOOL = 29, + __INT32 = 30, + __DESKTOPINPUT = 31, + __SPEEXDSP = 32, + __STREAMTYPE = 33, + __AUDIOPREPROCESSORTYPE = 34, + __AUDIOPREPROCESSOR = 35, + __TTAUDIOPREPROCESSOR = 36, + __MEDIAFILEPLAYBACK = 37, + __CLIENTKEEPALIVE = 38, + __UINT32 = 39, + __AUDIOINPUTPROGRESS = 40, + __JITTERCONFIG = 41, + __WEBRTCAUDIOPREPROCESSOR = 42, + __ENCRYPTIONCONTEXT = 43, + } TTType; + + /** + * @brief 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 @ref events explains event handling in the local client + * instance. + * + * @see TT_GetMessage */ + typedef struct TTMessage + { + /** @brief The event's message number @see ClientEvent */ + ClientEvent nClientEvent; + /** @brief The source of the event depends on @c wmMsg */ + INT32 nSource; + /** @brief Specifies which member to access in the union */ + TTType ttType; + /** @brief Reserved. To preserve alignment. */ + UINT32 uReserved; + union + { + /** @brief Valid if @c ttType is #__CHANNEL. */ + Channel channel; + /** @brief Valid if @c ttType is #__CLIENTERRORMSG. */ + ClientErrorMsg clienterrormsg; + /** @brief Valid if @c ttType is #__DESKTOPINPUT. */ + DesktopInput desktopinput; + /** @brief Valid if @c ttType is #__FILETRANSFER. */ + FileTransfer filetransfer; + /** @brief Valid if @c ttType is #__MEDIAFILEINFO. */ + MediaFileInfo mediafileinfo; + /** @brief Valid if @c ttType is #__REMOTEFILE. */ + RemoteFile remotefile; + /** @brief Valid if @c ttType is #__SERVERPROPERTIES. */ + ServerProperties serverproperties; + /** @brief Valid if @c ttType is #__SERVERSTATISTICS. */ + ServerStatistics serverstatistics; + /** @brief Valid if @c ttType is #__TEXTMESSAGE. */ + TextMessage textmessage; + /** @brief Valid if @c ttType is #__USER. */ + User user; + /** @brief Valid if @c ttType is #__USERACCOUNT. */ + UserAccount useraccount; + /** @brief Valid if @c ttType is #__BANNEDUSER. */ + BannedUser banneduser; + /** @brief Valid if @c ttType is #__TTBOOL. */ + TTBOOL bActive; + /** @brief Valid if @c ttType is #__INT32. */ + INT32 nBytesRemain; + /** @brief Valid if @c ttType is #__INT32. */ + INT32 nStreamID; + /** @brief Valid if @c ttType is #__INT32. */ + INT32 nPayloadSize; + /** @brief Valid if @c ttType is #__STREAMTYPE. */ + StreamType nStreamType; + /** @brief Valid if @c ttType is #__AUDIOINPUTPROGRESS. */ + AudioInputProgress audioinputprogress; + /* brief First byte in union. */ + char data[1]; + }; + } TTMessage; + + /** @}*/ + + + /** @addtogroup initclient + * @{ */ + + /** + * @brief 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 enum ClientFlag + { + /** @brief 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_CLOSED = 0x00000000, + /** @brief If set the client instance's sound input device has + * been initialized, i.e. #TT_InitSoundInputDevice has been + * called successfully. */ + CLIENT_SNDINPUT_READY = 0x00000001, + /** @brief If set the client instance's sound output device + * has been initialized, i.e. #TT_InitSoundOutputDevice has + * been called successfully. */ + CLIENT_SNDOUTPUT_READY = 0x00000002, + /** @brief 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_SNDINOUTPUT_DUPLEX = 0x00000004, + /** @brief 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 TT_SetVoiceActivationLevel + * @see TT_EnableVoiceActivation */ + CLIENT_SNDINPUT_VOICEACTIVATED = 0x00000008, + /** @brief 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 + * TT_SetVoiceActivationLevel() @see + * TT_EnableVoiceActivation() */ + CLIENT_SNDINPUT_VOICEACTIVE = 0x00000010, + /** @brief If set the client instance has muted all users. + * @see TT_SetSoundOutputMute */ + CLIENT_SNDOUTPUT_MUTE = 0x00000020, + /** @brief 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 TT_SetUserPosition() + * @see TT_Enable3DSoundPositioning */ + CLIENT_SNDOUTPUT_AUTO3DPOSITION = 0x00000040, + /** @brief If set the client instance's video device has been + * initialized, i.e. #TT_InitVideoCaptureDevice has been + * called successfuly. */ + CLIENT_VIDEOCAPTURE_READY = 0x00000080, + /** @brief If set the client instance is currently transmitting + * audio. @see TT_EnableVoiceTransmission() */ + CLIENT_TX_VOICE = 0x00000100, + /** @brief If set the client instance is currently + * transmitting video. @see + * TT_StartVideoCaptureTransmission() */ + CLIENT_TX_VIDEOCAPTURE = 0x00000200, + /** @brief 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_TX_DESKTOP = 0x00000400, + /** @brief 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_DESKTOP_ACTIVE = 0x00000800, + /** @brief If set the client instance is currently muxing + * audio streams into a single file. This is enabled by calling + * TT_StartRecordingMuxedAudioFile(). */ + CLIENT_MUX_AUDIOFILE = 0x00001000, + /** @brief If set the client instance is currently try to + * connect to a server, i.e. #TT_Connect has been called. */ + CLIENT_CONNECTING = 0x00002000, + /** @brief 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_CONNECTED = 0x00004000, + /** @brief Helper for #CLIENT_CONNECTING and #CLIENT_CONNECTED + * to see if #TT_Disconnect should be called. */ + CLIENT_CONNECTION = CLIENT_CONNECTING | CLIENT_CONNECTED, + /** @brief If set the client instance is logged on to a + * server, i.e. got #CLIENTEVENT_CMD_MYSELF_LOGGEDIN event + * after issueing #TT_DoLogin. */ + CLIENT_AUTHORIZED = 0x00008000, + /** @brief 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 TT_StartStreamingMediaFileToChannel() */ + CLIENT_STREAM_AUDIO = 0x00010000, + /** @brief 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 TT_StartStreamingMediaFileToChannel() */ + CLIENT_STREAM_VIDEO = 0x00020000 + } ClientFlag; + + /** @brief A bitmask based on #ClientFlag describing the local client + * instance's current state. */ + typedef UINT32 ClientFlags; + + /** @ingroup initclient + * + * @brief Pointer to a TeamTalk client instance created by + * #TT_InitTeamTalk. @see TT_CloseTeamTalk */ + typedef VOID TTInstance; + + /** @ingroup sounddevices + * + * @brief Pointer to a sound loop for testing sound devices + * created by TT_StartSoundLoopbackTest() */ + typedef VOID TTSoundLoop; + + /** @brief Get the DLL's version number. */ + TEAMTALKDLL_API const TTCHAR* TT_GetVersion(void); + +#if defined(WIN32) + /** + * @brief 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. + * + * @param hWnd The window handle which will receive the events defined + * in #ClientEvent. + * @param uMsg The message ID which will be passed to @c hWnd when a + * new event can be retrieved by TT_GetMessage(). + * @return A pointer to a new client instance. NULL if a failure occured. + * @see TT_CloseTeamTalk */ + TEAMTALKDLL_API TTInstance* TT_InitTeamTalk(IN HWND hWnd, IN UINT32 uMsg); + + /** + * @brief Replace the HWND passed as parameter to #TT_InitTeamTalk + * with this HWND. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param hWnd The new HWND which should receive event messages. */ + TEAMTALKDLL_API TTBOOL TT_SwapTeamTalkHWND(IN TTInstance* lpTTInstance, + IN HWND hWnd); +#endif + + /** + * @brief 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. + * + * @return A pointer to a new client instance. NULL if a failure occured. + * @see TT_CloseTeamTalk */ + TEAMTALKDLL_API TTInstance* TT_InitTeamTalkPoll(void); + + /** + * @brief 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. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @see TT_InitTeamTalk */ + TEAMTALKDLL_API TTBOOL TT_CloseTeamTalk(IN TTInstance* lpTTInstance); + + /** + * @brief Poll for events in the client instance. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param pMsg Pointer to a TTMessage instance which will hold the + * event that has occured. + * @param 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. + * @return Returns TRUE if an event has occured otherwise FALSE. + * @see TT_InitTeamTalkPolled + * @see ClientEvent */ + TEAMTALKDLL_API TTBOOL TT_GetMessage(IN TTInstance* lpTTInstance, + OUT TTMessage* pMsg, + IN const INT32* pnWaitMs); + + /** + * @brief 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 @c 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. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nClientEvent The event which should be queued. Currently + * only #CLIENTEVENT_USER_STATECHANGE is supported. + * @param nIdentifier The ID of the object to retrieve. Currently + * only nUserID is supported. + * + * @return Returns TRUE if the event has been scheduled. */ + TEAMTALKDLL_API TTBOOL TT_PumpMessage(IN TTInstance* lpTTInstance, + ClientEvent nClientEvent, + INT32 nIdentifier); + + /** + * @brief 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. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return A bitmask describing the current state (based on + * #ClientFlag). + * @see ClientFlag */ + TEAMTALKDLL_API ClientFlags TT_GetFlags(IN TTInstance* lpTTInstance); + + /** + * @brief Set license information to disable trial mode. + * + * This function must be called before #TT_InitTeamTalk. + * + * @param szRegName The registration name provided by BearWare.dk. + * @param szRegKey The registration key provided by BearWare.dk. + * @return True if the provided registration is acceptable. */ + TEAMTALKDLL_API TTBOOL TT_SetLicenseInformation(IN const TTCHAR szRegName[TT_STRLEN], + IN const TTCHAR szRegKey[TT_STRLEN]); + /** @} */ + + /** @addtogroup sounddevices + * @{ */ + + /** + * @brief Get the default sound devices. + * + * @param lpnInputDeviceID The ID of the default input device. + * @param lpnOutputDeviceID The ID of the default output device. + * @see TT_InitSoundInputDevice + * @see TT_InitSoundOutputDevice */ + TEAMTALKDLL_API TTBOOL TT_GetDefaultSoundDevices(OUT INT32* lpnInputDeviceID, + OUT INT32* lpnOutputDeviceID); + /** + * @brief Get the default sound devices for the specified sound system. + * + * @see TT_GetDefaultSoundDevices() */ + TEAMTALKDLL_API TTBOOL TT_GetDefaultSoundDevicesEx(IN SoundSystem nSndSystem, + OUT INT32* lpnInputDeviceID, + OUT INT32* lpnOutputDeviceID); + + /** + * @brief Retrieve list of sound devices for recording and playback. + * + * @param lpSoundDevices Array of SoundDevice-structs where lpnHowMany holds + * the size of the array. Pass NULL as @a lpSoundDevices to query the + * number of devices. + * @param lpnHowMany This is both an input and an output parameter. If + * @a lpSoundDevices is NULL lpnHowMany will after the call hold the + * number of devices, otherwise it should hold the size of the + * @a lpSoundDevices array. + * @see TT_GetDefaultSoundDevices + * @see TT_InitSoundInputDevice + * @see TT_InitSoundOutputDevice */ + TEAMTALKDLL_API TTBOOL TT_GetSoundDevices(IN OUT SoundDevice* lpSoundDevices, + IN OUT INT32* lpnHowMany); + + + /** + * @brief Reinitialize sound system (in order to detect + * new/removed devices). + * + * When the TeamTalk client is first initialized all the sound + * devices are detected and stored in a list inside the client + * instance. If a user adds or removes e.g. a USB sound device + * then it's not picked up automatically by the client + * instance. TT_RestartSoundSystem() can be used to reinitialize + * the sound system and thereby detect if sound devices have been + * removed or added. + * + * In order to restart the sound system all sound devices in all + * client instances must be closed using TT_CloseSoundInputDevice(), + * TT_CloseSoundoutputDevice() and TT_CloseSoundDuplexDevices(). */ + TEAMTALKDLL_API TTBOOL TT_RestartSoundSystem(void); + + /** + * @brief Perform a record and playback test of specified sound + * devices along with an audio configuration. + * + * @deprecated Use TT_StartSoundLoopbackTestEx() */ + TEAMTALKDLL_API TTSoundLoop* TT_StartSoundLoopbackTest(IN INT32 nInputDeviceID, + IN INT32 nOutputDeviceID, + IN INT32 nSampleRate, + IN INT32 nChannels, + IN TTBOOL bDuplexMode, + IN const SpeexDSP* lpSpeexDSP); + + /** + * @brief Perform a record and playback test of specified sound + * devices along with an audio configuration. + * + * Call TT_CloseSoundLoopbackTest() to stop the loopback + * test. + * + * This function allows the use of #SpeexDSP to enable AGC and echo + * cancellation. + * + * @param nInputDeviceID Should be the @a nDeviceID extracted through + * TT_GetSoundDevices(). + * @param nOutputDeviceID Should be the @a nDeviceID extracted through + * TT_GetSoundDevices(). + * @param nSampleRate The sample rate the client's recorder should + * use. + * @param nChannels Number of channels to use, i.e. 1 = mono, 2 = stereo. + * @param bDuplexMode Both input and output devices MUST support + * the specified sample rate since this loop back test uses duplex + * mode ( @see TT_InitSoundDuplexDevices() ). Check out @c + * supportedSampleRates of #SoundDevice to see which sample rates + * are supported. The #SoundDevice must have the feature + * #SOUNDDEVICEFEATURE_DUPLEXMODE. + * @param lpAudioPreprocessor The preprocessing settings to use, i.e. AGC + * and denoising properties. Pass NULL to ignore AGC, denoise and AEC. + * @param lpSoundDeviceEffects The sound device effects which should be + * applied before the loopback test is started. + * @return Returns NULL in case of error, otherwise sound loop instance + * which can be closed by TT_CloseSoundLoopbackTest(); + * @see TT_InitSoundInputDevice() + * @see TT_InitSoundOutputDevice() + * @see TT_InitSoundDuplexDevices() + * @see TT_CloseSoundLoopbackTest() */ + TEAMTALKDLL_API TTSoundLoop* TT_StartSoundLoopbackTestEx(IN INT32 nInputDeviceID, + IN INT32 nOutputDeviceID, + IN INT32 nSampleRate, + IN INT32 nChannels, + IN TTBOOL bDuplexMode, + IN const AudioPreprocessor* lpAudioPreprocessor, + IN const SoundDeviceEffects* lpSoundDeviceEffects); + + + /** + * @brief Stop recorder and playback test. + * + * @c lpTTSoundLoop is destroyed after this call. + * + * @param lpTTSoundLoop Pointer to sound loop instance created by + * TT_StartSoundLoopbackTest(). + * @see TT_InitSoundInputDevice + * @see TT_InitSoundOutputDevice + * @see TT_StartSoundLoopbackTest */ + TEAMTALKDLL_API TTBOOL TT_CloseSoundLoopbackTest(IN TTSoundLoop* lpTTSoundLoop); + + /** + * @brief Initialize the sound input device (for recording audio). + * + * The @a nDeviceID of the #SoundDevice should be used as @a + * nInputDeviceID. + * + * The @c nInputDeviceID can be or'ed with + * #TT_SOUNDDEVICE_ID_SHARED_FLAG if the #TTInstance should share + * recording device with other instances. + * + * Notice fixed sound device ID for some platforms: + * - iOS + * - #TT_SOUNDDEVICE_ID_REMOTEIO + * - #TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO + * - Android + * - #TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT + * - All platforms + * - #TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL + * + * Calling this function will set the flag #CLIENT_SNDINPUT_READY. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nInputDeviceID The @a nDeviceID of #SoundDevice extracted + * through TT_GetSoundDevices(). + * @see SoundDevice + * @see TT_GetDefaultSoundDevices + * @see TT_GetSoundDevices + * @see TT_CloseSoundInputDevice + * @see TT_GetSoundInputLevel */ + TEAMTALKDLL_API TTBOOL TT_InitSoundInputDevice(IN TTInstance* lpTTInstance, + IN INT32 nInputDeviceID); + + /** + * @brief Setup sample rate, channels and frame size of shared + * sound input device. + * + * By default a shared sound device (checkout + * #TT_SOUNDDEVICE_ID_SHARED_FLAG) initialized by + * TT_InitSoundInputDevice will use the sound device's @c + * nDefaultSampleRate, @c nMaxInputChannels of #SoundDevice and + * a frame size (callback buffer) of nDefaultSampleRate * 0.04. + * + * TT_InitSoundInputSharedDevice() can be used to override these + * default settings. + * + * Note that TT_InitSoundInputSharedDevice() must be called prior + * to TT_InitSoundInputDevice(). Also ensure no shared sound input + * device is currently active. + * + * @param nSampleRate The sample rate to use on the shared + * device. Must exist in #SoundDevice's @c inputSampleRates. + * Pass zero to reset to default behaviour. + * @param nChannels The number of channels to use (mono, + * stereo). Must be less or equals to #SoundDevice's @c + * nMaxInputChannels. Pass zero to reset to default behaviour. + * @param nFrameSize The number of samples in each callback from + * the shared sound device. A 40 msec callback on a 48 KHz input + * is calculated like this: nFrameSize = 48000 * 0.04. Pass zero + * to reset to default behaviour. + * + * @see TT_InitSoundInputDevice() + * @see TT_InitSoundOutputSharedDevice() */ + TEAMTALKDLL_API TTBOOL TT_InitSoundInputSharedDevice(IN INT32 nSampleRate, + IN INT32 nChannels, + IN INT32 nFrameSize); + /** + * @brief Initialize the sound output device (for audio playback). + * + * The @a nDeviceID of the #SoundDevice should be used as @a + * nOutputDeviceID. + * + * The @c nOutputDeviceID can be or'ed with + * #TT_SOUNDDEVICE_ID_SHARED_FLAG if the #TTInstance should share + * output device with other instances. + * + * Notice fixed sound device ID for some platforms: + * - iOS + * - #TT_SOUNDDEVICE_ID_REMOTEIO + * - #TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO + * - Android + * - #TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT + * - All platforms + * - #TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL + * + * Callling this function will set the flag + * #CLIENT_SNDOUTPUT_READY. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nOutputDeviceID The @a nDeviceID of #SoundDevice extracted + * through TT_GetSoundDevices(). + * @see SoundDevice + * @see TT_GetDefaultSoundDevices + * @see TT_GetSoundDevices + * @see TT_CloseSoundOutputDevice */ + TEAMTALKDLL_API TTBOOL TT_InitSoundOutputDevice(IN TTInstance* lpTTInstance, + IN INT32 nOutputDeviceID); + + /** + * @brief Setup sample rate, channels and frame size of shared + * sound output device. + * + * By default a shared sound device (checkout + * #TT_SOUNDDEVICE_ID_SHARED_FLAG) initialized by + * TT_InitSoundOutputDevice will use the sound device's @c + * nDefaultSampleRate, @c nMaxOutputChannels of #SoundDevice and + * a frame size (callback buffer) of nDefaultSampleRate * 0.04. + * + * TT_InitSoundOutputSharedDevice() can be used to override these + * default settings. + * + * Note that TT_InitSoundOutputSharedDevice() must be called prior + * to TT_InitSoundOutputDevice(). Also ensure no shared sound output + * device is currently active. + * + * @param nSampleRate The sample rate to use on the shared + * device. Must exist in #SoundDevice's @c outputSampleRates. + * Pass zero to reset to default behaviour. + * @param nChannels The number of channels to use (mono, + * stereo). Must be less or equals to #SoundDevice's @c + * nMaxOutputChannels. Pass zero to reset to default behaviour. + * @param nFrameSize The number of samples in each callback from + * the shared sound device. A 40 msec callback on a 48KHz output + * is calculated like this: nFrameSize = 48000 * 0.04. Pass zero + * to reset to default behaviour. + * + * @see TT_InitSoundInputDevice() + * @see TT_InitSoundOutputSharedDevice() */ + TEAMTALKDLL_API TTBOOL TT_InitSoundOutputSharedDevice(IN INT32 nSampleRate, + IN INT32 nChannels, + IN INT32 nFrameSize); + /** + * @brief Enable duplex mode where multiple audio streams are + * mixed into a single stream using software. + * + * To use duplex mode the feature #SOUNDDEVICEFEATURE_DUPLEXMODE + * must be available on the #SoundDevice. + * + * If TT_InitSoundDuplexDevices() is successful the following + * flags will be set: + * + * - #CLIENT_SNDINOUTPUT_DUPLEX + * - #CLIENT_SNDOUTPUT_READY + * - #CLIENT_SNDINPUT_READY + * + * Call TT_CloseSoundDuplexDevices() to shut down duplex mode. + * + * Note that it is only the audio streams from users in the local + * client instance's current channel which will be mixed. If the + * local client instance calls TT_DoSubscribe() with + * #SUBSCRIBE_INTERCEPT_VOICE on a user in another channel then + * the audio from this user will be started in a separate + * stream. The reason for this is that the other user may use an + * audio codec with a different sample rate or number of audio + * channels. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nInputDeviceID The @a nDeviceID of #SoundDevice extracted + * through TT_GetSoundDevices(). + * @param nOutputDeviceID The @a nDeviceID of #SoundDevice extracted + * through TT_GetSoundDevices(). + * @see TT_InitSoundInputDevice() + * @see TT_InitSoundOutputDevice() + * @see TT_CloseSoundDuplexDevices() */ + TEAMTALKDLL_API TTBOOL TT_InitSoundDuplexDevices(IN TTInstance* lpTTInstance, + IN INT32 nInputDeviceID, + IN INT32 nOutputDeviceID); + + /** + * @brief Shutdown the input sound device. + * + * Callling this function will clear the flag + * #CLIENT_SNDINPUT_READY. + * + * If the local client instance is running in duplex mode (flag + * #CLIENT_SNDINOUTPUT_DUPLEX is set) then trying to close the + * sound device will fail since duplex mode require that both + * input and output sound devices are active at the same + * time. Therefore in order to close sound devices running in + * duplex mode call TT_CloseSoundDuplexDevices(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return If running in sound duplex mode (#CLIENT_SNDINOUTPUT_DUPLEX) + * then ensure to disable duplex mode prior to closing the sound device. + * @see TT_InitSoundInputDevice */ + TEAMTALKDLL_API TTBOOL TT_CloseSoundInputDevice(IN TTInstance* lpTTInstance); + + /** + * @brief Shutdown the output sound device. + * + * Callling this function will clear set the flag + * #CLIENT_SNDOUTPUT_READY. + * + * If the local client instance is running in duplex mode (flag + * #CLIENT_SNDINOUTPUT_DUPLEX is set) then trying to close the + * sound device will fail since duplex mode require that both + * input and output sound devices are active at the same + * time. Therefore in order to close sound devices running in + * duplex mode call TT_CloseSoundDuplexDevices(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return If running in sound duplex mode (#CLIENT_SNDINOUTPUT_DUPLEX) + * then ensure to disable duplex mode prior to closing the sound device. + * @see TT_InitSoundOutputDevice */ + TEAMTALKDLL_API TTBOOL TT_CloseSoundOutputDevice(IN TTInstance* lpTTInstance); + + /** + * @brief Shut down sound devices running in duplex mode. + * + * Calling this function only applies if sound devices has been + * initialized with TT_InitSoundDuplexDevices(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. */ + TEAMTALKDLL_API TTBOOL TT_CloseSoundDuplexDevices(IN TTInstance* lpTTInstance); + + /** + * @brief Set up audio effects on a sound device. + * + * Some devices, like Android, enable the user to toggle certain + * audio effects on their device to improve audio quality. The + * #SoundDeviceEffects-struct can be used to toggle these audio + * effects on the device. + * + * The following sound systems support TT_SetSoundDeviceEffects(): + * - #SOUNDSYSTEM_OPENSLES_ANDROID + * - Modifying #SoundDeviceEffects on Android will apply to all + * active #TTInstance, i.e. #SoundDeviceEffects are applied + * globally. + * - #SOUNDSYSTEM_WASAPI + * - TT_SetSoundDeviceEffects() must be called prior to + * TT_InitSoundDuplexDevices(). Sound device effects cannot be + * used with TT_InitSoundInputDevice() and TT_InitSoundOutputDevice() + * since Windows needs to know both input and output device upon + * initialization. + * + * This setting should not be confused with + * TT_SetSoundInputPreprocessEx() which runs entirely in software + * and is specific to the #TTInstance. + * + * Investigate #SoundDeviceFeature to see what audio effects are + * supported by the available #SoundDevice. + * + * Note that the sound effects may not be immediately applied + * since an sound device is not active until the #TTInstance joins + * a channel where the sound device knowns the sample rate and + * number of channels + * (mono/stereo). #INTERR_SNDEFFECT_FAILURE will be + * posted if the #SoundDeviceEffects was unable to initialize. + * + * @see TT_GetSoundDeviceEffects() */ + TEAMTALKDLL_API TTBOOL TT_SetSoundDeviceEffects(IN TTInstance* lpTTInstance, + IN const SoundDeviceEffects* lpSoundDeviceEffect); + + /** + * @brief Get the audio effects that are currently enabled. + * + * @see TT_SoundDeviceEffects() */ + TEAMTALKDLL_API TTBOOL TT_GetSoundDeviceEffects(IN TTInstance* lpTTInstance, + OUT SoundDeviceEffects* lpSoundDeviceEffect); + + /** + * @brief Get the volume level of the current recorded audio. + * + * The current level is updated at an interval specified in a channel's + * #AudioCodec. + * + * Note that the volume level will not be available until the + * client instance joins a channel, i.e. it knows what sample rate + * to use. + * + * If #WebRTCAudioPreprocessor is active with @c levelestimation enabled + * then the current input level is based on WebRTC's level estimater. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns a value between #SOUND_VU_MIN and #SOUND_VU_MAX. */ + TEAMTALKDLL_API INT32 TT_GetSoundInputLevel(IN TTInstance* lpTTInstance); + + /** + * @brief Set voice gaining of recorded audio. + * + * The gain level ranges from #SOUND_GAIN_MIN to #SOUND_GAIN_MAX + * where #SOUND_GAIN_DEFAULT is no gain. So 100 is 1/10 of the + * original volume and 8000 is 8 times the original volume. + * + * Note that using TT_SetSoundInputPreprocess() will override + * settings on input gain level. This is because automatic gain + * control will adjust the volume level. + * + * @deprecated Use TT_SetSoundInputPreprocessEx() and #TEAMTALK_AUDIOPREPROCESSOR. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nLevel A value from #SOUND_GAIN_MIN to #SOUND_GAIN_MAX. + * @see TT_GetSoundInputGainLevel */ + TEAMTALKDLL_API TTBOOL TT_SetSoundInputGainLevel(IN TTInstance* lpTTInstance, + IN INT32 nLevel); + + /** + * @brief Get voice gain level of outgoing audio + * + * @deprecated Use TT_GetSoundInputPreprocessEx() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return A value from #SOUND_GAIN_MIN to #SOUND_GAIN_MAX. + * @see TT_SetSoundInputGainLevel */ + TEAMTALKDLL_API INT32 TT_GetSoundInputGainLevel(IN TTInstance* lpTTInstance); + + /** + * @brief Enable sound preprocessor which should be used for + * processing audio recorded by the sound input device (voice input). + * + * To ensure common settings for all users in a channel it's + * possible to use the @c audiocfg member of #Channel as shared + * source for audio settings. + * + * In order for echo cancellation to work best it's important to + * also enable AGC in the #SpeexDSP. + * + * @deprecated Use TT_SetSoundInputPreprocessEx() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpSpeexDSP The sound preprocessor settings to use. + * Preferably from the #Channel's @c audiocfg member to ensure common + * settings for all users. + * @return TRUE on success, FALSE on failure. */ + TEAMTALKDLL_API TTBOOL TT_SetSoundInputPreprocess(IN TTInstance* lpTTInstance, + IN const SpeexDSP* lpSpeexDSP); + + /** + * @brief Get the sound preprocessor settings which are currently in use + * for recorded sound input device (voice input). + * + * @deprecated Use TT_GetSoundInputPreprocessEx() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpSpeexDSP A preallocated SpeexDSP which will + * receive the settings that is currently in effect. + * @return TRUE on success, FALSE on failure. */ + TEAMTALKDLL_API TTBOOL TT_GetSoundInputPreprocess(IN TTInstance* lpTTInstance, + OUT SpeexDSP* lpSpeexDSP); + + /** + * @brief Enable sound preprocessor which should be used for + * processing audio recorded by the sound input device (voice + * input). + * + * It is recommended to use the sound device's native echo + * cancellor, denoising and automatic gain control instead of + * #SpeexDSP. Checkout TT_SetSoundDeviceEffects(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpAudioPreprocessor The sound preprocessor settings to use. + * @return TRUE on success, FALSE on failure. */ + TEAMTALKDLL_API TTBOOL TT_SetSoundInputPreprocessEx(IN TTInstance* lpTTInstance, + IN const AudioPreprocessor* lpAudioPreprocessor); + + /** + * @brief Get the sound preprocessor settings which are currently + * in use for recorded sound input device (voice input). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpAudioPreprocessor A preallocated #AudioPreprocessor which will + * receive the settings that is currently in effect. + * @return TRUE on success, FALSE on failure. */ + TEAMTALKDLL_API TTBOOL TT_GetSoundInputPreprocessEx(IN TTInstance* lpTTInstance, + OUT AudioPreprocessor* lpAudioPreprocessor); + + /** + * @brief Set master volume. + * + * If still not loud enough use #TT_SetUserVolume. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nVolume A value from #SOUND_VOLUME_MIN to #SOUND_VOLUME_MAX. + * @see TT_SetUserVolume */ + TEAMTALKDLL_API TTBOOL TT_SetSoundOutputVolume(IN TTInstance* lpTTInstance, + IN INT32 nVolume); + + /** + * @brief Get master volume. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns the master volume. + * @see SOUND_VOLUME_MAX + * @see SOUND_VOLUME_MIN */ + TEAMTALKDLL_API INT32 TT_GetSoundOutputVolume(IN TTInstance* lpTTInstance); + + /** + * @brief Set all users mute. + * + * To stop receiving audio from a user call #TT_DoUnsubscribe. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param bMuteAll Whether to mute or unmute all users. + * @see CLIENT_SNDOUTPUT_MUTE */ + TEAMTALKDLL_API TTBOOL TT_SetSoundOutputMute(IN TTInstance* lpTTInstance, + IN TTBOOL bMuteAll); + + /** + * @brief Enable automatically position users using 3D-sound. + * + * 3D sound position requires #SOUNDDEVICEFEATURE_3DPOSITION. + * + * Note that 3d-sound does not work if sound is running in duplex + * mode (#CLIENT_SNDINOUTPUT_DUPLEX) or in stereo. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param bEnable TRUE to enable, otherwise FALSE. + * @see TT_SetUserPosition() */ + TEAMTALKDLL_API TTBOOL TT_Enable3DSoundPositioning(IN TTInstance* lpTTInstance, + IN TTBOOL bEnable); + + /** + * @brief Automatically position users using 3D-sound. + * + * 3D sound position requires #SOUNDDEVICEFEATURE_3DPOSITION. + * + * Note that 3d-sound does not work if sound is running in duplex + * mode (#CLIENT_SNDINOUTPUT_DUPLEX) or in stereo. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @see TT_SetUserPosition() */ + TEAMTALKDLL_API TTBOOL TT_AutoPositionUsers(IN TTInstance* lpTTInstance); + + /** + * @brief Enable/disable access to raw audio from individual + * users, local microphone input or mixed stream of all users. + * + * @deprecated Use TT_EnableAudioBlockEventEx(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID See description in TT_EnableAudioBlockEventEx() + * @param uStreamTypes See description in TT_EnableAudioBlockEventEx() + * @param bEnable See description in TT_EnableAudioBlockEventEx() + * @see TT_AcquireUserAudioBlock() + * @see TT_ReleaseUserAudioBlock() + * @see CLIENTEVENT_USER_AUDIOBLOCK */ + TEAMTALKDLL_API TTBOOL TT_EnableAudioBlockEvent(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamTypes uStreamTypes, + IN TTBOOL bEnable); + + /** + * @brief Enable/disable access to raw audio from individual + * users, local microphone input or mixed stream of all users. + * + * With audio block event enabled all audio which has been played + * will be accessible by calling TT_AcquireUserAudioBlock(). Every + * time a new #AudioBlock is available the event + * #CLIENTEVENT_USER_AUDIOBLOCK is generated. + * + * Special user IDs can be used to retrieve certain types of audio + * from the client instance: + * + * - #TT_LOCAL_USERID + * - Unprocessed audio from microphone when using #STREAMTYPE_VOICE. + * - Decoded PCM16 when using #STREAMTYPE_MEDIAFILE_AUDIO. + * - Decoded PCM16 when using #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO + * from all active local playbacks @see TT_InitLocalPlayback(). + * - #TT_LOCAL_TX_USERID + * - Processed audio from microphone that is transmitted to channel + * when using #STREAMTYPE_VOICE. + * - Not applicable for all other stream types except #STREAMTYPE_VOICE + * - #TT_MUXED_USERID + * - Decoded PCM16 from all specified audio streams (#StreamTypes) + * mixed into a single stream. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID User ID has different meanings depending on + * the #StreamType being passed. + * + * For #STREAMTYPE_VOICE: + * - Pass user ID to receive audio from voice stream. + * - Pass special user ID #TT_LOCAL_USERID for audio callback from + * local recorded audio prior to encoding/processing. + * - Pass special user ID #TT_MUXED_USERID to receive audio where + * voice stream has been mixed into the single stream. + * For #STREAMTYPE_MEDIAFILE_AUDIO: + * - Pass user ID to receive audio from media stream. + * - Pass #TT_LOCAL_USERID to receive audio from media file being + * streamed (transmitted). @see TT_StartStreamingMediaFileToChannel(). + * - Pass special user ID #TT_MUXED_USERID to receive audio where + * media stream has been mixed into the single stream. + * For #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO: + * - Pass session ID returned by TT_InitLocalPlayback() to receive + * audio stream from local playback. + * - Pass #TT_LOCAL_USERID to receive audio stream from all local + * playbacks. + * - Pass special user ID #TT_MUXED_USERID to receive audio where + * local playback stream has been mixed into the single stream. + * + * When using #TT_MUXED_USERID as user ID the #TTInstance must be + * in a channel with a configured #AudioCodec. Alternatively use + * @c lpAudioFormat to specify the audio properties. + * + * @param uStreamTypes Either #STREAMTYPE_VOICE, + * #STREAMTYPE_MEDIAFILE_AUDIO or #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO. + * For #TT_MUXED_USERID it's possible to mix #StreamTypes so e.g. + * #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO **or'ed** with + * #STREAMTYPE_VOICE) will return an #AudioBlock where these two + * stream types have been mixed together. + * + * @param lpAudioFormat Resample audio format from user to this + * #AudioFormat. Currently only #AFF_WAVE_FORMAT is supported. + * Specify NULL to get original audio format. + * + * When using #TT_MUXED_USERID as user ID in combination with @c + * lpAudioFormat will cause #AudioBlock to contain 20 msec of + * audio. If @c lpAudioFormat is NULL then the #TTInstance will + * use the audio format that is configured in the channel's + * #AudioCodec. + * + * @param bEnable Whether to enable the #CLIENTEVENT_USER_AUDIOBLOCK event. + * + * @see TT_AcquireUserAudioBlock() + * @see TT_ReleaseUserAudioBlock() + * @see CLIENTEVENT_USER_AUDIOBLOCK */ + TEAMTALKDLL_API TTBOOL TT_EnableAudioBlockEventEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamTypes uStreamTypes, + IN const AudioFormat* lpAudioFormat, + IN TTBOOL bEnable); + + /** @} */ + + /** @addtogroup transmission + * @{ */ + + /** + * @brief Transmit application provided raw audio in + * #AudioBlock-structs as #STREAMTYPE_VOICE, i.e. microphone + * input. + * + * Since #STREAMTYPE_VOICE is being replaced by audio input this + * means that while audio input is active then subsequent calls to + * TT_EnableVoiceTransmission() or TT_EnableVoiceActivation() will + * fail until the audio input has ended. + * + * If the flags #CLIENT_TX_VOICE or + * #CLIENT_SNDINPUT_VOICEACTIVATED are active then calling + * TT_InputAudioBlock() will fail because #STREAMTYPE_VOICE is + * already in use. + * + * TT_InsertAudioBlock() can be called multiple times until the + * client instance's internal queue is full. When the queue has + * been filled then monitor #CLIENTEVENT_AUDIOINPUT to see when + * more data can be queued. + * + * To end raw audio input set parameter @c lpAudioBlock to NULL + * and then TT_EnableVoiceTransmission() or + * TT_StartStreamingMediaFileToChannel() will be available again. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpAudioBlock The audio to submit as audio input. + * The member @c nStreamID of #AudioBlock is used to identify the + * audio input session which is currently in progress and is + * posted as the @c nSource of #CLIENTEVENT_AUDIOINPUT. + * The member @c uSampleIndex of #AudioBlock is ignored. */ + TEAMTALKDLL_API TTBOOL TT_InsertAudioBlock(IN TTInstance* lpTTInstance, + IN const AudioBlock* lpAudioBlock); + + /** + * @brief Start/stop transmitting of voice data from sound input. + * + * Sound input is initialized using TT_InitSoundInputDevice() or + * TT_InitSoundDuplexDevices(). + * + * Voice transmission is stream type #STREAMTYPE_VOICE. + * + * User rights required: + * - #USERRIGHT_TRANSMIT_VOICE + * + * Note that voice activation cannot be enabled when + * TT_InsertAudioBlock() is active. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param bEnable Enable/disable transmission. + * @return TRUE on success. FALSE if voice transmission could + * not be activated on the client instance. */ + TEAMTALKDLL_API TTBOOL TT_EnableVoiceTransmission(IN TTInstance* lpTTInstance, + IN TTBOOL bEnable); + + /** + * @brief Enable voice activation. + * + * The client instance will start transmitting audio if the + * recorded audio level is above or equal to the voice activation + * level set by TT_SetVoiceActivationLevel(). Once the voice + * activation level is reached the event + * #CLIENTEVENT_VOICE_ACTIVATION is posted. + * + * The current volume level can be queried calling + * #TT_GetSoundInputLevel. + * + * Voice transmission is stream type #STREAMTYPE_VOICE. + * + * User rights required: + * - #USERRIGHT_TRANSMIT_VOICE + * + * Note that voice activation cannot be enabled when + * TT_InsertAudioBlock() is active. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param bEnable TRUE to enable, otherwise FALSE. + * @return TRUE on success. FALSE if voice activation cannot + * be enabled on the client instance. + * + * @see CLIENT_SNDINPUT_VOICEACTIVATION + * @see TT_SetVoiceActivationStopDelay */ + TEAMTALKDLL_API TTBOOL TT_EnableVoiceActivation(IN TTInstance* lpTTInstance, + IN TTBOOL bEnable); + + /** + * @brief Set voice activation level. + * + * The current volume level can be queried calling + * TT_GetSoundInputLevel(). When TT_GetSoundInputLevel() is + * greater or equal to voice activation level then + * #CLIENTEVENT_VOICE_ACTIVATION is triggered. + * + * If #WebRTCAudioPreprocessor is active with @c voicedetection + * enabled then TT_SetVoiceActivationLevel() is not applicable. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nLevel Must be between #SOUND_VU_MIN and #SOUND_VU_MAX + * @see TT_EnableVoiceActivation + * @see TT_GetVoiceActivationLevel + * @see TT_SetVoiceActivationStopDelay */ + TEAMTALKDLL_API TTBOOL TT_SetVoiceActivationLevel(IN TTInstance* lpTTInstance, + IN INT32 nLevel); + + /** + * @brief Get voice activation level. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns A value between #SOUND_VU_MIN and #SOUND_VU_MAX + * @see TT_EnableVoiceActivation + * @see TT_SetVoiceActivationLevel */ + TEAMTALKDLL_API INT32 TT_GetVoiceActivationLevel(IN TTInstance* lpTTInstance); + + /** + * @brief Set the delay of when voice activation should be stopped. + * + * When TT_GetSoundInputLevel() becomes higher than the specified + * voice activation level the client instance will start + * transmitting until TT_GetSoundInputLevel() becomes lower than + * the voice activation level, plus a delay. This delay is by + * default set to 1500 msec but this value can be changed by + * calling TT_SetVoiceActivationStopDelay(). + * + * @see TT_EnableVoiceActivation + * @see TT_SetVoiceActivationLevel */ + TEAMTALKDLL_API TTBOOL TT_SetVoiceActivationStopDelay(IN TTInstance* lpTTInstance, + IN INT32 nDelayMSec); + + /** + * @brief Get the delay of when voice active state should be disabled. + * + * @return The number of miliseconds before voice activated state + * should be turned back to inactive. + * + * @see TT_SetVoiceActivationStopDelay + * @see TT_EnableVoiceActivation + * @see TT_SetVoiceActivationLevel */ + TEAMTALKDLL_API INT32 TT_GetVoiceActivationStopDelay(IN TTInstance* lpTTInstance); + + /** + * @brief Store all audio conversations with specific #AudioCodec + * settings to a single file. + * + * To record conversations from a specific channel to a single + * file call TT_StartRecordingMuxedAudioFileEx(). + * + * TT_StartRecordingMuxedAudioFile() can be used to record + * conversations "across" channels given that the channels use the + * same #AudioCodec properties (i.e. @c audiocodec member of + * #Channel). To receive audio outside the TeamTalk instance's + * channel use TT_DoSubscribe() and #SUBSCRIBE_INTERCEPT_VOICE. + * + * If the user changes to a channel which uses a different audio + * codec then the recording will continue but simply be silent + * until the user again joins a channel with the same audio codec + * as was used for initializing muxed audio recording. + * + * Calling TT_StartRecordingMuxedAudioFile() will enable the + * #CLIENT_MUX_AUDIOFILE flag from TT_GetFlags(). + * + * Call TT_StopRecordingMuxedAudioFile() to stop recording. Note + * that only one muxed audio recording can be active at the same + * time. + * + * Only #STREAMTYPE_VOICE is stored into the audio file, not + * #STREAMTYPE_MEDIAFILE_AUDIO. To record other stream types use + * TT_StartRecordingMuxedStreams(). + * + * TT_StartRecordingMuxedAudioFile() is mutually exclusive with + * TT_StartRecordingMuxedStreams(). + * + * Use TT_SetUserMediaStorageDir() to store users' audio streams + * in separate files. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpAudioCodec The audio codec which should be used as + * reference for muxing users' audio streams. In most situations + * this is the #AudioCodec of the current channel, i.e. + * TT_GetMyChannelID(). + * @param szAudioFileName The file to store audio to, e.g. + * C:\\MyFiles\\Conf.mp3. + * @param uAFF The audio format which should be used in the recorded + * file. The muxer will convert to this format. + * + * @see TT_SetUserMediaStorageDir() + * @see TT_StartRecordingMuxedAudioFileEx() + * @see TT_StartRecordingMuxedStreams() + * @see TT_StopRecordingMuxedAudioFile() */ + TEAMTALKDLL_API TTBOOL TT_StartRecordingMuxedAudioFile(IN TTInstance* lpTTInstance, + IN const AudioCodec* lpAudioCodec, + IN const TTCHAR* szAudioFileName, + IN AudioFileFormat uAFF); + + /** + * @brief Store audio conversations from a specific channel into a + * single file. + * + * To record audio outside the #TTInstance's current channel use + * the TT_DoSubscribe() with the #SUBSCRIBE_INTERCEPT_VOICE on all + * the user's in the channel. + * + * Unlike TT_StartRecordingMuxedAudioFile() this function does not + * toggle the flag #CLIENT_MUX_AUDIOFILE. + * + * Use TT_StartRecordingMuxedAudioFile() to record conversations + * from many different channels with the same #AudioCodec + * settings. + * + * Only #STREAMTYPE_VOICE is stored into the audio file, not + * #STREAMTYPE_MEDIAFILE_AUDIO. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The recording will contain the conversations + * from this channel ID. + * @param szAudioFileName The file to store audio to, e.g. + * C:\\MyFiles\\Conf.mp3. + * @param uAFF The audio format which should be used in the recorded + * file. The muxer will convert to this format. + * + * @see TT_StartRecordingMuxedAudioFile() + * @see TT_StartRecordingMuxedStreams() + * @see TT_StopRecordingMuxedAudioFileEx() */ + TEAMTALKDLL_API TTBOOL TT_StartRecordingMuxedAudioFileEx(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN const TTCHAR* szAudioFileName, + IN AudioFileFormat uAFF); + + /** + * @brief Mix multiple #StreamTypes into a single audio file. + * + * Both voice, media streams, etc. can be mixed together into a + * single file using this feature. + * + * Streams that can be mixed into a single file are: + * - #STREAMTYPE_VOICE + * - #STREAMTYPE_MEDIAFILE_AUDIO + * - #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO + * + * TT_StartRecordingMuxedAudioFile() is mutually exclusive with + * TT_StartRecordingMuxedStreams(). + * + * Use TT_StopRecordingMuxedAudioFile() to stop the recording. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param uStreamTypes The #StreamTypes to mix together. + * Streams that can be mixed into a single file are: + * - #STREAMTYPE_VOICE + * - #STREAMTYPE_MEDIAFILE_AUDIO + * - #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO + * @param lpAudioCodec The reference codec for the recording. The recording + * will use the sample rate and number of channels specified by the #AudioCodec. + * @param szAudioFileName The file to store audio to, e.g. + * C:\\MyFiles\\Conf.mp3. + * @param uAFF The audio format which should be used in the recorded + * file. The muxer will convert to this format. + * + * @see TT_StartRecordingMuxedAudioFile() + * @see TT_StartRecordingMuxedAudioFileEx() + * @see TT_StopRecordingMuxedAudioFileE() */ + TEAMTALKDLL_API TTBOOL TT_StartRecordingMuxedStreams(IN TTInstance* lpTTInstance, + IN StreamTypes uStreamTypes, + IN const AudioCodec* lpAudioCodec, + IN const TTCHAR* szAudioFileName, + IN AudioFileFormat uAFF); + + /** + * @brief Stop an active muxed audio recording. + * + * A muxed audio recording started with + * TT_StartRecordingMuxedAudioFile() can be stopped using this + * function. + * + * Calling TT_StopRecordingMuxedAudioFile() will clear the + * #CLIENT_MUX_AUDIOFILE flag from TT_GetFlags(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * + * @see TT_StartRecordingMuxedAudioFile() */ + TEAMTALKDLL_API TTBOOL TT_StopRecordingMuxedAudioFile(IN TTInstance* lpTTInstance); + + /** + * @brief Stop recording conversations from a channel to a single file. + * + * Stop a recording initiated by TT_StartRecordingMuxedAudioFileEx(). + * + * @see TT_StopRecordingMuxedAudioFile() */ + TEAMTALKDLL_API TTBOOL TT_StopRecordingMuxedAudioFileEx(IN TTInstance* lpTTInstance, + IN INT32 nChannelID); + + /** + * @brief Start transmitting from video capture device. + * + * The video capture device is initiated by calling + * TT_InitVideoCaptureDevice(). After joining a channel and + * calling this function the other users will see the video from + * the capture device. + * + * Video capture data is transmitted with stream type + * #STREAMTYPE_VIDEOCAPTURE and is subscribed/unsubscribed using + * #SUBSCRIBE_VIDEOCAPTURE. + * + * To stop transmitting call TT_StopVideoCaptureTransmission() + * + * User rights required: + * - #USERRIGHT_TRANSMIT_VIDEOCAPTURE. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpVideoCodec The video codec settings to use for + * transmission. + * + * @see TT_StartStreamingMediaFileToChannel() + * @see TT_EnableVoiceTransmission() */ + TEAMTALKDLL_API TTBOOL TT_StartVideoCaptureTransmission(IN TTInstance* lpTTInstance, + IN const VideoCodec* lpVideoCodec); + + /** + * @brief Stop transmitting from video capture device. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @see TT_StartVideoCaptureTransmission() */ + TEAMTALKDLL_API TTBOOL TT_StopVideoCaptureTransmission(IN TTInstance* lpTTInstance); + + /** @} */ + + /** @addtogroup videocapture + * @{ */ + + /** + * @brief Get the list of devices available for video capture. + * + * @param lpVideoDevices Array of VideoCaptureDevice-stucts where + * @a lpnHowMany hold the size of the array. Pass NULL to query + * the number of devices. + * @param lpnHowMany This is both an input and output + * parameter. If @a lpVideoDevices is NULL @a lpnHowMany will after + * the call hold the number of devices, otherwise it should hold + * the size of the @a lpVideoDevices array. + * @see TT_InitVideoCaptureDevice */ + TEAMTALKDLL_API TTBOOL TT_GetVideoCaptureDevices(IN OUT VideoCaptureDevice* lpVideoDevices, + IN OUT INT32* lpnHowMany); + + /** + * @brief Initialize a video capture device. + * + * To transmit video capture data to a channel call + * TT_StartVideoCaptureTransmission() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szDeviceID The device idenfier @a szDeviceID of #VideoCaptureDevice. + * @param lpVideoFormat The capture format to use, + * i.e. frame-rate, resolution and picture format. + * @see TT_GetVideoCaptureDevices + * @see TT_CloseVideoCaptureDevice */ + TEAMTALKDLL_API TTBOOL TT_InitVideoCaptureDevice(IN TTInstance* lpTTInstance, + IN const TTCHAR* szDeviceID, + IN const VideoFormat* lpVideoFormat); + /** + * @brief Close a video capture device. + * + * @see TT_InitVideoCaptureDevice */ + TEAMTALKDLL_API TTBOOL TT_CloseVideoCaptureDevice(IN TTInstance* lpTTInstance); + +#if defined(WIN32) + /** + * @brief Paint user's video frame using a Windows' DC (device + * context). + * + * Same as calling TT_PaintVideoFrameEx() like this: + * + @verbatim + TT_PaintVideoFrameEx(lpTTInstance, nUserID, hDC, + XDest, YDest, nDestWidth, + nDestHeight, 0, 0, + src_bmp_width, src_bmp_height); + @endverbatim + * + * @c src_bmp_width and @c src_bmp_height are extracted internally + * from the source image. */ + TEAMTALKDLL_API TTBOOL TT_PaintVideoFrame(IN HDC hDC, + IN INT32 XDest, + IN INT32 YDest, + IN INT32 nDestWidth, + IN INT32 nDestHeight, + IN VideoFrame* lpVideoFrame); + + /** + * @brief Paint user's video frame using a Windows' DC (device + * context). + * + * An application can either paint using #TT_AcquireUserVideoCaptureFrame + * which provides a raw RGB32 array of the image or the + * application can ask the client instance to paint the image + * using this function. + * + * Typically this paint operation will be called in the WM_PAINT + * message. Here is how the client instance paints internally: + * + @verbatim + StretchDIBits(hDC, nPosX, nPosY, nWidth, nHeight, XSrc, YSrc, + nSrcWidth, nSrcHeight, frame_buf, &bmi, + DIB_RGB_COLORS, SRCCOPY); + @endverbatim + * + * @param hDC The handle to the Windows device context. + * @param XDest Coordinate of left corner where to start painting. + * @param YDest Coordinate or top corner where to start painting. + * @param nDestWidth The width of the image. + * @param nDestHeight The height of the image. + * @param XSrc The left coordinate in the source bitmap of where + * to start reading. + * @param YSrc The top left coordinate in the source bitmap of where + * to start reading. + * @param nSrcWidth The number of width pixels to read from source bitmap. + * @param nSrcHeight The number of height pixels to read from source bitmap. + * @param lpVideoFrame Video frame retrieved by TT_AcquireUserVideoCaptureFrame() + * @see TT_AcquireUserVideoCaptureFrame */ + TEAMTALKDLL_API TTBOOL TT_PaintVideoFrameEx(IN HDC hDC, + IN INT32 XDest, + IN INT32 YDest, + IN INT32 nDestWidth, + IN INT32 nDestHeight, + IN INT32 XSrc, + IN INT32 YSrc, + IN INT32 nSrcWidth, + IN INT32 nSrcHeight, + IN VideoFrame* lpVideoFrame); +#endif + + /** @brief Extract a user's video capture frame for display. + * + * The #VideoFrame extracted from the client instance will contain a + * pointer to the image's frame buffer, so a RGB32 bitmap can be + * displayed in a window control. + * + * To release the acquired #VideoFrame call + * TT_ReleaseUserVideoCaptureFrame(). + * + * A video capture frame comes from a user's + * #STREAMTYPE_VIDEOCAPTURE. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID. 0 for local user. + * @return Returns video frame which will contain the image data. Note + * that it's the @a frameBuffer member of #VideoFrame which will contain + * the image data allocated internally by TeamTalk. Returns NULL if no + * video frame could be acquired. + * @see TT_ReleaseUserVideoCaptureFrame */ + TEAMTALKDLL_API VideoFrame* TT_AcquireUserVideoCaptureFrame(IN TTInstance* lpTTInstance, + IN INT32 nUserID); + + /** @brief Delete a user's video frame, acquired through + * TT_AcquireUserVideoCaptureFrame(), so its allocated resources can be + * released. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpVideoFrame Pointer to #VideoFrame which should be deallocated. + * @return Returns TRUE If a video frame was successfully deallocated. + * @see TT_AcquireUserVideoCaptureFrame */ + TEAMTALKDLL_API TTBOOL TT_ReleaseUserVideoCaptureFrame(IN TTInstance* lpTTInstance, + IN VideoFrame* lpVideoFrame); + /** @} */ + + /** @addtogroup mediastream + * @{ */ + + /** @brief Stream media file to channel, e.g. avi-, wav- or MP3-file. + * @see TT_StartStreamingMediaFileToChannelEx() */ + TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannel(IN TTInstance* lpTTInstance, + IN const TTCHAR* szMediaFilePath, + IN const VideoCodec* lpVideoCodec); + + /** + * @brief Stream media file to channel, e.g. avi, wav or MP3-file. + * + * Call TT_GetMediaFileInfo() to get the properties of a media + * file, i.e. audio and video format. + * + * The event #CLIENTEVENT_STREAM_MEDIAFILE is posted when + * the media file starts streaming. The flags #CLIENT_STREAM_AUDIO + * and/or #CLIENT_STREAM_VIDEO will be set if the call is successful. + * + * A media file is streamed using #STREAMTYPE_MEDIAFILE_AUDIO + * and/or #STREAMTYPE_MEDIAFILE_VIDEO. To subscribe/unsubscribe a + * media file being streamed use #SUBSCRIBE_MEDIAFILE. + * + * Streaming a media file requires + * #USERRIGHT_TRANSMIT_MEDIAFILE_VIDEO and/or + * #USERRIGHT_TRANSMIT_MEDIAFILE_AUDIO. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szMediaFilePath File path to media file. + * @param lpMediaFilePlayback Playback settings to pause, seek and + * preprocess audio. If #SPEEXDSP_AUDIOPREPROCESSOR then the echo + * cancellation part of #SpeexDSP is unused. Only denoise and AGC + * settings are applied. + * @param lpVideoCodec If video file then specify output codec properties + * here, otherwise NULL. + * + * @see TT_UpdateStreamingMediaFileToChannel() + * @see TT_StopStreamingMediaFileToChannel() + * @see TT_InitLocalPlayback() */ + TEAMTALKDLL_API TTBOOL TT_StartStreamingMediaFileToChannelEx(IN TTInstance* lpTTInstance, + IN const TTCHAR* szMediaFilePath, + IN const MediaFilePlayback* lpMediaFilePlayback, + IN const VideoCodec* lpVideoCodec); + + /** + * @brief Update active media file being streamed to channel. + * + * While streaming a media file to a channel it's possible to + * pause, seek and manipulate audio preprocessing by passing new + * #MediaFilePlayback properties. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpMediaFilePlayback Playback settings to pause, seek and + * preprocess audio. If #SPEEXDSP_AUDIOPREPROCESSOR then the echo + * cancellation part of #SpeexDSP is unused. Only denoise and AGC + * settings are applied. + * @param lpVideoCodec If video file then specify output codec properties + * here, otherwise NULL. + * + * @see TT_StartStreamingMediaFileToChannel() + * @see TT_StopStreamingMediaFileToChannel() */ + TEAMTALKDLL_API TTBOOL TT_UpdateStreamingMediaFileToChannel(IN TTInstance* lpTTInstance, + IN const MediaFilePlayback* lpMediaFilePlayback, + IN const VideoCodec* lpVideoCodec); + + /** + * @brief Stop streaming media file to channel. + * + * This will clear the flags #CLIENT_STREAM_AUDIO + * and/or #CLIENT_STREAM_VIDEO. + * + * @see TT_StartStreamingMediaFileToChannel() */ + TEAMTALKDLL_API TTBOOL TT_StopStreamingMediaFileToChannel(IN TTInstance* lpTTInstance); + + /** + * @brief Play media file using settings from #TTInstance. + * + * The sound system properties of the @c lpTTInstance will be used + * for playback, i.e. TT_SetSoundOutputMute(), + * TT_SetSoundOutputVolume() and TT_InitSoundOutputDevice(). + * + * Monitor progress of playback by checking for event + * #CLIENTEVENT_LOCAL_MEDIAFILE. + * + * Raw audio from local media playback can be retrieved using + * TT_EnableAudioBlockEvent(). + * + * A maximum of 16 simultaneous local media playbacks can be started. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szMediaFilePath Path to media file. + * @param lpMediaFilePlayback Playback settings to pause, seek and + * preprocess audio. If #SPEEXDSP_AUDIOPREPROCESSOR then the echo + * cancellation part of #SpeexDSP is unused. Only denoise and AGC + * settings are applied. + * + * @return A Session ID, @c nPlaybackSessionID, for identifing the + * media playback session. If Session ID is <= 0 indicates an error. + * + * @see TT_UpdateLocalPlayback() + * @see TT_StopLocalPlayback() + * @see TT_StartStreamingMediaFileToChannel() */ + TEAMTALKDLL_API INT32 TT_InitLocalPlayback(IN TTInstance* lpTTInstance, + IN const TTCHAR* szMediaFilePath, + IN const MediaFilePlayback* lpMediaFilePlayback); + + /** + * Update media file currently being played by TeamTalk instance. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nPlaybackSessionID Session ID created by TT_InitLocalPlayback(). + * @param lpMediaFilePlayback #AudioPreprocessorType of + * #AudioPreprocessor cannot be changed. It must be the same as + * used in TT_InitLocalPlayback(). + * + * @see TT_InitLocalPlayback() + * @see TT_StopLocalPlayback() + * @see TT_UpdateStreamingMediaFileToChannel() */ + TEAMTALKDLL_API TTBOOL TT_UpdateLocalPlayback(IN TTInstance* lpTTInstance, + IN INT32 nPlaybackSessionID, + IN const MediaFilePlayback* lpMediaFilePlayback); + + /** + * Stop media file currently being played by TeamTalk instance. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nPlaybackSessionID Session ID created by TT_InitLocalPlayback(). + * + * @see TT_InitLocalPlayback() + * @see TT_UpdateLocalPlayback() */ + TEAMTALKDLL_API TTBOOL TT_StopLocalPlayback(IN TTInstance* lpTTInstance, + IN INT32 nPlaybackSessionID); + + /** + * @brief Get the properties of a media file. + * + * Use this function to determine the audio and video properties of + * a media file, so the user knows what can be streamed. + * + * @see TT_StartStreamingMediaFileToChannel() */ + TEAMTALKDLL_API TTBOOL TT_GetMediaFileInfo(IN const TTCHAR* szMediaFilePath, + OUT MediaFileInfo* lpMediaFileInfo); + + /** @brief Extract a user's media video frame for display. + * + * The #VideoFrame extracted from the client instance will contain a + * pointer to the image's frame buffer, so a RGB32 bitmap can be + * displayed in a window control. + * + * To release the acquired #VideoFrame call + * TT_ReleaseUserMediaVideoFrame(). + * + * A media video frame comes from a user's + * #STREAMTYPE_MEDIAFILE_VIDEO. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID. 0 for local user. + * @return Returns video frame which will contain the image data. Note + * that it's the @a frameBuffer member of #VideoFrame which will contain + * the image data allocated internally by TeamTalk. Returns NULL if no + * video frame could be acquired. + * @see TT_ReleaseUserMediaVideoFrame() */ + TEAMTALKDLL_API VideoFrame* TT_AcquireUserMediaVideoFrame(IN TTInstance* lpTTInstance, + IN INT32 nUserID); + + /** @brief Delete a user's video frame, acquired through + * TT_AcquireUserMediaVideoFrame(), so its allocated resources can + * be released. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpVideoFrame Pointer to #VideoFrame which should be deallocated. + * @return Returns TRUE if a video frame was successfully deallocated. + * @see TT_AcquireUserMediaVideoFrame() */ + TEAMTALKDLL_API TTBOOL TT_ReleaseUserMediaVideoFrame(IN TTInstance* lpTTInstance, + IN VideoFrame* lpVideoFrame); + /** @} */ + + /** @addtogroup desktopshare + * @{ */ + + /** + * @brief Transmit a desktop window (bitmap) to users in the same + * channel. + * + * When TT_SendDesktopWindow() is called the first time a new + * desktop session will be started. To update the current desktop + * session call TT_SendDesktopWindow() again once the previous + * desktop transmission has finished. Tracking progress of the + * current desktop transmission is done by checking for the + * #CLIENTEVENT_DESKTOPWINDOW_TRANSFER event. While the desktop + * transmission is active the flag #CLIENT_TX_DESKTOP will be set + * on the local client instance. + * + * If the desktop window (bitmap) changes size (width/height) or + * format a new desktop session will be started. Also if the user + * changes channel a new desktop session will be started. Check @c + * nSessionID of #DesktopWindow to see if a new desktop session is + * started or the #CLIENTEVENT_USER_DESKTOPWINDOW event. + * + * Remote users will get the #CLIENTEVENT_USER_DESKTOPWINDOW event + * and can call TT_AcquireUserDesktopWindow() to retrieve the desktop + * window. + * + * User rights required: + * - #USERRIGHT_TRANSMIT_DESKTOP + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpDesktopWindow Properties of the bitmap. Set the @c nSessionID + * property to 0. + * @param nConvertBmpFormat Before transmission convert the bitmap to this + * format. + * @return TRUE if desktop window is queued for transmission. FALSE if + * @c nBitmapSize is invalid or if a desktop transmission is already + * active. + * @return -1 on error. 0 if bitmap has no changes. Greater than 0 on + * success. + * @see TT_CloseDesktopWindow() + * @see TT_SendDesktopCursorPosition() */ + TEAMTALKDLL_API INT32 TT_SendDesktopWindow(IN TTInstance* lpTTInstance, + IN const DesktopWindow* lpDesktopWindow, + IN BitmapFormat nConvertBmpFormat); + + /** + * @brief Close the current desktop session. + * + * Closing the desktop session will cause the users receiving the + * current desktop session to see the desktop session ID change to + * 0 in the #CLIENTEVENT_USER_DESKTOPWINDOW event. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. */ + TEAMTALKDLL_API TTBOOL TT_CloseDesktopWindow(IN TTInstance* lpTTInstance); + + /** + * @brief Get RGB values of the palette for the bitmap format. + * + * This currently only applies to bitmaps of format #BMP_RGB8_PALETTE. + * + * Note that the pointer returned is non-const which means the + * palette can be overwritten with a custom palette. The custom + * palette will then be used internally during bitmap + * conversion. + * + * @param nBmpPalette The bitmap format. Currently only #BMP_RGB8_PALETTE + * is supported. + * @param nIndex The index in the color table of the RGB values to + * extract. + * @return Pointer to RGB colors. First byte is Red, second Blue and + * third Green. Returns NULL if the color-index is invalid. */ + TEAMTALKDLL_API unsigned char* TT_Palette_GetColorTable(IN BitmapFormat nBmpPalette, + IN INT32 nIndex); +#if defined(WIN32) + + /** @brief Get the handle (HWND) of the window which is currently + * active (focused) on the Windows desktop. */ + TEAMTALKDLL_API HWND TT_Windows_GetDesktopActiveHWND(void); + + /** @brief Get the handle (HWND) of the Windows desktop (full desktop). */ + TEAMTALKDLL_API HWND TT_Windows_GetDesktopHWND(void); + + /** @brief Enumerate all the handles (@c HWND) of visible + * windows. Increment @c nIndex until the function returns + * FALSE. Use TT_Windows_GetWindow() to get information about each + * window. */ + TEAMTALKDLL_API TTBOOL TT_Windows_GetDesktopWindowHWND(IN INT32 nIndex, + OUT HWND* lpHWnd); + + /** + * @brief A struct which describes the properties of a window + * which can be shared. + * @see TT_Windows_GetDesktopWindowHWND() + * @see TT_Windows_GetWindow() */ + typedef struct ShareWindow + { + /** @brief The Windows handle of the window. */ + HWND hWnd; + /** @brief X coordinate of the window relative to the Windows desktop. */ + INT32 nWndX; + /** @brief Y coordinate of the window relative to the Windows desktop. */ + INT32 nWndY; + /** @brief The width in pixels of the window. */ + INT32 nWidth; + /** @brief The height in pixels of the window. */ + INT32 nHeight; + /** @brief The title of the window. */ + TTCHAR szWindowTitle[TT_STRLEN]; + } ShareWindow; + + /** + * @brief Get the properties of a window from its window handle (HWND). */ + TEAMTALKDLL_API TTBOOL TT_Windows_GetWindow(IN HWND hWnd, + OUT ShareWindow* lpShareWindow); + + /** + * @brief Transmit the specified window in a desktop session. + * + * Same as TT_SendDesktopWindow() except the properties for the + * #DesktopWindow are extracted automatically. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param hWnd Windows handle for the window to transmit. + * @param nBitmapFormat Bitmap format to use for the transmitted image. + * @param nDesktopProtocol The protocol to use for transmitting the image. + * @return See TT_SendDesktopWindow(). */ + TEAMTALKDLL_API INT32 TT_SendDesktopWindowFromHWND(IN TTInstance* lpTTInstance, + IN HWND hWnd, + IN BitmapFormat nBitmapFormat, + IN DesktopProtocol nDesktopProtocol); + + /** + * @brief Paint user's desktop window using a Windows' DC (device + * context). + * + * Same as calling TT_PaintDesktopWindowEx() like this: + * + @verbatim + TT_PaintDesktopWindowEx(lpTTInstance, nUserID, hDC, + XDest, YDest, nDestWidth, + nDestHeight, 0, 0, + 'src_bmp_width', 'src_bmp_height'); + @endverbatim + * + * @c src_bmp_width and @c src_bmp_height are extracted internally + * from the source image. */ + TEAMTALKDLL_API TTBOOL TT_PaintDesktopWindow(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN HDC hDC, + IN INT32 XDest, + IN INT32 YDest, + IN INT32 nDestWidth, + IN INT32 nDestHeight); + + /** + * @brief Paint user's desktop window using a Windows' DC (device + * context). + * + * An application can either paint a bitmap by using + * TT_AcquireUserDesktopWindow() which provides a pointer to a bitmap + * or the application can ask the client instance to paint the + * image using this function. + * + * Typically this paint operation will be called in the WM_PAINT + * message. Here is how the client instance paints internally: + * + @verbatim + StretchDIBits(hDC, nPosX, nPosY, nWidth, nHeight, XSrc, YSrc, + nSrcWidth, nSrcHeight, frame_buf, &bmi, + DIB_RGB_COLORS, SRCCOPY); + @endverbatim + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID. + * @param hDC The handle to the Windows device context. + * @param XDest Coordinate of left corner where to start painting. + * @param YDest Coordinate or top corner where to start painting. + * @param nDestWidth The width of the image. + * @param nDestHeight The height of the image. + * @param XSrc The left coordinate in the source bitmap of where + * to start reading. + * @param YSrc The top left coordinate in the source bitmap of where + * to start reading. + * @param nSrcWidth The number of width pixels to read from source bitmap. + * @param nSrcHeight The number of height pixels to read from source bitmap. + * @return TRUE on success. FALSE on error, e.g. if user doesn't exist. + * @see TT_AcquireUserDesktopWindow() */ + TEAMTALKDLL_API TTBOOL TT_PaintDesktopWindowEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN HDC hDC, + IN INT32 XDest, + IN INT32 YDest, + IN INT32 nDestWidth, + IN INT32 nDestHeight, + IN INT32 XSrc, + IN INT32 YSrc, + IN INT32 nSrcWidth, + IN INT32 nSrcHeight); +#endif + +#if defined(__APPLE__) + + /** + * @brief A struct which describes the properties of a window + * which can be shared. + * @see TT_MacOS_GetWindow() + * @see TT_MacOS_GetWindowFromWindowID() */ + typedef struct ShareWindow + { + /** @brief The CGWindowID */ + INT64 nWindowID; + /** @brief X coordinate of window. */ + INT32 nWindowX; + /** @brief Y coordinate of window. */ + INT32 nWindowY; + /** @brief The width of the window. */ + INT32 nWidth; + /** @brief The height of the window. */ + INT32 nHeight; + /** @brief The title of the window. */ + TTCHAR szWindowTitle[TT_STRLEN]; + /** @brief The PID of the owning process. */ + INT64 nPID; + } ShareWindow; + + /** @brief Enumerate all windows on the desktop. Increment @c + * nIndex until the function returns FALSE. Use + * TT_MacOS_GetWindowFromWindowID() to get information about the + * window, e.g. title, dimensions, etc. */ + TEAMTALKDLL_API TTBOOL TT_MacOS_GetWindow(IN INT32 nIndex, + OUT ShareWindow* lpShareWindow); + + /** @brief Get information about a window by passing its handle + * (@c CGWindowID). @see TT_MacOS_GetWindow() */ + TEAMTALKDLL_API TTBOOL TT_MacOS_GetWindowFromWindowID(IN INT64 nWindowID, + OUT ShareWindow* lpShareWindow); + + /** + * @brief Transmit the specified window in a desktop session. + * + * Same as TT_SendDesktopWindow() except the properties for the + * #DesktopWindow are extracted automatically. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nWindowID The handle of the window which should be converted to + * bitmap and sent to the server. + * @param nBitmapFormat Bitmap format to use for the transmitted image. + * @param nDesktopProtocol The protocol to use for transmitting the image. + * @return See TT_SendDesktopWindow(). */ + TEAMTALKDLL_API INT32 TT_SendDesktopFromWindowID(IN TTInstance* lpTTInstance, + IN INT64 nWindowID, + IN BitmapFormat nBitmapFormat, + IN DesktopProtocol nDesktopProtocol); +#endif + + /** + * @brief Send the position of mouse cursor to users in the same + * channel. + * + * It's only possible to send the mouse cursor position if there's + * a desktop session which is currently active. + * + * User rights required: + * - #USERRIGHT_TRANSMIT_DESKTOP + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nPosX X coordinate of mouse cursor. + * @param nPosY Y coordinate of mouse cursor. + * @see TT_SendDesktopWindow() */ + TEAMTALKDLL_API TTBOOL TT_SendDesktopCursorPosition(IN TTInstance* lpTTInstance, + IN UINT16 nPosX, + IN UINT16 nPosY); + /** + * @brief Send a mouse or keyboard event to a shared desktop + * window. + * + * If a user is sharing a desktop window it's possible for a + * remote user to take control of mouse and keyboard input on the + * remote computer. Read section @ref txdesktopinput on how to + * transmit desktop input to a shared window. + * + * When the remote user receives the issued #DesktopInput the + * event #CLIENTEVENT_USER_DESKTOPINPUT is posted to the client + * instance sharing the desktop window. + * + * User rights required: + * - #USERRIGHT_TRANSMIT_DESKTOPINPUT + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID who owns the shared desktop window + * and should receive desktop input. + * @param lpDesktopInputs An array of #DesktopInput structs which + * should be transmitted to the user. Internally in the client + * instance each user ID has an internal queue which can contain a + * maximum of 100 #DesktopInput structs. + * @param nDesktopInputCount Must be less or equal to #TT_DESKTOPINPUT_MAX. + * @return FALSE If user doesn't exist or if desktop input queue is full or + * if @c nUserID doesn't subscribe to desktop input. */ + TEAMTALKDLL_API TTBOOL TT_SendDesktopInput(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN const DesktopInput lpDesktopInputs[TT_DESKTOPINPUT_MAX], + IN INT32 nDesktopInputCount); + + /** + * @brief Acquire a user's desktop window (bitmap image). + * + * A user's desktop window can be extracted when the + * #CLIENTEVENT_USER_DESKTOPWINDOW is received. + * + * When the #DesktopWindow is no longer needed call + * TT_ReleaseUserDesktopWindow() to release the memory allocated by + * the client instance. + * + * A desktop window is simply a bitmap image. This method is used for + * retrieving the user's bitmap image. + * + * For #BMP_RGB8_PALETTE bitmaps check out TT_Palette_GetColorTable(). + * + * To convert bitmap to a different format use + * TT_AcquireUserDesktopWindowEx(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID. + * @return NULL If there's no active desktop window for this user. + * @see TT_SendDesktopWindow() */ + TEAMTALKDLL_API DesktopWindow* TT_AcquireUserDesktopWindow(IN TTInstance* lpTTInstance, + IN INT32 nUserID); + + /** + * @brief Same as TT_AcquireUserDesktopWindow() except an extra + * option for converting bitmap to a different format. + * + * It is highly adviced to use TT_AcquireUserDesktopWindow() since + * converting to a different bitmap format is very inefficient. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user's ID. + * @param nBitmapFormat The bitmap format to convert to. + * @return NULL If there's no active desktop window for this user. */ + TEAMTALKDLL_API DesktopWindow* TT_AcquireUserDesktopWindowEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN BitmapFormat nBitmapFormat); + + /** @brief Release memory allocated by the #DesktopWindow. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpDesktopWindow Pointer to #DesktopWindow to release. + * @see TT_AcquireUserDesktopWindow() */ + TEAMTALKDLL_API TTBOOL TT_ReleaseUserDesktopWindow(IN TTInstance* lpTTInstance, + IN DesktopWindow* lpDesktopWindow); + /** @} */ + + /** @addtogroup connectivity + * @{ */ + + /** + * @brief Setup encryption properties prior to TT_Connect(). + * + * If the server does peer verification then client must specify + * certificate file and private key file. + * + * Do not set encryption context unless server requires clients to + * do so. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpEncryptionContext Encryption properties for peer + * verification. */ + TEAMTALKDLL_API TTBOOL TT_SetEncryptionContext(IN TTInstance* lpTTInstance, + const EncryptionContext* lpEncryptionContext); + + /** + * @brief Connect to a server. + * + * This is a non-blocking call (but may block due to DNS lookup) + * so the user application must wait for the event + * #CLIENTEVENT_CON_SUCCESS to be posted once the connection has + * been established or #CLIENTEVENT_CON_FAILED if connection could + * not be established. If the connection could not be establish + * ensure to call #TT_Disconnect to close open connections in the + * client instance before trying again. + * + * Once connected call #TT_DoLogin to log on to the server. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szHostAddress The IP-address or hostname of the server. + * @param nTcpPort The host port of the server (TCP). + * @param nUdpPort The audio/video port of the server (UDP). + * @param nLocalTcpPort The local TCP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param nLocalUdpPort The local UDP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param bEncrypted Whether the server requires an encrypted + * connection. As of TeamTalk v5.5 and onwards encryption is + * available in both TeamTalk SDK Standard and Professional + * Edition. + * @return Returns TRUE if connection process was initiated. + * @see CLIENTEVENT_CON_SUCCESS + * @see CLIENTEVENT_CON_FAILED + * @see TT_DoLogin */ + TEAMTALKDLL_API TTBOOL TT_Connect(IN TTInstance* lpTTInstance, + IN const TTCHAR* szHostAddress, + IN INT32 nTcpPort, + IN INT32 nUdpPort, + IN INT32 nLocalTcpPort, + IN INT32 nLocalUdpPort, + IN TTBOOL bEncrypted); + + /** + * @brief Same as TT_Connect() but the option of providing a + * unique system-ID. + * + * The system-ID is set in the TeamTalk server API using + * TTS_StartServerSysID(). If a client tries to connect with a + * different system-ID that client will receive the error + * #CMDERR_INCOMPATIBLE_PROTOCOLS when trying to log in. + * + * Requires TeamTalk version 5.1.3.4506. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szHostAddress The IP-address or hostname of the server. + * @param nTcpPort The host port of the server (TCP). + * @param nUdpPort The audio/video port of the server (UDP). + * @param nLocalTcpPort The local TCP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param nLocalUdpPort The local UDP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param bEncrypted Whether the server requires an encrypted + * connection. As of TeamTalk v5.5 and onwards encryption is + * available in both TeamTalk SDK Standard and Professional + * Edition. + * @param szSystemID The identification of the conferencing system. + * The default value is "teamtalk". See TTS_StartServerSysID() + * @return Returns TRUE if connection process was initiated. */ + TEAMTALKDLL_API TTBOOL TT_ConnectSysID(IN TTInstance* lpTTInstance, + IN const TTCHAR* szHostAddress, + IN INT32 nTcpPort, + IN INT32 nUdpPort, + IN INT32 nLocalTcpPort, + IN INT32 nLocalUdpPort, + IN TTBOOL bEncrypted, + IN const TTCHAR* szSystemID); + + /** + * @brief Bind to specific IP-address prior to connecting to server. + * + * Same as TT_Connect() except that this also allows which IP-address + * to bind to on the local interface. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szHostAddress The IP-address or hostname of the server. + * @param nTcpPort The host port of the server (TCP). + * @param nUdpPort The audio/video port of the server (UDP). + * @param szBindIPAddr The IP-address to bind to on the local interface + * in dotted decimal format, e.g. 192.168.1.10. + * @param nLocalTcpPort The local TCP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param nLocalUdpPort The local UDP port which should be used. + * Setting it to 0 makes OS select a port number (recommended). + * @param bEncrypted Whether the server requires an encrypted + * connection. As of TeamTalk v5.5 and onwards encryption is + * available in both TeamTalk SDK Standard and Professional + * Edition. + * @see TT_Connect */ + TEAMTALKDLL_API TTBOOL TT_ConnectEx(IN TTInstance* lpTTInstance, + IN const TTCHAR* szHostAddress, + IN INT32 nTcpPort, + IN INT32 nUdpPort, + IN const TTCHAR* szBindIPAddr, + IN INT32 nLocalTcpPort, + IN INT32 nLocalUdpPort, + IN TTBOOL bEncrypted); + + /** + * @brief Disconnect from the server. + * + * This will clear the flag #CLIENT_CONNECTED and #CLIENT_CONNECTING. + * + * Use #TT_CloseTeamTalk to release all resources allocated by the + * client instance. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. */ + TEAMTALKDLL_API TTBOOL TT_Disconnect(IN TTInstance* lpTTInstance); + + /** + * @brief Query the maximum size of UDP data packets to the user + * or server. + * + * The #CLIENTEVENT_CON_MAX_PAYLOAD_UPDATED event is posted when + * the query has finished. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user to query or 0 for querying + * server. Currently only @c nUserID = 0 is supported. */ + TEAMTALKDLL_API TTBOOL TT_QueryMaxPayload(IN TTInstance* lpTTInstance, + IN INT32 nUserID); + + /** + * @brief Retrieve client statistics of bandwidth usage and + * response times. + * + * @see ClientStatistics */ + TEAMTALKDLL_API TTBOOL TT_GetClientStatistics(IN TTInstance* lpTTInstance, + OUT ClientStatistics* lpClientStatistics); + + /** + * @brief Update the client instance's default keep alive settings. + * + * It is generally discouraged to change the client instance's + * keep alive settings unless the network has special + * requirements. + * + * After calling TT_SetClientKeepAlive() it is recommended doing a + * TT_DoPing() since all TCP and UDP keep alive timers will be + * restarted. + * + * @see TT_DoPing() + * @see TT_GetClientKeepAlive() + * @see TT_GetClientStatistics() */ + TEAMTALKDLL_API TTBOOL TT_SetClientKeepAlive(IN TTInstance* lpTTInstance, + IN const ClientKeepAlive* lpClientKeepAlive); + + /** + * @brief Get the client instance's current keep alive settings. + * + * @see TT_DoPing() + * @see TT_SetClientKeepAlive() + * @see TT_GetClientStatistics() */ + TEAMTALKDLL_API TTBOOL TT_GetClientKeepAlive(IN TTInstance* lpTTInstance, + OUT ClientKeepAlive* lpClientKeepAlive); + + /** @} */ + + /** @addtogroup commands + * @{ */ + + /** @brief Ping server and wait for server to reply. + * + * Use this command to check if the server is responding. + * + * If the client instance doesn't ping the server within the timeout + * specified by @c nUserTimeout in #ServerProperties, then the server + * will disconnect the client. + * + * The client instance automatically pings the server at half the time + * specified by @c nUserTimeout in #ServerProperties. + * + * #CLIENTEVENT_CMD_PROCESSING is posted if server replies. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. */ + TEAMTALKDLL_API INT32 TT_DoPing(IN TTInstance* lpTTInstance); + + /** @brief Same as TT_DologinEx() but without the option to + * specify @c szClientName. Kept for backwards compatibility. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szNickname The nickname to use. + * @param szUsername The username of the #UserAccount set up on the + * server. + * @param szPassword The password of the user account on the server. Leave + * blank if no account is needed on the server. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. */ + TEAMTALKDLL_API INT32 TT_DoLogin(IN TTInstance* lpTTInstance, + IN const TTCHAR* szNickname, + IN const TTCHAR* szUsername, + IN const TTCHAR* szPassword); + + + /** + * @brief Logon to a server. + * + * Once connected to a server call this function to logon. If + * the login is successful #CLIENTEVENT_CMD_MYSELF_LOGGEDIN is + * posted, otherwise #CLIENTEVENT_CMD_ERROR. Once logged on it's + * not possible to talk to other users until the client instance + * joins a channel. Call #TT_DoJoinChannel to join a channel. + * + * Possible errors: + * - #CMDERR_INCORRECT_CHANNEL_PASSWORD + * - #CMDERR_INVALID_ACCOUNT + * - #CMDERR_MAX_SERVER_USERS_EXCEEDED + * - #CMDERR_SERVER_BANNED + * - #CMDERR_ALREADY_LOGGEDIN + * + * Requires TeamTalk version 5.1.3.4506. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szNickname The nickname to use. + * @param szUsername The username of the #UserAccount set up on the + * server. + * @param szPassword The password of the user account on the server. Leave + * blank if no account is needed on the server. + * @param szClientName The name of the client application used. This is an + * optional value and can be kept blank. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see ServerProperties + * @see TT_DoJoinChannel + * @see CLIENTEVENT_CMD_MYSELF_LOGGEDIN + * @see CLIENTEVENT_CMD_ERROR */ + TEAMTALKDLL_API INT32 TT_DoLoginEx(IN TTInstance* lpTTInstance, + IN const TTCHAR* szNickname, + IN const TTCHAR* szUsername, + IN const TTCHAR* szPassword, + IN const TTCHAR* szClientName); + + /** + * @brief Logout of the server. + * + * If successful the event #CLIENTEVENT_CMD_MYSELF_LOGGEDOUT + * will be posted. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see CLIENTEVENT_CMD_MYSELF_LOGGEDOUT */ + TEAMTALKDLL_API INT32 TT_DoLogout(IN TTInstance* lpTTInstance); + + /** + * @brief Create a new channel and join it. + * + * This function can also be used to join an existing channel and + * in this case the parameters @a szTopic and @a szOpPassword are + * ignored. + * + * When #TT_DoJoinChannel is used to create channels it works + * similar to IRC. If the client instance tries to join a channel + * which does not exist it will be created as a new channel. If + * the client instance is the last user to leave a channel the + * channel will be removed on the server. + * + * If the channel is created successfully the event + * #CLIENTEVENT_CMD_CHANNEL_NEW will be sent, followed by + * #CLIENTEVENT_CMD_USER_JOINED. + * + * User rights required: + * - #USERRIGHT_CREATE_TEMPORARY_CHANNEL + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_INCORRECT_CHANNEL_PASSWORD + * - #CMDERR_MAX_CHANNEL_USERS_EXCEEDED + * - #CMDERR_ALREADY_IN_CHANNEL + * - #CMDERR_AUDIOCODEC_BITRATE_LIMIT_EXCEEDED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpChannel The channel to join or create if it doesn't already + * exist. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoLeaveChannel + * @see TT_DoMakeChannel + * @see CLIENTEVENT_CMD_CHANNEL_NEW + * @see CLIENTEVENT_CMD_MYSELF_JOINED */ + TEAMTALKDLL_API INT32 TT_DoJoinChannel(IN TTInstance* lpTTInstance, + IN const Channel* lpChannel); + + /** + * @brief Join an existing channel. + * + * This command basically calls #TT_DoJoinChannel but omits the + * unnecessary parameters for only joining a channel and not + * creating a new one. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_INCORRECT_CHANNEL_PASSWORD + * - #CMDERR_MAX_CHANNEL_USERS_EXCEEDED + * - #CMDERR_ALREADY_IN_CHANNEL + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel to join. + * @param szPassword The password for the channel to join. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoLeaveChannel + * @see TT_DoMakeChannel + * @see CLIENTEVENT_CMD_CHANNEL_NEW + * @see CLIENTEVENT_CMD_MYSELF_JOINED */ + TEAMTALKDLL_API INT32 TT_DoJoinChannelByID(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN const TTCHAR* szPassword); + + /** + * @brief Leave the current channel. + * + * Note that #TT_DoLeaveChannel() doesn't take any parameters + * since a user can only participate in one channel at the time. + * If command is successful the event #CLIENTEVENT_CMD_USER_LEFT + * will be posted. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_NOT_IN_CHANNEL + * - #CMDERR_CHANNEL_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoJoinChannel + * @see CLIENTEVENT_CMD_MYSELF_LEFT */ + TEAMTALKDLL_API INT32 TT_DoLeaveChannel(IN TTInstance* lpTTInstance); + + /** + * @brief Change the client instance's nick name. + * + * The event #CLIENTEVENT_CMD_USER_UPDATE will be posted if the + * update was successful. + * + * Command will be rejected if #USERRIGHT_LOCKED_NICKNAME is set. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szNewNick is the new nick name to use. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see CLIENTEVENT_CMD_USER_UPDATE */ + TEAMTALKDLL_API INT32 TT_DoChangeNickname(IN TTInstance* lpTTInstance, + IN const TTCHAR* szNewNick); + + /** + * @brief Change the client instance's currect status + * + * The event #CLIENTEVENT_CMD_USER_UPDATE will be posted if the update + * was successful. + * + * Command will be rejected if #USERRIGHT_LOCKED_STATUS is set. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nStatusMode The value for the status mode. + * @param szStatusMessage The user's message associated with the status + * mode. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see CLIENTEVENT_CMD_USER_UPDATE */ + TEAMTALKDLL_API INT32 TT_DoChangeStatus(IN TTInstance* lpTTInstance, + IN INT32 nStatusMode, + IN const TTCHAR* szStatusMessage); + + /** + * @brief Send a text message to either a user or a channel. + * + * Can also be a broadcast message which is received by all users + * on the server. This, however, requires + * #USERRIGHT_TEXTMESSAGE_BROADCAST. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpTextMessage A preallocated text-message struct. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see USERRIGHT_TEXTMESSAGE_BROADCAST */ + TEAMTALKDLL_API INT32 TT_DoTextMessage(IN TTInstance* lpTTInstance, + IN const TextMessage* lpTextMessage); + + /** + * @brief Make another user operator of a channel. + * + * User rights required: + * - #USERRIGHT_OPERATOR_ENABLE + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user who should become channel operator. + * @param nChannelID The channel where the user should become operator. + * @param bMakeOperator Whether user should be op'ed or deop'ed. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoChannelOpEx */ + TEAMTALKDLL_API INT32 TT_DoChannelOp(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID, + IN TTBOOL bMakeOperator); + + /** + * @brief Make another user operator of a channel using the + * @a szOpPassword of #Channel. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_USER_NOT_FOUND + * - #CMDERR_INCORRECT_OP_PASSWORD + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user who should become channel operator. + * @param nChannelID The channel where the user should become operator. + * @param szOpPassword The @a szOpPassword of #Channel. + * @param bMakeOperator Whether user should be op'ed or deop'ed. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoChannelOp */ + TEAMTALKDLL_API INT32 TT_DoChannelOpEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID, + IN const TTCHAR* szOpPassword, + IN TTBOOL bMakeOperator); + + /** + * @brief Kick user from either channel or server. + * + * To ban a user call #TT_DoBanUser before #TT_DoKickUser. + * + * User rights required: + * - #USERRIGHT_KICK_USERS + * - Alternative channel-operator (see TT_DoChannelOp()). + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user to kick. + * @param nChannelID The channel where the user shoul be kicked from + * or specify 0 to kick the user off the server. + * + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoBanUser */ + TEAMTALKDLL_API INT32 TT_DoKickUser(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID); + + /** + * @brief Send a file to the specified channel. + * + * If user is logged on as an admin the file can be located in any + * channel. If the user is not an admin the file must be located + * in the same channel as the user is currently participating in. + * The file being uploaded must have a file size which is less + * than the disk quota of the channel, minus the sum of all the + * files in the channel. The disk quota of a channel can be + * obtained in the @c nDiskQuota of the #Channel struct passed to + * #TT_GetChannel. + * + * User rights required: + * - #USERRIGHT_UPLOAD_FILES + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_MAX_DISKUSAGE_EXCEEDED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_FILETRANSFER_NOT_FOUND + * - #CMDERR_OPENFILE_FAILED + * - #CMDERR_FILE_NOT_FOUND + * - #CMDERR_FILE_ALREADY_EXISTS + * - #CMDERR_FILESHARING_DISABLED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel of where to put the file. Only + * admins can upload in channel other then their own. + * @param szLocalFilePath The path of the file to upload, e.g. C:\\myfile.txt. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see Channel + * @see TT_GetChannel */ + TEAMTALKDLL_API INT32 TT_DoSendFile(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN const TTCHAR* szLocalFilePath); + + /** + * @brief Download a file from the specified channel. + * + * If user is logged on as an admin the file can be located in any + * channel. If the user is not an admin the file must be located + * in the same channel as the user is currently participating in. + * + * User rights required: + * - #USERRIGHT_DOWNLOAD_FILES + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_FILETRANSFER_NOT_FOUND + * - #CMDERR_OPENFILE_FAILED + * - #CMDERR_FILE_NOT_FOUND + * - #CMDERR_FILESHARING_DISABLED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel of where to get the file. Only + * admins can download in channel other then their own. + * @param nFileID The ID of the file which is passed by #CLIENTEVENT_CMD_FILE_NEW. + * @param szLocalFilePath The path of where to store the file, e.g. + * C:\\myfile.txt. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see CLIENTEVENT_CMD_FILE_NEW + * @see TT_GetChannelFiles */ + TEAMTALKDLL_API INT32 TT_DoRecvFile(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN INT32 nFileID, + IN const TTCHAR* szLocalFilePath); + + /** + * @brief Delete a file from a channel. + * + * A user is allowed to delete a file from a channel if either the + * user is an admin, operator of the channel or owner of the + * file. To be owner of the file a user must have a #UserAccount + * on the server. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_FILE_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel where the file is located. + * @param nFileID The ID of the file to delete. The ID of the file which + * is passed by #CLIENTEVENT_CMD_FILE_NEW. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see CLIENTEVENT_CMD_FILE_NEW + * @see TT_GetChannelFiles */ + TEAMTALKDLL_API INT32 TT_DoDeleteFile(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN INT32 nFileID); + + /** + * @brief Subscribe to user events and/or data. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user this should affect. + * @param uSubscriptions Union of #Subscription to subscribe to. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see Subscription */ + TEAMTALKDLL_API INT32 TT_DoSubscribe(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN Subscriptions uSubscriptions); + + /** + * @brief Unsubscribe to user events/data. This can be used to ignore messages + * or voice data from a specific user. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user this should affect. + * @param uSubscriptions Union of #Subscription to unsubscribe. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see Subscription */ + TEAMTALKDLL_API INT32 TT_DoUnsubscribe(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN Subscriptions uSubscriptions); + + /** + * @brief Make a new channel on the server. + * + * This command only applies to users with #USERRIGHT_MODIFY_CHANNELS. + * + * User rights required: + * - #USERRIGHT_MODIFY_CHANNELS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_ALREADY_EXISTS + * - #CMDERR_CHANNEL_NOT_FOUND If channel's combined path is longer than + * #TT_STRLEN. + * - #CMDERR_INCORRECT_CHANNEL_PASSWORD If the password is longer than + * #TT_STRLEN. + * - #CMDERR_UNKNOWN_AUDIOCODEC If the server doesn't support the audio + * codec. Introduced in version 4.1.0.1264. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpChannel A Channel-structure containing information about + * the channel being created. The Channel's member @a nChannelID is ignored. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoJoinChannel */ + TEAMTALKDLL_API INT32 TT_DoMakeChannel(IN TTInstance* lpTTInstance, + IN const Channel* lpChannel); + + /** + * @brief Update a channel's properties. + * + * Users with #USERRIGHT_MODIFY_CHANNELS can update all properties of + * a channel. + * + * A user with channel-operator status (see TT_DoChannelOp()) can + * also update a channel's properties, but is not able to change the + * following properties: + * - @c audiocodec + * - @c nDiskQuota + * - @c nMaxUsers + * - @c uChannelType + * - Cannot modify #CHANNEL_PERMANENT + * + * Note that a channel's #AudioCodec cannot be changed + * if there's currently users in the channel. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_CHANNEL_HAS_USERS + * - #CMDERR_CHANNEL_ALREADY_EXISTS + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpChannel A Channel-structure containing information about + * the channel being modified. The channel member's @c nParentID + * and @c szName are ignored. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoMakeChannel */ + TEAMTALKDLL_API INT32 TT_DoUpdateChannel(IN TTInstance* lpTTInstance, + IN const Channel* lpChannel); + + /** + * @brief Remove a channel from a server. + * + * This command only applies to users with + * #USERRIGHT_MODIFY_CHANNELS. + * + * If there's any users in the channel they will be kicked and + * subchannels will be deleted as well. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel to remove. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoMakeChannel */ + TEAMTALKDLL_API INT32 TT_DoRemoveChannel(IN TTInstance* lpTTInstance, + IN INT32 nChannelID); + + /** + * @brief Issue command to move a user from one channel to + * another. + * + * User rights required: + * - #USERRIGHT_MOVE_USERS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_CHANNEL_NOT_FOUND + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID User to be moved. + * @param nChannelID Channel where user should be put into. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoMoveUserByID */ + TEAMTALKDLL_API INT32 TT_DoMoveUser(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID); + + /** + * @brief Update server properties. + * + * User rights required: + * - #USERRIGHT_UPDATE_SERVERPROPERTIES + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpServerProperties A structure holding the information to be set + * on the server. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_GetServerProperties */ + TEAMTALKDLL_API INT32 TT_DoUpdateServer(IN TTInstance* lpTTInstance, + IN const ServerProperties* lpServerProperties); + + /** + * @brief Issue command to list user accounts on the server. + * + * The event #CLIENTEVENT_CMD_USERACCOUNT will be posted for every + * #UserAccount on the server. Ensure not to list too many many user + * accounts since this may suspend event handling. + * + * User accounts can be used to create users with different user + * rights. + * + * Only #USERTYPE_ADMIN can issue this command. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nIndex Index of first user to display. + * @param nCount The number of users to retrieve. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see UserAccount + * @see UserType */ + TEAMTALKDLL_API INT32 TT_DoListUserAccounts(IN TTInstance* lpTTInstance, + IN INT32 nIndex, + IN INT32 nCount); + + /** + * @brief Issue command to create a new user account on the + * server. + * + * Check out section @ref useradmin to see how the server handles + * users. + * + * Only #USERTYPE_ADMIN can issue this command. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_INVALID_USERNAME + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpUserAccount The properties of the user account to create. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoListUserAccounts + * @see TT_DoDeleteUserAccount + * @see UserAccount + * @see UserType */ + TEAMTALKDLL_API INT32 TT_DoNewUserAccount(IN TTInstance* lpTTInstance, + IN const UserAccount* lpUserAccount); + + /** + * @brief Issue command to delete a user account on the server. + * + * Only #USERTYPE_ADMIN can issue this command. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_ACCOUNT_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szUsername The username of the user account to delete. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoListUserAccounts + * @see TT_DoNewUserAccount + * @see UserAccount + * @see UserType */ + TEAMTALKDLL_API INT32 TT_DoDeleteUserAccount(IN TTInstance* lpTTInstance, + IN const TTCHAR* szUsername); + + /** + * @brief Issue a ban command on a user. + * + * The ban applies to the user's IP-address. Call #TT_DoKickUser + * to kick the user off the server. + * + * User rights required: + * - #USERRIGHT_BAN_USERS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_USER_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user to ban. + * @param nChannelID Set to 0 to ban from logging in. Otherwise specify + * user's current channel. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoKickUser() + * @see TT_DoListBans() + * @see TT_DoBanIPAddress() + * @see TT_DoBan() + * @see TT_DoBanUser() + * @see TT_DoBanUserEx() */ + TEAMTALKDLL_API INT32 TT_DoBanUser(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID); + + /** + * @brief Ban the user with @c nUserID using the ban types specified. + * + * If @c uBanTypes contains #BANTYPE_USERNAME then the username cannot join + * the channel where @n nUserID is currently present. + * + * If @c uBanTypes contains #BANTYPE_IPADDR then the IP-address cannot join + * the channel where @n nUserID is currently present. + * + * @see TT_DoListBans() + * @see TT_DoBan() */ + TEAMTALKDLL_API INT32 TT_DoBanUserEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN BanTypes uBanTypes); + + /** + * @brief Ban the properties specified in @c lpBannedUser. + * + * The @c uBanTypes specifies what the ban applies to. If + * #BANTYPE_CHANNEL is specified in the @c uBanTypes of @c + * lpBannedUser then the ban applies to joining a channel, + * TT_DoJoinChannel(). Otherwise the ban applies to login, + * TT_DoLogin(). + * + * If #BANTYPE_IPADDR is specified then the IP-address must be set + * in @c szIPAddress and any IP-address matching will receive + * #CMDERR_SERVER_BANNED or #CMDERR_CHANNEL_BANNED for + * TT_DoLogin() or TT_DoJoinChannel(). If instead + * #BANTYPE_USERNAME is specified then @c szUsername must be set + * and the same rule applies as for IP-addresses. + * + * @see TT_DoListBans() + * @see TT_DoBanUserEx() */ + TEAMTALKDLL_API INT32 TT_DoBan(IN TTInstance* lpTTInstance, + IN const BannedUser* lpBannedUser); + + /** + * @brief Issue a ban command on an IP-address user. + * + * Same as TT_DoBanUser() except this command applies to IP-addresses + * and therefore doesn't require a user to be logged in. + * + * User rights required: + * - #USERRIGHT_BAN_USERS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szIPAddress The IP-address to ban. + * @param nChannelID Set to zero. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoKickUser + * @see TT_DoListBans */ + TEAMTALKDLL_API INT32 TT_DoBanIPAddress(IN TTInstance* lpTTInstance, + IN const TTCHAR* szIPAddress, + IN INT32 nChannelID); + + /** + * @brief Unban the user with the specified IP-address. + * + * User rights required: + * - #USERRIGHT_BAN_USERS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_BAN_NOT_FOUND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szIPAddress The IP-address to unban. + * @param nChannelID Set to zero. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * + * @see TT_DoUnBanUserEx() + * @see TT_DoBanUser + * @see TT_DoListBans + * @see TT_DoBanIPAddress */ + TEAMTALKDLL_API INT32 TT_DoUnBanUser(IN TTInstance* lpTTInstance, + IN const TTCHAR* szIPAddress, + IN INT32 nChannelID); + /** + * @brief Unban the properties specified in #BannedUser. + * + * The uBanTypes in #BannedUser determines which properties should have + * their ban remove. E.g. uBanTypes = #BANTYPE_USERNAME and + * @c szUsername = "guest" will remove all bans where the username + * is "guest". + * + * @see TT_DoBan() */ + TEAMTALKDLL_API INT32 TT_DoUnBanUserEx(IN TTInstance* lpTTInstance, + IN const BannedUser* lpBannedUser); + + /** + * @brief Issue a command to list the banned users. + * + * The event #CLIENTEVENT_CMD_BANNEDUSER will be posted for every + * #BannedUser on the server. + * + * User rights required: + * - #USERRIGHT_BAN_USERS + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID Set to zero. + * @param nIndex Index of first ban to display. + * @param nCount The number of bans to display. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoBanUser() */ + TEAMTALKDLL_API INT32 TT_DoListBans(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN INT32 nIndex, + IN INT32 nCount); + + /** + * @brief Save the server's current state to its settings file + * (typically the server's .xml file). + * + * Only #USERTYPE_ADMIN can issue this command. + * + * Note that the server only saves channels with the flag + * #CHANNEL_PERMANENT. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. + * @see TT_DoUpdateServer */ + TEAMTALKDLL_API INT32 TT_DoSaveConfig(IN TTInstance* lpTTInstance); + + /** + * @brief Get the server's current statistics. + * + * Event #CLIENTEVENT_CMD_SERVERSTATISTICS will be posted when + * server has sent response. + * + * Only #USERTYPE_ADMIN can issue this command. + * + * Possible errors: + * - #CMDERR_NOT_LOGGEDIN + * - #CMDERR_NOT_AUTHORIZED + * - #CMDERR_UNKNOWN_COMMAND + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. */ + TEAMTALKDLL_API INT32 TT_DoQueryServerStats(IN TTInstance* lpTTInstance); + + /** + * @brief Quit from server. + * + * Possible errors: + * - none + * + * This will generate a #CLIENTEVENT_CON_LOST since the server + * will drop the client. + * + * @return Returns command ID which will be passed in + * #CLIENTEVENT_CMD_PROCESSING event when the server is processing the + * command. -1 is returned in case of error. */ + TEAMTALKDLL_API INT32 TT_DoQuit(IN TTInstance* lpTTInstance); + /** @} */ + + /** @addtogroup server + * @{ + */ + + /** + * @brief Get the server's properties. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpServerProperties A struct to hold the server's properties. */ + TEAMTALKDLL_API TTBOOL TT_GetServerProperties(IN TTInstance* lpTTInstance, + OUT ServerProperties* lpServerProperties); + + /** + * @brief Get all the users on the server. + * + * If only users in a specific channel is needed call + * TT_GetChannelUsers() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpUsers A preallocated array which has room for @a lpnHowMany + * #User elements. Pass NULL to query the number of users in channel. + * @param lpnHowMany The number of elements in the array @a lpUsers. If + * @a lpUsers is NULL @a lpnHowMany will receive the number of users. + * @see TT_GetChannelUsers + * @see TT_GetUser + * @see TT_GetServerChannels*/ + TEAMTALKDLL_API TTBOOL TT_GetServerUsers(IN TTInstance* lpTTInstance, + IN OUT User* lpUsers, + IN OUT INT32* lpnHowMany); + /** @} */ + + /** @addtogroup channels + * @{ */ + + /** + * @brief Get the root channel's ID + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns the ID of the root channel. If 0 is returned no root + * channel exists. + * @see TT_GetMyChannelID + * @see TT_GetChannelPath */ + TEAMTALKDLL_API INT32 TT_GetRootChannelID(IN TTInstance* lpTTInstance); + + /** + * @brief Get the channel which the local client instance is + * currently participating in. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns the ID of the current channel. If 0 is returned the + * user is not participating in a channel. */ + TEAMTALKDLL_API INT32 TT_GetMyChannelID(IN TTInstance* lpTTInstance); + + /** + * @brief Get the channel with a specific ID. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel to get information about. + * @param lpChannel A preallocated struct which will receive the + * channel's properties. + * @return FALSE if unable to retrieve channel otherwise TRUE. */ + TEAMTALKDLL_API TTBOOL TT_GetChannel(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + OUT Channel* lpChannel ); + + /** + * @brief Get the channel's path. Channels are separated by '/'. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The channel's ID. + * @param szChannelPath Will receive the channel's path. + * @return Returns TRUE if channel exists. */ + TEAMTALKDLL_API TTBOOL TT_GetChannelPath(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + OUT TTCHAR szChannelPath[TT_STRLEN]); + + /** + * @brief Get the channel ID of the supplied path. Channels are + * separated by '/' + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szChannelPath Will receive the channel's path. + * @return The channel's ID or 0 on error. */ + TEAMTALKDLL_API INT32 TT_GetChannelIDFromPath(IN TTInstance* lpTTInstance, + IN const TTCHAR* szChannelPath); + + /** + * @brief Get the IDs of all users in a channel. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The channel's ID. + * @param lpUsers A preallocated array which has room for @a lpnHowMany + * user elements. Pass NULL to query the number of users in channel. + * @param lpnHowMany The number of elements in the array @a lpUsers. If + * @a lpUserIDs is NULL @a lpnHowMany will receive the number of users in + * the channel. + * @see User + * @see TT_GetChannel */ + TEAMTALKDLL_API TTBOOL TT_GetChannelUsers(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN OUT User* lpUsers, + IN OUT INT32* lpnHowMany); + + /** + * @brief Get the list of the files in a channel which can be + * downloaded. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel to extract the files from. + * @param lpRemoteFiles A preallocated struct which will receive + * file information. If @a lpRemoteFiles is NULL then @a lpnHowMany will + * receive the number of files in the channel. + * @param lpnHowMany Use for both querying and specifying the number of + * files. If @a lpRemoteFiles is NULL then lpnHowMany will receive the number + * of files in the channel. If @a lpRemoteFiles is not NULL then + * @a lpnHowMany should specify the size of the @a lpRemoteFiles array. + * @see TT_GetChannelFile */ + TEAMTALKDLL_API TTBOOL TT_GetChannelFiles(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN OUT RemoteFile* lpRemoteFiles, + IN OUT INT32* lpnHowMany); + + /** + * @brief Get information about a file which can be downloaded. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nChannelID The ID of the channel to extract the file from. + * @param nFileID The ID of the file. + * @param lpRemoteFile A preallocated struct which will receive + * file information. */ + TEAMTALKDLL_API TTBOOL TT_GetChannelFile(IN TTInstance* lpTTInstance, + IN INT32 nChannelID, + IN INT32 nFileID, + OUT RemoteFile* lpRemoteFile); + + /** + * @brief Check whether user is operator of a channel + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID the ID of the user to check. + * @param nChannelID the ID of the channel to check whether user + * is operator of. */ + TEAMTALKDLL_API TTBOOL TT_IsChannelOperator(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN INT32 nChannelID); + + /** + * @brief Get all the channels on the server. + * + * Use TT_GetChannel() to get more information about each of the + * channels. + * @see TT_GetServerUsers() */ + TEAMTALKDLL_API TTBOOL TT_GetServerChannels(IN TTInstance* lpTTInstance, + IN OUT Channel* lpChannels, + IN OUT INT32* lpnHowMany); + /** @} */ + + /** @addtogroup users + * @{ */ + + /** + * @brief Get the local client instance's user ID. + * + * This information can be retrieved after the + * #CLIENTEVENT_CMD_MYSELF_LOGGEDIN event. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return Returns the user ID assigned to the current user on the server. + * -1 is returned if no ID has been assigned to the user. */ + TEAMTALKDLL_API INT32 TT_GetMyUserID(IN TTInstance* lpTTInstance); + + /** + * @brief Get the local client instance's #UserAccount. + * + * This information can be retrieved after + * #CLIENTEVENT_CMD_MYSELF_LOGGEDIN event. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param lpUserAccount The local client's user account registered on + * the server. Note that the @a szPassword field of #UserAccount + * will not be set. + * @see TT_DoLogin */ + TEAMTALKDLL_API TTBOOL TT_GetMyUserAccount(IN TTInstance* lpTTInstance, + OUT UserAccount* lpUserAccount); + + /** + * @brief Get the client instance's user type. + * + * This information can be retrieved after + * #CLIENTEVENT_CMD_MYSELF_LOGGEDIN event. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return A bitmask of the type of user based on #UserType. + * @see TT_GetMyUserAccount + * @see TT_DoLogin + * @see UserType */ + TEAMTALKDLL_API UserTypes TT_GetMyUserType(IN TTInstance* lpTTInstance); + + /** + * @brief Convenience method for TT_GetMyUserAccount() + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + */ + TEAMTALKDLL_API UserRights TT_GetMyUserRights(IN TTInstance* lpTTInstance); + + /** + * @brief If an account was used in #TT_DoLogin then this value will + * return the @a nUserData from the #UserAccount. + * + * This information can be retrieved after + * #CLIENTEVENT_CMD_MYSELF_LOGGEDIN event. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @return If set, @a nUserData from #UserAccount, otherwise 0. + * @see TT_GetMyUserAccount */ + TEAMTALKDLL_API INT32 TT_GetMyUserData(IN TTInstance* lpTTInstance); + + /** + * @brief Get the user with the specified ID. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user to extract. + * @param lpUser A preallocated #User struct. + * @see TT_GetUserByUsername */ + TEAMTALKDLL_API TTBOOL TT_GetUser(IN TTInstance* lpTTInstance, + IN INT32 nUserID, OUT User* lpUser); + + /** + * @brief Get statistics for data and packet reception from a user. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user to extract. + * @param lpUserStatistics A preallocated #UserStatistics struct. */ + TEAMTALKDLL_API TTBOOL TT_GetUserStatistics(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + OUT UserStatistics* lpUserStatistics); + /** + * @brief Get the user with the specified username. + * + * Remember to take into account that multiple users can log in + * with the same account if #USERRIGHT_MULTI_LOGIN is specified. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param szUsername The user's username (from #UserAccount). + * @param lpUser A preallocated #User struct. */ + TEAMTALKDLL_API TTBOOL TT_GetUserByUsername(IN TTInstance* lpTTInstance, + IN const TTCHAR* szUsername, + OUT User* lpUser); + /** @} */ + + /** @addtogroup sounddevices + * @{ */ + + /** + * @brief Set the volume of a user. + * + * Note that it's a virtual volume which is being set since the + * master volume affects the user volume. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user whose volume will be changed. + * @param nStreamType The type of stream to change, either + * #STREAMTYPE_VOICE or #STREAMTYPE_MEDIAFILE_AUDIO. + * @param nVolume Must be between #SOUND_VOLUME_MIN and #SOUND_VOLUME_MAX. + * @see TT_SetSoundOutputVolume */ + TEAMTALKDLL_API TTBOOL TT_SetUserVolume(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN INT32 nVolume); + + /** + * @brief Mute a user. + * + * To stop receiving audio from a user call #TT_DoUnsubscribe with + * #SUBSCRIBE_VOICE. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The user ID of the user to mute (or unmute). + * @param nStreamType The type of stream to change, either + * #STREAMTYPE_VOICE or #STREAMTYPE_MEDIAFILE_AUDIO. + * @param bMute TRUE will mute, FALSE will unmute. + * @see TT_SetSoundOutputMute */ + TEAMTALKDLL_API TTBOOL TT_SetUserMute(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN TTBOOL bMute); + + /** + * @brief Set the delay of when a user should no longer be considered + * as playing audio (either voice or audio from media file). + * + * When a user starts talking the #CLIENTEVENT_USER_STATECHANGE is + * triggered with @c uUserState changing. A user will remain in this active + * state until no packets are received from this user, plus a + * delay (due to network interruptions). This delay is by default + * set to 500 msec but can be changed by calling + * TT_SetUserStoppedTalkingDelay(). */ + TEAMTALKDLL_API TTBOOL TT_SetUserStoppedPlaybackDelay(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN INT32 nDelayMSec); + + /** + * @brief Set the configuration for de-jitter measures for a user. + * + * TeamTalk can add a fixed delay at the start of the playout of a user stream. + * This delay acts as a buffer to smooth out jittering (non-constant delays) + * in the reception of network packets. + * The fixed delay is applied at the start of every new stream, such as a new PTT session. + * The default fixed delay is zero. + * + * TeamTalk can also apply adaptive jitter buffering where the actual jitter is measured + * and the delay at the start of a stream is adapted based on those measurements. + * The adaptive delay will not go below the fixed delay. + * The parameter nMaxAdaptiveDelayMSec maximizes the total adaptive delay. + * By default, the adaptive mechanism is OFF + * + * By default, all jitter control is OFF + * + * The result of jitter buffering is that playout frames will get buffered in the playout buffer. + * Make sure to also size the playout buffer for the expected jitter via #TT_SetUserAudioStreamBufferSize + * + * @param lpTTInstance Pointer to client instance created by #TT_InitTeamTalk. + * @param nUserID The user ID of the user to apply the configuration to. + * @param nStreamType The type of stream to change, currently only + * #STREAMTYPE_VOICE is supported. Other types are a no-op. + * @param lpJitterConfig The jitter buffer configuration.*/ + TEAMTALKDLL_API TTBOOL TT_SetUserJitterControl(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN const JitterConfig* lpJitterConfig); + + /** + * @brief Get the de-jitter configuration for a user. + * + * @see TT_SetUserJitterControl() + * + * @param lpTTInstance Pointer to client instance created by #TT_InitTeamTalk. + * @param nUserID The user ID of the user to apply the configuration to. + * @param nStreamType The type of stream to change, currently only + * #STREAMTYPE_VOICE is supported. Other types are a no-op. + * @param lpJitterConfig Pointer to an application-provided jitter buffer + configuration that will be filled upon return.*/ + TEAMTALKDLL_API TTBOOL TT_GetUserJitterControl(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN JitterConfig* lpJitterConfig); + + /** + * @brief Set the position of a user. + * + * 3D sound position requires #SOUNDDEVICEFEATURE_3DPOSITION. + * + * This can only be done using DirectSound (#SOUNDSYSTEM_DSOUND), + * a mono channel and with sound duplex mode + * (#CLIENT_SNDINOUTPUT_DUPLEX) disabled. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID ID of user. + * @param nStreamType The type of stream to change, either + * #STREAMTYPE_VOICE or #STREAMTYPE_MEDIAFILE_AUDIO. + * @param x Distance in meters to user (left/right). + * @param y Distance in meters to user (back/forward). + * @param z Distance in meters to user (up/down). */ + TEAMTALKDLL_API TTBOOL TT_SetUserPosition(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN float x, + IN float y, + IN float z); + + /** + * @brief Set whether a user should speak in the left, right or + * both speakers. This function only works if #AudioCodec has been + * set to use stereo. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID ID of user. + * @param nStreamType The type of stream to change, either + * #STREAMTYPE_VOICE or #STREAMTYPE_MEDIAFILE_AUDIO. + * @param bLeftSpeaker TRUE if user should be played in left speaker. + * @param bRightSpeaker TRUE if user should be played in right speaker. */ + TEAMTALKDLL_API TTBOOL TT_SetUserStereo(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamType nStreamType, + IN TTBOOL bLeftSpeaker, + IN TTBOOL bRightSpeaker); + + /** + * @brief Store user's audio to disk. + * + * Set the path of where to store audio from a user to disk. + * Event #CLIENTEVENT_USER_RECORD_MEDIAFILE is triggered when + * recording starts/stops. + * + * To stop recording set @a szFolderPath to an empty string and @a + * uAFF to #AFF_NONE. + * + * To store audio of users not in current channel of the client + * instance check out the section @ref spying. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the #User which should store audio to + * disk. Pass 0 to store local instance's media stream. + * @param szFolderPath The path on disk to where files should be + * stored. This value will be stored in @a szMediaStorageDir of + * #User. + * @param szFileNameVars The file name used for audio files can + * consist of the following variables: \%nickname\%, \%username\%, + * \%userid\%, \%counter\%, \%starttick\% and a specified time based on @c + * strftime (google @c 'strftime' for a description of the + * format. The default format used by TeamTalk is: + * '\%Y\%m\%d-\%H\%M\%S #\%userid\% \%username\%'. The \%counter\% + * variable is a 9 digit integer which is incremented for each + * audio file. The file extension is automatically appended based + * on the file type (.wav for #AFF_WAVE_FORMAT and .mp3 for + * AFF_MP3_*_FORMAT). Pass NULL or empty string to revert to + * default format. + * @param uAFF The #AudioFileFormat to use for storing audio files. Passing + * #AFF_NONE will cancel/reset the current recording. + * @return FALSE if path is invalid, otherwise TRUE. + * @see User + * @see CLIENTEVENT_USER_RECORD_MEDIAFILE */ + TEAMTALKDLL_API TTBOOL TT_SetUserMediaStorageDir(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN const TTCHAR* szFolderPath, + IN const TTCHAR* szFileNameVars, + IN AudioFileFormat uAFF); + + /** + * @brief Store user's audio to disk. + * + * This extension has an extra parameter for an aditional delay that will be waited + * before closing the per-user recording. This allows the recording to still capture + * all voice of a stream in a single file even if there's heavy network jitter. + * A recording will always be started if a different stream is received for the + * user. The delay is added on top of the standard playout delay that can be set via + * + * Note that the delay starts after the last packet was written to the playout and thus + * the delay is already 'counting' when the jitter-buffered playout is still playing + * + * Only supported for #STREAMTYPE_VOICE. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID See description in TT_SetUserMediaStorageDir() + * @param szFolderPath See description in TT_SetUserMediaStorageDir() + * @param szFileNameVars See description in TT_SetUserMediaStorageDir() + * @param uAFF See description in TT_SetUserMediaStorageDir() + * @param nStopRecordingExtraDelayMSec Extra delay before closing the recording file + * default is 0. + * @return FALSE if path is invalid, otherwise TRUE. + * @see TT_SetUserMediaStorageDir() */ + TEAMTALKDLL_API TTBOOL TT_SetUserMediaStorageDirEx(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN const TTCHAR* szFolderPath, + IN const TTCHAR* szFileNameVars, + IN AudioFileFormat uAFF, + IN INT32 nStopRecordingExtraDelayMSec); + + /** + * @brief Change the amount of media data which can be buffered + * in the user's playback queue. + * + * Increasing the media buffer size is especially important when + * the user is currently streaming a media file using + * TT_StartStreamingMediaFileToChannel(). Once streaming has finished + * it is recommended to reset the media buffer, i.e. setting it + * to zero. + * + * A simple way to notify users that the client instance is streaming + * a media file is to change the status of the local client instance + * using TT_DoChangeStatus() or to send a #TextMessage using + * TT_DoTextMessage(). + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nUserID The ID of the user who should have changed + * the size of the media buffer. + * @param uStreamType The stream type to apply the buffer for, i.e. + * either #STREAMTYPE_VOICE or #STREAMTYPE_MEDIAFILE_AUDIO. + * @param nMSec The number of miliseconds of audio and video which + * should be allowed to be stored in the media buffer. 2000 - 3000 + * msec is a good size for a media buffer. Set the media + * buffer size to 0 msec to reset the media buffer to its default value. + */ + TEAMTALKDLL_API TTBOOL TT_SetUserAudioStreamBufferSize(IN TTInstance* lpTTInstance, + IN INT32 nUserID, + IN StreamTypes uStreamType, + IN INT32 nMSec); + + /** + * @brief Extract the raw audio associated with the event + * #CLIENTEVENT_USER_AUDIOBLOCK. + * + * To enable access to raw audio first call + * TT_EnableAudioBlockEvent(). Whenever new audio becomes + * available the event #CLIENTEVENT_USER_AUDIOBLOCK is generated + * and TT_AcquireUserAudioBlock() can be called to extract the + * audio. + * + * The #AudioBlock contains shared memory with the local client + * instance therefore always remember to call + * TT_ReleaseUserAudioBlock() to release the shared memory. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param uStreamTypes The stream type to extract, either #STREAMTYPE_VOICE + * #STREAMTYPE_MEDIAFILE_AUDIO, #STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO. + * @param nUserID The ID of the user to retrieve the #AudioBlock from. + * Basically #TTMessage's @c nSource from #CLIENTEVENT_USER_AUDIOBLOCK. + * @see TT_ReleaseUserAudioBlock() + * @see TT_EnableAudioBlockEvent() + * @see CLIENTEVENT_USER_AUDIOBLOCK */ + TEAMTALKDLL_API AudioBlock* TT_AcquireUserAudioBlock(IN TTInstance* lpTTInstance, + IN StreamTypes uStreamTypes, + IN INT32 nUserID); + + /** + * @brief Release the shared memory of an #AudioBlock. + * + * All #AudioBlock-structures extracted through + * TT_AcquireUserAudioBlock() must be released again since they + * share memory with the local client instance. + * + * Never access @c lpAudioBlock after releasing its + * #AudioBlock. This will cause the application to crash with a + * memory exception. + * + * @see TT_AcquireUserAudioBlock() + * @see CLIENTEVENT_USER_AUDIOBLOCK */ + TEAMTALKDLL_API TTBOOL TT_ReleaseUserAudioBlock(IN TTInstance* lpTTInstance, + IN AudioBlock* lpAudioBlock); + + /** @} */ + + /** @ingroup channels + * @brief Get information about an active file transfer. + * + * An active file transfer is one which has been posted through the + * event #CLIENTEVENT_FILETRANSFER. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nTransferID The ID of the file transfer to investigate. Transfer + * ID is passed by #CLIENTEVENT_FILETRANSFER. + * @param lpFileTransfer A preallocated struct which will receive the file + * transfer information. + * @see TT_CancelFileTransfer */ + TEAMTALKDLL_API TTBOOL TT_GetFileTransferInfo(IN TTInstance* lpTTInstance, + IN INT32 nTransferID, + OUT FileTransfer* lpFileTransfer); + + /** @ingroup channels + * @brief Cancel an active file transfer. + * + * An active file transfer is one which has been post through the + * event #CLIENTEVENT_FILETRANSFER. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nTransferID The ID of the file transfer to investigate. Transfer + * ID is passed by #CLIENTEVENT_FILETRANSFER. */ + TEAMTALKDLL_API TTBOOL TT_CancelFileTransfer(IN TTInstance* lpTTInstance, + IN INT32 nTransferID); + + /** @ingroup errorhandling + * @brief Get textual discription of an error message. + * + * Get a description of an error code posted by either + * #CLIENTEVENT_CMD_ERROR or #CLIENTEVENT_INTERNAL_ERROR. + * + * @param nError The number of the error. + * @param szErrorMsg A text description of the error. + * @see CLIENTEVENT_CMD_ERROR + * @see CLIENTEVENT_INTERNAL_ERROR */ + TEAMTALKDLL_API void TT_GetErrorMessage(IN INT32 nError, + OUT TTCHAR szErrorMsg[TT_STRLEN]); + + + /** @addtogroup desktopshare + * @{ */ + + /** + * @brief Translate to and from TeamTalk's intermediate key-codes (TTKEYCODE). + * @see #CLIENTEVENT_USER_DESKTOPINPUT */ + typedef enum TTKeyTranslate + { + /** @brief Perform no translation. */ + TTKEY_NO_TRANSLATE = 0, + /** @brief Translate from Windows scan-code to TTKEYCODE. The + * Windows scan-code can be retrieved in Windows' @c + * WM_KEYDOWN and @c WM_KEYUP event. */ + TTKEY_WINKEYCODE_TO_TTKEYCODE = 1, + /** @brief Translate from TTKEYCODE to Windows scan-code. */ + TTKEY_TTKEYCODE_TO_WINKEYCODE = 2, + /** @brief Translate from Mac OS X Carbon @c kVK_* key-code to + * TTKEYCODE. The Mac OS X key-codes are defined in Carbon's + * API. */ + TTKEY_MACKEYCODE_TO_TTKEYCODE = 3, + /** @brief Translate from TTKEYCODE to Mac OS X Carbon @c + * kVK_* key-code. */ + TTKEY_TTKEYCODE_TO_MACKEYCODE = 4 + } TTKeyTranslate; + + /** + * @brief Translate platform key-code to and from TeamTalk's + * intermediate format. + * + * Section @ref keytranslate has a table which shows how the keys on a US + * 104-keyboard are translated to TeamTalk's intermediate format. + * + * Section @ref transdesktopinput explains how to transmit key-codes. + * + * @param nTranslate The key-code format to translate to and from. + * @param lpDesktopInputs An array of #DesktopInput structs to translate. + * @param lpTranslatedDesktopInputs A pre-allocated array of #DesktopInput + * struct to hold the translated desktop input. + * @param nDesktopInputCount The number of elements to translate in @c + * lpDesktopInputs. + * @return The number of translated #DesktopInput stucts. If value + * is different from @c nDesktopInputCount then some @c uKeyCode + * values could not be translated and have been assigned the value + * TT_DESKTOPINPUT_KEYCODE_IGNORE. + * @see TT_SendDesktopInput() + * @see TT_DesktopInput_Execute() */ + TEAMTALKDLL_API INT32 TT_DesktopInput_KeyTranslate(TTKeyTranslate nTranslate, + IN const DesktopInput* lpDesktopInputs, + OUT DesktopInput* lpTranslatedDesktopInputs, + IN INT32 nDesktopInputCount); + + /** + * @brief Execute desktop (mouse or keyboard) input. + * + * When executed either a key-press, key-release or mouse move + * will take place on the computer running the client + * instance. Remember to calculate the offsets for the mouse + * cursor prior to this call. The mouse position will be relative + * to the screen resolution. + * + * The content of the #DesktopInput struct must been translated to + * the platform's key-code format prior to this + * call. I.e. uKeyCode must be a either a Windows scan-code, Mac + * OS X Carbon key-code or one of the mouse buttons: + * #TT_DESKTOPINPUT_KEYCODE_LMOUSEBTN, + * #TT_DESKTOPINPUT_KEYCODE_RMOUSEBTN, + * #TT_DESKTOPINPUT_KEYCODE_MMOUSEBTN. + * + * @param lpDesktopInputs The mouse or keyboard inputs. + * @param nDesktopInputCount The number of elements in @c lpDesktopInputs. + * @return The number of mouse and keyboard events inserted. + * @see TT_DesktopInput_KeyTranslate() */ + TEAMTALKDLL_API INT32 TT_DesktopInput_Execute(IN const DesktopInput* lpDesktopInputs, + IN INT32 nDesktopInputCount); + + /** @} */ + +#if defined(WIN32) + + /** @addtogroup hotkey + * @{ */ + + /** + * @brief Register a global hotkey. + * + * When the hotkey becomes active or inactive it will send + * #CLIENTEVENT_HOTKEY to the HWND passed to #TT_InitTeamTalk. + * + * A hotkey can e.g. be used as a push-to-talk key + * combination. When the hotkey becomes active call + * TT_EnableVoiceTransmission(). + * + * Note that having a hotkey enabled makes the Visual Studio + * debugger really slow to respond, so when debugging it's best + * not to have hotkeys enabled. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nHotKeyID The ID of the hotkey to register. It will be + * passed as the WPARAM when the hotkey becomes either active or inactive. + * @param lpnVKCodes An array of virtual key codes which constitute the + * hotkey. This document outlines the virtual key codes: + * http://msdn.microsoft.com/en-us/library/ms645540(VS.85).aspx + * A hotkey consisting of Left Control+A would have the array consist of + * [162, 65]. + * @param nVKCodeCount The number of virtual key codes in the array + * (in other words the size of the @a lpnVKCodes array). + * @see TT_InitTeamTalk + * @see TT_HotKey_Unregister + * @see TT_HotKey_InstallTestHook */ + TEAMTALKDLL_API TTBOOL TT_HotKey_Register(IN TTInstance* lpTTInstance, + IN INT32 nHotKeyID, + IN const INT32* lpnVKCodes, + IN INT32 nVKCodeCount); + + /** + * @brief Unregister a registered hotkey. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nHotKeyID is the ID of the hotkey to unregister. + * @see TT_HotKey_Register */ + TEAMTALKDLL_API TTBOOL TT_HotKey_Unregister(IN TTInstance* lpTTInstance, + IN INT32 nHotKeyID); + + /** + * @brief Check whether hotkey is active. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nHotKeyID is the ID of the registered hotkey. + * @return 1 if active, 0 if inactive, -1 if hotkey-ID is invalid */ + TEAMTALKDLL_API INT32 TT_HotKey_IsActive(IN TTInstance* lpTTInstance, + IN INT32 nHotKeyID); + + /** + * @brief Install a test hook so the HWND will be messaged + * whenever a key or mouse button is pressed. + * + * Capture the event #CLIENTEVENT_HOTKEY_TEST. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param hWnd is the handle of the window which will be + * notified. + * @param uMsg The window message to post to @c hWnd when a key event + * occurs. Basically it calls PostMessage(hWnd, Msg, VirtualKey-id, Active); + * @see TT_HotKey_RemoveTestHook + * @see CLIENTEVENT_HOTKEY_TEST */ + TEAMTALKDLL_API TTBOOL TT_HotKey_InstallTestHook(IN TTInstance* lpTTInstance, + IN HWND hWnd, UINT32 uMsg); + + /** + * @brief Remove the test hook again so the @a hWnd in + * #TT_HotKey_InstallTestHook will no longer be notified. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @see TT_HotKey_InstallTestHook */ + TEAMTALKDLL_API TTBOOL TT_HotKey_RemoveTestHook(IN TTInstance* lpTTInstance); + + /** + * @brief Get a string description of the virtual-key code. + * + * @param lpTTInstance Pointer to client instance created by + * #TT_InitTeamTalk. + * @param nVKCode The virtual key code passed in #CLIENTEVENT_HOTKEY_TEST. + * @param szKeyName Will receive key description in local language. + * @see TT_HotKey_Register */ + TEAMTALKDLL_API TTBOOL TT_HotKey_GetKeyString(IN TTInstance* lpTTInstance, + IN INT32 nVKCode, + OUT TTCHAR szKeyName[TT_STRLEN]); + /** @} */ +#endif + + /* Get the 'sizeof' of a structure used by TeamTalk. Useful to ensuring + * binary compatibility when integrating with other programming + * languages. */ + TEAMTALKDLL_API INT32 TT_DBG_SIZEOF(IN TTType nType); + + TEAMTALKDLL_API VOID* TT_DBG_GETDATAPTR(IN TTMessage* pMsg); + + TEAMTALKDLL_API TTBOOL TT_DBG_SetSoundInputTone(IN TTInstance* lpTTInstance, + IN StreamTypes uStreamTypes, + IN INT32 nFrequency); + + TEAMTALKDLL_API TTBOOL TT_DBG_WriteAudioFileTone(IN const MediaFileInfo* lpMediaFileInfo, + IN INT32 nFrequency); + +#if defined(WIN32) /* Exclude mixer and firewall functions from + * non-Windows platforms */ + + /** @addtogroup mixer + * @{ */ + + /** + * @brief The Windows mixer controls which can be queried by the + * TT_Mixer_* functions. + * + * Wave-In devices which are not in the enum-structure can be + * accessed by #TT_Mixer_GetWaveInControlCount which allows the user to + * query selection based on an index. + * + * Note that Windows Vista has deprecated mixer controls. + * + * @see TT_Mixer_SetWaveOutMute + * @see TT_Mixer_SetWaveOutVolume + * @see TT_Mixer_SetWaveInSelected + * @see TT_Mixer_SetWaveInVolume + * @see TT_Mixer_GetWaveInControlName + * @see TT_Mixer_SetWaveInControlSelected */ + typedef enum MixerControl + { + WAVEOUT_MASTER, + WAVEOUT_WAVE, + WAVEOUT_MICROPHONE, + + WAVEIN_MICROPHONE, + WAVEIN_LINEIN, + WAVEIN_WAVEOUT, + } MixerControl; + + /** + * @brief Get the number of Windows Mixers available. + * + * The index from 0 to #TT_Mixer_GetMixerCount()-1 should be passed to the + * TT_Mixer_* functions. + * @see TT_Mixer_GetMixerName */ + TEAMTALKDLL_API INT32 TT_Mixer_GetMixerCount(void); + + /** + * @brief Get the name of a Windows Mixer based on its name. + * + * @param nMixerIndex The index of the mixer. Ranging from 0 to + * #TT_Mixer_GetMixerCount()-1. + * @param szMixerName The output string receiving the name of the device. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_GetMixerName(IN INT32 nMixerIndex, + OUT TTCHAR szMixerName[TT_STRLEN]); + + /** + * @brief Get the name of the mixer associated with a wave-in device. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param szMixerName The output string receiving the name of the device. + * @see TT_GetSoundDevices() */ + TEAMTALKDLL_API TTBOOL TT_Mixer_GetWaveInName(IN INT32 nWaveDeviceID, + OUT TTCHAR szMixerName[TT_STRLEN]); + + /** + * @brief Get the name of the mixer associated with a wave-out device. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param szMixerName The output string receiving the name of the device. + * @see TT_GetSoundDevices */ + TEAMTALKDLL_API TTBOOL TT_Mixer_GetWaveOutName(IN INT32 nWaveDeviceID, + OUT TTCHAR szMixerName[TT_STRLEN]); + + /** + * @brief Mute or unmute a Windows Mixer Wave-Out device from the + * 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @param bMute True if device should be muted, False if it should be + * unmuted. + * @see TT_Mixer_GetWaveOutMute */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveOutMute(IN INT32 nWaveDeviceID, + IN MixerControl nControl, + IN TTBOOL bMute); + + /** + * @brief Get the mute state of a Windows Mixer Wave-Out device + * from the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @return TRUE if mute, FALSE if unmuted, -1 on error. + * @see TT_Mixer_SetWaveOutMute */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveOutMute(IN INT32 nWaveDeviceID, + IN MixerControl nControl); + + /** + * @brief Set the volume of a Windows Mixer Wave-Out device from + * the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @param nVolume A value ranging from 0 to 65535. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveOutVolume(IN INT32 nWaveDeviceID, + IN MixerControl nControl, + IN INT32 nVolume); + + /** + * @brief Get the volume of a Windows Mixer Wave-Out device from + * the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @return A value ranging from 0 to 65535, or -1 on error. */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveOutVolume(IN INT32 nWaveDeviceID, + IN MixerControl nControl); + + /** + * @brief Set the selected state of a Windows Mixer Wave-In + * device from the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveInSelected(IN INT32 nWaveDeviceID, + IN MixerControl nControl); + + /** + * @brief Get the selected state of a Windows Mixer Wave-In device + * from the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @return TRUE if mute, FALSE if unmuted, -1 on error. */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveInSelected(IN INT32 nWaveDeviceID, + IN MixerControl nControl); + + /** + * @brief Set the volume of a Windows Mixer Wave-In device from + * the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @param nVolume A value ranging from 0 to 65535. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveInVolume(IN INT32 nWaveDeviceID, + IN MixerControl nControl, + IN INT32 nVolume); + + /** + * @brief Get the volume of a Windows Mixer Wave-In device from + * the 'enum' of devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControl A mixer control. + * @return A value ranging from 0 to 65535, or -1 on error. */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveInVolume(IN INT32 nWaveDeviceID, + IN MixerControl nControl); + + /** + * @brief Enable and disable microphone boost. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param bEnable TRUE to enable, FALSE to disable. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveInBoost(IN INT32 nWaveDeviceID, + IN TTBOOL bEnable); + /** + * @brief See if microphone boost is enabled. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @return TRUE if boost is enabled, FALSE if disabled, -1 on error. */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveInBoost(IN INT32 nWaveDeviceID); + + /** + * @brief Mute/unmute microphone input. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param bEnable TRUE to enable, FALSE to disable. */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveInMute(IN INT32 nWaveDeviceID, + IN TTBOOL bEnable); + + /** + * @brief See if microphone is muted. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @return TRUE if mute is enabled, FALSE if disabled, -1 on error. */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveInMute(IN INT32 nWaveDeviceID); + + /** + * @brief Get the number of Windows Mixer Wave-In devices. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @return Number of controls, or -1 on error. + * @see TT_Mixer_GetWaveInControlName + * @see TT_Mixer_SetWaveInControlSelected + * @see TT_Mixer_GetWaveInControlSelected */ + TEAMTALKDLL_API INT32 TT_Mixer_GetWaveInControlCount(IN INT32 nWaveDeviceID); + + /** + * @brief Get the name of the Wave-In device with the specified + * index. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControlIndex The index of the control. Randing from 0 to + * #TT_Mixer_GetWaveInControlCount()-1. + * @param szDeviceName The output string of the name of the device. + * @see TT_Mixer_GetWaveInControlCount */ + TEAMTALKDLL_API TTBOOL TT_Mixer_GetWaveInControlName(IN INT32 nWaveDeviceID, + IN INT32 nControlIndex, + OUT TTCHAR szDeviceName[TT_STRLEN]); + + /** + * @brief Set the selected state of a Wave-In device in the + * Windows Mixer. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControlIndex The index of the device. Randing from 0 to + * #TT_Mixer_GetWaveInControlCount()-1. + * @see TT_Mixer_GetWaveInControlCount */ + TEAMTALKDLL_API TTBOOL TT_Mixer_SetWaveInControlSelected(IN INT32 nWaveDeviceID, + IN INT32 nControlIndex); + + /** + * @brief Get the selected state of a Wave-In device in the + * Windows Mixer. + * + * @param nWaveDeviceID The @a nWaveDeviceID from the #SoundDevice + * struct. + * @param nControlIndex The index of the device. Randing from 0 to + * #TT_Mixer_GetWaveInControlCount()-1. + * @return TRUE if selected, FALSE if unselected, -1 on error. + * @see TT_Mixer_GetWaveInControlCount */ + TEAMTALKDLL_API TTBOOL TT_Mixer_GetWaveInControlSelected(IN INT32 nWaveDeviceID, + IN INT32 nControlIndex); + /** @} */ + + /** @addtogroup firewall + * @{ */ + + /** + * @brief Check if the Windows Firewall is currently enabled. + * + * This function does not invoke UAC on Windows Vista/7. + * @see TT_Firewall_Enable */ + TEAMTALKDLL_API TTBOOL TT_Firewall_IsEnabled(void); + + /** + * @brief Enable/disable the Windows Firewall. + * + * The Windows Firewall was introduced in Windows XP SP2. + * + * On Windows XP (SP2+) the user calling this function is assumed + * to have administrator rights. On Windows Vista/7 UAC is invoked + * to ask the user for administrator rights. + * @see TT_Firewall_IsEnabled */ + TEAMTALKDLL_API TTBOOL TT_Firewall_Enable(IN TTBOOL bEnable); + + /** + * @brief Check if an executable is already in the Windows + * Firewall exception list. + * + * This function does not invoke UAC on Windows Vista/7. + * @see TT_Firewall_AddAppException */ + TEAMTALKDLL_API TTBOOL TT_Firewall_AppExceptionExists(IN const TTCHAR* szExecutable); + + /** + * @brief Add an application to the Windows Firewall exception + * list. + * + * On Windows XP (SP2+) the user calling this function is assumed + * to have administrator rights. On Windows Vista/7 UAC is invoked + * to ask the user for administrator rights. + * @see TT_Firewall_AppExceptionExists + * @see TT_Firewall_RemoveAppException */ + TEAMTALKDLL_API TTBOOL TT_Firewall_AddAppException(IN const TTCHAR* szName, + IN const TTCHAR* szExecutable); + + /** + * @brief Remove an application from the Windows Firewall exception + * list. + * + * On Windows XP (SP2+) the user calling this function is assumed + * to have administrator rights. On Windows Vista/7 UAC is invoked + * to ask the user for administrator rights. + * @see TT_Firewall_AppExceptionExists + * @see TT_Firewall_AddAppException */ + TEAMTALKDLL_API TTBOOL TT_Firewall_RemoveAppException(IN const TTCHAR* szExecutable); + /** @} */ + +#endif /** WIN32 */ + +#ifdef __cplusplus +} +#endif + +#endif /** TEAMTALKDLL_H */ diff --git a/TeamTalk_DLL/TeamTalk5.lib b/TeamTalk_DLL/TeamTalk5.lib new file mode 100644 index 0000000000000000000000000000000000000000..00c6d6e502f43e13b7dc3801180ab47046e944bd GIT binary patch literal 49470 zcmeHwd7KnQvVW*}theCe?V`(iuz(kXxU2g(hGRHKW5lv7VB>7afO*&AS&*#Ltl0mPmH82WF3 zna^puwKV|IvtMYsbq>BGCAMg~<{bc{d53G7yd8k(kz+Mo-4a02ZTLjG0plWi=rc`E z1Aw9id?F>9XqsILplB&Rk><4bXdyn4Zds>k#B~5fiHkLjXo~MhkId0Dbuj?ZwC0)~ zMIO-&cW8Qa3ce#v^Jo#`6HWJM5$2O<`UFjj@JV#(JDP?q0U)}p(j!dQWk|P8)HDIh zQBgO1A}yJ!>Bf5ih@RX_(@jSL5Iu=?K=c&iE5dl5LVD&)P0L0C5H0;q)3Y^LFGx4G z(sbLth>J9`TGIo|0EixJt7%vVOfS+yBQ!m|8Ot4MX-3m?ZvYT2`$E$#=VCb{J$JsQ zXBsdaNY|h~Q5@qYn*XJyhkF1J4af2&dJywS^!z}NHsBL!d2f%_;uGm%jDzTY#3p(G z%Zg~hAdlX}CsOqqP4SM1i!?v2Y2g9@qLCkH8nqZe5vFAnQu0Gh^Cn|EMVf?dh-hI4 zO_TnB???@=YZ~1dKoQ0{8fna-n(8qxM46@@ZN?{3-F8hE)d3J)jBycNgt$cMzM3*v zw?yNIXc~7g08#omP2<;LIMOAUMxrrSXu9M(d`B8LLDLw-B)W8@rtEqEqJ|4K)wjlU zBGt9@Xc|6|QoTLG@<}0GJYUl#m_MTIP)*}7ZlbXrJX(NHr0WrbXlkjZ>plk{nu2vj zbmfhjt~wWhXyV73u6haIktSlDm)C zO-DVVnLRbl!15$oa0wi~3$lQj)*h3y+@a&t{d>~BQ1Uun7-Wr=3}UDM5|r|3X@BF(DNbkiK{_eeD} zJUSMiMB6phj>hCKEDjxl+=_UnccLnutdEx^ho#cBu?#CZnXO|jjSq`uYcdt7Y_hsEJ{n`; z7!p5HvuguOpP-8pT00VuF;KRDygn04>jYMet2a1f(GMC$lX*RW`ljqvO^%<||n|D}^ewdn}Q3wEQGGd>2d5 zWOxDJ#Vk+9>(VJ4d4zINpq7A(YOzdhFjz|<8kco(uizbIK5~VbjiGCOzbthN8_{Mk!$5x*7CE_uc%N)05=rq;qiZrYv?hL9scLxTsrm$cM-s{5!FUoWf!dw2 znUt?IpdP>9fm)bl&^l$S6RFNMsj5+3N5_-aFs-3nc9fo7gQBJ`|1$hWrZYjLK@vk8 zgETOOU&YFFELmThsOOUsjT9E(x}B;riP6qC+0wMwsE2Jp#TSHzyQ3(8y4Vs#mfbc* z0TH(%ld3C?*TlvKg%nO)ASB`k>>OzbgeV>K_3j_9N~No@<@L!n#H&?xbxYLP?KhWH zBeB>`B^R34W5Y-lnKaH`t>!Jn;>)PCr0Vj>P_$6)ICyppLqHc|>>q4sK}B{TcE~-+Ps>>@jYS6g^F)nI(y;D`O znsOXDY4O1uC1;_$P9P699Y|t&>5b5!6mk~IV?Q#LNGrr3Ng)nOTWw5fspc5n4qX|H z!D?SF*JLe+4COFR%hCE#n45DF$?DXYAjx4C%BxNrp&;;3qdZm<&t&3MHeFIRsdObx zeF7Ajje0sc^`z(FsV{Y$+ZS?5iLo@MulS;-#%fI8lH##wMv!wW=^hK^LxtWgovP)K z(ITj?hP;US5qP48Jx+vm^vGZ(qDwYipGx}^(jb4)B0QgJiZ7~Z4oX`+B_eN;5;?T( zd`9W(+**Ao0zXnh778YD2^$oQ9}w`+OjBmr z+B^Xr8c5mM^h9*7N)z=}E{GL|F`S)^r^oh*HI&E3)}&(9L0Vh}%2NNXN#M!?KP{O= zeI`+5P240V>R{frPOo^pu2W57v^6jYJR3#OFdzXBHA++EY-Q!WD^Bm!@PuXhEKTWv zfM=JT$MwpNL{nL-dK8;Nly=WlA{qLKm!|AsSFZC|yE2)qV(C=HW256j#J%lsB}qcV z<9!oVqmpb2RjMWz7RQpNs>@o{=F58FO0p7LZ^(*TnzDmUj5vkqR~NJz9i0y3GQ6C< z{PnBz%eoilf+lQsR3=QtM1u`qxs;|%n3BMi!Dv^)geeJJgT*s(SH=p}NZFzFRq4b~ ztEnQC2~;uzlJzFQe27a^cCeD`6B{K}rX8%~Q}ZyP+V#A}XDHeJ@!FKwL^wm^qoiA| zef%&Bxgwq(%}d{#?&)wP*&F*j#nq{*3T@oB=?!~^%TpSC<6|rZyKWthlGgPQp%7*& zozAhOn>|0s=JVF)N%(CKU+tvPtFK#D-l@7e&CF?~DHI68mE?e=7o{Cf5XfbCT8xyR z8Y)SQjrCCzredm~0V0(gmawcz*g%6&C8Y*%U9Hr)S$rX$r;%Wz-Pu`uM-GmF31?#?#I$v&b}VcYmk!sG{Zpxo*TU@q5@k6@OZOQo%i7^u((g5pg>P<4Tn3TKjKr8HfOlDD`_D_jU(GVD_Df@pN&1;!XGUOtiq=~m$=Syu1q_QQIM zWm4Ag8fNL3b!B>LJRJ^8%l8>ed2p)D1lls*u))e%3;G;ex^irtHU47Ow5STU<@zUv zkFXoJk@Oh0Y-ubL6W~>_mZQ8d2^A3VB4$1$Ww8SJ&Z>0y=NVH-@)ir_aV|uGf*IQi z4&*{6Xp-`6&t6=#eyxjF`-^8BKpp!d>4-uBPR|4`?9w>cWYQ^X_rpWr+#uIH-0pn@ z$+-cRw7yV6%Wb(xJH}!ZQZSdW$f%J{;UDK2{~I22E7~NVJHn-?brL#rABNs?SBO z9;pmsVKENJkFY%wxQsw{Kr$UAZLtFRvU+Xg2=d{@Z5WnpvOW{5si8gh9;uXN{_<5E zexRvmf{}_2JJ7?LzyiRA%NA4~9AlzRY3J^PE6N6S?bj{Hj1}fdbnjY8&M4)T{kfDC z?#E?s7gnZ{c3l%xi0$c}lTKvfW@jU;DDY9UPog27rk1aMbfFn-kU)tU(&@`qU0g-+ zY>jhpdRCT~TvaA+Su7Z+C17;DSS^CY~lqLOqBP=t;*pNQ&nx(=9-Nvnz4W9R4_ zWy%tV^A_G0O>VsyOkF#TAyO_fEm1MKX*O~gQ#ahG8iQjzPSy23w$-2oo~@zfgE7m9 zdkkB)Qyp4bs^ZE%*|h;bZr04+=m|nBj_PV#LIB3KGLx{i^(Tk1O@W&f2tqsHx!>OR z++Ppqw>%hq#A5*e9*RENGXYxP3h>3V=qHcQEeU{kt^qiF9>8|=K|S^nfR05k_89e9l4r#Zv*APs8^|(I*t+ zn1atK_}*j@(sabc=LCFCz~?)cqCf61fXd4-E~JUKVHzg@bVHiD1btP}UwE%40gk*0 z^MTJMPoWIbm(QRd_cDO*mZBdl=A{+N?TfnA=m)#(0f4p-0(8K5M_~FlW7;z)_Xhg& zet|mYVw%s#-whbY2+aGkIL3#5u00;c^bSW%)E)Rdzy_q=%K_FREkoWL_hY&+?m-Ix z-b7kc4bTyF)2O>(A;1TSy?7MHgY;n%{eH1b7oyK>2ju+$pRYFnbVgs@1xSaEL7aLl zqYS1GX?q>|UtffB7o#pd`=&9!7(Qe?z`^6NOz?dj{+@gZ`p=^7clexu;hXXING!wk zS%3>M{?-_0ON?t8QtuR|2WdXWc__*cMVZa0(_t*80crj9Sf5x|pI?Xhnu6y8uEesr z3gF|3059RQ4xi+Ny%o!K5X#%L0Cuo&&7P+i@0~AK8DZ7=OhfP zyaU@QhL@twTKwJPPJnF~z6ziBT!HdPk6n)CgVY?$V)icR0}bcExljiG1t-FT&>N0` z!=M=)4tv3w@MpLH&WFe0F<1;wz(X(}E`-Zq0$c)@!blhewUC4~Tnxiu1f(DVSHd`` zhByp^EHuD)sDi6t5?lmhu#oGZ9%|rnxB@aT8pgs2&X_I2lfbMeqnLgaz;@JPcjoP&gQV4b9;Y*d6wSKSFDm4ol!kSP5(3MR*xj z!&C4)tbk{5ICvIbfR|tuJO|5RDJ+8usD!iNPtXVUhQV+@oCiIjBOC|=U?B8@{t$yf zurC}5zky@mw{SfC4(^3J;2xL@x4~U-H{1@l!bxxnoCfWn1P+3x&p^n-FZ8+L(R|F35LzpRZ0;q%nm87M}?K9UbUjKTCWzcup|}jOrcE^mhpgvGm`}=1v|0yMtcatCWFr+Gnrx2 zi_Vq92*{r&$kKnG}Nw0i^SNP7OvpE>rDK(osIx_R>S8Hh7 zP}ucz_v7>|U+^%-3~63q0@VJ%Q4F05t>gH#QhF^0bKOOjnYibg`P*}TZ|z~L>gWl` z#1^cD>`-BGfNWe`Srrw$`CA}7q@Hksps4+t@V*aqLZhslAeajRMd`XmXe8m}j+X|3 zqiX^qbIqX`WLsL5fmX+FPA;K{`Z$oB#rKV^S~|Q(7QF*wZHtKeIl=~uwL2s2+*PQ} zWV5%VlcWQ!twlT7E_UGzhbL;ExUz!O2+ht)U>OA;EA0&K%JV}GOd(*IdQ!3J?^s~t zLM49y_kQxd9xpJo58{P~Hj?}Ud^)M&@1fr=oxW@5&tcK7kKPZ$I3ujPjoO$6gS9c7 z2hr+YYb?Sxch1>YwCx#j-fse=Ef{+GTK@eWeD_)T;a%=ku4%p*Ft6|M(aly_#)!74PPc# zI-;QWFb39#2!Y`u28O#a89Sa+L?%2kmqvmo!32l1V^|T12xZ4pV95?UWKt^%hw4E{ zg{y|A{fd3jAjp@KoODUrIx~x}g5O`{wxPvfs}@SH#S_*n7T4}HCJPbAQ3F?I$0Zd3 zEoW3UC{QA-uzVbFl}5;4QHP2ioLGIrX<@A(f38p?_yVzS6XOJ*8l4SGDPZY}_4Tj~ z;cCinsysAkju=kgCN(t-?N9536F>BA^7IPXFArj~5=D_m@8<_9jrb+73^^Y+^WDQV zJ1q9y!|!bL@hD134!&3PVF_KP>Wi%ORb{(NV3}jZsbi53jQA5VTtc!`7A3b9N*!SXHGYO&aS#FZjo5?DKuj5{_shq>z=%5@)t9Cp_8}oyTrj zzpNO-HZY56Tf*dE*R|hR#Vm1V8?(bBJbu-OTJp6P&ouB%hR-h8_A?9ISkbI7$ChSs z+=CV&yP74d+=s1qV`F1s5w7f(z0DFgRyR9L^24_+aF(nwyaoN5eD*!(ZC--5P0o%Y zx1+wcW(3h|>y}`pGf`@ZV6e~U?7p2+%RCnxbaxY==0WWHZ}5%P&9&hP68U%$c=o)o zc3{;D^90+T5yCaDZ{ZWdl$|dk+;VaVBC%|Kf||1Y3E|Wio#-4ZAX9Q}fi_dH`vuj7 z=@j^OeWL`k4%$(NY=n#%y7h?L3vF57YRJMO{qC)SiseL`4I{j+MVIkNZ|;ygIJYm_ z>C|1&SQ*1C%hniXhAUcF$T2nB`WRw3Hb|N8TuXs9987P5HX8 z*Vs7S7#&Ne%eL&DhDAn0zNTR;-SU|2Gt9Rwpb=bV&kW1R^Wa=IQ5Hvdt{k$DGWl== z2-;!DRvKtVA7wEXL-ixdt57kO(a^+c6m1)76xTBoMnxaCr#2Fiu^vXrDXU2oGiOE` zjoKX#SV3TO$N`Pq9N5T}<3?LdjzTtE*B0w!-^fV`G|Z^%8-bijjL5#HEMzcjnGM== zm}d{tuI<+3)?siR$&MRnTGm_>=-PA*!!pAL6VM>_7CU0GZb?L15-b_J>pPYN!QyL@ zX_;{yyRRgot-lh-*l4_qFs*nsOS+07WDmAt7S8qCT){SMv-R+=bsF^+&RTT#~FD3fcD{IIQAby=G7vqA~W`8H`Dmufz; zi7e7S?ZlA7?3%Y^DDCzbA+K1e3?pVu#LA;6BZYWsa$B;kEatFh2U4z8+i)b?w!_R} z><_wp*p6-4xlM#&DSr7(n6E=3r8GO|J;eSE#ciu=YS5v-vD^1cPWG?oAF_A#q}|{z z4_>V(CqM*75WX(Hx~Wy{TJ_v9=M&`CaUqoZ_87C*1`DWHKb3x zfZg!f5l&w2$+h=_(X$xu{6{=rj>0=ai{-oG^I-HgrhohS)7}!w)bY^lz&$bab;Uz3 zZ1g@}nQhu9QI$^Br-o%(oY4Qo7QM^*_VW1bu`j++Qi#yWU;R1||KDBxVmQ#TDpgyD z>0O!KWtX3SwslY#9fOJdYAEGj-kvy4pB!eP>Oi2(z;m6W{-am>9&^bEz zw=23ha?8=vO8kPN zo=QE<{?`#Y`aP|kA5L}-9p&za-~S@_ThYgIPUB=WE+-{4JvI?xBY^YI%kWZet}vjwif#>bjPQxrfFSc7Qo3d&{GSCCo|V z7yL+=dwQ7Ron?knaM`x^ry^EgdSmwG%TGkiy(~<@R>y%0FJWQyIB(iNSJLS5D;L?e z0v3te-v1<6Ieux~Q`=8K+`U~~wt(Qk>@APlm2lrX=%}rPyN`>j*QNe>km7oeP{UJS zUiChG4ED8f{rvDIv;(8FfOpla3*Vp?wV#D&j}l@=3vN;EgmGfymnUpE43YQuko|Kt ztVjz-Iz2ohjXiJQl}8}b0SqZL>=%qxBDB}9R@QxTG-4gdu)I@2ENgzPs%d;4t<+33 zt=_R;p98kEK(vE2n&Z#G5P0Ls1FxMv%#6hu%pp$u@{E5SiFi!|JntTk;;>4D5vOnc z_*ZDeX=Y*BwkPF(!eI-pL8<3ovSRKg>iGu;xY9iy#nq)yw$0Wo{P{S<{k4ZHIn40v zvbQ{HwEbz}zH#%1hrj%LL~SmhGDjQ+R`}Q>wWj#(8~%q{(;*&q;Nio;*jpa?Y$xQi zXUq529)ehhdRY1#9IM2FTaVNu|M5aE)guqHZ~~VkmXpGJq%gJ(7})Pe8ru%H@W?jF zBj17g5_;t0qc3=c7J)}NSUX`P6=v^Wwb^~ev50o0kEUI)f+L8m@>t2{(MF`YyRgTy ztt}AoD2_;5%y@GtL*Q?D;I$LVGf}f@GnMDjHlBBUl4Y*&mMMJcJKw+iN}5^xCWN*V z>QDF*u4!}nJM<-N;p18EZ^e~miO>($bsPKU?-1=6j;1yXv?m*{vch{riBP7OzdHR* zD$`?qRNG&VXR`1*6y{9dFMakuw6^-KfTu6=Ew0^2qjd9GcfLiVbW0!8co^~wvbQ{X zgwzAS-{-uIEfDK>J{I#_WC*-E^T3nx)_%_U+bD0x89d)3vN$Yhy|{4O%|Fq4@pv1{ zYM(`qFhYBI{M`dyqdE2o22*)(^2`<7GTRCL@2$7{uA=YIi43Xuk)@rm+HY5u-Fi4; zwX(2MbUQX{{Om1{_96A}Ef;?GI`!}0`$)DgD+4HeJdxUCeER0ks6Dnec;?3B;_@bZ zU*El;VikQ~+xS?H^DWOFd&{FV+X;w}y?ooDh}hOg)W_tD%bCzV(zkB>fO^_VK2FG4 znB|7In;p#CF4=yYC~qeRm~@A6QF)VE$nE!ae}P)aDL#&IZY~b1M3^(ro$&Na#~{|J z0haAF%>fG@MWoeplaChuhvp2Y`G}S`Hiu(x`P7-P;%fbEd_9$AJA>xm^v+`EwU`f< zFxNZi=^5K-u2*8PjQ2PPE4&u@l)KY?JmcEV z3$O4|QW}-tx@z2CDR&)0XvKeTB)p2F=C3EbGXlKe4*nubQ|fnH_k8wy>UV!Ic+B;` zSVUou=76&=eys%}{*fbAcz5s@HHt}lLT9x<bf(6OJgdO7%HHzmhmuvPg~1h`Z)x1<^wx$AG;VZp(7l5(#Uctbty`aO^CHc(N*%=D#0>{!Z#!7VXZ8B> zBP!#r4yJIDhrtzI#?t(2;{I*^LUV?08a+7O<8&bgokvck)$r}p=5B9+SlwMLb@YfK zaP)leg!$fW{fB=-?Wc!?=PpkR9u-T38Q9P}XT3ul6G6^SR5Yy80Pex!2k<>JxmzxZ+$`ekPMyjQ4S_6`u8Lt{neQm_ELy=v}DWP$7B zV3PS1tt#|4yEtgUElAp}ssHkvf6#7CUxO-~Vsn65GV6a6=#T zLXo9WzU$Okf1%b?ZjjljJO)wtm?zm*n{*%gDb?)R1~GKpuSitM%5%g$`@BL{p8f%< zI!DN%*jpZTSt8gaUOefVO=JnFFi6Trhcc<}Gh@@iLJ_5}$VX!jex1G|l@?-sJ^rbX zB3r8T6?xffj|2U>WRnUiDiw|o$V)$UW-UR!8= zc8-In?~!AbSMZo4t#%)rHb$*>&vo$dU@0%og3+Y@KKkYN{zm=%JO|Cc1+TdLN$cJF zCJ$UqH&C%IS}3NpmT!0bqd(JHzDmHf&WSUq!s}J?Pr3ZQnXi$5N_9@;&_t{7 zkyluqTsdL#tF$_ab8L1pjc1v?Z zAz4T9S#}DqPie*X>%IQ?cPi5n43nSK4k1~~fl2=^2ZXM+`!BBVJ%0!yuEhtMW zU%8P6)4!B}<%m~o9{H12L2tKxcMXk2qXMi%bv)H2R+q`9@xH6ki7Ncljz!`MGp|nH z{^m^@7it3B6hZ~p!AJvA!F^M*w9QVA|CX#kwNc2yc}Je@g3+ZF(Zk6uFVMF6;F;w?H2@cHO@@QSs4D_64@BcvG);f;s-&4ULc3_kczUI5V)<&&y zFJg%10*qo2g?Y=>OKw<8^Om%ONE@EP9m4FxT6jwm#^9ghZT?9kQ$54AuIwl_uL9-| ztH0Plm>G>3z6+#COsVZI`D?{G8lkcQW}^oeSTgcyyTUj8q7RzftIM_K3E)?97r4f1F4?{Q5h&)!r z&5`MX(IwA;AFE$nL!JZU0(8GKx3)0b--aGz!I)Y-7WoJZm-O^b#Kz=c1Wlzm%6If6J$Ah0*EE-8!wL(dkkT zF?9V7%hnEjZv@-*-p^*1)A#%`jcIPBQ9ryZ%vqHd-e!fBT+23NKBSf01PN8&GR{C* z#`7s%VLY6)%lRv5JiOe&wC~7aI0e_KG&XFTvt<*F4OfV$?1Cc>UT`@}qw#*zFMW?j z<12Ha?}YO9{`?<1G4t(;0UJ+7?1{Os&AmZ9^Xx63`W9ODicKAqU-VTXzPiDL!R(y= z)aS^FE2uwB5>bVsF1((F)yP2;H@-@%k*h`2h(azHS@J5`_xn#?qi^nH5!t)FrPy*7 zdULBmsjsOwUnAh+_g<)8mWX`Xlz@7{qT@a$)G0EmP`!nsN?*V|U%2iynn7MGql$%G zD6V9&*zJmM)rfhWjf?l|?8FgMDC6BuJ8lb&8`q1d?rmi(p9PQD(h9fVV{2Zc9z0dV z7aCT<{YbJiZrw6%1@+(?MAToh2jBhQ`+h_{c$$bTHm-tmEVZsvZyfh7^`+?o?#}7K zQePV0ed(|M?G^@yyh?;Y;dx+vRWhU;FQgsVY@cgiC4b{vJY4JU!6MNl``7h-zIvJJa<)cuFEuO{Q7G4* znd6nu<{XV^U1S)!^eVVMC9js>4gXO2<=z^?{iW|}nP2tBH#A4TErk5b-bR`x^BJFnG4ajzn` zdfHXHQ)61!Q99RLvJ4j9cO{F$l>I(d=Z@|QVJn*)&mVuwBe&A-&*`7-{}zpmcZU$Y z8{~@2rBuR0J~-fYD&cz~FwKRZMPf@Q4cD|=y_{OqTpv4hlPCveZ~2t5@RjX$(;t;5 z=e-6~_`6lbSu=!jvijj(Khdo1K7%UUe9E%718rEq{nf&|Hxlms23H%i*_EnA;!5+j zOPa1!x6(Yoad)cEfiy4QvgG6MX}{B z=5uUqNEenstipG&A6;|(!)s`^`jCXVQ|9IEg`8IY`HJu83%J0bDvv$!mR*+1!pCP} z?5ODZt1Xo0hZ*|L^a+sq(%O#YY7MlIp*pwz^8E3)JZe~)V{Oasy^=hKAIXIqYS66I z^FWqn&CkE`=dWni{3u7xW?Z+^g6ERbtofhcz55N#ninxNb3HQ4&<>2sg8lEOA>%(F zzs1KGqId6dk$93-yX~1@tstxR;|`v1p>vVwl9%S=+b8^oa=VzJi$g@g^(lP=&TID9 zujw1`gu!zTk^N%69!)2H`aYHOk|^Yz=IbGijh8K&yOGAmCq4A=HP>oQwiC|eNc#t! z)~^4a?0`=-j$ZVbA?=-P{kH!nv@Ux(65qe%n>TUxmdAJ{jnMaQYW+4@sg_#UYM!+- z@BR~fW)Ik2`ZbNv&*Z`_y0lLh?#x*+>xuX2(&%M2a*oT+St%F%bvj+h`;`Yy`iw5g zeKx-o6kQ7Kg*~g8Ree7`3DfYLl?HnyzBA8{O6$egZ$Df^>&54NeD~IOUhIXBu7dUM zkrp?8Lu1_X05j@3`C`$962D;lr=L)XuV@rKRN;l^URY0^F{Ja#QxN}!06*8o^Tn2c zFaths;ql+nD8DjDL7q*HB_@xNPO^zS+5DBQ-ltHhSvY=Hp}UX^EEc=|KpmjnDEgys_7SX8p3~d!1~(-ya?D^9yKj} z)8ezYe@)-Cm!i=1UjQ!3QX str: machine = platform.machine() if sys.platform == "win32": architecture = platform.architecture() - if machine == "AMD64" or machine == "x86": - if architecture[0] == "64bit": - return "win64" - else: - return "win32" + if machine in ["AMD64", "x86"]: + return "win64" if architecture[0] == "64bit" else "win32" else: - sys.exit("Native Windows on ARM is not supported") + sys.exit("Native Windows on ARM is not supported.") elif sys.platform == "darwin": - sys.exit("Darwin is not supported") + sys.exit("macOS is not supported.") else: - if machine == "AMD64" or machine == "x86_64": + if machine in ["AMD64", "x86_64"]: return "ubuntu18_x86_64" elif "arm" in machine: return "raspbian_armhf" else: - sys.exit("Your architecture is not supported") + sys.exit("Your system architecture is not supported.") def download() -> None: - headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3'} + headers = {'User-Agent': 'Mozilla/5.0'} r = requests.get(url, headers=headers) page = bs4.BeautifulSoup(r.text, features="html.parser") - # The last tested version series is v5.12x versions = page.find_all("li") version = [i for i in versions if "5.12" in i.text][-1].a.get("href")[0:-1] download_url = ( @@ -55,7 +50,7 @@ def download() -> None: + "/" + "tt5sdk_{v}_{p}.7z".format(v=version, p=get_url_suffix_from_platform()) ) - print("Downloading from " + download_url) + print("Downloading from: " + download_url) downloader.download_file(download_url, os.path.join(os.getcwd(), "ttsdk.7z")) @@ -66,32 +61,51 @@ def extract() -> None: shutil.rmtree(os.path.join(os.getcwd(), "ttsdk")) os.mkdir(os.path.join(os.getcwd(), "ttsdk")) patoolib.extract_archive( - os.path.join(os.getcwd(), "ttsdk.7z"), outdir=os.path.join(os.getcwd(), "ttsdk") + os.path.join(os.getcwd(), "ttsdk.7z"), + outdir=os.path.join(os.getcwd(), "ttsdk") ) + def move() -> None: - path = os.path.join(os.getcwd(), "ttsdk", os.listdir(os.path.join(os.getcwd(), "ttsdk"))[0]) + sdk_root = os.path.join(os.getcwd(), "ttsdk") + contents = os.listdir(sdk_root) + + if not contents: + raise RuntimeError("SDK extraction failed: 'ttsdk/' folder is empty.") + + for entry in contents: + entry_path = os.path.join(sdk_root, entry) + if os.path.isdir(entry_path) and os.path.isdir(os.path.join(entry_path, "Library")): + path = entry_path + break + else: + raise RuntimeError("No 'Library' folder found in extracted SDK.") + libraries = ["TeamTalk_DLL", "TeamTalkPy"] dest_dir = os.path.join(os.getcwd(), os.pardir) if os.path.basename(os.getcwd()) == "tools" else os.getcwd() + for library in libraries: + src = os.path.join(path, "Library", library) + dst = os.path.join(dest_dir, library) + + if not os.path.exists(src): + print(f"WARNING: {library} not found.") + continue + try: - os.rename( - os.path.join(path, "Library", library), os.path.join(dest_dir, library) - ) + os.rename(src, dst) except OSError: - shutil.rmtree(os.path.join(dest_dir, library)) - os.rename( - os.path.join(path, "Library", library), os.path.join(dest_dir, library) - ) - try: - os.rename( - os.path.join(path, "License.txt"), os.path.join(dest_dir, "TTSDK_license.txt") - ) - except FileExistsError: - os.remove(os.path.join(dest_dir, "TTSDK_license.txt")) - os.rename( - os.path.join(path, "License.txt"), os.path.join(dest_dir, "TTSDK_license.txt") - ) + if os.path.exists(dst): + shutil.rmtree(dst) + os.rename(src, dst) + + license_path = os.path.join(path, "License.txt") + dst_license = os.path.join(dest_dir, "TTSDK_license.txt") + + if os.path.exists(license_path): + if os.path.exists(dst_license): + os.remove(dst_license) + os.rename(license_path, dst_license) def clean() -> None: @@ -100,17 +114,17 @@ def clean() -> None: def install() -> None: - print("Installing TeamTalk sdk components") - print("Downloading latest sdk version") + print("Starting TeamTalk SDK installation...") + print("Downloading the latest SDK version...") download() - print("Downloaded. extracting") + print("Download complete. Extracting...") extract() - print("Extracted. moving") + print("Extraction complete. Moving files...") move() - print("moved. cleaning") + print("Move complete. Cleaning up...") clean() - print("cleaned.") - print("Installed") + print("Cleanup done.") + print("TeamTalk SDK successfully installed.") if __name__ == "__main__":