OpenTTD Source: Packet Struct Reference

OpenTTD Source 14.0-beta3

Public Member Functions | Private Attributes
Packet Struct Reference

Internal entity of a packet. More...

`#include <packet.h>`

## Public Member Functions
| Packet (NetworkSocketHandler *cs, size_t limit, size_t initial_read_size=sizeof(PacketSize))
| Create a packet that is used to read from a network socket. More...
| Packet (PacketType type, size_t limit=COMPAT_MTU)
| Creates a packet to send. More...
void | PrepareToSend ()
| Writes the packet size from the raw packet from packet->size.
bool | CanWriteToPacket (size_t bytes_to_write)
| Is it safe to write to the packet, i.e. More...
void | Send_bool (bool data)
| Package a boolean in the packet. More...
void | Send_uint8 (uint8_t data)
| Package a 8 bits integer in the packet. More...
void | Send_uint16 (uint16_t data)
| Package a 16 bits integer in the packet. More...
void | Send_uint32 (uint32_t data)
| Package a 32 bits integer in the packet. More...
void | Send_uint64 (uint64_t data)
| Package a 64 bits integer in the packet. More...
void | Send_string (const std::string_view data)
| Sends a string over the network. More...
void | Send_buffer (const std::vector< byte > &data)
| Copy a sized byte buffer into the packet. More...
size_t | Send_bytes (const byte *begin, const byte *end)
| Send as many of the bytes as possible in the packet. More...
bool | HasPacketSizeData () const
| Check whether the packet, given the position of the "write" pointer, has read enough of the packet to contain its size. More...
bool | ParsePacketSize ()
| Reads the packet size from the raw packet and stores it in the packet->size. More...
size_t | Size () const
| Get the number of bytes in the packet. More...
void | PrepareToRead ()
| Prepares the packet so it can be read.
PacketType | GetPacketType () const
| Get the `PacketType` from this packet. More...
bool | CanReadFromPacket (size_t bytes_to_read, bool close_connection=false)
| Is it safe to read from the packet, i.e. More...
bool | Recv_bool ()
| Read a boolean from the packet. More...
uint8_t | Recv_uint8 ()
| Read a 8 bits integer from the packet. More...
uint16_t | Recv_uint16 ()
| Read a 16 bits integer from the packet. More...
uint32_t | Recv_uint32 ()
| Read a 32 bits integer from the packet. More...
uint64_t | Recv_uint64 ()
| Read a 64 bits integer from the packet. More...
std::vector< byte > | Recv_buffer ()
| Extract a sized byte buffer from the packet. More...
std::string | Recv_string (size_t length, StringValidationSettings settings=SVS_REPLACE_WITH_QUESTION_MARK)
| Reads characters (bytes) from the packet until it finds a '\0', or reaches a maximum of `length` characters. More...
size_t | RemainingBytesToTransfer () const
| Get the amount of bytes that are still available for the Transfer functions. More...
template<typename A = size_t, typename F , typename D , typename ... Args>
ssize_t | TransferOutWithLimit (F transfer_function, size_t limit, D destination, Args &&... args)
| Transfer data from the packet to the given function. More...
template<typename A = size_t, typename F , typename D , typename ... Args>
ssize_t | TransferOut (F transfer_function, D destination, Args &&... args)
| Transfer data from the packet to the given function. More...
template<typename A = size_t, typename F , typename S , typename ... Args>
ssize_t | TransferIn (F transfer_function, S source, Args &&... args)
| Transfer data from the given function into the packet. More...

## Private Attributes
PacketSize | pos
| The current read/write position in the packet.
std::vector< byte > | buffer
| The buffer of this packet.
size_t | limit
| The limit for the packet size.
NetworkSocketHandler * | cs
| Socket we're associated with.

## Detailed Description

Internal entity of a packet.

As everything is sent as a packet, all network communication will need to call the functions that populate the packet. Every packet can be at most a limited number bytes set in the constructor. Overflowing this limit will give an assertion when sending (i.e. writing) the packet. Reading past the size of the packet when receiving will return all 0 values and "" in case of the string.

— Points of attention —

- all > 1 byte integral values are written in little endian, unless specified otherwise. Thus, 0x01234567 would be sent as {0x67, 0x45, 0x23, 0x01}.
- all sent strings are of variable length and terminated by a '\0'. Thus, the length of the strings is not sent.
- years that are leap years in the 'days since X' to 'date' calculations: (year % 4 == 0) and ((year % 100 != 0) or (year % 400 == 0))

Definition at line 42 of file packet.h.

## Constructor & Destructor Documentation

## ◆ Packet() [1/2]

