#include <Telemetry.h>

Classes
struct	TelemetryEventData

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

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

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

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

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

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

static void	Broadcast (TransmitMode tm, ezUInt32 uiSystemID, ezUInt32 uiMsgID, ezStreamReader &inout_stream, ezInt32 iDataBytes=-1)

static void	Broadcast (TransmitMode tm, ezTelemetryMessage &ref_msg)

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

static void	SendToServer (ezUInt32 uiSystemID, ezUInt32 uiMsgID, ezStreamReader &inout_stream, ezInt32 iDataBytes=-1)

static void	SendToServer (ezTelemetryMessage &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 ezTime	GetPingToServer ()
	Returns the last round trip time ('Ping') to the Server. Only meaningful if there is an active connection (see IsConnectedToServer() ).

static ezStringView	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 (ezStringView sName)
	Sets the name of the telemetry server. This is broadcast to connected clients, which can display this string for usability. More...

static ezStringView	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 ezUInt32	GetServerID ()
	Returns a 'unique' ID for the application instance to which this Client is connected. More...

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

Static Public Attributes
static ezUInt16	s_uiPort = 1040
	The port over which ezTelemetry will connect.

Friends
class	ezTelemetryThread

Processing Messages
using	ProcessMessagesCallback = void()(void )

static ezResult	RetrieveMessage (ezUInt32 uiSystemID, ezTelemetryMessage &out_message)
	Checks whether any message for the system with the given ID exists and returns that. More...

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

static void	AcceptMessagesForSystem (ezUInt32 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 (ezUInt32 uiSystemID, ezUInt16 uiMaxQueued)
	Specifies how many reliable messages from a system might get queued when no recipient is available yet. More...

ezTelemetry Events
using	ezEventTelemetry = ezEvent< const TelemetryEventData &, ezMutex >

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

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

Detailed Description

Todo:: document and test (and finish)

Member Enumeration Documentation

◆ ConnectionMode

enum ezTelemetry::ConnectionMode

Defines how the ezTelemetry 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 ezTelemetry::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 ezTelemetry::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()

ezResult ezTelemetry::ConnectToServer ( ezStringView 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 ezTelemetry connection mode to 'Client'. This is mutually exclusive with CreateServer().

◆ CreateServer()

void ezTelemetry::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 ezUInt32 ezTelemetry::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()

ezMutex & ezTelemetry::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()

ezResult ezTelemetry::RetrieveMessage	(	ezUInt32	uiSystemID,
		ezTelemetryMessage &	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, EZ_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 ezTelemetry::SetOutgoingQueueSize	(	ezUInt32	uiSystemID,
		ezUInt16	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 ezTelemetry::SetServerName ( ezStringView 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 ezTelemetry::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/ezEngine/ezEngine/Code/Engine/Foundation/Communication/Telemetry.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Communication/Implementation/Telemetry.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Communication/Implementation/TelemetryHelpers.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Communication/Implementation/TelemetryThread.cpp
/home/runner/work/ezEngine/ezEngine/Code/EnginePlugins/InspectorPlugin/InspectorPlugin.cpp

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Friends

Processing Messages

ezTelemetry Events

Detailed Description

Member Enumeration Documentation

◆ ConnectionMode

◆ TransmitMode

Member Function Documentation

◆ CloseConnection()

◆ ConnectToServer()

◆ CreateServer()

◆ GetServerID()

◆ GetTelemetryMutex()

◆ RetrieveMessage()

◆ SetOutgoingQueueSize()

◆ SetServerName()

◆ UpdateNetwork()