UPNP¶

Funciones de red de UPNP.

Descripción¶

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)

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 1025 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))
        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():
    # Wait for thread finish here to handle game exit while the thread is running.
    thread.wait_to_finish()

Propiedades¶

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

Métodos¶

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 )

Enumeraciones¶

enum UPNPResult:

UPNP_RESULT_SUCCESS = 0 --- El comando o descubrimiento de la UPNP fue exitoso.
UPNP_RESULT_NOT_AUTHORIZED = 1 --- No está autorizado a usar el comando en el UPNPDevice. Puede ser devuelto cuando el usuario deshabilite el UPNP en su router.
UPNP_RESULT_PORT_MAPPING_NOT_FOUND = 2 --- No se encontró ningún mapeo de puerto para la combinación de protocolos del UPNPDevice dado.
UPNP_RESULT_INCONSISTENT_PARAMETERS = 3 --- Parámetros inconsistentes.
UPNP_RESULT_NO_SUCH_ENTRY_IN_ARRAY = 4 --- No hay tal entrada en el array. Puede ser devuelto si un puerto dado, la combinación de protocolos no se encuentra en un UPNPDevice.
UPNP_RESULT_ACTION_FAILED = 5 --- La acción falló.
UPNP_RESULT_SRC_IP_WILDCARD_NOT_PERMITTED = 6 --- El UPNPDevice no permite valores comodín para la dirección IP de origen.
UPNP_RESULT_EXT_PORT_WILDCARD_NOT_PERMITTED = 7 --- El UPNPDevice no permite valores comodín para el puerto externo.
UPNP_RESULT_INT_PORT_WILDCARD_NOT_PERMITTED = 8 --- El UPNPDevice no permite valores comodín para el puerto interno.
UPNP_RESULT_REMOTE_HOST_MUST_BE_WILDCARD = 9 --- El valor del host remoto debe ser un comodín.
UPNP_RESULT_EXT_PORT_MUST_BE_WILDCARD = 10 --- El valor del puerto externo debe ser un comodín.
UPNP_RESULT_NO_PORT_MAPS_AVAILABLE = 11 --- No hay mapas de puertos disponibles. También puede ser devuelto si la funcionalidad de mapas de puertos no está disponible.
UPNP_RESULT_CONFLICT_WITH_OTHER_MECHANISM = 12 --- Conflicto con otro mecanismo. Puede ser devuelto en lugar de UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING si un mapeo de puertos entra en conflicto con uno existente.
UPNP_RESULT_CONFLICT_WITH_OTHER_MAPPING = 13 --- Conflicto con una mapeo de puertos existente.
UPNP_RESULT_SAME_PORT_VALUES_REQUIRED = 14 --- Los valores de los puertos externos e internos deben ser los mismos.
UPNP_RESULT_ONLY_PERMANENT_LEASE_SUPPORTED = 15 --- Sólo se admiten los arrendamientos permanentes. No utilice el parámetro duration cuando añada mapeos de puertos.
UPNP_RESULT_INVALID_GATEWAY = 16 --- Gateway invalida.
UPNP_RESULT_INVALID_PORT = 17 --- Puerto inválido.
UPNP_RESULT_INVALID_PROTOCOL = 18 --- Protocolo inválido.
UPNP_RESULT_INVALID_DURATION = 19 --- Duración inválida.
UPNP_RESULT_INVALID_ARGS = 20 --- Argumentos inválidos.
UPNP_RESULT_INVALID_RESPONSE = 21 --- Respuesta inválida.
UPNP_RESULT_INVALID_PARAM = 22 --- Parámetro inválido.
UPNP_RESULT_HTTP_ERROR = 23 --- Error HTTP.
UPNP_RESULT_SOCKET_ERROR = 24 --- Error de socket.
UPNP_RESULT_MEM_ALLOC_ERROR = 25 --- Error en la asignación de la memoria.
UPNP_RESULT_NO_GATEWAY = 26 --- No hay ninguna gateway disponible. Puede que tengas que llamar a discover primero, o el descubrimiento no detectó ningúna IGD (InternetGatewayDevices) válida.
UPNP_RESULT_NO_DEVICES = 27 --- No hay dispositivos disponibles. Puede que tengas que llamar a discover primero, o el descubrimiento no detectó ninguna UPNPDevice válida.
UPNP_RESULT_UNKNOWN_ERROR = 28 --- Error desconocido.