Packet::Packet | ( | NetworkSocketHandler * | cs,
|  | size_t | limit,
|  | size_t | initial_read_size = `sizeof(PacketSize)`
| ) |  |

Create a packet that is used to read from a network socket.

Parameters

  cs | The socket handler associated with the socket we are reading from.
  limit | The maximum size of packets to accept.
  initial_read_size | The initial amount of data to transfer from the socket into the packet. This defaults to just the required bytes to determine the packet's size. That default is the wanted for streams such as TCP as you do not want to read data of the next packet yet. For UDP you need to read the whole packet at once otherwise you might loose some the data of the packet, so there you pass the maximum size for the packet you expect from the network.

Definition at line 31 of file packet.cpp.

References buffer, and cs.

## ◆ Packet() [2/2]

Packet::Packet | ( | PacketType | type,
|  | size_t | limit = `COMPAT_MTU`
| ) |  |

Creates a packet to send.

Parameters

  type | The type of the packet to send
  limit | The maximum number of bytes the packet may have. Default is COMPAT_MTU. Be careful of compatibility with older clients/servers when changing the limit as it might break things if the other side is not expecting much larger packets than what they support.

Definition at line 47 of file packet.cpp.

References Send_uint16(), and Send_uint8().

## Member Function Documentation

## ◆ CanReadFromPacket()

bool Packet::CanReadFromPacket | ( | size_t | bytes_to_read,
|  | bool | close_connection = `false`
| ) |  |

Is it safe to read from the packet, i.e.

didn't we run over the buffer? In case `close_connection` is true, the connection will be closed when one would overrun the buffer. When it is false, the connection remains untouched.

Parameters

  bytes_to_read | The amount of bytes we want to try to read.
  close_connection | Whether to close the connection if one cannot read that amount.

Returns
  True if that is safe, otherwise false.

Definition at line 204 of file packet.cpp.

References cs, NetworkSocketHandler::HasClientQuit(), pos, and Size().

Referenced by ClientNetworkGameSocketHandler::Receive_SERVER_FRAME(), Recv_uint32(), Recv_uint64(), and Recv_uint8().

## ◆ CanWriteToPacket()

bool Packet::CanWriteToPacket | ( | size_t | bytes_to_write | ) |

Is it safe to write to the packet, i.e.

didn't we run over the buffer?

Parameters

  bytes_to_write | The amount of bytes we want to try to write.

Returns
  True iff the given amount of bytes can be written to the packet.

Definition at line 74 of file packet.cpp.

References limit, and Size().

Referenced by Send_buffer(), Send_string(), Send_uint32(), Send_uint64(), and Send_uint8().

## ◆ GetPacketType()

PacketType Packet::GetPacketType | ( |  | ) | const

Get the `PacketType` from this packet.

Returns
  The packet type.

Definition at line 273 of file packet.cpp.

References buffer, and Size().

## ◆ HasPacketSizeData()

bool Packet::HasPacketSizeData | ( |  | ) | const

Check whether the packet, given the position of the "write" pointer, has read enough of the packet to contain its size.

Returns
  True iff there is enough data in the packet to contain the packet's size.

Definition at line 223 of file packet.cpp.

References pos.

Referenced by NetworkTCPSocketHandler::ReceivePacket().

## ◆ ParsePacketSize()

bool Packet::ParsePacketSize | ( |  | ) |

Reads the packet size from the raw packet and stores it in the packet->size.

Returns
  True iff the packet size seems plausible.

Definition at line 244 of file packet.cpp.

References buffer, cs, limit, and pos.

Referenced by NetworkTCPSocketHandler::ReceivePacket(), and NetworkUDPSocketHandler::ReceivePackets().

## ◆ Recv_bool()

bool Packet::Recv_bool | ( |  | ) |

Read a boolean from the packet.

Returns
  The read data.

Definition at line 283 of file packet.cpp.

References Recv_uint8().

Referenced by ClientNetworkGameSocketHandler::Receive_SERVER_CHAT(), and ClientNetworkGameSocketHandler::Receive_SERVER_COMMAND().

## ◆ Recv_buffer()

std::vector< byte > Packet::Recv_buffer | ( |  | ) |

Extract a sized byte buffer from the packet.

Returns
  The extracted buffer.

Definition at line 359 of file packet.cpp.

## ◆ Recv_string()

std::string Packet::Recv_string | ( | size_t | length,
|  | StringValidationSettings | settings = `SVS_REPLACE_WITH_QUESTION_MARK`
| ) |  |

Reads characters (bytes) from the packet until it finds a '\0', or reaches a maximum of `length` characters.

When the '\0' has not been reached in the first `length` read characters, more characters are read from the packet until '\0' has been reached. However, these characters will not end up in the returned string. The length of the returned string will be at most `length` - 1 characters.

Parameters

  length | The maximum length of the string including '\0'.
  settings | The string validation settings.

Returns
  The validated string.

Definition at line 383 of file packet.cpp.

References Recv_uint8(), settings, and StrMakeValid().

Referenced by ClientNetworkCoordinatorSocketHandler::Receive_GC_CONNECT_FAILED(), ClientNetworkCoordinatorSocketHandler::Receive_GC_CONNECTING(), ClientNetworkCoordinatorSocketHandler::Receive_GC_DIRECT_CONNECT(), ClientNetworkCoordinatorSocketHandler::Receive_GC_ERROR(), ClientNetworkCoordinatorSocketHandler::Receive_GC_LISTING(), ClientNetworkCoordinatorSocketHandler::Receive_GC_REGISTER_ACK(), ClientNetworkCoordinatorSocketHandler::Receive_GC_STUN_CONNECT(), ClientNetworkCoordinatorSocketHandler::Receive_GC_STUN_REQUEST(), ClientNetworkCoordinatorSocketHandler::Receive_GC_TURN_CONNECT(), ClientNetworkGameSocketHandler::Receive_SERVER_CHAT(), ClientNetworkGameSocketHandler::Receive_SERVER_CONFIG_UPDATE(), ClientNetworkContentSocketHandler::Receive_SERVER_CONTENT(), ClientNetworkGameSocketHandler::Receive_SERVER_EXTERNAL_CHAT(), ClientNetworkContentSocketHandler::Receive_SERVER_INFO(), ClientNetworkGameSocketHandler::Receive_SERVER_NEED_COMPANY_PASSWORD(), ClientNetworkGameSocketHandler::Receive_SERVER_RCON(), ClientNetworkGameSocketHandler::Receive_SERVER_WELCOME(), and ClientNetworkTurnSocketHandler::Receive_TURN_CONNECTED().

## ◆ Recv_uint16()

uint16_t Packet::Recv_uint16 | ( |  | ) |

Read a 16 bits integer from the packet.

Returns
  The read data.

Definition at line 306 of file packet.cpp.

Referenced by ClientNetworkCoordinatorSocketHandler::Receive_GC_LISTING(), ClientNetworkGameSocketHandler::Receive_SERVER_EXTERNAL_CHAT(), and ClientNetworkGameSocketHandler::Receive_SERVER_RCON().

## ◆ Recv_uint32()

uint32_t Packet::Recv_uint32 | ( |  | ) |

Read a 32 bits integer from the packet.

Returns
  The read data.

Definition at line 321 of file packet.cpp.

References buffer, CanReadFromPacket(), and pos.

Referenced by ClientNetworkCoordinatorSocketHandler::Receive_GC_NEWGRF_LOOKUP(), ClientNetworkGameSocketHandler::Receive_SERVER_CHAT(), ClientNetworkGameSocketHandler::Receive_SERVER_CLIENT_INFO(), ClientNetworkGameSocketHandler::Receive_SERVER_COMMAND(), ClientNetworkContentSocketHandler::Receive_SERVER_CONTENT(), ClientNetworkGameSocketHandler::Receive_SERVER_ERROR_QUIT(), ClientNetworkGameSocketHandler::Receive_SERVER_FRAME(), ClientNetworkContentSocketHandler::Receive_SERVER_INFO(), ClientNetworkGameSocketHandler::Receive_SERVER_JOIN(), ClientNetworkGameSocketHandler::Receive_SERVER_MAP_BEGIN(), ClientNetworkGameSocketHandler::Receive_SERVER_MAP_SIZE(), ClientNetworkGameSocketHandler::Receive_SERVER_MOVE(), ClientNetworkGameSocketHandler::Receive_SERVER_NEED_COMPANY_PASSWORD(), ClientNetworkGameSocketHandler::Receive_SERVER_QUIT(), ClientNetworkGameSocketHandler::Receive_SERVER_SYNC(), and ClientNetworkGameSocketHandler::Receive_SERVER_WELCOME().

## ◆ Recv_uint64()

uint64_t Packet::Recv_uint64 | ( |  | ) |

Read a 64 bits integer from the packet.

Returns
  The read data.

Definition at line 338 of file packet.cpp.

References buffer, CanReadFromPacket(), and pos.

Referenced by ClientNetworkGameSocketHandler::Receive_SERVER_CHAT().

## ◆ Recv_uint8()

uint8_t Packet::Recv_uint8 | ( |  | ) |

