net.tomp2p.upnp
Class InternetGatewayDevice

java.lang.Object
  net.tomp2p.upnp.InternetGatewayDevice

public class InternetGatewayDevice
extends Object

This class can be used to access some functionalities on the InternetGatewayDevice on your network without having to know anything about the required input/output parameters. All device functions are not provided.

Version:

1.0

Author:

SuperBonBon

Method Summary

boolean	addPortMapping(String description, String protocol, String internalHost, int externalPort, int internalPort)
boolean	addPortMapping(String description, String protocol, String remoteHost, int externalPort, String internalClient, int internalPort, int leaseDuration) Configures a nat entry on the UPNP device.
boolean	deletePortMapping(String remoteHost, int externalPort, String protocol) Deletes a port mapping on the IDG device
static Collection<InternetGatewayDevice>	getDevices(int timeout) Lookup all the IGD (IP or PPP) devices on the network.
static Collection<InternetGatewayDevice>	getDevices(int timeout, int ttl, int mx, NetworkInterface ni) Lookup all the IGD (IP urn:schemas-upnp-org:service:WANIPConnection:1, or PPP urn:schemas-upnp-org:service:WANPPPConnection:1) devices for a given network interface.
String	getExternalIPAddress() Retrieves the external IP address
ActionResponse	getGenericPortMappingEntry(int newPortMappingIndex) Retrieves a generic port mapping entry.
RootDevice	getIGDRootDevice() Retrieves the IDG UNPNRootDevice object
Integer	getNatMappingsCount() Retrieves the current number of mapping in the NAT table
ActionResponse	getSpecificPortMappingEntry(String remoteHost, int externalPort, String protocol) Retrieves information about a specific port mapping

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getIGDRootDevice

public RootDevice getIGDRootDevice()

Retrieves the IDG UNPNRootDevice object

Returns:

the UNPNRootDevie object bound to this object

getDevices

public static Collection<InternetGatewayDevice> getDevices(int timeout)
                                                    throws IOException

Lookup all the IGD (IP or PPP) devices on the network. If a device implements both IP and PPP, the active service will be used for nat mappings.

Parameters:

timeout - the timeout in ms to listen for devices response, -1 for default value

Returns:

an array of devices to play with or null if nothing found.

Throws:

IOException - if some IO Exception occurs during discovery

getDevices

public static Collection<InternetGatewayDevice> getDevices(int timeout,
                                                           int ttl,
                                                           int mx,
                                                           NetworkInterface ni)
                                                    throws IOException

Lookup all the IGD (IP urn:schemas-upnp-org:service:WANIPConnection:1, or PPP urn:schemas-upnp-org:service:WANPPPConnection:1) devices for a given network interface. If a device implements both IP and PPP, the active service will be used for nat mappings.

Parameters:

timeout - the timeout in ms to listen for devices response, -1 for default value

ttl - the discovery ttl such as Discovery.DEFAULT_TTL

mx - the discovery mx such as Discovery.DEFAULT_MX

ni - the network interface where to lookup IGD devices

Returns:

an array of devices to play with or null if nothing found.

Throws:

IOException - if some IO Exception occurs during discovery

getExternalIPAddress

public String getExternalIPAddress()
                            throws UPNPResponseException,
                                   IOException

Retrieves the external IP address

Returns:

a String representing the external IP

Throws:

UPNPResponseException - if the devices returns an error code

IOException - if some error occurs during communication with the device

getGenericPortMappingEntry

public ActionResponse getGenericPortMappingEntry(int newPortMappingIndex)
                                          throws IOException,
                                                 UPNPResponseException

Retrieves a generic port mapping entry.

Parameters:

newPortMappingIndex - the index to lookup in the nat table of the upnp device

Returns:

an action response Object containing the following fields : NewRemoteHost, NewExternalPort, NewProtocol, NewInternalPort, NewInternalClient, NewEnabled, NewPortMappingDescription, NewLeaseDuration or null if the index does not exists

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if some unexpected error occurs on the UPNP device

getSpecificPortMappingEntry

public ActionResponse getSpecificPortMappingEntry(String remoteHost,
                                                  int externalPort,
                                                  String protocol)
                                           throws IOException,
                                                  UPNPResponseException

Retrieves information about a specific port mapping

Parameters:

remoteHost - the remote host ip to check, null if wildcard

externalPort - the port to check

protocol - the protocol for the mapping, either TCP or UDP

Returns:

an action response Object containing the following fields : NewInternalPort, NewInternalClient, NewEnabled, NewPortMappingDescription, NewLeaseDuration or null if no such entry exists in the device NAT table

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if some unexpected error occurs on the UPNP device

addPortMapping

public boolean addPortMapping(String description,
                              String protocol,
                              String internalHost,
                              int externalPort,
                              int internalPort)
                       throws IOException,
                              UPNPResponseException

Throws:

IOException

UPNPResponseException

addPortMapping

public boolean addPortMapping(String description,
                              String protocol,
                              String remoteHost,
                              int externalPort,
                              String internalClient,
                              int internalPort,
                              int leaseDuration)
                       throws IOException,
                              UPNPResponseException

Configures a nat entry on the UPNP device.

Parameters:

description - the mapping description, null for no description

protocol - the protocol, either TCP or UDP

remoteHost - the remote host ip for this entry, null for a wildcard value

externalPort - the external port to open on the UPNP device an map on the internal client, 0 for a wildcard value

internalClient - the internal client ip where data should be redirected

internalPort - the internal client port where data should be redirected

leaseDuration - the lease duration in seconds 0 for an infinite time

Returns:

true if the port is mapped false if the mapping is already done for another internal client

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if the device does not accept some settings :
402 Invalid Args See UPnP Device Architecture section on Control
501 Action Failed See UPnP Device Architecture section on Control
715 WildCardNotPermittedInSrcIP The source IP address cannot be wild-carded
716 WildCardNotPermittedInExtPort The external port cannot be wild-carded
724 SamePortValuesRequired Internal and External port values must be the same
725 OnlyPermanentLeasesSupported The NAT implementation only supports permanent lease times on port mappings
726 RemoteHostOnlySupportsWildcard RemoteHost must be a wildcard and cannot be a specific IP address or DNS name
727 ExternalPortOnlySupportsWildcard ExternalPort must be a wildcard and cannot be a specific port value

deletePortMapping

public boolean deletePortMapping(String remoteHost,
                                 int externalPort,
                                 String protocol)
                          throws IOException,
                                 UPNPResponseException

Deletes a port mapping on the IDG device

Parameters:

remoteHost - the host ip for which the mapping was done, null value for a wildcard value

externalPort - the port to close

protocol - the protocol for the mapping, TCP or UDP

Returns:

true if the port has been unmapped correctly otherwise false ( entry does not exists ).

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if the devices returns an error message

getNatMappingsCount

public Integer getNatMappingsCount()
                            throws IOException,
                                   UPNPResponseException

Retrieves the current number of mapping in the NAT table

Returns:

the nat table current number of mappings or null if the device does not allow to query state variables

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if the devices returns an error message with error code other than 404