Support Forum       G3D Web Page     
Classes | Public Member Functions | Static Public Member Functions | Friends | List of all members
G3D::NetworkDevice Class Reference

Abstraction of network (socket) functionality. More...

Classes

class  EthernetAdapter
 Description of an ethernet or wireless ethernet adapter. More...
 

Public Member Functions

 ~NetworkDevice ()
 
const Array< EthernetAdapter > & adapterArray () const
 Returns the available ethernet adapters for the current machine that are online. More...
 
const Array< uint32 > & broadcastAddressArray () const
 Returns the (unique) IP addresses for UDP broadcasting extracted from adapterArray(). More...
 
void describeSystem (TextOutput &t)
 
Prints a human-readable description of this machine to the text output stream. More...
 
void describeSystem (String &s)
 
void localHostAddresses (Array< NetAddress > &array) const
 There is often more than one address for the local host. More...
 
String localHostName () const
 Returns the name (or one of the names) of this computer. More...
 

Static Public Member Functions

static void cleanup ()
 
Shuts down the network device (destroying the global instance). More...
 
static String formatIP (uint32 ip)
 Prints an IP address to a string. More...
 
static String formatMAC (const uint8 mac[6])
 Prints a MAC address to a string. More...
 
static NetworkDeviceinstance ()
 
Returns nullptr if there was a problem initializing the network. More...
 

Friends

class Conduit
 
class LightweightConduit
 
class NetListener
 
class ReliableConduit
 

Detailed Description

Abstraction of network (socket) functionality.

An abstraction over sockets that provides a message-based network infrastructure optimized for sending many small (~500 bytes) messages. All functions always return immediately.

Create only one NetworkDevice per process (a WinSock restriction).

NetworkDevice is technically not thread safe. However, as long as you use different conduits on different threads (or lock conduits before sending), you will encounter no problems sharing the single NetworkDevice across multiple threads. That is, do not invoke the same Conduit's send or receive method on two threads at once.

This assumes that the underlying WinSock/BSD sockets implementation is thread safe. That is not guaranteed, but in practice seems to always be true (see http://tangentsoft.net/wskfaq/intermediate.html#threadsafety)


IP networks use "network byte order" (big-endian) for communicating integers. "Host byte order" is the endian-ness of the local machine (typically little-endian; see System::endian). The C functions htonl() and ntohl() convert 32-bit values between these formats. G3D only ever exposes host byte order, so programmers rarely need to be aware of the distinction.


These classes abstract networking from the socket level to a serialized messaging style that is more appropriate for games. The performance has been tuned for sending many small messages. The message protocol contains a header that prevents them from being used with raw UDP/TCP (e.g. connecting to an HTTP server).

LightweightConduit and ReliableConduits have different interfaces because they have different semantics. You would never want to interchange them without rewriting the surrounding code.

NetworkDevice creates conduits because they need access to a global log pointer and because I don't want non-reference counted conduits being created.

Be careful with threads and reference counting. The reference counters are not threadsafe, and are also not updated correctly if a thread is explicitly killed. Since the conduits will be passed by const XConduitRef& most of the time this doesn't appear as a major problem. With non-blocking conduits, you should need few threads anyway.

LightweightConduits preceed each message with a 4-byte host order unsigned integer that is the message type. This does not appear in the message serialization/deserialization.

ReliableConduits preceed each message with two 4-byte host order unsigned integers. The first is the message type and the second indicates the length of the rest of the data. The size does not include the size of the header itself. The minimum message is 9 bytes:a 4-byte type, a 4-byte header equal to "1", and one byte of data.

Deprecated:

Constructor & Destructor Documentation

◆ ~NetworkDevice()

G3D::NetworkDevice::~NetworkDevice ( )

Member Function Documentation

◆ adapterArray()

const Array<EthernetAdapter>& G3D::NetworkDevice::adapterArray ( ) const
inline

Returns the available ethernet adapters for the current machine that are online.

Does not include the loopback adapter for localhost.

◆ broadcastAddressArray()

const Array<uint32>& G3D::NetworkDevice::broadcastAddressArray ( ) const
inline

Returns the (unique) IP addresses for UDP broadcasting extracted from adapterArray().

All are in host byte order.

◆ cleanup()

static void G3D::NetworkDevice::cleanup ( )
static


Shuts down the network device (destroying the global instance).

◆ describeSystem() [1/2]

void G3D::NetworkDevice::describeSystem ( TextOutput t)


Prints a human-readable description of this machine to the text output stream.

◆ describeSystem() [2/2]

void G3D::NetworkDevice::describeSystem ( String s)

◆ formatIP()

static String G3D::NetworkDevice::formatIP ( uint32  ip)
static

Prints an IP address to a string.

Parameters
ipIn host byte order.

◆ formatMAC()

static String G3D::NetworkDevice::formatMAC ( const uint8  mac[6])
static

Prints a MAC address to a string.

◆ instance()

static NetworkDevice* G3D::NetworkDevice::instance ( )
static


Returns nullptr if there was a problem initializing the network.

◆ localHostAddresses()

void G3D::NetworkDevice::localHostAddresses ( Array< NetAddress > &  array) const

There is often more than one address for the local host.

This returns all of them.

Deprecated:
Use adapterArray()

◆ localHostName()

String G3D::NetworkDevice::localHostName ( ) const

Returns the name (or one of the names) of this computer.

Friends And Related Function Documentation

◆ Conduit

friend class Conduit
friend

◆ LightweightConduit

friend class LightweightConduit
friend

◆ NetListener

friend class NetListener
friend

◆ ReliableConduit

friend class ReliableConduit
friend

documentation generated on Wed Nov 24 2021 08:01:58 using doxygen 1.8.15