TeamTalk 4 C-API DLL  Version 4.5A
Channel Properties

Users are arranged in a tree structure consisting of channels where each channel can hold a number of users. While in a channel users can transmit audio and video to each other as well as sending channel messages. On a server there will always be a root channel which cannot be deleted. More...

Classes

struct  Channel
 A struct containing the properties of a channel. More...
 
struct  FileTransfer
 A struct containing the properties of a file transfer. More...
 
struct  FileInfo
 A struct containing the properties of a file in a Channel. More...
 

Macros

#define TT_VOICEUSERS_MAX   16
 
#define TT_VIDEOUSERS_MAX   16
 
#define TT_DESKTOPUSERS_MAX   16
 
#define TT_CLASSROOM_FREEFORALL   0xFFFF
 

Typedefs

typedef enum ChannelType ChannelType
 The types of channels supported. More...
 
typedef UINT32 ChannelTypes
 Bitmask of ChannelType. More...
 
typedef struct Channel Channel
 A struct containing the properties of a channel. More...
 
typedef struct FileTransfer FileTransfer
 A struct containing the properties of a file transfer. More...
 
typedef enum FileTransferStatus FileTransferStatus
 Status of a file transfer. More...
 
typedef struct FileInfo FileInfo
 A struct containing the properties of a file in a Channel. More...
 

Enumerations

enum  ChannelType {
  CHANNEL_DEFAULT = 0x0000, CHANNEL_STATIC = 0x0001, CHANNEL_SOLO_TRANSMIT = 0x0002, CHANNEL_ECHO = 0x0004,
  CHANNEL_ECHO_AUDIO = 0x0004, CHANNEL_CLASSROOM = 0x0008, CHANNEL_ECHO_VIDEO = 0x0010, CHANNEL_ECHO_DESKTOP = 0x0020,
  CHANNEL_OPERATOR_RECVONLY = 0x0040
}
 The types of channels supported. More...
 
enum  FileTransferStatus { FILETRANSFER_ERROR = 0, FILETRANSFER_STARTED = 1, FILETRANSFER_FINISHED = 2 }
 Status of a file transfer. More...
 

Functions

TEAMTALKDLL_API INT32 TT_GetRootChannelID (IN TTInstance *lpTTInstance)
 Get the root channel's ID. More...
 
TEAMTALKDLL_API INT32 TT_GetMyChannelID (IN TTInstance *lpTTInstance)
 Get the channel which the local client instance is currently participating in. More...
 
TEAMTALKDLL_API BOOL TT_GetChannel (IN TTInstance *lpTTInstance, IN INT32 nChannelID, OUT Channel *lpChannel)
 Get the channel with a specific ID. More...
 
TEAMTALKDLL_API BOOL TT_GetChannelPath (IN TTInstance *lpTTInstance, IN INT32 nChannelID, OUT TTCHAR szChannelPath[TT_STRLEN])
 Get the channel's path. Channels are separated by '/'. More...
 
TEAMTALKDLL_API INT32 TT_GetChannelIDFromPath (IN TTInstance *lpTTInstance, IN const TTCHAR *szChannelPath)
 Get the channel ID of the supplied path. Channels are separated by '/'. More...
 
TEAMTALKDLL_API BOOL TT_GetChannelUsers (IN TTInstance *lpTTInstance, IN INT32 nChannelID, IN OUT INT32 *lpUserIDs, IN OUT INT32 *lpnHowMany)
 Get the IDs of all users in a channel. More...
 
TEAMTALKDLL_API BOOL TT_GetChannelFiles (IN TTInstance *lpTTInstance, IN INT32 nChannelID, IN OUT FileInfo *lpFileInfos, IN OUT INT32 *lpnHowMany)
 Get the list of the files in a channel which can be downloaded. More...
 
TEAMTALKDLL_API BOOL TT_GetChannelFileInfo (IN TTInstance *lpTTInstance, IN INT32 nChannelID, IN INT32 nFileID, OUT FileInfo *lpFileInfo)
 Get information about a file which can be downloaded. More...
 
TEAMTALKDLL_API BOOL TT_IsChannelOperator (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN INT32 nChannelID)
 Check whether user is operator of a channel. More...
 
TEAMTALKDLL_API BOOL TT_GetServerChannels (IN TTInstance *lpTTInstance, IN OUT INT32 *lpChannelIDs, IN OUT INT32 *lpnHowMany)
 Get the IDs of all the channels on the server. More...
 
TEAMTALKDLL_API BOOL TT_GetFileTransferInfo (IN TTInstance *lpTTInstance, IN INT32 nTransferID, OUT FileTransfer *lpTransfer)
 Get information about an active file transfer. More...
 
TEAMTALKDLL_API BOOL TT_CancelFileTransfer (IN TTInstance *lpTTInstance, IN INT32 nTransferID)
 Cancel an active file transfer. More...
 

Detailed Description

Users are arranged in a tree structure consisting of channels where each channel can hold a number of users. While in a channel users can transmit audio and video to each other as well as sending channel messages. On a server there will always be a root channel which cannot be deleted.