Read a 8 bits integer from the packet.

Returns
  The read data.

Definition at line 292 of file packet.cpp.

References buffer, CanReadFromPacket(), and pos.

Referenced by NetworkTurnSocketHandler::HandlePacket(), NetworkContentSocketHandler::HandlePacket(), NetworkCoordinatorSocketHandler::HandlePacket(), NetworkAdminSocketHandler::HandlePacket(), NetworkGameSocketHandler::HandlePacket(), NetworkUDPSocketHandler::HandleUDPPacket(), ServerNetworkGameSocketHandler::Receive_CLIENT_ERROR(), ClientNetworkCoordinatorSocketHandler::Receive_GC_DIRECT_CONNECT(), ClientNetworkCoordinatorSocketHandler::Receive_GC_ERROR(), ClientNetworkCoordinatorSocketHandler::Receive_GC_REGISTER_ACK(), ClientNetworkCoordinatorSocketHandler::Receive_GC_STUN_CONNECT(), ClientNetworkCoordinatorSocketHandler::Receive_GC_TURN_CONNECT(), ClientNetworkGameSocketHandler::Receive_SERVER_CHAT(), ClientNetworkGameSocketHandler::Receive_SERVER_CHECK_NEWGRFS(), ClientNetworkGameSocketHandler::Receive_SERVER_CONFIG_UPDATE(), ClientNetworkContentSocketHandler::Receive_SERVER_CONTENT(), QueryNetworkGameSocketHandler::Receive_SERVER_ERROR(), ClientNetworkGameSocketHandler::Receive_SERVER_FRAME(), ClientNetworkContentSocketHandler::Receive_SERVER_INFO(), Recv_bool(), and Recv_string().

## ◆ RemainingBytesToTransfer()

size_t Packet::RemainingBytesToTransfer | ( |  | ) | const

Get the amount of bytes that are still available for the Transfer functions.

Returns
  The number of bytes that still have to be transfered.

Definition at line 405 of file packet.cpp.

References pos, and Size().

Referenced by PacketReader::AddPacket(), ClientNetworkContentSocketHandler::Receive_SERVER_CONTENT(), NetworkTCPSocketHandler::ReceivePacket(), and NetworkTCPSocketHandler::SendPackets().

## ◆ Send_bool()

void Packet::Send_bool | ( | bool | data | ) |

Package a boolean in the packet.

Parameters

  data | The data to send.

Definition at line 95 of file packet.cpp.

References Send_uint8().

## ◆ Send_buffer()

void Packet::Send_buffer | ( | const std::vector< byte > & | data | ) |

Copy a sized byte buffer into the packet.

Parameters

  data | The data to send.

Definition at line 167 of file packet.cpp.

References CanWriteToPacket().

Referenced by NetworkGameSocketHandler::SendCommand().

## ◆ Send_bytes()

size_t Packet::Send_bytes | ( | const byte * | begin,
|  | const byte * | end
| ) |  |

Send as many of the bytes as possible in the packet.

This can mean that it is possible that not all bytes are sent. To cope with this the function returns the amount of bytes that were actually sent.

Parameters

  begin | The begin of the buffer to send.
  end | The end of the buffer to send.

Returns
  The number of bytes that were added to this packet.

Definition at line 182 of file packet.cpp.

References buffer, limit, and Size().

## ◆ Send_string()

void Packet::Send_string | ( | const std::string_view | data | ) |

Sends a string over the network.

It sends out the string + '\0'. No size-byte or something.

Parameters

  data | The string to send

Definition at line 156 of file packet.cpp.

References buffer, and CanWriteToPacket().

## ◆ Send_uint16()

void Packet::Send_uint16 | ( | uint16_t | data | ) |

Package a 16 bits integer in the packet.

Parameters

  data | The data to send.

Definition at line 114 of file packet.cpp.

Referenced by Packet(), and NetworkGameSocketHandler::SendCommand().

## ◆ Send_uint32()

void Packet::Send_uint32 | ( | uint32_t | data | ) |

Package a 32 bits integer in the packet.

Parameters

  data | The data to send.

Definition at line 125 of file packet.cpp.

References buffer, CanWriteToPacket(), and GB().

## ◆ Send_uint64()

void Packet::Send_uint64 | ( | uint64_t | data | ) |

Package a 64 bits integer in the packet.

Parameters

  data | The data to send.

Definition at line 138 of file packet.cpp.

References buffer, CanWriteToPacket(), and GB().

## ◆ Send_uint8()

void Packet::Send_uint8 | ( | uint8_t | data | ) |

Package a 8 bits integer in the packet.

