cmgr

README

Cmgr is a connection manager that makes it simple for an application 
to listen for, and accept, TCP connections and to send/receive packets
via TCP or UDP.  Parallel sessions are supported, and messages received
are delivered to the application via a channel.

Documentation

Overview

Creates and manages a connetion environment that allows the user to establish TCP connections (outgoing) and listens/accepts connection requests from remote processes.

The connection manager object is created with NewManager which accepts a listen port and a channel on which Sess_data objects are written. The listener is invoked and when a connection is accepted a connection reader is started and a ST_NEW Sess_data object is written on the user's channel. The reader sends all data via the channel (ST_DATA) and if the session is disconnected a Sess_data object with the ST_DISC state is written and the connection is cleaned up (no need for user to invoke the Close function in a disconnect case.

When a user establishes a connection the remote IP address and a session id (name) are supplied along with a communication channel. The channel may be the same channel supplied when the connection manager object was created or it may be a different channel.

Data received from either a UDP listener, or on a connected TCP session is bundled into a Sess_data struct and placed onto the appropriate channel. The struct contains, in addition to the received buffer, the ID of the session that can be used on a generic Write command to, the current state of the session (ST_ constants), and a string indicating some useful (humanised) data about the session.

Index

• Constants
• func Xlate_udp_addr(addr string) (xla *net.UDPAddr, e error)
• type Cmgr
  • func NewManager(port string, data2usr chan *Sess_data) *Cmgr
  • func (this *Cmgr) Close(id string)
  • func (this *Cmgr) Connect(target string, uid string, data2usr chan *Sess_data)
  • func (this *Cmgr) List_stats()
  • func (this *Cmgr) Listen(kind string, port string, iface string, data2usr chan *Sess_data) (string, bool)
  • func (this *Cmgr) Listen_tcp(port string, data2usr chan *Sess_data) (string, bool)
  • func (this *Cmgr) Listen_udp(port int, data2usr chan *Sess_data) (string, bool)
  • func (this *Cmgr) Write(id string, buf []byte) (err error)
  • func (this *Cmgr) Write_n(id string, buf []byte, n int) (err error)
  • func (this *Cmgr) Write_str(id string, buf string) (err error)
  • func (this *Cmgr) Write_to_all(buf []byte) (err error)
  • func (this *Cmgr) Write_udp(id string, to string, ibuf interface{}) (err error)
  • func (this *Cmgr) Write_udp_addr(id string, toi interface{}, ibuf interface{}) (err error)
• type Sess_data
  • func (this *Sess_data) Write(buf []byte) (err error)
  • func (this *Sess_data) Write_n(buf []byte, n int) (err error)
  • func (this *Sess_data) Write_str(buf string) (err error)

Constants

const (
	// state describing the session data returned on the user's channel
	ST_NEW      = iota // new connection
	ST_DATA            // data received
	ST_DISC            // disconnected connection
	ST_ACCEPTED        // session has been accepted
)

const (
	LISTENER string = "l0" // our magic session id for the default litener
)

const (
	ST_CLOSING int = 1 // close already in progress
)

Functions

func Xlate_udp_addr

func Xlate_udp_addr(addr string) (xla *net.UDPAddr, e error)

Xlate_udp_addr allows a user to xlate an ip:port host:port into a udp address that can be passed to Write_udp_addr for faster udp writes.

Types

type Cmgr

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

func NewManager

func NewManager(port string, data2usr chan *Sess_data) *Cmgr

NewManager creates a new connection manager object. If the port is greater than zero, a TCP listener will be started on the port and any data received by sessions connected to the port will be sent to the user application using the channel provided. If port is <= 0, or an empty string, then no listener is opened by default; a call to either the udp listen or tcp listen function can be made to start a listener and provide a channel.

If the listener cannot be established a nil object is returned.

func (*Cmgr) Close

func (this *Cmgr) Close(id string)

Close does what ever is needed to terminate the connection represented by id.

func (*Cmgr) Connect

func (this *Cmgr) Connect(target string, uid string, data2usr chan *Sess_data)

Connect establishes a connection to the target process (ip:port) and starts a reader listening for data on the session. Any received data will be forwarded to the user application via the channel provided.

func (*Cmgr) List_stats

func (this *Cmgr) List_stats()

Lists the current statistics about connections to the standard output device.

func (*Cmgr) Listen

func (this *Cmgr) Listen(kind string, port string, iface string, data2usr chan *Sess_data) (string, bool)

Listen starts a TCP listener, allowing the caller to supply type (tcp, tcp4, tcp6) and interface (0.0.0.0 for any) then opens and binds to the socket. A goroutine is started to actually do the listening and will accept sessions that connect. Generally the listen method will be driven during the construction of a cmgr object, though I user can use this if more than one listen port is required.

Returns an ID which identifies the listener, and a boolean set to true if the listener was established successfully.

func (*Cmgr) Listen_tcp

func (this *Cmgr) Listen_tcp(port string, data2usr chan *Sess_data) (string, bool)

Listen_tcp provides a more consistant interface with the Listen_udp name convention and is just a wrapper for Listen().

func (*Cmgr) Listen_udp

func (this *Cmgr) Listen_udp(port int, data2usr chan *Sess_data) (string, bool)

Listen_udp starts a UDP listener which will forward received data back to the application using the supplied channel. The listener ID is returned along with a boolian indication of success (true) or failure.

func (*Cmgr) Write

func (this *Cmgr) Write(id string, buf []byte) (err error)

Write writes the byte array to the named connection.

func (*Cmgr) Write_n

func (this *Cmgr) Write_n(id string, buf []byte, n int) (err error)

Write_n writes n bytes from the byte array to the named session.

func (*Cmgr) Write_str

func (this *Cmgr) Write_str(id string, buf string) (err error)

Write_udp writes the string to the named session.

func (*Cmgr) Write_to_all

func (this *Cmgr) Write_to_all(buf []byte) (err error)

Write_to_all writes the byte array to all active sessions.

func (*Cmgr) Write_udp

func (this *Cmgr) Write_udp(id string, to string, ibuf interface{}) (err error)

Writes the byte array to the udp address given in 'to'. The address is expected to be host:port format. To is the addr:port to send the data to, and id of the UDP listener that is used for writing. Ibuf is one of: array of bytes, string or pointer to string containing the data to write.

func (*Cmgr) Write_udp_addr

func (this *Cmgr) Write_udp_addr(id string, toi interface{}, ibuf interface{}) (err error)

Write_udp_addr writes the data (ibuf) to the udp address given in 'to'. The address in to is something that has been resolved by net.ResolveUDPAddr() so this should be faster than Write_udp(). Ibuf may be a byte array, string or pointer to string.

type Sess_data

type Sess_data struct {
	Buf   []byte // actual data
	Id    string // identify src for user that receives data from multiple connections
	From  string // message source address
	State int    // ST_ constants indicating the session state
	Data  string // maybe useful (humanised) data about the session or message; generally empty for data.
	// contains filtered or unexported fields
}

Data that is returned on the channel to the user.

func (*Sess_data) Write

func (this *Sess_data) Write(buf []byte) (err error)

Write sends the contents of buf (bytes) to the process that sent the data represented by Sess_data

func (*Sess_data) Write_n

func (this *Sess_data) Write_n(buf []byte, n int) (err error)

Write_n sends n bytes to the process that sent the data represented by Sess_data

func (*Sess_data) Write_str

func (this *Sess_data) Write_str(buf string) (err error)

Write_str sends the string to the process that sent the data represented by Sess_data