net.sbbi.upnp.impls

Class InternetGatewayDevice

java.lang.Object

net.sbbi.upnp.impls.InternetGatewayDevice

public class InternetGatewayDevice
extends java.lang.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.

Method Summary

Modifier and Type	Method and Description
boolean	addPortMapping(java.lang.String description, java.lang.String protocol, java.lang.String remoteHost, int externalPort, java.lang.String internalClient, int internalPort, int leaseDuration) Configures a nat entry on the UPNP device.
boolean	deletePortMapping(java.lang.String remoteHost, int externalPort, java.lang.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, java.net.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.
java.lang.String	getExternalIPAddress() Retrieves the external IP address
ActionResponse	getGenericPortMappingEntry(int newPortMappingIndex) Retrieves a generic port mapping entry.
RootDevice	getIGDRootDevice() Retrieves the IDG UNPNRootDevice object
java.lang.Integer	getNatMappingsCount() Retrieves the current number of mapping in the NAT table
java.lang.Integer	getNatTableSize() Computes the total entries in available 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
ActionResponse	getSpecificPortMappingEntry(java.lang.String remoteHost, int externalPort, java.lang.String protocol) Retrieves information about a specific port mapping
static void	main(java.lang.String[] args)
static void	printDevices() Discovers and prints devices found on the local network

Methods inherited from class java.lang.Object

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

Method Detail

main

public static void main(java.lang.String[] args)

Parameters:

args -

printDevices

public static void printDevices()

Discovers and prints devices found on the local network

getIGDRootDevice

public RootDevice getIGDRootDevice()

Retrieves the IDG UNPNRootDevice object

Returns:

the UNPNRootDevie object bound to this object

getDevices

public static InternetGatewayDevice[] getDevices(int timeout)
                                          throws java.io.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:

java.io.IOException - if some IO Exception occurs during discovery

getDevices

public static InternetGatewayDevice[] getDevices(int timeout,
                                                 int ttl,
                                                 int mx,
                                                 java.net.NetworkInterface ni)
                                          throws java.io.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:

java.io.IOException - if some IO Exception occurs during discovery

getExternalIPAddress

public java.lang.String getExternalIPAddress()
                                      throws UPNPResponseException,
                                             java.io.IOException

Retrieves the external IP address

Returns:

a String representing the external IP

Throws:

UPNPResponseException - if the devices returns an error code

java.io.IOException - if some error occurs during communication with the device

getGenericPortMappingEntry

public ActionResponse getGenericPortMappingEntry(int newPortMappingIndex)
                                          throws java.io.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:

java.io.IOException - if some error occurs during communication with the device

UPNPResponseException - if some unexpected error occurs on the UPNP device

getSpecificPortMappingEntry

public ActionResponse getSpecificPortMappingEntry(java.lang.String remoteHost,
                                                  int externalPort,
                                                  java.lang.String protocol)
                                           throws java.io.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:

java.io.IOException - if some error occurs during communication with the device

UPNPResponseException - if some unexpected error occurs on the UPNP device

addPortMapping

public boolean addPortMapping(java.lang.String description,
                              java.lang.String protocol,
                              java.lang.String remoteHost,
                              int externalPort,
                              java.lang.String internalClient,
                              int internalPort,
                              int leaseDuration)
                       throws java.io.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:

java.io.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(java.lang.String remoteHost,
                                 int externalPort,
                                 java.lang.String protocol)
                          throws java.io.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:

java.io.IOException - if some error occurs during communication with the device

UPNPResponseException - if the devices returns an error message

getNatMappingsCount

public java.lang.Integer getNatMappingsCount()
                                      throws java.io.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:

java.io.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 java.lang.Integer getNatTableSize()
                                  throws java.io.IOException,
                                         UPNPResponseException

Computes the total entries in available 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:

java.io.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