Struct Upnp

pub struct Upnp { /* private fields */ }

Expand description

Godot class UPNP.

Inherits RefCounted.

Related symbols:

upnp: sidecar module with related enum/flag types
IUpnp: virtual methods

§Construction

This class is reference-counted. You can create a new instance using Upnp::new_gd().

§Godot docs

This class can be used to discover compatible UPNPDevices on the local network and execute commands on them, like managing port mappings (for port forwarding/NAT traversal) and querying the local and remote network IP address. Note that methods on this class are synchronous and block the calling thread.

To forward a specific port (here 7777, note both discover and add_port_mapping can return errors that should be checked):

var upnp = UPNP.new()
upnp.discover()
upnp.add_port_mapping(7777)

To close a specific port (e.g. after you have finished using it):

upnp.delete_port_mapping(port)

Note: UPnP discovery blocks the current thread. To perform discovery without blocking the main thread, use Threads like this:

# Emitted when UPnP port mapping setup is completed (regardless of success or failure).
signal upnp_completed(error)

# Replace this with your own server port number between 1024 and 65535.
const SERVER_PORT = 3928
var thread = null

func _upnp_setup(server_port):
	# UPNP queries take some time.
	var upnp = UPNP.new()
	var err = upnp.discover()

	if err != OK:
		push_error(str(err))
		upnp_completed.emit(err)
		return

	if upnp.get_gateway() and upnp.get_gateway().is_valid_gateway():
		upnp.add_port_mapping(server_port, server_port, ProjectSettings.get_setting("application/config/name"), "UDP")
		upnp.add_port_mapping(server_port, server_port, ProjectSettings.get_setting("application/config/name"), "TCP")
		upnp_completed.emit(OK)

func _ready():
	thread = Thread.new()
	thread.start(_upnp_setup.bind(SERVER_PORT))

func _exit_tree():
	# Wait for thread finish here to handle game exit while the thread is running.
	thread.wait_to_finish()

Terminology: In the context of UPnP networking, “gateway” (or “internet gateway device”, short IGD) refers to network devices that allow computers in the local network to access the internet (“wide area network”, WAN). These gateways are often also called “routers”.

Pitfalls:

As explained above, these calls are blocking and shouldn’t be run on the main thread, especially as they can block for multiple seconds at a time. Use threading!
Networking is physical and messy. Packets get lost in transit or get filtered, addresses, free ports and assigned mappings change, and devices may leave or join the network at any time. Be mindful of this, be diligent when checking and handling errors, and handle these gracefully if you can: add clear error UI, timeouts and re-try handling.
Port mappings may change (and be removed) at any time, and the remote/external IP address of the gateway can change likewise. You should consider re-querying the external IP and try to update/refresh the port mapping periodically (for example, every 5 minutes and on networking failures).
Not all devices support UPnP, and some users disable UPnP support. You need to handle this (e.g. documenting and requiring the user to manually forward ports, or adding alternative methods of NAT traversal, like a relay/mirror server, or NAT hole punching, STUN/TURN, etc.).
Consider what happens on mapping conflicts. Maybe multiple users on the same network would like to play your game at the same time, or maybe another application uses the same port. Make the port configurable, and optimally choose a port automatically (re-trying with a different port on failure).

Further reading: If you want to know more about UPnP (and the Internet Gateway Device (IGD) and Port Control Protocol (PCP) specifically), Wikipedia is a good first stop, the specification can be found at the Open Connectivity Foundation and Godot’s implementation is based on the MiniUPnP client.

Implementations§

§

impl Upnp

pub fn get_device_count(&self) -> i32

pub fn get_device(&self, index: i32) -> Option<Gd<UpnpDevice>>

pub fn add_device(&mut self, device: impl AsArg<Option<Gd<UpnpDevice>>>)

pub fn set_device( &mut self, index: i32, device: impl AsArg<Option<Gd<UpnpDevice>>>, )

pub fn remove_device(&mut self, index: i32)

pub fn clear_devices(&mut self)

pub fn get_gateway(&self) -> Option<Gd<UpnpDevice>>

pub fn discover(&mut self) -> i32

To set the default parameters, use Self::discover_ex and its builder methods. See the book for detailed usage instructions.

pub fn discover_ex<'ex>(&'ex mut self) -> ExDiscover<'ex>

pub fn query_external_address(&self) -> GString

pub fn add_port_mapping(&self, port: i32) -> i32

