Class 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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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