Packet Types and Formats

Packet Formats

Header and Type (all packets)

The data portion of each packet begins with a 4-byte header followed by a byte which identifies the packet type.

Therefore, each packet begins with the following two fields:

The possible values for the packet type byte are as follows:

Content Length (most packets)

With the exception of heartbeats, all packets include a 2-byte short integer field which indicates the content length. This is the number of bytes remaining in the packet. Since many socket implementations handle TCP data as a continuous stream, it's often necessary to know how many bytes are remaining when attempting to read data from the socket. The value of this field must be positive, and no larger than 1024.

Note: In this protocol, the content length does not include the header, packet type, or content length itself.

Identity String

The identity string is the first thing the server sends to the client after a connection is initiated. Currently, this packet can be safely ignored by clients. The main purpose of the identity string is to identify the listener if someone were to telnet to its port, for example. After the identity string is sent to the client, the server expects to receive a valid connection request. If a packet is not received from the client within 2 seconds, or if the next packet is not a valid connection request, then the server will close the socket.

The format of the identity packet is as follows:

Connection Request

The connection request is a TCP packet sent from the client to the server. The format of the connection request is as follows:

Notes:

• The password field must be present, even if no password is specified. If no password is specified, then the password field will just be an uppercase P followed by a space. The password in the packet is ignored if the server does not require a password for client connections.

• The game server IP can be either an IPv4 or IPv6 address. If this field does not contain a valid IPv4 or IPv6 address, the server will return an error and close the connection.

• The game server port field must be a valid port number in the range {1..65535}. If this field does not contain a valid port number, the server will return an error and close the connection.

Sample packet data:

ff ff ff ff 02 19 00 50 20 61 62 63 64 31 32 33 .......P abcd123

34 00 31 2e 32 2e 33 2e 34 00 32 37 30 31 35 00 4.1.2.3.4.27015.

In the above example, the client is sending the following information to the server:

• Password: abcd1234

• Game server IP: 1.2.3.4

• Game server port: 27015

Connection Response

The connection response is a TCP packet sent from the server to the client. The format of the connection response is as follows:

If the connection succeeds, then the packet type will be 0x04 and the response string will be OK (uppercase). If the connection request is rejected for some reason, then the packet type will be 0x03 and the response string will be an uppercase E followed by a space and a short error message. The error message for a rejected connection will be one of the following:

Notes:

• • If auto-bans are enabled on the server, each of the first six errors in the table above will cause the client IP's "bad attempts" counter to be incremented, and may result in the client IP being banned.

  • A connection which is rejected with a Too many connections error is not considered a bad connection attempt by the server.

  • The server's limit for simultaneous client connections can be changed by setting the maxClients option in the Chat Relay properties file (see Using the Chat Relay). Adjusting the maxClients and/or clientCheckInterval options may reduce the chances of the client receiving a Too many connections error.

Sample packet data (successful connection):

ff ff ff ff 04 02 00 4f 4b 00 .......OK.

Sample packet data (bad password rejection):

ff ff ff ff 03 0e 00 45 20 42 61 64 20 70 61 73 .......E Bad pas

73 77 6f 72 64 00 sword.

Chat Message

Each chat message is sent in a TCP packet from the client to the server. The format of the chat message is as follows:

Sample packet data:

ff ff ff ff 05 4f 00 01 10 42 81 52 00 31 32 37 .....O...B.R.127

2e 30 2e 30 2e 31 00 32 33 34 35 00 20 31 31 2f .0.0.1.2345. 11/

31 31 2f 32 30 31 33 20 2d 20 31 35 3a 34 35 3a 11/2013 - 15:45:

30 30 00 53 6f 6d 65 50 6c 61 79 65 72 00 53 75 00.SomePlayer.Su

72 76 69 76 6f 72 00 54 68 69 73 20 69 73 20 61 rvivor.This is a

20 74 65 73 74 21 00 test!.

In the above example, the field values are as follows:

• • Content Length: 79

  • Protocol Version: 1

  • Server Timestamp: 1384202768

  • say_team: 0

  • From IP: 127.0.0.1

  • From Port: 2345

  • Message Timestamp: 11/11/2013 - 15:45:00

  • Player Name: SomePlayer

  • Player Team: Survivor

  • Message: This is a test!

Heartbeat

The heartbeat allows the server to know which clients are still connected. The format of the heartbeat is as follows:

The Chat Relay server will send a heartbeat packet to each client at a fixed interval. The heartbeat interval is specified in the server's configuration. There is no specific response format expected from the client; any response from the client will keep the connection alive. In the simplest implementation, the client program can ignore the heartbeat packet and the automatic TCP ACK packet will be the client's response. If no response is received, then the client is dropped from the server and the client's connection slot on the server is freed.

Note: This is the only packet type which does not include the content length field.

Sample packet data:

ff ff ff ff 01 .....

Control Packets

As of version 1.3.0, the CheckValve Chat Relay implements a control listener which accepts control requests from the Chat Relay Control program (chatrelayctl.jar) on the loopback address. Control requests can be used to start, stop, or get status information from the Chat Relay.

All control packets use a common format:

The possible values for the request type byte are as follows: