/extlibs/SFML/include/SFML/Network/IpAddress.hpp

  1////////////////////////////////////////////////////////////
  2//
  3// SFML - Simple and Fast Multimedia Library
  4// Copyright (C) 2007-2009 Laurent Gomila (laurent.gom@gmail.com)
  5//
  6// This software is provided 'as-is', without any express or implied warranty.
  7// In no event will the authors be held liable for any damages arising from the use of this software.
  8//
  9// Permission is granted to anyone to use this software for any purpose,
 10// including commercial applications, and to alter it and redistribute it freely,
 11// subject to the following restrictions:
 12//
 13// 1. The origin of this software must not be misrepresented;
 14//    you must not claim that you wrote the original software.
 15//    If you use this software in a product, an acknowledgment
 16//    in the product documentation would be appreciated but is not required.
 17//
 18// 2. Altered source versions must be plainly marked as such,
 19//    and must not be misrepresented as being the original software.
 20//
 21// 3. This notice may not be removed or altered from any source distribution.
 22//
 23////////////////////////////////////////////////////////////
 24
 25#ifndef SFML_IPADDRESS_HPP
 26#define SFML_IPADDRESS_HPP
 27
 28////////////////////////////////////////////////////////////
 29// Headers
 30////////////////////////////////////////////////////////////
 31#include <SFML/Config.hpp>
 32#include <istream>
 33#include <ostream>
 34#include <string>
 35
 36
 37namespace sf
 38{
 39////////////////////////////////////////////////////////////
 40/// \brief Encapsulate an IPv4 network address
 41///
 42////////////////////////////////////////////////////////////
 43class SFML_API IpAddress
 44{
 45public :
 46
 47    ////////////////////////////////////////////////////////////
 48    /// \brief Default constructor
 49    ///
 50    /// This constructor creates an empty (invalid) address
 51    ///
 52    ////////////////////////////////////////////////////////////
 53    IpAddress();
 54
 55    ////////////////////////////////////////////////////////////
 56    /// \brief Construct the address from a string
 57    ///
 58    /// Here \a address can be either a decimal address
 59    /// (ex: "192.168.1.56") or a network name (ex: "localhost").
 60    ///
 61    /// \param address IP address or network name
 62    ///
 63    ////////////////////////////////////////////////////////////
 64    IpAddress(const std::string& address);
 65
 66    ////////////////////////////////////////////////////////////
 67    /// \brief Construct the address from a string
 68    ///
 69    /// Here \a address can be either a decimal address
 70    /// (ex: "192.168.1.56") or a network name (ex: "localhost").
 71    /// This is equivalent to the constructor taking a std::string
 72    /// parameter, it is defined for convenience so that the
 73    /// implicit conversions from literal strings to IpAddress work.
 74    ///
 75    /// \param address IP address or network name
 76    ///
 77    ////////////////////////////////////////////////////////////
 78    IpAddress(const char* address);
 79
 80    ////////////////////////////////////////////////////////////
 81    /// \brief Construct the address from 4 bytes
 82    ///
 83    /// Calling IpAddress(a, b, c, d) is equivalent to calling
 84    /// IpAddress("a.b.c.d"), but safer as it doesn't have to
 85    /// parse a string to get the address components.
 86    ///
 87    /// \param byte0 First byte of the address
 88    /// \param byte1 Second byte of the address
 89    /// \param byte2 Third byte of the address
 90    /// \param byte3 Fourth byte of the address
 91    ///
 92    ////////////////////////////////////////////////////////////
 93    IpAddress(Uint8 byte0, Uint8 byte1, Uint8 byte2, Uint8 byte3);
 94
 95    ////////////////////////////////////////////////////////////
 96    /// \brief Construct the address from a 32-bits integer
 97    ///
 98    /// This constructor uses the internal representation of
 99    /// the address directly. It should be used for optimization
100    /// purposes, and only if you got that representation from
101    /// IpAddress::ToInteger().
102    ///
103    /// \param address 4 bytes of the address packed into a 32-bits integer
104    ///
105    /// \see ToInteger
106    ///
107    ////////////////////////////////////////////////////////////
108    explicit IpAddress(Uint32 address);
109
110    ////////////////////////////////////////////////////////////
111    /// \brief Get a string representation of the address
112    ///
113    /// The returned string is the decimal representation of the
114    /// IP address (like "192.168.1.56"), even if it was constructed
115    /// from a host name.
116    ///
117    /// \return String representation of the address
118    ///
119    /// \see ToInteger
120    ///
121    ////////////////////////////////////////////////////////////
122    std::string ToString() const;
123
124    ////////////////////////////////////////////////////////////
125    /// \brief Get an integer representation of the address
126    ///
127    /// The returned number is the internal representation of the
128    /// address, and should be used for optimization purposes only
129    /// (like sending the address through a socket).
130    /// The integer produced by this function can then be converted
131    /// back to a sf::IpAddress with the proper constructor.
132    ///
133    /// \return 32-bits unsigned integer representation of the address
134    ///
135    /// \see ToString
136    ///
137    ////////////////////////////////////////////////////////////
138    Uint32 ToInteger() const;
139
140    ////////////////////////////////////////////////////////////
141    /// \brief Get the computer's local address
142    ///
143    /// The local address is the address of the computer from the
144    /// LAN point of view, i.e. something like 192.168.1.56. It is
145    /// meaningful only for communications over the local network.
146    /// Unlike GetPublicAddress, this function is fast and may be
147    /// used safely anywhere.
148    ///
149    /// \return Local IP address of the computer
150    ///
151    /// \see GetPublicAddress
152    ///
153    ////////////////////////////////////////////////////////////
154    static IpAddress GetLocalAddress();
155
156    ////////////////////////////////////////////////////////////
157    /// \brief Get the computer's public address
158    ///
159    /// The public address is the address of the computer from the
160    /// internet point of view, i.e. something like 89.54.1.169.
161    /// It is necessary for communications over the world wide web.
162    /// The only way to get a public address is to ask it to a
163    /// distant website; as a consequence, this function depends on
164    /// both your network connection and the server, and may be
165    /// very slow. You should use it as few as possible. Because
166    /// this function depends on the network connection and on a distant
167    /// server, you may use a time limit if you don't want your program
168    /// to be possibly stuck waiting in case there is a problem; this
169    /// limit is deactivated by default.
170    ///
171    /// \param timeout Maximum time to wait, in seconds
172    ///
173    /// \return Public IP address of the computer
174    ///
175    /// \see GetLocalAddress
176    ///
177    ////////////////////////////////////////////////////////////
178    static IpAddress GetPublicAddress(float timeout = 0.f);
179
180    ////////////////////////////////////////////////////////////
181    // Static member data
182    ////////////////////////////////////////////////////////////
183    static const IpAddress None;      ///< Value representing an empty/invalid address
184    static const IpAddress LocalHost; ///< The "localhost" address (for connecting a computer to itself locally)
185
186private :
187
188    ////////////////////////////////////////////////////////////
189    // Member data
190    ////////////////////////////////////////////////////////////
191    Uint32 myAddress; ///< Address stored as an unsigned 32 bits integer
192};
193
194////////////////////////////////////////////////////////////
195/// \brief Overload of == operator to compare two IP addresses
196///
197/// \param left  Left operand (a IP address)
198/// \param right Right operand (a IP address)
199///
200/// \return True if both addresses are equal
201///
202////////////////////////////////////////////////////////////
203SFML_API bool operator ==(const IpAddress& left, const IpAddress& right);
204
205////////////////////////////////////////////////////////////
206/// \brief Overload of != operator to compare two IP addresses
207///
208/// \param left  Left operand (a IP address)
209/// \param right Right operand (a IP address)
210///
211/// \return True if both addresses are different
212///
213////////////////////////////////////////////////////////////
214SFML_API bool operator !=(const IpAddress& left, const IpAddress& right);
215
216////////////////////////////////////////////////////////////
217/// \brief Overload of < operator to compare two IP addresses
218///
219/// \param left  Left operand (a IP address)
220/// \param right Right operand (a IP address)
221///
222/// \return True if \a left is lesser than \a right
223///
224////////////////////////////////////////////////////////////
225SFML_API bool operator <(const IpAddress& left, const IpAddress& right);
226
227////////////////////////////////////////////////////////////
228/// \brief Overload of > operator to compare two IP addresses
229///
230/// \param left  Left operand (a IP address)
231/// \param right Right operand (a IP address)
232///
233/// \return True if \a left is greater than \a right
234///
235////////////////////////////////////////////////////////////
236SFML_API bool operator >(const IpAddress& left, const IpAddress& right);
237
238////////////////////////////////////////////////////////////
239/// \brief Overload of <= operator to compare two IP addresses
240///
241/// \param left  Left operand (a IP address)
242/// \param right Right operand (a IP address)
243///
244/// \return True if \a left is lesser or equal than \a right
245///
246////////////////////////////////////////////////////////////
247SFML_API bool operator <=(const IpAddress& left, const IpAddress& right);
248
249////////////////////////////////////////////////////////////
250/// \brief Overload of >= operator to compare two IP addresses
251///
252/// \param left  Left operand (a IP address)
253/// \param right Right operand (a IP address)
254///
255/// \return True if \a left is greater or equal than \a right
256///
257////////////////////////////////////////////////////////////
258SFML_API bool operator >=(const IpAddress& left, const IpAddress& right);
259
260////////////////////////////////////////////////////////////
261/// \brief Overload of >> operator to extract an IP address from an input stream
262///
263/// \param stream  Input stream
264/// \param address IP address to extract
265///
266/// \return Reference to the input stream
267///
268////////////////////////////////////////////////////////////
269SFML_API std::istream& operator >>(std::istream& stream, IpAddress& address);
270
271////////////////////////////////////////////////////////////
272/// \brief Overload of << operator to print an IP address to an output stream
273///
274/// \param stream  Output stream
275/// \param address IP address to print
276///
277/// \return Reference to the output stream
278///
279////////////////////////////////////////////////////////////
280SFML_API std::ostream& operator <<(std::ostream& stream, const IpAddress& address);
281
282} // namespace sf
283
284
285#endif // SFML_IPADDRESS_HPP
286
287
288////////////////////////////////////////////////////////////
289/// \class sf::IpAddress
290/// \ingroup network
291///
292/// sf::IpAddress is a utility class for manipulating network
293/// addresses. It provides a set a implicit constructors and
294/// conversion functions to easily build or transform an IP
295/// address from/to various representations.
296///
297/// Usage example:
298/// \code
299/// sf::IpAddress a0;                                     // an invalid address
300/// sf::IpAddress a1 = sf::IpAddress::None;               // an invalid address (same as a0)
301/// sf::IpAddress a2("127.0.0.1");                        // the local host address
302/// sf::IpAddress a3 = sf::IpAddress::LocalHost;          // the local host address (same as a2)
303/// sf::IpAddress a4(192, 168, 1, 56);                    // a local address
304/// sf::IpAddress a5("my_computer");                      // a local address created from a network name
305/// sf::IpAddress a6("89.54.1.169");                      // a distant address
306/// sf::IpAddress a7("www.google.com");                   // a distant address created from a network name
307/// sf::IpAddress a8 = sf::IpAddress::GetLocalAddress();  // my address on the local network
308/// sf::IpAddress a9 = sf::IpAddress::GetPublicAddress(); // my address on the internet
309/// \endcode
310///
311/// Note that sf::IpAddress currently doesn't support IPv6
312/// nor other types of network addresses.
313///
314////////////////////////////////////////////////////////////