Open 3D Engine AzNetworking API Reference  2205.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Classes | Public Member Functions | Friends | List of all members
AzNetworking::UdpNetworkInterface Class Referencefinal

This class implements a UDP network interface. More...

#include <UdpNetworkInterface.h>

Inherits AzNetworking::INetworkInterface.

Public Member Functions

 UdpNetworkInterface (AZ::Name name, IConnectionListener &connectionListener, TrustZone trustZone, UdpReaderThread &readerThread)
 
bool IsEncrypted () const
 
bool IsOpen () const
 
AZ::Name GetName () const override
 
ProtocolType GetType () const override
 
TrustZone GetTrustZone () const override
 
uint16_t GetPort () const override
 
IConnectionSetGetConnectionSet () override
 
IConnectionListenerGetConnectionListener () override
 
bool Listen (uint16_t port) override
 
ConnectionId Connect (const IpAddress &remoteAddress) override
 
void Update (AZ::TimeMs deltaTimeMs) override
 
bool SendReliablePacket (ConnectionId connectionId, const IPacket &packet) override
 
PacketId SendUnreliablePacket (ConnectionId connectionId, const IPacket &packet) override
 
bool WasPacketAcked (ConnectionId connectionId, PacketId packetId) override
 
bool StopListening () override
 
bool Disconnect (ConnectionId connectionId, DisconnectReason reason) override
 
void SetTimeoutMs (AZ::TimeMs timeoutMs) override
 
AZ::TimeMs GetTimeoutMs () const override
 
- Public Member Functions inherited from AzNetworking::INetworkInterface
 AZ_RTTI (INetworkInterface, "{ECDA6FA2-4AA0-435E-881F-214C4B179A31}")
 
const NetworkInterfaceMetricsGetMetrics () const
 
NetworkInterfaceMetricsGetMetrics ()
 

Friends

class UdpReliableQueue
 
class UdpConnection
 

Detailed Description

This class implements a UDP network interface.

UdpNetworkInterface is an implementation of AzNetworking::INetworkInterface. Since UDP is a very bare bones protocol, the Open 3D Engine implementation has to provide significantly more than its TCP counterpart (since TCP implements a significant number of reliability features.)

When sent through UDP, a packet can have additional actions performed on it depending on which features are enabled and configured. Each feature listed in this description is in the order a packet will see them on Send.

Packet structure

The general structure of a UDP packet is:

For more information, read Networking Packets in the O3DE documentation.

Reliability

UDP packets can be sent reliably or unreliably. Reliably sent packets are registered for tracking first. This causes the reliable packet to be resent if a timeout on the packet is reached. Once the packet is acknowledged, the packet is unregistered.

Fragmentation

If the raw packet size exceeds the configured maximum transmission unit (MTU) then the packet is broken into multiple reliable fragments to avoid fragmentation at the routing level. Fragments are always reliable so the original packet can be reconstructed. Operations that alter the payload generally follow this step so that they can be separately applied to the Fragments in addition to not being applied to both the original and Fragments.

Compression

Compression here refers to content insensitive compression using libraries like LZ4. If enabled, the target payload is run through the compressor and replaces the original payload if it's in fact smaller. To tell if compression is enabled on a given packet, we operate on a bit in the packet's Flags. The Sender writes this bit while the Receiver checks it to see if a packet needs to be decompressed.

O3DE could potentially move from over MTU to under with compression, and the UDP interface doesn't check for this. Detecting a change that would reduce the number of fragmented packets would require pre-emptively compressing payloads to tell if that change happened, which could potentially lead to a lot of unnecessary calls to the compressor.

Encryption

AzNetworking uses the OpenSSL library to implement Datagram Layer Transport Security (DTLS) encryption on UDP traffic. Encryption operates as described in O3DE Networking Encryption on the documentation website. Once both endpoints have completed their handshake, all traffic is expected to be fully encrypted.

Constructor & Destructor Documentation

◆ UdpNetworkInterface()

AzNetworking::UdpNetworkInterface::UdpNetworkInterface ( AZ::Name  name,
IConnectionListener connectionListener,
TrustZone  trustZone,
UdpReaderThread readerThread 
)

Constructor.

Parameters
namethe name of this network interface instance.
connectionListenerreference to the connection listener responsible for handling all connection events
trustZonethe trust level assigned to this network interface, server to server or client to server
readerThreadpointer to the reader thread to be bound to this network interface

Member Function Documentation

◆ Connect()

ConnectionId AzNetworking::UdpNetworkInterface::Connect ( const IpAddress remoteAddress)
overridevirtual

Opens a new connection to the provided address.

Parameters
remoteAddressthe IpAddress of the remote process to open a connection to
Returns
the connectionId of the new connection, or InvalidConnectionId if the operation failed

Implements AzNetworking::INetworkInterface.

◆ Disconnect()

bool AzNetworking::UdpNetworkInterface::Disconnect ( ConnectionId  connectionId,
DisconnectReason  reason 
)
overridevirtual

Disconnects the specified connection.

Parameters
connectionIdidentifier of the connection to terminate
reasonreason for the disconnect
Returns
boolean true on success

