goagi

package module
v1.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 8, 2022 License: MIT Imports: 4 Imported by: 0

README

goagi: Golang library to build agi/fastagi applications

Build Status codecov CodeFactor Scrutinizer Code Quality Go Report Card GitHub

Simple library that helps to build AGI scripts or FastAGI servers with Go.

import "github.com/staskobzar/goagi"

API documentation link is here.

Usage FastAGI

AGI object is created with New method with three arguments:

Debugger interface is required only for debugging and usually nil. See below for more details.

Reader and Writer are interfaces are any objects that implement Read/Write methods and can be net.Conn, tls.Conn, os.Stdin, os.Stdout or any other, for example from packages strings, bufio, bytes.

New method will read AGI session setup environment variables and provides interface to AGI commands. AGI environment variables and arguments can be accessed with methods Env and EnvArgs. If AGI channel receives HANGUP message, the session will be marked as hungup. Hangup status can be checked by method IsHungup.

Usage example for AGI:
	import (
		"github.com/staskobzar/goagi"
		"os"
	)

	agi, err := goagi.New(os.Stdin, os.Stdout, nil)
	if err != nil {
		panic(err)
	}
	agi.Verbose("Hello World!")
Fast AGI example:
	ln, err := net.Listen("tcp", "127.0.0.1:4573")
	if err != nil {
		panic(err)
	}
	for {
		conn, err := ln.Accept()
		if err != nil {
			panic(err)
		}
		go func(conn net.Conn) {
			agi, err := goagi.New(conn, conn, nil)
			if err != nil {
				panic(err)
			}
			agi.Verbose("Hello World!")
		}(conn)
	}

See working examples in [examples/] folder.

Index of methods that implements AGI commands see here.

Commands Response interface

Every AGI command method return interface Response. This is interface that provides access to AGI response values. Success response example:

200 result=1 (speech) endpos=9834523 results=5

Fail response example:

511 Command Not Permitted on a dead channel or intercept routine

There are success and error responses. Response interface implements following methods:

  • Code() int: response code: 200, 510 etc.
  • RawResponse() string: returns full text of AGI response.
  • Result() int: returns value of result= field.
  • Value() string: returns response value field that comes in parentheses. For exmpale "(timeout)" in response "200 result=1 (timeout)".
  • Data() string: returns text for error responses and dtmf values for command like GetData.
  • EndPos() int64: returns value for endpos= field.
  • Digit() string: return digit from digit= field.
  • SResults() int: return value for results= field.

Debugger

Interface that provides debugging capabilities with configurable output.

Example of usage:

	dbg := logger.New(os.Stdout, "myagi:", log.Lmicroseconds)
	r, w := net.Pipe()
	agi, err := goagi.New(r, w, dbg)

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrAGI = newError("AGI session")

ErrAGI goagi error

Functions

This section is empty.

Types

type AGI 

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

AGI object

func New added in v1.1.0 

func New(r Reader, w Writer, dbg Debugger) (*AGI, error)

New creates and returns AGI object. Can be used to create agi and fastagi sessions.

Parameters:

- Reader that implements Read method

- Writer that implements Write method

- Debugger that allows to deep library debugging. Nil for production.

func (*AGI) Answer 

func (agi *AGI) Answer() (Response, error)

Answer executes AGI command "ANSWER" Answers channel if not already in answer state.

func (*AGI) AsyncAGIBreak 

func (agi *AGI) AsyncAGIBreak() (Response, error)

AsyncAGIBreak Interrupts Async AGI 

Interrupts expected flow of Async AGI commands and returns control

to previous source (typically, the PBX dialplan).

func (*AGI) ChannelStatus 

func (agi *AGI) ChannelStatus(channel string) (Response, error)

ChannelStatus returns status of the connected channel.

If no channel name is given (empty line) then returns the status of the current channel.

Return values:

0 - Channel is down and available.

1 - Channel is down, but reserved.

2 - Channel is off hook.

3 - Digits (or equivalent) have been dialed.

4 - Line is ringing.

5 - Remote end is ringing.

6 - Line is up.

7 - Line is busy.

func (*AGI) Close added in v1.3.2 

func (agi *AGI) Close()

func (*AGI) Command 

func (agi *AGI) Command(cmd string) (Response, error)

Command sends command as string to the AGI and returns response valus with text response

func (*AGI) ControlStreamFile 

func (agi *AGI) ControlStreamFile(filename, digits string, args ...string) (Response, error)

ControlStreamFile sends audio file on channel and allows the listener to control the stream. Send the given file, allowing playback to be controlled by the given digits, if any. Use double quotes for the digits if you wish none to be permitted. If offsetms is provided then the audio will seek to offsetms before play starts.

Example: 

