UPNP

Inherits: Reference < Object

UPNP network functions.

Description

Provides UPNP functionality to discover UPNPDevices on the local network and execute commands on them, like managing port mappings (port forwarding) 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:

const PORT = 7777
var upnp = UPNP.new()
upnp.discover(2000, 2, "InternetGatewayDevice")
upnp.add_port_mapping(port)

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

upnp.delete_port_mapping(port)

Properties

bool	discover_ipv6	false
int	discover_local_port	0
String	discover_multicast_if	""

Methods

void	add_device ( UPNPDevice device )
int	add_port_mapping ( int port, int port_internal=0, String desc="", String proto="UDP", int duration=0 ) const
void	clear_devices ( )
int	delete_port_mapping ( int port, String proto="UDP" ) const
int	discover ( int timeout=2000, int ttl=2, String device_filter="InternetGatewayDevice" )
UPNPDevice	get_device ( int index ) const
int	get_device_count ( ) const
UPNPDevice	get_gateway ( ) const
String	query_external_address ( ) const
void	remove_device ( int index )
void	set_device ( int index, UPNPDevice device )

Enumerations

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 an 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.

Property Descriptions

bool discover_ipv6

Default	false
Setter	set_discover_ipv6(value)
Getter	is_discover_ipv6()

If true, IPv6 is used for UPNPDevice discovery.

int discover_local_port

Default	0
Setter	set_discover_local_port(value)
Getter	get_discover_local_port()

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.

String discover_multicast_if

Default	""
Setter	set_discover_multicast_if(value)
Getter	get_discover_multicast_if()

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

Method Descriptions

void add_device ( UPNPDevice device )

Adds the given UPNPDevice to the list of discovered devices.

int add_port_mapping ( int port, int port_internal=0, String desc="", String proto="UDP", int duration=0 ) const

Adds a mapping to forward the external port (between 1 and 65535) on the default gateway (see get_gateway) to the internal_port 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.

If internal_port 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 router 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). However, some routers are incompatible with one or both of these, so use with caution and add fallback logic in case of errors to retry without them if in doubt.

See UPNPResult for possible return values.

void clear_devices ( )

Clears the list of discovered devices.

int delete_port_mapping ( int port, String proto="UDP" ) const

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. See UPNPResult for possible return values.

int discover ( int timeout=2000, int ttl=2, String device_filter="InternetGatewayDevice" )

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.

UPNPDevice get_device ( int index ) const

Returns the UPNPDevice at the given index.

int get_device_count ( ) const

Returns the number of discovered UPNPDevices.

UPNPDevice get_gateway ( ) const

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

String query_external_address ( ) const

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

void remove_device ( int index )

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

void set_device ( int index, UPNPDevice device )

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