MessageMgr::Connect

Defined in: C4Messages.h

Establishes a connection with a server.

Prototype

NetworkResult Connect(const NetworkAddress& address);

Parameters

address The address of the server.

Description

Calling the Connect function causes a connection request to be sent to the server at the network address given by the address parameter. If the Message Manager is in single player mode, the Connect function attempts to configure the local machine as a multiplayer client by calling the MessageMgr::BeginMultiplayerGame function with the host parameter set to false. The Connect function returns one of the following network result codes.

`kEngineOkay`	The Network Manager was successfully initialized and the connection request was submitted.
`kNetworkInitFailed`	The Network Manager could not be initialized because the operating system returned an error.

If successful, the Connect function returns immediately and the Network Manager listens for a response. The number of attempts to make a connection and the time interval between attempts are controlled by the reliable resend count and reliable resend time settings maintained by the Network Manager.

If the connection is accepted by the server, a new Player object is created to represent the server and this player is added to the Message Manager's player map. The Message Manager then calls the Application::HandleConnectionEvent function with the kConnectionServerAccepted event to notify the application module that the connection has been established. The Message Manager will then make a call to the Application::HandlePlayerEvent function with the kPlayerConnected event once for each player already connected to the server to inform the application module about any additional players in the game. The Message Manager on the server machine and every other client machine connected to the game also calls Application::HandlePlayerEvent one time to inform the application modules running on those machines that a new player has arrived.

After the server accepts a connection and sends events about the players in a game, the Message Manager on the server calls the Application::HandlePlayerEvent function with the kPlayerInitialized event to inform the application module to optionally send any kind of game information messages needed before the current game state is sent. Then, the server sends the message journal to the new client. Finally, the server allows all StateSender objects to send their game state.

If the connection attempt fails or the connection request was denied by the server, the Message Manager calls the Application::HandleConnectionEvent function with the kConnectionAttemptFailed event to notify the application module that the connection could not be established. The reason for the connection failure passed to this function is one of the following constants.

`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.