Changes for implementing server calling APIs (#21029)

* Call automation and recording APIs implementation

* Changes to call recording APIs

* Recording download live test - Sync

* Resolving lint warnings

* Changing from AsyncHttpReponse to HttpReponse in sync files

* Removing convertor for StartCallRecording and fix for CI build failure

* Fixing CI build issues with importing urlparse

* Updating recording file for recording download parallel

* skipping test_download_content_to_stream_on_chunks_parallel as it's failing with 401 and needs investigation

* Resolving lint errors

Author: ravithanneeru

sdk/communication/azure-communication-callingserver/azure/communication/callingserver/__init__.py

@@ -14,14 +14,19 @@
                                 CreateCallRequest, PhoneNumberIdentifierModel,
                                 PlayAudioRequest, PlayAudioResult,
                                 MediaType, EventSubscriptionType,
-                                OperationStatus)
+                                OperationStatus, CallConnectionStateChangedEvent,
+                                ToneReceivedEvent, ToneInfo,
+                                PlayAudioResultEvent, CommunicationIdentifierModel,
+                                CommunicationUserIdentifierModel, AddParticipantResultEvent,
+                                CallConnectionState, ToneValue)
 from ._models import (
     CreateCallOptions,
     JoinCallOptions,
     PlayAudioOptions,
     CallLocator,
     GroupCallLocator,
-    ServerCallLocator
+    ServerCallLocator,
+    CallingServerEventType
     )
 from ._shared.models import CommunicationIdentifier, CommunicationUserIdentifier, PhoneNumberIdentifier
 
@@ -46,6 +51,16 @@
     'PlayAudioResult',
     'CallLocator',
     'GroupCallLocator',
-    'ServerCallLocator'
+    'ServerCallLocator',
+    'CallConnectionStateChangedEvent',
+    'ToneReceivedEvent',
+    'ToneInfo',
+    'PlayAudioResultEvent',
+    'CommunicationIdentifierModel',
+    'CommunicationUserIdentifierModel',
+    'AddParticipantResultEvent',
+    'CallConnectionState',
+    'ToneValue',
+    'CallingServerEventType'
 ]
 __version__ = VERSION

sdk/communication/azure-communication-callingserver/azure/communication/callingserver/_call_connection.py

@@ -3,18 +3,15 @@
 # Licensed under the MIT License. See License.txt in the project root for
 # license information.
 # --------------------------------------------------------------------------
-
 from typing import TYPE_CHECKING, Any, Optional  # pylint: disable=unused-import
-
 from azure.core.tracing.decorator import distributed_trace
