Inbound Play Wav

UAS API - Inbound Play Wav Sample Application

Filename:

samples/inbound_play_wav.py

Description:

This sample will answer an inbound call and play a wav file. It requires that the wav file to play has been uploaded to the cloud, this can be done on the Media File Management page (Manage -> Media Files). The name of the wav file is passed to the application via the application_parameters variable which is configured on the Inbound Services page (Manage -> Inbound Services).

After ringing and answering the call, the channel.FilePlayer.play() function is used to play the wav file. The name of the wav file is taken from application_parameters. This will halt our application until the wave. This function will block until the file has finished playing - it is possible to start playing a file and then continue with the application by using the channel.FilePlayer.start() function instead.

Code:

"""
A simple example that will answer an inbound call and play a wav file.
The wav to play is passed in through application_parameters, which is
configured on the inbound services page of the CWP.

    Actions:
        - check the channel state
        - ring and answer
        - play a file - file name in application_parameters
        - hang up

"""

from prosody.uas import Hangup, Error, AESCBCCipher
import time

__uas_version__  = "0.0.1"
__uas_identify__ = "application"

def main(channel, application_instance_id, file_man, my_log, application_parameters):
    return_code = 0
    try:
        # This application will play a file. If the file is encrypted it must
        # be validated before it can be played. Validation should happen before
        # the call is answered.
        # In the bit of code below we assume that the cipher key and vector are supplied 
        # in application_parameters, along with the file name (using ; as the delimiter).

        # check the incoming channel state
        state = channel.state()
        if state == channel.State.CALL_INCOMING:
            state = channel.ring()   # this can raise a Hangup exception
            if state == channel.State.RING_INCOMING:
                state = channel.answer() # this can raise a Hangup exception
        else:
            raise Hangup('No inbound call, state is {0}'.format(state))
        if state != channel.State.ANSWERED:
            raise Hangup('Failed to answer inbound call, state is {0}'.format(state))
        
        my_log.info("Answered an inbound call") # log at info level

        # play a wav file, file name is provided in application_parameters
        cause = channel.FilePlayer.play(application_parameters)
        if cause != channel.FilePlayer.Cause.NORMAL:
            raise Error("Play failed: cause is {0}".format(cause))

        # Bye bye
        cause = channel.FilePlayer.say("Bye bye.")
        if cause != channel.FilePlayer.Cause.NORMAL:
            raise Error("Say bye bye failed: cause is {0}".format(cause))
        
    except Hangup as exc:
        my_log.info("Hangup exception reports: {0}".format(exc))
         # in this app a hangup is not an error, return a positive value
        return_code = 100
        
    except Error as exc:
        # for error conditions return a negative value
        my_log.error("Error exception reports: {0}".format(exc))
        return_code = -101
        
    except Exception as exc:
        # an unexpected exception, return a negative value
        my_log.exception("Unexpected exception reports: {0}".format(exc))
        return_code = -102
        
    finally:
        if channel.state() != channel.State.IDLE:
            channel.hang_up()

    return return_code

Filename:

Samples\C#\InboundPlayWav\InboundPlayWav.cs

Description:

For this example, you will need to upload a wav file (e.g. via the Media Files menu option). Once uploaded, note the pathname and filename. To run this application, insert the filename into the Application Parameters field of the Inbound Service that runs this application.

We call Ring and Answer and then play the file using channel.FilePlayer.Play(). This plays the wav file contained in the applicationParameters argument, blocking until the wav file has finished playing. Note that we could have started played the file without blocking using the channel.FilePlayer.Start() method.

Code:

using System;
using System.Threading;
using AMSClassLibrary;
using UASAppAPI;

// An inbound application that plays a wav file to the
// caller then hangs up.
//
// Requires:
// [applicationParameters = the wav filename]
namespace InboundPlayWav
{
    // The application class.
    // This must have the same name as the assembly and must inherit from either 
    // UASInboundApplication or UASOutboundApplication.
    // It must override the Run method.
    public class InboundPlayWav : UASInboundApplication
    {
        enum ReturnCode
        {
            // Success Codes:
            Success = 0,
            // ... any positive integer

            // Fail Codes:
            // -1 to -99 reserved
            ExceptionThrown = -100,
            PlayInterrupted = -101
        }

        // This is the entry point for the application
        public override int Run(UASCallChannel channel, string applicationParameters)
        {
            this.Trace.TraceInfo("Start - appParms [{0}]", applicationParameters);
            ReturnCode reply = ReturnCode.Success;

            try
            {
                // Ring for 2 seconds
                channel.Ring(2);

                // Answer the call
                CallState state = channel.Answer();
                if (state == CallState.Answered)
                {
                    this.Trace.TraceInfo("Answered");

                    if (applicationParameters.Length == 0)
                    {
                        channel.FilePlayer.Say("No wav file name was specified to play");
                    }
                    else
                    {
                        FilePlayerCause playCause = channel.FilePlayer.Play(applicationParameters);
                        if (FilePlayerCause.Normal != playCause)
                        {
                            this.Trace.TraceError("Play failed or was interrupted");
                            reply = ReturnCode.PlayInterrupted;
                        }
                    }

                    channel.HangUp();
                }
            }
            catch (Exception e)
            {
                this.Trace.TraceError("Exception caught: {0}", e.Message);
                reply = ReturnCode.ExceptionThrown;
            }

            this.Trace.TraceInfo("Completed");
            return (int)reply;
        }
    }
}

