NetworkProtocol
From OpenCity
Nowadays, more and more games offer the possibility to play on-line and share game experience with anyone over the Internet. Why not OpenCity ? The main idea is: in fact you are not alone to build a big city, and you are not alone to decide everything neither. So in the future releases, you can share the management of your city with the others via Internet.
If you want to run a server, there will be 2 modes:
- One-man-show mode
- Cooperation mode
As a server, you can limit the number of clients who would like to cooperate or visit your favorite city. Whereas a client will be able to choose between:
- Visitor mode
- Cooperation mode
When an OpenCity server is opened to anyone in "Cooperation mode", a client will be able to join it either in "Visitor mode" or in "Cooperation mode". When an OpenCity server is run in "One-man-show mode", the clients can join it with "Visitor mode" only.
Contents |
Current implementation
The networking support is implemented as the development of OpenCity goes. Refer to this page for more information.
Networking interface (c: client, s: server)
IP GetClientIP( int index ): (s), return the IP of the specified client
uint GetClientNum: (s), return the current number of active connections
uint GetClientMax: (s), return the maximum number of the connections that the server can handle. If the queried machine is running OpenCity as a client application, the returned value is undefined.
enum GetMachineRole: (c/s), return the following enumerations: OC_SERVER_STANDARD OC_SERVER_DISTRIBUTED OC_CLIENT_STANDARD OC_CLIENT_SERVER
uint GetPing: (c/s), return the maximum ping time in millisecond.
uint GetServerNum: (c/s), return the number of servers that the machine knows
IP GetServerIP( int index ): (c/s), return the IP of the specified server
string GetVersion: (c/s), return the string which describes the OpenCity version of the remote machine. Example: 0.0.2beta
string GetProtocol: (c/s), return the string which describes the latest OpenCity networking protocol that the machine can understand. The returned string is in the form: x.y.z like 0.0.1
enum Open( IP adr): (c/s), try to open a connection to the host specified by its IP OC_CONNECTION_ACCEPTED OC_CONNECTION_REJECTED OC_CONNECTION_TIMEOUT
enum Close(): (c), close the connection to the server
enum Close( uint id ): (s), close the connection specified by its index.
enum Accept( uint id ): (s), accept the connection request from a machine.
enum Reject( uint id ): (s), reject the connection request from a machine.
enum StartServer(): (c), create a new socket and begin to listen for incoming connection requests. Return the following enumerations: OC_SERVER_READY OC_SERVER_STARTED
enum StopServer(): (s), close the server socket and free all server's ressources. Return the following enumerations: OC_SERVER_STOPED
enum Send( void* data, uint len ): (c/s), send the data to the server
enum Send( void* data, uint len, uint cid ): (c/s), send the data to client specified by its index.
enum Receive( void* data, uint maxlen ): (c/s), read the data sent sent by the server.
enum Receive( uint sid, void* data, uint maxlen ): (c/s), read the data sent sent by the server specified by its index.
Networking protocol v 0.0.4
The hosts talk together by sending information packages. Those information packages have the following format:
| Command | Command's length | Data's length | Source IP | Dest IP | Reserved | Data |
| 16 chars | 4-bytes int | 4-bytes int | 6 bytes | 6 bytes | 28 bytes | 512 bytes |
The maximum size of the header is 36 + 28 = 64 bytes. The header contains from left to right: the command in capitalized characters, the command's length in integer (greater than 0), the data's length in integer (greater or equal to 0), the source and destination addresses in SDL_net's IPadress type. Like any professional protocol, there's also a reserved space in the message's header for future use. The data part should not be greater than 512 bytes in length in the current protocol version (v 0.0.3).
The commands are described below.
CNT
The program sends this command to an OpenCity server when it wants to establish a connection. The data's part should contain a 4 bytes integer which indicates which version of the protocol the program can understand. The following formula must be used to translate a protocol's version in a string format into an integer format:
string version: a.b.c integer version: a*65536 + b*256 + c
Depending on the client's status, the server can respond with the ACK or NCK commands. The server uses ACK for an affirmative answer, and NCK otherwise. An optional reason can be sent back to the host in the data part of the ACK or NCK command.
DNT
A host sends this command to an OpenCity server when it wants to notify its willing to disconnect from the server. The host should wait for a ACK command from the server before going to disconnect completely. The time-out for this command should not be longer than 2000ms. Even if the server doesn't answer within that period, the host can disconnect and shut down. It's recommended that in such case, the host should display a warning message to the user.
ACK
This command is used by a host (client or server) to reply in an affirmative way. In English, it means: “yes”. The ACK command can contain an optional information in its data part.
NCK
This is the opposite of the ACK command. NCK is used to answer in a negative way. In English, it means: “no”. Like the ACK command, the NCK command can contain an optional information in its data part.
NFO
This command is used to obtain descriptive information about a net node (client or server). The machine which processes this command should answer with an ACK command and uses the ACK command data field to return the requested information.
MAP
When a node wants to retrieve the map data from another node, it issues this command. The node which processes this command uses the ACK or the NACK command to reply. In case of an affirmative answer ACK, the data field contains the size in bytes of the map that will be sent back to the node which requests for it. The map data will be sent in multiple DAT messages. When the whole map data has been received successfully, the request node will notify the answer node by sending an ACK command with the map size in byte in the ACK command's data field.
PIN and PON
If there's no activity between a client and a server for more than 15s, the server should send the PIN command to the client. If the client is still active, it must answer with a PON command within 2000ms, otherwise, the server will disconnect it without any further notification. The PIN and PON commands can also contain optional information in its body (data) part.
MSG
From time to time, a client want to talk with another via the server. It can use this command with the destination address in the header. If there's no address specified in the header (0.0.0.0), the message will be sent to call connected clients known by the server. In order to prevent an abuse use of this command, the data's length is limited to 128 bytes. A client can not send more than 1 broadcast message per second otherwise it will be disconnected without any warning from the server.
DAT
The DAT command is used to send subsequent data packets from one node to another.
Glossary
- Node: a node designate either an OpenCity server or an OpenCity client
- ZeN: sometimes, the term "ZeN" is used instead of OpenCity server.
References
