.. index:: pair: class; EE::Network::Packet .. _doxid-class_e_e_1_1_network_1_1_packet: class EE::Network::Packet ========================= .. toctree:: :hidden: Overview ~~~~~~~~ Utility class to build blocks of data to transfer over the network. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class Packet { public: // construction virtual :ref:`~Packet`(); // methods void :ref:`append`(const void* data, std::size_t sizeInBytes); void :ref:`clear`(); const void* :ref:`getData`() const; std::size_t :ref:`getDataSize`() const; bool :ref:`endOfPacket`() const; :ref:`operator BoolType`() const; Packet& :ref:`operator>>`(bool& data); Packet& :target:`operator>>`(:ref:`Int8`& data); Packet& :target:`operator>>`(:ref:`Uint8`& data); Packet& :target:`operator>>`(:ref:`Int16`& data); Packet& :target:`operator>>`(:ref:`Uint16`& data); Packet& :target:`operator>>`(:ref:`Int32`& data); Packet& :target:`operator>>`(:ref:`Uint32`& data); Packet& :target:`operator>>`(float& data); Packet& :target:`operator>>`(double& data); Packet& :target:`operator>>`(char* data); Packet& :target:`operator>>`(std::string& data); Packet& :target:`operator>>`(wchar_t* data); Packet& :target:`operator>>`(std::wstring& data); Packet& :target:`operator>>`(:ref:`String`& data); Packet& :ref:`operator<<`(bool data); Packet& :target:`operator<<`(:ref:`Int8` data); Packet& :target:`operator<<`(:ref:`Uint8` data); Packet& :target:`operator<<`(:ref:`Int16` data); Packet& :target:`operator<<`(:ref:`Uint16` data); Packet& :target:`operator<<`(:ref:`Int32` data); Packet& :target:`operator<<`(:ref:`Uint32` data); Packet& :target:`operator<<`(float data); Packet& :target:`operator<<`(double data); Packet& :target:`operator<<`(const char* data); Packet& :target:`operator<<`(const std::string& data); Packet& :target:`operator<<`(const wchar_t* data); Packet& :target:`operator<<`(const std::wstring& data); Packet& :target:`operator<<`(const :ref:`String`& data); }; .. _details-class_e_e_1_1_network_1_1_packet: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Utility class to build blocks of data to transfer over the network. Packets provide a safe and easy way to serialize data, in order to send it over the network using sockets (:ref:`TcpSocket `, :ref:`UdpSocket `). Packets solve 2 fundamental problems that arise when transfering data over the network: * data is interpreted correctly according to the endianness * the bounds of the packet are preserved (one send == one receive) The :ref:`Packet ` class provides both input and output modes. It is designed to follow the behaviour of standard C++ streams, using operators >> and << to extract and insert data. It is recommended to use only fixed-size types (like Int32, etc.), to avoid possible differences between the sender and the receiver. Indeed, the native C++ types may have different sizes on two platforms and your data may be corrupted if that happens. Usage example: .. ref-code-block:: cpp Uint32 x = 24; std::string s = "hello"; double d = 5.89; // Group the variables to send into a packet Packet packet; packet << x << s << d; // Send it over the network (socket is a valid TcpSocket) socket.send(packet); ----------------------------------------------------------------- // Receive the packet at the other end Packet packet; socket.receive(packet); // Extract the variables contained in the packet Uint32 x; std::string s; double d; if (packet >> x >> s >> d) { // Data extracted successfully... } Packets have built-in operator >> and << overloads for standard types: * bool * fixed-size integer types (Int8/16/32, Uint8/16/32) * floating point numbers (float, double) * string types (char\*, wchar_t\*, std::string, std::wstring, :ref:`String `) Like standard streams, it is also possible to define your own overloads of operators >> and << in order to handle your custom types. .. ref-code-block:: cpp struct MyStruct { float number; Int8 integer; std::string str; }; Packet& operator <<(Packet& packet, const MyStruct& m) { return packet << m.number << m.integer << m.str; } Packet& operator >>(Packet& packet, MyStruct& m) { return packet >> m.number >> m.integer >> m.str; } Packets also provide an extra feature that allows to apply custom transformations to the data before it is sent, and after it is received. This is typically used to handle automatic compression or encryption of the data. This is achieved by inheriting from :ref:`Packet `, and overriding the onSend and onReceive functions. Here is an example: .. ref-code-block:: cpp class ZipPacket : public Packet { virtual const void* onSend(std::size_t& size) { const void* srcData = getData(); std::size_t srcSize = getDataSize(); return MySuperZipFunction(srcData, srcSize, &size); } virtual void onReceive(const void* data, std::size_t size) { std::size_t dstSize; const void* dstData = MySuperUnzipFunction(data, size, &dstSize); append(dstData, dstSize); } }; // Use like regular packets: ZipPacket packet; packet << x << s << d; ... .. rubric:: See also: :ref:`EE::Network::TcpSocket `, :ref:`EE::Network::UdpSocket ` Construction ------------ .. _doxid-class_e_e_1_1_network_1_1_packet_1ac28e884558cab817a0f4c5bf054a9e4d: .. ref-code-block:: cpp :class: doxyrest-title-code-block virtual ~Packet() Virtual destructor. Methods ------- .. index:: pair: function; append .. _doxid-class_e_e_1_1_network_1_1_packet_1a95e4114b3a954e71b6ca0b7e73a66dce: .. ref-code-block:: cpp :class: doxyrest-title-code-block void append(const void* data, std::size_t sizeInBytes) Append data to the end of the packet. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - data - Pointer to the sequence of bytes to append * - sizeInBytes - Number of bytes to append .. rubric:: See also: Clear .. index:: pair: function; clear .. _doxid-class_e_e_1_1_network_1_1_packet_1a6841c695eb292bf0259f932d51275a91: .. ref-code-block:: cpp :class: doxyrest-title-code-block void clear() Clear the packet After calling Clear, the packet is empty. .. rubric:: See also: Append .. index:: pair: function; getData .. _doxid-class_e_e_1_1_network_1_1_packet_1a28db7d7f8187fdc3a726ee9150f9884f: .. ref-code-block:: cpp :class: doxyrest-title-code-block const void* getData() const Get a pointer to the data contained in the packet Warning: the returned pointer may become invalid after you append data to the packet, therefore it should never be stored. The return pointer is NULL if the packet is empty. .. rubric:: Returns: Pointer to the data .. rubric:: See also: GetDataSize .. index:: pair: function; getDataSize .. _doxid-class_e_e_1_1_network_1_1_packet_1ac9b1038c316b036257aad0e3d73904e5: .. ref-code-block:: cpp :class: doxyrest-title-code-block std::size_t getDataSize() const Get the size of the data contained in the packet This function returns the number of bytes pointed to by what GetData returns. .. rubric:: Returns: Data size, in bytes .. rubric:: See also: GetData .. index:: pair: function; endOfPacket .. _doxid-class_e_e_1_1_network_1_1_packet_1a9127c42e3d91b3e45f3fbed6ef10f7ac: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool endOfPacket() const Tell if the reading position has reached the / end of the packet This function is useful to know if there is some data left to be read, without actually reading it. .. rubric:: Returns: True if all data was read, false otherwise .. rubric:: See also: operator bool .. index:: pair: function; operator BoolType .. _doxid-class_e_e_1_1_network_1_1_packet_1a42e222480af509e37a095b84668180ca: .. ref-code-block:: cpp :class: doxyrest-title-code-block operator BoolType() const Test the validity of the packet, for reading This operator allows to test the packet as a boolean variable, to check if a reading operation was successful. A packet will be in an invalid state if it has no more data to read. This behaviour is the same as standard C++ streams. Usage example: .. ref-code-block:: cpp float x; packet >> x; if (packet) { /// // ok, x was extracted successfully } /// // -- or -- /// float x; if (packet >> x) { /// // ok, x was extracted successfully } / Don't focus on the return type, it's equivalent to bool but it disallows unwanted implicit conversions to integer or pointer types. / .. rubric:: Returns: True if last data extraction from packet was successful / .. rubric:: See also: EndOfPacket .. index:: pair: function; operator>> .. _doxid-class_e_e_1_1_network_1_1_packet_1ae256c6aa653013309f2b34056df365f2: .. ref-code-block:: cpp :class: doxyrest-title-code-block Packet& operator>>(bool& data) Overloads of operator >> to read data from the packet .. index:: pair: function; operator<< .. _doxid-class_e_e_1_1_network_1_1_packet_1a73d202b1342f36c3220640b50a32cd64: .. ref-code-block:: cpp :class: doxyrest-title-code-block Packet& operator<<(bool data) Overloads of operator << to write data into the packet