TextMessageMemoryLimit

TextMessageMemoryLimit

#Overview

name: TextMessageMemoryLimit

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of TextMessageMemoryLimit is to set a memory limit for receiving UTF-8 text messages on a WebSocket connection. This variable is used to control the maximum size of the buffer allocated for incoming text messages, helping to manage memory usage and prevent potential buffer overflow issues.

TextMessageMemoryLimit is primarily used in the WebSockets module of Unreal Engine, which is part of the Online subsystem. It is specifically implemented in the Lws (libwebsockets) and WinHttp WebSocket implementations.

The value of this variable is typically set in two ways:

  1. Through the engine configuration file (GEngineIni) under the [WebSockets] section with the key “TextMessageMemoryLimit”.
  2. Programmatically using the SetTextMessageMemoryLimit() function of the IWebSocket interface.

This variable interacts with the MaxTextMessageBufferSize member of the FLwsWebSocket class, which is used to store the actual memory limit value.

Developers should be aware of the following when using this variable:

  1. The default value is 1MB (1024 * 1024 bytes) if not specified in the configuration.
  2. It affects only text messages, not binary messages.
  3. The WinHttp implementation currently does not support changing this limit (it logs a message that the feature is not implemented).

Best practices when using this variable include:

  1. Set an appropriate limit based on the expected size of text messages in your application to balance between memory usage and functionality.
  2. Consider the potential impact on performance and memory usage when setting very large limits.
  3. Handle potential errors that may occur if a message exceeds the set limit.
  4. Be consistent in setting this value across different platforms if your game targets multiple platforms, as the implementation may vary (e.g., between Lws and WinHttp).

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:74, section: [WebSockets]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Media/PixelStreaming/Source/PixelStreaming/Private/Tests/SignallingServerConnectionTests.cpp:96

Scope (from outer to inner):

file
namespace    anonymous
class        class FMockWebSocket : public IWebSocket
function     virtual void SetTextMessageMemoryLimit

Source code excerpt:

		virtual void Send(const FString& Data) override { OnMessageSentEvent.Broadcast(Data); }
		virtual void Send(const void* Data, SIZE_T Size, bool bIsBinary = false) override {}
		virtual void SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit) override {}
		virtual FWebSocketConnectedEvent& OnConnected() override { return OnConnectedEvent; }
		virtual FWebSocketConnectionErrorEvent& OnConnectionError() override { return OnErrorEvent; }
		virtual FWebSocketClosedEvent& OnClosed() override { return OnClosedEvent; }
		virtual FWebSocketMessageEvent& OnMessage() override { return OnMessageEvent; }
		virtual FWebSocketBinaryMessageEvent& OnBinaryMessage() override { return OnBinaryMessageEvent; }
		virtual FWebSocketRawMessageEvent& OnRawMessage() override { return OnRawMessageEvent; }

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/Lws/LwsWebSocket.cpp:81

Scope (from outer to inner):

file
function     FLwsWebSocket::FLwsWebSocket

Source code excerpt:

}

FLwsWebSocket::FLwsWebSocket(FPrivateToken, const FString& InUrl, const TArray<FString>& InProtocols, const FString& InUpgradeHeader, uint64 TextMessageMemoryLimit)
	: State(EState::None)
	, LastGameThreadState(EState::None)
	, bWasSendQueueEmpty(true)
	, LwsConnection(nullptr)
	, Url(InUrl)
	, Protocols(InProtocols)
	, UpgradeHeader(InUpgradeHeader)
	, MaxTextMessageBufferSize(TextMessageMemoryLimit)
	, Identifier(++IncrementingIdentifier)
{
	UE_LOG(LogWebSockets, VeryVerbose, TEXT("FLwsWebSocket[%d]: Constructed url=%s protocols=%s"), Identifier, *InUrl, *FString::Join(Protocols, TEXT(",")));
}

FLwsWebSocket::~FLwsWebSocket()

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/Lws/LwsWebSocket.cpp:179

Scope (from outer to inner):

file
function     void FLwsWebSocket::SetTextMessageMemoryLimit

Source code excerpt:



void FLwsWebSocket::SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit)
{
	MaxTextMessageBufferSize = TextMessageMemoryLimit;
}

