gami

README

GAMI

GO - Asterisk Manager Interface (AMI)

communicate with the AMI, Actions and Events.

###BASIC USAGE

Example connecting to Asterisk and Send Action get Events.

package main

import (
	"log"

	"github.com/party79/gami"
	"github.com/party79/gami/event"
)

func main() {
	ami, err := gami.Dial("127.0.0.1:5038")
	if err != nil {
		fmt.Print(err)
		os.Exit(1)
	}
	ami.Run()
	defer ami.Close()
	//install manager
	go func() {
		for {
			select {
			//handle network errors
			case err := <-ami.NetError:
				log.Println("Network Error:", err)
				//try new connection every second
				<-time.After(time.Second)
				if err := ami.Reconnect(); err == nil {
					//call start actions
					ami.Action("Events", gami.Params{"EventMask": "on"})
				}
			case err := <-ami.Error:
				log.Println("error:", err)
			//wait events and process
			case ev := <-ami.Events:
				log.Println("Event Detect: %v", *ev)
				//if want type of events
				log.Println("EventType:", event.New(ev))
			}
		}
	}()
	if err := ami.Login("admin", "root"); err != nil {
		log.Fatal(err)
	}
	if rs, err = ami.Action("Ping", nil); err == nil {
		log.Fatal(rs)
	}
	//or with can do async
	pingResp, pingErr := ami.AsyncAction("Ping", gami.Params{"ActionID": "miping"})
	if pingErr != nil {
		log.Fatal(pingErr)
	}
	if rs, err = ami.Action("Events", ami.Params{"EventMask":"on"}); err != nil {
		fmt.Print(err)
	}
	log.Println("future ping:", <-pingResp)
}

###TLS SUPPORT

In order to use TLS connection to manager interface you could Dial with additional parameters

//without TLS
ami, err := gami.Dial("127.0.0.1:5038")

//if certificate is trusted
ami, err := gami.Dial("127.0.0.1:5039", gami.UseTLS)

//if self signed certificate
ami, err := gami.Dial("127.0.0.1:5039", gami.UseTLS, gami.UnsecureTLS)

//if custom tls configuration
ami, err := gami.Dial("127.0.0.1:5039", gami.UseTLSConfig(&tls.Config{}))

WARNING: Only Asterisk >=1.6 supports TLS connection to AMI and it needs additional configuration(follow the AMI configuration documentation)

###CUSTOM CONNECTION

Example connecting to Asterisk with a basic connection, you would use this with your own io.ReadWriteCloser

package main

import (
	"log"
	"net"

	"github.com/party79/gami"
)

func main() {
	c, err := net.Dial("tcp", "127.0.0.1:5038")
	if err != nil {
		log.Fatal(err)
	}
	ami, err := gami.NewClient(c)
	if err != nil {
		log.Fatal(err)
	}
	ami.Run()
	defer ami.Close()
	//do something
}

CURRENT EVENT TYPES

The events use documentation and struct from PAMI.

use party79/gami/event.New() for get this struct from raw event

EVENT ID	TYPE TEST
Newchannel	YES
Newexten	YES
Newstate	YES
Dial	YES
ExtensionStatus	YES
Hangup	YES
PeerStatus	YES
PeerEntry	YES
VarSet	YES
AgentLogin	YES
Agents	YES
AgentLogoff	YES
AgentConnect	YES
RTPReceiverStats	YES
RTPSenderStats	YES
Bridge	YES

Documentation

Overview

Package gami provites primitives for interacting with Asterisk Manager Interface (AMI)

Basic Usage

ami, err := gami.Dial("127.0.0.1:5038")
if err != nil {
	fmt.Print(err)
	os.Exit(1)
}
ami.Run()
defer ami.Close()

//install manager
go func() {
	for {
		select {
		//handle network errors
		case err := <-ami.NetError:
			log.Println("Network Error:", err)
			//try new connection every second
			<-time.After(time.Second)
			if err := ami.Reconnect(); err == nil {
				//call start actions
				ami.Action("Events", gami.Params{"EventMask": "on"})
			}

		case err := <-ami.Error:
			log.Println("error:", err)
		//wait events and process
		case ev := <-ami.Events:
			log.Println("Event Detect: %v", *ev)
			//if want type of events
			log.Println("EventType:", event.New(ev))
		}
	}
}()

