net.sbbi.upnp.impls
Class InternetGatewayDevice

java.lang.Object
  extended bynet.sbbi.upnp.impls.InternetGatewayDevice

public class InternetGatewayDevice
extends java.lang.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(java.lang.String description, java.lang.String remoteHost, int internalPort, int externalPort, java.lang.String internalClient, int leaseDuration, java.lang.String protocol)
          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()
          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 )
 java.lang.Integer getNatMappingsCount()
          Retreives the current number of mapping in the NAT table
 java.lang.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(java.lang.String remoteHost, int externalPort, java.lang.String protocol)
          Retreives information about a specific port mapping
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

InternetGatewayDevice

public InternetGatewayDevice(UPNPRootDevice igd)
                      throws java.lang.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 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

getIPDevices

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

getPPPDevices

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

getExternalIPAddress

public java.lang.String getExternalIPAddress()
                                      throws UPNPResponseException,
                                             java.io.IOException
Retreives 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
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:
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
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:
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 remoteHost,
                              int internalPort,
                              int externalPort,
                              java.lang.String internalClient,
                              int leaseDuration,
                              java.lang.String protocol)
                       throws java.io.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:
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
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:
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 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:
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


Copyright © 2005 SuperBonBon Industries. All Rights Reserved.