NetworkMgr::SetNetworkEventCallback

Defined in: C4Network.h

Installs a callback function that is called when a network event occurs.

NOTE. This is a low-level function that is normally called exclusively by the Message Manager. Calling this function directly is not recommended if the Message Manager is being used.

Prototype

void SetNetworkEventCallback(NetworkEventCallback *callback);

Parameters

callback A pointer to a network event callback function. This parameter may be nullptr, in which case no network event callback function is called when a network event occurs.

Description

The Network Manager generates a network event when a network connection is created or destroyed. When a network event occurs, the Network Manager calls the currently installed network event callback function. The following are the possible network events.

`kNetworkEventOpen`	A new connection has been opened by means of the local machine accepting a connection request from a remote machine.
`kNetworkEventAccept`	A connection request originating from the local machine has been accepted by a remote machine.
`kNetworkEventClose`	A remote machine has explicitly disconnected from the local machine.
`kNetworkEventFail`	An attempt to connection to a remote machine has failed.
`kNetworkEventTimeout`	A remote machine has timed out due to a reliable packet not being acknowledged.

The NetworkEventCallback type is defined as follows.

typedef void NetworkEventCallback(NetworkEvent, const NetworkAddress&, uint32);

The first parameter passed to this function is set to one of the above network event constants. The second parameter is the address of the machine to which the network event pertains. The third parameter is currently used only for the kNetworkEventFailed event and supplies one of the following reasons for the connection failure.

`kNetworkFailTimeout`	The remote machine did not respond and the connection attempt timed out.
`kNetworkFailWrongProtocol`	The remote machine is not using the same communications protocol that the local machine is using.
`kNetworkFailNotServer`	The remote machine is using the correct protocol, but it is not a server.
`kNetworkFailServerFull`	The remote machine did not accept the connection because the maximum number of clients have already connected.