overloading EventParser.Parse method and adding EventParser.ParseMany. Add code examples to README.md (#30373)

Author: yyw-msft

sdk/communication/Azure.Communication.CallingServer/README.md

@@ -49,7 +49,7 @@ To make an outbound call, call the `CreateCall` or `CreateCallAsync` function fr
 CallSource callSource = new CallSource(
        new CommunicationUserIdentifier("<source-identifier>"), // Your Azure Communication Resource Guid Id used to make a Call
        );
-callSource.CallerId = new PhoneNumberIdentifier("<caller-id-phonenumber>") // E.164 formatted recipient phone number
+callSource.CallerId = new PhoneNumberIdentifier("<caller-id-phonenumber>") // E.164 formatted phone number that's associated to your Azure Communication Resource
 ```
 ```C#
 CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(
@@ -60,6 +60,60 @@ CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(
 Console.WriteLine($"Call connection id: {createCallResult.CallProperties.CallConnectionId}");
 ```
 
+### Handle Mid-Connection call back events
+Your app will receive mid-connection call back events via the callbackEndpoint you provided. You will need to write event handler controller to receive the events and direct your app flow based on your business logic.
+```C#
+    /// <summary>
+    /// Handle call back events.
+    /// </summary>>
+    [HttpPost]
+    [Route("/CallBackEvent")]
+    public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
+    {
+        try
+        {
+            if (events != null)
+            {
+                // Helper function to parse CloudEvent to a CallingServer event.
+                CallAutomationEventBase callBackEvent = EventParser.Parse(events.FirstOrDefault());
+            
+                switch (callBackEvent)
+                {
+                    case CallConnected ev:
+                        # logic to handle a CallConnected event
+                        break;
+                    case CallDisconnected ev:
+                        # logic to handle a CallDisConnected event
+                        break;
+                    case ParticipantsUpdated ev:
+                        # cast the event into a ParticipantUpdated event and do something with it. Eg. iterate through the participants
+                        ParticipantsUpdated updatedEvent = (ParticipantsUpdated)ev;
+                        break;
+                    case AddParticipantsSucceeded ev:
+                        # logic to handle an AddParticipantsSucceeded event
+                        break;
+                    case AddParticipantsFailed ev:
+                        # logic to handle an AddParticipantsFailed event
+                        break;
+                    case CallTransferAccepted ev:
+                        # logic to handle CallTransferAccepted event
+                        break;
+                    case CallTransferFailed ev:
+                        # logic to handle CallTransferFailed event
+                       break;
+                    default:
+                        break;
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            // handle exception
+        }
+        return Ok();
+    }
+```
+
 ## Troubleshooting
 A `RequestFailedException` is thrown as a service response for any unsuccessful requests. The exception contains information about what response code was returned from the service.
 

sdk/communication/Azure.Communication.CallingServer/api/Azure.Communication.CallingServer.netstandard2.0.cs

@@ -263,7 +263,12 @@ internal CreateCallResult() { }
     }
     public static partial class EventParser
     {
+        public static Azure.Communication.CallingServer.CallAutomationEventBase Parse(Azure.Messaging.CloudEvent cloudEvent) { throw null; }
+        public static Azure.Communication.CallingServer.CallAutomationEventBase Parse(System.BinaryData content) { throw null; }
         public static Azure.Communication.CallingServer.CallAutomationEventBase Parse(string content) { throw null; }
+        public static Azure.Communication.CallingServer.CallAutomationEventBase[] ParseMany(Azure.Messaging.CloudEvent[] cloudEvents) { throw null; }
+        public static Azure.Communication.CallingServer.CallAutomationEventBase[] ParseMany(System.BinaryData content) { throw null; }
+        public static Azure.Communication.CallingServer.CallAutomationEventBase[] ParseMany(string content) { throw null; }
     }
     public partial class FileSource : Azure.Communication.CallingServer.PlaySource
     {

sdk/communication/Azure.Communication.CallingServer/src/Models/Events/EventParser.cs

@@ -14,17 +14,97 @@ public static class EventParser
         private const string EventPrefix = "Microsoft.Communication.";
 
         /// <summary>
-        /// Parsing an event from json.
+        /// Parsing an event from a string.
         /// </summary>
-        /// <param name="content"></param>
-        /// <returns></returns>
+        /// <param name="content"> event json in string format.</param>
+        /// <returns>A <see cref="CallAutomationEventBase"/> object.</returns>
         public static CallAutomationEventBase Parse(string content)
         {
             CloudEvent cloudEvent = CloudEvent.Parse(BinaryData.FromString(content));
-            var eventType = cloudEvent.Type.Replace(EventPrefix, "");
+            return Deserialize(cloudEvent);
+        }
+
+        /// <summary>
+        /// Parsing an event from BinaryData.
+        /// </summary>
+        /// <param name="content"> event json in BinaryData format.</param>
+        /// <returns>A <see cref="CallAutomationEventBase"/> object.</returns>
+        public static CallAutomationEventBase Parse(BinaryData content)
+        {
+            CloudEvent cloudEvent = CloudEvent.Parse(content);
+            return Deserialize(cloudEvent);
+        }
+
+        /// <summary>
+        /// Parsing an event from a CloudEvent.
+        /// </summary>
+        /// <param name="cloudEvent"><see cref="CloudEvent"/>.</param>
+        /// <returns>A <see cref="CallAutomationEventBase"/> object.</returns>
+        public static CallAutomationEventBase Parse(CloudEvent cloudEvent)
+        {
+            return Deserialize(cloudEvent);
+        }
+
+        /// <summary>
+        /// Parsing events from a string.
+        /// </summary>
+        /// <param name="content"> events json in string format.</param>
+        /// <returns>An array of <see cref="CallAutomationEventBase"/> object.</returns>
+        public static CallAutomationEventBase[] ParseMany(string content)
+        {
+            CloudEvent[] cloudEvents = CloudEvent.ParseMany(BinaryData.FromString(content));
+            var callAutomationEvents = new CallAutomationEventBase[cloudEvents.Length];
+            for (int i = 0; i < cloudEvents.Length; i++)
+            {
+                var cloudEvent = cloudEvents[i];
+                callAutomationEvents[i] = Deserialize(cloudEvent);
+            }
+            return callAutomationEvents;
+        }
 
+        /// <summary>
+        /// Parsing events from BinaryData.
+        /// </summary>
+        /// <param name="content"> events json in BinaryData format.</param>
+        /// <returns>An array of <see cref="CallAutomationEventBase"/> object.</returns>
+        public static CallAutomationEventBase[] ParseMany(BinaryData content)
+        {
+            CloudEvent[] cloudEvents = CloudEvent.ParseMany(content);
+            var callAutomationEvents = new CallAutomationEventBase[cloudEvents.Length];
+            for (int i = 0; i < cloudEvents.Length; i++)
+            {
+                var cloudEvent = cloudEvents[i];
+                callAutomationEvents[i] = Deserialize(cloudEvent);
+            }
+            return callAutomationEvents;
+        }
+
+        /// <summary>
+        /// Parsing events from an array of CloudEvent.
+        /// </summary>
+        /// <param name="cloudEvents"><see cref="CloudEvent"/>.</param>
+        /// <returns>An array of <see cref="CallAutomationEventBase"/> object.</returns>
+        public static CallAutomationEventBase[] ParseMany(CloudEvent[] cloudEvents)
+        {
+            var callAutomationEvents = new CallAutomationEventBase[cloudEvents.Length];
+            for (int i = 0; i < cloudEvents.Length; i++)
+            {
+                var cloudEvent = cloudEvents[i];
+                callAutomationEvents[i] = Deserialize(cloudEvent);
+            }
+            return callAutomationEvents;
+        }
+
+        /// <summary>
+        /// Deserialize a CloudEvent to its corresponding CallingServer Event.
+        /// </summary>
+        /// <param name="cloudEvent"><see cref="CloudEvent"/>.</param>
+        /// <returns>A <see cref="CallAutomationEventBase"/> object.</returns>
+        private static CallAutomationEventBase Deserialize(CloudEvent cloudEvent)
+        {
             if (cloudEvent != null && cloudEvent.Data != null)
             {
+                var eventType = cloudEvent.Type.Replace(EventPrefix, "");
                 switch (eventType)
                 {
                     case nameof(AddParticipantsFailed):
@@ -47,5 +127,5 @@ public static CallAutomationEventBase Parse(string content)
             }
             return null;
         }
-     }
+    }
 }