In other conferencing tools channels are also refered to as "rooms".

Channel Administration

To create a new channel on a server an administrator can call TT_DoMakeChannel whereas a default user (without administrator rights) has to use TT_DoJoinChannel to create a new channel. Using TT_DoJoinChannel creates a dynamic channel which disappears again from the server when the last user leaves the channel. The first user to join a dynamic channel will become operator of the channel, meaning that he can kick user and make other operators as well.

Updating a channel's properties can only be done by administrators and operators of the channel and this is done by using TT_DoUpdateChannel.

To remove a channel a user must be administrator and can do so by calling TT_DoRemoveChannel.

File Sharing

While in a channel users can upload and download files. To upload a file to a channel the channel needs to have a disk quota. The disk quota is specified by nDiskQuota in the Channel-struct. The file being uploaded must have a file size which is less than the disk quota and the sum of sizes of existing files. Once a file is uploaded only administrators, channel operators and the file's owner can delete a file. Note that the file's owner must have an account on the server to delete the file.

Call TT_DoSendFile to upload a file and TT_DoRecvFile to download a file. Only users who have a UserAccount on the server are allowed to upload files. There is no limit on the maximum number of file transfers but it is advised to queue file transfers so the file transfers do no affect server performance.

Storing Conversations to Audio Files

In some applications it may be required to be able to save all audio data received by the client instance to disk. This can be archived by calling TT_SetUserAudioFolder which will then save received audio data in the following format: "YYYYMMDD-HHMMSS \#USERID USERNAME.wav". USERNAME is the szUsername from User.

To store audio data from outside the local client instance's channel, please read section Spying on Users.

Macro Definition Documentation

#define TT_VOICEUSERS_MAX   16

The maximum number of users allowed to transmit audio when a Channel is configured with CHANNEL_CLASSROOM.

#define TT_VIDEOUSERS_MAX   16

The maximum number of users allowed to transmit video when a Channel is configured with CHANNEL_CLASSROOM.

#define TT_DESKTOPUSERS_MAX   16

The maximum number of users allowed to transmit when a Channel is configured with CHANNEL_CLASSROOM.

#define TT_CLASSROOM_FREEFORALL   0xFFFF

If a Channel is configured with CHANNEL_CLASSROOM then only users certain user IDs are allowed to transmit. If, however, TT_CLASSROOM_FREEFORALL is put in either voiceUsers, videoUsers and desktopUsers then everyone in the channel are allowed to transmit.

Typedef Documentation

typedef enum ChannelType ChannelType

The types of channels supported.

See Also
Channel
typedef UINT32 ChannelTypes

Bitmask of ChannelType.

typedef struct Channel Channel

A struct containing the properties of a channel.

See Also
TT_GetChannel
ChannelType
AudioCodec
typedef struct FileTransfer FileTransfer

A struct containing the properties of a file transfer.

See Also
TT_GetFileTransferInfo

Status of a file transfer.

See Also
WM_TEAMTALK_FILETRANSFER
typedef struct FileInfo FileInfo

A struct containing the properties of a file in a Channel.

See Also
TT_GetChannelFileInfo

Enumeration Type Documentation

The types of channels supported.

See Also
Channel
Enumerator
CHANNEL_DEFAULT 

A default channel is a channel which disappears after the last user leaves the channel.

CHANNEL_STATIC 

A channel which persists even when the last user leaves the channel.

CHANNEL_SOLO_TRANSMIT 

Only one user can transmit at a time. Note that this option doesn't apply if clients are running in peer to peer mode.

See Also
TT_EnablePeerToPeer
CHANNEL_ECHO 

Audio transmitted to the channel by the client instance is also sent back and played by the client instance.

CHANNEL_ECHO_AUDIO 

Same as CHANNEL_ECHO.

CHANNEL_CLASSROOM 

Voice and video transmission in the channel is controlled by a channel operator (or an administrator). For a user to transmit audio or video to this type of channel the channel operator must add the user's ID to either voiceUsers or videoUsers in the Channel struct and call TT_DoUpdateChannel.

Note
Requires server version 4.1.0.994 or later.
See Also
TT_IsChannelOperator
USERTYPE_ADMIN
CHANNEL_ECHO_VIDEO 

Video sent to the channel should also be sent back to the local client instance.

CHANNEL_ECHO_DESKTOP 

Desktop session sent to the channel should also be sent back to the local client instance.

CHANNEL_OPERATOR_RECVONLY 

Only channel operators (and administrators) will receive audio/video/desktop transmissions. Default channel users will only see transmissions from operators and/or administrators.

Status of a file transfer.

See Also
WM_TEAMTALK_FILETRANSFER
Enumerator
FILETRANSFER_ERROR 

Error during file transfer.

FILETRANSFER_STARTED 

File transfer started.

FILETRANSFER_FINISHED 

File transfer finished.

Function Documentation

TEAMTALKDLL_API INT32 TT_GetRootChannelID ( IN TTInstance lpTTInstance)

