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\UASApplications\InboundPlayWav\src\main\java\com\aculab\uas\app\InboundPlayWav.java

    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.getFilePlayer().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.getFilePlayer().start() method.

    Code:

    package com.aculab.uas.app;
    
    // An inbound application that plays a wav file to the
    // caller then hangs up.
    //
    // Requires:
    // [applicationParameters = the wav filename]
    import com.aculab.amsapi.*;
    import com.aculab.uasapi.*;
    
    // The application class.
    // This must extend either UASInboundApplication or UASOutboundApplication and
    // override the run method.
    // It must be packaged in a jar file of the same name together with a manifest file.
    public class InboundPlayWav extends UASInboundApplication
    {
        // Success Codes:
        final int Success = 0;
        // ... any positive integer
    
        // Fail Codes:
        // -1 to -99 reserved
        final int ExceptionThrown = -100;
        final int PlayInterrupted = -101;
    
        
        // This is the entry point for the application
        @Override
        public int run(UASCallChannel channel, String applicationParameters)
            throws Exception
        {
            this.getTrace().traceInfo("Start - appParms [%s]", applicationParameters);
            int returnCode = Success;
    
            try
            {
                // Ring for 2 seconds
                channel.ring(2);
    
                // Answer the call
                CallState state = channel.answer();
                if (state == CallState.Answered)
                {
                    this.getTrace().traceInfo("Answered");
    
                    if (applicationParameters.length() == 0)
                    {
                        channel.getFilePlayer().say("No wav file name was specified to play");
                    }
                    else
                    {
                        FilePlayerCause playCause = channel.getFilePlayer().play(applicationParameters);
                        if (FilePlayerCause.Normal != playCause)
                        {
                            this.getTrace().traceError("Play failed or was interrupted");
                            returnCode = PlayInterrupted;
                        }
                    }
    
                    channel.hangUp();
                }
            }
            catch (Exception e)
            {
                this.getTrace().traceError("Exception caught: %s", e.getMessage());
                returnCode = ExceptionThrown;
            }
    
            this.getTrace().traceInfo("Completed with return code %d", returnCode);
            return returnCode;
        }
    }
    
  • 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