void FLwsWebSocket::SendFromQueue()
{
	check(LwsConnection);

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/Lws/LwsWebSocket.h:137

Scope (from outer to inner):

file
class        class FLwsWebSocket : public IWebSocket , public TSharedFromThis<FLwsWebSocket>

Source code excerpt:

	virtual void Send(const FString& Data);
	virtual void Send(const void* Data, SIZE_T Size, bool bIsBinary) override;
	virtual void SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit) override;

	/** Delegate called when a web socket connection has been established */
	DECLARE_DERIVED_EVENT(FLwsWebSocket, IWebSocket::FWebSocketConnectedEvent, FWebSocketConnectedEvent);
	virtual FWebSocketConnectedEvent& OnConnected() override
	{
		return ConnectedEvent;

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/Lws/LwsWebSocket.h:221

Scope (from outer to inner):

file
class        class FLwsWebSocket : public IWebSocket , public TSharedFromThis<FLwsWebSocket>

Source code excerpt:

public:
	/** Constructor */
	FLwsWebSocket(FPrivateToken, const FString& Url, const TArray<FString>& Protocols, const FString& UpgradeHeader, uint64 TextMessageMemoryLimit);

private:
	/**
	 * Start connecting
	 * @param LwsContext libwebsockets context
	 */

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/Lws/LwsWebSocketsManager.cpp:411

Scope (from outer to inner):

file
function     TSharedRef<IWebSocket> FLwsWebSocketsManager::CreateWebSocket

Source code excerpt:


	// default memory limit for IWebSocket text messages
	int TextMessageMemoryLimit = 1024 * 1024;
	GConfig->GetInt(TEXT("WebSockets"), TEXT("TextMessageMemoryLimit"), TextMessageMemoryLimit, GEngineIni);

	FLwsWebSocketRef Socket = MakeShared<FLwsWebSocket>(FLwsWebSocket::FPrivateToken{}, Url, Protocols, UpgradeHeaderString, TextMessageMemoryLimit);
	return Socket;
}

void FLwsWebSocketsManager::StartProcessingWebSocket(FLwsWebSocket* Socket)
{
	Sockets.Emplace(Socket->AsShared());

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/WinHttp/WinHttpWebSocket.cpp:187

Scope (from outer to inner):

file
function     void FWinHttpWebSocket::SetTextMessageMemoryLimit

Source code excerpt:

}

void FWinHttpWebSocket::SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit)
{
	UE_LOG(LogWebSockets, Verbose, TEXT("SetTextMessageMemoryLimit not implemented for WinHttpWebSocket."));
}

FWinHttpWebSocket::FWebSocketConnectedEvent& FWinHttpWebSocket::OnConnected()
{

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Private/WinHttp/WinHttpWebSocket.h:43

Scope (from outer to inner):

file
class        class FWinHttpWebSocket : public IWebSocket , public TSharedFromThis<FWinHttpWebSocket>

Source code excerpt:

	virtual void Send(const FString& Data) override final;
	virtual void Send(const void* Data, SIZE_T Size, bool bIsBinary) override final;
	virtual void SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit) override final;
	DECLARE_DERIVED_EVENT(FWinHttpWebSocket, IWebSocket::FWebSocketConnectedEvent, FWebSocketConnectedEvent);
	virtual FWebSocketConnectedEvent& OnConnected() override final;
	DECLARE_DERIVED_EVENT(FWinHttpWebSocket, IWebSocket::FWebSocketConnectionErrorEvent, FWebSocketConnectionErrorEvent);
	virtual FWebSocketConnectionErrorEvent& OnConnectionError() override final;
	DECLARE_DERIVED_EVENT(FWinHttpWebSocket, IWebSocket::FWebSocketClosedEvent, FWebSocketClosedEvent);
	virtual FWebSocketClosedEvent& OnClosed() override final;

#Loc: <Workspace>/Engine/Source/Runtime/Online/WebSockets/Public/IWebSocket.h:44

Scope (from outer to inner):

file
class        class IWebSocket

Source code excerpt:

	/**
	 * Optionally change memory limit for receiving UTF-8 text on this socket. 
	 * Default from config TextMessageMemoryLimit under [WebSockets] or 1MB.
	 * @param TextMessageMemoryLimit new buffer size upper limit in bytes.
	 */
	virtual void SetTextMessageMemoryLimit(uint64 TextMessageMemoryLimit) = 0;

	/**
	 * Delegate called when a web socket connection has been established successfully.
	 *
	 */
	DECLARE_EVENT(IWebSocket, FWebSocketConnectedEvent);
	virtual FWebSocketConnectedEvent& OnConnected() = 0;