.. index:: pair: class; EE::Network::UdpSocket .. _doxid-class_e_e_1_1_network_1_1_udp_socket: class EE::Network::UdpSocket ============================ .. toctree:: :hidden: Overview ~~~~~~~~ Specialized socket using the UDP protocol. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class UdpSocket: public :ref:`EE::Network::Socket` { public: // enums enum { :ref:`MaxDatagramSize` = 65507, }; // methods static UdpSocket* :target:`New`(); unsigned short :ref:`getLocalPort`() const; :ref:`Status` :ref:`bind`(unsigned short port, const :ref:`IpAddress`& address = :ref:`IpAddress::Any`); void :ref:`unbind`(); :ref:`Status` :ref:`send`(const void* data, std::size_t size, const :ref:`IpAddress`& remoteAddress, unsigned short remotePort); :ref:`Status` :ref:`receive`(void* data, std::size_t size, std::size_t& received, :ref:`IpAddress`& remoteAddress, unsigned short& remotePort); :ref:`Status` :ref:`send`(:ref:`Packet`& packet, const :ref:`IpAddress`& remoteAddress, unsigned short remotePort); :ref:`Status` :ref:`receive`(:ref:`Packet`& packet, :ref:`IpAddress`& remoteAddress, unsigned short& remotePort); void :ref:`setSendTimeout`(:ref:`SocketHandle` sock, const :ref:`Time`& timeout); void :ref:`setReceiveTimeout`(:ref:`SocketHandle` sock, const :ref:`Time`& timeout); }; Inherited Members ----------------- .. ref-code-block:: cpp :class: doxyrest-overview-inherited-code-block public: // enums enum { :ref:`AnyPort` = 0, }; enum :ref:`Status`; // methods void :ref:`setBlocking`(bool blocking); bool :ref:`isBlocking`() const; .. _details-class_e_e_1_1_network_1_1_udp_socket: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Specialized socket using the UDP protocol. A UDP socket is a connectionless socket. Instead of connecting once to a remote host, like TCP sockets, it can send to and receive from any host at any time. It is a datagram protocol: bounded blocks of data (datagrams) are transfered over the network rather than a continuous stream of data (TCP). Therefore, one call to send will always match one call to receive (if the datagram is not lost), with the same data that was sent. The UDP protocol is lightweight but unreliable. Unreliable means that datagrams may be duplicated, be lost or arrive reordered. However, if a datagram arrives, its data is guaranteed to be valid. UDP is generally used for real-time communication (audio or video streaming, real-time games, etc.) where speed is crucial and lost data doesn't matter much. Sending and receiving data can use either the low-level or the high-level functions. The low-level functions process a raw sequence of bytes, whereas the high-level interface uses packets (see :ref:`Packet `), which are easier to use and provide more safety regarding the data that is exchanged. You can look at the :ref:`Packet ` class to get more details about how they work. It is important to note that :ref:`UdpSocket ` is unable to send datagrams bigger than MaxDatagramSize. In this case, it returns an error and doesn't send anything. This applies to both raw data and packets. Indeed, even packets are unable to split and recompose data, due to the unreliability of the protocol (dropped, mixed or duplicated datagrams may lead to a big mess when trying to recompose a packet). If the socket is bound to a port, it is automatically unbound from it when the socket is destroyed. However, you can unbind the socket explicitely with the Unbind function if necessary, to stop receiving messages or make the port available for other sockets. Usage example: .. ref-code-block:: cpp // ----- The client ----- // Create a socket and bind it to the port 55001 UdpSocket socket; socket.bind(55001); // Send a message to 192.168.1.50 on port 55002 std::string message = "Hi, I am " + IpAddress::getLocalAddress().toString(); socket.Send(message.c_str(), message.size() + 1, "192.168.1.50", 55002); // Receive an answer (most likely from 192.168.1.50, but could be anyone else) char buffer[1024]; std::size_t received = 0; IpAddress sender; unsigned short port; socket.receive(buffer, sizeof(buffer), received, sender, port); std::cout << sender.toString() << " said: " << buffer << std::endl; // ----- The server ----- // Create a socket and bind it to the port 55002 UdpSocket socket; socket.bind(55002); // Receive a message from anyone char buffer[1024]; std::size_t received = 0; IpAddress sender; unsigned short port; socket.receive(buffer, sizeof(buffer), received, sender, port); std::cout << sender.toString() << " said: " << buffer << std::endl; // Send an answer std::string message = "Welcome " + sender.toString(); socket.send(message.c_str(), message.size() + 1, sender, port); .. rubric:: See also: :ref:`EE::Network::Socket `, :ref:`EE::Network::TcpSocket `, :ref:`EE::Network::Packet ` Enum Values ----------- .. index:: pair: enumvalue; MaxDatagramSize .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1ac4582effd475562ec3d6018ca967daf8a2a4e7dd271823b5282c0aa4da0590995: .. ref-code-block:: cpp :class: doxyrest-title-code-block MaxDatagramSize The maximum number of bytes that can be sent in a single UDP datagram. Methods ------- .. index:: pair: function; getLocalPort .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a5af9343b8e97ff466047c2ab5a8142e8: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned short getLocalPort() const Get the port to which the socket is bound locally If the socket is not bound to a port, this function returns 0. .. rubric:: Returns: Port to which the socket is bound .. rubric:: See also: Bind .. index:: pair: function; bind .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a2f74b17a10f4505a2a8447080f312aa7: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` bind(unsigned short port, const :ref:`IpAddress`& address = :ref:`IpAddress::Any`) Bind the socket to a specific port Binding the socket to a port is necessary for being able to receive data on that port. You can use the special value :ref:`Socket::AnyPort ` to tell the system to automatically pick an available port, and then call GetLocalPort to retrieve the chosen port. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - port - Port to Bind the socket to * - address - Address of the interface to bind to .. rubric:: Returns: Status code .. rubric:: See also: Unbind, GetLocalPort .. index:: pair: function; unbind .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a36c366707503eaca5c1ca0178c9be7fb: .. ref-code-block:: cpp :class: doxyrest-title-code-block void unbind() Unbind the socket from the local port to which it is bound The port that the socket was previously using is immediately available after this function is called. If the socket is not bound to a port, this function has no effect. .. rubric:: See also: Bind .. index:: pair: function; send .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a402f5e136fce363d93590528497136b0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` send(const void* data, std::size_t size, const :ref:`IpAddress`& remoteAddress, unsigned short remotePort) Send raw data to a remote peer Make sure that *size* is not greater than :ref:`UdpSocket::MaxDatagramSize `, otherwise this function will fail and no data will be sent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - data - Pointer to the sequence of bytes to send * - size - Number of bytes to send * - remoteAddress - Address of the receiver * - remotePort - Port of the receiver to send the data to .. rubric:: Returns: Status code .. rubric:: See also: Receive .. index:: pair: function; receive .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a1afb6165b0e1a925a4b98a154025bc0a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` receive(void* data, std::size_t size, std::size_t& received, :ref:`IpAddress`& remoteAddress, unsigned short& remotePort) Receive raw data from a remote peer In blocking mode, this function will wait until some bytes are actually received. Be careful to use a buffer which is large enough for the data that you intend to receive, if it is too small then an error will be returned and *all* the data will be lost. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - data - Pointer to the array to fill with the received bytes * - size - Maximum number of bytes that can be received * - received - This variable is filled with the actual number of bytes received * - remoteAddress - Address of the peer that sent the data * - remotePort - Port of the peer that sent the data .. rubric:: Returns: Status code .. rubric:: See also: Send .. index:: pair: function; send .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a991e80dfa7d67e811448875fd55aa96a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` send(:ref:`Packet`& packet, const :ref:`IpAddress`& remoteAddress, unsigned short remotePort) Send a formatted packet of data to a remote peer Make sure that the packet size is not greater than :ref:`UdpSocket::MaxDatagramSize `, otherwise this function will fail and no data will be sent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - packet - :ref:`Packet ` to send * - remoteAddress - Address of the receiver * - remotePort - Port of the receiver to send the data to .. rubric:: Returns: Status code .. rubric:: See also: Receive .. index:: pair: function; receive .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a8540c2f60502394b5cacc24c2aae930b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` receive(:ref:`Packet`& packet, :ref:`IpAddress`& remoteAddress, unsigned short& remotePort) Receive a formatted packet of data from a remote peer In blocking mode, this function will wait until the whole packet has been received. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - packet - :ref:`Packet ` to fill with the received data * - remoteAddress - Address of the peer that sent the data * - remotePort - Port of the peer that sent the data .. rubric:: Returns: Status code .. rubric:: See also: Send .. index:: pair: function; setSendTimeout .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1ae9dfc1d3af6017788a468537a50f2bb0: .. ref-code-block:: cpp :class: doxyrest-title-code-block void setSendTimeout(:ref:`SocketHandle` sock, const :ref:`Time`& timeout) Set the send timeout. Only callable after bind ( after the socket has been initialized ). .. index:: pair: function; setReceiveTimeout .. _doxid-class_e_e_1_1_network_1_1_udp_socket_1a340f4168dffc63b71ec9759e8962bec3: .. ref-code-block:: cpp :class: doxyrest-title-code-block void setReceiveTimeout(:ref:`SocketHandle` sock, const :ref:`Time`& timeout) Set the receive timeout Only callable after bind ( after the socket has been initialized ).