goami2

README

goami2: Simple Asterisk Manager Interface (AMI) library

Go library that provides interface to Asteris AMI. The library uses given net.Conn (tcp or tls), login and starts reading AMI messages from connection and parse them into *Message object. Provides simple interface to send messages to AMI. It uses re2c to create very fast protocol parser. Run "make bench" for benchmark tests.

Usage example:

import (
	"errors"
	"fmt"
	"log"
	"net"

	"github.com/staskobzar/goami2"
)

func main() {
	conn, err := net.Dial("tcp", "asterisk.host:5038")
	if err != nil {
		log.Fatalln(err)
	}

	// login and create client
	client, err := goami2.NewClient(conn, "admin", "pa55w0rd")
	if err != nil {
		log.Fatalln(err)
	}

	log.Println("client connected and logged in")

	// create AMI Action message and send to the asterisk.host
	msg := goami2.NewAction("CoreStatus")
	msg.AddActionID()
	client.Send(msg.Byte())

	defer client.Close() // close connections and all channels
	for {
		select {
		case msg := <-client.AllMessages():
			log.Printf("Got message: %s\n", msg.JSON())
		case err := <-client.Err():
			// terminate on network closed
			if errors.Is(err, goami2.ErrEOF) {
				log.Fatalf("Connection error: %s", err)
			}
			log.Printf("WARNING: AMI client error: %s", err)
		}
	}
}

Docs

See documentation at https://pkg.go.dev/github.com/staskobzar/goami2

Documentation

Overview

Package goami2 library for Asterisk Manager Interface

Index

• Variables
• type Client
  • func NewClient(conn net.Conn, username, password string) (*Client, error)
  • func NewClientWithContext(ctx context.Context, conn net.Conn, username, password string) (*Client, error)
  • func (c *Client) Action(action *Message) bool
  • func (c *Client) AllMessages() <-chan *Message
  • func (c *Client) Close()
  • func (c *Client) Err() <-chan error
  • func (c *Client) MustSend(msg []byte) error
  • func (c *Client) Send(msg []byte)
• type Header
• type Message
  • func FromJSON(input string) (*Message, error)
  • func NewAction(name string) *Message
  • func NewMessage() *Message
  • func Parse(data string) (*Message, error)
  • func (m *Message) ActionID() string
  • func (m *Message) AddActionID()
  • func (m *Message) AddField(key, value string)
  • func (m *Message) Byte() []byte
  • func (m *Message) DelField(key string)
  • func (m *Message) Field(key string) string
  • func (m *Message) FieldValues(key string) []string
  • func (m *Message) Headers() []Header
  • func (m *Message) IsEvent() bool
  • func (m *Message) IsResponse() bool
  • func (m *Message) IsSuccess() bool
  • func (m *Message) JSON() string
  • func (m *Message) Len() int
  • func (m *Message) SetField(name, value string)
  • func (m *Message) String() string
  • func (m *Message) Var(key string) (string, bool)

Variables

var (
	Error   = errors.New("goami2")
	ErrConn = fmt.Errorf("%w: net conn", Error)
	ErrAMI  = fmt.Errorf("%w: AMI proto", Error)
	ErrEOF  = fmt.Errorf("%w: terminated", Error)
)

Types

type Client

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

Client is a AMI connection management object

func NewClient

func NewClient(conn net.Conn, username, password string) (*Client, error)

NewClient creates client. It is using NewClientWithContext in the background with a bogus context. For better context control use NewClientWithContext function.

func NewClientWithContext

func NewClientWithContext(ctx context.Context, conn net.Conn, username, password string) (*Client, error)

NewClientWithContext creates client with provided connection net.Conn and login into AMI server. It returns error if fials to login. Runs internal connection loop and provides AMI messages via AllMessages and error via Err methods.

func (*Client) Action

func (c *Client) Action(action *Message) bool

Action sends AMI action to an Asterisk server Returns true on success and false if fails This function is deprecated and will be removed Use Send or MustSend instead

func (*Client) AllMessages

func (c *Client) AllMessages() <-chan *Message

AllMessages returns a channel that receives any AMI messages from the client connection

func (*Client) Close

func (c *Client) Close()

Close client

func (*Client) Err

func (c *Client) Err() <-chan error

Err returns channel of errors of the client

func (*Client) MustSend

func (c *Client) MustSend(msg []byte) error

MustSend sends a message to nework and returns network errors if any write away. May block until network timeout

func (*Client) Send

func (c *Client) Send(msg []byte)

Send AMI message as a bytes array None-blocking method. Any network errors will be send back via Client.Err() channel

type Header

type Header struct {
	Name  string
	Value string
}

Header of AMI Message

type Message

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

Message represents AMI message object

func FromJSON

func FromJSON(input string) (*Message, error)

func NewAction

func NewAction(name string) *Message

NewAction creats action message

func NewMessage

func NewMessage() *Message

NewMessage creates new Message

func Parse

func Parse(data string) (*Message, error)

Parse AMI message as string into *Message structure

func (*Message) ActionID

func (m *Message) ActionID() string

ActionID get AMI message action id as string

func (*Message) AddActionID

func (m *Message) AddActionID()

AddActionID create random ID and add ActionID field to the message

func (*Message) AddField

func (m *Message) AddField(key, value string)

AddField add field with key and name

func (*Message) Byte

func (m *Message) Byte() []byte

Byte AMI message as byte array

func (*Message) DelField

func (m *Message) DelField(key string)

DelField removes field from message by name

func (*Message) Field

func (m *Message) Field(key string) string

Field return field value. Case insensitive field search by name

func (*Message) FieldValues

func (m *Message) FieldValues(key string) []string

FieldValues list of values for multiple headers with the same name

func (*Message) Headers

func (m *Message) Headers() []Header

Headers list of the Message

func (*Message) IsEvent

func (m *Message) IsEvent() bool

IsEvent returns true if message is event

func (*Message) IsResponse

func (m *Message) IsResponse() bool

IsResponse returns true if message is response

func (*Message) IsSuccess

func (m *Message) IsSuccess() bool

IsSuccess returns true if successfully response

func (*Message) JSON

func (m *Message) JSON() string

func (*Message) Len

func (m *Message) Len() int

Len returns number of headers in the message

func (*Message) SetField

func (m *Message) SetField(name, value string)

SetField get first available field by name and updates its value. If field not in list then append new field

func (*Message) String

func (m *Message) String() string

String AMI message as string

func (*Message) Var

func (m *Message) Var(key string) (string, bool)

Var search in AMI message variable fields like Variable or ChanVariable etc for a value of the type key=value or just key. If found, returns value as string and true. Variable name is case insensative.