lauchmelder/SFML
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improved the API documentation of sf::IpAddress

Browse source 
git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1452 4e206d99-4929-0410-ac5d-dfc041789085
This commit is contained in:
LaurentGom 2010-03-12 09:35:17 +00:00
parent b7eb09cb79
commit e924c9cf39
34 changed files with 336 additions and 264 deletions
Download patch file Download diff file Expand all files Collapse all files

2
include/SFML/Network.hpp
View file

@ -32,7 +32,7 @@
#include <SFML/System.hpp>
#include <SFML/Network/Ftp.hpp>
#include <SFML/Network/Http.hpp>
#include <SFML/Network/IPAddress.hpp>
#include <SFML/Network/IpAddress.hpp>
#include <SFML/Network/Packet.hpp>
#include <SFML/Network/Selector.hpp>
#include <SFML/Network/SocketTCP.hpp>

4
include/SFML/Network/Ftp.hpp
View file

@ -36,7 +36,7 @@
namespace sf
{
class IPAddress;
class IpAddress;
////////////////////////////////////////////////////////////
/// This class provides methods for manipulating the FTP
@ -267,7 +267,7 @@ public :
/// \return Server response to the request
///
////////////////////////////////////////////////////////////
Response Connect(const IPAddress& server, unsigned short port = 21, float timeout = 0.f);
Response Connect(const IpAddress& server, unsigned short port = 21, float timeout = 0.f);
////////////////////////////////////////////////////////////
/// Log in using anonymous account

4
include/SFML/Network/Http.hpp
View file

@ -29,7 +29,7 @@
// Headers
////////////////////////////////////////////////////////////
#include <SFML/System/NonCopyable.hpp>
#include <SFML/Network/IPAddress.hpp>
#include <SFML/Network/IpAddress.hpp>
#include <SFML/Network/SocketTCP.hpp>
#include <map>
#include <string>
@ -334,7 +334,7 @@ private :
// Member data
////////////////////////////////////////////////////////////
SocketTCP myConnection; ///< Connection to the host
IPAddress myHost; ///< Web host address
IpAddress myHost; ///< Web host address
std::string myHostName; ///< Web host name
unsigned short myPort; ///< Port used for connection with host
};

235
include/SFML/Network/IpAddress.hpp
View file

