TeamTalk 5 C-API DLL: User Properties

TeamTalk 5 C-API DLL Version 5.18A

Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions
User Properties

This section explains users interact and how to configure user settings. More...

## Classes

struct | User
| A struct containing the properties of a user. More...
struct | UserStatistics
| Packet reception and data statistics for a user. More...
struct | TextMessage
| A struct containing the properties of a text message sent by a user. More...

## Typedefs

typedef enum UserType | UserType
| The types of users supported.
typedef UINT32 | UserTypes
| A bitmask based on UserType describing the user type.
typedef enum Subscription | Subscription
| 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.
typedef UINT32 | Subscriptions
| A bitmask based on Subscription describing which subscriptions are enabled.
typedef enum UserState | UserState
| The possible states for a user. Used for User's uUserState variable.
typedef UINT32 | UserStates
| A bitmask based on UserState indicating a User's current state.
typedef struct User | User
| A struct containing the properties of a user.
typedef struct UserStatistics | UserStatistics
| Packet reception and data statistics for a user.
typedef enum TextMsgType | TextMsgType
| Text message types.
typedef struct TextMessage | TextMessage
| A struct containing the properties of a text message sent by a user.

## Enumerations

enum | UserType { USERTYPE_NONE = 0x0 , USERTYPE_DEFAULT = 0x01 , USERTYPE_ADMIN = 0x02 }
| The types of users supported. More...

enum

Subscription {
SUBSCRIBE_NONE = 0x00000000 , SUBSCRIBE_USER_MSG = 0x00000001 , SUBSCRIBE_CHANNEL_MSG = 0x00000002 , SUBSCRIBE_BROADCAST_MSG = 0x00000004 ,
SUBSCRIBE_CUSTOM_MSG = 0x00000008 , SUBSCRIBE_VOICE = 0x00000010 , SUBSCRIBE_VIDEOCAPTURE = 0x00000020 , SUBSCRIBE_DESKTOP = 0x00000040 ,
SUBSCRIBE_DESKTOPINPUT = 0x00000080 , SUBSCRIBE_MEDIAFILE = 0x00000100 , SUBSCRIBE_INTERCEPT_USER_MSG = 0x00010000 , SUBSCRIBE_INTERCEPT_CHANNEL_MSG = 0x00020000 ,
SUBSCRIBE_INTERCEPT_CUSTOM_MSG = 0x00080000 , SUBSCRIBE_INTERCEPT_VOICE = 0x00100000 , SUBSCRIBE_INTERCEPT_VIDEOCAPTURE = 0x00200000 , SUBSCRIBE_INTERCEPT_DESKTOP = 0x00400000 ,
SUBSCRIBE_INTERCEPT_MEDIAFILE = 0x01000000
}

| 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. More...

enum

UserState {
USERSTATE_NONE = 0x0000000 , USERSTATE_VOICE = 0x00000001 , USERSTATE_MUTE_VOICE = 0x00000002 , USERSTATE_MUTE_MEDIAFILE = 0x00000004 ,
USERSTATE_DESKTOP = 0x00000008 , USERSTATE_VIDEOCAPTURE = 0x00000010 , USERSTATE_MEDIAFILE_AUDIO = 0x00000020 , USERSTATE_MEDIAFILE_VIDEO = 0x00000040 ,
USERSTATE_MEDIAFILE
}

| The possible states for a user. Used for User's uUserState variable. More...
enum | TextMsgType { MSGTYPE_NONE = 0 , MSGTYPE_USER = 1 , MSGTYPE_CHANNEL = 2 , MSGTYPE_BROADCAST = 3 , MSGTYPE_CUSTOM = 4 }
| Text message types. More...

## Functions

