#include <Telemetry.h>

Classes
struct	TelemetryEventData

Public Types
enum	ConnectionMode { None , Server , Client }
	Defines how the xiiTelemetry system was configured. More...

enum	TransmitMode { Reliable , Unreliable }
	Describes how to send messages. More...

Static Public Member Functions
Connection Configuration
static xiiResult	ConnectToServer (xiiStringView sConnectTo={})
	Starts a connection as a 'Client' to one server.

static void	CreateServer ()
	Opens a connection as a server.

static void	CloseConnection ()
	Closes any connection previously opened using ConnectToServer() or CreateServer().

Sending Data
static void	Broadcast (TransmitMode tm, xiiUInt32 uiSystemID, xiiUInt32 uiMsgID, const void *pData, xiiUInt32 uiDataBytes)

static void	Broadcast (TransmitMode tm, xiiUInt32 uiSystemID, xiiUInt32 uiMsgID, xiiStreamReader &ref_stream, xiiInt32 iDataBytes=-1)

static void	Broadcast (TransmitMode tm, xiiTelemetryMessage &ref_msg)

static void	SendToServer (xiiUInt32 uiSystemID, xiiUInt32 uiMsgID, const void *pData=nullptr, xiiUInt32 uiDataBytes=0)

static void	SendToServer (xiiUInt32 uiSystemID, xiiUInt32 uiMsgID, xiiStreamReader &ref_stream, xiiInt32 iDataBytes=-1)

static void	SendToServer (xiiTelemetryMessage &ref_msg)

Querying State
static ConnectionMode	GetConnectionMode ()
	Returns whether the telemetry system is set up as Server, Client or not initialized at all.

static bool	IsConnectedToServer ()
	Returns whether a Client has an active connection to a Server.

static bool	IsConnectedToClient ()
	Returns whether a Server has an active connection to at least one Client.

static bool	IsConnectedToOther ()
	Returns whether a connection to another application has been made. Does not differentiate between Server and Client mode.

static xiiTime	GetPingToServer ()
	Returns the last round trip time ('Ping') to the Server. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static xiiStringView	GetServerName ()
	Returns the name of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static void	SetServerName (xiiStringView sName)
	Sets the name of the telemetry server. This is broadcast to connected clients, which can display this string for usability.

static xiiStringView	GetServerIP ()
	Returns the IP address of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static xiiUInt32	GetServerID ()
	Returns a 'unique' ID for the application instance to which this Client is connected.

static xiiMutex &	GetTelemetryMutex ()
	Returns the internal mutex used to synchronize all telemetry data access.

Static Public Attributes
static xiiUInt16	s_uiPort = 1040
	The port over which xiiTelemetry will connect.

Friends
class	xiiTelemetryThread

Processing Messages
using	ProcessMessagesCallback = void ()(void)

static xiiResult	RetrieveMessage (xiiUInt32 uiSystemID, xiiTelemetryMessage &out_message)
	Checks whether any message for the system with the given ID exists and returns that.

static void	UpdateNetwork ()
	Polls the network for new incoming messages and ensures outgoing messages are sent.

static void	AcceptMessagesForSystem (xiiUInt32 uiSystemID, bool bAccept, ProcessMessagesCallback callback=nullptr, void *pPassThrough=nullptr)

static void	PerFrameUpdate ()
	Call this once per frame to process queued messages and to send the PerFrameUpdate event.

static void	SetOutgoingQueueSize (xiiUInt32 uiSystemID, xiiUInt16 uiMaxQueued)
	Specifies how many reliable messages from a system might get queued when no recipient is available yet.

xiiTelemetry Events
using	xiiEventTelemetry = xiiEvent<const TelemetryEventData&, xiiMutex>

static void	AddEventHandler (xiiEventTelemetry::Handler handler)
	Adds an event handler that is called for every xiiTelemetry event.

static void	RemoveEventHandler (xiiEventTelemetry::Handler handler)
	Removes a previously added event handler.

Detailed Description

Todo: document and test (and finish)

Member Enumeration Documentation

◆ ConnectionMode

enum xiiTelemetry::ConnectionMode

Defines how the xiiTelemetry system was configured.

Enumerator
None	Not configured yet, at all.
Server	Set up as a Server, i.e. this is an application that broadcasts information about its current state to one or several Clients.
Client	Set up as a Client, i.e. this is a tool that gathers information from a Server, usually for debugging/inspection use cases.

◆ TransmitMode

enum xiiTelemetry::TransmitMode

Describes how to send messages.

Enumerator
Reliable	Messages should definitely arrive at the target, if necessary they are send several times, until the target acknowledged it.
Unreliable	Messages are sent at most once, if they get lost, they are not resend. If it is known beforehand, that not receiver exists, they are dropped without sending them at all.

Member Function Documentation

◆ CloseConnection()

void xiiTelemetry::CloseConnection ( )