Filename:

Samples\VB\InboundPlayWav\InboundPlayWav.vb

Description:

For this example, you will need to upload a wav file (e.g. via the Media Files menu option). Once uploaded, note the pathname and filename. To run this application, insert the filename into the Application Parameters field of the Inbound Service that runs this application.

We call Ring and Answer and then play the file using channel.FilePlayer.Play(). This plays the wav file contained in the applicationParameters argument, blocking until the wav file has finished playing. Note that we could have started played the file without blocking using the channel.FilePlayer.Start() method.

Code:

Imports AMSClassLibrary
Imports UASAppAPI

' An inbound application that plays a wav file (filename passed in) to the
' caller then hangs up.
'
' Requires:
' [applicationParameters = the wav filename]
Namespace InboundPlayWav

    ' The application class.
    ' This must have the same name as the assembly and must inherit from either 
    ' UASInboundApplication or UASOutboundApplication.
    ' It must override the Run method.
    Public Class InboundPlayWav
        Inherits UASInboundApplication

        ' Possible return codes
        Enum ReturnCode
            ' Success Codes:
            Success = 0
            ' ... any positive integer

            ' Fail Codes:
            ' -1 to -99 reserved
            ExceptionThrown = -100
            PlayInterrupted = -101
        End Enum

        ' This is the entry point for the application
        Overrides Function Run(ByVal channel As UASCallChannel, _
                               ByVal applicationParameters As String) _
                               As Integer

            Me.Trace.TraceInfo("In - appParms [{0}]", applicationParameters)
            Dim reply As ReturnCode = ReturnCode.Success

            Try
                ' Ring for 2 seconds
                channel.Ring(2)

                ' Answer the call
                Dim state As CallState
                state = channel.Answer()
                If state = CallState.Answered Then

                    Me.Trace.TraceInfo("Answered")

                    If String.IsNullOrEmpty(applicationParameters) Then
                        channel.FilePlayer.Say("No wav file name was specified to play")
                    Else
                        ' Play the specified file
                        Dim playCause = channel.FilePlayer.Play(applicationParameters)
                        If FilePlayerCause.Normal <> playCause Then
                            Me.Trace.TraceError("Play failed or was interrupted")
                            reply = ReturnCode.PlayInterrupted
                        End If
                    End If

                    channel.HangUp()
                End If

            Catch ex As Exception
                Me.Trace.TraceError("Exception thrown {0}", ex.Message)
                reply = ReturnCode.ExceptionThrown
            End Try

            Me.Trace.TraceInfo("Completed")
            Return reply

        End Function

    End Class

End Namespace

Filename:

Samples\F#\InboundPlayWav\InboundPlayWav.fs

Description:

For this example, you will need to upload a wav file (e.g. via the Media Files menu option). Once uploaded, note the pathname and filename. To run this application, insert the filename into the Application Parameters field of the Inbound Service that runs this application.

We call Ring and Answer and then play the file using channel.FilePlayer.Play(). This plays the wav file contained in the applicationParameters argument, blocking until the wav file has finished playing. Note that we could have started played the file without blocking using the channel.FilePlayer.Start() method.

Code:

// An inbound application that plays a wav file (filename passed in) to the
// caller then hangs up.
//
// Requires:
// [applicationParameters = the wav filename]
namespace InboundPlayWav

    open System
    open System.Threading
    open AMSClassLibrary
    open UASAppAPI

    // Possible return codes
    type ReturnCode =
        // Success Codes:
        | Success = 0
        // ... any positive integer

        // Fail Codes:
        // -1 to -99 reserved
        | ExceptionThrown = -100
        | PlayInterrupted = -101

    // The application class.
    // This must have the same name as the assembly and must inherit from either 
    // UASInboundApplication or UASOutboundApplication.
    // It must override the Run method.
    type InboundPlayWav() = 
        inherit UASInboundApplication()

        // This is the entry point for the application
        override obj.Run(channel:UASCallChannel, applicationParameters:string) : int = 
            
            obj.Trace.TraceInfo("In - appParms [{0}]", applicationParameters)
            let mutable reply = ReturnCode.Success

            try
                // Ring for 2 seconds
                channel.Ring(2) |> ignore

                // Answer the call
                if channel.Answer() = CallState.Answered then

                    obj.Trace.TraceInfo("Call answered")

                    if applicationParameters.Length = 0 then
                        channel.FilePlayer.Say("No wav file name was specified to play") |> ignore
                    elif channel.FilePlayer.Play(applicationParameters) <> FilePlayerCause.Normal then
                        obj.Trace.TraceError("Play failed or was interrupted")
                        reply <- ReturnCode.PlayInterrupted

                    channel.HangUp() |> ignore
            with 
                | _ as e -> 
                    obj.Trace.TraceError("Exception caught {0}", e.Message)
                    reply <- ReturnCode.ExceptionThrown

                
            obj.Trace.TraceInfo("Completed")
            (int)reply