UPNP¶

UPNP 网络功能。

描述¶

提供 UPNP 功能来发现本地网络上的 UPNPDevice，并对它们执行指令，如管理端口映射（端口转发）和查询本地和远程网络 IP 地址。注意，这个类的方法是同步的，会阻塞调用线程。

要转发一个特定的端口：

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

要关闭一个特定的端口（例如，在你使用完它之后）：

upnp.delete_port_mapping(port)

注意：UPnP 发现会阻塞当前线程。要在不阻塞主线程的情况下执行发现，可以像这样使用 Thread：

# 当完成 UPnP 端口映射设置时发出（无论成功或失败）。
signal upnp_completed(error)

# 将其替换为您自己的服务器端口号（介于 1025 和 65535之间）。
const SERVER_PORT = 3928
var thread = null

func _upnp_setup(server_port):
    # UPNP 查询需要一些时间。
    var upnp = UPNP.new()
    var err = upnp.discover()

    if err != OK:
        push_error(str(err))
        emit_signal("upnp_completed", 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")
        emit_signal("upnp_completed", OK)

func _ready():
    thread = Thread.new()
    thread.start(self, "_upnp_setup", SERVER_PORT)

func _exit_tree():
    # 当线程正在运行时，在这里等待线程结束来处理游戏退出。
    thread.wait_to_finish()

属性¶

bool	discover_ipv6	`false`
int	discover_local_port	`0`
String	discover_multicast_if	`""`

方法¶

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 )

枚举¶

enum UPNPResult:

UPNP_RESULT_SUCCESS = 0 --- UPNP命令或发现成功。
UPNP_RESULT_NOT_AUTHORIZED = 1 --- 未授权在UPNPDevice上使用该命令。当用户在其路由器上禁用UPNP时，可能会被返回。
UPNP_RESULT_PORT_MAPPING_NOT_FOUND = 2 --- 在给定的UPNPDevice上没有找到给定端口、协议组合的端口映射。
UPNP_RESULT_INCONSISTENT_PARAMETERS = 3 --- 参数不一致。
UPNP_RESULT_NO_SUCH_ENTRY_IN_ARRAY = 4 --- 数组中没有此条目。如果在UPNPDevice上没有找到给定的端口、协议组合，可能会被返回。
UPNP_RESULT_ACTION_FAILED = 5 --- 操作失败。
UPNP_RESULT_SRC_IP_WILDCARD_NOT_PERMITTED = 6 --- UPNPDevice不允许源IP地址的通配符值。
UPNP_RESULT_EXT_PORT_WILDCARD_NOT_PERMITTED = 7 --- UPNPDevice不允许外部端口的通配符值。
UPNP_RESULT_INT_PORT_WILDCARD_NOT_PERMITTED = 8 --- UPNPDevice不允许内部端口的通配符值。
UPNP_RESULT_REMOTE_HOST_MUST_BE_WILDCARD = 9 --- 远程主机值必须是通配符。
UPNP_RESULT_EXT_PORT_MUST_BE_WILDCARD = 10 --- 外部端口值必须是通配符。
UPNP_RESULT_NO_PORT_MAPS_AVAILABLE = 11 --- 没有可用的端口映射。如果端口映射功能不可用，也可能被返回。
UPNP_RESULT_CONFLICT_WITH_OTHER_MECHANISM = 12 --- 与其他机制冲突。如果一个端口映射与现有的冲突，可能会被返回，而不是UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING。
UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING = 13 --- 与现有的端口映射相冲突。
UPNP_RESULT_SAME_PORT_VALUES_REQUIRED = 14 --- 外部和内部端口值必须相同。
UPNP_RESULT_ONLY_PERMANENT_LEASE_SUPPORTED = 15 --- 只支持永久租用。在添加端口映射时，不要使用duration参数。
UPNP_RESULT_INVALID_GATEWAY = 16 --- 无效网关。
UPNP_RESULT_INVALID_PORT = 17 --- 无效端口。
UPNP_RESULT_INVALID_PROTOCOL = 18 --- 无效协议。
UPNP_RESULT_INVALID_DURATION = 19 --- 无效持续时间。
UPNP_RESULT_INVALID_ARGS = 20 --- 无效参数。
UPNP_RESULT_INVALID_RESPONSE = 21 --- 无效响应。
UPNP_RESULT_INVALID_PARAM = 22 --- 无效参数。
UPNP_RESULT_HTTP_ERROR = 23 --- HTTP错误。
UPNP_RESULT_SOCKET_ERROR = 24 --- 套接字错误。
UPNP_RESULT_MEM_ALLOC_ERROR = 25 --- 分配内存时出错。
UPNP_RESULT_NO_GATEWAY = 26 --- 没有可用的网关。你可能需要先调用discover ，否则发现没有检测到任何有效的IGD（InternetGatewayDevices）。
UPNP_RESULT_NO_DEVICES = 27 --- 没有可用的设备。你可能需要先调用discover，或者发现没有检测到任何有效的UPNPDevice。
UPNP_RESULT_UNKNOWN_ERROR = 28 --- 未知错误。