if err := ami.Login("admin", "root"); err != nil {
	log.Fatal(err)
}

if rs, err = ami.Action("Ping", nil); err == nil {
	log.Fatal(rs)
}

//or with can do async
pingResp, pingErr := ami.AsyncAction("Ping", gami.Params{"ActionID": "miping"})
if pingErr != nil {
	log.Fatal(pingErr)
}

if rs, err = ami.Action("Events", ami.Params{"EventMask":"on"}); err != nil {
	fmt.Print(err)
}

log.Println("future ping:", <-pingResp)

Index

• Variables
• func UnsecureTLS(c *AMIClient)
• func UseTLS(c *AMIClient)
• func UseTLSConfig(config *tls.Config) func(*AMIClient)
• type AMIClient
  • func Dial(address string, options ...func(*AMIClient)) (*AMIClient, error)
  • func NewClient(conn io.ReadWriteCloser, options ...func(*AMIClient)) (*AMIClient, error)
  • func (client *AMIClient) Action(action string, params Params) (*AMIResponse, error)
  • func (client *AMIClient) AsyncAction(action string, params Params) (<-chan *AMIResponse, error)
  • func (client *AMIClient) AsyncActionMulti(action string, params Params) (chan *AMIResponse, error)
  • func (client *AMIClient) ClearResponse(response *AMIResponse)
  • func (client *AMIClient) Close()
  • func (client *AMIClient) Login(username, password string) error
  • func (client *AMIClient) NewConn() (err error)
  • func (client *AMIClient) Reconnect() error
  • func (client *AMIClient) Run()
• type AMIEvent
• type AMIResponse
• type Params

Variables

var ErrNotAMI = errors.New("Server not AMI interface")

Raise when not response expected protocol AMI

Functions

func UnsecureTLS

func UnsecureTLS(c *AMIClient)

func UseTLS

func UseTLS(c *AMIClient)

func UseTLSConfig

func UseTLSConfig(config *tls.Config) func(*AMIClient)

Types

type AMIClient

type AMIClient struct {

	// Events for client parse
	Events chan *AMIEvent

	// Error Raise on logic
	Error chan error

	//NetError a network error
	NetError chan error
	// contains filtered or unexported fields
}

AMIClient a connection to AMI server

func Dial

func Dial(address string, options ...func(*AMIClient)) (*AMIClient, error)

Dial create a new connection to AMI

func NewClient

func NewClient(conn io.ReadWriteCloser, options ...func(*AMIClient)) (*AMIClient, error)

Dial create a new connection to AMI

func (*AMIClient) Action

func (client *AMIClient) Action(action string, params Params) (*AMIResponse, error)

Action send with params

func (*AMIClient) AsyncAction

func (client *AMIClient) AsyncAction(action string, params Params) (<-chan *AMIResponse, error)

func (*AMIClient) AsyncActionMulti

func (client *AMIClient) AsyncActionMulti(action string, params Params) (chan *AMIResponse, error)

func (*AMIClient) ClearResponse

func (client *AMIClient) ClearResponse(response *AMIResponse)

func (*AMIClient) Close

func (client *AMIClient) Close()

Close the connection to AMI

func (*AMIClient) Login

func (client *AMIClient) Login(username, password string) error

Login authenticate to AMI

func (*AMIClient) NewConn

func (client *AMIClient) NewConn() (err error)

NewConn create a new connection to AMI

func (*AMIClient) Reconnect

func (client *AMIClient) Reconnect() error

Reconnect the session, autologin if a new network error it put on client.NetError

func (*AMIClient) Run

func (client *AMIClient) Run()

Run process socket waiting events and responses

type AMIEvent

type AMIEvent struct {
	//Identification of event Event: xxxx
	ID string

	Privilege []string

	// Params  of arguments received
	Params map[string]string
}

AMIEvent it's a representation of Event readed

type AMIResponse

type AMIResponse struct {
	ID     string
	Status string
	Params map[string]string
}

AMIResponse from action

type Params

type Params map[string]string

Params for the actions