Skip to content

Commit e6bd74b

Browse files
jonatackjonatack
committed
net: move Doxygen docs from netbase.cpp to netbase.h
1 parent 12cc570 commit e6bd74b

File tree

2 files changed

+136
-129
lines changed

2 files changed

+136
-129
lines changed

‎src/netbase.cpp

Lines changed: 0 additions & 128 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 std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
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, DNSLookupFn)
203-
* for 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 std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
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,15 +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 otherwise.
281-
*
282-
* @see Lookup(const std::string&, std::vector<CService>&, int, bool, unsigned int, DNSLookupFn)
283-
* for additional parameter descriptions.
284-
*/
285229
CService LookupNumeric(const std::string& name, int portDefault, DNSLookupFn dns_lookup_function)
286230
{
287231
if (!ValidAsCString(name)) {
@@ -419,24 +363,6 @@ static std::string Socks5ErrorString(uint8_t err)
419363
}
420364
}
421365

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

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

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

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

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

‎src/netbase.h

Lines changed: 136 additions & 1 deletion
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

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+
*/
105205
bool ConnectSocketDirectly(const CService &addrConnect, const SOCKET& hSocketRet, 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)