iamkinetic / neventsocket

A reactive FreeSwitch eventsocket library for .Net/.Net Framework (.net standard 2)

NEventSocket.DotNetCore

Windows / .NET	Linux / Mono

NEventSocket is a FreeSwitch event socket client/server library for .Net/.Net Framework (.Net Standard 2). This is pretty much a direct port of danbarua/NEventSocket.

Installing Release builds

Package Manager Console: Install-Package NEventSocket.DotNetCore

CommandLine: nuget install NEventSocket.DotNetCore

Inbound Socket Client

An InboundSocket connects and authenticates to a FreeSwitch server (inbound from the point of view of FreeSwitch) and can listen for all events going on in the system and issue commands to control calls. You can use ReactiveExtensions to filter events using LINQ queries and extension methods. All methods are async and awaitable.

using System;
using System.Reactive.Linq;
using System.Threading.Tasks;

using NEventSocket;
using NEventSocket.FreeSwitch;

using (var socket = await InboundSocket.Connect("localhost", 8021, "ClueCon"))
{
  var apiResponse = await socket.SendApi("status");
  Console.WriteLine(apiResponse.BodyText);

  //Tell FreeSwitch which events we are interested in
  await socket.SubscribeEvents(EventName.ChannelAnswer);

  //Handle events as they come in using Rx
  socket.ChannelEvents.Where(x => x.EventName == EventName.ChannelAnswer)
        .Subscribe(async x =>
            {
                Console.WriteLine("Channel Answer Event " +  x.UUID);

                //we have a channel id, now we can control it
                await socket.Play(x.UUID, "misc/8000/misc-freeswitch_is_state_of_the_art.wav");
            });

  Console.WriteLine("Press [Enter] to exit.");
  Console.ReadLine();
}

Outbound Socket Server

An OutboundListener listens on a TCP port for socket connections (outbound from the point of view of FreeSwitch) when the FreeSwitch dialplan is setup to route calls to the EventSocket. An OutboundSocket receives events for one particular channel, the API is the same as for an InboundSocket, so you will need to pass in the channel UUID to issue commands for it.

Don't forget to use the async and full flags in your dialplan. async means that applications will not block (e.g. a bridge will block until the channel hangs up and completes the call) and full gives the socket access to the full EventSocket api (without this you will see -ERR Unknown Command responses)

<action application="socket" data="127.0.0.1:8084 async full"/>

using System;
using System.Reactive.Linq;
using System.Threading.Tasks;

using NEventSocket;
using NEventSocket.FreeSwitch;

using (var listener = new OutboundListener(8084))
{
  listener.Connections.Subscribe(
    async socket => {
      await socket.Connect();

      //after calling .Connect(), socket.ChannelData
      //is populated with all the headers and variables of the channel

      var uuid = socket.ChannelData.Headers[HeaderNames.UniqueId];
      Console.WriteLine("OutboundSocket connected for channel " + uuid);

      await socket.SubscribeEvents(EventName.ChannelHangup);

      socket.ChannelEvents
            .Where(x => x.EventName == EventName.ChannelHangup && x.UUID == uuid)
            .Take(1)
            .Subscribe(async x => {
                  Console.WriteLine("Hangup Detected on " + x.UUID);
                  await socket.Exit();
            });
      
      
      //if we use 'full' in our FS dialplan, we'll get events for ALL channels in FreeSwitch
      //this is not desirable here - so we'll filter in for our unique id only
      //cases where this is desirable is in the channel api where we want to catch other channels bridging to us
      await socket.Filter(HeaderNames.UniqueId, uuid);
      
      //tell FreeSwitch not to end the socket on hangup, we'll catch the hangup event and .Exit() ourselves
      await socket.Linger();
      
      await socket.ExecuteApplication(uuid, "answer");
      await socket.Play(uuid, "misc/8000/misc-freeswitch_is_state_of_the_art.wav");
      await socket.Hangup(uuid, HangupCause.NormalClearing);
    });

  listener.Start();

  Console.WriteLine("Press [Enter] to exit.");
  Console.ReadLine();
}