-
+from .utils._utils import CallingServerUtils
 from ._communication_identifier_serializer import serialize_identifier
 from ._converters import (
     AddParticipantRequestConverter,
     RemoveParticipantRequestConverter,
     CancelAllMediaOperationsConverter,
     TransferCallRequestConverter,
-    CancelMediaOperationRequestConverter,
     CancelParticipantMediaOperationRequestConverter,
     PlayAudioRequestConverter,
     PlayAudioToParticipantRequestConverter
@@ -76,9 +73,18 @@ def play_audio(
         if not audio_file_uri:
             raise ValueError("audio_file_uri can not be None")
 
+        if not CallingServerUtils.is_valid_url(audio_file_uri):
+            raise ValueError("audio_file_uri is invalid")
+
         if not play_audio_options:
             raise ValueError("options can not be None")
 
+        if not play_audio_options.audio_file_id:
+            raise ValueError("audio_file_id can not be None")
+
+        if not CallingServerUtils.is_valid_url(play_audio_options.callback_uri):
+            raise ValueError("callback_uri is invalid")
+
         play_audio_request = PlayAudioRequestConverter.convert(audio_file_uri, play_audio_options)
 
         return self._call_connection_client.play_audio(
@@ -147,9 +153,15 @@ def play_audio_to_participant(
         if not audio_file_uri:
             raise ValueError("audio_file_uri can not be None")
 
+        if not CallingServerUtils.is_valid_url(audio_file_uri):
+            raise ValueError("audio_file_uri is invalid")
+
         if not play_audio_options:
             raise ValueError("play_audio_options can not be None")
 
+        if not CallingServerUtils.is_valid_url(play_audio_options.callback_uri):
+            raise ValueError("callback_uri is invalid")
+
         play_audio_to_participant_request = PlayAudioToParticipantRequestConverter.convert(
             identifier=serialize_identifier(participant),
             audio_file_uri=audio_file_uri,

sdk/communication/azure-communication-callingserver/azure/communication/callingserver/_callingserver_client.py

@@ -5,9 +5,11 @@
 # --------------------------------------------------------------------------
 
 from typing import TYPE_CHECKING, Any, List, Optional  # pylint: disable=unused-import
-
 from azure.core.tracing.decorator import distributed_trace
-
+from azure.core.pipeline.transport import HttpResponse
+from .utils._utils import CallingServerUtils
+from ._content_downloader import ContentDownloader
+from ._download import ContentStreamDownloader
 from ._communication_identifier_serializer import serialize_identifier
 from ._communication_call_locator_serializer import serialize_call_locator
 from ._generated._azure_communication_calling_server_service import \
@@ -16,10 +18,13 @@
     CreateCallRequest,
     PhoneNumberIdentifierModel,
     PlayAudioResult,
-    AddParticipantResult
+    AddParticipantResult,
+    StartCallRecordingResult,
+    CallRecordingProperties,
+    StartCallRecordingRequest,
+    StartCallRecordingWithCallLocatorRequest
     )
 from ._shared.models import CommunicationIdentifier
-from ._models import CallLocator
 from ._call_connection import CallConnection
 from ._converters import (
     JoinCallRequestConverter,
@@ -35,7 +40,13 @@
 
 if TYPE_CHECKING:
     from azure.core.credentials import TokenCredential
-    from ._models import CreateCallOptions, JoinCallOptions, PlayAudioOptions
+    from ._models import (
+        CreateCallOptions,
+        JoinCallOptions,
+        PlayAudioOptions,
+        ParallelDownloadOptions,
+        CallLocator
+    )
 
 class CallingServerClient(object):
     """A client to interact with the AzureCommunicationService Calling Server.
@@ -196,9 +207,9 @@ def join_call(
             raise ValueError("call_options can not be None")
 
         join_call_request = JoinCallRequestConverter.convert(
-            serialize_call_locator(call_locator),
-            serialize_identifier(source),
-            call_options
+            call_locator=serialize_call_locator(call_locator),
+            source=serialize_identifier(source),
+            join_call_options=call_options
             )
 
         join_call_response = self._server_call_client.join_call(
@@ -224,13 +235,17 @@ def play_audio(
             raise ValueError("call_locator can not be None")
         if not audio_file_uri:
             raise ValueError("audio_file_uri can not be None")
+        if not CallingServerUtils.is_valid_url(audio_file_uri):
+            raise ValueError("audio_file_uri is invalid")
         if not play_audio_options:
             raise ValueError("options can not be None")
+        if not CallingServerUtils.is_valid_url(play_audio_options.callback_uri):
+            raise ValueError("callback_uri is invalid")
 
         play_audio_request = PlayAudioWithCallLocatorRequestConverter.convert(
-            serialize_call_locator(call_locator),
-            audio_file_uri,
-            play_audio_options
+            call_locator=serialize_call_locator(call_locator),
+            audio_file_uri=audio_file_uri,
+            play_audio_options=play_audio_options
             )
 
         return self._server_call_client.play_audio(
@@ -254,14 +269,18 @@ def play_audio_to_participant(
             raise ValueError("participant can not be None")
         if not audio_file_uri:
             raise ValueError("audio_file_uri can not be None")
+        if not CallingServerUtils.is_valid_url(audio_file_uri):
+            raise ValueError("audio_file_uri is invalid")
         if not play_audio_options:
             raise ValueError("play_audio_options can not be None")
+        if not CallingServerUtils.is_valid_url(play_audio_options.callback_uri):
+            raise ValueError("callback_uri is invalid")
 
         play_audio_to_participant_request = PlayAudioToParticipantWithCallLocatorRequestConverter.convert(
-            serialize_call_locator(call_locator),
-            serialize_identifier(participant),
-            audio_file_uri,
-            play_audio_options
+            call_locator=serialize_call_locator(call_locator),
+            identifier=serialize_identifier(participant),
+            audio_file_uri=audio_file_uri,
+            play_audio_options=play_audio_options
             )
 
         return self._server_call_client.participant_play_audio(
@@ -359,7 +378,8 @@ def cancel_participant_media_operation(
         if not media_operation_id:
             raise ValueError("media_operation_id can not be None")
 
-        cancel_participant_media_operation_request = CancelParticipantMediaOperationWithCallLocatorRequestConverter.convert(
+        cancel_participant_media_operation_request = \
+        CancelParticipantMediaOperationWithCallLocatorRequestConverter.convert(
             serialize_call_locator(call_locator),
             serialize_identifier(participant),
             media_operation_id=media_operation_id
@@ -368,4 +388,132 @@ def cancel_participant_media_operation(
         return self._server_call_client.cancel_participant_media_operation(
             cancel_participant_media_operation_request=cancel_participant_media_operation_request,
             **kwargs
-            )
+            )
+
+    @distributed_trace()
+    def start_recording(
+        self,
+        call_locator,  # type: CallLocator
+        recording_state_callback_uri,  # type: str
+        **kwargs  # type: Any
+    ):  # type: (...) -> StartCallRecordingResult
+
+        if not call_locator:
+            raise ValueError("call_locator cannot be None")
+        if not CallingServerUtils.is_valid_url(recording_state_callback_uri):
+            raise ValueError("recording_state_callback_uri is invalid")
+
+        start_call_recording_request = StartCallRecordingRequest(
+            recording_state_callback_uri=recording_state_callback_uri,
+            **kwargs
+        )
+
+        start_call_recording_with_calllocator_request = StartCallRecordingWithCallLocatorRequest(
+            call_locator=serialize_call_locator(call_locator),
+            start_call_recording_request=start_call_recording_request
+        )
+
+        return self._server_call_client.start_recording(
+           start_call_recording_with_call_locator_request=start_call_recording_with_calllocator_request,
+            **kwargs
+        )
+
+    @distributed_trace()
+    def pause_recording(
+        self,
+        recording_id,  # type: str
+        **kwargs  # type: Any
+    ):  # type: (...) -> HttpResponse
+
+        if not recording_id:
+            raise ValueError("recording_id cannot be None")
+
+        return self._server_call_client.pause_recording(
+            recording_id=recording_id,
+            **kwargs
+        )
+
+    @distributed_trace()
+    def resume_recording(
+        self,
+        recording_id,  # type: str
+        **kwargs  # type: Any
+    ):  # type: (...) -> HttpResponse
+
+        if not recording_id:
+            raise ValueError("recording_id cannot be None")
+
+        return self._server_call_client.resume_recording(
+            recording_id=recording_id,
+            **kwargs
+        )
+
+    @distributed_trace()
+    def stop_recording(
+        self,
+        recording_id,  # type: str
+        **kwargs  # type: Any
+    ):  # type: (...) -> HttpResponse
+
+        if not recording_id:
+            raise ValueError("recording_id cannot be None")
+
+        return self._server_call_client.stop_recording(
+            recording_id=recording_id,
+            **kwargs
+        )
+
+    @distributed_trace()
+    def get_recording_properities(
+        self,
+        recording_id,  # type: str
+        **kwargs  # type: Any
+    ):  # type: (...) -> CallRecordingProperties
+
+        if not recording_id:
+            raise ValueError("recording_id cannot be None")
+
+        return self._server_call_client.get_recording_properties(
+            recording_id=recording_id,
+            **kwargs
+        )
+
+    @distributed_trace()
+    def download(
+        self,
+        content_url,  # type: str
+        start_range=None,  # type: int
+        end_range=None,  # type: int
+        parallel_download_options=None,  # type: ParallelDownloadOptions
+        **kwargs  # type: Any
+    ):  # type: (...) -> ContentStreamDownloader
+        """Download using content url.
+
+        :param str content_url:
+            The content url.
+        :returns: ContentStreamDownloader for a successful download request.
+        :rtype: ~ContentStreamDownloader
+        """
+        if not content_url:
+            raise ValueError("content_url can not be None")
+
+        if not CallingServerUtils.is_valid_url(content_url):
+            raise ValueError("content_url is invalid")
+
+        content_downloader = ContentDownloader(
+            self._callingserver_service_client._client, # pylint:disable=protected-access
+            self._callingserver_service_client._serialize, # pylint:disable=protected-access
+            self._callingserver_service_client._deserialize, # pylint:disable=protected-access
+            self._callingserver_service_client._config) # pylint:disable=protected-access
+        stream_downloader = ContentStreamDownloader(
+            content_downloader,
+            self._callingserver_service_client._config, # pylint:disable=protected-access
+            start_range,
+            end_range,
+            endpoint=content_url,
+            parallel_download_options=parallel_download_options,
+            **kwargs
+        )
+        stream_downloader._setup() # pylint:disable=protected-access
+
+        return stream_downloader