AmiClient

Asterisk Management Interface (AMI) client library for .NET

• https://github.com/alexforster/AmiClient/
• https://www.nuget.org/packages/AmiClient

Features

• Designed to be used with async/await
• Methods can be safely called from multiple threads
• The AmiClient class is IObservable for use with Reactive Extensions (Rx)

Dependencies

• System.Reactive.Interfaces

Note: While it's not a dependency, you will probably want to use the System.Reactive.Linq package alongside this library.

Quick start

Here's an easy way to set up an Asterisk 13 development environment:

First, build an Asterisk 13 Docker image...

cat <<'EOF' | docker build -t asterisk13 -
FROM amd64/ubuntu:bionic
SHELL ["/bin/bash", "-e", "-u", "-o", "pipefail", "-c"]

RUN \
	export DEBIAN_FRONTEND=noninteractive; \
	apt-get update; \
	apt-get -y install ca-certificates apt-utils; \
	apt-get -y install asterisk;

RUN printf '%s\n' \
	'[general]' \
	'enabled = yes' \
	'bindaddr = 0.0.0.0' \
	'port = 5038' \
	'timestampevents = yes' \
	'' \
	'#include "manager.d/*.conf"' \
> /etc/asterisk/manager.conf

RUN printf '%s\n' \
	'[admin]' \
	'secret = amp111' \
	'read = all' \
	'write = all' \
> /etc/asterisk/manager.d/admin.conf

VOLUME /etc/asterisk
USER asterisk:asterisk
EXPOSE 5038/tcp
EXPOSE 5060/udp
EXPOSE 10000-10500/udp

ENTRYPOINT ["/usr/sbin/asterisk", "-vvvvvvvvv", "-ddddddddd", "-c"]
EOF

Then, run your new Asterisk 13 Docker image in a temporary container...

docker run -it --rm \
           --name asterisk13-dev \
           -p 5060:5060 -p 5060:5060/udp \
           -p 10000-10500:10000-10500/udp \
           -p 5038:5038 \
           asterisk13

Use the example code below as a starting point for learning the AmiClient API...

Example code

using System;
using System.Text;
using System.Net.Sockets;
using System.Threading.Tasks;
using System.Reactive.Linq;

using Ami;

namespace Playground
{
  internal static class Program
  {
    public static async Task Main(String[] args)
    {
      // Let's create the AmiClient and set up some general event handling...

      var client = new AmiClient();

      // Activity on the wire can be observed and logged using the DataSent
      // and DataReceived events...

      client.DataSent += (s, e) =>
        Console.Error.Write($"{Encoding.UTF8.GetString(e.Data)}");
      client.DataReceived += (s, e) =>
        Console.Error.Write($"{Encoding.UTF8.GetString(e.Data)}");

      // To make testing possible, an AmiClient can operate on any underlying
      // Stream object that is readable and writable. This means that the user
      // is responsible for maintaining a TCP connection to the AMI server...

      var socket = new TcpClient(hostname: "127.0.0.1", port: 5038);

      // The Stopped event can be used to observe when the AmiClient stops
      // processing the underlying stream for any reason...

      client.Stopped += (s, e) =>
      {
        if(e.Exception != null)
        {
          Console.Error.WriteLine($"Exception: {e.Exception}");
        }
      };

      // Let's go...

      using(socket)
      using(client)
      {
        // First, complete the AMI protocol handshake and start a background
        // I/O task to consume data from the socket...

        await client.Start(socket.GetStream());

        // Next, let's authenticate using the Login() helper function...

        if(!await client.Login(username: "admin", secret: "amp111", md5: true))
        {
          Console.Out.WriteLine("Login failed");
          return;
        }

        // In case the Asterisk server hasn't finished booting, let's wait
        // until it's ready...

        await client.Where(message => message["Event"] == "FullyBooted").FirstAsync();

        // Now, let's issue a PJSIPShowEndpoints command...

        var response = await client.Publish(new AmiMessage
        {
          { "Action", "PJSIPShowEndpoints" },
        });

        // Because we didn't specify an ActionID, one was implicitly
        // created for us by the AmiMessage object. That's how we track
        // requests and responses, allowing this client to be used
        // by multiple threads or tasks.

        if(response["Response"] == "Success")
        {
          // After the PJSIPShowEndpoints command successfully executes,
          // Asterisk will begin emitting EndpointList events.

          // Each EndpointList event represents a single PJSIP endpoint,
          // and has the same ActionID as the PJSIPShowEndpoints command
          // that caused it.

          // Once events have been emitted for all PJSIP endpoints,
          // an EndpointListComplete event will be emitted, again with
          // the same ActionID as the PJSIPShowEndpoints command
          // that caused it.

          // Using System.Reactive.Linq, all of that can be modeled with
          // a simple Rx IObservable consumer...

          await client
              .Where(message => message["ActionID"] == response["ActionID"])
              .TakeWhile(message => message["Event"] != "EndpointListComplete")
              .Do(message =>
                  Console.Out.WriteLine(
                    $"~~~ \"{message["ObjectName"]}\" ({message["DeviceState"]}) ~~~"));
        }

        // We're done, so let's be a good client and use the Logoff()
        // helper function...

        if(!await client.Logoff())
        {
          Console.Out.WriteLine("Logoff failed");
          return;
        }
      }
    }
  }
}

