gosmpp

README

gosmpp

SMPP (3.4) Client Library in pure Go.

This library is well tested with SMSC simulators:

• Melroselabs SMSC

Installation

go get -u github.com/linxGnu/gosmpp

Usage

Highlight

• From v0.1.4, gosmpp is written in event-based style and fully-manage your smpp session, connection, error, rebinding, etc. You only need to implement some hooks:

		trans, err := gosmpp.NewSession(
		gosmpp.TRXConnector(gosmpp.NonTLSDialer, auth),
		gosmpp.Settings{
			EnquireLink: 5 * time.Second,

			ReadTimeout: 10 * time.Second,

			OnSubmitError: func(_ pdu.PDU, err error) {
				log.Fatal("SubmitPDU error:", err)
			},

			OnReceivingError: func(err error) {
				fmt.Println("Receiving PDU/Network error:", err)
			},

			OnRebindingError: func(err error) {
				fmt.Println("Rebinding but error:", err)
			},

			OnPDU: handlePDU(),

			OnClosed: func(state gosmpp.State) {
				fmt.Println(state)
			},
		}, 5*time.Second)
		if err != nil {
		  log.Println(err)
		}
		defer func() {
		  _ = trans.Close()
		}()

Version (0.1.4.RC+)

• Full example could be found: here
  • In this example, you should run smsc first:
    • Please point to: https://github.com/linxGnu/gosmpp/blob/master/example/smsc
    • Build & Run SMSC (g++ required): ./run.sh
  • Next is build and run: https://github.com/linxGnu/gosmpp/blob/master/example/main.go
    • Build: go build
    • Run: ./example
  • You should see: logs of communication between SMSC and Example. Each SubmitSM will trigger SMSC to simulate a MO.

Old version (0.1.3 and previous)

Full example could be found: gist

Supported PDUs

• bind_transmitter
• bind_transmitter_resp
• bind_receiver
• bind_receiver_resp
• bind_transceiver
• bind_transceiver_resp
• outbind
• unbind
• unbind_resp
• submit_sm
• submit_sm_resp
• submit_sm_multi
• submit_sm_multi_resp
• data_sm
• data_sm_resp
• deliver_sm
• deliver_sm_resp
• query_sm
• query_sm_resp
• cancel_sm
• cancel_sm_resp
• replace_sm
• replace_sm_resp
• enquire_link
• enquire_link_resp
• alert_notification
• generic_nack

Documentation

Index

• Constants
• Variables
• type Auth
• type ClosedCallback
• type Connection
  • func NewConnection(conn net.Conn) (c *Connection)
  • func (c *Connection) Close() error
  • func (c *Connection) LocalAddr() net.Addr
  • func (c *Connection) Read(b []byte) (n int, err error)
  • func (c *Connection) RemoteAddr() net.Addr
  • func (c *Connection) SetDeadline(t time.Time) error
  • func (c *Connection) SetReadDeadline(t time.Time) error
  • func (c *Connection) SetReadTimeout(t time.Duration) error
  • func (c *Connection) SetWriteDeadline(t time.Time) error
  • func (c *Connection) SetWriteTimeout(t time.Duration) error
  • func (c *Connection) Write(b []byte) (n int, err error)
  • func (c *Connection) WritePDU(p pdu.PDU) (n int, err error)
• type Connector
  • func RXConnector(dialer Dialer, auth Auth) Connector
  • func TRXConnector(dialer Dialer, auth Auth) Connector
  • func TXConnector(dialer Dialer, auth Auth) Connector
• type Dialer
• type ErrorCallback
• type PDUCallback
• type PDUErrorCallback
• type Receiver
• type Session
  • func NewSession(c Connector, settings Settings, rebindingInterval time.Duration) (session *Session, err error)
  • func (s *Session) Close() (err error)
  • func (s *Session) Receiver() Receiver
  • func (s *Session) Transceiver() Transceiver
  • func (s *Session) Transmitter() Transmitter
• type Settings
• type State
  • func (s *State) String() string
• type Transceiver
• type Transmitter

Constants

const (
	Alive int32 = iota
	Closed
)

Variables

var (
	// ErrConnectionClosing indicates transmitter is closing. Can not send any PDU.
	ErrConnectionClosing = fmt.Errorf("connection is closing, can not send PDU to SMSC")
)

var (
	// NonTLSDialer is non-tls connection dialer.
	NonTLSDialer = func(addr string) (net.Conn, error) {
		return net.Dial("tcp", addr)
	}
)

Types

type Auth

type Auth struct {
	// SMSC is SMSC address.
	SMSC       string
	SystemID   string
	Password   string
	SystemType string
}

Auth represents basic authentication to SMSC.

type ClosedCallback

type ClosedCallback func(State)

ClosedCallback notifies closed event due to State.

type Connection

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

Connection wraps over net.Conn with buffered data reader.

func NewConnection

func NewConnection(conn net.Conn) (c *Connection)

NewConnection returns a Connection.

func (*Connection) Close

func (c *Connection) Close() error

Close closes the connection. Any blocked Read or Write operations will be unblocked and return errors.

func (*Connection) LocalAddr

func (c *Connection) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Connection) Read

func (c *Connection) Read(b []byte) (n int, err error)

Read reads data from the connection. Read can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.

func (*Connection) RemoteAddr

func (c *Connection) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*Connection) SetDeadline

func (c *Connection) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

A deadline is an absolute time after which I/O operations fail with a timeout (see type Error) instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.

An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.

A zero value for t means I/O operations will not time out.