Error Handling

NEventSocket makes a best effort to handle errors gracefully, there is one scenario that you do need to handle in your application code. In a realtime async application, there may be a situation where we are trying to write to a socket when FreeSwitch has already hung up and disconnected the socket. In this case, NEventSocket will throw a TaskCanceledException (Note incorrect spelling of Cancelled) which you can catch in order to do any clean up.

It's a good idea to wrap any IObservable.Subscribe(() => {}) callbacks in a try/catch block.

try {
  await socket.Connect();

  var uuid = socket.ChannelData.Headers[HeaderNames.UniqueId];
  Console.WriteLine("OutboundSocket connected for channel " + uuid);

  await socket.SubscribeEvents(EventName.Dtmf);

  socket.ChannelEvents.Where(x => x.UUID == uuid && x.EventName == EventName.Dtmf)
        .Subscribe(async e => {
          try {
            Console.WriteLine(e.Headers[HeaderNames.DtmfDigit]);
           //speak the number to the caller
            await client.Say(
                  uuid,
                  new SayOptions()
                  {
                    Text = e.Headers[HeaderNames.DtmfDigit],
                    Type = SayType.Number,
                    Method = SayMethod.Iterated
                    });
           }
           catch(TaskCanceledException ex){
            //channel hungup
           }
      ));
}
catch (TaskCanceledException ex) {
  //FreeSwitch disconnected, do any clean up here.
}

Channel API

Whilst the InboundSocket and OutboundSocket give you a close-to-the-metal experience with the EventSocket interface, the Channel API is a high level abstraction built on top of these. A Channel object maintains its own state by subscribing to events from FreeSwitch and allows us to control calls in a more object oriented manner without having to pass channel UUIDs around as strings.

Although the InboundSocket and OutboundSocket APIs are reasonably stable, the Channel API is a work in progress with the goal of providing a pleasant, easy to use, strongly-typed API on top of the EventSocket.

There is an in-depth example in the examples/Channels folder.

using System;
using System.Reactive.Linq;
using System.Threading.Tasks;

using NEventSocket;
using NEventSocket.Channels;
using NEventSocket.FreeSwitch;
using NEventSocket.Util;

