ezEngine  Milestone 7
ezTelemetry Class Reference

#include <Telemetry.h>

Classes

struct  MessageQueue
 
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, ezStreamReaderBase &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, ezStreamReaderBase &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 * GetServerName ()
 Returns the name of the machine on which the Server is running. Only meaningful if there is an active connection (see IsConnectedToServer() ).
 
static const char * 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 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.
 

Private Types

typedef ezDeque
< ezTelemetryMessage
MessageDeque
 

Static Private Member Functions

static void UpdateServerPing ()
 
static ezResult OpenConnection (ConnectionMode Mode, const char *szConnectTo=nullptr)
 
static void Transmit (TransmitMode tm, const void *pData, ezUInt32 uiDataBytes)
 
static void Send (TransmitMode tm, ezUInt32 uiSystemID, ezUInt32 uiMsgID, const void *pData, ezUInt32 uiDataBytes)
 
static void Send (TransmitMode tm, ezUInt32 uiSystemID, ezUInt32 uiMsgID, ezStreamReaderBase &Stream, ezInt32 iDataBytes=-1)
 
static void Send (TransmitMode tm, ezTelemetryMessage &msg)
 
static void FlushOutgoingQueues ()
 
static void InitializeAsServer ()
 
static ezResult InitializeAsClient (const char *szConnectTo)
 
static void QueueOutgoingMessage (TransmitMode tm, ezUInt32 uiSystemID, ezUInt32 uiMsgID, const void *pData, ezUInt32 uiDataBytes)
 
static void StartTelemetryThread ()
 
static void StopTelemetryThread ()
 

Static Private Attributes

static ConnectionMode s_ConnectionMode = ezTelemetry::None
 
static ezUInt32 s_uiApplicationID = 0
 
static ezUInt32 s_uiServerID = 0
 
static ezString s_ServerName
 
static ezString s_ServerIP
 
static bool s_bConnectedToServer = false
 
static bool s_bConnectedToClient = false
 
static bool s_bAllowNetworkUpdate = true
 
static ezTime s_PingToServer
 
static ezMap< ezUInt64,
MessageQueue
s_SystemMessages
 
static ezEventTelemetry s_TelemetryEvents
 
static ezMutex s_TelemetryMutex
 

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 &, ezMutex
ezEventTelemetry
 
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

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.

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

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.

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().

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.

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.

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.

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.

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.

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.

Todo:
This assumes we only connect to a single client ...
Todo:
This assumes we only connect to a single client ...

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