 |
ToxMod Server SDK 1.5.2
ToxMod Server-Side SDK
|
|
|
ToxMod Server SDK 1.5.2
ToxMod Server-Side SDK
|
|
#include <stddef.h>Go to the source code of this file.
Data Structures | |
| struct | tox_server_instance_t |
| struct | tox_server_config_t |
Macros | |
| #define | TOX_SERVER_DEF_PREFIX |
| #define | TOX_SERVER_VERSION "1.5.2" |
Typedefs | |
| typedef void *(* | tox_server_malloc_callback) (size_t size) |
| typedef void(* | tox_server_free_callback) (void *ptr) |
| typedef void *(* | tox_server_realloc_callback) (void *ptr, size_t size) |
| typedef char *(* | tox_server_strdup_callback) (const char *str) |
| typedef void *(* | tox_server_calloc_callback) (size_t nmemb, size_t size) |
| #define TOX_SERVER_DEF_PREFIX |
Definition prefix used to export functions
| #define TOX_SERVER_VERSION "1.5.2" |
The version of the ToxMod server library - this updates anytime Modulate ships a new libtox with bugfixes, performance improvements, API changes, etc. ToxMod follows semantic versioning, therefore: Major (first number) versions are not compatible Minor (second number) versions are backwards compatible - applications compiled against less recent versions can link with more recent versions, but not necessarily vice versa Patch (third number) all versions compatible - internal differences only Dev Build - "d" for dev build, nothing for external release
| typedef void *(* tox_server_malloc_callback) (size_t size) |
Typedefs to memory callback functions are provided to simplify the API - not needed unless you're using custom memory allocation
| enum TOX_SERVER_ERROR |
Error value responses from ToxMod server functions; use tox_server_error_name() to get related message on error.
| Enumerator | |
|---|---|
| TOX_SERVER_NO_ERROR | Default return value for successful function calls. |
| TOX_SERVER_UNKNOWN_ERROR | Returned in case of internal library errors, and should not be encountered during normal use of the SDK. |
| TOX_SERVER_BAD_INSTANCE | returned if the tox_server_instance_t parameter was not initialized by tox_server_create_instance(), or has otherwise become corrupted. |
| TOX_SERVER_BAD_ACCOUNT_UUID | Returned if an account UUID is null |
| TOX_SERVER_BAD_API_KEY | Returned if an operation was performed using a null API key |
| TOX_SERVER_BAD_CONFIG | Returned if a null tox_server_config_t is used |
| TOX_SERVER_BAD_PLAYER_NAME | Returned if a null player name is passed |
| TOX_SERVER_BAD_SESSION_NAME | Returned if a null session name is passed |
| TOX_SERVER_BAD_MAX_NUM_PACKETS | Returned if the circular buffer max num packets is 0 |
| TOX_SERVER_BAD_MAX_PACKET_SIZE | Returned if the max packet size is 0 |
| TOX_SERVER_BAD_PACKET | Returned if something is wrong with the packet array, either one of the packets is null or the array is null |
| TOX_SERVER_CURL_ERROR | Returned if curl fails to initialize a valid multi handle |
| TOX_SERVER_EMPTY_PACKET | Returned if the packet is a null pointer or packet_size is 0 |
| TOX_SERVER_PACKET_TOO_LARGE | Returned if the packet size is greater than tox_server_config_t.max_packet_size, tox_server_config_t.max_packet_size may need to be increased |
| TOX_SERVER_CIRCULAR_BUFFER_FULL | Returned if the underlying circular buffer has been saturated by adding packets - either increase the tox_server_config_t.circular_buffer_max_num_packets to hold more packets and avoid dropping them, or increase the rate at which tox_server_run_buffer_copy() is run to drain the circular buffer more often |
| TOX_SERVER_UPLOAD_QUEUE_FULL | Returned if the underlying clip upload buffer is full, so a new Ogg data buffer could not be added to the upload queue and has been dropped. This indicates that tox_server_begin_upload() has run insufficiently often on this tox_server_instance_t to empty the upload queue into curl for active uploading |
| TOX_SERVER_BAD_MEM_FUNCTION | Returned if if NULL is passed instead of one of the required memory functions (malloc, free, realloc) |
| TOX_SERVER_UPLOAD_METADATA_FAILED | Returned if the player or session alias failed to upload (only applicable if tox_server_config_t.obscure_names is 0). |
| TOX_SERVER_BAD_PLAYER_ALIAS | Returned if player alias is a null pointer |
| TOX_SERVER_BAD_SESSION_ALIAS | Returned if session alias is a null pointer |
| TOX_SERVER_BAD_PLAYER_LIST | Returned if the player list is null but num_players isn't 0. |
| TOX_SERVER_PROXIMITY_CHAT_DISABLED | Returned if proximity_chat_session is 0 in the instance's config. |
| TOX_SERVER_BAD_REALTIME_CONFIG | Returned if the tox_server_instance passed in has been set up for realtime use and an attempt is made to use non-realtime functionality |
| const char * tox_server_get_version | ( | void | ) |
Return the version string for the library that this is built with
Should match TOX_SERVER_VERSION
| TOX_SERVER_ERROR tox_server_set_log_info_callback | ( | void(* | log_info_callback )(const char *) | ) |
Set a user-defined callback to print/log info messages from ToxMod
If this is not called, ToxMod will print info messages to stdout. Passing a null pointer will restore the default logging behavior using stdout/stderr.
| [in] | log_info_callback | - logging callback |
| TOX_SERVER_ERROR tox_server_set_log_error_callback | ( | void(* | log_error_callback )(const char *) | ) |
Set a user-defined callback to print/log error messages from ToxMod
If this is not called, ToxMod will print error messages to stderr. Passing a null pointer will restore the default logging behavior using stdout/stderr.
| [in] | log_error_callback | - logging callback |
| const char * tox_server_error_name | ( | TOX_SERVER_ERROR | error | ) |
Return the associated string for a ToxMod Server error - useful in log messages
| [in] | error | - the tox error for which to retrieve an error string |
| TOX_SERVER_ERROR tox_server_global_init | ( | const char * | account_uuid, |
| const char * | api_key, | ||
| const char * | single_tenant_prefix ) |
Global initialization, setting state for curl and account parameters for all tox_server_instance_t objects. This must be called before any other tox_server functions aside from tox_server_get_version() and tox_server_error_name().
An error from this function means that ToxMod will not work properly and should be aborted.
| [in] | account_uuid | Provided by Modulate directly or retrieved from the Admin page in the web console. |
| [in] | api_key | Provided by Modulate directly or retrieved from the Admin page in the web console |
| [in] | single_tenant_prefix | Provided by Modulate directly for single tenancy customers. If not applicable, pass in a null pointer. |
| TOX_SERVER_ERROR tox_server_global_init_mem | ( | const char * | account_uuid, |
| const char * | api_key, | ||
| const char * | single_tenant_prefix, | ||
| tox_server_malloc_callback | tox_malloc, | ||
| tox_server_free_callback | tox_free, | ||
| tox_server_realloc_callback | tox_realloc, | ||
| tox_server_strdup_callback | tox_strdup, | ||
| tox_server_calloc_callback | tox_calloc ) |
Global initialization using custom memory allocators, which replaces all memory management performed by ToxMod with allocations/frees using the specified callbacks. Additionally, memory allocated by the curl dependency as used by ToxMod will use these callbacks, though depending on which dependencies to curl are installed (such as the SSL library), they themselves may not use these callbacks. The standard Ogg library dependency does not use these callbacks by default. This function replaces tox_global_init(), see that documentation above for more information.
| [in] | account_uuid | Provided by Modulate directly or retrieved from the Admin page in the web console. |
| [in] | api_key | Provided by Modulate directly or retrieved from the Admin page in the web console |
| [in] | single_tenant_prefix | Provided by Modulate directly for single tenancy customers. If not applicable, pass in a null pointer. |
| [in] | tox_malloc | a callback for ToxMod to get a pointer to allocated memory. |
| [in] | tox_free | a callback to free memory allocated with tox_malloc, which must use the same heap as the tox_malloc callback. |
| [in] | tox_realloc | a callback implementing realloc, for ToxMod to use, which must use the same head as the tox_malloc and tox_free callbacks. |
| [in] | tox_strdup | an optional pointer to a strdup implementation, or if null, ToxMod will use a default implementation based on the specified tox_malloc and tox_free functions. |
| [in] | tox_calloc | an optional pointer to a calloc implementation, or if null, ToxMod will use a default implementaiton based on the specified tox_malloc function. |
| TOX_SERVER_ERROR tox_server_global_cleanup | ( | void | ) |
Global cleanup of the initialization from tox_server_global_init(). Call only once no more tox_server functions (excluding tox_server_get_version() and tox_server_error_name()) will be called.
| TOX_SERVER_ERROR tox_server_create_instance | ( | tox_server_instance_t * | tox_instance_ptr, |
| const tox_server_config_t * | tox_server_config_ptr ) |
Create a tox_server_instance_t to store internal state specific to a single player in voice chat session. One should be created for each player in a voice chat session, for each voice chat session. Internal storage is allocated to preserve the config values passed in, so the tox_server_config_t object may be discarded after this function returns.
| [in] | tox_instance_ptr | Pointer to a fresh tox_server_instance_t |
| [in] | tox_server_config_ptr | Pointer to a tox_server_config_t |
Example:
| TOX_SERVER_ERROR tox_server_destroy_instance | ( | tox_server_instance_t * | tox_instance_ptr | ) |
Destroy a tox_server_instance_t to free internal state. This must be done when tox_server functions will no longer be called on this tox_server_instance_t, and is not threadsafe with other tox_server functions when operating on the same tox_server_instance_t.
| [in] | tox_instance_ptr | Pointer to the tox_server_jnstance_t to be destroyed |
| TOX_SERVER_ERROR tox_server_get_internal_player_uuid | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char ** | internal_player_uuid ) |
Get the ToxMod-internal anonymous UUID associated with the provided player. Retrieving this and storing it in your own database allows you to consume messages from ToxMod (e.g. "a moderator banned <player_uuid>") and relate them back to your internal player database or players' usernames, without ToxMod storing any player usernames. If it is acceptable for ToxMod to store player usernames, you can avoid storing this relationship yourself. Do this by providing ToxMod a player alias which you can consume later - such as the player username or internal database ID - using tox_set_player_alias, in which case the above messages will also include the alias (e.g. "a moderator banned <player_uuid>, alias: <player_alias>").
| [in] | tox_instance_ptr | Pointer to the tox_server_instance_t of the player in question |
| [out] | internal_player_uuid | The toxmod internal UUID used to identify the player in question. This will remain valid until the corresponding tox_server_instance_t is destroyed. |
Example:
| TOX_SERVER_ERROR tox_server_get_internal_session_uuid | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char ** | internal_session_uuid ) |
Get the ToxMod-internal anonymous UUID associated with the provided session. This works much like tox_get_internal_player_uuid(), except that it is associated with a session instead of a player. Retrieving and storing the session UUID in your own database allows you to associate the UUID included in moderation messages with your internal session database or sessions' names, without ToxMod storing any session names. Alternatively, you can avoid storing this relationship yourself by providing ToxMod a session alias (i.e. the session name itsef) which will be passed back to you in moderation messages.
| [in] | tox_instance_ptr | Pointer to the tox_server_instance_t of the session in question |
| [out] | internal_session_uuid | The toxmod internal UUID used to identify the session in question. This will remain valid until the corresponding tox_server_instance_t is destroyed. |
Example:
| TOX_SERVER_ERROR tox_server_add_session_data | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char * | session_data ) |
Send additional session context/data/events to ToxMod for use in assisting moderation. Since each game has different structure and different relevant events that may contribute to player toxicity, the format for this session data is determined on a per-customer basis. Please reach out to your Modulate account representative for more information.
| [in] | tox_instance_ptr | Pointer representing the player/session in question |
| [in] | session_data | The session data to pass to ToxMod. This is copied to internal storage and does not need to be preserved after this function returns. |
Example:
| TOX_SERVER_ERROR tox_server_set_proximity_chat_player_can_hear | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char *const * | players, | ||
| unsigned int | num_players ) |
Set a list of players that this player can hear. This should be the full list of players that this player can hear at the time of the function call, and should be called each time that that list changes. For example, if another player leaves proximity chat range and this player can no longer hear them, call this function with the remaining list of players that this player can hear. Use either this function or tox_server_set_proximity_chat_can_hear_player() to specify proximity chat information, not both.
| [in] | tox_instance_ptr | Pointer referencing the primary player in question |
| [in] | players | Array of players who the primary player can hear. This specifies the ToxMod-internal UUIDs associated with those players, NOT the raw string player names used at ToxMod instance creation. This is an optimization to prevent the SDK from re-hashing the names to UUIDs on each function call. These internal UUIDs can be retrieved from the tox_server_instance objects corresponding to the other players by calling tox_server_get_internal_player_uuid() on the instance object. |
| [in] | num_players | Length of the players array |
Example:
| TOX_SERVER_ERROR tox_server_set_proximity_chat_can_hear_player | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char *const * | players, | ||
| unsigned int | num_players ) |
Set a list of players that can hear this player. This should be the full list of players that can hear this player at the time of the function call, and should be called each time that that list changes. For example, if another player leaves proximity chat range and they can no longer hear this player, call this function with the remaining list of players that can hear this player. Use either this function or tox_server_set_proximity_chat_player_can_hear() to specify proximity chat information, not both.
| [in] | tox_instance_ptr | Pointer referencing the primary player in question |
| [in] | players | Array of players who can hear the primary player. This specifies the ToxMod-internal UUIDs associated with those players, NOT the raw string player names used at ToxMod instance creation. This is an optimization to prevent the SDK from re-hashing the names to UUIDs on each function call. These internal UUIDs can be retrieved from the tox_server_instance objects corresponding to the other players by calling tox_server_get_internal_player_uuid() on the instance object. |
| [in] | num_players | Length of the players array |
Example:
| TOX_SERVER_ERROR tox_server_add_packet | ( | tox_server_instance_t * | tox_instance_ptr, |
| const unsigned char * | packet, | ||
| unsigned int | packet_size ) |
Add a new Opus packet from the associated player in the associated voice chat room to the tox_server_instance_t for processing. This function is realtime safe, and is implemented as a lightweight copy to a circular buffer using atomics. Errors indicate that the packet was not added to the circular buffer but do not otherwise compromise the tox_server_instance_t state.
| [in] | tox_instance_ptr | Pointer referencing the player/session to add the packet to |
| [in] | packet | Encoded Opus data packet |
| [in] | packet_size | Size in bytes of the encoded Opus data packet |
| TOX_SERVER_ERROR tox_server_add_packets_nonrealtime | ( | tox_server_instance_t * | tox_instance_ptr, |
| const unsigned char ** | packets, | ||
| const unsigned int * | packet_sizes, | ||
| unsigned int | num_packets ) |
Add an array of non-realtime Opus packets from the associated player in the associated voice chat room to the tox_server_instance_t for processing. This function is not realtime safe and can block when called. This function is thread safe, and is designed to be called from multiple threads concurrently.
| [in] | tox_instance_ptr | Pointer referencing the player/session to add the packet to |
| [in] | packets | Array of encoded Opus data packets |
| [in] | packet_sizes | Array with sizes in bytes of the encoded Opus data packets |
| [in] | num_packets | Number of Opus packets |
| TOX_SERVER_ERROR tox_server_set_global_muted | ( | tox_server_instance_t * | tox_instance_ptr, |
| int | muted ) |
Signal to ToxMod that the player associated with an instance has muted or unmuted voice chat entirely.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the player in question |
| [in] | muted | 0 signals that voice chat was unmuted, 1 signals that voice chat was muted. |
| TOX_SERVER_ERROR tox_server_set_player_muted | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char * | player, | ||
| int | muted ) |
Signal to ToxMod that the player associated with an instance has muted or unmuted another player.
The player argument specifies the ToxMod-internal UUID associated with the muted/unmuted player, NOT the raw string player name used at ToxMod instance creation. This is an optimization to prevent the SDK from re-hashing the name to a UUID on each function call. The internal UUID can be retrieved from the tox_server_instance_t objects corresponding to the muted/unmuted player by calling tox_server_get_internal_player_uuid() on the instance object.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the primary player in question |
| [in] | player | the ToxMod-internal UUID of the player being muted/unmuted |
| [in] | muted | 0 signals that the player was unmuted, 1 signals that the player was muted. |
| TOX_SERVER_ERROR tox_server_set_players_muted_at_join | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char *const * | players, | ||
| unsigned int | num_players ) |
Notify ToxMod that the player associated with an instance has a preexisting persistent mute set on one or more players in this session. ToxMod will treat this differently than a call to tox_server_set_player_muted(), which should be used for real-time muting actions.
This is intended to be called when the associated player joins a session, and again if a player who the associated player has muted joins the session later.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the primary player in question |
| [in] | players | an array of the ToxMod-internal UUIDs of the players who are muted-at-join |
| [in] | num_players | length of the players list |
| TOX_SERVER_ERROR tox_server_run_buffer_copy | ( | tox_server_instance_t * | tox_instance_ptr | ) |
Run on a timed loop to drain the circular buffer of the tox_server_instance_t of new packets and into an encoded Ogg data buffer. When the underlying Ogg data buffer is ready to upload, this function will add that file buffer to an upload queue and allocate a new data buffer. This function should not be run in a realtime audio loop.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the player/session pair in question |
| TOX_SERVER_ERROR tox_server_begin_upload | ( | tox_server_instance_t * | tox_instance_ptr | ) |
Run on a timed loop to empty the upload queue and begin uploading the relevant clips. This should be run once every few seconds to ensure low latency between an offense occurring and it being escalated by ToxMod, and to ensure that the upload queue does not saturate.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the player/session pair in question |
| TOX_SERVER_ERROR tox_server_run_all_uploads_with_timeout | ( | int * | num_running_uploads, |
| int | wait_timeout_milliseconds ) |
Run on a loop to progress all in-progress uploads across all tox_server_instance_t objects. This function should be run with no caller-side waiting function, as the function will internally wait up to wait_timeout_milliseconds if no uploading work is available to do.
| [out] | num_running_uploads | Reference to an int to store the number of uploads still running |
| [in] | wait_timeout_milliseconds | Maximum time period to wait for work to do in milliseconds |
| TOX_SERVER_ERROR tox_server_run_all_uploads | ( | int * | num_running_uploads | ) |
Run on a timed loop to progress all in-progress uploads across all tox_server_instance_t objects. This should be run once every few seconds to ensure that uploads complete in a timely manner. Note: this function may need to be run more often if many uploads are running, up to ~20x/second if multiple hundreds of uploads are occurring.
| [out] | num_running_uploads | Reference to an int to store the number of uploads still running |
| TOX_SERVER_ERROR tox_server_set_player_alias | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char * | player_alias ) |
Save an alias for the associated player within ToxMod's database, to be passed back to you upon moderation actions. This avoids you having to store the ToxMod anonymous id and do the association yourself, as moderation actions will produce messages that you consume with the information "a moderator banned <player_uuid>, alias: <player_alias>" The player alias is copied to internal storage, and does not need to be preserved after this function returns.
| [in] | tox_instance_ptr | reference to the tox_instance_t for the player/session pair in question |
| [in] | player_alias | alias for the player in question |
Example:
| TOX_SERVER_ERROR tox_server_set_session_alias | ( | tox_server_instance_t * | tox_instance_ptr, |
| const char * | session_alias ) |
Save an alias for the associated session within ToxMod's database, to be passed back to you upon moderation actions. This allows you to associate a session name with the conversations shown in the web console rather than the internal UUID ToxMod uses to identify sessions.
| [in] | tox_instance_ptr | reference to the tox_server_instance_t for the player/session pair in question |
| [in] | session_alias | alias for the session in question |
Additional error codes
Example:
1.13.2