using (var listener = new OutboundListener(8084))
{
  listener.Channels.Subscribe(
    async channel => {
      try
      {
          await channel.Answer();
          await channel.PlayFile("ivr/8000/ivr-call_being_transferred.wav");
          await channel.StartDetectingInbandDtmf();

          var bridgeOptions = 
                  new BridgeOptions()
                      {
                        IgnoreEarlyMedia = true,
                        RingBack =
                            "tone_stream://%(400,200,400,450);%(400,2000,400,450);loops=-1",
                        ContinueOnFail = true,
                        HangupAfterBridge = true,
                        TimeoutSeconds = 60,
                        //can get variables from a channel using the indexer
                        CallerIdName = channel["effective_caller_id_name"], 
                        CallerIdNumber = channel["effective_caller_id_number"],
                      };

          //attempt a bridge to user/1001, write to the console when it starts ringing
          await channel.BridgeTo("user/1001", 
                                  bridgeOptions,
                                  (evt) => Console.WriteLine("B-Leg is ringing..."))

          //channel.Bridge represents the bridge status
          if (!channel.Bridge.IsBridged)
          {
              //we can inspect the HangupCause to determine why it failed
              Console.WriteLine("Bridge Failed - {0}".Fmt(channel.Bridge.HangupCause));
              await channel.PlayFile("ivr/8000/ivr-call_rejected.wav");
              await channel.Hangup(HangupCause.NormalTemporaryFailure);
              return;
          }
              
          Console.WriteLine("Bridge success - {0}".Fmt(channel.Bridge.ResponseText));

          //the bridged channel maintains its own state
          //and handles a subset of full Channel operations
          channel.Bridge.Channel.HangupCallBack = 
            (e) => ColorConsole.WriteLine("Hangup Detected on B-Leg {0} {1}"
                  .Fmt(e.Headers[HeaderNames.CallerUniqueId],
                    e.Headers[HeaderNames.HangupCause]));

          //we'll listen out for the feature code #9
          //on the b-leg to do an attended transfer
          channel.Bridge.Channel.FeatureCodes("#")
            .Subscribe(async x =>
            {
              switch (x)
              {
                case "#9":
                  Console.WriteLine("Getting the extension to do an attended transfer to...");

                  //play a dial tone to the b-leg and get 4 digits to dial
                  var digits = await channel.Bridge.Channel.Read(
                                    new ReadOptions {
                                        MinDigits = 3,
                                        MaxDigits = 4, 
                                        Prompt = "tone_stream://%(10000,0,350,440)",
                                        TimeoutMs = 30000,
                                        Terminators = "#" });

                  if (digits.Result == ReadResultStatus.Success && digits.Digits.Length == 4)
                  {
                    await channel.Bridge.Channel
                      .PlayFile("ivr/8000/ivr-please_hold_while_party_contacted.wav");
                    
                    var xfer = await channel.Bridge.Channel
                      .AttendedTransfer("user/{0}".Fmt(digits));

                    //attended transfers are a work-in-progress at the moment
                    if (xfer.Status == AttendedTransferResultStatus.Failed)
                    {
                      if (xfer.HangupCause == HangupCause.CallRejected)
                      {
                          //we can play audio into the b-leg via the a-leg channel
                          await channel
                            .PlayFile("ivr/8000/ivr-call-rejected.wav", Leg.BLeg);
                      }
                      else if (xfer.HangupCause == HangupCause.NoUserResponse 
                                || xfer.HangupCause == HangupCause.NoAnswer)
                      {
                          //or we can play audio on the b-leg channel object
                          await channel.Bridge.Channel
                            .PlayFile("ivr/8000/ivr-no_user_response.wav");
                      }
                      else if (xfer.HangupCause == HangupCause.UserBusy)
                      {
                          await channel.Bridge.Channel
                            .PlayFile("ivr/8000/ivr-user_busy.wav");
                      }
                    }
                    else
                    {
                      //otherwise the a-leg is now connected to either
                      // 1) the c-leg
                      //    in this case, channel.Bridge.Channel is now the c-leg channel
                      // 2) the b-leg and the c-leg in a 3-way chat
                      //    in this case, if the b-leg hangs up, then channel.Bridge.Channel
                      //    will become the c-leg
                      await channel
                      .PlayFile("ivr/8000/ivr-call_being_transferred.wav", Leg.ALeg);
                    }
                  }
                break;
              }
            });
      }
      catch(TaskCanceledException)
      {
          Console.WriteLine("Channel {0} hungup".Fmt(channel.UUID));
      }
    }
    });

  listener.Start();

  Console.WriteLine("Press [Enter] to exit.");
  Console.ReadLine();
}

neventsocket's Issues

does support Freeswitch 1.10.6 ?

some code like these :
using (var socket = await InboundSocket.Connect("192.168.1.100", 8021, "123456789"))
{

                //Tell FreeSwitch which events we are interested in
              //  await socket.SubscribeEvents(EventName.All);
                 await socket.SubscribeEvents(EventName.ChannelAnswer,EventName.ChannelCreate);
                //Handle events as they come in using Rx
                socket.ChannelEvents.Where(x => (x.EventName == EventName.ChannelAnswer
                || x.EventName == EventName.ChannelCreate
                    || x.EventName == EventName.ChannelHangup
                       || x.EventName == EventName.ChannelHangupComplete
                || EventName.ChannelOriginate == x.EventName
                || x.EventName == EventName.ChannelDestroy))
                          .Subscribe(async x =>
                      {
                          Console.WriteLine("Channel Answer Event " + x.UUID);

                          //we have a channel id, now we can control it
                          await socket.Play(x.UUID, "misc/8000/misc-freeswitch_is_state_of_the_art.wav");
                      });

                var apiResponse = await socket.SendApi("status");
                Console.WriteLine(apiResponse.BodyText);
                Console.WriteLine((await socket.SendApi("status")).BodyText);
                Console.WriteLine();
                Console.WriteLine((await socket.SendApi("invalid_api_command")).BodyText);
                Console.WriteLine();
                Console.WriteLine((await socket.SendApi("sofia status")).BodyText);
                Console.WriteLine();
                Console.WriteLine((await socket.SendApi("show bridged_calls")).BodyText);

                Console.WriteLine("Press [Enter] to exit.");
                Console.ReadLine();
            }