TEAMTALKDLL_API INT32 | TT_GetMyUserID (IN TTInstance *lpTTInstance)
| Get the local client instance's user ID.
TEAMTALKDLL_API TTBOOL | TT_GetMyUserAccount (IN TTInstance *lpTTInstance, OUT UserAccount *lpUserAccount)
| Get the local client instance's UserAccount.
TEAMTALKDLL_API UserTypes | TT_GetMyUserType (IN TTInstance *lpTTInstance)
| Get the client instance's user type.
TEAMTALKDLL_API UserRights | TT_GetMyUserRights (IN TTInstance *lpTTInstance)
| Convenience method for TT_GetMyUserAccount()
TEAMTALKDLL_API INT32 | TT_GetMyUserData (IN TTInstance *lpTTInstance)
| If an account was used in TT_DoLogin then this value will return the nUserData from the UserAccount.
TEAMTALKDLL_API TTBOOL | TT_GetUser (IN TTInstance *lpTTInstance, IN INT32 nUserID, OUT User *lpUser)
| Get the user with the specified ID.
TEAMTALKDLL_API TTBOOL | TT_GetUserStatistics (IN TTInstance *lpTTInstance, IN INT32 nUserID, OUT UserStatistics *lpUserStatistics)
| Get statistics for data and packet reception from a user.
TEAMTALKDLL_API TTBOOL | TT_GetUserByUsername (IN TTInstance *lpTTInstance, IN const TTCHAR *szUsername, OUT User *lpUser)
| Get the user with the specified username.

## Detailed Description

This section explains users interact and how to configure user settings.

Users can be seen on the server after a successful call to TT_DoLogin. Once logged in a user can send user to user text-messages using TT_DoTextMessage as well as receive broadcast messages. A user cannot send audio and video data to other users until they have joined the same channel.

Sections:

- User Types
- User Interaction
- User Audio Settings
- User Subscriptions
  - Spying on Users

# User Types

A user can either be a default user USERTYPE_DEFAULT or an administrator USERTYPE_ADMIN. A default user has limited rights on the server (see `uUserRights` of UserAccount) whereas an administrator can change server properties, create, delete and remove channels as well as move, kick and ban users. Checkout User Administration on how to set up user rights.

# User Interaction

Once a user has joined a channel it is possible to transmit voice and video data to other users. If a user starts talking in the channel the event CLIENTEVENT_USER_STATECHANGE is posted to the user application and if a video frame is received the event CLIENTEVENT_USER_VIDEOCAPTURE is sent to the user application.

# User Audio Settings

While in the same channel the user application can change different settings on a user. If e.g. a user's volume is too low the user application can call TT_SetUserVolume to increase the volume.

If on the other hand the user application wants to mute a user TT_SetUserMute can be used for this. Note that muting a user doesn't mean that the client instance will stop receiving audio from that user, it simply means it will not be played. To stop receiving audio from a user the local client instance must ask the server to unsubscribe voice data from the user. This is explained in the next section.

# User Subscriptions

When logging on to a server the local client instance will by default subscribe to user messages, channel messages, broadcast messages, audio data and video data from all users. If, however, a client wants to stop receiving e.g. audio from a user, he can call TT_DoUnsubscribe along with the user ID and the SUBSCRIBE_VOICE-flag to tell the server that he no longer wants to receive audio from that user. The server will then respond with the event CLIENTEVENT_CMD_USER_UPDATE and the uLocalSubscriptions member of User will have the SUBSCRIBE_VOICE-flag removed. At the remote user the uPeerSubscriptions member will be changed. Subscribe/unsubscribe can also be done for user, channel and broadcast messages and video data. The function TT_DoSubscribe can be used to revert unsubscriptions.

## Spying on Users

Previously it has been said that users can only receive audio and video from users when they are in the same channel, but actually an administrator user can call TT_DoSubscribe with the flags prefixed SUBSCRIBE_INTERCEPT_* to spy on users outside his own channel. In other words it's possible hear and see video data outside ones channel. Also all user and channel messages sent by a user can also be intercepted in this way.

Having the ability to intercept all data sent from users in any channel means that it's possible to log everything that is happening on the server. Both audio and video transfers as well as text messaging. Checkout TT_SetUserMediaStorageDir() on how to store voice data to audio files.

## Typedef Documentation

## ◆ UserType

typedef enum UserType UserType

The types of users supported.

See also
  User
  UserAccount

## ◆ UserTypes

typedef UINT32 UserTypes

A bitmask based on UserType describing the user type.

See also
  UserType

Definition at line 1978 of file TeamTalk.h.

## ◆ Subscription

