|
| 1 | +//////////////////////////////////////////////////////////// |
| 2 | +// |
| 3 | +// SFML - Simple and Fast Multimedia Library |
| 4 | +// Copyright (C) 2007-2025 Laurent Gomila ([email protected]) |
| 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 | +#pragma once |
| 26 | + |
| 27 | +//////////////////////////////////////////////////////////// |
| 28 | +// Headers |
| 29 | +//////////////////////////////////////////////////////////// |
| 30 | +#include <SFML/Network/Export.hpp> |
| 31 | + |
| 32 | +#include <SFML/Network/IpAddress.hpp> |
| 33 | + |
| 34 | +#include <SFML/System/String.hpp> |
| 35 | +#include <SFML/System/Time.hpp> |
| 36 | + |
| 37 | +#include <optional> |
| 38 | +#include <vector> |
| 39 | + |
| 40 | +#include <cstdint> |
| 41 | + |
| 42 | + |
| 43 | +//////////////////////////////////////////////////////////// |
| 44 | +/// \brief Perform Domain Name System queries to lookup |
| 45 | +/// DNS records for various purposes |
| 46 | +/// |
| 47 | +//////////////////////////////////////////////////////////// |
| 48 | +namespace sf::Dns |
| 49 | +{ |
| 50 | +//////////////////////////////////////////////////////////// |
| 51 | +/// \brief Resolve a hostname into a list of IP addresses |
| 52 | +/// |
| 53 | +/// \param hostname Hostname to resolve |
| 54 | +/// \param servers The list of servers to query, if empty use the default servers |
| 55 | +/// \param timeout Query timeout if using a provided list of servers, `std::nullopt` to wait forever |
| 56 | +/// |
| 57 | +/// \return List of IP addresses the given hostname resolves to, `std::nullopt` is returned if name resolution fails, an empty list is returned if the hostname could not be resolved to any address |
| 58 | +/// |
| 59 | +//////////////////////////////////////////////////////////// |
| 60 | +[[nodiscard]] SFML_NETWORK_API std::optional<std::vector<IpAddress>> resolve( |
| 61 | + const sf::String& hostname, |
| 62 | + const std::vector<sf::IpAddress>& servers = {}, |
| 63 | + std::optional<sf::Time> timeout = sf::seconds(1)); |
| 64 | + |
| 65 | +//////////////////////////////////////////////////////////// |
| 66 | +/// \brief Query NS records for a hostname |
| 67 | +/// |
| 68 | +/// \param hostname Hostname to query NS records for |
| 69 | +/// \param servers The list of servers to query, if empty use the default servers |
| 70 | +/// \param timeout Query timeout if using a provided list of servers, `std::nullopt` to wait forever |
| 71 | +/// |
| 72 | +/// \return List of NS record strings, an empty list is returned if there are no NS records for the hostname |
| 73 | +/// |
| 74 | +//////////////////////////////////////////////////////////// |
| 75 | +[[nodiscard]] SFML_NETWORK_API std::vector<sf::String> queryNs(const sf::String& hostname, |
| 76 | + const std::vector<sf::IpAddress>& servers = {}, |
| 77 | + std::optional<sf::Time> timeout = sf::seconds(1)); |
| 78 | + |
| 79 | +//////////////////////////////////////////////////////////// |
| 80 | +/// \brief A DNS MX record |
| 81 | +/// |
| 82 | +//////////////////////////////////////////////////////////// |
| 83 | +struct MxRecord |
| 84 | +{ |
| 85 | + sf::String exchange; //!< Host willing to act as mail exchange |
| 86 | + std::uint16_t preference{}; //!< Preference of this record among others, lower values are preferred |
| 87 | +}; |
| 88 | + |
| 89 | +//////////////////////////////////////////////////////////// |
| 90 | +/// \brief Query MX records for a hostname |
| 91 | +/// |
| 92 | +/// \param hostname Hostname to query MX records for |
| 93 | +/// \param servers The list of servers to query, if empty use the default servers |
| 94 | +/// \param timeout Query timeout if using a provided list of servers, `std::nullopt` to wait forever |
| 95 | +/// |
| 96 | +/// \return List of MX records, an empty list is returned if there are no MX records for the hostname |
| 97 | +/// |
| 98 | +//////////////////////////////////////////////////////////// |
| 99 | +[[nodiscard]] SFML_NETWORK_API std::vector<MxRecord> queryMx(const sf::String& hostname, |
| 100 | + const std::vector<sf::IpAddress>& servers = {}, |
| 101 | + std::optional<sf::Time> timeout = sf::seconds(1)); |
| 102 | + |
| 103 | +//////////////////////////////////////////////////////////// |
| 104 | +/// \brief A DNS SRV record |
| 105 | +/// |
| 106 | +//////////////////////////////////////////////////////////// |
| 107 | +struct SrvRecord |
| 108 | +{ |
| 109 | + sf::String target; //!< The domain name of the target host |
| 110 | + std::uint16_t port{}; //!< The port on the target host of the service |
| 111 | + std::uint16_t weight{}; //!< Server selection mechanism, larger weights should be given a proportionately higher probability of being selected |
| 112 | + std::uint16_t priority{}; //!< The priority of the target host, a client must attempt to contact the target host with the lowest-numbered priority it can reach |
| 113 | +}; |
| 114 | + |
| 115 | +//////////////////////////////////////////////////////////// |
| 116 | +/// \brief Query SRV records for a hostname |
| 117 | +/// |
| 118 | +/// \param hostname Hostname to query SRV records for |
| 119 | +/// \param servers The list of servers to query, if empty use the default servers |
| 120 | +/// \param timeout Query timeout if using a provided list of servers, `std::nullopt` to wait forever |
| 121 | +/// |
| 122 | +/// \return List of SRV records, an empty list is returned if there are no SRV records for the hostname |
| 123 | +/// |
| 124 | +//////////////////////////////////////////////////////////// |
| 125 | +[[nodiscard]] SFML_NETWORK_API std::vector<SrvRecord> querySrv(const sf::String& hostname, |
| 126 | + const std::vector<sf::IpAddress>& servers = {}, |
| 127 | + std::optional<sf::Time> timeout = sf::seconds(1)); |
| 128 | + |
| 129 | +//////////////////////////////////////////////////////////// |
| 130 | +/// \brief Query TXT records for a hostname |
| 131 | +/// |
| 132 | +/// \param hostname Hostname to query TXT records for |
| 133 | +/// \param servers The list of servers to query, if empty use the default servers |
| 134 | +/// \param timeout Query timeout if using a provided list of servers, `std::nullopt` to wait forever |
| 135 | +/// |
| 136 | +/// \return List of TXT record string lists, an empty list is returned if there are no TXT records for the hostname |
| 137 | +/// |
| 138 | +//////////////////////////////////////////////////////////// |
| 139 | +[[nodiscard]] SFML_NETWORK_API std::vector<std::vector<sf::String>> queryTxt( |
| 140 | + const sf::String& hostname, |
| 141 | + const std::vector<sf::IpAddress>& servers = {}, |
| 142 | + std::optional<sf::Time> timeout = sf::seconds(1)); |
| 143 | + |
| 144 | +//////////////////////////////////////////////////////////// |
| 145 | +/// \brief Get the computer's public address via DNS |
| 146 | +/// |
| 147 | +/// The public address is the address of the computer from the |
| 148 | +/// point of view of the internet, i.e. something like 89.54.1.169 |
| 149 | +/// or 2600:1901:0:13e0::1 as opposed to a private or local address |
| 150 | +/// like 192.168.1.56 or fe80::1234:5678:9abc. |
| 151 | +/// It is necessary for communication with hosts outside of the |
| 152 | +/// local network. |
| 153 | +/// |
| 154 | +/// The only way to reliably get the public address is to send |
| 155 | +/// data to a host on the internet and see what the origin |
| 156 | +/// address is; as a consequence, this function depends on both |
| 157 | +/// your network connection and the server, and may be very slow. |
| 158 | +/// You should try to use it as little as possible. Because this |
| 159 | +/// function depends on the network connection and on a distant |
| 160 | +/// server, you can specify a time limit if you don't want your |
| 161 | +/// program to get stuck waiting in case there is a problem; this |
| 162 | +/// limit is deactivated by default. |
| 163 | +/// |
| 164 | +/// This function makes use of DNS queries get the public address. |
| 165 | +/// |
| 166 | +/// \param timeout Maximum time to wait, `std::nullopt` to wait forever |
| 167 | +/// \param type The type of public address to get |
| 168 | +/// |
| 169 | +/// \return Public IP address of the computer on success, `std::nullopt` otherwise |
| 170 | +/// |
| 171 | +//////////////////////////////////////////////////////////// |
| 172 | +[[nodiscard]] SFML_NETWORK_API std::optional<IpAddress> getPublicAddress(std::optional<Time> timeout = std::nullopt, |
| 173 | + IpAddress::Type type = IpAddress::Type::IpV4); |
| 174 | +} // namespace sf::Dns |
| 175 | + |
| 176 | + |
| 177 | +//////////////////////////////////////////////////////////// |
| 178 | +/// \namespace sf::Dns |
| 179 | +/// \ingroup network |
| 180 | +/// |
| 181 | +/// The `sf::Dns` functions allow querying the Domain Name System. |
| 182 | +/// The Domain Name System contains many different kinds of |
| 183 | +/// records. The most common records are A and AAAA records |
| 184 | +/// used to resolve hostnames to IPv4 and IPv6 addresses |
| 185 | +/// respectively. Additionally, other kinds of records such |
| 186 | +/// as MX, SRV and TXT records can be queried. |
| 187 | +/// |
| 188 | +/// Usage example: |
| 189 | +/// \code |
| 190 | +/// std::vector<sf::IpAddress> addresses0 = sf::Dns::resolve("127.0.0.1"); // the local host address |
| 191 | +/// std::vector<sf::IpAddress> addresses1 = sf::Dns::resolve("my_computer"); // a list of local addresses created from a network name |
| 192 | +/// std::vector<sf::IpAddress> addresses2 = sf::Dns::resolve("89.54.1.169"); // a distant IPv4 address |
| 193 | +/// std::vector<sf::IpAddress> addresses3 = sf::Dns::resolve("2606:4700:4700::1111"); // a distant IPv6 address |
| 194 | +/// std::vector<sf::IpAddress> addresses4 = sf::Dns::resolve("www.google.com"); // a list of distant address created from a network name |
| 195 | +/// |
| 196 | +/// for (const sf::IpAddress& address : addresses4) |
| 197 | +/// { |
| 198 | +/// if (address.isV4()) |
| 199 | +/// { |
| 200 | +/// // Do something with IPv4 address |
| 201 | +/// } |
| 202 | +/// else |
| 203 | +/// { |
| 204 | +/// // Do something with IPv6 address |
| 205 | +/// } |
| 206 | +/// } |
| 207 | +/// |
| 208 | +/// std::vector<sf::String> nsRecords = sf::Dns::queryNs("sfml-dev.org"); |
| 209 | +/// std::vector<sf::Dns::MxRecord> mxRecords = sf::Dns::queryMx("sfml-dev.org"); |
| 210 | +/// std::vector<std::vector<sf::String>> txtRecords = sf::Dns::queryTxt("sfml-dev.org"); |
| 211 | +/// std::vector<sf::Dns::SrvRecord> srvRecords = sf::Dns::querySrv("_irc._tcp.sfml-dev.org"); |
| 212 | +/// \endcode |
| 213 | +/// |
| 214 | +//////////////////////////////////////////////////////////// |
0 commit comments