Example output

Action: Challenge
ActionID: 24871f64-ca7e-4dfb-a67f-734ba3893efb
AuthType: MD5

Response: Success
ActionID: 24871f64-ca7e-4dfb-a67f-734ba3893efb
Challenge: 158303519

Action: Login
ActionID: 214fdbe7-7c7c-4ead-abfe-037a3d4cedff
AuthType: MD5
Username: admin
Key: 6a717a8d45e8445832d5d088862654e9

Response: Success
ActionID: 214fdbe7-7c7c-4ead-abfe-037a3d4cedff
Message: Authentication accepted

Event: FullyBooted
Privilege: system,all
Status: Fully Booted

Action: PJSIPShowEndpoints
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2

Event: SuccessfulAuth
Privilege: security,all
EventTV: 2019-01-21T19:56:27.148+0000
Severity: Informational
Service: AMI
EventVersion: 1
AccountID: admin
SessionID: 0x7fcb00000d50
LocalAddress: IPV4/TCP/0.0.0.0/5038
RemoteAddress: IPV4/TCP/172.17.0.1/44628
UsingPassword: 0
SessionTV: 2019-01-21T19:56:27.148+0000

Response: Success
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
EventList: start
Message: A listing of Endpoints follows, presented as EndpointList events

Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1107
Transport: 
Aor: 1107
Auths: 1107
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1107" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1113
Transport: 
Aor: 1113
Auths: 1113
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1113" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1106
Transport: 
Aor: 1106
Auths: 1106
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1106" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1101
Transport: 
Aor: 1101
Auths: 1101
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1101" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1103
Transport: 
Aor: 1103
Auths: 1103
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1103" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1102
Transport: 
Aor: 1102
Auths: 1102
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1102" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1114
Transport: 
Aor: 1114
Auths: 1114
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1114" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1115
Transport: 
Aor: 1115
Auths: 1115
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1115" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1109
Transport: 
Aor: 1109
Auths: 1109
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1109" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1110
Transport: 
Aor: 1110
Auths: 1110
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1110" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: dcs-endpoint
Transport: 
Aor: dcs-aor
Auths: 
OutboundAuths: dcs-auth
Contacts: dcs-aor/sip:sip.digiumcloud.net,
DeviceState: Not in use
ActiveChannels: 

~~~ "dcs-endpoint" (Not in use) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1111
Transport: 
Aor: 1111
Auths: 1111
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1111" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1105
Transport: 
Aor: 1105
Auths: 1105
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1105" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1108
Transport: 
Aor: 1108
Auths: 1108
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1108" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1112
Transport: 
Aor: 1112
Auths: 1112
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1112" (Unavailable) ~~~
Event: EndpointList
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
ObjectType: endpoint
ObjectName: 1104
Transport: 
Aor: 1104
Auths: 1104
OutboundAuths: 
Contacts: 
DeviceState: Unavailable
ActiveChannels: 

~~~ "1104" (Unavailable) ~~~
Event: EndpointListComplete
ActionID: 3ec566db-feec-4758-bc41-407ae70491c2
EventList: Complete
ListItems: 16

Action: Logoff
ActionID: e8427d14-04c4-43f3-9f03-e9dd2fc1b891

Response: Goodbye
ActionID: e8427d14-04c4-43f3-9f03-e9dd2fc1b891
Message: Thanks for all the fish.

Public API

public sealed class AmiMessage : IEnumerable<KeyValuePair<String, String>>
{
   public AmiMessage();

   public DateTimeOffset Timestamp { get; }

   // deserialization

   public static AmiMessage FromBytes(Byte[] bytes);

   public static AmiMessage FromString(String @string);

   // direct field access

   public readonly List<KeyValuePair<String, String>> Fields;

   // field initialization support

   public void Add(String key, String value);

   // field indexer support

   public String this[String key] { get; set; }

   // field enumeration support

   public IEnumerator<KeyValuePair<String, String>> GetEnumerator();

   IEnumerator IEnumerable.GetEnumerator();

   // serialization

   public Byte[] ToBytes();

   public override String ToString();
}

public sealed class AmiClient : IDisposable, IObservable<AmiMessage>
{
   public AmiClient();

   // lifecycle management

   public async Task<Task> Start(Stream stream);

   public void Stop();

   public sealed class LifecycleEventArgs : EventArgs
   {
       public readonly Exception Exception;
   }

   public event EventHandler<LifecycleEventArgs> Stopped;

   // AMI protocol helpers

   public async Task<Boolean> Login(String username, String secret, Boolean md5 = true);

   public async Task<Boolean> Logoff();

   // AMI protocol debugging

   public sealed class DataEventArgs : EventArgs
   {
       public readonly Byte[] Data;
   }

   public event EventHandler<DataEventArgs> DataSent;

   public event EventHandler<DataEventArgs> DataReceived;

   // request/reply

   public async Task<AmiMessage> Publish(AmiMessage action);

   // IObservable<AmiMessage>

   public IDisposable Subscribe(IObserver<AmiMessage> observer);

   public void Unsubscribe(IObserver<AmiMessage> observer);

   public void Dispose();
}