mirror of
https://github.com/bitcoin/bitcoin.git
synced 2025-01-12 04:42:36 -03:00
Merge #21444: net, doc: Doxygen updates and fixes in netbase.{h,cpp}
8348a3742bnet: fix hSocket param in netbase.h::ConnectSocketDirectly() (Jon Atack)e6bd74b2e5net: move Doxygen docs from netbase.cpp to netbase.h (Jon Atack)12cc5704dbnet: update incorrect Doxygen documentation in netbase.cpp (Jon Atack) Pull request description: While doing #21328, I noticed docs that were out-of-date or in the wrong file. The second commit is essentially move-only and is best reviewed with `colorMoved = dimmed-zebra` and `colorMovedWs = allow-indentation-change`. ACKs for top commit: laanwj: Code review ACK8348a3742bTree-SHA512: 13dae4abd3009fc43dfffc98e0f7eebcd6ad02afdd6050a7685a2ad4e6aaad93480d93886a2d1bd2375c2439d426494e4a8bc0c60e0e3104bfaa1830831ca663
This commit is contained in:
Wladimir J. van der Laan
commit
cb0aafbd21
2 changed files with 137 additions and 131 deletions
129
src/netbase.cpp
129
src/netbase.cpp
|
|
@ -166,21 +166,6 @@ static bool LookupIntern(const std::string& name, std::vector<CNetAddr>& vIP, un
|
|||
return (vIP.size() > 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a host string to its corresponding network addresses.
|
||||
*
|
||||
* @param name The string representing a host. Could be a name or a numerical
|
||||
* IP address (IPv6 addresses in their bracketed form are
|
||||
* allowed).
|
||||
* @param[out] vIP The resulting network addresses to which the specified host
|
||||
* string resolved.
|
||||
*
|
||||
* @returns Whether or not the specified host string successfully resolved to
|
||||
* any resulting network addresses.
|
||||
*
|
||||
* @see Lookup(const char *, std::vector<CService>&, int, bool, unsigned int)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (!ValidAsCString(name)) {
|
||||
|
|
@ -196,12 +181,6 @@ bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned in
|
|||
return LookupIntern(strHost, vIP, nMaxSolutions, fAllowLookup, dns_lookup_function);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a host string to its first corresponding network address.
|
||||
*
|
||||
* @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool) for
|
||||
* additional parameter descriptions.
|
||||
*/
|
||||
bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (!ValidAsCString(name)) {
|
||||
|
|
@ -215,26 +194,6 @@ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSL
|
|||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a service string to its corresponding service.
|
||||
*
|
||||
* @param name The string representing a service. Could be a name or a
|
||||
* numerical IP address (IPv6 addresses should be in their
|
||||
* disambiguated bracketed form), optionally followed by a port
|
||||
* number. (e.g. example.com:8333 or
|
||||
* [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
|
||||
* @param[out] vAddr The resulting services to which the specified service string
|
||||
* resolved.
|
||||
* @param portDefault The default port for resulting services if not specified
|
||||
* by the service string.
|
||||
* @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
|
||||
* external queries may be performed.
|
||||
* @param nMaxSolutions The maximum number of results we want, specifying 0
|
||||
* means "as many solutions as we get."
|
||||
*
|
||||
* @returns Whether or not the service string successfully resolved to any
|
||||
* resulting services.
|
||||
*/
|
||||
bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (name.empty() || !ValidAsCString(name)) {
|
||||
|
|
@ -254,12 +213,6 @@ bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefau
|
|||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a service string to its first corresponding service.
|
||||
*
|
||||
* @see Lookup(const char *, std::vector<CService>&, int, bool, unsigned int)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (!ValidAsCString(name)) {
|
||||
|
|
@ -273,16 +226,6 @@ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllo
|
|||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a service string with a numeric IP to its first corresponding
|
||||
* service.
|
||||
*
|
||||
* @returns The resulting CService if the resolution was successful, [::]:0
|
||||
* otherwise.
|
||||
*
|
||||
* @see Lookup(const char *, CService&, int, bool) for additional parameter
|
||||
* descriptions.
|
||||
*/
|
||||
CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (!ValidAsCString(name)) {
|
||||
|
|
@ -420,24 +363,6 @@ static std::string Socks5ErrorString(uint8_t err)
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to a specified destination service through an already connected
|
||||
* SOCKS5 proxy.
|
||||
*
|
||||
* @param strDest The destination fully-qualified domain name.
|
||||
* @param port The destination port.
|
||||
* @param auth The credentials with which to authenticate with the specified
|
||||
* SOCKS5 proxy.
|
||||
* @param sock The SOCKS5 proxy socket.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*
|
||||
* @note The specified SOCKS5 proxy socket must already be connected to the
|
||||
* SOCKS5 proxy.
|
||||
*
|
||||
* @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
|
||||
* Version 5</a>
|
||||
*/
|
||||
bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& sock)
|
||||
{
|
||||
IntrRecvError recvr;
|
||||
|
|
@ -612,18 +537,6 @@ static void LogConnectFailure(bool manual_connection, const char* fmt, const Arg
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Try to connect to the specified service on the specified socket.
|
||||
*
|
||||
* @param addrConnect The service to which to connect.
|
||||
* @param hSocket The socket on which to connect.
|
||||
* @param nTimeout Wait this many milliseconds for the connection to be
|
||||
* established.
|
||||
* @param manual_connection Whether or not the connection was manually requested
|
||||
* (e.g. through the addnode RPC)
|
||||
*
|
||||
* @returns Whether or not a connection was successfully made.
|
||||
*/
|
||||
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection)
|
||||
{
|
||||
// Create a sockaddr from the specified service.
|
||||
|
|
@ -722,22 +635,6 @@ bool GetProxy(enum Network net, proxyType &proxyInfoOut) {
|
|||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the name proxy to use for all connections to nodes specified by a
|
||||
* hostname. After setting this proxy, connecting to a node specified by a
|
||||
* hostname won't result in a local lookup of said hostname, rather, connect to
|
||||
* the node by asking the name proxy for a proxy connection to the hostname,
|
||||
* effectively delegating the hostname lookup to the specified proxy.
|
||||
*
|
||||
* This delegation increases privacy for those who set the name proxy as they no
|
||||
* longer leak their external hostname queries to their DNS servers.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*
|
||||
* @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
|
||||
* server in common use (most notably Tor) actually implements UDP
|
||||
* support, and a DNS resolver is beyond the scope of this project.
|
||||
*/
|
||||
bool SetNameProxy(const proxyType &addrProxy) {
|
||||
if (!addrProxy.IsValid())
|
||||
return false;
|
||||
|
|
@ -768,21 +665,6 @@ bool IsProxy(const CNetAddr &addr) {
|
|||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to a specified destination service through a SOCKS5 proxy by first
|
||||
* connecting to the SOCKS5 proxy.
|
||||
*
|
||||
* @param proxy The SOCKS5 proxy.
|
||||
* @param strDest The destination service to which to connect.
|
||||
* @param port The destination port.
|
||||
* @param sock The socket on which to connect to the SOCKS5 proxy.
|
||||
* @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
|
||||
* proxy to be established.
|
||||
* @param[out] outProxyConnectionFailed Whether or not the connection to the
|
||||
* SOCKS5 proxy failed.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*/
|
||||
bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed)
|
||||
{
|
||||
// first connect to proxy server
|
||||
|
|
@ -806,17 +688,6 @@ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int
|
|||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse and resolve a specified subnet string into the appropriate internal
|
||||
* representation.
|
||||
*
|
||||
* @param strSubnet A string representation of a subnet of the form `network
|
||||
* address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
|
||||
* `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
|
||||
* @param ret The resulting internal representation of a subnet.
|
||||
*
|
||||
* @returns Whether the operation succeeded or not.
|
||||
*/
|
||||
bool LookupSubNet(const std::string& strSubnet, CSubNet& ret, DNSLookupFn dns_lookup_function)
|
||||
{
|
||||
if (!ValidAsCString(strSubnet)) {
|
||||
|
|
|
|||
139
src/netbase.h
139
src/netbase.h
|
|
@ -76,6 +76,22 @@ std::vector<std::string> GetNetworkNames(bool append_unroutable = false);
|
|||
bool SetProxy(enum Network net, const proxyType &addrProxy);
|
||||
bool GetProxy(enum Network net, proxyType &proxyInfoOut);
|
||||
bool IsProxy(const CNetAddr &addr);
|
||||
/**
|
||||
* Set the name proxy to use for all connections to nodes specified by a
|
||||
* hostname. After setting this proxy, connecting to a node specified by a
|
||||
* hostname won't result in a local lookup of said hostname, rather, connect to
|
||||
* the node by asking the name proxy for a proxy connection to the hostname,
|
||||
* effectively delegating the hostname lookup to the specified proxy.
|
||||
*
|
||||
* This delegation increases privacy for those who set the name proxy as they no
|
||||
* longer leak their external hostname queries to their DNS servers.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*
|
||||
* @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
|
||||
* server in common use (most notably Tor) actually implements UDP
|
||||
* support, and a DNS resolver is beyond the scope of this project.
|
||||
*/
|
||||
bool SetNameProxy(const proxyType &addrProxy);
|
||||
bool HaveNameProxy();
|
||||
bool GetNameProxy(proxyType &nameProxyOut);
|
||||
|
|
@ -83,11 +99,83 @@ bool GetNameProxy(proxyType &nameProxyOut);
|
|||
using DNSLookupFn = std::function<std::vector<CNetAddr>(const std::string&, bool)>;
|
||||
extern DNSLookupFn g_dns_lookup;
|
||||
|
||||
/**
|
||||
* Resolve a host string to its corresponding network addresses.
|
||||
*
|
||||
* @param name The string representing a host. Could be a name or a numerical
|
||||
* IP address (IPv6 addresses in their bracketed form are
|
||||
* allowed).
|
||||
* @param[out] vIP The resulting network addresses to which the specified host
|
||||
* string resolved.
|
||||
*
|
||||
* @returns Whether or not the specified host string successfully resolved to
|
||||
* any resulting network addresses.
|
||||
*
|
||||
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
* Resolve a host string to its first corresponding network address.
|
||||
*
|
||||
* @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool, DNSLookupFn)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
* Resolve a service string to its corresponding service.
|
||||
*
|
||||
* @param name The string representing a service. Could be a name or a
|
||||
* numerical IP address (IPv6 addresses should be in their
|
||||
* disambiguated bracketed form), optionally followed by a port
|
||||
* number. (e.g. example.com:8333 or
|
||||
* [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
|
||||
* @param[out] vAddr The resulting services to which the specified service string
|
||||
* resolved.
|
||||
* @param portDefault The default port for resulting services if not specified
|
||||
* by the service string.
|
||||
* @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
|
||||
* external queries may be performed.
|
||||
* @param nMaxSolutions The maximum number of results we want, specifying 0
|
||||
* means "as many solutions as we get."
|
||||
*
|
||||
* @returns Whether or not the service string successfully resolved to any
|
||||
* resulting services.
|
||||
*/
|
||||
bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
* Resolve a service string to its first corresponding service.
|
||||
*
|
||||
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
* Resolve a service string with a numeric IP to its first corresponding
|
||||
* service.
|
||||
*
|
||||
* @returns The resulting CService if the resolution was successful, [::]:0 otherwise.
|
||||
*
|
||||
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
|
||||
* for additional parameter descriptions.
|
||||
*/
|
||||
CService LookupNumeric(const std::string& name, int portDefault = 0, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
* Parse and resolve a specified subnet string into the appropriate internal
|
||||
* representation.
|
||||
*
|
||||
* @param strSubnet A string representation of a subnet of the form `network
|
||||
* address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
|
||||
* `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
|
||||
* @param ret The resulting internal representation of a subnet.
|
||||
*
|
||||
* @returns Whether the operation succeeded or not.
|
||||
*/
|
||||
bool LookupSubNet(const std::string& strSubnet, CSubNet& subnet, DNSLookupFn dns_lookup_function = g_dns_lookup);
|
||||
|
||||
/**
|
||||
|
|
@ -102,14 +190,61 @@ std::unique_ptr<Sock> CreateSockTCP(const CService& address_family);
|
|||
*/
|
||||
extern std::function<std::unique_ptr<Sock>(const CService&)> CreateSock;
|
||||
|
||||
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, int nTimeout, bool manual_connection);
|
||||
/**
|
||||
* Try to connect to the specified service on the specified socket.
|
||||
*
|
||||
* @param addrConnect The service to which to connect.
|
||||
* @param hSocket The socket on which to connect.
|
||||
* @param nTimeout Wait this many milliseconds for the connection to be
|
||||
* established.
|
||||
* @param manual_connection Whether or not the connection was manually requested
|
||||
* (e.g. through the addnode RPC)
|
||||
*
|
||||
* @returns Whether or not a connection was successfully made.
|
||||
*/
|
||||
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection);
|
||||
|
||||
/**
|
||||
* Connect to a specified destination service through a SOCKS5 proxy by first
|
||||
* connecting to the SOCKS5 proxy.
|
||||
*
|
||||
* @param proxy The SOCKS5 proxy.
|
||||
* @param strDest The destination service to which to connect.
|
||||
* @param port The destination port.
|
||||
* @param sock The socket on which to connect to the SOCKS5 proxy.
|
||||
* @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
|
||||
* proxy to be established.
|
||||
* @param[out] outProxyConnectionFailed Whether or not the connection to the
|
||||
* SOCKS5 proxy failed.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*/
|
||||
bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed);
|
||||
|
||||
/** Disable or enable blocking-mode for a socket */
|
||||
bool SetSocketNonBlocking(const SOCKET& hSocket, bool fNonBlocking);
|
||||
/** Set the TCP_NODELAY flag on a socket */
|
||||
bool SetSocketNoDelay(const SOCKET& hSocket);
|
||||
void InterruptSocks5(bool interrupt);
|
||||
|
||||
/**
|
||||
* Connect to a specified destination service through an already connected
|
||||
* SOCKS5 proxy.
|
||||
*
|
||||
* @param strDest The destination fully-qualified domain name.
|
||||
* @param port The destination port.
|
||||
* @param auth The credentials with which to authenticate with the specified
|
||||
* SOCKS5 proxy.
|
||||
* @param sock The SOCKS5 proxy socket.
|
||||
*
|
||||
* @returns Whether or not the operation succeeded.
|
||||
*
|
||||
* @note The specified SOCKS5 proxy socket must already be connected to the
|
||||
* SOCKS5 proxy.
|
||||
*
|
||||
* @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
|
||||
* Version 5</a>
|
||||
*/
|
||||
bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& socket);
|
||||
|
||||
#endif // BITCOIN_NETBASE_H
|
||||
|
|
|
|||
Loading…
Reference in a new issue