The server lib will notify the server application about certain actions by sending events as callbacks. Callback function pointers needs to be initialized in ts3server_initServerLib
.
![]() | Note |
---|---|
Your callback implementations should exit quickly to avoid blocking the server. If you require to do lengthly operations, consider using a new thread to let the callback itself finish as soon as possible. |
All strings are UTF-8 encoded.
A client has connected:
void onClientConnected( | serverID, | |
clientID, | ||
channelID, | ||
removeClientError) ; |
uint64 serverID
;anyID clientID
;uint64 channelID
;unsigned int* removeClientError
;Parameters
serverID
ID of the virtual server.
clientID
ID of the connected client.
channelID
ID of the channel the client has joined.
removeClientError
If the pointer value is ERROR_ok
(default), this client will connect normally to the virtual server. To prevent the client connecting, set the pointer value to any valid error (see the header public_errors.h
):
*removeClientError = ERROR_client_insufficient_permissions;
If you do not want to block the client, it's best to not modify the removeClientError
parameter at all and leave the default value of ERROR_ok
.
A client has disconnected:
void onClientDisconnected( | serverID, | |
clientID, | ||
channelID) ; |
uint64 serverID
;anyID clientID
;uint64 channelID
;Parameters
serverID
ID of the virtual server.
clientID
ID of the disconnected client.
channelID
ID of the channel the client has left.
A client has moved into another channel:
void onClientMoved( | serverID, | |
clientID, | ||
oldChannelID, | ||
newChannelID) ; |
uint64 serverID
;anyID clientID
;uint64 oldChannelID
;uint64 newChannelID
;Parameters
serverID
ID of the virtual server.
clientID
ID of the moved client.
oldChannelID
ID of the old channel the client has left.
newChannelID
ID of the new channel the client has joined.
A channel has been created:
void onChannelCreated( | serverID, | |
invokerClientID, | ||
channelID) ; |
uint64 serverID
;anyID invokerClientID
;uint64 channelID
;Parameters
serverID
ID of the virtual server.
invokerClientID
ID of the invoker who created the channel (client or server ID).
channelID
ID of the created channel.
A channel has been edited:
void onChannelEdited( | serverID, | |
invokerClientID, | ||
channelID) ; |
uint64 serverID
;anyID invokerClientID
;uint64 channelID
;Parameters
serverID
ID of the virtual server.
invokerClientID
ID of the invoker who edited the channel (client or server ID).
channelID
ID of the edited channel.
A channel has been deleted:
void onChannelDeleted( | serverID, | |
invokerClientID, | ||
channelID) ; |
uint64 serverID
;anyID invokerClientID
;uint64 channelID
;Parameters
serverID
ID of the virtual server.
invokerClientID
ID of the invoker who deleted the channel (client or server ID).
channelID
ID of the deleted channel.
Text messages can be received on the server side. Only server and channel chats trigger this event, client-to-client messages are not caught for privacy reasons.
Server chat messages can be intercepted with:
void onServerTextMessageEvent( | serverID, | |
invokerClientID, | ||
textMessage) ; |
uint64 serverID
;anyID invokerClientID
;const char* textMessage
;Parameters
serverID
ID of the virtual server.
invokerClientID
ID of the client who sent the text message.
textMessage
Message text
Channel chat messages can be intercepted with:
void onChannelTextMessageEvent( | serverID, | |
invokerClientID, | ||
targetChannelID, | ||
textMessage) ; |
uint64 serverID
;anyID invokerClientID
;uint64 targetChannelID
;const char* textMessage
;Parameters
serverID
ID of the virtual server.
invokerClientID
ID of the client who sent the text message.
targetChannelID
ID of the channel in which the text message was sent.
textMessage
Message text
If user-defined logging was enabled when initialzing the Server Lib by passing LogType_USERLOGGING
to the usedLogTypes
parameter of ts3server_initServerLib
, log messages will be sent to the following callback, which allows user customizable logging and handling or critical errors:
void onUserLoggingMessageEvent( | logMessage, | |
logLevel, | ||
logChannel, | ||
logID, | ||
logTime, | ||
completeLogString) ; |
const char* logMessage
;int logLevel
;const char* logChannel
;uint64 logID
;const char* logTime
;const char* completeLogString
;Parameters
logMessage
Actual log message text.
logLevel
Severity of log message, defined by the enum LogLevel.
enum LogLevel { LogLevel_CRITICAL = 0, //these messages stop the program LogLevel_ERROR, //everything that is really bad, but not so bad we need to shut down LogLevel_WARNING, //everything that *might* be bad LogLevel_DEBUG, //output that might help find a problem LogLevel_INFO, //informational output, like "starting database version x.y.z" LogLevel_DEVEL //developer only output (will not be displayed in release mode) };
Note that only log messages of a level higher than the one configured with ts3server_setLogVerbosity
will appear.
logChannel
Optional custom text to categorize the message channel.
logID
Virtual server ID identifying the current virtual server when using multiple connections.
logTime
String with date and time when the log message occured.
completeLogString
Provides a verbose log message including all previous parameters for convinience.
A client connected to this server starts or stops talking:
void onClientStartTalkingEvent( | serverID, | |
clientID) ; |
uint64 serverID
;anyID clientID
;
void onClientStopTalkingEvent( | serverID, | |
clientID) ; |
uint64 serverID
;anyID clientID
;
Parameters
serverID
The ID of the server which sent the event.
clientID
ID of the client who starts or stops talking
If required, the raw voice data can be caught by the server to implement server-side voice recording. Whenever a client is sending voice data, the following function is called:
void onVoiceDataEvent( | serverID, | |
clientID, | ||
voiceData, | ||
voiceDataSize, | ||
frequency) ; |
uint64 serverID
;anyID clientID
;unsigned char* voiceData
;unsigned int voiceDataSize
;unsigned int frequency
;Parameters
serverID
The ID of the server which sent the event.
clientID
ID of the client who sent the voice data.
voiceData
Buffer containing the voice data. Format is 16 bit mono.
![]() | Caution |
---|---|
The buffer must not be freed. |
voiceDataSize
Size of the voiceData
buffer.
frequency
Frequency of the voice data.
![]() | Note |
---|---|
This event is always fired, even if the client is the only user in a channel. So clients “talking to themselves” will also be recorded. |
If server-side recording is not required, don't implement this callback.
The following event is called when a license error occurs, like for example missing license file, expired license, starting too many virtual servers etc. Instead of shutting down the whole process by throwing a critical error in the Server Lib, this callback allows you to handle the issue gracefully and keep your application running.
void onAccountingErrorEvent( | serverID, | |
errorCode) ; |
uint64 serverID
;unsigned int errorCode
;
Parameters
serverID
The ID of the virtual server on which the license error occured. This virtual server will be automatically shutdown, other virtual servers keep running.
If serverID
is zero, all virtual servers are affected and have been shutdown. In this case you might want to call ts3server_destroyServerLib
to clean up resources.
errorCode
Code of the occured error. Use ts3server_getGlobalErrorMessage
to convert to a message string.