typedef enum Subscription Subscription

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 uLocalSubscriptions. The subscriptions with the prefix `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 also
  TT_DoSubscribe
  TT_DoUnsubscribe

## ◆ Subscriptions

typedef UINT32 Subscriptions

A bitmask based on Subscription describing which subscriptions are enabled.

See also
  Subscription

Definition at line 2144 of file TeamTalk.h.

## ◆ UserState

typedef enum UserState UserState

The possible states for a user. Used for User's uUserState variable.

## ◆ UserStates

typedef UINT32 UserStates

A bitmask based on UserState indicating a User's current state.

Definition at line 2190 of file TeamTalk.h.

## ◆ User

typedef struct User User

A struct containing the properties of a user.

See also
  UserType
  TT_GetUser

## ◆ UserStatistics

typedef struct UserStatistics UserStatistics

Packet reception and data statistics for a user.

See also
  TT_GetUserStatistics

## ◆ TextMsgType

typedef enum TextMsgType TextMsgType

Text message types.

The types of messages which can be passed to TT_DoTextMessage().

See also
  TextMessage
  TT_DoTextMessage
  CLIENTEVENT_CMD_USER_TEXTMSG

## ◆ TextMessage

typedef struct TextMessage TextMessage

A struct containing the properties of a text message sent by a user.

See also
  CLIENTEVENT_CMD_USER_TEXTMSG
  TT_DoTextMessage

## Enumeration Type Documentation

## ◆ UserType

enum UserType

The types of users supported.

See also
  User
  UserAccount

Enumerator
USERTYPE_NONE | Used internally to denote an unauthenticated user.
USERTYPE_DEFAULT | A default user who can join channels.
USERTYPE_ADMIN | A user with administrator privileges.

Definition at line 1964 of file TeamTalk.h.

## ◆ Subscription

enum Subscription

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 uLocalSubscriptions. The subscriptions with the prefix `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 also
  TT_DoSubscribe
  TT_DoUnsubscribe

Enumerator
SUBSCRIBE_NONE | No subscriptions.

SUBSCRIBE_USER_MSG

Subscribing to user text messages.

See also
  MSGTYPE_USER.

SUBSCRIBE_CHANNEL_MSG

Subscribing to channel texxt messages.

See also
  MSGTYPE_CHANNEL.

SUBSCRIBE_BROADCAST_MSG

Subscribing to broadcast text messsages.

See also
  MSGTYPE_BROADCAST.

SUBSCRIBE_CUSTOM_MSG

Subscribing to custom user messages.

See also
  MSGTYPE_CUSTOM.

SUBSCRIBE_VOICE | Subscribing to STREAMTYPE_VOICE.
SUBSCRIBE_VIDEOCAPTURE | Subscribing to STREAMTYPE_VIDEOCAPTURE.
SUBSCRIBE_DESKTOP | Subscribing to STREAMTYPE_DESKTOP.

SUBSCRIBE_DESKTOPINPUT

Subscribing to STREAMTYPE_DESKTOPINPUT.

See also
  TT_GetUserDesktopInput()
  TT_SendDesktopInput()

SUBSCRIBE_MEDIAFILE | Subscribing to STREAMTYPE_MEDIAFILE_VIDEO and STREAMTYPE_MEDIAFILE_AUDIO.
SUBSCRIBE_INTERCEPT_USER_MSG | Intercept all user text messages sent by a user. Only user-type USERTYPE_ADMIN can do this.
SUBSCRIBE_INTERCEPT_CHANNEL_MSG | Intercept all channel messages sent by a user. Only user-type USERTYPE_ADMIN can do this.
SUBSCRIBE_INTERCEPT_CUSTOM_MSG | Intercept all custom text messages sent by user. Only user-type USERTYPE_ADMIN can do this.
SUBSCRIBE_INTERCEPT_VOICE | 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_VIDEOCAPTURE | 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_DESKTOP | 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_MEDIAFILE | 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.

Definition at line 2078 of file TeamTalk.h.

## ◆ UserState

enum UserState

The possible states for a user. Used for User's uUserState variable.

Enumerator
USERSTATE_NONE | The user is in initial state.
USERSTATE_VOICE | If set the user is currently talking. If this flag changes the event CLIENTEVENT_USER_STATECHANGE is posted.

USERSTATE_MUTE_VOICE

If set the user's voice is muted.

See also
  TT_SetUserMute

USERSTATE_MUTE_MEDIAFILE

If set the user's media file playback is muted.

See also
  TT_SetUserMute

USERSTATE_DESKTOP

If set the user currently has an active desktop session. If this flag changes the event CLIENTEVENT_USER_STATECHANGE is posted.

See also
  TT_SendDesktopWindow().

USERSTATE_VIDEOCAPTURE

