DTLS.HandshakeRetry

DTLS.HandshakeRetry

#Overview

name: DTLS.HandshakeRetry

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DTLS.HandshakeRetry is to set the handshake retry time for the DTLS (Datagram Transport Layer Security) protocol in Unreal Engine 5. This setting is used in the network communication system, specifically for secure UDP connections.

This setting variable is primarily used in the DTLSHandlerComponent plugin, which is part of the PacketHandlers runtime plugin system in Unreal Engine 5. The plugin is responsible for handling DTLS connections in the engine’s networking subsystem.

The value of this variable is set as a console variable (CVar) with a default value of 500 milliseconds. It can be adjusted at runtime or set in configuration files.

The associated variable CVarHandshakeRetry interacts directly with DTLS.HandshakeRetry. They share the same value and purpose.

Developers must be aware that this variable affects the timeout for DTLS handshake retries. A lower value will result in more frequent retries, potentially improving connection speed in unstable network conditions, but may also increase network traffic. A higher value will reduce retry frequency, which can be beneficial in stable network environments to reduce unnecessary traffic.

Best practices when using this variable include:

  1. Adjusting the value based on the expected network conditions of your game’s target audience.
  2. Testing different values to find the optimal balance between connection reliability and network efficiency.
  3. Considering the impact on both client and server performance when modifying this value.
  4. Monitoring network performance metrics to ensure the chosen value is appropriate for your specific use case.

Regarding the associated variable CVarHandshakeRetry:

The purpose of CVarHandshakeRetry is to provide programmatic access to the DTLS.HandshakeRetry setting within the C++ code of the DTLSHandlerComponent.

This variable is used directly in the DTLSContext namespace of the DTLSHandlerComponent plugin. It’s specifically utilized in the DTLSTimerCallback function, which is likely a callback for the OpenSSL library used for DTLS implementation.

The value of CVarHandshakeRetry is set automatically based on the DTLS.HandshakeRetry console variable. It can be accessed in the code using the GetValueOnAnyThread() method.

CVarHandshakeRetry interacts directly with the DTLS.HandshakeRetry setting, serving as its in-code representation.

Developers should be aware that changes to DTLS.HandshakeRetry will be reflected in CVarHandshakeRetry, and vice versa. This variable is used to determine the DTLS handshake retry interval in microseconds.

Best practices for using CVarHandshakeRetry include:

  1. Using GetValueOnAnyThread() when accessing the value to ensure thread-safety.
  2. Being cautious when modifying this value directly, as it could impact the behavior of the DTLS handshake process.
  3. Considering the performance implications of frequently accessing this value in performance-critical code paths.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSContext.cpp:27

Scope (from outer to inner):

file
namespace    DTLSContext

Source code excerpt:


	TAutoConsoleVariable<int32> CVarCertLifetime(TEXT("DTLS.CertLifetime"), 4 * 60 * 60, TEXT("Lifetime to set on generated certificates, in seconds."));
	TAutoConsoleVariable<int32> CVarHandshakeRetry(TEXT("DTLS.HandshakeRetry"), 500, TEXT("Handshake retry time, in milliseconds."));
}

const TCHAR* LexToString(EDTLSContextType ContextType)
{
	switch (ContextType)
	{

#Associated Variable and Callsites

This variable is associated with another variable named CVarHandshakeRetry. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSContext.cpp:27

Scope (from outer to inner):

file
namespace    DTLSContext

Source code excerpt:


	TAutoConsoleVariable<int32> CVarCertLifetime(TEXT("DTLS.CertLifetime"), 4 * 60 * 60, TEXT("Lifetime to set on generated certificates, in seconds."));
	TAutoConsoleVariable<int32> CVarHandshakeRetry(TEXT("DTLS.HandshakeRetry"), 500, TEXT("Handshake retry time, in milliseconds."));
}

const TCHAR* LexToString(EDTLSContextType ContextType)
{
	switch (ContextType)
	{

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSContext.cpp:45

Scope (from outer to inner):

file
function     static unsigned int DTLSTimerCallback

Source code excerpt:

static unsigned int DTLSTimerCallback(SSL* SSlPtr, unsigned int TimerInUS)
{
	return DTLSContext::CVarHandshakeRetry.GetValueOnAnyThread() * 1000;
}

static int DTLSCertVerifyCallback(X509_STORE_CTX* Context, void* UserData)
{
	FDTLSContext* DTLSContext = static_cast<FDTLSContext*>(UserData);