Note that if a TCP connection has keep-alive turned on, which is the default unless overridden by Dialer.KeepAlive or ListenConfig.KeepAlive, then a keep-alive failure may also return a timeout error. On Unix systems a keep-alive failure on I/O can be detected using errors.Is(err, syscall.ETIMEDOUT).

func (*Connection) SetReadDeadline

func (c *Connection) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.

func (*Connection) SetReadTimeout

func (c *Connection) SetReadTimeout(t time.Duration) error

SetReadTimeout is equivalent to ReadDeadline(now + timeout)

func (*Connection) SetWriteDeadline

func (c *Connection) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.

func (*Connection) SetWriteTimeout

func (c *Connection) SetWriteTimeout(t time.Duration) error

SetWriteTimeout is equivalent to WriteDeadline(now + timeout)

func (*Connection) Write

func (c *Connection) Write(b []byte) (n int, err error)

Write writes data to the connection. Write can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetWriteDeadline.

func (*Connection) WritePDU

func (c *Connection) WritePDU(p pdu.PDU) (n int, err error)

WritePDU data to the connection.

type Connector

type Connector interface {
	Connect() (conn *Connection, err error)
}

Connector is connection factory interface.

func RXConnector

func RXConnector(dialer Dialer, auth Auth) Connector

RXConnector returns a Receiver (RX) connector.

func TRXConnector

func TRXConnector(dialer Dialer, auth Auth) Connector

TRXConnector returns a Transceiver (TRX) connector.

func TXConnector

func TXConnector(dialer Dialer, auth Auth) Connector

TXConnector returns a Transmitter (TX) connector.

type Dialer

type Dialer func(addr string) (net.Conn, error)

Dialer is connection dialer.

type ErrorCallback

type ErrorCallback func(error)

ErrorCallback notifies happened error while reading PDU.

type PDUCallback

type PDUCallback func(pdu pdu.PDU, responded bool)

PDUCallback handles received PDU.

type PDUErrorCallback

type PDUErrorCallback func(pdu pdu.PDU, err error)

PDUErrorCallback notifies fail-to-submit PDU with along error.

type Receiver

type Receiver interface {
	io.Closer
	SystemID() string
}

Receiver interface.

type Session

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

Session represents session for TX, RX, TRX.

func NewSession

func NewSession(c Connector, settings Settings, rebindingInterval time.Duration) (session *Session, err error)

NewSession creates new session for TX, RX, TRX.

Session will `non-stop`, automatically rebind (create new and authenticate connection with SMSC) when unexpected error happened.

`rebindingInterval` indicates duration that Session has to wait before rebinding again.

Setting `rebindingInterval <= 0` will disable `auto-rebind` functionality.

func (*Session) Close

func (s *Session) Close() (err error)

Close session.

func (*Session) Receiver

func (s *Session) Receiver() Receiver

Receiver returns bound Receiver.

func (*Session) Transceiver

func (s *Session) Transceiver() Transceiver

Transceiver returns bound Transceiver.

func (*Session) Transmitter

func (s *Session) Transmitter() Transmitter

Transmitter returns bound Transmitter.

type Settings

type Settings struct {
	// ReadTimeout is timeout for reading PDU from SMSC.
	// Underlying net.Conn will be stricted with ReadDeadline(now + timeout).
	// This setting is very important to detect connection failure.
	//
	// Must: ReadTimeout > max(0, EnquireLink)
	ReadTimeout time.Duration

	// WriteTimeout is timeout for submitting PDU.
	WriteTimeout time.Duration

	// EnquireLink periodically sends EnquireLink to SMSC.
	// The duration must not be smaller than 1 minute.
	//
	// Zero duration disables auto enquire link.
	EnquireLink time.Duration

	// OnPDU handles received PDU from SMSC.
	//
	// `Responded` flag indicates this pdu is responded automatically,
	// no manual respond needed.
	OnPDU PDUCallback

	// OnReceivingError notifies happened error while reading PDU
	// from SMSC.
	OnReceivingError ErrorCallback

	// OnSubmitError notifies fail-to-submit PDU with along error.
	OnSubmitError PDUErrorCallback

	// OnRebindingError notifies error while rebinding.
	OnRebindingError ErrorCallback

	// OnClosed notifies `closed` event due to State.
	OnClosed ClosedCallback
	// contains filtered or unexported fields
}

Settings for TX (transmitter), RX (receiver), TRX (transceiver).

type State

type State byte

State represents Transmitter/Receiver/Transceiver state.

const (
	// ExplicitClosing indicates that Transmitter/Receiver/Transceiver is closed
	// explicitly (from outside).
	ExplicitClosing State = iota

	// StoppingProcessOnly stops daemons but does not close underlying net conn.
	StoppingProcessOnly

	// InvalidStreaming indicates Transceiver/Receiver data reading state is
	// invalid due to network connection or SMSC responsed with an invalid PDU
	// which potentially damages other following PDU(s).
	//
	// In both cases, Transceiver/Receiver is closed implicitly.
	InvalidStreaming

	// ConnectionIssue indicates that Transmitter/Receiver/Transceiver is closed
	// due to network connection issue or SMSC is not available anymore.
	ConnectionIssue

	// UnbindClosing indicates Receiver got unbind request from SMSC and closed due to this request.
	UnbindClosing
)

func (*State) String

func (s *State) String() string

String interface.

type Transceiver

type Transceiver interface {
	io.Closer
	Submit(pdu.PDU) error
	SystemID() string
}

Transceiver interface.

type Transmitter

type Transmitter interface {
	io.Closer
	Submit(pdu.PDU) error
	SystemID() string
}

Transmitter interface.