static

Closes any connection previously opened using ConnectToServer() or CreateServer().

This will remove all queued incoming and outgoing messages (though it might send some of them still). It will not reset the state of which messages are filtered out or which callbacks to fire.

◆ ConnectToServer()

xiiResult xiiTelemetry::ConnectToServer ( xiiStringView sConnectTo = {} )

static

Starts a connection as a 'Client' to one server.

Parameters

szConnectTo String that contains a host name or IP address to connect to. If empty, 'localhost' is used.

Note: Connections to invalid host names often succeed, because the underlying network API will fall back to 'localhost'. Connections to invalid IP addresses will however always fail.

This function will set the xiiTelemetry connection mode to 'Client'. This is mutually exclusive with CreateServer().

◆ CreateServer()

void xiiTelemetry::CreateServer ( )

static

Opens a connection as a server.

Other applications can then connect to this application using ConnectToServer() with the IP of this machine.

◆ GetServerID()

static xiiUInt32 xiiTelemetry::GetServerID ( )

inlinestatic

Returns a 'unique' ID for the application instance to which this Client is connected.

Only meaningful if there is an active connection (see IsConnectedToServer() ). This can be used when a connection got lost and a Client had to reconnect to the Server, to check whether the instance that the Client connected to is still the same as before. If it did not change, the application can simply continue gathering data. Otherwise it should clear its state and start from scratch.

◆ GetTelemetryMutex()

xiiMutex & xiiTelemetry::GetTelemetryMutex ( )

static

Returns the internal mutex used to synchronize all telemetry data access.

This can be used to block all threads from accessing telemetry data, thus stopping the application. This can be useful when you want to implement some operation that is fully synchronous with some external tool and you want to wait for its response and prevent all other actions while you wait for that.

◆ RetrieveMessage()

xiiResult xiiTelemetry::RetrieveMessage	(	xiiUInt32	uiSystemID,
		xiiTelemetryMessage &	out_message )

static

Checks whether any message for the system with the given ID exists and returns that.

If no message for the given system is available, XII_FAILURE is returned. This function will not poll the network to check whether new messages arrived. Use UpdateNetwork() and RetrieveMessage() in a loop, if you are waiting for a specific message, to continuously update the network state and check whether the desired message has arrived. However, if you do so, you will be able to deadlock your application, if such a message never arrives. Also it might fill up other message queues which might lead to messages getting discarded.

◆ SetOutgoingQueueSize()

void xiiTelemetry::SetOutgoingQueueSize	(	xiiUInt32	uiSystemID,
		xiiUInt16	uiMaxQueued )

static

Specifies how many reliable messages from a system might get queued when no recipient is available yet.

Parameters

uiSystemID	The ID for the system that sends the messages.
uiMaxQueued	The maximum number of reliable messages that get queued and delivered later, once a proper recipient is available. Set this to zero to discard all messages from a system, when no recipient is available.

The default queue size is 1000. When a connection to a suitable recipient is made, all queued messages are delivered in one burst.

◆ SetServerName()

void xiiTelemetry::SetServerName ( xiiStringView sName )

static

Sets the name of the telemetry server. This is broadcast to connected clients, which can display this string for usability.

Usually this would be used to send the application name, to make it easier to see to which app the tool is connected, but setting a custom name can be used to add important details, e.g. whether the app is running in single-player or multi-player mode etc. The server name can be changed at any time.

◆ UpdateNetwork()

void xiiTelemetry::UpdateNetwork ( )

static

Polls the network for new incoming messages and ensures outgoing messages are sent.

Usually it is not necessary to call this function manually, as a worker thread will do that periodically already. However, if you are waiting for a specific message (see RetrieveMessage() ), you can call this function in a loop together with RetrieveMessage() to wait for that message. In that case it might also make sense to use GetTelemetryMutex() to lock the entire section while waiting for the message.

The documentation for this class was generated from the following files:

/home/runner/work/XII/XII/Source/Engine/Foundation/Communication/Telemetry.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Communication/Implementation/Telemetry.cpp
/home/runner/work/XII/XII/Source/Engine/Foundation/Communication/Implementation/TelemetryHelpers.cpp
/home/runner/work/XII/XII/Source/Engine/Foundation/Communication/Implementation/TelemetryThread.cpp
/home/runner/work/XII/XII/Source/EnginePlugins/InspectorPlugin/InspectorPlugin.cpp

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Friends

Processing Messages

xiiTelemetry Events

Detailed Description

Member Enumeration Documentation

◆ ConnectionMode

◆ TransmitMode

Member Function Documentation

◆ CloseConnection()

◆ ConnectToServer()

◆ CreateServer()

◆ GetServerID()

◆ GetTelemetryMutex()

◆ RetrieveMessage()

◆ SetOutgoingQueueSize()

◆ SetServerName()

◆ UpdateNetwork()