Get the root channel's ID.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
Returns
Returns the ID of the root channel. If 0 is returned no root channel exists.
See Also
TT_GetMyChannelID
TT_GetChannelPath
TEAMTALKDLL_API INT32 TT_GetMyChannelID ( IN TTInstance lpTTInstance)

Get the channel which the local client instance is currently participating in.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
Returns
Returns the ID of the current channel. If 0 is returned the user is not participating in a channel.
TEAMTALKDLL_API BOOL TT_GetChannel ( IN TTInstance lpTTInstance,
IN INT32  nChannelID,
OUT Channel lpChannel 
)

Get the channel with a specific ID.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nChannelIDThe ID of the channel to get information about.
lpChannelA preallocated struct which will receive the channel's properties.
Returns
FALSE if unable to retrieve channel otherwise TRUE.
TEAMTALKDLL_API BOOL TT_GetChannelPath ( IN TTInstance lpTTInstance,
IN INT32  nChannelID,
OUT TTCHAR  szChannelPath[TT_STRLEN] 
)

Get the channel's path. Channels are separated by '/'.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nChannelIDThe channel's ID.
szChannelPathWill receive the channel's path.
Returns
Returns TRUE if channel exists.
TEAMTALKDLL_API INT32 TT_GetChannelIDFromPath ( IN TTInstance lpTTInstance,
IN const TTCHAR szChannelPath 
)

Get the channel ID of the supplied path. Channels are separated by '/'.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
szChannelPathWill receive the channel's path.
Returns
The channel's ID or 0 on error.
TEAMTALKDLL_API BOOL TT_GetChannelUsers ( IN TTInstance lpTTInstance,
IN INT32  nChannelID,
IN OUT INT32 *  lpUserIDs,
IN OUT INT32 *  lpnHowMany 
)

Get the IDs of all users in a channel.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nChannelIDThe channel's ID.
lpUserIDsA preallocated array which has room for lpnHowMany user ID elements. Pass NULL to query the number of users in channel.
lpnHowManyThe number of elements in the array lpUserIDs. If lpUserIDs is NULL lpnHowMany will receive the number of users in the channel.
See Also
User
TT_GetChannel
TEAMTALKDLL_API BOOL TT_GetChannelFiles ( IN TTInstance lpTTInstance,
IN INT32  nChannelID,
IN OUT FileInfo lpFileInfos,
IN OUT INT32 *  lpnHowMany 
)

Get the list of the files in a channel which can be downloaded.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nChannelIDThe ID of the channel to extract the files from.
lpFileInfosA preallocated struct which will receive file information. If lpFileInfo is NULL then lpnHowMany will receive the number of files in the channel.
lpnHowManyUse for both querying and specifying the number of files. If lpFileInfos is NULL then lpnHowMany will receive the number of files in the channel. If lpFileInfos is not NULL then lpnHowMany should specify the size of the lpFileInfos array.
See Also
TT_GetChannelFileInfo
TEAMTALKDLL_API BOOL TT_GetChannelFileInfo ( IN TTInstance lpTTInstance,
IN INT32  nChannelID,
IN INT32  nFileID,
OUT FileInfo lpFileInfo 
)

Get information about a file which can be downloaded.

Typically this is called after receiving WM_TEAMTALK_CMD_FILE_NEW.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nChannelIDThe ID of the channel to extract the file from.
nFileIDThe ID of the file.
lpFileInfoA preallocated struct which will receive file information.
TEAMTALKDLL_API BOOL TT_IsChannelOperator ( IN TTInstance lpTTInstance,
IN INT32  nUserID,
IN INT32  nChannelID 
)

Check whether user is operator of a channel.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDthe ID of the user to check.
nChannelIDthe ID of the channel to check whether user is operator of.
TEAMTALKDLL_API BOOL TT_GetServerChannels ( IN TTInstance lpTTInstance,
IN OUT INT32 *  lpChannelIDs,
IN OUT INT32 *  lpnHowMany 
)

Get the IDs of all the channels on the server.

Use TT_GetChannel() to get more information about each of the channels.

See Also
TT_GetServerUsers()
TEAMTALKDLL_API BOOL TT_GetFileTransferInfo ( IN TTInstance lpTTInstance,
IN INT32  nTransferID,
OUT FileTransfer lpTransfer 
)

Get information about an active file transfer.

An active file transfer is one which has been posted through the event WM_TEAMTALK_FILETRANSFER.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nTransferIDThe ID of the file transfer to investigate. Transfer ID is passed by WM_TEAMTALK_FILETRANSFER.
lpTransferA preallocated struct which will receive the file transfer information.
See Also
TT_CancelFileTransfer
TEAMTALKDLL_API BOOL TT_CancelFileTransfer ( IN TTInstance lpTTInstance,
IN INT32  nTransferID 
)

Cancel an active file transfer.

An active file transfer is one which has been post through the event WM_TEAMTALK_FILETRANSFER.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nTransferIDThe ID of the file transfer to investigate. Transfer ID is passed by WM_TEAMTALK_FILETRANSFER.