goesl

README

##FreeSWITCH Event Socket Library Wrapper for Go

GoESL is a small wrapper around FreeSWITCH Event Socket Library written in Go.

Point of this library is to fully implement FreeSWITCH ESL and bring outbound server as inbound client to you, fellow Go developer :)

TODO?

You can find what still needs to be done at GoESL TODO

Examples

There are few different types of examples that can be found at GoESL Examples.

Feel free to suggest more examples :)

Contributions / Issues?

Please reach me over nevio.vesic@gmail.com or visit my website or submit new issue. I'd prefer tho if you would submit issue.

License

The MIT License (MIT)

Copyright (c) 2015 Nevio Vesic

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• Variables
• func Debug(message string, args ...interface{})
• func Error(message string, args ...interface{})
• func Info(message string, args ...interface{})
• func Notice(message string, args ...interface{})
• func StringInSlice(str string, list []string) bool
• func Warning(message string, args ...interface{})
• type Client
  • func NewClient(host string, port uint, passwd string, timeout int) (*Client, error)
  • func (c *Client) Authenticate() error
  • func (c *Client) EstablishConnection() error
• type Message
  • func (m *Message) Dump() (resp string)
  • func (m *Message) GetCallUUID() string
  • func (m *Message) GetHeader(key string) string
  • func (m *Message) Parse() error
  • func (m *Message) PrettyPrint()
  • func (m *Message) String() string
• type OutboundServer
  • func NewOutboundServer(addr string) (*OutboundServer, error)
  • func (s *OutboundServer) Start() error
  • func (s *OutboundServer) Stop()
• type SocketConnection
  • func (sc *SocketConnection) Api(command string) error
  • func (sc *SocketConnection) BgApi(command string) error
  • func (c *SocketConnection) Close() error
  • func (sc *SocketConnection) Connect() error
  • func (c *SocketConnection) Dial(network string, addr string, timeout time.Duration) (net.Conn, error)
  • func (c *SocketConnection) Execute(command, args string, sync bool) (m *Message, err error)
  • func (sc *SocketConnection) ExecuteAnswer(args string, sync bool) (m *Message, err error)
  • func (sc *SocketConnection) ExecuteHangup(uuid string, args string, sync bool) (m *Message, err error)
  • func (sc *SocketConnection) ExecuteSet(key string, value string, sync bool) (m *Message, err error)
  • func (c *SocketConnection) ExecuteUUID(uuid string, command string, args string, sync bool) (m *Message, err error)
  • func (sc *SocketConnection) Exit() error
  • func (c *SocketConnection) Handle()
  • func (c *SocketConnection) OriginatorAddr() net.Addr
  • func (c *SocketConnection) ReadMessage() (*Message, error)
  • func (c *SocketConnection) Send(cmd string) error
  • func (c *SocketConnection) SendEvent(eventHeaders []string) error
  • func (c *SocketConnection) SendMany(cmds []string) error
  • func (c *SocketConnection) SendMsg(msg map[string]string, uuid, data string) (m *Message, err error)

Variables

var (
	EInvalidCommandProvided  = "Invalid command provided. Command cannot contain \\r and/or \\n. Provided command is: %s"
	ECouldNotReadMIMEHeaders = "Error while reading MIME headers: %s"
	EInvalidContentLength    = "Unable to get size of content-length: %s"
	EUnsuccessfulReply       = "Got error while reading from reply command: %s"
	ECouldNotReadyBody       = "Got error while reading reader body: %s"
	EUnsupportedMessageType  = "Unsupported message type! We got '%s'. Supported types are: %v "
	ECouldNotDecode          = "Could not decode/unescape message: %s"
	ECouldNotStartListener   = "Got error while attempting to start listener: %s"
	EListenerConnection      = "Listener connection error: %s"
	EInvalidServerAddr       = "Please make sure to pass along valid address. You've passed: \"%s\""
	EUnexpectedAuthHeader    = "Expected auth/request content type. Got %s"
	EInvalidPassword         = "Could not authenticate against freeswitch with provided password: %s"
	ECouldNotCreateMessage   = "Error while creating new message: %s"
	ECouldNotSendEvent       = "Must send at least one event header, detected `%d` header"
)

var (

	// Size of buffer when we read from connection.
	// 1024 << 6 == 65536
	ReadBufferSize = 1024 << 6

	// Freeswitch events that we can handle (have logic for it)
	AvailableMessageTypes = []string{"auth/request", "text/disconnect-notice", "text/event-json", "text/event-plain", "api/response", "command/reply"}
)

Functions

func Debug

func Debug(message string, args ...interface{})

func Error

func Error(message string, args ...interface{})

func Info

func Info(message string, args ...interface{})

func Notice

func Notice(message string, args ...interface{})

func StringInSlice

func StringInSlice(str string, list []string) bool

StringInSlice - Will check if string in list. This is equivalent to python if x in [] @TODO - What the fuck Nevio...

func Warning

func Warning(message string, args ...interface{})

Types

type Client

type Client struct {
	SocketConnection

	Proto   string `json:"freeswitch_protocol"`
	Addr    string `json:"freeswitch_addr"`
	Passwd  string `json:"freeswitch_password"`
	Timeout int    `json:"freeswitch_connection_timeout"`
}

Client - In case you need to do inbound dialing against freeswitch server in order to originate call or see sofia statuses or whatever else you came up with

func NewClient

func NewClient(host string, port uint, passwd string, timeout int) (*Client, error)

