Skip to content

Commit cb0aafb

Browse files
laanwjlaanwj
committed
Merge #21444: net, doc: Doxygen updates and fixes in netbase.{h,cpp}
8348a37 net: fix hSocket param in netbase.h::ConnectSocketDirectly() (Jon Atack) e6bd74b net: move Doxygen docs from netbase.cpp to netbase.h (Jon Atack) 12cc570 net: 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 ACK 8348a37 Tree-SHA512: 13dae4abd3009fc43dfffc98e0f7eebcd6ad02afdd6050a7685a2ad4e6aaad93480d93886a2d1bd2375c2439d426494e4a8bc0c60e0e3104bfaa1830831ca663
2 parents 8e65320 + 8348a37 commit cb0aafb

File tree

2 files changed

+137
-131
lines changed

2 files changed

+137
-131
lines changed

‎src/netbase.cpp

Lines changed: 0 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -166,21 +166,6 @@ static bool LookupIntern(const std::string& name, std::vector<CNetAddr>& vIP, un
166166
return (vIP.size() > 0);
167167
}
168168

169-
/**
170-
* Resolve a host string to its corresponding network addresses.
171-
*
172-
* @param name The string representing a host. Could be a name or a numerical
173-
* IP address (IPv6 addresses in their bracketed form are
174-
* allowed).
175-
* @param[out] vIP The resulting network addresses to which the specified host
176-
* string resolved.
177-
*
178-
* @returns Whether or not the specified host string successfully resolved to
179-
* any resulting network addresses.
180-
*
181-
* @see Lookup(const char *, std::vector<CService>&, int, bool, unsigned int)
182-
* for additional parameter descriptions.
183-
*/
184169
bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function)
185170
{
186171
if (!ValidAsCString(name)) {
@@ -196,12 +181,6 @@ bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned in
196181
return LookupIntern(strHost, vIP, nMaxSolutions, fAllowLookup, dns_lookup_function);
197182
}
198183

199-
/**
200-
* Resolve a host string to its first corresponding network address.
201-
*
202-
* @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool) for
203-
* additional parameter descriptions.
204-
*/
205184
bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function)
206185
{
207186
if (!ValidAsCString(name)) {
@@ -215,26 +194,6 @@ bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSL
215194
return true;
216195
}
217196

218-
/**
219-
* Resolve a service string to its corresponding service.
220-
*
221-
* @param name The string representing a service. Could be a name or a
222-
* numerical IP address (IPv6 addresses should be in their
223-
* disambiguated bracketed form), optionally followed by a port
224-
* number. (e.g. example.com:8333 or
225-
* [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
226-
* @param[out] vAddr The resulting services to which the specified service string
227-
* resolved.
228-
* @param portDefault The default port for resulting services if not specified
229-
* by the service string.
230-
* @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
231-
* external queries may be performed.
232-
* @param nMaxSolutions The maximum number of results we want, specifying 0
233-
* means "as many solutions as we get."
234-
*
235-
* @returns Whether or not the service string successfully resolved to any
236-
* resulting services.
237-
*/
238197
bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function)
239198
{
240199
if (name.empty() || !ValidAsCString(name)) {
@@ -254,12 +213,6 @@ bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefau
254213
return true;
255214
}
256215

257-
/**
258-
* Resolve a service string to its first corresponding service.
259-
*
260-
* @see Lookup(const char *, std::vector<CService>&, int, bool, unsigned int)
261-
* for additional parameter descriptions.
262-
*/
263216
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function)
264217
{
265218
if (!ValidAsCString(name)) {
@@ -273,16 +226,6 @@ bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllo
273226
return true;
274227
}
275228

276-
/**
277-
* Resolve a service string with a numeric IP to its first corresponding
278-
* service.
279-
*
280-
* @returns The resulting CService if the resolution was successful, [::]:0
281-
* otherwise.
282-
*
283-
* @see Lookup(const char *, CService&, int, bool) for additional parameter
284-
* descriptions.
285-
*/
286229
CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function)
287230
{
288231
if (!ValidAsCString(name)) {
@@ -420,24 +363,6 @@ static std::string Socks5ErrorString(uint8_t err)
420363
}
421364
}
422365