Descripciones de Propiedades¶

bool discover_ipv6

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

Si true, IPv6 se utiliza para el descubrimiento de UPNPDevice.

int discover_local_port

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

Si 0, el puerto local a utilizar para el descubrimiento es elegido automáticamente por el sistema. Si 1, el descubrimiento se hará desde el puerto de origen 1900 (el mismo que el puerto de destino). De lo contrario, el valor se utilizará como el puerto.

String discover_multicast_if

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

Interfaz de multidifusión para usar para el descubrimiento. Utiliza la interfaz de multidifusión predeterminada si está vacía.

Descripciones de Métodos¶

void add_device ( UPNPDevice device )

Añade el UPNPDevice dado a la lista de dispositivos descubiertos.

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

Añade un mapeo para reenviar el port externo (entre 1 y 65535) en la pasarela por defecto (ver get_gateway) al internal_port en la máquina local para el protocolo dado proto (ya sea TCP o UDP, siendo UDP el predeterminado). Si ya existe un mapeo de puertos para la combinación de puertos y protocolos dada en ese dispositivo de entrada, este método intenta sobrescribirlo. Si no se desea, se puede recuperar la pasarela manualmente con get_gateway y llamar a add_port_mapping en ella, si existe.

Si internal_port es 0 (el valor por defecto), se utiliza el mismo número de puerto tanto para el puerto externo como para el interno (el valor de port).

La descripción (desc) se muestra en algunas interfaces de routers y puede utilizarse para señalar qué aplicación añadió el mapeo. La duración del arrendamiento de la cartografía puede limitarse especificando una duración duration (en segundos). Sin embargo, algunos enrutadores son incompatibles con uno o ambos, por lo que hay que utilizarlos con precaución y añadir una lógica de reserva en caso de errores para volver a intentarlo sin ellos en caso de duda.

Véase UPNPResult para los posibles valores de retorno.

void clear_devices ( )

Borra la lista de dispositivos descubiertos.

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

Elimina la asignación de puertos para la combinación de puertos y protocolos dada en la pasarela por defecto (ver get_gateway) si existe. port debe ser un puerto válido entre 1 y 65535, proto puede ser TCP o UDP. Ver UPNPResult para los posibles valores de retorno.

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

Descubre los dispositivos locales UPNPDevice. Borra la lista de dispositivos descubiertos anteriormente.

Filtra los dispositivos de tipo IGD (InternetGatewayDevice) por defecto, ya que éstos gestionan el reenvío de puertos. timeout es el tiempo de espera de las respuestas en milisegundos. ttl es el tiempo de vida; sólo toca esto si sabes lo que estás haciendo.

Ver UPNPResult para los posibles valores de retorno.

UPNPDevice get_device ( int index ) const

Devuelve el UPNPDevice en el index dado.

int get_device_count ( ) const

Devuelve el número de UPNPDevice descubiertos.

UPNPDevice get_gateway ( ) const

Devuelve la puerta de enlace por defecto. Es el primer dispositivo descubierto UPNPDevice que también es un IGD (InternetGatewayDevice) válido.

String query_external_address ( ) const

Devuelve la dirección IP externa de la pasarela por defecto (ver get_gateway) como string. Devuelve una string vacía en caso de error.

void remove_device ( int index )

Elimina el dispositivo en el index de la lista de dispositivos descubiertos.

void set_device ( int index, UPNPDevice device )

Establece el dispositivo en index de la lista de dispositivos descubiertos a device.