NewClient - Will initiate new client that will establish connection and attempt to authenticate against connected freeswitch server

func (*Client) Authenticate

func (c *Client) Authenticate() error

Authenticate - Method used to authenticate client against freeswitch. In case of any errors durring so we will return error.

func (*Client) EstablishConnection

func (c *Client) EstablishConnection() error

EstablishConnection - Will attempt to establish connection against freeswitch and create new SocketConnection

type Message

type Message struct {
	Headers map[string]string
	Body    []byte
	// contains filtered or unexported fields
}

Message - Freeswitch Message that is received by GoESL. Message struct is here to help with parsing message and dumping its contents. In addition to that it's here to make sure received message is in fact message we wish/can support

func (*Message) Dump

func (m *Message) Dump() (resp string)

Dump - Will return message prepared to be dumped out. It's like prettify message for output

func (*Message) GetCallUUID

func (m *Message) GetCallUUID() string

GetCallUUID - Will return Caller-Unique-Id

func (*Message) GetHeader

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

GetHeader - Will return message header value, or "" if the key is not set.

func (*Message) Parse

func (m *Message) Parse() error

Parse - Will parse out message received from Freeswitch and basically build it accordingly for later use. However, in case of any issues func will return error.

func (*Message) PrettyPrint

func (m *Message) PrettyPrint()

func (*Message) String

func (m *Message) String() string

String - Will return message representation as string

type OutboundServer

type OutboundServer struct {
	net.Listener

	Addr  string `json:"address"`
	Proto string

	Conns chan SocketConnection
}

OutboundServer - In case you need to start server, this Struct have it covered

func NewOutboundServer

func NewOutboundServer(addr string) (*OutboundServer, error)

NewOutboundServer - Will instanciate new outbound server

func (*OutboundServer) Start

func (s *OutboundServer) Start() error

Start - Will start new outbound server

func (*OutboundServer) Stop

func (s *OutboundServer) Stop()

Stop - Will close server connection once SIGTERM/Interrupt is received

type SocketConnection

type SocketConnection struct {
	net.Conn
	// contains filtered or unexported fields
}

Main connection against ESL - Gotta add more description here

func (*SocketConnection) Api

func (sc *SocketConnection) Api(command string) error

BgApi - Helper designed to attach api in front of the command so that you do not need to write it

func (*SocketConnection) BgApi

func (sc *SocketConnection) BgApi(command string) error

BgApi - Helper designed to attach bgapi in front of the command so that you do not need to write it

func (*SocketConnection) Close

func (c *SocketConnection) Close() error

Close - Will close down net connection and return error if error happen

func (*SocketConnection) Connect

func (sc *SocketConnection) Connect() error

Connect - Helper designed to help you handle connection. Each outbound server when handling needs to connect e.g. accept connection in order for you to do answer, hangup or do whatever else you wish to do

func (*SocketConnection) Dial

func (c *SocketConnection) Dial(network string, addr string, timeout time.Duration) (net.Conn, error)

Dial - Will establish timedout dial against specified address. In this case, it will be freeswitch server

func (*SocketConnection) Execute

func (c *SocketConnection) Execute(command, args string, sync bool) (m *Message, err error)

Execute - Helper fuck to execute commands with its args and sync/async mode

func (*SocketConnection) ExecuteAnswer

func (sc *SocketConnection) ExecuteAnswer(args string, sync bool) (m *Message, err error)

ExecuteHangup - Helper desgned to help with executing Answer against active ESL session

func (*SocketConnection) ExecuteHangup

func (sc *SocketConnection) ExecuteHangup(uuid string, args string, sync bool) (m *Message, err error)

ExecuteHangup - Helper desgned to help with executing Hangup against active ESL session

func (*SocketConnection) ExecuteSet

func (sc *SocketConnection) ExecuteSet(key string, value string, sync bool) (m *Message, err error)

Set - Helper that you can use to execute SET application against active ESL session

func (*SocketConnection) ExecuteUUID

func (c *SocketConnection) ExecuteUUID(uuid string, command string, args string, sync bool) (m *Message, err error)

ExecuteUUID - Helper fuck to execute uuid specific commands with its args and sync/async mode

func (*SocketConnection) Exit

func (sc *SocketConnection) Exit() error

Exit - Used to send exit signal to ESL. It will basically hangup call and close connection

func (*SocketConnection) Handle

func (c *SocketConnection) Handle()

Handle - Will handle new messages and close connection when there are no messages left to process

func (*SocketConnection) OriginatorAddr

func (c *SocketConnection) OriginatorAddr() net.Addr

OriginatorAdd - Will return originator address known as net.RemoteAddr() This will actually be a freeswitch address

func (*SocketConnection) ReadMessage

func (c *SocketConnection) ReadMessage() (*Message, error)

ReadMessage - Will read message from channels and return them back accordingy.  If error is received, error will be returned. If not, message will be returned back!

func (*SocketConnection) Send

func (c *SocketConnection) Send(cmd string) error

Send - Will send raw message to open net connection

func (*SocketConnection) SendEvent

func (c *SocketConnection) SendEvent(eventHeaders []string) error

SendEvent - Will loop against passed event headers

func (*SocketConnection) SendMany

func (c *SocketConnection) SendMany(cmds []string) error

SendMany - Will loop against passed commands and return 1st error if error happens

func (*SocketConnection) SendMsg

func (c *SocketConnection) SendMsg(msg map[string]string, uuid, data string) (m *Message, err error)

SendMsg - Basically this func will send message to the opened connection