@ -37,56 +37,93 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// IPAddress provides easy manipulation of IP v4 addresses
/// \brief Encapsulate an IPv4 network address
///
////////////////////////////////////////////////////////////
class SFML_API IPAddress
class SFML_API IpAddress
{
public :
////////////////////////////////////////////////////////////
/// Default constructor -- constructs an invalid address
/// \brief Default constructor
///
/// This constructor creates an empty (invalid) address
///
////////////////////////////////////////////////////////////
IPAddress();
IpAddress();
////////////////////////////////////////////////////////////
/// Construct the address from a string
/// \brief Construct the address from a string
///
/// \param address : IP address ("xxx.xxx.xxx.xxx") or network name
/// Here \a address can be either a decimal address
/// (ex: "192.168.1.56") or a network name (ex: "localhost").
///
/// \param address IP address or network name
///
////////////////////////////////////////////////////////////
IPAddress(const std::string& address);
IpAddress(const std::string& address);
////////////////////////////////////////////////////////////
/// Construct the address from a C-style string ;
/// Needed for implicit conversions from literal strings to IPAddress to work
/// \brief Construct the address from a string
///
/// \param address : IP address ("xxx.xxx.xxx.xxx") or network name
/// Here \a address can be either a decimal address
/// (ex: "192.168.1.56") or a network name (ex: "localhost").
/// This is equivalent to the constructor taking a std::string
/// parameter, it is defined for convenience so that the
/// implicit conversions from literal strings to IpAddress work.
///
/// \param address IP address or network name
///
////////////////////////////////////////////////////////////
IPAddress(const char* address);
IpAddress(const char* address);
////////////////////////////////////////////////////////////
/// Construct the address from 4 bytes
/// \brief Construct the address from 4 bytes
///
/// \param byte0 : First byte of the address
/// \param byte1 : Second byte of the address
/// \param byte2 : Third byte of the address
/// \param byte3 : Fourth byte of the address
/// Calling IpAddress(a, b, c, d) is equivalent to calling
/// IpAddress("a.b.c.d"), but safer as it doesn't have to
/// parse a string to get the address components.
///
/// \param byte0 First byte of the address
/// \param byte1 Second byte of the address
/// \param byte2 Third byte of the address
/// \param byte3 Fourth byte of the address
///
////////////////////////////////////////////////////////////
IPAddress(Uint8 byte0, Uint8 byte1, Uint8 byte2, Uint8 byte3);
IpAddress(Uint8 byte0, Uint8 byte1, Uint8 byte2, Uint8 byte3);
////////////////////////////////////////////////////////////
/// Construct the address from a 32-bits integer
/// \brief Construct the address from a 32-bits integer
///
/// \param address : 4 bytes of the address packed into a 32-bits integer
/// This constructor uses the internal representation of
/// the address directly. It should be used for optimization
/// purposes, and only if you got that representation from
/// IpAddress::ToInteger().
///
/// \param address 4 bytes of the address packed into a 32-bits integer
///
/// \see ToInteger
///
////////////////////////////////////////////////////////////
IPAddress(Uint32 address);
IpAddress(Uint32 address);
////////////////////////////////////////////////////////////
/// Tell if the address is a valid one
/// \brief Check if the address is a valid one
///
/// If the address was constructed from a decimal representation
/// (like "192.168.1.56") this function will always return true
/// unless the address is the special one 255.255.255.255.
/// If the address was constructed from a host name, it is
/// reported as beeing valid only if the host exists and could
/// be converted to a decimal IP address.
///
/// Examples:
/// \begincode
/// bool b1 = sf::IpAddress("127.0.0.1").IsValid(); // true
/// bool b2 = sf::IpAddress("1.2.3.4").IsValid(); // true
/// bool b3 = sf::IpAddress("www.google.com").IsValid(); // true
/// bool b4 = sf::IpAddress("www.dfgfghqsd.com").IsValid(); // false
/// \endcode
///
/// \return True if address has a valid syntax
///
@ -94,46 +131,79 @@ public :
bool IsValid() const;
////////////////////////////////////////////////////////////
/// Get a string representation of the address
/// \brief Get a string representation of the address
///
/// \return String representation of the IP address ("xxx.xxx.xxx.xxx")
/// The returned string is the decimal representation of the
/// IP address (like "192.168.1.56"), even if it was constructed
/// from a host name.
///
/// \return String representation of the address
///
/// \see ToInteger
///
////////////////////////////////////////////////////////////
std::string ToString() const;
////////////////////////////////////////////////////////////
/// Get an integer representation of the address
/// \brief Get an integer representation of the address
///
/// \return 32-bits integer containing the 4 bytes of the address, in system endianness
/// The returned number is the internal representation of the
/// address, and should be used for optimization purposes only
/// (like sending the address through a socket).
/// The integer produced by this function can then be converted
/// back to a sf::IpAddress with the proper constructor.
///
/// \return 32-bits unsigned integer representation of the address
///
/// \see ToString
///
////////////////////////////////////////////////////////////
Uint32 ToInteger() const;
////////////////////////////////////////////////////////////
/// Get the computer's local IP address (from the LAN point of view)
/// \brief Get the computer's local address
///
/// \return Local IP address
/// The local address is the address of the computer from the
/// LAN point of view, i.e. something like 192.168.1.56. It is
/// meaningful only for communications over the local network.
/// Unlike GetPublicAddress, this function is fast and may be
/// used safely anywhere.
///
/// \return Local IP address of the computer
///
/// \see GetPublicAddress
///
////////////////////////////////////////////////////////////
static IPAddress GetLocalAddress();
static IpAddress GetLocalAddress();
////////////////////////////////////////////////////////////
/// Get the computer's public IP address (from the web point of view).
/// \brief Get the computer's public address
///
/// The public address is the address of the computer from the
/// internet point of view, i.e. something like 89.54.1.169.
/// It is necessary for communications over the world wide web.
/// The only way to get a public address is to ask it to a
/// distant website ; as a consequence, this function may be
/// very slow -- use it as few as possible !
/// distant website; as a consequence, this function depends on
/// both your network connection and the server, and may be
/// very slow. You should use it as few as possible. Because
/// this function depends on the network connection and on a distant
/// server, you may use a time limit if you don't want your program
/// to be possibly stuck waiting in case there is a problem; this
/// limit is deactivated by default.
///
/// \param timeout : Maximum time to wait, in seconds (0 by default : no timeout)
/// \param timeout Maximum time to wait, in seconds
///
/// \return Public IP address
/// \return Public IP address of the computer
///
/// \see GetLocalAddress
///
////////////////////////////////////////////////////////////
static IPAddress GetPublicAddress(float timeout = 0.f);
static IpAddress GetPublicAddress(float timeout = 0.f);
////////////////////////////////////////////////////////////
// Static member data
////////////////////////////////////////////////////////////
static const IPAddress LocalHost; ///< Local host address (to connect to the same computer)
static const IpAddress LocalHost; ///< The "localhost" address (for connecting a computer to itself locally)
private :
@ -144,94 +214,121 @@ private :
};
////////////////////////////////////////////////////////////
/// \brief Overload of == operator to compare two host addresses
/// \brief Overload of == operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if both hosts are equal
/// \return True if both addresses are equal
///
////////////////////////////////////////////////////////////
SFML_API bool operator ==(const IPAddress& left, const IPAddress& right);
SFML_API bool operator ==(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// \brief Overload of != operator to compare two host addresses
/// \brief Overload of != operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if both hosts are different
/// \return True if both addresses are different
///
////////////////////////////////////////////////////////////
SFML_API bool operator !=(const IPAddress& left, const IPAddress& right);
SFML_API bool operator !=(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// \brief Overload of < operator to compare two host addresses
/// \brief Overload of < operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if \a left is lesser than \a right
///
////////////////////////////////////////////////////////////
SFML_API bool operator <(const IPAddress& left, const IPAddress& right);
SFML_API bool operator <(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// \brief Overload of > operator to compare two host addresses
/// \brief Overload of > operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if \a left is greater than \a right
///
////////////////////////////////////////////////////////////
SFML_API bool operator >(const IPAddress& left, const IPAddress& right);
SFML_API bool operator >(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// \brief Overload of <= operator to compare two host addresses
/// \brief Overload of <= operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if \a left is lesser or equal than \a right
///
////////////////////////////////////////////////////////////
SFML_API bool operator <=(const IPAddress& left, const IPAddress& right);
SFML_API bool operator <=(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// \brief Overload of >= operator to compare two host addresses
/// \brief Overload of >= operator to compare two IP addresses
///
/// \param left Left operand (a host address)
/// \param right Right operand (a host address)
/// \param left Left operand (a IP address)
/// \param right Right operand (a IP address)
///
/// \return True if \a left is greater or equal than \a right
///
////////////////////////////////////////////////////////////
SFML_API bool operator >=(const IPAddress& left, const IPAddress& right);
SFML_API bool operator >=(const IpAddress& left, const IpAddress& right);
////////////////////////////////////////////////////////////
/// Operator >> overload to extract an host address from an input stream
/// \brief Overload of >> operator to extract an IP address from an input stream
///
/// \param Stream : Input stream
/// \param Address : Host address to extract
/// \param stream Input stream
/// \param address IP address to extract
///
/// \return Reference to the input stream
///
////////////////////////////////////////////////////////////
SFML_API std::istream& operator >>(std::istream& stream, IPAddress& address);
SFML_API std::istream& operator >>(std::istream& stream, IpAddress& address);
////////////////////////////////////////////////////////////
/// Operator << overload to print an host address to an output stream
/// \brief Overload of << operator to print an IP address to an output stream
///
/// \param Stream : Output stream
/// \param Address : Host address to print
/// \param stream Output stream
/// \param address IP address to print
///
/// \return Reference to the output stream
///
////////////////////////////////////////////////////////////
SFML_API std::ostream& operator <<(std::ostream& stream, const IPAddress& address);
SFML_API std::ostream& operator <<(std::ostream& stream, const IpAddress& address);
} // namespace sf
#endif // SFML_IPADDRESS_HPP
////////////////////////////////////////////////////////////
/// \class sf::IpAddress
///
/// sf::IpAddress is a utility class for manipulating network
/// addresses. It provides a set a implicit constructors and
/// conversion functions to easily build or transform an IP
/// address from/to various representations.
///
/// Usage example:
/// \code
/// sf::IpAddress a1; // an invalid address
/// sf::IpAddress a2("127.0.0.1"); // the local host address
/// sf::IpAddress a3 = sf::IpAddress::LocalHost; // the local host address (same as a2)
/// sf::IpAddress a4(192, 168, 1, 56); // a local address
/// sf::IpAddress a5("my_computer"); // a local address created from a network name
/// sf::IpAddress a6("89.54.1.169"); // a distant address
/// sf::IpAddress a7("www.google.com"); // a distant address created from a network name
/// sf::IpAddress a8 = sf::IpAddress::GetLocalAddress(); // my address on the local network
/// sf::IpAddress a9 = sf::IpAddress::GetPublicAddress(); // my address on the internet
/// \endcode
///
/// Note that sf::IpAddress currently doesn't support IPv6
/// nor other types of network addresses.
///
////////////////////////////////////////////////////////////

6
include/SFML/Network/SocketTCP.hpp
View file

@ -35,7 +35,7 @@
namespace sf
{
class Packet;
class IPAddress;
class IpAddress;
template <typename> class Selector;
////////////////////////////////////////////////////////////
@ -71,7 +71,7 @@ public :
/// \return True if operation has been successful
///
////////////////////////////////////////////////////////////
Socket::Status Connect(unsigned short port, const IPAddress& host, float timeout = 0.f);
Socket::Status Connect(unsigned short port, const IpAddress& host, float timeout = 0.f);
////////////////////////////////////////////////////////////
/// Listen to a specified port for incoming data or connections
@ -93,7 +93,7 @@ public :
/// \return Status code
///
////////////////////////////////////////////////////////////
Socket::Status Accept(SocketTCP& connected, IPAddress* address = NULL);
Socket::Status Accept(SocketTCP& connected, IpAddress* address = NULL);
////////////////////////////////////////////////////////////
/// Send an array of bytes to the host (must be connected first)

10
include/SFML/Network/SocketUDP.hpp
View file

@ -35,7 +35,7 @@
namespace sf
{
class Packet;
class IPAddress;
class IpAddress;
template <typename> class Selector;
////////////////////////////////////////////////////////////
@ -90,7 +90,7 @@ public :
/// \return Status code
///
////////////////////////////////////////////////////////////
Socket::Status Send(const char* data, std::size_t sizeInBytes, const IPAddress& address, unsigned short port);
Socket::Status Send(const char* data, std::size_t sizeInBytes, const IpAddress& address, unsigned short port);
////////////////////////////////////////////////////////////
/// Receive an array of bytes.
@ -105,7 +105,7 @@ public :
/// \return Status code
///
////////////////////////////////////////////////////////////
Socket::Status Receive(char* data, std::size_t maxSize, std::size_t& sizeReceived, IPAddress& address, unsigned short& port);
Socket::Status Receive(char* data, std::size_t maxSize, std::size_t& sizeReceived, IpAddress& address, unsigned short& port);
////////////////////////////////////////////////////////////
/// Send a packet of data
@ -117,7 +117,7 @@ public :
/// \return Status code
///
////////////////////////////////////////////////////////////
Socket::Status Send(Packet& packet, const IPAddress& address, unsigned short port);
Socket::Status Send(Packet& packet, const IpAddress& address, unsigned short port);
////////////////////////////////////////////////////////////
/// Receive a packet.
@ -130,7 +130,7 @@ public :
/// \return Status code
///
////////////////////////////////////////////////////////////
Socket::Status Receive(Packet& packet, IPAddress& address, unsigned short& port);
Socket::Status Receive(Packet& packet, IpAddress& address, unsigned short& port);
////////////////////////////////////////////////////////////
/// Close the socket