goupnp

Documentation

Overview

A small library for using the port mapping controls of UPnP-enabled IGDs

Index

• Constants
• func DiscoverIGD() (ret chan *IGD)
• func IsPrivateIPAddress(addr net.IP) bool
• func ParseProtocol(proto string) (ret protocol)
• type ConnectionStatus
• type IGD
  • func (self *IGD) AddLocalPortRedirection(port uint16, proto protocol) (ret chan *PortMapping)
  • func (self *IGD) DeletePortRedirection(portMappings ...*PortMapping) (ret chan error)
  • func (self *IGD) GetConnectionStatus() (ret chan *ConnectionStatus)
  • func (self *IGD) ListRedirections() (ret chan *PortMapping)
  • func (self *IGD) String() string
• type PortMapping
  • func (self *PortMapping) String() string
• Bugs

Constants

const (
	TCP protocol = 1 << iota
	UDP
)

Functions

func DiscoverIGD

func DiscoverIGD() (ret chan *IGD)

This function returns a channel which will be sent the first IGD it finds in traversing `net.InterfaceAddrs()` with IP addresses in the private network range.

The channel this function returns should be listened on to avoid leaking goroutines. Additionally the listener must check whether the channel the value returned by the channel against nil, to ensure that an IGD was indeed found.

func IsPrivateIPAddress

func IsPrivateIPAddress(addr net.IP) bool

This function returns true if and only if the passed IP address belongs to one of the ranges reserved in RFC 1918 for use in private networks

This function is only part of this package as it is used internally and is public as it is deemed useful for developers to assertain whether or not a given external IP address such as one returned by GetConnectionStatus is public or not and as creating a standalone package just for this one function seemed excessive.

func ParseProtocol

func ParseProtocol(proto string) (ret protocol)

Function for parsing a protocol in string form to protocol type for use with this library's methods. Only TCP and UDP are supported.

Types

type ConnectionStatus

type ConnectionStatus struct {
	Connected bool
	IP        net.IP
}

type IGD

type IGD struct {
	// contains filtered or unexported fields
}

This opaque type provides a handle to a discovered IGD Use DiscoverIGD() to obtain such a handle.

NOTA BENE Using instances of this struct not retured by the appropriate function call has undefined behaviour

func (*IGD) AddLocalPortRedirection

func (self *IGD) AddLocalPortRedirection(port uint16, proto protocol) (ret chan *PortMapping)

This method creates a port mapping on the IGD with internal, external ports and protocol respectively equal to the passed port argument (bis) and protocol

Errors are indicated by the channel closing before a PortMapping is returned. Listeners should therefore check at the very least for nil, better still for channel closure.

NOTA BENE the channel closes after a successive PortMapping has been send on it, in order to not leak resources.

func (*IGD) DeletePortRedirection

func (self *IGD) DeletePortRedirection(portMappings ...*PortMapping) (ret chan error)

BUG(nhelke): NOT IMPLEMENTED — ALWAYS RETURNS ERROR

Please feel free to submit a pull request to https://github.com/nhelke/goupnpc and I will be sure to merge it.

func (*IGD) GetConnectionStatus

func (self *IGD) GetConnectionStatus() (ret chan *ConnectionStatus)

This method fetches the status of the IGD.

Errors are indicated by the channel closing before a ConnectionStatus is returned. Listeners should therefore check at the very least for nil, better still for channel closure.

NOTA BENE the channel closes after a successive ConnectionStatus has been send on it, in order to not leak resources.

func (*IGD) ListRedirections

func (self *IGD) ListRedirections() (ret chan *PortMapping)

This method returns a buffered channel which should be iterated over. The channel is closed on after the last port mapping, so iterating over the channel will not loop forever.

func (*IGD) String

func (self *IGD) String() string

type PortMapping

type PortMapping struct {
	InternalPort uint16
	ExternalPort uint16
	Protocol     protocol
	InternalHost net.IP
	Description  string
	Enabled      bool
	Lease        uint
}

This type provides all the information about port mappings. It also serves as a handle returned by AddLocalPortRedirection() for use with DeletePortRedirection().

func (*PortMapping) String

func (self *PortMapping) String() string

Notes

Bugs

• NOT IMPLEMENTED — ALWAYS RETURNS ERROR

  Please feel free to submit a pull request to https://github.com/nhelke/goupnpc and I will be sure to merge it.