MessageMgr::BeginMultiplayerGame

Defined in: C4Messages.h

Configures the Message Manager for a multiplayer game.

Prototype

NetworkResult BeginMultiplayerGame(bool host = true);

Parameters

host Indicates whether the local machine is the server.

Description

Calling the BeginMultiplayerGame function places the Message Manager in multiplayer mode and returns one of the following network result codes.

`kEngineOkay`	The Network Manager was successfully initialized and the Message Manager has been placed in multiplayer mode.
`kNetworkInitFailed`	The Network Manager could not be initialized because the operating system returned an error. If this result code is returned, then the Message Manager remains in single player mode.

If the host parameter is set to true, then the local machine is configured as the server. In this case, the BeginMultiplayerGame function calls the Network Manager function NetworkMgr::SetMaxConnectionCount to set the maximum number of connections that will be accepted by client machines. The number of connections allowed is one less than the current maximum player count since the server machine counts as the first player. The maximum player count should be set prior to calling BeginMultiplayerGame by calling the MessageMgr::SetMaxPlayerCount function.

If the host parameter is set to false, then the local machine is configured as a client. In this case, the BeginMultiplayerGame function calls the Network Manager function NetworkMgr::SetMaxConnectionCount with a maximum connection count of zero to prevent other machines from connecting to the local machine. The local machine is still able to make outgoing connections.

After a successful call to BeginMultiplayerGame, subsequent calls to MessageMgr::GetMultiplayerFlag return true, and subsequent calls to MessageMgr::GetServerFlag return the value given by the host parameter. If BeginMultiplayerGame returns the result code kNetworkInitFailed, then the Message Manager is placed in single player mode.

On a machine configured as a multiplayer server, the Message Manager calls the Application::HandleConnectionEvent function with the kConnectionQueryReceived event whenever it receives a broadcasted query asking servers to identify themselves.

Special Considerations

A call to the MessageMgr::Connect function while the Message Manager is in single player mode will cause an implicit call to BeginMultiplayerGame to be made in an attempt to configure the local machine as a multiplayer client. If the Message Manager is already in multiplayer mode (as a client or as a server) when the MessageMgr::Connect function is called, then the BeginMultiplayerGame function is not implicitly called.

Before calling BeginMultiplayerGame, the Network Manager function NetworkMgr::SetPortNumber should be called to indicate what port is to be used for communications. For a server, the port number should be one on which clients expect the server to be listening. For a client, the port number may be zero, in which case the underlying TCP/IP implementation will choose an available port number automatically.

The Network Manager function NetworkMgr::SetBroadcastPortNumber should also be called to set the port on which broadcasts will be sent and received. For a server, the broadcast port number should be the same as the normal port number. For a client, the broadcast port number should specify the port on which it expects servers to be listening.