nattraverso/portmapper.py

   1 """
   2 Generic NAT Port mapping interface.
   3
   4 TODO: Example
   5
   6 @author: Raphael Slinckx
   7 @copyright: Copyright 2005
   8 @license: LGPL
   9 @contact: U{raphael@slinckx.net<mailto:raphael@slinckx.net>}
  10 @version: 0.1.0
  11 """
  12
  13 __revision__ = "$id"
  14
  15 from twisted.internet.base import BasePort
  16
  17 # Public API
  18 def get_port_mapper(proto="TCP"):
  19         """
  20         Returns a L{NATMapper} instance, suited to map a port for
  21         the given protocol. Defaults to TCP.
  22
  23         For the moment, only upnp mapper is available. It accepts both UDP and TCP.
  24
  25         @param proto: The protocol: 'TCP' or 'UDP'
  26         @type proto: string
  27         @return: A deferred called with a L{NATMapper} instance
  28         @rtype: L{twisted.internet.defer.Deferred}
  29         """
  30         import nattraverso.pynupnp
  31         return nattraverso.pynupnp.get_port_mapper()
  32
  33 class NATMapper:
  34         """
  35         Define methods to map port objects (as returned by twisted's listenXX).
  36         This allows NAT to be traversed from incoming packets.
  37
  38         Currently the only implementation of this class is the UPnP Mapper, which
  39         can map UDP and TCP ports, if an UPnP Device exists.
  40         """
  41         def __init__(self):
  42                 raise NotImplementedError("Cannot instantiate the class")
  43
  44         def map(self, port):
  45                 """
  46                 Create a mapping for the given twisted's port object.
  47
  48                 The deferred will call back with a tuple (extaddr, extport):
  49                         - extaddr: The ip string of the external ip address of this host
  50                         - extport: the external port number used to map the given Port object
  51
  52                 When called multiple times with the same Port,
  53                 callback with the existing mapping.
  54
  55                 @param port: The port object to map
  56                 @type port: a L{twisted.internet.interfaces.IListeningPort} object
  57                 @return: A deferred called with the above defined tuple
  58                 @rtype: L{twisted.internet.defer.Deferred}
  59                 """
  60                 raise NotImplementedError
  61
  62         def info(self, port):
  63                 """
  64                 Returns the existing mapping for the given port object. That means map()
  65                 has to be called before.
  66
  67                 @param port: The port object to retreive info from
  68                 @type port: a L{twisted.internet.interfaces.IListeningPort} object
  69                 @raise ValueError: When there is no such existing mapping
  70                 @return: a tuple (extaddress, extport).
  71                 @see: L{map() function<map>}
  72                 """
  73                 raise NotImplementedError
  74
  75         def unmap(self, port):
  76                 """
  77                 Remove an existing mapping for the given twisted's port object.
  78
  79                 @param port: The port object to unmap
  80                 @type port: a L{twisted.internet.interfaces.IListeningPort} object
  81                 @return: A deferred called with None
  82                 @rtype: L{twisted.internet.defer.Deferred}
  83                 @raise ValueError: When there is no such existing mapping
  84                 """
  85                 raise NotImplementedError
  86
  87         def get_port_mappings(self):
  88                 """
  89                 Returns a deferred that will be called with a dictionnary of the
  90                 existing mappings.
  91
  92                 The dictionnary structure is the following:
  93                         - Keys: tuple (protocol, external_port)
  94                                 - protocol is "TCP" or "UDP".
  95                                 - external_port is the external port number, as see on the
  96                                         WAN side.
  97                         - Values:tuple (internal_ip, internal_port)
  98                                 - internal_ip is the LAN ip address of the host.
  99                                 - internal_port is the internal port number mapped
 100                                         to external_port.
 101
 102                 @return: A deferred called with the above defined dictionnary
 103                 @rtype: L{twisted.internet.defer.Deferred}
 104                 """
 105                 raise NotImplementedError
 106
 107         def _check_valid_port(self, port):
 108                 """Various Port object validity checks. Raise a ValueError."""
 109                 if not isinstance(port, BasePort):
 110                         raise ValueError("expected a Port, got %r"%(port))
 111
 112                 if not port.connected:
 113                         raise ValueError("Port %r is not listening"%(port))
 114
 115                 loc_addr = port.getHost()
 116                 if loc_addr.port == 0:
 117                         raise ValueError("Port %r has port number of 0"%(port))
 118