agi.ControlStreamFile("prompt_en", "19", "3000", "#", "0", "#", "1600")
agi.ControlStreamFile("prompt_en", "")
agi.ControlStreamFile("prompt_en", "19", "", "", "", "#", "1600")

func (*AGI) DatabaseDel 

func (agi *AGI) DatabaseDel(family, key string) (Response, error)

DatabaseDel deletes an entry in the Asterisk database for a given family and key. 

Returns status and error if fails.

func (*AGI) DatabaseDelTree 

func (agi *AGI) DatabaseDelTree(family, keytree string) (Response, error)

DatabaseDelTree deletes a family or specific keytree within a family in the Asterisk database.

func (*AGI) DatabaseGet 

func (agi *AGI) DatabaseGet(family, key string) (Response, error)

DatabaseGet Retrieves an entry in the Asterisk database for a given family and key. 

	Returns value as string or error if failed or value not set
 Response.Value() for result

func (*AGI) DatabasePut 

func (agi *AGI) DatabasePut(family, key, val string) (Response, error)

DatabasePut adds or updates an entry in the Asterisk database for a given family, key, and value.

func (*AGI) Env 

func (agi *AGI) Env(key string) string

Env returns AGI environment variable by key

func (*AGI) EnvArgs 

func (agi *AGI) EnvArgs() []string

EnvArgs returns list of environment arguments

func (*AGI) Exec 

func (agi *AGI) Exec(app, opts string) (Response, error)

Exec executes application with given options.

func (*AGI) GetData 

func (agi *AGI) GetData(file string, timeout, maxdigit int) (Response, error)

GetData Stream the given file, and receive DTMF data. Note: when timeout is 0 then Asterisk will use 6 seconds. Note: Asterisk has strange way to handle get data response. Contrary to other responses, where result has numeric value, here asterisk puts DTMF to sent by user to result and this value may contain "#" and "*".

To get DTMF sent by user use Response.Data()

Response.Value() will contain "timeout" if user has not terminated input with "#"

func (*AGI) GetFullVariable 

func (agi *AGI) GetFullVariable(name, channel string) (Response, error)

GetFullVariable evaluates a channel expression

func (*AGI) GetOption 

func (agi *AGI) GetOption(filename, digits string, timeout int32) (Response, error)

GetOption Stream file, prompt for DTMF, with timeout. 

Behaves similar to STREAM FILE but used with a timeout option.
Returns digit pressed, offset and error

func (*AGI) GetVariable 

func (agi *AGI) GetVariable(name string) (Response, error)

GetVariable Gets a channel variable.

func (*AGI) Hangup 

func (agi *AGI) Hangup(channel ...string) (Response, error)

Hangup hangs up the specified channel. If no channel name is given, hangs up the current channel

func (*AGI) IsHungup added in v1.2.0 

func (agi *AGI) IsHungup() bool

IsHungup returns true if AGI channel received HANGUP signal

func (*AGI) ReceiveChar 

func (agi *AGI) ReceiveChar(timeout int) (Response, error)

ReceiveChar Receives one character from channels supporting it. Most channels do not support the reception of text. Returns the decimal value of the character if one is received, or 0 if the channel does not support text reception.

timeout - The maximum time to wait for input in milliseconds, or 0 for infinite.

Returns result -1 on error or char byte

func (*AGI) ReceiveText 

func (agi *AGI) ReceiveText(timeout int) (Response, error)

ReceiveText Receives text from channels supporting it.

timeout - The timeout to be the maximum time to wait for input in milliseconds, or 0 for infinite.

func (*AGI) RecordFile 

func (agi *AGI) RecordFile(file, format, escDigits string,
	timeout, offset int, beep bool, silence int) (Response, error)

RecordFile Record to a file until a given dtmf digit in the sequence is received. The format will specify what kind of file will be recorded. The timeout is the maximum record time in milliseconds, or -1 for no timeout.

offset samples is optional, and, if provided, will seek to the offset without exceeding the end of the file.

beep causes Asterisk to play a beep to the channel that is about to be recorded.

silence is the number of seconds of silence allowed before the function returns despite the lack of dtmf digits or reaching timeout.

silence is the number of seconds of silence that are permitted before the recording is terminated, regardless of the escape_digits or timeout arguments

If interrupted by DTMF, digits will be available in Response.Data()

func (*AGI) SayAlpha 

func (agi *AGI) SayAlpha(line, escDigits string) (Response, error)

SayAlpha says a given character string, returning early if any of the given DTMF digits are received on the channel.

func (*AGI) SayDate 

func (agi *AGI) SayDate(date, escDigits string) (Response, error)

SayDate say a given date, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SayDatetime 

func (agi *AGI) SayDatetime(time, escDigits, format, timezone string) (Response, error)