423-
/**
424-
* Connect to a specified destination service through an already connected
425-
* SOCKS5 proxy.
426-
*
427-
* @param strDest The destination fully-qualified domain name.
428-
* @param port The destination port.
429-
* @param auth The credentials with which to authenticate with the specified
430-
* SOCKS5 proxy.
431-
* @param sock The SOCKS5 proxy socket.
432-
*
433-
* @returns Whether or not the operation succeeded.
434-
*
435-
* @note The specified SOCKS5 proxy socket must already be connected to the
436-
* SOCKS5 proxy.
437-
*
438-
* @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
439-
* Version 5</a>
440-
*/
441366
bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& sock)
442367
{
443368
IntrRecvError recvr;
@@ -612,18 +537,6 @@ static void LogConnectFailure(bool manual_connection, const char* fmt, const Arg
612537
}
613538
}
614539

615-
/**
616-
* Try to connect to the specified service on the specified socket.
617-
*
618-
* @param addrConnect The service to which to connect.
619-
* @param hSocket The socket on which to connect.
620-
* @param nTimeout Wait this many milliseconds for the connection to be
621-
* established.
622-
* @param manual_connection Whether or not the connection was manually requested
623-
* (e.g. through the addnode RPC)
624-
*
625-
* @returns Whether or not a connection was successfully made.
626-
*/
627540
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection)
628541
{
629542
// Create a sockaddr from the specified service.
@@ -722,22 +635,6 @@ bool GetProxy(enum Network net, proxyType &proxyInfoOut) {
722635
return true;
723636
}
724637

725-
/**
726-
* Set the name proxy to use for all connections to nodes specified by a
727-
* hostname. After setting this proxy, connecting to a node specified by a
728-
* hostname won't result in a local lookup of said hostname, rather, connect to
729-
* the node by asking the name proxy for a proxy connection to the hostname,
730-
* effectively delegating the hostname lookup to the specified proxy.
731-
*
732-
* This delegation increases privacy for those who set the name proxy as they no
733-
* longer leak their external hostname queries to their DNS servers.
734-
*
735-
* @returns Whether or not the operation succeeded.
736-
*
737-
* @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
738-
* server in common use (most notably Tor) actually implements UDP
739-
* support, and a DNS resolver is beyond the scope of this project.
740-
*/
741638
bool SetNameProxy(const proxyType &addrProxy) {
742639
if (!addrProxy.IsValid())
743640
return false;
@@ -768,21 +665,6 @@ bool IsProxy(const CNetAddr &addr) {
768665
return false;
769666
}
770667

771-
/**
772-
* Connect to a specified destination service through a SOCKS5 proxy by first
773-
* connecting to the SOCKS5 proxy.
774-
*
775-
* @param proxy The SOCKS5 proxy.
776-
* @param strDest The destination service to which to connect.
777-
* @param port The destination port.
778-
* @param sock The socket on which to connect to the SOCKS5 proxy.
779-
* @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
780-
* proxy to be established.
781-
* @param[out] outProxyConnectionFailed Whether or not the connection to the
782-
* SOCKS5 proxy failed.
783-
*
784-
* @returns Whether or not the operation succeeded.
785-
*/
786668
bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed)
787669
{
788670
// first connect to proxy server
@@ -806,17 +688,6 @@ bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int
806688
return true;
807689
}
808690

809-
/**
810-
* Parse and resolve a specified subnet string into the appropriate internal
811-
* representation.
812-
*
813-
* @param strSubnet A string representation of a subnet of the form `network
814-
* address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
815-
* `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
816-
* @param ret The resulting internal representation of a subnet.
817-
*
818-
* @returns Whether the operation succeeded or not.
819-
*/
820691
bool LookupSubNet(const std::string& strSubnet, CSubNet& ret, DNSLookupFn dns_lookup_function)
821692
{
822693
if (!ValidAsCString(strSubnet)) {

‎src/netbase.h

Lines changed: 137 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,18 +76,106 @@ std::vector<std::string> GetNetworkNames(bool append_unroutable = false);
7676
bool SetProxy(enum Network net, const proxyType &addrProxy);
7777
bool GetProxy(enum Network net, proxyType &proxyInfoOut);
7878
bool IsProxy(const CNetAddr &addr);
79+
/**
80+
* Set the name proxy to use for all connections to nodes specified by a
81+
* hostname. After setting this proxy, connecting to a node specified by a
82+
* hostname won't result in a local lookup of said hostname, rather, connect to
83+
* the node by asking the name proxy for a proxy connection to the hostname,
84+
* effectively delegating the hostname lookup to the specified proxy.
85+
*
86+
* This delegation increases privacy for those who set the name proxy as they no
87+
* longer leak their external hostname queries to their DNS servers.
88+
*
89+
* @returns Whether or not the operation succeeded.
90+
*
91+
* @note SOCKS5's support for UDP-over-SOCKS5 has been considered, but no SOCK5
92+
* server in common use (most notably Tor) actually implements UDP
93+
* support, and a DNS resolver is beyond the scope of this project.
94+
*/
7995
bool SetNameProxy(const proxyType &addrProxy);
8096
bool HaveNameProxy();
8197
bool GetNameProxy(proxyType &nameProxyOut);
8298

8399
using DNSLookupFn = std::function<std::vector<CNetAddr>(const std::string&, bool)>;
84100
extern DNSLookupFn g_dns_lookup;
85101

102+
/**
103+
* Resolve a host string to its corresponding network addresses.
104+
*
105+
* @param name The string representing a host. Could be a name or a numerical
106+
* IP address (IPv6 addresses in their bracketed form are
107+
* allowed).
108+
* @param[out] vIP The resulting network addresses to which the specified host
109+
* string resolved.
110+
*
111+
* @returns Whether or not the specified host string successfully resolved to
112+
* any resulting network addresses.
113+
*
114+
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
115+
* for additional parameter descriptions.
116+
*/
86117
bool LookupHost(const std::string& name, std::vector<CNetAddr>& vIP, unsigned int nMaxSolutions, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
118+
119+
/**
120+
* Resolve a host string to its first corresponding network address.
121+
*
122+
* @see LookupHost(const std::string&, std::vector<CNetAddr>&, unsigned int, bool, DNSLookupFn)
123+
* for additional parameter descriptions.
124+
*/
87125
bool LookupHost(const std::string& name, CNetAddr& addr, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
88-
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
126+
127+
/**
128+
* Resolve a service string to its corresponding service.
129+
*
130+
* @param name The string representing a service. Could be a name or a
131+
* numerical IP address (IPv6 addresses should be in their
132+
* disambiguated bracketed form), optionally followed by a port
133+
* number. (e.g. example.com:8333 or
134+
* [2001:db8:85a3:8d3:1319:8a2e:370:7348]:420)
135+
* @param[out] vAddr The resulting services to which the specified service string
136+
* resolved.
137+
* @param portDefault The default port for resulting services if not specified
138+
* by the service string.
139+
* @param fAllowLookup Whether or not hostname lookups are permitted. If yes,
140+
* external queries may be performed.
141+
* @param nMaxSolutions The maximum number of results we want, specifying 0
142+
* means "as many solutions as we get."
143+
*
144+
* @returns Whether or not the service string successfully resolved to any
145+
* resulting services.
146+
*/
89147
bool Lookup(const std::string& name, std::vector<CService>& vAddr, int portDefault, bool fAllowLookup, unsigned int nMaxSolutions, DNSLookupFn dns_lookup_function = g_dns_lookup);
148+
149+
/**
150+
* Resolve a service string to its first corresponding service.
151+
*
152+
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
153+
* for additional parameter descriptions.
154+
*/
155+
bool Lookup(const std::string& name, CService& addr, int portDefault, bool fAllowLookup, DNSLookupFn dns_lookup_function = g_dns_lookup);
156+
157+
/**
158+
* Resolve a service string with a numeric IP to its first corresponding
159+
* service.
160+
*
161+
* @returns The resulting CService if the resolution was successful, [::]:0 otherwise.
162+
*
163+
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
164+
* for additional parameter descriptions.
165+
*/
90166
CService LookupNumeric(const std::string& name, int portDefault = 0, DNSLookupFn dns_lookup_function = g_dns_lookup);
167+
168+
/**
169+
* Parse and resolve a specified subnet string into the appropriate internal
170+
* representation.
171+
*
172+
* @param strSubnet A string representation of a subnet of the form `network
173+
* address [ "/", ( CIDR-style suffix | netmask ) ]`(e.g.
174+
* `2001:db8::/32`, `192.0.2.0/255.255.255.0`, or `8.8.8.8`).
175+
* @param ret The resulting internal representation of a subnet.
176+
*
177+
* @returns Whether the operation succeeded or not.
178+
*/
91179
bool LookupSubNet(const std::string& strSubnet, CSubNet& subnet, DNSLookupFn dns_lookup_function = g_dns_lookup);
92180

93181
/**
@@ -102,14 +190,61 @@ std::unique_ptr<Sock> CreateSockTCP(const CService& address_family);
102190
*/
103191
extern std::function<std::unique_ptr<Sock>(const CService&)> CreateSock;
104192

105-
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, int nTimeout, bool manual_connection);
193+
/**
194+
* Try to connect to the specified service on the specified socket.
195+
*
196+
* @param addrConnect The service to which to connect.
197+
* @param hSocket The socket on which to connect.
198+
* @param nTimeout Wait this many milliseconds for the connection to be
199+
* established.
200+
* @param manual_connection Whether or not the connection was manually requested
201+
* (e.g. through the addnode RPC)
202+
*
203+
* @returns Whether or not a connection was successfully made.
204+
*/
205+
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocket, int nTimeout, bool manual_connection);
206+
207+
/**
208+
* Connect to a specified destination service through a SOCKS5 proxy by first
209+
* connecting to the SOCKS5 proxy.
210+
*
211+
* @param proxy The SOCKS5 proxy.
212+
* @param strDest The destination service to which to connect.
213+
* @param port The destination port.
214+
* @param sock The socket on which to connect to the SOCKS5 proxy.
215+
* @param nTimeout Wait this many milliseconds for the connection to the SOCKS5
216+
* proxy to be established.
217+
* @param[out] outProxyConnectionFailed Whether or not the connection to the
218+
* SOCKS5 proxy failed.
219+
*
220+
* @returns Whether or not the operation succeeded.
221+
*/
106222
bool ConnectThroughProxy(const proxyType& proxy, const std::string& strDest, int port, const Sock& sock, int nTimeout, bool& outProxyConnectionFailed);
223+
107224
/** Disable or enable blocking-mode for a socket */
108225
bool SetSocketNonBlocking(const SOCKET& hSocket, bool fNonBlocking);
109226
/** Set the TCP_NODELAY flag on a socket */
110227
bool SetSocketNoDelay(const SOCKET& hSocket);
111228
void InterruptSocks5(bool interrupt);
112229

230+
/**
231+
* Connect to a specified destination service through an already connected
232+
* SOCKS5 proxy.
233+
*
234+
* @param strDest The destination fully-qualified domain name.
235+
* @param port The destination port.
236+
* @param auth The credentials with which to authenticate with the specified
237+
* SOCKS5 proxy.
238+
* @param sock The SOCKS5 proxy socket.
239+
*
240+
* @returns Whether or not the operation succeeded.
241+
*
242+
* @note The specified SOCKS5 proxy socket must already be connected to the
243+
* SOCKS5 proxy.
244+
*
245+
* @see <a href="https://www.ietf.org/rfc/rfc1928.txt">RFC1928: SOCKS Protocol
246+
* Version 5</a>
247+
*/
113248
bool Socks5(const std::string& strDest, int port, const ProxyCredentials* auth, const Sock& socket);
114249

115250
#endif // BITCOIN_NETBASE_H

0 commit comments

Comments
 (0)