NetworkMgr::SendReliablePacket

Defined in: C4Network.h

Sends a reliable packet to another machine.

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

NetworkResult SendReliablePacket(const NetworkAddress& to, unsigned long size, const void *data, unsigned long flags = 0);

Parameters

`to`	The destination address.
`size`	The size of the data packet. This value may not exceed the maximum size given by the constant `kMaxMessageSize`.
`data`	A pointer to the data to be sent.
`flags`	Packet flags. This value is used internally and should be set to zero.

Description

The SendReliablePacket function sends a data packet to the machine whose address is given by the to parameter and listens for an acknowledgement of receipt. The return value is one of the following network result codes.

`kNetworkOkay`	The packet was successfully queued for transmission.
`kNetworkNoConnection`	The operation failed because the address specified by the `to` parameter does not correspond to any current network connection.
`kNetworkPacketTooLarge`	The packet could not be sent because its size exceeds `kMaxMessageSize`.
`kNetworkBufferFull`	The packet could not be sent because the outgoing packet buffers are full. Try sending the packet again at a later time.

A connection must be established with a machine before the SendReliablePacket function can be used to send messages to it. Connections are established at the Network Manager level by calling the NetworkMgr::Connect function.

When the Network Manager sends a reliable packet, it waits for a return receipt, or acknowledgement, from the receiving machine which confirms the packet's arrival at its destination. If an acknowledgement has not been received after a certain time period, the packet is retransmitted. The Network Manager makes a certain number of attempts before a connection is considered to have timed out. The number of attempts and the time interval between those attempts can be set using the NetworkMgr::SetReliableResendCount and NetworkMgr::SetReliableResendTime functions.

When a connection times out because a reliable packet was not acknowledged, the Network Manager calls the currently installed network event procedure, if any, and then disconnects from the machine that timed out. The low-level network event procedure can be set using the NetworkMgr::SetNetworkEventProc function, but this procedure should not be changed if the Message Manager is being used. Instead, the Message Manager will call the Application::HandleConnectionEvent function when a connection times out.

Packet data is encrypted before it is transmitted.