属性说明¶

bool discover_ipv6

Default	`false`
Setter	set_discover_ipv6(value)
Getter	is_discover_ipv6()

如果true，则IPv6用于UPNPDevice发现。

int discover_local_port

Default	`0`
Setter	set_discover_local_port(value)
Getter	get_discover_local_port()

如果0，系统会自动选择用于发现的本地端口。如果1，将从源端口1900进行发现，注，与目的端口相同。否则，将使用该值作为端口。

String discover_multicast_if

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

用于发现的多播接口。如果为空，则使用默认的多播接口。

方法说明¶

void add_device ( UPNPDevice device )

将给定的 UPNPDevice 添加到已发现设备的列表中。

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

添加一个映射，将默认网关上的外部port，介于1和65535之间，转发到本地机器上的internal_port，用于指定协议proto，即TCP或UDP，默认为UDP。如果该网关设备上已经存在给定端口和协议组合的端口映射，该方法将尝试覆盖它。如果不希望这样，你可以用get_gateway手动检索该网关，如果有的话，就调用add_port_mapping。

如果internal_port是0（默认值），外部和内部端口都使用相同的端口号（port值）。

描述（desc）显示在一些路由器的UI中，可以用来指出是哪个应用添加了映射。可以通过指定duration（单位：秒）来限制映射的租用期限。然而，有些路由器与其中的个别不兼容，所以要谨慎使用，并在出错时添加回退逻辑，如果有疑问，可以在没有它们的情况下重试。

参阅get_gateway。参阅UPNPResult，了解可能的返回值。

void clear_devices ( )

清除已发现设备的列表。

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

删除默认网关上给定端口和协议组合的端口映射，如果存在的话。port必须是1到65535之间的有效端口，proto可以是TCP或UDP。可能的返回值，参阅UPNPResult。参阅get_gateway。

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

发现本地的UPNPDevice。清除先前发现的设备的列表。

默认情况下过滤IGD（InternetGatewayDevice）类型的设备，因为这些设备管理端口转发。timeout 是等待响应的时间，单位是毫秒。ttl是生存时间；只有在你了解在做什么的情况下才会遇到这个。

参阅UPNPResult了解可能的返回值。

UPNPDevice get_device ( int index ) const

返回给定index处的UPNPDevice。

int get_device_count ( ) const

返回已发现的UPNPDevice的数量。

UPNPDevice get_gateway ( ) const

返回默认网关。这是第一个发现的UPNPDevice，也是一个有效的IGD（InternetGatewayDevice）。

String query_external_address ( ) const

返回默认网关的外部IP地址字符串。错误时返回一个空字符串。参阅get_gateway。

void remove_device ( int index )

将index处的设备从已发现的设备列表中移除。

void set_device ( int index, UPNPDevice device )

将index处的设备从已发现的设备列表中设置为device。