Parameters

  data | The data to send.

Definition at line 104 of file packet.cpp.

References buffer, and CanWriteToPacket().

Referenced by Packet(), Send_bool(), and NetworkGameSocketHandler::SendCommand().

## ◆ Size()

size_t Packet::Size | ( |  | ) | const

Get the number of bytes in the packet.

When sending a packet this is the size of the data up to that moment. When receiving a packet (before PrepareToRead) this is the allocated size for the data to be read. When reading a packet (after PrepareToRead) this is the full size of the packet.

Returns
  The packet's size.

Definition at line 235 of file packet.cpp.

References buffer.

Referenced by CanReadFromPacket(), CanWriteToPacket(), GetPacketType(), PrepareToSend(), NetworkUDPSocketHandler::ReceivePackets(), RemainingBytesToTransfer(), and Send_bytes().

## ◆ TransferIn()

template<typename A = size_t, typename F , typename S , typename ... Args>

ssize_t Packet::TransferIn | ( | F | transfer_function,
|  | S | source,
|  | Args &&... | args
| ) |  |
| inline

Transfer data from the given function into the packet.

It starts writing at the position the last transfer stopped.

Examples of functions that can be used to transfer data into a packet are TCP's recv and UDP's recvfrom functions. They will directly write their data into the packet without an intermediate buffer. Examples of functions that can be used to transfer data from a packet are TCP's send and UDP's sendto functions. They will directly read the data from the packet's buffer without an intermediate buffer. These are functions are special in a sense as even though the packet can send or receive an amount of data, those functions can say they only processed a smaller amount, so special handling is required to keep the position pointers correct. Most of these transfer functions are in the form function(source, buffer, amount, ...), so the template of this function will assume that as the base parameter order.

This will attempt to write all the remaining bytes into the packet. It updates the position based on how many bytes were actually written by the called transfer_function.

Parameters

  transfer_function | The function to pass the buffer as second parameter and the amount to read as third parameter. It returns the amount that was read or -1 upon errors.
  source | The first parameter of the transfer function.
  args | The fourth and further parameters to the transfer function, if any.

Template Parameters

  A | The type for the amount to be passed, so it can be cast to the right type.
  F | The type of the transfer_function.
  S | The type of the source.
  Args | The types of the remaining arguments to the function.

Returns
  The return value of the transfer_function.

Definition at line 171 of file packet.h.

Referenced by NetworkTCPSocketHandler::ReceivePacket(), and NetworkUDPSocketHandler::ReceivePackets().

## ◆ TransferOut()

template<typename A = size_t, typename F , typename D , typename ... Args>

ssize_t Packet::TransferOut | ( | F | transfer_function,
|  | D | destination,
|  | Args &&... | args
| ) |  |
| inline

Transfer data from the packet to the given function.

It starts reading at the position the last transfer stopped. See Packet::TransferIn for more information about transferring data to functions.

Parameters

  transfer_function | The function to pass the buffer as second parameter and the amount to write as third parameter. It returns the amount that was written or -1 upon errors.
  destination | The first parameter of the transfer function.
  args | The fourth and further parameters to the transfer function, if any.

Template Parameters

  A | The type for the amount to be passed, so it can be cast to the right type.
  F | The type of the transfer_function.
  D | The type of the destination.
  Args | The types of the remaining arguments to the function.

Returns
  The return value of the transfer_function.

Definition at line 136 of file packet.h.

Referenced by ClientNetworkContentSocketHandler::Receive_SERVER_CONTENT(), NetworkUDPSocketHandler::SendPacket(), and NetworkTCPSocketHandler::SendPackets().

## ◆ TransferOutWithLimit()

template<typename A = size_t, typename F , typename D , typename ... Args>

ssize_t Packet::TransferOutWithLimit | ( | F | transfer_function,
|  | size_t | limit,
|  | D | destination,
|  | Args &&... | args
| ) |  |
| inline

Transfer data from the packet to the given function.

It starts reading at the position the last transfer stopped. See Packet::TransferIn for more information about transferring data to functions.

Parameters

  transfer_function | The function to pass the buffer as second parameter and the amount to write as third parameter. It returns the amount that was written or -1 upon errors.
  limit | The maximum amount of bytes to transfer.
  destination | The first parameter of the transfer function.
  args | The fourth and further parameters to the transfer function, if any.

Returns
  The return value of the transfer_function. < The types of the remaining arguments to the function.

Definition at line 106 of file packet.h.

Referenced by PacketReader::AddPacket().

The documentation for this struct was generated from the following files:

- src/network/core/packet.h
- src/network/core/packet.cpp