To set the default parameters, use Self::add_port_mapping_ex and its builder methods. See the book for detailed usage instructions.

pub fn add_port_mapping_ex<'ex>(&'ex self, port: i32) -> ExAddPortMapping<'ex>

pub fn delete_port_mapping(&self, port: i32) -> i32

To set the default parameters, use Self::delete_port_mapping_ex and its builder methods. See the book for detailed usage instructions.

pub fn delete_port_mapping_ex<'ex>( &'ex self, port: i32, ) -> ExDeletePortMapping<'ex>

pub fn set_discover_multicast_if(&mut self, m_if: impl AsArg<GString>)

pub fn get_discover_multicast_if(&self) -> GString

pub fn set_discover_local_port(&mut self, port: i32)

pub fn get_discover_local_port(&self) -> i32

pub fn set_discover_ipv6(&mut self, ipv6: bool)

pub fn is_discover_ipv6(&self) -> bool

Methods from Deref<Target = RefCounted>§

pub fn get_reference_count(&self) -> i32

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

pub fn remove_meta(&mut self, name: impl AsArg<StringName>)

pub fn get_meta(&self, name: impl AsArg<StringName>) -> Variant

To set the default parameters, use Self::get_meta_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_meta_ex<'ex>( &'ex self, name: impl AsArg<StringName> + 'ex, ) -> ExGetMeta<'ex>

pub fn has_meta(&self, name: impl AsArg<StringName>) -> bool

pub fn get_meta_list(&self) -> Array<StringName>

pub fn add_user_signal(&mut self, signal: impl AsArg<GString>)

To set the default parameters, use Self::add_user_signal_ex and its builder methods. See the book for detailed usage instructions.

pub fn add_user_signal_ex<'ex>( &'ex mut self, signal: impl AsArg<GString> + 'ex, ) -> ExAddUserSignal<'ex>

pub fn has_user_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn remove_user_signal(&mut self, signal: impl AsArg<StringName>)

pub fn emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Error

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Error, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn set_deferred( &mut self, property: impl AsArg<StringName>, value: &Variant, )

pub fn callv( &mut self, method: impl AsArg<StringName>, arg_array: &AnyArray, ) -> Variant

pub fn has_method(&self, method: impl AsArg<StringName>) -> bool

pub fn get_method_argument_count(&self, method: impl AsArg<StringName>) -> i32

pub fn has_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn get_signal_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_signal_connection_list( &self, signal: impl AsArg<StringName>, ) -> Array<Dictionary<Variant, Variant>>

pub fn get_incoming_connections(&self) -> Array<Dictionary<Variant, Variant>>

pub fn disconnect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, )

pub fn is_connected( &self, signal: impl AsArg<StringName>, callable: &Callable, ) -> bool

pub fn has_connections(&self, signal: impl AsArg<StringName>) -> bool

pub fn set_block_signals(&mut self, enable: bool)

pub fn is_blocking_signals(&self) -> bool

pub fn notify_property_list_changed(&mut self)

pub fn set_message_translation(&mut self, enable: bool)

pub fn can_translate_messages(&self) -> bool

pub fn tr(&self, message: impl AsArg<StringName>) -> GString

To set the default parameters, use Self::tr_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_ex<'ex>(&'ex self, message: impl AsArg<StringName> + 'ex) -> ExTr<'ex>

pub fn tr_n( &self, message: impl AsArg<StringName>, plural_message: impl AsArg<StringName>, n: i32, ) -> GString

To set the default parameters, use Self::tr_n_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_n_ex<'ex>( &'ex self, message: impl AsArg<StringName> + 'ex, plural_message: impl AsArg<StringName> + 'ex, n: i32, ) -> ExTrN<'ex>

pub fn get_translation_domain(&self) -> StringName

pub fn set_translation_domain(&mut self, domain: impl AsArg<StringName>)

pub fn is_queued_for_deletion(&self) -> bool

pub fn cancel_free(&mut self)

pub fn notify(&mut self, what: ObjectNotification)

⚠️ Sends a Godot notification to all classes inherited by the object.

Triggers calls to on_notification(), and depending on the notification, also to Godot’s lifecycle callbacks such as ready().

Starts from the highest ancestor (the Object class) and goes down the hierarchy. See also Godot docs for Object::notification().

§Panics

If you call this method on a user-defined object while holding a GdRef or GdMut guard on the instance, you will encounter a panic. The reason is that the receiving virtual method on_notification() acquires a GdMut lock dynamically, which must be exclusive.