WebSocket Client - C++

Introduction

WebSocket is a communication protocol used in networking allowing full-duplex communication. You can learn more about it here. This page shows how to use the WebSockets module built in Unreal Engine 4 to create a client communicating with a WebSocket server in C++.

Setup

Adding the WebSocket module

To use this module, we need to update the project's

.Build.cs

. Open

MyProject/Source/MyProject/MyProject.build.cs

and add

WebSockets

to the public dependency module names :

// Copyright 1998-2020 Epic Games, Inc. All Rights Reserved.
using UnrealBuildTool;
    
public class MyProject: ModuleRules
{
    public MyProject(ReadOnlyTargetRules Target) : base(Target)
    {
        // Other code...
    
        PublicDependencyModuleNames.AddRange(new string[] { "WebSockets" });
    }
}

For the includes files to work with your IDE, you might want to close your IDE and regenerate project files.

Loading the module

In order to use this module, we need to load it. To do so, we will load it on game instance initialization :

// MyProjectGameInstance.h
UCLASS()
class MYPROJECT_API UMyProjectGameInstance : public UGameInstance
{
    GENERATED_BODY()
public:
    virtual void Init() override;
}

// MyProjectGameInstance.cpp
#include "WebSocketsModule.h"
void UMyProjectGameInstance::Init()
{
    Super::Init();
    
    // Load the WebSockets module. An assertion will fail if it isn't found.
    FWebSocketsModule& Module = FModuleManager::LoadModuleChecked<FWebSocketsModule>(TEXT("WebSockets"));
}

Utilisation

Header files

#include "WebSocketsModule.h" // Module definition
#include "IWebSocket.h"       // Socket definition

Creating the socket

The socket allows us to send or receive messages from the server. To create it, we call the

CreateWebSocket

function from the module.

const FString ServerURL = TEXT("ws://127.0.0.1:3000/"); // Your server URL. You can use ws, wss or wss+insecure.
const FString ServerProtocol = TEXT("ws");              // The WebServer protocol you want to use.
    
TSharedPtr<IWebSocket> Socket = FWebSocketsModule::Get().CreateWebSocket(ServerURL, ServerProtocol);

Connecting to the server

Before connecting to the server, we need to at least bind the events

OnConnection

and

OnConnectionError

.

NOTE: We are using lambdas here for readability. You can bind UObject or any other function as they are basic delegates.

// We bind all available events
Socket->OnConnected().AddLambda([]() -> void {
    // This code will run once connected.
});
    
Socket->OnConnectionError().AddLambda([](const FString & Error) -> void {
    // This code will run if the connection failed. Check Error to see what happened.
});
    
Socket->OnClosed().AddLambda([](int32 StatusCode, const FString& Reason, bool bWasClean) -> void {
    // This code will run when the connection to the server has been terminated.
    // Because of an error or a call to Socket->Close().
});
    
Socket->OnMessage().AddLambda([](const FString & Message) -> void {
    // This code will run when we receive a string message from the server.
});
    
Socket->OnRawMessage().AddLambda([](const void* Data, SIZE_T Size, SIZE_T BytesRemaining) -> void {
    // This code will run when we receive a raw (binary) message from the server.
});
    
Socket->OnMessageSent().AddLambda([](const FString& MessageString) -> void {
    // This code is called after we sent a message to the server.
});
    
// And we finally connect to the server. 
Socket->Connect();

Sending data

To send data, we use the

Send

method on our connected socket. The

Send

method is overloaded and can send either raw binary or a string.

if (!Socket->IsConnected())
{
    // Don't send if we're not connected.
    return;
}
    
const FString StringMessage = TEXT("Hello there !");
const TArray BinaryMessage = { 'H', 'e', 'l', 'l', 'o', ' ', 't', 'h', 'e', 'r', 'e', ' ', '!' };
  
Socket->Send(StringMessage);
Socket->Send(BinaryMessage.GetData(), sizeof(uint8) * BinaryMessage.Num());

Closing the connection

If you want to close the connection from the client side, call

Socket->Close()

.

References

Engine WebSockets API page.