Index · Object → RefCounted → UPNP

UPNP

Universal Plug and Play (UPnP) functions for network device discovery, querying and port forwarding.

Class Description

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 != UPNP.UPNP_RESULT_SUCCESS:
		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(UPNP.UPNP_RESULT_SUCCESS)

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.

Properties

var discover_ipv6: bool = false

If true, IPv6 is used for UPNPDevice discovery.

var discover_local_port: int = 0

If 0, the local port to use for discovery is chosen automatically by the system. If 1, discovery will be done from the source port 1900 (same as destination port). Otherwise, the value will be used as the port.

var discover_multicast_if: String = ""

Multicast interface to use for discovery. Uses the default multicast interface if empty.

Methods

func add_device(device: UPNPDevice) -> void

Adds the given UPNPDevice to the list of discovered devices.

func add_port_mapping(port: int, port_internal: int = 0, desc: String = "", proto: String = "UDP", duration: int = 0) -> int

Adds a mapping to forward the external port (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see get_gateway()) to the port_internal on the local machine for the given protocol proto (either "TCP" or "UDP", with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with get_gateway() and call add_port_mapping() on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device.

Depending on the gateway device, if a mapping for that port already exists, it will either be updated or it will refuse this command due to that conflict, especially if the existing mapping for that port wasn't created via UPnP or points to a different network address (or device) than this one.

If port_internal is 0 (the default), the same port number is used for both the external and the internal port (the port value).

The description (desc) is shown in some routers management UIs and can be used to point out which application added the mapping.

The mapping's lease duration can be limited by specifying a duration in seconds. The default of 0 means no duration, i.e. a permanent lease and notably some devices only support these permanent leases. Note that whether permanent or not, this is only a request and the gateway may still decide at any point to remove the mapping (which usually happens on a reboot of the gateway, when its external IP address changes, or on some models when it detects a port mapping has become inactive, i.e. had no traffic for multiple minutes). If not 0 (permanent), the allowed range according to spec is between 120 (2 minutes) and 86400 seconds (24 hours).

See UPNPResult for possible return values.

func clear_devices() -> void

Clears the list of discovered devices.

func delete_port_mapping(port: int, proto: String = "UDP") -> int

Deletes the port mapping for the given port and protocol combination on the default gateway (see get_gateway()) if one exists. port must be a valid port between 1 and 65535, proto can be either "TCP" or "UDP". May be refused for mappings pointing to addresses other than this one, for well-known ports (below 1024), or for mappings not added via UPnP. See UPNPResult for possible return values.

func discover(timeout: int = 2000, ttl: int = 2, device_filter: String = "InternetGatewayDevice") -> int

Discovers local UPNPDevices. Clears the list of previously discovered devices.

Filters for IGD (InternetGatewayDevice) type devices by default, as those manage port forwarding. timeout is the time to wait for responses in milliseconds. ttl is the time-to-live; only touch this if you know what you're doing.

See UPNPResult for possible return values.

func get_device(index: int) -> UPNPDevice

Returns the UPNPDevice at the given index.

func get_device_count() -> int

Returns the number of discovered UPNPDevices.

func get_gateway() -> UPNPDevice

Returns the default gateway. That is the first discovered UPNPDevice that is also a valid IGD (InternetGatewayDevice).

func query_external_address() -> String

Returns the external IP address of the default gateway (see get_gateway()) as string. Returns an empty string on error.

func remove_device(index: int) -> void

Removes the device at index from the list of discovered devices.

func set_device(index: int, device: UPNPDevice) -> void

Sets the device at index from the list of discovered devices to device.

Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum UPNPResult
UPNP_RESULT_SUCCESS = 0

UPNP command or discovery was successful.

UPNP_RESULT_NOT_AUTHORIZED = 1

Not authorized to use the command on the UPNPDevice. May be returned when the user disabled UPNP on their router.

UPNP_RESULT_PORT_MAPPING_NOT_FOUND = 2

No port mapping was found for the given port, protocol combination on the given UPNPDevice.

UPNP_RESULT_INCONSISTENT_PARAMETERS = 3

Inconsistent parameters.

UPNP_RESULT_NO_SUCH_ENTRY_IN_ARRAY = 4

No such entry in array. May be returned if a given port, protocol combination is not found on a UPNPDevice.

UPNP_RESULT_ACTION_FAILED = 5

The action failed.

UPNP_RESULT_SRC_IP_WILDCARD_NOT_PERMITTED = 6

The UPNPDevice does not allow wildcard values for the source IP address.

UPNP_RESULT_EXT_PORT_WILDCARD_NOT_PERMITTED = 7

The UPNPDevice does not allow wildcard values for the external port.

UPNP_RESULT_INT_PORT_WILDCARD_NOT_PERMITTED = 8

The UPNPDevice does not allow wildcard values for the internal port.

UPNP_RESULT_REMOTE_HOST_MUST_BE_WILDCARD = 9

The remote host value must be a wildcard.

UPNP_RESULT_EXT_PORT_MUST_BE_WILDCARD = 10

The external port value must be a wildcard.

UPNP_RESULT_NO_PORT_MAPS_AVAILABLE = 11

No port maps are available. May also be returned if port mapping functionality is not available.

UPNP_RESULT_CONFLICT_WITH_OTHER_MECHANISM = 12

Conflict with other mechanism. May be returned instead of UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING if a port mapping conflicts with an existing one.

UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING = 13

Conflict with an existing port mapping.

UPNP_RESULT_SAME_PORT_VALUES_REQUIRED = 14

External and internal port values must be the same.

UPNP_RESULT_ONLY_PERMANENT_LEASE_SUPPORTED = 15

Only permanent leases are supported. Do not use the duration parameter when adding port mappings.

UPNP_RESULT_INVALID_GATEWAY = 16

Invalid gateway.

UPNP_RESULT_INVALID_PORT = 17

Invalid port.

UPNP_RESULT_INVALID_PROTOCOL = 18

Invalid protocol.

UPNP_RESULT_INVALID_DURATION = 19

Invalid duration.

UPNP_RESULT_INVALID_ARGS = 20

Invalid arguments.

UPNP_RESULT_INVALID_RESPONSE = 21

Invalid response.

UPNP_RESULT_INVALID_PARAM = 22

Invalid parameter.

UPNP_RESULT_HTTP_ERROR = 23

HTTP error.

UPNP_RESULT_SOCKET_ERROR = 24

Socket error.

UPNP_RESULT_MEM_ALLOC_ERROR = 25

Error allocating memory.

UPNP_RESULT_NO_GATEWAY = 26

No gateway available. You may need to call discover() first, or discovery didn't detect any valid IGDs (InternetGatewayDevices).

UPNP_RESULT_NO_DEVICES = 27

No devices available. You may need to call discover() first, or discovery didn't detect any valid UPNPDevices.

UPNP_RESULT_UNKNOWN_ERROR = 28

Unknown error.