Implements AzNetworking::INetworkInterface.

◆ GetConnectionListener()

IConnectionListener& AzNetworking::UdpNetworkInterface::GetConnectionListener ( )
overridevirtual

Returns a reference to the connection listener for this network interface.

Returns
reference to the connection listener for this network interface

Implements AzNetworking::INetworkInterface.

◆ GetConnectionSet()

IConnectionSet& AzNetworking::UdpNetworkInterface::GetConnectionSet ( )
overridevirtual

Returns the connection set for this network interface.

Returns
the connection set for this network interface

Implements AzNetworking::INetworkInterface.

◆ GetName()

AZ::Name AzNetworking::UdpNetworkInterface::GetName ( ) const
overridevirtual

◆ GetPort()

uint16_t AzNetworking::UdpNetworkInterface::GetPort ( ) const
overridevirtual

Returns the port number this network interface is bound to.

Returns
the port number this network interface is bound to

Implements AzNetworking::INetworkInterface.

◆ GetTimeoutMs()

AZ::TimeMs AzNetworking::UdpNetworkInterface::GetTimeoutMs ( ) const
overridevirtual

Retrieves the timeout time in milliseconds for this network interface, 0 ms means timeouts are disabled.

Returns
the timeout time in milliseconds for this network interface, 0 ms means timeouts are disabled

Implements AzNetworking::INetworkInterface.

◆ GetTrustZone()

TrustZone AzNetworking::UdpNetworkInterface::GetTrustZone ( ) const
overridevirtual

Retrieves the trust zone for this network interface instance.

Returns
the trust zone for this network interface instance

Implements AzNetworking::INetworkInterface.

◆ GetType()

ProtocolType AzNetworking::UdpNetworkInterface::GetType ( ) const
overridevirtual

Retrieves the type of this network interface instance.

Returns
the type of this network interface instance

Implements AzNetworking::INetworkInterface.

◆ IsEncrypted()

bool AzNetworking::UdpNetworkInterface::IsEncrypted ( ) const

Returns true if this is an encrypted socket, false if not.

Returns
boolean true if this is an encrypted socket, false if not

◆ IsOpen()

bool AzNetworking::UdpNetworkInterface::IsOpen ( ) const

Returns true if this connection instance is in an open state, and is capable of actively sending and receiving packets.

Returns
boolean true if this connection instance is in an open state

◆ Listen()

bool AzNetworking::UdpNetworkInterface::Listen ( uint16_t  port)
overridevirtual

Opens the network interface to allow it to accept new incoming connections.

Parameters
portthe listen port number this network interface will potentially bind to, 0 if it's a don't care
Returns
boolean true if the operation was successful, false if it failed

Implements AzNetworking::INetworkInterface.

◆ SendReliablePacket()

bool AzNetworking::UdpNetworkInterface::SendReliablePacket ( ConnectionId  connectionId,
const IPacket packet 
)
overridevirtual

A helper function that transmits a packet on this connection reliably. Note that a packetId is not returned here, since retransmits may cause the packetId to change

Parameters
connectionIdidentifier of the connection to send to
packetpacket to transmit
Returns
boolean true if the packet was transmitted (not an indication of delivery)

Implements AzNetworking::INetworkInterface.

◆ SendUnreliablePacket()

PacketId AzNetworking::UdpNetworkInterface::SendUnreliablePacket ( ConnectionId  connectionId,
const IPacket packet 
)
overridevirtual

A helper function that transmits a packet on this connection unreliably.

Parameters
connectionIdidentifier of the connection to send to
packetpacket to transmit
Returns
the unreliable packet identifier of the transmitted packet

Implements AzNetworking::INetworkInterface.

◆ SetTimeoutMs()

void AzNetworking::UdpNetworkInterface::SetTimeoutMs ( AZ::TimeMs  timeoutMs)
overridevirtual

Sets the timeout time in milliseconds, 0 ms means timeouts are disabled.

Parameters
timeoutMsthe number of milliseconds with no traffic before we timeout and close a connection

Implements AzNetworking::INetworkInterface.

◆ StopListening()

bool AzNetworking::UdpNetworkInterface::StopListening ( )
overridevirtual

Closes the network interface to stop accepting new incoming connections.

Returns
boolean true if the operation was successful, false if it failed

Implements AzNetworking::INetworkInterface.

◆ Update()

void AzNetworking::UdpNetworkInterface::Update ( AZ::TimeMs  deltaTimeMs)
overridevirtual

Updates the INetworkInterface.

Parameters
deltaTimeMsmilliseconds since update was last invoked

Implements AzNetworking::INetworkInterface.

◆ WasPacketAcked()

bool AzNetworking::UdpNetworkInterface::WasPacketAcked ( ConnectionId  connectionId,
PacketId  packetId 
)
overridevirtual

Returns true if the given packet id was confirmed acknowledged by the remote endpoint, false otherwise.

Parameters
connectionIdidentifier of the connection to send to
packetIdthe packet id of the packet to confirm acknowledgment of
Returns
boolean true if the packet is confirmed acknowledged, false if the packet number is out of range, lost, or still pending acknowledgment

Implements AzNetworking::INetworkInterface.


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