SayDatetime say a given time, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SayDigits 

func (agi *AGI) SayDigits(number, escDigits string) (Response, error)

SayDigits say a given digit string, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SayNumber 

func (agi *AGI) SayNumber(number, escDigits string) (Response, error)

SayNumber say a given digit string, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SayPhonetic 

func (agi *AGI) SayPhonetic(str, escDigits string) (Response, error)

SayPhonetic say a given character string with phonetics, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SayTime 

func (agi *AGI) SayTime(time, escDigits string) (Response, error)

SayTime say a given time, returning early if any of the given DTMF digits are received on the channel

func (*AGI) SendImage 

func (agi *AGI) SendImage(image string) (Response, error)

SendImage Sends the given image on a channel. Most channels do not support the transmission of images.

func (*AGI) SendText 

func (agi *AGI) SendText(text string) (Response, error)

SendText Sends the given text on a channel. Most channels do not support the transmission of text.

func (*AGI) SetAutoHangup 

func (agi *AGI) SetAutoHangup(seconds int) (Response, error)

SetAutoHangup Cause the channel to automatically hangup at time seconds in the future. Setting to 0 will cause the autohangup feature to be disabled on this channel.

func (*AGI) SetCallerid 

func (agi *AGI) SetCallerid(clid string) (Response, error)

SetCallerid Changes the callerid of the current channel.

func (*AGI) SetContext 

func (agi *AGI) SetContext(ctx string) (Response, error)

SetContext Sets the context for continuation upon exiting the application.

func (*AGI) SetExtension 

func (agi *AGI) SetExtension(ext string) (Response, error)

SetExtension Changes the extension for continuation upon exiting the application.

func (*AGI) SetMusic 

func (agi *AGI) SetMusic(enable bool, class string) (Response, error)

SetMusic Enables/Disables the music on hold generator. If class is not specified, then the default music on hold class will be used.

func (*AGI) SetPriority 

func (agi *AGI) SetPriority(priority string) (Response, error)

SetPriority Changes the priority for continuation upon exiting the application. The priority must be a valid priority or label.

func (*AGI) SetVariable 

func (agi *AGI) SetVariable(name, value string) (Response, error)

SetVariable Sets a variable to the current channel.

func (*AGI) StreamFile 

func (agi *AGI) StreamFile(file, escDigits string, offset int) (Response, error)

StreamFile Send the given file, allowing playback to be interrupted by the given digits, if any.

func (*AGI) TDDMode 

func (agi *AGI) TDDMode(mode string) (Response, error)

TDDMode Enable/Disable TDD transmission/reception on a channel. Modes: on, off, mate, tdd

func (*AGI) Verbose 

func (agi *AGI) Verbose(msg string, level ...int) (Response, error)

Verbose Sends message to the console via verbose message system. level is the verbose level (1-4)

func (*AGI) WaitForDigit 

func (agi *AGI) WaitForDigit(timeout int) (Response, error)

WaitForDigit Waits up to timeout *milliseconds* for channel to receive a DTMF digit. Use -1 for the timeout value if you desire the call to block indefinitely.

Return digit pressed as string or error

type Debugger added in v1.1.0 

type Debugger interface {
	Printf(format string, v ...interface{})
}

Debugger for AGI instance. Any interface that provides Printf method. It should be used only for debugging as it give lots of output.

type Error added in v1.1.0 

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

Error object for goagi library

func (*Error) Error added in v1.1.0 

func (e *Error) Error() string

Error message for the Error object

func (*Error) Msg added in v1.1.0 

func (e *Error) Msg(msg string, args ...interface{}) error

Msg append message to main context message

type Reader added in v1.1.0 

type Reader interface {
	Read(b []byte) (int, error)
}

Reader interface for AGI object. Can be net.Conn, os.File or crafted

type Response added in v1.1.0 

type Response interface {
	// Code of response: 200, 510 etc
	Code() int
	// RawResponse return full text of AGI response
	RawResponse() string
	// Result returns value of result= field
	Result() int
	// Value returns value field: (timeout)
	Value() string
	// Data returns text for error responses and dtmf values for command like GetData
	Data() string
	// EndPos returns value for endpos= field
	EndPos() int64
	// Digit return digit from digit= field
	Digit() string
	// SResults return value for results= field
	SResults() int
}

Response interface that all commands return. Helps to access different parts of AGI response

type Writer added in v1.1.0 

type Writer interface {
	Write(b []byte) (int, error)
}

Writer interface for AGI object. Can be net.Conn, os.File or crafted

Source Files

View all Source files

Directories

Path Synopsis
Example of usage NewAGI for Asterisk.
 Example of usage NewAGI for Asterisk.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.