Update CallMedia, CallConnection, and CallRecording methods and models based on ABR feedback (Azure#35746)

* add media fixes

* add callconnection and callrecording updates

* revert playmedia() method back to play()

* export api

* update media docstrings and playoptions

* update api

* add simple method overloads for play

Author: atazimsft

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

@@ -3,7 +3,7 @@
 
 namespace Azure.Communication.CallAutomation
 {
-    /// <summary><see cref="StartRecognizingEventResult"/> is returned from WaitForEvent of <see cref="StartRecognizingResult"/>.</summary>
+    /// <summary><see cref="StartRecognizingEventResult"/> is returned from WaitForEvent of <see cref="StartRecognizingCallMediaResult"/>.</summary>
     public class StartRecognizingEventResult
     {
         /// <summary>

sdk/communication/Azure.Communication.CallAutomation/src/CallAutomationEventProcessor/EventResult/StartRecognizingEventResult.cs

@@ -479,20 +479,20 @@ private static AddParticipantRequestInternal CreateAddParticipantRequest(AddPart
         }
 
         /// <summary> Get participant from a call. </summary>
-        /// <param name="participantMri">The participant's MRI.</param>
+        /// <param name="participantIdentifier">The participant's identifier.</param>
         /// <param name="cancellationToken"> The cancellation token. </param>
         /// <exception cref="RequestFailedException">The server returned an error. See <see cref="Exception.Message"/> for details returned from the server.</exception>
-        /// <exception cref="ArgumentNullException"> <paramref name="participantMri"/> is null. </exception>
+        /// <exception cref="ArgumentNullException"> <paramref name="participantIdentifier"/> is null. </exception>
         /// <returns>The <see cref="CallParticipant"/>.</returns>
-        public virtual async Task<Response<CallParticipant>> GetParticipantAsync(string participantMri, CancellationToken cancellationToken = default)
+        public virtual async Task<Response<CallParticipant>> GetParticipantAsync(CommunicationIdentifier participantIdentifier, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallConnection)}.{nameof(GetParticipant)}");
             scope.Start();
             try
             {
                 var response = await RestClient.GetParticipantAsync(
                     callConnectionId: CallConnectionId,
-                    participantMri,
+                    participantIdentifier.RawId,
                     cancellationToken: cancellationToken
                     ).ConfigureAwait(false);
 
@@ -506,20 +506,20 @@ public virtual async Task<Response<CallParticipant>> GetParticipantAsync(string
         }
 
         /// <summary> Get participant from a call. </summary>
-        /// <param name="participantMri">The participant MRI.</param>
+        /// <param name="participantIdentifier">The participant identifier.</param>
         /// <param name="cancellationToken"> The cancellation token. </param>
         /// <exception cref="RequestFailedException">The server returned an error. See <see cref="Exception.Message"/> for details returned from the server.</exception>
-        /// <exception cref="ArgumentNullException"> <paramref name="participantMri"/> is null. </exception>
+        /// <exception cref="ArgumentNullException"> <paramref name="participantIdentifier"/> is null. </exception>
         /// <returns>The <see cref="CallParticipant"/>.</returns>
-        public virtual Response<CallParticipant> GetParticipant(string participantMri, CancellationToken cancellationToken = default)
+        public virtual Response<CallParticipant> GetParticipant(CommunicationIdentifier participantIdentifier, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallConnection)}.{nameof(GetParticipant)}");
             scope.Start();
             try
             {
                 var response = RestClient.GetParticipant(
                     callConnectionId: CallConnectionId,
-                    participantMri,
+                    participantIdentifier.RawId,
                     cancellationToken: cancellationToken
                     );
 

sdk/communication/Azure.Communication.CallAutomation/src/CallConnection.cs

@@ -47,18 +47,18 @@ protected CallRecording()
         /// </summary>
         /// <param name="options">Options for start recording</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual Response<RecordingStateResult> StartRecording(StartRecordingOptions options, CancellationToken cancellationToken = default)
+        public virtual Response<RecordingStateResult> Start(StartRecordingOptions options, CancellationToken cancellationToken = default)
         {
             if (options == null)
                 throw new ArgumentNullException(nameof(options));
 
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(StartRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Start)}");
             scope.Start();
             try
             {
                 StartCallRecordingRequestInternal request = new(CallLocatorSerializer.Serialize(options.CallLocator))
                 {
-                    RecordingStateCallbackUri = options.RecordingStateCallbackEndpoint?.AbsoluteUri,
+                    RecordingStateCallbackUri = options.RecordingStateCallbackUri?.AbsoluteUri,
                     RecordingChannelType = options.RecordingChannel,
                     RecordingContentType = options.RecordingContent,
                     RecordingFormatType = options.RecordingFormat,
@@ -95,18 +95,18 @@ public virtual Response<RecordingStateResult> StartRecording(StartRecordingOptio
         /// </summary>
         /// <param name="options">Options for start recording</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual async Task<Response<RecordingStateResult>> StartRecordingAsync(StartRecordingOptions options, CancellationToken cancellationToken = default)
+        public virtual async Task<Response<RecordingStateResult>> StartAsync(StartRecordingOptions options, CancellationToken cancellationToken = default)
         {
             if (options == null)
                 throw new ArgumentNullException(nameof(options));
 
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(StartRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Start)}");
             scope.Start();
             try
             {
                 StartCallRecordingRequestInternal request = new(CallLocatorSerializer.Serialize(options.CallLocator))
                 {
-                    RecordingStateCallbackUri = options.RecordingStateCallbackEndpoint?.AbsoluteUri,
+                    RecordingStateCallbackUri = options.RecordingStateCallbackUri?.AbsoluteUri,
                     RecordingChannelType = options.RecordingChannel,
                     RecordingContentType = options.RecordingContent,
                     RecordingFormatType = options.RecordingFormat,
@@ -156,9 +156,9 @@ public virtual async Task<Response<RecordingStateResult>> StartRecordingAsync(St
         /// </summary>
         /// <param name="recordingId">The recording id to get the state of.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual Response<RecordingStateResult> GetRecordingState(string recordingId, CancellationToken cancellationToken = default)
+        public virtual Response<RecordingStateResult> GetState(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(GetRecordingState)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(GetState)}");
             scope.Start();
             try
             {
@@ -179,9 +179,9 @@ public virtual Response<RecordingStateResult> GetRecordingState(string recording
         /// </summary>
         /// <param name="recordingId">The recording id to get the state of.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual async Task<Response<RecordingStateResult>> GetRecordingStateAsync(string recordingId, CancellationToken cancellationToken = default)
+        public virtual async Task<Response<RecordingStateResult>> GetStateAsync(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(GetRecordingState)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(GetState)}");
             scope.Start();
             try
             {
@@ -202,9 +202,9 @@ public virtual async Task<Response<RecordingStateResult>> GetRecordingStateAsync
         /// </summary>
         /// <param name="recordingId">The recording id to stop.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual Response StopRecording(string recordingId, CancellationToken cancellationToken = default)
+        public virtual Response Stop(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(StopRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Stop)}");
             scope.Start();
             try
             {
@@ -225,9 +225,9 @@ public virtual Response StopRecording(string recordingId, CancellationToken canc
         /// </summary>
         /// <param name="recordingId">The recording id to stop.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual async Task<Response> StopRecordingAsync(string recordingId, CancellationToken cancellationToken = default)
+        public virtual async Task<Response> StopAsync(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(StopRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Stop)}");
             scope.Start();
             try
             {
@@ -248,9 +248,9 @@ public virtual async Task<Response> StopRecordingAsync(string recordingId, Cance
         /// </summary>
         /// <param name="recordingId">The recording id to pause.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual async Task<Response> PauseRecordingAsync(string recordingId, CancellationToken cancellationToken = default)
+        public virtual async Task<Response> PauseAsync(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(PauseRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Pause)}");
             scope.Start();
             try
             {
@@ -271,9 +271,9 @@ public virtual async Task<Response> PauseRecordingAsync(string recordingId, Canc
         /// </summary>
         /// <param name="recordingId">The recording id to pause.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual Response PauseRecording(string recordingId, CancellationToken cancellationToken = default)
+        public virtual Response Pause(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(PauseRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Pause)}");
             scope.Start();
             try
             {
@@ -294,9 +294,9 @@ public virtual Response PauseRecording(string recordingId, CancellationToken can
         /// </summary>
         /// <param name="recordingId">The recording id to pause.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual async Task<Response> ResumeRecordingAsync(string recordingId, CancellationToken cancellationToken = default)
+        public virtual async Task<Response> ResumeAsync(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(ResumeRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Resume)}");
             scope.Start();
             try
             {
@@ -317,9 +317,9 @@ public virtual async Task<Response> ResumeRecordingAsync(string recordingId, Can
         /// </summary>
         /// <param name="recordingId">The recording id to resume.</param>
         /// <param name="cancellationToken">The cancellation token.</param>
-        public virtual Response ResumeRecording(string recordingId, CancellationToken cancellationToken = default)
+        public virtual Response Resume(string recordingId, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(ResumeRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Resume)}");
             scope.Start();
             try
             {
@@ -533,7 +533,7 @@ public virtual async Task<Response> DownloadToAsync(Uri sourceLocation, string d
         }
 
         /// <summary>
-        /// The <see cref="DeleteRecording(Uri, CancellationToken)"/>
+        /// The <see cref="Delete(Uri, CancellationToken)"/>
         /// operation deletes the specified content from storage.
         /// </summary>
         /// <param name="recordingLocation">
@@ -550,9 +550,9 @@ public virtual async Task<Response> DownloadToAsync(Uri sourceLocation, string d
         /// A <see cref="RequestFailedException"/> will be thrown if
         /// a failure occurs.
         /// </remarks>
-        public virtual Response DeleteRecording(Uri recordingLocation, CancellationToken cancellationToken = default)
+        public virtual Response Delete(Uri recordingLocation, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(DeleteRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Delete)}");
             scope.Start();
             try
             {
@@ -575,7 +575,7 @@ public virtual Response DeleteRecording(Uri recordingLocation, CancellationToken
         }
 
         /// <summary>
-        /// The <see cref="DeleteRecordingAsync(Uri, CancellationToken)"/>
+        /// The <see cref="DeleteAsync(Uri, CancellationToken)"/>
         /// operation deletes the specified content from storage
         /// using parallel requests.
         /// </summary>
@@ -593,9 +593,9 @@ public virtual Response DeleteRecording(Uri recordingLocation, CancellationToken
         /// A <see cref="RequestFailedException"/> will be thrown if
         /// a failure occurs.
         /// </remarks>
-        public virtual async Task<Response> DeleteRecordingAsync(Uri recordingLocation, CancellationToken cancellationToken = default)
+        public virtual async Task<Response> DeleteAsync(Uri recordingLocation, CancellationToken cancellationToken = default)
         {
-            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(DeleteRecording)}");
+            using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(CallRecording)}.{nameof(Delete)}");
             scope.Start();
             try
             {

sdk/communication/Azure.Communication.CallAutomation/src/CallMedia.cs

@@ -36,7 +36,7 @@ public static AnswerCallResult AnswerCallResult(CallConnection callConnection =
         /// <param name="serverCallId">The server call id.</param>
         /// <param name="targets">The targets of the call.</param>
         /// <param name="callConnectionState">The state of the call connection.</param>
-        /// <param name="callbackEndpoint">The callback URI.</param>
+        /// <param name="callbackUri">The callback URI.</param>
         /// <param name="sourceIdentity">Source identity.</param>
         /// <param name="sourceCallerIdNumber">Caller ID phone number to appear on the invitee.</param>
         /// <param name="sourceDisplayName">Display name to appear on the invitee.</param>
@@ -47,13 +47,13 @@ public static CallConnectionProperties CallConnectionProperties(
             string serverCallId = default,
             IEnumerable<CommunicationIdentifier> targets = default,
             CallConnectionState callConnectionState = default,
-            Uri callbackEndpoint = default,
+            Uri callbackUri = default,
             CommunicationIdentifier sourceIdentity = default,
             PhoneNumberIdentifier sourceCallerIdNumber = default,
             string sourceDisplayName = default,
             string mediaSubscriptionId = default)
         {
-            return new CallConnectionProperties(callConnectionId, serverCallId, targets, callConnectionState, callbackEndpoint, sourceIdentity, sourceCallerIdNumber, sourceDisplayName, mediaSubscriptionId);
+            return new CallConnectionProperties(callConnectionId, serverCallId, targets, callConnectionState, callbackUri, sourceIdentity, sourceCallerIdNumber, sourceDisplayName, mediaSubscriptionId);
         }
 
         /// <summary> Initializes a new instance of CallParticipant. </summary>

sdk/communication/Azure.Communication.CallAutomation/src/CallRecording.cs

@@ -15,7 +15,7 @@ internal CallConnectionProperties(
             string serverCallId,
             IEnumerable<CommunicationIdentifier> targets,
             CallConnectionState callConnectionState,
-            Uri callbackEndpoint,
+            Uri callbackUri,
             CommunicationIdentifier sourceIdentity,
             PhoneNumberIdentifier sourceCallerIdNumber,
             string sourceDisplayName,
@@ -26,7 +26,7 @@ string mediaSubscriptionId
             ServerCallId = serverCallId;
             Targets = targets == null ? new List<CommunicationIdentifier>() : targets.ToList();
             CallConnectionState = callConnectionState == default ? CallConnectionState.Unknown : callConnectionState;
-            CallbackEndpoint = callbackEndpoint;
+            CallbackUri = callbackUri;
             SourceIdentity = sourceIdentity;
             SourceCallerIdNumber = sourceCallerIdNumber;
             SourceDisplayName = sourceDisplayName;
@@ -48,7 +48,7 @@ internal CallConnectionProperties(CallConnectionPropertiesInternal callConnectio
                 CallConnectionState = callConnectionPropertiesDtoInternal.CallConnectionState.Value;
             }
 
-            CallbackEndpoint = new Uri(callConnectionPropertiesDtoInternal.CallbackUri);
+            CallbackUri = new Uri(callConnectionPropertiesDtoInternal.CallbackUri);
             MediaSubscriptionId = callConnectionPropertiesDtoInternal.MediaSubscriptionId;
             SourceIdentity = CommunicationIdentifierSerializer.Deserialize(callConnectionPropertiesDtoInternal.SourceIdentity);
             SourceDisplayName = callConnectionPropertiesDtoInternal.SourceDisplayName;
@@ -68,7 +68,7 @@ internal CallConnectionProperties(CallConnectionPropertiesInternal callConnectio
         /// <summary> The state of the call connection. </summary>
         public CallConnectionState CallConnectionState { get; }
         /// <summary> The callback URI. </summary>
-        public Uri CallbackEndpoint { get; }
+        public Uri CallbackUri { get; }
         /// <summary> SubscriptionId for media streaming. </summary>
         public string MediaSubscriptionId { get; }
         /// <summary>

sdk/communication/Azure.Communication.CallAutomation/src/Models/CallAutomationModelFactory.cs

@@ -34,6 +34,6 @@ public CallMediaRecognizeDtmfOptions(CommunicationIdentifier targetParticipant,
         /// <summary>
         /// List of tones that will stop recognizing.
         /// </summary>
-        public IReadOnlyList<DtmfTone> StopTones { get; set; }
+        public IList<DtmfTone> StopTones { get; set; }
     }
 }