If set the user currently has an active video stream. If this flag changes the event CLIENTEVENT_USER_STATECHANGE is posted.

See also
  CLIENTEVENT_USER_VIDEOCAPTURE.

USERSTATE_MEDIAFILE_AUDIO

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

USERSTATE_MEDIAFILE_VIDEO

If set the user currently streams a video file. If this flag changes the event CLIENTEVENT_USER_STATECHANGE is posted.

See also
  TT_StartStreamingMediaFile()

USERSTATE_MEDIAFILE

If set user is streaming a media file. If this flag changes the event CLIENTEVENT_USER_STATECHANGE is posted.

See also
  TT_StartStreamingMediaFile()

Definition at line 2148 of file TeamTalk.h.

## ◆ TextMsgType

enum TextMsgType

Text message types.

The types of messages which can be passed to TT_DoTextMessage().

See also
  TextMessage
  TT_DoTextMessage
  CLIENTEVENT_CMD_USER_TEXTMSG

Enumerator
MSGTYPE_NONE | An incomplete text message.
MSGTYPE_USER | A User to user text message. A message of this type can be sent across channels.
MSGTYPE_CHANNEL | 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_BROADCAST | A broadcast message. Requires USERRIGHT_TEXTMESSAGE_BROADCAST.
MSGTYPE_CUSTOM | A custom user to user text message. Works the same way as MSGTYPE_USER.

Definition at line 2367 of file TeamTalk.h.

## Function Documentation

## ◆ TT_GetMyUserID()

TEAMTALKDLL_API INT32 TT_GetMyUserID | ( | IN TTInstance * | lpTTInstance | ) |

Get the local client instance's user ID.

This information can be retrieved after the CLIENTEVENT_CMD_MYSELF_LOGGEDIN event.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  Returns the user ID assigned to the current user on the server. -1 is returned if no ID has been assigned to the user.

## ◆ TT_GetMyUserAccount()

TEAMTALKDLL_API TTBOOL TT_GetMyUserAccount | ( | IN TTInstance * | lpTTInstance,
|  | OUT UserAccount * | lpUserAccount )

Get the local client instance's UserAccount.

This information can be retrieved after CLIENTEVENT_CMD_MYSELF_LOGGEDIN event.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpUserAccount | The local client's user account registered on the server. Note that the szPassword field of UserAccount will not be set.

See also
  TT_DoLogin

## ◆ TT_GetMyUserType()

TEAMTALKDLL_API UserTypes TT_GetMyUserType | ( | IN TTInstance * | lpTTInstance | ) |

Get the client instance's user type.

This information can be retrieved after CLIENTEVENT_CMD_MYSELF_LOGGEDIN event.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  A bitmask of the type of user based on UserType.

See also
  TT_GetMyUserAccount
  TT_DoLogin
  UserType

## ◆ TT_GetMyUserRights()

TEAMTALKDLL_API UserRights TT_GetMyUserRights | ( | IN TTInstance * | lpTTInstance | ) |

Convenience method for TT_GetMyUserAccount()

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

## ◆ TT_GetMyUserData()

TEAMTALKDLL_API INT32 TT_GetMyUserData | ( | IN TTInstance * | lpTTInstance | ) |

If an account was used in TT_DoLogin then this value will return the nUserData from the UserAccount.

This information can be retrieved after CLIENTEVENT_CMD_MYSELF_LOGGEDIN event.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  If set, nUserData from UserAccount, otherwise 0.

See also
  TT_GetMyUserAccount

## ◆ TT_GetUser()

TEAMTALKDLL_API TTBOOL TT_GetUser | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | OUT User * | lpUser )

Get the user with the specified ID.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the user to extract.
  lpUser | A preallocated User struct.

See also
  TT_GetUserByUsername

## ◆ TT_GetUserStatistics()

TEAMTALKDLL_API TTBOOL TT_GetUserStatistics | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | OUT UserStatistics * | lpUserStatistics )

Get statistics for data and packet reception from a user.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the user to extract.
  lpUserStatistics | A preallocated UserStatistics struct.

## ◆ TT_GetUserByUsername()

TEAMTALKDLL_API TTBOOL TT_GetUserByUsername | ( | IN TTInstance * | lpTTInstance,
|  | IN const TTCHAR * | szUsername,
|  | OUT User * | lpUser )

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.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  szUsername | The user's username (from UserAccount).
  lpUser | A preallocated User struct.