SendApi(...) looks ok . but xxxxx. .Subscribe(async x =>..... nothing happen at all when i use microsip for some dials .
i need some help for my question . please.. .

Examples cannot run

Examples cannot run. tips： Net.Reflection, Net.System, Net.Text not found！

Support Voicemail natively

ITNOA

Is your feature request related to a problem? Please describe.
This feature request is aimed at accessing the events published by freeswitch regarding it's VoiceMail functionality.

Describe the solution you'd like
Natively supporting Event Headers and Messages in a structured way pertaining to Voice mail module of freeswitch.

Describe alternatives you've considered
while these events can be manually parsed as any other custom event at a higher layer, It is preferable to Implement the parsing of these events data alongside other custom events to prevent code duplication and move logic closer to data.

Value cannot be null. (Parameter 'factory')

I created a simple program and got Value cannot be null. (Parameter 'factory') from Microsoft.Extensions.Logging.Abstractions

code as follows :

using System;
using System.Reactive.Linq;
using System.Threading.Tasks;
using NEventSocket;
using NEventSocket.FreeSwitch;

namespace ConsoleApp1
{
class Program
{
static async Task Main(string[] args)
{
await CallTracking();

        Console.WriteLine("Hello World!");
    }

    public static async Task CallTracking()
    {
        using (var socket = await InboundSocket.Connect("XXX.XXX.XXX.XXX", 8021, "ClueCon"))
        {
            var apiResponse = await socket.SendApi("status");
            Console.WriteLine(apiResponse.BodyText);

            //Tell FreeSwitch which events we are interested in
            await socket.SubscribeEvents(EventName.ChannelAnswer);

            //Handle events as they come in using Rx
            socket.ChannelEvents.Where(x => x.EventName == EventName.ChannelAnswer)
                  .Subscribe(async x =>
                  {
                      Console.WriteLine("Channel Answer Event " + x.UUID);

                      //we have a channel id, now we can control it
                      await socket.Play(x.UUID, "misc/8000/misc-freeswitch_is_state_of_the_art.wav");
                  });
        }
    }
}

}

any ideas ??

i am using .net core 3.1

ChannelData.UUID from InboundSocket.Originate returns null

I was following the Demo https://github.com/iamkinetic/NEventSocket/blob/master/NEventSocket.Examples/Examples/DtmfExample.cs
But the program crashes since ChannelData.UUID is null.
I am using Freeswitch 1.10.6, with default configuration
For the softphones I used MicroSip and PhonerLite
the OS is Windows10

To Reproduce
Steps to reproduce the behavior:

1. Download Freeswitch,softphones and setup visual studio
2. Create new solution/project (and install NEventSocket using NuGet)
3. In Program.cs put this code:
   `using Microsoft.Extensions.Logging;
   using NEventSocket;
   using NEventSocket.FreeSwitch;
   using System;
   using System.Collections.Generic;
   using System.Reactive.Linq;
   using System.Threading.Tasks;

namespace Test_FSw
{
class Program
{
static async Task Main(string[] args)
{
NEventSocket.Logging.Logger.Configure(new LoggerFactory());
InboundSocket client;
client = await InboundSocket.Connect("localhost", 8021, "ClueCon", TimeSpan.FromSeconds(20));

        var originate = await client.Originate("user/1001", new OriginateOptions
        {
            CallerIdNumber = "123456789",
            CallerIdName = "test2",
            HangupAfterBridge = false,
            TimeoutSeconds = 20
        });

        if (!originate.Success)
        {
            Console.WriteLine("Failed");
            Console.WriteLine(originate.HangupCause.ToString());
            await client.Exit();
        }
        else
        {
            Console.WriteLine(originate.ChannelData.UUID);/*UUID or ChannelData is null*/
            var uuid = originate.ChannelData.UUID;
            /*unreached code*/
            await client.SubscribeEvents(EventName.Dtmf);
        }
        Console.WriteLine("Exit[Enter]");
        Console.ReadLine();


    }
   
}

}

`
4. Execute

Error compiling file commandlinereader

'“string”未包含“To”的定义，并且找不到可接受第一个“string”类型参数的可访问扩展方法“To”(是否缺少 using 指令或程序集引用?)NEventSocket.Examples\NetCore\CommandLineReader.cs
'“PropertyInfo”未包含“GetAttribute”的定义，并且找不到可接受第一个“PropertyInfo”类型参数的可访问扩展方法“GetAttribute”(是否缺少 using 指令或程序集引用?) NEventSocket.Examples\NetCore\CommandLineReader.cs

命名空间“Net”中不存在类型或命名空间名“System”(是否缺少程序集引用?) NEventSocket.Examples K:\FSEventSocket\NEventSocket.Examples\NetCore\CommandLineReader.cs
命名空间“Net”中不存在类型或命名空间名“Text”(是否缺少程序集引用?) NEventSocket.Examples K:\FSEventSocket\NEventSocket.Examples\NetCore\CommandLineReader.cs

SubscribeEvents may not be Thread-Safe

I was using InboundSocket to originate some calls and play Audio files, and sometimes i got an ThrowInvalidOperationException_ConcurrentOperationsNotSupported where I called Play(...).

Here is the call stack:

    System.ThrowHelper.ThrowInvalidOperationException_ConcurrentOperationsNotSupported()
    System.Collections.Generic.HashSet<T>.FindItemIndex(T)
    System.Collections.Generic.HashSet<T>.Contains(T)
    NEventSocket.Sockets.EventSocket.SubscribeEvents.AnonymousMethod__28_0(NEventSocket.FreeSwitch.EventName)
    System.Linq.Enumerable.All<TSource>(System.Collections.Generic.IEnumerable<TSource>, System.Func<TSource, bool>)
    NEventSocket.Sockets.EventSocket.SubscribeEvents(NEventSocket.FreeSwitch.EventName[])
    NEventSocket.Sockets.EventSocket.ExecuteApplication(string, string, string, bool, bool, int)
    NEventSocket.ApplicationExtensions.Play(NEventSocket.Sockets.EventSocket, string, string, NEventSocket.FreeSwitch.PlayOptions)

I checked the library and I noticed the use of HashSet:
private readonly HashSet<EventName> subscribedEvents = new HashSet<EventName>();

Am I missing something or is it really not Thread-Safe ?

Release version 1.0 non beta.

Let's release version 1.0.

I don't understand how to use it

For beginners, I don't need to care about NEventSocket.Tests. I just need to introduce the NEventSocket class library in my own project, and call InboundSocket.cs and OutboundListener.cs during project execution. Can I just listen? Is there a demo that can be run directly.

Update documentation

Is your feature request related to a problem? Please describe.
The documentation is not up to date. Some work needs to be done.

Is this library alive?

ITNOA

Hi

Is this library alive?

Examples are not compatible with Net Core 3.x

Solution builds ok on Net Core 2.x. But when changing to Net Core 3.0, example project doesn't build. Get a lot of errors like:
'ILifetimeScope' does not contain a definition for 'ImplementationsFor' and no accessible extension method 'ImplementationsFor' accepting a first argument of type 'ILifetimeScope' could be found

Guess some extensions are missing in Net Core 3.x.

Any ideas?

Best regards, Gregor