Merge pull request #47398 from Faless/feature/network-local-port-salvaged

4 files changed, 64 insertions, 24 deletions

diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml
index d7cf6cc8c6..5d059ad3df 100644
--- a/doc/classes/PacketPeerUDP.xml
+++ b/doc/classes/PacketPeerUDP.xml
@@ -9,11 +9,27 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="bind">
+			<return type="int" enum="Error">
+			</return>
+			<argument index="0" name="port" type="int">
+			</argument>
+			<argument index="1" name="bind_address" type="String" default="&quot;*&quot;">
+			</argument>
+			<argument index="2" name="recv_buf_size" type="int" default="65536">
+			</argument>
+			<description>
+				Binds this [PacketPeerUDP] to the specified [code]port[/code] and [code]address[/code] with a buffer size [code]recv_buf_size[/code], allowing it to receive incoming packets.
+				If [code]address[/code] is set to [code]"*"[/code] (default), the peer will be bound on all available addresses (both IPv4 and IPv6).
+				If [code]address[/code] is set to [code]"0.0.0.0"[/code] (for IPv4) or [code]"::"[/code] (for IPv6), the peer will be bound to all available addresses matching that IP type.
+				If [code]address[/code] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc), the peer will only be bound to the interface with that addresses (or fail if no interface with the given address exists).
+			</description>
+		</method>
 		<method name="close">
 			<return type="void">
 			</return>
 			<description>
-				Closes the UDP socket the [PacketPeerUDP] is currently listening on.
+				Closes the [PacketPeerUDP]'s underlying UDP socket.
 			</description>
 		</method>
 		<method name="connect_to_host">
@@ -28,6 +44,13 @@
 				[b]Note:[/b] Connecting to the remote peer does not help to protect from malicious attacks like IP spoofing, etc. Think about using an encryption technique like SSL or DTLS if you feel like your application is transferring sensitive information.
 			</description>
 		</method>
+		<method name="get_local_port" qualifiers="const">
+			<return type="int">
+			</return>
+			<description>
+				Returns the local port to which this peer is bound.
+			</description>
+		</method>
 		<method name="get_packet_ip" qualifiers="const">
 			<return type="String">
 			</return>
@@ -42,18 +65,18 @@
 				Returns the port of the remote peer that sent the last packet(that was received with [method PacketPeer.get_packet] or [method PacketPeer.get_var]).
 			</description>
 		</method>
-		<method name="is_connected_to_host" qualifiers="const">
+		<method name="is_bound" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
-				Returns [code]true[/code] if the UDP socket is open and has been connected to a remote address. See [method connect_to_host].
+				Returns whether this [PacketPeerUDP] is bound to an address and can receive packets.
 			</description>
 		</method>
-		<method name="is_listening" qualifiers="const">
+		<method name="is_connected_to_host" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
-				Returns whether this [PacketPeerUDP] is listening.
+				Returns [code]true[/code] if the UDP socket is open and has been connected to a remote address. See [method connect_to_host].
 			</description>
 		</method>
 		<method name="join_multicast_group">
@@ -80,22 +103,6 @@
 				Removes the interface identified by [code]interface_name[/code] from the multicast group specified by [code]multicast_address[/code].
 			</description>
 		</method>
-		<method name="listen">
-			<return type="int" enum="Error">
-			</return>
-			<argument index="0" name="port" type="int">
-			</argument>
-			<argument index="1" name="bind_address" type="String" default="&quot;*&quot;">
-			</argument>
-			<argument index="2" name="recv_buf_size" type="int" default="65536">
-			</argument>
-			<description>
-				Makes this [PacketPeerUDP] listen on the [code]port[/code] binding to [code]bind_address[/code] with a buffer size [code]recv_buf_size[/code].
-				If [code]bind_address[/code] is set to [code]"*"[/code] (default), the peer will listen on all available addresses (both IPv4 and IPv6).
-				If [code]bind_address[/code] is set to [code]"0.0.0.0"[/code] (for IPv4) or [code]"::"[/code] (for IPv6), the peer will listen on all available addresses matching that IP type.
-				If [code]bind_address[/code] is set to any valid address (e.g. [code]"192.168.1.101"[/code], [code]"::1"[/code], etc), the peer will only listen on the interface with that addresses (or fail if no interface with the given address exists).
-			</description>
-		</method>
 		<method name="set_broadcast_enabled">
 			<return type="void">
 			</return>
