ezEngine  Milestone 9
ezTelemetry Class Reference

#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 (const char *szConnectTo=nullptr)
 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 &Stream, ezInt32 iDataBytes=-1)
 
static void Broadcast (TransmitMode tm, ezTelemetryMessage &Msg)
 
static void SendToServer (ezUInt32 uiSystemID, ezUInt32 uiMsgID, const void *pData=nullptr, ezUInt32 uiDataBytes=0)
 
static void SendToServer (ezUInt32 uiSystemID, ezUInt32 uiMsgID, ezStreamReader &Stream, ezInt32 iDataBytes=-1)
 
static void SendToServer (ezTelemetryMessage &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 const char * GetServerIP ()
 Returns the name of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ). More...
 
static ezUInt32 GetServerID ()
 Returns a 'unique' ID for the application instance to which this Client is connected. More...
 
static ezMutexGetTelemetryMutex ()
 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

typedef void(* ProcessMessagesCallback) (void *pPassThrough)
 
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

typedef ezEvent< const TelemetryEventData &, ezMutexezEventTelemetry
 
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

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

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 ( const char *  szConnectTo = nullptr)
static

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

Parameters
szConnectToString 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.

◆ GetServerIP()

static const char* ezTelemetry::GetServerIP ( )
inlinestatic

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

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

◆ 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
uiSystemIDThe ID for the system that sends the messages.
uiMaxQueuedThe 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.

◆ 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: