EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-06-02 08:58:14
0001 //////////////////////////////////////////////////////////// 0002 // 0003 // SFML - Simple and Fast Multimedia Library 0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org) 0005 // 0006 // This software is provided 'as-is', without any express or implied warranty. 0007 // In no event will the authors be held liable for any damages arising from the use of this software. 0008 // 0009 // Permission is granted to anyone to use this software for any purpose, 0010 // including commercial applications, and to alter it and redistribute it freely, 0011 // subject to the following restrictions: 0012 // 0013 // 1. The origin of this software must not be misrepresented; 0014 // you must not claim that you wrote the original software. 0015 // If you use this software in a product, an acknowledgment 0016 // in the product documentation would be appreciated but is not required. 0017 // 0018 // 2. Altered source versions must be plainly marked as such, 0019 // and must not be misrepresented as being the original software. 0020 // 0021 // 3. This notice may not be removed or altered from any source distribution. 0022 // 0023 //////////////////////////////////////////////////////////// 0024 0025 #ifndef SFML_UDPSOCKET_HPP 0026 #define SFML_UDPSOCKET_HPP 0027 0028 //////////////////////////////////////////////////////////// 0029 // Headers 0030 //////////////////////////////////////////////////////////// 0031 #include <SFML/Network/Export.hpp> 0032 #include <SFML/Network/Socket.hpp> 0033 #include <SFML/Network/IpAddress.hpp> 0034 #include <vector> 0035 0036 0037 namespace sf 0038 { 0039 class Packet; 0040 0041 //////////////////////////////////////////////////////////// 0042 /// \brief Specialized socket using the UDP protocol 0043 /// 0044 //////////////////////////////////////////////////////////// 0045 class SFML_NETWORK_API UdpSocket : public Socket 0046 { 0047 public: 0048 0049 //////////////////////////////////////////////////////////// 0050 // Constants 0051 //////////////////////////////////////////////////////////// 0052 enum 0053 { 0054 MaxDatagramSize = 65507 //!< The maximum number of bytes that can be sent in a single UDP datagram 0055 }; 0056 0057 //////////////////////////////////////////////////////////// 0058 /// \brief Default constructor 0059 /// 0060 //////////////////////////////////////////////////////////// 0061 UdpSocket(); 0062 0063 //////////////////////////////////////////////////////////// 0064 /// \brief Get the port to which the socket is bound locally 0065 /// 0066 /// If the socket is not bound to a port, this function 0067 /// returns 0. 0068 /// 0069 /// \return Port to which the socket is bound 0070 /// 0071 /// \see bind 0072 /// 0073 //////////////////////////////////////////////////////////// 0074 unsigned short getLocalPort() const; 0075 0076 //////////////////////////////////////////////////////////// 0077 /// \brief Bind the socket to a specific port 0078 /// 0079 /// Binding the socket to a port is necessary for being 0080 /// able to receive data on that port. 0081 /// 0082 /// When providing sf::Socket::AnyPort as port, the listener 0083 /// will request an available port from the system. 0084 /// The chosen port can be retrieved by calling getLocalPort(). 0085 /// 0086 /// Since the socket can only be bound to a single port at 0087 /// any given moment, if it is already bound when this 0088 /// function is called, it will be unbound from the previous 0089 /// port before being bound to the new one. 0090 /// 0091 /// \param port Port to bind the socket to 0092 /// \param address Address of the interface to bind to 0093 /// 0094 /// \return Status code 0095 /// 0096 /// \see unbind, getLocalPort 0097 /// 0098 //////////////////////////////////////////////////////////// 0099 Status bind(unsigned short port, const IpAddress& address = IpAddress::Any); 0100 0101 //////////////////////////////////////////////////////////// 0102 /// \brief Unbind the socket from the local port to which it is bound 0103 /// 0104 /// The port that the socket was previously bound to is immediately 0105 /// made available to the operating system after this function is called. 0106 /// This means that a subsequent call to bind() will be able to re-bind 0107 /// the port if no other process has done so in the mean time. 0108 /// If the socket is not bound to a port, this function has no effect. 0109 /// 0110 /// \see bind 0111 /// 0112 //////////////////////////////////////////////////////////// 0113 void unbind(); 0114 0115 //////////////////////////////////////////////////////////// 0116 /// \brief Send raw data to a remote peer 0117 /// 0118 /// Make sure that \a size is not greater than 0119 /// UdpSocket::MaxDatagramSize, otherwise this function will 0120 /// fail and no data will be sent. 0121 /// 0122 /// \param data Pointer to the sequence of bytes to send 0123 /// \param size Number of bytes to send 0124 /// \param remoteAddress Address of the receiver 0125 /// \param remotePort Port of the receiver to send the data to 0126 /// 0127 /// \return Status code 0128 /// 0129 /// \see receive 0130 /// 0131 //////////////////////////////////////////////////////////// 0132 Status send(const void* data, std::size_t size, const IpAddress& remoteAddress, unsigned short remotePort); 0133 0134 //////////////////////////////////////////////////////////// 0135 /// \brief Receive raw data from a remote peer 0136 /// 0137 /// In blocking mode, this function will wait until some 0138 /// bytes are actually received. 0139 /// Be careful to use a buffer which is large enough for 0140 /// the data that you intend to receive, if it is too small 0141 /// then an error will be returned and *all* the data will 0142 /// be lost. 0143 /// 0144 /// \param data Pointer to the array to fill with the received bytes 0145 /// \param size Maximum number of bytes that can be received 0146 /// \param received This variable is filled with the actual number of bytes received 0147 /// \param remoteAddress Address of the peer that sent the data 0148 /// \param remotePort Port of the peer that sent the data 0149 /// 0150 /// \return Status code 0151 /// 0152 /// \see send 0153 /// 0154 //////////////////////////////////////////////////////////// 0155 Status receive(void* data, std::size_t size, std::size_t& received, IpAddress& remoteAddress, unsigned short& remotePort); 0156 0157 //////////////////////////////////////////////////////////// 0158 /// \brief Send a formatted packet of data to a remote peer 0159 /// 0160 /// Make sure that the packet size is not greater than 0161 /// UdpSocket::MaxDatagramSize, otherwise this function will 0162 /// fail and no data will be sent. 0163 /// 0164 /// \param packet Packet to send 0165 /// \param remoteAddress Address of the receiver 0166 /// \param remotePort Port of the receiver to send the data to 0167 /// 0168 /// \return Status code 0169 /// 0170 /// \see receive 0171 /// 0172 //////////////////////////////////////////////////////////// 0173 Status send(Packet& packet, const IpAddress& remoteAddress, unsigned short remotePort); 0174 0175 //////////////////////////////////////////////////////////// 0176 /// \brief Receive a formatted packet of data from a remote peer 0177 /// 0178 /// In blocking mode, this function will wait until the whole packet 0179 /// has been received. 0180 /// 0181 /// \param packet Packet to fill with the received data 0182 /// \param remoteAddress Address of the peer that sent the data 0183 /// \param remotePort Port of the peer that sent the data 0184 /// 0185 /// \return Status code 0186 /// 0187 /// \see send 0188 /// 0189 //////////////////////////////////////////////////////////// 0190 Status receive(Packet& packet, IpAddress& remoteAddress, unsigned short& remotePort); 0191 0192 private: 0193 0194 //////////////////////////////////////////////////////////// 0195 // Member data 0196 //////////////////////////////////////////////////////////// 0197 std::vector<char> m_buffer; //!< Temporary buffer holding the received data in Receive(Packet) 0198 }; 0199 0200 } // namespace sf 0201 0202 0203 #endif // SFML_UDPSOCKET_HPP 0204 0205 0206 //////////////////////////////////////////////////////////// 0207 /// \class sf::UdpSocket 0208 /// \ingroup network 0209 /// 0210 /// A UDP socket is a connectionless socket. Instead of 0211 /// connecting once to a remote host, like TCP sockets, 0212 /// it can send to and receive from any host at any time. 0213 /// 0214 /// It is a datagram protocol: bounded blocks of data (datagrams) 0215 /// are transfered over the network rather than a continuous 0216 /// stream of data (TCP). Therefore, one call to send will always 0217 /// match one call to receive (if the datagram is not lost), 0218 /// with the same data that was sent. 0219 /// 0220 /// The UDP protocol is lightweight but unreliable. Unreliable 0221 /// means that datagrams may be duplicated, be lost or 0222 /// arrive reordered. However, if a datagram arrives, its 0223 /// data is guaranteed to be valid. 0224 /// 0225 /// UDP is generally used for real-time communication 0226 /// (audio or video streaming, real-time games, etc.) where 0227 /// speed is crucial and lost data doesn't matter much. 0228 /// 0229 /// Sending and receiving data can use either the low-level 0230 /// or the high-level functions. The low-level functions 0231 /// process a raw sequence of bytes, whereas the high-level 0232 /// interface uses packets (see sf::Packet), which are easier 0233 /// to use and provide more safety regarding the data that is 0234 /// exchanged. You can look at the sf::Packet class to get 0235 /// more details about how they work. 0236 /// 0237 /// It is important to note that UdpSocket is unable to send 0238 /// datagrams bigger than MaxDatagramSize. In this case, it 0239 /// returns an error and doesn't send anything. This applies 0240 /// to both raw data and packets. Indeed, even packets are 0241 /// unable to split and recompose data, due to the unreliability 0242 /// of the protocol (dropped, mixed or duplicated datagrams may 0243 /// lead to a big mess when trying to recompose a packet). 0244 /// 0245 /// If the socket is bound to a port, it is automatically 0246 /// unbound from it when the socket is destroyed. However, 0247 /// you can unbind the socket explicitly with the Unbind 0248 /// function if necessary, to stop receiving messages or 0249 /// make the port available for other sockets. 0250 /// 0251 /// Usage example: 0252 /// \code 0253 /// // ----- The client ----- 0254 /// 0255 /// // Create a socket and bind it to the port 55001 0256 /// sf::UdpSocket socket; 0257 /// socket.bind(55001); 0258 /// 0259 /// // Send a message to 192.168.1.50 on port 55002 0260 /// std::string message = "Hi, I am " + sf::IpAddress::getLocalAddress().toString(); 0261 /// socket.send(message.c_str(), message.size() + 1, "192.168.1.50", 55002); 0262 /// 0263 /// // Receive an answer (most likely from 192.168.1.50, but could be anyone else) 0264 /// char buffer[1024]; 0265 /// std::size_t received = 0; 0266 /// sf::IpAddress sender; 0267 /// unsigned short port; 0268 /// socket.receive(buffer, sizeof(buffer), received, sender, port); 0269 /// std::cout << sender.ToString() << " said: " << buffer << std::endl; 0270 /// 0271 /// // ----- The server ----- 0272 /// 0273 /// // Create a socket and bind it to the port 55002 0274 /// sf::UdpSocket socket; 0275 /// socket.bind(55002); 0276 /// 0277 /// // Receive a message from anyone 0278 /// char buffer[1024]; 0279 /// std::size_t received = 0; 0280 /// sf::IpAddress sender; 0281 /// unsigned short port; 0282 /// socket.receive(buffer, sizeof(buffer), received, sender, port); 0283 /// std::cout << sender.ToString() << " said: " << buffer << std::endl; 0284 /// 0285 /// // Send an answer 0286 /// std::string message = "Welcome " + sender.toString(); 0287 /// socket.send(message.c_str(), message.size() + 1, sender, port); 0288 /// \endcode 0289 /// 0290 /// \see sf::Socket, sf::TcpSocket, sf::Packet 0291 /// 0292 ////////////////////////////////////////////////////////////
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|