net.sbbi.upnp.impls
Class InternetGatewayDevice

java.lang.Object
  net.sbbi.upnp.impls.InternetGatewayDevice

public class InternetGatewayDevice
extends Object

This class can be used to access some funtionalities 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

Constructor Summary

InternetGatewayDevice(UPNPRootDevice igd)

Method Summary

boolean	addPortMapping(String description, String remoteHost, int internalPort, int externalPort, String internalClient, int leaseDuration, String protocol) 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 InternetGatewayDevice[]	getDevices(int timeout) Lookup all the IGD (IP or PPP) devices on the network.
static 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() Retreives the external IP address
ActionResponse	getGenericPortMappingEntry(int newPortMappingIndex) Retreives a generic port mapping entry.
UPNPRootDevice	getIGDRootDevice() Retreives the IDG UNPNRootDevice object
static InternetGatewayDevice[]	getIPDevices(int timeout) Deprecated. use generic getDevices(int) or getDevices(int, int, int, NetworkInterface) methods since this one is not usable with all IGD devices ( will only work with devices implementing the urn:schemas-upnp-org:service:WANIPConnection:1 service )
Integer	getNatMappingsCount() Retreives the current number of mapping in the NAT table
Integer	getNatTableSize() Computes the total entries in avaliable in the nat table size, not that this method is not guaranteed to work with all upnp devices since it is not an generic IGD command
static InternetGatewayDevice[]	getPPPDevices(int timeout) Deprecated. use generic getDevices(int) or getDevices(int, int, int, NetworkInterface) methods since this one is not usable with all IGD devices ( will only work with devices implementing the urn:schemas-upnp-org:service:WANPPPConnection:1 service )
ActionResponse	getSpecificPortMappingEntry(String remoteHost, int externalPort, String protocol) Retreives information about a specific port mapping

Methods inherited from class java.lang.Object

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

Constructor Detail

InternetGatewayDevice

public InternetGatewayDevice(UPNPRootDevice igd)
                      throws UnsupportedOperationException

Throws:

UnsupportedOperationException

Method Detail

getIGDRootDevice

public UPNPRootDevice getIGDRootDevice()

Retreives the IDG UNPNRootDevice object

Returns:

the UNPNRootDevie object bound to this object

getDevices

public static 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 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

getIPDevices

public static InternetGatewayDevice[] getIPDevices(int timeout)
                                            throws IOException

Deprecated. use generic getDevices(int) or getDevices(int, int, int, NetworkInterface) methods since this one is not usable with all IGD devices ( will only work with devices implementing the urn:schemas-upnp-org:service:WANIPConnection:1 service )

Lookup all the IGD IP devices on the network (urn:schemas-upnp-org:service:WANIPConnection:1 service)

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 or if found devices do not have the urn:schemas-upnp-org:service:WANIPConnection:1 service

Throws:

IOException

getPPPDevices

public static InternetGatewayDevice[] getPPPDevices(int timeout)
                                             throws IOException

Deprecated. use generic getDevices(int) or getDevices(int, int, int, NetworkInterface) methods since this one is not usable with all IGD devices ( will only work with devices implementing the urn:schemas-upnp-org:service:WANPPPConnection:1 service )

Lookup all the IGD PPP devices on the network (urn:schemas-upnp-org:service:WANPPPConnection:1 service)

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 or if found devices do not have the urn:schemas-upnp-org:service:WANPPPConnection:1 service

Throws:

IOException

getExternalIPAddress

public String getExternalIPAddress()
                            throws UPNPResponseException,
                                   IOException

Retreives 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

Retreives 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

Retreives 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 remoteHost,
                              int internalPort,
                              int externalPort,
                              String internalClient,
                              int leaseDuration,
                              String protocol)
                       throws IOException,
                              UPNPResponseException

Configures a nat entry on the UPNP device.

Parameters:

description - the mapping description, null for no description

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

internalPort - the internal client port where data should be redirected

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

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

protocol - the protocol, either TCP or UDP

Returns:

true if the port is mapped false if the mapping is allready 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

Retreives 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

getNatTableSize

public Integer getNatTableSize()
                        throws IOException,
                               UPNPResponseException

Computes the total entries in avaliable in the nat table size, not that this method is not guaranteed to work with all upnp devices since it is not an generic IGD command

Returns:

the number of entries or null if the NAT table size cannot be computed for the device

Throws:

IOException - if some error occurs during communication with the device

UPNPResponseException - if the devices returns an error message with error code other than 713 or 402