@@ -122,7 +129,7 @@
 			<return type="int" enum="Error">
 			</return>
 			<description>
-				Waits for a packet to arrive on the listening port. See [method listen].
+				Waits for a packet to arrive on the bound address. See [method bind].
 				[b]Note:[/b] [method wait] can't be interrupted once it has been called. This can be worked around by allowing the other party to send a specific "death pill" packet like this:
 		[codeblocks]
 		[gdscript]
diff --git a/doc/classes/StreamPeerTCP.xml b/doc/classes/StreamPeerTCP.xml
index b6d91715ee..7b7c1d7426 100644
--- a/doc/classes/StreamPeerTCP.xml
+++ b/doc/classes/StreamPeerTCP.xml
@@ -9,6 +9,18 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="bind">
+			<return type="int" enum="Error">
+			</return>
+			<argument index="0" name="port" type="int">
+			</argument>
+			<argument index="1" name="host" type="String" default="&quot;*&quot;">
+			</argument>
+			<description>
+				Opens the TCP socket, and binds it to the specified local address.
+				This method is generally not needed, and only used to force the subsequent call to [method connect_to_host] to use the specified [code]host[/code] and [code]port[/code] as source address. This can be desired in some NAT punchthrough techniques, or when forcing the source network interface.
+			</description>
+		</method>
 		<method name="connect_to_host">
 			<return type="int" enum="Error">
 			</return>
@@ -17,7 +29,7 @@
 			<argument index="1" name="port" type="int">
 			</argument>
 			<description>
-				Connects to the specified [code]host:port[/code] pair. A hostname will be resolved if valid. Returns [constant OK] on success or [constant FAILED] on failure.
+				Connects to the specified [code]host:port[/code] pair. A hostname will be resolved if valid. Returns [constant OK] on success.
 			</description>
 		</method>
 		<method name="disconnect_from_host">
@@ -41,6 +53,13 @@
 				Returns the port of this peer.
 			</description>
 		</method>
+		<method name="get_local_port" qualifiers="const">
+			<return type="int">
+			</return>
+			<description>
+				Returns the local port to which this peer is bound.
+			</description>
+		</method>
 		<method name="get_status">
 			<return type="int" enum="StreamPeerTCP.Status">
 			</return>
diff --git a/doc/classes/TCP_Server.xml b/doc/classes/TCP_Server.xml
index 72e9ca923d..ec91d75d47 100644
--- a/doc/classes/TCP_Server.xml
+++ b/doc/classes/TCP_Server.xml
@@ -9,6 +9,13 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="get_local_port" qualifiers="const">
+			<return type="int">
+			</return>
+			<description>
+				Returns the local port this server is listening to.
+			</description>
+		</method>
 		<method name="is_connection_available" qualifiers="const">
 			<return type="bool">
 			</return>
diff --git a/doc/classes/UDPServer.xml b/doc/classes/UDPServer.xml
index 0fc00f67f8..6f3ccb8a17 100644
--- a/doc/classes/UDPServer.xml
+++ b/doc/classes/UDPServer.xml
@@ -123,6 +123,13 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="get_local_port" qualifiers="const">
+			<return type="int">
+			</return>
+			<description>
+				Returns the local port this server is listening to.
+			</description>
+		</method>
 		<method name="is_connection_available" qualifiers="const">
 			<return type="bool">
 			</return>
@@ -145,7 +152,7 @@
 			<argument index="1" name="bind_address" type="String" default="&quot;*&quot;">
 			</argument>
 			<description>
-				Starts the server by opening a UDP socket listening on the given port. You can optionally specify a [code]bind_address[/code] to only listen for packets sent to that address. See also [method PacketPeerUDP.listen].
+				Starts the server by opening a UDP socket listening on the given port. You can optionally specify a [code]bind_address[/code] to only listen for packets sent to that address. See also [method PacketPeerUDP.bind].
 			</description>
 		</method>
 		<method name="poll">